From 0301a0a062f6d8d625e222ce52ee6dc3eb1dc87b Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Fri, 18 Sep 2026 02:50:46 +0800
Subject: [PATCH 01/37] fix(desktop): place Windows caption tooltips below the
 titlebar

The Windows caption menu host sits at z-index 1100 in the strip that --dsh-windows-menu-start reserves to the right of the sidebar toggle and New Session, so the sidebar's right-side hover bubbles rendered underneath the Application/Edit text. Render those two bubbles below the 40px caption instead; ordinary Web and macOS keep the default right side.
---
 packages/client/ui-sidebar/README.i18n.yaml   |  4 +--
 packages/client/ui-sidebar/README.md          |  2 +-
 packages/client/ui-sidebar/README.zh.md       |  2 +-
 .../ui-sidebar/src/client/SidebarRoot.tsx     |  8 +++--
 .../tests/sidebar-root.client.spec.tsx        | 35 +++++++++++++++++++
 5 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index 74a544bbbe..82cd695b6f 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/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-sidebar/README.md
-README.md: 513e9d3151aba64b640475c3cd8c2f993df077db
-README.zh.md: 69050dc8c530bf4c794d42113f2679fe41891e5f
+README.md: 4fae6feff2abb7a0934b142e010140db5cdb104e
+README.zh.md: 961ce0c0ff46317ae2c4f16b0a0b4cf68f37ed35
diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md
index 513e9d3151..4fae6feff2 100644
--- a/packages/client/ui-sidebar/README.md
+++ b/packages/client/ui-sidebar/README.md
@@ -41,7 +41,7 @@ The top expand button hosts the optional, non-interactive `sidebar.toggle.badge`
 
 During a live collapse, the expanded content fades out at its current width, the upper controls share one fade and leftward translation into the 56px rail, and the layout's column slide ends the motion. A page that starts collapsed renders the rail statically, and reduced-motion mode disables both transitions. The bottom-pinned `sidebar.settings` control shares the fade timing but has no horizontal translation.
 
-On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region.
+On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region. Their hover bubbles open below the caption, where the Desktop-owned menu text cannot cover them.
 
 ### macOS desktop
 
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index 69050dc8c5..961ce0c0ff 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -41,7 +41,7 @@ dsh Web 客户端的侧边栏让用户识别当前构建、启动新会话、将
 
 实时收起时，展开内容在当前宽度淡出，上方控件共用同一段透明度渐变，并向左平移进入 56px 轨道，由布局的栏滑动结束整段动画。页面初始即为收起状态时会静态渲染轨道；减少动态效果模式会禁用两段过渡。固定在底部的 `sidebar.settings` 控件共用相同的透明度渐变时序，但不发生横向位移。
 
-在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。
+在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。其悬停提示在顶栏下方展开，Desktop 菜单文字不会盖住它们。
 
 ### macOS 桌面
 
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
index ea362a51f2..4ab6303c28 100644
--- a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
@@ -107,6 +107,10 @@ export function SidebarRoot({
   }, [collapsed])
   const windowsTitlebar = document.documentElement.hasAttribute('data-windows-titlebar')
   const wide = windowsTitlebar ? !collapsed : !collapsed || !settled
+  // The Windows caption menus occupy the strip to the right of these controls
+  // (that is what --dsh-windows-menu-start reserves), so a right-side bubble
+  // lands under their text. Below the caption is the only clear side.
+  const captionTooltipSide = windowsTitlebar ? 'bottom' : 'right'
 
   // Freeze the content at its expanded width while it fades out (collapsed
   // && wide): the sliding column then clips it instead of reflowing it. The
@@ -169,7 +173,7 @@ export function SidebarRoot({
   // (the expand affordance, figma sidebar-hover flow). Expanded it is a plain
   // panel icon.
   const toggle = (
-    <Tooltip label={collapsed ? t('toggle.open') : t('toggle.collapse')} delayMs={500}>
+    <Tooltip label={collapsed ? t('toggle.open') : t('toggle.collapse')} delayMs={500} side={captionTooltipSide}>
       <button
         type="button"
         className={clsx(css.iconButton, css.toggle)}
@@ -238,7 +242,7 @@ export function SidebarRoot({
       </div>
 
       {/* Expanded, the button carries its own label — tooltip only on the rail. */}
-      <Tooltip label={t('session.new.label')} delayMs={500} disabled={wide}>
+      <Tooltip label={t('session.new.label')} delayMs={500} disabled={wide} side={captionTooltipSide}>
         <button
           type="button"
           className={css.newSession}
diff --git a/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx b/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
index ed35997338..8bcc323b59 100644
--- a/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
+++ b/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
@@ -244,3 +244,38 @@ it.each([undefined, 'win32', 'linux', 'darwin'])('shows header sidebar controls
   expect(toggleSidebar).toHaveBeenCalledOnce()
   expect(startSession).toHaveBeenCalledOnce()
 })
+
+describe('Windows caption tooltips', () => {
+  afterEach(() => { document.documentElement.removeAttribute('data-windows-titlebar') })
+
+  const hover = (button: HTMLElement): void => {
+    fireEvent.mouseEnter(button)
+    act(() => { vi.advanceTimersByTime(500) })
+  }
+
+  it.each([false, true])(
+    'drops the sidebar toggle bubble below the caption (collapsed=%s)',
+    (collapsed) => {
+      vi.useFakeTimers()
+      document.documentElement.setAttribute('data-windows-titlebar', '')
+      mountShell({ collapsed, width: collapsed ? 0 : 300 })
+      hover(screen.getByRole('button', { name: collapsed ? 'Open sidebar' : 'Collapse sidebar' }))
+      expect(screen.getByRole('tooltip').getAttribute('data-side')).toBe('bottom')
+    },
+  )
+
+  it('drops the collapsed New Session bubble below the caption as well', () => {
+    vi.useFakeTimers()
+    document.documentElement.setAttribute('data-windows-titlebar', '')
+    mountShell({ collapsed: true, width: 0 })
+    hover(screen.getByRole('button', { name: 'New session' }))
+    expect(screen.getByRole('tooltip').getAttribute('data-side')).toBe('bottom')
+  })
+
+  it('keeps the ordinary Web bubble beside its anchor', () => {
+    vi.useFakeTimers()
+    mountShell({ collapsed: true, width: 0 })
+    hover(screen.getByRole('button', { name: 'Open sidebar' }))
+    expect(screen.getByRole('tooltip').getAttribute('data-side')).toBe('right')
+  })
+})

From c85e1d7b7226fb8bf0c01939fd45974a6a991a6e Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Fri, 18 Sep 2026 04:09:19 +0800
Subject: [PATCH 02/37] fix(client): raise the plugin inventory package
 identity to 12px

The Plugins settings inventory drew the Loader entry identity (cardIdentity)
at 11px in the code font, one step below the 12px the same identifier gets in
the expanded card's entry row. On Windows the code stack resolves to Consolas,
where 11px reads thin. Raise it to 12px/18px so it matches the sibling
identifier row and the page's other small text.

Fixes #4496
---
 .../src/client/PluginInventorySettingsTab.module.css          | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

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 bbf984fb20..c0df17c0ae 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
@@ -183,8 +183,8 @@
   width: 100%;
   color: var(--dsw-alias-label-tertiary);
   font-family: var(--ds-font-family-code);
-  font-size: 11px;
-  line-height: 16px;
+  font-size: 12px;
+  line-height: 18px;
 }
 
 .cardTrailing {

From 3014457c601e140e7f77484dc454f314816d46ac Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Fri, 18 Sep 2026 17:33:35 +0800
Subject: [PATCH 03/37] fix(client): share one size for the plugin inventory
 entry identity

Keep the Loader entry id at one size in both places it appears - the card
subtitle and the row the card expands into - by moving the shared code-font
typography into a single rule. The subtitle keeps its own secondary label
colour against the expanded row's primary one.
---
 .../client/PluginInventorySettingsTab.module.css | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

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 c0df17c0ae..1dba113eec 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
@@ -178,15 +178,20 @@
   font-weight: 600;
 }
 
-.cardIdentity {
-  display: block;
-  width: 100%;
-  color: var(--dsw-alias-label-tertiary);
+/* The Loader entry id keeps one size in the card subtitle and the row it expands into. */
+.cardIdentity,
+.entryValue {
   font-family: var(--ds-font-family-code);
   font-size: 12px;
   line-height: 18px;
 }
 
+.cardIdentity {
+  display: block;
+  width: 100%;
+  color: var(--dsw-alias-label-secondary);
+}
+
 .cardTrailing {
   display: inline-flex;
   flex: none;
@@ -383,9 +388,6 @@
   display: block;
   overflow-wrap: anywhere;
   color: var(--dsw-alias-label-primary);
-  font-family: var(--ds-font-family-code);
-  font-size: 12px;
-  line-height: 18px;
 }
 
 .details {

From bb2326f044fe49641fe2ba3d65fb9eae60a05fd6 Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Sat, 19 Sep 2026 22:24:35 +0800
Subject: [PATCH 04/37] fix(client): raise the plugin package name contrast on
 the detail page

The package name under a plugin's title is the exact spec that installs it, yet
it was the palest alias in the palette: label-caption, 2.13:1 against white,
lighter than the free-text description below it. Use label-secondary, the same
alias the description uses, for 5.80:1.
---
 .../ui-plugin-manager/src/client/PluginManagerPage.module.css   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
index 38875cb7c6..562ca219c0 100644
--- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
+++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
@@ -899,7 +899,7 @@
   margin: 0;
   font-size: 12px;
   line-height: 18px;
-  color: var(--dsw-alias-label-caption);
+  color: var(--dsw-alias-label-secondary);
   overflow-wrap: anywhere;
 }
 

From a9985b49ae4c32006a606432c1ee14ef8325028f Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sat, 19 Sep 2026 22:47:01 +0800
Subject: [PATCH 05/37] fix(session): migrate historical subagents only when
 opened

---
 ...leased-session-format-migrations.i18n.yaml |   4 +-
 ...8-31-released-session-format-migrations.md |  10 +-
 ...1-released-session-format-migrations.zh.md |  10 +-
 ...01-parent-owned-subagent-catalog.i18n.yaml |   4 +-
 ...026-09-01-parent-owned-subagent-catalog.md |   4 +-
 ...-09-01-parent-owned-subagent-catalog.zh.md |   4 +-
 ...session-local-subagent-migration.i18n.yaml |   6 +
 ...-09-19-session-local-subagent-migration.md |  33 +++
 ...-19-session-local-subagent-migration.zh.md |  33 +++
 ...ncomplete-child-catalog-evidence.i18n.yaml |   4 +-
 ...19-v3-incomplete-child-catalog-evidence.md |  10 +-
 ...v3-incomplete-child-catalog-evidence.zh.md |  10 +-
 ...web-subagent-catalog-projections.i18n.yaml |   4 +-
 ...-09-08-web-subagent-catalog-projections.md |   6 +-
 ...-08-web-subagent-catalog-projections.zh.md |   6 +-
 apps/web/tests/preset-migration.snapshot.ts   |  49 ++++
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   2 +-
 docs/config-catalog.zh.md                     |   2 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |  10 +-
 docs/subsystems/subagent.zh.md                |  10 +-
 docs/tool-catalog.i18n.yaml                   |   4 +-
 docs/tool-catalog.md                          |   2 +-
 docs/tool-catalog.zh.md                       |   2 +-
 .../api/session-controller/README.i18n.yaml   |   4 +-
 packages/api/session-controller/README.md     |   2 +-
 packages/api/session-controller/README.zh.md  |   2 +-
 .../src/client/sessions/manager.ts            |  12 +-
 .../src/client/sessions/session.ts            |   5 +-
 .../api/session-controller/src/history.ts     |   2 +-
 packages/api/session-controller/src/types.ts  |   2 +-
 .../tests/manager.client.spec.ts              |  40 ++-
 .../tests/transport.host.spec.ts              |  21 ++
 packages/client/ui-subagent/README.i18n.yaml  |   4 +-
 packages/client/ui-subagent/README.md         |   8 +-
 packages/client/ui-subagent/README.zh.md      |   8 +-
 .../src/client/SubagentHeaderLineage.tsx      |  41 ++-
 .../src/client/SubagentReadOnlyComposer.tsx   |   4 +-
 .../client/ui-subagent/src/client/index.ts    |   5 +-
 .../client/ui-subagent/src/client/locales.ts  |   4 +
 .../src/client/sidebar-chat/index.tsx         |   4 +-
 .../tests/browser-plugin.client.spec.ts       |  20 +-
 .../tests/conversation-ui.client.spec.tsx     |  66 ++++-
 .../tests/sidebar-chat.client.spec.tsx        |  10 +-
 packages/client/ui-workspace/README.i18n.yaml |   4 +-
 packages/client/ui-workspace/README.md        |   2 +-
 packages/client/ui-workspace/README.zh.md     |   2 +-
 .../ui-workspace/src/client/navigation.ts     |   1 -
 .../tests/workspaces-service.client.spec.ts   |   1 -
 .../extensions/tool-cordis/src/api-catalog.ts |  14 +-
 .../session-format-catalog/README.i18n.yaml   |   4 +-
 .../session/session-format-catalog/README.md  |   4 +-
 .../session-format-catalog/README.zh.md       |   4 +-
 .../session-format-catalog/src/children.ts    |   2 +-
 .../tests/children.spec.ts                    |   4 +-
 .../session-format-v3-to-v4/README.i18n.yaml  |   4 +-
 .../session/session-format-v3-to-v4/README.md |   4 +-
 .../session-format-v3-to-v4/README.zh.md      |   4 +-
 .../session-format-v3-to-v4/src/migration.ts  |   8 +-
 .../tests/catalog-completion.spec.ts          |   4 +-
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-jsonl/README.md       |   6 +-
 .../session-persistence-jsonl/README.zh.md    |   6 +-
 .../src/catalog-migration.ts                  |  82 ------
 .../src/generation.ts                         |  33 ---
 .../session-persistence-jsonl/src/index.ts    |  91 +-----
 .../tests/catalog-migration.spec.ts           | 271 ++++--------------
 .../tests/generation.spec.ts                  |  14 -
 .../tests/jsonl.spec.ts                       |   6 +-
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   2 +-
 packages/subagent/subagent/README.zh.md       |   2 +-
 .../subagent/subagent/src/control-types.ts    |  10 +
 packages/subagent/subagent/src/index.ts       |   8 +-
 .../subagent/subagent/src/list-children.ts    |  21 +-
 .../subagent/tests/list-children.spec.ts      |  12 +-
 .../tool-subagent-control/README.i18n.yaml    |   4 +-
 .../subagent/tool-subagent-control/README.md  |   4 +-
 .../tool-subagent-control/README.zh.md        |   4 +-
 .../tool-subagent-control/src/list-agents.ts  |   9 +-
 .../tests/list-agents.spec.ts                 |  11 +
 scripts/gen-cordis-catalog.ts                 |   1 +
 .../sdk/bash-tool/tool-schemas.expected.json  |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../sdk/text-turn/tool-schemas.expected.json  |   2 +-
 .../tool-schemas.expected.json                |   4 +-
 .../tool-schemas.expected.json                |   2 +-
 .../both-mode-turn/system-prompt.expected.md  |   2 +-
 .../both-mode-turn/tool-schemas.expected.json |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   4 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../lsp-definition/tool-schemas.expected.json |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../mcp-resources/tool-schemas.expected.json  |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   4 +-
 .../plugin-manager/tool-schemas.expected.json |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../provider-cwd/tool-schemas.expected.json   |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../ptc-python-turn/system-prompt.expected.md |   2 +-
 .../ptc-read-image/system-prompt.expected.md  |   2 +-
 .../ptc-turn/system-prompt.expected.md        |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../pwsh-tool-turn/tool-schemas.expected.json |   2 +-
 .../ralph-loop/tool-schemas.1.expected.json   |   2 +-
 .../ralph-loop/tool-schemas.2.expected.json   |   2 +-
 .../ralph-loop/tool-schemas.expected.json     |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../text-turn/tool-schemas.expected.json      |   2 +-
 .../web-fetch/tool-schemas.expected.json      |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../web/preset-migration/session.1.v2.jsonl   |   3 +
 .../web/ptc-round/system-prompt.expected.md   |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 143 files changed, 613 insertions(+), 686 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
 delete mode 100644 packages/session/session-persistence-jsonl/src/catalog-migration.ts
 create mode 100644 snapshots/web/preset-migration/session.1.v2.jsonl

diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
index ad8ffb6167..78e0976e24 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.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-31-released-session-format-migrations.md
-2026-08-31-released-session-format-migrations.md: 273b51ac7ce9c507c2322499788dc2084b857415
-2026-08-31-released-session-format-migrations.zh.md: 69132ec1763ad12b51480e150c3968aa1dcacf61
+2026-08-31-released-session-format-migrations.md: 11c35eb80862ccebbead566164e61b5f4a7792fb
+2026-08-31-released-session-format-migrations.zh.md: a79bf77ab19ae85bc4dc9c6a942022b8bd198378
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
index 273b51ac7c..11c35eb808 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
@@ -105,7 +105,7 @@ Preparation forwards cancellation through source reads and observes it at the ex
 
 The Stage pipeline ends at one prepared current artifact. [Historical Session read preparation](2026-09-05-read-only-session-migration-preparation.md) defines how read open consumes that artifact immediately while write open performs encode, verification, and publication before returning append access.
 
-The bulk V4 migration command shares one JSONL persistence Context across a bounded job queue, retaining the backend’s two-Worker verification limit and cache for reusing recently decoded logs. A child’s concurrent publication can change its parent’s selected child generation; the ordinary revision check refuses that attempt. The command defers only this source-change error for one sequential retry after the initial queue drains, collecting fresh evidence without relaxing publication checks or retrying unrelated failures.
+The bulk V4 migration command explicitly requests each Session through a bounded queue and shares one JSONL Context, including its two-Worker verification limit. Each publication validates only its own source. The command may retry a source-change refusal after the queue drains; a child publication does not invalidate a parent preparation.
 
 ### Durable format and publication rules
 
@@ -131,20 +131,20 @@ Existing write handles retain the process-local claim and kernel-backed cross-pr
 
 ### Parent catalog prerequisites
 
-V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; absent entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs without backfilling that child, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. An unsupported generation or unreadable header elsewhere in that scan refuses migration because it cannot prove unrelatedness. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The storage decoder classifies physical JSON and compression failures before the collector adds child context; filesystem reads and cancellation keep their original errors. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
+Original runtime policy (superseded by [Session-local migration](../bug-fix/2026-09-19-session-local-subagent-migration.md)): V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; absent entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs without backfilling that child, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. An unsupported generation or unreadable header elsewhere in that scan refuses migration because it cannot prove unrelatedness. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The storage decoder classifies physical JSON and compression failures before the collector adds child context; filesystem reads and cancellation keep their original errors. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
 
 Raw parent/child migration tests retain 24 historical creation-time conflicts as rejection evidence. Detached controls align only the child creation time and prove event-preserving restoration, including a published child without a descriptor. Headless/ACP and SDK snapshot adapters validate live parent/child clocks before normalization and preserve their equality during refresh; committed predecessor generations remain unchanged.
 
-Historical public revisions combine the parent’s physical revision with a fingerprint of every selected canonical path and its filesystem revision. Parent-only tokens cannot identify catalog changes supplied by children; a root fingerprint preserves metadata-only `stat`/`list` and includes unreadable or unsupported members without a new persistent index. Unrelated changes also invalidate historical caches, and obtaining the token costs a root scan. Current tokens stay file-local. The preparation memo keeps physical parent revisions and separately validates child membership and revisions.
+Original runtime policy (superseded by [Session-local migration](../bug-fix/2026-09-19-session-local-subagent-migration.md)): Historical public revisions combine the parent’s physical revision with a fingerprint of every selected canonical path and its filesystem revision. Parent-only tokens cannot identify catalog changes supplied by children; a root fingerprint preserves metadata-only `stat`/`list` and includes unreadable or unsupported members without a new persistent index. Unrelated changes also invalidate historical caches, and obtaining the token costs a root scan. Current tokens stay file-local. The preparation memo keeps physical parent revisions and separately validates child membership and revisions.
 
-The generic format interfaces carry only the artifact being restored. Parent-specific catalog assembly replaces the V3→V4 declaration with a closure over the collected child evidence; it reuses the generated codec, migration, and validation inventory. The assembly compiles one short migration chain per parent preparation, with independent stage state per restore. Binding at assembly keeps child evidence out of generic restore options and stage inputs without moving discovery or source revalidation into the migration. Static header and native current reads need no child evidence; an unbound historical body restore refuses rather than assuming an empty child set.
+Original runtime policy (superseded by [Session-local migration](../bug-fix/2026-09-19-session-local-subagent-migration.md)): The generic format interfaces carry only the artifact being restored. Parent-specific catalog assembly replaces the V3→V4 declaration with a closure over the collected child evidence; it reuses the generated codec, migration, and validation inventory. The assembly compiles one short migration chain per parent preparation, with independent stage state per restore. Binding at assembly keeps child evidence out of generic restore options and stage inputs without moving discovery or source revalidation into the migration. Static header and native current reads need no child evidence; an unbound historical body restore refuses rather than assuming an empty child set.
 
 <a id="catalog-scan-measurements"></a>
 ### Catalog scan measurements
 
 The package-local [diagnostic](../../../../packages/session/session-persistence-jsonl/tests/catalog-migration.perf.ts) measures one raw V3 parent, four direct children with 1,000 events each, and 0/100/1,000 unrelated header-only V3 Sessions. Each sample creates its own temporary corpus and Cordis context in a fresh process, runs stat → cold read → memo read → write publication → current warm read, and disposes the context and files. It uses built workspace exports under plain Node; fixture creation is outside the measured intervals. These are filesystem-cache-warm observations after fixture creation, not disk-cold latency or a performance gate.
 
-On macOS arm64 with Node v26.0.0, all three samples per size are below in milliseconds. Read-only opens do not publish: membership scanning remains proportional to corpus size even when decoding is memoized. The 1,000-unrelated medians are 84.14 ms for stat, 237.97 ms for cold read, 110.98 ms for memo read, 268.46 ms for publication, and 0.41 ms for the same-process current read. These measurements document the cost; they establish no speedup claim or cross-host threshold.
+The table records the eager catalog-scan implementation on macOS arm64 with Node v26.0.0 before Session-local runtime migration. The 1,000-unrelated medians were 84.14 ms for stat, 237.97 ms for cold read, 110.98 ms for memo read, 268.46 ms for publication, and 0.41 ms for the same-process current read. These historical measurements explain why metadata-only access was insufficient while preparation still decoded child bodies; they are not current timings or cross-host thresholds.
 
 | Unrelated Sessions | Historical stat | Cold read | Memo read | Publish | Current warm read |
 |---:|---:|---:|---:|---:|---:|
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
index 69132ec176..a79bf77ab1 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
@@ -105,7 +105,7 @@ Preparation 会把 cancellation 传给 source read，并在现有的约 500 ms D
 
 Stage pipeline 终止于一份 prepared current artifact。[历史 Session 只读迁移准备](2026-09-05-read-only-session-migration-preparation.zh.md)定义 read open 如何立即消费该 artifact，以及 write open 如何在返回 append 权限前完成 encode、verification 与 publication。
 
-批量 V4 迁移命令在有界任务队列中共享一个 JSONL persistence Context，保留 backend 的双 Worker 校验上限，以及复用近期已解码日志的缓存。子 Session 并发发布可能改变父 Session 选中的子代际；普通修订检查会拒绝这次尝试。命令只把这种源变化错误延后到初始队列清空后串行重试一次，重新收集证据，不放宽发布检查，也不重试无关失败。
+批量 V4 迁移命令通过有界队列显式请求各个会话，共享一个 JSONL Context 及其两个 Worker 的校验限制。每次发布只校验自身源文件。命令可在队列排空后重试源变化拒绝；子会话发布不会使父会话准备结果失效。
 
 ### Durable format 与 publication 规则
 
@@ -131,20 +131,20 @@ POSIX publication 使用 hard-link creation 加目录 sync；Windows 使用 no-o
 
 ### 父目录前置事实
 
-V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；缺失记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志但不补填对应子 Session，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。扫描中其他任何不支持代际或不可读 header 都会拒绝迁移，因为无法证明它与父 Session 无关。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。存储解码器先将物理 JSON 与压缩错误归类，再由收集器补充子日志信息；文件系统读取与取消保留原始错误。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
+原运行时规则（已由[会话独立迁移](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代）：V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；缺失记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志但不补填对应子 Session，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。扫描中其他任何不支持代际或不可读 header 都会拒绝迁移，因为无法证明它与父 Session 无关。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。存储解码器先将物理 JSON 与压缩错误归类，再由收集器补充子日志信息；文件系统读取与取消保留原始错误。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
 
 原始父子迁移测试保留 24 个历史创建时间冲突作为拒绝证据。独立的内存对照只对齐子创建时间，证明恢复保留事件，包括已发布但没有 descriptor 的子 Session。Headless/ACP 与 SDK 快照适配器在规范化之前校验实时父子时钟，并在刷新时保持两者相等；已提交的前代文件保持不变。
 
-历史格式的公开修订号组合父日志物理修订号与每个所选规范路径及其文件系统修订号的指纹。仅父日志令牌无法标识子日志提供的目录变化；全库指纹让 `stat`/`list` 保持只读元数据，也纳入不可读或不支持的成员，无需新增持久化索引。无关变化也会使历史缓存失效，获取令牌需要扫描根目录。当前格式令牌仍只取决于自身文件。准备缓存保留父日志物理修订号，并独立校验子成员集合与修订。
+原运行时规则（已由[会话独立迁移](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代）：历史格式的公开修订号组合父日志物理修订号与每个所选规范路径及其文件系统修订号的指纹。仅父日志令牌无法标识子日志提供的目录变化；全库指纹让 `stat`/`list` 保持只读元数据，也纳入不可读或不支持的成员，无需新增持久化索引。无关变化也会使历史缓存失效，获取令牌需要扫描根目录。当前格式令牌仍只取决于自身文件。准备缓存保留父日志物理修订号，并独立校验子成员集合与修订。
 
-通用格式接口只传递正在恢复的 artifact。每个父 Session 的 catalog 组装将 V3→V4 声明替换为捕获已收集子 Session 证据的闭包，并复用生成的 codec、迁移与校验清单。每次父 Session 准备只编译一条短迁移链，每次恢复拥有独立的 stage 状态。在组装处绑定证据，使通用恢复选项和 stage 输入不必携带子 Session 证据，同时保留存储对发现与来源重验的所有权。静态 header 和原生当前格式读取不需要子 Session 证据；未绑定的历史正文恢复会拒绝，不会假定子 Session 集合为空。
+原运行时规则（已由[会话独立迁移](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代）：通用格式接口只传递正在恢复的 artifact。每个父 Session 的 catalog 组装将 V3→V4 声明替换为捕获已收集子 Session 证据的闭包，并复用生成的 codec、迁移与校验清单。每次父 Session 准备只编译一条短迁移链，每次恢复拥有独立的 stage 状态。在组装处绑定证据，使通用恢复选项和 stage 输入不必携带子 Session 证据，同时保留存储对发现与来源重验的所有权。静态 header 和原生当前格式读取不需要子 Session 证据；未绑定的历史正文恢复会拒绝，不会假定子 Session 集合为空。
 
 <a id="catalog-scan-measurements"></a>
 ### 目录扫描测量
 
 包内[诊断脚本](../../../../packages/session/session-persistence-jsonl/tests/catalog-migration.perf.ts)测量一个原始 V3 父日志、四个各有 1,000 条事件的直属子日志，以及 0/100/1,000 个只有 header 的无关 V3 Session。每个样本在新进程中创建独立临时日志库与 Cordis 上下文，按 stat → 冷读 → 缓存读取 → 写入发布 → 当前格式热读顺序执行，最后释放上下文并删除文件。脚本在普通 Node 下使用已构建的工作区导出；创建夹具不计入测量区间。这些结果是夹具创建后的文件系统缓存热态观察，不代表磁盘冷读延迟，也不是性能门禁。
 
-以下为 macOS arm64、Node v26.0.0 下各规模的全部三个样本，单位为毫秒。只读打开不发布后继：即使解码结果已缓存，成员扫描仍与日志库规模成正比。1,000 个无关日志时，中位数分别为 stat 84.14 ms、冷读 237.97 ms、缓存读取 110.98 ms、发布 268.46 ms，以及同进程当前格式读取 0.41 ms。这些测量记录成本，不证明性能提升，也不设跨主机阈值。
+下表记录会话独立运行时迁移之前，macOS arm64、Node v26.0.0 上主动 catalog 扫描实现的测量。1,000 个无关会话时，中位数为 stat 84.14 ms、冷读 237.97 ms、缓存读 110.98 ms、发布 268.46 ms、同进程当前格式读取 0.41 ms。这些历史测量说明：当准备仍解码子正文时，仅优化元数据访问并不足够；它们不是当前耗时或跨主机阈值。
 
 | 无关 Session | 历史 stat | 冷读 | 缓存读取 | 发布 | 当前格式热读 |
 |---:|---:|---:|---:|---:|---:|
diff --git a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.i18n.yaml
index 59e3f84862..5f7de01cfd 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-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 .agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
-2026-09-01-parent-owned-subagent-catalog.md: 536ec33148bd675a974622b98ee23de812691dc0
-2026-09-01-parent-owned-subagent-catalog.zh.md: ec78ff9e4b7d54a7309baf21c383ec5ff83a19c8
+2026-09-01-parent-owned-subagent-catalog.md: 1c65813cd92aebbd2e45acc6b1f121aba442646d
+2026-09-01-parent-owned-subagent-catalog.zh.md: 7eded398ca53997ad80c3910aad333b4a1476286
diff --git a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
index 536ec33148..1c65813cd9 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
+++ b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
@@ -44,6 +44,8 @@ Current-writer snapshot expectations include catalog facts even when replay inpu
 
 ## Consequences
 
-Session observations and client snapshots expose the direct-child list through `projections.values.subagentCatalog`. The projection change feed publishes a complete list when catalog state changes. Each view costs O(D), so D creations can incur O(D²) cumulative view work; this follows the existing projection mechanism. `listChildren()` reads the parent projection through one live-preferred Session observation; descendant listing uses the Session corpus and child identity projection. [Web projection consumption](../simplification/2026-09-08-web-subagent-catalog-projections.md) owns browser loading and synchronization.
+Session observations and client snapshots expose durable catalog facts through `projections.values.subagentCatalog`. The change feed publishes complete lists, so D creations can incur O(D²) cumulative view work. Historical children may lack these facts: `listChildren()` supplements one parent observation with header-only discovery and returns unresolved rows without reading child bodies. The Web derives the same missing entries from its existing Session list. This preserves the catalog as the sole durable creation record while accepting O(N) header enumeration for explicit service discovery. [Web projection consumption](../simplification/2026-09-08-web-subagent-catalog-projections.md) owns browser loading and synchronization.
 
 [Creation metadata exclusion](../simplification/2026-09-16-subagent-catalog-membership-only.md) records why model configuration is absent from catalog facts.
+
+The [Session-local migration decision](../bug-fix/2026-09-19-session-local-subagent-migration.md) supersedes runtime child-body collection and unopened-branch projection reads; optional offline completion and durable catalog semantics remain active.
diff --git a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md
index ec78ff9e4b..7eded398ca 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md
@@ -44,6 +44,8 @@ snapshot normalizer 会把 `childCreatedAt` 归零，因为它来自 process clo
 
 ## 后果
 
-Session observation 与 client snapshot 通过 `projections.values.subagentCatalog` 暴露直接子级列表。目录状态变化时，projection change feed 发布完整列表。每次 view 的成本为 O(D)，因此 D 次创建可能累计产生 O(D²) 的 view 工作量；这沿用现有 projection 机制。`listChildren()` 通过一次 live-preferred Session observation 读取父 projection；后代枚举使用 Session 语料库与子身份 projection。[Web projection 消费决策](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md) 说明浏览器加载与同步。
+会话观察和客户端快照通过 `projections.values.subagentCatalog` 暴露持久化 catalog 事实。变化流发布完整列表，因此 D 次创建可能累计 O(D²) 视图工作。历史子会话可能缺少这些事实：`listChildren()` 在一次父观察之外补充仅头部发现，返回未解析条目，不读子正文。Web 从已有会话列表派生同类缺失条目。这保留 catalog 作为唯一持久化创建记录，同时接受显式服务发现的 O(N) 头部枚举成本。[Web 投影消费](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md) 负责浏览器加载与同步。
 
 [创建元数据排除决策](../simplification/2026-09-16-subagent-catalog-membership-only.zh.md) 说明目录事实为何不包含模型配置。
+
+[会话独立迁移决策](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代运行时子正文收集与未打开分支投影读取；可选离线补全和持久化 catalog 语义仍有效。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
new file mode 100644
index 0000000000..dcd77fa51d
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.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/bug-fix/2026-09-19-session-local-subagent-migration.md
+2026-09-19-session-local-subagent-migration.md: c3da2812ac2d48fe4894b62b3b5743664564633a
+2026-09-19-session-local-subagent-migration.zh.md: 43875dd8cd34635d33f711745aa9725641e4cec3
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
new file mode 100644
index 0000000000..c3da2812ac
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
@@ -0,0 +1,33 @@
+# Agent Note: Migrate each Session independently of its children
+
+Status: implemented
+
+English | [中文](2026-09-19-session-local-subagent-migration.zh.md)
+
+## Problem
+
+Runtime V3→V4 preparation collected every direct child's descriptor to complete the parent catalog. This decoded whole child logs before opening the parent, and unrelated unreadable headers could prevent complete membership classification. A corrupt child therefore blocked valid parent history. Historical revisions also fingerprinted the entire root, invalidating a parent's cached preparation when unrelated files changed.
+
+## Decision
+
+JSONL migrates only the Session explicitly opened by a reader or writer. It preserves existing catalog facts and does not read child bodies or collect cross-session evidence. Read opens prepare current logical events without publishing; write opens validate the selected source and exclusively publish its immutable successor. Public revisions and preparation reuse depend only on the selected file. Predecessor generations remain byte-identical.
+
+Discovery combines parent catalog facts with header relationships. The subagent service returns unresolved direct-child entries when no catalog fact exists; the Web derives them from its existing Session list. Menu and branch refreshes enumerate headers without requesting child projections. Selecting a child opens its own history, validates its direct parent and descriptor, and resolves mode and label. Until then the address grants no continuation authority and the composer stays read-only. A child open failure remains local. Explicit programmatic reads and continuation requests also migrate their selected Session on demand; explicit descendant inspection and bulk migration still read the Sessions they request.
+
+The catalog remains the durable source of successful creation facts. Unresolved discovery rows are neither persisted events nor projection values. No new Session format or persistent index is needed. Offline fixture preparation and Preview packing may still explicitly supply child evidence for catalog completion; their caller already owns that corpus.
+
+This partially supersedes runtime catalog prerequisites and corpus revisions in [released migrations](../architecture/2026-08-31-released-session-format-migrations.md), the discovery-only assumption in [parent catalogs](../architecture/2026-09-01-parent-owned-subagent-catalog.md), and unopened-branch reads in [Web projection consumption](../simplification/2026-09-08-web-subagent-catalog-projections.md). Their format, creation, ordering, and transport decisions remain active. [Incomplete evidence](2026-09-19-v3-incomplete-child-catalog-evidence.md) continues to govern optional offline completion.
+
+## Alternatives considered
+
+**Catch child failures and continue backfill.** This still decodes every healthy child, hides failures, and permanently omits discovery facts when the parent successor is published.
+
+**Supply an empty child set without changing discovery.** This removes migration coupling but makes historical children disappear from catalog-only consumers.
+
+**Persist placeholder catalog events or another child index.** Unknown mode and label are not successful creation facts. A second persistent index adds write coordination and repair without improving header-based navigation.
+
+## Consequences
+
+Explicit direct-child discovery now enumerates N headers in addition to materializing D catalog facts. It avoids all child-body decoding, while ordinary parent migration has no corpus-dependent preparation. Historical rows may initially show an id instead of a label and cannot promise resumability. Headers that cannot be decoded cannot contribute a navigation row, but do not block opening another known Session.
+
+Raw and compressed persistence regressions cover V0–V3, child corruption and future formats, independent publication, unchanged predecessors, and stable parent revisions across child mutations. Service tests verify only the parent is observed. Client and Host tests verify unresolved addresses, selected-child decoding, mode resolution, and ownership rejection. The shipped Web preset-migration snapshot round-trips parent and child generations with a corrupt sibling and checks that only explicitly opened Sessions migrate.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
new file mode 100644
index 0000000000..43875dd8cd
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 独立于子会话迁移每个会话
+
+Status: implemented
+
+[English](2026-09-19-session-local-subagent-migration.md) | 中文
+
+## 问题
+
+运行时 V3→V4 准备收集每个直接子会话的 descriptor 以补全父 catalog。这在打开父会话之前解码完整子日志，而无关的不可读头部也可能阻止完整成员分类。因此，一个损坏子会话就会阻断有效父历史。历史版本标识还对整个根目录取指纹，无关文件变化也使父缓存准备失效。
+
+## 决策
+
+JSONL 只迁移读写方显式打开的会话。它保留已有 catalog 事实，不读取子正文或收集跨会话证据。读 open 准备当前逻辑事件但不发布；写 open 校验所选源并独占发布不可变后继。公开版本标识和准备复用只依赖所选文件。前代文件字节保持不变。
+
+发现机制合并父 catalog 事实与头部关系。没有 catalog 事实时，子代理服务返回未解析直接子条目；Web 从已有会话列表派生这些条目。菜单和分支刷新枚举头部，不请求子投影。选择子会话时打开自身历史，校验直接父归属和 descriptor，并解析模式与标签。此前地址不授予续接权限，输入区保持只读。子打开失败仅影响自身。显式程序读取和续接请求同样按需迁移选中会话；显式后代检查和批量迁移仍读取它们所请求的会话。
+
+Catalog 仍是成功创建事实的持久化来源。未解析发现行既不是持久化事件，也不是投影值。无需新会话格式或持久化索引。离线夹具准备和 Preview 打包仍可显式提供子证据来补全 catalog，因为调用者已拥有该语料库。
+
+本决策部分取代[已发布迁移](../architecture/2026-08-31-released-session-format-migrations.zh.md)中的运行时 catalog 前提与全库版本标识、[父 catalog](../architecture/2026-09-01-parent-owned-subagent-catalog.zh.md)中的仅靠 catalog 发现假设，以及 [Web 投影消费](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md)中的未打开分支读取。它们的格式、创建、排序和传输决策仍有效。[不完整证据](2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)继续约束可选离线补全。
+
+## 考虑过的替代方案
+
+**捕获子错误并继续回填。** 这仍解码所有健康子会话、隐藏失败，并在父后继发布时永久省略发现事实。
+
+**传入空子集合而不改发现机制。** 这消除了迁移耦合，却让历史子会话从仅消费 catalog 的调用方消失。
+
+**持久化占位 catalog 事件或另建子索引。** 未知模式和标签不是成功创建事实。第二份持久化索引增加写协调和修复工作，并不能改善基于头部的导航。
+
+## 影响
+
+显式直接子发现除物化 D 条 catalog 事实外，还枚举 N 个头部。它避免所有子正文解码，而普通父迁移没有依赖全库的准备工作。历史行最初可能显示 id 而非标签，且不能承诺可续接。无法解码的头部不能贡献导航行，但不会阻止打开另一个已知会话。
+
+原始与压缩持久化回归覆盖 V0–V3、子损坏与未来格式、独立发布、前代不变，以及子变化期间父版本标识稳定。服务测试确认只观察父会话。Client 和 Host 测试验证未解析地址、选中子解码、模式解析与归属拒绝。正式 Web preset-migration 快照在损坏兄弟会话存在时往返父子代次，并检查只有显式打开的会话才迁移。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
index 4ede5bd457..2d37c0209c 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.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-09-19-v3-incomplete-child-catalog-evidence.md
-2026-09-19-v3-incomplete-child-catalog-evidence.md: 22ca91502425257ed30aa4962f5a38497b8a8a92
-2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: c11e6de2c27b9892a72c28f327b6d06834d84038
+2026-09-19-v3-incomplete-child-catalog-evidence.md: d9cab54d0d381667e840d666a48608298464441e
+2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: 248cc0cc7f899837f06e2cc082b174e87d125262
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
index 22ca915024..d9cab54d0d 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
@@ -10,9 +10,9 @@ A valid V3 child log can have no own descriptor, an unsupported descriptor versi
 
 ## Decision
 
-The V3→V4 migration appends a missing parent catalog entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions contribute no new catalog fact. Existing parent entries and child events remain intact. This replaces only the missing-evidence refusal in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
+Optional V3→V4 catalog completion for offline fixture preparation and Preview packing appends a missing parent entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions contribute no new fact; existing parent entries and child events remain intact. Runtime JSONL migration does not collect this evidence and restores each Session independently, as specified in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
 
-Known child creation times must still match existing parent entries. Mode/label and descriptor fields are checked only for exactly one supported own descriptor. Invalid fields in that descriptor, corrupt logs, unreadable membership, unsupported selected generations, and changed source revisions retain their existing failures.
+Supplied child creation times must match existing parent entries. Mode, label, and descriptor fields are checked only for exactly one supported own descriptor. These evidence checks belong to explicit offline completion; child corruption or unsupported generations never prevent runtime parent migration.
 
 ## Alternatives considered
 
@@ -24,6 +24,8 @@ Known child creation times must still match existing parent entries. Mode/label
 
 ## Consequences
 
-A historical child without a usable descriptor remains readable by id but may be absent from its parent's direct-child catalog. Existing catalog entries remain visible. Once a V4 successor is published, opening it does not rescan historical children; automatic later catalog repair is outside this migration. Preparation still rechecks child revisions before publication, so newly available evidence cannot silently bypass source consistency checks.
+A historical child without a usable descriptor remains discoverable from a readable parent-linked header even when no parent catalog entry exists. Runtime migration preserves that absence rather than inventing a fact. The child’s own open performs decoding and reports any failure locally; publishing a parent successor never requires successful child decoding.
 
-Unit, JSONL read/write, and Preview packing tests cover unavailable evidence, unchanged source bytes, retained entries, identity conflicts, and evidence changes before publication.
+Pure completion and Preview tests retain unavailable-evidence, existing-entry, and conflict coverage. JSONL read/write regressions cover independent parent and child opens, stable parent revisions across child changes, and unchanged predecessor bytes.
+
+The [Session-local migration decision](./2026-09-19-session-local-subagent-migration.md) supersedes runtime child-body collection and unopened-branch projection reads; optional offline completion and durable catalog semantics remain active.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
index c11e6de2c2..248cc0cc7f 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## Decision
 
-V3→V4 迁移只在恰好一个受支持的自身子 descriptor 提供发现字段时，追加缺失的父目录项。其他 descriptor 数量及不受支持的版本不贡献新的目录事实。已有父目录项和子事件保持完整。这只替代[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)中的证据缺失拒绝规则。
+离线夹具准备和 Preview 打包中的可选 V3→V4 catalog 补全，仅在恰好一个受支持的自身子 descriptor 提供发现字段时追加缺失父条目。其他 descriptor 数量或不支持的版本不贡献新事实，已有父条目和子事件保持完整。运行时 JSONL 迁移不收集这些证据，并按[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)独立恢复各会话。
 
-已知子创建时间仍必须与已有父目录项一致。只有恰好一个受支持的自身 descriptor 时，才校验其字段并比较 mode／label。该 descriptor 字段无效、日志损坏、成员关系不可读、所选代际不受支持以及源修订变化仍保留原有失败行为。
+传入子创建时间必须匹配已有父条目。只有恰好一个受支持自身 descriptor 时才检查模式、标签和 descriptor 字段。这些证据检查属于显式离线补全；子会话损坏或不支持的代次不会阻止运行时父会话迁移。
 
 ## Alternatives considered
 
@@ -24,6 +24,8 @@ V3→V4 迁移只在恰好一个受支持的自身子 descriptor 提供发现字
 
 ## Consequences
 
-没有可用 descriptor 的历史子 Session 仍可按 id 读取，但可能不出现在其父级的直属子目录中。已有目录项仍可见。V4 后继发布后，打开它不会重新扫描历史子日志；后续自动修复目录不属于本迁移。准备过程仍会在发布前复查子修订，因此新出现的证据无法悄悄绕过源一致性检查。
+即使没有父 catalog 条目，缺少可用 descriptor 的历史子会话仍可通过可读且关联父会话的头部被发现。运行时迁移保留该缺失状态，不虚构事实。子会话自身 open 执行解码并局部报告失败；发布父后继从不要求子解码成功。
 
-单元、JSONL 读写和 Preview 打包测试覆盖不可用证据、源字节不变、条目保留、身份冲突以及发布前的证据变化。
+纯补全与 Preview 测试保留不可用证据、已有条目和冲突覆盖。JSONL 读写回归覆盖父子独立打开、子变化期间父版本标识稳定，以及前代字节不变。
+
+[会话独立迁移决策](./2026-09-19-session-local-subagent-migration.zh.md)取代运行时子正文收集与未打开分支投影读取；可选离线补全和持久化 catalog 语义仍有效。
diff --git a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.i18n.yaml
index d589324465..f05b4787c1 100644
--- a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.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-09-08-web-subagent-catalog-projections.md
-2026-09-08-web-subagent-catalog-projections.md: 766d33e581bcac53844b0836f23cda615858fc27
-2026-09-08-web-subagent-catalog-projections.zh.md: ef14db2530ed10a7aa34408c5a6fada6f0a28858
+2026-09-08-web-subagent-catalog-projections.md: f714418a8641b76228cf8723657205fbfda22133
+2026-09-08-web-subagent-catalog-projections.zh.md: c23b29f47795a6b8113d5be5f7a57c4713e203d9
diff --git a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md
index 766d33e581..f714418a86 100644
--- a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md
+++ b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md
@@ -10,9 +10,9 @@ The parent catalog projection already publishes complete membership through the
 
 ## Decision
 
-The Client retains catalog membership only in its standard per-Session projection store. Initial `session.projections` reads return a complete projection baseline from one live-preferred Session observation. The endpoint accepts any Session id and has no catalog-specific dependency or validation. The same observation supplies the values and sequence cursor. Initial baselines and live control frames use the store's existing sequence ordering, so an older response cannot replace a newer value. The endpoint does not activate an Agent or sample child activity. Opening a conversation uses its follow baseline without scheduling a second projection read; unopened catalog branches still use explicit reads.
+The Client retains catalog membership only in its standard per-Session projection store. Initial `session.projections` reads return a complete projection baseline from one live-preferred Session observation. The endpoint accepts any Session id and has no catalog-specific dependency or validation. The same observation supplies the values and sequence cursor. Initial baselines and live control frames use the store's existing sequence ordering, so an older response cannot replace a newer value. The endpoint does not activate an Agent or sample child activity. Opening a conversation uses its follow baseline without scheduling a second projection read; unopened branches use header relationships from the Session list instead of requesting child projections. Missing historical catalog entries remain non-durable unresolved navigation rows until the child is opened.
 
-Feature consumers select `subagentCatalog` from `projectionsBySession` and derive row activity from Session-list baselines and status events. Session summaries report Agent availability separately; Agent creation and disposal republish the existing summary event. Completed subagents retain their summaries and display projections after removal. Generic projection reads own loading and error state; parent availability comes from the Session list independently of membership. Opening a loaded catalog reuses its data; an initial failure can be retried. Reconnect cancels previous reads and starts fresh reads for requested catalogs. Session removal cancels its pending read and marks parent availability false; projection responses cannot change Agent availability.
+Feature consumers select `subagentCatalog` from `projectionsBySession`, supplement missing rows from parent-linked subagent summaries, and derive activity from Session-list baselines and status events. Header-discovered rows carry unresolved mode and grant no continuation authority. Menu and branch refreshes update only the lightweight Session list. Opening the selected child validates its descriptor and parent and resolves the mode; a failed open stays local to that child. Existing projection ordering, generic explicit projection reads, and independent parent availability remain unchanged.
 
 The [parent-catalog decision](../architecture/2026-09-01-parent-owned-subagent-catalog.md) owns durable creation facts and ordering. This decision supersedes the dedicated membership-refresh mechanism in [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md); that note remains active for navigation, control, and presentation decisions.
 
@@ -29,3 +29,5 @@ Host summaries replace running and availability state; local create/fork placeho
 Membership changes use the existing control stream without extra catalog notifications or reads. Whole-value projection publication still costs O(D) for D children; this change does not introduce delta transport. Initial reads return the observation's complete projection baseline, including values beyond the catalog, so they reuse standard baseline semantics at the cost of that additional initial payload. Session sequence ordering does not establish identity across reused Session ids.
 
 Manager tests cover pushed membership, stale initial responses, lazy loading, status composition, retained completion metadata, retry, removal of empty catalogs, late create/fork responses, and reconnect cancellation. Host tests exercise the shared control stream and cold observations. The persisted-subagent Web scenario covers nested historical navigation and continuation through the shipped application.
+
+The [Session-local migration decision](../bug-fix/2026-09-19-session-local-subagent-migration.md) supersedes runtime child-body collection and unopened-branch projection reads; optional offline completion and durable catalog semantics remain active.
diff --git a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md
index ef14db2530..c23b29f477 100644
--- a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md
+++ b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-Client 仅在标准逐 Session projection store 中保留目录成员关系。初始 `session.projections` 读取通过一次 live-preferred Session observation 返回完整 projection 基线。endpoint 接受任意 Session id，不含目录专用依赖或校验。值与序号游标来自同一次 observation。初始基线与实时 control 帧使用 store 既有的序号排序，因此旧响应不能替换新值。该 endpoint 不激活 Agent，也不采样子代理活动状态。打开会话时使用其 follow baseline，不再额外调度一次投影读取；未打开的目录分支仍使用显式读取。
+Client 仅在标准每会话投影存储中保留 catalog 事实。显式 `session.projections` 读取从一次优先存活来源的会话观察返回完整基线；端点接受任意会话 id，不依赖 catalog 专用校验。观察同时提供数值和序列游标；初始基线与实时控制帧遵循已有序列排序，旧响应不能覆盖新值。端点不激活 Agent 或采样子活动。打开对话使用 follow 基线，不另行请求投影。未打开分支使用会话列表的头部关系，不请求子投影；缺失的历史 catalog 条目保持为非持久化、未解析的导航行，直到打开子会话。
 
-功能消费者从 `projectionsBySession` 中选择 `subagentCatalog`，并从 Session 列表基线与状态事件派生行活动状态。Session 摘要单独报告 Agent 可用性；Agent 创建与销毁重新发布已有摘要事件。完成的子代理在移除后保留摘要与展示 projection。通用 projection 读取拥有加载与错误状态；父 Agent 可用性来自 Session 列表，独立于成员关系。打开已加载目录会复用数据，初始失败可以重试。重连取消此前的读取，并为已请求的目录重新读取。Session 移除会取消其待完成读取并将父 Agent 可用性标为 false；projection 响应不能改变 Agent 可用性。
+功能消费者从 `projectionsBySession` 选择 `subagentCatalog`，用关联父会话的子代理摘要补充缺失行，并从会话列表基线和状态事件派生活动。头部发现的条目携带未解析模式，不授予续接权限。菜单与分支刷新只更新轻量会话列表。打开选中的子会话时校验 descriptor 和父归属并解析模式，失败仅影响该子会话。已有投影排序、通用显式投影读取和独立父可用性保持不变。
 
 [父目录决策](../architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明持久创建事实与顺序。本决策取代 [Web 子代理会话](../feature/2026-07-27-web-subagent-conversations.zh.md) 中的专用成员刷新机制；该记录继续保留导航、控制与展示决策。
 
@@ -29,3 +29,5 @@ Host 摘要替换运行状态与可用性；本地 create/fork 占位摘要只
 成员变化使用既有 control stream，无需额外目录通知或读取。对 D 个子级发布完整 projection 值仍需 O(D)；本变更不引入增量传输。初始读取返回 observation 的完整 projection 基线，其中包括目录以外的值，以额外初始载荷换取标准基线语义的复用。Session 序号排序不确立复用 Session id 之间的身份关系。
 
 Manager 测试覆盖成员推送、过时初始响应、按需加载、状态组合、完成元数据保留、重试、空目录移除、晚到的 create/fork 响应与重连取消。Host 测试覆盖共享 control stream 与冷 observation。持久化子代理 Web 场景通过发布应用验证嵌套历史导航与续传。
+
+[会话独立迁移决策](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代运行时子正文收集与未打开分支投影读取；可选离线补全和持久化 catalog 语义仍有效。
diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts
index d8fccb3271..0874c1da15 100644
--- a/apps/web/tests/preset-migration.snapshot.ts
+++ b/apps/web/tests/preset-migration.snapshot.ts
@@ -13,6 +13,7 @@ import type {} from '@deepseek-ai/dsh-api-session-controller'
 import { normalizeSessionSnapshots } from '@deepseek-ai/dsh-session-snapshot'
 import { launchWebScaffold, webSnapshotMode } from './scaffold.ts'
 
+const childFixturePath = fileURLToPath(new URL('../../../snapshots/web/preset-migration/session.1.v2.jsonl', import.meta.url))
 const fixturePath = fileURLToPath(new URL('../../../snapshots/web/preset-migration/session.v2.jsonl', import.meta.url))
 
 describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration through the Web Host', () => {
@@ -32,6 +33,27 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
       await mkdir(dirname(predecessor), { recursive: true })
       await writeFile(predecessor, source)
 
+      const childId = SessionId('preset-migration-child')
+      const brokenId = SessionId('preset-migration-broken-child')
+      const childFixture = (await readFile(childFixturePath, 'utf8')).trimEnd().split('\n')
+        .map((line): Record<string, unknown> => JSON.parse(line) as Record<string, unknown>)
+      const childRows: Record<string, unknown>[] = childFixture.slice(1).map((row, seq) => ({ ...row, seq, time: seq + 3 }))
+      const childHeader = { ...childFixture[0], id: childId, parentSession: id, cwd: scaffold.workspaceCwd }
+      const childSource = Buffer.concat([childHeader, ...childRows].map(row => zstdCompressSync(Buffer.from(JSON.stringify(row) + '\n'))))
+      const childPath = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, childId, 2, 'zstd')
+      const brokenPath = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, brokenId, 2, 'zstd')
+      await mkdir(dirname(childPath), { recursive: true })
+      await mkdir(dirname(brokenPath), { recursive: true })
+      await writeFile(childPath, childSource)
+      await writeFile(brokenPath, Buffer.concat([
+        zstdCompressSync(Buffer.from(JSON.stringify({ ...childHeader, id: brokenId }) + '\n')),
+        zstdCompressSync(Buffer.from('{broken\n' + JSON.stringify({ type: 'turn/end', seq: 1, time: 2,
+          data: { turn: 1, reason: { kind: 'completed' } } }) + '\n')),
+      ]))
+      const brokenSource = await readFile(brokenPath)
+      const listed = await scaffold.ctx.sessionController.list({}, new AbortController().signal)
+      expect(listed.items.map(item => item.sessionId)).toEqual(expect.arrayContaining([id, childId, brokenId]))
+
       const reader = await scaffold.ctx.sessionPersistence.open(id, 'read')
       try {
         expect(reader.header.agentPreset).toBe('ptc')
@@ -49,6 +71,30 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
         .filter(event => event.type === 'agent-preset/selected')
         .map(event => event.data.agentPreset)).toEqual(withSelections ? ['ptc', 'standard', 'ptc'] : [])
 
+      const childSuccessor = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, childId, SESSION_FORMAT_VERSION, 'zstd')
+      await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' })
+      const signal = new AbortController().signal
+      const address = { kind: 'subagent', parentSessionId: id, childSessionId: childId, mode: 'unresolved' } as const
+      const childPage = await scaffold.ctx.sessionController.page({ address, throughSeq: childRows.length - 1 }, signal)
+      expect(childPage.records.map(record => record.event.type)).toEqual(childRows.map(row => row['type']))
+      await expect(scaffold.ctx.sessionController.page({ address: { ...address, childSessionId: brokenId }, throughSeq: 1 }, signal))
+        .rejects.toThrow()
+      await expect(scaffold.ctx.sessionController.page({ address: { kind: 'session', sessionId: id }, throughSeq: rows.length - 1 }, signal))
+        .resolves.toMatchObject({ hasMore: false })
+      const childWriter = await scaffold.ctx.sessionPersistence.open(childId, 'write')
+      await childWriter.close()
+      const childPublished = await readFile(childSuccessor)
+      const childText = Buffer.concat(scanZstdFrames(childPublished).frames
+        .map(({ start, end }) => zstdDecompressSync(childPublished.subarray(start, end)))).toString('utf8')
+      expect(childText.trimEnd().split('\n').map((line): unknown => JSON.parse(line))).toEqual([
+        { ...childHeader, version: SESSION_FORMAT_VERSION, agentPreset: 'ptc' }, ...childRows,
+      ])
+      expect(await readFile(childPath)).toEqual(childSource)
+      expect(await readFile(brokenPath)).toEqual(brokenSource)
+      await expect(readFile(generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, brokenId, SESSION_FORMAT_VERSION, 'zstd')))
+        .rejects.toMatchObject({ code: 'ENOENT' })
+
+      await scaffold.ctx.sessions.flush(resolved.agent.session)
       const publishedBytes = await readFile(successor)
       const published = Buffer.concat(scanZstdFrames(publishedBytes).frames
         .map(({ start, end }) => zstdDecompressSync(publishedBytes.subarray(start, end)))).toString('utf8')
@@ -60,6 +106,9 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
           : row),
         // Agent activation closes its restored prefix with a fresh seed marker.
         { type: 'session/end-seed', seq: rows.length, time: 0, data: {} },
+        { type: 'permission/preset', seq: rows.length + 1, time: 0, data: { preset: 'workspace-write' } },
+        { type: 'sandbox/mode', seq: rows.length + 2, time: 0, data: { mode: 'workspace-write' } },
+        { type: 'approval/policy', seq: rows.length + 3, time: 0, data: { policy: 'ask' } },
       ].map(row => JSON.stringify(row)).join('\n') + '\n'
       const context = { sessionIds: [id], cwd: scaffold.workspaceCwd }
       expect(normalizeSessionSnapshots([published], context)).toEqual(normalizeSessionSnapshots([expected], context))
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index a3e2cdf686..da1b1dd793 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: 9f9a47ff24f67dfda288c046b482ec8a1127787c
-config-catalog.zh.md: 95d9bb8415f5f7bb116f58bbd8f9a46c3cf42182
+config-catalog.md: 8d0f32cc4d1487dd7170737ee12b5c2a3ed70bc6
+config-catalog.zh.md: 677c025fff4486da212a8f1b53d5d8390e410a32
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 9f9a47ff24..8d0f32cc4d 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2208,7 +2208,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session/session-persistence-jsonl/src/index.ts:90`](../packages/session/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session/session-persistence-jsonl/src/index.ts:88`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 95d9bb8415..677c025fff 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -2210,7 +2210,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-来源：[`packages/session/session-persistence-jsonl/src/index.ts:90`](../packages/session/session-persistence-jsonl/src/index.ts)
+来源：[`packages/session/session-persistence-jsonl/src/index.ts:88`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 034d835426..ae1d614ac8 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: d642fe1658926b17cb29f280803f12e61228be60
-subagent.zh.md: ff153c7861b4ac46bb058efd00a2f5a50181b6f2
+subagent.md: dc3ebd74d2f6674f3f81c1a77e36cceeaf0664ab
+subagent.zh.md: 03ada2686dd9a55f0ebaa3dc7e8cf5c1ac9c1db1
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index d642fe1658..dc3ebd74d2 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -268,7 +268,7 @@ A local one-shot provider appends the descriptor inside the child's initial turn
 
 The model-facing `list_agents` adapter reports current activity as `running` or `inactive`. These values do not describe task completion or guarantee that `send_message` will succeed.
 
-`SubagentRuntime.listChildren(parentSessionId, signal?)` reads the parent's `subagentCatalog` view through a live-preferred Session observation and releases that observation on success or failure. It returns direct-child entries in parent event order without reading child logs or enumerating the Session corpus. Query failures propagate; a missing catalog projection fails explicitly. Browser rows derive membership from the shared projection store and add activity from Session status; the control stream pushes complete catalog updates. `listDescendants()` retains corpus traversal, child-identity diagnostics, and complete `hasChildren` computation. [The parent-catalog Agent Note](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns creation, fork isolation, ordering, and persistence costs.
+`SubagentRuntime.listChildren(parentSessionId, signal?)` owns one parent observation and supplements its catalog with Session-header discovery. It returns `SubagentDiscoveryEntry[]`: catalog facts in event order, followed by `{ id: SessionId; createdAt: number; mode: 'unresolved' }` rows for children without a catalog fact. It never opens child bodies. Query failures propagate; a missing parent catalog projection fails explicitly. `listDescendants()` explicitly reads child identities and returns diagnostics and complete `hasChildren` information. [Session-local migration](../../.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md) owns lazy discovery and migration isolation.
 
 `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:
 
@@ -465,7 +465,7 @@ The spawn and fork backends create an ordinary one-shot agent through `parent.ct
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
 - **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/runtime-diagnostics/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
 
-`SubagentCatalogEntry` describes one successful direct-child creation fact; `SubagentCatalogState` is the host-only projection state. `listChildren()` owns a live-preferred parent observation without opening child logs. Browser consumers read `subagentCatalog` through the shared Session projection store and combine membership with Session-list activity. `SubagentCatalogRow` belongs to complete-descendant listing. [The parent-catalog decision](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns the persistent facts and read semantics.
+`SubagentCatalogEntry` describes a durable successful-creation fact; `SubagentCatalogState` is its host projection state. `SubagentDiscoveryEntry` adds non-durable unresolved header rows for direct listing. Browser consumers combine catalog facts with parent-linked summaries and cached child identities. `SubagentAddress` carries parent and child ids with known or unresolved mode; history opening validates the child descriptor before continuation. `SubagentCatalogRow` belongs to complete-descendant listing.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -574,15 +574,15 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>
 
 /**
- * Read the parent's durable direct-child catalog without loading or resuming an Agent.
+ * Read the parent's catalog and discover missing direct children from Session headers.
  * The service owns and releases the live-preferred Session observation.
  * @param parentSessionId - parent whose direct children are requested.
  * @param signal - cancellation forwarded to the Session query.
- * @returns catalog children in parent event order.
+ * @returns catalog children in event order, then unresolved children whose bodies remain unread.
  * @throws {@link SubagentError} when query or catalog projection is unavailable.
  * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
  */
-listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>
 
 /**
  * Enumerate the root's complete session-backed subagent tree in stable
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ff153c7861..03ada2686d 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -268,7 +268,7 @@ interface ContinuableCreateSpec {
 
 模型侧的 `list_agents` 适配器将当前活动表示为 `running` 或 `inactive`。这些值不描述任务完成情况，也不保证 `send_message` 会成功。
 
-`SubagentRuntime.listChildren(parentSessionId, signal?)` 通过优先使用在线 Session 的观察读取父会话的 `subagentCatalog` 视图，并在成功或失败时释放观察。它按父会话事件顺序返回直接子级条目，不读取子级日志，也不枚举 Session 语料库。查询失败直接传播；缺少目录投影时显式失败。浏览器条目从共享 projection store 派生成员关系，并从 Session 状态补充活动状态；control stream 推送完整目录更新。`listDescendants()` 保留语料库遍历、子级身份诊断和完整的 `hasChildren` 计算。[父目录 Agent Note](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明创建、fork 隔离、排序和持久化成本。
+`SubagentRuntime.listChildren(parentSessionId, signal?)` 持有一次父观察，并以会话头部发现补充 catalog。它返回 `SubagentDiscoveryEntry[]`：先按事件顺序返回 catalog 事实，再为缺少 catalog 事实的子会话返回 `{ id: SessionId; createdAt: number; mode: 'unresolved' }` 行。不打开任何子正文。查询失败向上传播，缺少父 catalog 投影时显式报错。`listDescendants()` 显式读取子身份，返回诊断和完整 `hasChildren` 信息。[会话独立迁移](../../.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md) 负责按需发现与迁移隔离。
 
 `SubagentRuntime.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -469,7 +469,7 @@ spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
 - **Fork 种子注入**使用 [`CreateAgentOptions.seed`](core.zh.md#creation-and-ownership)（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/runtime-diagnostics/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
 
-`SubagentCatalogEntry` 描述一条成功创建直接子级的事实；`SubagentCatalogState` 是仅 host 使用的 projection state。`listChildren()` 拥有一次 live-preferred 父 Session observation，不打开子级日志。浏览器消费者通过共享 Session projection store 读取 `subagentCatalog`，并将成员关系与 Session 列表活动状态组合。`SubagentCatalogRow` 属于完整后代列表。[父目录决策](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 规定持久事实与读取语义。
+`SubagentCatalogEntry` 描述持久化成功创建事实，`SubagentCatalogState` 是其 Host 投影状态。`SubagentDiscoveryEntry` 为直接列表增加非持久化、未解析的头部行。浏览器消费者合并 catalog 事实、关联父会话的摘要与缓存子身份。`SubagentAddress` 携带父子 id 及已知或未解析模式；历史打开在续接前校验子会话 descriptor。`SubagentCatalogRow` 属于完整后代列表。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -578,15 +578,15 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>
 
 /**
- * Read the parent's durable direct-child catalog without loading or resuming an Agent.
+ * Read the parent's catalog and discover missing direct children from Session headers.
  * The service owns and releases the live-preferred Session observation.
  * @param parentSessionId - parent whose direct children are requested.
  * @param signal - cancellation forwarded to the Session query.
- * @returns catalog children in parent event order.
+ * @returns catalog children in event order, then unresolved children whose bodies remain unread.
  * @throws {@link SubagentError} when query or catalog projection is unavailable.
  * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
  */
-listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>
 
 /**
  * Enumerate the root's complete session-backed subagent tree in stable
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 04a2230cee..dff680a206 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-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/tool-catalog.md
-tool-catalog.md: 2f5746fc63e73b1caf2692a05ff942c13399e6bc
-tool-catalog.zh.md: 6fb80b689ca569834e8f585c765547d23cec50df
+tool-catalog.md: 03e2813a528ed1415f9e89593ce4dc8fa884b7e5
+tool-catalog.zh.md: d66c7677a0452fac8557596cd2c666136c0630b1
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 2f5746fc63..03e2813a52 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -1886,7 +1886,7 @@ Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/sub
 
 ### `list_agents`
 
-List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.
+List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.
 
 ```json
 {
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 6fb80b689c..d66c7677a0 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -1892,7 +1892,7 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
 
 ### `list_agents`
 
-按持久 id 和标签列出你的可继续后台 subagent。用它回忆你启动过哪些 subagent，而不是轮询完成情况——subagent 完成时你会被告知。状态来自实时注册表：running 表示 agent 此刻正在工作；inactive 表示没有轮次在执行，包括已加载和需要恢复的 child。inactive 不表示任务完成、成功、失败或等待其他 agent。`send_message` 会在运行中 child 的最近 step 边界 steer 消息，或为 inactive child 启动或恢复轮次，且无论处于哪种状态，直接子级都仍可作为 `send_message` 的目标。该快照并非投递承诺；`send_message` 会执行权威检查，仍可能失败。无法读取的子级仅在 `descendants` 作用域中作为诊断信息报告。`descendants` 作用域会按稳定的前序顺序遍历你下方的整棵树，并为每个条目标注其持久的直接父会话 id 和深度。只有深度为 1 的条目可以使用 `send_message`；更深的条目只能作为 `interrupt_agent` 的候选目标。
+按持久 id 和标签列出你的可继续后台 subagent。用它回忆你启动过哪些 subagent，而不是轮询完成情况——subagent 完成时你会被告知。状态来自实时注册表：running 表示 agent 此刻正在工作；inactive 表示没有轮次在执行，包括已加载和需要恢复的 child。inactive 不表示任务完成、成功、失败或等待其他 agent。`send_message` 会在运行中 child 的最近 step 边界 steer 消息，或为 inactive child 启动或恢复轮次，且无论处于哪种状态，直接子级都仍可作为 `send_message` 的目标。该快照并非投递承诺；`send_message` 会执行权威检查，仍可能失败。无法在未打开时确定身份的子级会作为诊断信息报告。`descendants` 作用域会按稳定的前序顺序遍历你下方的整棵树，并为每个条目标注其持久的直接父会话 id 和深度。只有深度为 1 的条目可以使用 `send_message`；更深的条目只能作为 `interrupt_agent` 的候选目标。
 
 ```json
 {
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index 8ceb4a8da4..c2406e4699 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: 228ed88ed20b9f9581496468e47079afd1542e4f
-README.zh.md: edebf8bdda249cf0ea6797db7dd77fcfa973074a
+README.md: 01701383352458de80d82bbfa1183136fb0bdade
+README.zh.md: 4ac801506db13faceee1f8c7971f90a6aae0bfff
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index 228ed88ed2..0170138335 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -29,7 +29,7 @@ History pages and follow opening snapshots carry one `{ type: 'event', event: Se
 
 The Client journal validates exact V3 event envelopes before publishing follow snapshots, live entries, or history pages. It reuses the browser-safe Session validators for required surface markers, exact replacement endpoints, earlier unique source seqs, embedded Assistant provider metadata, request-header omissions, and tool-error consistency. Invalid records fail without field stripping or normalization; range membership and source existence remain durable-log checks on the Host.
 
-Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` reads one complete baseline through a live-preferred Session observation without activating an Agent. It returns null for a missing Session and serves any registered projection keys. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Initial reads and live projection frames use the same sequence ordering.
+Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` reads one complete baseline through a live-preferred Session observation without activating an Agent. It returns null for a missing Session and serves any registered projection keys. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Initial reads and live projection frames use the same sequence ordering. Header-discovered subagent history accepts `mode: 'unresolved'`; opening still validates the exact parent and the child’s own descriptor. The Client derives the usable mode from the opened child projection, and a failed child open does not invalidate its parent.
 
 Client list rows and resident Sessions use the current `sessionListMetadata` projection to reject stale blank-session hints; recency is the later of the summary timestamp and the projected last user prompt. When SessionManager creates an instance before its list row arrives, it reconciles blankness with metadata already retained for that Session. An opened conversation is therefore not reused by New Session even when an older list response still marks it blank.
 
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index edebf8bdda..4ac801506d 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 Client journal 在发布 follow 快照、live entry 或历史页之前验证精确的 V3 事件 envelope。它复用浏览器安全的 Session validator，检查必需的 surface marker、精确的 replacement endpoint、更早且唯一的 source seq、内嵌 Assistant 提供方元数据、request header 可选字段的省略规则以及工具错误一致性。无效 record 直接失败，不删除字段或归一化；范围成员与来源存在性仍由 Host 的持久日志检查。
 
-每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 通过一次 live-preferred Session observation 读取完整基线，不激活 Agent。Session 不存在时返回 null，并可提供任意已注册的 projection key。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。初始读取与实时 projection 帧使用相同的序号排序规则。
+每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 通过一次 live-preferred Session observation 读取完整基线，不激活 Agent。Session 不存在时返回 null，并可提供任意已注册的 projection key。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。初始读取与实时 projection 帧使用相同的序号排序规则。 从头部发现的子代理历史接受 `mode: 'unresolved'`；打开时仍校验精确父会话和子会话自身 descriptor。Client 从已打开子会话的投影确定可用模式，子会话打开失败不会使父会话失效。
 
 Client 列表行和驻留 Session 使用当前 `sessionListMetadata` 投影纠正过期的空白会话提示；最近活动时间取摘要时间戳与投影中最后一次用户提示词时间的较晚值。当 SessionManager 在列表行到达前创建实例时，会使用已保留的该 Session 元数据对账空白状态。因此，即使旧列表响应仍将已有对话标为空白，新会话操作也不会复用已经打开过的对话。
 
diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts
index b6061ce2b4..f396b364fd 100644
--- a/packages/api/session-controller/src/client/sessions/manager.ts
+++ b/packages/api/session-controller/src/client/sessions/manager.ts
@@ -165,6 +165,14 @@ export class SessionManager {
         }
       }
     }
+    const summary = this.summaries.find(item => item.sessionId === sessionId)
+    if (summary?.origin === 'subagent' && summary.parentSessionId !== undefined) {
+      return {
+        parentSessionId: summary.parentSessionId,
+        childSessionId: sessionId,
+        mode: this.projectionStores.get(sessionId)?.values().subagent?.mode ?? 'unresolved',
+      }
+    }
     return undefined
   }
 
@@ -666,10 +674,6 @@ export class SessionManager {
     this.listInflight = null
     void this.refreshList()
     const parents = new Set(this.projectionLoads.keys())
-    for (const id of this.sessions.keys()) {
-      const address = this.addresses.get(id)
-      if (address !== undefined) parents.add(address.parentSessionId)
-    }
     for (const { controller } of this.projectionInflight.values()) controller.abort()
     this.projectionInflight.clear()
     this.projectionLoads.clear()
diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts
index cd38a26fcf..bb4540f94c 100644
--- a/packages/api/session-controller/src/client/sessions/session.ts
+++ b/packages/api/session-controller/src/client/sessions/session.ts
@@ -812,6 +812,7 @@ export class Session implements SessionFace {
   }
 
   private buildSnapshot(): SessionSnapshot {
+    const identity = this.projections.values().subagent
     return {
       sessionId: this.sessionId,
       pendingSubmissions: this.pendingSubmissions,
@@ -819,7 +820,9 @@ export class Session implements SessionFace {
       subagent: this.address === undefined
         ? null
         : {
-          address: this.address,
+          address: this.address.mode === 'unresolved' && identity != null
+            ? { ...this.address, mode: identity.mode }
+            : this.address,
           ...(this.parentAvailable === undefined ? {} : { parentAvailable: this.parentAvailable }),
         },
       removed: this.removed,
diff --git a/packages/api/session-controller/src/history.ts b/packages/api/session-controller/src/history.ts
index a22badc1f1..ab31da6737 100644
--- a/packages/api/session-controller/src/history.ts
+++ b/packages/api/session-controller/src/history.ts
@@ -364,7 +364,7 @@ function validateAddress(
       reason: 'unsupported',
     })
   }
-  if (identity.mode !== address.mode) {
+  if (address.mode !== 'unresolved' && identity.mode !== address.mode) {
     throw new RemoteError('subagent/unauthorized', 'subagent mode does not match the supplied address', {
       childSessionId: address.childSessionId,
     })
diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts
index a925e9da83..bd4d3d1840 100644
--- a/packages/api/session-controller/src/types.ts
+++ b/packages/api/session-controller/src/types.ts
@@ -393,7 +393,7 @@ export type SessionAddress =
     readonly kind: 'subagent'
     readonly parentSessionId: SessionId
     readonly childSessionId: SessionId
-    readonly mode: 'one-shot' | 'continuable'
+    readonly mode: 'one-shot' | 'continuable' | 'unresolved'
   }
 
 /** One non-activating Session projection read. */
diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts
index 7ee5be5397..05495adfee 100644
--- a/packages/api/session-controller/tests/manager.client.spec.ts
+++ b/packages/api/session-controller/tests/manager.client.spec.ts
@@ -417,6 +417,33 @@ describe('Host Remote event routing', () => {
 })
 
 describe('subagent catalogs', () => {
+  it.for(['one-shot', 'continuable'] as const)('opens a header-discovered child on demand and resolves %s mode', async (mode, { mock, remote, start }) => {
+    remote.session.list.mockImplementation(() => Promise.resolve(ok({ items: [
+      summary(S1), summary(S2, { parentSessionId: S1, origin: 'subagent' }),
+    ] })))
+    mock.load(sessionWorld)
+    mock.stream(FOLLOW, followScript(ok({
+      records: [], hasMore: false,
+      projections: { asOfSeq: 0, values: { subagent: { mode, label: 'restored', seq: 0 } } },
+    })))
+    const client = await start()
+    const manager = new SessionManager(client.ctx.remote)
+    try {
+      await manager.refreshList()
+      manager.resolveTarget(S2)
+      expect(manager.subagentAddress(S2)).toEqual({ parentSessionId: S1, childSessionId: S2, mode: 'unresolved' })
+      expect(remote.session.projections).not.toHaveBeenCalled()
+      expect(mock.log.requests(FOLLOW)).toEqual([])
+      const child = manager.get(S2)
+      await child.open()
+      expect(mock.log.requests(FOLLOW)).toEqual([{
+        address: { kind: 'subagent', parentSessionId: S1, childSessionId: S2, mode: 'unresolved' },
+        assistantStream: true, maxMessages: 50,
+      }])
+      expect(child.getSnapshot().subagent?.address.mode).toBe(mode)
+    } finally { await manager.dispose() }
+  })
+
   it('keeps a catalog-discovered child address across identity resolution and status frames', async ({ mock, remote, start }) => {
     remote.session.list.mockImplementation(() => Promise.resolve(ok({ items: [
       summary(S1),
@@ -1010,33 +1037,24 @@ describe('connected generation', () => {
     expect(remote.session.page).toHaveBeenCalledTimes(historyCallsBefore)
   })
 
-  it('retains the durable parent address and refreshes that parent across reconnect', async ({ mock, remote }) => {
+  it('retains the durable parent address across reconnect without opening the parent', async ({ mock, remote }) => {
     const address = {
       parentSessionId: S1,
       childSessionId: S2,
       mode: 'continuable' as const,
     }
     remote.session.list.mockImplementation(() => Promise.resolve(ok({ items: [summary(S1)] as never[] })))
-    const parent = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.projections>>>()
-    remote.session.projections.mockImplementation(() => parent.promise)
     const manager = makeManager(mock, remote)
     manager.resolveTarget(address)
     manager.get(S2)
 
     manager.handleConnected()
     expect(manager.get(S2).getSnapshot().subagent).toEqual({ address })
-    parent.resolve(ok({ asOfSeq: 0, values: { subagentCatalog: [{ createdAt: 1,
-      id: S2, mode: 'continuable', label: 'worker',
-    }] } }))
 
     await vi.waitFor(() => {
       expect(remote.session.list.mock.calls.map(([request]) => request)).toHaveLength(1)
     })
-    await vi.waitFor(() => {
-      expect(remote.session.projections.mock.calls.map(([request]) => request)).toEqual([
-        { sessionId: S1 },
-      ])
-    })
+    expect(remote.session.projections).not.toHaveBeenCalled()
     expect(manager.get(S2).getSnapshot().subagent).toEqual({
       address,
       parentAvailable: true,
diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts
index 04b43972e9..2fae510838 100644
--- a/packages/api/session-controller/tests/transport.host.spec.ts
+++ b/packages/api/session-controller/tests/transport.host.spec.ts
@@ -641,6 +641,27 @@ describe('SessionHistoryController', () => {
       .rejects.toMatchObject({ code: 'subagent/unauthorized' })
   })
 
+  it('resolves a header-discovered address while retaining child ownership and descriptor validation', async () => {
+    const bench = await setup()
+    const parentSessionId = SessionId('unresolved-parent')
+    const childSessionId = SessionId('unresolved-child')
+    const header: SessionHeader = {
+      version: SESSION_FORMAT_VERSION, id: childSessionId, createdAt: 1, cwd: '/workspace',
+      isSeeded: false, origin: 'subagent', parentSession: parentSessionId,
+    }
+    cold(bench.ctx, header, [event('subagent/descriptor', SessionSeq(0), {
+      version: 3, mode: 'one-shot', provider: 'spawn',
+    })])
+    const address = { kind: 'subagent', parentSessionId, childSessionId, mode: 'unresolved' } as const
+    await expect(bench.transport.page({ address, throughSeq: 0 }, signal())).resolves.toMatchObject({
+      records: [{ type: 'event', event: { type: 'subagent/descriptor' } }],
+    })
+    await expect(bench.transport.page({ address: { ...address, parentSessionId: SessionId('wrong') }, throughSeq: 0 }, signal()))
+      .rejects.toMatchObject({ code: 'subagent/unauthorized' })
+    await expect(bench.transport.page({ address: { ...address, mode: 'continuable' }, throughSeq: 0 }, signal()))
+      .rejects.toMatchObject({ code: 'subagent/unauthorized' })
+  })
+
   it('reports an unavailable descriptor when an observed child has no projection value', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index 45a496719c..83ca816b51 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/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-subagent/README.md
-README.md: 1404e893add386b88a24d78675a4f0be06f497a0
-README.zh.md: 97c743b580e25cd50bcb01a3a7547cb7415a0e08
+README.md: 33d8da78b2cf27ccce1cfa8ee7c26ddb43b3d083
+README.zh.md: 9cc1fff725d8539abc648ab7d198413194674160
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index 1404e893ad..33d8da78b2 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -25,17 +25,17 @@ Use this package to browse every subagent conversation beneath a parent session,
 <a id="use-this-package"></a>
 ## Use this package
 
-The session header keeps the current session title as the lineage breadcrumb and appends a `/` count trigger when its direct catalog has entries or a read has failed. An absent catalog, an empty loading catalog, or a successfully loaded empty catalog hides the count trigger. The trigger opens that direct catalog, reports its total and running counts, and loads nested catalogs only when their rows expand. Select any depth to open that child's conversation with its exact `{parentSessionId, childSessionId, mode}` address, or use the row's trailing arrow to open the same address in the right Sidebar, preferring a separate pane when room permits.
+The session header keeps the current session title as the lineage breadcrumb and appends a `/` count trigger for known direct children or a catalog error. Rows combine existing parent catalog facts with Session-list header relationships, so historical children remain discoverable without opening their logs. Opening the menu or expanding a branch refreshes the lightweight Session list. Selecting a row opens only that child through its exact `{parentSessionId, childSessionId, mode}` address; a header-only row uses `mode: 'unresolved'` until its own descriptor is read. The trailing arrow opens the same address in the right Sidebar.
 
-This package registers the `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` resource and builtin Sidebar tab type. The resource refreshes the direct-parent catalog before it retains the child `SessionReference`, and releases the reference when the tab record closes. The tab renders the shared `conversation.content` Factory through `sidebar.chat.conversation`, fixes the local View to Chat, and omits the main Conversation header and width controls.
+This package registers the `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` resource and builtin Sidebar tab type. The resource refreshes the lightweight Session list before it retains the child `SessionReference`, and releases the reference when the tab record closes. The tab renders the shared `conversation.content` Factory through `sidebar.chat.conversation`, fixes the local View to Chat, and omits the main Conversation header and width controls.
 
 ### Browsing the tree
 
-Rows display mode plus activity and an optional log-backed title; running uses the shared ongoing loader, an inactive child whose latest closed turn completed normally uses the shared success dot, and other inactive children use the shared idle dot. Every row reserves the same 14px status column, centering smaller dots so titles align with the loader state. The compact header trigger vertically centers its activity glyph and count with a 4px gap. The trailing column stacks total durable provider usage above active-turn duration. Keyboard navigation works with ArrowRight/ArrowLeft to expand and collapse branches and ArrowUp/ArrowDown, Home, End, and Escape to navigate or close the tree. An unlabeled one-shot row falls back to its session id. A row is a known leaf only after its own catalog loads empty.
+Rows display mode plus activity and an optional log-backed title; unresolved rows display “Not opened” and use their id until identity data is available. Known parent catalog labels remain authoritative. Running, completed, and other inactive children use the shared ongoing, success, and idle indicators. Cached usage and duration remain optional. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree. A header-discovered child with no listed descendants or cached catalog entries is a leaf without a body read.
 
 ### Continuing a conversation
 
-A continuable child with a live parent keeps the ordinary input chrome: typing and Send stay available while the child runs because every follow-up joins the child's FIFO inbox, and an independent Stop routes through `subagents/interruptByParent`. A continuable child whose exact parent is unavailable and which is not running elects a read-only composer explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer with input and Send disabled but its independent Stop usable.
+An unresolved child keeps a read-only composer until opening its history supplies a valid identity. A continuable child with a live parent keeps the ordinary input chrome: follow-ups join the child’s FIFO inbox, and Stop routes through `subagents/interruptByParent`. A continuable child whose parent is unavailable and which is not running uses a read-only composer; while it runs, input and Send remain disabled but Stop stays usable. One-shot history remains read-only.
 
 ### The `@` reference source
 
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index 97c743b580..9cc1fff725 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -25,17 +25,17 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-会话页头保留当前会话 title 作为谱系面包屑，并在直接目录有子项或读取失败时追加 `/` 数量触发器。目录缺席、空目录加载中或成功加载为空时，均隐藏数量触发器。触发器打开该直接目录，报告总数与运行数，并且只在行展开时加载嵌套目录。选择任意深度，即可用该子会话的确切 `{parentSessionId, childSessionId, mode}` 地址打开其对话；也可以使用行尾箭头在右侧 Sidebar 打开同一地址，并在空间允许时优先使用独立分栏。
+会话头部保留当前标题作为层级导航，并为已知直接子会话或 catalog 错误追加 `/` 数量入口。列表行合并已有父 catalog 事实和会话列表中的头部关系，让历史子会话无需打开日志即可被发现。打开菜单或展开分支只刷新轻量会话列表。选择一行时，通过精确的 `{parentSessionId, childSessionId, mode}` 地址只打开该子会话；只有头部的条目使用 `mode: 'unresolved'`，直到读取自身 descriptor。末尾箭头将同一地址打开到右侧 Sidebar。
 
-本包注册 `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` 资源与 builtin Sidebar tab 类型。资源先刷新直接 parent 目录，再保留 child 的 `SessionReference`，并在 tab 记录关闭时释放 reference。tab 通过 `sidebar.chat.conversation` 渲染共享 `conversation.content` Factory，把局部 View 固定为 Chat，并省略主 Conversation 的 Header 与宽度控制。
+本包注册 `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` 资源和内置 Sidebar 标签类型。资源在持有子会话 `SessionReference` 前刷新轻量会话列表，并在标签记录关闭时释放引用。标签通过 `sidebar.chat.conversation` 渲染共享的 `conversation.content` Factory，将局部 View 固定为 Chat，省略主 Conversation 头部和宽度控件。
 
 ### 浏览目录
 
-行显示 mode、活动状态与由日志支撑的可选 title；running 使用共享 ongoing loading，最近一个已结束轮次正常完成的 inactive child 使用共享 success 绿点，其他 inactive child 使用共享 idle 灰点。每行都为状态图标预留相同的 14px 列宽，并将较小的圆点居中，使 title 与 loading 状态对齐。紧凑的页头触发器会垂直居中活动图标与数量，并保留 4px 水平间距。尾随列在上行显示提供方的持久化 token 用量总计，在下行显示活跃轮次耗时。键盘导航：ArrowRight/ArrowLeft 展开和折叠分支；ArrowUp/ArrowDown、Home、End 与 Escape 用于导航或关闭树。没有 label 的 one-shot 行回退到其会话 id。只有一行自身的目录加载为空后，它才是已知叶子。
+列表行显示模式、活动状态和可选的日志标题；未解析条目显示“尚未打开”，在身份数据可用前使用 id。已有父 catalog 标签仍具有权威性。运行、完成和其他空闲子会话分别使用共享的进行中、成功和空闲标记。缓存的用量和耗时为可选项。ArrowRight/ArrowLeft 展开或收起分支，ArrowUp/ArrowDown、Home、End、Escape 用于导航或关闭树。头部发现的子会话若没有列出的后代或缓存 catalog 条目，无需读取正文即可作为叶节点。
 
 ### 续接对话
 
-确切 parent 存活时，可继续 child 保留普通输入 chrome：child 运行期间输入和 Send 保持可用，因为每条后续消息都会进入 child 的 FIFO inbox，而独立的 Stop 经由 `subagents/interruptByParent` 路由。确切 parent 不可用且 child 未在运行的可继续 child 会选用说明恢复路径的只读编辑器；此类 child 仍在运行期间，selector 会让位给普通编辑器——输入区与 Send 被禁用，但独立的 Stop 保持可用。
+未解析子会话保持只读输入区，直到打开历史记录并得到有效身份。父代理在线的可继续子会话使用普通输入区：后续消息进入子代理 FIFO 收件箱，Stop 经 `subagents/interruptByParent` 路由。父代理不可用且未运行的可继续子会话使用只读输入区；仍运行时禁用输入和 Send，但保留 Stop。一次性子会话历史始终只读。
 
 ### `@` 引用 source
 
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
index 6dd416fb95..e734fd9dd9 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
@@ -17,7 +17,7 @@ import css from './SubagentHeaderLineage.module.css'
 
 type SubagentCatalogSnapshot = Omit<SessionProjectionSnapshot, 'values' | 'state'> & {
   state: 'loading' | 'ready' | 'error'
-  entries: (SessionProjectionMap['subagentCatalog'][number] & { activity: 'running' | 'inactive' })[]
+  entries: { id: SessionId; mode: SubagentAddress['mode']; label?: string; activity: 'running' | 'inactive' }[]
 }
 type Catalogs = Readonly<Record<SessionId, SubagentCatalogSnapshot>>
 
@@ -238,7 +238,8 @@ function CatalogRows({
           || (childCatalog.state === 'loading' && childCatalog.entries.length === 0)
         const summary = summaries[entry.id]
         const label = entry.label ?? entry.id
-        const mode = entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
+        const mode = entry.mode === 'unresolved' ? t('mode.unresolved')
+          : entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
         const completed = entry.activity === 'inactive'
           && summary?.projectionValues?.subagentTiming?.lastTurnCompleted === true
         const activity = entry.activity === 'running'
@@ -451,15 +452,31 @@ function CatalogDropdown({
   const projections = useSessions(state => state.projectionsBySession)
   const summaries = useSessions(state => state.byId)
   const statuses = useSessionStatus(value => value)
-  const catalogs = useMemo<Catalogs>(() => Object.fromEntries(Object.entries(projections).map(([id, snapshot]) => [id, {
-    state: snapshot.state === 'idle'
-      ? snapshot.values.subagentCatalog === undefined ? 'loading' : 'ready'
-      : snapshot.state,
-    error: snapshot.error,
-    entries: (snapshot.values.subagentCatalog ?? []).map(entry => ({
-      ...entry, activity: (statuses.get(entry.id)?.running ?? summaries[entry.id]?.running) === true ? 'running' as const : 'inactive' as const,
-    })),
-  }])), [projections, summaries, statuses])
+  const catalogs = useMemo<Catalogs>(() => {
+    const result: Record<SessionId, SubagentCatalogSnapshot> = Object.fromEntries(Object.entries(projections).map(([id, snapshot]) => [id, {
+      state: snapshot.state === 'idle'
+        ? snapshot.values.subagentCatalog === undefined ? 'loading' : 'ready'
+        : snapshot.state,
+      error: snapshot.error,
+      entries: (snapshot.values.subagentCatalog ?? []).map(entry => ({
+        ...entry, activity: (statuses.get(entry.id)?.running ?? summaries[entry.id]?.running) === true ? 'running' as const : 'inactive' as const,
+      })),
+    }]))
+    const known = new Map(Object.entries(result).map(([id, catalog]) => [id, new Set(catalog.entries.map(entry => entry.id))]))
+    for (const summary of Object.values(summaries)) {
+      if (summary.origin !== 'subagent' || summary.parentId === undefined) continue
+      result[summary.id] ??= { state: 'ready', error: null, entries: [] }
+      const catalog = result[summary.parentId] ??= { state: 'ready', error: null, entries: [] }
+      if (known.get(summary.parentId)?.has(summary.id)) continue
+      const identity = summary.projectionValues?.subagent
+      catalog.entries.push({
+        id: summary.id, mode: identity?.mode ?? 'unresolved',
+        ...(identity?.label === undefined ? {} : { label: identity.label }),
+        activity: (statuses.get(summary.id)?.running ?? summary.running) ? 'running' : 'inactive',
+      })
+    }
+    return result
+  }, [projections, summaries, statuses])
   const catalog = catalogs[rootSessionId]
   const [open, setOpen] = useState(false)
   const [menuPosition, setMenuPosition] = useState<CSSProperties>()
@@ -473,7 +490,7 @@ function CatalogDropdown({
     ? undefined
     : catalog?.entries.find(entry => entry.id === currentSessionId)
   const switcherDisplayTitle = currentEntry !== undefined
-    ? currentEntry.label ?? currentEntry.id
+    ? currentEntry.label ?? (currentEntry.mode === 'unresolved' ? displayTitle : currentEntry.id)
     : displayTitle
   const directChildren = catalog?.entries ?? []
   const directCount = directChildren.length
diff --git a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
index 158e8cb77b..1271d13f2c 100644
--- a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
@@ -4,7 +4,7 @@ import css from './SubagentReadOnlyComposer.module.css'
 
 /** Why a catalog-addressed conversation cannot accept human input. */
 export interface SubagentReadOnlyMatch {
-  reason: 'one-shot' | 'parent-unavailable'
+  reason: 'one-shot' | 'parent-unavailable' | 'unresolved'
 }
 
 /** Full chain props after the read-only subagent selector accepts the owner currency. */
@@ -24,7 +24,7 @@ export function SubagentReadOnlyComposer({
     <div className={css.frame} role="status">
       <strong>{t(oneShot ? 'readonly.oneShot.title' : 'readonly.title')}</strong>
       <span>
-        {t(oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
+        {t(matched.reason === 'unresolved' ? 'readonly.unresolved.body' : oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
       </span>
     </div>
   )
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 0055ea8c3f..ce92feca36 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -37,6 +37,7 @@ export const inject = ['sessions', 'uiWorkspace', 'slots', 'locale', 'sidebarRig
 function selectReadOnlySubagent(owner: ComposerChainProps): SubagentReadOnlyMatch | null {
   const subagent = owner.session?.subagent
   if (subagent === undefined || subagent === null) return null
+  if (subagent.address.mode === 'unresolved') return { reason: 'unresolved' }
   if (subagent.address.mode === 'one-shot') return { reason: 'one-shot' }
   // Until a Host summary establishes parent availability, keep the normal
   // disabled composer instead of claiming that the parent is offline.
@@ -67,8 +68,8 @@ export function apply(ctx: ClientContext): void {
         preferNewPane: true,
       })
     },
-    refresh(parentSessionId: SessionId) {
-      void sessions.refreshProjections(parentSessionId)
+    refresh() {
+      void sessions.refresh()
     },
   })
   ctx.slots.inject(
diff --git a/packages/client/ui-subagent/src/client/locales.ts b/packages/client/ui-subagent/src/client/locales.ts
index cc966d411c..2de85e949c 100644
--- a/packages/client/ui-subagent/src/client/locales.ts
+++ b/packages/client/ui-subagent/src/client/locales.ts
@@ -22,6 +22,7 @@ export const zh = {
   'loading.label': '正在加载子代理…',
   'load.error': '无法加载子代理',
   'retry': '重试',
+  'mode.unresolved': '尚未打开',
   'mode.oneShot': '一次性',
   'mode.continuable': '可继续',
   'activity.running': '正在运行',
@@ -40,6 +41,7 @@ export const zh = {
   'readonly.oneShot.title': '一次性子代理记录',
   'readonly.title': '此子代理暂时只读',
   'readonly.oneShot.body': '一次性任务不支持后续消息，可在这里查看完整执行记录。',
+  'readonly.unresolved.body': '打开会话后才能确认是否支持后续消息。',
   'readonly.body': '父会话当前不在线，重新打开父会话后即可继续发送消息。',
 } as const
 
@@ -62,6 +64,7 @@ export const en: Record<SubagentKey, string> = {
   'loading.label': 'Loading subagents…',
   'load.error': 'Unable to load subagents',
   'retry': 'Retry',
+  'mode.unresolved': 'Not opened',
   'mode.oneShot': 'one-shot',
   'mode.continuable': 'continuable',
   'activity.running': 'running',
@@ -80,6 +83,7 @@ export const en: Record<SubagentKey, string> = {
   'readonly.oneShot.title': 'One-shot subagent record',
   'readonly.title': 'This subagent is read-only for now',
   'readonly.oneShot.body': 'One-shot tasks do not accept follow-ups; review the full execution record here.',
+  'readonly.unresolved.body': 'Open this conversation to check whether it supports follow-up messages.',
   'readonly.body': 'The parent session is offline; reopen it to continue sending messages.',
 }
 
diff --git a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
index a4fe489714..f83b9bb07f 100644
--- a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
+++ b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
@@ -73,7 +73,7 @@ export function parseSubagentChatAddress(value: string): SubagentAddress | undef
   if (parts.length !== 2 || parts[0] !== 'session') return undefined
   const parentSessionId = url.searchParams.get('parent')
   const mode = url.searchParams.get('mode')
-  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable')) {
+  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable' && mode !== 'unresolved')) {
     return undefined
   }
   try {
@@ -106,7 +106,7 @@ function subagentChatResourceProvider(sessions: ISessions): ResourceProvider<'su
       const address = parseSubagentChatAddress(resourceAddress)
       if (address === undefined) throw new Error(`ui-subagent: invalid chat resource address "${resourceAddress}"`)
       if (isAbortRequested(signal)) return
-      await sessions.refreshProjections(address.parentSessionId)
+      await sessions.refresh()
       if (isAbortRequested(signal)) return
       const reference = sessions.retain(address, { source: 'sidebarChat', signal })
       try {
diff --git a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
index 49b2ac6016..ab7dc11320 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
@@ -2,7 +2,7 @@
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { Context } from '@deepseek-ai/cordis'
 import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import type {
   SessionListState, SessionSnapshot, SessionSummary,
 } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -51,8 +51,8 @@ function sessionsWith(sessions: SessionSummary[]) {
     subagentAddress: (childSessionId: SessionId) => childSessionId === address.childSessionId
       ? address
       : undefined,
-    refreshProjections: (parentSessionId: SessionId) => {
-      actionCalls.push({ method: 'refreshProjections', args: [parentSessionId] })
+    refresh: () => {
+      actionCalls.push({ method: 'refresh', args: [] })
       return Promise.resolve()
     },
   }
@@ -74,6 +74,10 @@ async function fullBench(sessions: SessionSummary[]) {
   const ctx = new Context()
   const face = sessionsWith(sessions)
   ctx.provide('sessions', face)
+  const registerResources = vi.fn(() => () => {})
+  const registerTab = vi.fn(() => () => {})
+  ctx.provide('resources', { register: registerResources })
+  ctx.provide('sidebarRightTabs', { register: registerTab })
   ctx.provide('uiWorkspace', {
     openSession: (address: SubagentAddress) => {
       face.actionCalls.push({ method: 'openSession', args: [address] })
@@ -89,7 +93,7 @@ async function fullBench(sessions: SessionSummary[]) {
   await provideSlotFaces(ctx)
   await ctx.plugin({ inject: localeInject, apply: applyLocale }).await()
   await ctx.plugin({ inject: [...inject], apply }).await()
-  return { face, ctx }
+  return { face, ctx, registerResources, registerTab }
 }
 
 const FAMILY: SessionSummary[] = [
@@ -108,7 +112,9 @@ describe('apply', () => {
   })
 
   it('registers catalog actions and selects read-only subagent composers from session facts', async () => {
-    const { ctx, face } = await fullBench(FAMILY)
+    const { ctx, face, registerResources, registerTab } = await fullBench(FAMILY)
+    expect(registerResources).toHaveBeenCalledOnce()
+    expect(registerTab).toHaveBeenCalledOnce()
     const catalogEntry = ctx.slots.entries('conversation.session.header.lineage')
       .find(entry => entry.component === SubagentHeaderLineage)!
     const actions = (catalogEntry.inject as unknown as (id: SessionId) => SubagentCatalogInjected)(sid('parent'))
@@ -129,7 +135,7 @@ describe('apply', () => {
           { kind: 'subagentchat', preferNewPane: true },
         ],
       },
-      { method: 'refreshProjections', args: [sid('parent')] },
+      { method: 'refresh', args: [] },
     ])
 
     const composerEntry = ctx.slots.entries('conversation.composer')
@@ -146,6 +152,8 @@ describe('apply', () => {
       pendingInteraction: undefined,
     })
     expect(select(owner(undefined))).toBeNull()
+    expect(select(owner({ address: { ...address, mode: 'unresolved' }, parentAvailable: true })))
+      .toEqual({ reason: 'unresolved' })
     expect(select(owner(null))).toBeNull()
     expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true })))
       .toEqual({ reason: 'one-shot' })
diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
index 626026fe54..a7dc9f63a5 100644
--- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
@@ -182,7 +182,7 @@ describe('SubagentHeaderLineage', () => {
     expect(inactiveTrigger.querySelector('[data-state="ongoing"]')).toBeNull()
   })
 
-  it('does not count Sessions outside projected membership', () => {
+  it('adds header-discovered children without counting ordinary forks or their descendants', () => {
     const fork = 'fork' as SessionId
     const forkChild = 'fork-child' as SessionId
     render(<SubagentHeaderLineage {...props(catalog({
@@ -198,7 +198,7 @@ describe('SubagentHeaderLineage', () => {
       [forkChild]: { ...summary(forkChild, 1), parentId: fork, origin: 'subagent', running: true },
     })} />)
 
-    const trigger = screen.getByRole('button', { name: '1 个子代理' })
+    const trigger = screen.getByRole('button', { name: '2 个子代理' })
     expect(trigger.querySelector('[data-state="ongoing"]')).toBeNull()
   })
 
@@ -571,7 +571,30 @@ describe('SubagentHeaderLineage', () => {
     })
   })
 
-  it('shows one generic state while a child catalog loads', () => {
+  it('shows a loading branch until its child headers arrive', () => {
+    const input = props(catalog(), { [CHILD]: catalog({ entries: [], state: 'loading' }) })
+    render(<SubagentHeaderLineage {...input} />)
+    hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
+    fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
+    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
+  })
+
+  it('uses an already opened child identity without loading the parent catalog', () => {
+    const input = props(undefined, {}, {
+      [CHILD]: {
+        ...summary(CHILD, 1), parentId: PARENT, origin: 'subagent',
+        projectionValues: { subagent: { mode: 'one-shot', label: 'restored', seq: 0 } },
+      },
+    })
+    render(<SubagentHeaderLineage {...input} />)
+    hoverCatalog(screen.getByRole('button', { name: /1 个子代理/ }))
+    fireEvent.click(screen.getByRole('treeitem', { name: /restored/ }))
+    expect(input.openChild).toHaveBeenCalledWith({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'one-shot',
+    })
+  })
+
+  it('shows header-discovered descendants before their identity projections load', () => {
     const secondGrandchild = 'grandchild-2' as SessionId
     const summaries = {
       [CHILD]: { ...summary(CHILD, 1), running: true },
@@ -589,15 +612,18 @@ describe('SubagentHeaderLineage', () => {
     fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
 
     expect(deferred.refresh).toHaveBeenCalledWith(CHILD)
-    expect(screen.getByRole('group').getAttribute('aria-busy')).toBe('true')
-    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
-    expect(screen.queryByRole('treeitem', { name: '正在加载子代理' })).toBeNull()
+    expect(screen.getByRole('group').getAttribute('aria-busy')).toBeNull()
+    expect(screen.getAllByRole('treeitem', { name: /尚未打开/ })).toHaveLength(2)
+    fireEvent.click(screen.getByRole('treeitem', { name: /grandchild-2/ }))
+    expect(deferred.openChild).toHaveBeenCalledWith({ parentSessionId: CHILD, childSessionId: secondGrandchild, mode: 'unresolved' })
 
     const loading = props(catalog(), {
       [CHILD]: catalog({ entries: [], state: 'loading' }),
     }, summaries)
     view.rerender(<SubagentHeaderLineage {...loading} />)
-    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
+    hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
+    fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
+    expect(screen.getAllByRole('treeitem', { name: /尚未打开/ })).toHaveLength(2)
 
     const ready = props(catalog(), {
       [CHILD]: catalog({
@@ -680,7 +706,7 @@ describe('SubagentHeaderLineage', () => {
     expect(failed.refresh).toHaveBeenCalledWith(PARENT)
   })
 
-  it('does not expose summary-only descendants as catalog rows', () => {
+  it('keeps header-discovered children available without parent catalog facts', () => {
     const second = 'child-2' as SessionId
     const summaries = {
       [CHILD]: {
@@ -692,11 +718,11 @@ describe('SubagentHeaderLineage', () => {
     }
     const absent = props(undefined, {}, summaries)
     const view = render(<SubagentHeaderLineage {...absent} />)
-    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.getByRole('button', { name: /子代理/ })).toBeTruthy()
 
     const staleEmpty = props(catalog({ entries: [] }), {}, summaries)
     view.rerender(<SubagentHeaderLineage {...staleEmpty} />)
-    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.getByRole('button', { name: /子代理/ })).toBeTruthy()
   })
 
   it('hides a bare loading catalog and keeps the error fallback without focusable rows', async () => {
@@ -889,6 +915,21 @@ describe('SubagentHeaderLineage', () => {
     expect(input.refresh).not.toHaveBeenCalled()
   })
 
+  it('shows a loading switcher before the restored child header arrives', () => {
+    const input = {
+      ...props(undefined, {}, {}, {
+        parentSessionId: PARENT, childSessionId: CHILD, mode: 'unresolved',
+      }),
+      lineageSessionId: CHILD,
+      displayTitle: 'restored child',
+    }
+    render(<SubagentHeaderLineage {...input} />)
+    hoverCatalog(screen.getByRole('button', { name: '切换子代理：restored child' }))
+    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
+    expect(input.refresh).toHaveBeenCalledWith(PARENT)
+    expect(input.openChild).not.toHaveBeenCalled()
+  })
+
   it('keeps a nested title switcher scoped to its direct-parent catalog', () => {
     const input = {
       ...props(catalog(), {
@@ -921,6 +962,11 @@ describe('SubagentHeaderLineage', () => {
 })
 
 describe('SubagentReadOnlyComposer', () => {
+  it('keeps an unresolved child read-only', () => {
+    render(<SubagentReadOnlyComposer matched={{ reason: 'unresolved' }} t={t} />)
+    expect(screen.getByRole('status').textContent).toContain(zh['readonly.unresolved.body'])
+  })
+
   it('explains the exact missing-parent recovery path', () => {
     render(<SubagentReadOnlyComposer matched={{ reason: 'parent-unavailable' }} t={t} />)
     expect(screen.getByRole('status').textContent).toContain('父会话当前不在线')
diff --git a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
index 143a0cb595..4233188518 100644
--- a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
@@ -38,6 +38,8 @@ describe('Sidebar chat address', () => {
     expect(parseSubagentChatAddress(resource)).toEqual(ADDRESS)
     expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'one-shot' })))
       .toEqual({ ...ADDRESS, mode: 'one-shot' })
+    expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'unresolved' })))
+      .toEqual({ ...ADDRESS, mode: 'unresolved' })
   })
 
   it.each([
@@ -64,7 +66,7 @@ describe('Sidebar chat registration', () => {
       [Symbol.dispose]: release,
     } as unknown as SessionReference
     const retain = vi.fn(() => reference)
-    const refreshProjections = vi.fn(() => Promise.resolve())
+    const refresh = vi.fn(() => Promise.resolve())
     const list = {
       getSnapshot: () => ({
         ids: [],
@@ -84,7 +86,7 @@ describe('Sidebar chat registration', () => {
     let definition: SidebarRightTabDefinition | undefined
     const registrations: { options: Record<string, unknown>; component: unknown }[] = []
     const ctx = {
-      sessions: { retain, refreshProjections, list } as unknown as ISessions,
+      sessions: { retain, refresh, list } as unknown as ISessions,
       resources: { register: (value: ResourceProvider<'subagentchat'>) => { provider = value; return () => {} } },
       sidebarRightTabs: { register: (value: SidebarRightTabDefinition) => { definition = value; return () => {} } },
       slots: {
@@ -114,7 +116,7 @@ describe('Sidebar chat registration', () => {
     const controller = new AbortController()
     const stream = provider!.open(subagentChatAddress(ADDRESS), { signal: controller.signal })[Symbol.asyncIterator]()
     expect(await stream.next()).toEqual({ done: false, value: { ok: true, value: { address: ADDRESS, reference } } })
-    expect(refreshProjections).toHaveBeenCalledWith(PARENT)
+    expect(refresh).toHaveBeenCalledWith()
     expect(retain).toHaveBeenCalledWith(ADDRESS, { source: 'sidebarChat', signal: controller.signal })
     const completion = stream.next()
     await Promise.resolve()
@@ -130,7 +132,7 @@ describe('Sidebar chat registration', () => {
     expect(release).toHaveBeenCalledTimes(2)
 
     let finishRefresh: (() => void) | undefined
-    refreshProjections.mockImplementationOnce(() => new Promise<void>((resolve) => { finishRefresh = resolve }))
+    refresh.mockImplementationOnce(() => new Promise<void>((resolve) => { finishRefresh = resolve }))
     const abortedDuringRefresh = new AbortController()
     const pending = provider!.open(
       subagentChatAddress(ADDRESS), { signal: abortedDuringRefresh.signal },
diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml
index fdcdf0ae9c..0ae989a458 100644
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-workspace/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-workspace/README.md
-README.md: dc9ecee1df515f8e9b4183b6d97c29301c848652
-README.zh.md: 065f77ac442943b5683f0d492b56ab7d6668ba99
+README.md: 1f0b518644b80ea87cc701c8c656c27e36a317fc
+README.zh.md: ad49fd683e04ed47aa7db0e8004cfb61b3e2a89e
diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md
index dc9ecee1df..1f0b518644 100644
--- a/packages/client/ui-workspace/README.md
+++ b/packages/client/ui-workspace/README.md
@@ -65,7 +65,7 @@ The value is intentionally best effort for cold Sessions. An identity-matching u
 
 -----
 
-`ctx.uiWorkspace.openSession(target)` synchronously replaces the owned `mainView` reference and returns the main area to Conversation without waiting for `reference.ready`, so history loading renders inside the selected Session view. The target may be a known Session id or a durable direct-parent subagent address; an explicit address does not require a preloaded parent catalog. `openWorkspace(id, beforeOpen?)` and `forkSession(id)` open their result only if no later navigation has superseded the request; New Session uses `openWorkspace`. The optional synchronous preparation callback runs after the target is retained and only for a current Workspace request, so superseded requests do not move composer drafts. Navigation or owner disposal suppresses the late UI commit, not the underlying Session creation. Startup restoration retains its main reference without changing the selected panel or cancelling a later navigation. Archiving the main Session releases its reference and clears the main selection. Selection failure leaves a global panel visible. Session rows read `usePanelInfo` to suppress their selected appearance while a global panel is active; search and directory-picker focus alone do not leave that panel.
+`ctx.uiWorkspace.openSession(target)` synchronously replaces the owned `mainView` reference and returns the main area to Conversation without waiting for `reference.ready`, so history loading renders inside the selected Session view. The target may be a known Session id or a durable direct-parent subagent address; an explicit address does not require a preloaded parent catalog. `openWorkspace(id, beforeOpen?)` and `forkSession(id)` open their result only if no later navigation has superseded the request; New Session uses `openWorkspace`. The optional synchronous preparation callback runs after the target is retained and only for a current Workspace request, so superseded requests do not move composer drafts. Navigation or owner disposal suppresses the late UI commit, not the underlying Session creation. Startup restoration retains its main reference without changing the selected panel or cancelling a later navigation. Restoring a subagent address opens only the selected child, without requesting its parent projections. Archiving the main Session releases its reference and clears the main selection. Selection failure leaves a global panel visible. Session rows read `usePanelInfo` to suppress their selected appearance while a global panel is active; search and directory-picker focus alone do not leave that panel.
 
 New Session tries to acquire the first eligible blank in catalog order; startup restoration tries the saved blank. If that writer is held, navigation creates a new Session without trying other blanks. Other acquisition failures abort the request and are currently reported only to the console. Released blanks retain their slash-command state when reused. Later navigation cancels a pending startup selection.
 
diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md
index 065f77ac44..ad49fd683e 100644
--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -65,7 +65,7 @@ Session 行渲染运行时的实时 `pendingInteraction` 分类：审批显示**
 
 -----
 
-`ctx.uiWorkspace.openSession(target)` 会同步替换其拥有的 `mainView` reference，并让主区域返回 Conversation，而不等待 `reference.ready`，因此历史加载会显示在已经选中的 Session 视图内。目标可以是已知 Session id，也可以是持久的直接父子 subagent 地址；显式地址不要求预先加载 parent catalog。`openWorkspace(id, beforeOpen?)` 和 `forkSession(id)` 仅在请求未被后续导航替代时打开结果；新会话使用 `openWorkspace`。可选的同步准备回调在目标被 retain 后执行，并且仅对仍有效的 Workspace 请求执行，因此过期请求不会搬移 composer 草稿。后续导航或 owner 释放会阻止晚到的 UI 提交，但不取消底层 Session 创建。启动恢复会 retain 主 reference，不改变已选面板，也不取消后续导航。归档主 Session 会释放其 reference 并清除主选择。选择失败时保留当前全局面板。Session 行读取 `usePanelInfo`，在全局面板活跃时不显示 Session 选中样式；仅把焦点移到搜索框或目录选择器不会离开该面板。
+`ctx.uiWorkspace.openSession(target)` 会同步替换其拥有的 `mainView` reference，并让主区域返回 Conversation，而不等待 `reference.ready`，因此历史加载会显示在已经选中的 Session 视图内。目标可以是已知 Session id，也可以是持久的直接父子 subagent 地址；显式地址不要求预先加载 parent catalog。`openWorkspace(id, beforeOpen?)` 和 `forkSession(id)` 仅在请求未被后续导航替代时打开结果；新会话使用 `openWorkspace`。可选的同步准备回调在目标被 retain 后执行，并且仅对仍有效的 Workspace 请求执行，因此过期请求不会搬移 composer 草稿。后续导航或 owner 释放会阻止晚到的 UI 提交，但不取消底层 Session 创建。启动恢复会 retain 主 reference，不改变已选面板，也不取消后续导航。归档主 Session 会释放其 reference 并清除主选择。选择失败时保留当前全局面板。Session 行读取 `usePanelInfo`，在全局面板活跃时不显示 Session 选中样式；仅把焦点移到搜索框或目录选择器不会离开该面板。 恢复子代理地址时只打开选中的子会话，不请求其父投影。
 
 新建会话尝试获取列表中第一个符合条件的空白会话；启动恢复尝试已保存的空白会话。若该写锁被占用，导航直接新建 Session，不再尝试其他空白会话。其他获取错误会中止请求，目前只报告到控制台。已释放的空白会话被复用时保留 slash 命令状态。后续导航会取消尚未完成的启动选择。
 
diff --git a/packages/client/ui-workspace/src/client/navigation.ts b/packages/client/ui-workspace/src/client/navigation.ts
index 82796c0b9c..5f80fa2e43 100644
--- a/packages/client/ui-workspace/src/client/navigation.ts
+++ b/packages/client/ui-workspace/src/client/navigation.ts
@@ -274,7 +274,6 @@ class UiWorkspaceService extends Service implements UiWorkspace {
   private async restoreSelection(workspaces: WorkspaceSnapshot, sessions: SessionListState): Promise<void> {
     const saved = this.selection.getSnapshot()
     if (saved.subagentAddress !== undefined) {
-      void this.sessions.refreshProjections(saved.subagentAddress.parentSessionId)
       this.replaceMain(saved.subagentAddress, this.lifetime.signal, 'preserve')
       return
     }
diff --git a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
index 625784bb5b..d71291443e 100644
--- a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
+++ b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
@@ -715,7 +715,6 @@ describe('UiWorkspaceService', () => {
 
     expect(b.sessions.retain).toHaveBeenCalledExactlyOnceWith(address, { source: 'mainView' })
     expect(b.sessions.refreshProjections.mock.calls).toEqual([
-      [address.parentSessionId],
       [address.childSessionId],
     ])
   })
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index de5ef44f14..453d087865 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -2603,10 +2603,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         throws: ['{SubagentError} `UNAUTHORIZED` when a resident target belongs to a different parent or the supplied parent identity is stale.'],
       },
       {
-        signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>',
-        description: 'Read the parent\'s durable direct-child catalog without loading or resuming an Agent. The service owns and releases the live-preferred Session observation.',
+        signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>',
+        description: 'Read the parent\'s catalog and discover missing direct children from Session headers. The service owns and releases the live-preferred Session observation.',
         parameters: [{ name: 'parentSessionId', description: 'parent whose direct children are requested.' }, { name: 'signal', description: 'cancellation forwarded to the Session query.' }],
-        returns: 'catalog children in parent event order.',
+        returns: 'catalog children in event order, then unresolved children whose bodies remain unread.',
         throws: ['{@link SubagentError} when query or catalog projection is unavailable.', 'SessionQueryError when the parent cannot be read or the query is cancelled.'],
       },
       {
@@ -5737,7 +5737,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     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};',
+    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\' | \'unresolved\';\n};',
   },
   {
     name: 'SessionAssistantStreamAttempt',
@@ -6435,6 +6435,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubagentDescriptorData',
     declaration: 'export type SubagentDescriptorData = OneShotSubagentDescriptorData | ContinuableSubagentDescriptorData;',
   },
+  {
+    name: 'SubagentDiscoveryEntry',
+    declaration: 'export type SubagentDiscoveryEntry = SubagentCatalogEntry | {\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly mode: \'unresolved\';\n};',
+  },
   {
     name: 'SubagentInterruptAuthority',
     declaration: 'export type SubagentInterruptAuthority = {\n    readonly kind: \'user\';\n    readonly parentSessionId: SessionId;\n} | {\n    readonly kind: \'ancestor\';\n    readonly agent: Agent;\n};',
@@ -6485,7 +6489,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubagentRuntime',
-    declaration: 'export class SubagentRuntime extends TypertRemoteService {\n    static Config: z<Config>;\n    constructor(ctx: Context, config: Config);\n    resolveMaxDepth(configured?: number | \'provider-managed\'): number | undefined;\n    async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;\n    async sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;\n    interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;\n    async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>;\n    async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;\n    listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>;\n    listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;\n    @Remote(\'prompt\')\n    async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>;\n    @Remote(\'interruptByParent\')\n    interruptByParent(childSessionId: SessionId, parentSessionId: SessionId, mode: \'continuable\'): SubagentInterruptReceipt;\n    registerProvider(provider: SubagentProvider): () => void;\n    getProvider(name: string): SubagentProvider | undefined;\n    list(): string[];\n    async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>;\n}',
+    declaration: 'export class SubagentRuntime extends TypertRemoteService {\n    static Config: z<Config>;\n    constructor(ctx: Context, config: Config);\n    resolveMaxDepth(configured?: number | \'provider-managed\'): number | undefined;\n    async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;\n    async sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;\n    interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;\n    async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>;\n    async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;\n    listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>;\n    listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;\n    @Remote(\'prompt\')\n    async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>;\n    @Remote(\'interruptByParent\')\n    interruptByParent(childSessionId: SessionId, parentSessionId: SessionId, mode: \'continuable\'): SubagentInterruptReceipt;\n    registerProvider(provider: SubagentProvider): () => void;\n    getProvider(name: string): SubagentProvider | undefined;\n    list(): string[];\n    async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>;\n}',
   },
   {
     name: 'SubagentSendMessageOptions',
diff --git a/packages/session/session-format-catalog/README.i18n.yaml b/packages/session/session-format-catalog/README.i18n.yaml
index 31246e1ed0..d792370356 100644
--- a/packages/session/session-format-catalog/README.i18n.yaml
+++ b/packages/session/session-format-catalog/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-format-catalog/README.md
-README.md: bb86bcaffee2c2e17afffd4ce7fbd917bf1c30ee
-README.zh.md: 156361ae330967169ae82e204ddeff26c50b05bd
+README.md: 82c1635ced88651ddcb250bd2d6b03e021faa176
+README.zh.md: 07758cd5ab14010a16889073f4b5b046e9dd0ba7
diff --git a/packages/session/session-format-catalog/README.md b/packages/session/session-format-catalog/README.md
index bb86bcaffe..82c1635ced 100644
--- a/packages/session/session-format-catalog/README.md
+++ b/packages/session/session-format-catalog/README.md
@@ -33,7 +33,7 @@ Import this library from persistence and test-support readers that need the comp
 
 ```text
 const descriptor = sessionFormatCatalog.readHeader(physicalHeader)
-const catalog = createSessionFormatCatalogWithChildren(childFacts)
+const catalog = sessionFormatCatalog
 const restore = catalog.createRestore(physicalHeader, { recovery: 'recoverable', validation: 'transformed' })
 for (const row of physicalRows) restore.decodeRow(row)
 const current = restore.finish()
@@ -47,7 +47,7 @@ Production historical reads select `{ recovery: 'recoverable', validation: 'tran
 
 The catalog contains all supported historical readers directly. A profile cannot add, remove, or reorder an edge by mounting a feature plugin. Its peer dependency on `dsh-session` supplies the installed current event vocabulary and current restoration rules, while historical edge validators remain frozen. The browser-safe `./message-projections` export assembles current plugin-owned interpreters for detached constructors and surface folds; it does not mount recovery listeners.
 
-`createSessionFormatCatalogWithChildren(childFacts)` binds explicit child evidence to V3→V4 during assembly; see the [catalog-completion specification](../session-format-v3-to-v4/README.md). `historicalSessionFormatCatalog` restores V0–V3 using the fixed released-V3 event vocabulary to collect child prerequisites without recursively completing their catalogs. An ignorable V3 extension remains opaque even when the installed writer knows its name. Isolated transcript replay explicitly supplies an empty array; persistence must collect the complete available direct-child set. Keep the supplied evidence unchanged for the catalog’s lifetime. Each restore owns independent stage state. The static `sessionFormatCatalog` supports header and native current-format reads; historical body reads require the child-bound catalog.
+`sessionFormatCatalog` restores historical bodies independently of other Sessions. `createSessionFormatCatalogWithChildren(childFacts)` optionally supplements parent catalogs for offline fixture preparation and Preview packing; see the [catalog-completion specification](../session-format-v3-to-v4/README.md). `historicalSessionFormatCatalog` restores V0–V3 using the fixed released-V3 vocabulary for that evidence collection. An ignorable V3 extension stays opaque even when the current writer knows its name. Supplied evidence remains unchanged for the catalog’s lifetime, and every restore owns independent stage state.
 
 -----
 
diff --git a/packages/session/session-format-catalog/README.zh.md b/packages/session/session-format-catalog/README.zh.md
index 156361ae33..07758cd5ab 100644
--- a/packages/session/session-format-catalog/README.zh.md
+++ b/packages/session/session-format-catalog/README.zh.md
@@ -33,7 +33,7 @@ kind: "package-library"
 
 ```text
 const descriptor = sessionFormatCatalog.readHeader(physicalHeader)
-const catalog = createSessionFormatCatalogWithChildren(childFacts)
+const catalog = sessionFormatCatalog
 const restore = catalog.createRestore(physicalHeader, { recovery: 'recoverable', validation: 'transformed' })
 for (const row of physicalRows) restore.decodeRow(row)
 const current = restore.finish()
@@ -47,7 +47,7 @@ Production 历史读取使用 `{ recovery: 'recoverable', validation: 'transform
 
 该目录直接包含所有受支持的历史读取器。Profile 无法通过挂载功能插件来添加、移除或重新排列迁移边。它通过对 `dsh-session` 的对等依赖（peer dependency）获得已安装的当前事件词表与当前还原规则，而历史迁移边校验器保持冻结。浏览器安全的 `./message-projections` 导出为独立构造函数和 surface 折叠装配当前插件拥有的处理器，不挂载恢复监听器。
 
-`createSessionFormatCatalogWithChildren(childFacts)` 在组装时将显式的子 Session 证据绑定到 V3→V4，见[目录补齐规范](../session-format-v3-to-v4/README.zh.md)。`historicalSessionFormatCatalog` 使用固定的已发布 V3 事件词汇恢复 V0–V3，收集子日志前置事实而不递归补齐其目录。即使已安装写入方认识事件名，可忽略 V3 扩展仍保持不透明。独立转录回放显式提供空数组；持久化必须收集完整的可用直属子 Session 集合。在 catalog 的生命周期内保持传入证据不变。每次恢复各自拥有独立的 stage 状态。静态 `sessionFormatCatalog` 支持 header 和原生当前格式读取；历史正文读取必须使用已绑定子 Session 的 catalog。
+`sessionFormatCatalog` 独立于其他会话恢复历史正文。`createSessionFormatCatalogWithChildren(childFacts)` 可在离线夹具准备和 Preview 打包时补充父会话 catalog；参见 [catalog 补全规范](../session-format-v3-to-v4/README.zh.md)。`historicalSessionFormatCatalog` 使用固定的已发布 V3 词汇恢复 V0–V3，为此收集证据。即使当前 writer 已认识某个名称，可忽略的 V3 扩展仍保持不透明。传入证据在 catalog 生命周期内保持不变，每次恢复拥有独立的阶段状态。
 
 -----
 
diff --git a/packages/session/session-format-catalog/src/children.ts b/packages/session/session-format-catalog/src/children.ts
index 580e46d2ae..bee7de134f 100644
--- a/packages/session/session-format-catalog/src/children.ts
+++ b/packages/session/session-format-catalog/src/children.ts
@@ -7,7 +7,7 @@ import { sessionFormatCatalogOptions } from './generated.ts'
 
 /**
  * Assemble a catalog whose V3→V4 edge knows one parent's historical children.
- * @param children - complete child evidence retained unchanged for the catalog's lifetime; an empty array declares no children.
+ * @param children - complete child evidence retained unchanged for the catalog's lifetime; an empty array requests no backfill.
  * @returns a catalog with independent restore state per artifact and unchanged current-format readers.
  */
 export function createSessionFormatCatalogWithChildren(children: readonly SessionFormatJsonValue[]): SessionFormatCatalog {
diff --git a/packages/session/session-format-catalog/tests/children.spec.ts b/packages/session/session-format-catalog/tests/children.spec.ts
index 4b2d465e93..7e600a8095 100644
--- a/packages/session/session-format-catalog/tests/children.spec.ts
+++ b/packages/session/session-format-catalog/tests/children.spec.ts
@@ -7,9 +7,9 @@ const child = (id: string) => ({ childId: id, childCreatedAt: 2, descriptorCount
   descriptor: { version: 3, provider: 'spawn', mode: 'one-shot' } })
 
 describe('parent-specific catalog assembly', () => {
-  it('requires explicit children for historical bodies while retaining header and native V4 reads', () => {
+  it('restores historical bodies independently while retaining optional catalog completion', () => {
     expect(sessionFormatCatalog.readHeader(header).status).toBe('migration-required')
-    expect(() => sessionFormatCatalog.createRestore(header, policy)).toThrow('explicit historical child facts')
+    expect(sessionFormatCatalog.createRestore(header, policy).finish().events).toEqual([])
     expect(createSessionFormatCatalogWithChildren([]).createRestore(header, policy).finish().events).toEqual([])
     expect(sessionFormatCatalog.createRestore({ ...header, version: 4 }, policy).finish().events).toEqual([])
   })
diff --git a/packages/session/session-format-v3-to-v4/README.i18n.yaml b/packages/session/session-format-v3-to-v4/README.i18n.yaml
index 892da2ad10..8b6ee01f8d 100644
--- a/packages/session/session-format-v3-to-v4/README.i18n.yaml
+++ b/packages/session/session-format-v3-to-v4/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-format-v3-to-v4/README.md
-README.md: 2c2d3b4342d68cec5e9a9f94f969a380bbbf15f2
-README.zh.md: a92ae34a73f134253880fec3f931815e067bc344
+README.md: cb23641b3cc3b9a60ee1dc3429ab529809df6c93
+README.zh.md: 67148ff09cc43eed9aed523f5ae7670c3348403b
diff --git a/packages/session/session-format-v3-to-v4/README.md b/packages/session/session-format-v3-to-v4/README.md
index 2c2d3b4342..cb23641b3c 100644
--- a/packages/session/session-format-v3-to-v4/README.md
+++ b/packages/session/session-format-v3-to-v4/README.md
@@ -48,7 +48,7 @@ Header-only migration validates and advances metadata without reading the body o
 const targetHeader = sessionFormatV3ToV4.migrateHeader(sourceHeader)
 ```
 
-Historical body restoration requires explicit child evidence. `sessionFormatV3ToV4.createStage()` refuses without that binding; an empty array explicitly declares no children. Persistence must collect the complete available direct-child set, while isolated transcript replay can supply its deliberately empty set. Keep the evidence unchanged for the catalog's lifetime.
+Historical body restoration through `sessionFormatV3ToV4` requires only the requested Session. It preserves existing catalog entries without reading children. Offline fixture preparation may explicitly supply child evidence through `createSessionFormatCatalogWithChildren()` to append missing catalog facts; an empty array requests no backfill. Keep supplied evidence unchanged for the catalog’s lifetime.
 
 ```text
 const catalog = createSessionFormatCatalogWithChildren(childFacts)
@@ -154,7 +154,7 @@ Catalog version 0 requires string `childId`, nonnegative safe-integer `childCrea
 
 The stage considers parent catalog records only after the final inherited cut. Every inherited marker discards earlier catalog candidates without interpreting their payloads. Missing entries append after all source events, sorted by creation time then child id, with dense new sequences. Their time is the final source event's time, or header creation time for an empty log. They neither enter the model surface nor change the inherited count.
 
-Storage supplies the complete recognizable child set within its root and rechecks membership and physical revisions during preparation, memo reuse, and publication. Incomplete descriptor evidence only prevents that child’s backfill. Unreadable headers that prevent classifying membership, unsupported selected generations, or source drift refuse the operation. The package itself reads no files; [persistence](../session-persistence-jsonl/README.md) owns encoding, locks, cancellation, and publication.
+The supplemental evidence rules apply only when a caller requests catalog completion. Runtime JSONL migration does not collect child evidence; it migrates each Session on its own open. The package reads no files; [persistence](../session-persistence-jsonl/README.md) owns encoding, locks, cancellation, source revision checks, and publication.
 
 <a id="sequence-references"></a>
 ### Sequence references and inheritance
diff --git a/packages/session/session-format-v3-to-v4/README.zh.md b/packages/session/session-format-v3-to-v4/README.zh.md
index a92ae34a73..67148ff09c 100644
--- a/packages/session/session-format-v3-to-v4/README.zh.md
+++ b/packages/session/session-format-v3-to-v4/README.zh.md
@@ -48,7 +48,7 @@ kind: "package-library"
 const targetHeader = sessionFormatV3ToV4.migrateHeader(sourceHeader)
 ```
 
-历史正文恢复要求显式的子级证据。没有该绑定时，`sessionFormatV3ToV4.createStage()` 会拒绝；空数组明确声明没有子级。持久化层必须收集完整的可用直属子级集合，而隔离的 transcript 回放可以提供其刻意为空的集合。Catalog 存续期间，证据必须保持不变。
+通过 `sessionFormatV3ToV4` 恢复历史正文只需要所请求的会话。它保留已有 catalog 条目，不读取子会话。离线夹具准备可以通过 `createSessionFormatCatalogWithChildren()` 显式传入子会话证据，追加缺失的 catalog 事实；空数组表示不回填。传入证据在 catalog 生命周期内必须保持不变。
 
 ```text
 const catalog = createSessionFormatCatalogWithChildren(childFacts)
@@ -154,7 +154,7 @@ Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt
 
 Stage 只把最终继承截点之后的父目录记录作为候选。每个 inherited marker 都会丢弃更早的目录候选，不解释其载荷。缺失项追加在所有源事件之后，按创建时间、child id 排序，并使用连续的新序号。时间取最后一个源事件的 time；空日志则取 header 创建时间。这些记录既不进入模型表面，也不改变继承计数。
 
-存储层提供其根目录内完整的可识别子级集合，并在准备、复用 memo 与发布时复查成员及物理版本。不完整的 descriptor 证据只阻止补填对应子 Session 的目录项。无法据此判断成员关系的不可读 header、不受支持的所选代际或源变化都会拒绝操作。本包不读取文件；[持久化层](../session-persistence-jsonl/README.zh.md)负责编码、锁、取消与发布。
+补充证据规则仅适用于调用者请求 catalog 补全时。运行时 JSONL 迁移不收集子会话证据，每个会话在自身 open 时独立迁移。本包不读取文件；[持久化](../session-persistence-jsonl/README.zh.md) 负责编码、锁、取消、源文件版本检查和发布。
 
 <a id="sequence-references"></a>
 ### 序号引用与继承
diff --git a/packages/session/session-format-v3-to-v4/src/migration.ts b/packages/session/session-format-v3-to-v4/src/migration.ts
index 3b1c1de60a..d3359baed8 100644
--- a/packages/session/session-format-v3-to-v4/src/migration.ts
+++ b/packages/session/session-format-v3-to-v4/src/migration.ts
@@ -10,7 +10,7 @@ import { namespaceV3OpaqueEvent, RELEASED_V3_EVENT_TYPES } from './extension-ide
 import { assertReleasedV4Header, validateDeliveryAccepted } from './validation.ts'
 import { catalogFact, childCatalogSource, childCatalogFact, childCatalogSubject } from './facts.ts'
 
-/** Header-only migration declaration; body restoration requires explicit child evidence. */
+/** Convert one Session independently, preserving its existing catalog entries. */
 export const sessionFormatV3ToV4 = defineSessionFormatMigration({
   name: '@deepseek-ai/dsh-session-format-v3-to-v4',
   fromVersion: 3,
@@ -19,15 +19,13 @@ export const sessionFormatV3ToV4 = defineSessionFormatMigration({
     assertReleasedV3Header(header)
     return { ...header, version: 4 }
   },
-  createStage() {
-    throw new SessionFormatUnsupportedMigrationError('V3 catalog migration requires explicit historical child facts, including an empty array for a parent without children')
-  },
+  createStage: input => new ReleasedV3ToV4Stage(input, []),
   validateTargetHeader: assertReleasedV4Header,
 })
 
 /**
  * Bind one parent's historical child evidence to its V3→V4 migration.
- * @param children - complete child evidence retained unchanged for the lifetime of this declaration; an empty array declares no children.
+ * @param children - complete child evidence retained unchanged for the lifetime of this declaration; an empty array requests no backfill.
  * @returns an adjacent migration that creates independent stages with the supplied evidence.
  */
 export function createSessionFormatV3ToV4(children: readonly SessionFormatJsonValue[]): SessionFormatMigration {
diff --git a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
index 7b1ad7e3c0..08069d659a 100644
--- a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
@@ -71,9 +71,9 @@ describe('V3 parent catalog completion', () => {
     expect(() => migrate([opaque], [])).toThrow('complete version 0')
   })
 
-  it('requires explicit corpus facts and refuses conflicting identities', () => {
+  it('accepts independent migration and refuses conflicting supplemental identities', () => {
     expect(() => sessionFormatV3ToV4.createStage({ sourceHeader: header, targetHeader: { ...header, version: 4 },
-      sourceKind: 'decoded', sourceInheritedEventCount: 0 })).toThrow('explicit historical child facts')
+      sourceKind: 'decoded', sourceInheritedEventCount: 0 })).not.toThrow()
     expect(() => migrate([], [{ ...child, mode: 'unknown' }])).toThrow('complete version 0')
     expect(() => migrate([{ type: 'subagent/catalog', seq: 0, time: 2, data: child }], [{ ...child, childCreatedAt: 3 }])).toThrow('conflicts')
   })
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 1589a1d5c7..6d1541c724 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: 96c333d9f845943ff44c8d5d539c40d07b9dc0f6
-README.zh.md: 71126dd909c92aabdee5c07d23505f708dc5e038
+README.md: 2581be5ccdee5e5539e383ac0598ea1a285b6376
+README.zh.md: 7eddf277cc82e078283961f3309c979214e0cb9f
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index 96c333d9f8..2581be5ccd 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -79,11 +79,11 @@ The current-generation scanner applies the current codec owner’s structural ad
 
 ### Reading the logs
 
-`open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Current revisions identify that file; historical revisions also fingerprint the selected files across the persistence root, so child changes invalidate cached logical events. Fingerprinting reads filesystem metadata only; unrelated changes conservatively invalidate historical revisions. One `list()` call shares a corpus fingerprint across its historical entries. 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'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Revisions identify only the selected Session file, independently of other Sessions. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
-Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It scans headers, decodes only direct children one at a time, and retains compact descriptor evidence plus source revisions. It rechecks membership and revisions before returning preparation, reusing it, and publishing. Source drift invalidates preparation: read open retries preparation once automatically, while write open refuses publication. Diagnostics name the changed, added, removed, or unreadable child path. An unsupported selected generation or unreadable header anywhere else in the scan refuses migration because it cannot establish complete membership. Ordinary listing still skips those files. Missing, unsupported, or multiple child descriptors prevent only that child’s catalog backfill; existing parent entries and child logs remain available. Invalid fields in exactly one supported own descriptor still report an unsupported format; malformed child events, JSON records, and compressed data report corruption at the child path. Filesystem errors and cancellation retain their original errors. Current V4 opens bypass this scan and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
+Historical preparation reads and migrates only the requested Session. It preserves existing parent catalog events without collecting child descriptors or validating other Session headers and bodies. Child corruption, unsupported generations, and child publication cannot invalidate a parent preparation. The [subagent service](../../subagent/subagent/README.md) discovers missing child entries from headers; opening a selected child performs its own migration and reports its own errors. Current reads validate catalog fields, uniqueness, and delivery ownership before exposing events.
 
-Historical `stat` and `list` revisions require metadata work proportional to the root’s Session count. Fresh body preparation scans all selected headers and decodes direct-child bodies; memo reuse still scans membership and checks revisions. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat that work. Current V4 body reads and revisions avoid the historical corpus scan. See the [measured costs and diagnostic command](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements).
+Historical revisions and memo reuse require no corpus fingerprint or child-body scan. Listing still enumerates Session headers; targeted generation lookup may enumerate directories to locate an uncached id. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat only the requested Session’s decoding. The [diagnostic measurements](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements) retain the earlier eager-scan baseline.
 
 -----
 
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 71126dd909..7eddf277cc 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -79,11 +79,11 @@ kind: "package-reference"
 
 ### 读取日志
 
-`open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；每个嵌套对象和数组都会冻结，句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的修订号。当前格式修订号标识该文件；历史格式修订号还包含持久化根目录中所选文件的指纹，因此子日志变化会使缓存的逻辑事件失效。指纹只读取文件系统元数据；无关变化也会保守地使历史修订号失效。一次 `list()` 为其历史条目共用一个全库指纹。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
+`open(id, 'read'|'write')` 选择最高规范代次。当前输入走普通快速路径。对于历史输入，读 open 解码并迁移源文件一次，校验当前逻辑结果，不发布后继文件。写 open 复用按源版本缓存的准备结果，或重新准备，再分块写同目录临时文件，经 Worker Thread 校验、复核源文件版本后，以不覆盖方式发布当前后继文件。源文件字节保持不变。准备后的源文件变化会拒绝该次写 open，已返回的逻辑历史不变；后续写 open 重新准备。缓存前深度冻结的事件图标记为 `shared-frozen`，读取和切片（包括空切片）保持这一状态；只有尚未物化的待写日志报告 `detached`。`stat(id)` 和 `list()` 只选择并转换最高代次的头部，不读事件行或启动迁移；快照携带所选文件的 `sizeBytes` 和尽力获取的版本标识。版本标识只对应所选会话文件，与其他会话无关。配置 `compression: 'none'` 时，外部工具可以直接读取逐行文本；压缩默认格式必须经后端读取。
 
-历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：扫描 header，仅逐个解码直属子 Session，保留紧凑的 descriptor 证据及来源修订。在准备返回、复用和发布前重新检查成员集合与修订。来源变化会使准备缓存失效：只读打开自动重新准备一次，写打开则拒绝发布。诊断指出发生变化、新增、删除或无法读取的子日志路径。扫描中其他任何被选中的不支持代际或不可读 header 都会拒绝迁移，因为无法确认成员集合完整。普通列举仍跳过这些文件。子 descriptor 缺失、版本不受支持或存在多个时，只跳过该子 Session 的目录补填；已有父目录项和子日志仍可读取。恰好一个受支持的自身 descriptor 字段无效时，仍会报告格式不支持；子事件、JSON 记录或压缩数据畸形会在子日志路径报告损坏。文件系统错误与取消保留原始错误。当前 V4 打开跳过此扫描，并在暴露事件之前检查目录字段、唯一性及当前投递归属。
+历史准备只读取并迁移所请求的会话。它保留已有父会话 catalog 事件，不收集子会话 descriptor，也不校验其他会话的头部或正文。子会话损坏、不支持的代次和子会话后继发布不会使父会话准备结果失效。[子代理服务](../../subagent/subagent/README.zh.md) 从头部发现缺失的子会话条目；打开选中的子会话时才独立迁移并报告其错误。当前读取在暴露事件前校验 catalog 字段、唯一性和交付归属。
 
-历史格式的 `stat` 与 `list` 修订号需要与根目录 Session 数量成正比的元数据工作。首次正文准备扫描所有所选 header 并解码直属子正文；复用准备缓存仍扫描成员集合并检查修订。只读访问从不发布升级，因此冷进程与被淘汰的准备缓存会重复这些工作。当前 V4 正文读取和修订号避开历史全库扫描。见[实测成本与诊断命令](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements)。
+历史版本标识和缓存复用不需要全库指纹或子会话正文扫描。列表仍枚举会话头部；定位尚未缓存的 id 时，定向代次查找可能枚举目录。只读访问不发布升级，因此冷进程和缓存淘汰后只重复所请求会话的解码。[诊断测量](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements) 保留此前主动扫描的基线。
 
 -----
 
diff --git a/packages/session/session-persistence-jsonl/src/catalog-migration.ts b/packages/session/session-persistence-jsonl/src/catalog-migration.ts
deleted file mode 100644
index 77e3d8b43e..0000000000
--- a/packages/session/session-persistence-jsonl/src/catalog-migration.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-/** Collect historical discovery facts without recursively preparing related current generations. */
-
-import { stat } from 'node:fs/promises'
-import { basename } from 'node:path'
-import { historicalSessionFormatCatalog, sessionFormatCatalog } from '@deepseek-ai/dsh-session-format-catalog'
-import { historicalChildCatalogSource } from '@deepseek-ai/dsh-session-format-v3-to-v4'
-import { SessionFormatUnsupportedError, SessionPersistenceCorruptionError } from '@deepseek-ai/dsh-session-persistence'
-import { SessionFormatError, SessionFormatUnsupportedMigrationError } from '@deepseek-ai/dsh-session-format'
-import type { SessionFormatJsonObject } from '@deepseek-ai/dsh-session-format'
-import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
-import { parseGenerationLogFilename } from './format.ts'
-import type { JsonlCompression } from './format.ts'
-import { JsonlGenerationSourceChangedError, readDecodedJsonlSource } from './generation.ts'
-import type { JsonlPhysicalIdentity } from './generation.ts'
-
-/** Per-parent supplemental facts and the source checks required before serving or publishing them. */
-interface PreparedCatalogFacts {
-  readonly facts: readonly SessionFormatJsonObject[]
-  /** @returns resolves while every decoded child still has the captured physical revision. */
-  validate(): Promise<void>
-}
-
-/**
- * Collect each related child's own descriptor through existing historical codecs.
- * @param parentId - parent whose incoming migration consumes these facts.
- * @param sources - header-indexed direct children in the selected source corpus.
- * @param compression - configured source encoding.
- * @param signal - cancellation forwarded through each source read.
- * @returns compact facts; complete child event arrays are released after extraction.
- */
-export async function prepareCatalogFacts(
-  parentId: SessionId,
-  sources: readonly { readonly header: SessionHeader; readonly path: string }[],
-  compression: JsonlCompression,
-  signal: AbortSignal,
-): Promise<PreparedCatalogFacts> {
-  const facts: SessionFormatJsonObject[] = []
-  const witnesses: { path: string; identity: JsonlPhysicalIdentity }[] = []
-  for (const source of sources) {
-    signal.throwIfAborted()
-    const version = parseGenerationLogFilename(basename(source.path), compression)
-    if (version === undefined) throw new SessionFormatUnsupportedMigrationError(`unrecognized historical child generation ${source.path}`)
-    let restored: Awaited<ReturnType<typeof readDecodedJsonlSource>>
-    try {
-      restored = await readDecodedJsonlSource(source.path, version, compression, {
-        createRestore: header => (version <= 3 ? historicalSessionFormatCatalog : sessionFormatCatalog).createRestore(header, {
-          recovery: 'recoverable', validation: 'current',
-        }),
-      }, signal)
-    } catch (error: unknown) {
-      if (error instanceof SessionFormatUnsupportedMigrationError) {
-        throw new SessionFormatUnsupportedError(
-          `child Session ${source.header.id}: ${error.message} (raw log: ${source.path})`,
-          { kind: 'jsonl', path: source.path },
-        )
-      }
-      if (error instanceof SessionFormatError) {
-        throw new SessionPersistenceCorruptionError(`child Session ${source.header.id}: ${error.message} (raw log: ${source.path})`, { cause: error })
-      }
-      throw error
-    }
-    const header = restored.artifact.header
-    if (header.id !== source.header.id || header.createdAt !== source.header.createdAt
-      || header.parentSession !== parentId || header.origin !== 'subagent'
-      || ['cwd', 'isSeeded', 'delegationDepth', 'agentPreset'].some(key => header[key] !== source.header[key as keyof SessionHeader])) {
-      throw new JsonlGenerationSourceChangedError(source.path)
-    }
-    facts.push({ ...historicalChildCatalogSource(restored.artifact), sourcePath: source.path })
-    witnesses.push({ path: source.path, identity: restored.identity })
-  }
-  return {
-    facts,
-    async validate() {
-      for (const witness of witnesses) {
-        const current = await stat(witness.path, { bigint: true })
-        if (current.dev !== witness.identity.dev || current.ino !== witness.identity.ino
-          || current.size !== witness.identity.size || current.mtimeNs !== witness.identity.mtimeNs
-          || current.ctimeNs !== witness.identity.ctimeNs) throw new JsonlGenerationSourceChangedError(witness.path)
-      }
-    },
-  }
-}
diff --git a/packages/session/session-persistence-jsonl/src/generation.ts b/packages/session/session-persistence-jsonl/src/generation.ts
index ff01e9a038..001c2dbc40 100644
--- a/packages/session/session-persistence-jsonl/src/generation.ts
+++ b/packages/session/session-persistence-jsonl/src/generation.ts
@@ -28,7 +28,6 @@ import { constants, createZstdCompress } from 'node:zlib'
 import { Session } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { BlockAssembler, expandAssistantStream } from '@deepseek-ai/dsh-llm'
-import { SessionFormatError } from '@deepseek-ai/dsh-session-format'
 import type {
   SessionFormatArtifact,
   SessionFormatJsonValue,
@@ -69,8 +68,6 @@ export interface JsonlGenerationFormatAdapter {
 
 /** Inputs for preparing one historical generation and publishing its current successor later. */
 export interface PrepareJsonlMigrationOptions {
-  /** Revalidate related source facts before preparation returns and immediately before publication. */
-  readonly validateRelatedSources?: () => Promise<void>
   /** Immutable generation selected by the backend resolver. */
   readonly sourcePath: string
   /** Version selected from the source filename and independently checked against its header. */
@@ -903,7 +900,6 @@ async function publishPreparedMigration(
       throw new Error('staged session generation changed during verification')
     }
     await internals.barrier('before-source-check', 1)
-    await options.validateRelatedSources?.()
     const beforePublish = await internals.fs.stat(sourcePath)
     if (identity(beforePublish) !== identity(sourceIdentity)) {
       throw new JsonlGenerationSourceChangedError(sourcePath)
@@ -978,7 +974,6 @@ async function prepareMigration(
   if (artifact.header.version !== format.currentVersion) {
     throw new Error(`format migration returned v${artifact.header.version}, expected v${format.currentVersion}`)
   }
-  await options.validateRelatedSources?.()
   const sourceIdentity = source.identity
   let publication: Promise<JsonlPhysicalIdentity> | undefined
   return {
@@ -1029,31 +1024,3 @@ export function createJsonlGenerationRuntime(
 }
 
 const defaultGenerationRuntime = createJsonlGenerationRuntime()
-
-/**
- * Read one stable source through the shared streaming parser without publishing a generation.
- * @param path - selected source generation path.
- * @param version - physical source version identified by its filename.
- * @param compression - source encoding.
- * @param format - codec/restore factory, independent of current-generation publication.
- * @param signal - cancellation observed during source reads and decode yields.
- * @returns decoded artifact and physical source identity for later revalidation.
- * @throws SessionFormatError for physical decoding failures; storage, cancellation, and unsupported migration errors retain their category.
- */
-export async function readDecodedJsonlSource(
-  path: string,
-  version: number,
-  compression: JsonlCompression,
-  format: Pick<JsonlGenerationFormatAdapter, 'createRestore'>,
-  signal?: AbortSignal,
-): Promise<{ artifact: SessionFormatArtifact; identity: JsonlPhysicalIdentity }> {
-  const source = await readStableJsonlFile(path, signal)
-  let artifact: SessionFormatArtifact
-  try {
-    artifact = await decodeStreamingMigration(source.bytes, compression, version, format, undefined, signal)
-  } catch (error: unknown) {
-    if (signal?.aborted || error instanceof SessionFormatError) throw error
-    throw new SessionFormatError(String(error), { cause: error })
-  }
-  return { artifact, identity: source.identity }
-}
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 6e7e7b5628..3efafa4b6d 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -9,7 +9,6 @@
 import { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import {
-  createSessionFormatCatalogWithChildren,
   SessionFormatUnsupportedMigrationError,
   sessionFormatCatalog,
 } from '@deepseek-ai/dsh-session-format-catalog'
@@ -18,7 +17,7 @@ import { open, mkdir, readdir, realpath, link, rm, stat, truncate } from 'node:f
 import { dirname, join, resolve } from 'node:path'
 import { performance } from 'node:perf_hooks'
 import { scheduler } from 'node:timers/promises'
-import { createHash, randomBytes } from 'node:crypto'
+import { randomBytes } from 'node:crypto'
 import {
   SessionPersistence, SessionPersistenceRevision, SessionFormatUnsupportedError,
   SessionPersistenceCorruptionError,
@@ -45,7 +44,6 @@ import {
 } from './zstd.ts'
 import { ensureDurableDirectoryWin32, publishNewFileWin32 } from './win32.ts'
 import { verifyCurrentGenerationInWorker } from './migration-verifier.ts'
-import { prepareCatalogFacts } from './catalog-migration.ts'
 import {
   JsonlGenerationSourceChangedError,
   JsonlGenerationUnsupportedMigrationError,
@@ -124,7 +122,6 @@ interface CurrentStoredLog extends StoredLogBase {
 /** A migrated historical generation retained until an explicit write open publishes it. */
 interface PreparedStoredLog extends StoredLogBase {
   readonly status: 'prepared'
-  readonly validateRelatedSources: () => Promise<void>
   readonly publication: {
     readonly source: ResolvedJsonlGeneration
     readonly value: PreparedJsonlMigration
@@ -255,7 +252,7 @@ class JsonlSessionPersistence extends SessionPersistence {
   private compression: JsonlCompression
   private rootEncodingCheck: Promise<void> | undefined
   private readonly tracker = new JsonlBackendTracker(this.name)
-  private readonly generationFormat: Omit<JsonlGenerationFormatAdapter, 'createRestore'>
+  private readonly generationFormat: JsonlGenerationFormatAdapter
   /**
    * Bounded LRU of parsed, validated stored logs keyed by session id and
    * guarded by the stat-derived revision, so an immediate cold-read handoff
@@ -281,6 +278,9 @@ class JsonlSessionPersistence extends SessionPersistence {
     this.compression = config.compression ?? DEFAULT_COMPRESSION
     this.generationFormat = {
       currentVersion: sessionFormatCatalog.currentVersion,
+      createRestore: header => sessionFormatCatalog.createRestore(header, {
+        recovery: 'recoverable', validation: 'transformed',
+      }),
       encodeHeader: (header, inheritedEventCount) =>
         sessionFormatCatalog.encodeCurrentHeader(header, inheritedEventCount),
       encodeEvent: event => sessionFormatCatalog.encodeCurrentEvent(event),
@@ -348,13 +348,7 @@ class JsonlSessionPersistence extends SessionPersistence {
       if (pending !== undefined) {
         return this.tracker.adopt(new JsonlSessionHandle(this, id, pending.header, 'read', { cursor: 0, materialized: false, inheritedEventCount: pending.inheritedEventCount }))
       }
-      let stored: StoredLog
-      try {
-        stored = await this.requireStoredLog(id, options?.signal)
-      } catch (error: unknown) {
-        if (!(error instanceof JsonlGenerationSourceChangedError)) throw error
-        stored = await this.requireStoredLog(id, options?.signal)
-      }
+      const stored = await this.requireStoredLog(id, options?.signal)
       let state: StorageHandleState
       if (stored.status === 'prepared') {
         state = {
@@ -454,9 +448,7 @@ class JsonlSessionPersistence extends SessionPersistence {
       options?.signal?.throwIfAborted()
       return {
         header,
-        revision: selected.sourceVersion < SESSION_FORMAT_VERSION
-          ? SessionPersistenceRevision(`${fileRevision(identity)}:${await this.historicalCorpusRevision(options?.signal)}`)
-          : fileRevision(identity),
+        revision: fileRevision(identity),
         sizeBytes: Number(identity.size),
       }
     } catch (error: unknown) {
@@ -481,8 +473,6 @@ class JsonlSessionPersistence extends SessionPersistence {
     // predate the scan), so create-to-list visibility never has a hole.
     const pending = [...this.tracker.pendingEntries()]
     const artifacts = await this.listArtifacts(signal)
-    const corpusRevision = artifacts.some(artifact => artifact.sourceVersion < SESSION_FORMAT_VERSION)
-      ? await this.historicalCorpusRevision(signal) : undefined
     for (const artifact of artifacts) {
       signal?.throwIfAborted()
       try {
@@ -491,9 +481,7 @@ class JsonlSessionPersistence extends SessionPersistence {
         listed.add(artifact.header.id)
         snapshots.push({
           header: artifact.header,
-          revision: artifact.sourceVersion < SESSION_FORMAT_VERSION
-            ? SessionPersistenceRevision(`${fileRevision(identity)}:${corpusRevision}`)
-            : fileRevision(identity),
+          revision: fileRevision(identity),
           sizeBytes: Number(identity.size),
         })
       } catch (error: unknown) {
@@ -586,12 +574,6 @@ class JsonlSessionPersistence extends SessionPersistence {
     signal.throwIfAborted()
     const memoized = this.coldLogMemo.get(id)
     if (memoized?.status === 'prepared' && memoized.revision === sourceRevision) {
-      try {
-        await memoized.validateRelatedSources()
-      } catch (error: unknown) {
-        this.coldLogMemo.delete(id)
-        throw this.generationFailure(id, selected, error)
-      }
       this.coldLogMemo.delete(id)
       this.coldLogMemo.set(id, memoized)
       return memoized
@@ -627,33 +609,13 @@ class JsonlSessionPersistence extends SessionPersistence {
     signal: AbortSignal,
   ): Promise<PreparedStoredLog> {
     let prepared: Awaited<ReturnType<typeof prepareJsonlMigration>>
-    let validateRelatedSources: () => Promise<void>
     try {
-      const children = async () => (await this.listArtifacts(signal, selected.sourcePath))
-        .filter(source => source.header.origin === 'subagent' && source.header.parentSession === id)
-      const sources = await children()
-      const related = await prepareCatalogFacts(id, sources, this.compression, signal)
-      const membership = sources.map(source => source.path).sort()
-      validateRelatedSources = async () => {
-        const current = (await children()).map(source => source.path).sort()
-        const before = new Set(membership)
-        const after = new Set(current)
-        const changed = current.find(path => !before.has(path)) ?? membership.find(path => !after.has(path))
-        if (changed !== undefined) throw new JsonlGenerationSourceChangedError(changed)
-        await related.validate()
-      }
       prepared = await prepareJsonlMigration({
         sourcePath: selected.sourcePath,
         sourceVersion: selected.sourceVersion,
         currentPath: selected.currentPath,
         compression: this.compression,
-        format: {
-          ...this.generationFormat,
-          createRestore: header => createSessionFormatCatalogWithChildren(related.facts).createRestore(header, {
-            recovery: 'recoverable', validation: 'transformed',
-          }),
-        },
-        validateRelatedSources,
+        format: this.generationFormat,
         verifyCurrentFile: verifyCurrentGenerationInWorker,
         validateHistoricalHeader: headerValue => this.validateSourceIdentity(
           selected,
@@ -672,7 +634,6 @@ class JsonlSessionPersistence extends SessionPersistence {
     validateStoredEvents(meta, events, { kind: 'jsonl', path: selected.sourcePath })
     const stored: PreparedStoredLog = {
       status: 'prepared',
-      validateRelatedSources,
       meta,
       ...freezeStoredEvents(events),
       tornTruncateTo: undefined,
@@ -1031,28 +992,8 @@ class JsonlSessionPersistence extends SessionPersistence {
     return sources
   }
 
-  /** Historical logical events depend on the corpus, including members with unreadable headers. */
-  private async historicalCorpusRevision(signal?: AbortSignal): Promise<string> {
-    const paths = (await this.listGenerations(signal)).map(source => source.sourcePath).sort()
-    const hash = createHash('sha256')
-    for (const path of paths) {
-      signal?.throwIfAborted()
-      let revision: string
-      try {
-        revision = fileRevision(await stat(path, { bigint: true }))
-      } catch (error: unknown) {
-        if (!isENOENT(error)) throw error
-        revision = 'missing'
-      }
-      hash.update(JSON.stringify([path, revision]))
-    }
-    signal?.throwIfAborted()
-    return hash.digest('hex')
-  }
-
   private async listArtifacts(
     signal?: AbortSignal,
-    migrationSource?: string,
   ): Promise<Array<{ header: SessionHeader; path: string; sourceVersion: number }>> {
     signal?.throwIfAborted()
     await this.ensureRootEncoding()
@@ -1061,26 +1002,14 @@ class JsonlSessionPersistence extends SessionPersistence {
     const ids = new Set<SessionId>()
     for (const selected of await this.listGenerations(signal)) {
       signal?.throwIfAborted()
-      if (migrationSource !== undefined && selected.sourceVersion > SESSION_FORMAT_VERSION) {
-        throw new SessionFormatUnsupportedError(
-          `catalog migration cannot inspect Session format v${selected.sourceVersion}; upgrade the harness (raw log: ${selected.sourcePath})`,
-          { kind: 'jsonl', path: selected.sourcePath },
-        )
-      }
       let header: SessionHeader | undefined
       try {
         header = await this.readGenerationHeader(selected, undefined, signal)
       } catch (error: unknown) {
-        if (error instanceof SessionFormatUnsupportedError && migrationSource === undefined) continue
+        if (error instanceof SessionFormatUnsupportedError) continue
         throw error
       }
       if (header === undefined) {
-        if (migrationSource !== undefined && selected.sourcePath !== migrationSource) {
-          throw new SessionFormatUnsupportedError(
-            `cannot establish complete catalog membership from an unreadable Session header (raw log: ${selected.sourcePath})`,
-            { kind: 'jsonl', path: selected.sourcePath },
-          )
-        }
         continue
       }
       if (ids.has(header.id)) {
diff --git a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
index af86cdbfe6..ec9acb1b74 100644
--- a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
@@ -1,5 +1,5 @@
 import { Context } from '@deepseek-ai/cordis'
-import { SessionId, type SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import { SessionFormatUnsupportedError, SessionPersistenceCorruptionError } from '@deepseek-ai/dsh-session-persistence'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { afterEach, describe, expect, it } from 'vitest'
@@ -7,7 +7,6 @@ import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { generationLogPath } from '../src/format.ts'
-import { prepareCatalogFacts } from '../src/catalog-migration.ts'
 import { compressZstdFrame } from '../src/zstd.ts'
 
 const roots: string[] = []
@@ -57,30 +56,6 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     await expect(f.ctx.sessionPersistence.open(f.parent, access)).rejects.toThrow('wrong Session')
   })
 
-  it('does not publish incomplete membership after a child header becomes unreadable', async () => {
-    const f = await fixture()
-    const path = await f.write('child', [], true)
-    const broken = '{broken header\n'
-    await writeFile(path, compression === 'none' ? broken : await compressZstdFrame(broken))
-    await expect(f.read()).rejects.toThrow(path)
-    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(path)
-    expect((await readdir(dirname(generationLogPath(f.root, undefined, f.parent, 3, compression)))).filter(name => name !== 'session.lock'))
-      .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
-  })
-
-  it('invalidates lightweight revisions on child membership and contents while retaining stable tokens', async () => {
-    const f = await fixture()
-    const revision = async () => (await f.ctx.sessionPersistence.stat(f.parent))!.revision
-    const first = await revision()
-    expect(await revision()).toBe(first)
-    await f.write('child', [f.descriptor], true)
-    const added = await revision()
-    expect(added).not.toBe(first)
-    expect((await f.ctx.sessionPersistence.list()).find(row => row.header.id === f.parent)?.revision).toBe(added)
-    await f.write('child', [f.descriptor, { type: 'feedback/record', seq: 1, time: 3, data: {} }], true)
-    expect(await revision()).not.toBe(added)
-  })
-
   it('reports malformed native catalog data without migration terminology', async () => {
     const f = await fixture()
     await f.write(f.parent, [{ type: 'subagent/catalog', seq: 0, time: 1,
@@ -102,48 +77,6 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).toBe(first)
   })
 
-  it('invalidates historical revisions when selected children disappear or gain an opaque successor', async () => {
-    const f = await fixture()
-    const path = await f.write('child', [f.descriptor], true)
-    const first = (await f.ctx.sessionPersistence.stat(f.parent))!.revision
-    await rm(path)
-    const removed = (await f.ctx.sessionPersistence.stat(f.parent))!.revision
-    expect(removed).not.toBe(first)
-    await f.write('child', [], true, 5)
-    expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).not.toBe(removed)
-    expect((await f.ctx.sessionPersistence.list()).find(row => row.header.id === f.parent)?.revision).not.toBe(removed)
-  })
-
-  it('reports a corrupt child body at the child location', async () => {
-    const f = await fixture()
-    const catalog = { type: 'subagent/catalog', seq: 0, time: 1,
-      data: { version: 0, childId: 'grandchild', childCreatedAt: 3, mode: 'one-shot' } }
-    const path = await f.write('child', [catalog, { ...catalog, seq: 1 }], true, 4)
-    await expect(f.read()).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
-    await expect(f.read()).rejects.toThrow(path)
-  })
-
-  it.each(['read', 'write'] as const)('locates physical child JSON corruption during %s access', async (access) => {
-    const f = await fixture()
-    const childPath = await f.write('child', [], true)
-    const first = JSON.stringify({ ...f.header, id: 'child', origin: 'subagent', parentSession: f.parent, delegationDepth: 1 }) + '\n'
-    // A sealed turn makes the malformed row corruption rather than a recoverable tail.
-    const body = '{broken\n' + JSON.stringify({ type: 'turn/end', seq: 1, time: 2,
-      data: { turn: 1, reason: { kind: 'completed' } } }) + '\n'
-    await writeFile(childPath, compression === 'none' ? first + body
-      : Buffer.concat([await compressZstdFrame(first), await compressZstdFrame(body)]))
-    const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
-    const original = await Promise.all([readFile(parentPath), readFile(childPath)])
-    const error: unknown = await f.ctx.sessionPersistence.open(f.parent, access).catch((error: unknown) => error)
-    expect(error).toBeInstanceOf(SessionPersistenceCorruptionError)
-    expect((error as Error).message).toContain(childPath)
-    expect((error as Error).message).not.toContain(parentPath)
-    expect((error as Error).message).toContain('row 1 is not valid JSON')
-    expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
-    expect((await readdir(dirname(parentPath))).filter(name => name !== 'session.lock'))
-      .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
-  })
-
   it('preserves opaque inherited catalogs through read preparation and write publication', async () => {
     const f = await fixture()
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
@@ -165,15 +98,6 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect(await readFile(parentPath)).toEqual(original)
   })
 
-  it.skipIf(compression !== 'zstd')('locates invalid compressed child frames at the child path', async () => {
-    const f = await fixture()
-    const childPath = await f.write('child', [], true)
-    await writeFile(childPath, Buffer.concat([await readFile(childPath), Buffer.alloc(8)]))
-    const error: unknown = await f.read().catch((error: unknown) => error)
-    expect(error).toBeInstanceOf(SessionPersistenceCorruptionError)
-    expect((error as Error).message).toContain(childPath)
-  })
-
   it('keeps a complete parent catalog when a published child never writes a descriptor', async () => {
     const f = await fixture()
     const catalog = { type: 'subagent/catalog', seq: 0, time: 2,
@@ -188,18 +112,6 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
   })
 
-  it.each([1, 2, 3])('backfills a missing catalog from descriptor v%i', async (version) => {
-    const f = await fixture()
-    const data = version === 1 ? { version, provider: 'spawn', label: 'old child' }
-      : { ...f.descriptor.data, version }
-    await f.write('child', [{ ...f.descriptor, data }], true)
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: {
-      childId: 'child', childCreatedAt: 2, mode: 'continuable', label: 'old child',
-    } }])
-    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    await writer.close()
-  })
-
   it.each(['missing', 'unknown', 'multiple'] as const)('publishes the parent without invented %s child discovery information', async (kind) => {
     const f = await fixture()
     const events = kind === 'missing' ? [] : kind === 'unknown'
@@ -219,37 +131,6 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
       .toEqual(compression === 'none' ? ['session.v3.jsonl', 'session.v4.jsonl'] : ['session.v3.jsonl.zstd', 'session.v4.jsonl.zstd'])
   })
 
-  it.each([false, true])('refuses an opaque future generation before publishing membership (prepared=%s)', async (prepared) => {
-    const f = await fixture()
-    await f.write('child', [f.descriptor], true)
-    if (prepared) expect(await f.read()).toHaveLength(1)
-    await f.write('child', [], true, 5)
-    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-    expect((await readdir(dirname(generationLogPath(f.root, undefined, f.parent, 3, compression)))).filter(name => name !== 'session.lock'))
-      .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
-  })
-
-  it('requires a readable corpus even when an unknown header cannot identify its parent', async () => {
-    const f = await fixture()
-    await f.write('future-root', [], false, 5)
-    expect((await f.ctx.sessionPersistence.list()).map(row => row.header.id)).toEqual([f.parent])
-    await expect(f.read()).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-  })
-
-  it('preserves unsupported child decoding errors instead of reporting parent corruption', async () => {
-    const f = await fixture()
-    const path = await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
-    await expect(f.read()).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-    await expect(f.read()).rejects.toThrow(path)
-  })
-
-  it('locates incomplete historical descriptor fields at their child source', async () => {
-    const f = await fixture()
-    const path = await f.write('child', [{ ...f.descriptor, data: { version: 2, provider: 'spawn', mode: 'unknown' } }], true)
-    await expect(f.read()).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-    await expect(f.read()).rejects.toThrow(path)
-  })
-
   it.each(['read', 'write'] as const)('rejects duplicate own catalogs through a current %s open', async (access) => {
     const f = await fixture()
     const catalog = { type: 'subagent/catalog', seq: 0, time: 2,
@@ -258,123 +139,73 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     await expect(f.ctx.sessionPersistence.open(f.parent, access)).rejects.toThrow('duplicate catalog child')
   })
 
-  it('recollects a changed child within the same read open', async () => {
-    const f = await fixture()
-    await f.write('child', [f.descriptor], true)
-    expect(await f.read()).toHaveLength(1)
-    await f.write('child', [f.descriptor, { type: 'feedback/record', seq: 1, time: 3, data: { text: 'appended' } }], true)
-    expect(await f.read()).toHaveLength(1)
-    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    await writer.close()
-  })
-
-  it('detects children added after preparation instead of publishing incomplete membership', async () => {
-    const f = await fixture()
-    expect(await f.read()).toEqual([])
-    await f.write('child', [f.descriptor], true)
-    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(generationLogPath(f.root, undefined, SessionId('child'), 3, compression))
-    expect(await f.read()).toHaveLength(1)
-    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    await writer.close()
-  })
-
-  it('recollects newly available discovery fields before publishing a prepared parent', async () => {
+  it.each(['read', 'write'] as const)('isolates malformed child JSON until explicit %s access', async (access) => {
     const f = await fixture()
     const childPath = await f.write('child', [], true)
-    expect(await f.read()).toEqual([])
-    await f.write('child', [f.descriptor], true)
-    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(childPath)
-    const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
-    expect((await readdir(dirname(parentPath))).filter(name => name !== 'session.lock'))
+    const first = JSON.stringify({ ...f.header, id: 'child', origin: 'subagent', parentSession: f.parent, delegationDepth: 1 }) + '\n'
+    const body = '{broken\n' + JSON.stringify({ type: 'turn/end', seq: 1, time: 2,
+      data: { turn: 1, reason: { kind: 'completed' } } }) + '\n'
+    await writeFile(childPath, compression === 'none' ? first + body
+      : Buffer.concat([await compressZstdFrame(first), await compressZstdFrame(body)]))
+    const original = await readFile(childPath)
+    const parent = await f.ctx.sessionPersistence.open(f.parent, access)
+    try { expect((await parent.read()).events).toEqual([]) } finally { await parent.close() }
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), access)).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
+    expect(await readFile(childPath)).toEqual(original)
+    expect((await readdir(dirname(childPath))).filter(name => name !== 'session.lock'))
       .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', label: 'old child' } }])
+    expect(await f.read()).toEqual([])
+  })
+
+  it.each([true, false])('opens the parent independently of unsupported related=%s generations', async (related) => {
+    const f = await fixture()
+    await f.write('future', [], related, 5)
+    expect(await f.read()).toEqual([])
+    const parent = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await parent.close()
+    await expect(f.ctx.sessionPersistence.open(SessionId('future'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
+  })
+
+  it('keeps unreadable child headers outside parent migration', async () => {
+    const f = await fixture()
+    const path = await f.write('child', [], true)
+    await writeFile(path, compression === 'none' ? '{broken\n' : await compressZstdFrame('{broken\n'))
+    expect(await f.read()).toEqual([])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
     await writer.close()
   })
 
-  it('reads current children without recursive migration and preserves current parent fast reads', async () => {
+  it('keeps revisions and prepared parent history independent of child membership and contents', async () => {
     const f = await fixture()
-    await f.write('child', [f.descriptor], true, 4)
-    expect(await f.read()).toHaveLength(1)
-    await f.write(f.parent, [], false, 4)
-    await f.write('child', [], true, 4)
+    const first = (await f.ctx.sessionPersistence.stat(f.parent))!.revision
     expect(await f.read()).toEqual([])
-  })
-
-  it('refuses publication when a related child disappears', async () => {
-    const f = await fixture()
     const path = await f.write('child', [f.descriptor], true)
-    const header = { ...f.header, id: SessionId('child'), origin: 'subagent', parentSession: f.parent, createdAt: 2, delegationDepth: 1 } as SessionHeader
-    const prepare = () => prepareCatalogFacts(f.parent, [{ path, header }], compression, new AbortController().signal)
-    const prepared = await prepare()
+    expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).toBe(first)
+    await f.write('child', [{ ...f.descriptor, data: { ...f.descriptor.data, label: 'changed' } }], true)
+    expect((await f.ctx.sessionPersistence.list()).find(row => row.header.id === f.parent)?.revision).toBe(first)
     await rm(path)
-    await expect(prepared.validate()).rejects.toMatchObject({ code: 'ENOENT' })
-    await expect(prepare()).rejects.toMatchObject({ code: 'ENOENT' })
+    expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).toBe(first)
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    try { expect((await writer.read()).events).toEqual([]) } finally { await writer.close() }
   })
 
-  it('rejects changed header identities and invalid source selection', async () => {
+  it.each([0, 1, 2, 3])('migrates a V%i child only on its own write open and preserves predecessors', async (version) => {
     const f = await fixture()
-    const path = await f.write('child', [f.descriptor], true)
-    const header = { ...f.header, id: SessionId('wrong-child'), origin: 'subagent', parentSession: f.parent } as SessionHeader
-    const signal = new AbortController().signal
-    await expect(prepareCatalogFacts(f.parent, [{ path, header }], compression, signal)).rejects.toThrow('changed')
-    await expect(prepareCatalogFacts(f.parent, [{ path: path + '.foreign', header }], compression, signal)).rejects.toThrow('unrecognized historical child generation')
-    const controller = new AbortController()
-    controller.abort(new Error('cancelled child collection'))
-    await expect(prepareCatalogFacts(f.parent, [{ path, header }], compression, controller.signal)).rejects.toThrow('cancelled child collection')
-  })
-
-  it.each([0, 1, 2])('composes a V%i parent and child through all preceding edges', async (version) => {
-    const f = await fixture()
-    const initial = generationLogPath(f.root, undefined, f.parent, 3, compression)
-    await rm(initial)
+    await rm(generationLogPath(f.root, undefined, f.parent, 3, compression))
     const parentPath = await f.write(f.parent, [], false, version)
     const childPath = await f.write('child', [f.descriptor], true, version)
-    const before = await Promise.all([readFile(parentPath), readFile(childPath)])
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', seq: 0, data: { childId: 'child', mode: 'continuable', label: 'old child' } }])
+    const original = await Promise.all([readFile(parentPath), readFile(childPath)])
+    expect(await f.read()).toEqual([])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
     await writer.close()
-    expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(before)
-    expect((await readdir(dirname(parentPath))).filter(name => name !== 'session.lock')).toHaveLength(2)
-  })
-
-  it('lists historical headers, prepares read-only membership, and publishes an unchanged-prefix successor', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-catalog-migration-'))
-    roots.push(root)
-    const parent = SessionId('parent')
-    const child = SessionId('child')
-    const header = { type: 'session', version: 3, id: parent, createdAt: 1, isSeeded: false, delegationDepth: 0 }
-    const childHeader = { ...header, id: child, createdAt: 2, origin: 'subagent', parentSession: parent, delegationDepth: 1 }
-    const descriptor = { type: 'subagent/descriptor', seq: 0, time: 2, data: { version: 3, mode: 'one-shot', provider: 'spawn', label: 'old child' } }
-    const sourcePaths: string[] = []
-    for (const [meta, events] of [[header, []], [childHeader, [descriptor]]] as const) {
-      const path = generationLogPath(root, undefined, meta.id, 3, compression)
-      sourcePaths.push(path)
-      await mkdir(dirname(path), { recursive: true })
-      const first = Buffer.from(JSON.stringify(meta) + '\n')
-      const body = Buffer.from(events.map(event => JSON.stringify(event) + '\n').join(''))
-      await writeFile(path, compression === 'none' ? Buffer.concat([first, body])
-        : Buffer.concat([await compressZstdFrame(first), ...(body.length === 0 ? [] : [await compressZstdFrame(body)])]))
-    }
-    const original = await Promise.all(sourcePaths.map(path => readFile(path)))
-    const ctx = new Context()
-    contexts.push(ctx)
-    await ctx.plugin(JsonlSessionPersistence, { root, compression })
-    expect((await ctx.sessionPersistence.list()).map(row => row.header.id).sort()).toEqual([child, parent])
-    const reader = await ctx.sessionPersistence.open(parent, 'read')
-    let expected
-    try {
-      expect(reader.header.version).toBe(4)
-      expected = (await reader.read()).events
-      expect(expected).toEqual([{ type: 'subagent/catalog', seq: 0, time: 1, data: {
-        version: 0, childId: child, childCreatedAt: 2, mode: 'one-shot', label: 'old child',
-      } }])
-      expect(await readdir(dirname(sourcePaths[0]!))).toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
-    } finally { await reader.close() }
-    const writer = await ctx.sessionPersistence.open(parent, 'write')
-    try { expect((await writer.read()).events).toEqual(expected) } finally { await writer.close() }
-    expect(await Promise.all(sourcePaths.map(path => readFile(path)))).toEqual(original)
-    const reopened = await ctx.sessionPersistence.open(parent, 'read')
-    try { expect((await reopened.read()).events).toEqual(expected) } finally { await reopened.close() }
+    const childSuccessor = generationLogPath(f.root, undefined, SessionId('child'), 4, compression)
+    await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' })
+    const childReader = await f.ctx.sessionPersistence.open(SessionId('child'), 'read')
+    try { expect((await childReader.read()).events).toEqual([f.descriptor]) } finally { await childReader.close() }
+    await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' })
+    const childWriter = await f.ctx.sessionPersistence.open(SessionId('child'), 'write')
+    await childWriter.close()
+    expect((await readFile(childSuccessor)).length).toBeGreaterThan(0)
+    expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
   })
 })
diff --git a/packages/session/session-persistence-jsonl/tests/generation.spec.ts b/packages/session/session-persistence-jsonl/tests/generation.spec.ts
index 4d398dca4b..398066f704 100644
--- a/packages/session/session-persistence-jsonl/tests/generation.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/generation.spec.ts
@@ -23,7 +23,6 @@ import {
   JsonlGenerationTargetConflictError,
   JsonlGenerationUnsupportedMigrationError,
   prepareJsonlMigration,
-  readDecodedJsonlSource,
   verifyJsonlCurrentGeneration,
   type JsonlGenerationFormatAdapter,
   type PrepareJsonlMigrationOptions,
@@ -87,19 +86,6 @@ function header(version: number, id = 'generation-test'): Record<string, unknown
 const event0 = { type: 'turn/start', seq: 0, time: 2, data: { turn: 1 } }
 const event1 = { type: 'turn/end', seq: 1, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }
 
-it('preserves cancellation raised while creating a child source decoder', async () => {
-  const path = join(await tempRoot(), 'session.v3.jsonl')
-  await writeFile(path, line(header(3)))
-  const controller = new AbortController()
-  const reason = new Error('child decoding cancelled')
-  await expect(readDecodedJsonlSource(path, 3, 'none', {
-    createRestore() {
-      controller.abort(reason)
-      throw reason
-    },
-  }, controller.signal)).rejects.toBe(reason)
-})
-
 const assistantUsage = { inputTokens: 3, outputTokens: 2 }
 const assistantReplayState = { response: { id: 'response' } }
 
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index 114b7f364e..d2f3e3868a 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -1211,7 +1211,7 @@ describe('JsonlSessionPersistence: immutable format generations', () => {
       .rejects.toThrow(/released v0 physical header lacks required member "type"/)
   })
 
-  it('tracks a disappearing corpus member and propagates its storage faults in historical revisions', async () => {
+  it('keeps historical revisions independent of another Session storage faults', async () => {
     const parent = meta('corpus-revision-parent', '/work')
     const child = meta('corpus-revision-child', '/work')
     for (const header of [parent, child]) {
@@ -1224,10 +1224,10 @@ describe('JsonlSessionPersistence: immutable format generations', () => {
     statFailure.error = Object.assign(new Error('member disappeared'), { code: 'ENOENT' })
     const missing = await ctx.sessionPersistence.stat(parent.id)
     expect(missing).toBeDefined()
-    expect(missing?.revision).not.toBe(present?.revision)
+    expect(missing?.revision).toBe(present?.revision)
     expect((await ctx.sessionPersistence.stat(parent.id))?.revision).toBe(missing?.revision)
     statFailure.error = Object.assign(new Error('member denied'), { code: 'EACCES' })
-    await expect(ctx.sessionPersistence.stat(parent.id)).rejects.toBe(statFailure.error)
+    expect((await ctx.sessionPersistence.stat(parent.id))?.revision).toBe(present?.revision)
   })
 
   it('surfaces source-read storage faults and aborts unwrapped during migration', async () => {
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index f2d1e1d365..ba1f32a337 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 7d62e423189906c49d9479bd7a6dbd14b7303afd
-README.zh.md: af62ad97bc4821222d46ed73509c823851953e1d
+README.md: 8351ff4aac8c3585ab0230cf5dbd1c2a4613adc7
+README.zh.md: 90806e0728acf61178e3d9914ec4c7bf0fa1a83c
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 7d62e42318..8351ff4aac 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -60,7 +60,7 @@ One-shot children run once and settle with a single result, plus an optional str
 
 ### Messaging, interrupting, and discovering
 
-Every exact live Agent can use `sendMessage()` with a direct continuable child; a resident continuable child can also use it with its direct parent. A working target receives the Agent message through Steer at its nearest step; an idle target starts a turn, and only a direct child can be cold-resumed. The parent can also interrupt a running descendant or list its children at any time. A browser continuation prompt independently selects Queue or Steer and may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Direct-child discovery reads the parent-owned `subagentCatalog` projection. `listChildren(parentSessionId, signal?)` owns a live-preferred Session observation and returns the catalog asynchronously without reading child logs. It forwards cancellation and releases the observation after materialization. Materialization preserves parent event order in O(D) time for D facts. Complete descendant discovery retains the Session corpus and child identity projection; neither path loads or resumes a child Agent.
+Every exact live Agent can use `sendMessage()` with a direct continuable child; a resident continuable child can also use it with its direct parent. A working target receives the Agent message through Steer at its nearest step; an idle target starts a turn, and only a direct child can be cold-resumed. The parent can also interrupt a running descendant or list its children at any time. A browser continuation prompt independently selects Queue or Steer and may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Direct-child discovery reads the parent-owned `subagentCatalog` projection and Session headers. `listChildren(parentSessionId, signal?)` returns catalog entries in parent event order, then header-discovered children with `mode: 'unresolved'`; it never opens child bodies. It forwards cancellation and releases the parent observation after materialization. Header enumeration costs O(N) for N Sessions, while catalog materialization costs O(D) for D facts. Complete descendant discovery explicitly reads child identity projections; neither path loads or resumes a child Agent.
 
 ### Failure and recovery
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index af62ad97bc..90806e0728 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -60,7 +60,7 @@ kind: "package-reference"
 
 ### 消息、中断与发现
 
-每个确切在线 Agent 都可以对直接可继续 child 使用 `sendMessage()`；驻留的可继续 child 还可以对自己的直接 parent 使用它。正在工作的目标通过 Steer 在最近 step 接收 Agent 消息；空闲目标启动轮次，且只有直接 child 可以冷恢复。parent 也可以随时中断正在运行的后代或列举自己的子级。浏览器发出的继续执行 prompt 会独立选择 Queue 或 Steer，并且可以携带图片部分：Host 先通过附件存储完成整批图片的准入与持久化，子级 inbox 才接受这条消息；当子级声明的模型不接受图片输入时拒绝投递。 直接子级发现读取 parent 自有的 `subagentCatalog` projection。`listChildren(parentSessionId, signal?)` 持有一次优先实时来源的 Session 观察，异步返回目录，不读取子级日志。它转发取消信号，并在物化后释放观察。物化以 O(D) 时间保留 D 条事实的父日志事件顺序。完整后代发现保留 Session 语料库与子级身份 projection；两条路径都不加载或恢复子级 Agent。
+每个存活 Agent 都可以通过 `sendMessage()` 向直接可继续子代理发送消息；驻留的可继续子代理也可以向直接父代理发送。工作中的目标在最近步骤通过 Steer 接收消息，空闲目标启动新轮次，只有直接子代理支持冷恢复。父代理可以随时中断运行中的后代或列出子代理。浏览器续接独立选择 Queue 或 Steer，支持图片：Host 在子代理收件箱接收消息前准入并持久化图片，模型不支持图片输入时拒绝交付。直接子代理发现读取父会话的 `subagentCatalog` 投影和会话头部。`listChildren(parentSessionId, signal?)` 按父事件顺序返回 catalog 条目，再返回头部发现的 `mode: 'unresolved'` 子会话，不打开子会话正文。它传递取消信号，并在物化后释放父会话观察。N 个会话的头部枚举为 O(N)，D 条事实的 catalog 物化为 O(D)。完整后代发现显式读取子会话身份投影；两条路径均不加载或恢复子 Agent。
 
 ### 失败与恢复
 
diff --git a/packages/subagent/subagent/src/control-types.ts b/packages/subagent/subagent/src/control-types.ts
index 10a8cfc426..ae478966db 100644
--- a/packages/subagent/subagent/src/control-types.ts
+++ b/packages/subagent/subagent/src/control-types.ts
@@ -9,6 +9,7 @@ import type { PromptContentPart } from '@deepseek-ai/dsh-attachment/types'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SubagentCatalogEntry } from './projection-types.ts'
 
 /**
  * Client-minted identity of one browser prompt, persisted on the exact accepted
@@ -71,6 +72,13 @@ export type SubagentListEntry =
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
 
+/** A direct child whose identity is known from the catalog or awaits an explicit child read. */
+export type SubagentDiscoveryEntry = SubagentCatalogEntry | {
+  readonly id: SessionId
+  readonly createdAt: number
+  readonly mode: 'unresolved'
+}
+
 /** Durable parent/child address that selects subagent transport in the client. */
 export type SubagentAddress =
   & {
@@ -80,6 +88,8 @@ export type SubagentAddress =
   & (
     | { readonly mode: 'one-shot' }
     | { readonly mode: 'continuable' }
+    /** Header-discovered child; opening it resolves its descriptor without granting continuation. */
+    | { readonly mode: 'unresolved' }
   )
 
 /** One human message addressed to a continuable direct child. */
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 0262c37476..406bf9374b 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -76,7 +76,7 @@ import type { SubagentDescendantListEntry } from './list-children.ts'
 import { snapshotSubagentDescriptor } from './descriptor.ts'
 import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts'
 import { establishCatalogChild, subagentCatalogProjectionDefinition } from './catalog.ts'
-import type { SubagentCatalogEntry } from './projection-types.ts'
+import type { SubagentDiscoveryEntry } from './control-types.ts'
 import { deliverSubagentPrompt } from './internal.ts'
 
 export type {} from './catalog.ts'
@@ -366,15 +366,15 @@ export class SubagentRuntime extends TypertRemoteService {
   }
 
   /**
-   * Read the parent's durable direct-child catalog without loading or resuming an Agent.
+   * Read the parent's catalog and discover missing direct children from Session headers.
    * The service owns and releases the live-preferred Session observation.
    * @param parentSessionId - parent whose direct children are requested.
    * @param signal - cancellation forwarded to the Session query.
-   * @returns catalog children in parent event order.
+   * @returns catalog children in event order, then unresolved children whose bodies remain unread.
    * @throws {@link SubagentError} when query or catalog projection is unavailable.
    * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
    */
-  listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]> {
+  listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]> {
     return listSubagentChildren(this.ctx, parentSessionId, signal)
   }
 
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index 9de66e771c..8c3b96c0e0 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,7 +1,8 @@
 /**
  * Direct-child discovery from a parent-owned `subagent/catalog` projection,
- * plus complete descendant-tree enumeration from the Session corpus. A direct
- * listing owns one parent observation and reads no child log. Descendant
+ * with header-only discovery of missing entries, plus complete descendant-tree
+ * enumeration from the Session corpus. A direct listing observes one parent
+ * and reads no child log. Descendant
  * enumeration retains the complete corpus and the child identity projection
  * because ordinary Sessions and one-shot children remain traversal nodes.
  *
@@ -17,7 +18,7 @@ import type { SessionObservation, SessionQueryEngine } from '@deepseek-ai/dsh-se
 import type { SubagentListEntry } from './control-types.ts'
 import { SubagentError } from './error.ts'
 import type { SubagentIdentityProjection } from './projection-types.ts'
-import type { SubagentCatalogEntry } from './projection-types.ts'
+import type { SubagentDiscoveryEntry } from './control-types.ts'
 
 export type { SubagentListEntry } from './control-types.ts'
 
@@ -61,14 +62,14 @@ interface PositionedCandidate {
  * @param ctx - context carrying the Session query service.
  * @param parentSessionId - parent whose direct children are requested.
  * @param signal - cancellation forwarded to the Session observation.
- * @returns direct-child rows in parent catalog event order.
+ * @returns catalog rows in event order, followed by header-discovered children without reading their bodies.
  * @throws {@link SubagentError} when query or catalog projection is unavailable.
  */
 export async function listChildren(
   ctx: Context,
   parentSessionId: SessionId,
   signal?: AbortSignal,
-): Promise<SubagentCatalogEntry[]> {
+): Promise<SubagentDiscoveryEntry[]> {
   const query = ctx.get('sessionQuery')
   if (query === undefined) {
     throw new SubagentError(
@@ -86,7 +87,15 @@ export async function listChildren(
       'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE',
     )
   }
-  return entries
+  const discovered: SubagentDiscoveryEntry[] = [...entries]
+  const known = new Set(entries.map(entry => entry.id))
+  const records = await query.listSessions(signal)
+  for (const { header } of records) {
+    if (header.origin === 'subagent' && header.parentSession === parentSessionId && !known.has(header.id)) {
+      discovered.push({ id: header.id, createdAt: header.createdAt, mode: 'unresolved' })
+    }
+  }
+  return discovered
 }
 
 /**
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index 84bcd8d6be..b472c074d6 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -184,7 +184,7 @@ function mutateStoredHeader(
 }
 
 describe('SubagentRuntime.listChildren', () => {
-  it('lists historical children through a migrated parent while preserving V3 files', async () => {
+  it('discovers historical children from headers while leaving their bodies unread', async () => {
     const { ctx, root } = await setup([], { compression: 'none' })
     const parent = SessionId('historical-parent')
     const child = SessionId('historical-child')
@@ -204,16 +204,18 @@ describe('SubagentRuntime.listChildren', () => {
       return { path, content }
     })
 
+    const observe = vi.spyOn(ctx.sessionQuery, 'observeSession')
     expect(await ctx.subagents.listChildren(parent)).toEqual([{
-      id: child, createdAt: 2, mode: 'continuable', label: 'historical child',
+      id: child, createdAt: 2, mode: 'unresolved',
     }])
+    expect(observe.mock.calls.map(([id]) => id)).toEqual([parent])
     for (const { path, content } of originals) {
       expect(readFileSync(path, 'utf8')).toBe(content)
       expect(readdirSync(dirname(path))).toEqual(['session.v3.jsonl'])
     }
   })
 
-  it('lists provider-established children from the parent catalog without a corpus or child read', async () => {
+  it('lists provider-established children from the parent catalog without a child body read', async () => {
     const { ctx, parent } = await setup([textResponse('once'), textResponse('again')])
     const oneShot = await ctx.subagents.start('spawn', {
       prompt: [{ type: 'text', text: 'finish once' }],
@@ -234,7 +236,7 @@ describe('SubagentRuntime.listChildren', () => {
       { id: continuableId, label: 'continuable child', mode: 'continuable' },
     ])
     expect(children.every(child => Number.isFinite(child.createdAt))).toBe(true)
-    expect(listSessions).not.toHaveBeenCalled()
+    expect(listSessions).toHaveBeenCalledOnce()
     expect(observeSession).toHaveBeenCalledOnce()
   })
 
@@ -338,7 +340,7 @@ describe('SubagentRuntime.listChildren', () => {
     }
     expect(chunkLengths).toEqual([1, ...Array.from({ length: 16 }, () => 64)])
     const entries = await ctx.subagents.listChildren(parent.id)
-    expect(listSessions).not.toHaveBeenCalled()
+    expect(listSessions).toHaveBeenCalledOnce()
     expect(entries).toHaveLength(1_025)
     expect(entries.find(entry => entry.id === 'child-064')).toEqual({
       id: SessionId('child-064'), createdAt: 64, mode: 'one-shot',
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index b8478ed970..d234a3b96e 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/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/subagent/tool-subagent-control/README.md
-README.md: 2cfa000f1ba9f7950b28369a9b7bd3523610b579
-README.zh.md: f2154fde965899e7b4f30271846bce52414b010d
+README.md: 1be0e2b15f6ff36235275f659770c0c92557006e
+README.zh.md: 3ee5e80aabd97df50feee46ea9183dee2916faf2
diff --git a/packages/subagent/tool-subagent-control/README.md b/packages/subagent/tool-subagent-control/README.md
index 2cfa000f1b..1be0e2b15f 100644
--- a/packages/subagent/tool-subagent-control/README.md
+++ b/packages/subagent/tool-subagent-control/README.md
@@ -54,7 +54,7 @@ Stops only the target's current turn: queued messages stay parked until a later
 
 ### list_agents
 
-Lists the continuable children below the calling agent: `children` (default) reads direct children from the parent catalog without opening child logs; `descendants` walks the whole tree in stable pre-order, annotating each entry with its durable direct-parent session id and depth. Status comes from the live Agent registry — `running` or `inactive`. One-shot children are intentionally absent because they cannot accept `send_message`, and unreadable candidates appear as diagnostics only in `descendants` scope.
+Lists the continuable children below the calling agent: `children` (default) combines parent catalog facts with header discovery without opening child logs; unresolved identities appear as `unavailable` diagnostics. `descendants` explicitly reads identities throughout the tree in stable pre-order and includes durable direct-parent ids and depths. Status comes from the live Agent registry: `running` or `inactive`. Known one-shot children are omitted because they cannot accept `send_message`.
 
 -----
 
@@ -150,7 +150,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = executing a turn; `inactive` = no turn executing, whether loaded or stored; neither status describes task completion or outcome). Only `descendants` scope adds `<id> [diagnostic: <reason>]` for a candidate that could not be read. The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection.
+One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = executing a turn; `inactive` = no turn executing, whether loaded or stored; neither status describes task completion or outcome). Either scope adds `<id> [diagnostic: <reason>]` for a candidate that could not be read. The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection.
 
 #### Token effect
 
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index f2154fde96..3ee5e80aab 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -54,7 +54,7 @@ kind: "package-reference"
 
 ### list_agents
 
-列出调用方 agent 下方的可继续子级：`children`（默认）从父目录读取直接子级，不打开子日志；`descendants` 按稳定前序遍历整棵树，并为每个条目标注其持久化直接父级会话 ID 与深度。状态来自在线 Agent 注册表——`running` 或 `inactive`。一次性子级因无法接受 `send_message` 而被有意排除，无法读取的候选项仅在 `descendants` 作用域中以诊断信息呈现。
+列出调用代理下的可继续子代理：`children`（默认）合并父 catalog 事实与头部发现，不打开子日志；未解析身份显示为 `unavailable` 诊断。`descendants` 按稳定前序显式读取整棵树的身份，并包含持久化直接父 id 和深度。状态取自存活 Agent 注册表：`running` 或 `inactive`。已知一次性子代理不支持 `send_message`，因此省略。
 
 -----
 
@@ -150,7 +150,7 @@ kind: "package-reference"
 
 #### 模型看到什么
 
-按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。仅 `descendants` 作用域会为无法读取的候选项添加 `<id> [diagnostic: <reason>]`。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。一次性子级会被有意排除；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
+按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。两个 scope 都会为身份不可用的候选项添加 `<id> [diagnostic: <reason>]`。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。一次性子级会被有意排除；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
 
 #### Token 影响
 
diff --git a/packages/subagent/tool-subagent-control/src/list-agents.ts b/packages/subagent/tool-subagent-control/src/list-agents.ts
index cd308b7056..6cc853371a 100644
--- a/packages/subagent/tool-subagent-control/src/list-agents.ts
+++ b/packages/subagent/tool-subagent-control/src/list-agents.ts
@@ -12,7 +12,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import type {
-  SubagentCatalogEntry, SubagentDescendantListEntry, SubagentListEntry,
+  SubagentDiscoveryEntry, SubagentDescendantListEntry, SubagentListEntry,
 } from '@deepseek-ai/dsh-subagent'
 import { assertNever } from '@deepseek-ai/dsh-util-values'
 
@@ -59,13 +59,16 @@ function statusOf(agents: { get(id: SessionId): Agent | undefined }, id: Session
 /** Project one service row into the model-facing entry, or omit a one-shot child. */
 function project(
   agents: { get(id: SessionId): Agent | undefined },
-  entry: SubagentCatalogEntry | SubagentListEntry,
+  entry: SubagentDiscoveryEntry | SubagentListEntry,
   position?: Pick<SubagentDescendantListEntry, 'parentId' | 'depth'>,
 ): ListAgentsEntry | undefined {
   const at = position === undefined ? {} : { parent: position.parentId, depth: position.depth }
   if ('kind' in entry && entry.kind === 'diagnostic') {
     return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at }
   }
+  if (entry.mode === 'unresolved') {
+    return { kind: 'diagnostic', id: entry.id, reason: 'unavailable', ...at }
+  }
   // One-shot children cannot be continued by send_message, so the model
   // never selects them; discovery still traversed them for descendants.
   if (entry.mode !== 'continuable') return undefined
@@ -94,7 +97,7 @@ export function apply(ctx: Context): void {
       + 'or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` '
       + 'candidate in every status. The snapshot is not a delivery '
       + 'promise — `send_message` performs the authoritative check and may still fail. Children that could '
-      + 'not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` '
+      + 'not be identified without opening them are reported as diagnostics. Scope `descendants` '
       + 'walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent '
       + 'session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are '
       + 'candidates for `interrupt_agent` only.',
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 2fd206ed1a..809f483369 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -131,6 +131,17 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     expect(text(result)).toBe('(no subagents)')
   })
 
+  it('reports header-discovered children without reading their unresolved identities', async () => {
+    const { ctx, parent } = await setup([])
+    vi.spyOn(ctx.subagents, 'listChildren').mockResolvedValue([
+      { id: SessionId('unopened'), createdAt: 1, mode: 'unresolved' },
+    ])
+    const result = await callTool(ctx, 'list_agents', {}, parent)
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('unopened')
+    expect(text(result)).toContain('unavailable')
+  })
+
   it('renders direct children in array order with registry statuses', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     const started = await ctx.subagents.startContinuable({
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index c3a8c6a239..c75ebb5d7f 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -561,6 +561,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuableStartSpec: 'subagent.md',
   AgentMessageSource: 'subagent.md',
   SubagentCatalogEntry: 'subagent.md',
+  SubagentDiscoveryEntry: 'subagent.md',
   SubagentCatalogState: 'subagent.md',
   SessionProjectionsRequest: 'session.md',
   SessionProjectionsValue: 'session.md',
diff --git a/snapshots/sdk/bash-tool/tool-schemas.expected.json b/snapshots/sdk/bash-tool/tool-schemas.expected.json
index 58b6f5a201..d0a1b52676 100644
--- a/snapshots/sdk/bash-tool/tool-schemas.expected.json
+++ b/snapshots/sdk/bash-tool/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json b/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json b/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json b/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json b/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json
index 55005a53e3..e9ead7a7fe 100644
--- a/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json
+++ b/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json
index c185eca7ec..cc45a91131 100644
--- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json
index e93f34ff32..f6f09a4ece 100644
--- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json
+++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json b/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json b/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/text-turn/tool-schemas.expected.json b/snapshots/sdk/text-turn/tool-schemas.expected.json
index 58b6f5a201..d0a1b52676 100644
--- a/snapshots/sdk/text-turn/tool-schemas.expected.json
+++ b/snapshots/sdk/text-turn/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/agent-instructions/tool-schemas.expected.json b/snapshots/session/agent-instructions/tool-schemas.expected.json
index a3a82e074d..51a6889dd0 100644
--- a/snapshots/session/agent-instructions/tool-schemas.expected.json
+++ b/snapshots/session/agent-instructions/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -857,7 +857,7 @@
       },
       {
         "name": "list_agents",
-        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
         "parameters": {
           "type": "object",
           "properties": {
diff --git a/snapshots/session/background-confinement-failure/tool-schemas.expected.json b/snapshots/session/background-confinement-failure/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/background-confinement-failure/tool-schemas.expected.json
+++ b/snapshots/session/background-confinement-failure/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/both-mode-turn/system-prompt.expected.md b/snapshots/session/both-mode-turn/system-prompt.expected.md
index f15f09f8de..0de6b19abb 100644
--- a/snapshots/session/both-mode-turn/system-prompt.expected.md
+++ b/snapshots/session/both-mode-turn/system-prompt.expected.md
@@ -133,7 +133,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/both-mode-turn/tool-schemas.expected.json b/snapshots/session/both-mode-turn/tool-schemas.expected.json
index 86ee3527e9..b08bf5c39c 100644
--- a/snapshots/session/both-mode-turn/tool-schemas.expected.json
+++ b/snapshots/session/both-mode-turn/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json b/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json
index 1cb484d359..ba94d36aa0 100644
--- a/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json
+++ b/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json b/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json
index db6f9d1f94..ca3f7b0bfb 100644
--- a/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json
+++ b/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json b/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json
index 09640f90af..d1f297b125 100644
--- a/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json
+++ b/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/compaction-recovery/tool-schemas.expected.json b/snapshots/session/compaction-recovery/tool-schemas.expected.json
index a3a82e074d..51a6889dd0 100644
--- a/snapshots/session/compaction-recovery/tool-schemas.expected.json
+++ b/snapshots/session/compaction-recovery/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -857,7 +857,7 @@
       },
       {
         "name": "list_agents",
-        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
         "parameters": {
           "type": "object",
           "properties": {
diff --git a/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json b/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json
index 024361e301..7b304d9d5b 100644
--- a/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json
+++ b/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json b/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json
index ececc98096..93aabc3d77 100644
--- a/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json
+++ b/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json
@@ -291,7 +291,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
index 158f24c1af..257de6a9aa 100644
--- a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
+++ b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
@@ -150,7 +150,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
index a48efa53bf..640e583b68 100644
--- a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
+++ b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
@@ -286,7 +286,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json b/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json
+++ b/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json b/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json
+++ b/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json b/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json
+++ b/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/fs-glob-sampling/tool-schemas.expected.json b/snapshots/session/fs-glob-sampling/tool-schemas.expected.json
index 1106ebbe40..e1a873b1da 100644
--- a/snapshots/session/fs-glob-sampling/tool-schemas.expected.json
+++ b/snapshots/session/fs-glob-sampling/tool-schemas.expected.json
@@ -165,7 +165,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/lsp-definition/tool-schemas.expected.json b/snapshots/session/lsp-definition/tool-schemas.expected.json
index da96eef30a..440ae6a4b9 100644
--- a/snapshots/session/lsp-definition/tool-schemas.expected.json
+++ b/snapshots/session/lsp-definition/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/mcp-resources-ptc/system-prompt.expected.md b/snapshots/session/mcp-resources-ptc/system-prompt.expected.md
index edb6c751b8..cb2a114d95 100644
--- a/snapshots/session/mcp-resources-ptc/system-prompt.expected.md
+++ b/snapshots/session/mcp-resources-ptc/system-prompt.expected.md
@@ -143,7 +143,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/mcp-resources/tool-schemas.expected.json b/snapshots/session/mcp-resources/tool-schemas.expected.json
index d6dea164c9..8122f0b7bd 100644
--- a/snapshots/session/mcp-resources/tool-schemas.expected.json
+++ b/snapshots/session/mcp-resources/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json b/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json
index 863f729ecd..8b68c58b38 100644
--- a/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json
+++ b/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json
@@ -120,7 +120,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json b/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
index 07f01589c0..261f0ddb8b 100644
--- a/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
+++ b/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -908,7 +908,7 @@
       },
       {
         "name": "list_agents",
-        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
         "parameters": {
           "type": "object",
           "properties": {
diff --git a/snapshots/session/plugin-manager/tool-schemas.expected.json b/snapshots/session/plugin-manager/tool-schemas.expected.json
index 2a18354c6f..bb8d07e52b 100644
--- a/snapshots/session/plugin-manager/tool-schemas.expected.json
+++ b/snapshots/session/plugin-manager/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/product-subagent-both/tool-schemas.expected.json b/snapshots/session/product-subagent-both/tool-schemas.expected.json
index a0ec94f072..1d647f6882 100644
--- a/snapshots/session/product-subagent-both/tool-schemas.expected.json
+++ b/snapshots/session/product-subagent-both/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/product-subagent-codex/tool-schemas.expected.json b/snapshots/session/product-subagent-codex/tool-schemas.expected.json
index fa96127988..4dbf14ee7b 100644
--- a/snapshots/session/product-subagent-codex/tool-schemas.expected.json
+++ b/snapshots/session/product-subagent-codex/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json b/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json
index af722e03b0..768692ba44 100644
--- a/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json
+++ b/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/provider-cwd/tool-schemas.expected.json b/snapshots/session/provider-cwd/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/provider-cwd/tool-schemas.expected.json
+++ b/snapshots/session/provider-cwd/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ptc-node-read-only/system-prompt.expected.md b/snapshots/session/ptc-node-read-only/system-prompt.expected.md
index ff41826d84..9dd66f0cdf 100644
--- a/snapshots/session/ptc-node-read-only/system-prompt.expected.md
+++ b/snapshots/session/ptc-node-read-only/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/ptc-node-workspace/system-prompt.expected.md b/snapshots/session/ptc-node-workspace/system-prompt.expected.md
index ff41826d84..9dd66f0cdf 100644
--- a/snapshots/session/ptc-node-workspace/system-prompt.expected.md
+++ b/snapshots/session/ptc-node-workspace/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/ptc-python-turn/system-prompt.expected.md b/snapshots/session/ptc-python-turn/system-prompt.expected.md
index b7dfe3bf47..897f2c85a2 100644
--- a/snapshots/session/ptc-python-turn/system-prompt.expected.md
+++ b/snapshots/session/ptc-python-turn/system-prompt.expected.md
@@ -527,7 +527,7 @@ class Tools(Protocol):
     async def job_output(self, args: JobOutputArgs) -> JobOutputOutput:
         """Read a background job. Stream jobs return only output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap."""
     async def list_agents(self, args: ListAgentsArgs) -> list[ListAgentsOutput1 | ListAgentsOutput2]:
-        """List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only."""
+        """List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only."""
     async def read(self, args: ReadArgs) -> ReadOutput:
         """Read a UTF-8 text file and return line-numbered content."""
     async def read_image(self, args: ReadImageArgs) -> ReadImageOutput:
diff --git a/snapshots/session/ptc-read-image/system-prompt.expected.md b/snapshots/session/ptc-read-image/system-prompt.expected.md
index fd956219e6..7174e00853 100644
--- a/snapshots/session/ptc-read-image/system-prompt.expected.md
+++ b/snapshots/session/ptc-read-image/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/ptc-turn/system-prompt.expected.md b/snapshots/session/ptc-turn/system-prompt.expected.md
index ff41826d84..9dd66f0cdf 100644
--- a/snapshots/session/ptc-turn/system-prompt.expected.md
+++ b/snapshots/session/ptc-turn/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json b/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json
index 4471c7a371..8b3d055a54 100644
--- a/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json
+++ b/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json b/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json
index 5002d370b8..7c1c97aeb2 100644
--- a/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json
+++ b/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json
@@ -172,7 +172,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ralph-loop/tool-schemas.1.expected.json b/snapshots/session/ralph-loop/tool-schemas.1.expected.json
index 2118a8e4b0..204212e968 100644
--- a/snapshots/session/ralph-loop/tool-schemas.1.expected.json
+++ b/snapshots/session/ralph-loop/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ralph-loop/tool-schemas.2.expected.json b/snapshots/session/ralph-loop/tool-schemas.2.expected.json
index 2118a8e4b0..204212e968 100644
--- a/snapshots/session/ralph-loop/tool-schemas.2.expected.json
+++ b/snapshots/session/ralph-loop/tool-schemas.2.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ralph-loop/tool-schemas.expected.json b/snapshots/session/ralph-loop/tool-schemas.expected.json
index 57eaf5feaa..486b2c380a 100644
--- a/snapshots/session/ralph-loop/tool-schemas.expected.json
+++ b/snapshots/session/ralph-loop/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/session-query-spill/tool-schemas.expected.json b/snapshots/session/session-query-spill/tool-schemas.expected.json
index 5c635ee9a1..ccf2f16ce0 100644
--- a/snapshots/session/session-query-spill/tool-schemas.expected.json
+++ b/snapshots/session/session-query-spill/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json b/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json
index 2c08e64dc9..0dda1ec644 100644
--- a/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json
+++ b/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json b/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json
index 50b44889ea..bf2659c163 100644
--- a/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json
+++ b/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json b/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json
index 1776b0e3ac..4852bca23e 100644
--- a/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json
+++ b/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json
@@ -159,7 +159,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/system-prompt-in-history/tool-schemas.expected.json b/snapshots/session/system-prompt-in-history/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/system-prompt-in-history/tool-schemas.expected.json
+++ b/snapshots/session/system-prompt-in-history/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/text-turn/tool-schemas.expected.json b/snapshots/session/text-turn/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/text-turn/tool-schemas.expected.json
+++ b/snapshots/session/text-turn/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/web-fetch/tool-schemas.expected.json b/snapshots/session/web-fetch/tool-schemas.expected.json
index cccf295aa2..3affe6bfcf 100644
--- a/snapshots/session/web-fetch/tool-schemas.expected.json
+++ b/snapshots/session/web-fetch/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/workflow-confinement/tool-schemas.expected.json b/snapshots/session/workflow-confinement/tool-schemas.expected.json
index f1421e3b5d..6001c6db73 100644
--- a/snapshots/session/workflow-confinement/tool-schemas.expected.json
+++ b/snapshots/session/workflow-confinement/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/workspace-dependencies/tool-schemas.expected.json b/snapshots/session/workspace-dependencies/tool-schemas.expected.json
index 7697c3522f..b4ad218ce2 100644
--- a/snapshots/session/workspace-dependencies/tool-schemas.expected.json
+++ b/snapshots/session/workspace-dependencies/tool-schemas.expected.json
@@ -200,7 +200,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/web/cordis-tool-round/tool-schemas.expected.json b/snapshots/web/cordis-tool-round/tool-schemas.expected.json
index ca7afe0add..aa85c50716 100644
--- a/snapshots/web/cordis-tool-round/tool-schemas.expected.json
+++ b/snapshots/web/cordis-tool-round/tool-schemas.expected.json
@@ -505,7 +505,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/web/fresh-round-trip/tool-schemas.expected.json b/snapshots/web/fresh-round-trip/tool-schemas.expected.json
index 48bb6c3607..1a8fbaa834 100644
--- a/snapshots/web/fresh-round-trip/tool-schemas.expected.json
+++ b/snapshots/web/fresh-round-trip/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/web/preset-migration/session.1.v2.jsonl b/snapshots/web/preset-migration/session.1.v2.jsonl
new file mode 100644
index 0000000000..47ef5e21a9
--- /dev/null
+++ b/snapshots/web/preset-migration/session.1.v2.jsonl
@@ -0,0 +1,3 @@
+{"type":"session","version":2,"id":"{{session:2}}","createdAt":2,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":1,"agentPreset":"code","origin":"subagent","parentSession":"{{session:1}}"}
+{"type":"subagent/descriptor","data":{"version":3,"provider":"spawn","mode":"one-shot","label":"historical child"}}
+{"type":"feedback/record","data":{"text":"Child history remains readable independently."}}
diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md
index 8787372c8f..68dadfbef1 100644
--- a/snapshots/web/ptc-round/system-prompt.expected.md
+++ b/snapshots/web/ptc-round/system-prompt.expected.md
@@ -155,7 +155,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/web/schedule-catalog/tool-schemas.expected.json b/snapshots/web/schedule-catalog/tool-schemas.expected.json
index 4fc9dab8fd..18e72de911 100644
--- a/snapshots/web/schedule-catalog/tool-schemas.expected.json
+++ b/snapshots/web/schedule-catalog/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {

From 1c16bc9a0e60876fda59dac5240c6c07c611c39c Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sat, 19 Sep 2026 22:47:59 +0800
Subject: [PATCH 06/37] test(subagent): use branded descriptor sequence in
 restored identity

---
 .../client/ui-subagent/tests/conversation-ui.client.spec.tsx  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
index a7dc9f63a5..0b7c79e9cf 100644
--- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
@@ -6,7 +6,7 @@ import type {
   SessionListState, SessionSummary, SessionSnapshot,
 } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SubagentAddress, SubagentCatalogRow } 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 type { SessionStatusSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
 import {
   SubagentHeaderLineage, type SubagentHeaderLineageProps,
@@ -583,7 +583,7 @@ describe('SubagentHeaderLineage', () => {
     const input = props(undefined, {}, {
       [CHILD]: {
         ...summary(CHILD, 1), parentId: PARENT, origin: 'subagent',
-        projectionValues: { subagent: { mode: 'one-shot', label: 'restored', seq: 0 } },
+        projectionValues: { subagent: { mode: 'one-shot', label: 'restored', seq: SessionSeq(0) } },
       },
     })
     render(<SubagentHeaderLineage {...input} />)

From e6e5d95b290de725560f59acfe21e94bfbbfe2e5 Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sat, 19 Sep 2026 23:03:38 +0800
Subject: [PATCH 07/37] test(session): align migration corpus and CLI
 expectations with lazy reads

---
 ...session-local-subagent-migration.i18n.yaml |  4 +--
 ...-09-19-session-local-subagent-migration.md |  2 ++
 ...-19-session-local-subagent-migration.zh.md |  2 ++
 packages/boot/app-boot/src/package-meta.ts    |  2 +-
 .../tests/components.client.spec.tsx          | 20 ++++++++---
 .../tests/sidebar-chat.client.spec.tsx        | 33 ++++++++++---------
 scripts/migrate-sessions-to-v4.spec.ts        | 12 ++++---
 scripts/no-unknown-casts.baseline.json        |  5 ---
 .../session-snapshot-corpus-policy.spec.ts    | 12 ++++---
 scripts/session-snapshot-corpus-policy.ts     |  2 +-
 scripts/session-snapshot-corpus.corpus.ts     |  2 +-
 scripts/verify-package-meta.ts                |  2 +-
 12 files changed, 58 insertions(+), 40 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
index dcd77fa51d..d304ff6814 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.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-09-19-session-local-subagent-migration.md
-2026-09-19-session-local-subagent-migration.md: c3da2812ac2d48fe4894b62b3b5743664564633a
-2026-09-19-session-local-subagent-migration.zh.md: 43875dd8cd34635d33f711745aa9725641e4cec3
+2026-09-19-session-local-subagent-migration.md: e02d2434b6f778556db454d88776a97ee699709f
+2026-09-19-session-local-subagent-migration.zh.md: 61cb891105c39e9ef9524f1c9df2f257d8938045
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
index c3da2812ac..e02d2434b6 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
@@ -30,4 +30,6 @@ This partially supersedes runtime catalog prerequisites and corpus revisions in
 
 Explicit direct-child discovery now enumerates N headers in addition to materializing D catalog facts. It avoids all child-body decoding, while ordinary parent migration has no corpus-dependent preparation. Historical rows may initially show an id instead of a label and cannot promise resumability. Headers that cannot be decoded cannot contribute a navigation row, but do not block opening another known Session.
 
+The V2 parent/child regression needs two independently stored historical roles to exercise deferred migration and unchanged predecessors. Its additional child raises the retained corpus budget from ten to eleven roles; the gate still rejects a twelfth role.
+
 Raw and compressed persistence regressions cover V0–V3, child corruption and future formats, independent publication, unchanged predecessors, and stable parent revisions across child mutations. Service tests verify only the parent is observed. Client and Host tests verify unresolved addresses, selected-child decoding, mode resolution, and ownership rejection. The shipped Web preset-migration snapshot round-trips parent and child generations with a corrupt sibling and checks that only explicitly opened Sessions migrate.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
index 43875dd8cd..61cb891105 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
@@ -30,4 +30,6 @@ Catalog 仍是成功创建事实的持久化来源。未解析发现行既不是
 
 显式直接子发现除物化 D 条 catalog 事实外，还枚举 N 个头部。它避免所有子正文解码，而普通父迁移没有依赖全库的准备工作。历史行最初可能显示 id 而非标签，且不能承诺可续接。无法解码的头部不能贡献导航行，但不会阻止打开另一个已知会话。
 
+V2 父子会话回归需要两个独立存储的历史角色，以验证延迟迁移和前代文件保持不变。新增子会话将保留语料预算从十个角色增至十一个；门禁仍拒绝第十二个角色。
+
 原始与压缩持久化回归覆盖 V0–V3、子损坏与未来格式、独立发布、前代不变，以及子变化期间父版本标识稳定。服务测试确认只观察父会话。Client 和 Host 测试验证未解析地址、选中子解码、模式解析与归属拒绝。正式 Web preset-migration 快照在损坏兄弟会话存在时往返父子代次，并检查只有显式打开的会话才迁移。
diff --git a/packages/boot/app-boot/src/package-meta.ts b/packages/boot/app-boot/src/package-meta.ts
index cc8fe2ebfe..434b233d1e 100644
--- a/packages/boot/app-boot/src/package-meta.ts
+++ b/packages/boot/app-boot/src/package-meta.ts
@@ -58,7 +58,7 @@ function textOf(value: unknown, path: string): string | undefined {
 function readObject(file: string): Record<string, unknown> {
   let contents: unknown
   try {
-    contents = JSON.parse(readFileSync(file, 'utf8')) as unknown
+    contents = JSON.parse(readFileSync(file, 'utf8'))
   } catch (error) {
     throw new Error(`${file}: ${String(error)}`)
   }
diff --git a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
index 0737596fb5..a1b18d00b5 100644
--- a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
+++ b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
@@ -101,15 +101,27 @@ function renderTab(state: Partial<PluginManagerState> = {}, config: Partial<Conf
     setRowEnabled: vi.fn(),
     dismissNotice: vi.fn(),
   }
-  const props = {
+  const unusedHook = () => { throw new Error('unused standard hook') }
+  const renderSlot: PluginManagerPageProps['renderSlot'] = (name, owner, opts) => {
+    if (!('view' in owner) || (owner.view !== 'summary' && owner.view !== 'page')) {
+      throw new Error('configuration fixture requires a summary or page view')
+    }
+    return bodies[`${name}:${opts?.only ?? opts?.entryKey ?? ''}`]?.(owner.view) ?? null
+  }
+  const props: PluginManagerPageProps = {
+    usePanelInfo: unusedHook,
+    useSessions: unusedHook,
+    useSessionStatus: unusedHook,
+    useSessionRetainInfo: unusedHook,
+    useResource: unusedHook,
+    useWorkspaces: unusedHook,
     t,
     resolveText,
     ...actions,
     usePluginManager: bindSnapshotSelector(store),
     useConfigLedger: bindSnapshotSelector(ledger),
-    renderSlot: (name: string, owner: { view: 'summary' | 'page' }, opts: { only?: string; entryKey?: string }) =>
-      bodies[`${name}:${opts.only ?? opts.entryKey ?? ''}`]?.(owner.view) ?? null,
-  } as unknown as PluginManagerPageProps
+    renderSlot,
+  }
   const { rerender } = render(<PluginManagerPage {...props} />)
   return {
     store,
diff --git a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
index 4233188518..744cdb174a 100644
--- a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
@@ -1,10 +1,10 @@
 // @vitest-environment jsdom
 import type { ReactNode } from 'react'
 import { cleanup, render } from '@testing-library/react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { Context } from '@deepseek-ai/cordis'
+import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
 import type {
-  ISessions, SessionListState, SessionReference, SessionSnapshot,
+  SessionListState, SessionReference, SessionSnapshot,
 } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { ResourceProvider } from '@deepseek-ai/dsh-client-resources/client'
 import { sessionSnapshot } from '@deepseek-ai/dsh-client-test-runtime'
@@ -85,19 +85,22 @@ describe('Sidebar chat registration', () => {
     let provider: ResourceProvider<'subagentchat'> | undefined
     let definition: SidebarRightTabDefinition | undefined
     const registrations: { options: Record<string, unknown>; component: unknown }[] = []
-    const ctx = {
-      sessions: { retain, refresh, list } as unknown as ISessions,
-      resources: { register: (value: ResourceProvider<'subagentchat'>) => { provider = value; return () => {} } },
-      sidebarRightTabs: { register: (value: SidebarRightTabDefinition) => { definition = value; return () => {} } },
-      slots: {
-        inject: (_name: string, install: () => () => void) => install(),
-        register: (options: Record<string, unknown>, component: unknown) => {
-          registrations.push({ options, component })
-          return () => {}
-        },
+    const ctx = new Context()
+    onTestFinished(async () => { await ctx.fiber.dispose() })
+    ctx.provide('sessions', { retain, refresh, list })
+    ctx.provide('resources', {
+      register: (value: ResourceProvider<'subagentchat'>) => { provider = value; return () => {} },
+    })
+    ctx.provide('sidebarRightTabs', {
+      register: (value: SidebarRightTabDefinition) => { definition = value; return () => {} },
+    })
+    ctx.provide('slots', {
+      inject: (_name: string, install: () => () => void) => install(),
+      register: (options: Record<string, unknown>, component: unknown) => {
+        registrations.push({ options, component })
+        return () => {}
       },
-      effect: (install: () => unknown) => { install(); return () => {} },
-    } as unknown as Context
+    })
 
     registerSidebarChat(ctx, (key: string) => key === 'sidebar.chat' ? 'Chat' : key)
 
diff --git a/scripts/migrate-sessions-to-v4.spec.ts b/scripts/migrate-sessions-to-v4.spec.ts
index cf52171fef..e14a0e7cfd 100644
--- a/scripts/migrate-sessions-to-v4.spec.ts
+++ b/scripts/migrate-sessions-to-v4.spec.ts
@@ -225,7 +225,7 @@ describe('one-time V4 migration command', () => {
     }
   })
 
-  it.each(['none', 'zstd'] as const)('preserves %s parent/child history and catalog with serial or parallel jobs', async (compression) => {
+  it.each(['none', 'zstd'] as const)('migrates %s parent/child history independently with serial or parallel jobs', async (compression) => {
     const outputs: Buffer[][] = []
     for (const jobs of [1, 2]) {
       const root = temporaryRoot()
@@ -246,8 +246,9 @@ describe('one-time V4 migration command', () => {
         ))
         current.push(decoded)
       }
-      expect(current[0]!.toString().trim().split('\n').slice(1).map((line): unknown => JSON.parse(line))).toMatchObject([
-        { type: 'subagent/catalog', data: { childId: 'z-child', childCreatedAt: 2, mode: 'continuable', label: 'saved child' } },
+      expect(current[0]!.toString().trim().split('\n').slice(1)).toEqual([])
+      expect(current[1]!.toString().trim().split('\n').slice(1).map((line): unknown => JSON.parse(line))).toMatchObject([
+        { type: 'subagent/descriptor', data: { mode: 'continuable', label: 'saved child' } },
       ])
       outputs.push(current)
     }
@@ -341,7 +342,7 @@ describe('one-time V4 migration command', () => {
       Backend.prototype.open = async function(id, access, options) {
         if (id === 'a-parent' && access === 'write' && !changed) {
           changed = true;
-          throw new JsonlGenerationSourceChangedError(${JSON.stringify(child.path)});
+          throw new JsonlGenerationSourceChangedError(${JSON.stringify(parent.path)});
         }
         return open.call(this, id, access, options);
       };
@@ -360,7 +361,8 @@ describe('one-time V4 migration command', () => {
     expect(lines.filter(line => line.includes('RETRY'))).toHaveLength(1)
     expect(result.summary).toMatchObject({ totals: { converted: 2, alreadyV4: 0, failed: 0, skipped: 0 }, failureGroups: [] })
     const target = await readFile(join(parent.directory, 'session.v4.jsonl'), 'utf8')
-    expect(target).toContain('"type":"subagent/catalog"')
+    expect(target.trim().split('\n')).toHaveLength(1)
+    expect(JSON.parse(target)).toMatchObject({ version: 4, id: 'a-parent' })
     for (const source of [parent, child]) expect(await readFile(source.path)).toEqual(source.bytes)
   })
 
diff --git a/scripts/no-unknown-casts.baseline.json b/scripts/no-unknown-casts.baseline.json
index 33c09b4424..a09c69e2cd 100644
--- a/scripts/no-unknown-casts.baseline.json
+++ b/scripts/no-unknown-casts.baseline.json
@@ -671,9 +671,6 @@
   "packages/client/ui-plugin-manager/tests/browser-plugin.client.spec.tsx": {
     "04984a2ce1486250236e638e0197da0a1a840855ed3975c59130a85358c7e5fe": 1
   },
-  "packages/client/ui-plugin-manager/tests/components.client.spec.tsx": {
-    "624ce7f0e7acb423fcd3937994cd5ca0916ac27b76cb56a7587025f209a14351": 1
-  },
   "packages/client/ui-primitives/tests/highlight-viewport.client.spec.tsx": {
     "6061de0a1e01547eb1abf9d4e1b5fa79fda112fa35dda980775491123413dcce": 1
   },
@@ -838,13 +835,11 @@
     "92d757187bb2dba986b160c2417c7b4a8b199784d441bfa0777d8077774b932b": 1
   },
   "packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx": {
-    "024f8748e8908a495117a23a7673046a871f0d8187f8fe561aceba1269aefa31": 1,
     "6f46259a9f4093d68b3fc7859c263f21b6318197b74aba368e8904321ab5c4f9": 1,
     "7eb46f4e5e11cef80bd04f36bf7e9b81b3b3e0811e6a50c8dc0e59b13409ab47": 1,
     "93043ae394699d6c87db0291ac271884e16d5f5e5f80b8dffd6ec2ccbe0cb774": 1,
     "9fe5203965e5ff62ab3b914bbcbb5229a5146bf9b12839d99684742579b0f30f": 1,
     "c3f6bb95ba0791435add9be26269aec3bd5cf7bb8a1ffd88913ff8b08b142ed3": 1,
-    "e9abfbf3920ecd6502b74e5eb04d3a1a40b2519f849f5daa193ab7819184ee8b": 1,
     "ffb048df32b10bac91f37b55c618701aa0f9d24c5b5504a3d3f953dc8b7cc7fb": 1
   },
   "packages/client/ui-theme/tests/apply.client.spec.ts": {
diff --git a/scripts/session-snapshot-corpus-policy.spec.ts b/scripts/session-snapshot-corpus-policy.spec.ts
index d1f317db33..0cfe2231b7 100644
--- a/scripts/session-snapshot-corpus-policy.spec.ts
+++ b/scripts/session-snapshot-corpus-policy.spec.ts
@@ -111,12 +111,14 @@ describe('recorded-session corpus policy', () => {
   )
 
   it('bounds explicitly retained roles and requires a baseline/current majority', () => {
+    expect(assertSnapshotCorpusPolicy([
+      baseline, current,
+      { ...completeV0, selectedVersions: Array<number>(9).fill(0) }, ...adjacent,
+    ]).retainedRoles).toBe(11)
     expect(() => assertSnapshotCorpusPolicy([
-      baseline,
-      current,
-      { ...completeV0, selectedVersions: Array<number>(11).fill(0) },
-      ...adjacent,
-    ])).toThrow(`Session corpus retains ${11 + adjacent.length} historical roles; maximum is 10`)
+      baseline, current,
+      { ...completeV0, selectedVersions: Array<number>(10).fill(0) }, ...adjacent,
+    ])).toThrow('Session corpus retains 12 historical roles; maximum is 11')
     expect(() => assertSnapshotCorpusPolicy([
       { ...baseline, selectedVersions: [3] }, completeV0, ...adjacent,
     ])).toThrow(`Session corpus requires a baseline/current majority; baseline=1, current=0, retained=${1 + adjacent.length}`)
diff --git a/scripts/session-snapshot-corpus-policy.ts b/scripts/session-snapshot-corpus-policy.ts
index e10e35506a..0f3b911c4e 100644
--- a/scripts/session-snapshot-corpus-policy.ts
+++ b/scripts/session-snapshot-corpus-policy.ts
@@ -22,7 +22,7 @@ export interface SnapshotCorpusGenerationSummary {
 }
 
 const RETAINED_BASELINE_VERSION = 3
-const MAX_RETAINED_ROLES = 10
+const MAX_RETAINED_ROLES = 11
 const REQUIRED_V0_COVERAGE = new Set([
   'multi-hop',
   'packed-row',
diff --git a/scripts/session-snapshot-corpus.corpus.ts b/scripts/session-snapshot-corpus.corpus.ts
index efa995e839..54d4124ad4 100644
--- a/scripts/session-snapshot-corpus.corpus.ts
+++ b/scripts/session-snapshot-corpus.corpus.ts
@@ -204,7 +204,7 @@ it('keeps V3 replay input plus bounded declared historical migration coverage',
   const summary = assertSnapshotCorpusPolicy(inventory)
   expect(summary.baselineRoles).toBeGreaterThan(0)
   expect(summary).toMatchObject({
-    retainedRoles: 10,
+    retainedRoles: 11,
     retainedScenarios: 8,
   })
 })
diff --git a/scripts/verify-package-meta.ts b/scripts/verify-package-meta.ts
index 70dcc6d7ee..f5a486678f 100644
--- a/scripts/verify-package-meta.ts
+++ b/scripts/verify-package-meta.ts
@@ -22,7 +22,7 @@ function sourceJsonFiles(dir: string): SourceJson[] {
     const file = path.replaceAll('\\', '/')
     let contents: unknown
     try {
-      contents = JSON.parse(readFileSync(join(dir, file), 'utf8')) as unknown
+      contents = JSON.parse(readFileSync(join(dir, file), 'utf8'))
     } catch (_error) {
       return { file, metadata: false, invalid: true }
     }

From f44b78a6224a3f0f0647146f6c24186f9b5e39d2 Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sun, 20 Sep 2026 12:09:57 +0800
Subject: [PATCH 08/37] fix(session): complete parent catalogs while isolating
 child failures

---
 ...leased-session-format-migrations.i18n.yaml |   4 +-
 ...8-31-released-session-format-migrations.md |  10 +-
 ...1-released-session-format-migrations.zh.md |  10 +-
 ...01-parent-owned-subagent-catalog.i18n.yaml |   4 +-
 ...026-09-01-parent-owned-subagent-catalog.md |   4 +-
 ...-09-01-parent-owned-subagent-catalog.zh.md |   4 +-
 ...session-local-subagent-migration.i18n.yaml |   4 +-
 ...-09-19-session-local-subagent-migration.md |  24 +-
 ...-19-session-local-subagent-migration.zh.md |  26 +-
 ...ncomplete-child-catalog-evidence.i18n.yaml |   4 +-
 ...19-v3-incomplete-child-catalog-evidence.md |  10 +-
 ...v3-incomplete-child-catalog-evidence.zh.md |  10 +-
 ...web-subagent-catalog-projections.i18n.yaml |   4 +-
 ...-09-08-web-subagent-catalog-projections.md |   6 +-
 ...-08-web-subagent-catalog-projections.zh.md |   6 +-
 apps/web/tests/preset-migration.snapshot.ts   |  16 +-
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   2 +-
 docs/config-catalog.zh.md                     |   2 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |  10 +-
 docs/subsystems/subagent.zh.md                |  10 +-
 docs/tool-catalog.i18n.yaml                   |   4 +-
 docs/tool-catalog.md                          |   2 +-
 docs/tool-catalog.zh.md                       |   2 +-
 .../api/session-controller/README.i18n.yaml   |   4 +-
 packages/api/session-controller/README.md     |   2 +-
 packages/api/session-controller/README.zh.md  |   2 +-
 .../src/client/sessions/manager.ts            |  12 +-
 .../src/client/sessions/session.ts            |   5 +-
 .../api/session-controller/src/history.ts     |   2 +-
 packages/api/session-controller/src/types.ts  |   2 +-
 .../tests/manager.client.spec.ts              |  40 +--
 .../tests/transport.host.spec.ts              |  21 --
 packages/client/ui-subagent/README.i18n.yaml  |   4 +-
 packages/client/ui-subagent/README.md         |   8 +-
 packages/client/ui-subagent/README.zh.md      |   8 +-
 .../src/client/SubagentHeaderLineage.tsx      |  41 +--
 .../src/client/SubagentReadOnlyComposer.tsx   |   4 +-
 .../client/ui-subagent/src/client/index.ts    |   5 +-
 .../client/ui-subagent/src/client/locales.ts  |   4 -
 .../src/client/sidebar-chat/index.tsx         |   4 +-
 .../tests/browser-plugin.client.spec.ts       |  20 +-
 .../tests/conversation-ui.client.spec.tsx     |  68 +---
 .../tests/sidebar-chat.client.spec.tsx        |  41 ++-
 .../ui-workspace/src/client/navigation.ts     |   1 +
 .../tests/workspaces-service.client.spec.ts   |   1 +
 .../extensions/tool-cordis/src/api-catalog.ts |  14 +-
 .../session-format-catalog/README.i18n.yaml   |   4 +-
 .../session/session-format-catalog/README.md  |   4 +-
 .../session-format-catalog/README.zh.md       |   4 +-
 .../session-format-catalog/src/children.ts    |   2 +-
 .../tests/children.spec.ts                    |   4 +-
 .../session-format-v3-to-v4/README.i18n.yaml  |   4 +-
 .../session/session-format-v3-to-v4/README.md |   4 +-
 .../session-format-v3-to-v4/README.zh.md      |   4 +-
 .../session-format-v3-to-v4/src/facts.ts      |   7 +-
 .../session-format-v3-to-v4/src/migration.ts  |   8 +-
 .../tests/catalog-completion.spec.ts          |   4 +-
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-jsonl/README.md       |   6 +-
 .../session-persistence-jsonl/README.zh.md    |   6 +-
 .../src/catalog-migration.ts                  |  88 +++++
 .../src/generation.ts                         |  33 ++
 .../session-persistence-jsonl/src/index.ts    |  79 ++++-
 .../tests/catalog-migration.spec.ts           | 306 ++++++++++++++----
 .../tests/generation.spec.ts                  |  14 +
 .../tests/jsonl.spec.ts                       |   6 +-
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   2 +-
 packages/subagent/subagent/README.zh.md       |   2 +-
 .../subagent/subagent/src/control-types.ts    |  10 -
 packages/subagent/subagent/src/index.ts       |   8 +-
 .../subagent/subagent/src/list-children.ts    |  21 +-
 .../subagent/tests/list-children.spec.ts      |  12 +-
 .../tool-subagent-control/README.i18n.yaml    |   4 +-
 .../subagent/tool-subagent-control/README.md  |   4 +-
 .../tool-subagent-control/README.zh.md        |   4 +-
 .../tool-subagent-control/src/list-agents.ts  |   9 +-
 .../tests/list-agents.spec.ts                 |  11 -
 scripts/gen-cordis-catalog.ts                 |   1 -
 scripts/migrate-sessions-to-v4.spec.ts        |  12 +-
 scripts/no-unknown-casts.baseline.json        |   2 +
 .../sdk/bash-tool/tool-schemas.expected.json  |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../sdk/text-turn/tool-schemas.expected.json  |   2 +-
 .../tool-schemas.expected.json                |   4 +-
 .../tool-schemas.expected.json                |   2 +-
 .../both-mode-turn/system-prompt.expected.md  |   2 +-
 .../both-mode-turn/tool-schemas.expected.json |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   4 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../lsp-definition/tool-schemas.expected.json |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../mcp-resources/tool-schemas.expected.json  |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   4 +-
 .../plugin-manager/tool-schemas.expected.json |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../provider-cwd/tool-schemas.expected.json   |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../system-prompt.expected.md                 |   2 +-
 .../ptc-python-turn/system-prompt.expected.md |   2 +-
 .../ptc-read-image/system-prompt.expected.md  |   2 +-
 .../ptc-turn/system-prompt.expected.md        |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../pwsh-tool-turn/tool-schemas.expected.json |   2 +-
 .../ralph-loop/tool-schemas.1.expected.json   |   2 +-
 .../ralph-loop/tool-schemas.2.expected.json   |   2 +-
 .../ralph-loop/tool-schemas.expected.json     |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.1.expected.json              |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../text-turn/tool-schemas.expected.json      |   2 +-
 .../web-fetch/tool-schemas.expected.json      |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 .../web/ptc-round/system-prompt.expected.md   |   2 +-
 .../tool-schemas.expected.json                |   2 +-
 142 files changed, 770 insertions(+), 550 deletions(-)
 create mode 100644 packages/session/session-persistence-jsonl/src/catalog-migration.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
index 78e0976e24..d31a7e21b8 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.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-31-released-session-format-migrations.md
-2026-08-31-released-session-format-migrations.md: 11c35eb80862ccebbead566164e61b5f4a7792fb
-2026-08-31-released-session-format-migrations.zh.md: a79bf77ab19ae85bc4dc9c6a942022b8bd198378
+2026-08-31-released-session-format-migrations.md: 21c95503ad05abf54b00c9cb20bec563cbd885ae
+2026-08-31-released-session-format-migrations.zh.md: 46e26b14d10adcc66cf4f0c0aea7573bae3f235a
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
index 11c35eb808..21c95503ad 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
@@ -105,7 +105,7 @@ Preparation forwards cancellation through source reads and observes it at the ex
 
 The Stage pipeline ends at one prepared current artifact. [Historical Session read preparation](2026-09-05-read-only-session-migration-preparation.md) defines how read open consumes that artifact immediately while write open performs encode, verification, and publication before returning append access.
 
-The bulk V4 migration command explicitly requests each Session through a bounded queue and shares one JSONL Context, including its two-Worker verification limit. Each publication validates only its own source. The command may retry a source-change refusal after the queue drains; a child publication does not invalidate a parent preparation.
+The bulk V4 migration command shares one JSONL persistence Context across a bounded job queue, retaining the backend’s two-Worker verification limit and cache for reusing recently decoded logs. A child’s concurrent publication can change its parent’s selected child generation; the ordinary revision check refuses that attempt. The command defers only this source-change error for one sequential retry after the initial queue drains, collecting fresh evidence without relaxing publication checks or retrying unrelated failures.
 
 ### Durable format and publication rules
 
@@ -131,20 +131,20 @@ Existing write handles retain the process-local claim and kernel-backed cross-pr
 
 ### Parent catalog prerequisites
 
-Original runtime policy (superseded by [Session-local migration](../bug-fix/2026-09-19-session-local-subagent-migration.md)): V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; absent entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs without backfilling that child, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. An unsupported generation or unreadable header elsewhere in that scan refuses migration because it cannot prove unrelatedness. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The storage decoder classifies physical JSON and compression failures before the collector adds child context; filesystem reads and cancellation keep their original errors. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
+Runtime child-failure handling in this paragraph is partially superseded by [session-local catalog preparation](../bug-fix/2026-09-19-session-local-subagent-migration.md): opening the parent still completes its catalog from direct-child reads, but unreadable children do not block healthy parent history. V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; absent entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs without backfilling that child, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. An unsupported generation or unreadable header elsewhere in that scan refuses migration because it cannot prove unrelatedness. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The storage decoder classifies physical JSON and compression failures before the collector adds child context; filesystem reads and cancellation keep their original errors. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
 
 Raw parent/child migration tests retain 24 historical creation-time conflicts as rejection evidence. Detached controls align only the child creation time and prove event-preserving restoration, including a published child without a descriptor. Headless/ACP and SDK snapshot adapters validate live parent/child clocks before normalization and preserve their equality during refresh; committed predecessor generations remain unchanged.
 
-Original runtime policy (superseded by [Session-local migration](../bug-fix/2026-09-19-session-local-subagent-migration.md)): Historical public revisions combine the parent’s physical revision with a fingerprint of every selected canonical path and its filesystem revision. Parent-only tokens cannot identify catalog changes supplied by children; a root fingerprint preserves metadata-only `stat`/`list` and includes unreadable or unsupported members without a new persistent index. Unrelated changes also invalidate historical caches, and obtaining the token costs a root scan. Current tokens stay file-local. The preparation memo keeps physical parent revisions and separately validates child membership and revisions.
+Historical public revisions combine the parent’s physical revision with a fingerprint of every selected canonical path and its filesystem revision. Parent-only tokens cannot identify catalog changes supplied by children; a root fingerprint preserves metadata-only `stat`/`list` and includes unreadable or unsupported members without a new persistent index. Unrelated changes also invalidate historical caches, and obtaining the token costs a root scan. Current tokens stay file-local. The preparation memo keeps physical parent revisions and separately validates child membership and revisions.
 
-Original runtime policy (superseded by [Session-local migration](../bug-fix/2026-09-19-session-local-subagent-migration.md)): The generic format interfaces carry only the artifact being restored. Parent-specific catalog assembly replaces the V3→V4 declaration with a closure over the collected child evidence; it reuses the generated codec, migration, and validation inventory. The assembly compiles one short migration chain per parent preparation, with independent stage state per restore. Binding at assembly keeps child evidence out of generic restore options and stage inputs without moving discovery or source revalidation into the migration. Static header and native current reads need no child evidence; an unbound historical body restore refuses rather than assuming an empty child set.
+The generic format interfaces carry only the artifact being restored. Parent-specific catalog assembly replaces the V3→V4 declaration with a closure over the collected child evidence; it reuses the generated codec, migration, and validation inventory. The assembly compiles one short migration chain per parent preparation, with independent stage state per restore. Binding at assembly keeps child evidence out of generic restore options and stage inputs without moving discovery or source revalidation into the migration. Static header and native current reads need no child evidence; an unbound historical body restore refuses rather than assuming an empty child set.
 
 <a id="catalog-scan-measurements"></a>
 ### Catalog scan measurements
 
 The package-local [diagnostic](../../../../packages/session/session-persistence-jsonl/tests/catalog-migration.perf.ts) measures one raw V3 parent, four direct children with 1,000 events each, and 0/100/1,000 unrelated header-only V3 Sessions. Each sample creates its own temporary corpus and Cordis context in a fresh process, runs stat → cold read → memo read → write publication → current warm read, and disposes the context and files. It uses built workspace exports under plain Node; fixture creation is outside the measured intervals. These are filesystem-cache-warm observations after fixture creation, not disk-cold latency or a performance gate.
 
-The table records the eager catalog-scan implementation on macOS arm64 with Node v26.0.0 before Session-local runtime migration. The 1,000-unrelated medians were 84.14 ms for stat, 237.97 ms for cold read, 110.98 ms for memo read, 268.46 ms for publication, and 0.41 ms for the same-process current read. These historical measurements explain why metadata-only access was insufficient while preparation still decoded child bodies; they are not current timings or cross-host thresholds.
+On macOS arm64 with Node v26.0.0, all three samples per size are below in milliseconds. Read-only opens do not publish: membership scanning remains proportional to corpus size even when decoding is memoized. The 1,000-unrelated medians are 84.14 ms for stat, 237.97 ms for cold read, 110.98 ms for memo read, 268.46 ms for publication, and 0.41 ms for the same-process current read. These measurements document the cost; they establish no speedup claim or cross-host threshold.
 
 | Unrelated Sessions | Historical stat | Cold read | Memo read | Publish | Current warm read |
 |---:|---:|---:|---:|---:|---:|
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
index a79bf77ab1..46e26b14d1 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
@@ -105,7 +105,7 @@ Preparation 会把 cancellation 传给 source read，并在现有的约 500 ms D
 
 Stage pipeline 终止于一份 prepared current artifact。[历史 Session 只读迁移准备](2026-09-05-read-only-session-migration-preparation.zh.md)定义 read open 如何立即消费该 artifact，以及 write open 如何在返回 append 权限前完成 encode、verification 与 publication。
 
-批量 V4 迁移命令通过有界队列显式请求各个会话，共享一个 JSONL Context 及其两个 Worker 的校验限制。每次发布只校验自身源文件。命令可在队列排空后重试源变化拒绝；子会话发布不会使父会话准备结果失效。
+批量 V4 迁移命令在有界任务队列中共享一个 JSONL persistence Context，保留 backend 的双 Worker 校验上限，以及复用近期已解码日志的缓存。子 Session 并发发布可能改变父 Session 选中的子代际；普通修订检查会拒绝这次尝试。命令只把这种源变化错误延后到初始队列清空后串行重试一次，重新收集证据，不放宽发布检查，也不重试无关失败。
 
 ### Durable format 与 publication 规则
 
@@ -131,20 +131,20 @@ POSIX publication 使用 hard-link creation 加目录 sync；Windows 使用 no-o
 
 ### 父目录前置事实
 
-原运行时规则（已由[会话独立迁移](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代）：V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；缺失记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志但不补填对应子 Session，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。扫描中其他任何不支持代际或不可读 header 都会拒绝迁移，因为无法证明它与父 Session 无关。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。存储解码器先将物理 JSON 与压缩错误归类，再由收集器补充子日志信息；文件系统读取与取消保留原始错误。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
+本段的运行时子会话错误处理部分由[逐会话目录准备](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代：打开父会话仍通过读取直属子会话补齐目录，但不可读子会话不再阻断健康父历史。V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；缺失记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志但不补填对应子 Session，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。扫描中其他任何不支持代际或不可读 header 都会拒绝迁移，因为无法证明它与父 Session 无关。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。存储解码器先将物理 JSON 与压缩错误归类，再由收集器补充子日志信息；文件系统读取与取消保留原始错误。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
 
 原始父子迁移测试保留 24 个历史创建时间冲突作为拒绝证据。独立的内存对照只对齐子创建时间，证明恢复保留事件，包括已发布但没有 descriptor 的子 Session。Headless/ACP 与 SDK 快照适配器在规范化之前校验实时父子时钟，并在刷新时保持两者相等；已提交的前代文件保持不变。
 
-原运行时规则（已由[会话独立迁移](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代）：历史格式的公开修订号组合父日志物理修订号与每个所选规范路径及其文件系统修订号的指纹。仅父日志令牌无法标识子日志提供的目录变化；全库指纹让 `stat`/`list` 保持只读元数据，也纳入不可读或不支持的成员，无需新增持久化索引。无关变化也会使历史缓存失效，获取令牌需要扫描根目录。当前格式令牌仍只取决于自身文件。准备缓存保留父日志物理修订号，并独立校验子成员集合与修订。
+历史格式的公开修订号组合父日志物理修订号与每个所选规范路径及其文件系统修订号的指纹。仅父日志令牌无法标识子日志提供的目录变化；全库指纹让 `stat`/`list` 保持只读元数据，也纳入不可读或不支持的成员，无需新增持久化索引。无关变化也会使历史缓存失效，获取令牌需要扫描根目录。当前格式令牌仍只取决于自身文件。准备缓存保留父日志物理修订号，并独立校验子成员集合与修订。
 
-原运行时规则（已由[会话独立迁移](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代）：通用格式接口只传递正在恢复的 artifact。每个父 Session 的 catalog 组装将 V3→V4 声明替换为捕获已收集子 Session 证据的闭包，并复用生成的 codec、迁移与校验清单。每次父 Session 准备只编译一条短迁移链，每次恢复拥有独立的 stage 状态。在组装处绑定证据，使通用恢复选项和 stage 输入不必携带子 Session 证据，同时保留存储对发现与来源重验的所有权。静态 header 和原生当前格式读取不需要子 Session 证据；未绑定的历史正文恢复会拒绝，不会假定子 Session 集合为空。
+通用格式接口只传递正在恢复的 artifact。每个父 Session 的 catalog 组装将 V3→V4 声明替换为捕获已收集子 Session 证据的闭包，并复用生成的 codec、迁移与校验清单。每次父 Session 准备只编译一条短迁移链，每次恢复拥有独立的 stage 状态。在组装处绑定证据，使通用恢复选项和 stage 输入不必携带子 Session 证据，同时保留存储对发现与来源重验的所有权。静态 header 和原生当前格式读取不需要子 Session 证据；未绑定的历史正文恢复会拒绝，不会假定子 Session 集合为空。
 
 <a id="catalog-scan-measurements"></a>
 ### 目录扫描测量
 
 包内[诊断脚本](../../../../packages/session/session-persistence-jsonl/tests/catalog-migration.perf.ts)测量一个原始 V3 父日志、四个各有 1,000 条事件的直属子日志，以及 0/100/1,000 个只有 header 的无关 V3 Session。每个样本在新进程中创建独立临时日志库与 Cordis 上下文，按 stat → 冷读 → 缓存读取 → 写入发布 → 当前格式热读顺序执行，最后释放上下文并删除文件。脚本在普通 Node 下使用已构建的工作区导出；创建夹具不计入测量区间。这些结果是夹具创建后的文件系统缓存热态观察，不代表磁盘冷读延迟，也不是性能门禁。
 
-下表记录会话独立运行时迁移之前，macOS arm64、Node v26.0.0 上主动 catalog 扫描实现的测量。1,000 个无关会话时，中位数为 stat 84.14 ms、冷读 237.97 ms、缓存读 110.98 ms、发布 268.46 ms、同进程当前格式读取 0.41 ms。这些历史测量说明：当准备仍解码子正文时，仅优化元数据访问并不足够；它们不是当前耗时或跨主机阈值。
+以下为 macOS arm64、Node v26.0.0 下各规模的全部三个样本，单位为毫秒。只读打开不发布后继：即使解码结果已缓存，成员扫描仍与日志库规模成正比。1,000 个无关日志时，中位数分别为 stat 84.14 ms、冷读 237.97 ms、缓存读取 110.98 ms、发布 268.46 ms，以及同进程当前格式读取 0.41 ms。这些测量记录成本，不证明性能提升，也不设跨主机阈值。
 
 | 无关 Session | 历史 stat | 冷读 | 缓存读取 | 发布 | 当前格式热读 |
 |---:|---:|---:|---:|---:|---:|
diff --git a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.i18n.yaml
index 5f7de01cfd..59e3f84862 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-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 .agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
-2026-09-01-parent-owned-subagent-catalog.md: 1c65813cd92aebbd2e45acc6b1f121aba442646d
-2026-09-01-parent-owned-subagent-catalog.zh.md: 7eded398ca53997ad80c3910aad333b4a1476286
+2026-09-01-parent-owned-subagent-catalog.md: 536ec33148bd675a974622b98ee23de812691dc0
+2026-09-01-parent-owned-subagent-catalog.zh.md: ec78ff9e4b7d54a7309baf21c383ec5ff83a19c8
diff --git a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
index 1c65813cd9..536ec33148 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
+++ b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md
@@ -44,8 +44,6 @@ Current-writer snapshot expectations include catalog facts even when replay inpu
 
 ## Consequences
 
-Session observations and client snapshots expose durable catalog facts through `projections.values.subagentCatalog`. The change feed publishes complete lists, so D creations can incur O(D²) cumulative view work. Historical children may lack these facts: `listChildren()` supplements one parent observation with header-only discovery and returns unresolved rows without reading child bodies. The Web derives the same missing entries from its existing Session list. This preserves the catalog as the sole durable creation record while accepting O(N) header enumeration for explicit service discovery. [Web projection consumption](../simplification/2026-09-08-web-subagent-catalog-projections.md) owns browser loading and synchronization.
+Session observations and client snapshots expose the direct-child list through `projections.values.subagentCatalog`. The projection change feed publishes a complete list when catalog state changes. Each view costs O(D), so D creations can incur O(D²) cumulative view work; this follows the existing projection mechanism. `listChildren()` reads the parent projection through one live-preferred Session observation; descendant listing uses the Session corpus and child identity projection. [Web projection consumption](../simplification/2026-09-08-web-subagent-catalog-projections.md) owns browser loading and synchronization.
 
 [Creation metadata exclusion](../simplification/2026-09-16-subagent-catalog-membership-only.md) records why model configuration is absent from catalog facts.
-
-The [Session-local migration decision](../bug-fix/2026-09-19-session-local-subagent-migration.md) supersedes runtime child-body collection and unopened-branch projection reads; optional offline completion and durable catalog semantics remain active.
diff --git a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md
index 7eded398ca..ec78ff9e4b 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md
@@ -44,8 +44,6 @@ snapshot normalizer 会把 `childCreatedAt` 归零，因为它来自 process clo
 
 ## 后果
 
-会话观察和客户端快照通过 `projections.values.subagentCatalog` 暴露持久化 catalog 事实。变化流发布完整列表，因此 D 次创建可能累计 O(D²) 视图工作。历史子会话可能缺少这些事实：`listChildren()` 在一次父观察之外补充仅头部发现，返回未解析条目，不读子正文。Web 从已有会话列表派生同类缺失条目。这保留 catalog 作为唯一持久化创建记录，同时接受显式服务发现的 O(N) 头部枚举成本。[Web 投影消费](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md) 负责浏览器加载与同步。
+Session observation 与 client snapshot 通过 `projections.values.subagentCatalog` 暴露直接子级列表。目录状态变化时，projection change feed 发布完整列表。每次 view 的成本为 O(D)，因此 D 次创建可能累计产生 O(D²) 的 view 工作量；这沿用现有 projection 机制。`listChildren()` 通过一次 live-preferred Session observation 读取父 projection；后代枚举使用 Session 语料库与子身份 projection。[Web projection 消费决策](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md) 说明浏览器加载与同步。
 
 [创建元数据排除决策](../simplification/2026-09-16-subagent-catalog-membership-only.zh.md) 说明目录事实为何不包含模型配置。
-
-[会话独立迁移决策](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代运行时子正文收集与未打开分支投影读取；可选离线补全和持久化 catalog 语义仍有效。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
index d304ff6814..7d4ff08c8e 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.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-09-19-session-local-subagent-migration.md
-2026-09-19-session-local-subagent-migration.md: e02d2434b6f778556db454d88776a97ee699709f
-2026-09-19-session-local-subagent-migration.zh.md: 61cb891105c39e9ef9524f1c9df2f257d8938045
+2026-09-19-session-local-subagent-migration.md: ee06345246f69b7a176170105d77e3e9ecca8ac8
+2026-09-19-session-local-subagent-migration.zh.md: 050f64877860dd8f63244a34a8ba9d8d3945189c
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
index e02d2434b6..ee06345246 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
@@ -1,4 +1,4 @@
-# Agent Note: Migrate each Session independently of its children
+# Agent Note: Complete parent catalogs without migrating child catalogs
 
 Status: implemented
 
@@ -6,30 +6,26 @@ English | [中文](2026-09-19-session-local-subagent-migration.zh.md)
 
 ## Problem
 
-Runtime V3→V4 preparation collected every direct child's descriptor to complete the parent catalog. This decoded whole child logs before opening the parent, and unrelated unreadable headers could prevent complete membership classification. A corrupt child therefore blocked valid parent history. Historical revisions also fingerprinted the entire root, invalidating a parent's cached preparation when unrelated files changed.
+Opening a historical parent requires discovery facts from its direct children. A child's corrupt body or invalid descriptor, or an unreadable header elsewhere in the root, could reject the parent's V4 preparation and hide otherwise readable history.
 
 ## Decision
 
-JSONL migrates only the Session explicitly opened by a reader or writer. It preserves existing catalog facts and does not read child bodies or collect cross-session evidence. Read opens prepare current logical events without publishing; write opens validate the selected source and exclusively publish its immutable successor. Public revisions and preparation reuse depend only on the selected file. Predecessor generations remain byte-identical.
+Opening A discovers candidate B Sessions through headers, reads their own descriptors, and completes A's catalog. Historical child reads use the V0–V3 catalog; current child reads use native validation. These reads neither prepare B's own catalog nor publish B's successor. Opening B separately performs B's migration and catalog preparation. Frontend discovery and `list_agents` retain their parent-catalog behavior and existing result types.
 
-Discovery combines parent catalog facts with header relationships. The subagent service returns unresolved direct-child entries when no catalog fact exists; the Web derives them from its existing Session list. Menu and branch refreshes enumerate headers without requesting child projections. Selecting a child opens its own history, validates its direct parent and descriptor, and resolves mode and label. Until then the address grants no continuation authority and the composer stays read-only. A child open failure remains local. Explicit programmatic reads and continuation requests also migrate their selected Session on demand; explicit descendant inspection and bulk migration still read the Sessions they request.
+JSONL omits unreadable or unsupported headers from discovery. A child-body or descriptor-field failure produces a warning with the child path and omits that child's supplemental fact, while preserving healthy siblings and existing parent entries. Cancellation and source-consistency failures still stop the operation. Inspected child revisions, including failed decodes, are rechecked before reuse and publication so repairs cannot silently reuse stale evidence. Released predecessors remain byte-identical.
 
-The catalog remains the durable source of successful creation facts. Unresolved discovery rows are neither persisted events nor projection values. No new Session format or persistent index is needed. Offline fixture preparation and Preview packing may still explicitly supply child evidence for catalog completion; their caller already owns that corpus.
-
-This partially supersedes runtime catalog prerequisites and corpus revisions in [released migrations](../architecture/2026-08-31-released-session-format-migrations.md), the discovery-only assumption in [parent catalogs](../architecture/2026-09-01-parent-owned-subagent-catalog.md), and unopened-branch reads in [Web projection consumption](../simplification/2026-09-08-web-subagent-catalog-projections.md). Their format, creation, ordering, and transport decisions remain active. [Incomplete evidence](2026-09-19-v3-incomplete-child-catalog-evidence.md) continues to govern optional offline completion.
+This partially supersedes child-failure propagation in [released migrations](../architecture/2026-08-31-released-session-format-migrations.md) and [incomplete child evidence](2026-09-19-v3-incomplete-child-catalog-evidence.md). Their format conversion, descriptor cardinality, conflict validation, and immutable publication rules remain active.
 
 ## Alternatives considered
 
-**Catch child failures and continue backfill.** This still decodes every healthy child, hides failures, and permanently omits discovery facts when the parent successor is published.
+**Skip catalog completion and discover children in each consumer.** This introduces incomplete tool results and additional UI states despite the parent's readable child descriptors. The parent catalog already serves these consumers.
 
-**Supply an empty child set without changing discovery.** This removes migration coupling but makes historical children disappear from catalog-only consumers.
+**Recursively prepare child catalogs.** A only needs B's own descriptor. Preparing B's descendants adds unrelated work and failure dependencies.
 
-**Persist placeholder catalog events or another child index.** Unknown mode and label are not successful creation facts. A second persistent index adds write coordination and repair without improving header-based navigation.
+**Refuse A when one child cannot be read.** The child's discovery metadata does not justify withholding the parent's healthy history. Warnings retain the child location without inventing mode or label fields.
 
 ## Consequences
 
-Explicit direct-child discovery now enumerates N headers in addition to materializing D catalog facts. It avoids all child-body decoding, while ordinary parent migration has no corpus-dependent preparation. Historical rows may initially show an id instead of a label and cannot promise resumability. Headers that cannot be decoded cannot contribute a navigation row, but do not block opening another known Session.
+Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. A failed child's missing catalog entry is not automatically repaired after parent publication; the child remains addressable by id, as with other incomplete historical descriptor evidence.
 
-The V2 parent/child regression needs two independently stored historical roles to exercise deferred migration and unchanged predecessors. Its additional child raises the retained corpus budget from ten to eleven roles; the gate still rejects a twelfth role.
-
-Raw and compressed persistence regressions cover V0–V3, child corruption and future formats, independent publication, unchanged predecessors, and stable parent revisions across child mutations. Service tests verify only the parent is observed. Client and Host tests verify unresolved addresses, selected-child decoding, mode resolution, and ownership rejection. The shipped Web preset-migration snapshot round-trips parent and child generations with a corrupt sibling and checks that only explicitly opened Sessions migrate.
+Raw and compressed tests cover catalog completion, child-local errors, source changes and repairs, unchanged child generations, and deferred child-catalog preparation. The shipped Web migration snapshot checks the parent catalog with a corrupt sibling, then opens the child independently. Its additional historical child raises the corpus budget from ten to eleven roles; the guard rejects a twelfth role.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
index 61cb891105..050f648778 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 独立于子会话迁移每个会话
+# Agent Note：补齐父目录而不迁移子目录
 
 Status: implemented
 
@@ -6,30 +6,26 @@ Status: implemented
 
 ## 问题
 
-运行时 V3→V4 准备收集每个直接子会话的 descriptor 以补全父 catalog。这在打开父会话之前解码完整子日志，而无关的不可读头部也可能阻止完整成员分类。因此，一个损坏子会话就会阻断有效父历史。历史版本标识还对整个根目录取指纹，无关文件变化也使父缓存准备失效。
+打开历史父会话需要直属子会话的发现事实。子日志正文损坏、descriptor 无效，或根目录其他位置的 header 不可读，都可能拒绝父会话的 V4 准备，使原本可读的历史无法打开。
 
 ## 决策
 
-JSONL 只迁移读写方显式打开的会话。它保留已有 catalog 事实，不读取子正文或收集跨会话证据。读 open 准备当前逻辑事件但不发布；写 open 校验所选源并独占发布不可变后继。公开版本标识和准备复用只依赖所选文件。前代文件字节保持不变。
+打开 A 时通过 header 发现候选 B Session，读取其自身 descriptor，并补齐 A 的 catalog。历史子日志使用 V0–V3 catalog 读取，当前子日志使用原生校验。这些读取不准备 B 自己的 catalog，也不发布 B 的后继。单独打开 B 时才执行 B 的迁移与目录准备。前端发现和 `list_agents` 保留读取父 catalog 的行为及现有结果类型。
 
-发现机制合并父 catalog 事实与头部关系。没有 catalog 事实时，子代理服务返回未解析直接子条目；Web 从已有会话列表派生这些条目。菜单和分支刷新枚举头部，不请求子投影。选择子会话时打开自身历史，校验直接父归属和 descriptor，并解析模式与标签。此前地址不授予续接权限，输入区保持只读。子打开失败仅影响自身。显式程序读取和续接请求同样按需迁移选中会话；显式后代检查和批量迁移仍读取它们所请求的会话。
+JSONL 在发现时跳过不可读或不支持的 header。子正文或 descriptor 字段失败会产生带子路径的警告，并跳过该子的补充事实，同时保留健康兄弟项和已有父目录项。取消与来源一致性失败仍中止操作。复用和发布前会重新检查已检查子日志的修订，包括解码失败的日志，使修复不能静默复用旧证据。已发布前驱保持逐字节不变。
 
-Catalog 仍是成功创建事实的持久化来源。未解析发现行既不是持久化事件，也不是投影值。无需新会话格式或持久化索引。离线夹具准备和 Preview 打包仍可显式提供子证据来补全 catalog，因为调用者已拥有该语料库。
-
-本决策部分取代[已发布迁移](../architecture/2026-08-31-released-session-format-migrations.zh.md)中的运行时 catalog 前提与全库版本标识、[父 catalog](../architecture/2026-09-01-parent-owned-subagent-catalog.zh.md)中的仅靠 catalog 发现假设，以及 [Web 投影消费](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md)中的未打开分支读取。它们的格式、创建、排序和传输决策仍有效。[不完整证据](2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)继续约束可选离线补全。
+本决策部分取代[已发布迁移](../architecture/2026-08-31-released-session-format-migrations.zh.md)和[不完整子证据](2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)中的子错误传播规则。其格式转换、descriptor 数量、冲突校验和不可变发布规则仍有效。
 
 ## 考虑过的替代方案
 
-**捕获子错误并继续回填。** 这仍解码所有健康子会话、隐藏失败，并在父后继发布时永久省略发现事实。
+**跳过目录补齐，让每个消费者发现子项。** 父会话明明有可读的子 descriptor，却会因此产生不完整工具结果和额外 UI 状态。父 catalog 已经服务这些消费者。
 
-**传入空子集合而不改发现机制。** 这消除了迁移耦合，却让历史子会话从仅消费 catalog 的调用方消失。
+**递归准备子目录。** A 只需要 B 自身的 descriptor。准备 B 的后代会增加无关工作与失败依赖。
 
-**持久化占位 catalog 事件或另建子索引。** 未知模式和标签不是成功创建事实。第二份持久化索引增加写协调和修复工作，并不能改善基于头部的导航。
+**一个子会话不可读就拒绝 A。** 子会话的发现元数据不足以成为阻断健康父历史的理由。警告保留子位置，不虚构 mode 或 label 字段。
 
-## 影响
+## 后果
 
-显式直接子发现除物化 D 条 catalog 事实外，还枚举 N 个头部。它避免所有子正文解码，而普通父迁移没有依赖全库的准备工作。历史行最初可能显示 id 而非标签，且不能承诺可续接。无法解码的头部不能贡献导航行，但不会阻止打开另一个已知会话。
+首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。父发布后不会自动修复失败子项缺失的目录记录；该子会话仍可按 id 寻址，与其他不完整历史 descriptor 证据一致。
 
-V2 父子会话回归需要两个独立存储的历史角色，以验证延迟迁移和前代文件保持不变。新增子会话将保留语料预算从十个角色增至十一个；门禁仍拒绝第十二个角色。
-
-原始与压缩持久化回归覆盖 V0–V3、子损坏与未来格式、独立发布、前代不变，以及子变化期间父版本标识稳定。服务测试确认只观察父会话。Client 和 Host 测试验证未解析地址、选中子解码、模式解析与归属拒绝。正式 Web preset-migration 快照在损坏兄弟会话存在时往返父子代次，并检查只有显式打开的会话才迁移。
+原始和压缩测试覆盖目录补齐、子会话错误隔离、来源变化与修复、子代际不变和延后的子目录准备。随产品 Web 迁移快照在损坏兄弟存在时检查父目录，再独立打开子会话。额外的历史子角色使语料预算由十个增加到十一个；守卫拒绝第十二个角色。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
index 2d37c0209c..00bf6ce0fd 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.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-09-19-v3-incomplete-child-catalog-evidence.md
-2026-09-19-v3-incomplete-child-catalog-evidence.md: d9cab54d0d381667e840d666a48608298464441e
-2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: 248cc0cc7f899837f06e2cc082b174e87d125262
+2026-09-19-v3-incomplete-child-catalog-evidence.md: 30aac77c231b34f04daaa8095f19fbba17c02ed8
+2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: f4f8ee9870e697f675c838284401f5dd943a389e
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
index d9cab54d0d..30aac77c23 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
@@ -10,9 +10,9 @@ A valid V3 child log can have no own descriptor, an unsupported descriptor versi
 
 ## Decision
 
-Optional V3→V4 catalog completion for offline fixture preparation and Preview packing appends a missing parent entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions contribute no new fact; existing parent entries and child events remain intact. Runtime JSONL migration does not collect this evidence and restores each Session independently, as specified in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
+The V3→V4 migration appends a missing parent catalog entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions contribute no new catalog fact. Existing parent entries and child events remain intact. This replaces only the missing-evidence refusal in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
 
-Supplied child creation times must match existing parent entries. Mode, label, and descriptor fields are checked only for exactly one supported own descriptor. These evidence checks belong to explicit offline completion; child corruption or unsupported generations never prevent runtime parent migration.
+The JSONL failure-propagation rules below are partially superseded by [session-local catalog preparation](2026-09-19-session-local-subagent-migration.md); the converter still validates supplied facts and conflicts. Known child creation times must still match existing parent entries. Mode/label and descriptor fields are checked only for exactly one supported own descriptor. Invalid fields in that descriptor, corrupt logs, unreadable membership, unsupported selected generations, and changed source revisions retain their existing failures.
 
 ## Alternatives considered
 
@@ -24,8 +24,6 @@ Supplied child creation times must match existing parent entries. Mode, label, a
 
 ## Consequences
 
-A historical child without a usable descriptor remains discoverable from a readable parent-linked header even when no parent catalog entry exists. Runtime migration preserves that absence rather than inventing a fact. The child’s own open performs decoding and reports any failure locally; publishing a parent successor never requires successful child decoding.
+A historical child without a usable descriptor remains readable by id but may be absent from its parent's direct-child catalog. Existing catalog entries remain visible. Once a V4 successor is published, opening it does not rescan historical children; automatic later catalog repair is outside this migration. Preparation still rechecks child revisions before publication, so newly available evidence cannot silently bypass source consistency checks.
 
-Pure completion and Preview tests retain unavailable-evidence, existing-entry, and conflict coverage. JSONL read/write regressions cover independent parent and child opens, stable parent revisions across child changes, and unchanged predecessor bytes.
-
-The [Session-local migration decision](./2026-09-19-session-local-subagent-migration.md) supersedes runtime child-body collection and unopened-branch projection reads; optional offline completion and durable catalog semantics remain active.
+Unit, JSONL read/write, and Preview packing tests cover unavailable evidence, unchanged source bytes, retained entries, identity conflicts, and evidence changes before publication.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
index 248cc0cc7f..f4f8ee9870 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## Decision
 
-离线夹具准备和 Preview 打包中的可选 V3→V4 catalog 补全，仅在恰好一个受支持的自身子 descriptor 提供发现字段时追加缺失父条目。其他 descriptor 数量或不支持的版本不贡献新事实，已有父条目和子事件保持完整。运行时 JSONL 迁移不收集这些证据，并按[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)独立恢复各会话。
+V3→V4 迁移只在恰好一个受支持的自身子 descriptor 提供发现字段时，追加缺失的父目录项。其他 descriptor 数量及不受支持的版本不贡献新的目录事实。已有父目录项和子事件保持完整。这只替代[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)中的证据缺失拒绝规则。
 
-传入子创建时间必须匹配已有父条目。只有恰好一个受支持自身 descriptor 时才检查模式、标签和 descriptor 字段。这些证据检查属于显式离线补全；子会话损坏或不支持的代次不会阻止运行时父会话迁移。
+下述 JSONL 错误传播规则部分由[逐会话目录准备](2026-09-19-session-local-subagent-migration.zh.md)取代；转换器仍校验提供的事实及冲突。已知子创建时间仍必须与已有父目录项一致。只有恰好一个受支持的自身 descriptor 时，才校验其字段并比较 mode／label。该 descriptor 字段无效、日志损坏、成员关系不可读、所选代际不受支持以及源修订变化仍保留原有失败行为。
 
 ## Alternatives considered
 
@@ -24,8 +24,6 @@ Status: implemented
 
 ## Consequences
 
-即使没有父 catalog 条目，缺少可用 descriptor 的历史子会话仍可通过可读且关联父会话的头部被发现。运行时迁移保留该缺失状态，不虚构事实。子会话自身 open 执行解码并局部报告失败；发布父后继从不要求子解码成功。
+没有可用 descriptor 的历史子 Session 仍可按 id 读取，但可能不出现在其父级的直属子目录中。已有目录项仍可见。V4 后继发布后，打开它不会重新扫描历史子日志；后续自动修复目录不属于本迁移。准备过程仍会在发布前复查子修订，因此新出现的证据无法悄悄绕过源一致性检查。
 
-纯补全与 Preview 测试保留不可用证据、已有条目和冲突覆盖。JSONL 读写回归覆盖父子独立打开、子变化期间父版本标识稳定，以及前代字节不变。
-
-[会话独立迁移决策](./2026-09-19-session-local-subagent-migration.zh.md)取代运行时子正文收集与未打开分支投影读取；可选离线补全和持久化 catalog 语义仍有效。
+单元、JSONL 读写和 Preview 打包测试覆盖不可用证据、源字节不变、条目保留、身份冲突以及发布前的证据变化。
diff --git a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.i18n.yaml
index f05b4787c1..d589324465 100644
--- a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.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-09-08-web-subagent-catalog-projections.md
-2026-09-08-web-subagent-catalog-projections.md: f714418a8641b76228cf8723657205fbfda22133
-2026-09-08-web-subagent-catalog-projections.zh.md: c23b29f47795a6b8113d5be5f7a57c4713e203d9
+2026-09-08-web-subagent-catalog-projections.md: 766d33e581bcac53844b0836f23cda615858fc27
+2026-09-08-web-subagent-catalog-projections.zh.md: ef14db2530ed10a7aa34408c5a6fada6f0a28858
diff --git a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md
index f714418a86..766d33e581 100644
--- a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md
+++ b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.md
@@ -10,9 +10,9 @@ The parent catalog projection already publishes complete membership through the
 
 ## Decision
 
-The Client retains catalog membership only in its standard per-Session projection store. Initial `session.projections` reads return a complete projection baseline from one live-preferred Session observation. The endpoint accepts any Session id and has no catalog-specific dependency or validation. The same observation supplies the values and sequence cursor. Initial baselines and live control frames use the store's existing sequence ordering, so an older response cannot replace a newer value. The endpoint does not activate an Agent or sample child activity. Opening a conversation uses its follow baseline without scheduling a second projection read; unopened branches use header relationships from the Session list instead of requesting child projections. Missing historical catalog entries remain non-durable unresolved navigation rows until the child is opened.
+The Client retains catalog membership only in its standard per-Session projection store. Initial `session.projections` reads return a complete projection baseline from one live-preferred Session observation. The endpoint accepts any Session id and has no catalog-specific dependency or validation. The same observation supplies the values and sequence cursor. Initial baselines and live control frames use the store's existing sequence ordering, so an older response cannot replace a newer value. The endpoint does not activate an Agent or sample child activity. Opening a conversation uses its follow baseline without scheduling a second projection read; unopened catalog branches still use explicit reads.
 
-Feature consumers select `subagentCatalog` from `projectionsBySession`, supplement missing rows from parent-linked subagent summaries, and derive activity from Session-list baselines and status events. Header-discovered rows carry unresolved mode and grant no continuation authority. Menu and branch refreshes update only the lightweight Session list. Opening the selected child validates its descriptor and parent and resolves the mode; a failed open stays local to that child. Existing projection ordering, generic explicit projection reads, and independent parent availability remain unchanged.
+Feature consumers select `subagentCatalog` from `projectionsBySession` and derive row activity from Session-list baselines and status events. Session summaries report Agent availability separately; Agent creation and disposal republish the existing summary event. Completed subagents retain their summaries and display projections after removal. Generic projection reads own loading and error state; parent availability comes from the Session list independently of membership. Opening a loaded catalog reuses its data; an initial failure can be retried. Reconnect cancels previous reads and starts fresh reads for requested catalogs. Session removal cancels its pending read and marks parent availability false; projection responses cannot change Agent availability.
 
 The [parent-catalog decision](../architecture/2026-09-01-parent-owned-subagent-catalog.md) owns durable creation facts and ordering. This decision supersedes the dedicated membership-refresh mechanism in [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md); that note remains active for navigation, control, and presentation decisions.
 
@@ -29,5 +29,3 @@ Host summaries replace running and availability state; local create/fork placeho
 Membership changes use the existing control stream without extra catalog notifications or reads. Whole-value projection publication still costs O(D) for D children; this change does not introduce delta transport. Initial reads return the observation's complete projection baseline, including values beyond the catalog, so they reuse standard baseline semantics at the cost of that additional initial payload. Session sequence ordering does not establish identity across reused Session ids.
 
 Manager tests cover pushed membership, stale initial responses, lazy loading, status composition, retained completion metadata, retry, removal of empty catalogs, late create/fork responses, and reconnect cancellation. Host tests exercise the shared control stream and cold observations. The persisted-subagent Web scenario covers nested historical navigation and continuation through the shipped application.
-
-The [Session-local migration decision](../bug-fix/2026-09-19-session-local-subagent-migration.md) supersedes runtime child-body collection and unopened-branch projection reads; optional offline completion and durable catalog semantics remain active.
diff --git a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md
index c23b29f477..ef14db2530 100644
--- a/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md
+++ b/.agents/notes/implemented/simplification/2026-09-08-web-subagent-catalog-projections.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-Client 仅在标准每会话投影存储中保留 catalog 事实。显式 `session.projections` 读取从一次优先存活来源的会话观察返回完整基线；端点接受任意会话 id，不依赖 catalog 专用校验。观察同时提供数值和序列游标；初始基线与实时控制帧遵循已有序列排序，旧响应不能覆盖新值。端点不激活 Agent 或采样子活动。打开对话使用 follow 基线，不另行请求投影。未打开分支使用会话列表的头部关系，不请求子投影；缺失的历史 catalog 条目保持为非持久化、未解析的导航行，直到打开子会话。
+Client 仅在标准逐 Session projection store 中保留目录成员关系。初始 `session.projections` 读取通过一次 live-preferred Session observation 返回完整 projection 基线。endpoint 接受任意 Session id，不含目录专用依赖或校验。值与序号游标来自同一次 observation。初始基线与实时 control 帧使用 store 既有的序号排序，因此旧响应不能替换新值。该 endpoint 不激活 Agent，也不采样子代理活动状态。打开会话时使用其 follow baseline，不再额外调度一次投影读取；未打开的目录分支仍使用显式读取。
 
-功能消费者从 `projectionsBySession` 选择 `subagentCatalog`，用关联父会话的子代理摘要补充缺失行，并从会话列表基线和状态事件派生活动。头部发现的条目携带未解析模式，不授予续接权限。菜单与分支刷新只更新轻量会话列表。打开选中的子会话时校验 descriptor 和父归属并解析模式，失败仅影响该子会话。已有投影排序、通用显式投影读取和独立父可用性保持不变。
+功能消费者从 `projectionsBySession` 中选择 `subagentCatalog`，并从 Session 列表基线与状态事件派生行活动状态。Session 摘要单独报告 Agent 可用性；Agent 创建与销毁重新发布已有摘要事件。完成的子代理在移除后保留摘要与展示 projection。通用 projection 读取拥有加载与错误状态；父 Agent 可用性来自 Session 列表，独立于成员关系。打开已加载目录会复用数据，初始失败可以重试。重连取消此前的读取，并为已请求的目录重新读取。Session 移除会取消其待完成读取并将父 Agent 可用性标为 false；projection 响应不能改变 Agent 可用性。
 
 [父目录决策](../architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明持久创建事实与顺序。本决策取代 [Web 子代理会话](../feature/2026-07-27-web-subagent-conversations.zh.md) 中的专用成员刷新机制；该记录继续保留导航、控制与展示决策。
 
@@ -29,5 +29,3 @@ Host 摘要替换运行状态与可用性；本地 create/fork 占位摘要只
 成员变化使用既有 control stream，无需额外目录通知或读取。对 D 个子级发布完整 projection 值仍需 O(D)；本变更不引入增量传输。初始读取返回 observation 的完整 projection 基线，其中包括目录以外的值，以额外初始载荷换取标准基线语义的复用。Session 序号排序不确立复用 Session id 之间的身份关系。
 
 Manager 测试覆盖成员推送、过时初始响应、按需加载、状态组合、完成元数据保留、重试、空目录移除、晚到的 create/fork 响应与重连取消。Host 测试覆盖共享 control stream 与冷 observation。持久化子代理 Web 场景通过发布应用验证嵌套历史导航与续传。
-
-[会话独立迁移决策](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代运行时子正文收集与未打开分支投影读取；可选离线补全和持久化 catalog 语义仍有效。
diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts
index 0874c1da15..16df0a6b84 100644
--- a/apps/web/tests/preset-migration.snapshot.ts
+++ b/apps/web/tests/preset-migration.snapshot.ts
@@ -70,11 +70,14 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
       expect(resolved.agent.session.snapshotEvents()
         .filter(event => event.type === 'agent-preset/selected')
         .map(event => event.data.agentPreset)).toEqual(withSelections ? ['ptc', 'standard', 'ptc'] : [])
+      expect(await scaffold.ctx.subagents.listChildren(id)).toEqual([
+        { id: childId, createdAt: childFixture[0]?.['createdAt'], mode: 'one-shot', label: 'historical child' },
+      ])
 
       const childSuccessor = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, childId, SESSION_FORMAT_VERSION, 'zstd')
       await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' })
       const signal = new AbortController().signal
-      const address = { kind: 'subagent', parentSessionId: id, childSessionId: childId, mode: 'unresolved' } as const
+      const address = { kind: 'subagent', parentSessionId: id, childSessionId: childId, mode: 'one-shot' } as const
       const childPage = await scaffold.ctx.sessionController.page({ address, throughSeq: childRows.length - 1 }, signal)
       expect(childPage.records.map(record => record.event.type)).toEqual(childRows.map(row => row['type']))
       await expect(scaffold.ctx.sessionController.page({ address: { ...address, childSessionId: brokenId }, throughSeq: 1 }, signal))
@@ -104,11 +107,14 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
           && (row['data'] as { agentPreset: string }).agentPreset === 'code'
           ? { ...row, data: { agentPreset: 'ptc' } }
           : row),
+        { type: 'subagent/catalog', seq: rows.length, time: rows.at(-1)?.['time'], data: {
+          version: 0, childId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'one-shot', label: 'historical child',
+        } },
         // Agent activation closes its restored prefix with a fresh seed marker.
-        { type: 'session/end-seed', seq: rows.length, time: 0, data: {} },
-        { type: 'permission/preset', seq: rows.length + 1, time: 0, data: { preset: 'workspace-write' } },
-        { type: 'sandbox/mode', seq: rows.length + 2, time: 0, data: { mode: 'workspace-write' } },
-        { type: 'approval/policy', seq: rows.length + 3, time: 0, data: { policy: 'ask' } },
+        { type: 'session/end-seed', seq: rows.length + 1, time: 0, data: {} },
+        { type: 'permission/preset', seq: rows.length + 2, time: 0, data: { preset: 'workspace-write' } },
+        { type: 'sandbox/mode', seq: rows.length + 3, time: 0, data: { mode: 'workspace-write' } },
+        { type: 'approval/policy', seq: rows.length + 4, time: 0, data: { policy: 'ask' } },
       ].map(row => JSON.stringify(row)).join('\n') + '\n'
       const context = { sessionIds: [id], cwd: scaffold.workspaceCwd }
       expect(normalizeSessionSnapshots([published], context)).toEqual(normalizeSessionSnapshots([expected], context))
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 1c125b1c20..106e1545fb 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: cd42163bec21d0c2110b4be56a9d93bacf50329d
-config-catalog.zh.md: 3bc3bb9d501e8bbdf500664fe74b9c06345e7254
+config-catalog.md: dad6b57ae0712e04ad16729b4067c541f83c68d6
+config-catalog.zh.md: 4ba0378810f3db4797c0d41fa5230f7069438b3f
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index cd42163bec..dad6b57ae0 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2208,7 +2208,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session/session-persistence-jsonl/src/index.ts:88`](../packages/session/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session/session-persistence-jsonl/src/index.ts:90`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 3bc3bb9d50..4ba0378810 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -2210,7 +2210,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-来源：[`packages/session/session-persistence-jsonl/src/index.ts:88`](../packages/session/session-persistence-jsonl/src/index.ts)
+来源：[`packages/session/session-persistence-jsonl/src/index.ts:90`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 <a id="deepseek-aidsh-session-projection-cache"></a>
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index ae1d614ac8..034d835426 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: dc3ebd74d2f6674f3f81c1a77e36cceeaf0664ab
-subagent.zh.md: 03ada2686dd9a55f0ebaa3dc7e8cf5c1ac9c1db1
+subagent.md: d642fe1658926b17cb29f280803f12e61228be60
+subagent.zh.md: ff153c7861b4ac46bb058efd00a2f5a50181b6f2
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index dc3ebd74d2..d642fe1658 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -268,7 +268,7 @@ A local one-shot provider appends the descriptor inside the child's initial turn
 
 The model-facing `list_agents` adapter reports current activity as `running` or `inactive`. These values do not describe task completion or guarantee that `send_message` will succeed.
 
-`SubagentRuntime.listChildren(parentSessionId, signal?)` owns one parent observation and supplements its catalog with Session-header discovery. It returns `SubagentDiscoveryEntry[]`: catalog facts in event order, followed by `{ id: SessionId; createdAt: number; mode: 'unresolved' }` rows for children without a catalog fact. It never opens child bodies. Query failures propagate; a missing parent catalog projection fails explicitly. `listDescendants()` explicitly reads child identities and returns diagnostics and complete `hasChildren` information. [Session-local migration](../../.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md) owns lazy discovery and migration isolation.
+`SubagentRuntime.listChildren(parentSessionId, signal?)` reads the parent's `subagentCatalog` view through a live-preferred Session observation and releases that observation on success or failure. It returns direct-child entries in parent event order without reading child logs or enumerating the Session corpus. Query failures propagate; a missing catalog projection fails explicitly. Browser rows derive membership from the shared projection store and add activity from Session status; the control stream pushes complete catalog updates. `listDescendants()` retains corpus traversal, child-identity diagnostics, and complete `hasChildren` computation. [The parent-catalog Agent Note](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns creation, fork isolation, ordering, and persistence costs.
 
 `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:
 
@@ -465,7 +465,7 @@ The spawn and fork backends create an ordinary one-shot agent through `parent.ct
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
 - **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/runtime-diagnostics/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
 
-`SubagentCatalogEntry` describes a durable successful-creation fact; `SubagentCatalogState` is its host projection state. `SubagentDiscoveryEntry` adds non-durable unresolved header rows for direct listing. Browser consumers combine catalog facts with parent-linked summaries and cached child identities. `SubagentAddress` carries parent and child ids with known or unresolved mode; history opening validates the child descriptor before continuation. `SubagentCatalogRow` belongs to complete-descendant listing.
+`SubagentCatalogEntry` describes one successful direct-child creation fact; `SubagentCatalogState` is the host-only projection state. `listChildren()` owns a live-preferred parent observation without opening child logs. Browser consumers read `subagentCatalog` through the shared Session projection store and combine membership with Session-list activity. `SubagentCatalogRow` belongs to complete-descendant listing. [The parent-catalog decision](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns the persistent facts and read semantics.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -574,15 +574,15 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>
 
 /**
- * Read the parent's catalog and discover missing direct children from Session headers.
+ * Read the parent's durable direct-child catalog without loading or resuming an Agent.
  * The service owns and releases the live-preferred Session observation.
  * @param parentSessionId - parent whose direct children are requested.
  * @param signal - cancellation forwarded to the Session query.
- * @returns catalog children in event order, then unresolved children whose bodies remain unread.
+ * @returns catalog children in parent event order.
  * @throws {@link SubagentError} when query or catalog projection is unavailable.
  * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
  */
-listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>
 
 /**
  * Enumerate the root's complete session-backed subagent tree in stable
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 03ada2686d..ff153c7861 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -268,7 +268,7 @@ interface ContinuableCreateSpec {
 
 模型侧的 `list_agents` 适配器将当前活动表示为 `running` 或 `inactive`。这些值不描述任务完成情况，也不保证 `send_message` 会成功。
 
-`SubagentRuntime.listChildren(parentSessionId, signal?)` 持有一次父观察，并以会话头部发现补充 catalog。它返回 `SubagentDiscoveryEntry[]`：先按事件顺序返回 catalog 事实，再为缺少 catalog 事实的子会话返回 `{ id: SessionId; createdAt: number; mode: 'unresolved' }` 行。不打开任何子正文。查询失败向上传播，缺少父 catalog 投影时显式报错。`listDescendants()` 显式读取子身份，返回诊断和完整 `hasChildren` 信息。[会话独立迁移](../../.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md) 负责按需发现与迁移隔离。
+`SubagentRuntime.listChildren(parentSessionId, signal?)` 通过优先使用在线 Session 的观察读取父会话的 `subagentCatalog` 视图，并在成功或失败时释放观察。它按父会话事件顺序返回直接子级条目，不读取子级日志，也不枚举 Session 语料库。查询失败直接传播；缺少目录投影时显式失败。浏览器条目从共享 projection store 派生成员关系，并从 Session 状态补充活动状态；control stream 推送完整目录更新。`listDescendants()` 保留语料库遍历、子级身份诊断和完整的 `hasChildren` 计算。[父目录 Agent Note](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明创建、fork 隔离、排序和持久化成本。
 
 `SubagentRuntime.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -469,7 +469,7 @@ spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
 - **Fork 种子注入**使用 [`CreateAgentOptions.seed`](core.zh.md#creation-and-ownership)（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/runtime-diagnostics/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
 
-`SubagentCatalogEntry` 描述持久化成功创建事实，`SubagentCatalogState` 是其 Host 投影状态。`SubagentDiscoveryEntry` 为直接列表增加非持久化、未解析的头部行。浏览器消费者合并 catalog 事实、关联父会话的摘要与缓存子身份。`SubagentAddress` 携带父子 id 及已知或未解析模式；历史打开在续接前校验子会话 descriptor。`SubagentCatalogRow` 属于完整后代列表。
+`SubagentCatalogEntry` 描述一条成功创建直接子级的事实；`SubagentCatalogState` 是仅 host 使用的 projection state。`listChildren()` 拥有一次 live-preferred 父 Session observation，不打开子级日志。浏览器消费者通过共享 Session projection store 读取 `subagentCatalog`，并将成员关系与 Session 列表活动状态组合。`SubagentCatalogRow` 属于完整后代列表。[父目录决策](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 规定持久事实与读取语义。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -578,15 +578,15 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>
 
 /**
- * Read the parent's catalog and discover missing direct children from Session headers.
+ * Read the parent's durable direct-child catalog without loading or resuming an Agent.
  * The service owns and releases the live-preferred Session observation.
  * @param parentSessionId - parent whose direct children are requested.
  * @param signal - cancellation forwarded to the Session query.
- * @returns catalog children in event order, then unresolved children whose bodies remain unread.
+ * @returns catalog children in parent event order.
  * @throws {@link SubagentError} when query or catalog projection is unavailable.
  * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
  */
-listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>
 
 /**
  * Enumerate the root's complete session-backed subagent tree in stable
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index dff680a206..04a2230cee 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-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/tool-catalog.md
-tool-catalog.md: 03e2813a528ed1415f9e89593ce4dc8fa884b7e5
-tool-catalog.zh.md: d66c7677a0452fac8557596cd2c666136c0630b1
+tool-catalog.md: 2f5746fc63e73b1caf2692a05ff942c13399e6bc
+tool-catalog.zh.md: 6fb80b689ca569834e8f585c765547d23cec50df
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 03e2813a52..2f5746fc63 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -1886,7 +1886,7 @@ Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/sub
 
 ### `list_agents`
 
-List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.
+List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.
 
 ```json
 {
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index d66c7677a0..6fb80b689c 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -1892,7 +1892,7 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
 
 ### `list_agents`
 
-按持久 id 和标签列出你的可继续后台 subagent。用它回忆你启动过哪些 subagent，而不是轮询完成情况——subagent 完成时你会被告知。状态来自实时注册表：running 表示 agent 此刻正在工作；inactive 表示没有轮次在执行，包括已加载和需要恢复的 child。inactive 不表示任务完成、成功、失败或等待其他 agent。`send_message` 会在运行中 child 的最近 step 边界 steer 消息，或为 inactive child 启动或恢复轮次，且无论处于哪种状态，直接子级都仍可作为 `send_message` 的目标。该快照并非投递承诺；`send_message` 会执行权威检查，仍可能失败。无法在未打开时确定身份的子级会作为诊断信息报告。`descendants` 作用域会按稳定的前序顺序遍历你下方的整棵树，并为每个条目标注其持久的直接父会话 id 和深度。只有深度为 1 的条目可以使用 `send_message`；更深的条目只能作为 `interrupt_agent` 的候选目标。
+按持久 id 和标签列出你的可继续后台 subagent。用它回忆你启动过哪些 subagent，而不是轮询完成情况——subagent 完成时你会被告知。状态来自实时注册表：running 表示 agent 此刻正在工作；inactive 表示没有轮次在执行，包括已加载和需要恢复的 child。inactive 不表示任务完成、成功、失败或等待其他 agent。`send_message` 会在运行中 child 的最近 step 边界 steer 消息，或为 inactive child 启动或恢复轮次，且无论处于哪种状态，直接子级都仍可作为 `send_message` 的目标。该快照并非投递承诺；`send_message` 会执行权威检查，仍可能失败。无法读取的子级仅在 `descendants` 作用域中作为诊断信息报告。`descendants` 作用域会按稳定的前序顺序遍历你下方的整棵树，并为每个条目标注其持久的直接父会话 id 和深度。只有深度为 1 的条目可以使用 `send_message`；更深的条目只能作为 `interrupt_agent` 的候选目标。
 
 ```json
 {
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index 14f1594ee4..d04576c269 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: 9a39b9a4cc859edac0f1023f16c60efe4b4f0b35
-README.zh.md: d0201c4693e303b068e660bd41a86638a572263f
+README.md: a0e18910d14f879171a1415476a7e05a0d261a8a
+README.zh.md: 58466e387fd604137a2358e8b9a7de3320691034
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index 9a39b9a4cc..a0e18910d1 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -29,7 +29,7 @@ History pages and follow opening snapshots carry one `{ type: 'event', event: Se
 
 The Client journal validates current Session event envelopes before publishing follow snapshots, live entries, or history pages. It reuses the browser-safe Session validators for required surface markers, exact replacement endpoints, earlier unique source seqs, embedded Assistant provider metadata, request-header omissions, and tool-error consistency. Invalid records fail without field stripping or normalization; range membership and source existence remain durable-log checks on the Host.
 
-Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` reads one complete baseline through a live-preferred Session observation without activating an Agent. It returns null for a missing Session and serves any registered projection keys. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Initial reads and live projection frames use the same sequence ordering. Header-discovered subagent history accepts `mode: 'unresolved'`; opening still validates the exact parent and the child’s own descriptor. The Client derives the usable mode from the opened child projection, and a failed child open does not invalidate its parent.
+Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the file-type association, including HTML and SVG. Both operations require the composed filesystem to map the requested Host path to the same canonical process path; unmapped remote paths are refused before a native command runs. `session.projections` reads one complete baseline through a live-preferred Session observation without activating an Agent. It returns null for a missing Session and serves any registered projection keys. The Client exposes shared values and explicit-read state through `projectionsBySession`; domains select their own keys. Session-list summaries carry `agentAvailable`, updated through existing summary and status events independently of durable projections. Initial reads and live projection frames use the same sequence ordering.
 
 Client list rows and resident Sessions use the current `sessionListMetadata` projection to reject stale blank-session hints; recency is the later of the summary timestamp and the projected last user prompt. When SessionManager creates an instance before its list row arrives, it reconciles blankness with metadata already retained for that Session. An opened conversation is therefore not reused by New Session even when an older list response still marks it blank.
 
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index d0201c4693..58466e387f 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 Client journal 在发布 follow 快照、live entry 或历史页之前验证当前 Session 事件 envelope。它复用浏览器安全的 Session validator，检查必需的 surface marker、精确的 replacement endpoint、更早且唯一的 source seq、内嵌 Assistant 提供方元数据、request header 可选字段的省略规则以及工具错误一致性。无效 record 直接失败，不删除字段或归一化；范围成员与来源存在性仍由 Host 的持久日志检查。
 
-每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 通过一次 live-preferred Session observation 读取完整基线，不激活 Agent。Session 不存在时返回 null，并可提供任意已注册的 projection key。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。初始读取与实时 projection 帧使用相同的序号排序规则。 从头部发现的子代理历史接受 `mode: 'unresolved'`；打开时仍校验精确父会话和子会话自身 descriptor。Client 从已打开子会话的投影确定可用模式，子会话打开失败不会使父会话失效。
+每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。取消要求 live 状态；queue 变更、模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器；省略 `action` 时按文件类型关联打开，包括 HTML 和 SVG。两种操作都要求当前文件系统将请求的 Host 路径映射到同一个规范进程路径；无法映射的远端路径会在执行原生命令之前被拒绝。 `session.projections` 通过一次 live-preferred Session observation 读取完整基线，不激活 Agent。Session 不存在时返回 null，并可提供任意已注册的 projection key。Client 通过 `projectionsBySession` 暴露共享值和显式读取状态，由领域选择自身的 key。Session 列表摘要携带 `agentAvailable`，通过已有摘要与状态事件更新，与持久化 projection 相互独立。初始读取与实时 projection 帧使用相同的序号排序规则。
 
 Client 列表行和驻留 Session 使用当前 `sessionListMetadata` 投影纠正过期的空白会话提示；最近活动时间取摘要时间戳与投影中最后一次用户提示词时间的较晚值。当 SessionManager 在列表行到达前创建实例时，会使用已保留的该 Session 元数据对账空白状态。因此，即使旧列表响应仍将已有对话标为空白，新会话操作也不会复用已经打开过的对话。
 
diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts
index 663f0150cc..f46b6cc8fe 100644
--- a/packages/api/session-controller/src/client/sessions/manager.ts
+++ b/packages/api/session-controller/src/client/sessions/manager.ts
@@ -166,14 +166,6 @@ export class SessionManager {
         }
       }
     }
-    const summary = this.summaries.find(item => item.sessionId === sessionId)
-    if (summary?.origin === 'subagent' && summary.parentSessionId !== undefined) {
-      return {
-        parentSessionId: summary.parentSessionId,
-        childSessionId: sessionId,
-        mode: this.projectionStores.get(sessionId)?.values().subagent?.mode ?? 'unresolved',
-      }
-    }
     return undefined
   }
 
@@ -689,6 +681,10 @@ export class SessionManager {
     this.listInflight = null
     void this.refreshList()
     const parents = new Set(this.projectionLoads.keys())
+    for (const id of this.sessions.keys()) {
+      const address = this.addresses.get(id)
+      if (address !== undefined) parents.add(address.parentSessionId)
+    }
     for (const { controller } of this.projectionInflight.values()) controller.abort()
     this.projectionInflight.clear()
     this.projectionLoads.clear()
diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts
index bb4540f94c..cd38a26fcf 100644
--- a/packages/api/session-controller/src/client/sessions/session.ts
+++ b/packages/api/session-controller/src/client/sessions/session.ts
@@ -812,7 +812,6 @@ export class Session implements SessionFace {
   }
 
   private buildSnapshot(): SessionSnapshot {
-    const identity = this.projections.values().subagent
     return {
       sessionId: this.sessionId,
       pendingSubmissions: this.pendingSubmissions,
@@ -820,9 +819,7 @@ export class Session implements SessionFace {
       subagent: this.address === undefined
         ? null
         : {
-          address: this.address.mode === 'unresolved' && identity != null
-            ? { ...this.address, mode: identity.mode }
-            : this.address,
+          address: this.address,
           ...(this.parentAvailable === undefined ? {} : { parentAvailable: this.parentAvailable }),
         },
       removed: this.removed,
diff --git a/packages/api/session-controller/src/history.ts b/packages/api/session-controller/src/history.ts
index ab31da6737..a22badc1f1 100644
--- a/packages/api/session-controller/src/history.ts
+++ b/packages/api/session-controller/src/history.ts
@@ -364,7 +364,7 @@ function validateAddress(
       reason: 'unsupported',
     })
   }
-  if (address.mode !== 'unresolved' && identity.mode !== address.mode) {
+  if (identity.mode !== address.mode) {
     throw new RemoteError('subagent/unauthorized', 'subagent mode does not match the supplied address', {
       childSessionId: address.childSessionId,
     })
diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts
index bd4d3d1840..a925e9da83 100644
--- a/packages/api/session-controller/src/types.ts
+++ b/packages/api/session-controller/src/types.ts
@@ -393,7 +393,7 @@ export type SessionAddress =
     readonly kind: 'subagent'
     readonly parentSessionId: SessionId
     readonly childSessionId: SessionId
-    readonly mode: 'one-shot' | 'continuable' | 'unresolved'
+    readonly mode: 'one-shot' | 'continuable'
   }
 
 /** One non-activating Session projection read. */
diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts
index 05495adfee..7ee5be5397 100644
--- a/packages/api/session-controller/tests/manager.client.spec.ts
+++ b/packages/api/session-controller/tests/manager.client.spec.ts
@@ -417,33 +417,6 @@ describe('Host Remote event routing', () => {
 })
 
 describe('subagent catalogs', () => {
-  it.for(['one-shot', 'continuable'] as const)('opens a header-discovered child on demand and resolves %s mode', async (mode, { mock, remote, start }) => {
-    remote.session.list.mockImplementation(() => Promise.resolve(ok({ items: [
-      summary(S1), summary(S2, { parentSessionId: S1, origin: 'subagent' }),
-    ] })))
-    mock.load(sessionWorld)
-    mock.stream(FOLLOW, followScript(ok({
-      records: [], hasMore: false,
-      projections: { asOfSeq: 0, values: { subagent: { mode, label: 'restored', seq: 0 } } },
-    })))
-    const client = await start()
-    const manager = new SessionManager(client.ctx.remote)
-    try {
-      await manager.refreshList()
-      manager.resolveTarget(S2)
-      expect(manager.subagentAddress(S2)).toEqual({ parentSessionId: S1, childSessionId: S2, mode: 'unresolved' })
-      expect(remote.session.projections).not.toHaveBeenCalled()
-      expect(mock.log.requests(FOLLOW)).toEqual([])
-      const child = manager.get(S2)
-      await child.open()
-      expect(mock.log.requests(FOLLOW)).toEqual([{
-        address: { kind: 'subagent', parentSessionId: S1, childSessionId: S2, mode: 'unresolved' },
-        assistantStream: true, maxMessages: 50,
-      }])
-      expect(child.getSnapshot().subagent?.address.mode).toBe(mode)
-    } finally { await manager.dispose() }
-  })
-
   it('keeps a catalog-discovered child address across identity resolution and status frames', async ({ mock, remote, start }) => {
     remote.session.list.mockImplementation(() => Promise.resolve(ok({ items: [
       summary(S1),
@@ -1037,24 +1010,33 @@ describe('connected generation', () => {
     expect(remote.session.page).toHaveBeenCalledTimes(historyCallsBefore)
   })
 
-  it('retains the durable parent address across reconnect without opening the parent', async ({ mock, remote }) => {
+  it('retains the durable parent address and refreshes that parent across reconnect', async ({ mock, remote }) => {
     const address = {
       parentSessionId: S1,
       childSessionId: S2,
       mode: 'continuable' as const,
     }
     remote.session.list.mockImplementation(() => Promise.resolve(ok({ items: [summary(S1)] as never[] })))
+    const parent = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.projections>>>()
+    remote.session.projections.mockImplementation(() => parent.promise)
     const manager = makeManager(mock, remote)
     manager.resolveTarget(address)
     manager.get(S2)
 
     manager.handleConnected()
     expect(manager.get(S2).getSnapshot().subagent).toEqual({ address })
+    parent.resolve(ok({ asOfSeq: 0, values: { subagentCatalog: [{ createdAt: 1,
+      id: S2, mode: 'continuable', label: 'worker',
+    }] } }))
 
     await vi.waitFor(() => {
       expect(remote.session.list.mock.calls.map(([request]) => request)).toHaveLength(1)
     })
-    expect(remote.session.projections).not.toHaveBeenCalled()
+    await vi.waitFor(() => {
+      expect(remote.session.projections.mock.calls.map(([request]) => request)).toEqual([
+        { sessionId: S1 },
+      ])
+    })
     expect(manager.get(S2).getSnapshot().subagent).toEqual({
       address,
       parentAvailable: true,
diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts
index 2fae510838..04b43972e9 100644
--- a/packages/api/session-controller/tests/transport.host.spec.ts
+++ b/packages/api/session-controller/tests/transport.host.spec.ts
@@ -641,27 +641,6 @@ describe('SessionHistoryController', () => {
       .rejects.toMatchObject({ code: 'subagent/unauthorized' })
   })
 
-  it('resolves a header-discovered address while retaining child ownership and descriptor validation', async () => {
-    const bench = await setup()
-    const parentSessionId = SessionId('unresolved-parent')
-    const childSessionId = SessionId('unresolved-child')
-    const header: SessionHeader = {
-      version: SESSION_FORMAT_VERSION, id: childSessionId, createdAt: 1, cwd: '/workspace',
-      isSeeded: false, origin: 'subagent', parentSession: parentSessionId,
-    }
-    cold(bench.ctx, header, [event('subagent/descriptor', SessionSeq(0), {
-      version: 3, mode: 'one-shot', provider: 'spawn',
-    })])
-    const address = { kind: 'subagent', parentSessionId, childSessionId, mode: 'unresolved' } as const
-    await expect(bench.transport.page({ address, throughSeq: 0 }, signal())).resolves.toMatchObject({
-      records: [{ type: 'event', event: { type: 'subagent/descriptor' } }],
-    })
-    await expect(bench.transport.page({ address: { ...address, parentSessionId: SessionId('wrong') }, throughSeq: 0 }, signal()))
-      .rejects.toMatchObject({ code: 'subagent/unauthorized' })
-    await expect(bench.transport.page({ address: { ...address, mode: 'continuable' }, throughSeq: 0 }, signal()))
-      .rejects.toMatchObject({ code: 'subagent/unauthorized' })
-  })
-
   it('reports an unavailable descriptor when an observed child has no projection value', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index 83ca816b51..45a496719c 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/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-subagent/README.md
-README.md: 33d8da78b2cf27ccce1cfa8ee7c26ddb43b3d083
-README.zh.md: 9cc1fff725d8539abc648ab7d198413194674160
+README.md: 1404e893add386b88a24d78675a4f0be06f497a0
+README.zh.md: 97c743b580e25cd50bcb01a3a7547cb7415a0e08
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index 33d8da78b2..1404e893ad 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -25,17 +25,17 @@ Use this package to browse every subagent conversation beneath a parent session,
 <a id="use-this-package"></a>
 ## Use this package
 
-The session header keeps the current session title as the lineage breadcrumb and appends a `/` count trigger for known direct children or a catalog error. Rows combine existing parent catalog facts with Session-list header relationships, so historical children remain discoverable without opening their logs. Opening the menu or expanding a branch refreshes the lightweight Session list. Selecting a row opens only that child through its exact `{parentSessionId, childSessionId, mode}` address; a header-only row uses `mode: 'unresolved'` until its own descriptor is read. The trailing arrow opens the same address in the right Sidebar.
+The session header keeps the current session title as the lineage breadcrumb and appends a `/` count trigger when its direct catalog has entries or a read has failed. An absent catalog, an empty loading catalog, or a successfully loaded empty catalog hides the count trigger. The trigger opens that direct catalog, reports its total and running counts, and loads nested catalogs only when their rows expand. Select any depth to open that child's conversation with its exact `{parentSessionId, childSessionId, mode}` address, or use the row's trailing arrow to open the same address in the right Sidebar, preferring a separate pane when room permits.
 
-This package registers the `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` resource and builtin Sidebar tab type. The resource refreshes the lightweight Session list before it retains the child `SessionReference`, and releases the reference when the tab record closes. The tab renders the shared `conversation.content` Factory through `sidebar.chat.conversation`, fixes the local View to Chat, and omits the main Conversation header and width controls.
+This package registers the `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` resource and builtin Sidebar tab type. The resource refreshes the direct-parent catalog before it retains the child `SessionReference`, and releases the reference when the tab record closes. The tab renders the shared `conversation.content` Factory through `sidebar.chat.conversation`, fixes the local View to Chat, and omits the main Conversation header and width controls.
 
 ### Browsing the tree
 
-Rows display mode plus activity and an optional log-backed title; unresolved rows display “Not opened” and use their id until identity data is available. Known parent catalog labels remain authoritative. Running, completed, and other inactive children use the shared ongoing, success, and idle indicators. Cached usage and duration remain optional. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree. A header-discovered child with no listed descendants or cached catalog entries is a leaf without a body read.
+Rows display mode plus activity and an optional log-backed title; running uses the shared ongoing loader, an inactive child whose latest closed turn completed normally uses the shared success dot, and other inactive children use the shared idle dot. Every row reserves the same 14px status column, centering smaller dots so titles align with the loader state. The compact header trigger vertically centers its activity glyph and count with a 4px gap. The trailing column stacks total durable provider usage above active-turn duration. Keyboard navigation works with ArrowRight/ArrowLeft to expand and collapse branches and ArrowUp/ArrowDown, Home, End, and Escape to navigate or close the tree. An unlabeled one-shot row falls back to its session id. A row is a known leaf only after its own catalog loads empty.
 
 ### Continuing a conversation
 
-An unresolved child keeps a read-only composer until opening its history supplies a valid identity. A continuable child with a live parent keeps the ordinary input chrome: follow-ups join the child’s FIFO inbox, and Stop routes through `subagents/interruptByParent`. A continuable child whose parent is unavailable and which is not running uses a read-only composer; while it runs, input and Send remain disabled but Stop stays usable. One-shot history remains read-only.
+A continuable child with a live parent keeps the ordinary input chrome: typing and Send stay available while the child runs because every follow-up joins the child's FIFO inbox, and an independent Stop routes through `subagents/interruptByParent`. A continuable child whose exact parent is unavailable and which is not running elects a read-only composer explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer with input and Send disabled but its independent Stop usable.
 
 ### The `@` reference source
 
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index 9cc1fff725..97c743b580 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -25,17 +25,17 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-会话头部保留当前标题作为层级导航，并为已知直接子会话或 catalog 错误追加 `/` 数量入口。列表行合并已有父 catalog 事实和会话列表中的头部关系，让历史子会话无需打开日志即可被发现。打开菜单或展开分支只刷新轻量会话列表。选择一行时，通过精确的 `{parentSessionId, childSessionId, mode}` 地址只打开该子会话；只有头部的条目使用 `mode: 'unresolved'`，直到读取自身 descriptor。末尾箭头将同一地址打开到右侧 Sidebar。
+会话页头保留当前会话 title 作为谱系面包屑，并在直接目录有子项或读取失败时追加 `/` 数量触发器。目录缺席、空目录加载中或成功加载为空时，均隐藏数量触发器。触发器打开该直接目录，报告总数与运行数，并且只在行展开时加载嵌套目录。选择任意深度，即可用该子会话的确切 `{parentSessionId, childSessionId, mode}` 地址打开其对话；也可以使用行尾箭头在右侧 Sidebar 打开同一地址，并在空间允许时优先使用独立分栏。
 
-本包注册 `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` 资源和内置 Sidebar 标签类型。资源在持有子会话 `SessionReference` 前刷新轻量会话列表，并在标签记录关闭时释放引用。标签通过 `sidebar.chat.conversation` 渲染共享的 `conversation.content` Factory，将局部 View 固定为 Chat，省略主 Conversation 头部和宽度控件。
+本包注册 `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` 资源与 builtin Sidebar tab 类型。资源先刷新直接 parent 目录，再保留 child 的 `SessionReference`，并在 tab 记录关闭时释放 reference。tab 通过 `sidebar.chat.conversation` 渲染共享 `conversation.content` Factory，把局部 View 固定为 Chat，并省略主 Conversation 的 Header 与宽度控制。
 
 ### 浏览目录
 
-列表行显示模式、活动状态和可选的日志标题；未解析条目显示“尚未打开”，在身份数据可用前使用 id。已有父 catalog 标签仍具有权威性。运行、完成和其他空闲子会话分别使用共享的进行中、成功和空闲标记。缓存的用量和耗时为可选项。ArrowRight/ArrowLeft 展开或收起分支，ArrowUp/ArrowDown、Home、End、Escape 用于导航或关闭树。头部发现的子会话若没有列出的后代或缓存 catalog 条目，无需读取正文即可作为叶节点。
+行显示 mode、活动状态与由日志支撑的可选 title；running 使用共享 ongoing loading，最近一个已结束轮次正常完成的 inactive child 使用共享 success 绿点，其他 inactive child 使用共享 idle 灰点。每行都为状态图标预留相同的 14px 列宽，并将较小的圆点居中，使 title 与 loading 状态对齐。紧凑的页头触发器会垂直居中活动图标与数量，并保留 4px 水平间距。尾随列在上行显示提供方的持久化 token 用量总计，在下行显示活跃轮次耗时。键盘导航：ArrowRight/ArrowLeft 展开和折叠分支；ArrowUp/ArrowDown、Home、End 与 Escape 用于导航或关闭树。没有 label 的 one-shot 行回退到其会话 id。只有一行自身的目录加载为空后，它才是已知叶子。
 
 ### 续接对话
 
-未解析子会话保持只读输入区，直到打开历史记录并得到有效身份。父代理在线的可继续子会话使用普通输入区：后续消息进入子代理 FIFO 收件箱，Stop 经 `subagents/interruptByParent` 路由。父代理不可用且未运行的可继续子会话使用只读输入区；仍运行时禁用输入和 Send，但保留 Stop。一次性子会话历史始终只读。
+确切 parent 存活时，可继续 child 保留普通输入 chrome：child 运行期间输入和 Send 保持可用，因为每条后续消息都会进入 child 的 FIFO inbox，而独立的 Stop 经由 `subagents/interruptByParent` 路由。确切 parent 不可用且 child 未在运行的可继续 child 会选用说明恢复路径的只读编辑器；此类 child 仍在运行期间，selector 会让位给普通编辑器——输入区与 Send 被禁用，但独立的 Stop 保持可用。
 
 ### `@` 引用 source
 
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
index e734fd9dd9..6dd416fb95 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
@@ -17,7 +17,7 @@ import css from './SubagentHeaderLineage.module.css'
 
 type SubagentCatalogSnapshot = Omit<SessionProjectionSnapshot, 'values' | 'state'> & {
   state: 'loading' | 'ready' | 'error'
-  entries: { id: SessionId; mode: SubagentAddress['mode']; label?: string; activity: 'running' | 'inactive' }[]
+  entries: (SessionProjectionMap['subagentCatalog'][number] & { activity: 'running' | 'inactive' })[]
 }
 type Catalogs = Readonly<Record<SessionId, SubagentCatalogSnapshot>>
 
@@ -238,8 +238,7 @@ function CatalogRows({
           || (childCatalog.state === 'loading' && childCatalog.entries.length === 0)
         const summary = summaries[entry.id]
         const label = entry.label ?? entry.id
-        const mode = entry.mode === 'unresolved' ? t('mode.unresolved')
-          : entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
+        const mode = entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
         const completed = entry.activity === 'inactive'
           && summary?.projectionValues?.subagentTiming?.lastTurnCompleted === true
         const activity = entry.activity === 'running'
@@ -452,31 +451,15 @@ function CatalogDropdown({
   const projections = useSessions(state => state.projectionsBySession)
   const summaries = useSessions(state => state.byId)
   const statuses = useSessionStatus(value => value)
-  const catalogs = useMemo<Catalogs>(() => {
-    const result: Record<SessionId, SubagentCatalogSnapshot> = Object.fromEntries(Object.entries(projections).map(([id, snapshot]) => [id, {
-      state: snapshot.state === 'idle'
-        ? snapshot.values.subagentCatalog === undefined ? 'loading' : 'ready'
-        : snapshot.state,
-      error: snapshot.error,
-      entries: (snapshot.values.subagentCatalog ?? []).map(entry => ({
-        ...entry, activity: (statuses.get(entry.id)?.running ?? summaries[entry.id]?.running) === true ? 'running' as const : 'inactive' as const,
-      })),
-    }]))
-    const known = new Map(Object.entries(result).map(([id, catalog]) => [id, new Set(catalog.entries.map(entry => entry.id))]))
-    for (const summary of Object.values(summaries)) {
-      if (summary.origin !== 'subagent' || summary.parentId === undefined) continue
-      result[summary.id] ??= { state: 'ready', error: null, entries: [] }
-      const catalog = result[summary.parentId] ??= { state: 'ready', error: null, entries: [] }
-      if (known.get(summary.parentId)?.has(summary.id)) continue
-      const identity = summary.projectionValues?.subagent
-      catalog.entries.push({
-        id: summary.id, mode: identity?.mode ?? 'unresolved',
-        ...(identity?.label === undefined ? {} : { label: identity.label }),
-        activity: (statuses.get(summary.id)?.running ?? summary.running) ? 'running' : 'inactive',
-      })
-    }
-    return result
-  }, [projections, summaries, statuses])
+  const catalogs = useMemo<Catalogs>(() => Object.fromEntries(Object.entries(projections).map(([id, snapshot]) => [id, {
+    state: snapshot.state === 'idle'
+      ? snapshot.values.subagentCatalog === undefined ? 'loading' : 'ready'
+      : snapshot.state,
+    error: snapshot.error,
+    entries: (snapshot.values.subagentCatalog ?? []).map(entry => ({
+      ...entry, activity: (statuses.get(entry.id)?.running ?? summaries[entry.id]?.running) === true ? 'running' as const : 'inactive' as const,
+    })),
+  }])), [projections, summaries, statuses])
   const catalog = catalogs[rootSessionId]
   const [open, setOpen] = useState(false)
   const [menuPosition, setMenuPosition] = useState<CSSProperties>()
@@ -490,7 +473,7 @@ function CatalogDropdown({
     ? undefined
     : catalog?.entries.find(entry => entry.id === currentSessionId)
   const switcherDisplayTitle = currentEntry !== undefined
-    ? currentEntry.label ?? (currentEntry.mode === 'unresolved' ? displayTitle : currentEntry.id)
+    ? currentEntry.label ?? currentEntry.id
     : displayTitle
   const directChildren = catalog?.entries ?? []
   const directCount = directChildren.length
diff --git a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
index 1271d13f2c..158e8cb77b 100644
--- a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
@@ -4,7 +4,7 @@ import css from './SubagentReadOnlyComposer.module.css'
 
 /** Why a catalog-addressed conversation cannot accept human input. */
 export interface SubagentReadOnlyMatch {
-  reason: 'one-shot' | 'parent-unavailable' | 'unresolved'
+  reason: 'one-shot' | 'parent-unavailable'
 }
 
 /** Full chain props after the read-only subagent selector accepts the owner currency. */
@@ -24,7 +24,7 @@ export function SubagentReadOnlyComposer({
     <div className={css.frame} role="status">
       <strong>{t(oneShot ? 'readonly.oneShot.title' : 'readonly.title')}</strong>
       <span>
-        {t(matched.reason === 'unresolved' ? 'readonly.unresolved.body' : oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
+        {t(oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
       </span>
     </div>
   )
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index ce92feca36..0055ea8c3f 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -37,7 +37,6 @@ export const inject = ['sessions', 'uiWorkspace', 'slots', 'locale', 'sidebarRig
 function selectReadOnlySubagent(owner: ComposerChainProps): SubagentReadOnlyMatch | null {
   const subagent = owner.session?.subagent
   if (subagent === undefined || subagent === null) return null
-  if (subagent.address.mode === 'unresolved') return { reason: 'unresolved' }
   if (subagent.address.mode === 'one-shot') return { reason: 'one-shot' }
   // Until a Host summary establishes parent availability, keep the normal
   // disabled composer instead of claiming that the parent is offline.
@@ -68,8 +67,8 @@ export function apply(ctx: ClientContext): void {
         preferNewPane: true,
       })
     },
-    refresh() {
-      void sessions.refresh()
+    refresh(parentSessionId: SessionId) {
+      void sessions.refreshProjections(parentSessionId)
     },
   })
   ctx.slots.inject(
diff --git a/packages/client/ui-subagent/src/client/locales.ts b/packages/client/ui-subagent/src/client/locales.ts
index 2de85e949c..cc966d411c 100644
--- a/packages/client/ui-subagent/src/client/locales.ts
+++ b/packages/client/ui-subagent/src/client/locales.ts
@@ -22,7 +22,6 @@ export const zh = {
   'loading.label': '正在加载子代理…',
   'load.error': '无法加载子代理',
   'retry': '重试',
-  'mode.unresolved': '尚未打开',
   'mode.oneShot': '一次性',
   'mode.continuable': '可继续',
   'activity.running': '正在运行',
@@ -41,7 +40,6 @@ export const zh = {
   'readonly.oneShot.title': '一次性子代理记录',
   'readonly.title': '此子代理暂时只读',
   'readonly.oneShot.body': '一次性任务不支持后续消息，可在这里查看完整执行记录。',
-  'readonly.unresolved.body': '打开会话后才能确认是否支持后续消息。',
   'readonly.body': '父会话当前不在线，重新打开父会话后即可继续发送消息。',
 } as const
 
@@ -64,7 +62,6 @@ export const en: Record<SubagentKey, string> = {
   'loading.label': 'Loading subagents…',
   'load.error': 'Unable to load subagents',
   'retry': 'Retry',
-  'mode.unresolved': 'Not opened',
   'mode.oneShot': 'one-shot',
   'mode.continuable': 'continuable',
   'activity.running': 'running',
@@ -83,7 +80,6 @@ export const en: Record<SubagentKey, string> = {
   'readonly.oneShot.title': 'One-shot subagent record',
   'readonly.title': 'This subagent is read-only for now',
   'readonly.oneShot.body': 'One-shot tasks do not accept follow-ups; review the full execution record here.',
-  'readonly.unresolved.body': 'Open this conversation to check whether it supports follow-up messages.',
   'readonly.body': 'The parent session is offline; reopen it to continue sending messages.',
 }
 
diff --git a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
index f83b9bb07f..a4fe489714 100644
--- a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
+++ b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
@@ -73,7 +73,7 @@ export function parseSubagentChatAddress(value: string): SubagentAddress | undef
   if (parts.length !== 2 || parts[0] !== 'session') return undefined
   const parentSessionId = url.searchParams.get('parent')
   const mode = url.searchParams.get('mode')
-  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable' && mode !== 'unresolved')) {
+  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable')) {
     return undefined
   }
   try {
@@ -106,7 +106,7 @@ function subagentChatResourceProvider(sessions: ISessions): ResourceProvider<'su
       const address = parseSubagentChatAddress(resourceAddress)
       if (address === undefined) throw new Error(`ui-subagent: invalid chat resource address "${resourceAddress}"`)
       if (isAbortRequested(signal)) return
-      await sessions.refresh()
+      await sessions.refreshProjections(address.parentSessionId)
       if (isAbortRequested(signal)) return
       const reference = sessions.retain(address, { source: 'sidebarChat', signal })
       try {
diff --git a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
index ab7dc11320..49b2ac6016 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
@@ -2,7 +2,7 @@
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { Context } from '@deepseek-ai/cordis'
 import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import type {
   SessionListState, SessionSnapshot, SessionSummary,
 } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -51,8 +51,8 @@ function sessionsWith(sessions: SessionSummary[]) {
     subagentAddress: (childSessionId: SessionId) => childSessionId === address.childSessionId
       ? address
       : undefined,
-    refresh: () => {
-      actionCalls.push({ method: 'refresh', args: [] })
+    refreshProjections: (parentSessionId: SessionId) => {
+      actionCalls.push({ method: 'refreshProjections', args: [parentSessionId] })
       return Promise.resolve()
     },
   }
@@ -74,10 +74,6 @@ async function fullBench(sessions: SessionSummary[]) {
   const ctx = new Context()
   const face = sessionsWith(sessions)
   ctx.provide('sessions', face)
-  const registerResources = vi.fn(() => () => {})
-  const registerTab = vi.fn(() => () => {})
-  ctx.provide('resources', { register: registerResources })
-  ctx.provide('sidebarRightTabs', { register: registerTab })
   ctx.provide('uiWorkspace', {
     openSession: (address: SubagentAddress) => {
       face.actionCalls.push({ method: 'openSession', args: [address] })
@@ -93,7 +89,7 @@ async function fullBench(sessions: SessionSummary[]) {
   await provideSlotFaces(ctx)
   await ctx.plugin({ inject: localeInject, apply: applyLocale }).await()
   await ctx.plugin({ inject: [...inject], apply }).await()
-  return { face, ctx, registerResources, registerTab }
+  return { face, ctx }
 }
 
 const FAMILY: SessionSummary[] = [
@@ -112,9 +108,7 @@ describe('apply', () => {
   })
 
   it('registers catalog actions and selects read-only subagent composers from session facts', async () => {
-    const { ctx, face, registerResources, registerTab } = await fullBench(FAMILY)
-    expect(registerResources).toHaveBeenCalledOnce()
-    expect(registerTab).toHaveBeenCalledOnce()
+    const { ctx, face } = await fullBench(FAMILY)
     const catalogEntry = ctx.slots.entries('conversation.session.header.lineage')
       .find(entry => entry.component === SubagentHeaderLineage)!
     const actions = (catalogEntry.inject as unknown as (id: SessionId) => SubagentCatalogInjected)(sid('parent'))
@@ -135,7 +129,7 @@ describe('apply', () => {
           { kind: 'subagentchat', preferNewPane: true },
         ],
       },
-      { method: 'refresh', args: [] },
+      { method: 'refreshProjections', args: [sid('parent')] },
     ])
 
     const composerEntry = ctx.slots.entries('conversation.composer')
@@ -152,8 +146,6 @@ describe('apply', () => {
       pendingInteraction: undefined,
     })
     expect(select(owner(undefined))).toBeNull()
-    expect(select(owner({ address: { ...address, mode: 'unresolved' }, parentAvailable: true })))
-      .toEqual({ reason: 'unresolved' })
     expect(select(owner(null))).toBeNull()
     expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true })))
       .toEqual({ reason: 'one-shot' })
diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
index 0b7c79e9cf..626026fe54 100644
--- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
@@ -6,7 +6,7 @@ import type {
   SessionListState, SessionSummary, SessionSnapshot,
 } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SubagentAddress, SubagentCatalogRow } from '@deepseek-ai/dsh-subagent/client'
-import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SessionStatusSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
 import {
   SubagentHeaderLineage, type SubagentHeaderLineageProps,
@@ -182,7 +182,7 @@ describe('SubagentHeaderLineage', () => {
     expect(inactiveTrigger.querySelector('[data-state="ongoing"]')).toBeNull()
   })
 
-  it('adds header-discovered children without counting ordinary forks or their descendants', () => {
+  it('does not count Sessions outside projected membership', () => {
     const fork = 'fork' as SessionId
     const forkChild = 'fork-child' as SessionId
     render(<SubagentHeaderLineage {...props(catalog({
@@ -198,7 +198,7 @@ describe('SubagentHeaderLineage', () => {
       [forkChild]: { ...summary(forkChild, 1), parentId: fork, origin: 'subagent', running: true },
     })} />)
 
-    const trigger = screen.getByRole('button', { name: '2 个子代理' })
+    const trigger = screen.getByRole('button', { name: '1 个子代理' })
     expect(trigger.querySelector('[data-state="ongoing"]')).toBeNull()
   })
 
@@ -571,30 +571,7 @@ describe('SubagentHeaderLineage', () => {
     })
   })
 
-  it('shows a loading branch until its child headers arrive', () => {
-    const input = props(catalog(), { [CHILD]: catalog({ entries: [], state: 'loading' }) })
-    render(<SubagentHeaderLineage {...input} />)
-    hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
-    fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
-    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
-  })
-
-  it('uses an already opened child identity without loading the parent catalog', () => {
-    const input = props(undefined, {}, {
-      [CHILD]: {
-        ...summary(CHILD, 1), parentId: PARENT, origin: 'subagent',
-        projectionValues: { subagent: { mode: 'one-shot', label: 'restored', seq: SessionSeq(0) } },
-      },
-    })
-    render(<SubagentHeaderLineage {...input} />)
-    hoverCatalog(screen.getByRole('button', { name: /1 个子代理/ }))
-    fireEvent.click(screen.getByRole('treeitem', { name: /restored/ }))
-    expect(input.openChild).toHaveBeenCalledWith({
-      parentSessionId: PARENT, childSessionId: CHILD, mode: 'one-shot',
-    })
-  })
-
-  it('shows header-discovered descendants before their identity projections load', () => {
+  it('shows one generic state while a child catalog loads', () => {
     const secondGrandchild = 'grandchild-2' as SessionId
     const summaries = {
       [CHILD]: { ...summary(CHILD, 1), running: true },
@@ -612,18 +589,15 @@ describe('SubagentHeaderLineage', () => {
     fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
 
     expect(deferred.refresh).toHaveBeenCalledWith(CHILD)
-    expect(screen.getByRole('group').getAttribute('aria-busy')).toBeNull()
-    expect(screen.getAllByRole('treeitem', { name: /尚未打开/ })).toHaveLength(2)
-    fireEvent.click(screen.getByRole('treeitem', { name: /grandchild-2/ }))
-    expect(deferred.openChild).toHaveBeenCalledWith({ parentSessionId: CHILD, childSessionId: secondGrandchild, mode: 'unresolved' })
+    expect(screen.getByRole('group').getAttribute('aria-busy')).toBe('true')
+    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
+    expect(screen.queryByRole('treeitem', { name: '正在加载子代理' })).toBeNull()
 
     const loading = props(catalog(), {
       [CHILD]: catalog({ entries: [], state: 'loading' }),
     }, summaries)
     view.rerender(<SubagentHeaderLineage {...loading} />)
-    hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
-    fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
-    expect(screen.getAllByRole('treeitem', { name: /尚未打开/ })).toHaveLength(2)
+    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
 
     const ready = props(catalog(), {
       [CHILD]: catalog({
@@ -706,7 +680,7 @@ describe('SubagentHeaderLineage', () => {
     expect(failed.refresh).toHaveBeenCalledWith(PARENT)
   })
 
-  it('keeps header-discovered children available without parent catalog facts', () => {
+  it('does not expose summary-only descendants as catalog rows', () => {
     const second = 'child-2' as SessionId
     const summaries = {
       [CHILD]: {
@@ -718,11 +692,11 @@ describe('SubagentHeaderLineage', () => {
     }
     const absent = props(undefined, {}, summaries)
     const view = render(<SubagentHeaderLineage {...absent} />)
-    expect(screen.getByRole('button', { name: /子代理/ })).toBeTruthy()
+    expect(screen.queryByRole('button')).toBeNull()
 
     const staleEmpty = props(catalog({ entries: [] }), {}, summaries)
     view.rerender(<SubagentHeaderLineage {...staleEmpty} />)
-    expect(screen.getByRole('button', { name: /子代理/ })).toBeTruthy()
+    expect(screen.queryByRole('button')).toBeNull()
   })
 
   it('hides a bare loading catalog and keeps the error fallback without focusable rows', async () => {
@@ -915,21 +889,6 @@ describe('SubagentHeaderLineage', () => {
     expect(input.refresh).not.toHaveBeenCalled()
   })
 
-  it('shows a loading switcher before the restored child header arrives', () => {
-    const input = {
-      ...props(undefined, {}, {}, {
-        parentSessionId: PARENT, childSessionId: CHILD, mode: 'unresolved',
-      }),
-      lineageSessionId: CHILD,
-      displayTitle: 'restored child',
-    }
-    render(<SubagentHeaderLineage {...input} />)
-    hoverCatalog(screen.getByRole('button', { name: '切换子代理：restored child' }))
-    expect(screen.getByText('正在加载子代理…')).toBeTruthy()
-    expect(input.refresh).toHaveBeenCalledWith(PARENT)
-    expect(input.openChild).not.toHaveBeenCalled()
-  })
-
   it('keeps a nested title switcher scoped to its direct-parent catalog', () => {
     const input = {
       ...props(catalog(), {
@@ -962,11 +921,6 @@ describe('SubagentHeaderLineage', () => {
 })
 
 describe('SubagentReadOnlyComposer', () => {
-  it('keeps an unresolved child read-only', () => {
-    render(<SubagentReadOnlyComposer matched={{ reason: 'unresolved' }} t={t} />)
-    expect(screen.getByRole('status').textContent).toContain(zh['readonly.unresolved.body'])
-  })
-
   it('explains the exact missing-parent recovery path', () => {
     render(<SubagentReadOnlyComposer matched={{ reason: 'parent-unavailable' }} t={t} />)
     expect(screen.getByRole('status').textContent).toContain('父会话当前不在线')
diff --git a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
index 744cdb174a..143a0cb595 100644
--- a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
@@ -1,10 +1,10 @@
 // @vitest-environment jsdom
 import type { ReactNode } from 'react'
 import { cleanup, render } from '@testing-library/react'
-import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
-import { Context } from '@deepseek-ai/cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Context } from '@deepseek-ai/cordis'
 import type {
-  SessionListState, SessionReference, SessionSnapshot,
+  ISessions, SessionListState, SessionReference, SessionSnapshot,
 } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { ResourceProvider } from '@deepseek-ai/dsh-client-resources/client'
 import { sessionSnapshot } from '@deepseek-ai/dsh-client-test-runtime'
@@ -38,8 +38,6 @@ describe('Sidebar chat address', () => {
     expect(parseSubagentChatAddress(resource)).toEqual(ADDRESS)
     expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'one-shot' })))
       .toEqual({ ...ADDRESS, mode: 'one-shot' })
-    expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'unresolved' })))
-      .toEqual({ ...ADDRESS, mode: 'unresolved' })
   })
 
   it.each([
@@ -66,7 +64,7 @@ describe('Sidebar chat registration', () => {
       [Symbol.dispose]: release,
     } as unknown as SessionReference
     const retain = vi.fn(() => reference)
-    const refresh = vi.fn(() => Promise.resolve())
+    const refreshProjections = vi.fn(() => Promise.resolve())
     const list = {
       getSnapshot: () => ({
         ids: [],
@@ -85,22 +83,19 @@ describe('Sidebar chat registration', () => {
     let provider: ResourceProvider<'subagentchat'> | undefined
     let definition: SidebarRightTabDefinition | undefined
     const registrations: { options: Record<string, unknown>; component: unknown }[] = []
-    const ctx = new Context()
-    onTestFinished(async () => { await ctx.fiber.dispose() })
-    ctx.provide('sessions', { retain, refresh, list })
-    ctx.provide('resources', {
-      register: (value: ResourceProvider<'subagentchat'>) => { provider = value; return () => {} },
-    })
-    ctx.provide('sidebarRightTabs', {
-      register: (value: SidebarRightTabDefinition) => { definition = value; return () => {} },
-    })
-    ctx.provide('slots', {
-      inject: (_name: string, install: () => () => void) => install(),
-      register: (options: Record<string, unknown>, component: unknown) => {
-        registrations.push({ options, component })
-        return () => {}
+    const ctx = {
+      sessions: { retain, refreshProjections, list } as unknown as ISessions,
+      resources: { register: (value: ResourceProvider<'subagentchat'>) => { provider = value; return () => {} } },
+      sidebarRightTabs: { register: (value: SidebarRightTabDefinition) => { definition = value; return () => {} } },
+      slots: {
+        inject: (_name: string, install: () => () => void) => install(),
+        register: (options: Record<string, unknown>, component: unknown) => {
+          registrations.push({ options, component })
+          return () => {}
+        },
       },
-    })
+      effect: (install: () => unknown) => { install(); return () => {} },
+    } as unknown as Context
 
     registerSidebarChat(ctx, (key: string) => key === 'sidebar.chat' ? 'Chat' : key)
 
@@ -119,7 +114,7 @@ describe('Sidebar chat registration', () => {
     const controller = new AbortController()
     const stream = provider!.open(subagentChatAddress(ADDRESS), { signal: controller.signal })[Symbol.asyncIterator]()
     expect(await stream.next()).toEqual({ done: false, value: { ok: true, value: { address: ADDRESS, reference } } })
-    expect(refresh).toHaveBeenCalledWith()
+    expect(refreshProjections).toHaveBeenCalledWith(PARENT)
     expect(retain).toHaveBeenCalledWith(ADDRESS, { source: 'sidebarChat', signal: controller.signal })
     const completion = stream.next()
     await Promise.resolve()
@@ -135,7 +130,7 @@ describe('Sidebar chat registration', () => {
     expect(release).toHaveBeenCalledTimes(2)
 
     let finishRefresh: (() => void) | undefined
-    refresh.mockImplementationOnce(() => new Promise<void>((resolve) => { finishRefresh = resolve }))
+    refreshProjections.mockImplementationOnce(() => new Promise<void>((resolve) => { finishRefresh = resolve }))
     const abortedDuringRefresh = new AbortController()
     const pending = provider!.open(
       subagentChatAddress(ADDRESS), { signal: abortedDuringRefresh.signal },
diff --git a/packages/client/ui-workspace/src/client/navigation.ts b/packages/client/ui-workspace/src/client/navigation.ts
index bd90298125..22138ec707 100644
--- a/packages/client/ui-workspace/src/client/navigation.ts
+++ b/packages/client/ui-workspace/src/client/navigation.ts
@@ -272,6 +272,7 @@ class UiWorkspaceService extends Service implements UiWorkspace {
   private async restoreSelection(workspaces: WorkspaceSnapshot, sessions: SessionListState): Promise<void> {
     const saved = this.selection.getSnapshot()
     if (saved.subagentAddress !== undefined) {
+      void this.sessions.refreshProjections(saved.subagentAddress.parentSessionId)
       this.replaceMain(saved.subagentAddress, this.lifetime.signal, 'preserve')
       return
     }
diff --git a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
index 26bd410059..310bb3627d 100644
--- a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
+++ b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
@@ -732,6 +732,7 @@ describe('UiWorkspaceService', () => {
 
     expect(b.sessions.retain).toHaveBeenCalledExactlyOnceWith(address, { source: 'mainView' })
     expect(b.sessions.refreshProjections.mock.calls).toEqual([
+      [address.parentSessionId],
       [address.childSessionId],
     ])
   })
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index 34e2cc130d..78975d4a43 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -2603,10 +2603,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         throws: ['{SubagentError} `UNAUTHORIZED` when a resident target belongs to a different parent or the supplied parent identity is stale.'],
       },
       {
-        signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>',
-        description: 'Read the parent\'s catalog and discover missing direct children from Session headers. The service owns and releases the live-preferred Session observation.',
+        signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>',
+        description: 'Read the parent\'s durable direct-child catalog without loading or resuming an Agent. The service owns and releases the live-preferred Session observation.',
         parameters: [{ name: 'parentSessionId', description: 'parent whose direct children are requested.' }, { name: 'signal', description: 'cancellation forwarded to the Session query.' }],
-        returns: 'catalog children in event order, then unresolved children whose bodies remain unread.',
+        returns: 'catalog children in parent event order.',
         throws: ['{@link SubagentError} when query or catalog projection is unavailable.', 'SessionQueryError when the parent cannot be read or the query is cancelled.'],
       },
       {
@@ -5745,7 +5745,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     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\' | \'unresolved\';\n};',
+    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};',
   },
   {
     name: 'SessionAssistantStreamAttempt',
@@ -6443,10 +6443,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubagentDescriptorData',
     declaration: 'export type SubagentDescriptorData = OneShotSubagentDescriptorData | ContinuableSubagentDescriptorData;',
   },
-  {
-    name: 'SubagentDiscoveryEntry',
-    declaration: 'export type SubagentDiscoveryEntry = SubagentCatalogEntry | {\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly mode: \'unresolved\';\n};',
-  },
   {
     name: 'SubagentInterruptAuthority',
     declaration: 'export type SubagentInterruptAuthority = {\n    readonly kind: \'user\';\n    readonly parentSessionId: SessionId;\n} | {\n    readonly kind: \'ancestor\';\n    readonly agent: Agent;\n};',
@@ -6497,7 +6493,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubagentRuntime',
-    declaration: 'export class SubagentRuntime extends TypertRemoteService {\n    static Config: z<Config>;\n    constructor(ctx: Context, config: Config);\n    resolveMaxDepth(configured?: number | \'provider-managed\'): number | undefined;\n    async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;\n    async sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;\n    interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;\n    async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>;\n    async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;\n    listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]>;\n    listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;\n    @Remote(\'prompt\')\n    async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>;\n    @Remote(\'interruptByParent\')\n    interruptByParent(childSessionId: SessionId, parentSessionId: SessionId, mode: \'continuable\'): SubagentInterruptReceipt;\n    registerProvider(provider: SubagentProvider): () => void;\n    getProvider(name: string): SubagentProvider | undefined;\n    list(): string[];\n    async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>;\n}',
+    declaration: 'export class SubagentRuntime extends TypertRemoteService {\n    static Config: z<Config>;\n    constructor(ctx: Context, config: Config);\n    resolveMaxDepth(configured?: number | \'provider-managed\'): number | undefined;\n    async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;\n    async sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;\n    interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;\n    async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>;\n    async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;\n    listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>;\n    listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;\n    @Remote(\'prompt\')\n    async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>;\n    @Remote(\'interruptByParent\')\n    interruptByParent(childSessionId: SessionId, parentSessionId: SessionId, mode: \'continuable\'): SubagentInterruptReceipt;\n    registerProvider(provider: SubagentProvider): () => void;\n    getProvider(name: string): SubagentProvider | undefined;\n    list(): string[];\n    async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>;\n}',
   },
   {
     name: 'SubagentSendMessageOptions',
diff --git a/packages/session/session-format-catalog/README.i18n.yaml b/packages/session/session-format-catalog/README.i18n.yaml
index d792370356..31246e1ed0 100644
--- a/packages/session/session-format-catalog/README.i18n.yaml
+++ b/packages/session/session-format-catalog/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-format-catalog/README.md
-README.md: 82c1635ced88651ddcb250bd2d6b03e021faa176
-README.zh.md: 07758cd5ab14010a16889073f4b5b046e9dd0ba7
+README.md: bb86bcaffee2c2e17afffd4ce7fbd917bf1c30ee
+README.zh.md: 156361ae330967169ae82e204ddeff26c50b05bd
diff --git a/packages/session/session-format-catalog/README.md b/packages/session/session-format-catalog/README.md
index 82c1635ced..bb86bcaffe 100644
--- a/packages/session/session-format-catalog/README.md
+++ b/packages/session/session-format-catalog/README.md
@@ -33,7 +33,7 @@ Import this library from persistence and test-support readers that need the comp
 
 ```text
 const descriptor = sessionFormatCatalog.readHeader(physicalHeader)
-const catalog = sessionFormatCatalog
+const catalog = createSessionFormatCatalogWithChildren(childFacts)
 const restore = catalog.createRestore(physicalHeader, { recovery: 'recoverable', validation: 'transformed' })
 for (const row of physicalRows) restore.decodeRow(row)
 const current = restore.finish()
@@ -47,7 +47,7 @@ Production historical reads select `{ recovery: 'recoverable', validation: 'tran
 
 The catalog contains all supported historical readers directly. A profile cannot add, remove, or reorder an edge by mounting a feature plugin. Its peer dependency on `dsh-session` supplies the installed current event vocabulary and current restoration rules, while historical edge validators remain frozen. The browser-safe `./message-projections` export assembles current plugin-owned interpreters for detached constructors and surface folds; it does not mount recovery listeners.
 
-`sessionFormatCatalog` restores historical bodies independently of other Sessions. `createSessionFormatCatalogWithChildren(childFacts)` optionally supplements parent catalogs for offline fixture preparation and Preview packing; see the [catalog-completion specification](../session-format-v3-to-v4/README.md). `historicalSessionFormatCatalog` restores V0–V3 using the fixed released-V3 vocabulary for that evidence collection. An ignorable V3 extension stays opaque even when the current writer knows its name. Supplied evidence remains unchanged for the catalog’s lifetime, and every restore owns independent stage state.
+`createSessionFormatCatalogWithChildren(childFacts)` binds explicit child evidence to V3→V4 during assembly; see the [catalog-completion specification](../session-format-v3-to-v4/README.md). `historicalSessionFormatCatalog` restores V0–V3 using the fixed released-V3 event vocabulary to collect child prerequisites without recursively completing their catalogs. An ignorable V3 extension remains opaque even when the installed writer knows its name. Isolated transcript replay explicitly supplies an empty array; persistence must collect the complete available direct-child set. Keep the supplied evidence unchanged for the catalog’s lifetime. Each restore owns independent stage state. The static `sessionFormatCatalog` supports header and native current-format reads; historical body reads require the child-bound catalog.
 
 -----
 
diff --git a/packages/session/session-format-catalog/README.zh.md b/packages/session/session-format-catalog/README.zh.md
index 07758cd5ab..156361ae33 100644
--- a/packages/session/session-format-catalog/README.zh.md
+++ b/packages/session/session-format-catalog/README.zh.md
@@ -33,7 +33,7 @@ kind: "package-library"
 
 ```text
 const descriptor = sessionFormatCatalog.readHeader(physicalHeader)
-const catalog = sessionFormatCatalog
+const catalog = createSessionFormatCatalogWithChildren(childFacts)
 const restore = catalog.createRestore(physicalHeader, { recovery: 'recoverable', validation: 'transformed' })
 for (const row of physicalRows) restore.decodeRow(row)
 const current = restore.finish()
@@ -47,7 +47,7 @@ Production 历史读取使用 `{ recovery: 'recoverable', validation: 'transform
 
 该目录直接包含所有受支持的历史读取器。Profile 无法通过挂载功能插件来添加、移除或重新排列迁移边。它通过对 `dsh-session` 的对等依赖（peer dependency）获得已安装的当前事件词表与当前还原规则，而历史迁移边校验器保持冻结。浏览器安全的 `./message-projections` 导出为独立构造函数和 surface 折叠装配当前插件拥有的处理器，不挂载恢复监听器。
 
-`sessionFormatCatalog` 独立于其他会话恢复历史正文。`createSessionFormatCatalogWithChildren(childFacts)` 可在离线夹具准备和 Preview 打包时补充父会话 catalog；参见 [catalog 补全规范](../session-format-v3-to-v4/README.zh.md)。`historicalSessionFormatCatalog` 使用固定的已发布 V3 词汇恢复 V0–V3，为此收集证据。即使当前 writer 已认识某个名称，可忽略的 V3 扩展仍保持不透明。传入证据在 catalog 生命周期内保持不变，每次恢复拥有独立的阶段状态。
+`createSessionFormatCatalogWithChildren(childFacts)` 在组装时将显式的子 Session 证据绑定到 V3→V4，见[目录补齐规范](../session-format-v3-to-v4/README.zh.md)。`historicalSessionFormatCatalog` 使用固定的已发布 V3 事件词汇恢复 V0–V3，收集子日志前置事实而不递归补齐其目录。即使已安装写入方认识事件名，可忽略 V3 扩展仍保持不透明。独立转录回放显式提供空数组；持久化必须收集完整的可用直属子 Session 集合。在 catalog 的生命周期内保持传入证据不变。每次恢复各自拥有独立的 stage 状态。静态 `sessionFormatCatalog` 支持 header 和原生当前格式读取；历史正文读取必须使用已绑定子 Session 的 catalog。
 
 -----
 
diff --git a/packages/session/session-format-catalog/src/children.ts b/packages/session/session-format-catalog/src/children.ts
index bee7de134f..580e46d2ae 100644
--- a/packages/session/session-format-catalog/src/children.ts
+++ b/packages/session/session-format-catalog/src/children.ts
@@ -7,7 +7,7 @@ import { sessionFormatCatalogOptions } from './generated.ts'
 
 /**
  * Assemble a catalog whose V3→V4 edge knows one parent's historical children.
- * @param children - complete child evidence retained unchanged for the catalog's lifetime; an empty array requests no backfill.
+ * @param children - complete child evidence retained unchanged for the catalog's lifetime; an empty array declares no children.
  * @returns a catalog with independent restore state per artifact and unchanged current-format readers.
  */
 export function createSessionFormatCatalogWithChildren(children: readonly SessionFormatJsonValue[]): SessionFormatCatalog {
diff --git a/packages/session/session-format-catalog/tests/children.spec.ts b/packages/session/session-format-catalog/tests/children.spec.ts
index 7e600a8095..4b2d465e93 100644
--- a/packages/session/session-format-catalog/tests/children.spec.ts
+++ b/packages/session/session-format-catalog/tests/children.spec.ts
@@ -7,9 +7,9 @@ const child = (id: string) => ({ childId: id, childCreatedAt: 2, descriptorCount
   descriptor: { version: 3, provider: 'spawn', mode: 'one-shot' } })
 
 describe('parent-specific catalog assembly', () => {
-  it('restores historical bodies independently while retaining optional catalog completion', () => {
+  it('requires explicit children for historical bodies while retaining header and native V4 reads', () => {
     expect(sessionFormatCatalog.readHeader(header).status).toBe('migration-required')
-    expect(sessionFormatCatalog.createRestore(header, policy).finish().events).toEqual([])
+    expect(() => sessionFormatCatalog.createRestore(header, policy)).toThrow('explicit historical child facts')
     expect(createSessionFormatCatalogWithChildren([]).createRestore(header, policy).finish().events).toEqual([])
     expect(sessionFormatCatalog.createRestore({ ...header, version: 4 }, policy).finish().events).toEqual([])
   })
diff --git a/packages/session/session-format-v3-to-v4/README.i18n.yaml b/packages/session/session-format-v3-to-v4/README.i18n.yaml
index 8b6ee01f8d..c22705c4fa 100644
--- a/packages/session/session-format-v3-to-v4/README.i18n.yaml
+++ b/packages/session/session-format-v3-to-v4/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-format-v3-to-v4/README.md
-README.md: cb23641b3cc3b9a60ee1dc3429ab529809df6c93
-README.zh.md: 67148ff09cc43eed9aed523f5ae7670c3348403b
+README.md: 4a6a58a0b1375ff3f318d7cf94bf008ec16ab9df
+README.zh.md: 7383dff61fd921976772a6cdaad9d98474f6c150
diff --git a/packages/session/session-format-v3-to-v4/README.md b/packages/session/session-format-v3-to-v4/README.md
index cb23641b3c..4a6a58a0b1 100644
--- a/packages/session/session-format-v3-to-v4/README.md
+++ b/packages/session/session-format-v3-to-v4/README.md
@@ -48,7 +48,7 @@ Header-only migration validates and advances metadata without reading the body o
 const targetHeader = sessionFormatV3ToV4.migrateHeader(sourceHeader)
 ```
 
-Historical body restoration through `sessionFormatV3ToV4` requires only the requested Session. It preserves existing catalog entries without reading children. Offline fixture preparation may explicitly supply child evidence through `createSessionFormatCatalogWithChildren()` to append missing catalog facts; an empty array requests no backfill. Keep supplied evidence unchanged for the catalog’s lifetime.
+Historical body restoration requires explicit child evidence. `sessionFormatV3ToV4.createStage()` refuses without that binding; an empty array explicitly declares no children. Persistence must collect the complete available direct-child set, while isolated transcript replay can supply its deliberately empty set. Keep the evidence unchanged for the catalog's lifetime.
 
 ```text
 const catalog = createSessionFormatCatalogWithChildren(childFacts)
@@ -154,7 +154,7 @@ Catalog version 0 requires string `childId`, nonnegative safe-integer `childCrea
 
 The stage considers parent catalog records only after the final inherited cut. Every inherited marker discards earlier catalog candidates without interpreting their payloads. Missing entries append after all source events, sorted by creation time then child id, with dense new sequences. Their time is the final source event's time, or header creation time for an empty log. They neither enter the model surface nor change the inherited count.
 
-The supplemental evidence rules apply only when a caller requests catalog completion. Runtime JSONL migration does not collect child evidence; it migrates each Session on its own open. The package reads no files; [persistence](../session-persistence-jsonl/README.md) owns encoding, locks, cancellation, source revision checks, and publication.
+Storage supplies recognizable direct-child evidence and rechecks membership and physical revisions during preparation, memo reuse, and publication. The JSONL provider isolates unreadable child headers, child decoding failures, and invalid descriptor fields while retaining other catalog entries; it does not migrate child catalogs during parent preparation. The converter still rejects conflicting supplied facts and changed parent history. [JSONL persistence](../session-persistence-jsonl/README.md) owns warnings, source checks, and child-local failure handling. Current V4 reads never invoke this converter and validate native catalog fields, uniqueness, and delivery ownership directly.
 
 <a id="sequence-references"></a>
 ### Sequence references and inheritance
diff --git a/packages/session/session-format-v3-to-v4/README.zh.md b/packages/session/session-format-v3-to-v4/README.zh.md
index 67148ff09c..7383dff61f 100644
--- a/packages/session/session-format-v3-to-v4/README.zh.md
+++ b/packages/session/session-format-v3-to-v4/README.zh.md
@@ -48,7 +48,7 @@ kind: "package-library"
 const targetHeader = sessionFormatV3ToV4.migrateHeader(sourceHeader)
 ```
 
-通过 `sessionFormatV3ToV4` 恢复历史正文只需要所请求的会话。它保留已有 catalog 条目，不读取子会话。离线夹具准备可以通过 `createSessionFormatCatalogWithChildren()` 显式传入子会话证据，追加缺失的 catalog 事实；空数组表示不回填。传入证据在 catalog 生命周期内必须保持不变。
+历史正文恢复要求显式的子级证据。没有该绑定时，`sessionFormatV3ToV4.createStage()` 会拒绝；空数组明确声明没有子级。持久化层必须收集完整的可用直属子级集合，而隔离的 transcript 回放可以提供其刻意为空的集合。Catalog 存续期间，证据必须保持不变。
 
 ```text
 const catalog = createSessionFormatCatalogWithChildren(childFacts)
@@ -154,7 +154,7 @@ Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt
 
 Stage 只把最终继承截点之后的父目录记录作为候选。每个 inherited marker 都会丢弃更早的目录候选，不解释其载荷。缺失项追加在所有源事件之后，按创建时间、child id 排序，并使用连续的新序号。时间取最后一个源事件的 time；空日志则取 header 创建时间。这些记录既不进入模型表面，也不改变继承计数。
 
-补充证据规则仅适用于调用者请求 catalog 补全时。运行时 JSONL 迁移不收集子会话证据，每个会话在自身 open 时独立迁移。本包不读取文件；[持久化](../session-persistence-jsonl/README.zh.md) 负责编码、锁、取消、源文件版本检查和发布。
+存储提供可识别的直属子证据，并在准备、memo 复用与发布时重新检查成员集合和物理修订。JSONL 提供方隔离不可读子 header、子日志解码失败和无效 descriptor 字段，同时保留其他目录项；准备父目录时不会迁移子目录。转换器仍拒绝冲突的已提供事实和发生变化的父历史。[JSONL 持久化](../session-persistence-jsonl/README.zh.md)拥有警告、来源检查与子会话错误隔离。当前 V4 读取不调用本转换器，直接校验原生目录字段、唯一性及投递归属。
 
 <a id="sequence-references"></a>
 ### 序号引用与继承
diff --git a/packages/session/session-format-v3-to-v4/src/facts.ts b/packages/session/session-format-v3-to-v4/src/facts.ts
index a08f2bda20..23a0c233d0 100644
--- a/packages/session/session-format-v3-to-v4/src/facts.ts
+++ b/packages/session/session-format-v3-to-v4/src/facts.ts
@@ -6,7 +6,8 @@ import type { SessionFormatArtifact, SessionFormatJsonObject, SessionFormatJsonV
 /**
  * Collect a child's own descriptor without requiring one before its parent catalog is read.
  * @param artifact - validated historical child artifact with its exact inherited cut.
- * @returns compact child identity and descriptor evidence for catalog completion.
+ * @returns compact child identity and descriptor evidence with validated discovery fields for catalog completion.
+ * @throws SessionFormatError when a supported own descriptor has invalid discovery fields.
  */
 export function historicalChildCatalogSource(artifact: SessionFormatArtifact): SessionFormatJsonObject {
   const header = artifact.header
@@ -14,10 +15,12 @@ export function historicalChildCatalogSource(artifact: SessionFormatArtifact): S
     throw new SessionFormatUnsupportedMigrationError('catalog migration requires a subagent child with a direct parent')
   }
   const descriptors = artifact.events.filter(event => event.type === 'subagent/descriptor' && event.seq >= artifact.inheritedEventCount)
-  return {
+  const source = {
     childId: header.id, childCreatedAt: header.createdAt,
     descriptorCount: descriptors.length, descriptor: descriptors[0]?.data ?? null,
   }
+  childCatalogFact(source)
+  return source
 }
 
 /**
diff --git a/packages/session/session-format-v3-to-v4/src/migration.ts b/packages/session/session-format-v3-to-v4/src/migration.ts
index d3359baed8..3b1c1de60a 100644
--- a/packages/session/session-format-v3-to-v4/src/migration.ts
+++ b/packages/session/session-format-v3-to-v4/src/migration.ts
@@ -10,7 +10,7 @@ import { namespaceV3OpaqueEvent, RELEASED_V3_EVENT_TYPES } from './extension-ide
 import { assertReleasedV4Header, validateDeliveryAccepted } from './validation.ts'
 import { catalogFact, childCatalogSource, childCatalogFact, childCatalogSubject } from './facts.ts'
 
-/** Convert one Session independently, preserving its existing catalog entries. */
+/** Header-only migration declaration; body restoration requires explicit child evidence. */
 export const sessionFormatV3ToV4 = defineSessionFormatMigration({
   name: '@deepseek-ai/dsh-session-format-v3-to-v4',
   fromVersion: 3,
@@ -19,13 +19,15 @@ export const sessionFormatV3ToV4 = defineSessionFormatMigration({
     assertReleasedV3Header(header)
     return { ...header, version: 4 }
   },
-  createStage: input => new ReleasedV3ToV4Stage(input, []),
+  createStage() {
+    throw new SessionFormatUnsupportedMigrationError('V3 catalog migration requires explicit historical child facts, including an empty array for a parent without children')
+  },
   validateTargetHeader: assertReleasedV4Header,
 })
 
 /**
  * Bind one parent's historical child evidence to its V3→V4 migration.
- * @param children - complete child evidence retained unchanged for the lifetime of this declaration; an empty array requests no backfill.
+ * @param children - complete child evidence retained unchanged for the lifetime of this declaration; an empty array declares no children.
  * @returns an adjacent migration that creates independent stages with the supplied evidence.
  */
 export function createSessionFormatV3ToV4(children: readonly SessionFormatJsonValue[]): SessionFormatMigration {
diff --git a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
index 08069d659a..7b1ad7e3c0 100644
--- a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
@@ -71,9 +71,9 @@ describe('V3 parent catalog completion', () => {
     expect(() => migrate([opaque], [])).toThrow('complete version 0')
   })
 
-  it('accepts independent migration and refuses conflicting supplemental identities', () => {
+  it('requires explicit corpus facts and refuses conflicting identities', () => {
     expect(() => sessionFormatV3ToV4.createStage({ sourceHeader: header, targetHeader: { ...header, version: 4 },
-      sourceKind: 'decoded', sourceInheritedEventCount: 0 })).not.toThrow()
+      sourceKind: 'decoded', sourceInheritedEventCount: 0 })).toThrow('explicit historical child facts')
     expect(() => migrate([], [{ ...child, mode: 'unknown' }])).toThrow('complete version 0')
     expect(() => migrate([{ type: 'subagent/catalog', seq: 0, time: 2, data: child }], [{ ...child, childCreatedAt: 3 }])).toThrow('conflicts')
   })
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 6d1541c724..21073ec706 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: 2581be5ccdee5e5539e383ac0598ea1a285b6376
-README.zh.md: 7eddf277cc82e078283961f3309c979214e0cb9f
+README.md: af64ea90850ea0777ceb7c61d4c43dd1a0bc6707
+README.zh.md: b61d64e72aa76f58b3ed9534da15c8657952e46a
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index 2581be5ccd..af64ea9085 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -79,11 +79,11 @@ The current-generation scanner applies the current codec owner’s structural ad
 
 ### Reading the logs
 
-`open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Revisions identify only the selected Session file, independently of other Sessions. 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'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Current revisions identify that file; historical revisions also fingerprint the selected files across the persistence root, so child changes invalidate cached logical events. Fingerprinting reads filesystem metadata only; unrelated changes conservatively invalidate historical revisions. One `list()` call shares a corpus fingerprint across its historical entries. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
-Historical preparation reads and migrates only the requested Session. It preserves existing parent catalog events without collecting child descriptors or validating other Session headers and bodies. Child corruption, unsupported generations, and child publication cannot invalidate a parent preparation. The [subagent service](../../subagent/subagent/README.md) discovers missing child entries from headers; opening a selected child performs its own migration and reports its own errors. Current reads validate catalog fields, uniqueness, and delivery ownership before exposing events.
+Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers are omitted from discovery. Child decoding and descriptor-field failures produce warnings naming the child path and omit its backfill; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors provide no new fact. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
 
-Historical revisions and memo reuse require no corpus fingerprint or child-body scan. Listing still enumerates Session headers; targeted generation lookup may enumerate directories to locate an uncached id. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat only the requested Session’s decoding. The [diagnostic measurements](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements) retain the earlier eager-scan baseline.
+Historical `stat` and `list` revisions require metadata work proportional to the root’s Session count. Fresh body preparation scans all selected headers and decodes direct-child bodies; memo reuse still scans membership and checks revisions. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat that work. Current V4 body reads and revisions avoid the historical corpus scan. See the [measured costs and diagnostic command](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements).
 
 -----
 
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 7eddf277cc..b61d64e72a 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -79,11 +79,11 @@ kind: "package-reference"
 
 ### 读取日志
 
-`open(id, 'read'|'write')` 选择最高规范代次。当前输入走普通快速路径。对于历史输入，读 open 解码并迁移源文件一次，校验当前逻辑结果，不发布后继文件。写 open 复用按源版本缓存的准备结果，或重新准备，再分块写同目录临时文件，经 Worker Thread 校验、复核源文件版本后，以不覆盖方式发布当前后继文件。源文件字节保持不变。准备后的源文件变化会拒绝该次写 open，已返回的逻辑历史不变；后续写 open 重新准备。缓存前深度冻结的事件图标记为 `shared-frozen`，读取和切片（包括空切片）保持这一状态；只有尚未物化的待写日志报告 `detached`。`stat(id)` 和 `list()` 只选择并转换最高代次的头部，不读事件行或启动迁移；快照携带所选文件的 `sizeBytes` 和尽力获取的版本标识。版本标识只对应所选会话文件，与其他会话无关。配置 `compression: 'none'` 时，外部工具可以直接读取逐行文本；压缩默认格式必须经后端读取。
+`open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；每个嵌套对象和数组都会冻结，句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的修订号。当前格式修订号标识该文件；历史格式修订号还包含持久化根目录中所选文件的指纹，因此子日志变化会使缓存的逻辑事件失效。指纹只读取文件系统元数据；无关变化也会保守地使历史修订号失效。一次 `list()` 为其历史条目共用一个全库指纹。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
-历史准备只读取并迁移所请求的会话。它保留已有父会话 catalog 事件，不收集子会话 descriptor，也不校验其他会话的头部或正文。子会话损坏、不支持的代次和子会话后继发布不会使父会话准备结果失效。[子代理服务](../../subagent/subagent/README.zh.md) 从头部发现缺失的子会话条目；打开选中的子会话时才独立迁移并报告其错误。当前读取在暴露事件前校验 catalog 字段、唯一性和交付归属。
+历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header 不参与发现。子日志解码或 descriptor 字段失败会产生带子路径的警告，并跳过该项补填；健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 不提供新事实。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
 
-历史版本标识和缓存复用不需要全库指纹或子会话正文扫描。列表仍枚举会话头部；定位尚未缓存的 id 时，定向代次查找可能枚举目录。只读访问不发布升级，因此冷进程和缓存淘汰后只重复所请求会话的解码。[诊断测量](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements) 保留此前主动扫描的基线。
+历史格式的 `stat` 与 `list` 修订号需要与根目录 Session 数量成正比的元数据工作。首次正文准备扫描所有所选 header 并解码直属子正文；复用准备缓存仍扫描成员集合并检查修订。只读访问从不发布升级，因此冷进程与被淘汰的准备缓存会重复这些工作。当前 V4 正文读取和修订号避开历史全库扫描。见[实测成本与诊断命令](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements)。
 
 -----
 
diff --git a/packages/session/session-persistence-jsonl/src/catalog-migration.ts b/packages/session/session-persistence-jsonl/src/catalog-migration.ts
new file mode 100644
index 0000000000..f07d5179a7
--- /dev/null
+++ b/packages/session/session-persistence-jsonl/src/catalog-migration.ts
@@ -0,0 +1,88 @@
+/** Collect historical discovery facts without recursively preparing related current generations. */
+
+import { stat } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { historicalSessionFormatCatalog, sessionFormatCatalog } from '@deepseek-ai/dsh-session-format-catalog'
+import { historicalChildCatalogSource } from '@deepseek-ai/dsh-session-format-v3-to-v4'
+import { SessionFormatUnsupportedMigrationError } from '@deepseek-ai/dsh-session-format'
+import type { SessionFormatJsonObject } from '@deepseek-ai/dsh-session-format'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { parseGenerationLogFilename } from './format.ts'
+import type { JsonlCompression } from './format.ts'
+import { JsonlGenerationSourceChangedError, readDecodedJsonlSource } from './generation.ts'
+import type { JsonlPhysicalIdentity } from './generation.ts'
+
+/** Per-parent supplemental facts and the source checks required before serving or publishing them. */
+interface PreparedCatalogFacts {
+  readonly facts: readonly SessionFormatJsonObject[]
+  readonly failures: readonly { readonly path: string; readonly error: unknown }[]
+  /** @returns resolves while every inspected child still has the captured physical revision. */
+  validate(): Promise<void>
+}
+
+/**
+ * Collect each related child's own descriptor through existing historical codecs.
+ * @param parentId - parent whose incoming migration consumes these facts.
+ * @param sources - header-indexed direct children in the selected source corpus.
+ * @param compression - configured source encoding.
+ * @param signal - cancellation forwarded through each source read.
+ * @returns compact facts and child-local failures; complete child event arrays are released after extraction.
+ */
+export async function prepareCatalogFacts(
+  parentId: SessionId,
+  sources: readonly { readonly header: SessionHeader; readonly path: string }[],
+  compression: JsonlCompression,
+  signal: AbortSignal,
+): Promise<PreparedCatalogFacts> {
+  const facts: SessionFormatJsonObject[] = []
+  const failures: { path: string; error: unknown }[] = []
+  const witnesses: { path: string; identity: JsonlPhysicalIdentity }[] = []
+  for (const source of sources) {
+    signal.throwIfAborted()
+    const version = parseGenerationLogFilename(basename(source.path), compression)
+    if (version === undefined) throw new SessionFormatUnsupportedMigrationError(`unrecognized historical child generation ${source.path}`)
+    const witness: { path: string; identity: JsonlPhysicalIdentity } = {
+      path: source.path, identity: await stat(source.path, { bigint: true }),
+    }
+    witnesses.push(witness)
+    let restored: Awaited<ReturnType<typeof readDecodedJsonlSource>>
+    try {
+      restored = await readDecodedJsonlSource(source.path, version, compression, {
+        createRestore: header => (version <= 3 ? historicalSessionFormatCatalog : sessionFormatCatalog).createRestore(header, {
+          recovery: 'recoverable', validation: 'current',
+        }),
+      }, signal)
+    } catch (error: unknown) {
+      signal.throwIfAborted()
+      failures.push({ path: source.path, error })
+      continue
+    }
+    witness.identity = restored.identity
+    const header = restored.artifact.header
+    if (header.id !== source.header.id || header.createdAt !== source.header.createdAt
+      || header.parentSession !== parentId || header.origin !== 'subagent'
+      || ['cwd', 'isSeeded', 'delegationDepth', 'agentPreset'].some(key => header[key] !== source.header[key as keyof SessionHeader])) {
+      throw new JsonlGenerationSourceChangedError(source.path)
+    }
+    let fact: SessionFormatJsonObject
+    try {
+      fact = historicalChildCatalogSource(restored.artifact)
+    } catch (error: unknown) {
+      failures.push({ path: source.path, error })
+      continue
+    }
+    facts.push({ ...fact, sourcePath: source.path })
+  }
+  return {
+    facts,
+    failures,
+    async validate() {
+      for (const witness of witnesses) {
+        const current = await stat(witness.path, { bigint: true })
+        if (current.dev !== witness.identity.dev || current.ino !== witness.identity.ino
+          || current.size !== witness.identity.size || current.mtimeNs !== witness.identity.mtimeNs
+          || current.ctimeNs !== witness.identity.ctimeNs) throw new JsonlGenerationSourceChangedError(witness.path)
+      }
+    },
+  }
+}
diff --git a/packages/session/session-persistence-jsonl/src/generation.ts b/packages/session/session-persistence-jsonl/src/generation.ts
index 001c2dbc40..ff01e9a038 100644
--- a/packages/session/session-persistence-jsonl/src/generation.ts
+++ b/packages/session/session-persistence-jsonl/src/generation.ts
@@ -28,6 +28,7 @@ import { constants, createZstdCompress } from 'node:zlib'
 import { Session } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { BlockAssembler, expandAssistantStream } from '@deepseek-ai/dsh-llm'
+import { SessionFormatError } from '@deepseek-ai/dsh-session-format'
 import type {
   SessionFormatArtifact,
   SessionFormatJsonValue,
@@ -68,6 +69,8 @@ export interface JsonlGenerationFormatAdapter {
 
 /** Inputs for preparing one historical generation and publishing its current successor later. */
 export interface PrepareJsonlMigrationOptions {
+  /** Revalidate related source facts before preparation returns and immediately before publication. */
+  readonly validateRelatedSources?: () => Promise<void>
   /** Immutable generation selected by the backend resolver. */
   readonly sourcePath: string
   /** Version selected from the source filename and independently checked against its header. */
@@ -900,6 +903,7 @@ async function publishPreparedMigration(
       throw new Error('staged session generation changed during verification')
     }
     await internals.barrier('before-source-check', 1)
+    await options.validateRelatedSources?.()
     const beforePublish = await internals.fs.stat(sourcePath)
     if (identity(beforePublish) !== identity(sourceIdentity)) {
       throw new JsonlGenerationSourceChangedError(sourcePath)
@@ -974,6 +978,7 @@ async function prepareMigration(
   if (artifact.header.version !== format.currentVersion) {
     throw new Error(`format migration returned v${artifact.header.version}, expected v${format.currentVersion}`)
   }
+  await options.validateRelatedSources?.()
   const sourceIdentity = source.identity
   let publication: Promise<JsonlPhysicalIdentity> | undefined
   return {
@@ -1024,3 +1029,31 @@ export function createJsonlGenerationRuntime(
 }
 
 const defaultGenerationRuntime = createJsonlGenerationRuntime()
+
+/**
+ * Read one stable source through the shared streaming parser without publishing a generation.
+ * @param path - selected source generation path.
+ * @param version - physical source version identified by its filename.
+ * @param compression - source encoding.
+ * @param format - codec/restore factory, independent of current-generation publication.
+ * @param signal - cancellation observed during source reads and decode yields.
+ * @returns decoded artifact and physical source identity for later revalidation.
+ * @throws SessionFormatError for physical decoding failures; storage, cancellation, and unsupported migration errors retain their category.
+ */
+export async function readDecodedJsonlSource(
+  path: string,
+  version: number,
+  compression: JsonlCompression,
+  format: Pick<JsonlGenerationFormatAdapter, 'createRestore'>,
+  signal?: AbortSignal,
+): Promise<{ artifact: SessionFormatArtifact; identity: JsonlPhysicalIdentity }> {
+  const source = await readStableJsonlFile(path, signal)
+  let artifact: SessionFormatArtifact
+  try {
+    artifact = await decodeStreamingMigration(source.bytes, compression, version, format, undefined, signal)
+  } catch (error: unknown) {
+    if (signal?.aborted || error instanceof SessionFormatError) throw error
+    throw new SessionFormatError(String(error), { cause: error })
+  }
+  return { artifact, identity: source.identity }
+}
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 3efafa4b6d..e5046b45ad 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -9,6 +9,7 @@
 import { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import {
+  createSessionFormatCatalogWithChildren,
   SessionFormatUnsupportedMigrationError,
   sessionFormatCatalog,
 } from '@deepseek-ai/dsh-session-format-catalog'
@@ -17,7 +18,7 @@ import { open, mkdir, readdir, realpath, link, rm, stat, truncate } from 'node:f
 import { dirname, join, resolve } from 'node:path'
 import { performance } from 'node:perf_hooks'
 import { scheduler } from 'node:timers/promises'
-import { randomBytes } from 'node:crypto'
+import { createHash, randomBytes } from 'node:crypto'
 import {
   SessionPersistence, SessionPersistenceRevision, SessionFormatUnsupportedError,
   SessionPersistenceCorruptionError,
@@ -44,6 +45,7 @@ import {
 } from './zstd.ts'
 import { ensureDurableDirectoryWin32, publishNewFileWin32 } from './win32.ts'
 import { verifyCurrentGenerationInWorker } from './migration-verifier.ts'
+import { prepareCatalogFacts } from './catalog-migration.ts'
 import {
   JsonlGenerationSourceChangedError,
   JsonlGenerationUnsupportedMigrationError,
@@ -122,6 +124,7 @@ interface CurrentStoredLog extends StoredLogBase {
 /** A migrated historical generation retained until an explicit write open publishes it. */
 interface PreparedStoredLog extends StoredLogBase {
   readonly status: 'prepared'
+  readonly validateRelatedSources: () => Promise<void>
   readonly publication: {
     readonly source: ResolvedJsonlGeneration
     readonly value: PreparedJsonlMigration
@@ -252,7 +255,7 @@ class JsonlSessionPersistence extends SessionPersistence {
   private compression: JsonlCompression
   private rootEncodingCheck: Promise<void> | undefined
   private readonly tracker = new JsonlBackendTracker(this.name)
-  private readonly generationFormat: JsonlGenerationFormatAdapter
+  private readonly generationFormat: Omit<JsonlGenerationFormatAdapter, 'createRestore'>
   /**
    * Bounded LRU of parsed, validated stored logs keyed by session id and
    * guarded by the stat-derived revision, so an immediate cold-read handoff
@@ -278,9 +281,6 @@ class JsonlSessionPersistence extends SessionPersistence {
     this.compression = config.compression ?? DEFAULT_COMPRESSION
     this.generationFormat = {
       currentVersion: sessionFormatCatalog.currentVersion,
-      createRestore: header => sessionFormatCatalog.createRestore(header, {
-        recovery: 'recoverable', validation: 'transformed',
-      }),
       encodeHeader: (header, inheritedEventCount) =>
         sessionFormatCatalog.encodeCurrentHeader(header, inheritedEventCount),
       encodeEvent: event => sessionFormatCatalog.encodeCurrentEvent(event),
@@ -348,7 +348,13 @@ class JsonlSessionPersistence extends SessionPersistence {
       if (pending !== undefined) {
         return this.tracker.adopt(new JsonlSessionHandle(this, id, pending.header, 'read', { cursor: 0, materialized: false, inheritedEventCount: pending.inheritedEventCount }))
       }
-      const stored = await this.requireStoredLog(id, options?.signal)
+      let stored: StoredLog
+      try {
+        stored = await this.requireStoredLog(id, options?.signal)
+      } catch (error: unknown) {
+        if (!(error instanceof JsonlGenerationSourceChangedError)) throw error
+        stored = await this.requireStoredLog(id, options?.signal)
+      }
       let state: StorageHandleState
       if (stored.status === 'prepared') {
         state = {
@@ -448,7 +454,9 @@ class JsonlSessionPersistence extends SessionPersistence {
       options?.signal?.throwIfAborted()
       return {
         header,
-        revision: fileRevision(identity),
+        revision: selected.sourceVersion < SESSION_FORMAT_VERSION
+          ? SessionPersistenceRevision(`${fileRevision(identity)}:${await this.historicalCorpusRevision(options?.signal)}`)
+          : fileRevision(identity),
         sizeBytes: Number(identity.size),
       }
     } catch (error: unknown) {
@@ -473,6 +481,8 @@ class JsonlSessionPersistence extends SessionPersistence {
     // predate the scan), so create-to-list visibility never has a hole.
     const pending = [...this.tracker.pendingEntries()]
     const artifacts = await this.listArtifacts(signal)
+    const corpusRevision = artifacts.some(artifact => artifact.sourceVersion < SESSION_FORMAT_VERSION)
+      ? await this.historicalCorpusRevision(signal) : undefined
     for (const artifact of artifacts) {
       signal?.throwIfAborted()
       try {
@@ -481,7 +491,9 @@ class JsonlSessionPersistence extends SessionPersistence {
         listed.add(artifact.header.id)
         snapshots.push({
           header: artifact.header,
-          revision: fileRevision(identity),
+          revision: artifact.sourceVersion < SESSION_FORMAT_VERSION
+            ? SessionPersistenceRevision(`${fileRevision(identity)}:${corpusRevision}`)
+            : fileRevision(identity),
           sizeBytes: Number(identity.size),
         })
       } catch (error: unknown) {
@@ -574,6 +586,12 @@ class JsonlSessionPersistence extends SessionPersistence {
     signal.throwIfAborted()
     const memoized = this.coldLogMemo.get(id)
     if (memoized?.status === 'prepared' && memoized.revision === sourceRevision) {
+      try {
+        await memoized.validateRelatedSources()
+      } catch (error: unknown) {
+        this.coldLogMemo.delete(id)
+        throw this.generationFailure(id, selected, error)
+      }
       this.coldLogMemo.delete(id)
       this.coldLogMemo.set(id, memoized)
       return memoized
@@ -609,13 +627,36 @@ class JsonlSessionPersistence extends SessionPersistence {
     signal: AbortSignal,
   ): Promise<PreparedStoredLog> {
     let prepared: Awaited<ReturnType<typeof prepareJsonlMigration>>
+    let validateRelatedSources: () => Promise<void>
     try {
+      const children = async () => (await this.listArtifacts(signal))
+        .filter(source => source.header.origin === 'subagent' && source.header.parentSession === id)
+      const sources = await children()
+      const related = await prepareCatalogFacts(id, sources, this.compression, signal)
+      for (const failure of related.failures) {
+        this.ctx.logger.warn(`${this.name}: session "${id}" catalog omitted an unreadable child (raw log: ${failure.path}): ${String(failure.error)}`)
+      }
+      const membership = sources.map(source => source.path).sort()
+      validateRelatedSources = async () => {
+        const current = (await children()).map(source => source.path).sort()
+        const before = new Set(membership)
+        const after = new Set(current)
+        const changed = current.find(path => !before.has(path)) ?? membership.find(path => !after.has(path))
+        if (changed !== undefined) throw new JsonlGenerationSourceChangedError(changed)
+        await related.validate()
+      }
       prepared = await prepareJsonlMigration({
         sourcePath: selected.sourcePath,
         sourceVersion: selected.sourceVersion,
         currentPath: selected.currentPath,
         compression: this.compression,
-        format: this.generationFormat,
+        format: {
+          ...this.generationFormat,
+          createRestore: header => createSessionFormatCatalogWithChildren(related.facts).createRestore(header, {
+            recovery: 'recoverable', validation: 'transformed',
+          }),
+        },
+        validateRelatedSources,
         verifyCurrentFile: verifyCurrentGenerationInWorker,
         validateHistoricalHeader: headerValue => this.validateSourceIdentity(
           selected,
@@ -634,6 +675,7 @@ class JsonlSessionPersistence extends SessionPersistence {
     validateStoredEvents(meta, events, { kind: 'jsonl', path: selected.sourcePath })
     const stored: PreparedStoredLog = {
       status: 'prepared',
+      validateRelatedSources,
       meta,
       ...freezeStoredEvents(events),
       tornTruncateTo: undefined,
@@ -992,6 +1034,25 @@ class JsonlSessionPersistence extends SessionPersistence {
     return sources
   }
 
+  /** Historical logical events depend on the corpus, including members with unreadable headers. */
+  private async historicalCorpusRevision(signal?: AbortSignal): Promise<string> {
+    const paths = (await this.listGenerations(signal)).map(source => source.sourcePath).sort()
+    const hash = createHash('sha256')
+    for (const path of paths) {
+      signal?.throwIfAborted()
+      let revision: string
+      try {
+        revision = fileRevision(await stat(path, { bigint: true }))
+      } catch (error: unknown) {
+        if (!isENOENT(error)) throw error
+        revision = 'missing'
+      }
+      hash.update(JSON.stringify([path, revision]))
+    }
+    signal?.throwIfAborted()
+    return hash.digest('hex')
+  }
+
   private async listArtifacts(
     signal?: AbortSignal,
   ): Promise<Array<{ header: SessionHeader; path: string; sourceVersion: number }>> {
diff --git a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
index ec9acb1b74..209cc851f4 100644
--- a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
@@ -1,18 +1,20 @@
 import { Context } from '@deepseek-ai/cordis'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { SessionId, type SessionHeader } from '@deepseek-ai/dsh-session'
 import { SessionFormatUnsupportedError, SessionPersistenceCorruptionError } from '@deepseek-ai/dsh-session-persistence'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { generationLogPath } from '../src/format.ts'
+import { prepareCatalogFacts } from '../src/catalog-migration.ts'
 import { compressZstdFrame } from '../src/zstd.ts'
 
 const roots: string[] = []
 const contexts: Context[] = []
 
 afterEach(async () => {
+  vi.restoreAllMocks()
   await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
   await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })))
 })
@@ -56,6 +58,29 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     await expect(f.ctx.sessionPersistence.open(f.parent, access)).rejects.toThrow('wrong Session')
   })
 
+  it('opens the parent when another Session header cannot be read', async () => {
+    const f = await fixture()
+    const path = await f.write('child', [], true)
+    await writeFile(path, compression === 'none' ? '{broken header\n' : await compressZstdFrame('{broken header\n'))
+    expect(await f.read()).toEqual([])
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+    expect(await readFile(generationLogPath(f.root, undefined, f.parent, 4, compression))).not.toHaveLength(0)
+  })
+
+  it('invalidates lightweight revisions on child membership and contents while retaining stable tokens', async () => {
+    const f = await fixture()
+    const revision = async () => (await f.ctx.sessionPersistence.stat(f.parent))!.revision
+    const first = await revision()
+    expect(await revision()).toBe(first)
+    await f.write('child', [f.descriptor], true)
+    const added = await revision()
+    expect(added).not.toBe(first)
+    expect((await f.ctx.sessionPersistence.list()).find(row => row.header.id === f.parent)?.revision).toBe(added)
+    await f.write('child', [f.descriptor, { type: 'feedback/record', seq: 1, time: 3, data: {} }], true)
+    expect(await revision()).not.toBe(added)
+  })
+
   it('reports malformed native catalog data without migration terminology', async () => {
     const f = await fixture()
     await f.write(f.parent, [{ type: 'subagent/catalog', seq: 0, time: 1,
@@ -77,6 +102,46 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).toBe(first)
   })
 
+  it('invalidates historical revisions when selected children disappear or gain an opaque successor', async () => {
+    const f = await fixture()
+    const path = await f.write('child', [f.descriptor], true)
+    const first = (await f.ctx.sessionPersistence.stat(f.parent))!.revision
+    await rm(path)
+    const removed = (await f.ctx.sessionPersistence.stat(f.parent))!.revision
+    expect(removed).not.toBe(first)
+    await f.write('child', [], true, 5)
+    expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).not.toBe(removed)
+    expect((await f.ctx.sessionPersistence.list()).find(row => row.header.id === f.parent)?.revision).not.toBe(removed)
+  })
+
+  it('isolates a corrupt child catalog and reports its path', async () => {
+    const f = await fixture()
+    const warn = vi.spyOn(f.ctx.logger, 'warn')
+    const catalog = { type: 'subagent/catalog', seq: 0, time: 1,
+      data: { version: 0, childId: 'grandchild', childCreatedAt: 3, mode: 'one-shot' } }
+    const path = await f.write('child', [catalog, { ...catalog, seq: 1 }], true, 4)
+    expect(await f.read()).toEqual([])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
+  })
+
+  it.each(['read', 'write'] as const)('isolates malformed child JSON during parent %s access', async (access) => {
+    const f = await fixture()
+    const childPath = await f.write('child', [], true)
+    const first = JSON.stringify({ ...f.header, id: 'child', origin: 'subagent', parentSession: f.parent, delegationDepth: 1 }) + '\n'
+    const body = '{broken\n' + JSON.stringify({ type: 'turn/end', seq: 1, time: 2,
+      data: { turn: 1, reason: { kind: 'completed' } } }) + '\n'
+    await writeFile(childPath, compression === 'none' ? first + body
+      : Buffer.concat([await compressZstdFrame(first), await compressZstdFrame(body)]))
+    const original = await readFile(childPath)
+    await f.write('healthy', [f.descriptor], true)
+    const parent = await f.ctx.sessionPersistence.open(f.parent, access)
+    try { expect((await parent.read()).events).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'healthy' } }]) } finally { await parent.close() }
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), access)).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
+    expect(await readFile(childPath)).toEqual(original)
+    await expect(readFile(generationLogPath(f.root, undefined, SessionId('child'), 4, compression))).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
   it('preserves opaque inherited catalogs through read preparation and write publication', async () => {
     const f = await fixture()
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
@@ -98,6 +163,14 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect(await readFile(parentPath)).toEqual(original)
   })
 
+  it.skipIf(compression !== 'zstd')('isolates invalid compressed child frames', async () => {
+    const f = await fixture()
+    const childPath = await f.write('child', [], true)
+    await writeFile(childPath, Buffer.concat([await readFile(childPath), Buffer.alloc(8)]))
+    expect(await f.read()).toEqual([])
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
+  })
+
   it('keeps a complete parent catalog when a published child never writes a descriptor', async () => {
     const f = await fixture()
     const catalog = { type: 'subagent/catalog', seq: 0, time: 2,
@@ -112,6 +185,18 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
   })
 
+  it.each([1, 2, 3])('backfills a missing catalog from descriptor v%i', async (version) => {
+    const f = await fixture()
+    const data = version === 1 ? { version, provider: 'spawn', label: 'old child' }
+      : { ...f.descriptor.data, version }
+    await f.write('child', [{ ...f.descriptor, data }], true)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: {
+      childId: 'child', childCreatedAt: 2, mode: 'continuable', label: 'old child',
+    } }])
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+  })
+
   it.each(['missing', 'unknown', 'multiple'] as const)('publishes the parent without invented %s child discovery information', async (kind) => {
     const f = await fixture()
     const events = kind === 'missing' ? [] : kind === 'unknown'
@@ -131,6 +216,39 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
       .toEqual(compression === 'none' ? ['session.v3.jsonl', 'session.v4.jsonl'] : ['session.v3.jsonl.zstd', 'session.v4.jsonl.zstd'])
   })
 
+  it.each([false, true])('omits an unsupported child generation (prepared=%s)', async (prepared) => {
+    const f = await fixture()
+    await f.write('child', [f.descriptor], true)
+    if (prepared) expect(await f.read()).toHaveLength(1)
+    await f.write('child', [], true, 5)
+    expect(await f.read()).toEqual([])
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
+  })
+
+  it('opens the parent independently of an unrelated future generation', async () => {
+    const f = await fixture()
+    await f.write('future-root', [], false, 5)
+    expect((await f.ctx.sessionPersistence.list()).map(row => row.header.id)).toEqual([f.parent])
+    expect(await f.read()).toEqual([])
+  })
+
+  it('omits unsupported child contents without migrating the child', async () => {
+    const f = await fixture()
+    await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    expect(await f.read()).toEqual([])
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
+  })
+
+  it('omits invalid descriptor fields and reports the child source', async () => {
+    const f = await fixture()
+    const warn = vi.spyOn(f.ctx.logger, 'warn')
+    const path = await f.write('child', [{ ...f.descriptor, data: { version: 2, provider: 'spawn', mode: 'unknown' } }], true)
+    expect(await f.read()).toEqual([])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
+  })
+
   it.each(['read', 'write'] as const)('rejects duplicate own catalogs through a current %s open', async (access) => {
     const f = await fixture()
     const catalog = { type: 'subagent/catalog', seq: 0, time: 2,
@@ -139,73 +257,153 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     await expect(f.ctx.sessionPersistence.open(f.parent, access)).rejects.toThrow('duplicate catalog child')
   })
 
-  it.each(['read', 'write'] as const)('isolates malformed child JSON until explicit %s access', async (access) => {
+  it('recollects a changed child within the same read open', async () => {
+    const f = await fixture()
+    await f.write('child', [f.descriptor], true)
+    expect(await f.read()).toHaveLength(1)
+    await f.write('child', [f.descriptor, { type: 'feedback/record', seq: 1, time: 3, data: { text: 'appended' } }], true)
+    expect(await f.read()).toHaveLength(1)
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+  })
+
+  it('detects children added after preparation instead of publishing incomplete membership', async () => {
+    const f = await fixture()
+    expect(await f.read()).toEqual([])
+    await f.write('child', [f.descriptor], true)
+    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(generationLogPath(f.root, undefined, SessionId('child'), 3, compression))
+    expect(await f.read()).toHaveLength(1)
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+  })
+
+  it('recollects newly available discovery fields before publishing a prepared parent', async () => {
     const f = await fixture()
     const childPath = await f.write('child', [], true)
-    const first = JSON.stringify({ ...f.header, id: 'child', origin: 'subagent', parentSession: f.parent, delegationDepth: 1 }) + '\n'
-    const body = '{broken\n' + JSON.stringify({ type: 'turn/end', seq: 1, time: 2,
-      data: { turn: 1, reason: { kind: 'completed' } } }) + '\n'
-    await writeFile(childPath, compression === 'none' ? first + body
-      : Buffer.concat([await compressZstdFrame(first), await compressZstdFrame(body)]))
-    const original = await readFile(childPath)
-    const parent = await f.ctx.sessionPersistence.open(f.parent, access)
-    try { expect((await parent.read()).events).toEqual([]) } finally { await parent.close() }
-    await expect(f.ctx.sessionPersistence.open(SessionId('child'), access)).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
-    expect(await readFile(childPath)).toEqual(original)
-    expect((await readdir(dirname(childPath))).filter(name => name !== 'session.lock'))
+    expect(await f.read()).toEqual([])
+    await f.write('child', [f.descriptor], true)
+    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(childPath)
+    const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
+    expect((await readdir(dirname(parentPath))).filter(name => name !== 'session.lock'))
       .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
-    expect(await f.read()).toEqual([])
-  })
-
-  it.each([true, false])('opens the parent independently of unsupported related=%s generations', async (related) => {
-    const f = await fixture()
-    await f.write('future', [], related, 5)
-    expect(await f.read()).toEqual([])
-    const parent = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    await parent.close()
-    await expect(f.ctx.sessionPersistence.open(SessionId('future'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-  })
-
-  it('keeps unreadable child headers outside parent migration', async () => {
-    const f = await fixture()
-    const path = await f.write('child', [], true)
-    await writeFile(path, compression === 'none' ? '{broken\n' : await compressZstdFrame('{broken\n'))
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', label: 'old child' } }])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
     await writer.close()
   })
 
-  it('keeps revisions and prepared parent history independent of child membership and contents', async () => {
+  it('reads current children without recursive migration and preserves current parent fast reads', async () => {
     const f = await fixture()
-    const first = (await f.ctx.sessionPersistence.stat(f.parent))!.revision
+    await f.write('child', [f.descriptor], true, 4)
+    expect(await f.read()).toHaveLength(1)
+    await f.write(f.parent, [], false, 4)
+    await f.write('child', [], true, 4)
     expect(await f.read()).toEqual([])
-    const path = await f.write('child', [f.descriptor], true)
-    expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).toBe(first)
-    await f.write('child', [{ ...f.descriptor, data: { ...f.descriptor.data, label: 'changed' } }], true)
-    expect((await f.ctx.sessionPersistence.list()).find(row => row.header.id === f.parent)?.revision).toBe(first)
-    await rm(path)
-    expect((await f.ctx.sessionPersistence.stat(f.parent))!.revision).toBe(first)
-    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    try { expect((await writer.read()).events).toEqual([]) } finally { await writer.close() }
   })
 
-  it.each([0, 1, 2, 3])('migrates a V%i child only on its own write open and preserves predecessors', async (version) => {
+  it('refuses publication when a related child disappears', async () => {
     const f = await fixture()
-    await rm(generationLogPath(f.root, undefined, f.parent, 3, compression))
+    const path = await f.write('child', [f.descriptor], true)
+    const header = { ...f.header, id: SessionId('child'), origin: 'subagent', parentSession: f.parent, createdAt: 2, delegationDepth: 1 } as SessionHeader
+    const prepare = () => prepareCatalogFacts(f.parent, [{ path, header }], compression, new AbortController().signal)
+    const prepared = await prepare()
+    await rm(path)
+    await expect(prepared.validate()).rejects.toMatchObject({ code: 'ENOENT' })
+    await expect(prepare()).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
+  it('rejects changed header identities and invalid source selection', async () => {
+    const f = await fixture()
+    const path = await f.write('child', [f.descriptor], true)
+    const header = { ...f.header, id: SessionId('wrong-child'), origin: 'subagent', parentSession: f.parent } as SessionHeader
+    const signal = new AbortController().signal
+    await expect(prepareCatalogFacts(f.parent, [{ path, header }], compression, signal)).rejects.toThrow('changed')
+    await expect(prepareCatalogFacts(f.parent, [{ path: path + '.foreign', header }], compression, signal)).rejects.toThrow('unrecognized historical child generation')
+    const controller = new AbortController()
+    controller.abort(new Error('cancelled child collection'))
+    await expect(prepareCatalogFacts(f.parent, [{ path, header }], compression, controller.signal)).rejects.toThrow('cancelled child collection')
+  })
+
+  it.each([0, 1, 2])('composes a V%i parent and child through all preceding edges', async (version) => {
+    const f = await fixture()
+    const initial = generationLogPath(f.root, undefined, f.parent, 3, compression)
+    await rm(initial)
     const parentPath = await f.write(f.parent, [], false, version)
     const childPath = await f.write('child', [f.descriptor], true, version)
-    const original = await Promise.all([readFile(parentPath), readFile(childPath)])
-    expect(await f.read()).toEqual([])
+    const before = await Promise.all([readFile(parentPath), readFile(childPath)])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', seq: 0, data: { childId: 'child', mode: 'continuable', label: 'old child' } }])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
     await writer.close()
-    const childSuccessor = generationLogPath(f.root, undefined, SessionId('child'), 4, compression)
-    await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' })
-    const childReader = await f.ctx.sessionPersistence.open(SessionId('child'), 'read')
-    try { expect((await childReader.read()).events).toEqual([f.descriptor]) } finally { await childReader.close() }
-    await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' })
-    const childWriter = await f.ctx.sessionPersistence.open(SessionId('child'), 'write')
-    await childWriter.close()
-    expect((await readFile(childSuccessor)).length).toBeGreaterThan(0)
-    expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
+    expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(before)
+    expect((await readdir(dirname(parentPath))).filter(name => name !== 'session.lock')).toHaveLength(2)
+  })
+
+  it('lists historical headers, prepares read-only membership, and publishes an unchanged-prefix successor', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-catalog-migration-'))
+    roots.push(root)
+    const parent = SessionId('parent')
+    const child = SessionId('child')
+    const header = { type: 'session', version: 3, id: parent, createdAt: 1, isSeeded: false, delegationDepth: 0 }
+    const childHeader = { ...header, id: child, createdAt: 2, origin: 'subagent', parentSession: parent, delegationDepth: 1 }
+    const descriptor = { type: 'subagent/descriptor', seq: 0, time: 2, data: { version: 3, mode: 'one-shot', provider: 'spawn', label: 'old child' } }
+    const sourcePaths: string[] = []
+    for (const [meta, events] of [[header, []], [childHeader, [descriptor]]] as const) {
+      const path = generationLogPath(root, undefined, meta.id, 3, compression)
+      sourcePaths.push(path)
+      await mkdir(dirname(path), { recursive: true })
+      const first = Buffer.from(JSON.stringify(meta) + '\n')
+      const body = Buffer.from(events.map(event => JSON.stringify(event) + '\n').join(''))
+      await writeFile(path, compression === 'none' ? Buffer.concat([first, body])
+        : Buffer.concat([await compressZstdFrame(first), ...(body.length === 0 ? [] : [await compressZstdFrame(body)])]))
+    }
+    const original = await Promise.all(sourcePaths.map(path => readFile(path)))
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(JsonlSessionPersistence, { root, compression })
+    expect((await ctx.sessionPersistence.list()).map(row => row.header.id).sort()).toEqual([child, parent])
+    const reader = await ctx.sessionPersistence.open(parent, 'read')
+    let expected
+    try {
+      expect(reader.header.version).toBe(4)
+      expected = (await reader.read()).events
+      expect(expected).toEqual([{ type: 'subagent/catalog', seq: 0, time: 1, data: {
+        version: 0, childId: child, childCreatedAt: 2, mode: 'one-shot', label: 'old child',
+      } }])
+      expect(await readdir(dirname(sourcePaths[0]!))).toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
+    } finally { await reader.close() }
+    const writer = await ctx.sessionPersistence.open(parent, 'write')
+    try { expect((await writer.read()).events).toEqual(expected) } finally { await writer.close() }
+    expect(await Promise.all(sourcePaths.map(path => readFile(path)))).toEqual(original)
+    const reopened = await ctx.sessionPersistence.open(parent, 'read')
+    try { expect((await reopened.read()).events).toEqual(expected) } finally { await reopened.close() }
+  })
+
+  it('recollects a repaired child before publishing a prepared parent', async () => {
+    const f = await fixture()
+    await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    expect(await f.read()).toEqual([])
+    await f.write('child', [f.descriptor], true)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child' } }])
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+  })
+
+  it('completes only the opened parent catalog and defers its child catalog', async () => {
+    const f = await fixture()
+    const childPath = await f.write('child', [f.descriptor], true)
+    const grandchildPath = await f.write('grandchild', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    // Reparent the physical fixture so only opening the child can inspect this damaged log.
+    const first = JSON.stringify({ ...f.header, id: 'grandchild', origin: 'subagent', parentSession: 'child', createdAt: 3, delegationDepth: 2 }) + '\n'
+    const body = JSON.stringify({ type: 'future/required', seq: 0, time: 3, data: {} }) + '\n'
+    await writeFile(grandchildPath, compression === 'none' ? first + body : Buffer.concat([await compressZstdFrame(first), await compressZstdFrame(body)]))
+    const warn = vi.spyOn(f.ctx.logger, 'warn')
+    const source = await readFile(childPath)
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    try { expect((await writer.read()).events).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child' } }]) } finally { await writer.close() }
+    expect(warn).not.toHaveBeenCalled()
+    expect(await readFile(childPath)).toEqual(source)
+    await expect(readFile(generationLogPath(f.root, undefined, SessionId('child'), 4, compression))).rejects.toMatchObject({ code: 'ENOENT' })
+    const child = await f.ctx.sessionPersistence.open(SessionId('child'), 'write')
+    await child.close()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(grandchildPath))
   })
 })
diff --git a/packages/session/session-persistence-jsonl/tests/generation.spec.ts b/packages/session/session-persistence-jsonl/tests/generation.spec.ts
index 398066f704..4d398dca4b 100644
--- a/packages/session/session-persistence-jsonl/tests/generation.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/generation.spec.ts
@@ -23,6 +23,7 @@ import {
   JsonlGenerationTargetConflictError,
   JsonlGenerationUnsupportedMigrationError,
   prepareJsonlMigration,
+  readDecodedJsonlSource,
   verifyJsonlCurrentGeneration,
   type JsonlGenerationFormatAdapter,
   type PrepareJsonlMigrationOptions,
@@ -86,6 +87,19 @@ function header(version: number, id = 'generation-test'): Record<string, unknown
 const event0 = { type: 'turn/start', seq: 0, time: 2, data: { turn: 1 } }
 const event1 = { type: 'turn/end', seq: 1, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }
 
+it('preserves cancellation raised while creating a child source decoder', async () => {
+  const path = join(await tempRoot(), 'session.v3.jsonl')
+  await writeFile(path, line(header(3)))
+  const controller = new AbortController()
+  const reason = new Error('child decoding cancelled')
+  await expect(readDecodedJsonlSource(path, 3, 'none', {
+    createRestore() {
+      controller.abort(reason)
+      throw reason
+    },
+  }, controller.signal)).rejects.toBe(reason)
+})
+
 const assistantUsage = { inputTokens: 3, outputTokens: 2 }
 const assistantReplayState = { response: { id: 'response' } }
 
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index d2f3e3868a..114b7f364e 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -1211,7 +1211,7 @@ describe('JsonlSessionPersistence: immutable format generations', () => {
       .rejects.toThrow(/released v0 physical header lacks required member "type"/)
   })
 
-  it('keeps historical revisions independent of another Session storage faults', async () => {
+  it('tracks a disappearing corpus member and propagates its storage faults in historical revisions', async () => {
     const parent = meta('corpus-revision-parent', '/work')
     const child = meta('corpus-revision-child', '/work')
     for (const header of [parent, child]) {
@@ -1224,10 +1224,10 @@ describe('JsonlSessionPersistence: immutable format generations', () => {
     statFailure.error = Object.assign(new Error('member disappeared'), { code: 'ENOENT' })
     const missing = await ctx.sessionPersistence.stat(parent.id)
     expect(missing).toBeDefined()
-    expect(missing?.revision).toBe(present?.revision)
+    expect(missing?.revision).not.toBe(present?.revision)
     expect((await ctx.sessionPersistence.stat(parent.id))?.revision).toBe(missing?.revision)
     statFailure.error = Object.assign(new Error('member denied'), { code: 'EACCES' })
-    expect((await ctx.sessionPersistence.stat(parent.id))?.revision).toBe(present?.revision)
+    await expect(ctx.sessionPersistence.stat(parent.id)).rejects.toBe(statFailure.error)
   })
 
   it('surfaces source-read storage faults and aborts unwrapped during migration', async () => {
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index ba1f32a337..f2d1e1d365 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 8351ff4aac8c3585ab0230cf5dbd1c2a4613adc7
-README.zh.md: 90806e0728acf61178e3d9914ec4c7bf0fa1a83c
+README.md: 7d62e423189906c49d9479bd7a6dbd14b7303afd
+README.zh.md: af62ad97bc4821222d46ed73509c823851953e1d
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 8351ff4aac..7d62e42318 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -60,7 +60,7 @@ One-shot children run once and settle with a single result, plus an optional str
 
 ### Messaging, interrupting, and discovering
 
-Every exact live Agent can use `sendMessage()` with a direct continuable child; a resident continuable child can also use it with its direct parent. A working target receives the Agent message through Steer at its nearest step; an idle target starts a turn, and only a direct child can be cold-resumed. The parent can also interrupt a running descendant or list its children at any time. A browser continuation prompt independently selects Queue or Steer and may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Direct-child discovery reads the parent-owned `subagentCatalog` projection and Session headers. `listChildren(parentSessionId, signal?)` returns catalog entries in parent event order, then header-discovered children with `mode: 'unresolved'`; it never opens child bodies. It forwards cancellation and releases the parent observation after materialization. Header enumeration costs O(N) for N Sessions, while catalog materialization costs O(D) for D facts. Complete descendant discovery explicitly reads child identity projections; neither path loads or resumes a child Agent.
+Every exact live Agent can use `sendMessage()` with a direct continuable child; a resident continuable child can also use it with its direct parent. A working target receives the Agent message through Steer at its nearest step; an idle target starts a turn, and only a direct child can be cold-resumed. The parent can also interrupt a running descendant or list its children at any time. A browser continuation prompt independently selects Queue or Steer and may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Direct-child discovery reads the parent-owned `subagentCatalog` projection. `listChildren(parentSessionId, signal?)` owns a live-preferred Session observation and returns the catalog asynchronously without reading child logs. It forwards cancellation and releases the observation after materialization. Materialization preserves parent event order in O(D) time for D facts. Complete descendant discovery retains the Session corpus and child identity projection; neither path loads or resumes a child Agent.
 
 ### Failure and recovery
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 90806e0728..af62ad97bc 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -60,7 +60,7 @@ kind: "package-reference"
 
 ### 消息、中断与发现
 
-每个存活 Agent 都可以通过 `sendMessage()` 向直接可继续子代理发送消息；驻留的可继续子代理也可以向直接父代理发送。工作中的目标在最近步骤通过 Steer 接收消息，空闲目标启动新轮次，只有直接子代理支持冷恢复。父代理可以随时中断运行中的后代或列出子代理。浏览器续接独立选择 Queue 或 Steer，支持图片：Host 在子代理收件箱接收消息前准入并持久化图片，模型不支持图片输入时拒绝交付。直接子代理发现读取父会话的 `subagentCatalog` 投影和会话头部。`listChildren(parentSessionId, signal?)` 按父事件顺序返回 catalog 条目，再返回头部发现的 `mode: 'unresolved'` 子会话，不打开子会话正文。它传递取消信号，并在物化后释放父会话观察。N 个会话的头部枚举为 O(N)，D 条事实的 catalog 物化为 O(D)。完整后代发现显式读取子会话身份投影；两条路径均不加载或恢复子 Agent。
+每个确切在线 Agent 都可以对直接可继续 child 使用 `sendMessage()`；驻留的可继续 child 还可以对自己的直接 parent 使用它。正在工作的目标通过 Steer 在最近 step 接收 Agent 消息；空闲目标启动轮次，且只有直接 child 可以冷恢复。parent 也可以随时中断正在运行的后代或列举自己的子级。浏览器发出的继续执行 prompt 会独立选择 Queue 或 Steer，并且可以携带图片部分：Host 先通过附件存储完成整批图片的准入与持久化，子级 inbox 才接受这条消息；当子级声明的模型不接受图片输入时拒绝投递。 直接子级发现读取 parent 自有的 `subagentCatalog` projection。`listChildren(parentSessionId, signal?)` 持有一次优先实时来源的 Session 观察，异步返回目录，不读取子级日志。它转发取消信号，并在物化后释放观察。物化以 O(D) 时间保留 D 条事实的父日志事件顺序。完整后代发现保留 Session 语料库与子级身份 projection；两条路径都不加载或恢复子级 Agent。
 
 ### 失败与恢复
 
diff --git a/packages/subagent/subagent/src/control-types.ts b/packages/subagent/subagent/src/control-types.ts
index ae478966db..10a8cfc426 100644
--- a/packages/subagent/subagent/src/control-types.ts
+++ b/packages/subagent/subagent/src/control-types.ts
@@ -9,7 +9,6 @@ import type { PromptContentPart } from '@deepseek-ai/dsh-attachment/types'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { SubagentCatalogEntry } from './projection-types.ts'
 
 /**
  * Client-minted identity of one browser prompt, persisted on the exact accepted
@@ -72,13 +71,6 @@ export type SubagentListEntry =
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
 
-/** A direct child whose identity is known from the catalog or awaits an explicit child read. */
-export type SubagentDiscoveryEntry = SubagentCatalogEntry | {
-  readonly id: SessionId
-  readonly createdAt: number
-  readonly mode: 'unresolved'
-}
-
 /** Durable parent/child address that selects subagent transport in the client. */
 export type SubagentAddress =
   & {
@@ -88,8 +80,6 @@ export type SubagentAddress =
   & (
     | { readonly mode: 'one-shot' }
     | { readonly mode: 'continuable' }
-    /** Header-discovered child; opening it resolves its descriptor without granting continuation. */
-    | { readonly mode: 'unresolved' }
   )
 
 /** One human message addressed to a continuable direct child. */
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 406bf9374b..0262c37476 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -76,7 +76,7 @@ import type { SubagentDescendantListEntry } from './list-children.ts'
 import { snapshotSubagentDescriptor } from './descriptor.ts'
 import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts'
 import { establishCatalogChild, subagentCatalogProjectionDefinition } from './catalog.ts'
-import type { SubagentDiscoveryEntry } from './control-types.ts'
+import type { SubagentCatalogEntry } from './projection-types.ts'
 import { deliverSubagentPrompt } from './internal.ts'
 
 export type {} from './catalog.ts'
@@ -366,15 +366,15 @@ export class SubagentRuntime extends TypertRemoteService {
   }
 
   /**
-   * Read the parent's catalog and discover missing direct children from Session headers.
+   * Read the parent's durable direct-child catalog without loading or resuming an Agent.
    * The service owns and releases the live-preferred Session observation.
    * @param parentSessionId - parent whose direct children are requested.
    * @param signal - cancellation forwarded to the Session query.
-   * @returns catalog children in event order, then unresolved children whose bodies remain unread.
+   * @returns catalog children in parent event order.
    * @throws {@link SubagentError} when query or catalog projection is unavailable.
    * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
    */
-  listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDiscoveryEntry[]> {
+  listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]> {
     return listSubagentChildren(this.ctx, parentSessionId, signal)
   }
 
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index 8c3b96c0e0..9de66e771c 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,8 +1,7 @@
 /**
  * Direct-child discovery from a parent-owned `subagent/catalog` projection,
- * with header-only discovery of missing entries, plus complete descendant-tree
- * enumeration from the Session corpus. A direct listing observes one parent
- * and reads no child log. Descendant
+ * plus complete descendant-tree enumeration from the Session corpus. A direct
+ * listing owns one parent observation and reads no child log. Descendant
  * enumeration retains the complete corpus and the child identity projection
  * because ordinary Sessions and one-shot children remain traversal nodes.
  *
@@ -18,7 +17,7 @@ import type { SessionObservation, SessionQueryEngine } from '@deepseek-ai/dsh-se
 import type { SubagentListEntry } from './control-types.ts'
 import { SubagentError } from './error.ts'
 import type { SubagentIdentityProjection } from './projection-types.ts'
-import type { SubagentDiscoveryEntry } from './control-types.ts'
+import type { SubagentCatalogEntry } from './projection-types.ts'
 
 export type { SubagentListEntry } from './control-types.ts'
 
@@ -62,14 +61,14 @@ interface PositionedCandidate {
  * @param ctx - context carrying the Session query service.
  * @param parentSessionId - parent whose direct children are requested.
  * @param signal - cancellation forwarded to the Session observation.
- * @returns catalog rows in event order, followed by header-discovered children without reading their bodies.
+ * @returns direct-child rows in parent catalog event order.
  * @throws {@link SubagentError} when query or catalog projection is unavailable.
  */
 export async function listChildren(
   ctx: Context,
   parentSessionId: SessionId,
   signal?: AbortSignal,
-): Promise<SubagentDiscoveryEntry[]> {
+): Promise<SubagentCatalogEntry[]> {
   const query = ctx.get('sessionQuery')
   if (query === undefined) {
     throw new SubagentError(
@@ -87,15 +86,7 @@ export async function listChildren(
       'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE',
     )
   }
-  const discovered: SubagentDiscoveryEntry[] = [...entries]
-  const known = new Set(entries.map(entry => entry.id))
-  const records = await query.listSessions(signal)
-  for (const { header } of records) {
-    if (header.origin === 'subagent' && header.parentSession === parentSessionId && !known.has(header.id)) {
-      discovered.push({ id: header.id, createdAt: header.createdAt, mode: 'unresolved' })
-    }
-  }
-  return discovered
+  return entries
 }
 
 /**
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index b472c074d6..84bcd8d6be 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -184,7 +184,7 @@ function mutateStoredHeader(
 }
 
 describe('SubagentRuntime.listChildren', () => {
-  it('discovers historical children from headers while leaving their bodies unread', async () => {
+  it('lists historical children through a migrated parent while preserving V3 files', async () => {
     const { ctx, root } = await setup([], { compression: 'none' })
     const parent = SessionId('historical-parent')
     const child = SessionId('historical-child')
@@ -204,18 +204,16 @@ describe('SubagentRuntime.listChildren', () => {
       return { path, content }
     })
 
-    const observe = vi.spyOn(ctx.sessionQuery, 'observeSession')
     expect(await ctx.subagents.listChildren(parent)).toEqual([{
-      id: child, createdAt: 2, mode: 'unresolved',
+      id: child, createdAt: 2, mode: 'continuable', label: 'historical child',
     }])
-    expect(observe.mock.calls.map(([id]) => id)).toEqual([parent])
     for (const { path, content } of originals) {
       expect(readFileSync(path, 'utf8')).toBe(content)
       expect(readdirSync(dirname(path))).toEqual(['session.v3.jsonl'])
     }
   })
 
-  it('lists provider-established children from the parent catalog without a child body read', async () => {
+  it('lists provider-established children from the parent catalog without a corpus or child read', async () => {
     const { ctx, parent } = await setup([textResponse('once'), textResponse('again')])
     const oneShot = await ctx.subagents.start('spawn', {
       prompt: [{ type: 'text', text: 'finish once' }],
@@ -236,7 +234,7 @@ describe('SubagentRuntime.listChildren', () => {
       { id: continuableId, label: 'continuable child', mode: 'continuable' },
     ])
     expect(children.every(child => Number.isFinite(child.createdAt))).toBe(true)
-    expect(listSessions).toHaveBeenCalledOnce()
+    expect(listSessions).not.toHaveBeenCalled()
     expect(observeSession).toHaveBeenCalledOnce()
   })
 
@@ -340,7 +338,7 @@ describe('SubagentRuntime.listChildren', () => {
     }
     expect(chunkLengths).toEqual([1, ...Array.from({ length: 16 }, () => 64)])
     const entries = await ctx.subagents.listChildren(parent.id)
-    expect(listSessions).toHaveBeenCalledOnce()
+    expect(listSessions).not.toHaveBeenCalled()
     expect(entries).toHaveLength(1_025)
     expect(entries.find(entry => entry.id === 'child-064')).toEqual({
       id: SessionId('child-064'), createdAt: 64, mode: 'one-shot',
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index d234a3b96e..b8478ed970 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/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/subagent/tool-subagent-control/README.md
-README.md: 1be0e2b15f6ff36235275f659770c0c92557006e
-README.zh.md: 3ee5e80aabd97df50feee46ea9183dee2916faf2
+README.md: 2cfa000f1ba9f7950b28369a9b7bd3523610b579
+README.zh.md: f2154fde965899e7b4f30271846bce52414b010d
diff --git a/packages/subagent/tool-subagent-control/README.md b/packages/subagent/tool-subagent-control/README.md
index 1be0e2b15f..2cfa000f1b 100644
--- a/packages/subagent/tool-subagent-control/README.md
+++ b/packages/subagent/tool-subagent-control/README.md
@@ -54,7 +54,7 @@ Stops only the target's current turn: queued messages stay parked until a later
 
 ### list_agents
 
-Lists the continuable children below the calling agent: `children` (default) combines parent catalog facts with header discovery without opening child logs; unresolved identities appear as `unavailable` diagnostics. `descendants` explicitly reads identities throughout the tree in stable pre-order and includes durable direct-parent ids and depths. Status comes from the live Agent registry: `running` or `inactive`. Known one-shot children are omitted because they cannot accept `send_message`.
+Lists the continuable children below the calling agent: `children` (default) reads direct children from the parent catalog without opening child logs; `descendants` walks the whole tree in stable pre-order, annotating each entry with its durable direct-parent session id and depth. Status comes from the live Agent registry — `running` or `inactive`. One-shot children are intentionally absent because they cannot accept `send_message`, and unreadable candidates appear as diagnostics only in `descendants` scope.
 
 -----
 
@@ -150,7 +150,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = executing a turn; `inactive` = no turn executing, whether loaded or stored; neither status describes task completion or outcome). Either scope adds `<id> [diagnostic: <reason>]` for a candidate that could not be read. The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection.
+One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = executing a turn; `inactive` = no turn executing, whether loaded or stored; neither status describes task completion or outcome). Only `descendants` scope adds `<id> [diagnostic: <reason>]` for a candidate that could not be read. The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection.
 
 #### Token effect
 
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index 3ee5e80aab..f2154fde96 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -54,7 +54,7 @@ kind: "package-reference"
 
 ### list_agents
 
-列出调用代理下的可继续子代理：`children`（默认）合并父 catalog 事实与头部发现，不打开子日志；未解析身份显示为 `unavailable` 诊断。`descendants` 按稳定前序显式读取整棵树的身份，并包含持久化直接父 id 和深度。状态取自存活 Agent 注册表：`running` 或 `inactive`。已知一次性子代理不支持 `send_message`，因此省略。
+列出调用方 agent 下方的可继续子级：`children`（默认）从父目录读取直接子级，不打开子日志；`descendants` 按稳定前序遍历整棵树，并为每个条目标注其持久化直接父级会话 ID 与深度。状态来自在线 Agent 注册表——`running` 或 `inactive`。一次性子级因无法接受 `send_message` 而被有意排除，无法读取的候选项仅在 `descendants` 作用域中以诊断信息呈现。
 
 -----
 
@@ -150,7 +150,7 @@ kind: "package-reference"
 
 #### 模型看到什么
 
-按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。两个 scope 都会为身份不可用的候选项添加 `<id> [diagnostic: <reason>]`。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。一次性子级会被有意排除；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
+按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。仅 `descendants` 作用域会为无法读取的候选项添加 `<id> [diagnostic: <reason>]`。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。一次性子级会被有意排除；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
 
 #### Token 影响
 
diff --git a/packages/subagent/tool-subagent-control/src/list-agents.ts b/packages/subagent/tool-subagent-control/src/list-agents.ts
index 6cc853371a..cd308b7056 100644
--- a/packages/subagent/tool-subagent-control/src/list-agents.ts
+++ b/packages/subagent/tool-subagent-control/src/list-agents.ts
@@ -12,7 +12,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import type {
-  SubagentDiscoveryEntry, SubagentDescendantListEntry, SubagentListEntry,
+  SubagentCatalogEntry, SubagentDescendantListEntry, SubagentListEntry,
 } from '@deepseek-ai/dsh-subagent'
 import { assertNever } from '@deepseek-ai/dsh-util-values'
 
@@ -59,16 +59,13 @@ function statusOf(agents: { get(id: SessionId): Agent | undefined }, id: Session
 /** Project one service row into the model-facing entry, or omit a one-shot child. */
 function project(
   agents: { get(id: SessionId): Agent | undefined },
-  entry: SubagentDiscoveryEntry | SubagentListEntry,
+  entry: SubagentCatalogEntry | SubagentListEntry,
   position?: Pick<SubagentDescendantListEntry, 'parentId' | 'depth'>,
 ): ListAgentsEntry | undefined {
   const at = position === undefined ? {} : { parent: position.parentId, depth: position.depth }
   if ('kind' in entry && entry.kind === 'diagnostic') {
     return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at }
   }
-  if (entry.mode === 'unresolved') {
-    return { kind: 'diagnostic', id: entry.id, reason: 'unavailable', ...at }
-  }
   // One-shot children cannot be continued by send_message, so the model
   // never selects them; discovery still traversed them for descendants.
   if (entry.mode !== 'continuable') return undefined
@@ -97,7 +94,7 @@ export function apply(ctx: Context): void {
       + 'or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` '
       + 'candidate in every status. The snapshot is not a delivery '
       + 'promise — `send_message` performs the authoritative check and may still fail. Children that could '
-      + 'not be identified without opening them are reported as diagnostics. Scope `descendants` '
+      + 'not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` '
       + 'walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent '
       + 'session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are '
       + 'candidates for `interrupt_agent` only.',
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 809f483369..2fd206ed1a 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -131,17 +131,6 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     expect(text(result)).toBe('(no subagents)')
   })
 
-  it('reports header-discovered children without reading their unresolved identities', async () => {
-    const { ctx, parent } = await setup([])
-    vi.spyOn(ctx.subagents, 'listChildren').mockResolvedValue([
-      { id: SessionId('unopened'), createdAt: 1, mode: 'unresolved' },
-    ])
-    const result = await callTool(ctx, 'list_agents', {}, parent)
-    expect(result.isError).toBe(false)
-    expect(text(result)).toContain('unopened')
-    expect(text(result)).toContain('unavailable')
-  })
-
   it('renders direct children in array order with registry statuses', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     const started = await ctx.subagents.startContinuable({
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index c75ebb5d7f..c3a8c6a239 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -561,7 +561,6 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuableStartSpec: 'subagent.md',
   AgentMessageSource: 'subagent.md',
   SubagentCatalogEntry: 'subagent.md',
-  SubagentDiscoveryEntry: 'subagent.md',
   SubagentCatalogState: 'subagent.md',
   SessionProjectionsRequest: 'session.md',
   SessionProjectionsValue: 'session.md',
diff --git a/scripts/migrate-sessions-to-v4.spec.ts b/scripts/migrate-sessions-to-v4.spec.ts
index e14a0e7cfd..cf52171fef 100644
--- a/scripts/migrate-sessions-to-v4.spec.ts
+++ b/scripts/migrate-sessions-to-v4.spec.ts
@@ -225,7 +225,7 @@ describe('one-time V4 migration command', () => {
     }
   })
 
-  it.each(['none', 'zstd'] as const)('migrates %s parent/child history independently with serial or parallel jobs', async (compression) => {
+  it.each(['none', 'zstd'] as const)('preserves %s parent/child history and catalog with serial or parallel jobs', async (compression) => {
     const outputs: Buffer[][] = []
     for (const jobs of [1, 2]) {
       const root = temporaryRoot()
@@ -246,9 +246,8 @@ describe('one-time V4 migration command', () => {
         ))
         current.push(decoded)
       }
-      expect(current[0]!.toString().trim().split('\n').slice(1)).toEqual([])
-      expect(current[1]!.toString().trim().split('\n').slice(1).map((line): unknown => JSON.parse(line))).toMatchObject([
-        { type: 'subagent/descriptor', data: { mode: 'continuable', label: 'saved child' } },
+      expect(current[0]!.toString().trim().split('\n').slice(1).map((line): unknown => JSON.parse(line))).toMatchObject([
+        { type: 'subagent/catalog', data: { childId: 'z-child', childCreatedAt: 2, mode: 'continuable', label: 'saved child' } },
       ])
       outputs.push(current)
     }
@@ -342,7 +341,7 @@ describe('one-time V4 migration command', () => {
       Backend.prototype.open = async function(id, access, options) {
         if (id === 'a-parent' && access === 'write' && !changed) {
           changed = true;
-          throw new JsonlGenerationSourceChangedError(${JSON.stringify(parent.path)});
+          throw new JsonlGenerationSourceChangedError(${JSON.stringify(child.path)});
         }
         return open.call(this, id, access, options);
       };
@@ -361,8 +360,7 @@ describe('one-time V4 migration command', () => {
     expect(lines.filter(line => line.includes('RETRY'))).toHaveLength(1)
     expect(result.summary).toMatchObject({ totals: { converted: 2, alreadyV4: 0, failed: 0, skipped: 0 }, failureGroups: [] })
     const target = await readFile(join(parent.directory, 'session.v4.jsonl'), 'utf8')
-    expect(target.trim().split('\n')).toHaveLength(1)
-    expect(JSON.parse(target)).toMatchObject({ version: 4, id: 'a-parent' })
+    expect(target).toContain('"type":"subagent/catalog"')
     for (const source of [parent, child]) expect(await readFile(source.path)).toEqual(source.bytes)
   })
 
diff --git a/scripts/no-unknown-casts.baseline.json b/scripts/no-unknown-casts.baseline.json
index 35e050b2ef..f5ecfea159 100644
--- a/scripts/no-unknown-casts.baseline.json
+++ b/scripts/no-unknown-casts.baseline.json
@@ -835,11 +835,13 @@
     "92d757187bb2dba986b160c2417c7b4a8b199784d441bfa0777d8077774b932b": 1
   },
   "packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx": {
+    "024f8748e8908a495117a23a7673046a871f0d8187f8fe561aceba1269aefa31": 1,
     "6f46259a9f4093d68b3fc7859c263f21b6318197b74aba368e8904321ab5c4f9": 1,
     "7eb46f4e5e11cef80bd04f36bf7e9b81b3b3e0811e6a50c8dc0e59b13409ab47": 1,
     "93043ae394699d6c87db0291ac271884e16d5f5e5f80b8dffd6ec2ccbe0cb774": 1,
     "9fe5203965e5ff62ab3b914bbcbb5229a5146bf9b12839d99684742579b0f30f": 1,
     "c3f6bb95ba0791435add9be26269aec3bd5cf7bb8a1ffd88913ff8b08b142ed3": 1,
+    "e9abfbf3920ecd6502b74e5eb04d3a1a40b2519f849f5daa193ab7819184ee8b": 1,
     "ffb048df32b10bac91f37b55c618701aa0f9d24c5b5504a3d3f953dc8b7cc7fb": 1
   },
   "packages/client/ui-theme/tests/apply.client.spec.ts": {
diff --git a/snapshots/sdk/bash-tool/tool-schemas.expected.json b/snapshots/sdk/bash-tool/tool-schemas.expected.json
index d0a1b52676..58b6f5a201 100644
--- a/snapshots/sdk/bash-tool/tool-schemas.expected.json
+++ b/snapshots/sdk/bash-tool/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json b/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-activation-limit/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json b/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json b/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json b/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json
index e9ead7a7fe..55005a53e3 100644
--- a/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json
+++ b/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json
index cc45a91131..c185eca7ec 100644
--- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json
index f6f09a4ece..e93f34ff32 100644
--- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json
+++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json b/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json b/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json
+++ b/snapshots/sdk/subagent-send-message/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/sdk/text-turn/tool-schemas.expected.json b/snapshots/sdk/text-turn/tool-schemas.expected.json
index d0a1b52676..58b6f5a201 100644
--- a/snapshots/sdk/text-turn/tool-schemas.expected.json
+++ b/snapshots/sdk/text-turn/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/agent-instructions/tool-schemas.expected.json b/snapshots/session/agent-instructions/tool-schemas.expected.json
index 51a6889dd0..a3a82e074d 100644
--- a/snapshots/session/agent-instructions/tool-schemas.expected.json
+++ b/snapshots/session/agent-instructions/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -857,7 +857,7 @@
       },
       {
         "name": "list_agents",
-        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
         "parameters": {
           "type": "object",
           "properties": {
diff --git a/snapshots/session/background-confinement-failure/tool-schemas.expected.json b/snapshots/session/background-confinement-failure/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/background-confinement-failure/tool-schemas.expected.json
+++ b/snapshots/session/background-confinement-failure/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/both-mode-turn/system-prompt.expected.md b/snapshots/session/both-mode-turn/system-prompt.expected.md
index 0de6b19abb..f15f09f8de 100644
--- a/snapshots/session/both-mode-turn/system-prompt.expected.md
+++ b/snapshots/session/both-mode-turn/system-prompt.expected.md
@@ -133,7 +133,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/both-mode-turn/tool-schemas.expected.json b/snapshots/session/both-mode-turn/tool-schemas.expected.json
index b08bf5c39c..86ee3527e9 100644
--- a/snapshots/session/both-mode-turn/tool-schemas.expected.json
+++ b/snapshots/session/both-mode-turn/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json b/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json
index ba94d36aa0..1cb484d359 100644
--- a/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json
+++ b/snapshots/session/browser-use-chrome-devtools-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json b/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json
index ca3f7b0bfb..db6f9d1f94 100644
--- a/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json
+++ b/snapshots/session/browser-use-playwright-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json b/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json
index d1f297b125..09640f90af 100644
--- a/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json
+++ b/snapshots/session/browser-use-stagehand-native/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/compaction-recovery/tool-schemas.expected.json b/snapshots/session/compaction-recovery/tool-schemas.expected.json
index 51a6889dd0..a3a82e074d 100644
--- a/snapshots/session/compaction-recovery/tool-schemas.expected.json
+++ b/snapshots/session/compaction-recovery/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -857,7 +857,7 @@
       },
       {
         "name": "list_agents",
-        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
         "parameters": {
           "type": "object",
           "properties": {
diff --git a/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json b/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json
index 7b304d9d5b..024361e301 100644
--- a/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json
+++ b/snapshots/session/computer-use-cua-driver-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json b/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json
index 93aabc3d77..ececc98096 100644
--- a/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json
+++ b/snapshots/session/computer-use-cua-driver-native/tool-schemas.expected.json
@@ -291,7 +291,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
index 257de6a9aa..158f24c1af 100644
--- a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
+++ b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
@@ -150,7 +150,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
index 640e583b68..a48efa53bf 100644
--- a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
+++ b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
@@ -286,7 +286,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json b/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json
+++ b/snapshots/session/deepseek-messages-system-prompt/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json b/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json
+++ b/snapshots/session/deepseek-protocol-system-prompt/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json b/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json
+++ b/snapshots/session/foreground-confinement-timeout/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/fs-glob-sampling/tool-schemas.expected.json b/snapshots/session/fs-glob-sampling/tool-schemas.expected.json
index e1a873b1da..1106ebbe40 100644
--- a/snapshots/session/fs-glob-sampling/tool-schemas.expected.json
+++ b/snapshots/session/fs-glob-sampling/tool-schemas.expected.json
@@ -165,7 +165,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/lsp-definition/tool-schemas.expected.json b/snapshots/session/lsp-definition/tool-schemas.expected.json
index 440ae6a4b9..da96eef30a 100644
--- a/snapshots/session/lsp-definition/tool-schemas.expected.json
+++ b/snapshots/session/lsp-definition/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/mcp-resources-ptc/system-prompt.expected.md b/snapshots/session/mcp-resources-ptc/system-prompt.expected.md
index cb2a114d95..edb6c751b8 100644
--- a/snapshots/session/mcp-resources-ptc/system-prompt.expected.md
+++ b/snapshots/session/mcp-resources-ptc/system-prompt.expected.md
@@ -143,7 +143,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/mcp-resources/tool-schemas.expected.json b/snapshots/session/mcp-resources/tool-schemas.expected.json
index 8122f0b7bd..d6dea164c9 100644
--- a/snapshots/session/mcp-resources/tool-schemas.expected.json
+++ b/snapshots/session/mcp-resources/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json b/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json
index 8b68c58b38..863f729ecd 100644
--- a/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json
+++ b/snapshots/session/persistent-pwsh-tool-turn/tool-schemas.expected.json
@@ -120,7 +120,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json b/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
index 261f0ddb8b..07f01589c0 100644
--- a/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
+++ b/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -908,7 +908,7 @@
       },
       {
         "name": "list_agents",
-        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+        "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
         "parameters": {
           "type": "object",
           "properties": {
diff --git a/snapshots/session/plugin-manager/tool-schemas.expected.json b/snapshots/session/plugin-manager/tool-schemas.expected.json
index bb8d07e52b..2a18354c6f 100644
--- a/snapshots/session/plugin-manager/tool-schemas.expected.json
+++ b/snapshots/session/plugin-manager/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/product-subagent-both/tool-schemas.expected.json b/snapshots/session/product-subagent-both/tool-schemas.expected.json
index 1d647f6882..a0ec94f072 100644
--- a/snapshots/session/product-subagent-both/tool-schemas.expected.json
+++ b/snapshots/session/product-subagent-both/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/product-subagent-codex/tool-schemas.expected.json b/snapshots/session/product-subagent-codex/tool-schemas.expected.json
index 4dbf14ee7b..fa96127988 100644
--- a/snapshots/session/product-subagent-codex/tool-schemas.expected.json
+++ b/snapshots/session/product-subagent-codex/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json b/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json
index 768692ba44..af722e03b0 100644
--- a/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json
+++ b/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/provider-cwd/tool-schemas.expected.json b/snapshots/session/provider-cwd/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/provider-cwd/tool-schemas.expected.json
+++ b/snapshots/session/provider-cwd/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ptc-node-read-only/system-prompt.expected.md b/snapshots/session/ptc-node-read-only/system-prompt.expected.md
index 9dd66f0cdf..ff41826d84 100644
--- a/snapshots/session/ptc-node-read-only/system-prompt.expected.md
+++ b/snapshots/session/ptc-node-read-only/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/ptc-node-workspace/system-prompt.expected.md b/snapshots/session/ptc-node-workspace/system-prompt.expected.md
index 9dd66f0cdf..ff41826d84 100644
--- a/snapshots/session/ptc-node-workspace/system-prompt.expected.md
+++ b/snapshots/session/ptc-node-workspace/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/ptc-python-turn/system-prompt.expected.md b/snapshots/session/ptc-python-turn/system-prompt.expected.md
index 897f2c85a2..b7dfe3bf47 100644
--- a/snapshots/session/ptc-python-turn/system-prompt.expected.md
+++ b/snapshots/session/ptc-python-turn/system-prompt.expected.md
@@ -527,7 +527,7 @@ class Tools(Protocol):
     async def job_output(self, args: JobOutputArgs) -> JobOutputOutput:
         """Read a background job. Stream jobs return only output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap."""
     async def list_agents(self, args: ListAgentsArgs) -> list[ListAgentsOutput1 | ListAgentsOutput2]:
-        """List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only."""
+        """List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only."""
     async def read(self, args: ReadArgs) -> ReadOutput:
         """Read a UTF-8 text file and return line-numbered content."""
     async def read_image(self, args: ReadImageArgs) -> ReadImageOutput:
diff --git a/snapshots/session/ptc-read-image/system-prompt.expected.md b/snapshots/session/ptc-read-image/system-prompt.expected.md
index 7174e00853..fd956219e6 100644
--- a/snapshots/session/ptc-read-image/system-prompt.expected.md
+++ b/snapshots/session/ptc-read-image/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/ptc-turn/system-prompt.expected.md b/snapshots/session/ptc-turn/system-prompt.expected.md
index 9dd66f0cdf..ff41826d84 100644
--- a/snapshots/session/ptc-turn/system-prompt.expected.md
+++ b/snapshots/session/ptc-turn/system-prompt.expected.md
@@ -135,7 +135,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json b/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json
index 8b3d055a54..4471c7a371 100644
--- a/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json
+++ b/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json b/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json
index 7c1c97aeb2..5002d370b8 100644
--- a/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json
+++ b/snapshots/session/pwsh-tool-turn/tool-schemas.expected.json
@@ -172,7 +172,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ralph-loop/tool-schemas.1.expected.json b/snapshots/session/ralph-loop/tool-schemas.1.expected.json
index 204212e968..2118a8e4b0 100644
--- a/snapshots/session/ralph-loop/tool-schemas.1.expected.json
+++ b/snapshots/session/ralph-loop/tool-schemas.1.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ralph-loop/tool-schemas.2.expected.json b/snapshots/session/ralph-loop/tool-schemas.2.expected.json
index 204212e968..2118a8e4b0 100644
--- a/snapshots/session/ralph-loop/tool-schemas.2.expected.json
+++ b/snapshots/session/ralph-loop/tool-schemas.2.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/ralph-loop/tool-schemas.expected.json b/snapshots/session/ralph-loop/tool-schemas.expected.json
index 486b2c380a..57eaf5feaa 100644
--- a/snapshots/session/ralph-loop/tool-schemas.expected.json
+++ b/snapshots/session/ralph-loop/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/session-query-spill/tool-schemas.expected.json b/snapshots/session/session-query-spill/tool-schemas.expected.json
index ccf2f16ce0..5c635ee9a1 100644
--- a/snapshots/session/session-query-spill/tool-schemas.expected.json
+++ b/snapshots/session/session-query-spill/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json b/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json
index 0dda1ec644..2c08e64dc9 100644
--- a/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json
+++ b/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json b/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json
index bf2659c163..50b44889ea 100644
--- a/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json
+++ b/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json b/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json
index 4852bca23e..1776b0e3ac 100644
--- a/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json
+++ b/snapshots/session/subagent-tool-filter/tool-schemas.1.expected.json
@@ -159,7 +159,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/system-prompt-in-history/tool-schemas.expected.json b/snapshots/session/system-prompt-in-history/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/system-prompt-in-history/tool-schemas.expected.json
+++ b/snapshots/session/system-prompt-in-history/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/text-turn/tool-schemas.expected.json b/snapshots/session/text-turn/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/text-turn/tool-schemas.expected.json
+++ b/snapshots/session/text-turn/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/web-fetch/tool-schemas.expected.json b/snapshots/session/web-fetch/tool-schemas.expected.json
index 3affe6bfcf..cccf295aa2 100644
--- a/snapshots/session/web-fetch/tool-schemas.expected.json
+++ b/snapshots/session/web-fetch/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/workflow-confinement/tool-schemas.expected.json b/snapshots/session/workflow-confinement/tool-schemas.expected.json
index 6001c6db73..f1421e3b5d 100644
--- a/snapshots/session/workflow-confinement/tool-schemas.expected.json
+++ b/snapshots/session/workflow-confinement/tool-schemas.expected.json
@@ -245,7 +245,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/workspace-dependencies/tool-schemas.expected.json b/snapshots/session/workspace-dependencies/tool-schemas.expected.json
index b4ad218ce2..7697c3522f 100644
--- a/snapshots/session/workspace-dependencies/tool-schemas.expected.json
+++ b/snapshots/session/workspace-dependencies/tool-schemas.expected.json
@@ -200,7 +200,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/web/cordis-tool-round/tool-schemas.expected.json b/snapshots/web/cordis-tool-round/tool-schemas.expected.json
index aa85c50716..ca7afe0add 100644
--- a/snapshots/web/cordis-tool-round/tool-schemas.expected.json
+++ b/snapshots/web/cordis-tool-round/tool-schemas.expected.json
@@ -505,7 +505,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/web/fresh-round-trip/tool-schemas.expected.json b/snapshots/web/fresh-round-trip/tool-schemas.expected.json
index 1a8fbaa834..48bb6c3607 100644
--- a/snapshots/web/fresh-round-trip/tool-schemas.expected.json
+++ b/snapshots/web/fresh-round-trip/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md
index 68dadfbef1..8787372c8f 100644
--- a/snapshots/web/ptc-round/system-prompt.expected.md
+++ b/snapshots/web/ptc-round/system-prompt.expected.md
@@ -155,7 +155,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
+  /** List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/snapshots/web/schedule-catalog/tool-schemas.expected.json b/snapshots/web/schedule-catalog/tool-schemas.expected.json
index 18e72de911..4fc9dab8fd 100644
--- a/snapshots/web/schedule-catalog/tool-schemas.expected.json
+++ b/snapshots/web/schedule-catalog/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be identified without opening them are reported as diagnostics. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "description": "List your continuable background subagents by durable id and label. Use it to recall which ones you started, not to poll for completion — you are told when one finishes. Status comes from the live registry: running means the agent is working right now; inactive means no turn is executing, whether the child is loaded or must be resumed. inactive does not describe task completion, success, failure, or waiting for other agents. A `send_message` steers a running child at its nearest step boundary or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {

From 63190fc8706213bb705f4879035d716328f210ef Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Sun, 20 Sep 2026 12:19:13 +0800
Subject: [PATCH 09/37] fix(client): unify the plugin identity colour on
 label-tertiary

Review feedback on this PR: keep one identity colour rather than raising the
card subtitle to label-secondary. The detail-page package name moves from
label-caption to label-tertiary; the settings card subtitle keeps its own
colour and shares only the 12px size with the row it expands into.
---
 .../ui-plugin-manager/src/client/PluginManagerPage.module.css   | 2 +-
 .../src/client/PluginInventorySettingsTab.module.css            | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
index b05f0f5045..8b4571db6d 100644
--- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
+++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
@@ -1118,7 +1118,7 @@ label.registryOption {
   margin: 0;
   font-size: 12px;
   line-height: 18px;
-  color: var(--dsw-alias-label-secondary);
+  color: var(--dsw-alias-label-tertiary);
   overflow-wrap: anywhere;
 }
 
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 1dba113eec..59d9b1afc0 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
@@ -189,7 +189,7 @@
 .cardIdentity {
   display: block;
   width: 100%;
-  color: var(--dsw-alias-label-secondary);
+  color: var(--dsw-alias-label-tertiary);
 }
 
 .cardTrailing {

From a026ab1397a908cd73e3be9ecb811d800ea86508 Mon Sep 17 00:00:00 2001
From: lsdsjy <1356263+lsdsjy@users.noreply.github.com>
Date: Sun, 20 Sep 2026 13:51:19 +0800
Subject: [PATCH 10/37] fix(onboarding): scope developer tools to trajectory
 tab visibility

---
 ...6-09-17-developer-tools-settings.i18n.yaml |  4 +--
 .../2026-09-17-developer-tools-settings.md    |  2 +-
 .../2026-09-17-developer-tools-settings.zh.md |  2 +-
 .../web/tests/developer-tools-settings.e2e.ts | 20 +++++++++--
 .../client/ui-agent-preset/README.i18n.yaml   |  4 +--
 packages/client/ui-agent-preset/README.md     |  6 ++--
 packages/client/ui-agent-preset/README.zh.md  |  6 ++--
 .../src/client/AgentPresetSection.tsx         | 35 +++++++++++--------
 .../ui-agent-preset/src/client/index.ts       |  2 +-
 .../tests/section.client.spec.tsx             | 11 +++++-
 .../client/ui-conversation/README.i18n.yaml   |  4 +--
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../ui-conversation/src/client/apply.ts       |  4 +--
 .../src/client/view-selection.ts              |  3 ++
 .../tests/apply-inject.client.spec.tsx        |  6 ++--
 .../tests/apply-wiring.client.spec.tsx        | 10 +++---
 17 files changed, 78 insertions(+), 45 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
index 69db5487b8..18a3bf3ba9 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.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-17-developer-tools-settings.md
-2026-09-17-developer-tools-settings.md: e76cb7f367faff71ef916d8a263dc523583f1cd2
-2026-09-17-developer-tools-settings.zh.md: 5a7d6d59db686f57ef4945b572ea65ffe54b7f9c
+2026-09-17-developer-tools-settings.md: 41aa7b52b439105ed2ce59655ad9ea3b99f8f35e
+2026-09-17-developer-tools-settings.zh.md: f73f93c3678b9d5b3525b19e381d7527cc1fa0de
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
index e76cb7f367..41aa7b52b4 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
@@ -12,7 +12,7 @@ Diagnostic views, preset selection and changed-file summaries add complexity to
 
 The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference, defaulting off. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
 
-Off exposes only Chat, hides tool Inspect actions when no visible View declares tool-call inspection, removes the conversation View tab bar, hides the new-session preset chip, and omits the changed-files card and its summary read. Turning it off from another View activates Chat. The preset composition, saved default, Session events and explicit delivery cards remain unchanged. This preference is presentation policy, not Host authorization.
+Off hides the Trajectory View, hides tool Inspect actions when no visible View declares tool-call inspection, hides the conversation View tab bar while fewer than two Views are available, hides the new-session preset chip and the settings row that allows switching Agent modes, and omits the changed-files card and its summary read. Views registered by other plugins stay available. Turning it off while Trajectory is active activates Chat. The preset composition, saved default, Session events and explicit delivery cards remain unchanged. This preference is presentation policy, not Host authorization.
 
 Plugin assembly translates the shared preference into component-specific capabilities (`showCodeDiff`, `showPresetPicker`, and `interactivePreview`). Conversation supplies the inspection callback using the visible target's `toolCallFocus`; Chat does not name the target. The builtin HTML renderer uses DOMPurify for complete-document sanitization and parser-mutation defenses. Off preserves root styling, removes active documents, resource hints, SVG animation and all `href` attributes, and mounts an iframe with no sandbox permissions and a CSP denying scripts and external resources. It reads no related files. On retains the opaque scripted Blob renderer and its bounded related-file reads. Switching modes replaces the browsing context and disposes pending reads. The [document-preview decision](../architecture/2026-09-08-document-preview-operations.md) and [filesystem-read authority](../architecture/2026-09-09-workspace-file-read-authority.md) remain authoritative for advanced rendering and Host read access.
 
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
index 5a7d6d59db..f73f93c367 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好，默认关闭。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
 
-关闭时仅展示 Chat，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，移除会话 View 标签栏，隐藏新会话预设入口，并省略改动文件卡片及其摘要读取。在其他 View 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
+关闭时隐藏 Trajectory View，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，可见 View 少于两个时隐藏会话 View 标签栏，隐藏新会话预设入口和「允许切换 agent 模式」设置行，并省略改动文件卡片及其摘要读取。其他插件注册的 View 保持可用。在 Trajectory 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
 
 插件组装层将共享偏好转换为组件自身的能力（`showCodeDiff`、`showPresetPicker` 和 `interactivePreview`）。Conversation 根据可见目标的 `toolCallFocus` 提供检查回调；Chat 不再指定目标名称。内置 HTML 渲染器使用 DOMPurify 清理完整文档并防护解析变异。关闭时保留根节点样式，移除主动文档、资源提示、SVG 动画及所有 `href` 属性，再放入不授予沙箱权限的 iframe，并通过 CSP 禁止脚本和外部资源。不读取关联文件。开启时保留不透明源的脚本 Blob 渲染器及其有界关联文件读取。切换模式会替换浏览上下文并清理待处理读取。[文档预览决策](../architecture/2026-09-08-document-preview-operations.zh.md)和[文件系统读取权限](../architecture/2026-09-09-workspace-file-read-authority.zh.md)继续定义高级渲染与 Host 读取访问。
 
diff --git a/apps/web/tests/developer-tools-settings.e2e.ts b/apps/web/tests/developer-tools-settings.e2e.ts
index 16c0e6500a..b35a3badd3 100644
--- a/apps/web/tests/developer-tools-settings.e2e.ts
+++ b/apps/web/tests/developer-tools-settings.e2e.ts
@@ -13,7 +13,9 @@ it('persists developer tools in the Host settings document and restores the acce
   onTestFinished(() => browser.close())
   const page = await newEnglishPage(browser)
   await page.goto(scaffold.authenticatedUrl)
-  await page.getByRole('button', { name: 'Settings', exact: true }).click()
+  await page.getByRole('button', { name: 'Account menu', exact: true }).click()
+  await page.getByRole('menuitem', { name: 'Settings', exact: true }).click()
+  await page.getByRole('button', { name: 'General', exact: true }).click()
   const toggle = page.getByRole('switch', { name: 'Developer tools' })
   expect(await toggle.getAttribute('aria-checked')).toBe('false')
   expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).not.toContain('ui-developer-tools:')
@@ -21,9 +23,23 @@ it('persists developer tools in the Host settings document and restores the acce
   await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
   expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n  enabled: true')
   await page.reload()
-  await page.getByRole('button', { name: 'Settings', exact: true }).click()
+  await page.getByRole('button', { name: 'Account menu', exact: true }).click()
+  await page.getByRole('menuitem', { name: 'Settings', exact: true }).click()
+  await page.getByRole('button', { name: 'General', exact: true }).click()
   await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
   await toggle.click()
   await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('false')
   expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n  enabled: false')
+
+  await page.getByRole('button', { name: 'Agent presets', exact: true }).click()
+  const pickerToggle = page.getByRole('switch', { name: 'Allow switching Agent modes' })
+  await expect.poll(() => page.getByRole('heading', { name: 'Agent presets', exact: true }).count()).toBe(1)
+  expect(await pickerToggle.count()).toBe(0)
+  await scaffold.ctx.settings.update('ui-developer-tools', { enabled: true })
+  await expect.poll(() => pickerToggle.count()).toBe(1)
+  const pickerEnabled = await pickerToggle.getAttribute('aria-checked')
+  await scaffold.ctx.settings.update('ui-developer-tools', { enabled: false })
+  await expect.poll(() => pickerToggle.count()).toBe(0)
+  await scaffold.ctx.settings.update('ui-developer-tools', { enabled: true })
+  await expect.poll(() => pickerToggle.getAttribute('aria-checked')).toBe(pickerEnabled)
 })
diff --git a/packages/client/ui-agent-preset/README.i18n.yaml b/packages/client/ui-agent-preset/README.i18n.yaml
index 2ed6513974..acc5d685c6 100644
--- a/packages/client/ui-agent-preset/README.i18n.yaml
+++ b/packages/client/ui-agent-preset/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-agent-preset/README.md
-README.md: c7a87da591c1cafc433fbb3bb5fa216d94ab85ef
-README.zh.md: a54b47baed132e790fc4f44ad1155f48a19c430b
+README.md: 5f2c9acaa5840e71d6ca237c5fc5eccb52724cda
+README.zh.md: 1bc0c8d08f2358725a104309269197036b74e71b
diff --git a/packages/client/ui-agent-preset/README.md b/packages/client/ui-agent-preset/README.md
index c7a87da591..5f2c9acaa5 100644
--- a/packages/client/ui-agent-preset/README.md
+++ b/packages/client/ui-agent-preset/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use this package to choose the agent preset for a new Web GUI session, see the active preset in the session header, and manage available presets in Settings. The Agent mode picker is shown by default; Settings can hide it without changing running or historical sessions. A preset is fixed when a session is created, so changing the selection or default affects only later sessions. If the deployment provides no presets, these controls stay hidden and every session uses the host composition.
+Use this package to choose the agent preset for a new Web GUI session, see the active preset in the session header, and manage available presets in Settings. The Agent mode picker is shown by default while Developer tools is enabled; Settings can hide it without changing running or historical sessions. A preset is fixed when a session is created, so changing the selection or default affects only later sessions. If the deployment provides no presets, these controls stay hidden and every session uses the host composition.
 
 ## Table of Contents
 
@@ -25,9 +25,9 @@ Use this package to choose the agent preset for a new Web GUI session, see the a
 <a id="use-this-package"></a>
 ## Use this package
 
-The new-session picker additionally requires Developer tools to be enabled in General Settings. This presentation preference does not alter the selected preset, saved default, Host composition, or the management section’s independent picker policy.
+The new-session picker and the management section’s “Allow switching Agent modes” row are visible only while Developer tools is enabled in General Settings. This presentation preference does not alter the selected preset, saved default, Host composition, or the management section’s independent picker policy.
 
-Mount this plugin alongside the settings and conversation packages; the management section then shows a visibility switch that is on by default. While it is off, the new-session chip is absent and the Host composes an unnamed session from the deployment default (`standard` in the shipped Web bundle). Turning it on restores the saved user default, or uses the deployment default when none has been saved, and carries that default to the current blank task; a chip pick itself is staged only once for the next blank session. Turning the picker off again returns the current blank task to the deployment default the same way and discards an unconsumed stage; started and historical sessions keep their labels, compositions, and recorded history.
+Mount this plugin alongside the settings and conversation packages; once Developer tools is enabled, the management section shows a visibility switch that is on by default. While it is off, the new-session chip is absent and the Host composes an unnamed session from the deployment default (`standard` in the shipped Web bundle). Turning it on restores the saved user default, or uses the deployment default when none has been saved, and carries that default to the current blank task; a chip pick itself is staged only once for the next blank session. Turning the picker off again returns the current blank task to the deployment default the same way and discards an unconsumed stage; started and historical sessions keep their labels, compositions, and recorded history.
 
 ### Managing the roster
 
diff --git a/packages/client/ui-agent-preset/README.zh.md b/packages/client/ui-agent-preset/README.zh.md
index a54b47baed..1bc0c8d08f 100644
--- a/packages/client/ui-agent-preset/README.zh.md
+++ b/packages/client/ui-agent-preset/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用本包可以为新的 Web GUI 会话选择 agent preset、在会话标题中查看当前 preset，并在设置中管理可用 preset。Agent 模式选择器默认显示；设置可以隐藏它，而不会改变运行中或历史会话。preset 在会话创建时即固定，因此更改选择或默认值只影响此后创建的会话。如果部署未提供任何 preset，这些控件保持隐藏，每个会话都使用宿主组装。
+使用本包可以为新的 Web GUI 会话选择 agent preset、在会话标题中查看当前 preset，并在设置中管理可用 preset。Agent 模式选择器在通用设置开启开发者工具时默认显示；设置可以隐藏它，而不会改变运行中或历史会话。preset 在会话创建时即固定，因此更改选择或默认值只影响此后创建的会话。如果部署未提供任何 preset，这些控件保持隐藏，每个会话都使用宿主组装。
 
 ## 目录
 
@@ -25,9 +25,9 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-新会话选择器还要求在通用设置中开启开发者工具。此展示偏好不会改变已选预设、保存的默认值、Host 组合或管理区域独立的选择器策略。
+新会话选择器和管理区域中的「允许切换 agent 模式」整行设置仅在通用设置中开启开发者工具时显示。此展示偏好不会改变已选预设、保存的默认值、Host 组合或管理区域独立的选择器策略。
 
-与设置和对话包一起挂载本插件；管理分区随后显示一个默认开启的可见性开关。关闭期间，新建会话 chip 不出现，宿主会依据部署默认值（随附 Web bundle 中为 `standard`）组装未指名会话。开启时会恢复已保存的用户默认值；尚未保存时则使用部署默认值；该默认值会同时带到当前空白任务上。chip 中的选择本身只为下一个空白会话暂存一次。再次关闭选择器会以同样方式把当前空白任务带回部署默认值，并丢弃尚未使用的暂存选择；已开始及历史会话的标签、组装与已记录历史均保持不变。
+与设置和对话包一起挂载本插件；通用设置开启开发者工具后，管理分区会显示一个默认开启的可见性开关。关闭期间，新建会话 chip 不出现，宿主会依据部署默认值（随附 Web bundle 中为 `standard`）组装未指名会话。开启时会恢复已保存的用户默认值；尚未保存时则使用部署默认值；该默认值会同时带到当前空白任务上。chip 中的选择本身只为下一个空白会话暂存一次。再次关闭选择器会以同样方式把当前空白任务带回部署默认值，并丢弃尚未使用的暂存选择；已开始及历史会话的标签、组装与已记录历史均保持不变。
 
 ### 管理名单
 
diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
index 5738a1fa36..d05fa305bf 100644
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
@@ -16,7 +16,7 @@ import {
   Button, IconBrowseOutlineRegular, IconCopyOutlineRegular, IconFolderOpenOutlineRegular,
   IconPlusOutlineRegular, IconTrashOutlineRegular, Modal, Switch, Tag, Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { ObservableSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import { draftBlocker, type AgentPresetSectionState } from './section-store.ts'
 import { presetDisplayText, type AgentPresetSettingsKey } from './locales.ts'
@@ -27,6 +27,8 @@ export interface AgentPresetSectionInjected {
   hooks: {
     /** Page snapshot bound by the renderer as useAgentPresetSection. */
     agentPresetSection: SnapshotStore<AgentPresetSectionState>
+    /** Shared preference controlling the picker-policy row. */
+    developerTools: ObservableSnapshot<boolean>
   }
   /** Read the roster; called once when the section first renders. */
   load: () => Promise<void>
@@ -181,6 +183,7 @@ function CardDescription({ text }: { text: string }): ReactNode {
 export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
   const { useAgentPresetSection, t, load } = props
   const state = useAgentPresetSection(snapshot => snapshot)
+  const developerTools = props.useDeveloperTools(enabled => enabled)
   const viewedId = state.view?.id
   const viewedRow = viewedId === undefined ? undefined : state.rows.find(row => row.id === viewedId)
   const viewedTitle = state.view === null
@@ -236,21 +239,23 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
     <div className={css.section}>
       <h2 className={css.title}>{t('nav')}</h2>
       <p className={css.intro}>{t('sectionIntro')}</p>
-      <div className={css.pickerPreference}>
-        <div className={css.pickerPreferenceCopy}>
-          <span className={css.pickerPreferenceTitleRow}>
-            <span className={css.pickerPreferenceTitle}>{t('showPicker')}</span>
-            <Tag>{t('showPickerBeta')}</Tag>
-          </span>
-          <p className={css.pickerPreferenceDescription}>{t('showPickerDescription')}</p>
+      {developerTools && (
+        <div className={css.pickerPreference}>
+          <div className={css.pickerPreferenceCopy}>
+            <span className={css.pickerPreferenceTitleRow}>
+              <span className={css.pickerPreferenceTitle}>{t('showPicker')}</span>
+              <Tag>{t('showPickerBeta')}</Tag>
+            </span>
+            <p className={css.pickerPreferenceDescription}>{t('showPickerDescription')}</p>
+          </div>
+          <Switch
+            checked={state.showPicker}
+            label={t('showPicker')}
+            disabled={state.status !== 'ready' || state.policySaving}
+            onChange={(next) => { void props.setPickerVisible(next) }}
+          />
         </div>
-        <Switch
-          checked={state.showPicker}
-          label={t('showPicker')}
-          disabled={state.status !== 'ready' || state.policySaving}
-          onChange={(next) => { void props.setPickerVisible(next) }}
-        />
-      </div>
+      )}
       {state.error === null ? null : <p className={css.error} role="alert">{state.error}</p>}
       {([['system', t('builtInGroup')], ['user', t('customGroup')]] as const).map(([trust, heading]) => {
         const group = state.rows
diff --git a/packages/client/ui-agent-preset/src/client/index.ts b/packages/client/ui-agent-preset/src/client/index.ts
index c335518aff..0838fd89aa 100644
--- a/packages/client/ui-agent-preset/src/client/index.ts
+++ b/packages/client/ui-agent-preset/src/client/index.ts
@@ -203,7 +203,7 @@ export function apply(ctx: ClientContext): void {
   }
 
   const sectionInjected = (): AgentPresetSectionInjected => ({
-    hooks: { agentPresetSection: section.store },
+    hooks: { agentPresetSection: section.store, developerTools: ctx.settingsScope.developerTools.enabled },
     load: () => section.load(),
     view: (id: string) => section.view(id),
     closeView: () => { section.closeView() },
diff --git a/packages/client/ui-agent-preset/tests/section.client.spec.tsx b/packages/client/ui-agent-preset/tests/section.client.spec.tsx
index d67dc98529..4c11822147 100644
--- a/packages/client/ui-agent-preset/tests/section.client.spec.tsx
+++ b/packages/client/ui-agent-preset/tests/section.client.spec.tsx
@@ -42,7 +42,7 @@ const READY: AgentPresetSectionState = {
  */
 function renderSection(
   state: Partial<AgentPresetSectionState> = {},
-  options: { creator?: boolean } = {},
+  options: { creator?: boolean; developerTools?: boolean } = {},
 ) {
   const store = createSnapshotStore<AgentPresetSectionState>({ ...READY, ...state })
   const actions = {
@@ -66,6 +66,7 @@ function renderSection(
   const props = {
     ...actions,
     useAgentPresetSection: bindSnapshotSelector(store),
+    useDeveloperTools: bindSnapshotSelector(createSnapshotStore(options.developerTools ?? true)),
     t: (key: keyof typeof en) => en[key],
   } as unknown as AgentPresetSectionProps
   render(<AgentPresetSection {...props} />)
@@ -82,6 +83,13 @@ function rowFor(id: string): HTMLElement {
 }
 
 describe('the preset list', () => {
+  it('hides the complete picker-policy row while developer tools are off', () => {
+    renderSection({}, { developerTools: false })
+    expect(screen.queryByRole('switch', { name: en.showPicker })).toBeNull()
+    expect(screen.queryByText(en.showPickerDescription)).toBeNull()
+    expect(screen.queryByText(en.showPickerBeta)).toBeNull()
+  })
+
   it('reads the roster once when it first renders', async () => {
     const actions = renderSection()
 
@@ -349,6 +357,7 @@ describe('the preset list', () => {
 
   it('renders nothing when the deployment composes no presets', () => {
     const { container } = render(<AgentPresetSection {...({
+      useDeveloperTools: bindSnapshotSelector(createSnapshotStore(true)),
       useAgentPresetSection: bindSnapshotSelector(
         createSnapshotStore<AgentPresetSectionState>({ ...READY, status: 'unavailable', rows: [] })),
       t: (key: keyof typeof en) => en[key],
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 74cd3168df..b871029e8d 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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-conversation/README.md
-README.md: fef3a6551b517af2ac636687883864525aac70ee
-README.zh.md: e9ab08c686420c38c11ca2bede2fd00099a247a5
+README.md: 16e821ed4caabae491d552a823bd69a2e976e2bd
+README.zh.md: 7316b00c69ca74284b81678082d93e870dee6bbe
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index fef3a6551b..16e821ed4c 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -40,7 +40,7 @@ The shared image slot props keep display choices separate from durable reference
 
 The context-occupancy button shows a ring and percentage below the input card, after the Session statistics. Clicking it opens the token breakdown in a panel kept inside the viewport, including when no statistics are shown; the button stays hidden until context usage and capacity are available.
 
-With Developer tools off, the shell exposes only Chat and hides the View tab bar. Turning it off while another View is active returns to Chat; stored View preferences and recorded Session data remain intact. Turning it on makes registered Views available again. View owners receive the available roster so their navigation actions can follow the same visibility.
+With Developer tools off, the shell hides only Trajectory; other plugin-contributed Views remain available. The View tab bar is hidden when fewer than two Views are available. Turning Developer tools off while Trajectory is active returns to Chat; stored View preferences and recorded Session data remain intact. Turning it on makes Trajectory available again. View owners receive the available roster so their navigation actions can follow the same visibility.
 
 The composer registers the File command action and owns its label, availability, and native file-dialog callback. Menu availability and invocation both consult the mounted composer's current attachment-intake policy. Unmounting or locking the composer disables that action; disposing the plugin removes its registration. The callback binding stays inside the input module.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index e9ab08c686..7316b00c69 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -40,7 +40,7 @@ target package 通过 declaration merge 扩展 snapshot 与 Location data map，
 
 上下文占用按钮在输入卡片下方、会话统计右侧显示圆环和百分比。点击按钮可在视口内的面板查看 token 构成，没有统计项时面板也不会越界；上下文用量和容量尚不可用时，按钮保持隐藏。
 
-关闭开发者工具时，外壳仅展示 Chat 并隐藏 View 标签栏。在其他 View 激活时关闭开关会返回 Chat；已保存的 View 偏好和 Session 记录保持不变。开启后，已注册的 View 恢复可用。View 所有者接收可用列表，使导航操作跟随相同的可见性。
+关闭开发者工具时，外壳仅隐藏 Trajectory；其他插件贡献的 View 仍然可用。可用 View 少于两个时隐藏 View 标签栏。在 Trajectory 激活时关闭开发者工具会返回 Chat；已保存的 View 偏好和 Session 记录保持不变。开启后，Trajectory 恢复可用。View 所有者接收可用列表，使导航操作跟随相同的可见性。
 
 输入框注册「文件」命令动作，负责其标题、可用性和原生文件选择器回调。菜单可用性与实际调用都读取已挂载输入框当前的附件接收策略。输入框卸载或锁定后该动作不可用，插件 dispose（资源释放）时移除注册。回调绑定留在输入模块内部。
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 3fef945990..07d754d873 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -35,7 +35,7 @@ import { ConversationHeader } from './skeleton/ConversationHeader.tsx'
 import { ConversationSession, ConversationSessionHeader } from './skeleton/ConversationSession.tsx'
 import { InputBar } from './skeleton/InputBar.tsx'
 import { todoDockEntry } from './skeleton/TodoPanel.tsx'
-import { DEFAULT_VIEW_ID, resolveActiveView } from './view-selection.ts'
+import { DEVELOPER_TOOLS_VIEW_ID, resolveActiveView } from './view-selection.ts'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
 import { CONVERSATION_SETTINGS_NAMESPACE, type ConversationSettings } from '../submission-settings.ts'
 
@@ -159,7 +159,7 @@ export function apply(ctx: Context, config: Config = Config({})): void {
     for (const entry of slots.entries('conversation.view')) {
       /* v8 ignore next -- list registration validates id at load. */
       if (entry.options.id === undefined) continue
-      if (!ctx.settingsScope.developerTools.enabled.getSnapshot() && entry.options.id !== DEFAULT_VIEW_ID) continue
+      if (!ctx.settingsScope.developerTools.enabled.getSnapshot() && entry.options.id === DEVELOPER_TOOLS_VIEW_ID) continue
       tabs.push({
         id: entry.options.id,
         label: resolveSlotLabel(entry.options.label) ?? entry.options.id,
diff --git a/packages/client/ui-conversation/src/client/view-selection.ts b/packages/client/ui-conversation/src/client/view-selection.ts
index 0d777c9b7d..53b0ffc86a 100644
--- a/packages/client/ui-conversation/src/client/view-selection.ts
+++ b/packages/client/ui-conversation/src/client/view-selection.ts
@@ -3,6 +3,9 @@ import type { ViewTab } from './contract/views.ts'
 /** Chat remains available when developer tools are disabled. */
 export const DEFAULT_VIEW_ID = 'chat'
 
+/** The one View the Developer tools preference gates; other Views stay registered by their owners. */
+export const DEVELOPER_TOOLS_VIEW_ID = 'trajectory'
+
 /**
  * Resolve a preferred registered View, then Chat, without choosing another View.
  * @param tabs - currently registered Views.
diff --git a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
index 6c12f28cfb..06da77c712 100644
--- a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
@@ -201,20 +201,20 @@ describe('Conversation inject API', () => {
     const unsubscribe = source.subscribe(changed)
     expect(source.getSnapshot()).toBeUndefined()
     const removeDefinition = b.runtime.ctx.uiConversation.views.register({
-      target: 'custom-inspector',
+      target: 'trajectory',
       toolCallFocus: callId => `tool:${callId}`,
       create: () => ({ empty: null, replace: () => null, apply: () => null }),
     })
     expect(source.getSnapshot()).toBeUndefined()
     const removeView = b.slots.register(
-      { name: 'conversation.view', id: 'custom-inspector' }, (() => null) as never,
+      { name: 'conversation.view', id: 'trajectory' }, (() => null) as never,
     )
     await b.runtime.flush()
     const inspect = source.getSnapshot()!
     expect(inspect).toBeTypeOf('function')
     expect(source.getSnapshot()).toBe(inspect)
     inspect('call-1')
-    expect(body.instance.store.getSnapshot().viewRequest).toEqual({ view: 'custom-inspector', focus: 'tool:call-1' })
+    expect(body.instance.store.getSnapshot().viewRequest).toEqual({ view: 'trajectory', focus: 'tool:call-1' })
     await b.runtime.ctx.settingsScope.developerTools.setEnabled(false)
     expect(source.getSnapshot()).toBeUndefined()
     await b.runtime.ctx.settingsScope.developerTools.setEnabled(true)
diff --git a/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx b/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx
index 32e2c1dcac..aca7780d30 100644
--- a/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx
@@ -44,18 +44,18 @@ function entry(
 }
 
 describe('target-neutral Conversation apply wiring', () => {
-  it('offers only Chat while developer tools are disabled and restores registered views when enabled', async () => {
+  it('hides only the Trajectory View while developer tools are disabled and restores it when enabled', async () => {
     const b = await bench()
     const header = b.runtime.slots.entries('conversation.session.header')[0]!
     const source = (header.inject!() as { hooks: { conversationViews: ObservableSnapshot<readonly ViewTab[]> } }).hooks.conversationViews
-    for (const id of ['chat', 'trajectory']) {
+    for (const id of ['chat', 'trajectory', 'probe']) {
       b.runtime.slots.register({ name: 'conversation.view', id, label: id }, (() => null) as never)
     }
-    await vi.waitFor(() => { expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory']) })
+    await vi.waitFor(() => { expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory', 'probe']) })
     b.developerTools.set(false)
-    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat'])
+    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'probe'])
     b.developerTools.set(true)
-    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory'])
+    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory', 'probe'])
     await b.runtime.dispose()
   })
   it('waits for the layout-owned conversation declaration before registering its subtree', async () => {

From c7c900a912f8b1868209988ebe56aa7ffc2f6396 Mon Sep 17 00:00:00 2001
From: lsdsjy <1356263+lsdsjy@users.noreply.github.com>
Date: Sun, 20 Sep 2026 14:15:59 +0800
Subject: [PATCH 11/37] fix(settings): enable developer tools by default

---
 ...6-09-17-developer-tools-settings.i18n.yaml |  4 +--
 .../2026-09-17-developer-tools-settings.md    |  4 +--
 .../2026-09-17-developer-tools-settings.zh.md |  4 +--
 .../web/tests/developer-tools-settings.e2e.ts | 21 ++++--------
 apps/web/tests/scaffold.ts                    |  6 ++--
 .../tests/apply.client.spec.ts                |  2 +-
 packages/client/ui-settings/README.i18n.yaml  |  4 +--
 packages/client/ui-settings/README.md         |  4 +--
 packages/client/ui-settings/README.zh.md      |  4 +--
 .../ui-settings/src/client/developer-tools.ts |  6 ++--
 .../src/developer-tools-settings.ts           |  4 +--
 .../tests/developer-tools.client.spec.ts      | 32 +++++++++++--------
 12 files changed, 46 insertions(+), 49 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
index 18a3bf3ba9..0565db8d75 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.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-17-developer-tools-settings.md
-2026-09-17-developer-tools-settings.md: 41aa7b52b439105ed2ce59655ad9ea3b99f8f35e
-2026-09-17-developer-tools-settings.zh.md: f73f93c3678b9d5b3525b19e381d7527cc1fa0de
+2026-09-17-developer-tools-settings.md: 0745eb32cf5244d5a4ed8e70b84a7598232856c6
+2026-09-17-developer-tools-settings.zh.md: f177eef8c5c07891db1712b55f63d398276a0cf3
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
index 41aa7b52b4..0745eb32cf 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
@@ -10,7 +10,7 @@ Diagnostic views, preset selection and changed-file summaries add complexity to
 
 ## Decision
 
-The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference, defaulting off. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
+The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference, defaulting on. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
 
 Off hides the Trajectory View, hides tool Inspect actions when no visible View declares tool-call inspection, hides the conversation View tab bar while fewer than two Views are available, hides the new-session preset chip and the settings row that allows switching Agent modes, and omits the changed-files card and its summary read. Views registered by other plugins stay available. Turning it off while Trajectory is active activates Chat. The preset composition, saved default, Session events and explicit delivery cards remain unchanged. This preference is presentation policy, not Host authorization.
 
@@ -26,4 +26,4 @@ Plugin assembly translates the shared preference into component-specific capabil
 
 Basic HTML sacrifices JavaScript, external and related resources, and link navigation; inline styles and data images remain available. Advanced mode retains normal browser networking and does not gain parent-origin, popup, form or top-navigation privileges. The setting does not constrain third-party preview implementations or revoke Host filesystem authority.
 
-Component and settings tests cover defaulting, schema rejection, accepted-state updates, chip disclosure, changed-file visibility and iframe disposal. The recorded-session [document preview](../../../../apps/web/tests/document-preview.e2e.ts) and [changed-files](../../../../apps/web/tests/changed-files-turn.e2e.ts) scenarios exercise the real settings control and the shared renderer. The browser scaffold enables developer tools by default. Only settings chrome, document preview, changed-files and developer-tools scenarios explicitly retain the shipped default; together they cover hidden diagnostic controls, static previews, and switching back to Chat. Refused Host writes recover accepted state and show the localized retry message. Native Electron execution remains unverified.
+Component and settings tests cover defaulting, schema rejection, accepted-state updates, chip disclosure, changed-file visibility and iframe disposal. The recorded-session [document preview](../../../../apps/web/tests/document-preview.e2e.ts) and [changed-files](../../../../apps/web/tests/changed-files-turn.e2e.ts) scenarios exercise the real settings control and the shared renderer. The browser scaffold uses the shipped default unless a scenario specifies a preference. Settings chrome, document preview and changed-files scenarios explicitly disable developer tools; together they cover hidden diagnostic controls, static previews, and switching back to Chat. Refused Host writes recover accepted state and show the localized retry message. Native Electron execution remains unverified.
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
index f73f93c367..f177eef8c5 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好，默认关闭。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
+设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好，默认开启。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
 
 关闭时隐藏 Trajectory View，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，可见 View 少于两个时隐藏会话 View 标签栏，隐藏新会话预设入口和「允许切换 agent 模式」设置行，并省略改动文件卡片及其摘要读取。其他插件注册的 View 保持可用。在 Trajectory 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
 
@@ -26,4 +26,4 @@ Status: implemented
 
 基础 HTML 放弃 JavaScript、外部与关联资源和链接导航；行内样式与 data 图片仍可用。高级模式保留正常浏览器网络能力，不增加父源、弹窗、表单或顶层导航权限。此设置不约束第三方预览实现，也不撤销 Host 文件系统读取权限。
 
-组件和设置测试覆盖默认值、schema 拒绝、已接受状态更新、入口折叠、改动文件展示和 iframe 清理。基于已记录 Session 的[文档预览](../../../../apps/web/tests/document-preview.e2e.ts)与[改动文件](../../../../apps/web/tests/changed-files-turn.e2e.ts)场景验证真实设置控件及共用渲染器。浏览器脚手架默认开启开发者工具，仅设置外壳、文档预览、改动文件和开发者工具场景显式保留产品默认值；这些场景共同覆盖诊断控件隐藏、静态预览和切回 Chat。Host 拒绝写入后会恢复已接受状态，并显示本地化重试提示。原生 Electron 执行尚未验证。
+组件和设置测试覆盖默认值、schema 拒绝、已接受状态更新、入口折叠、改动文件展示和 iframe 清理。基于已记录 Session 的[文档预览](../../../../apps/web/tests/document-preview.e2e.ts)与[改动文件](../../../../apps/web/tests/changed-files-turn.e2e.ts)场景验证真实设置控件及共用渲染器。浏览器脚手架使用产品默认值，除非场景指定偏好。设置外壳、文档预览和改动文件场景显式关闭开发者工具；这些场景共同覆盖诊断控件隐藏、静态预览和切回 Chat。Host 拒绝写入后会恢复已接受状态，并显示本地化重试提示。原生 Electron 执行尚未验证。
diff --git a/apps/web/tests/developer-tools-settings.e2e.ts b/apps/web/tests/developer-tools-settings.e2e.ts
index b35a3badd3..6790c94a0c 100644
--- a/apps/web/tests/developer-tools-settings.e2e.ts
+++ b/apps/web/tests/developer-tools-settings.e2e.ts
@@ -1,4 +1,4 @@
-/** Shared settings are off on a fresh Host and survive browser reload through the ordinary settings UI. */
+/** Developer tools default on for a fresh Host and survive browser reload through the ordinary settings UI. */
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { chromium } from 'playwright'
@@ -7,29 +7,22 @@ import { launchWebScaffold } from './scaffold.ts'
 import { newEnglishPage } from './support.ts'
 
 it('persists developer tools in the Host settings document and restores the accepted choice', async () => {
-  const scaffold = await launchWebScaffold({ developerTools: false })
+  const scaffold = await launchWebScaffold()
   onTestFinished(() => scaffold.close())
   const browser = await chromium.launch()
   onTestFinished(() => browser.close())
   const page = await newEnglishPage(browser)
   await page.goto(scaffold.authenticatedUrl)
-  await page.getByRole('button', { name: 'Account menu', exact: true }).click()
-  await page.getByRole('menuitem', { name: 'Settings', exact: true }).click()
-  await page.getByRole('button', { name: 'General', exact: true }).click()
+  await page.getByRole('button', { name: 'Settings', exact: true }).click()
   const toggle = page.getByRole('switch', { name: 'Developer tools' })
-  expect(await toggle.getAttribute('aria-checked')).toBe('false')
+  expect(await toggle.getAttribute('aria-checked')).toBe('true')
   expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).not.toContain('ui-developer-tools:')
   await toggle.click()
-  await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
-  expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n  enabled: true')
-  await page.reload()
-  await page.getByRole('button', { name: 'Account menu', exact: true }).click()
-  await page.getByRole('menuitem', { name: 'Settings', exact: true }).click()
-  await page.getByRole('button', { name: 'General', exact: true }).click()
-  await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
-  await toggle.click()
   await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('false')
   expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n  enabled: false')
+  await page.reload()
+  await page.getByRole('button', { name: 'Settings', exact: true }).click()
+  await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('false')
 
   await page.getByRole('button', { name: 'Agent presets', exact: true }).click()
   const pickerToggle = page.getByRole('switch', { name: 'Allow switching Agent modes' })
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index e7249a0b67..fa3e98dd35 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -302,7 +302,7 @@ export interface WebScaffold {
 
 /** Options for {@link launchWebScaffold}. */
 export interface LaunchOptions {
-  /** The scaffold enables developer tools unless false preserves the shipped default. */
+  /** Override the developer-tools preference; omitted uses the shipped default. */
   developerTools?: boolean
   /** Enable the real Open In rows with deterministic launch-environment facts. */
   openInAppEnvironment?: LaunchEnvironmentSnapshot
@@ -818,8 +818,8 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     }
     await ctx.loader.await()
     await auditStartupEntries(ctx, 'web e2e scaffold')
-    if (options.developerTools !== false) {
-      await ctx.settings.update('ui-developer-tools', { enabled: true })
+    if (options.developerTools !== undefined) {
+      await ctx.settings.update('ui-developer-tools', { enabled: options.developerTools })
     }
     if (options.welcomeNoticePending !== true) {
       await ctx.settings.mutate(WELCOME_NOTICE_SETTINGS_NAMESPACE, [{
diff --git a/packages/client/ui-settings-general/tests/apply.client.spec.ts b/packages/client/ui-settings-general/tests/apply.client.spec.ts
index 1d11e8ea30..ae974a73f3 100644
--- a/packages/client/ui-settings-general/tests/apply.client.spec.ts
+++ b/packages/client/ui-settings-general/tests/apply.client.spec.ts
@@ -107,7 +107,7 @@ describe('ui-settings-general apply', () => {
     const developerRow = c.ctx.slots.entries('settings.general.item').find(row => row.options.id === 'developer-tools')!
     const developer = (developerRow.inject as unknown as () => DeveloperToolsRowInjected)()
     expect(developer.hooks.developerTools).toBe(c.ctx.settingsScope.developerTools.enabled)
-    expect(developer.hooks.developerTools.getSnapshot()).toBe(false)
+    expect(developer.hooks.developerTools.getSnapshot()).toBe(true)
     const setEnabled = vi.spyOn(c.ctx.settingsScope.developerTools, 'setEnabled').mockResolvedValue(undefined)
     await developer.setEnabled(true)
     expect(setEnabled).toHaveBeenCalledExactlyOnceWith(true)
diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml
index 1b479691fd..fdb34612b3 100644
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/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-settings/README.md
-README.md: d70cb35878d77c1d3e928aa222a2c7e96874ea2c
-README.zh.md: 87687ac3ccc7f19d7b34f5724eba260a02e92044
+README.md: 8418c14273c863eb786c83e2d8eaedfd3d1ae2f6
+README.zh.md: 296f61f929187785c7cefa3e452eec3f3b3e72b0
diff --git a/packages/client/ui-settings/README.md b/packages/client/ui-settings/README.md
index d70cb35878..8418c14273 100644
--- a/packages/client/ui-settings/README.md
+++ b/packages/client/ui-settings/README.md
@@ -29,7 +29,7 @@ Feature plugins use this package to store and edit their preferences without re-
 
 ### Binding a namespace
 
-`ctx.settingsScope.developerTools` owns the shared Web and desktop preference `ui-developer-tools.enabled`, defaulting to `false`. Its `enabled` observable publishes accepted choices and `setEnabled` uses the same ordered settings writes. Desktop and loopback Web persist to the Host document; remote Web keeps this choice in one browser-local observable until reload without issuing Host writes. This controls presentation and HTML preview permissions, not Host authorization or Session recording.
+`ctx.settingsScope.developerTools` owns the shared Web and desktop preference `ui-developer-tools.enabled`, defaulting to `true`. Its `enabled` observable publishes accepted choices and `setEnabled` uses the same ordered settings writes. Desktop and loopback Web persist to the Host document; remote Web keeps this choice in one browser-local observable until reload without issuing Host writes. This controls presentation and HTML preview permissions, not Host authorization or Session recording.
 
 A feature calls `ctx.settingsScope.bind(spec)` with a per-namespace spec and gets a scope derived from the shared document mirror. The scope snapshot carries the resolved section, composition `base`, raw `user`, revision, writability, and host/memory mode; a field is overridden when it is present in `user`, even when its value equals `base`, and `unset` clears that override. Writes go through the scope: `set` and `unset` submit one operation, while `mutate` submits several ordered operations atomically. These methods return `true` for Host acceptance and `false` for refusal or skipped writes; transport failures reject. Each write is fenced by the namespace revision as `expectedRevision`, so a concurrent write from another surface is refused instead of silently overwritten. A staged editor can supply the revision where its draft began as a fixed fence; otherwise the scope uses the latest queued or mirrored revision.
 
@@ -53,7 +53,7 @@ The package realizes one ownership rule: the browser keeps one shared mirror of
 
 ### The describe mirror
 
-The Host half registers the `ui-developer-tools` schema and its default-off value with settings. The Client plugin injects `remote` with its `settings` namespace, resolves Host persistence once from the fixed `remote.$host` facts, and owns the one `settings.describe` reader in the browser: a shared mirror refreshed on every forwarded `settings/document-updated` event and on `connection/reset` (the first connection included, closing the window where a commit lands between the eager read and the SSE subscription). Cross-namespace surfaces read it through `ctx.settingsScope.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in).
+The Host half registers the `ui-developer-tools` schema and its default-on value with settings. The Client plugin injects `remote` with its `settings` namespace, resolves Host persistence once from the fixed `remote.$host` facts, and owns the one `settings.describe` reader in the browser: a shared mirror refreshed on every forwarded `settings/document-updated` event and on `connection/reset` (the first connection included, closing the window where a commit lands between the eager read and the SSE subscription). Cross-namespace surfaces read it through `ctx.settingsScope.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in).
 
 ### Scope derivation
 
diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md
index 87687ac3cc..296f61f929 100644
--- a/packages/client/ui-settings/README.zh.md
+++ b/packages/client/ui-settings/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 绑定命名空间
 
-`ctx.settingsScope.developerTools` 管理 Web 和桌面端共享的偏好 `ui-developer-tools.enabled`，默认为 `false`。其 `enabled` 可观察值发布已接受的选择，`setEnabled` 使用相同的有序设置写入。桌面端和回环 Web 将设置持久化到 Host 文档；远程 Web 将此选择保存在单个浏览器本地可观察值中，刷新后重置，不发送 Host 写入。此设置控制界面展示和 HTML 预览权限，不控制 Host 授权或 Session 记录。
+`ctx.settingsScope.developerTools` 管理 Web 和桌面端共享的偏好 `ui-developer-tools.enabled`，默认为 `true`。其 `enabled` 可观察值发布已接受的选择，`setEnabled` 使用相同的有序设置写入。桌面端和回环 Web 将设置持久化到 Host 文档；远程 Web 将此选择保存在单个浏览器本地可观察值中，刷新后重置，不发送 Host 写入。此设置控制界面展示和 HTML 预览权限，不控制 Host 授权或 Session 记录。
 
 功能调用 `ctx.settingsScope.bind(spec)` 并传入按命名空间的 spec，得到一个由共享文档镜像派生的 scope。scope 快照携带解析后的分区、组合 `base`、原始 `user`、revision、可写性以及 host/内存模式；字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等，`unset` 会清除该覆盖。写入经 scope 进行：`set` 与 `unset` 提交一个操作，`mutate` 则原子提交多个有序操作。这些方法在 Host 接受时返回 `true`，拒绝或跳过写入时返回 `false`；传输失败会 reject。每次写入都以命名空间 revision 作为 `expectedRevision` 围栏，因此来自另一界面的并发写入会被拒绝，而不是被静默覆盖。暂存编辑器可以把开始草拟时读取的 revision 作为固定围栏传入；否则 scope 使用最新排队或镜像 revision。
 
@@ -53,7 +53,7 @@ kind: "package-reference"
 
 ### Describe 镜像
 
-Host 部分向 settings 注册 `ui-developer-tools` schema 及其默认关闭值。Client 插件注入 `remote` 及其 `settings` 命名空间，从固定的 `remote.$host` 事实一次性解析 Host 持久化模式，并持有浏览器中唯一的 `settings.describe` 读取方：一面共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内，关闭「提交落在急切读取与 SSE 订阅之间」的窗口）。跨命名空间表面通过 `ctx.settingsScope.describe()` 读它，这是一个读取/折叠面（`getSnapshot`/`subscribe`/`ensure`，另有把写应答折入的 `acceptView`）。
+Host 部分向 settings 注册 `ui-developer-tools` schema 及其默认开启值。Client 插件注入 `remote` 及其 `settings` 命名空间，从固定的 `remote.$host` 事实一次性解析 Host 持久化模式，并持有浏览器中唯一的 `settings.describe` 读取方：一面共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内，关闭「提交落在急切读取与 SSE 订阅之间」的窗口）。跨命名空间表面通过 `ctx.settingsScope.describe()` 读它，这是一个读取/折叠面（`getSnapshot`/`subscribe`/`ensure`，另有把写应答折入的 `acceptView`）。
 
 ### Scope 派生
 
diff --git a/packages/client/ui-settings/src/client/developer-tools.ts b/packages/client/ui-settings/src/client/developer-tools.ts
index 22e1e8de3d..51466d878f 100644
--- a/packages/client/ui-settings/src/client/developer-tools.ts
+++ b/packages/client/ui-settings/src/client/developer-tools.ts
@@ -3,18 +3,18 @@ import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-c
 import type { DeveloperToolsSettings } from '../developer-tools-settings.ts'
 import type { SettingsScope } from './settings-contract.ts'
 
-/** Shared preference; no accepted value means developer tools are disabled. */
+/** Shared preference; no accepted value means developer tools are enabled. */
 export class DeveloperToolsPreference {
   /** Accepted enablement, observable through renderer-bound hooks. */
   readonly enabled: ObservableSnapshot<boolean>
-  private readonly local = createSnapshotStore(false)
+  private readonly local = createSnapshotStore(true)
 
   /**
    * @param scope - settings-owned namespace controller.
    */
   constructor(private readonly scope: SettingsScope<DeveloperToolsSettings>) {
     this.enabled = scope.getSnapshot().mode === 'memory' ? this.local : {
-      getSnapshot: () => scope.getSnapshot().value?.enabled ?? false,
+      getSnapshot: () => scope.getSnapshot().value?.enabled ?? true,
       subscribe: (listener) => {
         let previous = this.enabled.getSnapshot()
         return scope.subscribe(() => {
diff --git a/packages/client/ui-settings/src/developer-tools-settings.ts b/packages/client/ui-settings/src/developer-tools-settings.ts
index e7a64e0e26..9b80e5d31e 100644
--- a/packages/client/ui-settings/src/developer-tools-settings.ts
+++ b/packages/client/ui-settings/src/developer-tools-settings.ts
@@ -10,7 +10,7 @@ export interface DeveloperToolsSettings {
   enabled: boolean
 }
 
-/** New installations and missing values use the basic interface. */
+/** New installations and missing values enable the full interface. */
 export const DeveloperToolsSettingsSchema: z<DeveloperToolsSettings> = z.object({
-  enabled: z.boolean().default(false),
+  enabled: z.boolean().default(true),
 })
diff --git a/packages/client/ui-settings/tests/developer-tools.client.spec.ts b/packages/client/ui-settings/tests/developer-tools.client.spec.ts
index 3a68290c19..6b7aebebce 100644
--- a/packages/client/ui-settings/tests/developer-tools.client.spec.ts
+++ b/packages/client/ui-settings/tests/developer-tools.client.spec.ts
@@ -49,13 +49,14 @@ describe('developer tools settings', () => {
     await fiber.await()
     const preference = ctx.settingsScope.developerTools
     expect(fiber.ctx.settingsScope.developerTools.enabled).toBe(preference.enabled)
+    expect(preference.enabled.getSnapshot()).toBe(true)
     await preference.setEnabled(true)
     expect(fiber.ctx.settingsScope.developerTools.enabled.getSnapshot()).toBe(true)
     expect(describeCall).not.toHaveBeenCalled()
     await fiber.dispose()
     expect(ctx.get('settingsScope')).toBeUndefined()
   })
-  it('defaults off, persists valid choices and removes its schema on disposal', async () => {
+  it('defaults on, keeps an explicit false, persists valid choices and removes its schema on disposal', async () => {
     const ctx = new Context()
     const provider = ctx.plugin(MemorySettings)
     onTestFinished(() => provider.dispose())
@@ -63,6 +64,8 @@ describe('developer tools settings', () => {
     const fiber = ctx.plugin({ apply })
     onTestFinished(() => fiber.dispose())
     await fiber.await()
+    expect(ctx.settings.get(DEVELOPER_TOOLS_NAMESPACE)).toEqual({ enabled: true })
+    await ctx.settings.update(DEVELOPER_TOOLS_NAMESPACE, { enabled: false })
     expect(ctx.settings.get(DEVELOPER_TOOLS_NAMESPACE)).toEqual({ enabled: false })
     await ctx.settings.update(DEVELOPER_TOOLS_NAMESPACE, { enabled: true })
     expect(ctx.settings.get(DEVELOPER_TOOLS_NAMESPACE)).toEqual({ enabled: true })
@@ -71,19 +74,19 @@ describe('developer tools settings', () => {
     expect(ctx.settings.describe().map(row => row.ns)).not.toContain(DEVELOPER_TOOLS_NAMESPACE)
   })
 
-  it('stays off until accepted settings arrive and follows external changes', async () => {
+  it('stays on until accepted settings arrive, then follows a stored false and external changes', async () => {
     const host = stubSettingsScope<DeveloperToolsSettings>()
     const preference = new DeveloperToolsPreference(host.scope)
+    expect(preference.enabled.getSnapshot()).toBe(true)
     const notify = vi.fn()
     const dispose = preference.enabled.subscribe(notify)
+    host.publish({ status: 'ready', value: { enabled: false } })
     expect(preference.enabled.getSnapshot()).toBe(false)
-    host.publish({ status: 'ready', value: { enabled: true } })
-    expect(preference.enabled.getSnapshot()).toBe(true)
     expect(notify).toHaveBeenCalledOnce()
-    await preference.setEnabled(false)
-    expect(host.set).toHaveBeenCalledWith('enabled', false)
-    host.publish({ value: { enabled: false } })
-    expect(preference.enabled.getSnapshot()).toBe(false)
+    await preference.setEnabled(true)
+    expect(host.set).toHaveBeenCalledWith('enabled', true)
+    host.publish({ value: { enabled: true } })
+    expect(preference.enabled.getSnapshot()).toBe(true)
     dispose()
   })
 })
@@ -94,13 +97,14 @@ it('keeps remote browser choices local and publishes only changed values', async
   const preference = new DeveloperToolsPreference(host.scope)
   const notify = vi.fn()
   const dispose = preference.enabled.subscribe(notify)
-  expect(preference.enabled.getSnapshot()).toBe(false)
-  await preference.setEnabled(true)
   expect(preference.enabled.getSnapshot()).toBe(true)
-  await preference.setEnabled(true)
-  expect(notify).toHaveBeenCalledOnce()
   await preference.setEnabled(false)
   expect(preference.enabled.getSnapshot()).toBe(false)
+  await preference.setEnabled(false)
+  expect(notify).toHaveBeenCalledOnce()
+  await preference.setEnabled(true)
+  expect(preference.enabled.getSnapshot()).toBe(true)
+  expect(notify).toHaveBeenCalledTimes(2)
   expect(host.set).not.toHaveBeenCalled()
   dispose()
 })
@@ -111,9 +115,9 @@ it('ignores host revisions that do not change enablement', () => {
   const notify = vi.fn()
   const dispose = preference.enabled.subscribe(notify)
   host.publish({ revision: 1 })
-  host.publish({ value: { enabled: false } })
-  expect(notify).not.toHaveBeenCalled()
   host.publish({ value: { enabled: true } })
+  expect(notify).not.toHaveBeenCalled()
+  host.publish({ value: { enabled: false } })
   expect(notify).toHaveBeenCalledOnce()
   dispose()
 })

From 8cf9c0eded2fb48ccc352c9d31936997e69b1975 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 20 Sep 2026 14:28:57 +0800
Subject: [PATCH 12/37] fix(bash): allow blank justification without escalation
 (#4662)

* fix(bash): allow blank justification without escalation

* fix(bash): permit empty reasons when repeating the current mode
---
 packages/shell/tool-bash/README.i18n.yaml     |  4 +-
 packages/shell/tool-bash/README.md            |  2 +-
 packages/shell/tool-bash/README.zh.md         |  2 +-
 packages/shell/tool-bash/src/index.ts         | 13 +++--
 packages/shell/tool-bash/tests/tools.spec.ts  | 51 +++++++++++++++++++
 .../session.v4.jsonl                          | 22 ++++++++
 .../snapshot.yml                              |  7 +++
 .../session/bash-tool-turn/session.v4.jsonl   | 22 ++++++++
 snapshots/session/bash-tool-turn/snapshot.yml |  2 +-
 9 files changed, 115 insertions(+), 10 deletions(-)
 create mode 100644 snapshots/session/bash-same-mode-empty-justification/session.v4.jsonl
 create mode 100644 snapshots/session/bash-same-mode-empty-justification/snapshot.yml
 create mode 100644 snapshots/session/bash-tool-turn/session.v4.jsonl

diff --git a/packages/shell/tool-bash/README.i18n.yaml b/packages/shell/tool-bash/README.i18n.yaml
index 188434e067..f3b351a17c 100644
--- a/packages/shell/tool-bash/README.i18n.yaml
+++ b/packages/shell/tool-bash/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/tool-bash/README.md
-README.md: 3e01a8b800b5156feecc7e36c45f3490f9abdfc0
-README.zh.md: 91eb88c4b08eb515a0fd5f31257d33b6e3033ab9
+README.md: 5426cc17ccefc7eecf511355734e168377fc2d0f
+README.zh.md: f48c6cb1a9f37da08ccc816eed37c9fbd35eeb62
diff --git a/packages/shell/tool-bash/README.md b/packages/shell/tool-bash/README.md
index 3e01a8b800..5426cc17cc 100644
--- a/packages/shell/tool-bash/README.md
+++ b/packages/shell/tool-bash/README.md
@@ -60,7 +60,7 @@ Passing `run_in_background: true` admits a job and returns its id immediately; c
 
 ### Sandboxed execution and escalation
 
-When the mounted executor confines commands (for example `dsh-bash-sandbox`), a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a command failure. The model may then retry the exact same command once in the same turn with `sandbox_permissions` (the narrowest wider mode that suffices) and a one-sentence `justification`; the approval prompt raised by that retry is how the user consents. Request wider access only after a real denial; a rejected escalation is final for that command. Repeating the current mode runs without approval, while a narrower target fails before execution.
+When the mounted executor confines commands (for example `dsh-bash-sandbox`), a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a command failure. The model may then retry the exact same command once in the same turn with `sandbox_permissions` (the narrowest wider mode that suffices) and a one-sentence `justification`; the approval prompt raised by that retry is how the user consents. Request wider access only after a real denial; a rejected escalation is final for that command. Repeating the current mode runs without approval, while a narrower target fails before execution. Without `sandbox_permissions`, `justification` may be omitted, empty, or whitespace-only; a non-empty reason without a mode is rejected. Repeating the effective mode also permits an omitted or blank reason. A different requested mode requires a non-empty reason; widening still requires approval.
 
 ### What can go wrong
 
diff --git a/packages/shell/tool-bash/README.zh.md b/packages/shell/tool-bash/README.zh.md
index 91eb88c4b0..f48c6cb1a9 100644
--- a/packages/shell/tool-bash/README.zh.md
+++ b/packages/shell/tool-bash/README.zh.md
@@ -60,7 +60,7 @@ kind: "package-reference"
 
 ### 沙箱执行与升权
 
-当已挂载的执行器约束命令（例如 `dsh-bash-sandbox`）时，被阻止的文件操作会报告为 `[sandbox: file access denied under <mode> mode]`——这是策略拒绝，不是命令失败。模型随后可以在同一轮次中用 `sandbox_permissions`（满足需要的最窄更宽模式）与一句 `justification` 重试完全相同的命令一次；该重试引发的审批提示就是用户同意的方式。只有发生真实拒绝后才请求更宽权限；被拒绝的升权对该命令即为最终结果。重复当前模式无需审批即可执行，更窄目标则在执行前失败。
+当已挂载的执行器约束命令（例如 `dsh-bash-sandbox`）时，被阻止的文件操作会报告为 `[sandbox: file access denied under <mode> mode]`——这是策略拒绝，不是命令失败。模型随后可以在同一轮次中用 `sandbox_permissions`（满足需要的最窄更宽模式）与一句 `justification` 重试完全相同的命令一次；该重试引发的审批提示就是用户同意的方式。只有发生真实拒绝后才请求更宽权限；被拒绝的升权对该命令即为最终结果。重复当前模式无需审批即可执行，更窄目标则在执行前失败。未提供 `sandbox_permissions` 时，`justification` 可以省略、为空字符串或仅含空白；未指定模式却提供非空理由会被拒绝。重复当前生效模式时也可省略理由或提供空白理由。请求不同模式时必须提供非空理由；升权仍需审批。
 
 ### 可能出什么问题
 
diff --git a/packages/shell/tool-bash/src/index.ts b/packages/shell/tool-bash/src/index.ts
index a539ca7e4c..fd59129f49 100644
--- a/packages/shell/tool-bash/src/index.ts
+++ b/packages/shell/tool-bash/src/index.ts
@@ -48,10 +48,11 @@ interface BashToolArgs {
   workdir?: string
   run_in_background?: boolean
   sandbox_permissions?: string
+  /** Optional for an omitted or repeated effective mode; widening requires a non-empty reason. */
   justification?: string
 }
 
-function validateBashArgs(args: BashToolArgs): void {
+function validateBashArgs(args: BashToolArgs, effectiveMode: SandboxMode | undefined): void {
   if (args.command.trim().length === 0) {
     throw new Error('invalid command: expected a non-empty string')
   }
@@ -61,9 +62,11 @@ function validateBashArgs(args: BashToolArgs): void {
   if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
     throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`)
   }
-  // The escalation pairing (sandbox_permissions ⇔ justification, non-empty) is
-  // the shared rule both enforcing families validate identically.
-  validateEscalationArgs(args.sandbox_permissions, args.justification)
+  if (args.sandbox_permissions !== undefined && args.sandbox_permissions === effectiveMode) return
+  const justification = args.sandbox_permissions === undefined && args.justification?.trim() === ''
+    ? undefined
+    : args.justification
+  validateEscalationArgs(args.sandbox_permissions, justification)
 }
 
 function bashDescription(backgroundEnabled: boolean, escalationModes: readonly SandboxMode[]): string {
@@ -327,9 +330,9 @@ export function apply(ctx: Context, config: Config = {}): void {
       }],
     },
     async execute(args: BashToolArgs, exec) {
-      validateBashArgs(args)
       // Description is display metadata; workdir defaults to the caller's session.
       const standingPolicy = resolveSandboxPolicy(exec)
+      validateBashArgs(args, standingPolicy?.mode)
       const approvedMode = args.sandbox_permissions !== undefined && args.justification !== undefined
         ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy)
         : undefined
diff --git a/packages/shell/tool-bash/tests/tools.spec.ts b/packages/shell/tool-bash/tests/tools.spec.ts
index 34697d37b6..c2291d0812 100644
--- a/packages/shell/tool-bash/tests/tools.spec.ts
+++ b/packages/shell/tool-bash/tests/tools.spec.ts
@@ -619,6 +619,38 @@ describe('sandbox escalation through the generic task producer', () => {
     }
   })
 
+  it.each([undefined, '', ' \t\n'])('runs without escalation for justification %j', async (justification) => {
+    const { ctx, bash } = await setupSandboxed(true)
+    try {
+      const prompted = vi.fn()
+      ctx.on('approval/request', () => { prompted(); return Promise.resolve<ApprovalOutcome>('allowed-once') })
+      const result = await call(ctx, 'bash', {
+        command: 'true', description: 'ordinary', ...justification === undefined ? {} : { justification },
+      }, sandboxAgent('workspace-write'))
+      expect(result.isError, text(result)).toBe(false)
+      expect(text(result)).toBe('ok')
+      expect(bash.modes).toEqual(['workspace-write'])
+      expect(prompted).not.toHaveBeenCalled()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it.each(['', ' \t\n'])('rejects an explicit mode with blank justification %j before execution', async (justification) => {
+    const { ctx, bash } = await setupSandboxed(true)
+    try {
+      const prompted = vi.fn()
+      ctx.on('approval/request', () => { prompted(); return Promise.resolve<ApprovalOutcome>('allowed-once') })
+      const result = await call(ctx, 'bash', { ...escalate, justification }, sandboxAgent())
+      expect(text(result)).toContain('invalid justification: expected a non-empty sentence')
+      expect(result.isError).toBe(true)
+      expect(bash.modes).toEqual([])
+      expect(prompted).not.toHaveBeenCalled()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('rejects injected escalation without a sandbox and narrower escalation without prompting', async () => {
     const plain = await setup()
     expect(text(await call(plain, 'bash', escalate))).toContain('not available in this composition')
@@ -646,6 +678,25 @@ describe('sandbox escalation through the generic task producer', () => {
     expect(bash.modes).toEqual([mode])
   })
 
+  it.each(['workspace-write', 'danger-full-access'] as const)('runs a repeated %s request without a reason or approval', async (mode) => {
+    const { ctx, bash } = await setupSandboxed(true)
+    try {
+      const prompted = vi.fn()
+      ctx.on('approval/request', () => { prompted(); return Promise.resolve<ApprovalOutcome>('allowed-once') })
+      for (const justification of [undefined, '', ' \t\n']) {
+        const result = await call(ctx, 'bash', {
+          command: 'true', description: 'repeat current mode', sandbox_permissions: mode,
+          ...justification === undefined ? {} : { justification },
+        }, sandboxAgent(mode))
+        expect(result.isError, text(result)).toBe(false)
+      }
+      expect(bash.modes).toEqual([mode, mode, mode])
+      expect(prompted).not.toHaveBeenCalled()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('fails closed when approval cannot be routed', async () => {
     const withoutService = await setupSandboxed()
     expect(text(await call(withoutService.ctx, 'bash', escalate, sandboxAgent()))).toContain('no approval service')
diff --git a/snapshots/session/bash-same-mode-empty-justification/session.v4.jsonl b/snapshots/session/bash-same-mode-empty-justification/session.v4.jsonl
new file mode 100644
index 0000000000..81635830a5
--- /dev/null
+++ b/snapshots/session/bash-same-mode-empty-justification/session.v4.jsonl
@@ -0,0 +1,22 @@
+{"type":"session","version":4,"id":"{{session:1}}","createdAt":1783352050748,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
+{"type":"permission/preset","data":{"preset":"danger-full-access"}}
+{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
+{"type":"approval/policy","data":{"policy":"never"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"session/title","data":{"title":"Use the bash tool to","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to run a simple bash command and then reply with \"DONE\"."},{"type":"tool-call","id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":2877,"outputTokens":90,"cacheReadTokens":0,"reasoningTokens":18},"stream":[{"type":"chunk","time":1788699350043,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699350043,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," run"," a"," simple"," bash"," command"," and"," then"," reply"," with"," \"","D","ONE","\"."]},{"type":"chunk","time":1788699350043,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699350043,"index":1,"dt":[],"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","args":["{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"\"}"]},{"type":"chunk","time":1788699350044,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to run a simple bash command and then reply with \"DONE\"."}}},{"type":"chunk","time":1788699350044,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"\"}"}}},{"type":"chunk","time":1788699350044,"chunk":{"type":"usage","usage":{"inputTokens":2877,"outputTokens":90,"cacheReadTokens":0,"reasoningTokens":18}}},{"type":"chunk","time":1788699350044,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"\"}"}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233"},"toolCallId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","content":[{"type":"text","text":"TERMINAL_OK\n"}],"isError":false,"id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\"."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":168,"outputTokens":25,"cacheReadTokens":2816,"reasoningTokens":22},"stream":[{"type":"chunk","time":1788699350070,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699350070,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," command"," ran"," successfully"," and"," output"," \"","TER","MIN","AL","_OK","\"."," I"," should"," now"," reply"," with"," just"," \"","D","ONE","\"."]},{"type":"chunk","time":1788699350070,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788699350070,"index":1,"dt":[0],"texts":["D","ONE"]},{"type":"chunk","time":1788699350070,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\"."}}},{"type":"chunk","time":1788699350070,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1788699350070,"chunk":{"type":"usage","usage":{"inputTokens":168,"outputTokens":25,"cacheReadTokens":2816,"reasoningTokens":22}}},{"type":"chunk","time":1788699350070,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/session/bash-same-mode-empty-justification/snapshot.yml b/snapshots/session/bash-same-mode-empty-justification/snapshot.yml
new file mode 100644
index 0000000000..19327c2b5f
--- /dev/null
+++ b/snapshots/session/bash-same-mode-empty-justification/snapshot.yml
@@ -0,0 +1,7 @@
+version: 1
+scenario: bash-same-mode-empty-justification
+profile: headless
+composition: default
+recording: authored
+header:
+  class: default
diff --git a/snapshots/session/bash-tool-turn/session.v4.jsonl b/snapshots/session/bash-tool-turn/session.v4.jsonl
new file mode 100644
index 0000000000..a6ff5aaea4
--- /dev/null
+++ b/snapshots/session/bash-tool-turn/session.v4.jsonl
@@ -0,0 +1,22 @@
+{"type":"session","version":4,"id":"{{session:1}}","createdAt":1783352050748,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
+{"type":"permission/preset","data":{"preset":"danger-full-access"}}
+{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
+{"type":"approval/policy","data":{"policy":"never"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo TERMINAL_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"session/title","data":{"title":"Use the bash tool to","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to run a simple bash command and then reply with \"DONE\"."},{"type":"tool-call","id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\", \"justification\": \" \\t\\n \"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":2877,"outputTokens":90,"cacheReadTokens":0,"reasoningTokens":18},"stream":[{"type":"chunk","time":1788699350043,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699350043,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," run"," a"," simple"," bash"," command"," and"," then"," reply"," with"," \"","D","ONE","\"."]},{"type":"chunk","time":1788699350043,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699350043,"index":1,"dt":[0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","args":["","{","\"","command","\"",": ","\"","echo"," TER","MIN","AL","_OK","\"",", ","\"","description","\"",": ","\"","E","cho"," TER","MIN","AL","_OK"," to"," verify"," terminal"," access","\"",", \"justification\": \" \\t\\n \"}"]},{"type":"chunk","time":1788699350044,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to run a simple bash command and then reply with \"DONE\"."}}},{"type":"chunk","time":1788699350044,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\", \"justification\": \" \\t\\n \"}"}}},{"type":"chunk","time":1788699350044,"chunk":{"type":"usage","usage":{"inputTokens":2877,"outputTokens":90,"cacheReadTokens":0,"reasoningTokens":18}}},{"type":"chunk","time":1788699350044,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","name":"bash","arguments":"{\"command\": \"echo TERMINAL_OK\", \"description\": \"Echo TERMINAL_OK to verify terminal access\", \"justification\": \" \\t\\n \"}"}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233"},"toolCallId":"call_00_fkbBRJsUrGKd1pWVc4Gn8233","content":[{"type":"text","text":"TERMINAL_OK\n"}],"isError":false,"id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\"."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":168,"outputTokens":25,"cacheReadTokens":2816,"reasoningTokens":22},"stream":[{"type":"chunk","time":1788699350070,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699350070,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," command"," ran"," successfully"," and"," output"," \"","TER","MIN","AL","_OK","\"."," I"," should"," now"," reply"," with"," just"," \"","D","ONE","\"."]},{"type":"chunk","time":1788699350070,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788699350070,"index":1,"dt":[0],"texts":["D","ONE"]},{"type":"chunk","time":1788699350070,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The command ran successfully and output \"TERMINAL_OK\". I should now reply with just \"DONE\"."}}},{"type":"chunk","time":1788699350070,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1788699350070,"chunk":{"type":"usage","usage":{"inputTokens":168,"outputTokens":25,"cacheReadTokens":2816,"reasoningTokens":22}}},{"type":"chunk","time":1788699350070,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/session/bash-tool-turn/snapshot.yml b/snapshots/session/bash-tool-turn/snapshot.yml
index c2e7ed9bed..4fc363a8d0 100644
--- a/snapshots/session/bash-tool-turn/snapshot.yml
+++ b/snapshots/session/bash-tool-turn/snapshot.yml
@@ -2,6 +2,6 @@ version: 1
 scenario: bash-tool-turn
 profile: headless
 composition: default
-recording: live
+recording: authored
 header:
   class: default

From 17a52a8fe382ac220c4029be4186e9a72a4e0f6f Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sun, 20 Sep 2026 14:30:02 +0800
Subject: [PATCH 13/37] fix(subagent): retain unreadable children in migrated
 catalogs

---
 ...leased-session-format-migrations.i18n.yaml |   4 +-
 ...8-31-released-session-format-migrations.md |   2 +-
 ...1-released-session-format-migrations.zh.md |   2 +-
 ...session-local-subagent-migration.i18n.yaml |   4 +-
 ...-09-19-session-local-subagent-migration.md |   8 +-
 ...-19-session-local-subagent-migration.zh.md |   8 +-
 ...ncomplete-child-catalog-evidence.i18n.yaml |   4 +-
 ...19-v3-incomplete-child-catalog-evidence.md |   6 +-
 ...v3-incomplete-child-catalog-evidence.zh.md |   6 +-
 apps/web/tests/preset-migration.snapshot.ts   |  16 +-
 docs/persistence-catalog.i18n.yaml            |   4 +-
 docs/persistence-catalog.md                   |  69 ++++-
 docs/persistence-catalog.zh.md                |  69 ++++-
 ...2026-09-20-unknown-child-catalog.i18n.yaml |   6 +
 .../2026-09-20-unknown-child-catalog.md       |  48 +++
 ...26-09-20-unknown-child-catalog.schema.json | 104 +++++++
 .../2026-09-20-unknown-child-catalog.zh.md    |  48 +++
 .../historical-formats/README.i18n.yaml       |   4 +-
 .../historical-formats/README.md              |   2 +-
 .../historical-formats/README.zh.md           |   2 +-
 docs/persistence-schema.json                  | 283 ++++++++++++++++++
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   4 +-
 docs/subsystems/subagent.zh.md                |   4 +-
 .../api/session-controller/README.i18n.yaml   |   4 +-
 packages/api/session-controller/README.md     |   2 +-
 packages/api/session-controller/README.zh.md  |   2 +-
 .../src/client/sessions/session.ts            |   5 +-
 .../api/session-controller/src/history.ts     |   2 +-
 packages/api/session-controller/src/types.ts  |   2 +-
 .../tests/manager.client.spec.ts              |  19 ++
 .../tests/transport.host.spec.ts              |  10 +
 packages/client/ui-plan/README.i18n.yaml      |   4 +-
 packages/client/ui-plan/README.md             |   2 +-
 packages/client/ui-plan/README.zh.md          |   2 +-
 packages/client/ui-plan/src/client/plan.ts    |   2 +-
 .../tests/plan-resource.client.spec.ts        |   2 +-
 packages/client/ui-subagent/README.i18n.yaml  |   4 +-
 packages/client/ui-subagent/README.md         |   2 +
 packages/client/ui-subagent/README.zh.md      |   2 +
 .../src/client/SubagentHeaderLineage.tsx      |   3 +-
 .../src/client/SubagentReadOnlyComposer.tsx   |   4 +-
 .../client/ui-subagent/src/client/index.ts    |   1 +
 .../client/ui-subagent/src/client/locales.ts  |   4 +
 .../src/client/sidebar-chat/index.tsx         |   2 +-
 .../tests/browser-plugin.client.spec.ts       |   2 +
 .../tests/conversation-ui.client.spec.tsx     |  17 +-
 .../tests/sidebar-chat.client.spec.tsx        |   4 +-
 .../core/session/src/known-event-types.ts     |   1 +
 .../extensions/tool-cordis/src/api-catalog.ts |   4 +-
 packages/sdk/client/tests/sdk-client.spec.ts  |   4 +
 .../session-format-v3-to-v4/README.i18n.yaml  |   4 +-
 .../session/session-format-v3-to-v4/README.md |  12 +-
 .../session-format-v3-to-v4/README.zh.md      |  12 +-
 .../session-format-v3-to-v4/src/facts.ts      |  15 +
 .../session-format-v3-to-v4/src/migration.ts  |   7 +-
 .../session-format-v3-to-v4/src/validation.ts |   6 +-
 .../tests/catalog-completion.spec.ts          |  13 +-
 .../tests/validation.spec.ts                  |  17 ++
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-jsonl/README.md       |   2 +-
 .../session-persistence-jsonl/README.zh.md    |   2 +-
 .../src/catalog-migration.ts                  |   4 +
 .../session-persistence-jsonl/src/index.ts    |   2 +-
 .../tests/catalog-migration.spec.ts           |  45 ++-
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   2 +-
 packages/subagent/subagent/README.zh.md       |   2 +-
 packages/subagent/subagent/src/catalog.ts     |  36 ++-
 .../subagent/subagent/src/control-types.ts    |   3 +-
 .../subagent/subagent/src/projection-types.ts |   1 +
 .../subagent/subagent/tests/catalog.spec.ts   |   3 +
 python/sdk/tests/test_client.py               |   9 +
 73 files changed, 908 insertions(+), 120 deletions(-)
 create mode 100644 docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
 create mode 100644 docs/persistence-changes/2026-09-20-unknown-child-catalog.md
 create mode 100644 docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
 create mode 100644 docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
index d31a7e21b8..04fa599e6f 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.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-31-released-session-format-migrations.md
-2026-08-31-released-session-format-migrations.md: 21c95503ad05abf54b00c9cb20bec563cbd885ae
-2026-08-31-released-session-format-migrations.zh.md: 46e26b14d10adcc66cf4f0c0aea7573bae3f235a
+2026-08-31-released-session-format-migrations.md: e21793e0ea3d0c5376cbb3949c5d6ef599b9afb1
+2026-08-31-released-session-format-migrations.zh.md: 637d8fcf0206661df9a6f1b3b470ad8a55746720
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
index 21c95503ad..e21793e0ea 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
@@ -131,7 +131,7 @@ Existing write handles retain the process-local claim and kernel-backed cross-pr
 
 ### Parent catalog prerequisites
 
-Runtime child-failure handling in this paragraph is partially superseded by [session-local catalog preparation](../bug-fix/2026-09-19-session-local-subagent-migration.md): opening the parent still completes its catalog from direct-child reads, but unreadable children do not block healthy parent history. V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; absent entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs without backfilling that child, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. An unsupported generation or unreadable header elsewhere in that scan refuses migration because it cannot prove unrelatedness. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The storage decoder classifies physical JSON and compression failures before the collector adds child context; filesystem reads and cancellation keep their original errors. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
+Runtime child-failure handling in this paragraph is partially superseded by [session-local catalog preparation](../bug-fix/2026-09-19-session-local-subagent-migration.md): opening the parent still completes its catalog from direct-child reads, but unreadable children do not block healthy parent history. V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; new complete entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs and retain unknown-mode membership without inventing discovery fields, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. Unreadable or unsupported headers are excluded from discovery; failures reading a recognized child preserve its header identity as unknown-mode membership. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The collector reports child decoding and descriptor failures as warnings with the child path; cancellation and source-consistency checks still stop preparation. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
 
 Raw parent/child migration tests retain 24 historical creation-time conflicts as rejection evidence. Detached controls align only the child creation time and prove event-preserving restoration, including a published child without a descriptor. Headless/ACP and SDK snapshot adapters validate live parent/child clocks before normalization and preserve their equality during refresh; committed predecessor generations remain unchanged.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
index 46e26b14d1..637d8fcf02 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
@@ -131,7 +131,7 @@ POSIX publication 使用 hard-link creation 加目录 sync；Windows 使用 no-o
 
 ### 父目录前置事实
 
-本段的运行时子会话错误处理部分由[逐会话目录准备](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代：打开父会话仍通过读取直属子会话补齐目录，但不可读子会话不再阻断健康父历史。V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；缺失记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志但不补填对应子 Session，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。扫描中其他任何不支持代际或不可读 header 都会拒绝迁移，因为无法证明它与父 Session 无关。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。存储解码器先将物理 JSON 与压缩错误归类，再由收集器补充子日志信息；文件系统读取与取消保留原始错误。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
+本段的运行时子会话错误处理部分由[逐会话目录准备](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代：打开父会话仍通过读取直属子会话补齐目录，但不可读子会话不再阻断健康父历史。V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；新增完整记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志与未知模式成员关系，不编造发现字段，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。不可读或不支持的 header 不参与发现；读取已识别子会话失败时，其 header 身份保留为未知模式成员关系。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。收集器将子解码和 descriptor 失败报告为带子路径的警告；取消与来源一致性检查仍中止准备。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
 
 原始父子迁移测试保留 24 个历史创建时间冲突作为拒绝证据。独立的内存对照只对齐子创建时间，证明恢复保留事件，包括已发布但没有 descriptor 的子 Session。Headless/ACP 与 SDK 快照适配器在规范化之前校验实时父子时钟，并在刷新时保持两者相等；已提交的前代文件保持不变。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
index 7d4ff08c8e..fba52db72b 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.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-09-19-session-local-subagent-migration.md
-2026-09-19-session-local-subagent-migration.md: ee06345246f69b7a176170105d77e3e9ecca8ac8
-2026-09-19-session-local-subagent-migration.zh.md: 050f64877860dd8f63244a34a8ba9d8d3945189c
+2026-09-19-session-local-subagent-migration.md: fcdbb7830a12bca645b2a20c68178fff97d74626
+2026-09-19-session-local-subagent-migration.zh.md: bd6aaf5c434ec109cae2d3c68ddd29249debabf2
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
index ee06345246..fcdbb7830a 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
@@ -10,9 +10,9 @@ Opening a historical parent requires discovery facts from its direct children. A
 
 ## Decision
 
-Opening A discovers candidate B Sessions through headers, reads their own descriptors, and completes A's catalog. Historical child reads use the V0–V3 catalog; current child reads use native validation. These reads neither prepare B's own catalog nor publish B's successor. Opening B separately performs B's migration and catalog preparation. Frontend discovery and `list_agents` retain their parent-catalog behavior and existing result types.
+Opening A discovers candidate B Sessions through headers, reads their own descriptors, and completes A's catalog. Historical child reads use the V0–V3 catalog; current child reads use native validation. These reads neither prepare B's own catalog nor publish B's successor. Opening B separately performs B's migration and catalog preparation. Frontend discovery retains its parent-catalog source. Unknown-mode rows remain browsable; `list_agents` continues to select only known continuable children.
 
-JSONL omits unreadable or unsupported headers from discovery. A child-body or descriptor-field failure produces a warning with the child path and omits that child's supplemental fact, while preserving healthy siblings and existing parent entries. Cancellation and source-consistency failures still stop the operation. Inspected child revisions, including failed decodes, are rechecked before reuse and publication so repairs cannot silently reuse stale evidence. Released predecessors remain byte-identical.
+JSONL omits unreadable or unsupported headers from discovery. A child-body or descriptor-field failure produces a warning with the child path and retains the child's header identity. If the parent lacks a complete entry, migration appends `subagent/catalog-unknown`, projected as `mode: 'unknown'` alongside healthy siblings. Existing complete entries remain authoritative. Cancellation and source-consistency failures still stop the operation. Inspected child revisions, including failed decodes, are rechecked before reuse and publication so repairs cannot silently reuse stale evidence. Released predecessors remain byte-identical.
 
 This partially supersedes child-failure propagation in [released migrations](../architecture/2026-08-31-released-session-format-migrations.md) and [incomplete child evidence](2026-09-19-v3-incomplete-child-catalog-evidence.md). Their format conversion, descriptor cardinality, conflict validation, and immutable publication rules remain active.
 
@@ -20,12 +20,14 @@ This partially supersedes child-failure propagation in [released migrations](../
 
 **Skip catalog completion and discover children in each consumer.** This introduces incomplete tool results and additional UI states despite the parent's readable child descriptors. The parent catalog already serves these consumers.
 
+**Drop unreadable children from the catalog.** Published parents would lose their navigation entries. Header identity is sufficient to retain membership without inventing a mode or label.
+
 **Recursively prepare child catalogs.** A only needs B's own descriptor. Preparing B's descendants adds unrelated work and failure dependencies.
 
 **Refuse A when one child cannot be read.** The child's discovery metadata does not justify withholding the parent's healthy history. Warnings retain the child location without inventing mode or label fields.
 
 ## Consequences
 
-Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. A failed child's missing catalog entry is not automatically repaired after parent publication; the child remains addressable by id, as with other incomplete historical descriptor evidence.
+Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. Unknown entries are not automatically rewritten after publication. Opening a child retries its log and determines browsing capabilities from its actual descriptor, or reports the child-local error. A separate required-on-read event preserves the finalized V4 catalog payload while making unknown membership durable; older readers that lack this event refuse the log.
 
 Raw and compressed tests cover catalog completion, child-local errors, source changes and repairs, unchanged child generations, and deferred child-catalog preparation. The shipped Web migration snapshot checks the parent catalog with a corrupt sibling, then opens the child independently. Its additional historical child raises the corpus budget from ten to eleven roles; the guard rejects a twelfth role.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
index 050f648778..bd6aaf5c43 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-打开 A 时通过 header 发现候选 B Session，读取其自身 descriptor，并补齐 A 的 catalog。历史子日志使用 V0–V3 catalog 读取，当前子日志使用原生校验。这些读取不准备 B 自己的 catalog，也不发布 B 的后继。单独打开 B 时才执行 B 的迁移与目录准备。前端发现和 `list_agents` 保留读取父 catalog 的行为及现有结果类型。
+打开 A 时通过 header 发现候选 B Session，读取其自身 descriptor，并补齐 A 的 catalog。历史子日志使用 V0–V3 catalog 读取，当前子日志使用原生校验。这些读取不准备 B 自己的 catalog，也不发布 B 的后继。单独打开 B 时才执行 B 的迁移与目录准备。前端发现继续读取父 catalog。模式未知的条目仍可浏览；`list_agents` 继续只选择已知可继续的子会话。
 
-JSONL 在发现时跳过不可读或不支持的 header。子正文或 descriptor 字段失败会产生带子路径的警告，并跳过该子的补充事实，同时保留健康兄弟项和已有父目录项。取消与来源一致性失败仍中止操作。复用和发布前会重新检查已检查子日志的修订，包括解码失败的日志，使修复不能静默复用旧证据。已发布前驱保持逐字节不变。
+JSONL 在发现时跳过不可读或不支持的 header。子正文或 descriptor 字段失败会产生带子路径的警告，并保留该子的 header 身份。父目录没有完整条目时，迁移追加 `subagent/catalog-unknown`，与健康兄弟项一同投影为目录条目，其模式为 `mode: 'unknown'`。已有完整条目仍具有权威性。取消与来源一致性失败仍中止操作。复用和发布前会重新检查已检查子日志的修订，包括解码失败的日志，使修复不能静默复用旧证据。已发布前驱保持逐字节不变。
 
 本决策部分取代[已发布迁移](../architecture/2026-08-31-released-session-format-migrations.zh.md)和[不完整子证据](2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)中的子错误传播规则。其格式转换、descriptor 数量、冲突校验和不可变发布规则仍有效。
 
@@ -20,12 +20,14 @@ JSONL 在发现时跳过不可读或不支持的 header。子正文或 descripto
 
 **跳过目录补齐，让每个消费者发现子项。** 父会话明明有可读的子 descriptor，却会因此产生不完整工具结果和额外 UI 状态。父 catalog 已经服务这些消费者。
 
+**从目录删除不可读子会话。** 已发布父会话会丢失相应导航入口。Header 身份足以保留成员关系，无须编造模式或标签。
+
 **递归准备子目录。** A 只需要 B 自身的 descriptor。准备 B 的后代会增加无关工作与失败依赖。
 
 **一个子会话不可读就拒绝 A。** 子会话的发现元数据不足以成为阻断健康父历史的理由。警告保留子位置，不虚构 mode 或 label 字段。
 
 ## 后果
 
-首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。父发布后不会自动修复失败子项缺失的目录记录；该子会话仍可按 id 寻址，与其他不完整历史 descriptor 证据一致。
+首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。发布后不自动重写未知条目。打开子会话会重试其日志，根据实际 descriptor 确定浏览能力，或报告该子会话的错误。独立的必读事件保留已定稿 V4 目录载荷，同时持久记录未知成员；不认识该事件的旧读取器拒绝日志。
 
 原始和压缩测试覆盖目录补齐、子会话错误隔离、来源变化与修复、子代际不变和延后的子目录准备。随产品 Web 迁移快照在损坏兄弟存在时检查父目录，再独立打开子会话。额外的历史子角色使语料预算由十个增加到十一个；守卫拒绝第十二个角色。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
index 00bf6ce0fd..bf6d6c2fd0 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.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-09-19-v3-incomplete-child-catalog-evidence.md
-2026-09-19-v3-incomplete-child-catalog-evidence.md: 30aac77c231b34f04daaa8095f19fbba17c02ed8
-2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: f4f8ee9870e697f675c838284401f5dd943a389e
+2026-09-19-v3-incomplete-child-catalog-evidence.md: 400a84f376a7babc0a95492ca33a3bcd0761cd79
+2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: 535951630bc600647724d50107e74e83ab626739
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
index 30aac77c23..400a84f376 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
@@ -10,9 +10,9 @@ A valid V3 child log can have no own descriptor, an unsupported descriptor versi
 
 ## Decision
 
-The V3→V4 migration appends a missing parent catalog entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions contribute no new catalog fact. Existing parent entries and child events remain intact. This replaces only the missing-evidence refusal in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
+The V3→V4 migration appends a complete missing parent catalog entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions retain unknown-mode membership through [session-local catalog preparation](2026-09-19-session-local-subagent-migration.md). Existing parent entries and child events remain intact. This replaces only the missing-evidence refusal in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
 
-The JSONL failure-propagation rules below are partially superseded by [session-local catalog preparation](2026-09-19-session-local-subagent-migration.md); the converter still validates supplied facts and conflicts. Known child creation times must still match existing parent entries. Mode/label and descriptor fields are checked only for exactly one supported own descriptor. Invalid fields in that descriptor, corrupt logs, unreadable membership, unsupported selected generations, and changed source revisions retain their existing failures.
+The JSONL failure-propagation rules below are partially superseded by [session-local catalog preparation](2026-09-19-session-local-subagent-migration.md); the converter still validates supplied facts and conflicts. Known child creation times must still match existing parent entries. Mode/label and descriptor fields are checked only for exactly one supported own descriptor. JSONL isolates invalid descriptor fields and corrupt child bodies while retaining known header identity; unreadable or unsupported headers are excluded from discovery. Changed source revisions still refuse publication.
 
 ## Alternatives considered
 
@@ -24,6 +24,6 @@ The JSONL failure-propagation rules below are partially superseded by [session-l
 
 ## Consequences
 
-A historical child without a usable descriptor remains readable by id but may be absent from its parent's direct-child catalog. Existing catalog entries remain visible. Once a V4 successor is published, opening it does not rescan historical children; automatic later catalog repair is outside this migration. Preparation still rechecks child revisions before publication, so newly available evidence cannot silently bypass source consistency checks.
+A historical child with a readable header but no usable descriptor retains unknown-mode membership in its parent's direct-child catalog. Existing catalog entries remain visible. Once a V4 successor is published, opening it does not rescan historical children; automatic later mode backfill is outside this migration. Preparation still rechecks child revisions before publication, so newly available evidence cannot silently bypass source consistency checks.
 
 Unit, JSONL read/write, and Preview packing tests cover unavailable evidence, unchanged source bytes, retained entries, identity conflicts, and evidence changes before publication.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
index f4f8ee9870..535951630b 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## Decision
 
-V3→V4 迁移只在恰好一个受支持的自身子 descriptor 提供发现字段时，追加缺失的父目录项。其他 descriptor 数量及不受支持的版本不贡献新的目录事实。已有父目录项和子事件保持完整。这只替代[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)中的证据缺失拒绝规则。
+V3→V4 迁移仅在恰好一个受支持的自身子 descriptor 提供发现字段时，追加完整的缺失父目录项。其他 descriptor 数量和不支持的版本通过[逐会话目录准备](2026-09-19-session-local-subagent-migration.zh.md)保留模式未知的成员关系。已有父目录项和子事件保持不变。这取代[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)中对缺失证据的拒绝。
 
-下述 JSONL 错误传播规则部分由[逐会话目录准备](2026-09-19-session-local-subagent-migration.zh.md)取代；转换器仍校验提供的事实及冲突。已知子创建时间仍必须与已有父目录项一致。只有恰好一个受支持的自身 descriptor 时，才校验其字段并比较 mode／label。该 descriptor 字段无效、日志损坏、成员关系不可读、所选代际不受支持以及源修订变化仍保留原有失败行为。
+JSONL 错误传播规则由[逐会话目录准备](2026-09-19-session-local-subagent-migration.zh.md)部分取代；转换器仍校验已提供事实及冲突。已知子创建时间必须匹配已有父目录项。只有恰好一个受支持的自身 descriptor 时才检查 mode／label 和 descriptor 字段。JSONL 隔离无效 descriptor 字段和损坏子正文，并保留已知 header 身份；不可读或不支持的 header 不参与发现。来源修订变化仍拒绝发布。
 
 ## Alternatives considered
 
@@ -24,6 +24,6 @@ V3→V4 迁移只在恰好一个受支持的自身子 descriptor 提供发现字
 
 ## Consequences
 
-没有可用 descriptor 的历史子 Session 仍可按 id 读取，但可能不出现在其父级的直属子目录中。已有目录项仍可见。V4 后继发布后，打开它不会重新扫描历史子日志；后续自动修复目录不属于本迁移。准备过程仍会在发布前复查子修订，因此新出现的证据无法悄悄绕过源一致性检查。
+历史子会话具有可读 header 但没有可用 descriptor 时，在父直属子目录中保留未知模式成员关系。已有目录项仍可见。V4 后继发布后，打开它不重新扫描历史子日志；自动补齐后续模式不属于本迁移。准备过程仍在发布前重新检查子修订，因此新出现的证据不能静默绕过来源一致性检查。
 
 单元、JSONL 读写和 Preview 打包测试覆盖不可用证据、源字节不变、条目保留、身份冲突以及发布前的证据变化。
diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts
index 16df0a6b84..1f1b81ed90 100644
--- a/apps/web/tests/preset-migration.snapshot.ts
+++ b/apps/web/tests/preset-migration.snapshot.ts
@@ -71,6 +71,7 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
         .filter(event => event.type === 'agent-preset/selected')
         .map(event => event.data.agentPreset)).toEqual(withSelections ? ['ptc', 'standard', 'ptc'] : [])
       expect(await scaffold.ctx.subagents.listChildren(id)).toEqual([
+        { id: brokenId, createdAt: childFixture[0]?.['createdAt'], mode: 'unknown' },
         { id: childId, createdAt: childFixture[0]?.['createdAt'], mode: 'one-shot', label: 'historical child' },
       ])
 
@@ -80,7 +81,7 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
       const address = { kind: 'subagent', parentSessionId: id, childSessionId: childId, mode: 'one-shot' } as const
       const childPage = await scaffold.ctx.sessionController.page({ address, throughSeq: childRows.length - 1 }, signal)
       expect(childPage.records.map(record => record.event.type)).toEqual(childRows.map(row => row['type']))
-      await expect(scaffold.ctx.sessionController.page({ address: { ...address, childSessionId: brokenId }, throughSeq: 1 }, signal))
+      await expect(scaffold.ctx.sessionController.page({ address: { ...address, childSessionId: brokenId, mode: 'unknown' }, throughSeq: 1 }, signal))
         .rejects.toThrow()
       await expect(scaffold.ctx.sessionController.page({ address: { kind: 'session', sessionId: id }, throughSeq: rows.length - 1 }, signal))
         .resolves.toMatchObject({ hasMore: false })
@@ -107,14 +108,17 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
           && (row['data'] as { agentPreset: string }).agentPreset === 'code'
           ? { ...row, data: { agentPreset: 'ptc' } }
           : row),
-        { type: 'subagent/catalog', seq: rows.length, time: rows.at(-1)?.['time'], data: {
+        { type: 'subagent/catalog-unknown', seq: rows.length, time: rows.at(-1)?.['time'], data: {
+          version: 0, childId: brokenId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'unknown',
+        } },
+        { type: 'subagent/catalog', seq: rows.length + 1, time: rows.at(-1)?.['time'], data: {
           version: 0, childId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'one-shot', label: 'historical child',
         } },
         // Agent activation closes its restored prefix with a fresh seed marker.
-        { type: 'session/end-seed', seq: rows.length + 1, time: 0, data: {} },
-        { type: 'permission/preset', seq: rows.length + 2, time: 0, data: { preset: 'workspace-write' } },
-        { type: 'sandbox/mode', seq: rows.length + 3, time: 0, data: { mode: 'workspace-write' } },
-        { type: 'approval/policy', seq: rows.length + 4, time: 0, data: { policy: 'ask' } },
+        { type: 'session/end-seed', seq: rows.length + 2, time: 0, data: {} },
+        { type: 'permission/preset', seq: rows.length + 3, time: 0, data: { preset: 'workspace-write' } },
+        { type: 'sandbox/mode', seq: rows.length + 4, time: 0, data: { mode: 'workspace-write' } },
+        { type: 'approval/policy', seq: rows.length + 5, time: 0, data: { policy: 'ask' } },
       ].map(row => JSON.stringify(row)).join('\n') + '\n'
       const context = { sessionIds: [id], cwd: scaffold.workspaceCwd }
       expect(normalizeSessionSnapshots([published], context)).toEqual(normalizeSessionSnapshots([expected], context))
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index ae6c4b51eb..71aa4ee12b 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: 43b4f86125847625026bd5619216ccdc7be926c1
-persistence-catalog.zh.md: c655d97086fa60630aa5dae1bf3f93be595f179b
+persistence-catalog.md: 2f483ff9dfa831765a25f1ddd20399e47f150b8c
+persistence-catalog.zh.md: 782c30226d9df359b46f3aca02451478307d067e
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 43b4f86125..2f483ff9df 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -58,6 +58,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
 | `event:subagent/catalog` | event | `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871) |
+| `event:subagent/catalog-unknown` | event | `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21` | [`{ type: "subagent/catalog-unknown" }`](#persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -900,7 +901,21 @@ Source: [`packages/core/session/src/types.ts:299`](../packages/core/session/src/
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-Source: [`packages/subagent/subagent/src/catalog.ts:40`](../packages/subagent/subagent/src/catalog.ts)
+Source: [`packages/subagent/subagent/src/catalog.ts:48`](../packages/subagent/subagent/src/catalog.ts)
+
+<a id="subagentcatalog-unknown--log-only"></a>
+
+#### `subagent/catalog-unknown` — log-only
+
+```ts persistence-catalog
+/**
+ * A historical child's header identity when its descriptor cannot establish a mode.
+ * @param data - child identity retained for discovery and later history reads.
+ */
+'subagent/catalog-unknown': UnknownCatalogEvent
+```
+
+Source: [`packages/subagent/subagent/src/catalog.ts:53`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -2475,6 +2490,14 @@ SHA-256: `44c8c77aa9aa100b0d74d2deee85474b29faa6eee0ac0f662f7abe9931ddd7f2`
 
 `"subagent/catalog"`
 
+<a id="persistence-type-sha256-d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89"></a>
+
+### `"subagent/catalog-unknown"`
+
+SHA-256: `d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89`
+
+`"subagent/catalog-unknown"`
+
 <a id="persistence-type-sha256-5ebce1317eacd2c148456627a09668e927ee15c204f0643f5ea76b46b54a2647"></a>
 
 ### `"subagent/descriptor"`
@@ -2787,6 +2810,14 @@ SHA-256: `2c4c21f19f426a58f2dac914e34313aa43f8408972de857a486d1f086d5adb6c`
 
 `"unavailable"`
 
+<a id="persistence-type-sha256-05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04"></a>
+
+### `"unknown"`
+
+SHA-256: `05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04`
+
+`"unknown"`
+
 <a id="persistence-type-sha256-0bdaf9cb63594be4ef034b68901fffe792fe09d6d5f6bac42d7f56f6e7834fb9"></a>
 
 ### `"usage"`
@@ -5087,6 +5118,26 @@ Sources: [`packages/core/session/src/types.ts:232`](../packages/core/session/src
 | `interrupted` | not declared | none | [`{ kind: "interrupted" }`](#persistence-type-sha256-56b7c047694875a843ba020dfea3c8380d54ae4ff88ab349e72004dc21e07c23) |
 | `max-tokens` | not declared | none | [`{ kind: "max-tokens" }`](#persistence-type-sha256-ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7) |
 
+<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
+
+<a id="persistence-type-packagessubagentsubagentsrccatalogtsunknowncatalogevent"></a>
+
+<a id="persistence-type-unknowncatalogevent"></a>
+
+### `UnknownCatalogEvent`
+
+SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
+
+Sources: [`packages/subagent/subagent/src/catalog.ts:34`](../packages/subagent/subagent/src/catalog.ts)
+
+| Property | Presence | Type |
+|---|---|---|
+| `childCreatedAt` | required | `number` |
+| `childId` | required | `string` |
+| `label` | optional | `string` |
+| `mode` | required | `"unknown"` |
+| `version` | required | `0` |
+
 <a id="persistence-type-sha256-64ea5653002834c44f29bea4620e9c42aeb6024ae5b1d58d69f95158006b2586"></a>
 
 <a id="persistence-type-packagesllmllmsrcmessagetsusermessage"></a>
@@ -8237,6 +8288,22 @@ SHA-256: `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871`
 | `time` | required | `number` |
 | `type` | required | `"subagent/catalog"` |
 
+<a id="persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"></a>
+
+<a id="persistence-type-eventsubagentcatalog-unknown"></a>
+
+### `{ type: "subagent/catalog-unknown" }`
+
+SHA-256: `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21`
+
+| Property | Presence | Type |
+|---|---|---|
+| `data` | required | [`UnknownCatalogEvent`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca) |
+| `ignorable` | optional | `true` |
+| `seq` | required | `number` |
+| `time` | required | `number` |
+| `type` | required | `"subagent/catalog-unknown"` |
+
 <a id="persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5"></a>
 
 <a id="persistence-type-eventsubagentdescriptor"></a>
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index c655d97086..782c30226d 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -60,6 +60,7 @@
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
 | `event:subagent/catalog` | event | `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871) |
+| `event:subagent/catalog-unknown` | event | `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21` | [`{ type: "subagent/catalog-unknown" }`](#persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -902,7 +903,21 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-来源：[`packages/subagent/subagent/src/catalog.ts:40`](../packages/subagent/subagent/src/catalog.ts)
+来源：[`packages/subagent/subagent/src/catalog.ts:48`](../packages/subagent/subagent/src/catalog.ts)
+
+<a id="subagentcatalog-unknown--log-only"></a>
+
+#### `subagent/catalog-unknown` — log-only
+
+```ts persistence-catalog
+/**
+ * A historical child's header identity when its descriptor cannot establish a mode.
+ * @param data - child identity retained for discovery and later history reads.
+ */
+'subagent/catalog-unknown': UnknownCatalogEvent
+```
+
+来源：[`packages/subagent/subagent/src/catalog.ts:53`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -2477,6 +2492,14 @@ SHA-256: `44c8c77aa9aa100b0d74d2deee85474b29faa6eee0ac0f662f7abe9931ddd7f2`
 
 `"subagent/catalog"`
 
+<a id="persistence-type-sha256-d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89"></a>
+
+### `"subagent/catalog-unknown"`
+
+SHA-256: `d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89`
+
+`"subagent/catalog-unknown"`
+
 <a id="persistence-type-sha256-5ebce1317eacd2c148456627a09668e927ee15c204f0643f5ea76b46b54a2647"></a>
 
 ### `"subagent/descriptor"`
@@ -2789,6 +2812,14 @@ SHA-256: `2c4c21f19f426a58f2dac914e34313aa43f8408972de857a486d1f086d5adb6c`
 
 `"unavailable"`
 
+<a id="persistence-type-sha256-05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04"></a>
+
+### `"unknown"`
+
+SHA-256: `05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04`
+
+`"unknown"`
+
 <a id="persistence-type-sha256-0bdaf9cb63594be4ef034b68901fffe792fe09d6d5f6bac42d7f56f6e7834fb9"></a>
 
 ### `"usage"`
@@ -5089,6 +5120,26 @@ SHA-256: `f1687f982fa3d41ef29e159feed154ecd13af4dd209acaee16038f223f2e9402`
 | `interrupted` | 未声明 | 无 | [`{ kind: "interrupted" }`](#persistence-type-sha256-56b7c047694875a843ba020dfea3c8380d54ae4ff88ab349e72004dc21e07c23) |
 | `max-tokens` | 未声明 | 无 | [`{ kind: "max-tokens" }`](#persistence-type-sha256-ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7) |
 
+<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
+
+<a id="persistence-type-packagessubagentsubagentsrccatalogtsunknowncatalogevent"></a>
+
+<a id="persistence-type-unknowncatalogevent"></a>
+
+### `UnknownCatalogEvent`
+
+SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
+
+来源：[`packages/subagent/subagent/src/catalog.ts:34`](../packages/subagent/subagent/src/catalog.ts)
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `childCreatedAt` | 必需 | `number` |
+| `childId` | 必需 | `string` |
+| `label` | 可选 | `string` |
+| `mode` | 必需 | `"unknown"` |
+| `version` | 必需 | `0` |
+
 <a id="persistence-type-sha256-64ea5653002834c44f29bea4620e9c42aeb6024ae5b1d58d69f95158006b2586"></a>
 
 <a id="persistence-type-packagesllmllmsrcmessagetsusermessage"></a>
@@ -8239,6 +8290,22 @@ SHA-256: `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871`
 | `time` | 必需 | `number` |
 | `type` | 必需 | `"subagent/catalog"` |
 
+<a id="persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"></a>
+
+<a id="persistence-type-eventsubagentcatalog-unknown"></a>
+
+### `{ type: "subagent/catalog-unknown" }`
+
+SHA-256: `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21`
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `data` | 必需 | [`UnknownCatalogEvent`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca) |
+| `ignorable` | 可选 | `true` |
+| `seq` | 必需 | `number` |
+| `time` | 必需 | `number` |
+| `type` | 必需 | `"subagent/catalog-unknown"` |
+
 <a id="persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5"></a>
 
 <a id="persistence-type-eventsubagentdescriptor"></a>
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml b/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
new file mode 100644
index 0000000000..cfcd73af1d
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.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 docs/persistence-changes/2026-09-20-unknown-child-catalog.md
+2026-09-20-unknown-child-catalog.md: 80de55e616d63730bc1d0bbc0ffa43923f833923
+2026-09-20-unknown-child-catalog.zh.md: 1ee8a04e7318013ec27a7c736fadd540a96cfc0d
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
new file mode 100644
index 0000000000..80de55e616
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-20-unknown-child-catalog
+
+English | [中文](2026-09-20-unknown-child-catalog.zh.md)
+
+## Summary
+
+Add subagent/catalog-unknown to retain historical direct-child header identity when a descriptor cannot establish the mode.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-20-unknown-child-catalog
+baseline: false
+changes:
+  - root: "event:subagent/catalog-unknown"
+    previous: null
+    after: "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+This adds an ordinary required-on-read event without changing the finalized subagent/catalog payload, Session header, or envelope. Existing logs remain valid. Older readers that do not know the new event refuse logs containing it; current readers project it into the existing catalog with unknown mode and keep continuation requests restricted to supported child descriptors.
+
+<a id="verification"></a>
+## Verification
+
+pnpm exec vitest run packages/session/session-format-v3-to-v4/tests/validation.spec.ts packages/subagent/subagent/tests/catalog.spec.ts: 16 tests passed, covering unknown identity restoration, malformed payload rejection, duplicate child rejection, and shared catalog projection.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
new file mode 100644
index 0000000000..7fb3b867fa
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
@@ -0,0 +1,104 @@
+{
+  "formatVersion": 2,
+  "roots": [
+    {
+      "key": "event:subagent/catalog-unknown",
+      "kind": "event",
+      "event": "subagent/catalog-unknown",
+      "surface": false,
+      "digest": "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 6,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog-unknown"
+          }
+        ]
+      }
+    }
+  ],
+  "types": []
+}
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
new file mode 100644
index 0000000000..1ee8a04e73
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-20-unknown-child-catalog
+
+[English](2026-09-20-unknown-child-catalog.md) | 中文
+
+## 概述
+
+新增 subagent/catalog-unknown，在 descriptor 无法确定模式时保留历史直属子会话的 header 身份。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-20-unknown-child-catalog
+baseline: false
+changes:
+  - root: "event:subagent/catalog-unknown"
+    previous: null
+    after: "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+新增普通的必读事件，不修改已定稿的 subagent/catalog 载荷、Session header 或事件信封。已有日志仍有效。不认识新事件的旧读取器拒绝包含它的日志；当前读取器将其投影为现有目录中的未知模式项，继续执行请求仍受支持的子 descriptor 约束。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run packages/session/session-format-v3-to-v4/tests/validation.spec.ts packages/subagent/subagent/tests/catalog.spec.ts：16 个测试通过，覆盖未知身份恢复、畸形载荷拒绝、重复 child 拒绝及共享目录投影。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。
diff --git a/docs/persistence-changes/historical-formats/README.i18n.yaml b/docs/persistence-changes/historical-formats/README.i18n.yaml
index 15481ef915..93eb20d961 100644
--- a/docs/persistence-changes/historical-formats/README.i18n.yaml
+++ b/docs/persistence-changes/historical-formats/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 docs/persistence-changes/historical-formats/README.md
-README.md: 9bcfaa1246a03446d4d4fc95dd19f9ca60196301
-README.zh.md: 1f17367beb484feaeb289a42b3e5de50d3139be5
+README.md: 386b0bd9091cbd509843bd6464c8a95650accb99
+README.zh.md: e93e8033daa639eee3a5035efc2df8ef123f563e
diff --git a/docs/persistence-changes/historical-formats/README.md b/docs/persistence-changes/historical-formats/README.md
index 9bcfaa1246..386b0bd909 100644
--- a/docs/persistence-changes/historical-formats/README.md
+++ b/docs/persistence-changes/historical-formats/README.md
@@ -32,7 +32,7 @@ The index is generated from validated snapshots and the current writer constant.
 | 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 583 |
+| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 63 / 587 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-changes/historical-formats/README.zh.md b/docs/persistence-changes/historical-formats/README.zh.md
index 1f17367beb..e93e8033da 100644
--- a/docs/persistence-changes/historical-formats/README.zh.md
+++ b/docs/persistence-changes/historical-formats/README.zh.md
@@ -32,7 +32,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式
 | 1 | PR #3349 | [V1](v1.zh.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.zh.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.zh.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 62 / 583 |
+| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 63 / 587 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-schema.json b/docs/persistence-schema.json
index 428d512264..b069ba0699 100644
--- a/docs/persistence-schema.json
+++ b/docs/persistence-schema.json
@@ -14985,6 +14985,104 @@
         ]
       }
     },
+    {
+      "key": "event:subagent/catalog-unknown",
+      "kind": "event",
+      "event": "subagent/catalog-unknown",
+      "surface": false,
+      "digest": "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 6,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog-unknown"
+          }
+        ]
+      }
+    },
     {
       "key": "event:subagent/descriptor",
       "kind": "event",
@@ -21691,6 +21789,20 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "literal",
+            "value": "unknown"
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "05d2ae1e0c7f8770f83f9a09047afb39a335d8ac986df3193659aa1e581472cf",
       "schema": {
@@ -73477,6 +73589,67 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 2,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          }
+        ]
+      },
+      "names": [
+        "packages/subagent/subagent/src/catalog.ts#UnknownCatalogEvent"
+      ],
+      "sources": [
+        "packages/subagent/subagent/src/catalog.ts:34"
+      ]
+    },
     {
       "digest": "c8e6f48878cc2a2f0dc59682280d81f407943fb503f32c64bf9ff3d9393c3eff",
       "schema": {
@@ -76958,6 +77131,102 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 6,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog-unknown"
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "d28765f87d6b6ab408e0b2f3e7e297791b004b806d8e302c49903ebae815feb2",
       "schema": {
@@ -76972,6 +77241,20 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "literal",
+            "value": "subagent/catalog-unknown"
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "d4b739491689cc6bb13d07ffac1a32239875abda364c0d5edd8f74faf5e9c00d",
       "schema": {
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 034d835426..805d66f003 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: d642fe1658926b17cb29f280803f12e61228be60
-subagent.zh.md: ff153c7861b4ac46bb058efd00a2f5a50181b6f2
+subagent.md: 67f9bc31b46617ea2f7b1ec81bf8c52fd62720cb
+subagent.zh.md: a69e032ed96a24a980badaf9e14d924311e1d175
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index d642fe1658..67f9bc31b4 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -8,7 +8,7 @@ Service Definition: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subag
 
 Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
-The `subagentCatalog` projection exposes `SubagentCatalogEntry[]` in parent event order through Session observations and client snapshots. Each entry contains the child id, creation time, mode, and mode-dependent label; fork-inherited catalog facts are excluded. [The subagent package](../../packages/subagent/subagent/README.md) owns catalog creation and persistence semantics.
+The `subagentCatalog` projection exposes `SubagentCatalogEntry[]` in parent event order through Session observations and client snapshots. Each entry contains the child id, creation time, mode, and mode-dependent label; fork-inherited catalog facts are excluded. [The subagent package](../../packages/subagent/subagent/README.md) owns catalog creation and persistence semantics. Historical children with unavailable descriptors have `mode: 'unknown'`; their header identity remains discoverable without granting continuation capabilities.
 
 ## Two kinds of capability, discovered two ways
 
@@ -465,7 +465,7 @@ The spawn and fork backends create an ordinary one-shot agent through `parent.ct
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
 - **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/runtime-diagnostics/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
 
-`SubagentCatalogEntry` describes one successful direct-child creation fact; `SubagentCatalogState` is the host-only projection state. `listChildren()` owns a live-preferred parent observation without opening child logs. Browser consumers read `subagentCatalog` through the shared Session projection store and combine membership with Session-list activity. `SubagentCatalogRow` belongs to complete-descendant listing. [The parent-catalog decision](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns the persistent facts and read semantics.
+`SubagentCatalogEntry` describes a direct child with complete or unknown-mode discovery information; `SubagentCatalogState` is the host-only projection state. `listChildren()` owns a live-preferred parent observation without opening child logs. Browser consumers read `subagentCatalog` through the shared Session projection store and combine membership with Session-list activity. `SubagentCatalogRow` belongs to complete-descendant listing. [The parent-catalog decision](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns the persistent facts and read semantics.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ff153c7861..a69e032ed9 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -8,7 +8,7 @@ Service Definition：[dsh-subagent](../../packages/subagent/subagent)（`ctx.sub
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
-`subagentCatalog` projection 通过 Session 观察和客户端快照暴露按父会话事件排序的 `SubagentCatalogEntry[]`。每个条目包含子级 id、创建时间、模式和依模式确定的标签；fork 继承的目录事实不在其中。[subagent 包](../../packages/subagent/subagent/README.zh.md) 定义目录创建和持久化语义。
+`subagentCatalog` projection 通过 Session 观察和客户端快照暴露按父会话事件排序的 `SubagentCatalogEntry[]`。每个条目包含子级 id、创建时间、模式和依模式确定的标签；fork 继承的目录事实不在其中。[subagent 包](../../packages/subagent/subagent/README.zh.md) 定义目录创建和持久化语义。历史子会话的 descriptor 不可用时使用 `mode: 'unknown'`，保留 header 身份供发现，但不授予继续执行能力。
 
 ## 两类能力，两种发现方式
 
@@ -469,7 +469,7 @@ spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
 - **Fork 种子注入**使用 [`CreateAgentOptions.seed`](core.zh.md#creation-and-ownership)（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/runtime-diagnostics/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
 
-`SubagentCatalogEntry` 描述一条成功创建直接子级的事实；`SubagentCatalogState` 是仅 host 使用的 projection state。`listChildren()` 拥有一次 live-preferred 父 Session observation，不打开子级日志。浏览器消费者通过共享 Session projection store 读取 `subagentCatalog`，并将成员关系与 Session 列表活动状态组合。`SubagentCatalogRow` 属于完整后代列表。[父目录决策](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 规定持久事实与读取语义。
+`SubagentCatalogEntry` 描述一条完整或未知模式的直接子级目录记录；`SubagentCatalogState` 是仅 host 使用的 projection state。`listChildren()` 拥有一次 live-preferred 父 Session observation，不打开子级日志。浏览器消费者通过共享 Session projection store 读取 `subagentCatalog`，并将成员关系与 Session 列表活动状态组合。`SubagentCatalogRow` 属于完整后代列表。[父目录决策](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 规定持久事实与读取语义。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index d04576c269..6ea89c55b9 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: a0e18910d14f879171a1415476a7e05a0d261a8a
-README.zh.md: 58466e387fd604137a2358e8b9a7de3320691034
+README.md: 49eac824a0f9752fa5e2af6eb8c93d0b7b3bbfd9
+README.zh.md: d129ce01cf073dee679b965d83b19b48831d0188
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index a0e18910d1..49eac824a0 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -61,7 +61,7 @@ Attachment authorization reads declared content fields of built-in Session event
 
 `sessions.retain(target, { source, signal? })` immediately acquires one exact Client generation and starts its shared initial history opening. The target is a known Session id or a durable direct-parent subagent address; the Host validates an explicit address when history opens. The returned reference supports idempotent `release()` and `Symbol.dispose`; its `ready` Promise follows the shared `Session.open()` result and resolves to the exact binding when that attempt settles, including when a Remote failure is represented by `openState: 'error'`. It rejects when `Session.open()` rejects, its waiter is cancelled, or the reference is released early. Cancelling one waiter does not cancel another owner's opening. `sessions.using(target, options, operation)` waits for that settlement, holds its reference until the callback settles, and propagates rejected readiness and callback failures.
 
-References keep local Session data, scoped Contexts, and history streams alive, not Host Agents. Ordinary Session retention never adds a catalog row. Retained subagents with a known direct-parent address keep a fallback row and notify list readers even before the parent catalog arrives; these rows do not join Host-list membership. Fork-title assignment sends rename directly and applies the returned title projection without retaining the child or opening its history. Final release withdraws the generation before teardown; later acquisition can create a new generation with the same id. `binding(id)` and `scope(id)` only borrow an existing generation. `retainInfo(id)` observes stable read-only source counts independently of catalog membership and performs no history I/O. Consumer source keys are declaration-merge extensible; navigation and completion acknowledgement belong to UI consumers, not this Controller. See [Client Session references](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.md) for ownership and teardown rules.
+References keep local Session data, scoped Contexts, and history streams alive, not Host Agents. Ordinary Session retention never adds a catalog row. Retained subagents with a known direct-parent address keep a fallback row and notify list readers even before the parent catalog arrives; these rows do not join Host-list membership. Fork-title assignment sends rename directly and applies the returned title projection without retaining the child or opening its history. Final release withdraws the generation before teardown; later acquisition can create a new generation with the same id. `binding(id)` and `scope(id)` only borrow an existing generation. `retainInfo(id)` observes stable read-only source counts independently of catalog membership and performs no history I/O. Consumer source keys are declaration-merge extensible; navigation and completion acknowledgement belong to UI consumers, not this Controller. See [Client Session references](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.md) for ownership and teardown rules. An unknown-mode subagent address permits history reads with direct-parent validation. Successful descriptor restoration determines the displayed mode; failures remain local to the child, and control requests still require a confirmed continuable identity.
 
 <a id="session-media-references"></a>
 ## Session media references
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 58466e387f..d129ce01cf 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -61,7 +61,7 @@ Fork 复制 `atSeq` 所选的精确事件前缀，包含切点事件，允许在
 
 `sessions.retain(target, { source, signal? })` 立即获取一个精确 Client generation 的引用，并启动其共享的首次历史打开。目标是已知 Session id 或持久的直接父子 subagent 地址；Host 在打开历史时校验显式地址。返回引用支持幂等的 `release()` 和 `Symbol.dispose`；其 `ready` Promise 跟随共享的 `Session.open()` 结果，并在该次尝试结算时解析为确切 binding，包括 Remote failure 以 `openState: 'error'` 表示的情况。仅当 `Session.open()` 拒绝、等待方取消或引用提前释放时，`ready` 才拒绝。取消一个等待方不会取消其他 owner 的打开。`sessions.using(target, options, operation)` 等待该次结算，持有引用直到回调结束，并传播被拒绝的就绪与回调失败。
 
-引用保活本地会话数据、作用域 Context 和历史流，不保活 Host Agent。普通 Session 不因保留引用而添加目录行。已保留且具有明确直接父子地址的 subagent 即使尚未收到父目录，也会保留兜底行并通知列表读取方；这些行不加入 Host 列表成员集合。Fork 标题设置直接发送 rename 并应用返回的标题投影，不 retain 子会话，也不打开其历史。最后一个引用释放时，generation 先退出可访问映射，再执行清理；后续获取可以为同一 id 创建新 generation。`binding(id)` 和 `scope(id)` 只借用已有 generation。`retainInfo(id)` 独立于目录成员关系观察稳定的只读来源计数，不执行历史 I/O。消费方来源键可通过声明合并扩展；导航和完成确认属于 UI 消费方，不属于本控制器。所有权与清理规则见 [Client 会话引用](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.zh.md)。
+引用保活本地会话数据、作用域 Context 和历史流，不保活 Host Agent。普通 Session 不因保留引用而添加目录行。已保留且具有明确直接父子地址的 subagent 即使尚未收到父目录，也会保留兜底行并通知列表读取方；这些行不加入 Host 列表成员集合。Fork 标题设置直接发送 rename 并应用返回的标题投影，不 retain 子会话，也不打开其历史。最后一个引用释放时，generation 先退出可访问映射，再执行清理；后续获取可以为同一 id 创建新 generation。`binding(id)` 和 `scope(id)` 只借用已有 generation。`retainInfo(id)` 独立于目录成员关系观察稳定的只读来源计数，不执行历史 I/O。消费方来源键可通过声明合并扩展；导航和完成确认属于 UI 消费方，不属于本控制器。所有权与清理规则见 [Client 会话引用](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.zh.md)。 模式未知的子代理地址允许读取历史，但仍校验直接父级。成功恢复 descriptor 后确定展示模式；失败只影响该子会话，控制请求仍要求已确认的 continuable 身份。
 
 <a id="session-media-references"></a>
 ## 会话媒体引用
diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts
index cd38a26fcf..b3afc491da 100644
--- a/packages/api/session-controller/src/client/sessions/session.ts
+++ b/packages/api/session-controller/src/client/sessions/session.ts
@@ -812,6 +812,7 @@ export class Session implements SessionFace {
   }
 
   private buildSnapshot(): SessionSnapshot {
+    const identity = this.projections.values().subagent
     return {
       sessionId: this.sessionId,
       pendingSubmissions: this.pendingSubmissions,
@@ -819,7 +820,9 @@ export class Session implements SessionFace {
       subagent: this.address === undefined
         ? null
         : {
-          address: this.address,
+          address: this.address.mode === 'unknown' && identity != null
+            ? { ...this.address, mode: identity.mode }
+            : this.address,
           ...(this.parentAvailable === undefined ? {} : { parentAvailable: this.parentAvailable }),
         },
       removed: this.removed,
diff --git a/packages/api/session-controller/src/history.ts b/packages/api/session-controller/src/history.ts
index a22badc1f1..069ee3bf32 100644
--- a/packages/api/session-controller/src/history.ts
+++ b/packages/api/session-controller/src/history.ts
@@ -364,7 +364,7 @@ function validateAddress(
       reason: 'unsupported',
     })
   }
-  if (identity.mode !== address.mode) {
+  if (address.mode !== 'unknown' && identity.mode !== address.mode) {
     throw new RemoteError('subagent/unauthorized', 'subagent mode does not match the supplied address', {
       childSessionId: address.childSessionId,
     })
diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts
index a925e9da83..1d27d62dc5 100644
--- a/packages/api/session-controller/src/types.ts
+++ b/packages/api/session-controller/src/types.ts
@@ -393,7 +393,7 @@ export type SessionAddress =
     readonly kind: 'subagent'
     readonly parentSessionId: SessionId
     readonly childSessionId: SessionId
-    readonly mode: 'one-shot' | 'continuable'
+    readonly mode: 'one-shot' | 'continuable' | 'unknown'
   }
 
 /** One non-activating Session projection read. */
diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts
index 7ee5be5397..6f70f7636b 100644
--- a/packages/api/session-controller/tests/manager.client.spec.ts
+++ b/packages/api/session-controller/tests/manager.client.spec.ts
@@ -501,6 +501,25 @@ describe('subagent catalogs', () => {
     })
   })
 
+  it('resolves an unknown browsing mode from the child projection without changing parent membership', async ({ mock, start }) => {
+    mock.load(sessionWorld)
+    const client = await start()
+    const manager = new SessionManager(client.ctx.remote)
+    const entries = [{ id: S2, createdAt: 1, mode: 'unknown' as const }]
+    manager.handleControlFrame({ type: 'projection', sessionId: S1, key: 'subagentCatalog', seq: 0, value: entries })
+    const address = manager.subagentAddress(S2)!
+    expect(address).toEqual({ parentSessionId: S1, childSessionId: S2, mode: 'unknown' })
+    manager.resolveTarget(address)
+    const child = manager.get(S2)
+    expect(child.getSnapshot().subagent?.address.mode).toBe('unknown')
+    manager.handleControlFrame({ type: 'projection', sessionId: S2, key: 'subagent', seq: 0,
+      value: { seq: SessionSeq(0), mode: 'continuable', label: 'repaired child' } })
+    await child.open()
+    expect(child.getSnapshot().subagent?.address).toEqual({ ...address, mode: 'continuable' })
+    expect(manager.getListSnapshot().projectionsBySession[S1]?.values.subagentCatalog).toEqual(entries)
+    await manager.dispose()
+  })
+
   it('publishes pushed membership without a catalog request or an instantiated parent', ({ mock, remote }) => {
     const manager = makeManager(mock, remote)
     manager.handleSessionAdded(summary(S2, { origin: 'subagent', parentSessionId: S1, running: true }))
diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts
index 04b43972e9..341aaf4e86 100644
--- a/packages/api/session-controller/tests/transport.host.spec.ts
+++ b/packages/api/session-controller/tests/transport.host.spec.ts
@@ -451,6 +451,16 @@ describe('SessionHistoryController', () => {
     }, signal)).resolves.toMatchObject({
       records: [{ type: 'event', event: { type: 'subagent/descriptor' } }],
     })
+    await expect(transport.page({
+      address: { kind: 'subagent', parentSessionId, childSessionId, mode: 'unknown' },
+      throughSeq: 0,
+    }, signal)).resolves.toMatchObject({
+      records: [{ type: 'event', event: { type: 'subagent/descriptor' } }],
+    })
+    await expect(transport.page({
+      address: { kind: 'subagent', parentSessionId: SessionId('other-parent'), childSessionId, mode: 'unknown' },
+      throughSeq: 0,
+    }, signal)).rejects.toMatchObject({ code: 'subagent/unauthorized' })
     await expect(transport.page({
       address: {
         kind: 'subagent',
diff --git a/packages/client/ui-plan/README.i18n.yaml b/packages/client/ui-plan/README.i18n.yaml
index 74be8bbf76..24fc6a38eb 100644
--- a/packages/client/ui-plan/README.i18n.yaml
+++ b/packages/client/ui-plan/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-plan/README.md
-README.md: b6072cd7d75446a0a45abe4009273235e4ff4e1b
-README.zh.md: 44b5ce85ccd6250f30904f80b01ee083f804f1ce
+README.md: 96ecd3777ef0ce4ce6babd977eef055ad5c683ec
+README.zh.md: fb6eb850b868913bdccec175500ff4e26d7a2157
diff --git a/packages/client/ui-plan/README.md b/packages/client/ui-plan/README.md
index b6072cd7d7..96ecd3777e 100644
--- a/packages/client/ui-plan/README.md
+++ b/packages/client/ui-plan/README.md
@@ -51,7 +51,7 @@ Admission failures (`matched: false`, business errors, transport faults) surface
 
 The chip occupies the conversation-declared `conversation.input.plan` single seat; the node half is an empty apply (the roster row). Reads ride the generic projection pair through the standard-kit `useProjection`: the effective target is `pending ? !active : active` — a folded host value, not client optimism, so an arriving frame corrects the chip either way. The seat's injected face carries one verb, `exitPlanMode`, which executes `/plan off` through `ctx.remote.commands.execute` and maps admission failures to an inline error line. The placeholder and hint text live in ui-conversation's `conversation` locale namespace and are shared verbatim with the claimed `/plan` command hint.
 
-Plan cards derive from native `tool/call` or PTC dispatch arguments through a Conversation Definition, with each invocation’s resolved Turn location. They contribute to the additive `conversation.chat.turnTail` list alongside file deliveries. The plan resource address identifies the invocation and its complete ordinary or direct-parent subagent Session address; its provider reads existing Session history, including older pages, without storing document text in sidebar layout. The question plugin owns the review action slot and supplies its request key, complete text, and optional invocation identity. The [decision](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.md) explains why review lifetime and document lifetime remain separate.
+Plan cards derive from native `tool/call` or PTC dispatch arguments through a Conversation Definition, with each invocation’s resolved Turn location. They contribute to the additive `conversation.chat.turnTail` list alongside file deliveries. The plan resource address identifies the invocation and its complete ordinary or direct-parent subagent Session address; its provider reads existing Session history, including older pages, without storing document text in sidebar layout. The question plugin owns the review action slot and supplies its request key, complete text, and optional invocation identity. The [decision](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.md) explains why review lifetime and document lifetime remain separate. Subagent plan addresses also preserve unknown mode so history reads can resolve the child descriptor.
 
 </details>
 
diff --git a/packages/client/ui-plan/README.zh.md b/packages/client/ui-plan/README.zh.md
index 44b5ce85cc..fb6eb850b8 100644
--- a/packages/client/ui-plan/README.zh.md
+++ b/packages/client/ui-plan/README.zh.md
@@ -51,7 +51,7 @@ kind: "package-reference"
 
 徽章占据 conversation 声明的 `conversation.input.plan` 单实例座位；node 半部是空 apply（roster 行）。读取经 standard-kit 的 `useProjection` 走通用投影对：有效目标是 `pending ? !active : active`——折叠的宿主值而非客户端乐观态，因此到达的帧无论哪个方向都会纠正徽章。座位注入面携带一个动词 `exitPlanMode`，经 `ctx.remote.commands.execute` 执行 `/plan off`，并把准入失败映射为一行内联错误。placeholder 与提示文案位于 ui-conversation 的 `conversation` locale 命名空间，与已认领 `/plan` 命令的提示逐字共用。
 
-计划卡片通过 Conversation Definition 从原生 `tool/call` 或 PTC dispatch 参数派生，并使用每次调用已解析的回合位置。它们与文件产物一起贡献到可追加的 `conversation.chat.turnTail` 列表。计划资源地址标识调用及完整的普通会话地址或子会话直接父级地址；provider 读取已有会话历史及较早分页，不把正文存入侧边栏布局。提问插件拥有审批操作插槽，并提供请求键、完整正文和可选的调用标识。[决策记录](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.zh.md)说明审批与文档为何保持独立生命周期。
+计划卡片通过 Conversation Definition 从原生 `tool/call` 或 PTC dispatch 参数派生，并使用每次调用已解析的回合位置。它们与文件产物一起贡献到可追加的 `conversation.chat.turnTail` 列表。计划资源地址标识调用及完整的普通会话地址或子会话直接父级地址；provider 读取已有会话历史及较早分页，不把正文存入侧边栏布局。提问插件拥有审批操作插槽，并提供请求键、完整正文和可选的调用标识。[决策记录](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.zh.md)说明审批与文档为何保持独立生命周期。 子代理计划地址也保留未知模式，以便历史读取解析子 descriptor。
 
 </details>
 
diff --git a/packages/client/ui-plan/src/client/plan.ts b/packages/client/ui-plan/src/client/plan.ts
index e3dff30e29..d44b8f2dd9 100644
--- a/packages/client/ui-plan/src/client/plan.ts
+++ b/packages/client/ui-plan/src/client/plan.ts
@@ -74,7 +74,7 @@ export function parsePlanAddress(address: string): PlanAddress | undefined {
     if (parts.length === 2) return {
       session: { kind: 'session', sessionId: parts[0] as SessionId }, callId: parts[1] as ToolCallId,
     }
-    if (parts.length === 5 && parts[0] === 'subagent' && (parts[3] === 'one-shot' || parts[3] === 'continuable')) return {
+    if (parts.length === 5 && parts[0] === 'subagent' && (parts[3] === 'one-shot' || parts[3] === 'continuable' || parts[3] === 'unknown')) return {
       session: { kind: 'subagent', parentSessionId: parts[1] as SessionId, childSessionId: parts[2] as SessionId, mode: parts[3] },
       callId: parts[4] as ToolCallId,
     }
diff --git a/packages/client/ui-plan/tests/plan-resource.client.spec.ts b/packages/client/ui-plan/tests/plan-resource.client.spec.ts
index a27b03c185..57be9acd36 100644
--- a/packages/client/ui-plan/tests/plan-resource.client.spec.ts
+++ b/packages/client/ui-plan/tests/plan-resource.client.spec.ts
@@ -36,7 +36,7 @@ describe('plan history resource', () => {
     expect(b.page).toHaveBeenCalledWith({ address: { kind: 'session', sessionId: 'session' }, throughSeq: 100, beforeSeq: 80 }, expect.any(AbortSignal))
     expect(b.closed).toHaveBeenCalledOnce()
   })
-  it.each(['one-shot', 'continuable'] as const)('restores a %s subagent plan with its complete parent address on every page', async (mode) => {
+  it.each(['one-shot', 'continuable', 'unknown'] as const)('restores a %s subagent plan with its complete parent address on every page', async (mode) => {
     const b = setup([{ type: 'event', event: { type: 'user/message', seq: 80, data: {} } }], true)
     const address = `dsh-resource://plan/subagent/parent/child/${mode}/call`
     const session = { kind: 'subagent', parentSessionId: 'parent', childSessionId: 'child', mode }
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index 45a496719c..9bab3901c6 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/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-subagent/README.md
-README.md: 1404e893add386b88a24d78675a4f0be06f497a0
-README.zh.md: 97c743b580e25cd50bcb01a3a7547cb7415a0e08
+README.md: d0dc10f17b2b83d7a605ee622ea027698ebeac77
+README.zh.md: 1019fd3e7d6fbd8b259c6e94dd830c47ebb2058e
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index 1404e893ad..d0dc10f17b 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -65,6 +65,8 @@ Each visible catalog level advances its own clock while it contains a running ch
 
 One-shot children always elect a read-only composer. A continuable child elects one only when its exact parent is unavailable and the child is not running; otherwise the ordinary composer's Session routes prompts through `subagents/prompt`. This package never receives host context or calls a model-facing tool.
 
+Unknown-mode catalog rows remain visible and clickable, using the child id when no label is available. Their composer is read-only until child history establishes a supported mode; a read failure is reported in the child conversation.
+
 </details>
 
 -----
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index 97c743b580..1019fd3e7d 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -65,6 +65,8 @@ kind: "package-reference"
 
 one-shot child 始终选用只读编辑器。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器；否则普通编辑器的会话会经 `subagents/prompt` 路由提示词。本包绝不接收宿主上下文，也不调用面向模型的工具。
 
+模式未知的目录项仍可见、可点击，没有标签时显示子会话 id。读取子历史并确认受支持模式前，输入区保持只读；读取失败在该子会话中报告。
+
 </details>
 
 -----
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
index 6dd416fb95..75e130bbaa 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
@@ -238,7 +238,8 @@ function CatalogRows({
           || (childCatalog.state === 'loading' && childCatalog.entries.length === 0)
         const summary = summaries[entry.id]
         const label = entry.label ?? entry.id
-        const mode = entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
+        const mode = entry.mode === 'unknown' ? t('mode.unknown')
+          : entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
         const completed = entry.activity === 'inactive'
           && summary?.projectionValues?.subagentTiming?.lastTurnCompleted === true
         const activity = entry.activity === 'running'
diff --git a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
index 158e8cb77b..07feb84f55 100644
--- a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
@@ -4,7 +4,7 @@ import css from './SubagentReadOnlyComposer.module.css'
 
 /** Why a catalog-addressed conversation cannot accept human input. */
 export interface SubagentReadOnlyMatch {
-  reason: 'one-shot' | 'parent-unavailable'
+  reason: 'one-shot' | 'parent-unavailable' | 'unknown'
 }
 
 /** Full chain props after the read-only subagent selector accepts the owner currency. */
@@ -24,7 +24,7 @@ export function SubagentReadOnlyComposer({
     <div className={css.frame} role="status">
       <strong>{t(oneShot ? 'readonly.oneShot.title' : 'readonly.title')}</strong>
       <span>
-        {t(oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
+        {t(matched.reason === 'unknown' ? 'readonly.unknown.body' : oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
       </span>
     </div>
   )
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 0055ea8c3f..d0779cddc8 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -37,6 +37,7 @@ export const inject = ['sessions', 'uiWorkspace', 'slots', 'locale', 'sidebarRig
 function selectReadOnlySubagent(owner: ComposerChainProps): SubagentReadOnlyMatch | null {
   const subagent = owner.session?.subagent
   if (subagent === undefined || subagent === null) return null
+  if (subagent.address.mode === 'unknown') return { reason: 'unknown' }
   if (subagent.address.mode === 'one-shot') return { reason: 'one-shot' }
   // Until a Host summary establishes parent availability, keep the normal
   // disabled composer instead of claiming that the parent is offline.
diff --git a/packages/client/ui-subagent/src/client/locales.ts b/packages/client/ui-subagent/src/client/locales.ts
index cc966d411c..c17a2f3cb1 100644
--- a/packages/client/ui-subagent/src/client/locales.ts
+++ b/packages/client/ui-subagent/src/client/locales.ts
@@ -24,6 +24,8 @@ export const zh = {
   'retry': '重试',
   'mode.oneShot': '一次性',
   'mode.continuable': '可继续',
+  'mode.unknown': '模式未知',
+  'readonly.unknown.body': '读取子会话后才能确定是否可继续。',
   'activity.running': '正在运行',
   'activity.completed': '已完成',
   'activity.inactive': '当前未运行',
@@ -64,6 +66,8 @@ export const en: Record<SubagentKey, string> = {
   'retry': 'Retry',
   'mode.oneShot': 'one-shot',
   'mode.continuable': 'continuable',
+  'mode.unknown': 'unknown mode',
+  'readonly.unknown.body': 'Read the child session to determine whether it can be continued.',
   'activity.running': 'running',
   'activity.completed': 'completed',
   'activity.inactive': 'not running',
diff --git a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
index a4fe489714..fde31ff638 100644
--- a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
+++ b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
@@ -73,7 +73,7 @@ export function parseSubagentChatAddress(value: string): SubagentAddress | undef
   if (parts.length !== 2 || parts[0] !== 'session') return undefined
   const parentSessionId = url.searchParams.get('parent')
   const mode = url.searchParams.get('mode')
-  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable')) {
+  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable' && mode !== 'unknown')) {
     return undefined
   }
   try {
diff --git a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
index 49b2ac6016..a8e87cb283 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
@@ -152,6 +152,8 @@ describe('apply', () => {
     // One-shot stays read-only even while running: it has no stop action.
     expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true }, true)))
       .toEqual({ reason: 'one-shot' })
+    expect(select(owner({ address: { ...address, mode: 'unknown' }, parentAvailable: true })))
+      .toEqual({ reason: 'unknown' })
     expect(select(owner({ address }))).toBeNull()
     expect(select(owner({ address, parentAvailable: true }))).toBeNull()
     expect(select(owner({ address, parentAvailable: false })))
diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
index 626026fe54..44fad0a0b1 100644
--- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
@@ -25,7 +25,7 @@ const CHILD = 'child' as SessionId
 const GRANDCHILD = 'grandchild' as SessionId
 const t: SubagentHeaderLineageProps['t'] = makeTranslate(zh)
 
-type CatalogFixture = { entries: readonly SubagentCatalogRow[]; parentAvailable: boolean; state: 'loading' | 'ready' | 'error'; error: SessionListState['projectionsBySession'][SessionId]['error'] }
+type CatalogFixture = { entries: readonly (SubagentCatalogRow | { id: SessionId; mode: 'unknown'; label?: string; activity: 'inactive' })[]; parentAvailable: boolean; state: 'loading' | 'ready' | 'error'; error: SessionListState['projectionsBySession'][SessionId]['error'] }
 
 function catalog(over: Partial<CatalogFixture> = {}): CatalogFixture {
   return {
@@ -402,6 +402,16 @@ describe('SubagentHeaderLineage', () => {
     })
   })
 
+  it('keeps unknown catalog children clickable by their durable parent address', () => {
+    const input = props(catalog({ entries: [{ id: CHILD, mode: 'unknown', activity: 'inactive' }] }))
+    render(<SubagentHeaderLineage {...input} />)
+    hoverCatalog(screen.getByRole('button', { name: /子代理/ }))
+    const row = screen.getByRole('treeitem', { name: new RegExp(CHILD) })
+    expect(row.textContent).toContain('模式未知')
+    fireEvent.keyDown(row, { key: 'Enter' })
+    expect(input.openChild).toHaveBeenCalledWith({ parentSessionId: PARENT, childSessionId: CHILD, mode: 'unknown' })
+  })
+
   it('shows durable completion and token totals, ticks active duration, and freezes inactive rows', async () => {
     const now = 2_000_000_000_000
     const minute = 60_000
@@ -926,6 +936,11 @@ describe('SubagentReadOnlyComposer', () => {
     expect(screen.getByRole('status').textContent).toContain('父会话当前不在线')
   })
 
+  it('keeps an unknown child read-only until its descriptor is available', () => {
+    render(<SubagentReadOnlyComposer matched={{ reason: 'unknown' }} t={t} />)
+    expect(screen.getByRole('status').textContent).toContain('读取子会话后才能确定是否可继续')
+  })
+
   it('explains that one-shot histories never accept follow-ups', () => {
     render(<SubagentReadOnlyComposer matched={{ reason: 'one-shot' }} t={t} />)
     expect(screen.getByRole('status').textContent).toContain('一次性任务不支持后续消息')
diff --git a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
index 143a0cb595..0348f9c786 100644
--- a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
@@ -38,6 +38,8 @@ describe('Sidebar chat address', () => {
     expect(parseSubagentChatAddress(resource)).toEqual(ADDRESS)
     expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'one-shot' })))
       .toEqual({ ...ADDRESS, mode: 'one-shot' })
+    expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'unknown' })))
+      .toEqual({ ...ADDRESS, mode: 'unknown' })
   })
 
   it.each([
@@ -47,7 +49,7 @@ describe('Sidebar chat address', () => {
     'dsh-resource://subagentchat/other/child?parent=parent&mode=continuable',
     'dsh-resource://subagentchat/session/child?mode=continuable',
     'dsh-resource://subagentchat/session/child?parent=&mode=continuable',
-    'dsh-resource://subagentchat/session/child?parent=parent&mode=unknown',
+    'dsh-resource://subagentchat/session/child?parent=parent&mode=invalid',
     'dsh-resource://subagentchat/session/%?parent=parent&mode=continuable',
   ])('rejects %s', (address) => {
     expect(parseSubagentChatAddress(address)).toBeUndefined()
diff --git a/packages/core/session/src/known-event-types.ts b/packages/core/session/src/known-event-types.ts
index adaca29255..2679faecfb 100644
--- a/packages/core/session/src/known-event-types.ts
+++ b/packages/core/session/src/known-event-types.ts
@@ -58,6 +58,7 @@ export const KNOWN_SESSION_EVENT_TYPES: ReadonlySet<string> = new Set([
   'step/end',
   'step/start',
   'subagent/catalog',
+  'subagent/catalog-unknown',
   'subagent/descriptor',
   'subagent/model-selection-policy',
   'system/message',
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index 78975d4a43..cd09683c63 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -5745,7 +5745,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     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};',
+    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\' | \'unknown\';\n};',
   },
   {
     name: 'SessionAssistantStreamAttempt',
@@ -6429,7 +6429,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubagentCatalogEntry',
-    declaration: 'export type SubagentCatalogEntry = {\n    readonly id: SessionId;\n    readonly createdAt: number;\n} & ({\n    readonly mode: \'one-shot\';\n    readonly label?: string;\n} | {\n    readonly mode: \'continuable\';\n    readonly label: string;\n});',
+    declaration: 'export type SubagentCatalogEntry = {\n    readonly id: SessionId;\n    readonly createdAt: number;\n} & ({\n    readonly mode: \'one-shot\';\n    readonly label?: string;\n} | {\n    readonly mode: \'continuable\';\n    readonly label: string;\n} | {\n    readonly mode: \'unknown\';\n    readonly label?: string;\n});',
   },
   {
     name: 'SubagentCatalogRow',
diff --git a/packages/sdk/client/tests/sdk-client.spec.ts b/packages/sdk/client/tests/sdk-client.spec.ts
index 0fb2eafad1..2015d47d2c 100644
--- a/packages/sdk/client/tests/sdk-client.spec.ts
+++ b/packages/sdk/client/tests/sdk-client.spec.ts
@@ -647,6 +647,9 @@ describe('HarnessClient', () => {
     const inject = (method: string, params: Record<string, unknown>): void => {
       (client as unknown as { dispatchNotification(n: HarnessNotification): void }).dispatchNotification({ method, params })
     }
+    const unknownChild = { type: 'subagent/catalog-unknown', seq: 0, time: 1,
+      data: { version: 0, childId: 'unreadable-child', childCreatedAt: 1, mode: 'unknown' } }
+    inject('session.event', { sessionId: 'root', event: unknownChild })
     inject('subagent.started', { parentSessionId: 'root', childSessionId: 'child' })
     inject('subagent.started', { parentSessionId: 'child', childSessionId: 'grandchild' })
     inject('session.event', { sessionId: 'grandchild', event: { type: 'noop' } })
@@ -658,6 +661,7 @@ describe('HarnessClient', () => {
     inject('subagent.started', { parentSessionId: '', childSessionId: 'x' })
     inject('subagent.finished', { childSessionId: 'root' })
 
+    expect(await tree.next()).toEqual({ method: 'session.event', params: { sessionId: 'root', event: unknownChild } })
     expect((await tree.next()).method).toBe('subagent.started')
     expect((await tree.next()).method).toBe('subagent.started')
     expect((await tree.next()).params.sessionId).toBe('grandchild')
diff --git a/packages/session/session-format-v3-to-v4/README.i18n.yaml b/packages/session/session-format-v3-to-v4/README.i18n.yaml
index c22705c4fa..c5b3413814 100644
--- a/packages/session/session-format-v3-to-v4/README.i18n.yaml
+++ b/packages/session/session-format-v3-to-v4/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-format-v3-to-v4/README.md
-README.md: 4a6a58a0b1375ff3f318d7cf94bf008ec16ab9df
-README.zh.md: 7383dff61fd921976772a6cdaad9d98474f6c150
+README.md: 6721d43e7653942b055443a2da99d7fca1d6fd57
+README.zh.md: 48b7e5cbd00a19a81730cbf1310e462196cd8ca1
diff --git a/packages/session/session-format-v3-to-v4/README.md b/packages/session/session-format-v3-to-v4/README.md
index 4a6a58a0b1..6721d43e76 100644
--- a/packages/session/session-format-v3-to-v4/README.md
+++ b/packages/session/session-format-v3-to-v4/README.md
@@ -144,13 +144,13 @@ There is no recursive source search. Captured request text, assistant replay sta
 |---|---|
 | One descriptor with version 1 | Require string provider and label; derive `mode: 'continuable'`. |
 | One descriptor with version 2 or 3 | Require string provider; use its mode and optional label under catalog rules. |
-| Zero descriptors, or an unsupported descriptor version | May retain an existing parent entry; cannot create a missing entry. |
-| More than one own descriptor | Retain an existing parent entry without mode/label comparison; do not create a missing entry. |
+| Zero descriptors, or an unsupported descriptor version | Retain an existing parent entry; otherwise append unknown-mode membership. |
+| More than one own descriptor | Retain an existing parent entry without mode/label comparison; otherwise append unknown-mode membership. |
 | Existing own parent entry | Retain it and its extensions; require matching child creation time and mode/label from exactly one supported own descriptor, when available. |
 | Missing own parent entry with complete supported evidence | Append a version-0 catalog fact with child id, creation time, mode, and optional label. |
-| Missing own parent entry without complete evidence | Preserve the parent without inventing a catalog entry. |
+| Missing own parent entry without complete evidence | Append `subagent/catalog-unknown` with header identity and unknown mode, without inventing a label. |
 
-Catalog version 0 requires string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable` or `one-shot`, and a string label for continuable mode; a present one-shot label must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments.
+Catalog version 0 requires string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable` or `one-shot`, and a string label for continuable mode; a present one-shot label must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments. `subagent/catalog-unknown` separately records version 0, child id, creation time, and `mode: 'unknown'`; both event types contribute to the same unique-child catalog. Existing `subagent/catalog` payloads retain their mode requirements.
 
 The stage considers parent catalog records only after the final inherited cut. Every inherited marker discards earlier catalog candidates without interpreting their payloads. Missing entries append after all source events, sorted by creation time then child id, with dense new sequences. Their time is the final source event's time, or header creation time for an empty log. They neither enter the model surface nor change the inherited count.
 
@@ -243,7 +243,7 @@ Current common admission does not validate each user/tool/developer content bloc
 | `compaction/start`, `compaction/summary`, `compaction/end` | Match compaction id, source command, and the active turn context. Summary spans name exact current-surface nodes and exclude the protected head; successful completion has one summary. Inherited unfinished compactions expire at the end-seed marker. |
 | `compaction/prune` | Its span names exact current-surface nodes and excludes the protected head; it does not require a compaction transaction or its owner fields. |
 | Compact checkpoint replacement | Its `compact-checkpoint` source identifies the active compaction. |
-| Native `subagent/catalog` | Check own version-0 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
+| Native `subagent/catalog` and `subagent/catalog-unknown` | Check own version-0 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
 | Inherited cut and delivery | Apply the marker, coordinate, and generation-ownership rules stated above. |
 
 These checks are generation-owned in [relationships.ts](src/relationships.ts). Full common message/envelope acceptance and plugin-owned message projections additionally use the installed Session; the exported V4 restorer alone is not a replacement for complete catalog restoration.
@@ -334,7 +334,7 @@ The edge preserves the recorded request prefix. Provider cache availability and
 - **Nested historical tool results** — migration currently refuses results containing another tool-result wrapper. The original generation remains intact and no V4 successor is published. A later converter may support evidenced source cases without changing the established V4 format; the [migration cookbook](../../../docs/cookbook/adding-a-session-format-version.md#stages-and-validation) defines that distinction.
 - **Historical extension consumers** — prefixed message and result fields preserve JSON data without activating core fields. A consumer must explicitly understand those fields before interpreting them.
 - **Retained child logs required** — a parent alone cannot recover unrecorded child ids, creation times, or descriptors. Deleted children cannot be reconstructed from tool arguments; existing parent catalog records remain.
-- **Missing historical catalog entries** — without exactly one supported own descriptor, an absent parent entry is not backfilled. The child log remains readable by id; current V4 reads do not rescan children to repair that omission.
+- **Unknown historical modes** — without exactly one supported own descriptor, a missing parent entry records unknown mode. Current reads do not rewrite that entry; opening the child resolves available descriptor information or reports its own error.
 - **Storage scope** — facts cover recognizable children within the same persistence root. Cross-root import and corrupt-log repair are outside this migration.
 
 <a id="dev-note"></a>
diff --git a/packages/session/session-format-v3-to-v4/README.zh.md b/packages/session/session-format-v3-to-v4/README.zh.md
index 7383dff61f..48b7e5cbd0 100644
--- a/packages/session/session-format-v3-to-v4/README.zh.md
+++ b/packages/session/session-format-v3-to-v4/README.zh.md
@@ -144,13 +144,13 @@ V3 未知内容标签变为 `plugin:<original-type>`，其他字段原样保留
 |---|---|
 | 一个 version 1 descriptor | 要求字符串 provider 与 label；导出 `mode: 'continuable'`。 |
 | 一个 version 2 或 3 descriptor | 要求字符串 provider；按目录规则使用其 mode 和可选 label。 |
-| 没有 descriptor，或 descriptor 版本不受支持 | 可以保留已有父目录项；不能创建缺失项。 |
-| 多个自身 descriptor | 保留已有父目录项，不比较 mode／label；不创建缺失项。 |
+| 没有 descriptor，或 descriptor 版本不受支持 | 保留已有父目录项；否则追加模式未知的目录项。 |
+| 多个自身 descriptor | 保留已有父目录项，不比较 mode／label；否则追加模式未知的目录项。 |
 | 已有自身父目录项 | 保留条目及其扩展；要求子创建时间一致，并在恰好一个受支持的自身 descriptor 可用时比较其 mode／label。 |
 | 缺少自身父目录项，且受支持证据完整 | 追加带 child id、创建时间、mode 和可选 label 的 version-0 目录事实。 |
-| 缺少自身父目录项，且证据不完整 | 保留父 Session，不凭空创建目录项。 |
+| 缺少自身父目录项，且证据不完整 | 追加 `subagent/catalog-unknown`，记录 header 身份和未知模式，不编造标签。 |
 
-Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable` 或 `one-shot` mode，以及 continuable mode 下的字符串 label；存在的 one-shot label 也必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。
+Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable` 或 `one-shot` mode，以及 continuable mode 下的字符串 label；存在的 one-shot label 也必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。 `subagent/catalog-unknown` 单独记录 version 0、child id、创建时间和 `mode: 'unknown'`；两种事件共同组成 child id 唯一的目录。已有 `subagent/catalog` 载荷保留其 mode 要求。
 
 Stage 只把最终继承截点之后的父目录记录作为候选。每个 inherited marker 都会丢弃更早的目录候选，不解释其载荷。缺失项追加在所有源事件之后，按创建时间、child id 排序，并使用连续的新序号。时间取最后一个源事件的 time；空日志则取 header 创建时间。这些记录既不进入模型表面，也不改变继承计数。
 
@@ -243,7 +243,7 @@ System image 接纳要求非空 attachment id、PNG／JPEG／WebP／GIF MIME 类
 | `compaction/start`、`compaction/summary`、`compaction/end` | 匹配 compaction id、源 command 和活动 turn 上下文。Summary 区间引用精确的当前表面节点且排除 protected head；成功完成需要一个 summary。继承的未完成 compaction 在 end-seed marker 处过期。 |
 | `compaction/prune` | 其区间引用精确的当前表面节点且排除 protected head；它不要求存在 compaction 事务或其所有者字段。 |
 | Compact checkpoint 替换 | 其 `compact-checkpoint` 来源标识活动 compaction。 |
-| 原生 `subagent/catalog` | 检查继承截点之后的自身 version-0 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
+| 原生 `subagent/catalog` 与 `subagent/catalog-unknown` | 检查继承截点之后的自身 version-0 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
 | 继承截点与 delivery | 应用上文的 marker、坐标及代际归属规则。 |
 
 这些检查由 [relationships.ts](src/relationships.ts) 按代际拥有。完整的通用消息／信封接纳与插件拥有的消息投影还使用已安装 Session；单独的导出 V4 恢复器不能替代完整 catalog 恢复。
@@ -334,7 +334,7 @@ Fork 种子构造归核心 Session 所有，不属于此迁移。原生 V4 接
 - **历史嵌套工具结果**——当前迁移拒绝包含另一个 tool-result wrapper 的结果。原始代际保持完整，且不发布 V4 successor。后续转换器可以支持有证据的源数据场景，而不改变既定 V4 格式；[迁移 cookbook](../../../docs/cookbook/adding-a-session-format-version.zh.md#stages-and-validation) 定义了这一区别。
 - **历史扩展消费者**——带前缀的消息与结果字段保留 JSON 数据，不激活核心字段。消费者必须明确理解这些字段后才能解释它们。
 - **依赖保留的子日志**——仅凭父日志无法恢复未记录的子 id、创建时间或 descriptor。删除的子 Session 无法从工具参数恢复；已存在的父目录记录仍保留。
-- **历史目录项缺失**——没有恰好一个受支持的自身 descriptor 时，不补填父目录缺失项。子日志仍可按 id 读取；当前 V4 读取不会重新扫描子日志来补齐该条目。
+- **历史模式未知**——没有恰好一个受支持的自身 descriptor 时，缺失的父目录项记录未知模式。当前读取不重写该项；打开子会话时解析可用的 descriptor 信息，或报告该子会话的错误。
 - **存储范围**——事实只覆盖同一持久化根目录内可识别的子 Session。跨根目录导入和损坏日志修复不属于此迁移。
 
 <a id="dev-note"></a>
diff --git a/packages/session/session-format-v3-to-v4/src/facts.ts b/packages/session/session-format-v3-to-v4/src/facts.ts
index 23a0c233d0..a250801759 100644
--- a/packages/session/session-format-v3-to-v4/src/facts.ts
+++ b/packages/session/session-format-v3-to-v4/src/facts.ts
@@ -78,6 +78,21 @@ export function catalogFact(value: SessionFormatJsonValue, subject = 'subagent/c
   return value
 }
 
+/**
+ * Validate a current catalog entry retained without a supported child descriptor.
+ * @param value - decoded unknown-child payload.
+ * @returns the validated identity with unknown mode.
+ */
+export function unknownCatalogFact(value: SessionFormatJsonValue): SessionFormatJsonObject {
+  if (!isSessionFormatJsonObject(value) || value['version'] !== 0
+    || typeof value['childId'] !== 'string' || value['mode'] !== 'unknown'
+    || (value['label'] !== undefined && typeof value['label'] !== 'string')) {
+    throw new SessionFormatError('subagent/catalog-unknown requires a version 0 identity with unknown mode')
+  }
+  sessionFormatCount(value['childCreatedAt'], 'catalog child creation time')
+  return value
+}
+
 /**
  * Name the child and its optional storage-owned location in a migration diagnostic.
  * @param source - validated supplemental child evidence.
diff --git a/packages/session/session-format-v3-to-v4/src/migration.ts b/packages/session/session-format-v3-to-v4/src/migration.ts
index 3b1c1de60a..2184f5b819 100644
--- a/packages/session/session-format-v3-to-v4/src/migration.ts
+++ b/packages/session/session-format-v3-to-v4/src/migration.ts
@@ -122,9 +122,10 @@ class ReleasedV3ToV4Stage implements SessionFormatMigrationStage {
         }
         continue
       }
-      if (fact === undefined) continue
-      existingCatalogs.set(id, fact)
-      context.emitEvent({ type: 'subagent/catalog', seq: this.nextSeq++, time: this.time, data: fact })
+      const entry = fact ?? { version: 0, childId: id, childCreatedAt: source['childCreatedAt'] as number, mode: 'unknown' }
+      existingCatalogs.set(id, entry)
+      context.emitEvent({ type: fact === undefined ? 'subagent/catalog-unknown' : 'subagent/catalog',
+        seq: this.nextSeq++, time: this.time, data: entry })
     }
     return cut
   }
diff --git a/packages/session/session-format-v3-to-v4/src/validation.ts b/packages/session/session-format-v3-to-v4/src/validation.ts
index 8c0e74d61d..4b9df349cc 100644
--- a/packages/session/session-format-v3-to-v4/src/validation.ts
+++ b/packages/session/session-format-v3-to-v4/src/validation.ts
@@ -6,7 +6,7 @@ import type { SessionFormatArtifact, SessionFormatEvent } from '@deepseek-ai/dsh
 import { assertV4DeveloperData } from './developer.ts'
 import { assertV4LifecycleRelationships } from './relationships.ts'
 import { assertV4MessageSources } from './message-sources.ts'
-import { catalogFact } from './facts.ts'
+import { catalogFact, unknownCatalogFact } from './facts.ts'
 import { assertV4RetiredSyntax } from './retired-syntax.ts'
 import { assertV4SystemMessageFields } from './system-message.ts'
 import { assertV4ForkResult } from './fork-result.ts'
@@ -119,8 +119,8 @@ export function assertReleasedV4Relationships(artifact: SessionFormatArtifact, k
       && deliveryId !== artifact.header.id) {
       throw new SessionFormatError('current-generation delivery marker names the wrong Session')
     }
-    if (event.type === 'subagent/catalog' && event.seq >= artifact.inheritedEventCount) {
-      const fact = catalogFact(event.data)
+    if ((event.type === 'subagent/catalog' || event.type === 'subagent/catalog-unknown') && event.seq >= artifact.inheritedEventCount) {
+      const fact = event.type === 'subagent/catalog' ? catalogFact(event.data) : unknownCatalogFact(event.data)
       const id = fact['childId'] as string
       if (ids.has(id)) throw new SessionFormatError(`duplicate catalog child ${id}`)
       ids.add(id)
diff --git a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
index 7b1ad7e3c0..73733b0afc 100644
--- a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
@@ -74,7 +74,7 @@ describe('V3 parent catalog completion', () => {
   it('requires explicit corpus facts and refuses conflicting identities', () => {
     expect(() => sessionFormatV3ToV4.createStage({ sourceHeader: header, targetHeader: { ...header, version: 4 },
       sourceKind: 'decoded', sourceInheritedEventCount: 0 })).toThrow('explicit historical child facts')
-    expect(() => migrate([], [{ ...child, mode: 'unknown' }])).toThrow('complete version 0')
+    expect(() => migrate([], [{ ...child, mode: 'invalid' }])).toThrow('complete version 0')
     expect(() => migrate([{ type: 'subagent/catalog', seq: 0, time: 2, data: child }], [{ ...child, childCreatedAt: 3 }])).toThrow('conflicts')
   })
 
@@ -88,8 +88,8 @@ describe('V3 parent catalog completion', () => {
       ],
     }
     expect(childCatalogFact(historicalChildCatalogSource(artifact))).toEqual(child)
-    expect(migrate([], [historicalChildCatalogSource({ ...artifact, inheritedEventCount: 0 })]).events).toEqual([])
-    expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [] })]).events).toEqual([])
+    expect(migrate([], [historicalChildCatalogSource({ ...artifact, inheritedEventCount: 0 })]).events).toMatchObject([{ data: { childId: 'child', mode: 'unknown' } }])
+    expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [] })]).events).toMatchObject([{ data: { childId: 'child', mode: 'unknown' } }])
   })
   it('orders tied and differently dated children independently of directory enumeration', () => {
     const children = [{ ...child, childId: 'z' }, { ...child, childId: 'a' }, { ...child, childId: 'first', childCreatedAt: 1 }]
@@ -114,11 +114,11 @@ describe('V3 parent catalog completion', () => {
     expect(() => migrate([preceding, { ...delivery, data: { ...delivery.data, sessionFormatVersion: 3 } }], [])).toThrow('wrong Session')
   })
 
-  it('skips unavailable descriptors while requiring complete discovery fields for new facts', () => {
+  it('retains unknown children while validating available descriptor fields', () => {
     const artifact = { header: { ...header, origin: 'subagent' as const, parentSession: 'parent' }, inheritedEventCount: 0, events: [] }
     expect(() => historicalChildCatalogSource({ ...artifact, header })).toThrow('direct parent')
     for (const data of [null, {}, { version: 4, mode: 'one-shot', provider: 'spawn' }]) {
-      expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [{ type: 'subagent/descriptor', seq: 0, time: 1, data }] })]).events).toEqual([])
+      expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [{ type: 'subagent/descriptor', seq: 0, time: 1, data }] })]).events).toMatchObject([{ data: { childId: 'parent', mode: 'unknown' } }])
     }
     for (const value of [null, { ...child, version: 1 }, { ...child, childId: null },
       { ...child, label: null }, { ...child, childCreatedAt: -1 }]) {
@@ -148,7 +148,8 @@ describe('V3 parent catalog completion', () => {
     const unavailable = { childId: 'unavailable', childCreatedAt: 1,
       descriptorCount: kind === 'missing' ? 0 : kind === 'multiple' ? 2 : 1, descriptor }
     expect(migrate([], [child, unavailable]).events).toEqual([
-      { type: 'subagent/catalog', seq: 0, time: 1, data: child },
+      { type: 'subagent/catalog-unknown', seq: 0, time: 1, data: { version: 0, childId: 'unavailable', childCreatedAt: 1, mode: 'unknown' } },
+      { type: 'subagent/catalog', seq: 1, time: 1, data: child },
     ])
   })
 
diff --git a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
index 2d3c447842..a0e1f9e9de 100644
--- a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
@@ -113,6 +113,23 @@ describe('restoreReleasedV4Artifact', () => {
       .toThrow(/unseeded format v4 Session has inherited events/)
   })
 
+  it('retains unknown child membership and rejects invalid identities or duplicate child ids', () => {
+    const known = new Set([...KNOWN, 'subagent/catalog', 'subagent/catalog-unknown'])
+    const data = { version: 0, childId: 'unreadable', childCreatedAt: 2, mode: 'unknown' }
+    const event = { type: 'subagent/catalog-unknown', seq: 0, time: 1, data }
+    const valid = artifact([event])
+    expect(restoreReleasedV4Artifact(valid, known)).toBe(valid)
+    expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: { ...data, label: 'retained' } }]), known)).not.toThrow()
+    for (const invalid of [null, { ...data, version: 1 }, { ...data, childId: 1 },
+      { ...data, childCreatedAt: -1 }, { ...data, mode: 'one-shot' }, { ...data, label: null }]) {
+      expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: invalid }]), known)).toThrow()
+    }
+    expect(() => restoreReleasedV4Artifact(artifact([event, { ...event, seq: 1 }]), known)).toThrow('duplicate catalog child')
+    expect(() => restoreReleasedV4Artifact(artifact([event, { type: 'subagent/catalog', seq: 1, time: 1,
+      data: { ...data, mode: 'one-shot' } }]), known)).toThrow('duplicate catalog child')
+    expect(() => restoreReleasedV4Artifact(artifact([{ ...event, type: 'subagent/catalog' }]), known)).toThrow('complete version 0')
+  })
+
   it('validates only the envelope in physical mode', () => {
     const unknown = conversation()
     unknown.splice(2, 0, { type: 'campaign/unknown', seq: 0, time: 1, data: { x: 1 } })
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 21073ec706..166eaa18dc 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: af64ea90850ea0777ceb7c61d4c43dd1a0bc6707
-README.zh.md: b61d64e72aa76f58b3ed9534da15c8657952e46a
+README.md: 066b43d6a0f7c0e29b8c2ebbba17fa460103187a
+README.zh.md: 61693b96d904b8d2c3d679c065f3667eb3bdc46e
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index af64ea9085..066b43d6a0 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -81,7 +81,7 @@ The current-generation scanner applies the current codec owner’s structural ad
 
 `open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Current revisions identify that file; historical revisions also fingerprint the selected files across the persistence root, so child changes invalidate cached logical events. Fingerprinting reads filesystem metadata only; unrelated changes conservatively invalidate historical revisions. One `list()` call shares a corpus fingerprint across its historical entries. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
-Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers are omitted from discovery. Child decoding and descriptor-field failures produce warnings naming the child path and omit its backfill; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors provide no new fact. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
+Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers are omitted from discovery. Child decoding and descriptor-field failures produce warnings naming the child path and retain header identity through `subagent/catalog-unknown` when the parent has no complete entry; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors likewise produce unknown-mode membership without inventing a label. Published unknown entries remain browsable; child history reads retry the actual log and resolve its mode from a valid descriptor. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
 
 Historical `stat` and `list` revisions require metadata work proportional to the root’s Session count. Fresh body preparation scans all selected headers and decodes direct-child bodies; memo reuse still scans membership and checks revisions. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat that work. Current V4 body reads and revisions avoid the historical corpus scan. See the [measured costs and diagnostic command](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements).
 
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index b61d64e72a..61693b96d9 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -81,7 +81,7 @@ kind: "package-reference"
 
 `open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；每个嵌套对象和数组都会冻结，句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的修订号。当前格式修订号标识该文件；历史格式修订号还包含持久化根目录中所选文件的指纹，因此子日志变化会使缓存的逻辑事件失效。指纹只读取文件系统元数据；无关变化也会保守地使历史修订号失效。一次 `list()` 为其历史条目共用一个全库指纹。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
-历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header 不参与发现。子日志解码或 descriptor 字段失败会产生带子路径的警告，并跳过该项补填；健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 不提供新事实。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
+历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header 不参与发现。子日志解码或 descriptor 字段失败会产生带子路径的警告；父目录没有完整条目时，通过 `subagent/catalog-unknown` 保留 header 身份信息。健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 同样生成模式未知的目录项，不编造标签。已发布的未知条目仍可浏览；读取子历史时会重试实际日志，并从有效 descriptor 确定模式。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
 
 历史格式的 `stat` 与 `list` 修订号需要与根目录 Session 数量成正比的元数据工作。首次正文准备扫描所有所选 header 并解码直属子正文；复用准备缓存仍扫描成员集合并检查修订。只读访问从不发布升级，因此冷进程与被淘汰的准备缓存会重复这些工作。当前 V4 正文读取和修订号避开历史全库扫描。见[实测成本与诊断命令](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements)。
 
diff --git a/packages/session/session-persistence-jsonl/src/catalog-migration.ts b/packages/session/session-persistence-jsonl/src/catalog-migration.ts
index f07d5179a7..f0aefc057f 100644
--- a/packages/session/session-persistence-jsonl/src/catalog-migration.ts
+++ b/packages/session/session-persistence-jsonl/src/catalog-migration.ts
@@ -45,6 +45,8 @@ export async function prepareCatalogFacts(
       path: source.path, identity: await stat(source.path, { bigint: true }),
     }
     witnesses.push(witness)
+    const unavailable = { childId: source.header.id, childCreatedAt: source.header.createdAt,
+      descriptorCount: 0, descriptor: null, sourcePath: source.path }
     let restored: Awaited<ReturnType<typeof readDecodedJsonlSource>>
     try {
       restored = await readDecodedJsonlSource(source.path, version, compression, {
@@ -55,6 +57,7 @@ export async function prepareCatalogFacts(
     } catch (error: unknown) {
       signal.throwIfAborted()
       failures.push({ path: source.path, error })
+      facts.push(unavailable)
       continue
     }
     witness.identity = restored.identity
@@ -69,6 +72,7 @@ export async function prepareCatalogFacts(
       fact = historicalChildCatalogSource(restored.artifact)
     } catch (error: unknown) {
       failures.push({ path: source.path, error })
+      facts.push(unavailable)
       continue
     }
     facts.push({ ...fact, sourcePath: source.path })
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index e5046b45ad..24ee0d013e 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -634,7 +634,7 @@ class JsonlSessionPersistence extends SessionPersistence {
       const sources = await children()
       const related = await prepareCatalogFacts(id, sources, this.compression, signal)
       for (const failure of related.failures) {
-        this.ctx.logger.warn(`${this.name}: session "${id}" catalog omitted an unreadable child (raw log: ${failure.path}): ${String(failure.error)}`)
+        this.ctx.logger.warn(`${this.name}: session "${id}" catalog retained a child with unknown descriptor (raw log: ${failure.path}): ${String(failure.error)}`)
       }
       const membership = sources.map(source => source.path).sort()
       validateRelatedSources = async () => {
diff --git a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
index 209cc851f4..028edc5d1b 100644
--- a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
@@ -120,7 +120,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const catalog = { type: 'subagent/catalog', seq: 0, time: 1,
       data: { version: 0, childId: 'grandchild', childCreatedAt: 3, mode: 'one-shot' } }
     const path = await f.write('child', [catalog, { ...catalog, seq: 1 }], true, 4)
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
   })
@@ -136,7 +136,10 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const original = await readFile(childPath)
     await f.write('healthy', [f.descriptor], true)
     const parent = await f.ctx.sessionPersistence.open(f.parent, access)
-    try { expect((await parent.read()).events).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'healthy' } }]) } finally { await parent.close() }
+    try { expect((await parent.read()).events).toMatchObject([
+      { type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } },
+      { type: 'subagent/catalog', data: { childId: 'healthy', mode: 'continuable' } },
+    ]) } finally { await parent.close() }
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), access)).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
     expect(await readFile(childPath)).toEqual(original)
     await expect(readFile(generationLogPath(f.root, undefined, SessionId('child'), 4, compression))).rejects.toMatchObject({ code: 'ENOENT' })
@@ -167,16 +170,16 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const f = await fixture()
     const childPath = await f.write('child', [], true)
     await writeFile(childPath, Buffer.concat([await readFile(childPath), Buffer.alloc(8)]))
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
   })
 
-  it('keeps a complete parent catalog when a published child never writes a descriptor', async () => {
+  it.each([false, true])('keeps a complete parent catalog when child metadata is unavailable (corrupt=%s)', async (corrupt) => {
     const f = await fixture()
     const catalog = { type: 'subagent/catalog', seq: 0, time: 2,
       data: { version: 0, childId: 'child', childCreatedAt: 2, mode: 'one-shot', label: 'failed startup' } }
     const parentPath = await f.write(f.parent, [catalog])
-    const childPath = await f.write('child', [], true)
+    const childPath = await f.write('child', corrupt ? [{ type: 'future/required', seq: 0, time: 2, data: {} }] : [], true)
     const original = await Promise.all([readFile(parentPath), readFile(childPath)])
     expect(await f.read()).toEqual([catalog])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
@@ -205,10 +208,10 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const childPath = await f.write('child', events, true)
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
     const original = await Promise.all([readFile(parentPath), readFile(childPath)])
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    try { expect((await writer.read()).events).toEqual([]) } finally { await writer.close() }
-    expect(await f.read()).toEqual([])
+    try { expect((await writer.read()).events).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }]) } finally { await writer.close() }
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     const child = await f.ctx.sessionPersistence.open(SessionId('child'), 'read')
     try { expect((await child.read()).events).toEqual(events) } finally { await child.close() }
     expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
@@ -234,18 +237,18 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect(await f.read()).toEqual([])
   })
 
-  it('omits unsupported child contents without migrating the child', async () => {
+  it('retains unknown child identity without migrating unsupported contents', async () => {
     const f = await fixture()
     await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
   })
 
-  it('omits invalid descriptor fields and reports the child source', async () => {
+  it('retains unknown child identity and reports invalid descriptor fields', async () => {
     const f = await fixture()
     const warn = vi.spyOn(f.ctx.logger, 'warn')
     const path = await f.write('child', [{ ...f.descriptor, data: { version: 2, provider: 'spawn', mode: 'unknown' } }], true)
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
   })
 
@@ -280,7 +283,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
   it('recollects newly available discovery fields before publishing a prepared parent', async () => {
     const f = await fixture()
     const childPath = await f.write('child', [], true)
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     await f.write('child', [f.descriptor], true)
     await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(childPath)
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
@@ -380,13 +383,27 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
   it('recollects a repaired child before publishing a prepared parent', async () => {
     const f = await fixture()
     await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
     await f.write('child', [f.descriptor], true)
     expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child' } }])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
     await writer.close()
   })
 
+  it('keeps published unknown membership while a repaired child opens independently', async () => {
+    const f = await fixture()
+    await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+    const current = generationLogPath(f.root, undefined, f.parent, 4, compression)
+    const published = await readFile(current)
+    await f.write('child', [f.descriptor], true)
+    const child = await f.ctx.sessionPersistence.open(SessionId('child'), 'read')
+    try { expect((await child.read()).events).toEqual([f.descriptor]) } finally { await child.close() }
+    expect(await f.read()).toMatchObject([{ data: { childId: 'child', mode: 'unknown' } }])
+    expect(await readFile(current)).toEqual(published)
+  })
+
   it('completes only the opened parent catalog and defers its child catalog', async () => {
     const f = await fixture()
     const childPath = await f.write('child', [f.descriptor], true)
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index f2d1e1d365..37e5596037 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 7d62e423189906c49d9479bd7a6dbd14b7303afd
-README.zh.md: af62ad97bc4821222d46ed73509c823851953e1d
+README.md: 94da1be172b441aec1fd16d3853596eaee74ca1b
+README.zh.md: 462bc3aff2155b96f87d9f69c5aae1aa5002a9ca
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 7d62e42318..94da1be172 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -109,7 +109,7 @@ A request is validated against the provider's advertised capabilities, a durable
 
 The manager reserves a child identity, resolves the durable descriptor, creates (or cold-resumes) the child Agent, installs it in an Activation, and submits the prompt. Model-authored messages cross one parent/child edge through fixed Steer scheduling; browser human prompts choose Queue or best-effort Steer through an internal adapter, while other host protocols may retain Queue for distinct turns. A Session queue command admits a live subagent-owned Agent only from its own continuable descriptor. Settlement waits for Agent activity to finish, an empty Inbox, and no owned children, then flushes final Session state with admission open. Under the child lock, the manager revalidates the wake generation, Session sequence, Inbox, and owned children; the synchronous task entry of `Agent.runMaintenance()` claims the idle phase and closes the private subagent Inbox in the same JavaScript turn before handle disposal. An absent direct-child Activation cold-resumes from the persisted session. When a resident Activation settles, the manager tells the child's direct parent in the parent's own turn stream.
 
-Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives.
+Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives. Historical migration may instead append `subagent/catalog-unknown` from a readable child header. Its `mode: 'unknown'` projection keeps the child visible without claiming continuation support; an existing complete entry remains authoritative.
 
 ### Ownership and invariants
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index af62ad97bc..462bc3aff2 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -109,7 +109,7 @@ kind: "package-reference"
 
 管理器预留 child 身份、解析持久化描述符、创建（或冷恢复）child、把它安装进 Activation 并提交提示词。模型编写的消息通过固定 Steer 调度跨一条 parent/child 边；浏览器人类 prompt 通过内部适配器选择 Queue 或 best-effort Steer，其他 host 协议仍可保留 Queue 以创建独立轮次。Session queue command 仅根据 child 自身的 continuable descriptor 准入在线 subagent-owned Agent。Settlement 会等待 Agent 活动结束、Inbox 为空且没有所拥有子级，再在准入开放时 flush 最终 Session 状态。管理器随后在 child lock 内重新验证 wake generation、Session 序号、Inbox 与所拥有子级；`Agent.runMaintenance()` 的同步 task 入口会占用 idle 阶段，并在同一个 JavaScript turn 内关闭私有 subagent Inbox，然后才释放句柄。直接 child 不存在 Activation 时会从持久化会话冷恢复。当驻留 Activation 结算时，管理器会在 parent 自身的轮次流中告知该 child 的直接 parent。
 
-本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。
+本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。 历史迁移可根据可读子 header 追加 `subagent/catalog-unknown`。其 `mode: 'unknown'` 投影让子会话保持可见，但不表示支持继续执行；已有完整条目仍具有权威性。
 
 ### 所有权与不变式
 
diff --git a/packages/subagent/subagent/src/catalog.ts b/packages/subagent/subagent/src/catalog.ts
index 3ec29bbd2f..2fbc828892 100644
--- a/packages/subagent/subagent/src/catalog.ts
+++ b/packages/subagent/subagent/src/catalog.ts
@@ -31,6 +31,14 @@ export type SubagentCatalogEvent =
     | { readonly mode: 'continuable'; readonly label: string }
   )
 
+type UnknownCatalogEvent = {
+  readonly version: 0
+  readonly childId: SessionId
+  readonly childCreatedAt: number
+  readonly mode: 'unknown'
+  readonly label?: string
+}
+
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
@@ -38,13 +46,18 @@ declare module '@deepseek-ai/dsh-session/types' {
      * @param data - versioned parent-owned catalog entry.
      */
     'subagent/catalog': SubagentCatalogEvent
+    /**
+     * A historical child's header identity when its descriptor cannot establish a mode.
+     * @param data - child identity retained for discovery and later history reads.
+     */
+    'subagent/catalog-unknown': UnknownCatalogEvent
   }
 }
 
 /** Host fold state for one parent catalog. */
 export interface SubagentCatalogState {
   readonly inheritedEventCount: SessionLogOffset
-  readonly head?: ChunkedList<SubagentCatalogEvent> | undefined
+  readonly head?: ChunkedList<SubagentCatalogEvent | UnknownCatalogEvent> | undefined
 }
 
 const sessionIdSchema = z.string() as unknown as z.ZodType<SessionId>
@@ -62,10 +75,13 @@ const continuableCatalogSchema = z.object({
   mode: z.literal('continuable'),
   label: z.string(),
 }).strict()
+const unknownCatalogSchema = oneShotCatalogSchema.extend({ mode: z.literal('unknown') })
+const completeCatalogSchema = z.union([oneShotCatalogSchema, continuableCatalogSchema])
 const eventDataSchema = z.union([
   oneShotCatalogSchema,
   continuableCatalogSchema,
-]) as unknown as z.ZodType<SubagentCatalogEvent>
+  unknownCatalogSchema,
+]) as unknown as z.ZodType<SubagentCatalogEvent | UnknownCatalogEvent>
 const viewSchema = z.array(z.union([
   oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
     id: sessionIdSchema,
@@ -75,6 +91,10 @@ const viewSchema = z.array(z.union([
     id: sessionIdSchema,
     createdAt: continuableCatalogSchema.shape.childCreatedAt,
   }),
+  unknownCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+    id: sessionIdSchema,
+    createdAt: unknownCatalogSchema.shape.childCreatedAt,
+  }),
 ])) as unknown as z.ZodType<SubagentCatalogEntry[]>
 const stateSchema: z.ZodType<SubagentCatalogState> = z.object({
   inheritedEventCount: z.number().int().nonnegative() as unknown as z.ZodType<SessionLogOffset>,
@@ -88,14 +108,14 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 }
 
 /**
- * Materialize direct children from their parent's successful creation facts.
+ * Materialize complete and unknown-mode child identities from parent catalog events.
  * @param state - parent catalog fold state.
  * @returns current direct-child rows in parent catalog event order.
  */
 function subagentCatalogEntries(state: SubagentCatalogState): SubagentCatalogEntry[] {
   const entries: SubagentCatalogEntry[] = []
   for (const data of iterateChunkedList(state.head)) {
-    entries.push(data.mode === 'one-shot'
+    entries.push(data.mode !== 'continuable'
       ? {
         id: data.childId,
         createdAt: data.childCreatedAt,
@@ -118,10 +138,12 @@ export const subagentCatalogProjectionDefinition = {
   stateSchema,
   init: (_header: SessionHeader, inheritedEventCount: SessionLogOffset) => ({ inheritedEventCount }),
   apply: (state, event: SessionEvent) => {
-    if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount) return state
-    return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) }
+    if ((event.type !== 'subagent/catalog' && event.type !== 'subagent/catalog-unknown') || event.seq < state.inheritedEventCount) return state
+    const data = (event.type === 'subagent/catalog-unknown' ? unknownCatalogSchema : completeCatalogSchema)
+      .parse(event.data) as SubagentCatalogEvent | UnknownCatalogEvent
+    return { ...state, head: appendChunkedList(state.head, data) }
   },
-  stateVersion: 2,
+  stateVersion: 3,
   wire: { viewSchema, view: subagentCatalogEntries },
 } satisfies ProjectionDefinition<'subagentCatalog', SubagentCatalogState>
 
diff --git a/packages/subagent/subagent/src/control-types.ts b/packages/subagent/subagent/src/control-types.ts
index 10a8cfc426..965f4d70dc 100644
--- a/packages/subagent/subagent/src/control-types.ts
+++ b/packages/subagent/subagent/src/control-types.ts
@@ -71,7 +71,7 @@ export type SubagentListEntry =
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
 
-/** Durable parent/child address that selects subagent transport in the client. */
+/** Durable parent/child browsing address; unknown mode is resolved when child history is read. */
 export type SubagentAddress =
   & {
     readonly parentSessionId: SessionId
@@ -80,6 +80,7 @@ export type SubagentAddress =
   & (
     | { readonly mode: 'one-shot' }
     | { readonly mode: 'continuable' }
+    | { readonly mode: 'unknown' }
   )
 
 /** One human message addressed to a continuable direct child. */
diff --git a/packages/subagent/subagent/src/projection-types.ts b/packages/subagent/subagent/src/projection-types.ts
index c33a2df9fb..27201624fb 100644
--- a/packages/subagent/subagent/src/projection-types.ts
+++ b/packages/subagent/subagent/src/projection-types.ts
@@ -15,6 +15,7 @@ export type SubagentCatalogEntry =
   & (
     | { readonly mode: 'one-shot'; readonly label?: string }
     | { readonly mode: 'continuable'; readonly label: string }
+    | { readonly mode: 'unknown'; readonly label?: string }
   )
 
 /** Durable active-turn timing for one descriptor-backed child session. */
diff --git a/packages/subagent/subagent/tests/catalog.spec.ts b/packages/subagent/subagent/tests/catalog.spec.ts
index cfd51813fe..f8450cd93d 100644
--- a/packages/subagent/subagent/tests/catalog.spec.ts
+++ b/packages/subagent/subagent/tests/catalog.spec.ts
@@ -107,6 +107,8 @@ describe('subagent catalog projection', () => {
       fact(0, 'child-b', 1, { mode: 'one-shot' }),
       fact(1, 'child-a', 1, { mode: 'one-shot', label: 'once' }),
       fact(2, 'child-d', 3, { mode: 'continuable', label: 'later' }),
+      { type: 'subagent/catalog-unknown', seq: SessionSeq(3), time: 0,
+        data: { version: 0, childId: SessionId('unreadable'), childCreatedAt: 4, mode: 'unknown' } },
     ]
     const state = fold(events)
 
@@ -121,6 +123,7 @@ describe('subagent catalog projection', () => {
       { id: SessionId('child-b'), createdAt: 1, mode: 'one-shot' },
       { id: SessionId('child-a'), createdAt: 1, mode: 'one-shot', label: 'once' },
       { id: SessionId('child-d'), createdAt: 3, mode: 'continuable', label: 'later' },
+      { id: SessionId('unreadable'), createdAt: 4, mode: 'unknown' },
     ])
   })
 
diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py
index 0d1cc64097..cb889a6a6f 100644
--- a/python/sdk/tests/test_client.py
+++ b/python/sdk/tests/test_client.py
@@ -595,6 +595,15 @@ def test_client_keeps_unmatched_notifications_available_globally_while_subscribe
 def test_session_subscription_keeps_descendant_relationships_across_subscriptions() -> None:
     client = HarnessClient()
     with client.subscribe_session_notifications("main") as first:
+        unknown_child = {
+            "type": "subagent/catalog-unknown", "seq": 0, "time": 1,
+            "data": {"version": 0, "childId": "unreadable-child", "childCreatedAt": 1, "mode": "unknown"},
+        }
+        client._handle_message({
+            "jsonrpc": "2.0", "method": "session.event",
+            "params": {"sessionId": "main", "event": unknown_child},
+        })
+        assert first.next().payload == {"sessionId": "main", "event": unknown_child}
         client._handle_message({
             "jsonrpc": "2.0",
             "method": "subagent.started",

From 5992977f2ee459b798a4ec8c1dba656f0e75cb22 Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Sun, 20 Sep 2026 14:36:27 +0800
Subject: [PATCH 14/37] fix(pkg): make SEA native addon extraction atomic

@yao-pkg/pkg's SEA bootstrap extracts native addons from the VFS into a
per-user cache ($PKG_NATIVE_CACHE_PATH/pkg/<sha256>/) with plain
writeFileSync, so concurrent first starts of the same executable truncate
files another process has already mapped: SIGBUS on Linux, "Library not
loaded" for sharp's libvips on macOS. Extend the existing pnpm patch so the
three write sites go through a same-directory temporary file and
renameSync; a cache path is then either absent or complete, every process
finishes its own copy pass before it loads, and identical content makes
concurrent renames harmless without a lock. Cache location, hash keying,
and per-file comparison are unchanged. The single-exe Agent Note records
the decision and the measured before/after runs.

Closes #4664
---
 ...cutable-sdk-runtime-distribution.i18n.yaml |  4 +-
 ...ile-executable-sdk-runtime-distribution.md |  2 +
 ...-executable-sdk-runtime-distribution.zh.md |  2 +
 patches/@yao-pkg__pkg@6.21.0.patch            | 58 +++++++++++++++++--
 pnpm-lock.yaml                                |  6 +-
 5 files changed, 62 insertions(+), 10 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index d12179dde4..ce9821d058 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: 56c9770966647e97763e0eaf339e4589fba673fb
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 04351105a56304020f5696cf1ce82d7a83ed2ced
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: 2de12a542f6c17754eb494a9e42ba843573182cb
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: c391d7268ed55915aeefe4cb323dcf1350ad631f
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index 56c9770966..2de12a542f 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -23,6 +23,8 @@ The exe is packaged with the **`--sea` (enhanced SEA) mode** of [@yao-pkg/pkg](h
 
 `@yao-pkg/pkg` is an exact-pinned root `devDependency` invoked as `pnpm exec pkg`, with [`patches/@yao-pkg__pkg@6.21.0.patch`](../../../../patches/@yao-pkg__pkg@6.21.0.patch) removing the SEA bootstrap's `patchChildProcess` call. Unpatched, pkg rewrites spawned commands named `node` — including the string after a `-c`/`/c` flag, exactly the Bash tool's `bash -c` form — to the executable itself and stamps `PKG_EXECPATH` into every child environment, so a model-issued `node --version` silently boots the dsh CLI; Node's own SEA layer performs no such rewrite, and a SEA binary cannot impersonate plain Node because it always boots its embedded app. With the call removed, children resolve `node` through PATH like any other process (a machine without Node reports command-not-found honestly), no `PKG_EXECPATH` reaches children, absolute `process.execPath` spawns still re-enter the app, worker threads never applied the hook, and `process.pkg` sidecar selection is untouched.
 
+The same patch makes the SEA bootstrap's native-addon extraction atomic. On the first `dlopen` of an addon inside the VFS, pkg's `patchDlopen` copies the addon's package tree to `$PKG_NATIVE_CACHE_PATH/pkg/<sha256 of the .node file>/` (default `~/.cache/pkg/...`), a per-user directory that every concurrent process of the same executable shares; upstream writes each file straight to its final path with `writeFileSync`, which truncates a file another process may already have mapped and lets that process's `existsSync`/hash check read a half-written file. Concurrent first starts therefore die with SIGBUS on Linux or fail with `ERR_DLOPEN_FAILED: Library not loaded` on sharp's libvips on macOS ([#4664](https://github.com/deepseek-harness/deepseek-harness/issues/4664)). The patch routes the three write sites through a same-directory temporary file and `renameSync`, so a cache path is either absent or complete, every process finishes its own copy pass before it loads, and concurrent renames of identical content need no lock. The cache location, hash keying, and per-file comparison are unchanged, so a consumer that isolates the cache per instance through `PKG_NATIVE_CACHE_PATH` keeps working; worker threads only define the hook and never install it. Measured (linux-x64, node24 target, pkg 6.21.0, a probe that loads sharp with its 18 MB libvips library, 16 concurrent first starts against one empty cache, five rounds): 39 of 80 processes died with SIGBUS before the change and 0 of 80 after it, with no temporary files left behind.
+
 Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's testing-system "snapshot" (ACP replay expected outputs, `$DSH_SNAPSHOT`); this document says "VFS" for the former.
 
 ### The serving interface is a plugin inside the dsh application
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index 04351105a5..c391d7268e 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -23,6 +23,8 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 `@yao-pkg/pkg` 是精确钉版的根 `devDependency`，经 `pnpm exec pkg` 调用，并以 [`patches/@yao-pkg__pkg@6.21.0.patch`](../../../../patches/@yao-pkg__pkg@6.21.0.patch) 移除 SEA bootstrap 中的 `patchChildProcess` 调用。未打补丁时，pkg 会把 spawn 的 `node` 命令——包括 `-c`/`/c` 标志后的命令串，恰是 Bash 工具的 `bash -c` 形态——改写为 exe 自身，并向每个子进程环境注入 `PKG_EXECPATH`，模型下发的 `node --version` 会静默启动 dsh CLI；Node 自身的 SEA 层没有这种改写，且 SEA 二进制永远启动内嵌应用、无法充当纯 Node。移除该调用后，子进程像普通进程一样经 PATH 解析 `node`（无 Node 的机器如实报 command not found），子进程环境不再出现 `PKG_EXECPATH`，以 `process.execPath` 绝对路径 spawn 的重入不受影响，worker 线程本来就未应用该钩子，`process.pkg` 侧车选择也不受影响。
 
+同一补丁还把 SEA bootstrap 的原生插件解包改成原子写入。VFS 内的插件首次 `dlopen` 时，pkg 的 `patchDlopen` 会把该插件所在的包目录整棵拷到 `$PKG_NATIVE_CACHE_PATH/pkg/<.node 文件的 sha256>/`（默认 `~/.cache/pkg/...`），这是同一个 exe 的所有并发进程共用的按用户目录；上游用 `writeFileSync` 直接写目标路径，会把另一个进程可能已经映射的文件截断，并让该进程的 `existsSync`/哈希比对读到写了一半的文件。因此并发首次启动在 Linux 上以 SIGBUS 崩溃，在 macOS 上对 sharp 的 libvips 报 `ERR_DLOPEN_FAILED: Library not loaded`（[#4664](https://github.com/deepseek-harness/deepseek-harness/issues/4664)）。补丁让三处写入都经过同目录临时文件加 `renameSync`，于是缓存路径要么不存在、要么完整，每个进程都在加载前走完自己的拷贝，相同内容的并发 rename 不需要锁。缓存位置、哈希键与逐文件比对均未改变，通过 `PKG_NATIVE_CACHE_PATH` 按实例隔离缓存的消费方照常工作；worker 线程只定义该钩子而从不安装。 实测（linux-x64、node24 构建目标、pkg 6.21.0，一个加载 sharp 及其 18 MB libvips 库的探针，16 个进程对同一个空缓存并发首次启动，跑五轮）：改动前 80 个进程中 39 个以 SIGBUS 崩溃，改动后 80 个全部正常，且无残留临时文件。
+
 术语提醒：pkg 的 `/snapshot` VFS 与本仓库测试体系的「快照」（ACP（Agent Client Protocol）回放预期输出、`$DSH_SNAPSHOT`）无关，本文用「VFS」指前者。
 
 ### 对外服务接口是 dsh 应用中的插件
diff --git a/patches/@yao-pkg__pkg@6.21.0.patch b/patches/@yao-pkg__pkg@6.21.0.patch
index 9f0aa5919d..4facf1f7f2 100644
--- a/patches/@yao-pkg__pkg@6.21.0.patch
+++ b/patches/@yao-pkg__pkg@6.21.0.patch
@@ -1,8 +1,56 @@
 diff --git a/prelude/sea-bootstrap.bundle.js b/prelude/sea-bootstrap.bundle.js
-index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546f232fd23 100644
+index ac14980e953134f2285e326a5111cf52de717cf5..1b1c00d1274cba5f63487898a9d940e8870f4f19 100644
 --- a/prelude/sea-bootstrap.bundle.js
 +++ b/prelude/sea-bootstrap.bundle.js
-@@ -5356,6 +5356,39 @@ var require_sea_vfs_setup = __commonJS({
+@@ -63,6 +63,25 @@ var require_bootstrap_shared = __commonJS({
+           throw new Error("pkg: unknown compression codec id " + compression);
+       }
+     }
++    // Write `content` to `dest` through a same-directory temporary file and an
++    // atomic rename, so a concurrent process never observes a partially written
++    // addon: its existsSync/hash check and dlopen see either no file or a complete
++    // one. A direct writeFileSync truncates a file another process may already
++    // have mapped (SIGBUS on Linux, "Library not loaded" on macOS) and exposes the
++    // half-written bytes to that process's hash comparison.
++    function writeFileAtomic(dest, content) {
++      var tmp = dest + "." + process.pid + "." + Math.random().toString(36).slice(2) + ".tmp";
++      fs.writeFileSync(tmp, content);
++      try {
++        fs.renameSync(tmp, dest);
++      } catch (e) {
++        try {
++          fs.unlinkSync(tmp);
++        } catch (_) {
++        }
++        throw e;
++      }
++    }
+     function cpRecursive(src, dest) {
+       var st = fs.lstatSync(src);
+       if (st.isSymbolicLink()) {
+@@ -100,7 +119,7 @@ var require_bootstrap_shared = __commonJS({
+           return;
+         }
+       }
+-      fs.writeFileSync(dest, srcContent);
++      writeFileAtomic(dest, srcContent);
+     }
+     function patchDlopen(insideSnapshot) {
+       var ancestor = process.dlopen;
+@@ -134,10 +153,10 @@ var require_bootstrap_shared = __commonJS({
+               var dContent = fs.readFileSync(tmpModulePath);
+               var dHash = createHash("sha256").update(dContent).digest("hex");
+               if (hash !== dHash) {
+-                fs.writeFileSync(tmpModulePath, moduleContent);
++                writeFileAtomic(tmpModulePath, moduleContent);
+               }
+             } else {
+-              fs.writeFileSync(tmpModulePath, moduleContent);
++              writeFileAtomic(tmpModulePath, moduleContent);
+             }
+             newPath = tmpModulePath;
+           }
+@@ -5356,6 +5375,39 @@ var require_sea_vfs_setup = __commonJS({
          }
        };
      }
@@ -42,7 +90,7 @@ index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546
      var SEAProvider = class extends MemoryProvider {
        constructor(seaManifest) {
          super();
-@@ -5465,12 +5498,21 @@ var require_sea_vfs_setup = __commonJS({
+@@ -5465,12 +5517,21 @@ var require_sea_vfs_setup = __commonJS({
          }
          return -2;
        }
@@ -67,7 +115,7 @@ index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546
        }
        existsSync(filePath) {
          perf2.count("existsSync calls");
-@@ -5542,7 +5584,7 @@ var require_sea_vfs_setup = __commonJS({
+@@ -5542,7 +5603,7 @@ var require_sea_vfs_setup = __commonJS({
  var require_worker_bootstrap_string = __commonJS({
    "prelude/_worker-bootstrap-string.js"(exports2, module2) {
      "use strict";
@@ -76,7 +124,7 @@ index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546
    }
  });
 
-@@ -5560,7 +5602,6 @@ var require_sea_bootstrap_core = __commonJS({
+@@ -5560,7 +5621,6 @@ var require_sea_bootstrap_core = __commonJS({
      var insideSnapshot = vfs.insideSnapshot;
      var SNAPSHOT_PREFIX = vfs.SNAPSHOT_PREFIX;
      shared.patchDlopen(insideSnapshot);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dc16be7fbf..0aa5307d29 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -11,7 +11,7 @@ overrides:
 
 patchedDependencies:
   '@electron/osx-sign@1.3.3': 280e7b2816caf01423097d24e79107a66afeb563a348630ce9928ae8499a5861
-  '@yao-pkg/pkg@6.21.0': 07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337
+  '@yao-pkg/pkg@6.21.0': 75891fc22b277c145cafeab83e41baf4a70f5b8fe6dc0801c6a0b922d7ee88c7
   node-pty@1.2.0-beta.15: b40ae545608897914bd25fb009c97eeac478c34e8a910298ddcb01b746534bb0
 
 importers:
@@ -86,7 +86,7 @@ importers:
         version: 4.1.8(vitest@4.1.8)
       '@yao-pkg/pkg':
         specifier: 6.21.0
-        version: 6.21.0(patch_hash=07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337)(supports-color@9.4.0)
+        version: 6.21.0(patch_hash=75891fc22b277c145cafeab83e41baf4a70f5b8fe6dc0801c6a0b922d7ee88c7)(supports-color@9.4.0)
       '@yarnpkg/cli-dist':
         specifier: 4.17.1
         version: 4.17.1
@@ -23016,7 +23016,7 @@ snapshots:
       - bare-buffer
       - react-native-b4a
 
-  '@yao-pkg/pkg@6.21.0(patch_hash=07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337)(supports-color@9.4.0)':
+  '@yao-pkg/pkg@6.21.0(patch_hash=75891fc22b277c145cafeab83e41baf4a70f5b8fe6dc0801c6a0b922d7ee88c7)(supports-color@9.4.0)':
     dependencies:
       '@babel/generator': 7.29.7
       '@babel/parser': 7.29.7

From e3f0d3fb6e2a4acb12f7904f2e5267e2f4630abe Mon Sep 17 00:00:00 2001
From: liukx0205 <harusoda@berkeley.edu>
Date: Wed, 16 Sep 2026 16:28:28 +0800
Subject: [PATCH 15/37] fix(web): preserve session engagement across blank list
 refreshes

---
 ...ession-scope-and-provide-channel.i18n.yaml |   4 +-
 ...lient-session-scope-and-provide-channel.md |  19 +-
 ...nt-session-scope-and-provide-channel.zh.md |  19 +-
 ...ent-session-blank-reconciliation.i18n.yaml |   6 +
 ...-15-client-session-blank-reconciliation.md |  43 +++
 ...-client-session-blank-reconciliation.zh.md |  43 +++
 apps/web/tests/replay-round-trip.e2e.ts       | 140 +++++--
 .../api/session-controller/README.i18n.yaml   |   4 +-
 packages/api/session-controller/README.md     |   2 +
 packages/api/session-controller/README.zh.md  |   2 +
 .../src/client/sessions/lineage.ts            |   5 +-
 .../src/client/sessions/manager.ts            |  59 ++-
 .../src/client/sessions/service.ts            |   3 +-
 .../src/client/sessions/session.ts            |  34 +-
 .../tests/manager.client.spec.ts              | 341 +++++++++++++++++-
 .../tests/session.client.spec.ts              |  24 ++
 .../accepted-reconnect.expected.md            |   6 +
 17 files changed, 675 insertions(+), 79 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
 create mode 100644 snapshots/web/fresh-round-trip/accepted-reconnect.expected.md

diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index e891710dea..51b99eb8e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.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-client-session-scope-and-provide-channel.md
-2026-07-25-web-client-session-scope-and-provide-channel.md: 990a9b6eef862a7ac4a549358beae7f9081eaa0b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 5c90611fab36611766bb407138c4f0c8a6b3a01b
+2026-07-25-web-client-session-scope-and-provide-channel.md: 32be87f3a0a4f8da92100ec7351af788862532f7
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: b2e7efae98efb69d5f34d6719a382221ffc7a00d
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
index 990a9b6eef..32be87f3a0 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
@@ -28,7 +28,7 @@ Host-side `session.create(workspaceId)` produces Session + Agent + cwd in one pi
 - Session identity is the host's true form from birth: the sessionId arrives via the `session.create` response / the `host/session-added` frame, and every client-side address (the scope tag, slot store keys, RPC addressing) uses that same id.
 - The materialization moment = the instant the user picks a Workspace (cwd settled): the client calls `session.create({workspaceId})` on the spot and receives the complete entity.
 - "New Session with no workspace picked" is a **pure view state** (a navigation position) corresponding to no session/scope entity; until the pick, the composer is locked whole (no slash, no plain text).
-- A "blank session" is just an ordinary materialized session whose log is still empty; to every Agent-scope plugin on the host (goal/plan/skill/…) it is indistinguishable from any session, so slash/plan are all naturally live.
+- A "blank session" is an ordinary materialized session with no turn yet; to Agent-scope plugins on the host (goal/plan/skill/…) it remains an ordinary Session, so slash/plan are naturally live.
 
 ### Agent scope: the actx is the sole session carrier in the client-side cordis world
 
@@ -63,14 +63,14 @@ Session instances share the scope's lifecycle, while the catalog reports discove
 
 A session "materialized but with no first prompt" is governed by the summary-derived bit `blank` (a derived column, not a header field; SessionHeader stays immutable):
 
-- The Host criterion is absence of `turn/start`; slash-command and configuration events do not clear `blank`. Live summaries use the Session projection. Cold summaries use cached metadata, leaving cache misses visible as unknown. Reuse acquires the writer under [blank Session acquisition](2026-09-17-process-local-blank-sessions.md).
+- The Host criterion is absence of `turn/start`: the `sessionListMetadata.blank` projection starts true and only that event clears it, so slash-command, configuration, and creation-checkpoint events leave it true even after they reach disk — blank does not mean unpersisted. Missing metadata falls back to `session.seq === 0` for live Sessions and false for cold ones; cold summaries otherwise read cached metadata, leaving cache misses visible as unknown. Reuse acquires the writer under [blank Session acquisition](2026-09-17-process-local-blank-sessions.md).
 - The wire carries it in two places: the required `SessionSummary.blank` column, and the required `blank` field on the `host/session-added` frame (always true at creation, letting other tabs enter the same blank-session state into their mirrors).
-- The client mirror only lowers, never raises (monotonic), flipped from three sources, all reusing existing wire signals:
-  - The sender's own tab: the **successful response** to the first `prompt()` flips false (acceptance proves the user/message is already in the host log — this flip is confirmation, not optimism; `onEngaged` synchronously updates the list mirror, converting the current `New Session` row in place to an ordinary title, adding no list row). A rejected first prompt keeps the session blank: aligned with host authority, still shown as `New Session`, keeping its connectWorkspace reuse eligibility while it remains a Workspace member.
-  - Other tabs: the `host/session-status (running:true)` frame flips it — a blank session never runs, so the first running necessarily means no longer blank;
-  - Reconnect alignment: `session.list`'s summary.blank is authoritative, so a tab that missed frames aligns naturally on its next pull; a stale blank:true can never mark a converted session back to blank.
+- Client display also reflects accepted/running observations, whose retention the [blank rollback decision](../bug-fix/2026-09-15-client-session-blank-reconciliation.md) owns:
+  - The sender's own tab: the **successful response** to the first `prompt()` converts the current `New Session` row in place, adding no list row — acceptance is display memory, not proof that a turn or user message reached durable history. A rejected first prompt keeps the session blank: aligned with host authority, still shown as `New Session`, keeping its connectWorkspace reuse eligibility while it remains a Workspace member.
+  - Other tabs: the `host/session-status (running:true)` frame converts it — a blank session never runs, so the first running necessarily means no longer blank;
+  - Reconnect alignment: a list pull updates Host summaries while the Manager keeps those observations, and a `sessionListMetadata` hint of existing history prevents re-blanking on top of that; an empty-history response cannot mark a converted session back to blank.
 - List discipline: the store retains every row; the Workspace browser's grouping, flat view, search, and counts share one visible projection — every non-blank session shows, while blank sessions show only the row retained by the `mainView` source, with its title forced to `New Session`. After a Workspace switch, the old blank entity stays in the mirror but is hidden from the list while the target Workspace's main blank shows; the user-visible surface therefore holds at most one blank row globally.
-- Blank Sessions can persist through creation checkpoints and command events. Browser reloads and Host restarts reuse eligible blanks after acquiring their writer; occupied blanks are skipped. Old logs remain on disk without automatic cleanup.
+- Blank Sessions can persist through creation checkpoints and command events, and have no automatic garbage collection: browser reloads, Host restarts, and Workspace connections reuse eligible blanks after acquiring their writer and skip occupied candidates, while list-loading and multi-tab races can still create additional blank Sessions, whose old logs remain on disk.
 
 ### connectWorkspace: the sole entry point of New Session
 
@@ -129,12 +129,13 @@ Blank Sessions retain the header's leading and corner slots so navigation contro
 | Components receiving wiring-callback bundles (two-layer inject→props pass-down) | The standard-kit channel lets components fetch their own; the public API converges to hooks + stable props |
 | Swapping the no-session Hero view for the entire session Conversation | Even with the outer layout unchanged, the Hero, picker, and composer subtrees would remount together, making the whole UI region jump |
 | Making InputBar itself `session-maybe` | The input state machine, keyboard command surface, and actions would all have to accept absent values; replacing only the disabled input body keeps optionality at the shell boundary |
-| A dedicated conversion frame | `session-status(running:true)` semantically implies conversion (a blank session never runs); adding a frame buys zero information for one more wire type |
+| A dedicated conversion frame | Existing acceptance and running signals provide the observations used by the display rule; a new frame is unnecessary for that rule |
 
 ## Consequences
 
 - Plugins gain session context isomorphic to the host's: per-session state hangs on the actx and mounts/tears down in one piece with the scope fiber, making leaks structurally impossible; two-session isolation is structurally guaranteed by the scope filter.
 - The client object layer converges to a wire mirror: session identity, lifecycle, and capability adjudication all defer to the host entity — the input system (the next layer) always faces a session with a real Agent, and providers like slash/skill uniformly address by sessionId directly.
-- Blank-session governance takes zero dedicated mechanisms: state rides one derived bit, visibility rides the unified list projection (only the current blank shows, as `New Session`), reuse acquires the persisted writer, and the ordinary ceiling rides same-Workspace reuse.
+- Blank-session governance takes zero dedicated mechanisms: state rides one derived bit, visibility rides the unified list projection (only the current blank shows, as `New Session`), reuse acquires the persisted writer, and the ordinary ceiling rides same-Workspace reuse. The accepted/running display memory that guards the conversion is Client-local.
+
 - The cost: the id→ctx handoff discipline and provide's Concurrent discipline are conventions rather than type-enforced, pinned by review and tests. The single state axis still withholds machine faces until a Session exists; the [resident conversation shell](../../../../packages/client/ui-conversation/README.md) routes activation to the Workspace picker during that interval.
 - Known gaps: approval/question recovery across prune (TODO); model selection returns in live-mutation shape (the host `selectModel` trio is ready-made, its client consumer not yet built).
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 5c90611fab..b2e7efae98 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -28,7 +28,7 @@ host 侧 `session.create(workspaceId)` 一体产出 Session + Agent + cwd（作
 - 会话身份自出生即为 host 真身：sessionId 由 `session.create` 响应 / `host/session-added` 帧带来，client 侧一切寻址（scope tag、slot store 键、RPC 地址）用的都是同一个 id。
 - 实体化时点 = 用户选定 Workspace（cwd 确定）的瞬间：client 当场调 `session.create({workspaceId})`，拿到完整实体。
 - 「New Session 且未选 workspace」是**纯视图态**（一个导航位置），不对应任何会话/scope 实体；选定之前 composer 整体锁死（无 slash、无纯文本）。
-- 「空会话」就是一个日志还空着的普通实体化会话；对 host 上所有 Agent-scope 插件（goal/plan/skill（技能）/…）它与任何会话无异，slash/plan 天然全活。
+- 「空会话」是尚无轮次的普通实体化会话；对 host 上的 Agent-scope 插件（goal/plan/skill（技能）/…）而言，它仍是普通 Session，因此 slash/plan 自然可用。
 
 ### Agent scope：actx 是 client 侧 cordis 世界的唯一会话载体
 
@@ -63,14 +63,14 @@ Session 实例与 scope 同生命周期；catalog 只报告可发现性，不持
 
 「实体化但无首条提示词」的会话经 summary 派生位 `blank` 治理（派生列而非 header 字段，SessionHeader 保持不可变）：
 
-- Host 判据是没有 `turn/start`；slash 命令与配置事件不会清除 `blank`。Live summary 使用 Session 投影。Cold summary 使用缓存元数据，缓存缺失时以未知状态保留在列表中。复用按[空白 Session 获取](2026-09-17-process-local-blank-sessions.zh.md)规则取得写锁。
+- Host 判据是没有 `turn/start`：`sessionListMetadata.blank` 投影初始为 true，且只有该事件会清除它，因此 slash 命令、配置事件与创建检查点即使已落盘也不会清除——blank 不代表未持久化。metadata 缺失时，live Session 回退到 `session.seq === 0`，cold Session 回退到 false；cold summary 其余情况读缓存元数据，缓存缺失时以未知状态保留在列表中。复用按[空白 Session 获取](2026-09-17-process-local-blank-sessions.zh.md)规则取得写锁。
 - wire 承载两处：`SessionSummary.blank` 必填列；`host/session-added` 帧必填 `blank` 字段（创建时恒 true，供别的 tab 按同一空会话状态入镜像）。
-- client 镜像只降不升（单调），三来源翻转，全部复用既有 wire 信号：
-  - 发送方本地：首次 `prompt()` 的**成功响应**翻 false（受理即证明用户消息已入 host 日志——此点翻转是确证而非乐观；`onEngaged` 同步更新列表镜像，当前 `New Session` 行原地转为普通标题，不新增列表行）。首条提示词被拒则会话保持 blank：与 host 权威对齐、继续显示为 `New Session`、在仍为该工作区成员时保持 connectWorkspace 复用资格。
-  - 其他端：`host/session-status (running:true)` 帧翻转——blank 会话从不 running，首次 running 必然已非 blank；
-  - 重连对齐：`session.list` 的 summary.blank 是权威，错过帧的端下次拉取自然对齐；陈旧的 blank:true 不能把已转正的会话重新标回 blank。
+- 客户端展示还受已观察到的受理/运行影响，其保留期限由 [blank 回退修复决策](../bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md) 拥有：
+  - 发送方本地：首次 `prompt()` 的**成功响应**把当前 `New Session` 行原地转正，不新增列表行——受理是展示记忆，不证明轮次或用户消息已写入持久历史。首条提示词被拒则会话保持 blank：与 host 权威对齐、继续显示为 `New Session`、在仍为该工作区成员时保持 connectWorkspace 复用资格。
+  - 其他端：`host/session-status (running:true)` 帧转正——blank 会话从不 running，首次 running 必然已非 blank；
+  - 重连对齐：列表拉取更新 Host 摘要，Manager 则保留这些观察；在此基础上，`sessionListMetadata` 提示已有历史也会阻止回退 blank，因此空历史响应不能把已转正的会话标回 blank。
 - 列表纪律：store 保留全部行；Workspace browser 的分组、平铺、搜索和计数共用同一可见投影——所有非 blank 会话都显示，blank 会话只显示由 `mainView` 来源持有的一行，并强制标题为 `New Session`。切换 Workspace 后，旧 blank 实体仍在镜像中但从列表隐藏，目标 Workspace 的主 blank 显示；因此用户可见面全局至多一条 blank 行。
-- 空白 Session 可以通过创建检查点与命令事件持久化。浏览器刷新与 Host 重启会在取得写锁后复用符合条件的空白会话，并跳过被占用的候选。旧日志保留在磁盘上，不自动清理。
+- blank Session 可以通过创建检查点与命令事件持久化，且没有自动垃圾回收：浏览器刷新、Host 重启与工作区连接会在取得写锁后复用符合条件的空白会话并跳过被占用的候选；但列表加载与多 tab 竞态仍可能创建额外的 blank Session，其旧日志保留在磁盘上。
 
 ### connectWorkspace：New Session 的唯一入口
 
@@ -129,12 +129,13 @@ blank Session 保留 header 的 leading 与 corner slot，让右侧栏展开入
 | 组件收 wiring 回调包（inject→props 两层下传） | 标准件通道让组件自取；公共 API 收敛为 hooks + 稳定 props |
 | Hero 无会话视图与会话 Conversation 整支互换 | 即使外层 layout 不变，Hero、picker 与 composer 子树仍会一起重建，界面产生整块抖动 |
 | 让 InputBar 自身变成 `session-maybe` | 输入状态机、键盘命令面与动作都被迫接受缺省值；只替换 disabled 输入体能把可选性留在外壳边界 |
-| 专用「转正」帧 | `session-status(running:true)` 语义蕴含转正（blank 会话从不 running），加帧是 wire 多一型换零信息 |
+| 专用「转正」帧 | 既有受理和运行信号已经提供展示规则所需的观察；该规则不需要新增帧 |
 
 ## 后果
 
 - 插件获得与 host 同构的会话上下文：逐会话状态挂 actx、随 scope fiber 一次拆装，泄漏结构性不可能；双会话隔离由 scope filter 结构性保证。
 - client 对象层收敛为 wire 镜像：会话身份、生命周期、能力判别全部以 host 实体为准——输入体系（下一层）面对的永远是「有真 Agent 的会话」，slash/skill 等提供方一律以 sessionId 直接寻址。
-- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），复用时获取持久化写锁，常规上限靠同 Workspace 复用。
+- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），复用时获取持久化写锁，常规上限靠同 Workspace 复用。转正所依赖的受理/运行展示记忆仅保留在客户端。
+
 - 代价：id→ctx 换乘纪律、provide 的 Concurrent 纪律都是约定而非类型强制，靠 review 与测试钉住。单一状态轴仍会在 Session 存在前隐藏 machine face；这段时间内，[常驻会话壳](../../../../packages/client/ui-conversation/README.zh.md)会把激活操作转到 Workspace picker。
 - 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，其 client 消费方尚未构建）。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
new file mode 100644
index 0000000000..6060e1c4b6
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.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/bug-fix/2026-09-15-client-session-blank-reconciliation.md
+2026-09-15-client-session-blank-reconciliation.md: c9fe88f82f088f03539f8487740c83437bc53ade
+2026-09-15-client-session-blank-reconciliation.zh.md: 70e144b552d1dabfecb428db04894ad4007011c5
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
new file mode 100644
index 0000000000..c9fe88f82f
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
@@ -0,0 +1,43 @@
+# Agent Note: Keep accepted Session presentation across list refreshes
+
+Status: implemented
+
+English | [中文](2026-09-15-client-session-blank-reconciliation.zh.md)
+
+## Problem
+
+A successful prompt response converts the Client's `New Session` row before a turn necessarily starts. A later `session.list` response can still report `blank: true` and undo that conversion. Reconnect triggers the same refresh. Keeping the conversion only inside a Session object also loses it when that object is replaced.
+
+## Decision
+
+The [Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) retains accepted/running observations in a private set keyed by Session id. List rows and the existing Session blank updates use `summary.blank && !engagedSessions.has(sessionId)`. The existing summary mutations, Session snapshot fields, constructor, and projection stores retain their responsibilities.
+
+Every successful prompt response invokes the existing `onEngaged` callback, including from a replaced Session object. The Manager updates its retained observation, the list row, and the currently resident Session by id. Rejection records no engagement. A `running: true` status, addition, or list baseline also records engagement; a baseline predating removal cannot restore that observation, even if the row is re-added during the pull.
+
+The observation survives refresh, reconnect, and object replacement. Removal, drop, and successful list refresh forget it only when no list row, Session object, or child address retains the identity. Refresh evaluates retention after replaying in-flight mutations; failed and superseded pulls do not prune observations. Late acceptance cannot recreate a removed row or a Session object. Manager disposal clears the set and prevents late acceptance and outstanding list responses from publishing.
+
+Engagement is display memory, not proof that a turn started, work remains queued, or a message reached durable storage. It is not persisted across page reload. Historical `sessionListMetadata.blank` and the Host summary defaults are unchanged.
+
+## Alternatives considered
+
+**Preserve every previously false summary bit.** A previous Host summary is not evidence of local acceptance or running. Making all false values permanent would also suppress later Host corrections without either observation.
+
+**Introduce a shared Session record.** Combining this memory with projection stores requires constructor and cache-lifetime changes. Those changes are independent of preventing a blank rollback and are excluded.
+
+**Wait for history before converting the row.** This changes the existing acceptance-time display rule and is a separate UI decision.
+
+## Consequences
+
+Accepted or observed-running Sessions retain their existing display conversion, including when accepted input never starts a turn. Drafts, submission-error recovery, sidebar filtering and title rules, creation/reuse, UUIDs, Host protocol, persistence, and projection-cache lifetimes are unchanged. Reverting this Client-only fix needs no data migration.
+
+The Manager owns one additional per-id display flag. It does not replace Session-local presentation fields or implement a history/draft/presentation redesign.
+
+For an identity with neither subagent origin nor a retained child address, a removal notification discards its projection store, while a retained Session object keeps the store it was constructed with — for example a current row removed while its Session is still staged. If that identity returns to the list before its Session object is dropped, the Manager creates and seeds a second store that the resident object never reads, so list rows and that object's projection readers can disagree until a replacement instance adopts the current store. Repairing that projection ownership is deferred to its own change; blank display does not depend on it.
+
+## Verification
+
+Manager tests cover refresh without a turn, running-to-idle updates, object replacement, late acceptance, removal through notifications or list reconciliation, retained instances and child addresses, failed and superseded pulls, and disposal. They check both list and Session state where an instance exists. Session tests retain first-send rejection and later-send behavior. Browser verification uses the recorded first-turn scenario with acceptance held before `turn/start` and a same-page reconnect. A timestamp substituted only in the reconnect list response provides a visible synchronization marker; the Host's blank/running values and durable log remain unchanged.
+
+## Related decisions
+
+The [scope and provisioning decision](../architecture/2026-07-25-web-client-session-scope-and-provide-channel.md) owns Session scope, creation/reuse, and the visible blank row. The [Session/Conversation ownership decision](../architecture/2026-08-20-client-session-conversation-ownership.md) owns transport, assembly, and snapshot contents.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
new file mode 100644
index 0000000000..70e144b552
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: 在列表刷新后保留已受理会话的展示状态
+
+Status: implemented
+
+[English](2026-09-15-client-session-blank-reconciliation.md) | 中文
+
+## 问题
+
+提示词请求成功后，客户端会把 `New Session` 行转换为普通会话，但此时轮次不一定已经开始。后续 `session.list` 响应仍可能返回 `blank: true`，从而撤销该转换。重连会触发同样的刷新。若只在 Session 对象内保留转换状态，对象被替换时也会丢失。
+
+## 决策
+
+[Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) 使用按 Session id 索引的私有集合，保留已观察到的受理/运行。列表行与既有 Session blank 更新使用 `summary.blank && !engagedSessions.has(sessionId)`。既有摘要变更、Session 快照字段、构造函数和投影存储保留原有职责。
+
+每个成功的提示词响应都会调用既有 `onEngaged` 回调，包括来自已被替换的 Session 对象的响应。Manager 按 id 更新其保留的观察、列表行和当前驻留 Session。拒绝不会记录受理/运行。`running: true` 状态、添加事件或列表基线也会记录运行；早于移除的基线不能恢复该观察，即使该行在拉取期间重新加入。
+
+该观察跨刷新、重连和对象替换保留。移除、drop 和成功的列表刷新仅在列表行、Session 对象及子会话地址均不再保留该身份时清除它。刷新在重放请求期间的变更后判断保留资格；失败及被替代的请求不会清理观察。迟到的受理不能重建已移除的行或 Session 对象。Manager 销毁会清空集合，并阻止迟到的受理和未完成的列表响应发布。
+
+受理/运行是展示记忆，不证明轮次已经开始、工作仍在排队，或消息已经写入持久存储。它不会跨页面重载持久化。历史 `sessionListMetadata.blank` 与 Host 摘要默认值保持不变。
+
+## 考虑过的替代方案
+
+**保留所有曾为 false 的摘要位。** 先前的 Host 摘要不能证明客户端观察过受理或运行。将所有 false 永久保留，也会在两种观察均不存在时阻止后续 Host 校正。
+
+**引入共享 Session 记录。** 将这份记忆与投影存储合并，需要修改构造参数及缓存生命周期。这些改动独立于防止 blank 回退，因此不纳入。
+
+**等待历史后再转换行。** 这会改变现有的受理时展示规则，属于独立的 UI 决策。
+
+## 后果
+
+已受理或观察过运行的 Session 保持既有展示转换，包括已受理输入始终没有开始轮次的情况。草稿、发送错误恢复、侧边栏筛选与标题规则、创建/复用、UUID、Host 协议、持久化及投影缓存生命周期保持不变。回退这项纯客户端修复不需要数据迁移。
+
+Manager 额外维护一个按 id 保存的展示标记。它不替代 Session 本地展示字段，也不实施历史/草稿/展示状态重构。
+
+对于来源不是 subagent、也没有保留子会话地址的身份，移除通知会丢弃它的投影存储，而仍被保留的 Session 对象继续持有构造时采用的存储，例如当前行被移除而它的 Session 仍留在舞台上。若该身份在其 Session 对象被销毁前回到列表，Manager 会新建并写入第二个存储，而常驻对象从不读取它，因此在替换实例采用当前存储之前，列表行与该对象的投影读取方可能不一致。该投影归属的修复延期到独立的改动；blank 展示不依赖它。
+
+## 验证
+
+Manager 测试覆盖无轮次刷新、运行转空闲、对象替换、迟到受理、通过通知或列表对账移除、保留实例与子会话地址、失败及被替代的请求，以及销毁。在存在实例的场景中，测试同时检查列表和 Session 状态。Session 测试保留首发拒绝及后续发送行为。浏览器验证使用已有首轮录制场景，在受理后、`turn/start` 前暂停并进行同页重连。测试仅替换重连列表响应中的时间戳，用其显示结果作为同步标记；Host 的 blank/running 值及持久日志保持不变。
+
+## 相关决策
+
+[作用域与供给决策](../architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md) 拥有 Session 作用域、创建/复用及可见 blank 行。[Session/Conversation 归属决策](../architecture/2026-08-20-client-session-conversation-ownership.zh.md) 拥有传输、装配及快照内容。
diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts
index 8bddaee2d7..632d198e38 100644
--- a/apps/web/tests/replay-round-trip.e2e.ts
+++ b/apps/web/tests/replay-round-trip.e2e.ts
@@ -4,20 +4,22 @@
 // or the live adapter (record). Drive steps run in every mode and wait only
 // on generic completion (whenTurnSettled — never model-content selectors, so
 // record cannot hang on a live model answering differently); assertion steps
-// run in replay/refresh only. Settled states only — streaming fidelity is
-// asserted from the durable embedded Assistant stream, not transient DOM.
+// run in replay/refresh only. Streaming fidelity is asserted from the durable
+// embedded Assistant stream, not transient DOM.
 // Record: DSH_SNAPSHOT=record writes session.v3.jsonl, then a keyless
 // DSH_SNAPSHOT=refresh regenerates ui.expected.md.
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { Browser, Page } from 'playwright'
+import type { Browser, Page, Route, WebSocketRoute } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { ToolCallId, expandAssistantStream } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionListValue } from '@deepseek-ai/dsh-api-session-controller/types'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
 import {
-  assertFixtureInventory, captureExpandedTurnProcessAria, captureStableAria,
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureExpandedTurnProcessAria, captureStableAria,
   compareOrRefreshGolden, fixtureUserPrompts,
   launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
@@ -29,6 +31,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/fresh-round-t
 const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/session.v3.jsonl', import.meta.url))
 const UI_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/ui.expected.md', import.meta.url))
 const ECHO_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/submission-echo.expected.md', import.meta.url))
+const ACCEPTED_RECONNECT_EXPECTED = join(SNAPSHOT_DIR, 'accepted-reconnect.expected.md')
 const BLANK_EXPECTED = join(SNAPSHOT_DIR, 'blank-reload.expected.md')
 const UI_EXPANDED_EXPECTED = fileURLToPath(
   new URL('../../../snapshots/web/fresh-round-trip/ui-expanded.expected.md', import.meta.url),
@@ -41,6 +44,8 @@ const MODE = webSnapshotMode()
 // drift apart.
 const PROMPT = 'Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop.'
 
+type SessionListResponse = { result: RemoteResult<SessionListValue> }
+
 /** Rendered text of the system prompt surface node, or undefined when the surface carries none. */
 function systemPromptText(session: Session): string | undefined {
   const message = session.deriveMessages().find(candidate => candidate.role === 'system')
@@ -53,7 +58,9 @@ describe('web e2e: fresh round trip through the real assembly', () => {
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
   let settledSessionId: SessionId | undefined
+  let remoteSocket: WebSocketRoute | undefined
   const sessionEvents: SessionEvent[] = []
+  const browserNow = Date.now()
 
   beforeAll(async () => {
     scaffold = await launchWebScaffold({
@@ -63,6 +70,11 @@ describe('web e2e: fresh round trip through the real assembly', () => {
     scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
+    await page.clock.setFixedTime(browserNow)
+    await page.routeWebSocket('**/api/remote.mux', (route) => {
+      remoteSocket = route
+      route.connectToServer()
+    })
     tripwire = watchConsole(page)
     await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
@@ -94,26 +106,103 @@ describe('web e2e: fresh round trip through the real assembly', () => {
     }
     const input = page.locator('[data-composer-input]').first()
     await input.waitFor({ timeout: 10_000 })
-    // Arm the host-side settled barrier BEFORE the send click.
-    const settled = scaffold.whenTurnSettled()
-    await input.fill(PROMPT)
-    const echoSnapshot = await input.evaluate(async (element, prompt) => {
-      element.dispatchEvent(new KeyboardEvent('keydown', {
-        key: 'Enter', code: 'Enter', bubbles: true, cancelable: true,
-      }))
-      // sendSession registered its paint yield first. This frame observes the
-      // committed echo while admission remains queued on the following task.
-      await new Promise<void>((resolve) => { requestAnimationFrame(() => { resolve() }) })
-      const echo = document.querySelector<HTMLElement>('[data-submission-echo]')
-      return [
-        `echo: ${echo?.textContent?.includes(prompt) === true ? prompt : '(missing)'}`,
-        `composer: ${JSON.stringify(element.textContent ?? '')}`,
-        `contenteditable: ${element.getAttribute('contenteditable')}`,
-      ].join('\n')
-    }, PROMPT)
-    await compareOrRefreshGolden(ECHO_EXPECTED, echoSnapshot, MODE)
-    const sessionId = await settled
-    settledSessionId = sessionId
+    const sessionId = await page.evaluate(() => {
+      const selected = JSON.parse(localStorage.getItem('dsh.sessions.current')!) as { sessionId: string }
+      return selected.sessionId
+    }) as SessionId
+    const agent = scaffold.ctx.agents.get(sessionId)
+    if (agent === undefined) throw new Error('the selected Web Session has no live Agent')
+    await agent.whenIdle()
+    const release = Promise.withResolvers<undefined>()
+    // Maintenance leaves status idle and accepts inbox input without starting a turn.
+    const maintenance = agent.runMaintenance(() => release.promise)
+    let accepted = false
+    try {
+      await input.fill(PROMPT)
+      const admitted = page.waitForResponse('**/api/session/prompt')
+      const [echoSnapshot, response] = await Promise.all([
+        input.evaluate(async (element, prompt) => {
+          element.dispatchEvent(new KeyboardEvent('keydown', {
+            key: 'Enter', code: 'Enter', bubbles: true, cancelable: true,
+          }))
+          // sendSession registered its paint yield first. This frame observes the
+          // committed echo while admission remains queued on the following task.
+          await new Promise<void>((resolve) => { requestAnimationFrame(() => { resolve() }) })
+          const echo = document.querySelector<HTMLElement>('[data-submission-echo]')
+          return [
+            `echo: ${echo?.textContent?.includes(prompt) === true ? prompt : '(missing)'}`,
+            `composer: ${JSON.stringify(element.textContent ?? '')}`,
+            `contenteditable: ${element.getAttribute('contenteditable')}`,
+          ].join('\n')
+        }, PROMPT),
+        admitted,
+      ])
+      expect(await response.json()).toMatchObject({ result: { ok: true, value: { accepted: true } } })
+      accepted = true
+      await compareOrRefreshGolden(ECHO_EXPECTED, echoSnapshot, MODE)
+      const row = page.getByRole('tree', { name: 'Sessions', exact: true })
+        .locator('[role="treeitem"][aria-selected="true"]')
+      await expect.poll(() => row.getAttribute('draggable')).toBe('true')
+      expect(sessionEvents.some(event => event.type === 'turn/start')).toBe(false)
+
+      const disconnected = remoteSocket
+      if (disconnected === undefined) throw new Error('the Web Remote socket never connected')
+      const warningStart = tripwire.warnings.length
+      // Only this list response carries the 2d timestamp. Its rendered label
+      // confirms the refresh reached the row, without altering blank/running.
+      const listUrl = new URL('/api/session/list', scaffold.baseUrl).href
+      const markListResponse = async (route: Route): Promise<void> => {
+        const response = await route.fetch()
+        try {
+          const body = await response.json() as SessionListResponse
+          if (body.result.ok) {
+            body.result = { ...body.result, value: {
+              ...body.result.value,
+              items: body.result.value.items.map(item => item.sessionId === sessionId
+                ? { ...item, updatedAt: browserNow - 2 * 86_400_000 }
+                : item),
+            } }
+          }
+          await route.fulfill({ response, json: body })
+        } finally {
+          await response.dispose()
+        }
+      }
+      await page.route(listUrl, markListResponse, { times: 1 })
+      try {
+        const refreshing = page.waitForResponse(listUrl)
+        const [, refreshed] = await Promise.all([disconnected.close(), refreshing])
+        await expect.poll(() => remoteSocket !== disconnected).toBe(true)
+        const baseline = await refreshed.json() as SessionListResponse
+        expect(baseline.result.ok).toBe(true)
+        if (!baseline.result.ok) throw new Error('the reconnect list request failed')
+        const hostSummary = baseline.result.value.items.find(item => item.sessionId === sessionId)
+        expect(hostSummary).toMatchObject({ blank: true, running: false })
+        await row.getByText('2d', { exact: true }).waitFor()
+        expect(await row.getAttribute('draggable')).toBe('true')
+        expect(await row.getByText('New Session', { exact: true }).count()).toBe(0)
+        expect(sessionEvents.some(event => event.type === 'turn/start')).toBe(false)
+        const checkpoint = [
+          `selected sidebar rows: ${await row.count()}`,
+          `new-session labels: ${await row.getByText('New Session', { exact: true }).count()}`,
+          `row draggable: ${await row.getAttribute('draggable')}`,
+          `host history blank: ${hostSummary?.blank}`,
+          `composer: ${JSON.stringify(await input.textContent())}`,
+          `contenteditable: ${await input.getAttribute('contenteditable')}`,
+        ].join('\n')
+        await compareOrRefreshGolden(ACCEPTED_RECONNECT_EXPECTED, checkpoint, MODE)
+        acknowledgeReloadConnectionLoss(tripwire, warningStart)
+      } finally {
+        await page.unroute(listUrl, markListResponse)
+      }
+    } finally {
+      // No turn can settle before maintenance releases the accepted input.
+      const settled = accepted ? scaffold.whenTurnSettled() : undefined
+      release.resolve(undefined)
+      await maintenance
+      if (settled !== undefined) settledSessionId = await settled
+      await agent.whenIdle()
+    }
     if (MODE === 'record') {
       await recordFixture(scaffold, sessionId, FIXTURE)
     }
@@ -237,12 +326,13 @@ describe('web e2e: fresh round trip through the real assembly', () => {
     await expect.poll(() => think.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('false')
   })
 
-  it.skipIf(MODE === 'record')('stayed clean: no pageerrors, no reconnect self-healing, no server errors', async () => {
+  it.skipIf(MODE === 'record')('stayed clean after the intentional reconnect: no pageerrors or server errors', async () => {
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
       'blank-reload.expected.md',
       'session.v3.jsonl',
+      'accepted-reconnect.expected.md',
       'submission-echo.expected.md',
       'system-prompt.expected.md',
       'tool-schemas.expected.json',
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index f0c39d8dbb..bab878d24d 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: c9f63d462c6e291abda7312c66c8fffcd7109c57
-README.zh.md: f6d03b45b6bf9d3e809e70154adacd59ce341721
+README.md: 4bbb98b0ee9224f72a571b10e8ae40d32377a747
+README.zh.md: 820dd4c3f56e964cf2b34cb50d5e5f38e35eff68
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index c9f63d462c..4bbb98b0ee 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -39,6 +39,8 @@ Client list refreshes retain unchanged row objects and reuse the items array whe
 
 Projection reads retain loading and failure state independently of their values. Reconnect cancels reads from the previous connection and reloads previously requested projections; live membership updates arrive through the control stream. Parent availability comes from Host summaries and remains unknown until a summary or a successful list baseline establishes it. Address lookup resolves projected children without selecting them or creating scopes.
 
+Accepted prompts and observed running keep their Client display conversion across list refresh, reconnect, and Session-object replacement. The Manager retains these observations by Session id; they do not establish durable history. Drafts, projection stores, and sidebar display rules retain their existing behavior. The [blank rollback decision](../../../.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md) defines retention and late-response handling.
+
 The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, `append`, and `settle-assistant` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. The Web adapter explicitly opts into cursorless Assistant frames: each opening carries the active attempt's `startedAfterSeq`, `nextIndex`, and compact stream, and every stream member becomes a Client-only `assistant/live-chunk` entry ordered between durable cursors. The Host captures a follower-local arrival ordinal with that baseline and suppresses buffered frames at or before the cut; a replacement Agent may restart frame revision at one. A durable `assistant/message` or `assistant/attempt` arriving after an active opening stays staged only when its seq follows `startedAfterSeq` and its Turn and Step match; the matching end type, seq, and index publishes one named settlement delta that retires the attempt's transient rows and adds the durable entry while earlier same-step retries remain visible. Revision, dense-index, or settlement gaps for a known attempt reopen follow, while a controller that missed the start ignores unknown-attempt frames and publishes their durable settlement normally. An abandoned end publishes a settlement delta without a durable entry so its transient rows retire immediately. A durable gap-repair page has no Assistant baseline, so its held notification reopens follow once for a paired page and baseline. Every history record covers exactly its event seq. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces jobs and projection state instead of treating transient values as durable events. At each ready Host generation, a synchronous Client subscription clears retained projection values and watermarks before refreshing queries and restarting the control stream, including Sessions absent from the control baseline. The first control stream waits for generation readiness, so its opening values cannot precede invalidation. Outstanding list responses from the previous generation cannot republish those values. Within a generation, a delayed control baseline cannot overwrite or clear newer sequenced values, whether they arrived through a live Session's list block, a history page, or a frame; a cached list block, viewed from the projection cache for a cold Session, yields to the connected Session's baseline whatever watermark it carries. The durable `inbox` projection carries both pending lists through the same cold-read and reconnect path as other projections. Client Agent contexts provide the identity used by the independent [`fileUpload`](../../client/file-upload/README.md) service; Session objects expose lifecycle, prompt, queue, and history operations rather than file transfer.
 
 The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. The echo stores ordered image previews and durable file references. Session derives its `transcript`, `queued`, or `steering` placement from the current running state and requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, including pending messages in the `inbox` projection. An echo retires one animation frame after its durable event or queue occurrence is observed, immediately when its identified prompt fails or is abandoned, and as failed on disposal. Each retirement fires `onRetire` exactly once; an observed retirement includes the ordered durable attachment references so the composer can release successful cards while preserving failed drafts. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone.
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index f6d03b45b6..820dd4c3f5 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -39,6 +39,8 @@ Client 列表刷新保留未变化的行对象，并在顺序和值均相同时
 
 投影读取独立于其值保留加载与失败状态。重连会取消上一连接的读取，并重新加载已请求的投影；实时成员更新通过 control stream 到达。父 Agent 可用性来自 Host 摘要，在收到对应摘要或成功的列表 baseline 前保持未知。地址查找直接解析投影中的子项，不会选择它们或创建 scope。
 
+已受理的提示词与已观察到的运行，会使客户端展示转换跨列表刷新、重连及 Session 对象替换保留。Manager 按 Session id 保留这些观察；它们不证明持久历史已经产生。草稿、投影存储和侧边栏展示规则保留原有行为。[blank 回退修复决策](../../../.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md) 定义保留期限及迟到响应处理。
+
 Client 适配器提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend`、`append` 与 `settle-assistant` 变更，并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词：`loadOlder()` 拉一页 50 条消息，而 `loadThrough(seq)`——轮次跳转加载器——按每页 200 条消息循环拉取直到窗口覆盖目标 seq，重复调用会下调共享目标，遇到无进展的页即停止，忙碌状态复用同一个 `loadingOlder` 快照位。Web 适配器显式选择接收无 cursor 的 Assistant frame：每个 opening 携带活跃 attempt 的 `startedAfterSeq`、`nextIndex` 与紧凑 stream，每个 stream member 都成为排在持久 cursor 之间的 Client-only `assistant/live-chunk` 条目。Host 会随该 baseline 捕获 follower 本地到达序号，并抑制该 cut 及之前的 buffered frame；replacement Agent 可以从 revision 一重新开始。活跃 opening 之后到达的持久 `assistant/message` 或 `assistant/attempt` 只有在其 seq 晚于 `startedAfterSeq` 且轮次与步骤匹配时才会保持暂存；匹配的 end type、seq 与 index 会发布一个具名 settlement delta，删除该 attempt 的瞬态 row、加入持久条目，并保留同一步骤中更早的 retry。已知 attempt 的 revision、密集 index 或 settlement 缺口会重新打开 follow；若 controller 错过 start，则忽略 unknown-attempt frame，并正常发布其持久 settlement。Abandoned end 会发布不含持久条目的 settlement delta，使瞬态 row 立即退出。持久缺口修复 page 不携带 Assistant baseline，因此 held notification 会重新打开 follow 一次，以取得配对的 page 与 baseline。每条历史 record 只覆盖自身的事件 seq。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 jobs 和 projection 状态，而不会把瞬态值当作 durable event。每次 Host generation 就绪时，同步的 Client 订阅会先清除保留的投影值及其水位，再刷新查询并重新打开 control stream，其中也包括 control baseline 中没有列出的 Session。首次 control stream 会等待 generation 就绪，确保其 opening 值不会先于旧状态清理到达。上一代尚未完成的 list 响应无法重新发布这些值。同一 generation 内，延迟到达的 control baseline 不能覆盖或清除较新的 sequenced 值，无论它们来自活 Session 的 list block、history page 还是 frame；冷 Session 从 projection cache 看出来的 cached list block 则不论水位都让位于建连 Session 的 baseline。持久 `inbox` 投影通过与其他投影相同的冷读取和重连路径传输两份待处理列表。Client Agent 上下文提供独立 [`fileUpload`](../../client/file-upload/README.zh.md) 服务使用的身份；Session 对象提供生命周期、prompt、queue 与历史操作，不提供文件传输。
 
 Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与提示词之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。回显按顺序存放图片预览与持久文件引用。Session 根据当前运行状态与请求的投递模式推导其 `transcript`、`queued` 或 `steering` 位置，并在序列化期间保留该位置。提示词的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，`inbox` 投影中的待处理消息也保留同一 source。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休，带标识的提示词失败或被放弃时立即退休，销毁时按 failed 退休。每次退休恰好触发一次 `onRetire`；observed 退休还会携带有序的持久附件引用，让 composer 释放成功卡片并保留失败草稿。回显只存在于 Client 内存；刷新与重连只从持久事件重建会话。
diff --git a/packages/api/session-controller/src/client/sessions/lineage.ts b/packages/api/session-controller/src/client/sessions/lineage.ts
index 56d06d3e43..b0b49311f3 100644
--- a/packages/api/session-controller/src/client/sessions/lineage.ts
+++ b/packages/api/session-controller/src/client/sessions/lineage.ts
@@ -19,7 +19,10 @@ export interface SessionListEntry {
   title?: string
   updatedAt: number
   running: boolean
-  /** Summary blankness reconciled with `sessionListMetadata`; lists hide blank sessions (filtering stays with the consumer). */
+  /**
+   * New Session presentation and reuse eligibility, reconciled with
+   * `sessionListMetadata`; lists hide blank sessions (filtering stays with the consumer).
+   */
   blank: boolean
   parentSessionId?: SessionId
   /** Coarse durable origin for navigation filtering; not a continuation capability. */
diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts
index d3564d763b..4a7d1d685d 100644
--- a/packages/api/session-controller/src/client/sessions/manager.ts
+++ b/packages/api/session-controller/src/client/sessions/manager.ts
@@ -87,6 +87,9 @@ export class SessionManager {
   private readonly sessions = new Map<SessionId, Session>()
   /** In-flight Session disposals remain here after instances leave `sessions`, so manager disposal can await quiescence. */
   private readonly sessionDisposals = new Set<Promise<void>>()
+  /** Accepted/running presentation must survive a later empty-history list response. */
+  private readonly engagedSessions = new Set<SessionId>()
+  private disposed = false
   /** Per-session projection value stores, retained independently of instance arrival (the
    *  title-snapshot precedent, generalized): push frames land here whether or not the Session
    *  is instantiated (list rows read the 'title' key), and an instantiated Session adopts the
@@ -184,6 +187,7 @@ export class SessionManager {
     if (session !== expected) return Promise.resolve()
     this.sessions.delete(sessionId)
     this.addresses.delete(sessionId)
+    this.pruneEngagement(sessionId)
     return this.startSessionDisposal(session)
   }
 
@@ -192,6 +196,10 @@ export class SessionManager {
    * @returns once catalog requests and every Session stream have stopped.
    */
   async dispose(): Promise<void> {
+    this.disposed = true
+    this.listMutations = null
+    this.listInflight = null
+    this.engagedSessions.clear()
     const reads = [...this.projectionInflight.values()]
     for (const { controller } of reads) controller.abort()
     this.projectionInflight.clear()
@@ -235,7 +243,7 @@ export class SessionManager {
       // instance (consistency when the list precedes open).
       const summary = this.summaries.find(s => s.sessionId === sessionId)
       if (summary !== undefined) {
-        session.handleBlank(summary.blank)
+        session.handleBlank(this.effectiveBlank(summary))
         session.handleRunning(summary.running)
       } else {
         const address = this.addresses.get(sessionId)
@@ -268,12 +276,28 @@ export class SessionManager {
       // The sender's local first-send flip mirrors into the list row so the
       // session surfaces (lists filter on blank) before any host frame lands.
       onEngaged: (engaged) => {
+        if (this.disposed || !this.retainsSession(engaged.sessionId)) return
+        this.engagedSessions.add(engaged.sessionId)
         this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
+        this.sessions.get(engaged.sessionId)?.handleBlank(false)
       },
       projections: this.projectionStore(sessionId),
     })
   }
 
+  private effectiveBlank(summary: SessionSummary): boolean {
+    return summary.blank && !this.engagedSessions.has(summary.sessionId)
+  }
+
+  private retainsSession(sessionId: SessionId): boolean {
+    return this.sessions.has(sessionId) || this.addresses.has(sessionId)
+      || this.summaries.some(summary => summary.sessionId === sessionId)
+  }
+
+  private pruneEngagement(sessionId: SessionId): void {
+    if (!this.retainsSession(sessionId)) this.engagedSessions.delete(sessionId)
+  }
+
   /** Resident per-session projection store (create-on-demand; outlives instantiation). */
   private projectionStore(sessionId: SessionId): ProjectionValueStore {
     let store = this.projectionStores.get(sessionId)
@@ -367,15 +391,31 @@ export class SessionManager {
           const baseline: SessionSummary[] = this.listPhase === 'pending'
             ? [...result.value.items]
             : mergeOrderedBaseline(established, result.value.items, summary => summary.sessionId)
-          this.summaries = mutations.reduce(applyMutation, baseline)
+          // A removal supersedes running observed in the pull, including after re-addition.
+          const removedSincePull = new Set<SessionId>()
+          for (const mutation of mutations) {
+            if (mutation.kind === 'remove') removedSincePull.add(mutation.sessionId)
+          }
+          for (const s of baseline) {
+            if (s.running && !removedSincePull.has(s.sessionId)) this.engagedSessions.add(s.sessionId)
+          }
+          const summaries = mutations.reduce(applyMutation, baseline)
+          this.summaries = summaries
+          // A full list can remove identities without a removal frame.
+          const listedIds = new Set(summaries.map(summary => summary.sessionId))
+          for (const sessionId of this.engagedSessions) {
+            if (!listedIds.has(sessionId) && !this.sessions.has(sessionId) && !this.addresses.has(sessionId)) {
+              this.engagedSessions.delete(sessionId)
+            }
+          }
           this.listState = 'idle'
           this.listPhase = 'ready'
           this.updateParentAvailability()
-          // Sessions reconcile list blank hints with their current metadata projection.
+          // Resident Sessions and list rows share one display blank, reconciled with the metadata projection.
           for (const s of this.summaries) {
             const session = this.sessions.get(s.sessionId)
             if (session === undefined) continue
-            session.handleBlank(s.blank)
+            session.handleBlank(this.effectiveBlank(s))
             session.handleRunning(s.running)
           }
           // Land each row's projection block in the per-session value store
@@ -524,6 +564,7 @@ export class SessionManager {
 
   /** Apply immediately and retain for replay when a list response is in flight. */
   private recordMutation(mutation: SessionListMutation): void {
+    if (this.disposed) return
     this.listMutations?.push(mutation)
     this.summaries = applyMutation(this.summaries, mutation)
     this.notifier.markDirty()
@@ -599,7 +640,8 @@ export class SessionManager {
    */
   handleSessionAdded(summary: SessionSummary): void {
     this.mergeSummary(summary)
-    this.sessions.get(summary.sessionId)?.handleBlank(summary.blank)
+    if (!this.disposed && summary.running) this.engagedSessions.add(summary.sessionId)
+    this.sessions.get(summary.sessionId)?.handleBlank(this.effectiveBlank(summary))
     if (summary.projections !== undefined) this.applyListBlock(summary.sessionId, summary.projections)
   }
 
@@ -644,6 +686,7 @@ export class SessionManager {
     if (!durableSubagent && (catalog === undefined || catalog.length === 0)) {
       this.projectionStores.delete(sessionId)
     }
+    this.pruneEngagement(sessionId)
     this.projectionInflight.get(sessionId)?.controller.abort()
     this.projectionInflight.delete(sessionId)
     this.projectionLoads.delete(sessionId)
@@ -660,6 +703,7 @@ export class SessionManager {
    * @param running - current Agent running state.
    */
   handleSessionStatus(sessionId: SessionId, running: boolean): void {
+    if (!this.disposed && running) this.engagedSessions.add(sessionId)
     this.recordMutation({ kind: 'status', sessionId, running, agentAvailable: true })
     this.updateParentAvailability()
     this.sessions.get(sessionId)?.handleRunning(running)
@@ -716,7 +760,7 @@ export class SessionManager {
       return {
         ...summary,
         // Cached list hints can precede a history opening or control update.
-        blank: summary.blank && metadata?.blank !== false,
+        blank: this.effectiveBlank(summary) && metadata?.blank !== false,
         updatedAt: Math.max(summary.updatedAt, metadata?.lastPromptAt ?? 0),
         ...(typeof title === 'string' && title !== '' ? { title } : {}),
         ...(projectionValues === undefined ? {} : { projectionValues }),
@@ -786,8 +830,7 @@ function applyMutation(summaries: readonly SessionSummary[], mutation: SessionLi
     case 'remove':
       return summaries.filter(summary => summary.sessionId !== mutation.sessionId)
     case 'status':
-      // running:true doubles as the cross-client blank flip (a blank session
-      // never runs, so the first running frame proves a message landed).
+      // Running converts display state; it does not establish durable history.
       return summaries.map(summary => summary.sessionId === mutation.sessionId
         && (summary.running !== mutation.running
           || summary.agentAvailable !== mutation.agentAvailable || (mutation.running && summary.blank))
diff --git a/packages/api/session-controller/src/client/sessions/service.ts b/packages/api/session-controller/src/client/sessions/service.ts
index 28b22c796a..2d5cea16f0 100644
--- a/packages/api/session-controller/src/client/sessions/service.ts
+++ b/packages/api/session-controller/src/client/sessions/service.ts
@@ -39,7 +39,8 @@ export interface SessionSummary {
   /** Local ownership counts; Host metadata refreshes cannot overwrite them. */
   readonly retainedBy: SessionRetainInfo['retainedBy']
   /**
-   * Blankness from the Host summary reconciled with `sessionListMetadata`.
+   * New Session presentation and reuse eligibility, derived from the Host
+   * summary, `sessionListMetadata`, and client acceptance/running observations.
    * New Session reuses a blank one targeting the same workspace. Filtering
    * stays with the consumer: the store carries every row, while the Workspace
    * browser shows only the selected blank entry.
diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts
index fb1eb7a01d..08d935233c 100644
--- a/packages/api/session-controller/src/client/sessions/session.ts
+++ b/packages/api/session-controller/src/client/sessions/session.ts
@@ -66,12 +66,9 @@ export interface SessionOptions {
   /** Whether the exact direct parent Agent is available in Host summaries; absent until known. */
   parentAvailable?: boolean
   /**
-   * First ACCEPTED prompt on a blank session (fires at most once, on the
-   * prompt RPC's success response): the manager mirrors the blank→false flip
-   * into its list row so the session surfaces without waiting for a host
-   * frame. Acceptance is the flip point because it proves the user message
-   * is in the host log; a rejected first prompt keeps the session blank
-   * (hidden, still reusable by connectWorkspace).
+   * Publish each accepted prompt to the Manager, including after this Session
+   * object is replaced. Acceptance converts display state, but does not
+   * establish that a turn started or reached durable history.
    */
   onEngaged?(session: Session): void
   /**
@@ -117,7 +114,7 @@ export class Session implements SessionFace {
   private promptAttempted = false
   /** A first accepted prompt stays in the engaging phase until its turn is observable. */
   private firstPromptPendingTurn = false
-  /** Empty-log mirror (see ConversationSnapshot.blank); unknown bare sessions begin conservatively blank. */
+  /** New Session display state; unknown bare sessions begin conservatively blank. */
   private blankBit = true
   private removed = false
   private promptError: PromptError | null = null
@@ -291,19 +288,12 @@ export class Session implements SessionFace {
       this.notifier.markDirty()
       return result
     }
-    // Blank flips on ACCEPTANCE, not attempt: an accepted prompt starts the
-    // conversation's first turn on the host (the host criterion — a logged
-    // turn/start — is fact, not optimism; standalone command and projection
-    // events never flip it), while a rejected first prompt must keep the
-    // session blank — the client-side blank mirror only ever lowers, so
-    // flipping early on a failure would surface the session forever and
-    // strip its connectWorkspace reuse eligibility against the host's
-    // authority.
+    // Rejection must leave a first prompt blank and eligible for workspace reuse.
     if (this.blankBit) {
       this.blankBit = false
-      this.options.onEngaged?.(this)
       this.notifier.markDirty()
     }
+    this.options.onEngaged?.(this)
     return result
   }
 
@@ -514,8 +504,7 @@ export class Session implements SessionFace {
    * @param running - the new running state.
    */
   handleRunning(running: boolean): void {
-    // Turn-start conversion: a blank session never runs, so the first
-    // running:true proves another side's first message landed.
+    // Running converts display state without establishing durable turn history.
     if (running && this.blankBit) {
       this.blankBit = false
       this.notifier.markDirty()
@@ -553,9 +542,12 @@ export class Session implements SessionFace {
   }
 
   /**
-   * Relay list blankness without overriding a started conversation established
-   * by the current projection, a local prompt, or running state.
-   * @param blank - whether the list or projection reports an unstarted conversation.
+   * Apply the Manager's effective display blank, further reconciled with the
+   * current `sessionListMetadata` projection. Local send attempts and current
+   * running state prevent re-blanking; an earlier false summary alone does not.
+   * The Manager retains acceptance and earlier running observations across
+   * Session-object replacement.
+   * @param blank - New Session display state after Manager reconciliation.
    */
   handleBlank(blank: boolean): void {
     blank = blank && this.projections.values().sessionListMetadata?.blank !== false
diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts
index b41ee673c8..aed5009fdd 100644
--- a/packages/api/session-controller/tests/manager.client.spec.ts
+++ b/packages/api/session-controller/tests/manager.client.spec.ts
@@ -3,8 +3,9 @@
  * frame routing, and control baselines for uninstantiated sessions.
  */
 
-import { describe, expect, vi } from 'vitest'
+import { describe, expect, onTestFinished, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/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'
@@ -48,6 +49,318 @@ function makeManager(
 }
 
 describe('SessionManager instances', () => {
+  it.for(['event', 'list'] as const)(
+    'forgets running when an unretained identity disappears through a %s',
+    async (source, { mock, remote }) => {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+      await manager.refreshList()
+      manager.handleSessionStatus(S1, true)
+      manager.handleSessionStatus(S1, false)
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+
+      if (source === 'event') manager.handleSessionRemoved(S1)
+      else {
+        remote.session.list.mockResolvedValueOnce(ok({ items: [] }))
+        await manager.refreshList()
+      }
+      expect(manager.getListSnapshot().items).toEqual([])
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    },
+  )
+
+  it('retains acceptance while an unlisted Session remains resident, then forgets it on drop', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const session = manager.get(S1)
+    await session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    remote.session.list.mockResolvedValue(ok({ items: [] }))
+
+    await manager.refreshList()
+    expect(manager.getListSnapshot().items).toEqual([])
+    expect(session.getSnapshot().blank).toBe(false)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+
+    await manager.refreshList()
+    await manager.drop(S1, session)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+  })
+
+  it('retains running for an unlisted child with only a retained address', async ({ mock, remote }) => {
+    const address: SubagentAddress = { parentSessionId: S1, childSessionId: S2, mode: 'continuable' }
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.resolveTarget(address)
+    manager.handleSessionAdded(summary(S2, { blank: true }))
+    manager.handleSessionStatus(S2, true)
+    manager.handleSessionStatus(S2, false)
+    remote.session.list.mockResolvedValueOnce(ok({ items: [] }))
+
+    await manager.refreshList()
+    expect(manager.getListSnapshot().items).toEqual([])
+    manager.handleSessionAdded(summary(S2, { blank: true }))
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+  })
+
+  it('retains running for a row added during a pull whose baseline omits it', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    manager.handleSessionStatus(S1, true)
+    manager.handleSessionStatus(S1, false)
+    const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValueOnce(response.promise)
+    const refreshing = manager.refreshList()
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    response.resolve(ok({ items: [] }))
+
+    await refreshing
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+  })
+
+  it.for(['result', 'transport'] as const)(
+    'retains running observed before listing when the pull fails through %s',
+    async (source, { mock, remote }) => {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionStatus(S1, true)
+      manager.handleSessionStatus(S1, false)
+      const error = new RemoteError('gateway/internal', 'list unavailable', {})
+      if (source === 'result') remote.session.list.mockResolvedValueOnce(err(error))
+      else remote.session.list.mockRejectedValueOnce(error)
+
+      await manager.refreshList()
+      expect(manager.getListSnapshot().state).toBe('error')
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    },
+  )
+
+  it('accepts a later blank baseline without an acceptance or running observation', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: false }))
+    const session = manager.get(S1)
+    expect(session.getSnapshot().blank).toBe(false)
+    remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+
+    await manager.refreshList()
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(session.getSnapshot().blank).toBe(true)
+  })
+
+  it('retains acceptance received before the first list response', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValueOnce(response.promise)
+    const refreshing = manager.refreshList()
+    const session = manager.get(S1)
+    await session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    expect(manager.getListSnapshot().items).toEqual([])
+    response.resolve(ok({ items: [summary(S1, { blank: true })] }))
+
+    await refreshing
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(session.getSnapshot().blank).toBe(false)
+  })
+
+  it('keeps a rejected first prompt blank across refresh and object replacement', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    remote.session.prompt.mockResolvedValueOnce(err(new RemoteError('session/agent-busy', 'busy', { reason: 'x' })))
+    const session = manager.get(S1)
+    expect((await session.prompt([{ type: 'text', text: 'first' }], 'queue')).ok).toBe(false)
+    remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+    await manager.refreshList()
+    await manager.drop(S1, session)
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(manager.get(S1).getSnapshot().blank).toBe(true)
+  })
+
+  it('ignores running from a list response that predates removal, including after re-addition', async ({ mock, remote }) => {
+    for (const readdBeforeResponse of [false, true]) {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+      const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+      remote.session.list.mockReturnValueOnce(response.promise)
+      const refreshing = manager.refreshList()
+      manager.handleSessionRemoved(S1)
+      if (readdBeforeResponse) manager.handleSessionAdded(summary(S1, { blank: true }))
+
+      response.resolve(ok({ items: [summary(S1, { blank: true, running: true })] }))
+      await refreshing
+      if (!readdBeforeResponse) {
+        expect(manager.getListSnapshot().items).toEqual([])
+        manager.handleSessionAdded(summary(S1, { blank: true }))
+      }
+
+      expect(manager.getListSnapshot().items[0]).toMatchObject({ blank: true, running: false })
+    }
+  })
+
+  it('retains running observations after re-addition while an older list response is pending', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValue(response.promise)
+    const refreshing = manager.refreshList()
+    manager.handleSessionRemoved(S1)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    manager.handleSessionStatus(S1, true)
+    manager.handleSessionStatus(S1, false)
+
+    response.resolve(ok({ items: [summary(S1, { blank: true })] }))
+    await refreshing
+
+    expect(manager.getListSnapshot().items[0]).toMatchObject({ blank: false, running: false })
+  })
+
+  it('applies late acceptance to a re-added list row without materializing its Session', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+    remote.session.prompt.mockReturnValue(acceptance.promise)
+    const session = manager.get(S1)
+    const sending = session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    manager.handleSessionRemoved(S1)
+    await manager.drop(S1, session)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const getSession = vi.spyOn(manager, 'get')
+    onTestFinished(() => { getSession.mockRestore() })
+    acceptance.resolve(ok({ accepted: true }))
+    await sending
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(getSession).not.toHaveBeenCalled()
+  })
+
+  it('publishes a late acceptance to the replacement Session with the same id', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+    remote.session.prompt.mockReturnValue(acceptance.promise)
+    const session = manager.get(S1)
+    const sending = session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    await manager.drop(S1, session)
+    const replacement = manager.get(S1)
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(replacement.getSnapshot().blank).toBe(true)
+    acceptance.resolve(ok({ accepted: true }))
+    await sending
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(replacement.getSnapshot().blank).toBe(false)
+    await manager.drop(S1, session)
+    expect(manager.get(S1)).toBe(replacement)
+  })
+
+  it('keeps accepted presentation when its Session is rebuilt', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const session = manager.get(S1)
+    await session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    await manager.drop(S1, session)
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(manager.get(S1).getSnapshot().blank).toBe(false)
+  })
+
+  it('publishes acceptance from a nonblank sender after its list row is replaced', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const sender = manager.get(S1)
+    await sender.prompt([{ type: 'text', text: 'first' }], 'queue')
+    const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+    remote.session.prompt.mockReturnValueOnce(acceptance.promise)
+    const sending = sender.prompt([{ type: 'text', text: 'next' }], 'queue')
+    manager.handleSessionRemoved(S1)
+    await manager.drop(S1, sender)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const replacement = manager.get(S1)
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(replacement.getSnapshot().blank).toBe(true)
+
+    acceptance.resolve(ok({ accepted: true }))
+    await sending
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(replacement.getSnapshot().blank).toBe(false)
+  })
+
+  it('keeps observed running presentation across idle empty-history summaries', async ({ mock, remote }) => {
+    for (const source of ['addition', 'refresh'] as const) {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+      const session = manager.get(S1)
+      manager.handleSessionStatus(S1, true)
+      manager.handleSessionStatus(S1, false)
+      expect(session.getSnapshot().blank).toBe(false)
+
+      if (source === 'addition') manager.handleSessionAdded(summary(S1, { blank: true }))
+      else {
+        remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+        await manager.refreshList()
+      }
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+      expect(session.getSnapshot().blank).toBe(false)
+    }
+  })
+
+  it('does not restore a removed row or publish after disposal when acceptance arrives late', async ({ mock, remote }) => {
+    for (const dispose of [false, true]) {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+      const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+      remote.session.prompt.mockReturnValue(acceptance.promise)
+      const session = manager.get(S1)
+      const sending = session.prompt([{ type: 'text', text: 'first' }], 'queue')
+      manager.handleSessionRemoved(S1)
+      if (dispose) await manager.dispose()
+      else await manager.drop(S1, session)
+      const notify = vi.fn()
+      const unsubscribe = manager.subscribe(notify)
+      onTestFinished(unsubscribe)
+      acceptance.resolve(ok({ accepted: true }))
+      await sending
+      expect(manager.getListSnapshot().items).toEqual([])
+      expect(notify).not.toHaveBeenCalled()
+    }
+  })
+
+  it('keeps accepted presentation across a later list refresh without a turn', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    remote.session.list.mockResolvedValue(ok({ items: [summary(S1, { blank: true })] as never[] }))
+    await manager.refreshList()
+    await manager.get(S1).prompt([{ type: 'text', text: 'first' }], 'queue')
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+
+    await manager.refreshList()
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+  })
+
   it('lazily builds one resident instance per id and syncs the running bit from the list', async ({ mock, remote }) => {
     remote.session.list.mockResolvedValue(ok({ items: [summary(S1, { running: true })] as never[] }))
     const manager = makeManager(mock, remote)
@@ -876,6 +1189,32 @@ describe('remaining branches', () => {
 })
 
 describe('connected generation', () => {
+  it('does not prune running observations from a superseded empty list response', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    const oldList = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    const newList = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValueOnce(oldList.promise).mockReturnValueOnce(newList.promise)
+    const oldPull = manager.refreshList()
+    manager.handleSessionStatus(S1, true)
+    manager.handleSessionStatus(S1, false)
+    manager.handleConnected()
+    const newPull = manager.refreshList()
+    try {
+      oldList.resolve(ok({ items: [] }))
+      await oldPull
+      expect(manager.getListSnapshot().state).toBe('loading')
+      newList.resolve(ok({ items: [summary(S1, { blank: true })] }))
+      await newPull
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    } finally {
+      oldList.resolve(ok({ items: [] }))
+      newList.resolve(ok({ items: [] }))
+      await Promise.all([oldPull, newPull])
+    }
+  })
+
   it.for(['old-first', 'new-first'] as const)(
     'ignores a previous generation list response (%s)',
     async (order, { mock, remote }) => {
diff --git a/packages/api/session-controller/tests/session.client.spec.ts b/packages/api/session-controller/tests/session.client.spec.ts
index fd49737fb1..0c93b71af4 100644
--- a/packages/api/session-controller/tests/session.client.spec.ts
+++ b/packages/api/session-controller/tests/session.client.spec.ts
@@ -625,6 +625,30 @@ describe('prompt and cancel errors', () => {
     expect(session.getSnapshot()).toMatchObject({ running: true, awaitingFirstTurn: false })
   })
 
+  it('does not await a first turn when the history already contains one', async ({ mock, start }) => {
+    const session = await sessionBench(mock, start, SID)
+    session.handleBlank(false)
+    const inFlight = session.prompt([{ type: 'text', text: '继续' }], 'queue')
+    expect(session.getSnapshot()).toMatchObject({ blank: false, promptAttempted: true, awaitingFirstTurn: false })
+    expect((await inFlight).ok).toBe(true)
+    expect(session.getSnapshot()).toMatchObject({ blank: false, awaitingFirstTurn: false })
+  })
+
+  it('keeps an accepted first prompt converted when a later prompt is rejected', async ({ mock, start }) => {
+    const session = await sessionBench(mock, start, SID)
+    session.handleBlank(true)
+    expect((await session.prompt([{ type: 'text', text: '第一次' }], 'queue')).ok).toBe(true)
+    session.handleRunning(true)
+    session.handleRunning(false)
+    mock.remote.session.prompt.mockResolvedValue(err(new RemoteError('session/agent-busy', 'busy', { reason: 'x' })))
+
+    expect((await session.prompt([{ type: 'text', text: '第二次' }], 'queue')).ok).toBe(false)
+    expect(session.getSnapshot()).toMatchObject({
+      blank: false, running: false, awaitingFirstTurn: false,
+      promptError: { op: 'send', error: { code: 'session/agent-busy' } },
+    })
+  })
+
   it('keeps the attempted-first-prompt state when the Host rejects the prompt', async ({ mock, start }) => {
     const session = await sessionBench(mock, start, SID)
     session.handleBlank(true)
diff --git a/snapshots/web/fresh-round-trip/accepted-reconnect.expected.md b/snapshots/web/fresh-round-trip/accepted-reconnect.expected.md
new file mode 100644
index 0000000000..dca0e7be05
--- /dev/null
+++ b/snapshots/web/fresh-round-trip/accepted-reconnect.expected.md
@@ -0,0 +1,6 @@
+selected sidebar rows: 1
+new-session labels: 0
+row draggable: true
+host history blank: true
+composer: ""
+contenteditable: true

From 7aa2d4b5cc3b16393d43feb40618f48a21582ca0 Mon Sep 17 00:00:00 2001
From: liukx0205 <harusoda@berkeley.edu>
Date: Sun, 20 Sep 2026 12:44:55 +0800
Subject: [PATCH 16/37] docs(web): note the retained subagent catalog on
 session removal

---
 .../2026-09-15-client-session-blank-reconciliation.i18n.yaml  | 4 ++--
 .../bug-fix/2026-09-15-client-session-blank-reconciliation.md | 2 +-
 .../2026-09-15-client-session-blank-reconciliation.zh.md      | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
index 6060e1c4b6..a8864244b1 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.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-09-15-client-session-blank-reconciliation.md
-2026-09-15-client-session-blank-reconciliation.md: c9fe88f82f088f03539f8487740c83437bc53ade
-2026-09-15-client-session-blank-reconciliation.zh.md: 70e144b552d1dabfecb428db04894ad4007011c5
+2026-09-15-client-session-blank-reconciliation.md: 6303132ff61519c43383e44c1ee4ef6a6c74664d
+2026-09-15-client-session-blank-reconciliation.zh.md: 51ddd2d4cc73f5b585a79f62690847242631414d
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
index c9fe88f82f..6303132ff6 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
@@ -32,7 +32,7 @@ Accepted or observed-running Sessions retain their existing display conversion,
 
 The Manager owns one additional per-id display flag. It does not replace Session-local presentation fields or implement a history/draft/presentation redesign.
 
-For an identity with neither subagent origin nor a retained child address, a removal notification discards its projection store, while a retained Session object keeps the store it was constructed with — for example a current row removed while its Session is still staged. If that identity returns to the list before its Session object is dropped, the Manager creates and seeds a second store that the resident object never reads, so list rows and that object's projection readers can disagree until a replacement instance adopts the current store. Repairing that projection ownership is deferred to its own change; blank display does not depend on it.
+For an identity with neither subagent origin nor a retained child address, a removal notification discards its projection store unless that store already carries a non-empty `subagentCatalog`; a retained Session object keeps the store it was constructed with — for example a current row removed while its Session is still staged. If that identity returns to the list before its Session object is dropped, the Manager creates and seeds a second store that the resident object never reads, so list rows and that object's projection readers can disagree until a replacement instance adopts the current store. Repairing that projection ownership is deferred to its own change; blank display does not depend on it.
 
 ## Verification
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
index 70e144b552..51ddd2d4cc 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
@@ -32,7 +32,7 @@ Status: implemented
 
 Manager 额外维护一个按 id 保存的展示标记。它不替代 Session 本地展示字段，也不实施历史/草稿/展示状态重构。
 
-对于来源不是 subagent、也没有保留子会话地址的身份，移除通知会丢弃它的投影存储，而仍被保留的 Session 对象继续持有构造时采用的存储，例如当前行被移除而它的 Session 仍留在舞台上。若该身份在其 Session 对象被销毁前回到列表，Manager 会新建并写入第二个存储，而常驻对象从不读取它，因此在替换实例采用当前存储之前，列表行与该对象的投影读取方可能不一致。该投影归属的修复延期到独立的改动；blank 展示不依赖它。
+对于来源不是 subagent、也没有保留子会话地址的身份，移除通知会丢弃它的投影存储——除非该存储已带有非空的 `subagentCatalog`；而仍被保留的 Session 对象继续持有构造时采用的存储，例如当前行被移除而它的 Session 仍留在舞台上。若该身份在其 Session 对象被销毁前回到列表，Manager 会新建并写入第二个存储，而常驻对象从不读取它，因此在替换实例采用当前存储之前，列表行与该对象的投影读取方可能不一致。该投影归属的修复延期到独立的改动；blank 展示不依赖它。
 
 ## 验证
 

From ae58d210eb45f1abc4254704100f8e56fbc0afd4 Mon Sep 17 00:00:00 2001
From: liukx0205 <harusoda@berkeley.edu>
Date: Sun, 20 Sep 2026 12:48:14 +0800
Subject: [PATCH 17/37] docs(web): scope the second projection store to a
 discarded store

---
 .../2026-09-15-client-session-blank-reconciliation.i18n.yaml  | 4 ++--
 .../bug-fix/2026-09-15-client-session-blank-reconciliation.md | 2 +-
 .../2026-09-15-client-session-blank-reconciliation.zh.md      | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
index a8864244b1..9e26577ff2 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.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-09-15-client-session-blank-reconciliation.md
-2026-09-15-client-session-blank-reconciliation.md: 6303132ff61519c43383e44c1ee4ef6a6c74664d
-2026-09-15-client-session-blank-reconciliation.zh.md: 51ddd2d4cc73f5b585a79f62690847242631414d
+2026-09-15-client-session-blank-reconciliation.md: ef4734663783c8989173295119b680515be482f7
+2026-09-15-client-session-blank-reconciliation.zh.md: 1a8effe5a3a8caaf45f6941978590697fc563e76
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
index 6303132ff6..ef47346637 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
@@ -32,7 +32,7 @@ Accepted or observed-running Sessions retain their existing display conversion,
 
 The Manager owns one additional per-id display flag. It does not replace Session-local presentation fields or implement a history/draft/presentation redesign.
 
-For an identity with neither subagent origin nor a retained child address, a removal notification discards its projection store unless that store already carries a non-empty `subagentCatalog`; a retained Session object keeps the store it was constructed with — for example a current row removed while its Session is still staged. If that identity returns to the list before its Session object is dropped, the Manager creates and seeds a second store that the resident object never reads, so list rows and that object's projection readers can disagree until a replacement instance adopts the current store. Repairing that projection ownership is deferred to its own change; blank display does not depend on it.
+For an identity with neither subagent origin nor a retained child address, a removal notification discards its projection store unless that store already carries a non-empty `subagentCatalog`; a retained Session object keeps the store it was constructed with — for example a current row removed while its Session is still staged. If its projection store was discarded and that identity returns to the list before its Session object is dropped, the Manager creates and seeds a second store that the resident object never reads, so list rows and that object's projection readers can disagree until a replacement instance adopts the current store. Repairing that projection ownership is deferred to its own change; blank display does not depend on it.
 
 ## Verification
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
index 51ddd2d4cc..1a8effe5a3 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
@@ -32,7 +32,7 @@ Status: implemented
 
 Manager 额外维护一个按 id 保存的展示标记。它不替代 Session 本地展示字段，也不实施历史/草稿/展示状态重构。
 
-对于来源不是 subagent、也没有保留子会话地址的身份，移除通知会丢弃它的投影存储——除非该存储已带有非空的 `subagentCatalog`；而仍被保留的 Session 对象继续持有构造时采用的存储，例如当前行被移除而它的 Session 仍留在舞台上。若该身份在其 Session 对象被销毁前回到列表，Manager 会新建并写入第二个存储，而常驻对象从不读取它，因此在替换实例采用当前存储之前，列表行与该对象的投影读取方可能不一致。该投影归属的修复延期到独立的改动；blank 展示不依赖它。
+对于来源不是 subagent、也没有保留子会话地址的身份，移除通知会丢弃它的投影存储——除非该存储已带有非空的 `subagentCatalog`；而仍被保留的 Session 对象继续持有构造时采用的存储，例如当前行被移除而它的 Session 仍留在舞台上。若投影存储已被丢弃，且该身份在其 Session 对象被销毁前回到列表，Manager 会新建并写入第二个存储，而常驻对象从不读取它，因此在替换实例采用当前存储之前，列表行与该对象的投影读取方可能不一致。该投影归属的修复延期到独立的改动；blank 展示不依赖它。
 
 ## 验证
 

From 4bff618b17c7c40e95a5223e11f7db91ca617951 Mon Sep 17 00:00:00 2001
From: liukx0205 <harusoda@berkeley.edu>
Date: Sun, 20 Sep 2026 14:44:25 +0800
Subject: [PATCH 18/37] docs(web): note the metadata hint applied over the
 engagement rule

---
 .../2026-09-15-client-session-blank-reconciliation.i18n.yaml  | 4 ++--
 .../bug-fix/2026-09-15-client-session-blank-reconciliation.md | 2 +-
 .../2026-09-15-client-session-blank-reconciliation.zh.md      | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
index 9e26577ff2..154afe129e 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.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-09-15-client-session-blank-reconciliation.md
-2026-09-15-client-session-blank-reconciliation.md: ef4734663783c8989173295119b680515be482f7
-2026-09-15-client-session-blank-reconciliation.zh.md: 1a8effe5a3a8caaf45f6941978590697fc563e76
+2026-09-15-client-session-blank-reconciliation.md: 7213636e32702c4c51887adba3da019f49b8703c
+2026-09-15-client-session-blank-reconciliation.zh.md: 4b50340fea668b6d850c1d00787dda3874b61e0c
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
index ef47346637..7213636e32 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
@@ -10,7 +10,7 @@ A successful prompt response converts the Client's `New Session` row before a tu
 
 ## Decision
 
-The [Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) retains accepted/running observations in a private set keyed by Session id. List rows and the existing Session blank updates use `summary.blank && !engagedSessions.has(sessionId)`. The existing summary mutations, Session snapshot fields, constructor, and projection stores retain their responsibilities.
+The [Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) retains accepted/running observations in a private set keyed by Session id. List rows and the existing Session blank updates use `summary.blank && !engagedSessions.has(sessionId)`, with `sessionListMetadata` hints still applied on top. The existing summary mutations, Session snapshot fields, constructor, and projection stores retain their responsibilities.
 
 Every successful prompt response invokes the existing `onEngaged` callback, including from a replaced Session object. The Manager updates its retained observation, the list row, and the currently resident Session by id. Rejection records no engagement. A `running: true` status, addition, or list baseline also records engagement; a baseline predating removal cannot restore that observation, even if the row is re-added during the pull.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
index 1a8effe5a3..4b50340fea 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) 使用按 Session id 索引的私有集合，保留已观察到的受理/运行。列表行与既有 Session blank 更新使用 `summary.blank && !engagedSessions.has(sessionId)`。既有摘要变更、Session 快照字段、构造函数和投影存储保留原有职责。
+[Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) 使用按 Session id 索引的私有集合，保留已观察到的受理/运行。列表行与既有 Session blank 更新使用 `summary.blank && !engagedSessions.has(sessionId)`，其上仍叠加 `sessionListMetadata` 提示。既有摘要变更、Session 快照字段、构造函数和投影存储保留原有职责。
 
 每个成功的提示词响应都会调用既有 `onEngaged` 回调，包括来自已被替换的 Session 对象的响应。Manager 按 id 更新其保留的观察、列表行和当前驻留 Session。拒绝不会记录受理/运行。`running: true` 状态、添加事件或列表基线也会记录运行；早于移除的基线不能恢复该观察，即使该行在拉取期间重新加入。
 

From 4f0ee6b1059806531608516bf27cca0cde65d406 Mon Sep 17 00:00:00 2001
From: lsdsjy <1356263+lsdsjy@users.noreply.github.com>
Date: Sun, 20 Sep 2026 14:42:39 +0800
Subject: [PATCH 19/37] fix(settings): defer developer features until host
 preference resolves

---
 ...6-09-17-developer-tools-settings.i18n.yaml |  4 +-
 .../2026-09-17-developer-tools-settings.md    |  2 +-
 .../2026-09-17-developer-tools-settings.zh.md |  4 +-
 ...09-20-developer-tools-default-on.i18n.yaml |  6 +++
 .../2026-09-20-developer-tools-default-on.md  | 31 ++++++++++++
 ...026-09-20-developer-tools-default-on.zh.md | 31 ++++++++++++
 apps/web/tests/assembled-remote.ts            | 20 ++++----
 .../web/tests/developer-tools-settings.e2e.ts |  2 +
 apps/web/tests/document-preview.e2e.ts        |  2 +-
 .../client/ui-agent-preset/README.i18n.yaml   |  2 +-
 packages/client/ui-agent-preset/README.zh.md  |  2 +-
 .../tests/section.client.spec.tsx             | 29 ++++++-----
 .../src/client/view-selection.ts              |  2 +-
 .../tests/apply-inject.client.spec.tsx        | 22 ++++++++
 .../tests/apply.client.spec.ts                |  2 +-
 packages/client/ui-settings/README.i18n.yaml  |  4 +-
 packages/client/ui-settings/README.md         |  2 +-
 packages/client/ui-settings/README.zh.md      |  2 +-
 .../ui-settings/src/client/developer-tools.ts |  4 +-
 .../tests/developer-tools.client.spec.ts      | 50 +++++++++++++++++--
 .../tests/html-body.client.spec.tsx           | 28 +++++++++++
 scripts/no-unknown-casts.baseline.json        |  4 --
 .../web/document-preview/document.expected.md |  2 +-
 23 files changed, 208 insertions(+), 49 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md
 create mode 100644 .agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.zh.md

diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
index 0565db8d75..af257a325c 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.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-17-developer-tools-settings.md
-2026-09-17-developer-tools-settings.md: 0745eb32cf5244d5a4ed8e70b84a7598232856c6
-2026-09-17-developer-tools-settings.zh.md: f177eef8c5c07891db1712b55f63d398276a0cf3
+2026-09-17-developer-tools-settings.md: 7819b2a2df3c9eaf2db1e1271d7b419768affaff
+2026-09-17-developer-tools-settings.zh.md: 5ff9f2c1e2380f086969cc392bf649edd13e2893
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
index 0745eb32cf..7819b2a2df 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
@@ -10,7 +10,7 @@ Diagnostic views, preset selection and changed-file summaries add complexity to
 
 ## Decision
 
-The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference, defaulting on. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
+The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference. The initial default-off choice reduces routine-task complexity; [Developer tools default on after preference resolution](2026-09-20-developer-tools-default-on.md) supersedes that default and owns startup enablement. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
 
 Off hides the Trajectory View, hides tool Inspect actions when no visible View declares tool-call inspection, hides the conversation View tab bar while fewer than two Views are available, hides the new-session preset chip and the settings row that allows switching Agent modes, and omits the changed-files card and its summary read. Views registered by other plugins stay available. Turning it off while Trajectory is active activates Chat. The preset composition, saved default, Session events and explicit delivery cards remain unchanged. This preference is presentation policy, not Host authorization.
 
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
index f177eef8c5..5ff9f2c1e2 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## Decision
 
-设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好，默认开启。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
+设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好。最初默认关闭的选择用于降低日常任务的复杂度；[偏好解析后默认开启开发者工具](2026-09-20-developer-tools-default-on.zh.md)取代该默认值并负责启动时的启用策略。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
 
-关闭时隐藏 Trajectory View，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，可见 View 少于两个时隐藏会话 View 标签栏，隐藏新会话预设入口和「允许切换 agent 模式」设置行，并省略改动文件卡片及其摘要读取。其他插件注册的 View 保持可用。在 Trajectory 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
+关闭时隐藏 Trajectory View，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，可见 View 少于两个时隐藏会话 View 标签栏，隐藏新会话预设入口和「允许切换agent模式」设置行，并省略改动文件卡片及其摘要读取。其他插件注册的 View 保持可用。在 Trajectory 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
 
 插件组装层将共享偏好转换为组件自身的能力（`showCodeDiff`、`showPresetPicker` 和 `interactivePreview`）。Conversation 根据可见目标的 `toolCallFocus` 提供检查回调；Chat 不再指定目标名称。内置 HTML 渲染器使用 DOMPurify 清理完整文档并防护解析变异。关闭时保留根节点样式，移除主动文档、资源提示、SVG 动画及所有 `href` 属性，再放入不授予沙箱权限的 iframe，并通过 CSP 禁止脚本和外部资源。不读取关联文件。开启时保留不透明源的脚本 Blob 渲染器及其有界关联文件读取。切换模式会替换浏览上下文并清理待处理读取。[文档预览决策](../architecture/2026-09-08-document-preview-operations.zh.md)和[文件系统读取权限](../architecture/2026-09-09-workspace-file-read-authority.zh.md)继续定义高级渲染与 Host 读取访问。
 
diff --git a/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.i18n.yaml b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.i18n.yaml
new file mode 100644
index 0000000000..aa7199eff4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.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-20-developer-tools-default-on.md
+2026-09-20-developer-tools-default-on.md: 42c89faed11b966ac8ea0882236af9bf13557702
+2026-09-20-developer-tools-default-on.zh.md: a684844f5ba53a0bebdd1c3a3a3ade1ed150cc31
diff --git a/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md
new file mode 100644
index 0000000000..42c89faed1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md
@@ -0,0 +1,31 @@
+# Agent Note: Developer tools default on after preference resolution
+
+Status: implemented
+
+English | [中文](2026-09-20-developer-tools-default-on.zh.md)
+
+## Problem
+
+New installations need access to developer views, preset selection, change summaries and interactive HTML previews without first finding a Settings switch. A saved disabled preference must still prevent those features from activating during startup, including script execution that cannot be undone after it occurs.
+
+## Decision
+
+The Host schema defaults `ui-developer-tools.enabled` to `true`. Remote browsers with process-local preferences also start enabled. Saved Host values take precedence, including `false`. This supersedes only the initial default-off choice in [Shared developer-tool settings](2026-09-17-developer-tools-settings.md); that note retains ownership of shared persistence and rendering policy.
+
+Host-backed clients publish disabled until an accepted schema-resolved value arrives. Loading, failed initial reads and an unavailable namespace do not grant interactive-preview capabilities. The Host supplies the default for an absent stored field; the client does not interpret an absent response as consent to enable scripts. An accepted value remains authoritative during later refreshes.
+
+Only the Trajectory tab follows the developer-tools preference; third-party Views remain available. The conversation shell retains the explicit Trajectory id because the requested rule names that View. No current requirement makes arbitrary diagnostic Views share the switch.
+
+## Alternatives considered
+
+**Keep the default off.** This minimizes the initial interface but requires a separate opt-in for the features new installations now expose. Users can still save the disabled preference.
+
+**Default the Host client to enabled before settings arrive.** This makes rendering immediate, but briefly activates features for users who disabled them. Unmounting a scripted HTML iframe cannot undo scripts or requests already executed.
+
+**Add a generic developer-tool flag to View registration.** This expands the plugin API and allows other Views to join a switch whose current requirement is specific to Trajectory. A future requirement can justify that API separately.
+
+## Consequences
+
+Fresh profiles expose developer features after settings resolve; users with a saved disabled choice retain the simpler presentation. New users also receive interactive HTML previews with the capabilities documented by the [filesystem-read authority](../architecture/2026-09-09-workspace-file-read-authority.md). Host initialization can briefly withhold developer controls even when the eventual preference is enabled.
+
+Settings tests cover initial withholding, unavailable namespaces, explicit disabled values and process-local defaults. HTML renderer coverage checks that pending and disabled preferences neither read related files nor create script-enabled frames. Browser settings coverage verifies the default and a disabled choice across reload; document-preview replay pins the explicitly disabled scenario.
diff --git a/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.zh.md b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.zh.md
new file mode 100644
index 0000000000..a684844f5b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 偏好解析后默认开启开发者工具
+
+Status: implemented
+
+[English](2026-09-20-developer-tools-default-on.md) | 中文
+
+## Problem
+
+新安装需要直接使用开发者视图、预设选择、改动摘要和交互式 HTML 预览，无需先寻找设置开关。已保存的关闭偏好仍必须阻止这些功能在启动期间激活，包括发生后无法撤销的脚本执行。
+
+## Decision
+
+Host schema 将 `ui-developer-tools.enabled` 默认为 `true`。使用进程内偏好的远程浏览器也从开启状态启动。已保存的 Host 值优先，包括 `false`。这仅取代[共享开发者工具设置](2026-09-17-developer-tools-settings.zh.md)中最初默认关闭的选择；该记录继续负责共享持久化和渲染策略。
+
+使用 Host 偏好的客户端在收到经过 schema 解析并接受的值之前发布关闭状态。加载中、首次读取失败和命名空间不可用均不授予交互式预览能力。缺少存储字段时由 Host 提供默认值；客户端不会把缺少响应解释为允许开启脚本。后续刷新期间，已接受的值继续有效。
+
+只有 Trajectory 标签页受开发者工具偏好控制；第三方 View 保持可用。对话外壳保留显式 Trajectory id，因为当前需求明确指定此 View。没有现行需求要求任意诊断 View 共用该开关。
+
+## Alternatives considered
+
+**保持默认关闭。** 这可简化初始界面，但新安装现在直接提供的功能将需要额外启用。用户仍可保存关闭偏好。
+
+**在设置到达前让 Host 客户端默认开启。** 这可以立即渲染，却会短暂激活用户已关闭的功能。卸载可执行脚本的 HTML iframe 无法撤销已经执行的脚本或请求。
+
+**在 View 注册中增加通用开发者工具标记。** 这会扩展插件 API，并允许其他 View 加入当前仅针对 Trajectory 的开关。未来需求可以单独论证该 API。
+
+## Consequences
+
+新 profile 在设置解析后展示开发者功能；已保存关闭选择的用户保留简化展示。新用户也会获得带有[文件系统读取权限](../architecture/2026-09-09-workspace-file-read-authority.zh.md)所述能力的交互式 HTML 预览。即使最终偏好为开启，Host 初始化期间也可能短暂不展示开发者控件。
+
+设置测试覆盖首次等待、命名空间不可用、显式关闭值和进程内默认值。HTML 渲染器覆盖验证等待中及关闭偏好均不读取关联文件，也不创建允许脚本的 frame。浏览器设置覆盖验证默认值和关闭选择在刷新后保持；文档预览回放固定显式关闭的场景。
diff --git a/apps/web/tests/assembled-remote.ts b/apps/web/tests/assembled-remote.ts
index 72a3db40db..5d9b7f8a14 100644
--- a/apps/web/tests/assembled-remote.ts
+++ b/apps/web/tests/assembled-remote.ts
@@ -99,7 +99,7 @@ interface CapturedFixture {
 }
 
 export interface AssembledRemoteOptions {
-  /** Supply an enabled Host preference for diagnostic View scenarios. */
+  /** Override the schema-resolved Host preference for developer-tool scenarios. */
   readonly developerTools?: boolean
   /** Return the fixture's image-dimension admission error from Session prompt. */
   readonly rejectPrompt?: boolean
@@ -142,16 +142,14 @@ export function createAssembledRemote(options: AssembledRemoteOptions = {}): Ass
   const mock = RemoteMock.create().load(remoteDefaultResponses)
   mock.load({
     unary: {
-      'settings/describe': options.developerTools === true
-        ? ok({
-          ...fixture.settingsDescribe.value,
-          namespaces: [...fixture.settingsDescribe.value.namespaces, {
-            ns: 'ui-developer-tools',
-            schema: { type: 'object', dict: { enabled: { type: 'boolean' } } },
-            value: { enabled: true }, applies: 'live', secrets: [], revision: 0,
-          }],
-        })
-        : structuredClone(fixture.settingsDescribe),
+      'settings/describe': ok({
+        ...fixture.settingsDescribe.value,
+        namespaces: [...fixture.settingsDescribe.value.namespaces, {
+          ns: 'ui-developer-tools',
+          schema: { type: 'object', dict: { enabled: { type: 'boolean' } } },
+          value: { enabled: options.developerTools ?? true }, applies: 'live', secrets: [], revision: 0,
+        }],
+      }),
       'credentials/describe': structuredClone(fixture.credentialsDescribe),
       'session/modelCatalog': structuredClone(fixture.modelCatalog),
       'agentPresets/list': structuredClone(fixture.agentPresets),
diff --git a/apps/web/tests/developer-tools-settings.e2e.ts b/apps/web/tests/developer-tools-settings.e2e.ts
index 6790c94a0c..28dddd3c02 100644
--- a/apps/web/tests/developer-tools-settings.e2e.ts
+++ b/apps/web/tests/developer-tools-settings.e2e.ts
@@ -30,9 +30,11 @@ it('persists developer tools in the Host settings document and restores the acce
   expect(await pickerToggle.count()).toBe(0)
   await scaffold.ctx.settings.update('ui-developer-tools', { enabled: true })
   await expect.poll(() => pickerToggle.count()).toBe(1)
+  await expect.poll(() => pickerToggle.isEnabled()).toBe(true)
   const pickerEnabled = await pickerToggle.getAttribute('aria-checked')
   await scaffold.ctx.settings.update('ui-developer-tools', { enabled: false })
   await expect.poll(() => pickerToggle.count()).toBe(0)
   await scaffold.ctx.settings.update('ui-developer-tools', { enabled: true })
+  await expect.poll(() => pickerToggle.isEnabled()).toBe(true)
   await expect.poll(() => pickerToggle.getAttribute('aria-checked')).toBe(pickerEnabled)
 })
diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts
index 31b2fd06b6..8c41184009 100644
--- a/apps/web/tests/document-preview.e2e.ts
+++ b/apps/web/tests/document-preview.e2e.ts
@@ -365,7 +365,7 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
     await successShot(page, 'html-basic')
     sections.push([
       '## Basic HTML', '',
-      '- Developer tools: off by default on Web and desktop',
+      '- Developer tools: disabled for this scenario',
       '- Sandbox: no permissions',
       `- Inline script: ${await basicHtml.locator('#result').innerText()}`,
       `- Local script: ${await basicHtml.locator('#local-result').innerText()}`,
diff --git a/packages/client/ui-agent-preset/README.i18n.yaml b/packages/client/ui-agent-preset/README.i18n.yaml
index acc5d685c6..3b67b4ca8a 100644
--- a/packages/client/ui-agent-preset/README.i18n.yaml
+++ b/packages/client/ui-agent-preset/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-agent-preset/README.md
 README.md: 5f2c9acaa5840e71d6ca237c5fc5eccb52724cda
-README.zh.md: 1bc0c8d08f2358725a104309269197036b74e71b
+README.zh.md: 5c61823c25f145c0e516f3f2a16c2de05c250ef1
diff --git a/packages/client/ui-agent-preset/README.zh.md b/packages/client/ui-agent-preset/README.zh.md
index 1bc0c8d08f..5c61823c25 100644
--- a/packages/client/ui-agent-preset/README.zh.md
+++ b/packages/client/ui-agent-preset/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-新会话选择器和管理区域中的「允许切换 agent 模式」整行设置仅在通用设置中开启开发者工具时显示。此展示偏好不会改变已选预设、保存的默认值、Host 组合或管理区域独立的选择器策略。
+新会话选择器和管理区域中的「允许切换agent模式」整行设置仅在通用设置中开启开发者工具时显示。此展示偏好不会改变已选预设、保存的默认值、Host 组合或管理区域独立的选择器策略。
 
 与设置和对话包一起挂载本插件；通用设置开启开发者工具后，管理分区会显示一个默认开启的可见性开关。关闭期间，新建会话 chip 不出现，宿主会依据部署默认值（随附 Web bundle 中为 `standard`）组装未指名会话。开启时会恢复已保存的用户默认值；尚未保存时则使用部署默认值；该默认值会同时带到当前空白任务上。chip 中的选择本身只为下一个空白会话暂存一次。再次关闭选择器会以同样方式把当前空白任务带回部署默认值，并丢弃尚未使用的暂存选择；已开始及历史会话的标签、组装与已记录历史均保持不变。
 
diff --git a/packages/client/ui-agent-preset/tests/section.client.spec.tsx b/packages/client/ui-agent-preset/tests/section.client.spec.tsx
index 4c11822147..22de6a09cd 100644
--- a/packages/client/ui-agent-preset/tests/section.client.spec.tsx
+++ b/packages/client/ui-agent-preset/tests/section.client.spec.tsx
@@ -17,6 +17,8 @@ import { en } from '../src/client/locales.ts'
 
 afterEach(cleanup)
 
+const translations: ReadonlyMap<string, string> = new Map(Object.entries(en))
+
 const READY: AgentPresetSectionState = {
   status: 'ready',
   error: null,
@@ -35,6 +37,10 @@ const READY: AgentPresetSectionState = {
   revealedPaths: {},
 }
 
+function unusedHook(): never {
+  throw new Error('This section does not read global slot sources')
+}
+
 /**
  * Render the section over a fixed snapshot, with every action a spy.
  * @param state - the snapshot to render.
@@ -63,12 +69,18 @@ function renderSection(
     makeDefault: vi.fn(() => Promise.resolve()),
     setPickerVisible: vi.fn(() => Promise.resolve()),
   }
-  const props = {
+  const props: AgentPresetSectionProps = {
     ...actions,
+    usePanelInfo: unusedHook,
+    useSessions: unusedHook,
+    useSessionStatus: unusedHook,
+    useSessionRetainInfo: unusedHook,
+    useWorkspaces: unusedHook,
+    useResource: unusedHook,
     useAgentPresetSection: bindSnapshotSelector(store),
     useDeveloperTools: bindSnapshotSelector(createSnapshotStore(options.developerTools ?? true)),
-    t: (key: keyof typeof en) => en[key],
-  } as unknown as AgentPresetSectionProps
+    t: key => translations.get(key) ?? key,
+  }
   render(<AgentPresetSection {...props} />)
   return actions
 }
@@ -356,15 +368,8 @@ describe('the preset list', () => {
   })
 
   it('renders nothing when the deployment composes no presets', () => {
-    const { container } = render(<AgentPresetSection {...({
-      useDeveloperTools: bindSnapshotSelector(createSnapshotStore(true)),
-      useAgentPresetSection: bindSnapshotSelector(
-        createSnapshotStore<AgentPresetSectionState>({ ...READY, status: 'unavailable', rows: [] })),
-      t: (key: keyof typeof en) => en[key],
-      load: vi.fn(() => Promise.resolve()),
-    } as unknown as AgentPresetSectionProps)} />)
-
-    expect(container.firstChild).toBeNull()
+    renderSection({ status: 'unavailable', rows: [] })
+    expect(screen.queryByRole('heading')).toBeNull()
   })
 
   it('offers a retry when the roster could not be read', () => {
diff --git a/packages/client/ui-conversation/src/client/view-selection.ts b/packages/client/ui-conversation/src/client/view-selection.ts
index 53b0ffc86a..6d0589759c 100644
--- a/packages/client/ui-conversation/src/client/view-selection.ts
+++ b/packages/client/ui-conversation/src/client/view-selection.ts
@@ -1,6 +1,6 @@
 import type { ViewTab } from './contract/views.ts'
 
-/** Chat remains available when developer tools are disabled. */
+/** Fallback View selected when no stored preference resolves to a registered View. */
 export const DEFAULT_VIEW_ID = 'chat'
 
 /** The one View the Developer tools preference gates; other Views stay registered by their owners. */
diff --git a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
index 06da77c712..e90a11a163 100644
--- a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
@@ -219,6 +219,28 @@ describe('Conversation inject API', () => {
     expect(source.getSnapshot()).toBeUndefined()
     await b.runtime.ctx.settingsScope.developerTools.setEnabled(true)
     expect(source.getSnapshot()).toBe(inspect)
+    // Trajectory still owns inspection while both Views are visible; hiding
+    // it must leave a third-party View's inspection capability reachable.
+    const removePipelineDefinition = b.runtime.ctx.uiConversation.views.register({
+      target: 'pipeline',
+      toolCallFocus: callId => `stage:${callId}`,
+      create: () => ({ empty: null, replace: () => null, apply: () => null }),
+    })
+    const removePipelineView = b.slots.register(
+      { name: 'conversation.view', id: 'pipeline' }, (() => null) as never,
+    )
+    await b.runtime.flush()
+    expect(source.getSnapshot()).toBe(inspect)
+    await b.runtime.ctx.settingsScope.developerTools.setEnabled(false)
+    const pipelineInspect = source.getSnapshot()!
+    expect(pipelineInspect).toBeTypeOf('function')
+    pipelineInspect('call-2')
+    expect(body.instance.store.getSnapshot().viewRequest).toEqual({ view: 'pipeline', focus: 'stage:call-2' })
+    await b.runtime.ctx.settingsScope.developerTools.setEnabled(true)
+    removePipelineView()
+    removePipelineDefinition()
+    await b.runtime.flush()
+    expect(source.getSnapshot()).toBe(inspect)
     removeView()
     await b.runtime.flush()
     expect(source.getSnapshot()).toBeUndefined()
diff --git a/packages/client/ui-settings-general/tests/apply.client.spec.ts b/packages/client/ui-settings-general/tests/apply.client.spec.ts
index ae974a73f3..1d11e8ea30 100644
--- a/packages/client/ui-settings-general/tests/apply.client.spec.ts
+++ b/packages/client/ui-settings-general/tests/apply.client.spec.ts
@@ -107,7 +107,7 @@ describe('ui-settings-general apply', () => {
     const developerRow = c.ctx.slots.entries('settings.general.item').find(row => row.options.id === 'developer-tools')!
     const developer = (developerRow.inject as unknown as () => DeveloperToolsRowInjected)()
     expect(developer.hooks.developerTools).toBe(c.ctx.settingsScope.developerTools.enabled)
-    expect(developer.hooks.developerTools.getSnapshot()).toBe(true)
+    expect(developer.hooks.developerTools.getSnapshot()).toBe(false)
     const setEnabled = vi.spyOn(c.ctx.settingsScope.developerTools, 'setEnabled').mockResolvedValue(undefined)
     await developer.setEnabled(true)
     expect(setEnabled).toHaveBeenCalledExactlyOnceWith(true)
diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml
index fdb34612b3..8123e08a21 100644
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/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-settings/README.md
-README.md: 8418c14273c863eb786c83e2d8eaedfd3d1ae2f6
-README.zh.md: 296f61f929187785c7cefa3e452eec3f3b3e72b0
+README.md: d688442cb003f980b037354f76997c18a2ca0be2
+README.zh.md: 92e2026d04f188854fd6205fe4d35e8c9c8e57b2
diff --git a/packages/client/ui-settings/README.md b/packages/client/ui-settings/README.md
index 8418c14273..d688442cb0 100644
--- a/packages/client/ui-settings/README.md
+++ b/packages/client/ui-settings/README.md
@@ -29,7 +29,7 @@ Feature plugins use this package to store and edit their preferences without re-
 
 ### Binding a namespace
 
-`ctx.settingsScope.developerTools` owns the shared Web and desktop preference `ui-developer-tools.enabled`, defaulting to `true`. Its `enabled` observable publishes accepted choices and `setEnabled` uses the same ordered settings writes. Desktop and loopback Web persist to the Host document; remote Web keeps this choice in one browser-local observable until reload without issuing Host writes. This controls presentation and HTML preview permissions, not Host authorization or Session recording.
+`ctx.settingsScope.developerTools` owns the shared Web and desktop preference `ui-developer-tools.enabled`, defaulting to `true`. Its `enabled` observable publishes accepted choices and `setEnabled` uses the same ordered settings writes. Desktop and loopback Web persist to the Host document; remote Web keeps this choice in one browser-local observable until reload without issuing Host writes. This controls presentation and HTML preview permissions, not Host authorization or Session recording. Host-backed clients keep developer features disabled until the first accepted schema-resolved value arrives; missing or failed initial responses do not enable them. Later refreshes retain the last accepted choice.
 
 A feature calls `ctx.settingsScope.bind(spec)` with a per-namespace spec and gets a scope derived from the shared document mirror. The scope snapshot carries the resolved section, composition `base`, raw `user`, revision, writability, and host/memory mode; a field is overridden when it is present in `user`, even when its value equals `base`, and `unset` clears that override. Writes go through the scope: `set` and `unset` submit one operation, while `mutate` submits several ordered operations atomically. These methods return `true` for Host acceptance and `false` for refusal or skipped writes; transport failures reject. Each write is fenced by the namespace revision as `expectedRevision`, so a concurrent write from another surface is refused instead of silently overwritten. A staged editor can supply the revision where its draft began as a fixed fence; otherwise the scope uses the latest queued or mirrored revision.
 
diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md
index 296f61f929..92e2026d04 100644
--- a/packages/client/ui-settings/README.zh.md
+++ b/packages/client/ui-settings/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 绑定命名空间
 
-`ctx.settingsScope.developerTools` 管理 Web 和桌面端共享的偏好 `ui-developer-tools.enabled`，默认为 `true`。其 `enabled` 可观察值发布已接受的选择，`setEnabled` 使用相同的有序设置写入。桌面端和回环 Web 将设置持久化到 Host 文档；远程 Web 将此选择保存在单个浏览器本地可观察值中，刷新后重置，不发送 Host 写入。此设置控制界面展示和 HTML 预览权限，不控制 Host 授权或 Session 记录。
+`ctx.settingsScope.developerTools` 管理 Web 和桌面端共享的偏好 `ui-developer-tools.enabled`，默认为 `true`。其 `enabled` 可观察值发布已接受的选择，`setEnabled` 使用相同的有序设置写入。桌面端和回环 Web 将设置持久化到 Host 文档；远程 Web 将此选择保存在单个浏览器本地可观察值中，刷新后重置，不发送 Host 写入。此设置控制界面展示和 HTML 预览权限，不控制 Host 授权或 Session 记录。 使用 Host 偏好的客户端在首个经过 schema 解析并接受的值到达前保持开发者功能关闭；首次响应缺失或失败不会启用它们。后续刷新保留已接受的选择。
 
 功能调用 `ctx.settingsScope.bind(spec)` 并传入按命名空间的 spec，得到一个由共享文档镜像派生的 scope。scope 快照携带解析后的分区、组合 `base`、原始 `user`、revision、可写性以及 host/内存模式；字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等，`unset` 会清除该覆盖。写入经 scope 进行：`set` 与 `unset` 提交一个操作，`mutate` 则原子提交多个有序操作。这些方法在 Host 接受时返回 `true`，拒绝或跳过写入时返回 `false`；传输失败会 reject。每次写入都以命名空间 revision 作为 `expectedRevision` 围栏，因此来自另一界面的并发写入会被拒绝，而不是被静默覆盖。暂存编辑器可以把开始草拟时读取的 revision 作为固定围栏传入；否则 scope 使用最新排队或镜像 revision。
 
diff --git a/packages/client/ui-settings/src/client/developer-tools.ts b/packages/client/ui-settings/src/client/developer-tools.ts
index 51466d878f..907b32065a 100644
--- a/packages/client/ui-settings/src/client/developer-tools.ts
+++ b/packages/client/ui-settings/src/client/developer-tools.ts
@@ -3,7 +3,7 @@ import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-c
 import type { DeveloperToolsSettings } from '../developer-tools-settings.ts'
 import type { SettingsScope } from './settings-contract.ts'
 
-/** Shared preference; no accepted value means developer tools are enabled. */
+/** Shared preference; Host-backed features stay disabled until an accepted value arrives. */
 export class DeveloperToolsPreference {
   /** Accepted enablement, observable through renderer-bound hooks. */
   readonly enabled: ObservableSnapshot<boolean>
@@ -14,7 +14,7 @@ export class DeveloperToolsPreference {
    */
   constructor(private readonly scope: SettingsScope<DeveloperToolsSettings>) {
     this.enabled = scope.getSnapshot().mode === 'memory' ? this.local : {
-      getSnapshot: () => scope.getSnapshot().value?.enabled ?? true,
+      getSnapshot: () => scope.getSnapshot().value?.enabled ?? false,
       subscribe: (listener) => {
         let previous = this.enabled.getSnapshot()
         return scope.subscribe(() => {
diff --git a/packages/client/ui-settings/tests/developer-tools.client.spec.ts b/packages/client/ui-settings/tests/developer-tools.client.spec.ts
index 6b7aebebce..08d9e0aa47 100644
--- a/packages/client/ui-settings/tests/developer-tools.client.spec.ts
+++ b/packages/client/ui-settings/tests/developer-tools.client.spec.ts
@@ -39,6 +39,39 @@ describe('developer tools settings', () => {
     expect(ctx.settingsScope.developerTools.enabled.getSnapshot()).toBe(false)
   })
 
+  it.each([false, true])('withholds features during a delayed Host read before accepting %s', async (enabled) => {
+    const ctx = new Context()
+    const accepted = { ok: true, value: {
+      writable: true, hasDocument: true, namespaces: [{
+        ns: DEVELOPER_TOOLS_NAMESPACE,
+        schema: DeveloperToolsSettingsSchema.toJSON(),
+        value: { enabled }, revision: 1, applies: 'live', secrets: [],
+      }],
+    } }
+    const pending = Promise.withResolvers<typeof accepted>()
+    onTestFinished(async () => { pending.resolve(accepted); await ctx.fiber.dispose() })
+    new TestRemote(ctx, { settings: { describe: () => pending.promise } })
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    const preference = ctx.settingsScope.developerTools
+    const changed = vi.fn()
+    const dispose = preference.enabled.subscribe(changed)
+    onTestFinished(dispose)
+    expect(preference.enabled.getSnapshot()).toBe(false)
+    pending.resolve(accepted)
+    await ctx.settingsScope.describe().ensure()
+    expect(preference.enabled.getSnapshot()).toBe(enabled)
+    expect(changed).toHaveBeenCalledTimes(enabled ? 1 : 0)
+  })
+
+  it('keeps features disabled when the initial Host read fails', async () => {
+    const ctx = new Context()
+    onTestFinished(() => ctx.fiber.dispose())
+    new TestRemote(ctx, { settings: { describe: () => Promise.reject(new Error('disconnected')) } })
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    await ctx.settingsScope.describe().ensure()
+    expect(ctx.settingsScope.developerTools.enabled.getSnapshot()).toBe(false)
+  })
+
   it('shares one remote-browser preference across consumers and disposes it with the plugin', async () => {
     const ctx = new Context()
     onTestFinished(() => ctx.fiber.dispose())
@@ -74,15 +107,15 @@ describe('developer tools settings', () => {
     expect(ctx.settings.describe().map(row => row.ns)).not.toContain(DEVELOPER_TOOLS_NAMESPACE)
   })
 
-  it('stays on until accepted settings arrive, then follows a stored false and external changes', async () => {
+  it('stays off until accepted settings arrive, then follows a stored false and external changes', async () => {
     const host = stubSettingsScope<DeveloperToolsSettings>()
     const preference = new DeveloperToolsPreference(host.scope)
-    expect(preference.enabled.getSnapshot()).toBe(true)
+    expect(preference.enabled.getSnapshot()).toBe(false)
     const notify = vi.fn()
     const dispose = preference.enabled.subscribe(notify)
     host.publish({ status: 'ready', value: { enabled: false } })
     expect(preference.enabled.getSnapshot()).toBe(false)
-    expect(notify).toHaveBeenCalledOnce()
+    expect(notify).not.toHaveBeenCalled()
     await preference.setEnabled(true)
     expect(host.set).toHaveBeenCalledWith('enabled', true)
     host.publish({ value: { enabled: true } })
@@ -115,9 +148,16 @@ it('ignores host revisions that do not change enablement', () => {
   const notify = vi.fn()
   const dispose = preference.enabled.subscribe(notify)
   host.publish({ revision: 1 })
-  host.publish({ value: { enabled: true } })
-  expect(notify).not.toHaveBeenCalled()
   host.publish({ value: { enabled: false } })
+  expect(notify).not.toHaveBeenCalled()
+  host.publish({ value: { enabled: true } })
   expect(notify).toHaveBeenCalledOnce()
   dispose()
 })
+
+it('keeps an unavailable Host namespace disabled', () => {
+  const host = stubSettingsScope<DeveloperToolsSettings>()
+  const preference = new DeveloperToolsPreference(host.scope)
+  host.publish({ status: 'unavailable' })
+  expect(preference.enabled.getSnapshot()).toBe(false)
+})
diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
index be3a1a7869..b136e6791b 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
@@ -3,6 +3,9 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, render, screen, waitFor } from '@testing-library/react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { bindSnapshotSelector, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
+import { DeveloperToolsPreference } from '@deepseek-ai/dsh-client-ui-settings/src/client/developer-tools.ts'
+import type { DeveloperToolsSettings } from '@deepseek-ai/dsh-client-ui-settings/src/developer-tools-settings.ts'
 import type { Resources, ResourceSnapshot } from '@deepseek-ai/dsh-client-resources/client'
 import type { WorkspaceFileStat } from '@deepseek-ai/dsh-api-workspace-files/types'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -153,6 +156,31 @@ describe('HtmlBody', () => {
     expect(screen.getByRole('alert').textContent).toBe(en.failed)
   })
 
+  it('follows the shared developer-tools preference from loading through a stored false to enabled', async () => {
+    const host = stubSettingsScope<DeveloperToolsSettings>()
+    const preference = new DeveloperToolsPreference(host.scope)
+    const readRelated = vi.fn<HtmlBodyProps['readRelated']>().mockResolvedValue({ ok: true, value: {
+      absolutePath: '/workspace/asset.js', version: 'asset-v1', offset: 0, eof: true,
+      data: btoa('window.loaded = true'),
+    } })
+    const scripted: HtmlBodyProps = {
+      ...props('<p>Preview</p><script src="./asset.js"></script>'),
+      useInteractivePreview: bindSnapshotSelector(preference.enabled),
+      readRelated,
+    }
+    const view = render(<HtmlBody {...scripted} />)
+    expect(screen.getByTitle(en.frame).getAttribute('sandbox')).toBe('')
+    expect(readRelated).not.toHaveBeenCalled()
+    act(() => { host.publish({ status: 'ready', value: { enabled: false } }) })
+    expect(screen.getByTitle(en.frame).getAttribute('sandbox')).toBe('')
+    expect(readRelated).not.toHaveBeenCalled()
+    act(() => { host.publish({ value: { enabled: true } }) })
+    const advanced = await screen.findByTitle(en.frame)
+    expect(advanced.getAttribute('sandbox')).toBe('allow-scripts')
+    expect(readRelated).toHaveBeenCalledOnce()
+    view.unmount()
+  })
+
   it('renders a Blob iframe with only scripts allowed, keeping it mounted for unrelated props', async () => {
     const initial = props()
     const view = render(<HtmlBody {...initial} />)
diff --git a/scripts/no-unknown-casts.baseline.json b/scripts/no-unknown-casts.baseline.json
index f5ecfea159..1cd20f6c7f 100644
--- a/scripts/no-unknown-casts.baseline.json
+++ b/scripts/no-unknown-casts.baseline.json
@@ -481,10 +481,6 @@
   "packages/client/ui-agent-preset/tests/section-store.client.spec.ts": {
     "23e04af2a900d7a905ff7657de842e9833384a2d4c4afba33964477e43d8ba52": 1
   },
-  "packages/client/ui-agent-preset/tests/section.client.spec.tsx": {
-    "4cc9284f9e4d9df997ed042df717f143f3763130fdfb9e142226da4b5b4c60e6": 1,
-    "67694f8f44eb8347cb38c39d368f4f0ce1b78bd33a6a57a55cf4664f3eaa7f98": 1
-  },
   "packages/client/ui-agent-preset/tests/settings-store.client.spec.ts": {
     "c0e852e6b0e2a8a040b65723f8ab1d650d9cb06c26be7f3a0709ddb9f7525595": 1,
     "d6a04d954aef7a8edd403910851015c0ce1597f6f300292b5158a8bf993fc1d8": 1
diff --git a/snapshots/web/document-preview/document.expected.md b/snapshots/web/document-preview/document.expected.md
index e92c8cf01f..5495962ea8 100644
--- a/snapshots/web/document-preview/document.expected.md
+++ b/snapshots/web/document-preview/document.expected.md
@@ -17,7 +17,7 @@
 
 ## Basic HTML
 
-- Developer tools: off by default on Web and desktop
+- Developer tools: disabled for this scenario
 - Sandbox: no permissions
 - Inline script: pending
 - Local script: pending

From f984683956cc6ccfb983a8ef2eabddd548c5b08a Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sun, 20 Sep 2026 14:46:54 +0800
Subject: [PATCH 20/37] fix(subagent): store unknown mode in the existing
 catalog event

---
 ...session-local-subagent-migration.i18n.yaml |   4 +-
 ...-09-19-session-local-subagent-migration.md |   4 +-
 ...-19-session-local-subagent-migration.zh.md |   4 +-
 ...6-09-11-persistence-type-history.i18n.yaml |   4 +-
 .../2026-09-11-persistence-type-history.md    |   2 +-
 .../2026-09-11-persistence-type-history.zh.md |   2 +-
 apps/web/tests/preset-migration.snapshot.ts   |   2 +-
 docs/persistence-catalog.i18n.yaml            |   4 +-
 docs/persistence-catalog.md                   |  90 +-
 docs/persistence-catalog.zh.md                |  90 +-
 ...2026-09-20-unknown-child-catalog.i18n.yaml |   4 +-
 .../2026-09-20-unknown-child-catalog.md       |  12 +-
 ...26-09-20-unknown-child-catalog.schema.json | 118 ++-
 .../2026-09-20-unknown-child-catalog.zh.md    |  12 +-
 docs/persistence-changes/README.i18n.yaml     |   4 +-
 docs/persistence-changes/README.md            |   3 +
 docs/persistence-changes/README.zh.md         |   3 +
 .../historical-formats/README.i18n.yaml       |   4 +-
 .../historical-formats/README.md              |   2 +-
 .../historical-formats/README.zh.md           |   2 +-
 docs/persistence-schema.json                  | 888 ++++++++----------
 .../core/session/src/known-event-types.ts     |   1 -
 packages/sdk/client/tests/sdk-client.spec.ts  |   2 +-
 .../session-format-v3-to-v4/README.i18n.yaml  |   4 +-
 .../session/session-format-v3-to-v4/README.md |   6 +-
 .../session-format-v3-to-v4/README.zh.md      |   6 +-
 .../session-format-v3-to-v4/src/facts.ts      |  22 +-
 .../session-format-v3-to-v4/src/migration.ts  |   2 +-
 .../session-format-v3-to-v4/src/validation.ts |   6 +-
 .../tests/catalog-completion.spec.ts          |   8 +-
 .../tests/validation.spec.ts                  |   7 +-
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-jsonl/README.md       |   2 +-
 .../session-persistence-jsonl/README.zh.md    |   2 +-
 .../tests/catalog-migration.spec.ts           |  20 +-
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   2 +-
 packages/subagent/subagent/README.zh.md       |   2 +-
 packages/subagent/subagent/src/catalog.ts     |  29 +-
 .../subagent/subagent/tests/catalog.spec.ts   |   2 +-
 python/sdk/tests/test_client.py               |   2 +-
 scripts/persistence-changes.spec.ts           |  53 ++
 scripts/persistence-changes.ts                |  23 +
 43 files changed, 703 insertions(+), 764 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
index fba52db72b..8b543c4f2b 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.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-09-19-session-local-subagent-migration.md
-2026-09-19-session-local-subagent-migration.md: fcdbb7830a12bca645b2a20c68178fff97d74626
-2026-09-19-session-local-subagent-migration.zh.md: bd6aaf5c434ec109cae2d3c68ddd29249debabf2
+2026-09-19-session-local-subagent-migration.md: a44b6cdfe37656fc112f06187ef0c884e8b2fae1
+2026-09-19-session-local-subagent-migration.zh.md: e1c790d4e19dbc0bab962592d9ff14b2e94fbdb0
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
index fcdbb7830a..a44b6cdfe3 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
@@ -12,7 +12,7 @@ Opening a historical parent requires discovery facts from its direct children. A
 
 Opening A discovers candidate B Sessions through headers, reads their own descriptors, and completes A's catalog. Historical child reads use the V0–V3 catalog; current child reads use native validation. These reads neither prepare B's own catalog nor publish B's successor. Opening B separately performs B's migration and catalog preparation. Frontend discovery retains its parent-catalog source. Unknown-mode rows remain browsable; `list_agents` continues to select only known continuable children.
 
-JSONL omits unreadable or unsupported headers from discovery. A child-body or descriptor-field failure produces a warning with the child path and retains the child's header identity. If the parent lacks a complete entry, migration appends `subagent/catalog-unknown`, projected as `mode: 'unknown'` alongside healthy siblings. Existing complete entries remain authoritative. Cancellation and source-consistency failures still stop the operation. Inspected child revisions, including failed decodes, are rechecked before reuse and publication so repairs cannot silently reuse stale evidence. Released predecessors remain byte-identical.
+JSONL omits unreadable or unsupported headers from discovery. A child-body or descriptor-field failure produces a warning with the child path and retains the child's header identity. If the parent lacks a complete entry, migration appends `subagent/catalog`, projected as `mode: 'unknown'` alongside healthy siblings. Existing complete entries remain authoritative. Cancellation and source-consistency failures still stop the operation. Inspected child revisions, including failed decodes, are rechecked before reuse and publication so repairs cannot silently reuse stale evidence. Released predecessors remain byte-identical.
 
 This partially supersedes child-failure propagation in [released migrations](../architecture/2026-08-31-released-session-format-migrations.md) and [incomplete child evidence](2026-09-19-v3-incomplete-child-catalog-evidence.md). Their format conversion, descriptor cardinality, conflict validation, and immutable publication rules remain active.
 
@@ -28,6 +28,6 @@ This partially supersedes child-failure propagation in [released migrations](../
 
 ## Consequences
 
-Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. Unknown entries are not automatically rewritten after publication. Opening a child retries its log and determines browsing capabilities from its actual descriptor, or reports the child-local error. A separate required-on-read event preserves the finalized V4 catalog payload while making unknown membership durable; older readers that lack this event refuse the log.
+Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. Unknown entries are not automatically rewritten after publication. Opening a child retries its log and determines browsing capabilities from its actual descriptor, or reports the child-local error. Catalog mode adds `unknown` without changing existing alternatives or the V4 header. The persistence checker admits this scoped extension; older readers may reject records using the new mode.
 
 Raw and compressed tests cover catalog completion, child-local errors, source changes and repairs, unchanged child generations, and deferred child-catalog preparation. The shipped Web migration snapshot checks the parent catalog with a corrupt sibling, then opens the child independently. Its additional historical child raises the corpus budget from ten to eleven roles; the guard rejects a twelfth role.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
index bd6aaf5c43..e1c790d4e1 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 打开 A 时通过 header 发现候选 B Session，读取其自身 descriptor，并补齐 A 的 catalog。历史子日志使用 V0–V3 catalog 读取，当前子日志使用原生校验。这些读取不准备 B 自己的 catalog，也不发布 B 的后继。单独打开 B 时才执行 B 的迁移与目录准备。前端发现继续读取父 catalog。模式未知的条目仍可浏览；`list_agents` 继续只选择已知可继续的子会话。
 
-JSONL 在发现时跳过不可读或不支持的 header。子正文或 descriptor 字段失败会产生带子路径的警告，并保留该子的 header 身份。父目录没有完整条目时，迁移追加 `subagent/catalog-unknown`，与健康兄弟项一同投影为目录条目，其模式为 `mode: 'unknown'`。已有完整条目仍具有权威性。取消与来源一致性失败仍中止操作。复用和发布前会重新检查已检查子日志的修订，包括解码失败的日志，使修复不能静默复用旧证据。已发布前驱保持逐字节不变。
+JSONL 在发现时跳过不可读或不支持的 header。子正文或 descriptor 字段失败会产生带子路径的警告，并保留该子的 header 身份。父目录没有完整条目时，迁移追加 `subagent/catalog`，与健康兄弟项一同投影为目录条目，其模式为 `mode: 'unknown'`。已有完整条目仍具有权威性。取消与来源一致性失败仍中止操作。复用和发布前会重新检查已检查子日志的修订，包括解码失败的日志，使修复不能静默复用旧证据。已发布前驱保持逐字节不变。
 
 本决策部分取代[已发布迁移](../architecture/2026-08-31-released-session-format-migrations.zh.md)和[不完整子证据](2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)中的子错误传播规则。其格式转换、descriptor 数量、冲突校验和不可变发布规则仍有效。
 
@@ -28,6 +28,6 @@ JSONL 在发现时跳过不可读或不支持的 header。子正文或 descripto
 
 ## 后果
 
-首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。发布后不自动重写未知条目。打开子会话会重试其日志，根据实际 descriptor 确定浏览能力，或报告该子会话的错误。独立的必读事件保留已定稿 V4 目录载荷，同时持久记录未知成员；不认识该事件的旧读取器拒绝日志。
+首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。发布后不自动重写未知条目。打开子会话会重试其日志，根据实际 descriptor 确定浏览能力，或报告该子会话的错误。Catalog mode 增加 `unknown`，既有分支和 V4 header 保持不变。持久化检查允许这项限定扩展；旧读取器可能拒绝使用新模式的记录。
 
 原始和压缩测试覆盖目录补齐、子会话错误隔离、来源变化与修复、子代际不变和延后的子目录准备。随产品 Web 迁移快照在损坏兄弟存在时检查父目录，再独立打开子会话。额外的历史子角色使语料预算由十个增加到十一个；守卫拒绝第十二个角色。
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
index 94e92c9bac..30c4c0961b 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.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/process/2026-09-11-persistence-type-history.md
-2026-09-11-persistence-type-history.md: c7cddea5ecc479a64ad5f24f5447e869779b7f9e
-2026-09-11-persistence-type-history.zh.md: 001ce197c4cd12dc64a5e2bd710e39cb2b61f23a
+2026-09-11-persistence-type-history.md: a5c50a871ebdb583c7e955944b03f4e082c69fe2
+2026-09-11-persistence-type-history.zh.md: 8fc42ccd9964d7eab254da8bb8c40ae055ff1152
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
index c7cddea5ec..a5c50a871e 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
@@ -14,7 +14,7 @@ One normalized type model supplies the readable persistence catalog, the complet
 
 The dedicated [persistence-change records](../../../../docs/persistence-changes/README.md) bind acknowledgement to the after digest of each affected root. A generated companion stores complete after schemas. The initial record covers all roots; later records name each root's predecessor. A predecessor's after schema supplies the next before schema. Verification rejects ambiguous history and requires current source to match the terminal recorded state without consulting Git history or remote services.
 
-Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped [source-attribution policy](2026-09-17-persistence-schema-review.md) also permits qualified new producer kinds when both saved schemas opt in. Other structural changes require a version-bump decision that includes an increasing header version in that record. The [format-version procedure](../../../../docs/cookbook/adding-a-session-format-version.md) continues to own adjacent migration work. Every structural difference requires an explicit record, including additions allowed within the same version.
+Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped [source-attribution policy](2026-09-17-persistence-schema-review.md) also permits qualified new producer kinds when both saved schemas opt in. The [catalog exception](../../../../docs/persistence-changes/README.md#compatibility-rules) admits unknown child mode with unchanged identity fields and records the older-reader limitation. Other structural changes require a version-bump decision that includes an increasing header version in that record. The [format-version procedure](../../../../docs/cookbook/adding-a-session-format-version.md) continues to own adjacent migration work. Every structural difference requires an explicit record, including additions allowed within the same version.
 
 The new document kind preserves the compatibility reasoning and evidence for a historical type transition. Agent Notes retain mechanism-level decisions; they do not become a growing inventory of individual acknowledgements. Machine declarations remain identical across the bilingual pair and are parsed once.
 
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
index 001ce197c4..8fc42ccd99 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 专用的[持久化变更记录](../../../../docs/persistence-changes/README.zh.md)将确认绑定到每个受影响根的变更后摘要。生成的伴随文件保存完整的变更后 schema。初始记录覆盖所有根；后续记录为每个根指定前驱。前驱的变更后 schema 提供下一次的变更前 schema。验证拒绝有歧义的历史，并要求当前源码匹配最终记录状态，无需查询 Git 历史或远端服务。
 
-自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的[消息源归属策略](2026-09-17-persistence-schema-review.zh.md)也允许添加符合条件的生产者 kind。其他结构变更需要升版本决策，并在该记录中包含递增的头部版本。[格式版本流程](../../../../docs/cookbook/adding-a-session-format-version.zh.md)继续负责相邻迁移工作。每个结构差异都需要显式记录，包括允许保持同一版本的新增。
+自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的[消息源归属策略](2026-09-17-persistence-schema-review.zh.md)也允许添加符合条件的生产者 kind。[Catalog 例外](../../../../docs/persistence-changes/README.zh.md#compatibility-rules) 允许增加身份字段不变的未知子模式，并记录旧读取器限制。其他结构变更需要升版本决策，并在该记录中包含递增的头部版本。[格式版本流程](../../../../docs/cookbook/adding-a-session-format-version.zh.md)继续负责相邻迁移工作。每个结构差异都需要显式记录，包括允许保持同一版本的新增。
 
 新文档类型保留历史类型转换的兼容性说明和证据。Agent Note 保留机制层面的决策，不积累单次确认清单。双语对中的机器声明保持相同，且只解析一次。
 
diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts
index 1f1b81ed90..530a0f3ef9 100644
--- a/apps/web/tests/preset-migration.snapshot.ts
+++ b/apps/web/tests/preset-migration.snapshot.ts
@@ -108,7 +108,7 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
           && (row['data'] as { agentPreset: string }).agentPreset === 'code'
           ? { ...row, data: { agentPreset: 'ptc' } }
           : row),
-        { type: 'subagent/catalog-unknown', seq: rows.length, time: rows.at(-1)?.['time'], data: {
+        { type: 'subagent/catalog', seq: rows.length, time: rows.at(-1)?.['time'], data: {
           version: 0, childId: brokenId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'unknown',
         } },
         { type: 'subagent/catalog', seq: rows.length + 1, time: rows.at(-1)?.['time'], data: {
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index af54d7738c..43982e1667 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: 2c64c088a70a9a80430c2af377f09ddaedc356dc
-persistence-catalog.zh.md: 9ea121c475aed4f12c164aeae1d6f26cb1679ede
+persistence-catalog.md: 0733c6880cf65e445b35c2dea0589b7ce93a96b8
+persistence-catalog.zh.md: c4f4870fb8d712b43502579ecfd7adae8d74a535
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 2c64c088a7..0733c6880c 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -57,8 +57,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover
 | `event:session/title-llm-request` | event | `fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d) |
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
-| `event:subagent/catalog` | event | `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871) |
-| `event:subagent/catalog-unknown` | event | `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21` | [`{ type: "subagent/catalog-unknown" }`](#persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21) |
+| `event:subagent/catalog` | event | `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -895,27 +894,13 @@ Source: [`packages/core/session/src/types.ts:299`](../packages/core/session/src/
 
 ```ts persistence-catalog
 /**
- * A direct child's complete discovery fact.
+ * A direct child's identity and available discovery fields.
  * @param data - versioned parent-owned catalog entry.
  */
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-Source: [`packages/subagent/subagent/src/catalog.ts:48`](../packages/subagent/subagent/src/catalog.ts)
-
-<a id="subagentcatalog-unknown--log-only"></a>
-
-#### `subagent/catalog-unknown` — log-only
-
-```ts persistence-catalog
-/**
- * A historical child's header identity when its descriptor cannot establish a mode.
- * @param data - child identity retained for discovery and later history reads.
- */
-'subagent/catalog-unknown': UnknownCatalogEvent
-```
-
-Source: [`packages/subagent/subagent/src/catalog.ts:53`](../packages/subagent/subagent/src/catalog.ts)
+Source: [`packages/subagent/subagent/src/catalog.ts:41`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -2490,14 +2475,6 @@ SHA-256: `44c8c77aa9aa100b0d74d2deee85474b29faa6eee0ac0f662f7abe9931ddd7f2`
 
 `"subagent/catalog"`
 
-<a id="persistence-type-sha256-d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89"></a>
-
-### `"subagent/catalog-unknown"`
-
-SHA-256: `d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89`
-
-`"subagent/catalog-unknown"`
-
 <a id="persistence-type-sha256-5ebce1317eacd2c148456627a09668e927ee15c204f0643f5ea76b46b54a2647"></a>
 
 ### `"subagent/descriptor"`
@@ -4578,7 +4555,7 @@ One of:
 - [`{ type: "finish" }`](#persistence-type-sha256-a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1)
 - [`{ type: "usage" }`](#persistence-type-sha256-f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515)
 
-<a id="persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e"></a>
+<a id="persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce"></a>
 
 <a id="persistence-type-packagessubagentsubagentsrccatalogtssubagentcatalogevent"></a>
 
@@ -4586,7 +4563,7 @@ One of:
 
 ### `SubagentCatalogEvent`
 
-SHA-256: `3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e`
+SHA-256: `30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce`
 
 Sources: [`packages/subagent/subagent/src/catalog.ts:24`](../packages/subagent/subagent/src/catalog.ts)
 
@@ -4594,6 +4571,7 @@ One of:
 
 - [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd)
 - [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca)
 
 <a id="persistence-type-sha256-86d1d0e9cfebb240421187e3dc37fb71cc38a1501885cf32f8f9adef7b0a2bde"></a>
 
@@ -5118,26 +5096,6 @@ Sources: [`packages/core/session/src/types.ts:232`](../packages/core/session/src
 | `interrupted` | not declared | none | [`{ kind: "interrupted" }`](#persistence-type-sha256-56b7c047694875a843ba020dfea3c8380d54ae4ff88ab349e72004dc21e07c23) |
 | `max-tokens` | not declared | none | [`{ kind: "max-tokens" }`](#persistence-type-sha256-ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7) |
 
-<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
-
-<a id="persistence-type-packagessubagentsubagentsrccatalogtsunknowncatalogevent"></a>
-
-<a id="persistence-type-unknowncatalogevent"></a>
-
-### `UnknownCatalogEvent`
-
-SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
-
-Sources: [`packages/subagent/subagent/src/catalog.ts:34`](../packages/subagent/subagent/src/catalog.ts)
-
-| Property | Presence | Type |
-|---|---|---|
-| `childCreatedAt` | required | `number` |
-| `childId` | required | `string` |
-| `label` | optional | `string` |
-| `mode` | required | `"unknown"` |
-| `version` | required | `0` |
-
 <a id="persistence-type-sha256-64ea5653002834c44f29bea4620e9c42aeb6024ae5b1d58d69f95158006b2586"></a>
 
 <a id="persistence-type-packagesllmllmsrcmessagetsusermessage"></a>
@@ -5677,6 +5635,20 @@ SHA-256: `5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694`
 | `mode` | required | `"one-shot"` |
 | `version` | required | `0` |
 
+<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
+
+| Property | Presence | Type |
+|---|---|---|
+| `childCreatedAt` | required | `number` |
+| `childId` | required | `string` |
+| `label` | optional | `string` |
+| `mode` | required | `"unknown"` |
+| `version` | required | `0` |
+
 <a id="persistence-type-sha256-a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735"></a>
 
 ### `{ code, name, reason? }`
@@ -8272,38 +8244,22 @@ SHA-256: `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986`
 | `time` | required | `number` |
 | `type` | required | `"step/start"` |
 
-<a id="persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871"></a>
+<a id="persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"></a>
 
 <a id="persistence-type-eventsubagentcatalog"></a>
 
 ### `{ type: "subagent/catalog" }`
 
-SHA-256: `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871`
+SHA-256: `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3`
 
 | Property | Presence | Type |
 |---|---|---|
-| `data` | required | [`SubagentCatalogEvent`](#persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e) |
+| `data` | required | [`SubagentCatalogEvent`](#persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce) |
 | `ignorable` | optional | `true` |
 | `seq` | required | `number` |
 | `time` | required | `number` |
 | `type` | required | `"subagent/catalog"` |
 
-<a id="persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"></a>
-
-<a id="persistence-type-eventsubagentcatalog-unknown"></a>
-
-### `{ type: "subagent/catalog-unknown" }`
-
-SHA-256: `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21`
-
-| Property | Presence | Type |
-|---|---|---|
-| `data` | required | [`UnknownCatalogEvent`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca) |
-| `ignorable` | optional | `true` |
-| `seq` | required | `number` |
-| `time` | required | `number` |
-| `type` | required | `"subagent/catalog-unknown"` |
-
 <a id="persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5"></a>
 
 <a id="persistence-type-eventsubagentdescriptor"></a>
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 9ea121c475..c4f4870fb8 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -59,8 +59,7 @@
 | `event:session/title-llm-request` | event | `fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d) |
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
-| `event:subagent/catalog` | event | `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871) |
-| `event:subagent/catalog-unknown` | event | `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21` | [`{ type: "subagent/catalog-unknown" }`](#persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21) |
+| `event:subagent/catalog` | event | `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -897,27 +896,13 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 ```ts persistence-catalog
 /**
- * A direct child's complete discovery fact.
+ * A direct child's identity and available discovery fields.
  * @param data - versioned parent-owned catalog entry.
  */
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-来源：[`packages/subagent/subagent/src/catalog.ts:48`](../packages/subagent/subagent/src/catalog.ts)
-
-<a id="subagentcatalog-unknown--log-only"></a>
-
-#### `subagent/catalog-unknown` — log-only
-
-```ts persistence-catalog
-/**
- * A historical child's header identity when its descriptor cannot establish a mode.
- * @param data - child identity retained for discovery and later history reads.
- */
-'subagent/catalog-unknown': UnknownCatalogEvent
-```
-
-来源：[`packages/subagent/subagent/src/catalog.ts:53`](../packages/subagent/subagent/src/catalog.ts)
+来源：[`packages/subagent/subagent/src/catalog.ts:41`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -2492,14 +2477,6 @@ SHA-256: `44c8c77aa9aa100b0d74d2deee85474b29faa6eee0ac0f662f7abe9931ddd7f2`
 
 `"subagent/catalog"`
 
-<a id="persistence-type-sha256-d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89"></a>
-
-### `"subagent/catalog-unknown"`
-
-SHA-256: `d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89`
-
-`"subagent/catalog-unknown"`
-
 <a id="persistence-type-sha256-5ebce1317eacd2c148456627a09668e927ee15c204f0643f5ea76b46b54a2647"></a>
 
 ### `"subagent/descriptor"`
@@ -4580,7 +4557,7 @@ SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180`
 - [`{ type: "finish" }`](#persistence-type-sha256-a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1)
 - [`{ type: "usage" }`](#persistence-type-sha256-f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515)
 
-<a id="persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e"></a>
+<a id="persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce"></a>
 
 <a id="persistence-type-packagessubagentsubagentsrccatalogtssubagentcatalogevent"></a>
 
@@ -4588,7 +4565,7 @@ SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180`
 
 ### `SubagentCatalogEvent`
 
-SHA-256: `3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e`
+SHA-256: `30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce`
 
 来源：[`packages/subagent/subagent/src/catalog.ts:24`](../packages/subagent/subagent/src/catalog.ts)
 
@@ -4596,6 +4573,7 @@ SHA-256: `3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e`
 
 - [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd)
 - [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca)
 
 <a id="persistence-type-sha256-86d1d0e9cfebb240421187e3dc37fb71cc38a1501885cf32f8f9adef7b0a2bde"></a>
 
@@ -5120,26 +5098,6 @@ SHA-256: `f1687f982fa3d41ef29e159feed154ecd13af4dd209acaee16038f223f2e9402`
 | `interrupted` | 未声明 | 无 | [`{ kind: "interrupted" }`](#persistence-type-sha256-56b7c047694875a843ba020dfea3c8380d54ae4ff88ab349e72004dc21e07c23) |
 | `max-tokens` | 未声明 | 无 | [`{ kind: "max-tokens" }`](#persistence-type-sha256-ab7ec5f9eb2c6dfacca5da4c37cf7ba85d04172053ee6b1ebf1709ffcd99c1a7) |
 
-<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
-
-<a id="persistence-type-packagessubagentsubagentsrccatalogtsunknowncatalogevent"></a>
-
-<a id="persistence-type-unknowncatalogevent"></a>
-
-### `UnknownCatalogEvent`
-
-SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
-
-来源：[`packages/subagent/subagent/src/catalog.ts:34`](../packages/subagent/subagent/src/catalog.ts)
-
-| 属性 | 存在性 | 类型 |
-|---|---|---|
-| `childCreatedAt` | 必需 | `number` |
-| `childId` | 必需 | `string` |
-| `label` | 可选 | `string` |
-| `mode` | 必需 | `"unknown"` |
-| `version` | 必需 | `0` |
-
 <a id="persistence-type-sha256-64ea5653002834c44f29bea4620e9c42aeb6024ae5b1d58d69f95158006b2586"></a>
 
 <a id="persistence-type-packagesllmllmsrcmessagetsusermessage"></a>
@@ -5679,6 +5637,20 @@ SHA-256: `5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694`
 | `mode` | 必需 | `"one-shot"` |
 | `version` | 必需 | `0` |
 
+<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `childCreatedAt` | 必需 | `number` |
+| `childId` | 必需 | `string` |
+| `label` | 可选 | `string` |
+| `mode` | 必需 | `"unknown"` |
+| `version` | 必需 | `0` |
+
 <a id="persistence-type-sha256-a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735"></a>
 
 ### `{ code, name, reason? }`
@@ -8274,38 +8246,22 @@ SHA-256: `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986`
 | `time` | 必需 | `number` |
 | `type` | 必需 | `"step/start"` |
 
-<a id="persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871"></a>
+<a id="persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"></a>
 
 <a id="persistence-type-eventsubagentcatalog"></a>
 
 ### `{ type: "subagent/catalog" }`
 
-SHA-256: `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871`
+SHA-256: `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3`
 
 | 属性 | 存在性 | 类型 |
 |---|---|---|
-| `data` | 必需 | [`SubagentCatalogEvent`](#persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e) |
+| `data` | 必需 | [`SubagentCatalogEvent`](#persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce) |
 | `ignorable` | 可选 | `true` |
 | `seq` | 必需 | `number` |
 | `time` | 必需 | `number` |
 | `type` | 必需 | `"subagent/catalog"` |
 
-<a id="persistence-type-sha256-d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"></a>
-
-<a id="persistence-type-eventsubagentcatalog-unknown"></a>
-
-### `{ type: "subagent/catalog-unknown" }`
-
-SHA-256: `d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21`
-
-| 属性 | 存在性 | 类型 |
-|---|---|---|
-| `data` | 必需 | [`UnknownCatalogEvent`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca) |
-| `ignorable` | 可选 | `true` |
-| `seq` | 必需 | `number` |
-| `time` | 必需 | `number` |
-| `type` | 必需 | `"subagent/catalog-unknown"` |
-
 <a id="persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5"></a>
 
 <a id="persistence-type-eventsubagentdescriptor"></a>
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml b/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
index cfcd73af1d..d393e07ce1 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
+++ b/docs/persistence-changes/2026-09-20-unknown-child-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-changes/2026-09-20-unknown-child-catalog.md
-2026-09-20-unknown-child-catalog.md: 80de55e616d63730bc1d0bbc0ffa43923f833923
-2026-09-20-unknown-child-catalog.zh.md: 1ee8a04e7318013ec27a7c736fadd540a96cfc0d
+2026-09-20-unknown-child-catalog.md: 58e8a8ffedb7b3b913c9e04590ce5bbabd148ba6
+2026-09-20-unknown-child-catalog.zh.md: 488899ecadcdc93910927c80b22b8fcf0d319224
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
index 80de55e616..58e8a8ffed 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
@@ -9,7 +9,7 @@ English | [中文](2026-09-20-unknown-child-catalog.zh.md)
 
 ## Summary
 
-Add subagent/catalog-unknown to retain historical direct-child header identity when a descriptor cannot establish the mode.
+Retain unreadable historical children in subagent/catalog with unknown mode.
 
 ## Table of Contents
 
@@ -26,21 +26,21 @@ schemaVersion: 1
 id: 2026-09-20-unknown-child-catalog
 baseline: false
 changes:
-  - root: "event:subagent/catalog-unknown"
-    previous: null
-    after: "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"
+  - root: "event:subagent/catalog"
+    previous: "2026-09-11-initial"
+    after: "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"
     decision: same-version
 ```
 
 <a id="compatibility"></a>
 ## Compatibility
 
-This adds an ordinary required-on-read event without changing the finalized subagent/catalog payload, Session header, or envelope. Existing logs remain valid. Older readers that do not know the new event refuse logs containing it; current readers project it into the existing catalog with unknown mode and keep continuation requests restricted to supported child descriptors.
+The catalog adds one unknown-mode alternative with the same identity and optional label fields as one-shot mode. Existing alternatives and the V4 header remain unchanged. New readers accept old records; older readers may reject records with unknown mode. The persistence classifier has a scoped catalog exception for this addition, while other union additions and modifications remain strict. Unknown membership grants no continuation capability.
 
 <a id="verification"></a>
 ## Verification
 
-pnpm exec vitest run packages/session/session-format-v3-to-v4/tests/validation.spec.ts packages/subagent/subagent/tests/catalog.spec.ts: 16 tests passed, covering unknown identity restoration, malformed payload rejection, duplicate child rejection, and shared catalog projection.
+Catalog migration, restoration, projection, and Web regressions cover retained unknown membership and child-local errors. Persistence classifier tests accept the exact catalog extension and reject altered existing fields, other new modes, extra unknown fields, removals, and unrelated union additions.
 
 <a id="dev-note"></a>
 ## Dev Note
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
index 7fb3b867fa..ce4dd23ac3 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
@@ -2,11 +2,11 @@
   "formatVersion": 2,
   "roots": [
     {
-      "key": "event:subagent/catalog-unknown",
+      "key": "event:subagent/catalog",
       "kind": "event",
-      "event": "subagent/catalog-unknown",
+      "event": "subagent/catalog",
       "surface": false,
-      "digest": "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21",
+      "digest": "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3",
       "schema": {
         "root": 0,
         "nodes": [
@@ -20,54 +20,62 @@
               },
               {
                 "name": "ignorable",
-                "type": 6,
+                "type": 11,
                 "optional": true
               },
               {
                 "name": "seq",
-                "type": 2,
+                "type": 3,
                 "optional": false
               },
               {
                 "name": "time",
-                "type": 2,
+                "type": 3,
                 "optional": false
               },
               {
                 "name": "type",
-                "type": 7,
+                "type": 12,
                 "optional": false
               }
             ],
             "indices": []
           },
+          {
+            "kind": "union",
+            "types": [
+              2,
+              7,
+              9
+            ]
+          },
           {
             "kind": "object",
             "properties": [
               {
                 "name": "childCreatedAt",
-                "type": 2,
+                "type": 3,
                 "optional": false
               },
               {
                 "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": true
-              },
-              {
-                "name": "mode",
                 "type": 4,
                 "optional": false
               },
               {
-                "name": "version",
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
                 "type": 5,
                 "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
               }
             ],
             "indices": []
@@ -88,13 +96,83 @@
             "kind": "literal",
             "value": 0
           },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 8,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
           {
             "kind": "literal",
             "value": true
           },
           {
             "kind": "literal",
-            "value": "subagent/catalog-unknown"
+            "value": "subagent/catalog"
           }
         ]
       }
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
index 1ee8a04e73..488899ecad 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
@@ -9,7 +9,7 @@ kind: persistence-change
 
 ## 概述
 
-新增 subagent/catalog-unknown，在 descriptor 无法确定模式时保留历史直属子会话的 header 身份。
+在 subagent/catalog 中使用 unknown 模式保留不可读的历史子会话。
 
 ## 目录
 
@@ -26,21 +26,21 @@ schemaVersion: 1
 id: 2026-09-20-unknown-child-catalog
 baseline: false
 changes:
-  - root: "event:subagent/catalog-unknown"
-    previous: null
-    after: "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21"
+  - root: "event:subagent/catalog"
+    previous: "2026-09-11-initial"
+    after: "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"
     decision: same-version
 ```
 
 <a id="compatibility"></a>
 ## 兼容性
 
-新增普通的必读事件，不修改已定稿的 subagent/catalog 载荷、Session header 或事件信封。已有日志仍有效。不认识新事件的旧读取器拒绝包含它的日志；当前读取器将其投影为现有目录中的未知模式项，继续执行请求仍受支持的子 descriptor 约束。
+Catalog 增加一个 unknown 模式分支，身份与可选 label 字段和 one-shot 模式相同。已有分支及 V4 header 保持不变。新读取器接受旧记录；旧读取器可能拒绝 unknown 模式记录。持久化分类器仅为该 catalog 扩展设置限定例外，其他联合类型新增与修改仍严格检查。未知成员关系不授予继续执行能力。
 
 <a id="verification"></a>
 ## 验证
 
-pnpm exec vitest run packages/session/session-format-v3-to-v4/tests/validation.spec.ts packages/subagent/subagent/tests/catalog.spec.ts：16 个测试通过，覆盖未知身份恢复、畸形载荷拒绝、重复 child 拒绝及共享目录投影。
+Catalog 迁移、恢复、投影和 Web 回归覆盖未知成员保留与子会话局部报错。持久化分类器测试接受此 catalog 扩展，并拒绝已有字段修改、其他新增模式、未知分支额外字段、删除及无关联合类型新增。
 
 <a id="dev-note"></a>
 ## 开发备注
diff --git a/docs/persistence-changes/README.i18n.yaml b/docs/persistence-changes/README.i18n.yaml
index 830e77b05e..ea39a60513 100644
--- a/docs/persistence-changes/README.i18n.yaml
+++ b/docs/persistence-changes/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 docs/persistence-changes/README.md
-README.md: 3fd95e48548fdb9c1d04330c2925096d072850d1
-README.zh.md: f4ab3b3d22b1aa2f7f5923e84fd4effc339874db
+README.md: 1e7c7b7aec8ecf6687b37f36544dccb4c8e4c4f5
+README.zh.md: d6a315acb42a82a926fc323370b52c1a1b61065e
diff --git a/docs/persistence-changes/README.md b/docs/persistence-changes/README.md
index 3fd95e4854..1e7c7b7aec 100644
--- a/docs/persistence-changes/README.md
+++ b/docs/persistence-changes/README.md
@@ -53,12 +53,15 @@ Every detected structural change requires an acknowledgement. Record creation an
 | Add an optional event-body property, including its complete subtree | `same-version` |
 | Make a required event-body property optional | `same-version` |
 | Add an ordinary event type | `same-version` |
+| Add `unknown` mode to `subagent/catalog` using the one-shot fields, while preserving existing alternatives | `same-version` |
 | Add an explicitly qualified attribution kind to a user/developer source slot whose before and after schemas carry the same supported policy | `same-version` |
 | Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | `version-bump` |
 | Change the Session header or event envelope | `version-bump` |
 
 A finalized checkpoint protects the accepted baseline without replacing these compatibility rules. At V4, optional additions, ordinary events, and qualified attribution additions can receive new same-version records. Breaking differences require a higher writer version and an acknowledgement containing its own header increase. The accepted V4 record cannot be updated to reuse its original 3→4 transition.
 
+The catalog exception retains a historical child's identity when its descriptor is unavailable. It admits only an `unknown` alternative with the same fields as the one-shot alternative; existing alternatives still receive ordinary comparison. It does not permit other mode additions, removals, header changes, or arbitrary union extensions. Existing logs remain readable by the updated reader; older readers may reject the new mode. The [acknowledgement](2026-09-20-unknown-child-catalog.md) records this forward-read limitation.
+
 The extractor accepts an explicit `@persistenceSource` binding for a core-owned source property on a literal user or developer role; it does not infer a binding from an unannotated type. A producer qualifies its `MessageSourceMap` entry with `@persistenceAttribution`. Qualification promises that an unknown kind and its JSON metadata survive reading without the producer, and that the kind imposes no validation, replay, or authority requirement. A producer may inspect its own kind to resume duplicate suppression; other readers must preserve and derive the recorded messages without that projection. The recorded schema retains the binding, policy version, literal `kind` discriminator, preservation promise, and qualified kind set. Inventory format 2 stores those promises; extraction without a bound policy retains format 1. Session format versions are independent. Both compared snapshots must carry compatible policy state. Existing kind groups still receive ordinary structural comparison; removals, unmarked additions, policy changes, and unrelated breaking changes remain strict. Multiple context-form alternatives with the same wire kind form one group.
 
 A same-version explanation states why old records can omit the addition and why older readers can ignore it without changing replay. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
diff --git a/docs/persistence-changes/README.zh.md b/docs/persistence-changes/README.zh.md
index f4ab3b3d22..d6a315acb4 100644
--- a/docs/persistence-changes/README.zh.md
+++ b/docs/persistence-changes/README.zh.md
@@ -53,12 +53,15 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
 | 添加可选事件体属性，包括其完整子树 | `same-version` |
 | 将必选事件体属性改为可选 | `same-version` |
 | 添加普通事件类型 | `same-version` |
+| 为 `subagent/catalog` 增加使用 one-shot 字段的 `unknown` 模式，并保留既有分支 | `same-version` |
 | 在前后 schema 均带有相同受支持策略的 user/developer 消息源字段中，添加显式声明为归属信息的 kind | `same-version` |
 | 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | `version-bump` |
 | 更改会话头或事件封装 | `version-bump` |
 
 定稿检查点保护已接受基线，不替换这些兼容性规则。在 V4 中，可选新增、普通事件及符合条件的归属 kind 新增可以使用新的同版本记录。破坏性差异要求更高的写入器版本，以及包含自身头版本递增的确认记录。不能更新已接受 V4 记录以复用其原有 3→4 转换。
 
+Catalog 例外在 descriptor 不可用时保留历史子会话身份。它仅允许增加字段与 one-shot 分支相同的 `unknown` 分支；已有分支仍执行常规比较。它不允许其他模式新增、删除、header 变更或任意联合类型扩展。新版读取器仍可读取已有日志；旧版读取器可能拒绝新模式。[确认记录](2026-09-20-unknown-child-catalog.zh.md) 说明这一向前读取限制。
+
 提取器接受核心拥有的 source 属性上针对 user 或 developer 字面量角色的显式 `@persistenceSource` 绑定，不会从未标记类型中推断绑定。生产者用 `@persistenceAttribution` 标记其 `MessageSourceMap` 成员。该标记承诺：读取器无需生产者即可保留未知 kind 及其 JSON 元数据，且该 kind 不引入校验、回放或权限要求。生产者可以检查自身 kind 来恢复去重状态；其他读取器必须无需该投影也能保留并派生已记录的消息。记录的 schema 保存绑定、策略版本、字面量 `kind` 判别字段、保留承诺及符合条件的 kind 集合。Inventory format 2 保存这些承诺；没有绑定策略的提取仍使用 format 1。Session 格式版本独立于此。比较双方的快照必须带有兼容的策略状态。已有 kind 分组仍进行常规结构比较；删除、未标记的添加、策略更改及无关破坏性变更继续采用严格规则。同一 wire kind 的多个上下文形式分支归为一组。
 
 同版本说明须解释旧记录为何可以缺少新增内容，以及旧读取器为何可以忽略它而不改变回放。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
diff --git a/docs/persistence-changes/historical-formats/README.i18n.yaml b/docs/persistence-changes/historical-formats/README.i18n.yaml
index 93eb20d961..f34e60f4e7 100644
--- a/docs/persistence-changes/historical-formats/README.i18n.yaml
+++ b/docs/persistence-changes/historical-formats/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 docs/persistence-changes/historical-formats/README.md
-README.md: 386b0bd9091cbd509843bd6464c8a95650accb99
-README.zh.md: e93e8033daa639eee3a5035efc2df8ef123f563e
+README.md: f4e721bbef9d442021226c573280edc193792662
+README.zh.md: be4b7c86b68fa682e7f8275f85a2548f39f30df9
diff --git a/docs/persistence-changes/historical-formats/README.md b/docs/persistence-changes/historical-formats/README.md
index 386b0bd909..f4e721bbef 100644
--- a/docs/persistence-changes/historical-formats/README.md
+++ b/docs/persistence-changes/historical-formats/README.md
@@ -32,7 +32,7 @@ The index is generated from validated snapshots and the current writer constant.
 | 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 63 / 587 |
+| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 585 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-changes/historical-formats/README.zh.md b/docs/persistence-changes/historical-formats/README.zh.md
index e93e8033da..be4b7c86b6 100644
--- a/docs/persistence-changes/historical-formats/README.zh.md
+++ b/docs/persistence-changes/historical-formats/README.zh.md
@@ -32,7 +32,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式
 | 1 | PR #3349 | [V1](v1.zh.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.zh.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.zh.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 63 / 587 |
+| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 62 / 585 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-schema.json b/docs/persistence-schema.json
index ba5f5dbb0b..7456c002c0 100644
--- a/docs/persistence-schema.json
+++ b/docs/persistence-schema.json
@@ -14850,7 +14850,7 @@
       "kind": "event",
       "event": "subagent/catalog",
       "surface": false,
-      "digest": "ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871",
+      "digest": "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3",
       "schema": {
         "root": 0,
         "nodes": [
@@ -14864,7 +14864,7 @@
               },
               {
                 "name": "ignorable",
-                "type": 9,
+                "type": 11,
                 "optional": true
               },
               {
@@ -14879,7 +14879,7 @@
               },
               {
                 "name": "type",
-                "type": 10,
+                "type": 12,
                 "optional": false
               }
             ],
@@ -14889,7 +14889,8 @@
             "kind": "union",
             "types": [
               2,
-              7
+              7,
+              9
             ]
           },
           {
@@ -14908,7 +14909,7 @@
               {
                 "name": "label",
                 "type": 4,
-                "optional": false
+                "optional": true
               },
               {
                 "name": "mode",
@@ -14931,139 +14932,6 @@
             "kind": "primitive",
             "type": "string"
           },
-          {
-            "kind": "literal",
-            "value": "continuable"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 8,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "one-shot"
-          },
-          {
-            "kind": "literal",
-            "value": true
-          },
-          {
-            "kind": "literal",
-            "value": "subagent/catalog"
-          }
-        ]
-      }
-    },
-    {
-      "key": "event:subagent/catalog-unknown",
-      "kind": "event",
-      "event": "subagent/catalog-unknown",
-      "surface": false,
-      "digest": "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "data",
-                "type": 1,
-                "optional": false
-              },
-              {
-                "name": "ignorable",
-                "type": 6,
-                "optional": true
-              },
-              {
-                "name": "seq",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "time",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "type",
-                "type": 7,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 5,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
           {
             "kind": "literal",
             "value": "unknown"
@@ -15072,13 +14940,83 @@
             "kind": "literal",
             "value": 0
           },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 8,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
           {
             "kind": "literal",
             "value": true
           },
           {
             "kind": "literal",
-            "value": "subagent/catalog-unknown"
+            "value": "subagent/catalog"
           }
         ]
       }
@@ -33635,6 +33573,145 @@
         "packages/core/tools/src/types.ts:11"
       ]
     },
+    {
+      "digest": "30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "union",
+            "types": [
+              1,
+              6,
+              8
+            ]
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 7,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 9,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          }
+        ]
+      },
+      "names": [
+        "packages/subagent/subagent/src/catalog.ts#SubagentCatalogEvent"
+      ],
+      "sources": [
+        "packages/subagent/subagent/src/catalog.ts:24"
+      ]
+    },
     {
       "digest": "30d5a537b296685770b1241c4b4bbde19d5a31ff81aa23df73fab5e90b8fc65f",
       "schema": {
@@ -35345,109 +35422,6 @@
         "packages/feedback/message-feedback/src/types.ts:17"
       ]
     },
-    {
-      "digest": "3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "union",
-            "types": [
-              1,
-              6
-            ]
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "mode",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 5,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
-          {
-            "kind": "literal",
-            "value": "continuable"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 7,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 5,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "one-shot"
-          }
-        ]
-      },
-      "names": [
-        "packages/subagent/subagent/src/catalog.ts#SubagentCatalogEvent"
-      ],
-      "sources": [
-        "packages/subagent/subagent/src/catalog.ts:24"
-      ]
-    },
     {
       "digest": "3b04790e08b35241ffa0d38f6d7e4f8788aa921341f6c0d7574a329397c59408",
       "schema": {
@@ -44281,6 +44255,180 @@
         "packages/workflow/workflow/src/types.ts:13"
       ]
     },
+    {
+      "digest": "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 11,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 12,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "union",
+            "types": [
+              2,
+              7,
+              9
+            ]
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 8,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog"
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "4e011753f8263f436efaabfbb3b4db53a98fc55342c5ded2daf7208b217be159",
       "schema": {
@@ -70277,144 +70425,6 @@
       "names": [],
       "sources": []
     },
-    {
-      "digest": "ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "data",
-                "type": 1,
-                "optional": false
-              },
-              {
-                "name": "ignorable",
-                "type": 9,
-                "optional": true
-              },
-              {
-                "name": "seq",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "time",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "type",
-                "type": 10,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "union",
-            "types": [
-              2,
-              7
-            ]
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "mode",
-                "type": 5,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
-          {
-            "kind": "literal",
-            "value": "continuable"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 8,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "one-shot"
-          },
-          {
-            "kind": "literal",
-            "value": true
-          },
-          {
-            "kind": "literal",
-            "value": "subagent/catalog"
-          }
-        ]
-      },
-      "names": [],
-      "sources": []
-    },
     {
       "digest": "ae63d9d1080ed8945031594d93f8d96651d7101b848719cc3e1475875cd3d649",
       "schema": {
@@ -73643,12 +73653,8 @@
           }
         ]
       },
-      "names": [
-        "packages/subagent/subagent/src/catalog.ts#UnknownCatalogEvent"
-      ],
-      "sources": [
-        "packages/subagent/subagent/src/catalog.ts:34"
-      ]
+      "names": [],
+      "sources": []
     },
     {
       "digest": "c8e6f48878cc2a2f0dc59682280d81f407943fb503f32c64bf9ff3d9393c3eff",
@@ -77131,102 +77137,6 @@
       "names": [],
       "sources": []
     },
-    {
-      "digest": "d21dd6c60a43d9cb0d93da371e482f66ffd55daa36544e80978a0e7b32737b21",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "data",
-                "type": 1,
-                "optional": false
-              },
-              {
-                "name": "ignorable",
-                "type": 6,
-                "optional": true
-              },
-              {
-                "name": "seq",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "time",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "type",
-                "type": 7,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 5,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
-          {
-            "kind": "literal",
-            "value": "unknown"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          },
-          {
-            "kind": "literal",
-            "value": true
-          },
-          {
-            "kind": "literal",
-            "value": "subagent/catalog-unknown"
-          }
-        ]
-      },
-      "names": [],
-      "sources": []
-    },
     {
       "digest": "d28765f87d6b6ab408e0b2f3e7e297791b004b806d8e302c49903ebae815feb2",
       "schema": {
@@ -77241,20 +77151,6 @@
       "names": [],
       "sources": []
     },
-    {
-      "digest": "d437ebdbc1839ffcf3f6fa201a003126ec63945186b0c0792f1db466bf8ebd89",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "literal",
-            "value": "subagent/catalog-unknown"
-          }
-        ]
-      },
-      "names": [],
-      "sources": []
-    },
     {
       "digest": "d4b739491689cc6bb13d07ffac1a32239875abda364c0d5edd8f74faf5e9c00d",
       "schema": {
diff --git a/packages/core/session/src/known-event-types.ts b/packages/core/session/src/known-event-types.ts
index 2679faecfb..adaca29255 100644
--- a/packages/core/session/src/known-event-types.ts
+++ b/packages/core/session/src/known-event-types.ts
@@ -58,7 +58,6 @@ export const KNOWN_SESSION_EVENT_TYPES: ReadonlySet<string> = new Set([
   'step/end',
   'step/start',
   'subagent/catalog',
-  'subagent/catalog-unknown',
   'subagent/descriptor',
   'subagent/model-selection-policy',
   'system/message',
diff --git a/packages/sdk/client/tests/sdk-client.spec.ts b/packages/sdk/client/tests/sdk-client.spec.ts
index 2015d47d2c..41aef742aa 100644
--- a/packages/sdk/client/tests/sdk-client.spec.ts
+++ b/packages/sdk/client/tests/sdk-client.spec.ts
@@ -647,7 +647,7 @@ describe('HarnessClient', () => {
     const inject = (method: string, params: Record<string, unknown>): void => {
       (client as unknown as { dispatchNotification(n: HarnessNotification): void }).dispatchNotification({ method, params })
     }
-    const unknownChild = { type: 'subagent/catalog-unknown', seq: 0, time: 1,
+    const unknownChild = { type: 'subagent/catalog', seq: 0, time: 1,
       data: { version: 0, childId: 'unreadable-child', childCreatedAt: 1, mode: 'unknown' } }
     inject('session.event', { sessionId: 'root', event: unknownChild })
     inject('subagent.started', { parentSessionId: 'root', childSessionId: 'child' })
diff --git a/packages/session/session-format-v3-to-v4/README.i18n.yaml b/packages/session/session-format-v3-to-v4/README.i18n.yaml
index c5b3413814..b4b64bdc40 100644
--- a/packages/session/session-format-v3-to-v4/README.i18n.yaml
+++ b/packages/session/session-format-v3-to-v4/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-format-v3-to-v4/README.md
-README.md: 6721d43e7653942b055443a2da99d7fca1d6fd57
-README.zh.md: 48b7e5cbd00a19a81730cbf1310e462196cd8ca1
+README.md: 1c558d34cc67fc94aafcaf23405b0b1f2a0efa85
+README.zh.md: 6c079269503d5e11a0bbb03e3460d5a5432fa9e5
diff --git a/packages/session/session-format-v3-to-v4/README.md b/packages/session/session-format-v3-to-v4/README.md
index 6721d43e76..1c558d34cc 100644
--- a/packages/session/session-format-v3-to-v4/README.md
+++ b/packages/session/session-format-v3-to-v4/README.md
@@ -148,9 +148,9 @@ There is no recursive source search. Captured request text, assistant replay sta
 | More than one own descriptor | Retain an existing parent entry without mode/label comparison; otherwise append unknown-mode membership. |
 | Existing own parent entry | Retain it and its extensions; require matching child creation time and mode/label from exactly one supported own descriptor, when available. |
 | Missing own parent entry with complete supported evidence | Append a version-0 catalog fact with child id, creation time, mode, and optional label. |
-| Missing own parent entry without complete evidence | Append `subagent/catalog-unknown` with header identity and unknown mode, without inventing a label. |
+| Missing own parent entry without complete evidence | Append `subagent/catalog` with header identity and unknown mode, without inventing a label. |
 
-Catalog version 0 requires string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable` or `one-shot`, and a string label for continuable mode; a present one-shot label must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments. `subagent/catalog-unknown` separately records version 0, child id, creation time, and `mode: 'unknown'`; both event types contribute to the same unique-child catalog. Existing `subagent/catalog` payloads retain their mode requirements.
+Catalog version 0 requires string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable`, `one-shot`, or `unknown`, and a string label for continuable mode; a present label in any mode must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments. Unknown-mode entries retain header identity without asserting a supported child descriptor.
 
 The stage considers parent catalog records only after the final inherited cut. Every inherited marker discards earlier catalog candidates without interpreting their payloads. Missing entries append after all source events, sorted by creation time then child id, with dense new sequences. Their time is the final source event's time, or header creation time for an empty log. They neither enter the model surface nor change the inherited count.
 
@@ -243,7 +243,7 @@ Current common admission does not validate each user/tool/developer content bloc
 | `compaction/start`, `compaction/summary`, `compaction/end` | Match compaction id, source command, and the active turn context. Summary spans name exact current-surface nodes and exclude the protected head; successful completion has one summary. Inherited unfinished compactions expire at the end-seed marker. |
 | `compaction/prune` | Its span names exact current-surface nodes and excludes the protected head; it does not require a compaction transaction or its owner fields. |
 | Compact checkpoint replacement | Its `compact-checkpoint` source identifies the active compaction. |
-| Native `subagent/catalog` and `subagent/catalog-unknown` | Check own version-0 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
+| Native `subagent/catalog` | Check own version-0 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
 | Inherited cut and delivery | Apply the marker, coordinate, and generation-ownership rules stated above. |
 
 These checks are generation-owned in [relationships.ts](src/relationships.ts). Full common message/envelope acceptance and plugin-owned message projections additionally use the installed Session; the exported V4 restorer alone is not a replacement for complete catalog restoration.
diff --git a/packages/session/session-format-v3-to-v4/README.zh.md b/packages/session/session-format-v3-to-v4/README.zh.md
index 48b7e5cbd0..6c07926950 100644
--- a/packages/session/session-format-v3-to-v4/README.zh.md
+++ b/packages/session/session-format-v3-to-v4/README.zh.md
@@ -148,9 +148,9 @@ V3 未知内容标签变为 `plugin:<original-type>`，其他字段原样保留
 | 多个自身 descriptor | 保留已有父目录项，不比较 mode／label；否则追加模式未知的目录项。 |
 | 已有自身父目录项 | 保留条目及其扩展；要求子创建时间一致，并在恰好一个受支持的自身 descriptor 可用时比较其 mode／label。 |
 | 缺少自身父目录项，且受支持证据完整 | 追加带 child id、创建时间、mode 和可选 label 的 version-0 目录事实。 |
-| 缺少自身父目录项，且证据不完整 | 追加 `subagent/catalog-unknown`，记录 header 身份和未知模式，不编造标签。 |
+| 缺少自身父目录项，且证据不完整 | 追加 `subagent/catalog`，记录 header 身份和未知模式，不编造标签。 |
 
-Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable` 或 `one-shot` mode，以及 continuable mode 下的字符串 label；存在的 one-shot label 也必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。 `subagent/catalog-unknown` 单独记录 version 0、child id、创建时间和 `mode: 'unknown'`；两种事件共同组成 child id 唯一的目录。已有 `subagent/catalog` 载荷保留其 mode 要求。
+Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable`、`one-shot` 或 `unknown` mode，以及 continuable mode 下的字符串 label；任何 mode 下存在的 label 都必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。未知模式条目保留 header 身份信息，不声明子 descriptor 受支持。
 
 Stage 只把最终继承截点之后的父目录记录作为候选。每个 inherited marker 都会丢弃更早的目录候选，不解释其载荷。缺失项追加在所有源事件之后，按创建时间、child id 排序，并使用连续的新序号。时间取最后一个源事件的 time；空日志则取 header 创建时间。这些记录既不进入模型表面，也不改变继承计数。
 
@@ -243,7 +243,7 @@ System image 接纳要求非空 attachment id、PNG／JPEG／WebP／GIF MIME 类
 | `compaction/start`、`compaction/summary`、`compaction/end` | 匹配 compaction id、源 command 和活动 turn 上下文。Summary 区间引用精确的当前表面节点且排除 protected head；成功完成需要一个 summary。继承的未完成 compaction 在 end-seed marker 处过期。 |
 | `compaction/prune` | 其区间引用精确的当前表面节点且排除 protected head；它不要求存在 compaction 事务或其所有者字段。 |
 | Compact checkpoint 替换 | 其 `compact-checkpoint` 来源标识活动 compaction。 |
-| 原生 `subagent/catalog` 与 `subagent/catalog-unknown` | 检查继承截点之后的自身 version-0 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
+| 原生 `subagent/catalog` | 检查继承截点之后的自身 version-0 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
 | 继承截点与 delivery | 应用上文的 marker、坐标及代际归属规则。 |
 
 这些检查由 [relationships.ts](src/relationships.ts) 按代际拥有。完整的通用消息／信封接纳与插件拥有的消息投影还使用已安装 Session；单独的导出 V4 恢复器不能替代完整 catalog 恢复。
diff --git a/packages/session/session-format-v3-to-v4/src/facts.ts b/packages/session/session-format-v3-to-v4/src/facts.ts
index a250801759..2fb476377b 100644
--- a/packages/session/session-format-v3-to-v4/src/facts.ts
+++ b/packages/session/session-format-v3-to-v4/src/facts.ts
@@ -52,6 +52,9 @@ export function childCatalogFact(source: SessionFormatJsonObject): SessionFormat
   if (typeof descriptor['provider'] !== 'string') {
     throw new SessionFormatUnsupportedMigrationError(`${childCatalogSubject(source)} has an invalid subagent descriptor provider`)
   }
+  if (descriptor['version'] !== 1 && descriptor['mode'] !== 'continuable' && descriptor['mode'] !== 'one-shot') {
+    throw new SessionFormatUnsupportedMigrationError(`${childCatalogSubject(source)} has an invalid subagent descriptor mode`)
+  }
   return catalogFact({
     version: 0, childId: id, childCreatedAt: source['childCreatedAt'] as number,
     // V1 described only continuable children and carried no mode field.
@@ -69,25 +72,10 @@ export function childCatalogFact(source: SessionFormatJsonObject): SessionFormat
 export function catalogFact(value: SessionFormatJsonValue, subject = 'subagent/catalog'): SessionFormatJsonObject {
   if (!isSessionFormatJsonObject(value) || value['version'] !== 0
     || typeof value['childId'] !== 'string'
-    || (value['mode'] !== 'continuable' && value['mode'] !== 'one-shot')
+    || (value['mode'] !== 'continuable' && value['mode'] !== 'one-shot' && value['mode'] !== 'unknown')
     || (value['mode'] === 'continuable' && typeof value['label'] !== 'string')
     || (value['label'] !== undefined && typeof value['label'] !== 'string')) {
-    throw new SessionFormatError(`${subject} requires a complete version 0 catalog fact`)
-  }
-  sessionFormatCount(value['childCreatedAt'], 'catalog child creation time')
-  return value
-}
-
-/**
- * Validate a current catalog entry retained without a supported child descriptor.
- * @param value - decoded unknown-child payload.
- * @returns the validated identity with unknown mode.
- */
-export function unknownCatalogFact(value: SessionFormatJsonValue): SessionFormatJsonObject {
-  if (!isSessionFormatJsonObject(value) || value['version'] !== 0
-    || typeof value['childId'] !== 'string' || value['mode'] !== 'unknown'
-    || (value['label'] !== undefined && typeof value['label'] !== 'string')) {
-    throw new SessionFormatError('subagent/catalog-unknown requires a version 0 identity with unknown mode')
+    throw new SessionFormatError(`${subject} requires a version 0 catalog fact`)
   }
   sessionFormatCount(value['childCreatedAt'], 'catalog child creation time')
   return value
diff --git a/packages/session/session-format-v3-to-v4/src/migration.ts b/packages/session/session-format-v3-to-v4/src/migration.ts
index 2184f5b819..50c796a1df 100644
--- a/packages/session/session-format-v3-to-v4/src/migration.ts
+++ b/packages/session/session-format-v3-to-v4/src/migration.ts
@@ -124,7 +124,7 @@ class ReleasedV3ToV4Stage implements SessionFormatMigrationStage {
       }
       const entry = fact ?? { version: 0, childId: id, childCreatedAt: source['childCreatedAt'] as number, mode: 'unknown' }
       existingCatalogs.set(id, entry)
-      context.emitEvent({ type: fact === undefined ? 'subagent/catalog-unknown' : 'subagent/catalog',
+      context.emitEvent({ type: 'subagent/catalog',
         seq: this.nextSeq++, time: this.time, data: entry })
     }
     return cut
diff --git a/packages/session/session-format-v3-to-v4/src/validation.ts b/packages/session/session-format-v3-to-v4/src/validation.ts
index 4b9df349cc..8c0e74d61d 100644
--- a/packages/session/session-format-v3-to-v4/src/validation.ts
+++ b/packages/session/session-format-v3-to-v4/src/validation.ts
@@ -6,7 +6,7 @@ import type { SessionFormatArtifact, SessionFormatEvent } from '@deepseek-ai/dsh
 import { assertV4DeveloperData } from './developer.ts'
 import { assertV4LifecycleRelationships } from './relationships.ts'
 import { assertV4MessageSources } from './message-sources.ts'
-import { catalogFact, unknownCatalogFact } from './facts.ts'
+import { catalogFact } from './facts.ts'
 import { assertV4RetiredSyntax } from './retired-syntax.ts'
 import { assertV4SystemMessageFields } from './system-message.ts'
 import { assertV4ForkResult } from './fork-result.ts'
@@ -119,8 +119,8 @@ export function assertReleasedV4Relationships(artifact: SessionFormatArtifact, k
       && deliveryId !== artifact.header.id) {
       throw new SessionFormatError('current-generation delivery marker names the wrong Session')
     }
-    if ((event.type === 'subagent/catalog' || event.type === 'subagent/catalog-unknown') && event.seq >= artifact.inheritedEventCount) {
-      const fact = event.type === 'subagent/catalog' ? catalogFact(event.data) : unknownCatalogFact(event.data)
+    if (event.type === 'subagent/catalog' && event.seq >= artifact.inheritedEventCount) {
+      const fact = catalogFact(event.data)
       const id = fact['childId'] as string
       if (ids.has(id)) throw new SessionFormatError(`duplicate catalog child ${id}`)
       ids.add(id)
diff --git a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
index 73733b0afc..f533b9d502 100644
--- a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
@@ -67,14 +67,14 @@ describe('V3 parent catalog completion', () => {
     expect(migrate(source, [child], true).events).toEqual([
       ...source, { type: 'subagent/catalog', seq: 4, time: 2, data: child },
     ])
-    expect(() => migrate([...source, { ...opaque, seq: 4 }], [], true)).toThrow('complete version 0')
-    expect(() => migrate([opaque], [])).toThrow('complete version 0')
+    expect(() => migrate([...source, { ...opaque, seq: 4 }], [], true)).toThrow('version 0')
+    expect(() => migrate([opaque], [])).toThrow('version 0')
   })
 
   it('requires explicit corpus facts and refuses conflicting identities', () => {
     expect(() => sessionFormatV3ToV4.createStage({ sourceHeader: header, targetHeader: { ...header, version: 4 },
       sourceKind: 'decoded', sourceInheritedEventCount: 0 })).toThrow('explicit historical child facts')
-    expect(() => migrate([], [{ ...child, mode: 'invalid' }])).toThrow('complete version 0')
+    expect(() => migrate([], [{ ...child, mode: 'invalid' }])).toThrow('version 0')
     expect(() => migrate([{ type: 'subagent/catalog', seq: 0, time: 2, data: child }], [{ ...child, childCreatedAt: 3 }])).toThrow('conflicts')
   })
 
@@ -148,7 +148,7 @@ describe('V3 parent catalog completion', () => {
     const unavailable = { childId: 'unavailable', childCreatedAt: 1,
       descriptorCount: kind === 'missing' ? 0 : kind === 'multiple' ? 2 : 1, descriptor }
     expect(migrate([], [child, unavailable]).events).toEqual([
-      { type: 'subagent/catalog-unknown', seq: 0, time: 1, data: { version: 0, childId: 'unavailable', childCreatedAt: 1, mode: 'unknown' } },
+      { type: 'subagent/catalog', seq: 0, time: 1, data: { version: 0, childId: 'unavailable', childCreatedAt: 1, mode: 'unknown' } },
       { type: 'subagent/catalog', seq: 1, time: 1, data: child },
     ])
   })
diff --git a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
index a0e1f9e9de..7bd8b24539 100644
--- a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
@@ -114,20 +114,19 @@ describe('restoreReleasedV4Artifact', () => {
   })
 
   it('retains unknown child membership and rejects invalid identities or duplicate child ids', () => {
-    const known = new Set([...KNOWN, 'subagent/catalog', 'subagent/catalog-unknown'])
+    const known = new Set([...KNOWN, 'subagent/catalog'])
     const data = { version: 0, childId: 'unreadable', childCreatedAt: 2, mode: 'unknown' }
-    const event = { type: 'subagent/catalog-unknown', seq: 0, time: 1, data }
+    const event = { type: 'subagent/catalog', seq: 0, time: 1, data }
     const valid = artifact([event])
     expect(restoreReleasedV4Artifact(valid, known)).toBe(valid)
     expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: { ...data, label: 'retained' } }]), known)).not.toThrow()
     for (const invalid of [null, { ...data, version: 1 }, { ...data, childId: 1 },
-      { ...data, childCreatedAt: -1 }, { ...data, mode: 'one-shot' }, { ...data, label: null }]) {
+      { ...data, childCreatedAt: -1 }, { ...data, mode: 'invalid' }, { ...data, label: null }]) {
       expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: invalid }]), known)).toThrow()
     }
     expect(() => restoreReleasedV4Artifact(artifact([event, { ...event, seq: 1 }]), known)).toThrow('duplicate catalog child')
     expect(() => restoreReleasedV4Artifact(artifact([event, { type: 'subagent/catalog', seq: 1, time: 1,
       data: { ...data, mode: 'one-shot' } }]), known)).toThrow('duplicate catalog child')
-    expect(() => restoreReleasedV4Artifact(artifact([{ ...event, type: 'subagent/catalog' }]), known)).toThrow('complete version 0')
   })
 
   it('validates only the envelope in physical mode', () => {
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 166eaa18dc..4f0d2c2fe3 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: 066b43d6a0f7c0e29b8c2ebbba17fa460103187a
-README.zh.md: 61693b96d904b8d2c3d679c065f3667eb3bdc46e
+README.md: 609368aa42f1ba75d818a74877fcd574bf9d5ddf
+README.zh.md: 07c0dc94270ddb69812ec8443688a505269eba59
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index 066b43d6a0..609368aa42 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -81,7 +81,7 @@ The current-generation scanner applies the current codec owner’s structural ad
 
 `open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Current revisions identify that file; historical revisions also fingerprint the selected files across the persistence root, so child changes invalidate cached logical events. Fingerprinting reads filesystem metadata only; unrelated changes conservatively invalidate historical revisions. One `list()` call shares a corpus fingerprint across its historical entries. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
-Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers are omitted from discovery. Child decoding and descriptor-field failures produce warnings naming the child path and retain header identity through `subagent/catalog-unknown` when the parent has no complete entry; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors likewise produce unknown-mode membership without inventing a label. Published unknown entries remain browsable; child history reads retry the actual log and resolve its mode from a valid descriptor. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
+Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers are omitted from discovery. Child decoding and descriptor-field failures produce warnings naming the child path and retain header identity through `subagent/catalog` when the parent has no complete entry; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors likewise produce unknown-mode membership without inventing a label. Published unknown entries remain browsable; child history reads retry the actual log and resolve its mode from a valid descriptor. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
 
 Historical `stat` and `list` revisions require metadata work proportional to the root’s Session count. Fresh body preparation scans all selected headers and decodes direct-child bodies; memo reuse still scans membership and checks revisions. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat that work. Current V4 body reads and revisions avoid the historical corpus scan. See the [measured costs and diagnostic command](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements).
 
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 61693b96d9..07c0dc9427 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -81,7 +81,7 @@ kind: "package-reference"
 
 `open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；每个嵌套对象和数组都会冻结，句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的修订号。当前格式修订号标识该文件；历史格式修订号还包含持久化根目录中所选文件的指纹，因此子日志变化会使缓存的逻辑事件失效。指纹只读取文件系统元数据；无关变化也会保守地使历史修订号失效。一次 `list()` 为其历史条目共用一个全库指纹。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
-历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header 不参与发现。子日志解码或 descriptor 字段失败会产生带子路径的警告；父目录没有完整条目时，通过 `subagent/catalog-unknown` 保留 header 身份信息。健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 同样生成模式未知的目录项，不编造标签。已发布的未知条目仍可浏览；读取子历史时会重试实际日志，并从有效 descriptor 确定模式。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
+历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header 不参与发现。子日志解码或 descriptor 字段失败会产生带子路径的警告；父目录没有完整条目时，通过 `subagent/catalog` 保留 header 身份信息。健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 同样生成模式未知的目录项，不编造标签。已发布的未知条目仍可浏览；读取子历史时会重试实际日志，并从有效 descriptor 确定模式。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
 
 历史格式的 `stat` 与 `list` 修订号需要与根目录 Session 数量成正比的元数据工作。首次正文准备扫描所有所选 header 并解码直属子正文；复用准备缓存仍扫描成员集合并检查修订。只读访问从不发布升级，因此冷进程与被淘汰的准备缓存会重复这些工作。当前 V4 正文读取和修订号避开历史全库扫描。见[实测成本与诊断命令](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements)。
 
diff --git a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
index 028edc5d1b..e4c6d677a9 100644
--- a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
@@ -120,7 +120,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const catalog = { type: 'subagent/catalog', seq: 0, time: 1,
       data: { version: 0, childId: 'grandchild', childCreatedAt: 3, mode: 'one-shot' } }
     const path = await f.write('child', [catalog, { ...catalog, seq: 1 }], true, 4)
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
   })
@@ -137,7 +137,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     await f.write('healthy', [f.descriptor], true)
     const parent = await f.ctx.sessionPersistence.open(f.parent, access)
     try { expect((await parent.read()).events).toMatchObject([
-      { type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } },
+      { type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } },
       { type: 'subagent/catalog', data: { childId: 'healthy', mode: 'continuable' } },
     ]) } finally { await parent.close() }
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), access)).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
@@ -170,7 +170,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const f = await fixture()
     const childPath = await f.write('child', [], true)
     await writeFile(childPath, Buffer.concat([await readFile(childPath), Buffer.alloc(8)]))
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
   })
 
@@ -208,10 +208,10 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const childPath = await f.write('child', events, true)
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
     const original = await Promise.all([readFile(parentPath), readFile(childPath)])
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    try { expect((await writer.read()).events).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }]) } finally { await writer.close() }
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    try { expect((await writer.read()).events).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }]) } finally { await writer.close() }
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     const child = await f.ctx.sessionPersistence.open(SessionId('child'), 'read')
     try { expect((await child.read()).events).toEqual(events) } finally { await child.close() }
     expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
@@ -240,7 +240,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
   it('retains unknown child identity without migrating unsupported contents', async () => {
     const f = await fixture()
     await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
   })
 
@@ -248,7 +248,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const f = await fixture()
     const warn = vi.spyOn(f.ctx.logger, 'warn')
     const path = await f.write('child', [{ ...f.descriptor, data: { version: 2, provider: 'spawn', mode: 'unknown' } }], true)
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
   })
 
@@ -283,7 +283,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
   it('recollects newly available discovery fields before publishing a prepared parent', async () => {
     const f = await fixture()
     const childPath = await f.write('child', [], true)
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     await f.write('child', [f.descriptor], true)
     await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(childPath)
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
@@ -383,7 +383,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
   it('recollects a repaired child before publishing a prepared parent', async () => {
     const f = await fixture()
     await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
-    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog-unknown', data: { childId: 'child', mode: 'unknown' } }])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     await f.write('child', [f.descriptor], true)
     expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child' } }])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 37e5596037..25cea24568 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 94da1be172b441aec1fd16d3853596eaee74ca1b
-README.zh.md: 462bc3aff2155b96f87d9f69c5aae1aa5002a9ca
+README.md: 75237c6eda835459015d5b2f64402190d27d72af
+README.zh.md: 187d26ea3a4261c4ddeed96cd6c41f50fbd48c91
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 94da1be172..75237c6eda 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -109,7 +109,7 @@ A request is validated against the provider's advertised capabilities, a durable
 
 The manager reserves a child identity, resolves the durable descriptor, creates (or cold-resumes) the child Agent, installs it in an Activation, and submits the prompt. Model-authored messages cross one parent/child edge through fixed Steer scheduling; browser human prompts choose Queue or best-effort Steer through an internal adapter, while other host protocols may retain Queue for distinct turns. A Session queue command admits a live subagent-owned Agent only from its own continuable descriptor. Settlement waits for Agent activity to finish, an empty Inbox, and no owned children, then flushes final Session state with admission open. Under the child lock, the manager revalidates the wake generation, Session sequence, Inbox, and owned children; the synchronous task entry of `Agent.runMaintenance()` claims the idle phase and closes the private subagent Inbox in the same JavaScript turn before handle disposal. An absent direct-child Activation cold-resumes from the persisted session. When a resident Activation settles, the manager tells the child's direct parent in the parent's own turn stream.
 
-Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives. Historical migration may instead append `subagent/catalog-unknown` from a readable child header. Its `mode: 'unknown'` projection keeps the child visible without claiming continuation support; an existing complete entry remains authoritative.
+Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives. Historical migration may instead append `subagent/catalog` from a readable child header. Its `mode: 'unknown'` projection keeps the child visible without claiming continuation support; an existing complete entry remains authoritative.
 
 ### Ownership and invariants
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 462bc3aff2..187d26ea3a 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -109,7 +109,7 @@ kind: "package-reference"
 
 管理器预留 child 身份、解析持久化描述符、创建（或冷恢复）child、把它安装进 Activation 并提交提示词。模型编写的消息通过固定 Steer 调度跨一条 parent/child 边；浏览器人类 prompt 通过内部适配器选择 Queue 或 best-effort Steer，其他 host 协议仍可保留 Queue 以创建独立轮次。Session queue command 仅根据 child 自身的 continuable descriptor 准入在线 subagent-owned Agent。Settlement 会等待 Agent 活动结束、Inbox 为空且没有所拥有子级，再在准入开放时 flush 最终 Session 状态。管理器随后在 child lock 内重新验证 wake generation、Session 序号、Inbox 与所拥有子级；`Agent.runMaintenance()` 的同步 task 入口会占用 idle 阶段，并在同一个 JavaScript turn 内关闭私有 subagent Inbox，然后才释放句柄。直接 child 不存在 Activation 时会从持久化会话冷恢复。当驻留 Activation 结算时，管理器会在 parent 自身的轮次流中告知该 child 的直接 parent。
 
-本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。 历史迁移可根据可读子 header 追加 `subagent/catalog-unknown`。其 `mode: 'unknown'` 投影让子会话保持可见，但不表示支持继续执行；已有完整条目仍具有权威性。
+本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。 历史迁移可根据可读子 header 追加 `subagent/catalog`。其 `mode: 'unknown'` 投影让子会话保持可见，但不表示支持继续执行；已有完整条目仍具有权威性。
 
 ### 所有权与不变式
 
diff --git a/packages/subagent/subagent/src/catalog.ts b/packages/subagent/subagent/src/catalog.ts
index 2fbc828892..15ec24dd17 100644
--- a/packages/subagent/subagent/src/catalog.ts
+++ b/packages/subagent/subagent/src/catalog.ts
@@ -20,7 +20,7 @@ import type { SubagentCatalogEntry } from './projection-types.ts'
 /** Current payload version for `subagent/catalog` events. */
 export const SUBAGENT_CATALOG_VERSION = 0
 
-/** One complete parent-owned catalog fact. */
+/** One parent-owned catalog fact with known or unknown child mode. */
 export type SubagentCatalogEvent =
   & {
     readonly version: 0
@@ -29,35 +29,23 @@ export type SubagentCatalogEvent =
   } & (
     | { readonly mode: 'one-shot'; readonly label?: string }
     | { readonly mode: 'continuable'; readonly label: string }
+    | { readonly mode: 'unknown'; readonly label?: string }
   )
 
-type UnknownCatalogEvent = {
-  readonly version: 0
-  readonly childId: SessionId
-  readonly childCreatedAt: number
-  readonly mode: 'unknown'
-  readonly label?: string
-}
-
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
-     * A direct child's complete discovery fact.
+     * A direct child's identity and available discovery fields.
      * @param data - versioned parent-owned catalog entry.
      */
     'subagent/catalog': SubagentCatalogEvent
-    /**
-     * A historical child's header identity when its descriptor cannot establish a mode.
-     * @param data - child identity retained for discovery and later history reads.
-     */
-    'subagent/catalog-unknown': UnknownCatalogEvent
   }
 }
 
 /** Host fold state for one parent catalog. */
 export interface SubagentCatalogState {
   readonly inheritedEventCount: SessionLogOffset
-  readonly head?: ChunkedList<SubagentCatalogEvent | UnknownCatalogEvent> | undefined
+  readonly head?: ChunkedList<SubagentCatalogEvent> | undefined
 }
 
 const sessionIdSchema = z.string() as unknown as z.ZodType<SessionId>
@@ -76,12 +64,11 @@ const continuableCatalogSchema = z.object({
   label: z.string(),
 }).strict()
 const unknownCatalogSchema = oneShotCatalogSchema.extend({ mode: z.literal('unknown') })
-const completeCatalogSchema = z.union([oneShotCatalogSchema, continuableCatalogSchema])
 const eventDataSchema = z.union([
   oneShotCatalogSchema,
   continuableCatalogSchema,
   unknownCatalogSchema,
-]) as unknown as z.ZodType<SubagentCatalogEvent | UnknownCatalogEvent>
+]) as unknown as z.ZodType<SubagentCatalogEvent>
 const viewSchema = z.array(z.union([
   oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
     id: sessionIdSchema,
@@ -138,10 +125,8 @@ export const subagentCatalogProjectionDefinition = {
   stateSchema,
   init: (_header: SessionHeader, inheritedEventCount: SessionLogOffset) => ({ inheritedEventCount }),
   apply: (state, event: SessionEvent) => {
-    if ((event.type !== 'subagent/catalog' && event.type !== 'subagent/catalog-unknown') || event.seq < state.inheritedEventCount) return state
-    const data = (event.type === 'subagent/catalog-unknown' ? unknownCatalogSchema : completeCatalogSchema)
-      .parse(event.data) as SubagentCatalogEvent | UnknownCatalogEvent
-    return { ...state, head: appendChunkedList(state.head, data) }
+    if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount) return state
+    return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) }
   },
   stateVersion: 3,
   wire: { viewSchema, view: subagentCatalogEntries },
diff --git a/packages/subagent/subagent/tests/catalog.spec.ts b/packages/subagent/subagent/tests/catalog.spec.ts
index f8450cd93d..589e336c88 100644
--- a/packages/subagent/subagent/tests/catalog.spec.ts
+++ b/packages/subagent/subagent/tests/catalog.spec.ts
@@ -107,7 +107,7 @@ describe('subagent catalog projection', () => {
       fact(0, 'child-b', 1, { mode: 'one-shot' }),
       fact(1, 'child-a', 1, { mode: 'one-shot', label: 'once' }),
       fact(2, 'child-d', 3, { mode: 'continuable', label: 'later' }),
-      { type: 'subagent/catalog-unknown', seq: SessionSeq(3), time: 0,
+      { type: 'subagent/catalog', seq: SessionSeq(3), time: 0,
         data: { version: 0, childId: SessionId('unreadable'), childCreatedAt: 4, mode: 'unknown' } },
     ]
     const state = fold(events)
diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py
index cb889a6a6f..78178c1e18 100644
--- a/python/sdk/tests/test_client.py
+++ b/python/sdk/tests/test_client.py
@@ -596,7 +596,7 @@ def test_session_subscription_keeps_descendant_relationships_across_subscription
     client = HarnessClient()
     with client.subscribe_session_notifications("main") as first:
         unknown_child = {
-            "type": "subagent/catalog-unknown", "seq": 0, "time": 1,
+            "type": "subagent/catalog", "seq": 0, "time": 1,
             "data": {"version": 0, "childId": "unreadable-child", "childCreatedAt": 1, "mode": "unknown"},
         }
         client._handle_message({
diff --git a/scripts/persistence-changes.spec.ts b/scripts/persistence-changes.spec.ts
index 54b5a9588f..0a3be90d70 100644
--- a/scripts/persistence-changes.spec.ts
+++ b/scripts/persistence-changes.spec.ts
@@ -397,7 +397,60 @@ function unionBody(arms: readonly (readonly SchemaProperty[])[]): PersistenceRoo
   return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
 }
 
+function catalogModeRoot(unknownMode?: string, changeLabel = false, extraField = false): PersistenceRoot {
+  const snapshot = parsePersistenceSnapshot(JSON.parse(readFileSync(
+    new URL('../docs/persistence-changes/2026-09-11-initial.schema.json', import.meta.url), 'utf8',
+  )))
+  const root = snapshot.roots.find(root => root.key === 'event:subagent/catalog')!
+  const nodes: SchemaNode[] = [...structuredClone(root.schema.nodes)]
+  const union = nodes.find(node => node.kind === 'union')!
+  if (union.kind !== 'union') throw new Error('catalog fixture requires mode alternatives')
+  const oneShot = union.types.find((index) => {
+    const node = nodes[index]
+    if (node?.kind !== 'object') return false
+    const mode = nodes[node.properties.find(property => property.name === 'mode')!.type]
+    return mode?.kind === 'literal' && mode.value === 'one-shot'
+  })!
+  const variant = nodes[oneShot]!
+  if (variant.kind !== 'object') throw new Error('catalog fixture requires object alternatives')
+  if (unknownMode !== undefined) {
+    const index = nodes.length
+    nodes.push({ ...variant, properties: variant.properties.map(property => property.name === 'mode'
+      ? { ...property, type: index + 1 } : property) }, { kind: 'literal', value: unknownMode })
+    const added = nodes[index]!
+    if (extraField && added.kind === 'object') nodes[index] = { ...added,
+      properties: [...added.properties, { name: 'extra', type: variant.properties[0]!.type, optional: false }] }
+    nodes[nodes.indexOf(union)] = { ...union, types: [...union.types, index] }
+  }
+  if (changeLabel) nodes[oneShot] = { ...variant, properties: variant.properties.filter(property => property.name !== 'label') }
+  const schema = canonicalizeSchema(nodes, 0)
+  return { ...root, schema, digest: schemaDigest(schema) }
+}
+
 describe('persistence change classification', () => {
+  it('acknowledges unknown catalog mode at V4 while retaining the accepted checkpoint', () => {
+    const root = fixture()
+    const before = { ...inventory({}, 4), roots: [...inventory({}, 4).roots.filter(root => root.kind !== 'event'), catalogModeRoot()] }
+    finalize(root, before)
+    const after = { ...before, roots: before.roots.map(root => root.kind === 'event' ? catalogModeRoot('unknown') : root) }
+    expect(classifyPersistenceChange(catalogModeRoot(), catalogModeRoot('unknown')))
+      .toEqual([expect.objectContaining({ path: 'event:subagent/catalog.data', requiresVersionBump: false })])
+    runPersistenceChanges(['--record', COMPATIBLE_ID, '--prose', proseFile(root)], root, () => after)
+    verifyPersistenceChanges(root, after)
+  })
+
+  it('keeps other catalog modes, altered fields, classification changes, and removals breaking', () => {
+    const before = catalogModeRoot()
+    for (const after of [catalogModeRoot('other'), catalogModeRoot('unknown', true), catalogModeRoot('unknown', false, true)]) {
+      expect(classifyPersistenceChange(before, after).some(change => change.requiresVersionBump)).toBe(true)
+    }
+    const expanded = catalogModeRoot('unknown')
+    expect(classifyPersistenceChange(expanded, before).some(change => change.requiresVersionBump)).toBe(true)
+    expect(classifyPersistenceChange(before, { ...expanded, surface: true }).some(change => change.requiresVersionBump)).toBe(true)
+    expect(classifyPersistenceChange({ ...before, key: 'event:other' }, { ...expanded, key: 'event:other' })
+      .some(change => change.requiresVersionBump)).toBe(true)
+  })
+
   it('treats a new optional payload subtree as one additive change even with required descendants', () => {
     const before = typeRoot('event:example/value', { value: 'string' })
     const after = typeRoot('event:example/value', { value: 'string', 'details?': { name: 'string', count: 'number' } })
diff --git a/scripts/persistence-changes.ts b/scripts/persistence-changes.ts
index 65f17b279f..e53092e921 100644
--- a/scripts/persistence-changes.ts
+++ b/scripts/persistence-changes.ts
@@ -471,6 +471,29 @@ export function classifyPersistenceChange(before: PersistenceRoot | null, after:
   function compareAlternatives(
     oldTypes: readonly number[], newTypes: readonly number[], path: string, scope: Scope, active: ReadonlySet<string>,
   ): PersistenceTypeChange[] {
+    if (key === 'event:subagent/catalog' && path === `${key}.data` && scope === 'body'
+      && oldTypes.length === 2 && newTypes.length === 3) {
+      const modeNode = (index: number): number | undefined => {
+        const node = newRoot.schema.nodes[index]
+        return node?.kind === 'object' ? node.properties.find(property => property.name === 'mode' && !property.optional)?.type : undefined
+      }
+      const mode = (index: number): string | number | boolean | null | undefined => {
+        const node = newRoot.schema.nodes[modeNode(index) ?? -1]
+        return node?.kind === 'literal' ? node.value : undefined
+      }
+      const unknown = newTypes.find(index => mode(index) === 'unknown')
+      const oneShot = newTypes.find(index => mode(index) === 'one-shot')
+      if (unknown !== undefined && oneShot !== undefined) {
+        // The catalog exception admits only the one-shot fields with unknown mode;
+        // existing branches still pass the ordinary structural comparison below.
+        const normalized = { ...newRoot.schema, nodes: newRoot.schema.nodes.map((node, index) =>
+          index === modeNode(unknown) ? { kind: 'literal' as const, value: 'one-shot' } : node) }
+        if (subDigest(normalized, unknown) === fingerprint(newRoot.schema, oneShot, 1)) {
+          return [describe(path, 'union-variants-changed', false),
+            ...compareAlternatives(oldTypes, newTypes.filter(index => index !== unknown), path, scope, active)]
+        }
+      }
+    }
     if (oldTypes.length !== newTypes.length) return [describe(path, 'union-variants-changed')]
     const candidates = oldTypes.map(oldType => newTypes.map(newType => compare(oldType, newType, path, scope, active)))
     const matching = matchUnionVariants(candidates.map(row => row.flatMap((candidate, index) =>

From 065def9d41bd2588db6df74ec2d5db3b9ed40ef4 Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Sun, 20 Sep 2026 14:50:48 +0800
Subject: [PATCH 21/37] docs: use compliant issue references in native
 extraction note

---
 ...-single-file-executable-sdk-runtime-distribution.i18n.yaml | 4 ++--
 ...6-07-10-single-file-executable-sdk-runtime-distribution.md | 2 +-
 ...7-10-single-file-executable-sdk-runtime-distribution.zh.md | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index ce9821d058..6a0f5d94c7 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: 2de12a542f6c17754eb494a9e42ba843573182cb
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: c391d7268ed55915aeefe4cb323dcf1350ad631f
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: ff00327c388b0468e5e98d488141aa35eb40d104
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 3f7f18a9907b2f43f7cd8467f054f0d0bfcef14a
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index 2de12a542f..ff00327c38 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -23,7 +23,7 @@ The exe is packaged with the **`--sea` (enhanced SEA) mode** of [@yao-pkg/pkg](h
 
 `@yao-pkg/pkg` is an exact-pinned root `devDependency` invoked as `pnpm exec pkg`, with [`patches/@yao-pkg__pkg@6.21.0.patch`](../../../../patches/@yao-pkg__pkg@6.21.0.patch) removing the SEA bootstrap's `patchChildProcess` call. Unpatched, pkg rewrites spawned commands named `node` — including the string after a `-c`/`/c` flag, exactly the Bash tool's `bash -c` form — to the executable itself and stamps `PKG_EXECPATH` into every child environment, so a model-issued `node --version` silently boots the dsh CLI; Node's own SEA layer performs no such rewrite, and a SEA binary cannot impersonate plain Node because it always boots its embedded app. With the call removed, children resolve `node` through PATH like any other process (a machine without Node reports command-not-found honestly), no `PKG_EXECPATH` reaches children, absolute `process.execPath` spawns still re-enter the app, worker threads never applied the hook, and `process.pkg` sidecar selection is untouched.
 
-The same patch makes the SEA bootstrap's native-addon extraction atomic. On the first `dlopen` of an addon inside the VFS, pkg's `patchDlopen` copies the addon's package tree to `$PKG_NATIVE_CACHE_PATH/pkg/<sha256 of the .node file>/` (default `~/.cache/pkg/...`), a per-user directory that every concurrent process of the same executable shares; upstream writes each file straight to its final path with `writeFileSync`, which truncates a file another process may already have mapped and lets that process's `existsSync`/hash check read a half-written file. Concurrent first starts therefore die with SIGBUS on Linux or fail with `ERR_DLOPEN_FAILED: Library not loaded` on sharp's libvips on macOS ([#4664](https://github.com/deepseek-harness/deepseek-harness/issues/4664)). The patch routes the three write sites through a same-directory temporary file and `renameSync`, so a cache path is either absent or complete, every process finishes its own copy pass before it loads, and concurrent renames of identical content need no lock. The cache location, hash keying, and per-file comparison are unchanged, so a consumer that isolates the cache per instance through `PKG_NATIVE_CACHE_PATH` keeps working; worker threads only define the hook and never install it. Measured (linux-x64, node24 target, pkg 6.21.0, a probe that loads sharp with its 18 MB libvips library, 16 concurrent first starts against one empty cache, five rounds): 39 of 80 processes died with SIGBUS before the change and 0 of 80 after it, with no temporary files left behind.
+The same patch makes the SEA bootstrap's native-addon extraction atomic. On the first `dlopen` of an addon inside the VFS, pkg's `patchDlopen` copies the addon's package tree to `$PKG_NATIVE_CACHE_PATH/pkg/<sha256 of the .node file>/` (default `~/.cache/pkg/...`), a per-user directory that every concurrent process of the same executable shares; upstream writes each file straight to its final path with `writeFileSync`, which truncates a file another process may already have mapped and lets that process's `existsSync`/hash check read a half-written file. Concurrent first starts therefore die with SIGBUS on Linux or fail with `ERR_DLOPEN_FAILED: Library not loaded` on sharp's libvips on macOS (#4664). The patch routes the three write sites through a same-directory temporary file and `renameSync`, so a cache path is either absent or complete, every process finishes its own copy pass before it loads, and concurrent renames of identical content need no lock. The cache location, hash keying, and per-file comparison are unchanged, so a consumer that isolates the cache per instance through `PKG_NATIVE_CACHE_PATH` keeps working; worker threads only define the hook and never install it. Measured (linux-x64, node24 target, pkg 6.21.0, a probe that loads sharp with its 18 MB libvips library, 16 concurrent first starts against one empty cache, five rounds): 39 of 80 processes died with SIGBUS before the change and 0 of 80 after it, with no temporary files left behind.
 
 Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's testing-system "snapshot" (ACP replay expected outputs, `$DSH_SNAPSHOT`); this document says "VFS" for the former.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index c391d7268e..3f7f18a990 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -23,7 +23,7 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 `@yao-pkg/pkg` 是精确钉版的根 `devDependency`，经 `pnpm exec pkg` 调用，并以 [`patches/@yao-pkg__pkg@6.21.0.patch`](../../../../patches/@yao-pkg__pkg@6.21.0.patch) 移除 SEA bootstrap 中的 `patchChildProcess` 调用。未打补丁时，pkg 会把 spawn 的 `node` 命令——包括 `-c`/`/c` 标志后的命令串，恰是 Bash 工具的 `bash -c` 形态——改写为 exe 自身，并向每个子进程环境注入 `PKG_EXECPATH`，模型下发的 `node --version` 会静默启动 dsh CLI；Node 自身的 SEA 层没有这种改写，且 SEA 二进制永远启动内嵌应用、无法充当纯 Node。移除该调用后，子进程像普通进程一样经 PATH 解析 `node`（无 Node 的机器如实报 command not found），子进程环境不再出现 `PKG_EXECPATH`，以 `process.execPath` 绝对路径 spawn 的重入不受影响，worker 线程本来就未应用该钩子，`process.pkg` 侧车选择也不受影响。
 
-同一补丁还把 SEA bootstrap 的原生插件解包改成原子写入。VFS 内的插件首次 `dlopen` 时，pkg 的 `patchDlopen` 会把该插件所在的包目录整棵拷到 `$PKG_NATIVE_CACHE_PATH/pkg/<.node 文件的 sha256>/`（默认 `~/.cache/pkg/...`），这是同一个 exe 的所有并发进程共用的按用户目录；上游用 `writeFileSync` 直接写目标路径，会把另一个进程可能已经映射的文件截断，并让该进程的 `existsSync`/哈希比对读到写了一半的文件。因此并发首次启动在 Linux 上以 SIGBUS 崩溃，在 macOS 上对 sharp 的 libvips 报 `ERR_DLOPEN_FAILED: Library not loaded`（[#4664](https://github.com/deepseek-harness/deepseek-harness/issues/4664)）。补丁让三处写入都经过同目录临时文件加 `renameSync`，于是缓存路径要么不存在、要么完整，每个进程都在加载前走完自己的拷贝，相同内容的并发 rename 不需要锁。缓存位置、哈希键与逐文件比对均未改变，通过 `PKG_NATIVE_CACHE_PATH` 按实例隔离缓存的消费方照常工作；worker 线程只定义该钩子而从不安装。 实测（linux-x64、node24 构建目标、pkg 6.21.0，一个加载 sharp 及其 18 MB libvips 库的探针，16 个进程对同一个空缓存并发首次启动，跑五轮）：改动前 80 个进程中 39 个以 SIGBUS 崩溃，改动后 80 个全部正常，且无残留临时文件。
+同一补丁还把 SEA bootstrap 的原生插件解包改成原子写入。VFS 内的插件首次 `dlopen` 时，pkg 的 `patchDlopen` 会把该插件所在的包目录整棵拷到 `$PKG_NATIVE_CACHE_PATH/pkg/<.node 文件的 sha256>/`（默认 `~/.cache/pkg/...`），这是同一个 exe 的所有并发进程共用的按用户目录；上游用 `writeFileSync` 直接写目标路径，会把另一个进程可能已经映射的文件截断，并让该进程的 `existsSync`/哈希比对读到写了一半的文件。因此并发首次启动在 Linux 上以 SIGBUS 崩溃，在 macOS 上对 sharp 的 libvips 报 `ERR_DLOPEN_FAILED: Library not loaded`（#4664）。补丁让三处写入都经过同目录临时文件加 `renameSync`，于是缓存路径要么不存在、要么完整，每个进程都在加载前走完自己的拷贝，相同内容的并发 rename 不需要锁。缓存位置、哈希键与逐文件比对均未改变，通过 `PKG_NATIVE_CACHE_PATH` 按实例隔离缓存的消费方照常工作；worker 线程只定义该钩子而从不安装。 实测（linux-x64、node24 构建目标、pkg 6.21.0，一个加载 sharp 及其 18 MB libvips 库的探针，16 个进程对同一个空缓存并发首次启动，跑五轮）：改动前 80 个进程中 39 个以 SIGBUS 崩溃，改动后 80 个全部正常，且无残留临时文件。
 
 术语提醒：pkg 的 `/snapshot` VFS 与本仓库测试体系的「快照」（ACP（Agent Client Protocol）回放预期输出、`$DSH_SNAPSHOT`）无关，本文用「VFS」指前者。
 

From d8480db9f0d8d0dab3d8dde3d9f8642d42c65cb5 Mon Sep 17 00:00:00 2001
From: liukx0205 <harusoda@berkeley.edu>
Date: Sun, 20 Sep 2026 14:54:20 +0800
Subject: [PATCH 22/37] refactor(web): read engagement retention from one
 identity set

Address review: retention now has a single definition (retainedIds) shared by
the list-refresh sweep and the single-id prune, an already-engaged identity
skips the redundant row mutation, and the ledger documents why Host-asserted
running is recorded before any holder exists while the client-local acceptance
callback requires one.
---
 .../src/client/sessions/manager.ts            | 52 +++++++++++++------
 1 file changed, 35 insertions(+), 17 deletions(-)

diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts
index 4a7d1d685d..9744bf3c75 100644
--- a/packages/api/session-controller/src/client/sessions/manager.ts
+++ b/packages/api/session-controller/src/client/sessions/manager.ts
@@ -87,7 +87,13 @@ export class SessionManager {
   private readonly sessions = new Map<SessionId, Session>()
   /** In-flight Session disposals remain here after instances leave `sessions`, so manager disposal can await quiescence. */
   private readonly sessionDisposals = new Set<Promise<void>>()
-  /** Accepted/running presentation must survive a later empty-history list response. */
+  /**
+   * Accepted/running presentation must survive a later empty-history list
+   * response. Host-asserted running is recorded even before a row, instance, or
+   * address holds the identity — the listing that would hold it may not have
+   * landed yet — while the client-local acceptance callback requires a current
+   * holder, because it can arrive from a replaced or already-dropped Session.
+   */
   private readonly engagedSessions = new Set<SessionId>()
   private disposed = false
   /** Per-session projection value stores, retained independently of instance arrival (the
@@ -187,7 +193,7 @@ export class SessionManager {
     if (session !== expected) return Promise.resolve()
     this.sessions.delete(sessionId)
     this.addresses.delete(sessionId)
-    this.pruneEngagement(sessionId)
+    this.pruneEngagement(sessionId, this.retainedIds(this.summaries))
     return this.startSessionDisposal(session)
   }
 
@@ -276,9 +282,12 @@ export class SessionManager {
       // The sender's local first-send flip mirrors into the list row so the
       // session surfaces (lists filter on blank) before any host frame lands.
       onEngaged: (engaged) => {
-        if (this.disposed || !this.retainsSession(engaged.sessionId)) return
-        this.engagedSessions.add(engaged.sessionId)
-        this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
+        if (this.disposed || !this.retainedIds(this.summaries).has(engaged.sessionId)) return
+        // An identity already on the ledger needs no second row mutation.
+        if (!this.engagedSessions.has(engaged.sessionId)) {
+          this.engagedSessions.add(engaged.sessionId)
+          this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
+        }
         this.sessions.get(engaged.sessionId)?.handleBlank(false)
       },
       projections: this.projectionStore(sessionId),
@@ -289,13 +298,26 @@ export class SessionManager {
     return summary.blank && !this.engagedSessions.has(summary.sessionId)
   }
 
-  private retainsSession(sessionId: SessionId): boolean {
-    return this.sessions.has(sessionId) || this.addresses.has(sessionId)
-      || this.summaries.some(summary => summary.sessionId === sessionId)
+  /**
+   * Identities an engagement may still belong to: the given list rows, resident
+   * Session instances, and retained child addresses.
+   * @param summaries - list rows of the caller's snapshot.
+   * @returns the retained identity set.
+   */
+  private retainedIds(summaries: readonly SessionSummary[]): Set<SessionId> {
+    const retained = new Set(summaries.map(summary => summary.sessionId))
+    for (const sessionId of this.sessions.keys()) retained.add(sessionId)
+    for (const sessionId of this.addresses.keys()) retained.add(sessionId)
+    return retained
   }
 
-  private pruneEngagement(sessionId: SessionId): void {
-    if (!this.retainsSession(sessionId)) this.engagedSessions.delete(sessionId)
+  /**
+   * Forget one engagement that no retained identity holds.
+   * @param sessionId - identity whose engagement may be dropped.
+   * @param retained - identities from {@link retainedIds} for the caller's snapshot.
+   */
+  private pruneEngagement(sessionId: SessionId, retained: ReadonlySet<SessionId>): void {
+    if (!retained.has(sessionId)) this.engagedSessions.delete(sessionId)
   }
 
   /** Resident per-session projection store (create-on-demand; outlives instantiation). */
@@ -402,12 +424,8 @@ export class SessionManager {
           const summaries = mutations.reduce(applyMutation, baseline)
           this.summaries = summaries
           // A full list can remove identities without a removal frame.
-          const listedIds = new Set(summaries.map(summary => summary.sessionId))
-          for (const sessionId of this.engagedSessions) {
-            if (!listedIds.has(sessionId) && !this.sessions.has(sessionId) && !this.addresses.has(sessionId)) {
-              this.engagedSessions.delete(sessionId)
-            }
-          }
+          const retained = this.retainedIds(summaries)
+          for (const sessionId of this.engagedSessions) this.pruneEngagement(sessionId, retained)
           this.listState = 'idle'
           this.listPhase = 'ready'
           this.updateParentAvailability()
@@ -686,7 +704,7 @@ export class SessionManager {
     if (!durableSubagent && (catalog === undefined || catalog.length === 0)) {
       this.projectionStores.delete(sessionId)
     }
-    this.pruneEngagement(sessionId)
+    this.pruneEngagement(sessionId, this.retainedIds(this.summaries))
     this.projectionInflight.get(sessionId)?.controller.abort()
     this.projectionInflight.delete(sessionId)
     this.projectionLoads.delete(sessionId)

From b882e7fc2035bc4baeb0963797b15bc75e8ffbc5 Mon Sep 17 00:00:00 2001
From: liukx0205 <harusoda@berkeley.edu>
Date: Sun, 20 Sep 2026 14:54:27 +0800
Subject: [PATCH 23/37] docs(session): record the client-local engagement
 memory limits

---
 packages/api/session-controller/README.i18n.yaml | 4 ++--
 packages/api/session-controller/README.md        | 2 ++
 packages/api/session-controller/README.zh.md     | 2 ++
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index bab878d24d..32ffc5e1cd 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: 4bbb98b0ee9224f72a571b10e8ae40d32377a747
-README.zh.md: 820dd4c3f56e964cf2b34cb50d5e5f38e35eff68
+README.md: 56d0f17b815a4616707d33bfd84b77446125f742
+README.zh.md: 9d754a5a61da548e1fd6dd10d1332582bdd3d126
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index 4bbb98b0ee..56d0f17b81 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -101,6 +101,8 @@ No direct effect; model requests remain owned by the Agent and LLM packages.
 - A failed follow resumption remains visible to the caller instead of retrying indefinitely.
 - The raw browser upload is one streaming HTTP request without resumable offsets; a retry sends the file again from byte zero.
 - File-reference completion uses the shared Agent lookup and can resume a cold Session; the `skills/list` catalog is the non-activating alternative for skill metadata.
+- Accepted/running display memory lives only in Client memory and is lost on page reload.
+- That memory is not shared between tabs: one tab can show a converted row while another still shows `New Session` for the same Session.
 
 
 <a id="dev-note"></a>
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 820dd4c3f5..9d754a5a61 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -101,6 +101,8 @@ Fork 复制 `atSeq` 所选的精确事件前缀，包含切点事件，允许在
 - follow 恢复失败会对调用方可见，而不会无限重试。
 - 浏览器原始字节上传使用一次不带断点续传偏移的流式 HTTP 请求；重试会从第零字节重新传输整个文件。
 - 文件引用补全使用共享 Agent lookup，因此可能恢复冷 Session；`skills/list` 目录是不激活 Agent 的 skill 元数据读取路径。
+- 受理/运行的展示记忆只存在于客户端内存，页面重载后即丢失。
+- 该记忆不在 tab 之间共享：同一会话可能在一个 tab 中已转正，在另一个 tab 中仍显示为 `New Session`。
 
 
 <a id="dev-note"></a>

From 5e13010b907ad24059cfda0b3ce0118d18613d23 Mon Sep 17 00:00:00 2001
From: liukx0205 <harusoda@berkeley.edu>
Date: Sun, 20 Sep 2026 14:54:27 +0800
Subject: [PATCH 24/37] test(web): document suite-level browser setup and bound
 the reconnect polls

---
 apps/web/tests/replay-round-trip.e2e.ts | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts
index 632d198e38..48b505f398 100644
--- a/apps/web/tests/replay-round-trip.e2e.ts
+++ b/apps/web/tests/replay-round-trip.e2e.ts
@@ -8,6 +8,10 @@
 // embedded Assistant stream, not transient DOM.
 // Record: DSH_SNAPSHOT=record writes session.v3.jsonl, then a keyless
 // DSH_SNAPSHOT=refresh regenerates ui.expected.md.
+// Suite setup (beforeAll, not per step): one fixed page clock
+// (page.clock.setFixedTime) and one routed Remote mux socket
+// (page.routeWebSocket) serve every step below, so the reconnect checkpoints
+// rely on both without re-pinning or re-routing them.
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -142,7 +146,7 @@ describe('web e2e: fresh round trip through the real assembly', () => {
       await compareOrRefreshGolden(ECHO_EXPECTED, echoSnapshot, MODE)
       const row = page.getByRole('tree', { name: 'Sessions', exact: true })
         .locator('[role="treeitem"][aria-selected="true"]')
-      await expect.poll(() => row.getAttribute('draggable')).toBe('true')
+      await expect.poll(() => row.getAttribute('draggable'), { timeout: 5_000 }).toBe('true')
       expect(sessionEvents.some(event => event.type === 'turn/start')).toBe(false)
 
       const disconnected = remoteSocket
@@ -172,7 +176,8 @@ describe('web e2e: fresh round trip through the real assembly', () => {
       try {
         const refreshing = page.waitForResponse(listUrl)
         const [, refreshed] = await Promise.all([disconnected.close(), refreshing])
-        await expect.poll(() => remoteSocket !== disconnected).toBe(true)
+        // Cross-network reconnect: allow more than expect.poll's default.
+        await expect.poll(() => remoteSocket !== disconnected, { timeout: 15_000 }).toBe(true)
         const baseline = await refreshed.json() as SessionListResponse
         expect(baseline.result.ok).toBe(true)
         if (!baseline.result.ok) throw new Error('the reconnect list request failed')

From fd75c47ae9e013d9b5a8d683fcb8e0464b17db8d Mon Sep 17 00:00:00 2001
From: winewill <leto.wine@gmail.com>
Date: Sun, 20 Sep 2026 15:08:57 +0800
Subject: [PATCH 25/37] fix(desktop): localize macOS application menu names

---
 apps/desktop/README.i18n.yaml                  |  4 ++--
 apps/desktop/README.md                         |  2 +-
 apps/desktop/README.zh.md                      |  2 +-
 apps/desktop/src/locale.ts                     |  8 ++++++++
 apps/desktop/src/main.ts                       |  7 +++++--
 .../tests/expected/application-menu-en-US.json | 18 ++++++++++++++++++
 .../tests/expected/application-menu-zh-CN.json | 18 ++++++++++++++++++
 apps/desktop/tests/main-startup.spec.ts        | 16 ++++++++++++++++
 8 files changed, 69 insertions(+), 6 deletions(-)
 create mode 100644 apps/desktop/tests/expected/application-menu-en-US.json
 create mode 100644 apps/desktop/tests/expected/application-menu-zh-CN.json

diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml
index 455501862e..fe73a5be76 100644
--- a/apps/desktop/README.i18n.yaml
+++ b/apps/desktop/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 apps/desktop/README.md
-README.md: 6c9a6a8784732e6fa1369df5632391b789786b22
-README.zh.md: a0f2184d911eeab46902670cf992b6847e2bca31
+README.md: da4db5806b8ca50e14fc2e95d579cbcf0e50bb77
+README.zh.md: 8d43dbde6b829555203b39d06c71b367f318e14b
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index 6c9a6a8784..da4db5806b 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The desktop application is an Electron shell around the complete dsh Web application. An Electron RunAsNode child starts the shared profile runner, and Electron immediately loads the packaged Web entry at `dsh-app://app/`. Its shared loading page waits for Host boot injections, then starts the client without navigating to another document. Electron forwards application HTTP requests to the authenticated Web Host; WebSocket streams connect to that Host with credentials attached only for the owned application window. Node IPC carries boot injections, readiness, and shutdown. Desktop defaults to port `19387`, separate from Web’s `3080`; a `webserver.config.port` patch can override it.
 
-The first application-menu command, **About DeepSeek Harness**, opens Electron's native About panel with the application icon, product name, and installed release version. The menu follows the Desktop shell locale. macOS reads the icon from its application bundle, so an unpackaged development launch displays Electron's icon; Windows receives the packaged PNG.
+The first application-menu command, **About DeepSeek Harness**, opens Electron's native About panel with the application icon, product name, and installed release version. The menu follows the Desktop shell locale. On macOS, Hide, Hide Others, Show All, and Quit use localized labels; Hide and Quit include the DeepSeek Harness product name. These commands retain their native actions and shortcuts. macOS reads the icon from its application bundle, so an unpackaged development launch displays Electron's icon; Windows receives the packaged PNG.
 
 Desktop’s local native directory flow opens an Electron folder dialog attached to the application window, restoring, showing, and focusing that window first. Concurrent requests share one dialog; cancellation returns no path and failures remain retryable. Ordinary Web uses the Host chooser. Browse mode lists Host directories. On Linux without zenity or kdialog, automatic selection uses browse instead of the Electron dialog.
 
diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md
index a0f2184d91..8d43dbde6b 100644
--- a/apps/desktop/README.zh.md
+++ b/apps/desktop/README.zh.md
@@ -4,7 +4,7 @@
 
 桌面应用是完整 dsh Web 应用外的一层 Electron 壳。Electron RunAsNode 子进程启动共享 profile runner，Electron 立即从 `dsh-app://app/` 加载打包内的 Web 入口。共享加载页等待 Host 启动注入，然后在同一文档中启动客户端。Electron 将应用 HTTP 请求转发给已认证的 Web Host；WebSocket 流连接到该 Host，仅为归属的应用窗口附加凭据。Node IPC 承载启动注入、就绪与关闭。Desktop 默认使用端口 `19387`，与 Web 的 `3080` 分开；可通过 `webserver.config.port` patch 覆盖。
 
-应用菜单第一项“**关于 DeepSeek Harness**”打开 Electron 原生关于面板，展示应用图标、产品名称和当前安装的发布版本。菜单文案跟随桌面壳的语言。macOS 从应用包读取图标，因此未打包的开发启动会显示 Electron 图标；Windows 使用随包分发的 PNG。
+应用菜单第一项“**关于 DeepSeek Harness**”打开 Electron 原生关于面板，展示应用图标、产品名称和当前安装的发布版本。菜单文案跟随桌面壳的语言。macOS 的隐藏、隐藏其他、显示全部和退出条目使用本地化文案，隐藏和退出条目包含 DeepSeek Harness 产品名称。这些条目保留原生动作和快捷键。macOS 从应用包读取图标，因此未打包的开发启动会显示 Electron 图标；Windows 使用随包分发的 PNG。
 
 Desktop 的本地原生目录流程打开绑定应用窗口的 Electron 文件夹对话框，并先恢复、显示和聚焦该窗口。并发请求共用一个对话框；取消不返回路径，失败后可以重试。普通 Web 使用 Host 选择器。浏览模式列出 Host 目录。Linux 缺少 zenity 或 kdialog 时，自动选择使用浏览模式，不使用 Electron 对话框。
 
diff --git a/apps/desktop/src/locale.ts b/apps/desktop/src/locale.ts
index 03e6f29a57..09dedf44e5 100644
--- a/apps/desktop/src/locale.ts
+++ b/apps/desktop/src/locale.ts
@@ -3,6 +3,10 @@
 export const en = {
   application: 'Application',
   aboutMenu: 'About DeepSeek Harness',
+  hideApplication: 'Hide DeepSeek Harness',
+  hideOtherApplications: 'Hide Others',
+  showAllApplications: 'Show All',
+  quitApplication: 'Quit DeepSeek Harness',
   edit: 'Edit',
   menuBar: 'Application menu',
   delete: 'Delete',
@@ -94,6 +98,10 @@ export type DesktopMessages = { readonly [Key in keyof typeof en]: string }
 export const zh = {
   application: '应用',
   aboutMenu: '关于 DeepSeek Harness',
+  hideApplication: '隐藏 DeepSeek Harness',
+  hideOtherApplications: '隐藏其他',
+  showAllApplications: '显示全部',
+  quitApplication: '退出 DeepSeek Harness',
   edit: '编辑',
   menuBar: '应用菜单',
   delete: '删除',
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index e5aa563c6e..10634b7626 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -613,7 +613,9 @@ async function main(): Promise<void> {
     ? [{ role: 'fileMenu' }, { role: 'editMenu' }, { role: 'windowMenu' }]
     : [{ role: 'editMenu' }]
   const hideCommands: MenuItemConstructorOptions[] = darwin
-    ? [{ role: 'hide' }, { role: 'hideOthers' }, { role: 'unhide' }, { type: 'separator' }]
+    ? [{ role: 'hide', label: currentDesktopLocale().messages.hideApplication },
+      { role: 'hideOthers', label: currentDesktopLocale().messages.hideOtherApplications },
+      { role: 'unhide', label: currentDesktopLocale().messages.showAllApplications }, { type: 'separator' }]
     : []
   const applicationItems = (): MenuItemConstructorOptions[] => [
     { label: currentDesktopLocale().messages.aboutMenu, role: 'about' },
@@ -621,7 +623,8 @@ async function main(): Promise<void> {
     { label: currentDesktopLocale().messages.checkUpdatesMenu, click: () => { void openUpdatePrompt(true) } },
     { type: 'separator' },
     ...hideCommands,
-    { role: 'quit', ...(process.platform === 'win32' ? { label: currentDesktopLocale().messages.exitApplication } : {}) },
+    { role: 'quit', ...(darwin ? { label: currentDesktopLocale().messages.quitApplication }
+      : process.platform === 'win32' ? { label: currentDesktopLocale().messages.exitApplication } : {}) },
   ]
   Menu.setApplicationMenu(process.platform === 'win32' ? null : Menu.buildFromTemplate([{
     label: darwin ? app.name : currentDesktopLocale().messages.application,
diff --git a/apps/desktop/tests/expected/application-menu-en-US.json b/apps/desktop/tests/expected/application-menu-en-US.json
new file mode 100644
index 0000000000..af72c9b264
--- /dev/null
+++ b/apps/desktop/tests/expected/application-menu-en-US.json
@@ -0,0 +1,18 @@
+[
+  {
+    "role": "hide",
+    "label": "Hide DeepSeek Harness"
+  },
+  {
+    "role": "hideOthers",
+    "label": "Hide Others"
+  },
+  {
+    "role": "unhide",
+    "label": "Show All"
+  },
+  {
+    "role": "quit",
+    "label": "Quit DeepSeek Harness"
+  }
+]
diff --git a/apps/desktop/tests/expected/application-menu-zh-CN.json b/apps/desktop/tests/expected/application-menu-zh-CN.json
new file mode 100644
index 0000000000..991b9d7639
--- /dev/null
+++ b/apps/desktop/tests/expected/application-menu-zh-CN.json
@@ -0,0 +1,18 @@
+[
+  {
+    "role": "hide",
+    "label": "隐藏 DeepSeek Harness"
+  },
+  {
+    "role": "hideOthers",
+    "label": "隐藏其他"
+  },
+  {
+    "role": "unhide",
+    "label": "显示全部"
+  },
+  {
+    "role": "quit",
+    "label": "退出 DeepSeek Harness"
+  }
+]
diff --git a/apps/desktop/tests/main-startup.spec.ts b/apps/desktop/tests/main-startup.spec.ts
index 171e3855f1..3c792be2eb 100644
--- a/apps/desktop/tests/main-startup.spec.ts
+++ b/apps/desktop/tests/main-startup.spec.ts
@@ -672,6 +672,22 @@ describe('desktop main startup', () => {
     expect(harness.menu.setApplicationMenu).toHaveBeenCalledOnce()
   })
 
+  it.each(['en-US', 'zh-CN'])('localizes macOS visibility and quit commands without changing the application name (%s)', async (locale) => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
+    vi.spyOn(harness.app, 'getLocale').mockReturnValue(locale)
+    const originalName = harness.app.name
+    harness.app.name = '@deepseek-ai/dsh-desktop'
+    try {
+      await import('../src/main.ts')
+      await harness.preparing.promise
+      const commands = applicationMenuItems().filter(item =>
+        item.role === 'hide' || item.role === 'hideOthers' || item.role === 'unhide' || item.role === 'quit')
+      await expect(JSON.stringify(commands, null, 2) + '\n')
+        .toMatchFileSnapshot(`./expected/application-menu-${locale}.json`)
+      expect(harness.app.name).toBe('@deepseek-ai/dsh-desktop')
+    } finally { harness.app.name = originalName }
+  })
+
   it('attaches Host socket credentials only to the owned application origin and window', async () => {
     await import('../src/main.ts')
     await harness.preparing.promise

From a978ad1994aa27f9c69daad9436bdb547fd3caf8 Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sun, 20 Sep 2026 15:09:37 +0800
Subject: [PATCH 26/37] fix(subagent): version unknown catalog payloads locally

---
 ...session-local-subagent-migration.i18n.yaml |    4 +-
 ...-09-19-session-local-subagent-migration.md |    2 +-
 ...-19-session-local-subagent-migration.zh.md |    2 +-
 ...6-09-11-persistence-type-history.i18n.yaml |    4 +-
 .../2026-09-11-persistence-type-history.md    |    2 +-
 .../2026-09-11-persistence-type-history.zh.md |    2 +-
 apps/web/tests/preset-migration.snapshot.ts   |    2 +-
 docs/persistence-catalog.i18n.yaml            |    4 +-
 docs/persistence-catalog.md                   |   54 +-
 docs/persistence-catalog.zh.md                |   54 +-
 ...2026-09-20-unknown-child-catalog.i18n.yaml |    4 +-
 .../2026-09-20-unknown-child-catalog.md       |    6 +-
 ...26-09-20-unknown-child-catalog.schema.json |   86 +-
 .../2026-09-20-unknown-child-catalog.zh.md    |    6 +-
 docs/persistence-changes/README.i18n.yaml     |    4 +-
 docs/persistence-changes/README.md            |    6 +-
 docs/persistence-changes/README.zh.md         |    6 +-
 .../historical-formats/README.i18n.yaml       |    4 +-
 .../historical-formats/README.md              |    2 +-
 .../historical-formats/README.zh.md           |    2 +-
 docs/persistence-schema.json                  | 1076 +++++++++++------
 packages/sdk/client/tests/sdk-client.spec.ts  |    2 +-
 .../session-format-v3-to-v4/README.i18n.yaml  |    4 +-
 .../session/session-format-v3-to-v4/README.md |    6 +-
 .../session-format-v3-to-v4/README.zh.md      |    6 +-
 .../session-format-v3-to-v4/src/facts.ts      |    5 +-
 .../session-format-v3-to-v4/src/migration.ts  |    2 +-
 .../tests/catalog-completion.spec.ts          |   10 +-
 .../tests/validation.spec.ts                  |    4 +-
 packages/subagent/subagent/README.i18n.yaml   |    4 +-
 packages/subagent/subagent/README.md          |    2 +-
 packages/subagent/subagent/README.zh.md       |    2 +-
 packages/subagent/subagent/src/catalog.ts     |   24 +-
 .../subagent/subagent/tests/catalog.spec.ts   |   16 +-
 python/sdk/tests/test_client.py               |    2 +-
 scripts/no-unknown-casts.baseline.json        |    2 -
 scripts/persistence-changes.spec.ts           |   79 +-
 scripts/persistence-changes.ts                |   45 +-
 38 files changed, 1005 insertions(+), 542 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
index 8b543c4f2b..e2f0f66dda 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.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-09-19-session-local-subagent-migration.md
-2026-09-19-session-local-subagent-migration.md: a44b6cdfe37656fc112f06187ef0c884e8b2fae1
-2026-09-19-session-local-subagent-migration.zh.md: e1c790d4e19dbc0bab962592d9ff14b2e94fbdb0
+2026-09-19-session-local-subagent-migration.md: 26911ea6e2cb31126d13e4c8c6488ff3b45563e6
+2026-09-19-session-local-subagent-migration.zh.md: 673040a3dc73d3665e42013a4704ef2d5911b23d
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
index a44b6cdfe3..26911ea6e2 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
@@ -28,6 +28,6 @@ This partially supersedes child-failure propagation in [released migrations](../
 
 ## Consequences
 
-Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. Unknown entries are not automatically rewritten after publication. Opening a child retries its log and determines browsing capabilities from its actual descriptor, or reports the child-local error. Catalog mode adds `unknown` without changing existing alternatives or the V4 header. The persistence checker admits this scoped extension; older readers may reject records using the new mode.
+Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. Unknown entries are not automatically rewritten after publication. Opening a child retries its log and determines browsing capabilities from its actual descriptor, or reports the child-local error. Catalog payload v0 retains its two known modes; v1 also supports `unknown`. Readers support both versions; healthy creation and complete historical facts retain v0, while unknown migration facts use v1. The V4 Session header is unchanged, and older readers reject the new payload version.
 
 Raw and compressed tests cover catalog completion, child-local errors, source changes and repairs, unchanged child generations, and deferred child-catalog preparation. The shipped Web migration snapshot checks the parent catalog with a corrupt sibling, then opens the child independently. Its additional historical child raises the corpus budget from ten to eleven roles; the guard rejects a twelfth role.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
index e1c790d4e1..673040a3dc 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
@@ -28,6 +28,6 @@ JSONL 在发现时跳过不可读或不支持的 header。子正文或 descripto
 
 ## 后果
 
-首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。发布后不自动重写未知条目。打开子会话会重试其日志，根据实际 descriptor 确定浏览能力，或报告该子会话的错误。Catalog mode 增加 `unknown`，既有分支和 V4 header 保持不变。持久化检查允许这项限定扩展；旧读取器可能拒绝使用新模式的记录。
+首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。发布后不自动重写未知条目。打开子会话会重试其日志，根据实际 descriptor 确定浏览能力，或报告该子会话的错误。Catalog 载荷 v0 保留两种已知模式，v1 另支持 `unknown`。读取器支持两版；正常创建及完整历史事实继续使用 v0，未知迁移事实使用 v1。V4 Session header 不变，旧读取器拒绝新载荷版本。
 
 原始和压缩测试覆盖目录补齐、子会话错误隔离、来源变化与修复、子代际不变和延后的子目录准备。随产品 Web 迁移快照在损坏兄弟存在时检查父目录，再独立打开子会话。额外的历史子角色使语料预算由十个增加到十一个；守卫拒绝第十二个角色。
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
index 30c4c0961b..969ab3fd9e 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.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/process/2026-09-11-persistence-type-history.md
-2026-09-11-persistence-type-history.md: a5c50a871ebdb583c7e955944b03f4e082c69fe2
-2026-09-11-persistence-type-history.zh.md: 8fc42ccd9964d7eab254da8bb8c40ae055ff1152
+2026-09-11-persistence-type-history.md: 87e87041dd44c4f671409a75c1b374312736342a
+2026-09-11-persistence-type-history.zh.md: cfe5c4f7bd1998d4329dc422607cfe33273d1a5a
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
index a5c50a871e..87e87041dd 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
@@ -14,7 +14,7 @@ One normalized type model supplies the readable persistence catalog, the complet
 
 The dedicated [persistence-change records](../../../../docs/persistence-changes/README.md) bind acknowledgement to the after digest of each affected root. A generated companion stores complete after schemas. The initial record covers all roots; later records name each root's predecessor. A predecessor's after schema supplies the next before schema. Verification rejects ambiguous history and requires current source to match the terminal recorded state without consulting Git history or remote services.
 
-Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped [source-attribution policy](2026-09-17-persistence-schema-review.md) also permits qualified new producer kinds when both saved schemas opt in. The [catalog exception](../../../../docs/persistence-changes/README.md#compatibility-rules) admits unknown child mode with unchanged identity fields and records the older-reader limitation. Other structural changes require a version-bump decision that includes an increasing header version in that record. The [format-version procedure](../../../../docs/cookbook/adding-a-session-format-version.md) continues to own adjacent migration work. Every structural difference requires an explicit record, including additions allowed within the same version.
+Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped [source-attribution policy](2026-09-17-persistence-schema-review.md) also permits qualified new producer kinds when both saved schemas opt in. The [event-payload version rule](../../../../docs/persistence-changes/README.md#compatibility-rules) admits higher numeric payload versions when every old alternative remains unchanged and records the older-reader limitation. Other structural changes require a version-bump decision that includes an increasing header version in that record. The [format-version procedure](../../../../docs/cookbook/adding-a-session-format-version.md) continues to own adjacent migration work. Every structural difference requires an explicit record, including additions allowed within the same version.
 
 The new document kind preserves the compatibility reasoning and evidence for a historical type transition. Agent Notes retain mechanism-level decisions; they do not become a growing inventory of individual acknowledgements. Machine declarations remain identical across the bilingual pair and are parsed once.
 
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
index 8fc42ccd99..cfe5c4f7bd 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 专用的[持久化变更记录](../../../../docs/persistence-changes/README.zh.md)将确认绑定到每个受影响根的变更后摘要。生成的伴随文件保存完整的变更后 schema。初始记录覆盖所有根；后续记录为每个根指定前驱。前驱的变更后 schema 提供下一次的变更前 schema。验证拒绝有歧义的历史，并要求当前源码匹配最终记录状态，无需查询 Git 历史或远端服务。
 
-自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的[消息源归属策略](2026-09-17-persistence-schema-review.zh.md)也允许添加符合条件的生产者 kind。[Catalog 例外](../../../../docs/persistence-changes/README.zh.md#compatibility-rules) 允许增加身份字段不变的未知子模式，并记录旧读取器限制。其他结构变更需要升版本决策，并在该记录中包含递增的头部版本。[格式版本流程](../../../../docs/cookbook/adding-a-session-format-version.zh.md)继续负责相邻迁移工作。每个结构差异都需要显式记录，包括允许保持同一版本的新增。
+自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的[消息源归属策略](2026-09-17-persistence-schema-review.zh.md)也允许添加符合条件的生产者 kind。[事件载荷版本规则](../../../../docs/persistence-changes/README.zh.md#compatibility-rules) 允许在原样保留所有旧分支时增加更高的数字载荷版本，并记录旧读取器限制。其他结构变更需要升版本决策，并在该记录中包含递增的头部版本。[格式版本流程](../../../../docs/cookbook/adding-a-session-format-version.zh.md)继续负责相邻迁移工作。每个结构差异都需要显式记录，包括允许保持同一版本的新增。
 
 新文档类型保留历史类型转换的兼容性说明和证据。Agent Note 保留机制层面的决策，不积累单次确认清单。双语对中的机器声明保持相同，且只解析一次。
 
diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts
index 530a0f3ef9..42e69f65ef 100644
--- a/apps/web/tests/preset-migration.snapshot.ts
+++ b/apps/web/tests/preset-migration.snapshot.ts
@@ -109,7 +109,7 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
           ? { ...row, data: { agentPreset: 'ptc' } }
           : row),
         { type: 'subagent/catalog', seq: rows.length, time: rows.at(-1)?.['time'], data: {
-          version: 0, childId: brokenId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'unknown',
+          version: 1, childId: brokenId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'unknown',
         } },
         { type: 'subagent/catalog', seq: rows.length + 1, time: rows.at(-1)?.['time'], data: {
           version: 0, childId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'one-shot', label: 'historical child',
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 43982e1667..5f847038ca 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: 0733c6880cf65e445b35c2dea0589b7ce93a96b8
-persistence-catalog.zh.md: c4f4870fb8d712b43502579ecfd7adae8d74a535
+persistence-catalog.md: 11cea4328db6e69c1ee08994a6d36fe26e308a7c
+persistence-catalog.zh.md: 6207dc17023e566f73cb1e0c7cba40533a4a96ff
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 0733c6880c..11cea4328d 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -57,7 +57,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover
 | `event:session/title-llm-request` | event | `fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d) |
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
-| `event:subagent/catalog` | event | `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3) |
+| `event:subagent/catalog` | event | `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -900,7 +900,7 @@ Source: [`packages/core/session/src/types.ts:299`](../packages/core/session/src/
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-Source: [`packages/subagent/subagent/src/catalog.ts:41`](../packages/subagent/subagent/src/catalog.ts)
+Source: [`packages/subagent/subagent/src/catalog.ts:43`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -4555,7 +4555,7 @@ One of:
 - [`{ type: "finish" }`](#persistence-type-sha256-a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1)
 - [`{ type: "usage" }`](#persistence-type-sha256-f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515)
 
-<a id="persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce"></a>
+<a id="persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0"></a>
 
 <a id="persistence-type-packagessubagentsubagentsrccatalogtssubagentcatalogevent"></a>
 
@@ -4563,15 +4563,17 @@ One of:
 
 ### `SubagentCatalogEvent`
 
-SHA-256: `30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce`
+SHA-256: `1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0`
 
-Sources: [`packages/subagent/subagent/src/catalog.ts:24`](../packages/subagent/subagent/src/catalog.ts)
+Sources: [`packages/subagent/subagent/src/catalog.ts:28`](../packages/subagent/subagent/src/catalog.ts)
 
 One of:
 
 - [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd)
+- [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187)
 - [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694)
-- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499)
 
 <a id="persistence-type-sha256-86d1d0e9cfebb240421187e3dc37fb71cc38a1501885cf32f8f9adef7b0a2bde"></a>
 
@@ -5621,6 +5623,20 @@ SHA-256: `0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd`
 | `mode` | required | `"continuable"` |
 | `version` | required | `0` |
 
+<a id="persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187"></a>
+
+### `{ childCreatedAt, childId, label, mode, … }`
+
+SHA-256: `e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187`
+
+| Property | Presence | Type |
+|---|---|---|
+| `childCreatedAt` | required | `number` |
+| `childId` | required | `string` |
+| `label` | required | `string` |
+| `mode` | required | `"continuable"` |
+| `version` | required | `1` |
+
 <a id="persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694"></a>
 
 ### `{ childCreatedAt, childId, label?, mode, … }`
@@ -5635,11 +5651,11 @@ SHA-256: `5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694`
 | `mode` | required | `"one-shot"` |
 | `version` | required | `0` |
 
-<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
+<a id="persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499"></a>
 
 ### `{ childCreatedAt, childId, label?, mode, … }`
 
-SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
+SHA-256: `a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499`
 
 | Property | Presence | Type |
 |---|---|---|
@@ -5647,7 +5663,21 @@ SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
 | `childId` | required | `string` |
 | `label` | optional | `string` |
 | `mode` | required | `"unknown"` |
-| `version` | required | `0` |
+| `version` | required | `1` |
+
+<a id="persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a`
+
+| Property | Presence | Type |
+|---|---|---|
+| `childCreatedAt` | required | `number` |
+| `childId` | required | `string` |
+| `label` | optional | `string` |
+| `mode` | required | `"one-shot"` |
+| `version` | required | `1` |
 
 <a id="persistence-type-sha256-a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735"></a>
 
@@ -8244,17 +8274,17 @@ SHA-256: `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986`
 | `time` | required | `number` |
 | `type` | required | `"step/start"` |
 
-<a id="persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"></a>
+<a id="persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"></a>
 
 <a id="persistence-type-eventsubagentcatalog"></a>
 
 ### `{ type: "subagent/catalog" }`
 
-SHA-256: `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3`
+SHA-256: `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604`
 
 | Property | Presence | Type |
 |---|---|---|
-| `data` | required | [`SubagentCatalogEvent`](#persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce) |
+| `data` | required | [`SubagentCatalogEvent`](#persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0) |
 | `ignorable` | optional | `true` |
 | `seq` | required | `number` |
 | `time` | required | `number` |
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index c4f4870fb8..6207dc1702 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -59,7 +59,7 @@
 | `event:session/title-llm-request` | event | `fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d) |
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
-| `event:subagent/catalog` | event | `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3) |
+| `event:subagent/catalog` | event | `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -902,7 +902,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-来源：[`packages/subagent/subagent/src/catalog.ts:41`](../packages/subagent/subagent/src/catalog.ts)
+来源：[`packages/subagent/subagent/src/catalog.ts:43`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -4557,7 +4557,7 @@ SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180`
 - [`{ type: "finish" }`](#persistence-type-sha256-a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1)
 - [`{ type: "usage" }`](#persistence-type-sha256-f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515)
 
-<a id="persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce"></a>
+<a id="persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0"></a>
 
 <a id="persistence-type-packagessubagentsubagentsrccatalogtssubagentcatalogevent"></a>
 
@@ -4565,15 +4565,17 @@ SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180`
 
 ### `SubagentCatalogEvent`
 
-SHA-256: `30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce`
+SHA-256: `1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0`
 
-来源：[`packages/subagent/subagent/src/catalog.ts:24`](../packages/subagent/subagent/src/catalog.ts)
+来源：[`packages/subagent/subagent/src/catalog.ts:28`](../packages/subagent/subagent/src/catalog.ts)
 
 以下类型之一：
 
 - [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd)
+- [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187)
 - [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694)
-- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499)
 
 <a id="persistence-type-sha256-86d1d0e9cfebb240421187e3dc37fb71cc38a1501885cf32f8f9adef7b0a2bde"></a>
 
@@ -5623,6 +5625,20 @@ SHA-256: `0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd`
 | `mode` | 必需 | `"continuable"` |
 | `version` | 必需 | `0` |
 
+<a id="persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187"></a>
+
+### `{ childCreatedAt, childId, label, mode, … }`
+
+SHA-256: `e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187`
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `childCreatedAt` | 必需 | `number` |
+| `childId` | 必需 | `string` |
+| `label` | 必需 | `string` |
+| `mode` | 必需 | `"continuable"` |
+| `version` | 必需 | `1` |
+
 <a id="persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694"></a>
 
 ### `{ childCreatedAt, childId, label?, mode, … }`
@@ -5637,11 +5653,11 @@ SHA-256: `5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694`
 | `mode` | 必需 | `"one-shot"` |
 | `version` | 必需 | `0` |
 
-<a id="persistence-type-sha256-c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca"></a>
+<a id="persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499"></a>
 
 ### `{ childCreatedAt, childId, label?, mode, … }`
 
-SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
+SHA-256: `a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499`
 
 | 属性 | 存在性 | 类型 |
 |---|---|---|
@@ -5649,7 +5665,21 @@ SHA-256: `c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca`
 | `childId` | 必需 | `string` |
 | `label` | 可选 | `string` |
 | `mode` | 必需 | `"unknown"` |
-| `version` | 必需 | `0` |
+| `version` | 必需 | `1` |
+
+<a id="persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a`
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `childCreatedAt` | 必需 | `number` |
+| `childId` | 必需 | `string` |
+| `label` | 可选 | `string` |
+| `mode` | 必需 | `"one-shot"` |
+| `version` | 必需 | `1` |
 
 <a id="persistence-type-sha256-a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735"></a>
 
@@ -8246,17 +8276,17 @@ SHA-256: `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986`
 | `time` | 必需 | `number` |
 | `type` | 必需 | `"step/start"` |
 
-<a id="persistence-type-sha256-4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"></a>
+<a id="persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"></a>
 
 <a id="persistence-type-eventsubagentcatalog"></a>
 
 ### `{ type: "subagent/catalog" }`
 
-SHA-256: `4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3`
+SHA-256: `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604`
 
 | 属性 | 存在性 | 类型 |
 |---|---|---|
-| `data` | 必需 | [`SubagentCatalogEvent`](#persistence-type-sha256-30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce) |
+| `data` | 必需 | [`SubagentCatalogEvent`](#persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0) |
 | `ignorable` | 可选 | `true` |
 | `seq` | 必需 | `number` |
 | `time` | 必需 | `number` |
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml b/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
index d393e07ce1..60ad1d8f73 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
+++ b/docs/persistence-changes/2026-09-20-unknown-child-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-changes/2026-09-20-unknown-child-catalog.md
-2026-09-20-unknown-child-catalog.md: 58e8a8ffedb7b3b913c9e04590ce5bbabd148ba6
-2026-09-20-unknown-child-catalog.zh.md: 488899ecadcdc93910927c80b22b8fcf0d319224
+2026-09-20-unknown-child-catalog.md: ba729661d60856ff948854641a1520339ab30210
+2026-09-20-unknown-child-catalog.zh.md: 468b4c9a3d3afab56ec8a9b03359016c9c0307e0
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
index 58e8a8ffed..ba729661d6 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
@@ -28,19 +28,19 @@ baseline: false
 changes:
   - root: "event:subagent/catalog"
     previous: "2026-09-11-initial"
-    after: "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"
+    after: "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"
     decision: same-version
 ```
 
 <a id="compatibility"></a>
 ## Compatibility
 
-The catalog adds one unknown-mode alternative with the same identity and optional label fields as one-shot mode. Existing alternatives and the V4 header remain unchanged. New readers accept old records; older readers may reject records with unknown mode. The persistence classifier has a scoped catalog exception for this addition, while other union additions and modifications remain strict. Unknown membership grants no continuation capability.
+Catalog payload v0 remains unchanged. Payload v1 adds unknown mode, and current readers accept v0 and v1. Complete facts still use v0; migration emits v1 for unknown children. Existing logs need no rewrite, and the Session header remains V4. Older readers reject v1. The classifier allows higher event payload versions only when all old payload alternatives remain unchanged; same-version widening and removal of old readers stay breaking.
 
 <a id="verification"></a>
 ## Verification
 
-Catalog migration, restoration, projection, and Web regressions cover retained unknown membership and child-local errors. Persistence classifier tests accept the exact catalog extension and reject altered existing fields, other new modes, extra unknown fields, removals, and unrelated union additions.
+Migration, restoration, projection, and Web regressions retain unknown membership and child-local errors. Classifier tests accept higher payload versions with preserved predecessors and reject same-version additions, invalid versions, changed or removed old alternatives, and header/surface changes.
 
 <a id="dev-note"></a>
 ## Dev Note
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
index ce4dd23ac3..14c4b254ad 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
@@ -6,7 +6,7 @@
       "kind": "event",
       "event": "subagent/catalog",
       "surface": false,
-      "digest": "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3",
+      "digest": "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604",
       "schema": {
         "root": 0,
         "nodes": [
@@ -20,7 +20,7 @@
               },
               {
                 "name": "ignorable",
-                "type": 11,
+                "type": 14,
                 "optional": true
               },
               {
@@ -35,7 +35,7 @@
               },
               {
                 "name": "type",
-                "type": 12,
+                "type": 15,
                 "optional": false
               }
             ],
@@ -46,7 +46,9 @@
             "types": [
               2,
               7,
-              9
+              9,
+              11,
+              12
             ]
           },
           {
@@ -65,7 +67,7 @@
               {
                 "name": "label",
                 "type": 4,
-                "optional": true
+                "optional": false
               },
               {
                 "name": "mode",
@@ -90,7 +92,7 @@
           },
           {
             "kind": "literal",
-            "value": "unknown"
+            "value": "continuable"
           },
           {
             "kind": "literal",
@@ -116,12 +118,12 @@
               },
               {
                 "name": "mode",
-                "type": 8,
+                "type": 5,
                 "optional": false
               },
               {
                 "name": "version",
-                "type": 6,
+                "type": 8,
                 "optional": false
               }
             ],
@@ -129,7 +131,7 @@
           },
           {
             "kind": "literal",
-            "value": "continuable"
+            "value": 1
           },
           {
             "kind": "object",
@@ -166,6 +168,72 @@
             "kind": "literal",
             "value": "one-shot"
           },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
           {
             "kind": "literal",
             "value": true
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
index 488899ecad..468b4c9a3d 100644
--- a/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
@@ -28,19 +28,19 @@ baseline: false
 changes:
   - root: "event:subagent/catalog"
     previous: "2026-09-11-initial"
-    after: "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3"
+    after: "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"
     decision: same-version
 ```
 
 <a id="compatibility"></a>
 ## 兼容性
 
-Catalog 增加一个 unknown 模式分支，身份与可选 label 字段和 one-shot 模式相同。已有分支及 V4 header 保持不变。新读取器接受旧记录；旧读取器可能拒绝 unknown 模式记录。持久化分类器仅为该 catalog 扩展设置限定例外，其他联合类型新增与修改仍严格检查。未知成员关系不授予继续执行能力。
+Catalog 载荷 v0 保持不变。载荷 v1 增加 unknown 模式，当前读取器支持 v0 和 v1。完整事实继续使用 v0；迁移为未知子会话写入 v1。已有日志无需改写，Session header 保持 V4。旧读取器拒绝 v1。分类器仅在所有旧载荷分支保持不变时允许增加更高的事件载荷版本；同版本扩展和移除旧版读取支持仍属于破坏性变更。
 
 <a id="verification"></a>
 ## 验证
 
-Catalog 迁移、恢复、投影和 Web 回归覆盖未知成员保留与子会话局部报错。持久化分类器测试接受此 catalog 扩展，并拒绝已有字段修改、其他新增模式、未知分支额外字段、删除及无关联合类型新增。
+迁移、恢复、投影和 Web 回归覆盖未知成员保留与子会话局部报错。分类器测试接受保留前代的更高载荷版本，并拒绝同版本新增、无效版本、旧分支修改或删除，以及 header/model-surface 变更。
 
 <a id="dev-note"></a>
 ## 开发备注
diff --git a/docs/persistence-changes/README.i18n.yaml b/docs/persistence-changes/README.i18n.yaml
index ea39a60513..c2d80f8829 100644
--- a/docs/persistence-changes/README.i18n.yaml
+++ b/docs/persistence-changes/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 docs/persistence-changes/README.md
-README.md: 1e7c7b7aec8ecf6687b37f36544dccb4c8e4c4f5
-README.zh.md: d6a315acb42a82a926fc323370b52c1a1b61065e
+README.md: 2f3d2dd50adee751d9dce9ab250649ae13e45521
+README.zh.md: d2cec933b2210cc5652a7aa6c725517e1baff948
diff --git a/docs/persistence-changes/README.md b/docs/persistence-changes/README.md
index 1e7c7b7aec..2f3d2dd50a 100644
--- a/docs/persistence-changes/README.md
+++ b/docs/persistence-changes/README.md
@@ -53,18 +53,18 @@ Every detected structural change requires an acknowledgement. Record creation an
 | Add an optional event-body property, including its complete subtree | `same-version` |
 | Make a required event-body property optional | `same-version` |
 | Add an ordinary event type | `same-version` |
-| Add `unknown` mode to `subagent/catalog` using the one-shot fields, while preserving existing alternatives | `same-version` |
+| Add a higher numeric `data.version` to an ordinary event while retaining every old payload alternative unchanged | `same-version` |
 | Add an explicitly qualified attribution kind to a user/developer source slot whose before and after schemas carry the same supported policy | `same-version` |
 | Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | `version-bump` |
 | Change the Session header or event envelope | `version-bump` |
 
 A finalized checkpoint protects the accepted baseline without replacing these compatibility rules. At V4, optional additions, ordinary events, and qualified attribution additions can receive new same-version records. Breaking differences require a higher writer version and an acknowledgement containing its own header increase. The accepted V4 record cannot be updated to reuse its original 3→4 transition.
 
-The catalog exception retains a historical child's identity when its descriptor is unavailable. It admits only an `unknown` alternative with the same fields as the one-shot alternative; existing alternatives still receive ordinary comparison. It does not permit other mode additions, removals, header changes, or arbitrary union extensions. Existing logs remain readable by the updated reader; older readers may reject the new mode. The [acknowledgement](2026-09-20-unknown-child-catalog.md) records this forward-read limitation.
+An ordinary event may add payload alternatives with a required, nonnegative integer `data.version` greater than every existing payload version, provided all existing alternatives remain structurally unchanged. The reader must retain support for the old payloads; adding variants at an existing version, dropping old versions, and changing the Session header or envelope remain breaking. Older readers may reject the new payload version. The [catalog acknowledgement](2026-09-20-unknown-child-catalog.md) records one such transition.
 
 The extractor accepts an explicit `@persistenceSource` binding for a core-owned source property on a literal user or developer role; it does not infer a binding from an unannotated type. A producer qualifies its `MessageSourceMap` entry with `@persistenceAttribution`. Qualification promises that an unknown kind and its JSON metadata survive reading without the producer, and that the kind imposes no validation, replay, or authority requirement. A producer may inspect its own kind to resume duplicate suppression; other readers must preserve and derive the recorded messages without that projection. The recorded schema retains the binding, policy version, literal `kind` discriminator, preservation promise, and qualified kind set. Inventory format 2 stores those promises; extraction without a bound policy retains format 1. Session format versions are independent. Both compared snapshots must carry compatible policy state. Existing kind groups still receive ordinary structural comparison; removals, unmarked additions, policy changes, and unrelated breaking changes remain strict. Multiple context-form alternatives with the same wire kind form one group.
 
-A same-version explanation states why old records can omit the addition and why older readers can ignore it without changing replay. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
+A same-version explanation states how old records remain readable and how older readers handle new records. Optional additions explain why older readers can ignore them without changing replay; a new payload version records the older-reader rejection. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
 
 When a reader rejects a JSON property by name, declare the property as optional `never` and mark it with argument-free `@persistenceReserved`. The extractor retains the forbidden field, so allowing a JSON value later requires an existing-field type change. Required or JSON-valued properties cannot carry this marker. Unmarked optional `never` and `undefined` properties retain their existing omission behavior.
 
diff --git a/docs/persistence-changes/README.zh.md b/docs/persistence-changes/README.zh.md
index d6a315acb4..d2cec933b2 100644
--- a/docs/persistence-changes/README.zh.md
+++ b/docs/persistence-changes/README.zh.md
@@ -53,18 +53,18 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
 | 添加可选事件体属性，包括其完整子树 | `same-version` |
 | 将必选事件体属性改为可选 | `same-version` |
 | 添加普通事件类型 | `same-version` |
-| 为 `subagent/catalog` 增加使用 one-shot 字段的 `unknown` 模式，并保留既有分支 | `same-version` |
+| 为普通事件增加更高的数字 `data.version`，并原样保留所有旧载荷分支 | `same-version` |
 | 在前后 schema 均带有相同受支持策略的 user/developer 消息源字段中，添加显式声明为归属信息的 kind | `same-version` |
 | 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | `version-bump` |
 | 更改会话头或事件封装 | `version-bump` |
 
 定稿检查点保护已接受基线，不替换这些兼容性规则。在 V4 中，可选新增、普通事件及符合条件的归属 kind 新增可以使用新的同版本记录。破坏性差异要求更高的写入器版本，以及包含自身头版本递增的确认记录。不能更新已接受 V4 记录以复用其原有 3→4 转换。
 
-Catalog 例外在 descriptor 不可用时保留历史子会话身份。它仅允许增加字段与 one-shot 分支相同的 `unknown` 分支；已有分支仍执行常规比较。它不允许其他模式新增、删除、header 变更或任意联合类型扩展。新版读取器仍可读取已有日志；旧版读取器可能拒绝新模式。[确认记录](2026-09-20-unknown-child-catalog.zh.md) 说明这一向前读取限制。
+普通事件可增加具有必选、非负整数 `data.version` 的载荷分支，新版本必须高于所有已有载荷版本，且所有已有分支结构保持不变。读取器必须保留旧载荷支持；在已有版本中增加分支、移除旧版本，以及修改 Session header 或事件封装仍属于破坏性变更。旧读取器可能拒绝新载荷版本。[Catalog 确认记录](2026-09-20-unknown-child-catalog.zh.md) 记录了此类演进。
 
 提取器接受核心拥有的 source 属性上针对 user 或 developer 字面量角色的显式 `@persistenceSource` 绑定，不会从未标记类型中推断绑定。生产者用 `@persistenceAttribution` 标记其 `MessageSourceMap` 成员。该标记承诺：读取器无需生产者即可保留未知 kind 及其 JSON 元数据，且该 kind 不引入校验、回放或权限要求。生产者可以检查自身 kind 来恢复去重状态；其他读取器必须无需该投影也能保留并派生已记录的消息。记录的 schema 保存绑定、策略版本、字面量 `kind` 判别字段、保留承诺及符合条件的 kind 集合。Inventory format 2 保存这些承诺；没有绑定策略的提取仍使用 format 1。Session 格式版本独立于此。比较双方的快照必须带有兼容的策略状态。已有 kind 分组仍进行常规结构比较；删除、未标记的添加、策略更改及无关破坏性变更继续采用严格规则。同一 wire kind 的多个上下文形式分支归为一组。
 
-同版本说明须解释旧记录为何可以缺少新增内容，以及旧读取器为何可以忽略它而不改变回放。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
+同版本说明须解释旧记录如何保持可读，以及旧读取器如何处理新记录。可选新增须说明旧读取器为何可以忽略它而不改变回放；新增载荷版本须记录旧读取器的拒绝行为。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
 
 当读取器按属性名拒绝 JSON 字段时，将该属性声明为可选 `never`，并添加无参数的 `@persistenceReserved` 标记。提取器保留这一禁止字段，因此后续允许 JSON 值属于已有字段类型变更。必选属性或允许 JSON 值的属性不能携带该标记。未标记的可选 `never` 和 `undefined` 属性保留现有省略行为。
 
diff --git a/docs/persistence-changes/historical-formats/README.i18n.yaml b/docs/persistence-changes/historical-formats/README.i18n.yaml
index f34e60f4e7..1f6bfd547a 100644
--- a/docs/persistence-changes/historical-formats/README.i18n.yaml
+++ b/docs/persistence-changes/historical-formats/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 docs/persistence-changes/historical-formats/README.md
-README.md: f4e721bbef9d442021226c573280edc193792662
-README.zh.md: be4b7c86b68fa682e7f8275f85a2548f39f30df9
+README.md: a1064e815879d709fe466441bb4e8441c10b3aae
+README.zh.md: 87c9d32fa6ca5248886dad663a926afc6983406f
diff --git a/docs/persistence-changes/historical-formats/README.md b/docs/persistence-changes/historical-formats/README.md
index f4e721bbef..a1064e8158 100644
--- a/docs/persistence-changes/historical-formats/README.md
+++ b/docs/persistence-changes/historical-formats/README.md
@@ -32,7 +32,7 @@ The index is generated from validated snapshots and the current writer constant.
 | 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 585 |
+| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 587 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-changes/historical-formats/README.zh.md b/docs/persistence-changes/historical-formats/README.zh.md
index be4b7c86b6..87c9d32fa6 100644
--- a/docs/persistence-changes/historical-formats/README.zh.md
+++ b/docs/persistence-changes/historical-formats/README.zh.md
@@ -32,7 +32,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式
 | 1 | PR #3349 | [V1](v1.zh.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.zh.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.zh.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 62 / 585 |
+| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 62 / 587 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-schema.json b/docs/persistence-schema.json
index 7456c002c0..59b8a86b4a 100644
--- a/docs/persistence-schema.json
+++ b/docs/persistence-schema.json
@@ -14850,7 +14850,7 @@
       "kind": "event",
       "event": "subagent/catalog",
       "surface": false,
-      "digest": "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3",
+      "digest": "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604",
       "schema": {
         "root": 0,
         "nodes": [
@@ -14864,7 +14864,7 @@
               },
               {
                 "name": "ignorable",
-                "type": 11,
+                "type": 14,
                 "optional": true
               },
               {
@@ -14879,7 +14879,7 @@
               },
               {
                 "name": "type",
-                "type": 12,
+                "type": 15,
                 "optional": false
               }
             ],
@@ -14890,7 +14890,9 @@
             "types": [
               2,
               7,
-              9
+              9,
+              11,
+              12
             ]
           },
           {
@@ -14909,7 +14911,7 @@
               {
                 "name": "label",
                 "type": 4,
-                "optional": true
+                "optional": false
               },
               {
                 "name": "mode",
@@ -14934,7 +14936,7 @@
           },
           {
             "kind": "literal",
-            "value": "unknown"
+            "value": "continuable"
           },
           {
             "kind": "literal",
@@ -14960,12 +14962,12 @@
               },
               {
                 "name": "mode",
-                "type": 8,
+                "type": 5,
                 "optional": false
               },
               {
                 "name": "version",
-                "type": 6,
+                "type": 8,
                 "optional": false
               }
             ],
@@ -14973,7 +14975,7 @@
           },
           {
             "kind": "literal",
-            "value": "continuable"
+            "value": 1
           },
           {
             "kind": "object",
@@ -15010,6 +15012,72 @@
             "kind": "literal",
             "value": "one-shot"
           },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
           {
             "kind": "literal",
             "value": true
@@ -30979,6 +31047,213 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "union",
+            "types": [
+              1,
+              6,
+              8,
+              10,
+              11
+            ]
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 9,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 9,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 12,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          }
+        ]
+      },
+      "names": [
+        "packages/subagent/subagent/src/catalog.ts#SubagentCatalogEvent"
+      ],
+      "sources": [
+        "packages/subagent/subagent/src/catalog.ts:28"
+      ]
+    },
     {
       "digest": "1df34a6c086866ffdc2dd9e8e5c581c3751a010cdf6b8538a7327f7a3237f0b4",
       "schema": {
@@ -33573,145 +33848,6 @@
         "packages/core/tools/src/types.ts:11"
       ]
     },
-    {
-      "digest": "30a49d1a89bd03b8503fbdab94d4883e4ce839d931f29672ac070007cc0016ce",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "union",
-            "types": [
-              1,
-              6,
-              8
-            ]
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "mode",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 5,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
-          {
-            "kind": "literal",
-            "value": "continuable"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 7,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 5,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "one-shot"
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 9,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 5,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "unknown"
-          }
-        ]
-      },
-      "names": [
-        "packages/subagent/subagent/src/catalog.ts#SubagentCatalogEvent"
-      ],
-      "sources": [
-        "packages/subagent/subagent/src/catalog.ts:24"
-      ]
-    },
     {
       "digest": "30d5a537b296685770b1241c4b4bbde19d5a31ff81aa23df73fab5e90b8fc65f",
       "schema": {
@@ -35422,6 +35558,248 @@
         "packages/feedback/message-feedback/src/types.ts:17"
       ]
     },
+    {
+      "digest": "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 14,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 15,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "union",
+            "types": [
+              2,
+              7,
+              9,
+              11,
+              12
+            ]
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog"
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "3b04790e08b35241ffa0d38f6d7e4f8788aa921341f6c0d7574a329397c59408",
       "schema": {
@@ -44255,180 +44633,6 @@
         "packages/workflow/workflow/src/types.ts:13"
       ]
     },
-    {
-      "digest": "4d6002c7eec8d76bbb6e531a35a55bc66dfb87621bc2e89e3af0641acf947bb3",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "data",
-                "type": 1,
-                "optional": false
-              },
-              {
-                "name": "ignorable",
-                "type": 11,
-                "optional": true
-              },
-              {
-                "name": "seq",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "time",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "type",
-                "type": 12,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "union",
-            "types": [
-              2,
-              7,
-              9
-            ]
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 5,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
-          {
-            "kind": "literal",
-            "value": "unknown"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "mode",
-                "type": 8,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "continuable"
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 10,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "one-shot"
-          },
-          {
-            "kind": "literal",
-            "value": true
-          },
-          {
-            "kind": "literal",
-            "value": "subagent/catalog"
-          }
-        ]
-      },
-      "names": [],
-      "sources": []
-    },
     {
       "digest": "4e011753f8263f436efaabfbb3b4db53a98fc55342c5ded2daf7208b217be159",
       "schema": {
@@ -68329,6 +68533,63 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 2,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "a0f906856fc06f1c6f2083eb970e5a657a82b1a84c06c095445e5d6d161cda80",
       "schema": {
@@ -71917,6 +72178,63 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 2,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "b6ef9c6210be8350cd465f485cf520031fffa6bf3809c61a1e713e834c5982d0",
       "schema": {
@@ -73599,63 +73917,6 @@
       "names": [],
       "sources": []
     },
-    {
-      "digest": "c8d70349934748fe4cf79c49654c72459f4073c57b65e01ff1e8f49dfcce49ca",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 1,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 2,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 2,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 4,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
-          {
-            "kind": "literal",
-            "value": "unknown"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          }
-        ]
-      },
-      "names": [],
-      "sources": []
-    },
     {
       "digest": "c8e6f48878cc2a2f0dc59682280d81f407943fb503f32c64bf9ff3d9393c3eff",
       "schema": {
@@ -81538,6 +81799,63 @@
         "packages/schedule/schedule/src/types.ts:105"
       ]
     },
+    {
+      "digest": "e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "e2d0367e5716bc188435e51718ebff8ce873190625fa93b1c5331102d98758fa",
       "schema": {
diff --git a/packages/sdk/client/tests/sdk-client.spec.ts b/packages/sdk/client/tests/sdk-client.spec.ts
index 41aef742aa..10a1a431e4 100644
--- a/packages/sdk/client/tests/sdk-client.spec.ts
+++ b/packages/sdk/client/tests/sdk-client.spec.ts
@@ -648,7 +648,7 @@ describe('HarnessClient', () => {
       (client as unknown as { dispatchNotification(n: HarnessNotification): void }).dispatchNotification({ method, params })
     }
     const unknownChild = { type: 'subagent/catalog', seq: 0, time: 1,
-      data: { version: 0, childId: 'unreadable-child', childCreatedAt: 1, mode: 'unknown' } }
+      data: { version: 1, childId: 'unreadable-child', childCreatedAt: 1, mode: 'unknown' } }
     inject('session.event', { sessionId: 'root', event: unknownChild })
     inject('subagent.started', { parentSessionId: 'root', childSessionId: 'child' })
     inject('subagent.started', { parentSessionId: 'child', childSessionId: 'grandchild' })
diff --git a/packages/session/session-format-v3-to-v4/README.i18n.yaml b/packages/session/session-format-v3-to-v4/README.i18n.yaml
index b4b64bdc40..afd45897dc 100644
--- a/packages/session/session-format-v3-to-v4/README.i18n.yaml
+++ b/packages/session/session-format-v3-to-v4/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-format-v3-to-v4/README.md
-README.md: 1c558d34cc67fc94aafcaf23405b0b1f2a0efa85
-README.zh.md: 6c079269503d5e11a0bbb03e3460d5a5432fa9e5
+README.md: 7a1b188194b54ff3ba7730388126fa0d2164fa06
+README.zh.md: 9d0f48ac375501d7dbd1e0b914bb882e43b02ac8
diff --git a/packages/session/session-format-v3-to-v4/README.md b/packages/session/session-format-v3-to-v4/README.md
index 1c558d34cc..7a1b188194 100644
--- a/packages/session/session-format-v3-to-v4/README.md
+++ b/packages/session/session-format-v3-to-v4/README.md
@@ -148,9 +148,9 @@ There is no recursive source search. Captured request text, assistant replay sta
 | More than one own descriptor | Retain an existing parent entry without mode/label comparison; otherwise append unknown-mode membership. |
 | Existing own parent entry | Retain it and its extensions; require matching child creation time and mode/label from exactly one supported own descriptor, when available. |
 | Missing own parent entry with complete supported evidence | Append a version-0 catalog fact with child id, creation time, mode, and optional label. |
-| Missing own parent entry without complete evidence | Append `subagent/catalog` with header identity and unknown mode, without inventing a label. |
+| Missing own parent entry without complete evidence | Append a version-1 `subagent/catalog` with header identity and unknown mode, without inventing a label. |
 
-Catalog version 0 requires string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable`, `one-shot`, or `unknown`, and a string label for continuable mode; a present label in any mode must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments. Unknown-mode entries retain header identity without asserting a supported child descriptor.
+Catalog versions 0 and 1 require string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable` or `one-shot` (version 1 additionally accepts `unknown`), and a string label for continuable mode; a present label in any mode must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments. Unknown-mode entries retain header identity without asserting a supported child descriptor.
 
 The stage considers parent catalog records only after the final inherited cut. Every inherited marker discards earlier catalog candidates without interpreting their payloads. Missing entries append after all source events, sorted by creation time then child id, with dense new sequences. Their time is the final source event's time, or header creation time for an empty log. They neither enter the model surface nor change the inherited count.
 
@@ -243,7 +243,7 @@ Current common admission does not validate each user/tool/developer content bloc
 | `compaction/start`, `compaction/summary`, `compaction/end` | Match compaction id, source command, and the active turn context. Summary spans name exact current-surface nodes and exclude the protected head; successful completion has one summary. Inherited unfinished compactions expire at the end-seed marker. |
 | `compaction/prune` | Its span names exact current-surface nodes and excludes the protected head; it does not require a compaction transaction or its owner fields. |
 | Compact checkpoint replacement | Its `compact-checkpoint` source identifies the active compaction. |
-| Native `subagent/catalog` | Check own version-0 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
+| Native `subagent/catalog` | Check own version-0/version-1 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
 | Inherited cut and delivery | Apply the marker, coordinate, and generation-ownership rules stated above. |
 
 These checks are generation-owned in [relationships.ts](src/relationships.ts). Full common message/envelope acceptance and plugin-owned message projections additionally use the installed Session; the exported V4 restorer alone is not a replacement for complete catalog restoration.
diff --git a/packages/session/session-format-v3-to-v4/README.zh.md b/packages/session/session-format-v3-to-v4/README.zh.md
index 6c07926950..9d0f48ac37 100644
--- a/packages/session/session-format-v3-to-v4/README.zh.md
+++ b/packages/session/session-format-v3-to-v4/README.zh.md
@@ -148,9 +148,9 @@ V3 未知内容标签变为 `plugin:<original-type>`，其他字段原样保留
 | 多个自身 descriptor | 保留已有父目录项，不比较 mode／label；否则追加模式未知的目录项。 |
 | 已有自身父目录项 | 保留条目及其扩展；要求子创建时间一致，并在恰好一个受支持的自身 descriptor 可用时比较其 mode／label。 |
 | 缺少自身父目录项，且受支持证据完整 | 追加带 child id、创建时间、mode 和可选 label 的 version-0 目录事实。 |
-| 缺少自身父目录项，且证据不完整 | 追加 `subagent/catalog`，记录 header 身份和未知模式，不编造标签。 |
+| 缺少自身父目录项，且证据不完整 | 追加 version-1 `subagent/catalog`，记录 header 身份和未知模式，不编造标签。 |
 
-Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable`、`one-shot` 或 `unknown` mode，以及 continuable mode 下的字符串 label；任何 mode 下存在的 label 都必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。未知模式条目保留 header 身份信息，不声明子 descriptor 受支持。
+Catalog version 0 和 1 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable` 或 `one-shot` mode（version 1 还接受 `unknown`），以及 continuable mode 下的字符串 label；任何 mode 下存在的 label 都必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。未知模式条目保留 header 身份信息，不声明子 descriptor 受支持。
 
 Stage 只把最终继承截点之后的父目录记录作为候选。每个 inherited marker 都会丢弃更早的目录候选，不解释其载荷。缺失项追加在所有源事件之后，按创建时间、child id 排序，并使用连续的新序号。时间取最后一个源事件的 time；空日志则取 header 创建时间。这些记录既不进入模型表面，也不改变继承计数。
 
@@ -243,7 +243,7 @@ System image 接纳要求非空 attachment id、PNG／JPEG／WebP／GIF MIME 类
 | `compaction/start`、`compaction/summary`、`compaction/end` | 匹配 compaction id、源 command 和活动 turn 上下文。Summary 区间引用精确的当前表面节点且排除 protected head；成功完成需要一个 summary。继承的未完成 compaction 在 end-seed marker 处过期。 |
 | `compaction/prune` | 其区间引用精确的当前表面节点且排除 protected head；它不要求存在 compaction 事务或其所有者字段。 |
 | Compact checkpoint 替换 | 其 `compact-checkpoint` 来源标识活动 compaction。 |
-| 原生 `subagent/catalog` | 检查继承截点之后的自身 version-0 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
+| 原生 `subagent/catalog` | 检查继承截点之后的自身 version-0/version-1 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
 | 继承截点与 delivery | 应用上文的 marker、坐标及代际归属规则。 |
 
 这些检查由 [relationships.ts](src/relationships.ts) 按代际拥有。完整的通用消息／信封接纳与插件拥有的消息投影还使用已安装 Session；单独的导出 V4 恢复器不能替代完整 catalog 恢复。
diff --git a/packages/session/session-format-v3-to-v4/src/facts.ts b/packages/session/session-format-v3-to-v4/src/facts.ts
index 2fb476377b..aa99fd32fa 100644
--- a/packages/session/session-format-v3-to-v4/src/facts.ts
+++ b/packages/session/session-format-v3-to-v4/src/facts.ts
@@ -70,12 +70,13 @@ export function childCatalogFact(source: SessionFormatJsonObject): SessionFormat
  * @returns validated catalog payload.
  */
 export function catalogFact(value: SessionFormatJsonValue, subject = 'subagent/catalog'): SessionFormatJsonObject {
-  if (!isSessionFormatJsonObject(value) || value['version'] !== 0
+  if (!isSessionFormatJsonObject(value) || (value['version'] !== 0 && value['version'] !== 1)
     || typeof value['childId'] !== 'string'
     || (value['mode'] !== 'continuable' && value['mode'] !== 'one-shot' && value['mode'] !== 'unknown')
+    || (value['version'] === 0 && value['mode'] === 'unknown')
     || (value['mode'] === 'continuable' && typeof value['label'] !== 'string')
     || (value['label'] !== undefined && typeof value['label'] !== 'string')) {
-    throw new SessionFormatError(`${subject} requires a version 0 catalog fact`)
+    throw new SessionFormatError(`${subject} requires a supported versioned catalog fact`)
   }
   sessionFormatCount(value['childCreatedAt'], 'catalog child creation time')
   return value
diff --git a/packages/session/session-format-v3-to-v4/src/migration.ts b/packages/session/session-format-v3-to-v4/src/migration.ts
index 50c796a1df..c2a28e04b2 100644
--- a/packages/session/session-format-v3-to-v4/src/migration.ts
+++ b/packages/session/session-format-v3-to-v4/src/migration.ts
@@ -122,7 +122,7 @@ class ReleasedV3ToV4Stage implements SessionFormatMigrationStage {
         }
         continue
       }
-      const entry = fact ?? { version: 0, childId: id, childCreatedAt: source['childCreatedAt'] as number, mode: 'unknown' }
+      const entry = fact ?? { version: 1, childId: id, childCreatedAt: source['childCreatedAt'] as number, mode: 'unknown' }
       existingCatalogs.set(id, entry)
       context.emitEvent({ type: 'subagent/catalog',
         seq: this.nextSeq++, time: this.time, data: entry })
diff --git a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
index f533b9d502..455535ed79 100644
--- a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
@@ -67,14 +67,14 @@ describe('V3 parent catalog completion', () => {
     expect(migrate(source, [child], true).events).toEqual([
       ...source, { type: 'subagent/catalog', seq: 4, time: 2, data: child },
     ])
-    expect(() => migrate([...source, { ...opaque, seq: 4 }], [], true)).toThrow('version 0')
-    expect(() => migrate([opaque], [])).toThrow('version 0')
+    expect(() => migrate([...source, { ...opaque, seq: 4 }], [], true)).toThrow('supported versioned')
+    expect(() => migrate([opaque], [])).toThrow('supported versioned')
   })
 
   it('requires explicit corpus facts and refuses conflicting identities', () => {
     expect(() => sessionFormatV3ToV4.createStage({ sourceHeader: header, targetHeader: { ...header, version: 4 },
       sourceKind: 'decoded', sourceInheritedEventCount: 0 })).toThrow('explicit historical child facts')
-    expect(() => migrate([], [{ ...child, mode: 'invalid' }])).toThrow('version 0')
+    expect(() => migrate([], [{ ...child, mode: 'invalid' }])).toThrow('supported versioned')
     expect(() => migrate([{ type: 'subagent/catalog', seq: 0, time: 2, data: child }], [{ ...child, childCreatedAt: 3 }])).toThrow('conflicts')
   })
 
@@ -120,7 +120,7 @@ describe('V3 parent catalog completion', () => {
     for (const data of [null, {}, { version: 4, mode: 'one-shot', provider: 'spawn' }]) {
       expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [{ type: 'subagent/descriptor', seq: 0, time: 1, data }] })]).events).toMatchObject([{ data: { childId: 'parent', mode: 'unknown' } }])
     }
-    for (const value of [null, { ...child, version: 1 }, { ...child, childId: null },
+    for (const value of [null, { ...child, version: 2 }, { ...child, childId: null },
       { ...child, label: null }, { ...child, childCreatedAt: -1 }]) {
       expect(() => migrate([], [value])).toThrow()
     }
@@ -148,7 +148,7 @@ describe('V3 parent catalog completion', () => {
     const unavailable = { childId: 'unavailable', childCreatedAt: 1,
       descriptorCount: kind === 'missing' ? 0 : kind === 'multiple' ? 2 : 1, descriptor }
     expect(migrate([], [child, unavailable]).events).toEqual([
-      { type: 'subagent/catalog', seq: 0, time: 1, data: { version: 0, childId: 'unavailable', childCreatedAt: 1, mode: 'unknown' } },
+      { type: 'subagent/catalog', seq: 0, time: 1, data: { version: 1, childId: 'unavailable', childCreatedAt: 1, mode: 'unknown' } },
       { type: 'subagent/catalog', seq: 1, time: 1, data: child },
     ])
   })
diff --git a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
index 7bd8b24539..7142c6ab45 100644
--- a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
@@ -115,12 +115,12 @@ describe('restoreReleasedV4Artifact', () => {
 
   it('retains unknown child membership and rejects invalid identities or duplicate child ids', () => {
     const known = new Set([...KNOWN, 'subagent/catalog'])
-    const data = { version: 0, childId: 'unreadable', childCreatedAt: 2, mode: 'unknown' }
+    const data = { version: 1, childId: 'unreadable', childCreatedAt: 2, mode: 'unknown' }
     const event = { type: 'subagent/catalog', seq: 0, time: 1, data }
     const valid = artifact([event])
     expect(restoreReleasedV4Artifact(valid, known)).toBe(valid)
     expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: { ...data, label: 'retained' } }]), known)).not.toThrow()
-    for (const invalid of [null, { ...data, version: 1 }, { ...data, childId: 1 },
+    for (const invalid of [null, { ...data, version: 0 }, { ...data, version: 2 }, { ...data, childId: 1 },
       { ...data, childCreatedAt: -1 }, { ...data, mode: 'invalid' }, { ...data, label: null }]) {
       expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: invalid }]), known)).toThrow()
     }
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 25cea24568..fb26e9f540 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 75237c6eda835459015d5b2f64402190d27d72af
-README.zh.md: 187d26ea3a4261c4ddeed96cd6c41f50fbd48c91
+README.md: 4ed03104d3d8ab70816ee0cff7334a253196aef2
+README.zh.md: 92acf7498f282cdefea4f440d59e17f6dfffc81a
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 75237c6eda..4ed03104d3 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -109,7 +109,7 @@ A request is validated against the provider's advertised capabilities, a durable
 
 The manager reserves a child identity, resolves the durable descriptor, creates (or cold-resumes) the child Agent, installs it in an Activation, and submits the prompt. Model-authored messages cross one parent/child edge through fixed Steer scheduling; browser human prompts choose Queue or best-effort Steer through an internal adapter, while other host protocols may retain Queue for distinct turns. A Session queue command admits a live subagent-owned Agent only from its own continuable descriptor. Settlement waits for Agent activity to finish, an empty Inbox, and no owned children, then flushes final Session state with admission open. Under the child lock, the manager revalidates the wake generation, Session sequence, Inbox, and owned children; the synchronous task entry of `Agent.runMaintenance()` claims the idle phase and closes the private subagent Inbox in the same JavaScript turn before handle disposal. An absent direct-child Activation cold-resumes from the persisted session. When a resident Activation settles, the manager tells the child's direct parent in the parent's own turn stream.
 
-Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives. Historical migration may instead append `subagent/catalog` from a readable child header. Its `mode: 'unknown'` projection keeps the child visible without claiming continuation support; an existing complete entry remains authoritative.
+Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives. Catalog payload v0 records known modes; v1 also accepts unknown mode. Readers support both versions. Historical migration appends a v1 `subagent/catalog` from a readable child header when its descriptor is unavailable; normal creation retains v0. Its `mode: 'unknown'` projection keeps the child visible without claiming continuation support; an existing complete entry remains authoritative.
 
 ### Ownership and invariants
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 187d26ea3a..92acf7498f 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -109,7 +109,7 @@ kind: "package-reference"
 
 管理器预留 child 身份、解析持久化描述符、创建（或冷恢复）child、把它安装进 Activation 并提交提示词。模型编写的消息通过固定 Steer 调度跨一条 parent/child 边；浏览器人类 prompt 通过内部适配器选择 Queue 或 best-effort Steer，其他 host 协议仍可保留 Queue 以创建独立轮次。Session queue command 仅根据 child 自身的 continuable descriptor 准入在线 subagent-owned Agent。Settlement 会等待 Agent 活动结束、Inbox 为空且没有所拥有子级，再在准入开放时 flush 最终 Session 状态。管理器随后在 child lock 内重新验证 wake generation、Session 序号、Inbox 与所拥有子级；`Agent.runMaintenance()` 的同步 task 入口会占用 idle 阶段，并在同一个 JavaScript turn 内关闭私有 subagent Inbox，然后才释放句柄。直接 child 不存在 Activation 时会从持久化会话冷恢复。当驻留 Activation 结算时，管理器会在 parent 自身的轮次流中告知该 child 的直接 parent。
 
-本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。 历史迁移可根据可读子 header 追加 `subagent/catalog`。其 `mode: 'unknown'` 投影让子会话保持可见，但不表示支持继续执行；已有完整条目仍具有权威性。
+本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。Catalog 载荷 v0 记录已知模式，v1 还接受未知模式，读取器支持两版。历史迁移在 descriptor 不可用时根据可读子 header 追加 v1 `subagent/catalog`；正常创建保留 v0。其 `mode: 'unknown'` 投影让子会话保持可见，但不表示支持继续执行；已有完整条目仍具有权威性。
 
 ### 所有权与不变式
 
diff --git a/packages/subagent/subagent/src/catalog.ts b/packages/subagent/subagent/src/catalog.ts
index 15ec24dd17..81edf47fb6 100644
--- a/packages/subagent/subagent/src/catalog.ts
+++ b/packages/subagent/subagent/src/catalog.ts
@@ -17,19 +17,21 @@ import type {
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import type { SubagentCatalogEntry } from './projection-types.ts'
 
-/** Current payload version for `subagent/catalog` events. */
+/** Catalog payload version emitted by live child creation. */
 export const SUBAGENT_CATALOG_VERSION = 0
 
-/** One parent-owned catalog fact with known or unknown child mode. */
+type KnownCatalogMode =
+  | { readonly mode: 'one-shot'; readonly label?: string }
+  | { readonly mode: 'continuable'; readonly label: string }
+
+/** Parent catalog v0 records known modes; v1 also retains children with unknown mode. */
 export type SubagentCatalogEvent =
   & {
-    readonly version: 0
     readonly childId: SessionId
     readonly childCreatedAt: number
   } & (
-    | { readonly mode: 'one-shot'; readonly label?: string }
-    | { readonly mode: 'continuable'; readonly label: string }
-    | { readonly mode: 'unknown'; readonly label?: string }
+    | ({ readonly version: 0 } & KnownCatalogMode)
+    | ({ readonly version: 1 } & (KnownCatalogMode | { readonly mode: 'unknown'; readonly label?: string }))
   )
 
 declare module '@deepseek-ai/dsh-session/types' {
@@ -50,25 +52,25 @@ export interface SubagentCatalogState {
 
 const sessionIdSchema = z.string() as unknown as z.ZodType<SessionId>
 const oneShotCatalogSchema = z.object({
-  version: z.literal(SUBAGENT_CATALOG_VERSION),
+  version: z.union([z.literal(0), z.literal(1)]),
   childId: sessionIdSchema,
   childCreatedAt: z.number().int().nonnegative(),
   mode: z.literal('one-shot'),
   label: z.string().optional(),
 }).strict()
 const continuableCatalogSchema = z.object({
-  version: z.literal(SUBAGENT_CATALOG_VERSION),
+  version: z.union([z.literal(0), z.literal(1)]),
   childId: sessionIdSchema,
   childCreatedAt: z.number().int().nonnegative(),
   mode: z.literal('continuable'),
   label: z.string(),
 }).strict()
-const unknownCatalogSchema = oneShotCatalogSchema.extend({ mode: z.literal('unknown') })
+const unknownCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(1), mode: z.literal('unknown') })
 const eventDataSchema = z.union([
   oneShotCatalogSchema,
   continuableCatalogSchema,
   unknownCatalogSchema,
-]) as unknown as z.ZodType<SubagentCatalogEvent>
+]) as z.ZodType<SubagentCatalogEvent>
 const viewSchema = z.array(z.union([
   oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
     id: sessionIdSchema,
@@ -82,7 +84,7 @@ const viewSchema = z.array(z.union([
     id: sessionIdSchema,
     createdAt: unknownCatalogSchema.shape.childCreatedAt,
   }),
-])) as unknown as z.ZodType<SubagentCatalogEntry[]>
+])) as z.ZodType<SubagentCatalogEntry[]>
 const stateSchema: z.ZodType<SubagentCatalogState> = z.object({
   inheritedEventCount: z.number().int().nonnegative() as unknown as z.ZodType<SessionLogOffset>,
   head: chunkedListSchema(eventDataSchema).optional(),
diff --git a/packages/subagent/subagent/tests/catalog.spec.ts b/packages/subagent/subagent/tests/catalog.spec.ts
index 589e336c88..ffc95e1606 100644
--- a/packages/subagent/subagent/tests/catalog.spec.ts
+++ b/packages/subagent/subagent/tests/catalog.spec.ts
@@ -102,13 +102,26 @@ describe('subagent catalog projection', () => {
       .toEqual(Array.from({ length: 130 }, (_, i) => SessionId(`child-${i}`)))
   })
 
+  it.each([0, 1] as const)('reads known catalog modes at payload version %s', (version) => {
+    const events: SessionEvent[] = [
+      { type: 'subagent/catalog', seq: SessionSeq(0), time: 0,
+        data: { version, childId: SessionId('once'), childCreatedAt: 1, mode: 'one-shot' } },
+      { type: 'subagent/catalog', seq: SessionSeq(1), time: 0,
+        data: { version, childId: SessionId('ongoing'), childCreatedAt: 2, mode: 'continuable', label: 'child' } },
+    ]
+    expect(subagentCatalogProjectionDefinition.wire.view(fold(events))).toEqual([
+      { id: SessionId('once'), createdAt: 1, mode: 'one-shot' },
+      { id: SessionId('ongoing'), createdAt: 2, mode: 'continuable', label: 'child' },
+    ])
+  })
+
   it('validates recursive chunk state and materializes every label variant in event order', () => {
     const events: SessionEvent[] = [
       fact(0, 'child-b', 1, { mode: 'one-shot' }),
       fact(1, 'child-a', 1, { mode: 'one-shot', label: 'once' }),
       fact(2, 'child-d', 3, { mode: 'continuable', label: 'later' }),
       { type: 'subagent/catalog', seq: SessionSeq(3), time: 0,
-        data: { version: 0, childId: SessionId('unreadable'), childCreatedAt: 4, mode: 'unknown' } },
+        data: { version: 1, childId: SessionId('unreadable'), childCreatedAt: 4, mode: 'unknown' } },
     ]
     const state = fold(events)
 
@@ -143,6 +156,7 @@ describe('subagent catalog projection', () => {
   })
 
   it.each([
+    { version: 0, childId: 'child', childCreatedAt: 0, mode: 'unknown' },
     { version: 9, childId: 'child', childCreatedAt: 0, mode: 'one-shot' },
     { version: 0, childId: 'child', childCreatedAt: 0, mode: 'continuable' },
     { version: 0, childId: 'child', childCreatedAt: -1, mode: 'one-shot' },
diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py
index 78178c1e18..66b9b2665c 100644
--- a/python/sdk/tests/test_client.py
+++ b/python/sdk/tests/test_client.py
@@ -597,7 +597,7 @@ def test_session_subscription_keeps_descendant_relationships_across_subscription
     with client.subscribe_session_notifications("main") as first:
         unknown_child = {
             "type": "subagent/catalog", "seq": 0, "time": 1,
-            "data": {"version": 0, "childId": "unreadable-child", "childCreatedAt": 1, "mode": "unknown"},
+            "data": {"version": 1, "childId": "unreadable-child", "childCreatedAt": 1, "mode": "unknown"},
         }
         client._handle_message({
             "jsonrpc": "2.0", "method": "session.event",
diff --git a/scripts/no-unknown-casts.baseline.json b/scripts/no-unknown-casts.baseline.json
index f5ecfea159..c2e5867d75 100644
--- a/scripts/no-unknown-casts.baseline.json
+++ b/scripts/no-unknown-casts.baseline.json
@@ -2131,9 +2131,7 @@
     "b50b6842b3565ea7f1441afb3214ab0ccf027df0e44bb485005935849c46f8ea": 1
   },
   "packages/subagent/subagent/src/catalog.ts": {
-    "29a67bf48723006b65c652af8a0ff30a4385bb14d651d91ca3059e1ddcb44fcf": 1,
     "3e704e331ed2fc5d4c0855e2455b31b82924c525f2e267416e393cdbd36c251b": 1,
-    "c3a7c8abe19131a8d98f4fb6a495b590e67a56cbf2e741caccfe730f8261edb0": 1,
     "fdc5fcade0ba1abbc426ccccb07a1ad4998253799b8561815047d95178441cdf": 1
   },
   "packages/subagent/subagent/src/internal.ts": {
diff --git a/scripts/persistence-changes.spec.ts b/scripts/persistence-changes.spec.ts
index 0a3be90d70..ab6f0e50e3 100644
--- a/scripts/persistence-changes.spec.ts
+++ b/scripts/persistence-changes.spec.ts
@@ -397,58 +397,61 @@ function unionBody(arms: readonly (readonly SchemaProperty[])[]): PersistenceRoo
   return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
 }
 
-function catalogModeRoot(unknownMode?: string, changeLabel = false, extraField = false): PersistenceRoot {
-  const snapshot = parsePersistenceSnapshot(JSON.parse(readFileSync(
-    new URL('../docs/persistence-changes/2026-09-11-initial.schema.json', import.meta.url), 'utf8',
-  )))
-  const root = snapshot.roots.find(root => root.key === 'event:subagent/catalog')!
-  const nodes: SchemaNode[] = [...structuredClone(root.schema.nodes)]
-  const union = nodes.find(node => node.kind === 'union')!
-  if (union.kind !== 'union') throw new Error('catalog fixture requires mode alternatives')
-  const oneShot = union.types.find((index) => {
-    const node = nodes[index]
-    if (node?.kind !== 'object') return false
-    const mode = nodes[node.properties.find(property => property.name === 'mode')!.type]
-    return mode?.kind === 'literal' && mode.value === 'one-shot'
-  })!
-  const variant = nodes[oneShot]!
-  if (variant.kind !== 'object') throw new Error('catalog fixture requires object alternatives')
-  if (unknownMode !== undefined) {
+function versionedEvent(variants: readonly { version: number; mode: string; extra?: boolean }[]): PersistenceRoot {
+  const nodes: SchemaNode[] = [
+    { kind: 'object', indices: [], properties: [
+      { name: 'data', type: variants.length === 1 ? 3 : 1, optional: false },
+      { name: 'type', type: 3 + variants.length * 3, optional: false },
+    ] },
+    { kind: 'union', types: variants.map((_, index) => 3 + index * 3) },
+    { kind: 'primitive', type: 'string' },
+  ]
+  for (const variant of variants) {
     const index = nodes.length
-    nodes.push({ ...variant, properties: variant.properties.map(property => property.name === 'mode'
-      ? { ...property, type: index + 1 } : property) }, { kind: 'literal', value: unknownMode })
-    const added = nodes[index]!
-    if (extraField && added.kind === 'object') nodes[index] = { ...added,
-      properties: [...added.properties, { name: 'extra', type: variant.properties[0]!.type, optional: false }] }
-    nodes[nodes.indexOf(union)] = { ...union, types: [...union.types, index] }
+    nodes.push({ kind: 'object', indices: [], properties: [
+      { name: 'version', type: index + 1, optional: false },
+      { name: 'mode', type: index + 2, optional: false },
+      ...(variant.extra ? [{ name: 'extra', type: 2, optional: false }] : []),
+    ] }, { kind: 'literal', value: variant.version }, { kind: 'literal', value: variant.mode })
   }
-  if (changeLabel) nodes[oneShot] = { ...variant, properties: variant.properties.filter(property => property.name !== 'label') }
+  nodes.push({ kind: 'literal', value: 'example/value' })
   const schema = canonicalizeSchema(nodes, 0)
-  return { ...root, schema, digest: schemaDigest(schema) }
+  return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
 }
 
 describe('persistence change classification', () => {
-  it('acknowledges unknown catalog mode at V4 while retaining the accepted checkpoint', () => {
+  it.each([1, 2])('acknowledges a higher payload version while preserving %s old variant(s) and the V4 checkpoint', (count) => {
     const root = fixture()
-    const before = { ...inventory({}, 4), roots: [...inventory({}, 4).roots.filter(root => root.kind !== 'event'), catalogModeRoot()] }
+    const variants = [{ version: 0, mode: 'one-shot' }, { version: 0, mode: 'continuable' }].slice(0, count)
+    const oldEvent = versionedEvent(variants)
+    const nextEvent = versionedEvent([...variants, { version: 1, mode: 'unknown', extra: true }])
+    const before = { ...inventory({}, 4), roots: [...inventory({}, 4).roots.filter(root => root.kind !== 'event'), oldEvent] }
     finalize(root, before)
-    const after = { ...before, roots: before.roots.map(root => root.kind === 'event' ? catalogModeRoot('unknown') : root) }
-    expect(classifyPersistenceChange(catalogModeRoot(), catalogModeRoot('unknown')))
-      .toEqual([expect.objectContaining({ path: 'event:subagent/catalog.data', requiresVersionBump: false })])
+    const after = { ...before, roots: before.roots.map(root => root.kind === 'event' ? nextEvent : root) }
+    expect(classifyPersistenceChange(oldEvent, nextEvent))
+      .toEqual([expect.objectContaining({ kind: 'payload-version-added', requiresVersionBump: false })])
     runPersistenceChanges(['--record', COMPATIBLE_ID, '--prose', proseFile(root)], root, () => after)
     verifyPersistenceChanges(root, after)
   })
 
-  it('keeps other catalog modes, altered fields, classification changes, and removals breaking', () => {
-    const before = catalogModeRoot()
-    for (const after of [catalogModeRoot('other'), catalogModeRoot('unknown', true), catalogModeRoot('unknown', false, true)]) {
-      expect(classifyPersistenceChange(before, after).some(change => change.requiresVersionBump)).toBe(true)
-    }
-    const expanded = catalogModeRoot('unknown')
+  it('rejects changes to old payloads, missing versions, non-increasing versions, and removal of old readers', () => {
+    const variants = [{ version: 0, mode: 'one-shot' }, { version: 0, mode: 'continuable' }]
+    const before = versionedEvent(variants)
+    for (const after of [
+      versionedEvent([...variants, { version: 0, mode: 'unknown' }]),
+      versionedEvent([...variants, { version: -1, mode: 'unknown' }]),
+      versionedEvent([...variants, { version: 0.5, mode: 'unknown' }]),
+      versionedEvent([{ version: 0, mode: 'one-shot', extra: true }, variants[1]!, { version: 1, mode: 'unknown' }]),
+      versionedEvent([{ version: 1, mode: 'unknown' }]),
+    ]) expect(classifyPersistenceChange(before, after).some(change => change.requiresVersionBump)).toBe(true)
+    const expanded = versionedEvent([...variants, { version: 1, mode: 'unknown' }])
     expect(classifyPersistenceChange(expanded, before).some(change => change.requiresVersionBump)).toBe(true)
-    expect(classifyPersistenceChange(before, { ...expanded, surface: true }).some(change => change.requiresVersionBump)).toBe(true)
-    expect(classifyPersistenceChange({ ...before, key: 'event:other' }, { ...expanded, key: 'event:other' })
+    expect(classifyPersistenceChange({ ...before, surface: true }, { ...expanded, surface: true })
       .some(change => change.requiresVersionBump)).toBe(true)
+    expect(classifyPersistenceChange({ ...before, kind: 'header' }, { ...expanded, kind: 'header' })
+      .some(change => change.requiresVersionBump)).toBe(true)
+    const unversioned = unionBody([[{ name: 'mode', type: 2, optional: false }]])
+    expect(classifyPersistenceChange(unversioned, expanded).some(change => change.requiresVersionBump)).toBe(true)
   })
 
   it('treats a new optional payload subtree as one additive change even with required descendants', () => {
diff --git a/scripts/persistence-changes.ts b/scripts/persistence-changes.ts
index e53092e921..d1f38225a9 100644
--- a/scripts/persistence-changes.ts
+++ b/scripts/persistence-changes.ts
@@ -66,6 +66,7 @@ const CHANGE_DESCRIPTIONS = {
   'index-signature-changed': 'index signature changed',
   'tuple-length-changed': 'tuple length changed',
   'tuple-element-cardinality-changed': 'tuple element cardinality changed',
+  'payload-version-added': 'event payload version added',
   'union-variants-changed': 'union variants changed',
   'source-policy-changed': 'source compatibility policy changed',
   'attribution-kind-added': 'attribution-only source kind added',
@@ -405,6 +406,27 @@ export function classifyPersistenceChange(before: PersistenceRoot | null, after:
     }
     const oldNode = oldRoot.schema.nodes[oldIndex] as SchemaNode
     const newNode = newRoot.schema.nodes[newIndex] as SchemaNode
+    if (oldRoot.kind === 'event' && oldRoot.surface === false && scope === 'body' && path === `${key}.data`) {
+      const oldTypes = oldNode.kind === 'union' ? oldNode.types : [oldIndex]
+      const newTypes = newNode.kind === 'union' ? newNode.types : [newIndex]
+      const payloadVersion = (schema: CanonicalSchema, index: number): number | undefined => {
+        const node = schema.nodes[index]
+        if (node?.kind !== 'object') return undefined
+        const property = node.properties.find(property => property.name === 'version' && !property.optional)
+        const version = schema.nodes[property?.type ?? -1]
+        return version?.kind === 'literal' && typeof version.value === 'number'
+          && Number.isSafeInteger(version.value) && version.value >= 0 ? version.value : undefined
+      }
+      const versions = oldTypes.map(index => payloadVersion(oldRoot.schema, index))
+      const oldHashes = new Set(oldTypes.map(index => fingerprint(oldRoot.schema, index, 0)))
+      const newHashes = new Set(newTypes.map(index => fingerprint(newRoot.schema, index, 1)))
+      const added = newTypes.filter(index => !oldHashes.has(fingerprint(newRoot.schema, index, 1)))
+      if (versions.every(version => version !== undefined) && added.length > 0
+        && [...oldHashes].every(hash => newHashes.has(hash))
+        && added.every(index => (payloadVersion(newRoot.schema, index) ?? -1) > Math.max(...versions))) {
+        return [describe(path, 'payload-version-added', false)]
+      }
+    }
     if (oldNode.kind !== newNode.kind) return [describe(path, 'type-changed')]
     if (oldNode.kind === 'object' && newNode.kind === 'object') {
       const oldProps = new Map(oldNode.properties.map(property => [property.name, property]))
@@ -471,29 +493,6 @@ export function classifyPersistenceChange(before: PersistenceRoot | null, after:
   function compareAlternatives(
     oldTypes: readonly number[], newTypes: readonly number[], path: string, scope: Scope, active: ReadonlySet<string>,
   ): PersistenceTypeChange[] {
-    if (key === 'event:subagent/catalog' && path === `${key}.data` && scope === 'body'
-      && oldTypes.length === 2 && newTypes.length === 3) {
-      const modeNode = (index: number): number | undefined => {
-        const node = newRoot.schema.nodes[index]
-        return node?.kind === 'object' ? node.properties.find(property => property.name === 'mode' && !property.optional)?.type : undefined
-      }
-      const mode = (index: number): string | number | boolean | null | undefined => {
-        const node = newRoot.schema.nodes[modeNode(index) ?? -1]
-        return node?.kind === 'literal' ? node.value : undefined
-      }
-      const unknown = newTypes.find(index => mode(index) === 'unknown')
-      const oneShot = newTypes.find(index => mode(index) === 'one-shot')
-      if (unknown !== undefined && oneShot !== undefined) {
-        // The catalog exception admits only the one-shot fields with unknown mode;
-        // existing branches still pass the ordinary structural comparison below.
-        const normalized = { ...newRoot.schema, nodes: newRoot.schema.nodes.map((node, index) =>
-          index === modeNode(unknown) ? { kind: 'literal' as const, value: 'one-shot' } : node) }
-        if (subDigest(normalized, unknown) === fingerprint(newRoot.schema, oneShot, 1)) {
-          return [describe(path, 'union-variants-changed', false),
-            ...compareAlternatives(oldTypes, newTypes.filter(index => index !== unknown), path, scope, active)]
-        }
-      }
-    }
     if (oldTypes.length !== newTypes.length) return [describe(path, 'union-variants-changed')]
     const candidates = oldTypes.map(oldType => newTypes.map(newType => compare(oldType, newType, path, scope, active)))
     const matching = matchUnionVariants(candidates.map(row => row.flatMap((candidate, index) =>

From 21ec132c0e1dd1e258de5d3e03f819748442f047 Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sun, 20 Sep 2026 15:15:43 +0800
Subject: [PATCH 27/37] test(preview): expect versioned unknown child catalog
 entries

---
 .../webworker-packer/tests/preview.spec.ts             | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/experimental/webworker-packer/tests/preview.spec.ts b/packages/experimental/webworker-packer/tests/preview.spec.ts
index 2c5c381059..f3b5937ab9 100644
--- a/packages/experimental/webworker-packer/tests/preview.spec.ts
+++ b/packages/experimental/webworker-packer/tests/preview.spec.ts
@@ -65,7 +65,7 @@ describe('Node preparation of Preview Session data', () => {
     expect(packVfsOverlay(fixture.trees).files).toEqual(original.files)
   })
 
-  it.each(['missing-descriptor', 'other-root', 'other-origin', 'current-child'] as const)('adds catalog facts only for supported direct subagent children in the same root: %s', (mode) => {
+  it.each(['missing-descriptor', 'other-root', 'other-origin', 'current-child'] as const)('catalogs direct subagent children in the same root, retaining missing descriptors as unknown: %s', (mode) => {
     const fixture = source()
     const parent = fixture.put(3)
     const childDirectory = join(fixture.trees[0]!.directory, 'sessions', mode === 'other-root' ? 'other' : 'project', 'child')
@@ -84,8 +84,12 @@ describe('Node preparation of Preview Session data', () => {
     const packed = packPreviewFixture(fixture.trees)
     const restored = restore(packed.files[`home/sessions/project/example/${sessionFormatLogFilename(currentVersion)}`])
     expect(restored.inheritedEventCount).toBe(0)
-    expect(restored.events).toEqual(mode === 'current-child' ? [{ type: 'subagent/catalog', seq: 0, time: 1,
-      data: { version: 0, childId: 'child', childCreatedAt: 2, mode: 'one-shot' } }] : [])
+    const catalog = mode === 'current-child'
+      ? [{ version: 0, childId: 'child', childCreatedAt: 2, mode: 'one-shot' }]
+      : mode === 'missing-descriptor'
+        ? [{ version: 1, childId: 'child', childCreatedAt: 2, mode: 'unknown' }]
+        : []
+    expect(restored.events).toEqual(catalog.map(data => ({ type: 'subagent/catalog', seq: 0, time: 1, data })))
     for (const [path, bytes] of Object.entries(original.files)) expect(packed.files[path], path).toEqual(bytes)
     expect(readFileSync(parent)).toEqual(before)
     expect(readFileSync(childPath)).toEqual(childBefore)

From bea5bde6cc3273dec1ea8cd892eb005d77aedce3 Mon Sep 17 00:00:00 2001
From: winewill <leto.wine@gmail.com>
Date: Sun, 20 Sep 2026 15:27:06 +0800
Subject: [PATCH 28/37] docs(desktop): clarify localized native menu behavior

---
 .../bug-fix/2026-09-16-desktop-window-menus.i18n.yaml       | 4 ++--
 .../implemented/bug-fix/2026-09-16-desktop-window-menus.md  | 6 +++---
 .../bug-fix/2026-09-16-desktop-window-menus.zh.md           | 6 +++---
 apps/desktop/src/main.ts                                    | 1 +
 4 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.i18n.yaml
index a5158a3994..9c2cdd061a 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.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-09-16-desktop-window-menus.md
-2026-09-16-desktop-window-menus.md: 85ac42aa287b1cd9e595ade7cb44b965dea787dd
-2026-09-16-desktop-window-menus.zh.md: 1376b90058ceafa7e378b4fd543d261064f5d8aa
+2026-09-16-desktop-window-menus.md: 8a5343404e0cb3d2e7c4e20248a8b29f3bfbec47
+2026-09-16-desktop-window-menus.zh.md: d6ee6412462aecf49557a7994a683d37bf8e7253
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md
index 85ac42aa28..8a5343404e 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md
@@ -12,7 +12,7 @@ The Desktop shell replaces Electron's default application menu with a custom tem
 
 On macOS the template declares `{ role: 'fileMenu' }` before the Edit menu and `{ role: 'windowMenu' }` after it, and a separator-delimited run of `hide`, `hideOthers`, and `unhide` before Quit in the application submenu. Those roles contribute only the standard items; no Services submenu, window list, or other macOS default is declared. Windows and Linux keep the application and Edit menus.
 
-Electron's role labels are English string literals inside Electron (`lib/browser/api/menu-item-roles.ts`, `filemenu`, `windowmenu`, `close`, `minimize`, `hide`) with no locale lookup, and Electron re-applies them to the native menu items before the menu is shown, so a non-English Desktop shows them in English; the existing Edit menu behaves the same way. No custom close, minimize, or hide code is added: ⌘W destroys the window through Electron's own role.
+Electron supplies English defaults for the File, Window, and Edit roles. Explicit labels override role defaults while retaining native actions and shortcuts; the localized application commands are documented in the [Desktop README](../../../../apps/desktop/README.md). No custom close, minimize, or hide code is added: ⌘W destroys the window through Electron's own role.
 
 ## Alternatives considered
 
@@ -28,8 +28,8 @@ Electron's role labels are English string literals inside Electron (`lib/browser
 
 ## Consequences
 
-macOS regains the window and application commands the custom menu suppressed, at the cost of four menu roles. The labels stay English on a non-English Desktop.
+macOS regains the window and application commands the custom menu suppressed. File, Window, and Edit retain Electron’s default English labels; application commands use the Desktop locale.
 
 ## Testing
 
-A `apps/desktop/tests/main-startup.spec.ts` case pins the declared menu roles per platform, including the macOS hide commands. Role-based menu items execute natively, so a programmatic `click()` and the vitest Electron mock cannot exercise the shortcuts; a real Electron 44 run of the same template showed the standard File, Window, and application items present only after this change, with the same English labels while `app.getLocale()`, `getSystemLocale()`, and `getPreferredSystemLanguages()` all reported `zh-CN`.
+`apps/desktop/tests/main-startup.spec.ts` verifies the declared menu roles per platform and records English and Chinese application-label snapshots. Role-based menu items execute natively, so a programmatic `click()` and the Vitest Electron mock cannot exercise the shortcuts. The isolated Electron 44 demo confirms that explicit application labels appear in native menus; the template snapshots do not qualify native shortcut execution.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md
index 1376b90058..d6ee641246 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md
@@ -12,7 +12,7 @@ Desktop shell 用自定义模板替换了 Electron 的默认应用菜单，该
 
 macOS 上的模板在 Edit 菜单之前声明 `{ role: 'fileMenu' }`，在其之后声明 `{ role: 'windowMenu' }`，并在应用子菜单的 Quit 之前声明由分隔符隔开的 `hide`、`hideOthers` 和 `unhide`。这些 role 只提供标准菜单项；不声明 Services 子菜单、窗口列表或其他 macOS 默认项。Windows 和 Linux 保留应用菜单和 Edit 菜单。
 
-这些 role 的标签是 Electron 内部的英文常量（`lib/browser/api/menu-item-roles.ts` 的 `filemenu`、`windowmenu`、`close`、`minimize`、`hide`），没有语言查询，而且 Electron 在菜单显示前会把这些标签重新写到本机菜单项上，因此在非英文的 Desktop 上它们仍是英文；现有的 Edit 菜单同样如此。这里不新增任何自定义的关闭、最小化或隐藏代码：⌘W 通过 Electron 自身的 role 销毁窗口。
+Electron 为 File、Window 和 Edit role 提供英文默认标签。显式标签会覆盖 role 的默认标签，同时保留原生命令和快捷键；本地化的应用命令见 [Desktop README](../../../../apps/desktop/README.zh.md)。这里不新增任何自定义的关闭、最小化或隐藏代码：⌘W 通过 Electron 自身的 role 销毁窗口。
 
 ## 考虑过的替代方案
 
@@ -28,8 +28,8 @@ macOS 上的模板在 Edit 菜单之前声明 `{ role: 'fileMenu' }`，在其之
 
 ## 影响
 
-macOS 恢复了自定义菜单压掉的窗口和应用命令，代价是四个菜单 role。在非英文的 Desktop 上这些标签仍是英文。
+macOS 恢复了自定义菜单压掉的窗口和应用命令。File、Window 和 Edit 保留 Electron 的默认英文标签；应用命令使用 Desktop 的语言。
 
 ## 测试
 
-`apps/desktop/tests/main-startup.spec.ts` 中的一个用例固定了各平台声明的菜单 role，包括 macOS 的隐藏命令。基于 role 的菜单项由本机执行，因此程序化的 `click()` 和 vitest 的 Electron mock 都无法触达这些快捷键；用真实 Electron 44 运行同一模板显示，只有在本改动之后才出现标准的 File、Window 和应用菜单项，并且在 `app.getLocale()`、`getSystemLocale()` 和 `getPreferredSystemLanguages()` 都报告 `zh-CN` 时标签保持不变。
+`apps/desktop/tests/main-startup.spec.ts` 验证各平台声明的菜单 role，并记录中英文应用标签快照。基于 role 的菜单项由本机执行，因此程序化的 `click()` 和 Vitest 的 Electron mock 都无法触达这些快捷键。独立 Electron 44 demo 确认显式应用标签会显示在原生菜单中；模板快照不能验证原生快捷键的执行。
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 10634b7626..63680a5c0b 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -608,6 +608,7 @@ async function main(): Promise<void> {
   })
   // A custom application menu replaces Electron's default menu, so macOS needs
   // its standard menus and application hide commands declared explicitly.
+  // Keep app.name stable: Electron derives its default userData directory from it.
   const darwin = process.platform === 'darwin'
   const platformMenus: MenuItemConstructorOptions[] = darwin
     ? [{ role: 'fileMenu' }, { role: 'editMenu' }, { role: 'windowMenu' }]

From db7ee5f487a560a54c39b679aec688f150f4b70b Mon Sep 17 00:00:00 2001
From: winewill <leto.wine@gmail.com>
Date: Sun, 20 Sep 2026 15:27:25 +0800
Subject: [PATCH 29/37] build(desktop): parallelize Windows signature cache
 hits

---
 ...-windows-runtime-signature-cache.i18n.yaml |  4 +-
 ...6-09-17-windows-runtime-signature-cache.md |  2 +
 ...9-17-windows-runtime-signature-cache.zh.md |  2 +
 apps/desktop/.env.windows.example             |  3 +
 apps/desktop/README.i18n.yaml                 |  4 +-
 apps/desktop/README.md                        |  4 +-
 apps/desktop/README.zh.md                     |  4 +-
 .../scripts/desktop-package-environment.mjs   |  4 +-
 apps/desktop/scripts/package-target.ts        |  1 +
 apps/desktop/scripts/sign-primary-runtime.ts  |  5 +-
 .../scripts/windows-package-settings.d.mts    |  6 ++
 .../scripts/windows-package-settings.mjs      | 14 ++++
 .../scripts/windows-runtime-signature.d.mts   |  7 +-
 .../scripts/windows-runtime-signature.mjs     | 28 ++++++-
 .../scripts/windows-signature-cache.d.mts     | 12 ++-
 .../scripts/windows-signature-cache.mjs       | 10 ++-
 .../tests/desktop-package-environment.spec.ts | 25 ++++++
 .../tests/package-target-stages.spec.ts       |  7 +-
 .../tests/primary-runtime-signing.spec.ts     | 80 +++++++++++++++++++
 .../tests/windows-signature-cache.spec.ts     | 20 ++++-
 20 files changed, 220 insertions(+), 22 deletions(-)
 create mode 100644 apps/desktop/scripts/windows-package-settings.d.mts
 create mode 100644 apps/desktop/scripts/windows-package-settings.mjs

diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
index b2f71a9f4d..0ace5db1f2 100644
--- a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.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/process/2026-09-17-windows-runtime-signature-cache.md
-2026-09-17-windows-runtime-signature-cache.md: 911e0277199bac55165fbc4adebb22e2599043b9
-2026-09-17-windows-runtime-signature-cache.zh.md: bb8cdd6bdca445c94e8e77cddb68008d7b27f7ad
+2026-09-17-windows-runtime-signature-cache.md: e9229e47929664984a92499e54f87bb2166bde9d
+2026-09-17-windows-runtime-signature-cache.zh.md: 53b6182170d807843345fa90f962ee18807f2cf2
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
index 911e027719..e9229e4792 100644
--- a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
@@ -20,6 +20,8 @@ Serialize each complete signing stage and cache-maintenance operation with an ex
 
 Group public-key inspection into bounded batches of 32 files with at most four processes. Require one ordered result for every requested path and await every process in a failed batch. Preserve verification immediately after each hardware signature, before the next signing request.
 
+Within the stage lock, restore distinct cache-hit targets with a bounded worker pool and complete their post-verification before serially signing misses. Stop dispatch on the first restore, verification or audit failure and drain active workers before releasing ownership. Four workers are the configurable default: warm-cache experiments on 134 primary-runtime and 228 application files reduce combined median restore-plus-post-verification time from 226.18 seconds at one worker to 63.22 seconds at four; eight takes 42.18 seconds but increases measured CPU by 25.5% and peak committed memory from 387 to 631 MiB. These three-repeat measurements use exact reconstructed unsigned inputs, real Windows verification and a rejecting hardware callback; they exclude full packaging, cold trust state and hardware misses.
+
 The [primary-runtime decision](../feature/2026-09-14-desktop-primary-runtime.md) continues to own runtime contents, vendor-signature preservation and execution checks. The [release decision](../architecture/2026-08-25-electron-desktop-packaging-and-updates.md) continues to own release identity and signing. Neither is superseded. The cache must preserve their supervised preflight, per-user signing interlock, single-file hardware calls, signed inventory and final packaged-runtime validation.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
index bb8cdd6bdc..53b6182170 100644
--- a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
@@ -20,6 +20,8 @@ Windows 打包每次都会重新生成未签名的原生依赖。为未变化的
 
 公钥验签按每批 32 个文件分组，最多同时运行四个进程。要求每个请求路径都有一条顺序对应的结果，并等待失败批次中的所有进程退出。每次硬件签名后仍立即验签，通过后才开始下一个签名请求。
 
+在阶段锁内，使用有界工作池恢复不同的缓存命中目标，完成后置验签后才串行签署未命中项。首次恢复、验签或审计失败时停止派发，并在释放所有权前等待在途任务结束。可配置的默认并发为四：对 134 个主要运行时文件及 228 个应用文件的热缓存实验中，恢复加后置验签的合计中位耗时从单任务的 226.18 秒降至四任务的 63.22 秒；八任务为 42.18 秒，但实测 CPU 消耗增加 25.5%，峰值提交内存从 387 增至 631 MiB。这些三轮测量使用精确重建的未签名输入、真实 Windows 验签和拒绝硬件调用的回调；不包含完整打包、冷信任状态或硬件未命中。
+
 [主要运行时决策](../feature/2026-09-14-desktop-primary-runtime.zh.md) 继续定义运行时内容、厂商签名保留和执行检查。[发布决策](../architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md) 继续定义发布身份和签名。两者均未被取代。缓存必须保留受监督预检、每用户签名互锁、单文件硬件调用、已签名内容清单和最终打包运行时验证。
 
 ## Alternatives considered
diff --git a/apps/desktop/.env.windows.example b/apps/desktop/.env.windows.example
index 9b38d46df9..28e35a06d2 100644
--- a/apps/desktop/.env.windows.example
+++ b/apps/desktop/.env.windows.example
@@ -20,6 +20,9 @@ DSH_DESKTOP_WINDOWS_TOKEN_PIN=
 # Optional absolute, private local directory; defaults to %USERPROFILE%\.dsh-desktop-signing\signature-cache\v1.
 # DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_DIR=C:\Users\build\.dsh-desktop-signing\signature-cache\v1
 
+# Cache-hit restore and verification workers (1-8). Hardware signing remains serial.
+DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY=4
+
 # Optional upload configuration; packaging does not require these credentials.
 # DOWNLOAD_TEST_COS_BUCKET=
 # DOWNLOAD_TEST_COS_SECRET_ID=
diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml
index 455501862e..1187d5f1a7 100644
--- a/apps/desktop/README.i18n.yaml
+++ b/apps/desktop/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 apps/desktop/README.md
-README.md: 6c9a6a8784732e6fa1369df5632391b789786b22
-README.zh.md: a0f2184d911eeab46902670cf992b6847e2bca31
+README.md: 8885703f33223d381633c29a11516619d52fd711
+README.zh.md: b5a3f0433d874b3fc51ef16805d7ab6df20d9059
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index 6c9a6a8784..8885703f33 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -232,7 +232,9 @@ Runtime signing shares complete signed files across the current Windows account'
 
 Preflight, primary-runtime signing, application-runtime signing and artifact creation each hold the account's signing-stage lock until their supervised child processes settle. Other builds wait before entering those stages; compilation and preparation do not hold the lock. Runtime signing workers own their locks, so terminating only the outer packaging process does not unlock a surviving cache user. Migration and maintenance acquire the same lock; older or external signing commands do not participate and must be scheduled separately. Stage waiting is outside the preflight deadline. Closing the stage handle releases ordinary contention without removing the separate hardware-attempt interlock; a retained hardware failure still requires operator recovery.
 
-Each runtime stage writes `SIGNATURE_CACHE_SUMMARY` to stdout and its packaging journal, including the actual directory, policy identity, hit/miss counts, newly published and retained entries, signing requests, avoided signing requests and validation failures. Timings distinguish signing, trust verification of restored and newly signed files, and restoration; restoration includes its trust check and staging cleanup. These counters exclude preflight, final artifact signing and the outer runtime signature checks. Stage lock events record waiting separately.
+Cache-hit copying, hashing and per-file trust checks run with `DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY` workers from `.env.windows` (default `4`, integer `1`–`8`). All restores and their post-verification finish before cache misses enter serial hardware signing. A restore or verification failure stops new dispatch and drains active work before releasing the stage lock; hardware signing, runtime smoke checks and final integrity validation remain required.
+
+Each runtime stage writes `SIGNATURE_CACHE_SUMMARY` to stdout and its packaging journal, including the actual directory, policy identity, hit/miss counts, newly published and retained entries, signing requests, avoided signing requests and validation failures. Timings distinguish signing, trust verification of restored and newly signed files, and restoration; restoration includes its trust check and staging cleanup. These counters exclude preflight, final artifact signing and the outer runtime signature checks. Stage lock events record waiting separately. Concurrent timings sum per-file work rather than stage wall time.
 
 Use `pnpm --dir apps/desktop run cache:windows-signatures --usage` to inspect structurally complete-entry bytes and counts, or `--from <absolute-old-cache>` to import an explicitly selected cache owned by the same account. Migration leaves the source unchanged, skips staging names, rejects corrupt entries and retains valid existing entries even when their timestamp bytes differ. `--clear` explicitly removes complete entries under the stage lock; no automatic capacity eviction runs. `--directory <absolute-cache>` selects a maintenance destination without loading release credentials. Incomplete staging entries remain untouched and are counted separately; inspect them only after all builds have stopped. These commands never clear hardware failure evidence. Default storage is outside AppData so MSIX launcher virtualization does not split the account's cache; redirected overrides fail explicitly.
 
diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md
index a0f2184d91..b5a3f0433d 100644
--- a/apps/desktop/README.zh.md
+++ b/apps/desktop/README.zh.md
@@ -232,7 +232,9 @@ Windows 打包使用 Visual C++ Build Tools 和 Windows SDK 编译 x86 Win32/GDI
 
 预检、主要运行时签名、应用运行时签名和产物生成分别持有账户级签名阶段锁，直到受监督的子进程结束。其他构建进入这些阶段前等待；编译和准备步骤不持锁。运行时签名进程自行持锁，因此仅终止外层打包进程不会释放仍在访问缓存的阶段锁。迁移及维护获取同一把锁；旧版或外部签名命令不参与排队，应另行避免并发。阶段等待不计入预检期限。关闭阶段句柄会释放普通竞争锁，不删除独立的硬件尝试互锁；遗留硬件失败仍需操作人员恢复。
 
-每个运行时阶段向标准输出及打包日志写入 `SIGNATURE_CACHE_SUMMARY`，包含实际目录、策略标识、命中及未命中数、新发布及保留项数、签名请求数、省去的签名请求数和验证失败数。计时区分签名、恢复文件和新签名文件的信任验证及恢复；恢复耗时包含其信任检查和暂存清理。这些统计不包含预检、最终产物签名及外层运行时验签。阶段锁事件单独记录等待时间。
+缓存命中的复制、摘要和逐文件信任检查使用 `.env.windows` 中的 `DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY` 个工作任务（默认 `4`，整数 `1`–`8`）。所有恢复及后置验签完成后，未命中项才进入串行硬件签名。恢复或验签失败会停止派发新任务，并在释放阶段锁前等待在途工作结束；硬件签名、运行时 smoke 检查和最终完整性校验仍须执行。
+
+每个运行时阶段向标准输出及打包日志写入 `SIGNATURE_CACHE_SUMMARY`，包含实际目录、策略标识、命中及未命中数、新发布及保留项数、签名请求数、省去的签名请求数和验证失败数。计时区分签名、恢复文件和新签名文件的信任验证及恢复；恢复耗时包含其信任检查和暂存清理。这些统计不包含预检、最终产物签名及外层运行时验签。阶段锁事件单独记录等待时间。 并发计时累加逐文件工作耗时，不代表阶段墙钟时间。
 
 使用 `pnpm --dir apps/desktop run cache:windows-signatures --usage` 查看结构完整的缓存项字节数和数量，或用 `--from <absolute-old-cache>` 导入显式指定、属于同账户的旧缓存。迁移不修改源目录，跳过暂存名称，拒绝损坏项，并保留已有有效项，即使它们的时间戳字节不同。`--clear` 在阶段锁保护下显式删除完整缓存项；不执行自动容量淘汰。`--directory <absolute-cache>` 指定维护目标目录，无需加载发布凭据。不完整暂存项保持原状并单独计数；仅在所有构建停止后检查它们。这些命令绝不清除硬件失败证据。默认存储位于 AppData 之外，避免 MSIX 启动器虚拟化将账户缓存拆开；被重定向的覆盖目录会明确失败。
 
diff --git a/apps/desktop/scripts/desktop-package-environment.mjs b/apps/desktop/scripts/desktop-package-environment.mjs
index c8a794e3c7..f07b9653fa 100644
--- a/apps/desktop/scripts/desktop-package-environment.mjs
+++ b/apps/desktop/scripts/desktop-package-environment.mjs
@@ -10,10 +10,11 @@ import { createWindowsTokenSigner } from './windows-sign.mjs'
 import { resolveDesktopPolicyEnvironment } from './desktop-policy-environment.mjs'
 import { resolveMacOSPackageSettings } from './macos-package-settings.mjs'
 import { resolveWindowsSignatureCacheDirectory } from './windows-signature-cache-directory.mjs'
+import { resolveWindowsPackageSettings } from './windows-package-settings.mjs'
 
 const APP_ROOT = fileURLToPath(new URL('..', import.meta.url))
 const SHARED_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|MANDATORY_UPDATE_(?:CONFIG|(?:TEST|PROD)_ORIGIN))|DOWNLOAD_(?:TEST|PROD)_(?:ORIGIN|COS_BUCKET|COS_SECRET_ID|COS_SECRET_KEY))$/u
-const WINDOWS_SETTING = /^DSH_DESKTOP_WINDOWS_(?:CER_FILE|SIGNTOOL|KEY_CONTAINER|TOKEN_PIN|SIGNATURE_CACHE_DIR)$/u
+const WINDOWS_SETTING = /^DSH_DESKTOP_WINDOWS_(?:CER_FILE|SIGNTOOL|KEY_CONTAINER|TOKEN_PIN|SIGNATURE_CACHE_DIR|SIGNATURE_CACHE_CONCURRENCY)$/u
 const MACOS_SETTING = /^(?:DSH_DESKTOP_MACOS_(?:SIGNING_IDENTITY|TEAM_ID|PACK_CONCURRENCY|DOWNLOAD_PROXY|NOTARIZATION_PROXY)|APPLE_(?:API_KEY|API_KEY_ID|API_ISSUER|ID|APP_SPECIFIC_PASSWORD|TEAM_ID|KEYCHAIN|KEYCHAIN_PROFILE)|CSC_(?:LINK|KEY_PASSWORD))$/u
 const AMBIENT_RELEASE_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|MANDATORY_UPDATE_.*|WINDOWS_.*|MACOS_.*)|APPLE_.*|(?:WIN_)?CSC_.*|DOWNLOAD_(?:TEST|PROD)_.*)$/iu
 const FILE_SETTINGS = ['DSH_DESKTOP_WINDOWS_CER_FILE', 'DSH_DESKTOP_WINDOWS_SIGNTOOL', 'APPLE_API_KEY', 'APPLE_KEYCHAIN', 'CSC_LINK']
@@ -79,6 +80,7 @@ export function validateDesktopPackageEnvironment(environment, target, options =
   resolveDesktopAppId(environment)
   resolveDesktopPolicyEnvironment(environment)
   if (target.platform === 'darwin') resolveMacOSPackageSettings(environment)
+  else resolveWindowsPackageSettings(environment)
   if (options.unsigned) return
   if (!options.prepareOnly) resolveDesktopAutoUpdateConfig(environment, target.platform, target.arch)
   if (target.platform === 'win32') {
diff --git a/apps/desktop/scripts/package-target.ts b/apps/desktop/scripts/package-target.ts
index 651bd64cce..688d3d9671 100644
--- a/apps/desktop/scripts/package-target.ts
+++ b/apps/desktop/scripts/package-target.ts
@@ -30,6 +30,7 @@ const WINDOWS_SIGNING_ENV_NAMES = [
   'DSH_DESKTOP_WINDOWS_SIGNTOOL',
   'DSH_DESKTOP_WINDOWS_TOKEN_PIN',
   'DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_DIR',
+  'DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY',
 ] as const
 const DESKTOP_UPLOAD_CREDENTIAL_ENV_NAMES = new Set([
   'DOWNLOAD_TEST_COS_SECRET_ID',
diff --git a/apps/desktop/scripts/sign-primary-runtime.ts b/apps/desktop/scripts/sign-primary-runtime.ts
index d48711b4a0..d9a9b36c25 100644
--- a/apps/desktop/scripts/sign-primary-runtime.ts
+++ b/apps/desktop/scripts/sign-primary-runtime.ts
@@ -5,6 +5,7 @@ import { join, resolve } from 'node:path'
 import { createWindowsTokenSigner } from './windows-sign.mjs'
 import { inspectWindowsRuntimeSignature, signWindowsCode, type WindowsCodeSigningOptions } from './windows-runtime-signature.mjs'
 import { createCachedSigner, signatureCacheIdentity } from './windows-signature-cache.mjs'
+import { resolveWindowsPackageSettings } from './windows-package-settings.mjs'
 import { prepareWindowsSignatureCacheDirectory, resolveWindowsSignatureCacheDirectory } from './windows-signature-cache-directory.mjs'
 import { withWindowsSigningStage } from './windows-signing-stage.mjs'
 import { failPackagingRun, recordPackagingEvent } from './packaging-run.mjs'
@@ -46,6 +47,7 @@ export async function signWindowsDesktopRuntime(root: string, version: string,
 
 async function main(): Promise<void> {
   if (process.platform !== 'win32' || resolveDesktopBuildTarget() !== 'win-x64') throw new Error('primary runtime signing requires Windows x64')
+  const { signatureCacheConcurrency } = resolveWindowsPackageSettings(process.env)
   const runDirectory = process.env.DSH_DESKTOP_PACKAGING_RUN_DIR
   if (!runDirectory) throw new Error('primary runtime signing requires a supervised packaging run')
   await readFile(join(runDirectory, 'run.json'))
@@ -67,7 +69,8 @@ async function main(): Promise<void> {
       await prepareWindowsSignatureCacheDirectory(cacheRoot)
       const cachedSign = createCachedSigner({ root: cacheRoot, identity, thumbprint,
         sign, inspect: inspectWindowsRuntimeSignature, record })
-      const options = { thumbprint, sign: cachedSign, record }
+      const options = { thumbprint, sign: cachedSign, record,
+        cache: { restore: cachedSign.restore, concurrency: signatureCacheConcurrency } }
       record({ type: 'signature-cache-open', root: cachedSign.summary().root, identity })
       try {
         if (process.argv.includes('--dsh')) {
diff --git a/apps/desktop/scripts/windows-package-settings.d.mts b/apps/desktop/scripts/windows-package-settings.d.mts
new file mode 100644
index 0000000000..a7627e3b7d
--- /dev/null
+++ b/apps/desktop/scripts/windows-package-settings.d.mts
@@ -0,0 +1,6 @@
+/**
+ * Validate the file-owned Windows cache worker limit before packaging starts.
+ * @param environment Windows packaging settings loaded from .env.windows.
+ * @returns Worker limit from one to eight, defaulting to four when omitted; invalid values throw.
+ */
+export function resolveWindowsPackageSettings(environment: NodeJS.ProcessEnv): { signatureCacheConcurrency: number }
diff --git a/apps/desktop/scripts/windows-package-settings.mjs b/apps/desktop/scripts/windows-package-settings.mjs
new file mode 100644
index 0000000000..847849af97
--- /dev/null
+++ b/apps/desktop/scripts/windows-package-settings.mjs
@@ -0,0 +1,14 @@
+/** Resolve file-owned Windows signature-cache concurrency before packaging starts. */
+
+/**
+ * Validate the cache worker limit without accessing signing hardware.
+ * @param {NodeJS.ProcessEnv} environment File-owned Windows packaging settings.
+ * @returns {{signatureCacheConcurrency: number}} Worker limit, defaulting to four when omitted.
+ */
+export function resolveWindowsPackageSettings(environment) {
+  const value = environment.DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY ?? '4'
+  if (!/^[1-8]$/u.test(value)) {
+    throw new Error('desktop package: DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY must be an integer from 1 to 8')
+  }
+  return { signatureCacheConcurrency: Number(value) }
+}
diff --git a/apps/desktop/scripts/windows-runtime-signature.d.mts b/apps/desktop/scripts/windows-runtime-signature.d.mts
index 9c6e207a17..f47e306885 100644
--- a/apps/desktop/scripts/windows-runtime-signature.d.mts
+++ b/apps/desktop/scripts/windows-runtime-signature.d.mts
@@ -31,6 +31,11 @@ export interface WindowsCodeSigningOptions {
   sign: ReturnType<typeof import('./windows-sign.mjs').createWindowsTokenSigner>
   inspect?: typeof inspectWindowsRuntimeSignature
   record: (event: object) => void
+  /** Hardware-free restores on distinct targets; concurrency is a resolved positive integer. All restores and their verification drain before serial signing starts. */
+  cache?: {
+    restore: import('./windows-signature-cache.mjs').WindowsCachedSigner['restore']
+    concurrency: number
+  }
 }
 
 /**
@@ -44,7 +49,7 @@ export function windowsRuntimeCode(root: string): Promise<string[]>
  * Preserve valid signatures and sign unsigned PE files with a supervised signer.
  * @param root Materialized directory to sign.
  * @param options Signer, certificate identity and audit sink.
- * @returns Resolves after verified sequential signing; rejects without retries.
+ * @returns Resolves after verified parallel cache restores and sequential signing; stops dispatch and drains active restores on failure, without retries.
  */
 export function signWindowsCode(root: string, options: WindowsCodeSigningOptions): Promise<void>
 
diff --git a/apps/desktop/scripts/windows-runtime-signature.mjs b/apps/desktop/scripts/windows-runtime-signature.mjs
index ee70330fd7..8780f182ca 100644
--- a/apps/desktop/scripts/windows-runtime-signature.mjs
+++ b/apps/desktop/scripts/windows-runtime-signature.mjs
@@ -101,7 +101,7 @@ async function inspectWindowsCode(files, inspect) {
  * Preserve valid signatures and sign unsigned PE files with a supervised signer.
  * @param {string} root - Owned final runtime directory.
  * @param {import('./windows-runtime-signature.mjs').WindowsCodeSigningOptions} options - Supervised signer, certificate identity, audit sink.
- * @returns {Promise<void>} Resolves only after sequential signatures and verification; no retries.
+ * @returns {Promise<void>} Resolves after bounded cache restores and sequential hardware signing, each with verification; failures drain active restores before rejecting.
  */
 export async function signWindowsCode(root, options) {
   const inspect = options.inspect ?? inspectWindowsRuntimeSignature
@@ -116,14 +116,36 @@ export async function signWindowsCode(root, options) {
     else if (signature.status !== 'Valid') throw new Error(`Windows code: refusing ${signature.status} signature: ${path}`)
   }
   options.record({ type: 'windows-code-signing-plan', files: files.length, unsigned: unsigned.length })
-  for (const path of unsigned) {
-    await options.sign({ path, hash: 'sha256', isNest: false })
+  async function verifySigned(path) {
     const signature = await inspect(path)
     if (signature.status !== 'Valid' || !signature.timestamped || signature.thumbprint?.toUpperCase() !== options.thumbprint.toUpperCase()) {
       throw new Error(`Windows code: signing verification failed: ${path}`)
     }
     options.record({ type: 'windows-code-signature-verified', path, ...signature })
   }
+  const restored = new Set()
+  if (options.cache) {
+    let next = 0
+    let failure
+    const worker = async () => {
+      while (failure === undefined && next < unsigned.length) {
+        const path = unsigned[next++]
+        try {
+          if (await options.cache.restore({ path, hash: 'sha256', isNest: false })) {
+            await verifySigned(path)
+            restored.add(path)
+          }
+        } catch (error) { failure ??= { error } }
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(options.cache.concurrency, unsigned.length) }, worker))
+    if (failure !== undefined) throw failure.error
+  }
+  for (const path of unsigned) {
+    if (restored.has(path)) continue
+    await options.sign({ path, hash: 'sha256', isNest: false })
+    await verifySigned(path)
+  }
 }
 
 /**
diff --git a/apps/desktop/scripts/windows-signature-cache.d.mts b/apps/desktop/scripts/windows-signature-cache.d.mts
index e68abdf345..dcc2301371 100644
--- a/apps/desktop/scripts/windows-signature-cache.d.mts
+++ b/apps/desktop/scripts/windows-signature-cache.d.mts
@@ -18,7 +18,7 @@ export interface WindowsSignatureCacheOptions {
  */
 export function signatureCacheIdentity(files: readonly string[]): Promise<string>
 
-/** Counters include failed attempts; verification covers both restored and newly signed files, while restore time includes its verification and staging cleanup. */
+/** Counters include failed attempts; times sum per-file work. Verification covers restored and newly signed files; restore time includes its verification and staging cleanup. */
 export interface WindowsSignatureCacheSummary {
   root: string
   identity: string
@@ -34,8 +34,14 @@ export interface WindowsSignatureCacheSummary {
   signingMs: number
 }
 
-/** Serial cache callback with a snapshot of this instance's completed and failed operations. */
+/** Serial signing callback with a separate hardware-free restore operation and shared counters. */
 export type WindowsCachedSigner = ReturnType<typeof createWindowsTokenSigner> & {
+  /**
+   * Restore a hit without accessing hardware; distinct targets may run concurrently under the stage lock.
+   * @param configuration Unsigned target owned exclusively by the caller.
+   * @returns True after verified replacement, false for an absent entry without counting a signing miss; corrupt entries reject. The caller drains all restores before signing or reporting failure.
+   */
+  restore(configuration: Parameters<ReturnType<typeof createWindowsTokenSigner>>[0]): Promise<boolean>
   /** @returns Current counters and elapsed times; does not wait for queued operations. */
   summary(): WindowsSignatureCacheSummary
 }
@@ -43,7 +49,7 @@ export type WindowsCachedSigner = ReturnType<typeof createWindowsTokenSigner> &
 /**
  * Reuse complete signed files only after input, integrity, identity and timestamp checks.
  * @param options Cache policy, supervised signer, public-key verifier and audit sink.
- * @returns Serial signer that stops its queue on any failure and never repairs invalid cache entries.
+ * @returns Serial fail-stop signer with hardware-free restores; invalid cache entries are never repaired.
  */
 export function createCachedSigner(options: WindowsSignatureCacheOptions): WindowsCachedSigner
 
diff --git a/apps/desktop/scripts/windows-signature-cache.mjs b/apps/desktop/scripts/windows-signature-cache.mjs
index 1df9cd955f..39f75da374 100644
--- a/apps/desktop/scripts/windows-signature-cache.mjs
+++ b/apps/desktop/scripts/windows-signature-cache.mjs
@@ -125,7 +125,7 @@ export async function maintainSignatureCache(root, clear = false) {
 /**
  * Wrap a supervised signer with immutable entries keyed by unsigned bytes and signing policy.
  * @param {import('./windows-signature-cache.mjs').WindowsSignatureCacheOptions} options Cache policy and existing supervised operations.
- * @returns {import('./windows-signature-cache.mjs').WindowsCachedSigner} Serial, fail-stop callback with counters; cache hits still verify trust and timestamp.
+ * @returns {import('./windows-signature-cache.mjs').WindowsCachedSigner} Serial, fail-stop signer plus hardware-free restores; cache hits still verify trust and timestamp.
  */
 export function createCachedSigner(options) {
   let pending = Promise.resolve()
@@ -142,7 +142,7 @@ export function createCachedSigner(options) {
     if (record.inputDigest !== inputDigest || record.identity !== options.identity) throw new Error('signature cache: invalid input record')
     return record
   }
-  async function sign(configuration) {
+  async function sign(configuration, restoreOnly = false) {
     if (configuration.hash !== 'sha256' || configuration.isNest) throw new Error('signature cache: only unsigned SHA-256 runtime files are supported')
     const inputDigest = digest(await regularFile(configuration.path))
     const key = digest(JSON.stringify({ version: 1, inputDigest, identity: options.identity }))
@@ -173,8 +173,9 @@ export function createCachedSigner(options) {
       } finally { statistics.restoreMs += performance.now() - start }
       statistics.hits++
       options.record({ type: 'signature-cache-hit', key, path: configuration.path })
-      return
+      return true
     }
+    if (restoreOnly) return false
     statistics.misses++
     options.record({ type: 'signature-cache-miss', key, path: configuration.path })
     const start = performance.now()
@@ -210,9 +211,10 @@ export function createCachedSigner(options) {
     } finally { await rm(staging, { recursive: true, force: true }) }
   }
   const signer = configuration => {
-    pending = pending.then(() => sign(configuration))
+    pending = pending.then(async () => { await sign(configuration) })
     return pending
   }
+  signer.restore = configuration => sign(configuration, true)
   signer.summary = () => ({ root: options.root, identity: options.identity, ...statistics, avoidedSigningCalls: statistics.hits })
   return signer
 }
diff --git a/apps/desktop/tests/desktop-package-environment.spec.ts b/apps/desktop/tests/desktop-package-environment.spec.ts
index 7153f135a3..6335fe8eaa 100644
--- a/apps/desktop/tests/desktop-package-environment.spec.ts
+++ b/apps/desktop/tests/desktop-package-environment.spec.ts
@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { loadDesktopPackageEnvironment, validateDesktopPackageEnvironment } from '../scripts/desktop-package-environment.mjs'
+import { resolveWindowsPackageSettings } from '../scripts/windows-package-settings.mjs'
 
 const WINDOWS = { platform: 'win32', arch: 'x64' } as const
 const MACOS = { platform: 'darwin', arch: 'arm64' } as const
@@ -21,6 +22,30 @@ async function withDirectory(action: (directory: string) => Promise<void>): Prom
 }
 
 describe('Desktop local packaging configuration', () => {
+  it('takes cache concurrency from the Windows file and defaults to four without ambient overrides', async () => {
+    await withDirectory(async (directory) => {
+      const parent = { DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: '8' }
+      await writeFile(join(directory, '.env.windows'), '')
+      expect(resolveWindowsPackageSettings(loadDesktopPackageEnvironment('win32', parent, directory)).signatureCacheConcurrency).toBe(4)
+      await writeFile(join(directory, '.env.windows'), 'DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY=2\n')
+      expect(resolveWindowsPackageSettings(loadDesktopPackageEnvironment('win32', parent, directory)).signatureCacheConcurrency).toBe(2)
+    })
+  })
+
+  it.each(['1', '2', '4', '8'])('accepts cache concurrency %s', (value) => {
+    const settings = resolveWindowsPackageSettings({ DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: value })
+    expect(settings.signatureCacheConcurrency).toBe(Number(value))
+  })
+
+  it.each(['', '0', '-1', '9', '1.5', 'Infinity', '01'])('rejects invalid cache concurrency %s', (value) => {
+    expect(() => resolveWindowsPackageSettings({ DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: value })).toThrow('integer from 1 to 8')
+    for (const options of [{ unsigned: true }, { prepareOnly: true }]) {
+      expect(() => {
+        validateDesktopPackageEnvironment({ ...RELEASE, DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: value }, WINDOWS, options)
+      }).toThrow('integer from 1 to 8')
+    }
+  })
+
   it('selects the platform file, preserves literal secrets, and excludes stale ambient release settings', async () => {
     await withDirectory(async (directory) => {
       await writeFile(join(directory, '.env.windows'), '\uFEFFDSH_DESKTOP_APP_ID=com.example.windows\r\nDSH_DESKTOP_WINDOWS_TOKEN_PIN=" #!$%&literal "\r\nDSH_DESKTOP_WINDOWS_CER_FILE="keys/public certificate.cer"\r\n')
diff --git a/apps/desktop/tests/package-target-stages.spec.ts b/apps/desktop/tests/package-target-stages.spec.ts
index 5b8880ce6a..410c853fc8 100644
--- a/apps/desktop/tests/package-target-stages.spec.ts
+++ b/apps/desktop/tests/package-target-stages.spec.ts
@@ -29,7 +29,8 @@ vi.mock('node:fs', async importOriginal => ({
 afterEach(() => { vi.unstubAllEnvs(); vi.clearAllMocks() })
 
 const environment = { DSH_DESKTOP_APP_ID: 'com.example.test', DSH_DESKTOP_AUTO_UPDATE_ENV: 'test',
-  DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com', DSH_DESKTOP_WINDOWS_TOKEN_PIN: 'fixture-pin' }
+  DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com', DSH_DESKTOP_WINDOWS_TOKEN_PIN: 'fixture-pin',
+  DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: '2' }
 
 function supervisor(failure?: string) {
   vi.stubEnv('npm_execpath', 'fixture-pnpm.cjs')
@@ -56,6 +57,10 @@ it('requires one signing preflight before building, then records only the comple
   for (const call of run.run.mock.calls) {
     if (call[0].startsWith('run prepare:') || call[0].includes('smoke-packaged-runtime')) {
       expect(call[3].env).not.toHaveProperty('DSH_DESKTOP_WINDOWS_TOKEN_PIN')
+      expect(call[3].env).not.toHaveProperty('DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY')
+    }
+    if (call[0].startsWith('run sign:primary-runtime')) {
+      expect(call[3].env).toHaveProperty('DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY', '2')
     }
   }
   expect(writeFileSync).toHaveBeenCalledOnce()
diff --git a/apps/desktop/tests/primary-runtime-signing.spec.ts b/apps/desktop/tests/primary-runtime-signing.spec.ts
index 242c93f339..5c7b4aa080 100644
--- a/apps/desktop/tests/primary-runtime-signing.spec.ts
+++ b/apps/desktop/tests/primary-runtime-signing.spec.ts
@@ -26,6 +26,86 @@ async function fixture(names = ['a.exe', 'b.pyd', 'vendor.dll']): Promise<string
 
 afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }) })
 
+it('bounds overlapping cache restores and verifies all hits before serial hardware misses', async () => {
+  const root = await fixture(['a.exe', 'b.exe', 'c.exe', 'd.exe'])
+  const entered = Promise.withResolvers<undefined>()
+  const release = Promise.withResolvers<undefined>()
+  const signed = new Set<string>()
+  const verified = new Set<string>()
+  let active = 0
+  let peak = 0
+  let hits = 0
+  const sign = vi.fn(async ({ path }: { path: string }) => {
+    expect(active).toBe(0)
+    expect(hits).toBe(2)
+    expect(verified.has(join(root, 'a.exe')) && verified.has(join(root, 'b.exe'))).toBe(true)
+    signed.add(path)
+  })
+  const operation = signWindowsCode(root, { thumbprint, record: () => {}, sign,
+    inspect: async (path) => {
+      if (!signed.has(path)) return unsigned
+      verified.add(path)
+      return valid
+    },
+    cache: { concurrency: 2, restore: async ({ path }) => {
+      active++
+      peak = Math.max(peak, active)
+      if (active === 2) entered.resolve(undefined)
+      await release.promise
+      active--
+      if (path.endsWith('a.exe') || path.endsWith('b.exe')) { signed.add(path); hits++; return true }
+      return false
+    } },
+  })
+  try {
+    await Promise.race([entered.promise, operation])
+    expect(sign).not.toHaveBeenCalled()
+  } finally { release.resolve(undefined); await operation }
+  expect(peak).toBe(2)
+  expect(sign.mock.calls.map(([request]) => request.path)).toEqual(['c.exe', 'd.exe'].map(name => join(root, name)))
+})
+
+it.each(['restore', 'verification', 'audit'])('drains active cache restores after %s failure without dispatching more work', async (failure) => {
+  const root = await fixture(['a.exe', 'b.exe', 'c.exe'])
+  const entered = Promise.withResolvers<undefined>()
+  const release = Promise.withResolvers<undefined>()
+  const failed = Promise.withResolvers<undefined>()
+  const restored = new Set<string>()
+  const calls: string[] = []
+  const sign = vi.fn(async () => {})
+  let settled = false
+  const operation = signWindowsCode(root, { thumbprint, sign,
+    record: (event) => {
+      if (failure === 'audit' && 'type' in event && event.type === 'windows-code-signature-verified') {
+        failed.resolve(undefined)
+        throw new Error('audit failed')
+      }
+    },
+    inspect: async (path) => {
+      if (!restored.has(path)) return unsigned
+      if (failure === 'verification' && path.endsWith('a.exe')) { failed.resolve(undefined); throw new Error('verification failed') }
+      return valid
+    },
+    cache: { concurrency: 2, restore: async ({ path }) => {
+      calls.push(path)
+      if (path.endsWith('b.exe')) { entered.resolve(undefined); await release.promise; return false }
+      await entered.promise
+      if (failure === 'restore') { failed.resolve(undefined); throw new Error('restore failed') }
+      restored.add(path)
+      return true
+    } },
+  }).then(() => { settled = true; return undefined }, (error: unknown) => { settled = true; return error })
+  try {
+    await Promise.race([failed.promise, operation])
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(settled).toBe(false)
+    expect(sign).not.toHaveBeenCalled()
+  } finally { release.resolve(undefined); await operation }
+  expect(await operation).toEqual(new Error(`${failure} failed`))
+  expect(calls).toEqual(['a.exe', 'b.exe'].map(name => join(root, name)))
+  expect(sign).not.toHaveBeenCalled()
+})
+
 it('selects real PE code, including .node, without signing foreign native modules or data', async () => {
   const root = await fixture(['runtime.node', 'python.exe', 'extensionless', 'custom.binary'])
   await mkdir(join(root, 'nested'))
diff --git a/apps/desktop/tests/windows-signature-cache.spec.ts b/apps/desktop/tests/windows-signature-cache.spec.ts
index 975feb6fbe..9514b102e5 100644
--- a/apps/desktop/tests/windows-signature-cache.spec.ts
+++ b/apps/desktop/tests/windows-signature-cache.spec.ts
@@ -23,6 +23,22 @@ async function fixture(t: TestContext) {
   return { root, path, cache, state, options, request }
 }
 
+test('restore misses leave inputs and hardware untouched, then share a cached payload across targets', async (t) => {
+  const f = await fixture(t)
+  const signer = createCachedSigner(f.options)
+  assert.equal(await signer.restore(f.request), false)
+  assert.equal(f.state.hardwareCalls, 0)
+  assert.equal(signer.summary().misses, 0)
+  assert.equal(await readFile(f.path, 'utf8'), 'original')
+  await signer(f.request)
+  const targets = [join(f.root, 'first.node'), join(f.root, 'second.node')]
+  await Promise.all(targets.map(path => writeFile(path, 'original')))
+  assert.deepEqual(await Promise.all(targets.map(path => signer.restore({ ...f.request, path }))), [true, true])
+  assert.deepEqual(await Promise.all(targets.map(path => readFile(path, 'utf8'))), ['signed:original', 'signed:original'])
+  assert.equal(f.state.hardwareCalls, 1)
+  assert.equal(signer.summary().hits, 2)
+})
+
 test('unchanged bytes restored in another file avoid another hardware call', async (t) => {
   const f = await fixture(t)
   await createCachedSigner(f.options)(f.request)
@@ -71,7 +87,7 @@ test('different content or signing policy misses the cache', async (t) => {
   assert.equal(f.state.hardwareCalls, 3)
 })
 
-for (const corrupt of ['payload', 'record.json']) test(`corrupt ${corrupt} stops without signing or replacing the input`, async (t) => {
+for (const restoreOnly of [false, true]) for (const corrupt of ['payload', 'record.json']) test(`corrupt ${corrupt} stops without signing or replacing the input (restore-only: ${restoreOnly})`, async (t) => {
   const f = await fixture(t)
   await createCachedSigner(f.options)(f.request)
   await writeFile(f.path, 'original')
@@ -79,7 +95,7 @@ for (const corrupt of ['payload', 'record.json']) test(`corrupt ${corrupt} stops
   assert(entry)
   await writeFile(join(f.cache, entry, corrupt), 'corrupt')
   const signer = createCachedSigner(f.options)
-  await assert.rejects(signer(f.request))
+  await assert.rejects(restoreOnly ? signer.restore(f.request) : signer(f.request))
   assert.equal(signer.summary().validationFailures, 1)
   assert.equal(signer.summary().avoidedSigningCalls, 0)
   assert.equal(f.state.hardwareCalls, 1)

From 8b8f10a8c6f8e181b4a3bb681d25d0f4bd24a890 Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Sun, 20 Sep 2026 15:39:48 +0800
Subject: [PATCH 30/37] docs(ui-sidebar): scope the Windows caption bubble
 claim

The previous sentence claimed every caption icon bubble opens below the caption, but only the sidebar toggle and New Session derive side=bottom; an occupying sidebar.toggle.badge keeps the default side.
---
 packages/client/ui-sidebar/README.i18n.yaml | 4 ++--
 packages/client/ui-sidebar/README.md        | 2 +-
 packages/client/ui-sidebar/README.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index e45ccfc67e..9703fded4a 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/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-sidebar/README.md
-README.md: beedede7fa15bbd1e60b3b688302a95c3c9d5f41
-README.zh.md: adc3dfff1ec946e07bc5a4790f691123a5a32ed0
+README.md: 70489f5f4a8892996f455d21a9493a865990dc49
+README.zh.md: c9691315284c62b126043d070ec071d410fe38ce
diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md
index beedede7fa..70489f5f4a 100644
--- a/packages/client/ui-sidebar/README.md
+++ b/packages/client/ui-sidebar/README.md
@@ -41,7 +41,7 @@ The top expand button hosts the optional, non-interactive `sidebar.toggle.badge`
 
 During a live collapse, the expanded content fades out at its current width, the upper controls share one fade and leftward translation into the 56px rail, and the layout's column slide ends the motion. A page that starts collapsed renders the rail statically, and reduced-motion mode disables both transitions. The bottom-pinned `sidebar.settings` control shares the fade timing but has no horizontal translation.
 
-On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region. Their hover bubbles open below the caption, where the Desktop-owned menu text cannot cover them.
+On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region. The sidebar toggle and New Session bubbles open below the caption, where the Desktop-owned menu text cannot cover them; a `sidebar.toggle.badge` occupant keeps its default side.
 
 ### macOS desktop
 
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index adc3dfff1e..c969131528 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -41,7 +41,7 @@ dsh Web 客户端的侧边栏让用户识别当前构建、启动新会话、将
 
 实时收起时，展开内容在当前宽度淡出，上方控件共用同一段透明度渐变，并向左平移进入 56px 轨道，由布局的栏滑动结束整段动画。页面初始即为收起状态时会静态渲染轨道；减少动态效果模式会禁用两段过渡。固定在底部的 `sidebar.settings` 控件共用相同的透明度渐变时序，但不发生横向位移。
 
-在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。其悬停提示在顶栏下方展开，Desktop 菜单文字不会盖住它们。
+在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。侧栏开关与新建会话的悬停提示在顶栏下方展开，Desktop 菜单文字不会盖住它们；占用 `sidebar.toggle.badge` 的控件保持默认展开方向。
 
 ### macOS 桌面
 

From e44efedeb00498e1522160578e788f98d597569a Mon Sep 17 00:00:00 2001
From: Dudu-0223 <fsyo0223@gmail.com>
Date: Sun, 20 Sep 2026 15:44:52 +0800
Subject: [PATCH 31/37] fix(session): isolate corrupt compressed headers during
 discovery

---
 apps/web/tests/preset-migration.snapshot.ts   |  8 ++++
 .../README.i18n.yaml                          |  4 +-
 .../session-persistence-jsonl/README.md       |  2 +-
 .../session-persistence-jsonl/README.zh.md    |  2 +-
 .../session-persistence-jsonl/src/index.ts    | 22 +++++------
 .../tests/catalog-migration.spec.ts           | 39 ++++++++++++++-----
 .../tests/zstd.spec.ts                        | 10 +++--
 7 files changed, 60 insertions(+), 27 deletions(-)

diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts
index 42e69f65ef..37fdd06073 100644
--- a/apps/web/tests/preset-migration.snapshot.ts
+++ b/apps/web/tests/preset-migration.snapshot.ts
@@ -51,8 +51,14 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
           data: { turn: 1, reason: { kind: 'completed' } } }) + '\n')),
       ]))
       const brokenSource = await readFile(brokenPath)
+      const corruptHeaderId = SessionId('preset-migration-corrupt-header')
+      const corruptHeaderPath = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, corruptHeaderId, 2, 'zstd')
+      const corruptHeaderSource = Buffer.from('invalid Zstandard header frame')
+      await mkdir(dirname(corruptHeaderPath), { recursive: true })
+      await writeFile(corruptHeaderPath, corruptHeaderSource)
       const listed = await scaffold.ctx.sessionController.list({}, new AbortController().signal)
       expect(listed.items.map(item => item.sessionId)).toEqual(expect.arrayContaining([id, childId, brokenId]))
+      expect(listed.items.map(item => item.sessionId)).not.toContain(corruptHeaderId)
 
       const reader = await scaffold.ctx.sessionPersistence.open(id, 'read')
       try {
@@ -123,6 +129,8 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
       const context = { sessionIds: [id], cwd: scaffold.workspaceCwd }
       expect(normalizeSessionSnapshots([published], context)).toEqual(normalizeSessionSnapshots([expected], context))
       expect(await readFile(predecessor)).toEqual(source)
+      await expect(scaffold.ctx.sessionPersistence.open(corruptHeaderId, 'read')).rejects.toThrow(/invalid frame magic/)
+      expect(await readFile(corruptHeaderPath)).toEqual(corruptHeaderSource)
       expect((await readdir(dirname(predecessor))).filter(name => name.endsWith('.jsonl.zstd')).sort())
         .toEqual(['session.v2.jsonl.zstd', `session.v${SESSION_FORMAT_VERSION}.jsonl.zstd`])
     } finally {
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 4f0d2c2fe3..4b42d7fa5e 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: 609368aa42f1ba75d818a74877fcd574bf9d5ddf
-README.zh.md: 07c0dc94270ddb69812ec8443688a505269eba59
+README.md: 5846404961caaef7a91fb4dda562655d15fd2be9
+README.zh.md: b7dd646e57b75fe47f3683d2b230dace628f8eee
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index 609368aa42..5846404961 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -81,7 +81,7 @@ The current-generation scanner applies the current codec owner’s structural ad
 
 `open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Current revisions identify that file; historical revisions also fingerprint the selected files across the persistence root, so child changes invalidate cached logical events. Fingerprinting reads filesystem metadata only; unrelated changes conservatively invalidate historical revisions. One `list()` call shares a corpus fingerprint across its historical entries. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
-Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers are omitted from discovery. Child decoding and descriptor-field failures produce warnings naming the child path and retain header identity through `subagent/catalog` when the parent has no complete entry; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors likewise produce unknown-mode membership without inventing a label. Published unknown entries remain browsable; child history reads retry the actual log and resolve its mode from a valid descriptor. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
+Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers, including corrupt Zstandard header frames, are omitted from discovery and `list()`. Direct access to a corrupt compressed header still rejects; header I/O and cancellation errors propagate. Child decoding and descriptor-field failures produce warnings naming the child path and retain header identity through `subagent/catalog` when the parent has no complete entry; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors likewise produce unknown-mode membership without inventing a label. Published unknown entries remain browsable; child history reads retry the actual log and resolve its mode from a valid descriptor. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
 
 Historical `stat` and `list` revisions require metadata work proportional to the root’s Session count. Fresh body preparation scans all selected headers and decodes direct-child bodies; memo reuse still scans membership and checks revisions. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat that work. Current V4 body reads and revisions avoid the historical corpus scan. See the [measured costs and diagnostic command](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements).
 
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 07c0dc9427..b7dd646e57 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -81,7 +81,7 @@ kind: "package-reference"
 
 `open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；每个嵌套对象和数组都会冻结，句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的修订号。当前格式修订号标识该文件；历史格式修订号还包含持久化根目录中所选文件的指纹，因此子日志变化会使缓存的逻辑事件失效。指纹只读取文件系统元数据；无关变化也会保守地使历史修订号失效。一次 `list()` 为其历史条目共用一个全库指纹。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
-历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header 不参与发现。子日志解码或 descriptor 字段失败会产生带子路径的警告；父目录没有完整条目时，通过 `subagent/catalog` 保留 header 身份信息。健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 同样生成模式未知的目录项，不编造标签。已发布的未知条目仍可浏览；读取子历史时会重试实际日志，并从有效 descriptor 确定模式。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
+历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header（包括损坏的 Zstandard header 帧）不参与发现，也不出现在 `list()` 中。直接访问损坏的压缩 header 仍会失败；header 的 I/O 错误与取消错误继续传播。子日志解码或 descriptor 字段失败会产生带子路径的警告；父目录没有完整条目时，通过 `subagent/catalog` 保留 header 身份信息。健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 同样生成模式未知的目录项，不编造标签。已发布的未知条目仍可浏览；读取子历史时会重试实际日志，并从有效 descriptor 确定模式。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
 
 历史格式的 `stat` 与 `list` 修订号需要与根目录 Session 数量成正比的元数据工作。首次正文准备扫描所有所选 header 并解码直属子正文；复用准备缓存仍扫描成员集合并检查修订。只读访问从不发布升级，因此冷进程与被淘汰的准备缓存会重复这些工作。当前 V4 正文读取和修订号避开历史全库扫描。见[实测成本与诊断命令](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements)。
 
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 24ee0d013e..1a89b76d29 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -1067,7 +1067,7 @@ class JsonlSessionPersistence extends SessionPersistence {
       try {
         header = await this.readGenerationHeader(selected, undefined, signal)
       } catch (error: unknown) {
-        if (error instanceof SessionFormatUnsupportedError) continue
+        if (error instanceof SessionFormatUnsupportedError || error instanceof SessionPersistenceCorruptionError) continue
         throw error
       }
       if (header === undefined) {
@@ -1406,7 +1406,7 @@ class JsonlSessionPersistence extends SessionPersistence {
     }
   }
 
-  /** Read and validate only the independently compressed header frame. */
+  /** Read only the header frame; compression failures reject as corruption, while I/O and cancellation propagate. */
   private async readFirstZstdLine(path: string, signal?: AbortSignal): Promise<string | undefined> {
     signal?.throwIfAborted()
     const handle = await open(path, 'r')
@@ -1422,21 +1422,21 @@ class JsonlSessionPersistence extends SessionPersistence {
         signal?.throwIfAborted()
         content = Buffer.concat([content, chunk.subarray(0, bytesRead)])
         signal?.throwIfAborted()
-        const first = scanZstdFrames(content, 1).frames[0]
-        signal?.throwIfAborted()
-        if (first === undefined) continue
-        let plaintext: Buffer
         try {
+          const first = scanZstdFrames(content, 1).frames[0]
+          if (first === undefined) continue
+          const plaintext = await decompressZstdFrame(content.subarray(first.start, first.end))
           signal?.throwIfAborted()
-          plaintext = await decompressZstdFrame(content.subarray(first.start, first.end))
+          assertZstdHeaderFrame(plaintext)
+          return plaintext.subarray(0, -1).toString('utf8')
         } catch (error) {
           /* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
           if (signal?.aborted) signal.throwIfAborted()
-          throw new Error('corrupt Zstandard session log: header frame failed validation', { cause: error })
+          throw new SessionPersistenceCorruptionError(
+            `corrupt Zstandard session log: header frame failed validation: ${String(error)} (raw log: ${path})`,
+            { cause: error },
+          )
         }
-        signal?.throwIfAborted()
-        assertZstdHeaderFrame(plaintext)
-        return plaintext.subarray(0, -1).toString('utf8')
       }
     } finally {
       await handle.close()
diff --git a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
index e4c6d677a9..6abb14c0db 100644
--- a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
@@ -58,15 +58,36 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     await expect(f.ctx.sessionPersistence.open(f.parent, access)).rejects.toThrow('wrong Session')
   })
 
-  it('opens the parent when another Session header cannot be read', async () => {
-    const f = await fixture()
-    const path = await f.write('child', [], true)
-    await writeFile(path, compression === 'none' ? '{broken header\n' : await compressZstdFrame('{broken header\n'))
-    expect(await f.read()).toEqual([])
-    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    await writer.close()
-    expect(await readFile(generationLogPath(f.root, undefined, f.parent, 4, compression))).not.toHaveLength(0)
-  })
+  it.each(compression === 'none' ? ['json'] as const : ['json', 'magic', 'checksum', 'lines'] as const)(
+    'opens the parent when another Session header has corrupt %s', async (damage) => {
+      const f = await fixture()
+      await f.write('child', [f.descriptor], true)
+      const path = await f.write('unrelated', [])
+      let damaged: Buffer
+      if (damage === 'json') {
+        damaged = compression === 'none' ? Buffer.from('{broken header\n') : await compressZstdFrame('{broken header\n')
+      } else if (damage === 'lines') {
+        damaged = await compressZstdFrame('{}\n{}\n')
+      } else {
+        damaged = await readFile(path)
+        const offset = damage === 'magic' ? 0 : damaged.length - 1
+        damaged[offset] = damaged[offset]! ^ 0xFF
+      }
+      await writeFile(path, damaged)
+      expect((await f.ctx.sessionPersistence.list()).map(row => row.header.id).sort()).toEqual(['child', f.parent])
+      const expected = [{ type: 'subagent/catalog', data: { childId: 'child', mode: 'continuable', label: 'old child' } }]
+      expect(await f.read()).toMatchObject(expected)
+      const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+      try { expect((await writer.read()).events).toMatchObject(expected) } finally { await writer.close() }
+      expect(await readFile(generationLogPath(f.root, undefined, f.parent, 4, compression))).not.toHaveLength(0)
+      for (const access of ['read', 'write'] as const) {
+        await expect(f.ctx.sessionPersistence.open(SessionId('unrelated'), access)).rejects.toThrow()
+      }
+      expect(await readFile(path)).toEqual(damaged)
+      await expect(readFile(generationLogPath(f.root, undefined, SessionId('unrelated'), 4, compression)))
+        .rejects.toMatchObject({ code: 'ENOENT' })
+    },
+  )
 
   it('invalidates lightweight revisions on child membership and contents while retaining stable tokens', async () => {
     const f = await fixture()
diff --git a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
index 4ec279ac61..f7b2f98628 100644
--- a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
@@ -782,7 +782,7 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
     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 () => {
+  it('skips unreadable compressed headers during discovery while rejecting targeted reads', async () => {
     const root = await freshRoot()
     for (const [id, content] of [
       ['empty', Buffer.alloc(0)],
@@ -803,7 +803,7 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       JSON.stringify({ type: 'turn/start' }),
       '',
     ].join('\n')))
-    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/first frame is not exactly one header line/)
+    expect(await ctx.sessionPersistence.list()).toEqual([])
     await expect(ctx.sessionPersistence.open(twoLinesId, 'read'))
       .rejects.toThrow(/first frame is not exactly one header line/)
   })
@@ -824,7 +824,11 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       .rejects.toThrow(/empty or header-less Zstandard session log/)
     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/)
+    expect(await ctx.sessionPersistence.list()).toEqual([])
+    await expect(ctx.sessionPersistence.stat(SessionId('bad-checksum')))
+      .rejects.toThrow(/header frame failed validation/)
+    await expect(ctx.sessionPersistence.open(SessionId('bad-checksum'), 'read'))
+      .rejects.toThrow(/frame at byte 0 failed validation/)
   })
 })
 

From 78dcbc8587b8e0f89bc7044ff254fb0ef2340c9b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sun, 20 Sep 2026 15:50:41 +0800
Subject: [PATCH 32/37] feat(infra): unify Web and Desktop launch commands

Web and Desktop now share one command pair: start:* launches the artifacts
of a prior complete build and dev:* builds first, then launches. start:web
is new and spells out the same source launch vector as `pnpm dsh web`;
dev:web runs `pnpm run build`, the three rebuild watchers, and `dsh web` in
one terminal, with --skip-build and --no-serve for the previous two-terminal
flow. The launcher gate pins both scripts to the dsh CLI, and a root
Makefile names the same commands as make web|dev-web|desktop|dev-desktop|build.

The dev-web stage supervisor waits for stages the terminal already
interrupted, escalates only survivors, forwards SIGTERM once, and reports a
stage that exits on its own. Signal listeners are persistent because the
tsdown watchers bundle signal-exit, which re-raises a signal when it finds
no other listener.
---
 AGENTS.md                                     |   2 +
 Makefile                                      |  31 ++
 apps/cli/reference/README.i18n.yaml           |   4 +-
 apps/cli/reference/README.md                  |   2 +-
 apps/cli/reference/README.zh.md               |   2 +-
 apps/desktop/README.i18n.yaml                 |   4 +-
 apps/desktop/README.md                        |   2 +-
 apps/desktop/README.zh.md                     |   2 +-
 apps/web/tests/hmr-live.e2e.ts                |   8 +-
 apps/web/vite.config.ts                       |   2 +-
 docs/api-gateway.i18n.yaml                    |   4 +-
 docs/api-gateway.md                           |   5 +-
 docs/api-gateway.zh.md                        |   5 +-
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   2 +-
 docs/architecture.zh.md                       |   2 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |  15 +-
 docs/development.zh.md                        |  15 +-
 package.json                                  |   1 +
 packages/client/hmr/README.i18n.yaml          |   4 +-
 packages/client/hmr/README.md                 |   2 +-
 packages/client/hmr/README.zh.md              |   2 +-
 scripts/dev-web.spec.ts                       |  99 +++++-
 scripts/dev-web.ts                            | 325 ++++++++++++++----
 .../verify-application-entrypoints.spec.ts    |  24 +-
 scripts/verify-application-entrypoints.ts     |  35 +-
 27 files changed, 482 insertions(+), 125 deletions(-)
 create mode 100644 Makefile

diff --git a/AGENTS.md b/AGENTS.md
index 7a128b6167..aa83ae8c08 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,8 @@ pnpm run test:docs      # quick documentation checks (no build; doc-quick aggreg
 pnpm run website:build  # VitePress build (doubles as dead-link check)
 pnpm dsh --profile headless "task"  # run one task from source (needs DEEPSEEK_API_KEY)
 pnpm run demo:ptc -- "task"  # headless PTC mode run (needs key)
+pnpm run dev:web | dev:desktop  # build, then launch; Web also rebuilds client bundles on edits. start:web | start:desktop skip the build
+make web|dev-web|desktop|dev-desktop|build  # the same commands; ARGS='--no-open' forwards options
 ```
 
 ### Host sandbox failures
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000000..4b95df6766
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,31 @@
+# Short names for the Web and Desktop application commands. The package.json
+# scripts they call stay the source of truth; docs/development.md documents both.
+.DEFAULT_GOAL := help
+.PHONY: help build web desktop dev-web dev-desktop
+
+PNPM ?= pnpm
+ARGS ?=
+
+help:
+	@echo "make build        pnpm run build           complete repository build"
+	@echo "make web          pnpm run start:web       serve the built Web artifacts from source"
+	@echo "make desktop      pnpm run start:desktop   launch the built Desktop artifacts"
+	@echo "make dev-web      pnpm run dev:web         build, serve, and rebuild Web on source edits"
+	@echo "make dev-desktop  pnpm run dev:desktop     build, then launch Desktop"
+	@echo "ARGS='--no-open --port 3081' forwards options to the launched application;"
+	@echo "the Web commands accept dsh web flags, the Desktop launcher accepts none."
+
+build:
+	$(PNPM) run build
+
+web:
+	$(PNPM) run start:web $(ARGS)
+
+desktop:
+	$(PNPM) run start:desktop $(ARGS)
+
+dev-web:
+	$(PNPM) run dev:web $(ARGS)
+
+dev-desktop:
+	$(PNPM) run dev:desktop $(ARGS)
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 0cff0e5cdb..cb0eddf183 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: cf0e1400f2dc8cd29cc59cefbdda379df2e0b899
-README.zh.md: a01818f59ccf54f3f826c68505bfb830a9316664
+README.md: 33465e8c96df9cbfbecc038616caf297146ec971
+README.zh.md: d25d27851ca789a3db358157368b97c3669ed79d
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index cf0e1400f2..33465e8c96 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -85,7 +85,7 @@ Git-hosted plugins that ship sources build during install through their `prepare
 
 ## Web profile
 
-`dsh web` uses the profile shorthand. Launcher flags are parsed first; the remaining flags belong to the web app, whose ordinary bundle provider parses them. `--host` and `--port` override the composed values of the rows that carry them, repeatable `--trusted-host` contributes invocation authorities through `ctx.webRuntime.trustedHosts` (a deployment expression concatenates its own authorities), and `--no-open` disables the default-browser handoff for this invocation. The client-plugin HMR receiver is always mounted and stays idle until a separate `pnpm run dev:web` watcher rebuilds client bundles.
+`dsh web` uses the profile shorthand. Launcher flags are parsed first; the remaining flags belong to the web app, whose ordinary bundle provider parses them. `--host` and `--port` override the composed values of the rows that carry them, repeatable `--trusted-host` contributes invocation authorities through `ctx.webRuntime.trustedHosts` (a deployment expression concatenates its own authorities), and `--no-open` disables the default-browser handoff for this invocation. The client-plugin HMR receiver is always mounted and stays idle until `pnpm run dev:web` rebuilds client bundles; that command builds once, starts this same launcher, and keeps client bundles rebuilt, or with `--no-serve` runs only the watchers beside a `dsh web` started elsewhere.
 
 ```sh
 dsh web
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index a01818f59c..d25d27851c 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -87,7 +87,7 @@ dsh --profile tui
 
 ## Web Profile
 
-`dsh web` 使用 profile 简写。启动器先解析自身的 flag，其余 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--no-open` 则只对本次调用关闭默认浏览器交接。客户端插件 HMR（热模块替换）接收器始终挂载，在单独运行的 `pnpm run dev:web` watcher 重建客户端 bundle 之前保持空闲。
+`dsh web` 使用 profile 简写。启动器先解析自身的 flag，其余 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--no-open` 则只对本次调用关闭默认浏览器交接。客户端插件 HMR（热模块替换）接收器始终挂载，在 `pnpm run dev:web` 重建客户端 bundle 之前保持空闲；该命令先构建一次，再启动这同一个启动器并持续重建客户端 bundle，加 `--no-serve` 则只运行 watcher、配合别处启动的 `dsh web`。
 
 ```sh
 dsh web
diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml
index 455501862e..a37d3e8d49 100644
--- a/apps/desktop/README.i18n.yaml
+++ b/apps/desktop/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 apps/desktop/README.md
-README.md: 6c9a6a8784732e6fa1369df5632391b789786b22
-README.zh.md: a0f2184d911eeab46902670cf992b6847e2bca31
+README.md: 2d7882ec6bf8827dc65e2e9653c407908c0fbab5
+README.zh.md: 2a0277fa824ce43e45e8408df0ac029bb38c16a5
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index 6c9a6a8784..2d7882ec6b 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -93,7 +93,7 @@ After an explicit build, `start:desktop` reconstructs the disposable project and
 pnpm run start:desktop
 ```
 
-Workspace development runs the current CLI and private Desktop Host packages under Electron RunAsNode. Plugin management and recovery use `$DSH_HOME/profiles/desktop`, separate from the disposable workspace runtime. The Host uses runtime module resolution in both development and packaged builds without creating official-package fallback links; developer-installed packages, including links, retain native priority. Use an unpacked application to exercise Electron RunAsNode, bundled pnpm, bundled dsh resources, plugin installation and repair paths.
+The Web counterparts are `pnpm run dev:web` and `pnpm run start:web`, documented in the [development guide](../../docs/development.md). Workspace development runs the current CLI and private Desktop Host packages under Electron RunAsNode. Plugin management and recovery use `$DSH_HOME/profiles/desktop`, separate from the disposable workspace runtime. The Host uses runtime module resolution in both development and packaged builds without creating official-package fallback links; developer-installed packages, including links, retain native priority. Use an unpacked application to exercise Electron RunAsNode, bundled pnpm, bundled dsh resources, plugin installation and repair paths.
 
 ## Package
 
diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md
index a0f2184d91..2a0277fa82 100644
--- a/apps/desktop/README.zh.md
+++ b/apps/desktop/README.zh.md
@@ -93,7 +93,7 @@ pnpm run dev:desktop
 pnpm run start:desktop
 ```
 
-Workspace 开发使用 Electron RunAsNode 运行当前 CLI 与私有 Desktop Host 包，插件管理和恢复使用 `$DSH_HOME/profiles/desktop`，与一次性工作区运行时分离。Host 在开发与打包构建中都使用 runtime 模块解析，不创建官方包的 fallback 链接；开发者安装的包（包括链接）保留原生优先级。需要验证 Electron RunAsNode、内置 pnpm、内置 dsh 资源、插件安装和修复时，应运行未封装安装器的应用目录。
+Web 侧的对应命令是 `pnpm run dev:web` 与 `pnpm run start:web`，见[开发指南](../../docs/development.zh.md)。Workspace 开发使用 Electron RunAsNode 运行当前 CLI 与私有 Desktop Host 包，插件管理和恢复使用 `$DSH_HOME/profiles/desktop`，与一次性工作区运行时分离。Host 在开发与打包构建中都使用 runtime 模块解析，不创建官方包的 fallback 链接；开发者安装的包（包括链接）保留原生优先级。需要验证 Electron RunAsNode、内置 pnpm、内置 dsh 资源、插件安装和修复时，应运行未封装安装器的应用目录。
 
 ## 打包
 
diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts
index 716176a176..87adea12cc 100644
--- a/apps/web/tests/hmr-live.e2e.ts
+++ b/apps/web/tests/hmr-live.e2e.ts
@@ -1,4 +1,4 @@
-/** Published dsh web + pnpm dev:web → browser HMR, with no page reload. */
+/** Built dsh web + the `pnpm run dev:web --no-serve` watchers → browser HMR, with no page reload. */
 
 import { existsSync, globSync, statSync } from 'node:fs'
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
@@ -108,12 +108,14 @@ it('hot-reloads a real client-plugin source edit without refreshing the page', a
   const failures: unknown[] = []
   try {
     subprocessFiber = await subprocessCtx.plugin(LocalSubprocessRuntime)
+    // Watchers only: the built `dsh web` below is the server under test, and the
+    // built tree is this lane's precondition rather than something to rebuild.
     watcher = subprocessCtx.subprocess.spawn(spawnSpec(
-      ['pnpm', 'run', 'dev:web'],
+      ['pnpm', 'run', 'dev:web', '--skip-build', '--no-serve'],
       REPO_ROOT,
       { ...clientBuildEnvironment },
     ))
-    await waitForOutput(watcher, /dev-web: watching/, 'pnpm run dev:web')
+    await waitForOutput(watcher, /dev-web: watching/, 'pnpm run dev:web --skip-build --no-serve')
     host = subprocessCtx.subprocess.spawn(spawnSpec(
       [process.execPath, binPath, 'web', '--no-open', '--port', '0'],
       world,
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index ddf3683c59..9984bf38de 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -10,7 +10,7 @@ import { productWebBundleIsolation } from './product-isolation.ts'
 const src = (rel: string): string => fileURLToPath(new URL(rel, import.meta.url))
 const STANDALONE_ERROR = 'apps/web is not a standalone application: bare Vite cannot inject window.__DSH_BOOT__. '
   + 'From a repository checkout, run `pnpm dsh web`; an installed package uses `dsh web`. '
-  + 'For client-plugin HMR, run `pnpm dsh web` together with `pnpm run dev:web`.'
+  + 'For client-plugin HMR, run `pnpm run dev:web`, which starts `dsh web` and the rebuild watchers together.'
 const DEFAULT_CLIENT_TITLE = 'DSH Local Build'
 
 /** Escape build-time text before placing it in the HTML title element. */
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index fa62039df7..673807013b 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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/api-gateway.md
-api-gateway.md: 2cf7b2f345991fd20639e1294662cc64fc02093d
-api-gateway.zh.md: 5b80db08de49591b27751e187aa6278384a7444e
+api-gateway.md: aa8339219a563901d5d132f4f401325ca30a3d53
+api-gateway.zh.md: 99b2d9866d38e520880e5d13115c2e6370fca474
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 2cf7b2f345..aa8339219a 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -138,14 +138,13 @@ SRC solves only dispatch for a Host process running from source. The Client does
 
 ## Development mode
 
-Web development prepares current Host, Client, and Web artifacts with `pnpm run build`, then runs the source Host and the Client plugin watcher in separate terminals:
+Web development runs one command, which builds current Host, Client, and Web artifacts, starts the source Host, and keeps Client bundles rebuilt:
 
 ```sh
-pnpm dsh web
 pnpm run dev:web
 ```
 
-`dsh` starts the Host source through tsx, so the Host can use the SRC fallback; `dev:web` watches only Client plugins with a `dsh.client` declaration and rewrites their `lib/client.js`. It does not analyze Host decorators or generate Remote Client DTS.
+`dsh` starts the Host source through tsx, so the Host can use the SRC fallback; the `dev:web` watchers rebuild the client-face type emit, Client plugin and library bundles, and the Web shell on source edits. They do not analyze Host decorators or generate Remote Client DTS; only the complete build that `dev:web` runs first (or `pnpm run build`) does.
 
 Changing only a Remote method's implementation body without changing its contract does not require regenerating the Typert files. After adding or removing a decorator or changing an export name, namespace, parameter, return value, lookup, Context, or cancellation signature, rerun the ordered lib build so the Host generates the strict contract before the Client compiles and bundles the new contribution:
 
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 5b80db08de..99b2d9866d 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -138,14 +138,13 @@ SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Ho
 
 ## 开发模式
 
-Web 开发先使用 `pnpm run build` 准备当前 Host、Client 与 Web 产物，然后在两个终端中分别运行源码 Host 和 Client plugin watcher：
+Web 开发只需一条命令：它先构建当前 Host、Client 与 Web 产物，再启动源码 Host，并持续重建 Client bundle：
 
 ```sh
-pnpm dsh web
 pnpm run dev:web
 ```
 
-`dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dsh.client` 声明的 Client 插件并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
+`dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 的 watcher 会在源码修改时重建 client 侧类型输出、Client 插件与库 bundle 以及 Web 壳层。它们不会分析 Host decorator，也不会生成 Remote Client DTS；只有 `dev:web` 首先执行的完整构建（或 `pnpm run build`）才会。
 
 只修改 Remote 方法实现体而不改变约定时，无需重新生成 Typert 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格约定，再让 Client 编译并打包新的贡献：
 
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 3d9fba9385..66b457c8fa 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: 0bbf5ef7f4c0444635178ba0ba85fbb9527d76ec
-architecture.zh.md: 0d28dc349fd9c655529bcc43deabc47055e0d394
+architecture.md: 5e0bb09770e013349bcc1326bea1eab9cdc3e595
+architecture.zh.md: a146c93c14ef0f563babf98f7311f1e5686895cc
diff --git a/docs/architecture.md b/docs/architecture.md
index 0bbf5ef7f4..5e0bb09770 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -44,7 +44,7 @@ Composition mechanics are in [app-boot](../packages/boot/app-boot/README.md#prof
 
 Supported Node applications launch through named `dsh` profiles. The shipped profiles are `web`, `headless`, `sdk`, `sdk-minimal`, and `acp`, selected with `dsh --profile <name>` or `dsh <name>`. `plugin` names the management command; a profile with that name requires `--profile plugin`. The TypeScript SDK resolves its same-version `dsh` dependency and selects `sdk`; custom plugin composition remains a profile plus ordered patch files, not another executable or inline application tree. `sdk-minimal` is a repository-owned standalone bundle behind the same launcher, not a caller-supplied Cordis tree.
 
-Vendored CLIs, build-only and test-only executables, direct in-process plugin mounting, and the private browser WebWorker preview are not Harness application launchers. [`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts) keeps every package bin, executable source, and root demo in an explicit class and rejects a Node application path that bypasses `dsh`.
+Vendored CLIs, build-only and test-only executables, direct in-process plugin mounting, and the private browser WebWorker preview are not Harness application launchers. [`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts) keeps every package bin, executable source, root demo, and the root `start:web` and `dev:web` scripts in an explicit class and rejects a Node application path that bypasses `dsh`.
 
 The Python SDK follows the same application architecture. Its runtime wheel packages the normal `dsh` CLI as `deepseek-harness-sdk-runtime-<platform>-<arch>`, and the client launches `dsh --profile sdk` with an explicit Harness home by default. The minimal example selects the shipped `sdk-minimal` profile. Python exposes profile selection and ordered patch files rather than a complete Cordis tree; persistent external plugins are installed through `dsh plugin`. The removed private direct-config carrier has no compatibility bin or fallback parser.
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 0d28dc349f..a146c93c14 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -44,7 +44,7 @@ dsh --profile web --dump-config
 
 受支持的 Node 应用通过具名 `dsh` profile 启动。随附 profile 为 `web`、`headless`、`sdk`、`sdk-minimal` 和 `acp`，可通过 `dsh --profile <name>` 或 `dsh <name>` 选择。`plugin` 表示管理命令；同名 profile 必须用 `--profile plugin` 选择。TypeScript SDK 会解析其同版本 `dsh` 依赖并选择 `sdk`；自定义插件组合继续由 profile 与有序 patch 文件表达，而不是另一个可执行文件或内联应用树。`sdk-minimal` 是位于同一 launcher 后的仓库自有独立组合包，而不是由调用方提供的 Cordis 配置树。
 
-Vendored CLI、仅用于构建和测试的可执行文件、进程内直接挂载插件以及私有浏览器 WebWorker 预览都不属于 Harness 应用启动器。[`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts)将每个包 bin、可执行源码与根 demo 归入显式类别，并拒绝任何绕过 `dsh` 的 Node 应用路径。
+Vendored CLI、仅用于构建和测试的可执行文件、进程内直接挂载插件以及私有浏览器 WebWorker 预览都不属于 Harness 应用启动器。[`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts)将每个包 bin、可执行源码、根 demo 以及根脚本 `start:web` 与 `dev:web` 归入显式类别，并拒绝任何绕过 `dsh` 的 Node 应用路径。
 
 Python SDK 遵循相同的应用架构。其运行时 wheel 把普通 `dsh` CLI 打包为 `deepseek-harness-sdk-runtime-<platform>-<arch>`，客户端默认以显式 Harness home 启动 `dsh --profile sdk`。极简示例选择随附的 `sdk-minimal` profile。Python 暴露 profile 选择与有序 patch 文件，而不是完整 Cordis 树；持久外部插件通过 `dsh plugin` 安装。已删除的私有直读配置载体没有兼容 bin 或回退 parser。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 8959b05a1d..fd6198a8ca 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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/development.md
-development.md: ce8f1e7746562e696c96e6359ec9fcfde596d6e2
-development.zh.md: 85e95946dfd7210201f0807880d5ed1a92859356
+development.md: 7e8d0ded70ca880ce986cb3879d959fbe2a04304
+development.zh.md: 84d0d76d8c76f829c0ed928d28336df3e58ed7f0
diff --git a/docs/development.md b/docs/development.md
index ce8f1e7746..7e8d0ded70 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -83,7 +83,7 @@ Both tsdown passes use the same complete workspace match. They neither scan buil
 
 Typert runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start Typert. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build.
 
-`pnpm run build` embeds the root package version, the seven-character source commit, and a dirty marker when Git reports local changes; it also inherits other caller-supplied `DSH_CLIENT_*` values. `pnpm run build:official` is the cross-platform local equivalent of the CI and release artifact build and omits the local dirty marker. Each successful complete build writes a gitignored record that binds the exact public values to the Vite output and dynamic client bundles; release packing and built Web tests reject a missing record or artifacts changed by a later partial build. `pnpm run dev:web` still requires the artifact tree from a prior complete build, but it samples the current version and Git state once at startup and shares that environment across every watcher stage for the session; it does not validate the complete-build record because the watcher stages rewrite its recorded artifacts.
+`pnpm run build` embeds the root package version, the seven-character source commit, and a dirty marker when Git reports local changes; it also inherits other caller-supplied `DSH_CLIENT_*` values. `pnpm run build:official` is the cross-platform local equivalent of the CI and release artifact build and omits the local dirty marker. Each successful complete build writes a gitignored record that binds the exact public values to the Vite output and dynamic client bundles; release packing and built Web tests reject a missing record or artifacts changed by a later partial build. `pnpm run dev:web` runs that complete build first (`--skip-build` reuses an existing artifact tree instead), then samples the current version and Git state once and shares that environment across every watcher stage for the session; it does not validate the complete-build record because the watcher stages rewrite its recorded artifacts.
 
 Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already depends on the Typert contract-generation pass or the complete build. See the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership and the [Typert Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.
 
@@ -156,6 +156,19 @@ The PTC mode demo runs the same headless profile with code presentation enabled:
 pnpm run demo:ptc -- "summarize this workspace"
 ```
 
+### Application commands
+
+Web and Desktop share one command pair. `start:*` launches the artifacts of a prior `pnpm run build`; `dev:*` runs that build first and then launches. Web additionally keeps client bundles rebuilt on source edits, because its Host runs from source while the browser loads built bundles:
+
+```sh
+pnpm run start:web       # serve built Web artifacts through the source launcher (the same launch as pnpm dsh web)
+pnpm run dev:web         # build, serve, and rebuild Web client bundles on source edits
+pnpm run start:desktop   # launch built Desktop artifacts
+pnpm run dev:desktop     # build, then launch Desktop
+```
+
+Arguments after a Web command reach `dsh web`, for example `pnpm run dev:web --no-open --port 3081`; `dev:web` also accepts `--skip-build` to reuse the existing artifact tree and `--no-serve` to run only the rebuild watchers beside a server started elsewhere. Both Web commands use the normal Harness home, while the Desktop commands use the isolated development home described in the [Desktop README](../apps/desktop/README.md). The root `Makefile` names the same commands as `make web`, `make dev-web`, `make desktop`, `make dev-desktop`, and `make build`; `ARGS='--no-open'` forwards options.
+
 ### TODO markers
 
 Use one of three comment tags to flag known issues in the code, ordered by urgency:
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 85e95946df..84d0d76d8c 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -87,7 +87,7 @@ pnpm run build:web
 
 Typert 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 Typert。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。
 
-`pnpm run build` 会内联根包版本、七位源码 commit，并在 Git 报告本地变化时内联 dirty 标记；调用方提供的其他 `DSH_CLIENT_*` 值也会被继承。`pnpm run build:official` 是与 CI 和 release 产物构建等价的跨平台本地命令，并省略本地 dirty 标记。每次完整构建成功后都会写入一份被 gitignore 的记录，把精确公开值与 Vite 输出及动态 client bundle 绑定；release 打包和 built Web 测试会拒绝缺少记录或被后续局部构建改动的产物。`pnpm run dev:web` 仍需要先执行完整构建来准备产物树，但会在启动时读取一次当前版本和 Git 状态，并在本次会话的所有 watcher stage 之间共享该环境；它不会校验完整构建记录，因为 watcher stage 会重写记录覆盖的产物。
+`pnpm run build` 会内联根包版本、七位源码 commit，并在 Git 报告本地变化时内联 dirty 标记；调用方提供的其他 `DSH_CLIENT_*` 值也会被继承。`pnpm run build:official` 是与 CI 和 release 产物构建等价的跨平台本地命令，并省略本地 dirty 标记。每次完整构建成功后都会写入一份被 gitignore 的记录，把精确公开值与 Vite 输出及动态 client bundle 绑定；release 打包和 built Web 测试会拒绝缺少记录或被后续局部构建改动的产物。`pnpm run dev:web` 会先执行这次完整构建（`--skip-build` 则复用现有产物树），再读取一次当前版本和 Git 状态，并在本次会话的所有 watcher stage 之间共享该环境；它不会校验完整构建记录，因为 watcher stage 会重写记录覆盖的产物。
 
 静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本假定调用它的公共命令或调度器门禁已经依赖 Typert 约定生成阶段或完整构建。tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md)，门禁准备约定见 [Typert Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)。
 
@@ -160,6 +160,19 @@ PTC mode 演示启用代码式工具展示，并运行同一个 headless profile
 pnpm run demo:ptc -- "summarize this workspace"
 ```
 
+### 应用命令
+
+Web 与 Desktop 共用同一对命令。`start:*` 启动上一次 `pnpm run build` 的产物；`dev:*` 先执行该构建再启动。Web 还会在源码修改时持续重建 client bundle，因为它的 Host 从源码运行，而浏览器加载的是构建产物：
+
+```sh
+pnpm run start:web       # serve built Web artifacts through the source launcher (the same launch as pnpm dsh web)
+pnpm run dev:web         # build, serve, and rebuild Web client bundles on source edits
+pnpm run start:desktop   # launch built Desktop artifacts
+pnpm run dev:desktop     # build, then launch Desktop
+```
+
+Web 命令后面的参数会传给 `dsh web`，例如 `pnpm run dev:web --no-open --port 3081`；`dev:web` 还接受 `--skip-build` 复用现有产物树，以及 `--no-serve` 只运行重建 watcher、配合别处启动的服务器。两个 Web 命令使用正常的 Harness home，而 Desktop 命令使用 [Desktop README](../apps/desktop/README.zh.md) 描述的隔离开发 home。根目录 `Makefile` 以 `make web`、`make dev-web`、`make desktop`、`make dev-desktop` 和 `make build` 命名同一套命令；`ARGS='--no-open'` 用于转发参数。
+
 ### TODO 标记
 
 请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：
diff --git a/package.json b/package.json
index 4d36479376..eb4b2b92c9 100644
--- a/package.json
+++ b/package.json
@@ -196,6 +196,7 @@
     "demo:ptc": "node scripts/demo-ptc.mjs",
     "demo:inspector": "node --import tsx/esm apps/cli/src/bin.ts web --patch ./packages/experimental/inspector/cordis.source.patch.yml",
     "mock:llm": "node --import tsx packages/test-support/llm-mock-server/src/bin.ts",
+    "start:web": "node --import tsx/esm apps/cli/src/bin.ts web",
     "dev:web": "tsx scripts/dev-web.ts --poll",
     "postinstall": "node scripts/install-lefthook.mjs"
   },
diff --git a/packages/client/hmr/README.i18n.yaml b/packages/client/hmr/README.i18n.yaml
index 07ad3d545d..f6861208ea 100644
--- a/packages/client/hmr/README.i18n.yaml
+++ b/packages/client/hmr/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/hmr/README.md
-README.md: e459da10332ffdb3af422b75f639ce25df512487
-README.zh.md: 54e2f3af63472dedbfc75c5b4400b5d93e14f311
+README.md: 5dae1463ceed315c3409bf97de80649f10e83fa8
+README.zh.md: a77befcf63cd78be66b7e5b636d86367af6fdcdf
diff --git a/packages/client/hmr/README.md b/packages/client/hmr/README.md
index e459da1033..5dae1463ce 100644
--- a/packages/client/hmr/README.md
+++ b/packages/client/hmr/README.md
@@ -29,7 +29,7 @@ The shipped Web composition mounts this transport for live plugin changes. Durin
 
 ### Starting the reload chain
 
-Run `pnpm run dev:web` (or a watch process using the shared Client tsdown preset) against the same host; rebuilt plugins are then swapped into the running browser automatically, one at a time. The preset stamps `lib/client.js` after all package-local chunks are written, so a chunk-only rebuild also advances the package revision without Host-side chunk scanning.
+Run `pnpm run dev:web`, which starts the host and the rebuild watchers together (`--no-serve` attaches only the watchers to a host started elsewhere, as does any watch process using the shared Client tsdown preset); rebuilt plugins are then swapped into the running browser automatically, one at a time. The preset stamps `lib/client.js` after all package-local chunks are written, so a chunk-only rebuild also advances the package revision without Host-side chunk scanning.
 
 ### What a reload does
 
diff --git a/packages/client/hmr/README.zh.md b/packages/client/hmr/README.zh.md
index 54e2f3af63..a77befcf63 100644
--- a/packages/client/hmr/README.zh.md
+++ b/packages/client/hmr/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 启动重载链路
 
-对同一个宿主运行 `pnpm run dev:web`（或使用共享 Client tsdown 预设的 watch 进程）；重建后的插件随后会被自动逐个替换进运行中的浏览器。该预设会在所有包内 chunk 写完后标记 `lib/client.js`，因此仅 chunk 发生重建也会推进包 revision，无需 Host 扫描 chunk。
+运行 `pnpm run dev:web`，它会同时启动宿主与重建 watcher（`--no-serve` 则只把 watcher 接到别处启动的宿主上，使用共享 Client tsdown 预设的任何 watch 进程亦然）；重建后的插件随后会被自动逐个替换进运行中的浏览器。该预设会在所有包内 chunk 写完后标记 `lib/client.js`，因此仅 chunk 发生重建也会推进包 revision，无需 Host 扫描 chunk。
 
 ### 一次重载做什么
 
diff --git a/scripts/dev-web.spec.ts b/scripts/dev-web.spec.ts
index 76dbf82860..df1274c57c 100644
--- a/scripts/dev-web.spec.ts
+++ b/scripts/dev-web.spec.ts
@@ -1,15 +1,112 @@
 import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import type { TsdownBundle } from 'tsdown'
 import { writeClientBuildRecord } from './client-build-environment.ts'
 import {
   devWebBuildEnvironment,
   discoverLibraryDirs,
   discoverPluginDirs,
+  parseDevWebArguments,
+  StageSupervisor,
   watchClientPlugins,
 } from './dev-web.ts'
+import type { StageHandle } from './dev-web.ts'
+
+/** A stage double that exits only on the listed signals or an explicit exit code. */
+function fakeStage(name: string, exitOn: readonly NodeJS.Signals[]): {
+  handle: StageHandle
+  signals: NodeJS.Signals[]
+  exit: (code: number) => void
+} {
+  const exit = Promise.withResolvers<number | null>()
+  const signals: NodeJS.Signals[] = []
+  return {
+    handle: {
+      name,
+      exited: exit.promise,
+      kill(signal) {
+        signals.push(signal)
+        if (exitOn.includes(signal)) exit.resolve(null)
+      },
+    },
+    signals,
+    exit: (code) => { exit.resolve(code) },
+  }
+}
+
+describe('StageSupervisor', () => {
+  it('reports a stage that exits on its own', async () => {
+    const stale: [string, number | null][] = []
+    const supervisor = new StageSupervisor((name, code) => { stale.push([name, code]) })
+    const tsc = fakeStage('tsc', ['SIGTERM'])
+    supervisor.add(tsc.handle)
+    tsc.exit(2)
+    await tsc.handle.exited
+    expect(stale).toEqual([['tsc', 2]])
+  })
+
+  it('forwards one signal, escalates survivors after the grace period, and reports none of them', async () => {
+    const stale: string[] = []
+    const supervisor = new StageSupervisor((name) => { stale.push(name) })
+    const polite = fakeStage('vite', ['SIGTERM'])
+    const stubborn = fakeStage('dsh web', ['SIGKILL'])
+    supervisor.add(polite.handle)
+    supervisor.add(stubborn.handle)
+    await supervisor.stop({ signal: 'SIGTERM', graceMs: 20 })
+    expect(polite.signals).toEqual(['SIGTERM'])
+    expect(stubborn.signals).toEqual(['SIGTERM', 'SIGKILL'])
+    expect(stale).toEqual([])
+  })
+
+  it('waits for stages the terminal already interrupted before signaling survivors', async () => {
+    const supervisor = new StageSupervisor(() => { throw new Error('unexpected stale report') })
+    const interrupted = fakeStage('tsdown', [])
+    const survivor = fakeStage('dsh web', ['SIGTERM'])
+    supervisor.add(interrupted.handle)
+    supervisor.add(survivor.handle)
+    const stopping = supervisor.stop({ graceMs: 20 })
+    interrupted.exit(130)
+    await stopping
+    expect(interrupted.signals).toEqual([])
+    expect(survivor.signals).toEqual(['SIGTERM'])
+  })
+})
+
+describe('parseDevWebArguments', () => {
+  it('builds, serves, and watches natively by default', () => {
+    expect(parseDevWebArguments([])).toEqual({ skipBuild: false, serve: true, pollInterval: undefined, appArgs: [] })
+  })
+
+  it('reads the polling interval with its 500ms default', () => {
+    expect(parseDevWebArguments(['--poll']).pollInterval).toBe(500)
+    expect(parseDevWebArguments(['--poll=250']).pollInterval).toBe(250)
+  })
+
+  it.each(['--poll=abc', '--poll=0', '--poll=-5', '--poll=1.5'])('rejects the polling interval %s', (flag) => {
+    expect(() => parseDevWebArguments([flag])).toThrow(`invalid --poll interval "${flag}"`)
+  })
+
+  it('separates its own flags from the arguments forwarded to dsh web', () => {
+    expect(parseDevWebArguments(['--skip-build', '--poll', '--no-open', '--port', '8080'])).toEqual({
+      skipBuild: true, serve: true, pollInterval: 500, appArgs: ['--no-open', '--port', '8080'],
+    })
+  })
+
+  it('runs only the rebuild watchers with --no-serve', () => {
+    expect(parseDevWebArguments(['--no-serve', '--skip-build'])).toMatchObject({ serve: false, skipBuild: true })
+  })
+
+  it('ignores the separator pnpm run forwards verbatim', () => {
+    expect(parseDevWebArguments(['--', '--no-open']).appArgs).toEqual(['--no-open'])
+    expect(parseDevWebArguments(['--no-serve', '--'])).toMatchObject({ serve: false, appArgs: [] })
+  })
+
+  it('rejects dsh web arguments when no server is started', () => {
+    expect(() => parseDevWebArguments(['--no-serve', '--no-open'])).toThrow('--no-serve leaves no dsh web process for --no-open')
+  })
+})
 
 it('samples one local environment at startup without validating watcher outputs', async () => {
   const root = await mkdtemp(join(tmpdir(), 'dsh-dev-web-environment-'))
diff --git a/scripts/dev-web.ts b/scripts/dev-web.ts
index 35500eca13..dd282d773c 100644
--- a/scripts/dev-web.ts
+++ b/scripts/dev-web.ts
@@ -1,28 +1,38 @@
 /**
- * Watch-build for the web dev loop: rebuilds every artifact the browser reads
- * from a source edit. Reload signaling is not this script's business — the host
- * webserver stat-polls the bundles it serves and broadcasts `rebuilt` frames
- * itself (`dsh web`), so any process that rewrites `lib/client.js` files
- * triggers reloads; this script is merely the convenient way to keep them all
- * rebuilt on source change.
+ * The Web development loop: build once, serve through `dsh web`, and keep every
+ * browser-side artifact rebuilt on source edits, in one terminal.
  *
- * Three stages, because the compile shell links built lib products rather than
- * sources: `tsc -b tsconfig.client.json` emits `lib/types` (the tsdown lib
- * entries are that emit, not `src`), tsdown bundles `lib/index.js` and
- * `lib/client.js`, and `vite build` rewrites `apps/web/dist`, which `dsh web`
- * serves. A missing stage does not fail — it silently shows the previous
- * artifact, so an edit appears to do nothing.
+ * Stages, in order: `pnpm run build` (skipped by `--skip-build`), three
+ * long-lived watchers, then `dsh web` (skipped by `--no-serve`). The watchers
+ * exist because the compile shell links built lib products rather than
+ * sources: `tsc -b tsconfig.client.json --watch` emits `lib/types` (the tsdown
+ * lib entries are that emit, not `src`), tsdown watch bundles `lib/index.js`
+ * and `lib/client.js`, and `vite build --watch` rewrites `apps/web/dist`, which
+ * `dsh web` serves. A missing watcher does not fail — it silently shows the
+ * previous artifact, so an edit appears to do nothing; any stage exiting on its
+ * own therefore stops the loop with exit code 1.
  *
- * MUST NOT run concurrently with `pnpm run build`: both write the same
- * `lib/` and `apps/web/dist/` trees.
+ * Reload signaling is not this script's business — the host webserver
+ * stat-polls the bundles it serves and broadcasts `rebuilt` frames itself, so
+ * any process that rewrites `lib/client.js` files triggers reloads.
  *
- * Usage: `pnpm exec tsx scripts/dev-web.ts [--poll[=ms]]`. Requires one prior
- * `pnpm run build`: every stage is incremental over the previous stage's output
- * and none of them bootstraps a missing tree. `--poll` switches the source
- * watchers to polling (default 500ms): network mounts (weka) deliver no inotify
- * events, so native watching sees the initial build only and never a source
- * change. Polling has to reach tsc too — a native-watching tsc never re-emits
- * `lib/types`, which strands the other two stages on stale input.
+ * MUST NOT run beside `pnpm run build`: both write the same `lib/` and
+ * `apps/web/dist/` trees. The build stage here finishes before any watcher starts.
+ *
+ * Usage: `pnpm run dev:web [--skip-build] [--no-serve] [--poll[=ms]] [dsh web arguments]`.
+ * `--skip-build` requires the artifact tree from a prior complete build: every
+ * watcher is incremental over the previous stage's output and none of them
+ * bootstraps a missing tree. `--no-serve` keeps only the watchers, for a
+ * `dsh web` started elsewhere. `--poll` switches the source watchers to polling
+ * (default 500ms): network mounts (weka) deliver no inotify events, so native
+ * watching sees the initial build only and never a source change. Polling has
+ * to reach tsc too — a native-watching tsc never re-emits `lib/types`, which
+ * strands the other two stages on stale input.
+ *
+ * Shutdown: Ctrl+C reaches every stage through the terminal's process group, so
+ * the script only waits for them and escalates survivors; SIGTERM is addressed
+ * to this process alone and is forwarded once. The exit code is 130 after
+ * SIGINT, 0 after SIGTERM, and 1 when a stage exited on its own.
  *
  * Each package keeps its own tsdown.config.ts untouched: this script layers
  * `watch` through API-level inline config (tsdown workspace mode fills inline
@@ -39,6 +49,7 @@ import {
   clientBuildProcessEnvironment,
   repositoryClientBuildEnvironment,
 } from './client-build-environment.ts'
+import { pnpmInvocation } from './pnpm-invocation.ts'
 
 const repoRoot = fileURLToPath(new URL('..', import.meta.url))
 
@@ -67,6 +78,51 @@ export function devWebBuildEnvironment(
   return clientBuildProcessEnvironment(environment, repositoryClientBuildEnvironment(root, environment))
 }
 
+/** Resolved `dev-web` command line: the script's own flags plus the arguments forwarded to `dsh web`. */
+export interface DevWebArguments {
+  /** Skip the complete `pnpm run build` that otherwise precedes the watchers. */
+  readonly skipBuild: boolean
+  /** Start `dsh web`; false keeps only the rebuild watchers beside an already running server. */
+  readonly serve: boolean
+  /** Source-watcher polling interval in milliseconds; undefined selects native watching. */
+  readonly pollInterval: number | undefined
+  /** Arguments forwarded verbatim to `dsh web`, in order. */
+  readonly appArgs: readonly string[]
+}
+
+/** Polling interval selected by a bare `--poll`. */
+const DEFAULT_POLL_INTERVAL = 500
+
+/**
+ * Parse the script's command line. `--skip-build`, `--no-serve`, and `--poll[=ms]`
+ * belong to this script; a bare `--` is dropped; every other token is forwarded
+ * to `dsh web`.
+ * @param argv - arguments after the script path.
+ * @returns the resolved flags and forwarded arguments.
+ * @throws Error when `--poll` carries a non-positive or non-integer interval, or
+ * when `--no-serve` leaves forwarded arguments without a `dsh web` process.
+ */
+export function parseDevWebArguments(argv: readonly string[]): DevWebArguments {
+  let skipBuild = false
+  let serve = true
+  let pollInterval: number | undefined
+  const appArgs: string[] = []
+  for (const arg of argv) {
+    // `pnpm run` forwards a `--` separator verbatim; it carries no meaning here.
+    if (arg === '--') continue
+    if (arg === '--skip-build') skipBuild = true
+    else if (arg === '--no-serve') serve = false
+    else if (arg === '--poll' || arg.startsWith('--poll=')) {
+      pollInterval = arg === '--poll' ? DEFAULT_POLL_INTERVAL : Number(arg.slice('--poll='.length))
+      if (!Number.isInteger(pollInterval) || pollInterval <= 0) throw new Error(`dev-web: invalid --poll interval "${arg}"`)
+    } else appArgs.push(arg)
+  }
+  if (!serve && appArgs.length > 0) {
+    throw new Error(`dev-web: --no-serve leaves no dsh web process for ${appArgs[0] ?? ''}`)
+  }
+  return { skipBuild, serve, pollInterval, appArgs }
+}
+
 /**
  * Discover the watch workspace by declaration: every packages/<group>/<name>
  * whose package.json carries `dsh.client` with platform "web" is a client
@@ -153,46 +209,166 @@ export async function watchClientPlugins(
   return bundles
 }
 
-/**
- * Live watcher processes to terminate when this script is interrupted. Stages
- * register themselves as they start, so the set is complete from the first
- * spawn: an interrupt during a later stage's startup still tears down the
- * earlier ones instead of orphaning them.
- */
-const stages: StageHandle[] = []
+/** One long-lived stage process as the supervisor observes it. */
+export interface StageHandle {
+  /** Command label used in diagnostics. */
+  readonly name: string
+  /** Settles with the exit code, or null when a signal ended the stage. */
+  readonly exited: Promise<number | null>
+  /**
+   * Deliver one signal; a no-op once the stage has exited.
+   * @param signal - the signal to send.
+   */
+  kill(signal: NodeJS.Signals): void
+}
+
+/** How a requested stop reaches the stages. */
+export interface StageStop {
+  /** Signal sent to every live stage first; omitted when the terminal already delivered SIGINT to them. */
+  readonly signal?: NodeJS.Signals | undefined
+  /** Milliseconds to wait for exits before escalating to SIGTERM, and again before SIGKILL. */
+  readonly graceMs: number
+}
 
 /**
- * Spawn one watcher stage, inheriting stdio, registering it for teardown, and
- * failing loud if it ever exits: a dead stage leaves the artifact chain silently
- * stale, which reads as "my edit did nothing" — the one failure this script
- * exists to prevent.
- * @param stage - command label used in the exit diagnostic.
- * @param command - executable, resolved from the workspace bin when local.
+ * Own the live stages: report a stage that exits before a stop was requested,
+ * and on a requested stop signal, wait, and escalate until every stage has exited.
+ */
+export class StageSupervisor {
+  private readonly live = new Set<StageHandle>()
+  private stopping = false
+
+  /**
+   * @param onStale - receives the stage name and exit code when a stage exits before a stop was requested.
+   */
+  constructor(private readonly onStale: (stage: string, code: number | null) => void) {}
+
+  /**
+   * Track one started stage until it exits.
+   * @param stage - the stage to supervise.
+   */
+  add(stage: StageHandle): void {
+    this.live.add(stage)
+    void stage.exited.then((code) => {
+      this.live.delete(stage)
+      if (!this.stopping) this.onStale(stage.name, code)
+    })
+  }
+
+  /**
+   * Stop every live stage and resolve once all of them have exited.
+   * @param stop - initial signal and the grace period between escalation steps.
+   */
+  async stop(stop: StageStop): Promise<void> {
+    this.stopping = true
+    const escalation: (NodeJS.Signals | undefined)[] = [stop.signal]
+    if (stop.signal !== 'SIGTERM') escalation.push('SIGTERM')
+    for (const signal of escalation) {
+      if (this.live.size === 0) return
+      if (signal !== undefined) for (const stage of this.live) stage.kill(signal)
+      await this.settled(stop.graceMs)
+    }
+    for (const stage of this.live) stage.kill('SIGKILL')
+    await Promise.all([...this.live].map(stage => stage.exited))
+  }
+
+  private async settled(graceMs: number): Promise<void> {
+    let timer: NodeJS.Timeout | undefined
+    await Promise.race([
+      Promise.all([...this.live].map(stage => stage.exited)),
+      new Promise<void>((resolve) => { timer = setTimeout(resolve, graceMs) }),
+    ])
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Grace period per escalation step. `dsh web` gives its plugin tree five seconds
+ * to dispose after the first signal; escalating earlier would turn the graceful
+ * drain into a forced exit.
+ */
+const STOP_GRACE_MS = 6_000
+
+/**
+ * Spawn one long-lived stage with inherited stdio and hand it to the supervisor.
+ * @param supervisor - owner that reports an unexpected exit and stops the stage on shutdown.
+ * @param name - command label used in diagnostics.
+ * @param command - executable, resolved from the workspace bins when `local` is set.
  * @param args - command arguments.
  * @param local - whether to resolve `command` from the workspace's installed bins.
  */
-function spawnStage(stage: string, command: string, args: readonly string[], local: boolean): void {
+function spawnStage(
+  supervisor: StageSupervisor,
+  name: string,
+  command: string,
+  args: readonly string[],
+  local: boolean,
+): void {
   const child = execa(command, [...args], {
     cwd: repoRoot,
     stdio: 'inherit',
     preferLocal: local,
     reject: false,
   })
-  stages.push({ kill: () => { child.kill() } })
-  void child.then((result) => {
-    console.error(`dev-web: ${stage} exited (code ${String(result.exitCode)}); the artifact chain is now stale`)
-    process.exit(1)
+  supervisor.add({
+    name,
+    exited: child.then(result => result.exitCode ?? null),
+    kill(signal) { child.kill(signal) },
   })
 }
 
-/** The only capability this script needs from a live watcher process. */
-interface StageHandle {
-  readonly kill: () => void
+/**
+ * Run the complete repository build with the launch environment untouched:
+ * `scripts/build.ts` samples the public client values itself.
+ * @returns the build's exit code, or null when a signal ended it.
+ */
+async function runBuild(): Promise<number | null> {
+  const invocation = pnpmInvocation(['run', 'build'])
+  const result = await execa(invocation.command, invocation.args, { cwd: repoRoot, stdio: 'inherit', reject: false })
+  return result.exitCode ?? null
 }
 
 const invokedPath = process.argv[1]
 const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href
 if (isMain) {
+  let options: DevWebArguments
+  try {
+    options = parseDevWebArguments(process.argv.slice(2))
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error)
+    console.error('dev-web: usage: pnpm run dev:web [--skip-build] [--no-serve] [--poll[=ms]] [dsh web arguments]')
+    process.exit(1)
+  }
+
+  // Shutdown is requested once, by a terminal signal or by a stage exiting on
+  // its own; `signal` stays unset for SIGINT because the terminal's process
+  // group already delivered it to every stage.
+  const shutdown = Promise.withResolvers<number>()
+  const requested: { code?: number; signal?: NodeJS.Signals } = {}
+  const shutdownRequested = (): boolean => requested.code !== undefined
+  const requestShutdown = (code: number, signal: NodeJS.Signals | undefined): void => {
+    if (shutdownRequested()) return
+    requested.code = code
+    if (signal !== undefined) requested.signal = signal
+    shutdown.resolve(code)
+  }
+  const supervisor = new StageSupervisor((stage, code) => {
+    console.error(`dev-web: ${stage} exited (code ${String(code)}); stopping the other stages`)
+    requestShutdown(1, 'SIGTERM')
+  })
+  // Persistent listeners, not `once`: the tsdown watchers bundle signal-exit,
+  // which re-raises a signal whenever it finds no other listener left and would
+  // terminate this process in the middle of the teardown below.
+  process.on('SIGINT', () => { requestShutdown(130, undefined) })
+  process.on('SIGTERM', () => { requestShutdown(0, 'SIGTERM') })
+
+  const buildExit = options.skipBuild ? 0 : await runBuild()
+  if (shutdownRequested()) process.exit(await shutdown.promise)
+  if (buildExit !== 0) {
+    console.error(`dev-web: pnpm run build exited (code ${String(buildExit)})`)
+    process.exit(1)
+  }
+
   const buildEnvironment = devWebBuildEnvironment(repoRoot, process.env)
   for (const name of Object.keys(process.env)) {
     if (name === CLIENT_BUILD_PROFILE_SELECTOR || name.startsWith('DSH_CLIENT_')) {
@@ -214,32 +390,14 @@ if (isMain) {
     process.exit(1)
   }
 
-  const args = process.argv.slice(2)
-  const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
-  if (args.some(a => a !== pollArg)) {
-    console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
-    process.exit(1)
-  }
-  const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
-  if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
-    console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
-    process.exit(1)
-  }
-
-  // Registered before any stage starts: `stages` is read at signal time, so an
-  // interrupt during tsdown's initial builds still kills whatever is running.
-  const stop = (): void => { for (const stage of stages) stage.kill() }
-  process.once('SIGINT', stop)
-  process.once('SIGTERM', stop)
-
   // tsc has no polling interval flag, so `--poll` selects its fixed-interval
   // watchers rather than an interval. Dropping that translation leaves tsc
   // natively watching on a network mount where inotify never fires: it stops
   // re-emitting lib/types, and the two later stages then rebuild forever from
   // stale input without printing anything.
-  spawnStage(`tsc -b ${CLIENT_TYPE_PROGRAM} --watch`, 'tsc', [
+  spawnStage(supervisor, `tsc -b ${CLIENT_TYPE_PROGRAM} --watch`, 'tsc', [
     '-b', CLIENT_TYPE_PROGRAM, '--watch', '--preserveWatchOutput',
-    ...pollInterval !== undefined
+    ...options.pollInterval !== undefined
       ? ['--watchFile', 'fixedPollingInterval', '--watchDirectory', 'fixedPollingInterval']
       : [],
   ], true)
@@ -248,19 +406,34 @@ if (isMain) {
   // first build reads current lib bundles rather than whatever the last full
   // build left. Its own watch then covers later lib rewrites — those files are
   // in its module graph.
-  await watchClientPlugins(repoRoot, [...pluginDirs, ...libraryDirs], pollInterval)
-  // Through the shell's own `watch` script rather than vite's API: vite is not a
-  // repository-root dependency, and more importantly the vite root is its
-  // working directory — `resolve.dedupe` resolves react from that root, so
-  // running vite from anywhere but apps/web silently switches which react copy
-  // the bundle gets.
-  spawnStage('vite build --watch', 'pnpm', ['--filter', SHELL_PACKAGE, 'run', 'watch'], false)
+  const bundles = await watchClientPlugins(repoRoot, [...pluginDirs, ...libraryDirs], options.pollInterval)
+  if (!shutdownRequested()) {
+    // Through the shell's own `watch` script rather than vite's API: vite is not a
+    // repository-root dependency, and more importantly the vite root is its
+    // working directory — `resolve.dedupe` resolves react from that root, so
+    // running vite from anywhere but apps/web silently switches which react copy
+    // the bundle gets.
+    spawnStage(supervisor, 'vite build --watch', 'pnpm', ['--filter', SHELL_PACKAGE, 'run', 'watch'], false)
+    // The same launch vector as the root `dsh` script, so the served Host runs
+    // from source exactly as `pnpm dsh web` would.
+    if (options.serve) {
+      spawnStage(supervisor, 'dsh web', process.execPath, [
+        '--import', 'tsx/esm', 'apps/cli/src/bin.ts', 'web', ...options.appArgs,
+      ], false)
+    }
+    console.log(
+      `dev-web: watching ${String(pluginDirs.length)} dsh.client plugin packages`
+      + ` and ${String(libraryDirs.length)} statically linked library packages`
+      + (options.pollInterval !== undefined ? ` (polling ${String(options.pollInterval)}ms)` : '')
+      + `, plus tsc -b ${CLIENT_TYPE_PROGRAM} and the ${SHELL_PACKAGE} dist build`
+      + (options.serve ? ', serving through dsh web' : '')
+      + ':\n  '
+      + [...pluginDirs, ...libraryDirs].join('\n  '),
+    )
+  }
 
-  console.log(
-    `dev-web: watching ${String(pluginDirs.length)} dsh.client plugin packages`
-    + ` and ${String(libraryDirs.length)} statically linked library packages`
-    + (pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : '')
-    + `, plus tsc -b ${CLIENT_TYPE_PROGRAM} and the ${SHELL_PACKAGE} dist build:\n  `
-    + [...pluginDirs, ...libraryDirs].join('\n  '),
-  )
+  const exitCode = await shutdown.promise
+  await supervisor.stop({ signal: requested.signal, graceMs: STOP_GRACE_MS })
+  for (const bundle of bundles) await bundle[Symbol.asyncDispose]()
+  process.exit(exitCode)
 }
diff --git a/scripts/verify-application-entrypoints.spec.ts b/scripts/verify-application-entrypoints.spec.ts
index 0c84043dfc..6ff6cb673a 100644
--- a/scripts/verify-application-entrypoints.spec.ts
+++ b/scripts/verify-application-entrypoints.spec.ts
@@ -99,8 +99,28 @@ describe('application entrypoints', () => {
     write(root, 'scripts/demo-ptc.mjs', "spawn('node', ['packages/example/app/src/bin.ts'])\n")
 
     expect(applicationEntrypointViolations(root)).toEqual([
-      'scripts/demo-ptc.mjs: application demo wrapper must launch apps/cli/src/bin.ts',
-      'scripts/demo-ptc.mjs: application demo wrapper must not launch a package entry directly',
+      'scripts/demo-ptc.mjs: application launcher wrapper must launch apps/cli/src/bin.ts',
+      'scripts/demo-ptc.mjs: application launcher wrapper must not launch a package entry directly',
+    ])
+  })
+
+  it('rejects a start:web script that bypasses the dsh launcher', () => {
+    const root = fixture()
+    write(root, 'package.json', JSON.stringify({ scripts: { 'start:web': 'node packages/example/app/src/bin.ts web' } }))
+
+    expect(applicationEntrypointViolations(root)).toEqual([
+      'package.json scripts.start:web: application launcher script must launch apps/cli/src/bin.ts',
+      'package.json scripts.start:web: application launcher script must not launch a package entry directly',
+    ])
+  })
+
+  it('rejects a dev:web wrapper that serves without the dsh launcher', () => {
+    const root = fixture()
+    write(root, 'package.json', JSON.stringify({ scripts: { 'dev:web': 'tsx scripts/dev-web.ts --poll' } }))
+    write(root, 'scripts/dev-web.ts', "execa('vite', ['build', '--watch'])\n")
+
+    expect(applicationEntrypointViolations(root)).toEqual([
+      'scripts/dev-web.ts: application launcher wrapper must launch apps/cli/src/bin.ts',
     ])
   })
 
diff --git a/scripts/verify-application-entrypoints.ts b/scripts/verify-application-entrypoints.ts
index 728dd0832f..b629e7e9ab 100644
--- a/scripts/verify-application-entrypoints.ts
+++ b/scripts/verify-application-entrypoints.ts
@@ -18,7 +18,7 @@ interface RootManifest {
   readonly scripts?: Record<string, unknown>
 }
 
-interface DemoPolicy {
+interface LauncherPolicy {
   readonly kind: 'dsh-direct' | 'dsh-wrapper'
   readonly wrapper?: string
 }
@@ -48,10 +48,16 @@ const EXECUTABLE_SOURCE_ALLOWLIST = new Map<string, string>([
   ['python/sdk-runtime/runtime-bootstrap.mjs', 'private packaging-only runtime dispatcher'],
 ])
 
-/** Root demos are application wrappers and therefore must visibly select dsh. */
-const ROOT_DEMO_POLICIES = new Map<string, DemoPolicy>([
+/**
+ * Root scripts that start an application must visibly select dsh: every `demo:*`
+ * script needs a row here, and the Web start and development scripts are pinned
+ * by name.
+ */
+const ROOT_LAUNCHER_POLICIES = new Map<string, LauncherPolicy>([
   ['demo:ptc', { kind: 'dsh-wrapper', wrapper: 'scripts/demo-ptc.mjs' }],
   ['demo:inspector', { kind: 'dsh-direct' }],
+  ['start:web', { kind: 'dsh-direct' }],
+  ['dev:web', { kind: 'dsh-wrapper', wrapper: 'scripts/dev-web.ts' }],
 ])
 
 const SOURCE_PATTERNS = [
@@ -131,22 +137,23 @@ function referencesPackageEntry(source: string): boolean {
   return /packages\/[^/\s'"`]+\/[^/\s'"`]+\/(?:src|lib)\/[^\s'"`]+/.test(source)
 }
 
-function rootDemoViolations(root: string): string[] {
+function rootLauncherViolations(root: string): string[] {
   const manifestPath = resolve(root, 'package.json')
   if (!existsSync(manifestPath)) return []
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as RootManifest
   const failures: string[] = []
   for (const [name, commandValue] of Object.entries(manifest.scripts ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
-    if (!name.startsWith('demo:')) continue
-    const command = typeof commandValue === 'string' ? commandValue : ''
-    const policy = ROOT_DEMO_POLICIES.get(name)
+    const policy = ROOT_LAUNCHER_POLICIES.get(name)
     if (policy === undefined) {
-      failures.push(`package.json scripts.${name}: demo launcher has no explicit dsh or in-process classification`)
+      if (name.startsWith('demo:')) {
+        failures.push(`package.json scripts.${name}: demo launcher has no explicit dsh or in-process classification`)
+      }
       continue
     }
+    const command = typeof commandValue === 'string' ? commandValue : ''
     if (policy.kind === 'dsh-direct') {
-      if (!referencesDshCli(command)) failures.push(`package.json scripts.${name}: application demo must launch apps/cli/src/bin.ts`)
-      if (referencesPackageEntry(command)) failures.push(`package.json scripts.${name}: application demo must not launch a package entry directly`)
+      if (!referencesDshCli(command)) failures.push(`package.json scripts.${name}: application launcher script must launch apps/cli/src/bin.ts`)
+      if (referencesPackageEntry(command)) failures.push(`package.json scripts.${name}: application launcher script must not launch a package entry directly`)
       continue
     }
     const wrapper = policy.wrapper
@@ -156,12 +163,12 @@ function rootDemoViolations(root: string): string[] {
     }
     const wrapperPath = resolve(root, wrapper)
     if (!existsSync(wrapperPath)) {
-      failures.push(`${wrapper}: classified demo wrapper is missing`)
+      failures.push(`${wrapper}: classified launcher wrapper is missing`)
       continue
     }
     const source = readFileSync(wrapperPath, 'utf8')
-    if (!referencesDshCli(source)) failures.push(`${wrapper}: application demo wrapper must launch apps/cli/src/bin.ts`)
-    if (referencesPackageEntry(source)) failures.push(`${wrapper}: application demo wrapper must not launch a package entry directly`)
+    if (!referencesDshCli(source)) failures.push(`${wrapper}: application launcher wrapper must launch apps/cli/src/bin.ts`)
+    if (referencesPackageEntry(source)) failures.push(`${wrapper}: application launcher wrapper must not launch a package entry directly`)
   }
   return failures
 }
@@ -175,7 +182,7 @@ export function applicationEntrypointViolations(root: string): string[] {
   return [
     ...manifestBinViolations(root),
     ...executableSourceViolations(root),
-    ...rootDemoViolations(root),
+    ...rootLauncherViolations(root),
   ]
 }
 

From 91fcd9180ac5a5d5b9223d8859a11aedddf0209b Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Sun, 20 Sep 2026 15:55:29 +0800
Subject: [PATCH 33/37] docs(client): name the caption bubble owner and record
 the badge gap

The occupying badge chooses its own side, and the update badge keeps a right-opening bubble that the Windows caption menu can cover; ui-settings-general records that as a known limitation.
---
 packages/client/ui-settings-general/README.i18n.yaml | 4 ++--
 packages/client/ui-settings-general/README.md        | 1 +
 packages/client/ui-settings-general/README.zh.md     | 1 +
 packages/client/ui-sidebar/README.i18n.yaml          | 4 ++--
 packages/client/ui-sidebar/README.md                 | 2 +-
 packages/client/ui-sidebar/README.zh.md              | 2 +-
 6 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml
index a485e99405..2f86bc5b7c 100644
--- a/packages/client/ui-settings-general/README.i18n.yaml
+++ b/packages/client/ui-settings-general/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-settings-general/README.md
-README.md: cf8bb5a75aa90842108646b57ceec67ada8ae711
-README.zh.md: 7df3eee13df7bd041cc5f09288d1b7fe28acded6
+README.md: ebdb22adc071b5df435fddd6620dd982d866aa36
+README.zh.md: 0bb188ea5024b14e68baa1a687a654ee8963f3d7
diff --git a/packages/client/ui-settings-general/README.md b/packages/client/ui-settings-general/README.md
index cf8bb5a75a..ebdb22adc0 100644
--- a/packages/client/ui-settings-general/README.md
+++ b/packages/client/ui-settings-general/README.md
@@ -103,6 +103,7 @@ None; this package neither assembles nor sends a provider request.
 These limits define what the shell itself provides versus what features must supply; they are current package constraints.
 
 - **Additional General rows require their feature plugins** — the shell supplies Developer tools; feature plugins supply the remaining preferences.
+- **The Windows caption badge keeps a side-opening bubble** — `DesktopUpdateBadge` occupies `sidebar.toggle.badge` in the caption and requests `side="right"`, so the Desktop-owned menu text can cover its bubble while the sidebar is collapsed on Windows; the sidebar toggle and New Session bubbles open below the caption instead (#4688).
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md
index 7df3eee13d..0bb188ea50 100644
--- a/packages/client/ui-settings-general/README.zh.md
+++ b/packages/client/ui-settings-general/README.zh.md
@@ -103,6 +103,7 @@ kind: "package-reference"
 这些限制说明外壳自身提供什么、功能包必须提供什么；它们是当前包约束。
 
 - **额外的通用设置行需要相应功能插件**：外壳提供开发者工具；功能插件提供其他偏好。
+- **Windows 顶栏徽标的气泡仍向右展开**：`DesktopUpdateBadge` 占用顶栏的 `sidebar.toggle.badge` 且请求 `side="right"`，侧栏收起时其气泡会被 Desktop 菜单文字遮挡；侧栏开关与新建会话的气泡则改在顶栏下方展开（#4688）。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index 9703fded4a..72b5b20666 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/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-sidebar/README.md
-README.md: 70489f5f4a8892996f455d21a9493a865990dc49
-README.zh.md: c9691315284c62b126043d070ec071d410fe38ce
+README.md: 94bb3a70ca8c06b5838f41436bb0f2ba2751501e
+README.zh.md: 86f54882ba1c96b9b50898993931757f7afef4e5
diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md
index 70489f5f4a..94bb3a70ca 100644
--- a/packages/client/ui-sidebar/README.md
+++ b/packages/client/ui-sidebar/README.md
@@ -41,7 +41,7 @@ The top expand button hosts the optional, non-interactive `sidebar.toggle.badge`
 
 During a live collapse, the expanded content fades out at its current width, the upper controls share one fade and leftward translation into the 56px rail, and the layout's column slide ends the motion. A page that starts collapsed renders the rail statically, and reduced-motion mode disables both transitions. The bottom-pinned `sidebar.settings` control shares the fade timing but has no horizontal translation.
 
-On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region. The sidebar toggle and New Session bubbles open below the caption, where the Desktop-owned menu text cannot cover them; a `sidebar.toggle.badge` occupant keeps its default side.
+On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region. The sidebar toggle and New Session bubbles open below the caption, where the Desktop-owned menu text cannot cover them; an occupying `sidebar.toggle.badge` chooses its own bubble side.
 
 ### macOS desktop
 
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index c969131528..86f54882ba 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -41,7 +41,7 @@ dsh Web 客户端的侧边栏让用户识别当前构建、启动新会话、将
 
 实时收起时，展开内容在当前宽度淡出，上方控件共用同一段透明度渐变，并向左平移进入 56px 轨道，由布局的栏滑动结束整段动画。页面初始即为收起状态时会静态渲染轨道；减少动态效果模式会禁用两段过渡。固定在底部的 `sidebar.settings` 控件共用相同的透明度渐变时序，但不发生横向位移。
 
-在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。侧栏开关与新建会话的悬停提示在顶栏下方展开，Desktop 菜单文字不会盖住它们；占用 `sidebar.toggle.badge` 的控件保持默认展开方向。
+在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。侧栏开关与新建会话的悬停提示在顶栏下方展开，Desktop 菜单文字不会盖住它们；占用 `sidebar.toggle.badge` 的控件自行决定气泡展开方向。
 
 ### macOS 桌面
 

From 230d975a040cad9f11a11a8b96040c9f6ea94cc1 Mon Sep 17 00:00:00 2001
From: mektpoy <mektpoy@deepseek.com>
Date: Sun, 20 Sep 2026 16:18:56 +0800
Subject: [PATCH 34/37] docs(client): explain the identity tiers and the
 detailName scope

The shared rule now states why the collapsed identity and the expanded value keep two label tiers, and the detailName comment names the row identity it also renders.
---
 .../ui-plugin-manager/src/client/PluginManagerPage.module.css | 4 ++--
 .../src/client/PluginInventorySettingsTab.module.css          | 4 +++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
index 8b4571db6d..0975263b24 100644
--- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
+++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
@@ -1112,8 +1112,8 @@ label.registryOption {
   line-height: 22px;
 }
 
-/* The package name under the title: the exact spec that installs the package
-   elsewhere, where a title of its own or a shortened name hides it. */
+/* The package or row identity under the title: the exact spec that installs the
+   package elsewhere, where a title of its own or a shortened name hides it. */
 .detailName {
   margin: 0;
   font-size: 12px;
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 59d9b1afc0..5358b03f67 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
@@ -178,7 +178,9 @@
   font-weight: 600;
 }
 
-/* The Loader entry id keeps one size in the card subtitle and the row it expands into. */
+/* The Loader entry id keeps one size in the card subtitle and the row it expands into;
+   the collapsed subtitle stays on the quieter label tier, while the expanded row carries
+   the card's primary value. */
 .cardIdentity,
 .entryValue {
   font-family: var(--ds-font-family-code);

From 44cf9b703d6397f8a229505fa0b21e2cae1199fc Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sun, 20 Sep 2026 16:25:03 +0800
Subject: [PATCH 35/37] docs(readme): point developers at dev:web and the Make
 targets

---
 README.i18n.yaml | 4 ++--
 README.md        | 2 ++
 README.zh.md     | 2 ++
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/README.i18n.yaml b/README.i18n.yaml
index 904c7928d2..ce6f75b18d 100644
--- a/README.i18n.yaml
+++ b/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 README.md
-README.md: 36adfe913902e75ce0673adc2cb5cb692151a291
-README.zh.md: f6861b4c9490741b5e5f2d825a370766178dd9f6
+README.md: 423bccd7d9352dbc48f1705f37d35642e74f5b41
+README.zh.md: c760f87e4ac3b7dbb7bb55d733e31db5ab379836
diff --git a/README.md b/README.md
index 36adfe9139..423bccd7d9 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 Start with the [development guide](docs/development.md) and [architecture documentation](docs/architecture.md).
 
+`pnpm run dev:web` builds, serves, and rebuilds client bundles on source edits in one terminal, and `make help` lists the matching Make targets for Web and Desktop; the guide's application commands section owns the full table.
+
 For agents, follow [AGENTS.md](AGENTS.md).
 
 ## Citation
diff --git a/README.zh.md b/README.zh.md
index f6861b4c94..c760f87e4a 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -75,6 +75,8 @@ pnpm dsh web
 
 请先阅读[开发指南](docs/development.zh.md)与[架构文档](docs/architecture.zh.md)。
 
+`pnpm run dev:web` 会在一个终端里完成构建、启动，并在源码修改时重建 client bundle；`make help` 列出 Web 与 Desktop 对应的 Make target。完整表格见开发指南的「应用命令」一节。
+
 面向 agent：请遵循 [AGENTS.md](AGENTS.md)。
 
 ## 引用

From 3eab1714bcd8f85bdc0a16a5a56540c1d83e68d4 Mon Sep 17 00:00:00 2001
From: Turtle 2099 <turtle1999+1@deepseek.com>
Date: Sun, 20 Sep 2026 17:00:03 +0800
Subject: [PATCH 36/37] feat(web): add chat link opening preference (#4671)

* feat(web): add chat link opening preference

* docs(web): clarify preference-controlled link routing

* fix(web): hide link preference without a browser

* fix(web): make the built-in browser opt-in

* test(web): honor profile-aware browser availability

---------

Co-authored-by: Turtle <turtle1999@deepseek.com>
---
 .../web-default-isolation.expected.e2e.ts     |   7 +-
 apps/web/tests/clickable-links-gallery.e2e.ts |  28 +++-
 .../tests/clickable-links-gallery.overlay.yml |   2 +
 .../dialog-no-browser.expected.md             |  28 ++++
 .../tests/markdown-inline-code-links.e2e.ts   |   4 +-
 apps/web/tests/no-sidebar-browser.overlay.yml |   3 +
 apps/web/tests/settings-chrome.e2e.ts         |  21 +++
 apps/web/tests/sidebar-browser.e2e.ts         |   6 +-
 apps/web/tests/sidebar-browser.overlay.yml    |   3 +
 apps/web/tests/sidebar-right.e2e.ts           |   3 +-
 docs/subsystems/sidebar-right.i18n.yaml       |   4 +-
 docs/subsystems/sidebar-right.md              |   2 +-
 docs/subsystems/sidebar-right.zh.md           |   2 +-
 packages/bundle/web-app/cordis.patch.yml      |   3 +-
 .../web-app/tests/browser-defaults.spec.ts    |  41 ++++++
 packages/client/ui-chat/README.i18n.yaml      |   4 +-
 packages/client/ui-chat/README.md             |   2 +-
 packages/client/ui-chat/README.zh.md          |   2 +-
 packages/client/ui-chat/src/chat-settings.ts  |   9 ++
 packages/client/ui-chat/src/client/apply.ts   |  34 ++++-
 .../ui-chat/src/client/contract/slots.ts      |   2 +-
 packages/client/ui-chat/src/client/locale.ts  |   8 ++
 .../src/client/settings/LinkOpeningRow.tsx    |  47 +++++++
 .../tests/apply-inject.client.spec.tsx        | 130 +++++++++++++++++-
 .../ui-chat/tests/chat-apply.client.spec.tsx  |  12 +-
 .../tests/chat-settings.client.spec.ts        |  10 +-
 .../tests/performance-usage.client.spec.ts    |   4 +-
 .../transcript-view-policy.client.spec.ts     |   6 +-
 .../tests/transcript-view-row.client.spec.tsx |  49 ++++++-
 .../ui-sidebar-browser/README.i18n.yaml       |   4 +-
 packages/client/ui-sidebar-browser/README.md  |   6 +-
 .../client/ui-sidebar-browser/README.zh.md    |   6 +-
 .../src/client/slot-catalog.ts                |   1 +
 .../client-runtime/README.i18n.yaml           |   4 +-
 .../test-support/client-runtime/README.md     |   2 +-
 .../test-support/client-runtime/README.zh.md  |   2 +-
 .../src/assembly/bundle-roster.ts             |  37 +++--
 .../assembly-bundle-roster.client.spec.ts     |  88 +++++++++++-
 tsconfig.host.json                            |   3 +-
 39 files changed, 565 insertions(+), 64 deletions(-)
 create mode 100644 apps/web/tests/expected/settings-chrome/dialog-no-browser.expected.md
 create mode 100644 apps/web/tests/no-sidebar-browser.overlay.yml
 create mode 100644 apps/web/tests/sidebar-browser.overlay.yml
 create mode 100644 packages/bundle/web-app/tests/browser-defaults.spec.ts
 create mode 100644 packages/client/ui-chat/src/client/settings/LinkOpeningRow.tsx

diff --git a/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts b/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts
index 0e58af42f3..ecf19a7253 100644
--- a/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts
+++ b/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts
@@ -8,7 +8,7 @@ import { withDefaultWeb, webGet } from './default-web-process.ts'
 
 const experimentalName = '@deepseek-ai/dsh-experimental-client-ui-agent-team'
 
-it('boots the default Web profile without experimental Host modules, mounted plugins, or Client entries', async (test) => {
+it('boots default Web without experimental modules or an active built-in Browser', async (test) => {
   await withDefaultWeb(test, async ({ url, request }) => {
     const auth = await webGet(url, test.signal)
     const cookie = auth.headers['set-cookie']?.[0]?.split(';', 1)[0]
@@ -29,6 +29,11 @@ it('boots the default Web profile without experimental Host modules, mounted plu
     expect(roster.plugins.length).toBeGreaterThan(roster.entries.length)
     expect(roster.modules.some(url => modulePackage(url) === '@deepseek-ai/dsh')).toBe(true)
     expect(roster.client.entries.length).toBeGreaterThan(0)
+    const browserName = '@deepseek-ai/dsh-client-ui-sidebar-browser'
+    const browserEntry = roster.entries.find(entry => entry.name === browserName)
+    expect(browserEntry).toBeDefined()
+    expect(browserEntry!.state).toBeUndefined()
+    expect(delivered.entries.some(entry => entry.id === browserName)).toBe(false)
     expect(experimentalRuntimeReferences(roster)).toEqual([])
 
     const contaminated = await request('mount-experimental')
diff --git a/apps/web/tests/clickable-links-gallery.e2e.ts b/apps/web/tests/clickable-links-gallery.e2e.ts
index 21e4f78bae..2cf02b02eb 100644
--- a/apps/web/tests/clickable-links-gallery.e2e.ts
+++ b/apps/web/tests/clickable-links-gallery.e2e.ts
@@ -318,7 +318,7 @@ describe('web e2e: clickable links gallery', () => {
     await seedSession(scaffold, galleryFixture(imageUrl), SEED_ID, undefined, { createdAt: GALLERY_TIME })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
-    await page.route(/https?:\/\/docs\.example\.test\/.*/u, async route => route.fulfill({
+    await page.context().route(/https?:\/\/docs\.example\.test\/.*/u, async route => route.fulfill({
       contentType: 'text/html',
       body: `<h1>${new URL(route.request().url()).pathname}</h1>`,
     }))
@@ -454,5 +454,31 @@ describe('web e2e: clickable links gallery', () => {
     await expect.poll(() => browserAddress.inputValue()).toBe(GUIDE_URL)
     await markdown.locator(`a[href="${HTTP_URL}"]`).click()
     await expect.poll(() => browserAddress.inputValue()).toBe(HTTP_URL)
+
+    await page.getByRole('button', { name: 'Settings', exact: true }).click()
+    await page.getByRole('button', { name: 'Built-in browser', exact: true }).click()
+    await page.getByRole('menuitem', { name: 'New browser tab', exact: true }).click()
+    await expect.poll(() => scaffold.ctx.settings.get('ui-chat')).toMatchObject({ linkOpening: 'new-tab' })
+    await page.keyboard.press('Escape')
+    const popupPromise = page.waitForEvent('popup')
+    await guideLink.click()
+    const popup = await popupPromise
+    try {
+      await popup.waitForURL(GUIDE_URL)
+      expect(await popup.evaluate(() => window.opener === null)).toBe(true)
+      expect(await browserAddress.inputValue()).toBe(HTTP_URL)
+    } finally {
+      await popup.close()
+    }
+
+    await page.reload()
+    await page.getByRole('button', { name: 'Settings', exact: true }).click()
+    await page.getByRole('button', { name: 'New browser tab', exact: true }).click()
+    await page.getByRole('menuitem', { name: 'Built-in browser', exact: true }).click()
+    await expect.poll(() => scaffold.ctx.settings.get('ui-chat')).toMatchObject({ linkOpening: 'sidebar' })
+    await page.keyboard.press('Escape')
+    await guideLink.click()
+    await expect.poll(() => browserAddress.inputValue()).toBe(GUIDE_URL)
+    expect(tripwire.pageErrors).toEqual([])
   }, 90_000)
 })
diff --git a/apps/web/tests/clickable-links-gallery.overlay.yml b/apps/web/tests/clickable-links-gallery.overlay.yml
index d8adc80e3b..ad0114d151 100644
--- a/apps/web/tests/clickable-links-gallery.overlay.yml
+++ b/apps/web/tests/clickable-links-gallery.overlay.yml
@@ -7,3 +7,5 @@
 - id: settings-controller
   config:
     nativeOpen: true
+- id: ui-sidebar-browser
+  disabled: false
diff --git a/apps/web/tests/expected/settings-chrome/dialog-no-browser.expected.md b/apps/web/tests/expected/settings-chrome/dialog-no-browser.expected.md
new file mode 100644
index 0000000000..41d6462e11
--- /dev/null
+++ b/apps/web/tests/expected/settings-chrome/dialog-no-browser.expected.md
@@ -0,0 +1,28 @@
+- dialog "Settings":
+  - navigation:
+    - text: Settings
+    - button "General"
+    - button "Models"
+    - button "Built-in plugins"
+    - button "Agent presets"
+  - button "Open configuration file"
+  - button "Close"
+  - text: Permission Choose the default permission mode for new sessions
+  - button "Workspace Write"
+  - text: Language
+  - button "English"
+  - text: Appearance
+  - button "Light"
+  - button "Dark"
+  - button "System" [pressed]
+  - text: Font size Only affects conversation content 14
+  - button "Increase font size"
+  - button "Decrease font size"
+  - text: px Conversation display Controls process content in completed turns
+  - button "Compact"
+  - text: Performance & usage Choose how much performance and usage information to show
+  - button "Detailed"
+  - text: Developer tools Show tools and information for debugging and troubleshooting
+  - switch "Developer tools"
+  - text: Send behavior while busy What Enter and the Send button do while the agent is running; Cmd/Ctrl+Enter uses the other behavior
+  - button "Queue"
diff --git a/apps/web/tests/markdown-inline-code-links.e2e.ts b/apps/web/tests/markdown-inline-code-links.e2e.ts
index 8fb8b5942c..fc7392c433 100644
--- a/apps/web/tests/markdown-inline-code-links.e2e.ts
+++ b/apps/web/tests/markdown-inline-code-links.e2e.ts
@@ -92,7 +92,9 @@ describe('web e2e: Markdown inline-code links', () => {
   let tripwire: ReturnType<typeof watchConsole>
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold({})
+    scaffold = await launchWebScaffold({
+      extraOverlayPath: fileURLToPath(new URL('./sidebar-browser.overlay.yml', import.meta.url)),
+    })
     await seedSession(scaffold, markdownFixture(LINK_URL), SEED_ID)
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
diff --git a/apps/web/tests/no-sidebar-browser.overlay.yml b/apps/web/tests/no-sidebar-browser.overlay.yml
new file mode 100644
index 0000000000..2af93975a4
--- /dev/null
+++ b/apps/web/tests/no-sidebar-browser.overlay.yml
@@ -0,0 +1,3 @@
+# Exercise the settings surface without a built-in browser provider.
+- id: ui-sidebar-browser
+  disabled: true
diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts
index d84614d33c..53ccc552d4 100644
--- a/apps/web/tests/settings-chrome.e2e.ts
+++ b/apps/web/tests/settings-chrome.e2e.ts
@@ -722,10 +722,31 @@ describe('web e2e: settings modal and General preferences', () => {
     }
   }, 90_000)
 
+  it('hides link-opening settings when the built-in browser is disabled', async () => {
+    const fresh = await launchWebScaffold({
+      developerTools: false,
+      extraOverlayPath: fileURLToPath(new URL('./no-sidebar-browser.overlay.yml', import.meta.url)),
+    })
+    onTestFinished(() => fresh.close())
+    const withoutBrowser = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: 'en-US' })
+    onTestFinished(() => withoutBrowser.close())
+    const browserConsole = watchConsole(withoutBrowser)
+    await withoutBrowser.goto(fresh.authenticatedUrl, { waitUntil: 'load' })
+    await withoutBrowser.getByRole('button', { name: 'Settings', exact: true }).click()
+    const dialog = withoutBrowser.getByRole('dialog', { name: 'Settings' })
+    await dialog.getByRole('button', { name: 'Detailed', exact: true }).waitFor()
+    expect(await dialog.getByText('Open chat links in', { exact: true }).count()).toBe(0)
+    const snapshot = await captureStableAria(withoutBrowser, '[role="dialog"]', fresh.workspaceCwd)
+    await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'dialog-no-browser.expected.md'), snapshot, MODE)
+    expect(browserConsole.pageErrors).toEqual([])
+    expect(browserConsole.warnings).toEqual([])
+  })
+
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
       'dialog-en.expected.md',
+      'dialog-no-browser.expected.md',
       'dialog.expected.md',
       'plugin-instances.expected.md',
       'plugins.expected.md',
diff --git a/apps/web/tests/sidebar-browser.e2e.ts b/apps/web/tests/sidebar-browser.e2e.ts
index 7a3334bb1b..ca26a11a4c 100644
--- a/apps/web/tests/sidebar-browser.e2e.ts
+++ b/apps/web/tests/sidebar-browser.e2e.ts
@@ -29,7 +29,11 @@ describe.skipIf(MODE === 'record')('web e2e: Sidebar Browser', () => {
   let tripwire: ReturnType<typeof watchConsole>
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold({ replayFixture: FIXTURE, compareReplaySession: false })
+    scaffold = await launchWebScaffold({
+      replayFixture: FIXTURE,
+      compareReplaySession: false,
+      extraOverlayPath: fileURLToPath(new URL('./sidebar-browser.overlay.yml', import.meta.url)),
+    })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
     await page.route('https://browser.test/**', async (route) => {
diff --git a/apps/web/tests/sidebar-browser.overlay.yml b/apps/web/tests/sidebar-browser.overlay.yml
new file mode 100644
index 0000000000..66012abfce
--- /dev/null
+++ b/apps/web/tests/sidebar-browser.overlay.yml
@@ -0,0 +1,3 @@
+# Opt in to Browser for its integration scenarios.
+- id: ui-sidebar-browser
+  disabled: false
diff --git a/apps/web/tests/sidebar-right.e2e.ts b/apps/web/tests/sidebar-right.e2e.ts
index 49be02de85..90571db3f4 100644
--- a/apps/web/tests/sidebar-right.e2e.ts
+++ b/apps/web/tests/sidebar-right.e2e.ts
@@ -409,7 +409,8 @@ describe('web e2e: shipped right Sidebar', () => {
       }
 
       await expect.poll(async () => await tabTitles(column)).toEqual(['Start'])
-      await expect.poll(async () => await column.locator('[data-sidebar-right-guide-entry]').count()).toBe(3)
+      await expect.poll(async () => await column.locator('[data-sidebar-right-guide-entry]').count()).toBe(2)
+      expect(await column.locator('[data-sidebar-right-guide-entry="browser"]').count()).toBe(0)
       await column.locator('[data-sidebar-right-guide-entry="files"]').click()
 
       // A manual guide is closable beside Files and suppresses another add
diff --git a/docs/subsystems/sidebar-right.i18n.yaml b/docs/subsystems/sidebar-right.i18n.yaml
index a1164e5891..30b50d6a0a 100644
--- a/docs/subsystems/sidebar-right.i18n.yaml
+++ b/docs/subsystems/sidebar-right.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/sidebar-right.md
-sidebar-right.md: 9ad6bd63ed63c5c59dbe29cd1229a6412ad22de2
-sidebar-right.zh.md: d0a967f400ea80ab696e24e1b4f46d7d8664eff8
+sidebar-right.md: 27e5219aec8997cf0d168ac9ea2665baaf943906
+sidebar-right.zh.md: 63f2c1081009778e191789038ffd1923312fc55b
diff --git a/docs/subsystems/sidebar-right.md b/docs/subsystems/sidebar-right.md
index 9ad6bd63ed..27e5219aec 100644
--- a/docs/subsystems/sidebar-right.md
+++ b/docs/subsystems/sidebar-right.md
@@ -136,7 +136,7 @@ The Host `ctx.workspaceFiles` service and generated `workspaceFiles` Remote name
 - **`guide`** — `builtin`, opened as `openTab('guide')`. A muted compass sits above one capsule per contributed `guide` entry, in `order`; short lists show registered descriptions, and every missing icon uses the shipped placeholder. Picking a capsule opens the contributing type as a page in the guide tab's place. A pane holds at most one guide tab, and the strip's add control appears only while its pane has none. A new pane receives the registered default page: the sole guide entry directly, or the guide when the entry count is not one ([guide](../../packages/client/ui-sidebar-right/README.md#the-guide)).
 - **`text`** — `fallback`, `dsh-resource://file/**`, claiming Session addresses only. Document Preview observes metadata through `useResource<'file'>`, loads content through Remote callbacks, and owns renderer selection, the toolbar, per-tab refresh, scroll, and source navigation; unknown extensions render as plain text ([README](../../packages/client/ui-sidebar-documentpreview/README.md)).
 - **`files`** — `builtin`, opened as `openTab('files')`. The workspace directory tree, listed lazily through `list` and watched by expanded directory, opening a file with `tab.actions.openResource(fileAddressFor(sessionId, root, path))` into its own pane ([README](../../packages/client/ui-sidebar-files/README.md)).
-- **`browser`** — multi-instance `builtin`, opened as `openTab('browser', { params: { url? } })`. Assistant Markdown delegates HTTP(S) links to this page type. It accepts public and loopback HTTP(S) targets under the default sandbox, rejects local files in favor of Document Preview, and uses application-known iframe history ([README](../../packages/client/ui-sidebar-browser/README.md)).
+- **`browser`** — multi-instance `builtin`, opened as `openTab('browser', { params: { url? } })`. Chat's [link preference](../../packages/client/ui-chat/README.md) controls whether Assistant Markdown opens HTTP(S) links here. It accepts public and loopback HTTP(S) targets under the default sandbox, rejects local files in favor of Document Preview, and uses application-known iframe history ([README](../../packages/client/ui-sidebar-browser/README.md)).
 - **`subagentchat`** — `builtin`, `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>`. An explicitly addressed subagent Conversation retained by the resource provider and rendered through the shared Conversation Factory ([README](../../packages/client/ui-subagent/README.md)).
 
 <a id="not-built"></a>
diff --git a/docs/subsystems/sidebar-right.zh.md b/docs/subsystems/sidebar-right.zh.md
index d0a967f400..63f2c10810 100644
--- a/docs/subsystems/sidebar-right.zh.md
+++ b/docs/subsystems/sidebar-right.zh.md
@@ -136,7 +136,7 @@ Host 的 `ctx.workspaceFiles` 服务与生成的 `workspaceFiles` Remote 命名
 - **`guide`**——`builtin`，以 `openTab('guide')` 打开。一枚弱化的罗盘位于各类型按 `order` 贡献的入口胶囊上方；入口较少时显示已注册的描述，未提供图标的入口统一使用内置占位符。点选胶囊即在引导 tab 的位置把贡献它的类型作为页面打开。每个 pane 最多一个引导 tab，tab 条的新增控件只在本 pane 没有引导时出现。新 pane 使用已注册的默认页：只有一个引导入口时直接使用该入口，否则使用引导页（[引导](../../packages/client/ui-sidebar-right/README.zh.md#the-guide)）。
 - **`text`**——`fallback`，`dsh-resource://file/**`，只认领 Session 地址。Document Preview 通过 `useResource<'file'>` 观察元数据，经 Remote 回调加载内容，并拥有渲染器选择、工具栏、逐 tab 刷新、滚动与源码定位；未知扩展名按纯文本渲染（[README](../../packages/client/ui-sidebar-documentpreview/README.zh.md)）。
 - **`files`**——`builtin`，以 `openTab('files')` 打开。工作区目录树，经 `list` 懒加载，按展开目录建立监听，用 `tab.actions.openResource(fileAddressFor(sessionId, root, path))` 在自己所在 pane 打开文件（[README](../../packages/client/ui-sidebar-files/README.zh.md)）。
-- **`browser`**——可多开的 `builtin`，以 `openTab('browser', { params: { url? } })` 打开。Assistant Markdown 会把 HTTP(S) 链接委托给该页面类型。它在默认 sandbox 下接受公共与 loopback HTTP(S) 目标，本地文件改用 Document Preview，并使用应用已知的 iframe history（[README](../../packages/client/ui-sidebar-browser/README.zh.md)）。
+- **`browser`**——可多开的 `builtin`，以 `openTab('browser', { params: { url? } })` 打开。Chat 的[链接偏好](../../packages/client/ui-chat/README.zh.md)决定 Assistant Markdown 是否在此打开 HTTP(S) 链接。它在默认 sandbox 下接受公共与 loopback HTTP(S) 目标，本地文件改用 Document Preview，并使用应用已知的 iframe history（[README](../../packages/client/ui-sidebar-browser/README.zh.md)）。
 - **`subagentchat`**——`builtin`，`dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>`。资源提供方保留一个显式寻址的 subagent Conversation，并通过共享 Conversation Factory 渲染（[README](../../packages/client/ui-subagent/README.zh.md)）。
 
 <a id="not-built"></a>
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 1f4d203152..72f81ef676 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -233,9 +233,10 @@
     - id: ui-sidebar-documentpreview
       name: '@deepseek-ai/dsh-client-ui-sidebar-documentpreview'
 
-    # Sandboxed HTTP(S) Browser tabs, including loopback targets.
+    # Web profiles opt in; Desktop retains sandboxed HTTP(S) Browser tabs.
     - id: ui-sidebar-browser
       name: '@deepseek-ai/dsh-client-ui-sidebar-browser'
+      disabled: !!js "ctx.get('profileContext')?.name !== 'desktop'"
 
     - id: ui-sidebar-terminal
       name: '@deepseek-ai/dsh-client-ui-sidebar-terminal'
diff --git a/packages/bundle/web-app/tests/browser-defaults.spec.ts b/packages/bundle/web-app/tests/browser-defaults.spec.ts
new file mode 100644
index 0000000000..73ee9b1a82
--- /dev/null
+++ b/packages/bundle/web-app/tests/browser-defaults.spec.ts
@@ -0,0 +1,41 @@
+/** Profile defaults and explicit overrides for the shipped Browser entry. */
+import { fileURLToPath } from 'node:url'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import { applyEntryPatches } from '@deepseek-ai/cordis-plugin-include'
+import { loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
+import * as Browser from '@deepseek-ai/dsh-client-ui-sidebar-browser'
+import { expect, it, onTestFinished } from 'vitest'
+
+it.each([
+  { profile: 'web', override: undefined, disabled: true },
+  { profile: 'custom-web', override: undefined, disabled: true },
+  { profile: undefined, override: undefined, disabled: true },
+  { profile: 'desktop', override: undefined, disabled: false },
+  { profile: 'web', override: false, disabled: false },
+  { profile: 'desktop', override: true, disabled: true },
+])('applies Browser availability for $profile with override $override', async ({ profile, override, disabled }) => {
+  const rows = loadOverlayPatches('browser-defaults', fileURLToPath(new URL('../cordis.patch.yml', import.meta.url)))
+    .flatMap(patch => patch.insert ?? []).filter(row => row.id === 'ui-sidebar-browser')
+  expect(rows).toHaveLength(1)
+  expect(rows[0]!.name).toBe('@deepseek-ai/dsh-client-ui-sidebar-browser')
+  const configured = applyEntryPatches(rows, override === undefined ? [] : [{ id: 'ui-sidebar-browser', disabled: override }],
+    (message) => { throw new Error(message) })
+  const ctx = new Context()
+  onTestFinished(() => ctx.fiber.dispose())
+  if (profile !== undefined) {
+    ctx.provide('profileContext', {
+      name: profile, dir: '/profile', patchPath: '/profile/cordis.patch.yml', installAnchor: '/profile/package.json',
+      cwd: '/workspace', home: '/home', startedBundles: [], overlays: [], telemetryDisabledEnv: undefined,
+    })
+  }
+  ctx.baseUrl = 'file:///'
+  await ctx.plugin(Loader).await()
+  // Keep the real companion in the source-plane loader without native package resolution.
+  ctx.loader.builtins.browser = Browser
+  await ctx.loader.root.update([{ ...configured[0]!, name: 'cordis:browser' }])
+  await ctx.loader.await()
+  const entry = ctx.loader.resolve('ui-sidebar-browser')
+  expect(entry.disabled).toBe(disabled)
+  expect(entry.fiber !== undefined).toBe(!disabled)
+})
diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml
index c42928d650..7d9e60da65 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: b916802917bfdd406fb333174371507d466b8e19
-README.zh.md: 01de4d633cb1501a03200aa96f72e89622d0a7d8
+README.md: eea8eeda01c3d0bd30669cdf3743c64be0d76fbe
+README.zh.md: 58fef8e8c47ae5f67c8ecbf614a36bbfbf2e20b3
diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md
index b916802917..eea8eeda01 100644
--- a/packages/client/ui-chat/README.md
+++ b/packages/client/ui-chat/README.md
@@ -32,7 +32,7 @@ File-mention providers receive the viewed Session ID with the closing-turn owner
 
 Chat supplies file and HTTP(S) navigation through one `MarkdownDelegateProvider` around its node list. Assistant Markdown file links open in the right Sidebar after the message settles, including references to unmodified files. Relative paths resolve in the viewed Session's workspace; absolute paths retain the same Session's filesystem access. `#L24` and `#L24-L30` navigate to the first specified line and reuse an existing file tab. Missing files show the preview's error state.
 
-HTTP(S) links in Assistant Markdown open a new right-Sidebar Browser tab on ordinary clicks when that type is registered, or the system browser otherwise; modified clicks retain the native external-link behavior. Sent file references and skills confirmed by the message’s logged invocation also open in the right Sidebar. File paths use the viewed Session; skill names resolve through its current input-trigger source. Both use the prose file-link dotted underline on hover or focus. Sessions, directories, and command labels remain non-navigating references.
+Settings → General → Open chat links in selects the destination for ordinary clicks on Chat HTTP(S) links: Built-in browser (default) opens a new right-Sidebar Browser tab, while New browser tab opens an external tab. The setting is shown only while the built-in browser is available. If the Sidebar Browser is not registered, both choices use the external browser; modified clicks retain native behavior. The `ui-chat.linkOpening` preference persists on loopback browsers and stays process-local when settings cannot persist writes. Sent file references and skills confirmed by the message’s logged invocation also open in the right Sidebar. File paths use the viewed Session; skill names resolve through its current input-trigger source. Both use the prose file-link dotted underline on hover or focus. Sessions, directories, and command labels remain non-navigating references.
 
 <a id="system-prompt-row"></a>
 ## System prompt row
diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md
index 01de4d633c..58fef8e8c4 100644
--- a/packages/client/ui-chat/README.zh.md
+++ b/packages/client/ui-chat/README.zh.md
@@ -32,7 +32,7 @@ kind: "package-reference"
 
 Chat 在节点列表外通过一个 `MarkdownDelegateProvider` 提供文件及 HTTP(S) 导航。Assistant Markdown 文件链接在消息落定后可于右侧栏打开，包括未修改文件的引用。相对路径基于当前查看的 Session 工作区解析；绝对路径仍使用同一 Session 的文件系统访问。`#L24` 和 `#L24-L30` 定位到指定起始行，并复用现有文件标签。文件缺失时显示预览错误状态。
 
-Assistant Markdown 中的 HTTP(S) 链接在普通点击时会在该类型已注册时打开新的右侧 Sidebar Browser tab，否则改用系统浏览器；带修饰键的点击保留原生外部链接行为。已发送的文件引用及消息日志确认调用的 skill 也可在右侧栏打开预览。文件路径使用当前查看的 Session；skill 名称由该 Session 当前的输入触发源解析。两者悬停或聚焦时均使用正文文件链接的虚线下划线。会话、目录和命令标签仍只作为引用展示。
+设置 → 通用设置 → 聊天链接打开方式控制普通点击 Chat HTTP(S) 链接时的目标：「内置浏览器」（默认）打开新的右侧 Sidebar Browser tab，「浏览器新标签页」打开外部标签页。该设置项仅在内置浏览器可用时显示。若 Sidebar Browser 未注册，两种选择均使用外部浏览器；带修饰键的点击保留原生行为。`ui-chat.linkOpening` 偏好在回环地址浏览器中持久化，设置无法持久化写入时仅在当前进程内生效。已发送的文件引用及消息日志确认调用的 skill 也可在右侧栏打开预览。文件路径使用当前查看的 Session；skill 名称由该 Session 当前的输入触发源解析。两者悬停或聚焦时均使用正文文件链接的虚线下划线。会话、目录和命令标签仍只作为引用展示。
 
 <a id="system-prompt-row"></a>
 ## 系统提示词行
diff --git a/packages/client/ui-chat/src/chat-settings.ts b/packages/client/ui-chat/src/chat-settings.ts
index dbf9014320..021a2b0616 100644
--- a/packages/client/ui-chat/src/chat-settings.ts
+++ b/packages/client/ui-chat/src/chat-settings.ts
@@ -26,16 +26,25 @@ export type PerformanceUsageMode = typeof PERFORMANCE_USAGE_MODES[number]
 /** Preserve detailed accounting for users without an explicit preference. */
 export const DEFAULT_PERFORMANCE_USAGE: PerformanceUsageMode = 'detailed'
 
+/** Destinations for ordinary clicks on Chat HTTP(S) links. */
+export type LinkOpening = 'sidebar' | 'new-tab'
+
+/** Preserve the built-in browser for users without an explicit preference. */
+export const DEFAULT_LINK_OPENING: LinkOpening = 'sidebar'
+
 /** Durable Chat section shared by the Host schema and browser scope. */
 export interface ChatSettings {
   /** Presentation mode for completed Turn process content. */
   transcriptView: TranscriptViewMode
   /** Detail level for composer statistics and completed-Turn usage. */
   performanceUsage: PerformanceUsageMode
+  /** Default destination for Chat HTTP(S) links. */
+  linkOpening: LinkOpening
 }
 
 /** Durable Chat schema; also the wire envelope the browser scope validates against. */
 export const ChatSettingsSchema: z<ChatSettings> = z.object({
+  linkOpening: z.union(['sidebar', 'new-tab']).default(DEFAULT_LINK_OPENING),
   performanceUsage: z.union([...PERFORMANCE_USAGE_MODES]).default(DEFAULT_PERFORMANCE_USAGE),
   [TRANSCRIPT_VIEW_FIELD]: z.union([...TRANSCRIPT_VIEW_MODES]).default(DEFAULT_TRANSCRIPT_VIEW_MODE),
 })
diff --git a/packages/client/ui-chat/src/client/apply.ts b/packages/client/ui-chat/src/client/apply.ts
index 21a63ab782..079a5e2512 100644
--- a/packages/client/ui-chat/src/client/apply.ts
+++ b/packages/client/ui-chat/src/client/apply.ts
@@ -3,7 +3,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type { SessionBinding } from '@deepseek-ai/dsh-api-session-controller/client'
-import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-browser/client'
@@ -34,7 +34,8 @@ import { en, NS, zh } from './locale.ts'
 import { TranscriptViewRow, type TranscriptViewRowInjected } from './settings/TranscriptViewRow.tsx'
 import { createChatStore } from './stores.ts'
 import { TranscriptViewPolicy } from './transcript-view.ts'
-import { CHAT_SETTINGS_NAMESPACE, type ChatSettings } from '../chat-settings.ts'
+import { CHAT_SETTINGS_NAMESPACE, DEFAULT_LINK_OPENING, type ChatSettings } from '../chat-settings.ts'
+import { LinkOpeningRow, type LinkOpeningRowInjected } from './settings/LinkOpeningRow.tsx'
 import { PerformanceUsageRow, type PerformanceUsageRowInjected } from './settings/PerformanceUsageRow.tsx'
 import { PerformanceUsagePolicy } from './performance-usage.ts'
 import { useTurnDataValue } from './chat/use-turn-data.ts'
@@ -82,6 +83,33 @@ export function apply(ctx: Context): void {
   const chatStore = createChatStore()
   const chatScrollPositions = new Map<SessionId, ChatScrollPosition>()
   const chatSettings = ctx.settingsScope.bind<ChatSettings>({ namespace: CHAT_SETTINGS_NAMESPACE })
+  const linkOpening = createSnapshotStore(chatSettings.getSnapshot().value?.linkOpening ?? DEFAULT_LINK_OPENING)
+  ctx.effect(() => chatSettings.subscribe(() => {
+    const accepted = chatSettings.getSnapshot().value?.linkOpening
+    if (accepted !== undefined) linkOpening.set(accepted)
+  }))
+  ctx.inject(['sidebarRightTabs'], (scope) => {
+    const tabs = scope.sidebarRightTabs
+    const browserAvailable: ObservableSnapshot<boolean> = {
+      getSnapshot: () => tabs.get('browser') !== undefined,
+      subscribe: listener => tabs.subscribe(listener),
+    }
+    scope.slots.inject('settings.general.item', () => scope.slots.register({
+      name: 'settings.general.item',
+      id: 'link-opening',
+      order: 14,
+      locale: NS,
+      inject: (): LinkOpeningRowInjected => ({
+        hooks: { linkOpening, browserAvailable },
+        setLinkOpening: (destination) => {
+          linkOpening.set(destination)
+          void chatSettings.set('linkOpening', destination).catch((_error: unknown) => {
+            // The local choice remains usable when persistence is unavailable.
+          })
+        },
+      }),
+    }, LinkOpeningRow))
+  })
   const transcriptView = new TranscriptViewPolicy(chatSettings)
   const performancePolicy = new PerformanceUsagePolicy(chatSettings)
   const performanceUsage = performancePolicy.mode
@@ -158,7 +186,7 @@ export function apply(ctx: Context): void {
             ctx.get('inputTriggers')?.sessionOf(scope).openReference('skill', { ref: `/${name}` })
           },
           openExternalLink: (url) => {
-            if (ctx.get('sidebarRightTabs')?.get('browser') !== undefined) {
+            if (linkOpening.getSnapshot() === 'sidebar' && ctx.get('sidebarRightTabs')?.get('browser') !== undefined) {
               ctx.sidebarRight.openTab('browser', { params: { url } })
             } else {
               window.open(url, '_blank', 'noopener,noreferrer')
diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts
index d5b007b7cf..5e811b7963 100644
--- a/packages/client/ui-chat/src/client/contract/slots.ts
+++ b/packages/client/ui-chat/src/client/contract/slots.ts
@@ -150,7 +150,7 @@ export interface ChatViewInjected {
   }
   /** Open the current source file of a skill referenced by a sent message. */
   openSkill: (name: string) => void
-  /** Open one HTTP(S) message link in a Sidebar Browser tab. */
+  /** Open one HTTP(S) message link at the selected destination, using an external tab if Sidebar Browser is unavailable. */
   openExternalLink: (url: string) => void
   openFile: (path: string, options?: OpenFileOptions) => Promise<void>
   loadOlder: () => void
diff --git a/packages/client/ui-chat/src/client/locale.ts b/packages/client/ui-chat/src/client/locale.ts
index 344fef13d0..51d3adca00 100644
--- a/packages/client/ui-chat/src/client/locale.ts
+++ b/packages/client/ui-chat/src/client/locale.ts
@@ -31,6 +31,10 @@ export const zh = {
   'settings.performance.description': '选择性能与用量信息展示的详细程度',
   'settings.performance.compact': '简洁',
   'settings.performance.detailed': '详细',
+  'settings.links.title': '聊天链接打开方式',
+  'settings.links.description': '选择聊天中 HTTP(S) 链接的打开位置',
+  'settings.links.sidebar': '内置浏览器',
+  'settings.links.newTab': '浏览器新标签页',
   'settings.transcript.title': '对话显示',
   'settings.transcript.description': '控制已完成轮次的过程内容',
   'settings.transcript.normal': '标准',
@@ -141,6 +145,10 @@ export const en = {
   'settings.performance.description': 'Choose how much performance and usage information to show',
   'settings.performance.compact': 'Compact',
   'settings.performance.detailed': 'Detailed',
+  'settings.links.title': 'Open chat links in',
+  'settings.links.description': 'Choose where HTTP(S) links in chat open',
+  'settings.links.sidebar': 'Built-in browser',
+  'settings.links.newTab': 'New browser tab',
   'settings.transcript.title': 'Conversation display',
   'settings.transcript.description': 'Controls process content in completed turns',
   'settings.transcript.normal': 'Normal',
diff --git a/packages/client/ui-chat/src/client/settings/LinkOpeningRow.tsx b/packages/client/ui-chat/src/client/settings/LinkOpeningRow.tsx
new file mode 100644
index 0000000000..b17a3e4929
--- /dev/null
+++ b/packages/client/ui-chat/src/client/settings/LinkOpeningRow.tsx
@@ -0,0 +1,47 @@
+/** General Settings row for Chat HTTP(S) link destinations. */
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { LinkOpening } from '../../chat-settings.ts'
+import { PreferenceRow } from './PreferenceRow.tsx'
+
+/** Registration-side link-opening preference. */
+export interface LinkOpeningRowInjected {
+  hooks: {
+    /** Current destination, bound as useLinkOpening. */
+    linkOpening: ObservableSnapshot<LinkOpening>
+    /** Whether the built-in browser is registered, bound as useBrowserAvailable. */
+    browserAvailable: ObservableSnapshot<boolean>
+  }
+  /** Change the default destination for Chat HTTP(S) links. */
+  setLinkOpening: (destination: LinkOpening) => void
+}
+
+/** Full Settings-row props. */
+export type LinkOpeningRowProps =
+  PropsRuntime<'settings.general.item'>
+  & PropsLocale<'chat'>
+  & InjectFace<LinkOpeningRowInjected>
+
+/**
+ * Render the link-opening destination selector.
+ * @param props - Composed Settings slot props.
+ * @returns The preference row.
+ */
+export function LinkOpeningRow({ useLinkOpening, useBrowserAvailable, setLinkOpening, t }: LinkOpeningRowProps) {
+  const destination = useLinkOpening(value => value)
+  const browserAvailable = useBrowserAvailable(value => value)
+  if (!browserAvailable) return null
+  return (
+    <PreferenceRow
+      title={t('settings.links.title')}
+      description={t('settings.links.description')}
+      value={destination}
+      selectedLabel={t(destination === 'sidebar' ? 'settings.links.sidebar' : 'settings.links.newTab')}
+      options={[
+        { id: 'sidebar', label: t('settings.links.sidebar') },
+        { id: 'new-tab', label: t('settings.links.newTab') },
+      ]}
+      onSelect={(value) => { setLinkOpening(value as LinkOpening) }}
+    />
+  )
+}
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 7977740640..dff3bbe376 100644
--- a/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
@@ -19,6 +19,8 @@ import {
 import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
 import { createChatStore } from '../src/client/stores.ts'
+import { CHAT_SETTINGS_NAMESPACE, type ChatSettings } from '../src/chat-settings.ts'
+import type { LinkOpeningRowInjected } from '../src/client/settings/LinkOpeningRow.tsx'
 
 usePinnedBrowserLanguages('zh-CN')
 
@@ -47,9 +49,16 @@ function sessionFakeFor() {
   } satisfies SessionBehaviorOverrides
 }
 
-async function bench() {
+async function bench(initialSettings?: ChatSettings, withBrowserRegistry = true) {
   const runtime = await SlotTestRuntime.create()
-  runtime.ctx.provide('settingsScope', { developerTools: { enabled: createSnapshotStore(true) }, bind: () => stubSettingsScope().scope } as never)
+  const chatSettings = stubSettingsScope<ChatSettings>()
+  if (initialSettings !== undefined) chatSettings.publish({ value: initialSettings })
+  runtime.ctx.provide('settingsScope', {
+    developerTools: { enabled: createSnapshotStore(true) },
+    bind: ({ namespace }: { namespace: string }) => namespace === CHAT_SETTINGS_NAMESPACE
+      ? chatSettings.scope
+      : stubSettingsScope().scope,
+  } as never)
   const layout = { closeRightbar: vi.fn(), openRightbar: vi.fn() }
   runtime.ctx.provide('layout', layout as never)
   const sidebarRight = {
@@ -57,11 +66,13 @@ async function bench() {
     openTab: vi.fn<(kind: string, options?: unknown) => void>(),
   }
   runtime.ctx.provide('sidebarRight', sidebarRight as never)
+  const browserAvailable = createSnapshotStore(true)
   const sidebarRightTabs = {
-    get: vi.fn<(kind: string) => object | undefined>(() => ({})),
+    get: vi.fn<(kind: string) => object | undefined>(() => browserAvailable.getSnapshot() ? {} : undefined),
+    subscribe: (listener: () => void) => browserAvailable.subscribe(listener),
     register: vi.fn(() => () => {}),
   }
-  runtime.ctx.provide('sidebarRightTabs', sidebarRightTabs as never)
+  if (withBrowserRegistry) runtime.ctx.provide('sidebarRightTabs', sidebarRightTabs as never)
   runtime.ctx.provide('resources', { register: vi.fn(() => () => {}) } as never)
   const openWorkspacePath = vi.fn<ClientRemote['session']['openWorkspacePath']>(
     () => Promise.resolve({ ok: true, value: { opened: true } }),
@@ -88,9 +99,10 @@ async function bench() {
   runtime.slots.installLocale(locale)
   await runtime.root.declare({
     'main': { kind: 'keyed', scope: 'root' },
+    'settings.general.item': { kind: 'list', scope: 'root' },
   }, (_props: { renderSlot?: unknown }) => null)
   await runtime.mount({ inject: [...injectConversation], apply: applyConversation })
-  await runtime.mount({ inject: [...injectChat], apply: applyChat })
+  const chat = await runtime.mount({ inject: [...injectChat], apply: applyChat })
   runtime.renderRoot()
 
   const chatViewApi = (reference: SessionReference) => {
@@ -104,7 +116,13 @@ async function bench() {
     return { instance, injected }
   }
   return {
-    runtime, layout, openWorkspacePath, sidebarRight, sidebarRightTabs, session, chatViewApi, rootReference, openSession,
+    get linkPreference() {
+      const row = runtime.slots.entries('settings.general.item').find(entry => entry.options.id === 'link-opening')!
+      const preference: object = row.inject!()
+      return preference as LinkOpeningRowInjected
+    },
+    runtime, chat, chatSettings, browserAvailable,
+    layout, openWorkspacePath, sidebarRight, sidebarRightTabs, session, chatViewApi, rootReference, openSession,
   }
 }
 
@@ -184,6 +202,106 @@ describe('Chat inject API', () => {
     }
   })
 
+  it('applies restored and live link destinations without remounting the Chat view', async () => {
+    const settings: ChatSettings = { transcriptView: 'compact', performanceUsage: 'detailed', linkOpening: 'new-tab' }
+    const b = await bench(settings)
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null)
+    try {
+      const { injected } = b.chatViewApi(b.rootReference)
+      const source = b.linkPreference.hooks.linkOpening
+      expect(source.getSnapshot()).toBe('new-tab')
+      injected.openExternalLink('https://example.test/restored')
+      expect(open).toHaveBeenLastCalledWith('https://example.test/restored', '_blank', 'noopener,noreferrer')
+      expect(b.sidebarRight.openTab).not.toHaveBeenCalled()
+
+      b.chatSettings.publish({ value: { ...settings, linkOpening: 'sidebar' } })
+      expect(source.getSnapshot()).toBe('sidebar')
+      injected.openExternalLink('http://example.test/live')
+      expect(b.sidebarRight.openTab).toHaveBeenLastCalledWith('browser', { params: { url: 'http://example.test/live' } })
+
+      b.linkPreference.setLinkOpening('new-tab')
+      expect(b.chatSettings.set).toHaveBeenCalledWith('linkOpening', 'new-tab')
+      injected.openExternalLink('http://example.test/selected')
+      expect(open).toHaveBeenLastCalledWith('http://example.test/selected', '_blank', 'noopener,noreferrer')
+
+      await b.chat.dispose()
+      expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(false)
+      b.chatSettings.publish({ value: { ...settings, linkOpening: 'sidebar' } })
+      expect(source.getSnapshot()).toBe('new-tab')
+    } finally {
+      open.mockRestore()
+      await b.runtime.dispose()
+    }
+  })
+
+  it('follows browser registration and routes absent browsers externally', async () => {
+    const b = await bench()
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null)
+    const available = b.linkPreference.hooks.browserAvailable
+    const changed = vi.fn()
+    const unsubscribe = available.subscribe(changed)
+    try {
+      const { injected } = b.chatViewApi(b.rootReference)
+      expect(available.getSnapshot()).toBe(true)
+      b.browserAvailable.set(false)
+      expect(available.getSnapshot()).toBe(false)
+      expect(changed).toHaveBeenCalledOnce()
+      injected.openExternalLink('https://example.test/disabled')
+      expect(open).toHaveBeenCalledWith('https://example.test/disabled', '_blank', 'noopener,noreferrer')
+      b.browserAvailable.set(true)
+      injected.openExternalLink('https://example.test/enabled')
+      expect(b.sidebarRight.openTab).toHaveBeenCalledWith('browser', { params: { url: 'https://example.test/enabled' } })
+      expect(b.linkPreference.hooks.linkOpening.getSnapshot()).toBe('sidebar')
+    } finally {
+      unsubscribe()
+      open.mockRestore()
+      await b.runtime.dispose()
+    }
+  })
+
+  it('keeps Chat available while the optional tab registry appears and leaves', async () => {
+    const b = await bench(undefined, false)
+    try {
+      expect(b.runtime.slots.entries('conversation.view')).toHaveLength(1)
+      expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(false)
+      const registry = await b.runtime.mount({
+        apply(ctx) { ctx.provide('sidebarRightTabs', b.sidebarRightTabs as never) },
+      })
+      await vi.waitFor(() => {
+        expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(true)
+      })
+      await registry.dispose()
+      expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(false)
+      expect(b.runtime.slots.entries('conversation.view')).toHaveLength(1)
+    } finally {
+      await b.runtime.dispose()
+    }
+  })
+
+  it('keeps local link choices usable when settings cannot persist', async () => {
+    const b = await bench()
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null)
+    try {
+      const { injected } = b.chatViewApi(b.rootReference)
+      b.chatSettings.publish({ mode: 'memory', status: 'unavailable' })
+      b.chatSettings.set.mockResolvedValueOnce(false)
+      b.linkPreference.setLinkOpening('new-tab')
+      b.chatSettings.publish({ value: undefined })
+      injected.openExternalLink('https://example.test/local')
+      expect(open).toHaveBeenCalledWith('https://example.test/local', '_blank', 'noopener,noreferrer')
+      expect(b.sidebarRight.openTab).not.toHaveBeenCalled()
+
+      b.chatSettings.set.mockRejectedValueOnce(new Error('settings unavailable'))
+      b.linkPreference.setLinkOpening('sidebar')
+      await Promise.resolve()
+      injected.openExternalLink('https://example.test/local-sidebar')
+      expect(b.sidebarRight.openTab).toHaveBeenCalledWith('browser', { params: { url: 'https://example.test/local-sidebar' } })
+    } finally {
+      open.mockRestore()
+      await b.runtime.dispose()
+    }
+  })
+
   it('routes sent skill previews through the viewed Session source and tolerates an absent provider', async () => {
     const b = await bench()
     const { injected } = b.chatViewApi(b.rootReference)
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 028752d24c..e085bba34e 100644
--- a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
@@ -47,7 +47,11 @@ async function bench() {
   } as never)
   runtime.ctx.provide('layout', { openRightbar: vi.fn(), closeRightbar: vi.fn() } as never)
   runtime.ctx.provide('sidebarRight', { openResource: vi.fn(), openTab: vi.fn() } as never)
-  runtime.ctx.provide('sidebarRightTabs', { register: vi.fn(() => () => {}) } as never)
+  runtime.ctx.provide('sidebarRightTabs', {
+    register: vi.fn(() => () => {}),
+    get: vi.fn(() => ({})),
+    subscribe: vi.fn(() => () => {}),
+  } as never)
   runtime.ctx.provide('resources', { register: vi.fn(() => () => {}) } as never)
   const openSession = vi.fn<(id: SessionId) => void>()
   runtime.ctx.provide('uiWorkspace', {
@@ -94,7 +98,7 @@ describe('Chat apply wiring', () => {
     expect(b.runtime.slots.entries('conversation.composer.dock').map(row => row.options.id))
       .toEqual(['stats'])
     expect(b.runtime.slots.entries('settings.general.item').map(row => row.options.id))
-      .toEqual(['transcript-view', 'performance-usage', 'composer-enter'])
+      .toEqual(['transcript-view', 'performance-usage', 'link-opening', 'composer-enter'])
     await b.runtime.dispose()
   })
 
@@ -110,7 +114,7 @@ describe('Chat apply wiring', () => {
     expect(b.chatSettings.set).toHaveBeenCalledWith('transcriptView', 'normal')
 
     b.chatSettings.publish({
-      status: 'ready', value: { transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 1, writable: true,
+      status: 'ready', value: { linkOpening: 'sidebar', transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 1, writable: true,
     })
     expect(face.hooks.transcriptView.getSnapshot()).toBe('compact')
     await b.runtime.dispose()
@@ -123,7 +127,7 @@ describe('Chat apply wiring', () => {
     expect(face.hooks.performanceUsage.getSnapshot()).toBe('detailed')
     face.setPerformanceUsage('compact')
     expect(b.chatSettings.set).toHaveBeenCalledWith('performanceUsage', 'compact')
-    b.chatSettings.publish({ value: { transcriptView: 'compact', performanceUsage: 'compact' } })
+    b.chatSettings.publish({ value: { linkOpening: 'sidebar', transcriptView: 'compact', performanceUsage: 'compact' } })
     expect(face.hooks.performanceUsage.getSnapshot()).toBe('compact')
     for (const entry of [
       b.runtime.slots.entries('conversation.composer.dock').find(entry => entry.options.id === 'stats')!,
diff --git a/packages/client/ui-chat/tests/chat-settings.client.spec.ts b/packages/client/ui-chat/tests/chat-settings.client.spec.ts
index ad5ae6ab89..d2c146c40d 100644
--- a/packages/client/ui-chat/tests/chat-settings.client.spec.ts
+++ b/packages/client/ui-chat/tests/chat-settings.client.spec.ts
@@ -21,14 +21,20 @@ describe('ui-chat Host settings', () => {
     await fiber.await()
     const ns = CHAT_SETTINGS_NAMESPACE
 
-    expect(ctx.settings.get(ns)).toEqual({ transcriptView: DEFAULT_TRANSCRIPT_VIEW_MODE, performanceUsage: 'detailed' })
+    expect(ctx.settings.get(ns)).toEqual({ transcriptView: DEFAULT_TRANSCRIPT_VIEW_MODE, performanceUsage: 'detailed', linkOpening: 'sidebar' })
     await ctx.settings.update(ns, { transcriptView: 'normal' })
-    expect(ctx.settings.get(ns)).toEqual({ transcriptView: 'normal', performanceUsage: 'detailed' })
+    expect(ctx.settings.get(ns)).toEqual({ transcriptView: 'normal', performanceUsage: 'detailed', linkOpening: 'sidebar' })
     await expect(ctx.settings.update(ns, { transcriptView: 'dense' })).rejects.toThrow()
     await ctx.settings.update(ns, { performanceUsage: 'compact' })
     expect(ctx.settings.get(ns)).toMatchObject({ performanceUsage: 'compact' })
     await expect(ctx.settings.update(ns, { performanceUsage: 'hidden' })).rejects.toThrow()
 
+    await ctx.settings.update(ns, { linkOpening: 'new-tab' })
+    expect(ctx.settings.get(ns)).toMatchObject({ linkOpening: 'new-tab' })
+    await ctx.settings.update(ns, { linkOpening: 'sidebar' })
+    expect(ctx.settings.get(ns)).toMatchObject({ linkOpening: 'sidebar' })
+    await expect(ctx.settings.update(ns, { linkOpening: 'popup' })).rejects.toThrow()
+
     await fiber.dispose()
     expect(ctx.settings.describe().map(row => row.ns)).not.toContain(ns)
   })
diff --git a/packages/client/ui-chat/tests/performance-usage.client.spec.ts b/packages/client/ui-chat/tests/performance-usage.client.spec.ts
index 00e862cfe6..54ddfdd1de 100644
--- a/packages/client/ui-chat/tests/performance-usage.client.spec.ts
+++ b/packages/client/ui-chat/tests/performance-usage.client.spec.ts
@@ -21,10 +21,10 @@ describe('PerformanceUsagePolicy', () => {
 
   it('adopts accepted Host settings at construction and after updates', () => {
     const host = stubSettingsScope<ChatSettings>()
-    host.publish({ value: { transcriptView: 'normal', performanceUsage: 'compact' } })
+    host.publish({ value: { linkOpening: 'sidebar', transcriptView: 'normal', performanceUsage: 'compact' } })
     const policy = new PerformanceUsagePolicy(host.scope)
     expect(policy.mode.getSnapshot()).toBe('compact')
-    host.publish({ value: { transcriptView: 'normal', performanceUsage: 'detailed' } })
+    host.publish({ value: { linkOpening: 'sidebar', transcriptView: 'normal', performanceUsage: 'detailed' } })
     expect(policy.mode.getSnapshot()).toBe('detailed')
   })
 })
diff --git a/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts b/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts
index 84717bb5c0..ec8595496a 100644
--- a/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts
+++ b/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts
@@ -30,18 +30,18 @@ describe('TranscriptViewPolicy', () => {
     const host = stubSettingsScope<ChatSettings>()
     const policy = new TranscriptViewPolicy(host.scope)
 
-    host.publish({ status: 'ready', value: { transcriptView: 'normal', performanceUsage: 'detailed' }, revision: 1, writable: true })
+    host.publish({ status: 'ready', value: { linkOpening: 'sidebar', transcriptView: 'normal', performanceUsage: 'detailed' }, revision: 1, writable: true })
     expect(policy.mode.getSnapshot()).toBe('normal')
     policy.setMode('normal')
     expect(host.set).not.toHaveBeenCalled()
 
-    host.publish({ value: { transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 2 })
+    host.publish({ value: { linkOpening: 'sidebar', transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 2 })
     expect(policy.mode.getSnapshot()).toBe('compact')
   })
 
   it('adopts an accepted section standing at construction', () => {
     const host = stubSettingsScope<ChatSettings>()
-    host.publish({ status: 'ready', value: { transcriptView: 'normal', performanceUsage: 'detailed' }, revision: 1, writable: true })
+    host.publish({ status: 'ready', value: { linkOpening: 'sidebar', transcriptView: 'normal', performanceUsage: 'detailed' }, revision: 1, writable: true })
     expect(new TranscriptViewPolicy(host.scope).mode.getSnapshot()).toBe('normal')
   })
 })
diff --git a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
index ca5aeb1e00..82c928ac97 100644
--- a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
+++ b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { WorkspaceSnapshot } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionStatusSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
@@ -9,7 +9,8 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { TranscriptViewRow, type TranscriptViewRowProps } from '../src/client/settings/TranscriptViewRow.tsx'
 import { PerformanceUsageRow } from '../src/client/settings/PerformanceUsageRow.tsx'
-import type { PerformanceUsageMode } from '../src/chat-settings.ts'
+import type { LinkOpening, PerformanceUsageMode } from '../src/chat-settings.ts'
+import { LinkOpeningRow } from '../src/client/settings/LinkOpeningRow.tsx'
 import { en, zh } from '../src/client/locale.ts'
 
 afterEach(cleanup)
@@ -80,6 +81,50 @@ describe('TranscriptViewRow', () => {
 })
 
 
+describe('LinkOpeningRow', () => {
+  it('follows browser availability without clearing the saved destination', () => {
+    const b = mount()
+    const browserAvailable = createSnapshotStore(false)
+    const source = createSnapshotStore<LinkOpening>('new-tab')
+    render(<LinkOpeningRow
+      {...b.props}
+      useLinkOpening={bindSnapshotSelector(source)}
+      useBrowserAvailable={bindSnapshotSelector(browserAvailable)}
+      setLinkOpening={vi.fn()}
+    />)
+    expect(screen.queryByText('Open chat links in')).toBeNull()
+    act(() => { browserAvailable.set(true) })
+    expect(screen.getByRole('button', { name: 'New browser tab' })).toBeDefined()
+    act(() => { browserAvailable.set(false) })
+    expect(screen.queryByText('Open chat links in')).toBeNull()
+    expect(source.getSnapshot()).toBe('new-tab')
+  })
+
+  it.each([
+    [en, 'Open chat links in', 'Built-in browser', 'New browser tab'],
+    [zh, '聊天链接打开方式', '内置浏览器', '浏览器新标签页'],
+  ] as const)('selects either destination using localized labels (%s)', (dictionary, title, sidebar, newTab) => {
+    const b = mount('compact', dictionary)
+    const source = createSnapshotStore<LinkOpening>('sidebar')
+    const setLinkOpening = vi.fn((destination: LinkOpening) => { source.set(destination) })
+    render(<LinkOpeningRow
+      {...b.props}
+      useLinkOpening={bindSnapshotSelector(source)}
+      useBrowserAvailable={bindSnapshotSelector(createSnapshotStore(true))}
+      setLinkOpening={setLinkOpening}
+    />)
+    expect(screen.getByText(title)).toBeDefined()
+    fireEvent.click(screen.getByRole('button', { name: sidebar }))
+    fireEvent.click(screen.getByRole('menuitem', { name: newTab }))
+    expect(setLinkOpening).toHaveBeenLastCalledWith('new-tab')
+    fireEvent.click(screen.getByRole('button', { name: newTab }))
+    fireEvent.click(screen.getByRole('menuitem', { name: sidebar }))
+    expect(setLinkOpening).toHaveBeenLastCalledWith('sidebar')
+    expect(screen.getByRole('button', { name: sidebar }).getAttribute('aria-expanded')).toBe('false')
+    expect(b.setTranscriptView).not.toHaveBeenCalled()
+  })
+})
+
 describe('PerformanceUsageRow', () => {
   it('selects compact statistics independently of conversation display', () => {
     const b = mount()
diff --git a/packages/client/ui-sidebar-browser/README.i18n.yaml b/packages/client/ui-sidebar-browser/README.i18n.yaml
index 533b9d85e2..455edd84ea 100644
--- a/packages/client/ui-sidebar-browser/README.i18n.yaml
+++ b/packages/client/ui-sidebar-browser/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-sidebar-browser/README.md
-README.md: 61de40ef98c72501c20c56cffb1075322bcb4886
-README.zh.md: 8bdc88a85f2473e62c640e509db53577c1f2e6d4
+README.md: dcfaccdfb85cdada9300aadb2f6e9058dc5a95bc
+README.zh.md: 8d5c34ab4c1b4d87e2a25912f38f102442f7a454
diff --git a/packages/client/ui-sidebar-browser/README.md b/packages/client/ui-sidebar-browser/README.md
index 61de40ef98..dcfaccdfb8 100644
--- a/packages/client/ui-sidebar-browser/README.md
+++ b/packages/client/ui-sidebar-browser/README.md
@@ -25,7 +25,7 @@ Browse HTTP(S) pages, including loopback services, inside independent right-Side
 <a id="use-this-package"></a>
 ## Use this package
 
-The shipped Web and Desktop compositions already mount this package. Open **Browser** from the right-Sidebar guide, enter an HTTP(S) URL, or select an HTTP(S) link in Assistant Markdown. A host name without a scheme becomes HTTPS. Public and loopback targets use the same default sandbox. Each guide action or message-link activation creates another Browser tab.
+Browser is disabled by default in Web profiles and enabled on Desktop. Enable the shipped entry through the Web profile patch to use it. Open **Browser** from the right-Sidebar guide and enter an HTTP(S) URL. Chat HTTP(S) links open here when the [link preference](../ui-chat/README.md) selects the built-in browser. A host name without a scheme becomes HTTPS. Public and loopback targets use the same default sandbox. Each guide action or delegated message-link activation creates another Browser tab.
 
 ### When to choose it
 
@@ -33,11 +33,11 @@ Choose Browser for a Web page that should remain beside the current Session. Cho
 
 ### Minimal configuration
 
-The package has no configuration. A custom Web composition mounts its Host companion; the Client loader then discovers the browser entry declared by the package manifest:
+The package has no plugin configuration. A Web profile enables the shipped entry through its profile patch:
 
 ```yaml
 - id: ui-sidebar-browser
-  name: '@deepseek-ai/dsh-client-ui-sidebar-browser'
+  disabled: false
 ```
 
 Client plugins can open a tab through `ctx.sidebarRight.openTab('browser', { params: { url } })`. The optional URL passes the same validation as address-bar input before navigation.
diff --git a/packages/client/ui-sidebar-browser/README.zh.md b/packages/client/ui-sidebar-browser/README.zh.md
index 8bdc88a85f..8d5c34ab4c 100644
--- a/packages/client/ui-sidebar-browser/README.zh.md
+++ b/packages/client/ui-sidebar-browser/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-随附的 Web 与 Desktop composition 已挂载本包。可以从右侧 Sidebar guide 打开 **浏览器**、输入 HTTP(S) URL，或点击 Assistant Markdown 中的 HTTP(S) 链接。不带 scheme 的主机名会补全为 HTTPS。公共目标与 loopback 目标使用相同的默认 sandbox。每次 guide 操作或消息链接操作都会创建一个新的 Browser tab。
+Browser 在 Web profile 中默认禁用，在 Desktop 中默认启用。Web 用户可通过 profile patch 启用随附条目。可以从右侧 Sidebar guide 打开 **浏览器**并输入 HTTP(S) URL。Chat 的[链接偏好](../ui-chat/README.zh.md)选择内置浏览器时，HTTP(S) 链接会在此打开。不带 scheme 的主机名会补全为 HTTPS。公共目标与 loopback 目标使用相同的默认 sandbox。每次 guide 操作或委托到此的消息链接操作都会创建一个新的 Browser tab。
 
 ### 何时选择
 
@@ -33,11 +33,11 @@ kind: "package-reference"
 
 ### 最小配置
 
-本包没有配置字段。自定义 Web composition 挂载 Host companion；随后 Client loader 会发现 package manifest 声明的浏览器入口：
+本包没有插件配置字段。Web profile 通过其 profile patch 启用随附条目：
 
 ```yaml
 - id: ui-sidebar-browser
-  name: '@deepseek-ai/dsh-client-ui-sidebar-browser'
+  disabled: false
 ```
 
 Client 插件可以调用 `ctx.sidebarRight.openTab('browser', { params: { url } })` 打开 tab。可选 URL 会在导航前接受与地址栏输入相同的校验。
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 76a69a3cdf..b540e06b33 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -1988,6 +1988,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     declaredBy: 'an entry in \'settings.section\' (client-ui-settings-general), so it exists while that entry is mounted',
     occupants: [
       'client-locale LanguageRow id \'language\'',
+      'client-ui-chat LinkOpeningRow id \'link-opening\'',
       'client-ui-chat PerformanceUsageRow id \'performance-usage\'',
       'client-ui-chat TranscriptViewRow id \'transcript-view\'',
       'client-ui-conversation EnterBehaviorRow id \'composer-enter\'',
diff --git a/packages/test-support/client-runtime/README.i18n.yaml b/packages/test-support/client-runtime/README.i18n.yaml
index d37d28f763..6a6ad363c6 100644
--- a/packages/test-support/client-runtime/README.i18n.yaml
+++ b/packages/test-support/client-runtime/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/test-support/client-runtime/README.md
-README.md: 1e9a9aeabe8b27f67557216f354d31a6ccf9d594
-README.zh.md: 27f3f5447f2845f5dbcbc928d62222cb0fbefe84
+README.md: b4197ffc750ec585e4df1b9da9af1731558bfc99
+README.zh.md: 087d464ba900965d23b09d1ff9f67b9259f08933
diff --git a/packages/test-support/client-runtime/README.md b/packages/test-support/client-runtime/README.md
index 1e9a9aeabe..b4197ffc75 100644
--- a/packages/test-support/client-runtime/README.md
+++ b/packages/test-support/client-runtime/README.md
@@ -89,7 +89,7 @@ The [generic Remote proxy](../remote-mock/README.md#remote-proxy) supports every
 
 ### Roster and startup behavior
 
-`webApp` is the `web` profile's browser roster, read when the assembly entry is first imported from its bundles (`dsh-base`, then `dsh-web-app`) as the launcher composes them, except that a patch matching nothing throws here where the launcher warns: each bundle's `dsh.bundle.patch` list is parsed with the include plugin's YAML dialect and composed by its `applyEntryPatches`, and every enabled row whose package declares `dsh.client.platform === 'web'` becomes a row carrying that declaration's `inject` and `immediately`; `bundleRoster(bundles)` does the same for any bundle list. Nothing is copied from the bundles, so a bundle change is visible at the next test run. `webApp.closure(names)` keeps the named rows plus everything they inject, transitively (the rows a spec needs to boot those plugins as the bundle composes them), `webApp.pick(names)` and `webApp.without(names)` cut it down by hand, all three throw on unknown names, and `ClientRoster.of(rows)` builds one inline. `remoteDefaultResponses` holds default responses for exactly the Remote endpoints the roster calls while booting with no sessions, no workspaces, and default settings; a spec layers its own `RemoteTable` on top with `mock.load(table)`, and any call without a rule fails the test at `dispose()` through `mock.assertNoUnmatched()`. `mount` requires a roster that provides `uiRenderer`; `start` fails loud otherwise instead of returning an empty container. `client.connection` is the roster's Connection service (no `Context` augmentation declares it), and `connectTimeoutMs` bounds the readiness wait, whose failure message lists the mock log. `reload(name)` rebuilds one Loader entry through the shared Client Modules helper (registry-first teardown, then `entry.refresh()`); each client retains its own module system and instance-bound Connection replacement, so starts and reloads can overlap without changing a page global. `unload(name)` removes an entry and waits for plugin cleanup; `flush()` settles React inside `act`. jsdom implements neither `EventSource` (client-hmr opens one at apply) nor `ResizeObserver` (layout components observe size at mount), so `start` reference-counts inert stubs for whichever global is absent and `dispose` removes exactly those — a jsdom gap, not a client identity channel. The `@deepseek-ai/dsh-api-remotes` row is dropped from every roster: its generated Remote clients exist only in built `lib/`, and `remote.<ns>` is what the tier replaces anyway. `start` instead provides one contract-free proxy per `remote.<ns>` service the roster injects (plus the namespaces the mock has rules for at that point; a namespace first registered later has no proxy); `ctx.remote.<ns>.<method>(...args)` becomes a call on the endpoint `<ns>/<method>` carrying the positional args, a stream when the mock registered a `stream()` script and a unary call otherwise, with the generated client's outcome folding (`gateway/internal` for carrier throws, `gateway/cancelled` on abort). An endpoint without a rule is still dispatched, so the mock logs it and `dispose()` fails the test.
+`webApp` is the `web` profile's browser roster, read when the assembly entry is first imported from its bundles (`dsh-base`, then `dsh-web-app`) as the launcher composes them, except that a patch matching nothing throws here where the launcher warns: each bundle's `dsh.bundle.patch` list is parsed with the include plugin's YAML dialect and composed by its `applyEntryPatches`, and every enabled row whose package declares `dsh.client.platform === 'web'` becomes a row carrying that declaration's `inject` and `immediately`; `bundleRoster(bundles, anchor, disabledContext)` accepts an explicit Loader evaluation scope for conditional `disabled` flags; without one, browser expressions are rejected. `webApp` supplies the Web profile name, not business Host services. Nothing is copied from the bundles, so a bundle change is visible at the next test run. `webApp.closure(names)` keeps the named rows plus everything they inject, transitively (the rows a spec needs to boot those plugins as the bundle composes them), `webApp.pick(names)` and `webApp.without(names)` cut it down by hand, all three throw on unknown names, and `ClientRoster.of(rows)` builds one inline. `remoteDefaultResponses` holds default responses for exactly the Remote endpoints the roster calls while booting with no sessions, no workspaces, and default settings; a spec layers its own `RemoteTable` on top with `mock.load(table)`, and any call without a rule fails the test at `dispose()` through `mock.assertNoUnmatched()`. `mount` requires a roster that provides `uiRenderer`; `start` fails loud otherwise instead of returning an empty container. `client.connection` is the roster's Connection service (no `Context` augmentation declares it), and `connectTimeoutMs` bounds the readiness wait, whose failure message lists the mock log. `reload(name)` rebuilds one Loader entry through the shared Client Modules helper (registry-first teardown, then `entry.refresh()`); each client retains its own module system and instance-bound Connection replacement, so starts and reloads can overlap without changing a page global. `unload(name)` removes an entry and waits for plugin cleanup; `flush()` settles React inside `act`. jsdom implements neither `EventSource` (client-hmr opens one at apply) nor `ResizeObserver` (layout components observe size at mount), so `start` reference-counts inert stubs for whichever global is absent and `dispose` removes exactly those — a jsdom gap, not a client identity channel. The `@deepseek-ai/dsh-api-remotes` row is dropped from every roster: its generated Remote clients exist only in built `lib/`, and `remote.<ns>` is what the tier replaces anyway. `start` instead provides one contract-free proxy per `remote.<ns>` service the roster injects (plus the namespaces the mock has rules for at that point; a namespace first registered later has no proxy); `ctx.remote.<ns>.<method>(...args)` becomes a call on the endpoint `<ns>/<method>` carrying the positional args, a stream when the mock registered a `stream()` script and a unary call otherwise, with the generated client's outcome folding (`gateway/internal` for carrier throws, `gateway/cancelled` on abort). An endpoint without a rule is still dispatched, so the mock logs it and `dispose()` fails the test.
 
 ### When to use it
 
diff --git a/packages/test-support/client-runtime/README.zh.md b/packages/test-support/client-runtime/README.zh.md
index 27f3f5447f..087d464ba9 100644
--- a/packages/test-support/client-runtime/README.zh.md
+++ b/packages/test-support/client-runtime/README.zh.md
@@ -89,7 +89,7 @@ test('registers into the sidebar', async ({ remote, start }) => {
 
 ### Roster 与启动行为
 
-`webApp` 是 `web` profile 的浏览器 roster，首次 import 装配入口时从它的 bundle（先 `dsh-base`、再 `dsh-web-app`）按启动器的方式现读，只是匹配不到任何行的补丁在这里抛错、启动器只警告：每个 bundle 的 `dsh.bundle.patch` 列表用 include 插件的 YAML 方言解析、用它的 `applyEntryPatches` 合成，每个未禁用且其包声明 `dsh.client.platform === 'web'` 的行成为一行，带上该声明的 `inject` 与 `immediately`；`bundleRoster(bundles)` 对任意 bundle 列表做同样的事。没有任何东西从 bundle 拷贝出来，bundle 一改下次跑测试就能看见。`webApp.closure(names)` 保留点名的行及其传递注入的全部行（即按 bundle 组合方式起这些插件所需的行），`webApp.pick(names)` 与 `webApp.without(names)` 手工裁剪，三者都对未知名字抛错，`ClientRoster.of(rows)` 内联构造一份。`remoteDefaultResponses` 是 roster 在没有 session、没有 workspace、默认设置下启动时恰好会打的那些 Remote 端点的默认响应；测试用 `mock.load(table)` 在其上叠加自己的 `RemoteTable`，任何没有规则的调用都会在 `dispose()` 时经 `mock.assertNoUnmatched()` 让测试失败。`mount` 要求 roster 提供 `uiRenderer`；否则 `start` 响亮失败而不是返回一个空容器。`client.connection` 是 roster 的 Connection 服务（没有任何 `Context` 增强声明它），`connectTimeoutMs` 限定等就绪的时长，超时消息列出 mock log。`reload(name)` 通过共享的 Client Modules 辅助函数重建一个 Loader entry（先拆 registry，再 `entry.refresh()`）；每个客户端都保留自己的模块系统和绑定实例的 Connection 替换，因此启动与重载可以重叠而无需改写页面全局变量。`unload(name)` 移除 entry 并等待插件清理完成，`flush()` 在 `act` 内让 React 落定。jsdom 既没有 `EventSource`（client-hmr 在 apply 时打开一个）也没有 `ResizeObserver`（布局组件挂载时观察尺寸），所以 `start` 对缺失的全局惰性桩做引用计数，`dispose` 只移除它装的那些——这是 jsdom 的缺口，不是客户端身份通道。每个 roster 里的 `@deepseek-ai/dsh-api-remotes` 行都会被去掉：它生成的 Remote 客户端只存在于构建后的 `lib/`，而 `remote.<ns>` 正是本档要替掉的东西。`start` 改为给 roster 注入的每个 `remote.<ns>` 服务（加上此刻 mock 登记过规则的命名空间；之后才首次登记的命名空间没有代理）提供一个无契约代理；`ctx.remote.<ns>.<method>(...args)` 变成对端点 `<ns>/<method>` 的调用，携带位置参数，mock 登记了 `stream()` 脚本的走流、否则走一元，并沿用生成客户端的结果折叠（载体抛错折成 `gateway/internal`，中止折成 `gateway/cancelled`）。没有规则的端点照样发出，所以 mock 会记下它、`dispose()` 让测试失败。
+`webApp` 是 `web` profile 的浏览器 roster，首次 import 装配入口时从它的 bundle（先 `dsh-base`、再 `dsh-web-app`）按启动器的方式现读，只是匹配不到任何行的补丁在这里抛错、启动器只警告：每个 bundle 的 `dsh.bundle.patch` 列表用 include 插件的 YAML 方言解析、用它的 `applyEntryPatches` 合成，每个未禁用且其包声明 `dsh.client.platform === 'web'` 的行成为一行，带上该声明的 `inject` 与 `immediately`；`bundleRoster(bundles, anchor, disabledContext)` 接受显式 Loader 求值作用域来处理条件 `disabled` 标记；未提供作用域时拒绝浏览器表达式。`webApp` 仅提供 Web profile 名称，不提供业务 Host 服务。没有任何东西从 bundle 拷贝出来，bundle 一改下次跑测试就能看见。`webApp.closure(names)` 保留点名的行及其传递注入的全部行（即按 bundle 组合方式起这些插件所需的行），`webApp.pick(names)` 与 `webApp.without(names)` 手工裁剪，三者都对未知名字抛错，`ClientRoster.of(rows)` 内联构造一份。`remoteDefaultResponses` 是 roster 在没有 session、没有 workspace、默认设置下启动时恰好会打的那些 Remote 端点的默认响应；测试用 `mock.load(table)` 在其上叠加自己的 `RemoteTable`，任何没有规则的调用都会在 `dispose()` 时经 `mock.assertNoUnmatched()` 让测试失败。`mount` 要求 roster 提供 `uiRenderer`；否则 `start` 响亮失败而不是返回一个空容器。`client.connection` 是 roster 的 Connection 服务（没有任何 `Context` 增强声明它），`connectTimeoutMs` 限定等就绪的时长，超时消息列出 mock log。`reload(name)` 通过共享的 Client Modules 辅助函数重建一个 Loader entry（先拆 registry，再 `entry.refresh()`）；每个客户端都保留自己的模块系统和绑定实例的 Connection 替换，因此启动与重载可以重叠而无需改写页面全局变量。`unload(name)` 移除 entry 并等待插件清理完成，`flush()` 在 `act` 内让 React 落定。jsdom 既没有 `EventSource`（client-hmr 在 apply 时打开一个）也没有 `ResizeObserver`（布局组件挂载时观察尺寸），所以 `start` 对缺失的全局惰性桩做引用计数，`dispose` 只移除它装的那些——这是 jsdom 的缺口，不是客户端身份通道。每个 roster 里的 `@deepseek-ai/dsh-api-remotes` 行都会被去掉：它生成的 Remote 客户端只存在于构建后的 `lib/`，而 `remote.<ns>` 正是本档要替掉的东西。`start` 改为给 roster 注入的每个 `remote.<ns>` 服务（加上此刻 mock 登记过规则的命名空间；之后才首次登记的命名空间没有代理）提供一个无契约代理；`ctx.remote.<ns>.<method>(...args)` 变成对端点 `<ns>/<method>` 的调用，携带位置参数，mock 登记了 `stream()` 脚本的走流、否则走一元，并沿用生成客户端的结果折叠（载体抛错折成 `gateway/internal`，中止折成 `gateway/cancelled`）。没有规则的端点照样发出，所以 mock 会记下它、`dispose()` 让测试失败。
 
 ### 何时使用
 
diff --git a/packages/test-support/client-runtime/src/assembly/bundle-roster.ts b/packages/test-support/client-runtime/src/assembly/bundle-roster.ts
index 14284556f5..bd945ab43f 100644
--- a/packages/test-support/client-runtime/src/assembly/bundle-roster.ts
+++ b/packages/test-support/client-runtime/src/assembly/bundle-roster.ts
@@ -17,7 +17,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
+import { evaluate, isJsExpr, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import { applyEntryPatches, entryListSchema, type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import { exactPackageSpecifier, parseDshClient } from '@deepseek-ai/dsh-client-modules/client'
 import * as yaml from 'js-yaml'
@@ -41,11 +41,16 @@ interface BundleLayer {
  * Compose the browser roster of `bundles`, applied in order.
  * @param bundles - bundle package names in application order.
  * @param anchor - file whose package resolution locates the bundles; default this package.
+ * @param disabledContext - optional Loader evaluation scope for trusted `disabled` expressions.
  * @returns the roster in composition order, one row per package.
  * @throws {Error} when a bundle, its patch file, or an enabled row's package does not resolve, when the patch list
- * is not a list or does not apply as written, or when a browser row's `disabled` is a `!!js` expression.
+ * is not a list or does not apply as written, or when a browser row has an unevaluated `disabled` expression.
  */
-export function bundleRoster(bundles: readonly string[], anchor: string = fileURLToPath(import.meta.url)): ClientRoster {
+export function bundleRoster(
+  bundles: readonly string[],
+  anchor: string = fileURLToPath(import.meta.url),
+  disabledContext?: object,
+): ClientRoster {
   const layers = bundles.map(name => readLayer(name, anchor))
   const entries = applyEntryPatches([], layers.flatMap(layer => layer.patches), (message: string, ...args: unknown[]) => {
     throw new Error(`client-test-runtime: bundle patch ${describe(message, args)}`)
@@ -55,7 +60,9 @@ export function bundleRoster(bundles: readonly string[], anchor: string = fileUR
   const seen = new Set<string>()
   for (const { entry, disabled } of flattenGroups(entries)) {
     const name = exactPackageSpecifier(entry.name)
-    if (name === undefined || disabled === true || seen.has(name)) continue
+    if (name === undefined || disabled.includes(true) || seen.has(name)) continue
+    if (disabledContext !== undefined
+      && disabled.some(value => isJsExpr(value) && Boolean(evaluate(disabledContext, value.__jsExpr)))) continue
     seen.add(name)
     const manifestPath = locateManifest(anchors, name)
     if (manifestPath === undefined) {
@@ -67,7 +74,8 @@ export function bundleRoster(bundles: readonly string[], anchor: string = fileUR
     }
     const declaration = parseDshClient(name, manifest.dsh?.client)
     if (declaration === undefined || declaration.platform !== 'web') continue
-    if (disabled !== undefined && disabled !== null && typeof disabled !== 'boolean') {
+    if (disabled.some(value => value !== undefined && value !== null && typeof value !== 'boolean'
+      && !(disabledContext !== undefined && isJsExpr(value)))) {
       throw new Error(`client-test-runtime: browser row ${name} has a \`disabled\` value this reader cannot evaluate (a !!js expression)`)
     }
     rows.push({ name, inject: declaration.inject ?? [], immediately: declaration.immediately === true })
@@ -86,24 +94,23 @@ function readLayer(bundle: string, anchor: string): BundleLayer {
   return { manifestPath, patches: parsed as PatchOptions[] }
 }
 
-/** One Loader row with the `disabled` value that governs it: its own, or the nearest enclosing group's when that is set. */
+/** One Loader row with its ancestor and own disable conditions, in outer-to-inner order. */
 interface FlatEntry {
   readonly entry: EntryOptions
-  readonly disabled: unknown
+  readonly disabled: readonly unknown[]
 }
 
 /**
  * Rows in Loader order with groups descended, as the Loader loads them: a group is never a plugin itself, and a group's
  * `disabled` disables every row beneath it.
  * @param entries - composed entries, possibly nested.
- * @param inherited - the enclosing group's `disabled` when set.
+ * @param inherited - the enclosing groups' disable conditions.
  * @returns the plugin rows.
  */
-function flattenGroups(entries: readonly EntryOptions[], inherited?: unknown): FlatEntry[] {
+function flattenGroups(entries: readonly EntryOptions[], inherited: readonly unknown[] = []): FlatEntry[] {
   const rows: FlatEntry[] = []
   for (const entry of entries) {
-    const own = (entry as { disabled?: unknown }).disabled
-    const disabled = inherited !== undefined && inherited !== null && inherited !== false ? inherited : own
+    const disabled = [...inherited, (entry as { disabled?: unknown }).disabled]
     if (entry.group === true && Array.isArray(entry.config)) {
       rows.push(...flattenGroups(entry.config as EntryOptions[], disabled))
       continue
@@ -134,5 +141,9 @@ function describe(message: string, args: readonly unknown[]): string {
   return message.replace(/%C/g, () => JSON.stringify(args[index++]))
 }
 
-/** The `web` profile's browser roster, composed from its bundles at import. */
-export const webApp: ClientRoster = bundleRoster(WEB_PROFILE_BUNDLES)
+const webProfileServices: Readonly<Record<string, object | undefined>> = { profileContext: { name: 'web' } }
+
+/** The `web` profile's browser roster, composed with its profile name and no business Host services. */
+export const webApp: ClientRoster = bundleRoster(WEB_PROFILE_BUNDLES, undefined, {
+  get: (name: string) => webProfileServices[name],
+})
diff --git a/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts b/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts
index e73ce00818..a1fa3f6191 100644
--- a/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts
+++ b/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts
@@ -7,6 +7,11 @@ import { afterAll, describe, expect, it } from 'vitest'
 import { MODULES_PACKAGE } from '../src/assembly/modules.ts'
 import { WEB_PROFILE_BUNDLES, bundleRoster, webApp } from '../src/assembly/bundle-roster.ts'
 
+function profileScope(name: string) {
+  const services: Record<string, object | undefined> = { profileContext: { name } }
+  return { get: (key: string) => services[key] }
+}
+
 describe('webApp (the real web profile)', () => {
   it('composes dsh-base then dsh-web-app: unique names, inject edges on roster rows or platform seed words', () => {
     expect(WEB_PROFILE_BUNDLES).toEqual(['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'])
@@ -15,7 +20,10 @@ describe('webApp (the real web profile)', () => {
     const known = new Set([...names, ...Object.keys(getStaticModules())])
     const dangling = webApp.rows.flatMap(row => row.inject.filter(target => !known.has(target)).map(target => `${row.name} -> ${target}`))
     expect(dangling).toEqual([])
-    expect(bundleRoster(WEB_PROFILE_BUNDLES).rows).toEqual(webApp.rows)
+    expect(bundleRoster(WEB_PROFILE_BUNDLES, undefined, profileScope('web')).rows).toEqual(webApp.rows)
+    expect(names).not.toContain('@deepseek-ai/dsh-client-ui-sidebar-browser')
+    expect(bundleRoster(WEB_PROFILE_BUNDLES, undefined, profileScope('desktop')).rows.map(row => row.name))
+      .toContain('@deepseek-ai/dsh-client-ui-sidebar-browser')
   })
 
   it('keeps browser rows with their declarations and drops Host-only, disabled, and subpath rows', () => {
@@ -154,6 +162,84 @@ describe('bundleRoster on a scratch installation', () => {
     expect(() => scratch.roster(['@t/maybe-bundle'])).toThrow('browser row @t/maybe has a `disabled` value this reader cannot evaluate')
   })
 
+  it('evaluates profile conditions before deduplication and skips ignored row expressions', () => {
+    scratch.web('@t/conditional')
+    scratch.bundle('@t/conditional-bundle', `
+- insert:
+    - id: ignored
+      name: ./ignored.mjs
+      disabled: !!js missingIgnoredValue
+    - id: first
+      name: '@t/conditional'
+      disabled: !!js ctx.get('profileContext').name !== 'desktop'
+    - id: second
+      name: '@t/conditional'
+      disabled: false
+`)
+    expect(bundleRoster(['@t/conditional-bundle'], scratch.anchor, profileScope('web')).rows.map(row => row.name))
+      .toEqual(['@t/conditional'])
+  })
+
+  it('combines ancestor and child conditions without evaluating disabled subtrees', () => {
+    scratch.web('@t/conditional-on')
+    scratch.web('@t/conditional-off')
+    scratch.bundle('@t/conditional-groups', `
+- insert:
+    - id: parent-off
+      name: cordis:group
+      group: true
+      disabled: !!js true
+      config:
+        - id: unreachable
+          name: '@t/not-installed'
+          disabled: !!js missingInactiveValue
+    - id: literal-off
+      name: cordis:group
+      group: true
+      disabled: true
+      config:
+        - id: also-unreachable
+          name: '@t/not-installed-either'
+          disabled: !!js missingInactiveValue
+    - id: parent-on
+      name: cordis:group
+      group: true
+      disabled: !!js false
+      config:
+        - id: child-off
+          name: '@t/conditional-off'
+          disabled: true
+        - id: nested-on
+          name: cordis:group
+          group: true
+          disabled: !!js false
+          config:
+            - id: child-on
+              name: '@t/conditional-on'
+              disabled: null
+`)
+    expect(bundleRoster(['@t/conditional-groups'], scratch.anchor, {}).rows.map(row => row.name))
+      .toEqual(['@t/conditional-on'])
+  })
+
+  it('propagates evaluation failures and rejects unsupported literal flags with a scope', () => {
+    scratch.web('@t/bad-condition')
+    scratch.bundle('@t/bad-expression', `
+- insert:
+    - id: bad
+      name: '@t/bad-condition'
+      disabled: !!js missingConditionValue
+`)
+    expect(() => bundleRoster(['@t/bad-expression'], scratch.anchor, {})).toThrow('missingConditionValue')
+    scratch.bundle('@t/bad-literal', `
+- insert:
+    - id: bad
+      name: '@t/bad-condition'
+      disabled: not-a-boolean
+`)
+    expect(() => bundleRoster(['@t/bad-literal'], scratch.anchor, {})).toThrow('disabled')
+  })
+
   it('fails loud on a bundle that does not resolve, declares no patch, or whose patch is not a list', () => {
     expect(() => scratch.roster(['@t/missing'])).toThrow('cannot resolve bundle @t/missing from')
     scratch.pkg('@t/no-patch', { dsh: {} })
diff --git a/tsconfig.host.json b/tsconfig.host.json
index c1088e0ae8..f15cff939c 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -8,7 +8,8 @@
     "rewriteRelativeImportExtensions": false
   },
   "files": [
-    "packages/client/ui-settings-general/src/client/desktop-update-bridge.ts"
+    "packages/client/ui-settings-general/src/client/desktop-update-bridge.ts",
+    "packages/client/ui-sidebar-browser/src/index.ts"
   ],
   "include": [
     "apps/web/product-isolation.ts",

From 8f0dd55c2cb74610b0291067884955ab4eb74a70 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 20 Sep 2026 17:00:17 +0800
Subject: [PATCH 37/37] feat(plugins): render icons from package manifests
 (#4697)

* feat(plugins): render icons from package manifests

* fix(plugins): include declared icons in canonical package payloads
---
 .../expected/plugin-manager/icons.expected.md |   5 +
 .../fixtures/plugins/fixture-bundle/icon.svg  |   1 +
 .../plugins/fixture-bundle/package.json       |   1 +
 .../fixture-bundle/search.package.json        |   1 +
 apps/web/tests/plugin-manager.e2e.ts          |  46 ++++++-
 docs/cookbook/adding-a-package.i18n.yaml      |   4 +-
 docs/cookbook/adding-a-package.md             |   4 +-
 docs/cookbook/adding-a-package.zh.md          |   4 +-
 packages/boot/app-boot/README.i18n.yaml       |   4 +-
 packages/boot/app-boot/README.md              |   2 +-
 packages/boot/app-boot/README.zh.md           |   2 +-
 packages/boot/app-boot/src/package-meta.ts    |  57 +++++++--
 .../boot/app-boot/tests/package-meta.spec.ts  | 120 +++++++++++++++++-
 .../client/ui-plugin-manager/README.i18n.yaml |   4 +-
 packages/client/ui-plugin-manager/README.md   |   2 +-
 .../client/ui-plugin-manager/README.zh.md     |   2 +-
 .../src/client/PluginManagerPage.module.css   |   4 +
 .../src/client/PluginManagerPage.tsx          |  30 +++--
 .../tests/components.client.spec.tsx          |  32 +++++
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   2 +-
 packages/client/ui-primitives/README.zh.md    |   2 +-
 packages/client/ui-primitives/src/index.ts    |   2 +-
 .../ui-primitives/src/plugin-artwork.tsx      |  19 ---
 .../tests/plugin-artwork.client.spec.tsx      |   3 +-
 .../agent-team-profile/README.i18n.yaml       |   4 +-
 .../experimental/agent-team-profile/README.md |   2 +-
 .../agent-team-profile/README.zh.md           |   2 +-
 .../experimental/agent-team-profile/icon.svg  |  12 ++
 .../agent-team-profile/package.json           |   2 +
 .../extensions/tool-cordis/src/api-catalog.ts |   2 +-
 .../util/package-manifest/README.i18n.yaml    |   4 +-
 packages/util/package-manifest/README.md      |   2 +-
 packages/util/package-manifest/README.zh.md   |   2 +-
 packages/util/package-manifest/src/types.ts   |   6 +-
 scripts/check-workspace-constraints.spec.ts   |  14 ++
 scripts/check-workspace-constraints.ts        |   6 +-
 scripts/verify-package-meta.spec.ts           |  75 +++++++++++
 scripts/verify-package-meta.ts                |  32 ++++-
 39 files changed, 437 insertions(+), 85 deletions(-)
 create mode 100644 apps/web/tests/expected/plugin-manager/icons.expected.md
 create mode 100644 apps/web/tests/fixtures/plugins/fixture-bundle/icon.svg
 create mode 100644 packages/experimental/agent-team-profile/icon.svg

diff --git a/apps/web/tests/expected/plugin-manager/icons.expected.md b/apps/web/tests/expected/plugin-manager/icons.expected.md
new file mode 100644
index 0000000000..fb9df5edb1
--- /dev/null
+++ b/apps/web/tests/expected/plugin-manager/icons.expected.md
@@ -0,0 +1,5 @@
+Third-party bundle card: image, 36×36, decoded
+Disabled Agent Teams card: image, 36×36, decoded
+Agent Teams detail: image, 36×36, decoded
+Third-party bundle detail: image, 36×36, decoded
+Independent search row: image, 30×30, decoded
diff --git a/apps/web/tests/fixtures/plugins/fixture-bundle/icon.svg b/apps/web/tests/fixtures/plugins/fixture-bundle/icon.svg
new file mode 100644
index 0000000000..ad85688706
--- /dev/null
+++ b/apps/web/tests/fixtures/plugins/fixture-bundle/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36"><circle cx="18" cy="18" r="14" fill="#145AF3" /></svg>
diff --git a/apps/web/tests/fixtures/plugins/fixture-bundle/package.json b/apps/web/tests/fixtures/plugins/fixture-bundle/package.json
index 3224dfa296..71aa6bbd5f 100644
--- a/apps/web/tests/fixtures/plugins/fixture-bundle/package.json
+++ b/apps/web/tests/fixtures/plugins/fixture-bundle/package.json
@@ -1,6 +1,7 @@
 {
   "name": "@fixture/bundle",
   "version": "0.0.1",
+  "icon": "./icon.svg",
   "private": true,
   "description": "Registry description for the fixture bundle.",
   "type": "module",
diff --git a/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json b/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json
index 52a0c0f420..79083aafff 100644
--- a/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json
+++ b/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json
@@ -1,4 +1,5 @@
 {
   "name": "Search plugin",
+  "icon": "./icon.svg",
   "description": "Search package introduction."
 }
diff --git a/apps/web/tests/plugin-manager.e2e.ts b/apps/web/tests/plugin-manager.e2e.ts
index 373b0ba459..8ce5950d4c 100644
--- a/apps/web/tests/plugin-manager.e2e.ts
+++ b/apps/web/tests/plugin-manager.e2e.ts
@@ -140,6 +140,50 @@ describe('web e2e: plugin manager', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
+  it('decodes manifest icons for disabled bundles and independent plugin rows', async () => {
+    const panel = await openPluginsPanel()
+    const fixtureIcon = `data:image/svg+xml;base64,${(await readFile(join(FIXTURE_PLUGINS, 'fixture-bundle/icon.svg'))).toString('base64')}`
+    const teamIcon = `data:image/svg+xml;base64,${(await readFile(fileURLToPath(new URL('../../../packages/experimental/agent-team-profile/icon.svg', import.meta.url)))).toString('base64')}`
+    const images: string[] = []
+    const checkImage = async (selector: string, source: string, label: string) => {
+      const image = panel.locator(`${selector} img`).first()
+      await image.waitFor()
+      expect(await image.getAttribute('src')).toBe(source)
+      await image.evaluate(async (node: HTMLImageElement) => { await node.decode() })
+      const size = await image.evaluate((node: HTMLImageElement) => ({
+        width: node.width, height: node.height, naturalWidth: node.naturalWidth,
+      }))
+      expect(size.naturalWidth).toBeGreaterThan(0)
+      images.push(`${label}: image, ${size.width}×${size.height}, decoded`)
+    }
+    await checkImage('[data-plugin-package="@fixture/bundle"]', fixtureIcon, 'Third-party bundle card')
+    const team = panel.locator('[data-plugin-package="@deepseek-ai/dsh-experimental-agent-team-profile"]')
+    expect(await team.getByRole('switch').getAttribute('aria-checked')).toBe('false')
+    await checkImage('[data-plugin-package="@deepseek-ai/dsh-experimental-agent-team-profile"]', teamIcon, 'Disabled Agent Teams card')
+    try {
+      for (const colorScheme of ['light', 'dark'] as const) {
+        await page.emulateMedia({ colorScheme })
+        expect(await team.locator('img').evaluate((node: HTMLImageElement) => node.naturalWidth)).toBe(36)
+        if (MODE === 'refresh') {
+          const path = fileURLToPath(new URL(`../../../.artifacts/plugin-icons-${process.pid}-${colorScheme}.png`, import.meta.url))
+          await page.screenshot({ path })
+          console.log(`Plugin icon screenshot: ${path}`)
+        }
+      }
+    } finally {
+      await page.emulateMedia({ colorScheme: null })
+    }
+    await panel.getByRole('button', { name: '查看 智能体团队', exact: true }).click()
+    await checkImage('[data-plugin-detail]', teamIcon, 'Agent Teams detail')
+    await panel.getByRole('button', { name: '返回插件列表' }).click()
+    await panel.getByRole('button', { name: '查看 @fixture/bundle', exact: true }).click()
+    await checkImage('[data-plugin-detail]', fixtureIcon, 'Third-party bundle detail')
+    await checkImage('[data-plugin-row="fixture-search"]', fixtureIcon, 'Independent search row')
+    await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'icons.expected.md'), images.join('\n'), MODE)
+    await panel.getByRole('button', { name: '返回插件列表' }).click()
+    expect(tripwire.pageErrors).toEqual([])
+  })
+
   it('localizes independent exports and falls back per field without activating the plugins', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-plugin-manager-exports'))
     const panel = await openPluginsPanel()
@@ -331,7 +375,7 @@ describe('web e2e: plugin manager', () => {
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
-      'manager.expected.md', 'live-enabled.expected.md', 'missing-bundle.expected.md', 'exports.expected.md', 'exports-en.expected.md',
+      'manager.expected.md', 'live-enabled.expected.md', 'missing-bundle.expected.md', 'exports.expected.md', 'exports-en.expected.md', 'icons.expected.md',
     ])
   })
 })
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index b2b0467564..8c94de4306 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.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/cookbook/adding-a-package.md
-adding-a-package.md: 8c818bc371b4fcd646878ec440dd713f8c116083
-adding-a-package.zh.md: f6a09b411e246c50fcf3f44117c05433b12cbd4c
+adding-a-package.md: 60b5d6e047da5f9cdfab3ab504104a0f29b208f7
+adding-a-package.zh.md: 44a613bcf002009c4c58a34c0f68cab85ef097f3
diff --git a/docs/cookbook/adding-a-package.md b/docs/cookbook/adding-a-package.md
index 8c818bc371..60b5d6e047 100644
--- a/docs/cookbook/adding-a-package.md
+++ b/docs/cookbook/adding-a-package.md
@@ -143,7 +143,9 @@ Fields fall back independently before view-specific name formatting, using the e
 - Title: locale `meta.title` → `package.json.name` → complete Cordis plugin name.
 - Description: locale `meta.description` → `package.json.description` → no description.
 
-Export `<package name>/locale/en.json` for locale lookup; expose `<package name>/package.json` when package-field fallback is needed.
+Export `<package name>/locale/en.json` for locale lookup; expose `<package name>/package.json` for package-field fallback or an icon declaration.
+
+For an image on bundle cards, details, and component rows, set top-level `"icon": "./icon.svg"` in that exported manifest and include the image in `files`. The path is relative to the declaring manifest's directory, including for independently exported plugin manifests. SVG, PNG, JPEG (`.jpg`/`.jpeg`), and WebP files are supported up to 256 KiB. Absolute paths, URLs, paths outside that directory, and symlinks resolving outside it are rejected. Images need no separate export and must be self-contained; SVG is rendered as an image, not inline HTML. The Host returns a data URL without activating the plugin. Invalid declarations or unreadable files produce a metadata diagnostic while retaining valid text; missing or undecodable images use the panel's default artwork.
 
 Installed bundle cards and details, component lists and configuration details, and Settings' plugin inventory display this metadata, including disabled and preset plugins. Reads do not activate plugins.
 
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index f6a09b411e..44a613bcf0 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -143,7 +143,9 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - 标题：locale `meta.title` → `package.json.name` → 完整 Cordis 插件名。
 - 描述：locale `meta.description` → `package.json.description` → 不显示描述。
 
-导出 `<包名>/locale/en.json` 供 locale 查询；需要包字段回退时，再开放 `<包名>/package.json`。
+导出 `<包名>/locale/en.json` 供 locale 查询；需要包字段回退或声明图标时，开放 `<包名>/package.json`。
+
+要在组合包卡片、详情和组件行显示图片，在该导出清单顶层设置 `"icon": "./icon.svg"`，并将图片加入 `files`。路径相对于声明清单所在目录，独立导出的插件清单也遵循此规则。支持不超过 256 KiB 的 SVG、PNG、JPEG（`.jpg`/`.jpeg`）和 WebP 文件。绝对路径、URL、目录外路径，以及解析到目录外的符号链接均被拒绝。图片不需要单独导出，且必须自包含；SVG 作为图片渲染，不作为内联 HTML。Host 返回 data URL，不激活插件。声明无效或文件不可读时，显示元信息诊断并保留有效文本；图片缺失或无法解码时使用面板的默认插画。
 
 已安装 bundle 的卡片和详情、组件列表与配置详情、设置中的插件清单都展示这些元信息，包括禁用插件和预设内插件。读取时不激活插件。
 
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index aed223888a..98b11724ed 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
-README.md: 8439fb9ec1173ba24f9775ac476e64d23534a594
-README.zh.md: 0bb8c9819dacabed01905f6b7aff8c770ea3caae
+README.md: 6f24c46485abe3761994ef7aacbea90840e01bfb
+README.zh.md: b3a8aaa2746848bcc347291dad27f015e8a004e3
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index 8439fb9ec1..6f24c46485 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -68,7 +68,7 @@ Before you boot, you can print the exact configuration the app will mount: the d
 
 ### Reading plugin display metadata
 
-Use `readPluginMeta(specifier, parentURL)` or `ctx.pluginPackages.metaOf(specifier, parentURL)` to read installed package display text without importing or activating the plugin. Lookup uses the complete package specifier and the caller's resolution base, respecting Node exports. File paths and file URLs return no metadata without resolving resources. Missing locale fields fall back to the accessible `package.json` at that address; malformed metadata returns an `error` diagnostic. Results retain translations for Client-side language selection. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format.
+Use `readPluginMeta(specifier, parentURL)` or `ctx.pluginPackages.metaOf(specifier, parentURL)` to read installed package display text without importing or activating the plugin. Lookup uses the complete package specifier and the caller's resolution base, respecting Node exports. File paths and file URLs return no metadata without resolving resources. Missing locale fields fall back to the accessible `package.json` at that address; malformed metadata returns an `error` diagnostic. Results retain translations for Client-side language selection. The reader also loads `package.json.icon` as an image data URL, even when locale text is complete; an icon error preserves valid text alongside the diagnostic. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format.
 
 <a id="startup-and-reload-failures"></a>
 ### Startup and reload failures
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 0bb8c9819d..b3a8aaa274 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -68,7 +68,7 @@ profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`head
 
 ### 读取插件展示元信息
 
-使用 `readPluginMeta(specifier, parentURL)` 或 `ctx.pluginPackages.metaOf(specifier, parentURL)` 读取已安装包的展示文本，无需导入或激活插件。查询使用完整包标识与调用方的解析基准，并遵循 Node exports。文件路径与文件 URL 不解析资源，直接返回无元信息。缺失的 locale 字段回退到该地址下可访问的 `package.json`；格式错误的元信息返回 `error` 诊断。结果保留翻译，由 Client 选择语言。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。
+使用 `readPluginMeta(specifier, parentURL)` 或 `ctx.pluginPackages.metaOf(specifier, parentURL)` 读取已安装包的展示文本，无需导入或激活插件。查询使用完整包标识与调用方的解析基准，并遵循 Node exports。文件路径与文件 URL 不解析资源，直接返回无元信息。缺失的 locale 字段回退到该地址下可访问的 `package.json`；格式错误的元信息返回 `error` 诊断。结果保留翻译，由 Client 选择语言。即使 locale 文本完整，读取器也会将 `package.json.icon` 加载为图片 data URL；图标出错时，保留有效文本并附上诊断。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。
 
 <a id="startup-and-reload-failures"></a>
 ### 启动与重载失败
diff --git a/packages/boot/app-boot/src/package-meta.ts b/packages/boot/app-boot/src/package-meta.ts
index 434b233d1e..131082ce8a 100644
--- a/packages/boot/app-boot/src/package-meta.ts
+++ b/packages/boot/app-boot/src/package-meta.ts
@@ -1,7 +1,7 @@
-/** Read plugin display metadata through exported locale resources without evaluating plugin code. */
+/** Read plugin display text and icons through exported resources without evaluating plugin code. */
 
-import { readdirSync, readFileSync } from 'node:fs'
-import { dirname } from 'node:path'
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, extname, isAbsolute, relative, resolve, sep, win32 } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { ModuleLoader } from '@deepseek-ai/cordis-plugin-loader'
 import type { LocalizedText, PluginLocalizedMeta } from '@deepseek-ai/dsh-package-manifest'
@@ -11,6 +11,35 @@ const LANGUAGE_ID = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u
 
 type DisplayFields = Record<'title' | 'description', string | undefined>
 
+/** Maximum raw icon bytes admitted to plugin metadata. */
+const MAX_ICON_BYTES = 256 * 1024
+const ICON_MEDIA_TYPES = new Map([
+  ['.svg', 'image/svg+xml'], ['.png', 'image/png'], ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'], ['.webp', 'image/webp'],
+])
+
+function iconOf(value: unknown, manifestPath: string): string | undefined {
+  const icon = textOf(value, `${manifestPath}: icon`)
+  if (icon === undefined) return undefined
+  if (isAbsolute(icon) || win32.isAbsolute(icon) || /^[A-Za-z][A-Za-z\d+.-]*:/u.test(icon)) {
+    throw new Error(`${manifestPath}: icon must be a relative file path`)
+  }
+  const mediaType = ICON_MEDIA_TYPES.get(extname(icon).toLowerCase())
+  if (mediaType === undefined) throw new Error(`${manifestPath}: icon must be SVG, PNG, JPEG, or WebP`)
+  const directory = realpathSync(dirname(manifestPath))
+  const file = realpathSync(resolve(directory, icon))
+  const local = relative(directory, file)
+  if (local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+    throw new Error(`${manifestPath}: icon must remain inside its manifest directory`)
+  }
+  const stat = statSync(file)
+  if (!stat.isFile()) throw new Error(`${manifestPath}: icon must be a regular file`)
+  if (stat.size > MAX_ICON_BYTES) throw new Error(`${manifestPath}: icon exceeds 256 KiB`)
+  const bytes = readFileSync(file)
+  if (bytes.length > MAX_ICON_BYTES) throw new Error(`${manifestPath}: icon exceeds 256 KiB`)
+  return `data:${mediaType};base64,${bytes.toString('base64')}`
+}
+
 /**
  * Resolve a plugin resource through the active Node ESM resolver without evaluating it.
  * @param specifier - complete resource module specifier, including its locale filename.
@@ -104,7 +133,9 @@ function localizedText(
 }
 
 /**
- * Read meta.title and meta.description from a plugin's exported locale JSON files.
+ * Read localized display text and the icon declared in a plugin's exported package.json.
+ * Icons are manifest-relative SVG, PNG, JPEG, or WebP files of at most 256 KiB,
+ * contained in the manifest directory after realpath resolution. Icon failures retain display text.
  * Non-package specifiers are skipped without invoking the resource resolver.
  * Language files share the directory containing the resolved English resource;
  * each file is resolved through the complete plugin specifier before reading.
@@ -112,25 +143,29 @@ function localizedText(
  * maps retain an English fallback, ultimately the full module specifier for titles and empty for descriptions.
  * @param specifier - configured plugin module name, including any package subpath.
  * @param parentURL - owning Loader tree's module-resolution base.
- * @returns translated or fallback fields, a diagnostic, or undefined for non-package specifiers or absent display text.
+ * @returns display fields and any icon diagnostic, or undefined for non-package specifiers or absent metadata.
  */
 export function readPluginMeta(specifier: string, parentURL: string): PluginLocalizedMeta | undefined {
   if (barePackageName(specifier) === undefined) return undefined
   try {
     const englishPath = optionalResourcePath(`${specifier}/locale/en.json`, parentURL)
     const dictionaries = englishPath === undefined ? new Map<string, DisplayFields>() : dictionariesOf(englishPath, specifier, parentURL)
-    const english = dictionaries.get('en')
-    const manifestPath = english?.title === undefined || english.description === undefined
-      ? optionalResourcePath(`${specifier}/package.json`, parentURL)
-      : undefined
+    const manifestPath = optionalResourcePath(`${specifier}/package.json`, parentURL)
     const manifest = manifestPath === undefined ? undefined : readObject(manifestPath)
     const title = localizedText('title', dictionaries, fallbackText(manifest?.name), specifier)
     const description = localizedText('description', dictionaries, fallbackText(manifest?.description), '')
-    if (title === undefined && description === undefined) return undefined
-    return {
+    const text = {
       ...title === undefined ? {} : { title },
       ...description === undefined ? {} : { description },
     }
+    let icon: string | undefined
+    try {
+      icon = manifestPath === undefined ? undefined : iconOf(manifest?.icon, manifestPath)
+    } catch (error) {
+      return { ...text, error: `Plugin metadata for ${specifier}: ${String(error)}` }
+    }
+    if (title === undefined && description === undefined && icon === undefined) return undefined
+    return { ...text, ...icon === undefined ? {} : { icon } }
   } catch (error) {
     return { error: `Plugin metadata for ${specifier}: ${String(error)}` }
   }
diff --git a/packages/boot/app-boot/tests/package-meta.spec.ts b/packages/boot/app-boot/tests/package-meta.spec.ts
index 07b9af374b..73484f7db9 100644
--- a/packages/boot/app-boot/tests/package-meta.spec.ts
+++ b/packages/boot/app-boot/tests/package-meta.spec.ts
@@ -1,6 +1,6 @@
 /** Plugin locale resources resolve independently of entry execution and package display fields. */
 
-import fs, { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import fs, { mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
 import { syncBuiltinESMExports } from 'node:module'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -161,15 +161,122 @@ describe('plugin locale display metadata', () => {
     expect(readPluginMeta('localized', parentURL)?.error).toContain('meta.title must be a non-empty string')
   })
 
-  it('does not inspect package fallback when both English fields are supplied', () => {
-    manifest({ './locale/*.json': './locale/*.json', './package.json': './fallback.json' })
-    file(join(dir, 'fallback.json'), '{')
+  it('reads the manifest icon even when both English fields are supplied', () => {
+    manifest({ './locale/*.json': './locale/*.json', './package.json': './package.json' }, { icon: './art/team.svg' })
+    file(join(dir, 'art', 'team.svg'), '<svg xmlns="http://www.w3.org/2000/svg"/>')
     dictionary('en', { meta: { title: 'Plugin', description: 'Locale introduction' } })
     expect(readPluginMeta('localized', parentURL)).toEqual({
       title: { en: 'Plugin' }, description: { en: 'Locale introduction' },
+      icon: `data:image/svg+xml;base64,${Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"/>').toString('base64')}`,
     })
   })
 
+  it.each([
+    ['svg', 'image/svg+xml'], ['png', 'image/png'], ['jpg', 'image/jpeg'],
+    ['jpeg', 'image/jpeg'], ['webp', 'image/webp'], ['SVG', 'image/svg+xml'],
+  ])('encodes a package-local %s icon without executing the plugin', (extension, mediaType) => {
+    manifest({ '.': './index.js', './package.json': './package.json' }, { icon: `./icon.${extension}` })
+    const bytes = Buffer.from([0, 1, 127, 128, 255])
+    writeFileSync(join(dir, `icon.${extension}`), bytes)
+    expect(readPluginMeta('localized', parentURL)).toEqual({
+      title: 'localized', icon: `data:${mediaType};base64,${bytes.toString('base64')}`,
+    })
+  })
+
+  it('reads an icon-only subexport relative to its own manifest without inheriting the package icon', () => {
+    manifest({ './package.json': './package.json', './search/package.json': './search/manifest.json' }, { icon: './root.png' })
+    file(join(dir, 'root.png'), 'root')
+    file(join(dir, 'search', 'manifest.json'), JSON.stringify({ icon: './icon.webp' }))
+    file(join(dir, 'search', 'icon.webp'), 'search')
+    expect(readPluginMeta('localized/search', parentURL)).toEqual({
+      icon: `data:image/webp;base64,${Buffer.from('search').toString('base64')}`,
+    })
+    expect(readPluginMeta('localized/review', parentURL)).toBeUndefined()
+  })
+
+  it.each([null, false, 1, {}, [], '', '  '])('retains localized text while rejecting malformed icon %j', (icon) => {
+    manifest({ './locale/*.json': './locale/*.json', './package.json': './package.json' }, { icon })
+    dictionary('en', { meta: { title: 'Plugin', description: 'Introduction' } })
+    dictionary('zh', { meta: { title: '插件' } })
+    const { error, ...meta } = readPluginMeta('localized', parentURL)!
+    expect(meta).toEqual({ title: { en: 'Plugin', zh: '插件' }, description: { en: 'Introduction' } })
+    expect(error).toContain('icon must be a non-empty string')
+  })
+
+  it.each(['/tmp/icon.svg', 'C:\\icon.png', 'C:icon.png', '\\\\server\\share\\icon.png', 'https://example.test/icon.svg', 'data:image/svg+xml,<svg/>'])('rejects non-relative icon %s', (icon) => {
+    manifest({ './package.json': './package.json' }, { icon, description: 'Introduction' })
+    const { error, ...meta } = readPluginMeta('localized', parentURL)!
+    expect(meta).toEqual({ title: 'localized', description: 'Introduction' })
+    expect(error).toContain('icon must be a relative file path')
+  })
+
+  it.each(['icon.gif', 'icon.html', 'icon', 'icon.svg?query'])('rejects unsupported icon file %s', (icon) => {
+    manifest({ './package.json': './package.json' }, { icon })
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must be SVG, PNG, JPEG, or WebP')
+  })
+
+  it('reports missing files, directories, and paths outside the manifest directory', () => {
+    manifest({ './package.json': './package.json' }, { icon: './missing.svg' })
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('missing.svg')
+    mkdirSync(join(dir, 'missing.svg'))
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must be a regular file')
+    manifest({ './package.json': './package.json' }, { icon: '../localized-other/icon.svg' })
+    file(join(root, 'node_modules', 'localized-other', 'icon.svg'), 'outside')
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must remain inside its manifest directory')
+  })
+
+  it('accepts an icon at the byte limit and rejects one byte more', () => {
+    manifest({ './package.json': './package.json' }, { icon: './icon.png' })
+    const bytes = Buffer.alloc(256 * 1024)
+    writeFileSync(join(dir, 'icon.png'), bytes)
+    expect(readPluginMeta('localized', parentURL)?.icon).toBe(`data:image/png;base64,${bytes.toString('base64')}`)
+    writeFileSync(join(dir, 'icon.png'), Buffer.alloc(bytes.length + 1))
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon exceeds 256 KiB')
+  })
+
+  it('rejects an icon that grows beyond the limit after its size check', () => {
+    manifest({ './package.json': './package.json' }, { icon: './icon.png' })
+    const icon = join(dir, 'icon.png')
+    file(icon, 'small')
+    const original = fs.statSync
+    const stat = vi.spyOn(fs, 'statSync')
+    try {
+      stat.mockImplementation(new Proxy(original, {
+        apply(target, receiver: unknown, args: unknown[]): unknown {
+          const result: unknown = Reflect.apply(target, receiver, args)
+          if (String(args[0]).endsWith(join('localized', 'icon.png'))) writeFileSync(icon, Buffer.alloc(256 * 1024 + 1))
+          return result
+        },
+      }))
+      syncBuiltinESMExports()
+      expect(readPluginMeta('localized', parentURL)?.error).toContain('icon exceeds 256 KiB')
+    } finally {
+      stat.mockRestore()
+      syncBuiltinESMExports()
+    }
+  })
+
+  it('rejects icons reached through an external directory link and accepts internal links', () => {
+    manifest({ './package.json': './package.json' }, { icon: './art/icon.svg' })
+    const outside = join(root, 'outside')
+    file(join(outside, 'icon.svg'), 'outside')
+    const link = join(dir, 'art')
+    symlinkSync(outside, link, 'junction')
+    try {
+      expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must remain inside its manifest directory')
+    } finally {
+      unlinkSync(link)
+    }
+    const inside = join(dir, 'images')
+    file(join(inside, 'icon.svg'), 'inside')
+    symlinkSync(inside, link, 'junction')
+    try {
+      expect(readPluginMeta('localized', parentURL)?.icon).toBe(`data:image/svg+xml;base64,${Buffer.from('inside').toString('base64')}`)
+    } finally {
+      unlinkSync(link)
+    }
+  })
+
   it('keeps separate plugin exports independent even when their JavaScript entries share a directory', () => {
     manifest({
       './search': './lib/search.js', './review': './lib/review.js',
@@ -285,8 +392,9 @@ describe('plugin locale display metadata', () => {
     })
     const specifier = 'localized/locale/en.json'
     expect(resolveSync.mock.calls).toEqual(version === 'v1'
-      ? [[specifier, parentURL, {}], [specifier, parentURL, {}]]
-      : [[parentURL, { specifier, attributes: {} }], [parentURL, { specifier, attributes: {} }]])
+      ? [[specifier, parentURL, {}], [specifier, parentURL, {}], ['localized/package.json', parentURL, {}]]
+      : [[parentURL, { specifier, attributes: {} }], [parentURL, { specifier, attributes: {} }],
+        [parentURL, { specifier: 'localized/package.json', attributes: {} }]])
   })
 
   it('rejects case-equivalent language names in a directory listing', () => {
diff --git a/packages/client/ui-plugin-manager/README.i18n.yaml b/packages/client/ui-plugin-manager/README.i18n.yaml
index dfbe7fcedb..df24d45717 100644
--- a/packages/client/ui-plugin-manager/README.i18n.yaml
+++ b/packages/client/ui-plugin-manager/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-plugin-manager/README.md
-README.md: d7bcd2299d93dab90c8440565ac87112b37c9c10
-README.zh.md: 368058dabc27968b86088c34ee387dc5dd5bd364
+README.md: c04a614668d5afb2e09c1f923ac9be473a4aab5a
+README.zh.md: f0b30c91cb87ce96349d92086673809139956e0a
diff --git a/packages/client/ui-plugin-manager/README.md b/packages/client/ui-plugin-manager/README.md
index d7bcd2299d..c04a614668 100644
--- a/packages/client/ui-plugin-manager/README.md
+++ b/packages/client/ui-plugin-manager/README.md
@@ -27,7 +27,7 @@ Use the **Plugins** entry in the Web sidebar to manage the profile's installed b
 
 Select **Plugins** in the sidebar. The page reads the inventory and the bundles through `api-remotes` when first opened; a Host without a managed profile shows the page as unavailable. **Official** comes first and lists the bundles the installation ships for switching on — off until switched on, without an uninstall, and tagged **Beta** where the feature is one — followed by the official plugins that registered a configuration page; **Installed** lists the bundles the profile holds. Cards are listed by name, so switching a bundle on or off does not move its card. A dependency without a bundle patch is not a plugin and is not listed unless the profile selects it, in which case it carries a problem tag. Global configuration remains in the Settings **Plugins** section.
 
-Installed bundles and their plugin rows display their own title and description in the current UI language on cards and detail pages. Each field falls back from exported locale `meta` to the accessible `package.json` at that plugin address; the final title is the full package or module name, with no package description when both sources omit it. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format. Installation previews still use registry or manifest information.
+Installed bundles and their plugin rows display their own title and description in the current UI language on cards and detail pages. Each field falls back from exported locale `meta` to the accessible `package.json` at that plugin address; the final title is the full package or module name, with no package description when both sources omit it. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format. Bundle cards, details, and component rows display the image declared by their own `package.json.icon`; absent or undecodable images retain the default artwork. Installation previews still use registry or manifest information.
 
 ### Installing a bundle
 
diff --git a/packages/client/ui-plugin-manager/README.zh.md b/packages/client/ui-plugin-manager/README.zh.md
index 368058dabc..f0b30c91cb 100644
--- a/packages/client/ui-plugin-manager/README.zh.md
+++ b/packages/client/ui-plugin-manager/README.zh.md
@@ -27,7 +27,7 @@ kind: "package-reference"
 
 在侧栏选择**插件**。页面首次打开时通过 `api-remotes` 读取清单与组合包；没有受管 profile 的 Host 上页面显示为不可用。**官方**排在前面，列出安装随附、供开启的组合包——开启前保持关闭、没有卸载、属于 beta 功能的带 **Beta** 标签——其后是注册了配置页的官方插件；**已安装**列出 profile 持有的组合包。卡片按名称排序，启停组合包不会挪动它的卡片。没有组合包 patch 的依赖不是插件，除非 profile 选中了它才会带异常标签列出。全局配置仍在设置的**插件**分区中编辑。
 
-已安装的组合包及其插件行在卡片和详情页中，按当前界面语言显示各自的标题与描述。每个字段先读取导出的 locale `meta`，缺失时回退到该插件地址下可访问的 `package.json`；标题最终使用完整包名或模块名，两处都没有描述时不提供包描述。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。安装预览仍使用注册表或 manifest 信息。
+已安装的组合包及其插件行在卡片和详情页中，按当前界面语言显示各自的标题与描述。每个字段先读取导出的 locale `meta`，缺失时回退到该插件地址下可访问的 `package.json`；标题最终使用完整包名或模块名，两处都没有描述时不提供包描述。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。组合包卡片、详情和组件行显示各自 `package.json.icon` 声明的图片；未声明或无法解码时保留默认插画。安装预览仍使用注册表或 manifest 信息。
 
 ### 安装一个组合包
 
diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
index 0975263b24..a5f1da6197 100644
--- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
+++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
@@ -202,6 +202,10 @@
   color: var(--dsw-alias-label-secondary);
 }
 
+.packageImage {
+  object-fit: contain;
+}
+
 .cardMain {
   flex: 1;
   min-width: 0;
diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx
index 5235d53cd0..5ef0212a3c 100644
--- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx
+++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx
@@ -17,7 +17,7 @@ import {
   IconChevronRightOutlineRegular, IconCloseOutlineMedium,
   IconPlusOutlineRegular, IconRefreshOutlineRegular, IconTrashOutlineRegular,
   IconWarningOutlineRegular, Input, Modal,
-  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTeam, PluginArtworkTerminal,
+  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTerminal,
   StateDot, Switch, Tag, TerminalBlock, Toast, useAnchoredPosition, useDismissOnOutsidePointer,
   type IconProps, type StateDotState, type TerminalBlockLabels,
 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -130,21 +130,23 @@ const ITEM_ARTWORK = new Map<string, (props: IconProps) => ReactNode>([
   ['web-search', PluginArtworkSearch],
 ])
 
-/** The artwork of the official bundles with artwork of their own, by package name. */
-const PACKAGE_ARTWORK = new Map<string, (props: IconProps) => ReactNode>([
-  ['@deepseek-ai/dsh-experimental-agent-team-profile', PluginArtworkTeam],
-])
-
 /** An official plugin's card and page artwork; plugins without their own get the default. */
 function itemArtwork(id: string): ReactNode {
   const Artwork = ITEM_ARTWORK.get(id) ?? PluginArtworkDefault
   return <Artwork size={CARD_ARTWORK_SIZE} />
 }
 
-/** A package's card and page artwork; packages without their own get the default. */
-function packageArtwork(name: string): ReactNode {
-  const Artwork = PACKAGE_ARTWORK.get(name) ?? PluginArtworkDefault
-  return <Artwork size={CARD_ARTWORK_SIZE} />
+/** Manifest images remain isolated from the page DOM; a failed decode keeps the position's default artwork. */
+function PackageArtwork({ src, row = false, size = row ? ROW_ARTWORK_SIZE : CARD_ARTWORK_SIZE }: {
+  readonly src: string | undefined
+  readonly row?: boolean
+  readonly size?: number
+}): ReactNode {
+  const [failedSource, setFailedSource] = useState<string>()
+  const Fallback = row ? PluginArtworkSubagent : PluginArtworkDefault
+  return src === undefined || src === failedSource
+    ? <Fallback size={size} />
+    : <img className={css.packageImage} src={src} width={size} height={size} alt="" onError={() => { setFailedSource(src) }} />
 }
 
 /** A row's switch: locked, saying why, when the Host refuses to address the row through the profile patch. */
@@ -234,7 +236,7 @@ function RowsSection({ rows, t, resolveText, toggle, configure }: {
                 {...row.phase === 'failed' ? { 'data-state': 'failed' } : row.enabled ? {} : { 'data-state': 'off' }}
               >
                 <div className={css.rowLine}>
-                  <span className={css.rowIcon} aria-hidden="true"><PluginArtworkSubagent size={ROW_ARTWORK_SIZE} /></span>
+                  <span className={css.rowIcon} aria-hidden="true"><PackageArtwork key={row.meta?.icon} src={row.meta?.icon} row /></span>
                   <div className={css.rowMain}>
                     {configure?.has(row) === true
                       ? (
@@ -367,7 +369,7 @@ function PackageCard({ pkg, t, resolveText, busy, highlighted, onOpen, onSetEnab
         title={title}
         t={t}
         onOpen={onOpen}
-        icon={packageArtwork(pkg.name)}
+        icon={<PackageArtwork key={pkg.meta?.icon} src={pkg.meta?.icon} />}
         tags={(
           <>
             {beta ? <Tag className={css.statusTag} tone="info">{t('statusBeta')}</Tag> : null}
@@ -439,7 +441,7 @@ function RowDetail({ pkg, row, t, resolveText, onBack, renderSlot }: {
   const key = rowConfigKey(pkg.name, row.rowId)
   return (
     <div className={css.detail} data-plugin-row-detail={key}>
-      <DetailTop crumbLabel={t('backToPackage', { name: title })} crumbText={title} onBack={onBack} icon={<PluginArtworkSubagent size={CARD_ARTWORK_SIZE} />} />
+      <DetailTop crumbLabel={t('backToPackage', { name: title })} crumbText={title} onBack={onBack} icon={<PackageArtwork key={row.meta?.icon} src={row.meta?.icon} row size={CARD_ARTWORK_SIZE} />} />
       <div className={css.detailMain}>
         <div className={css.titleRow}>
           <h3 className={css.detailTitle}>{rowTitle}</h3>
@@ -491,7 +493,7 @@ function PackageDetail({
         crumbLabel={t('backToList')}
         crumbText={t('crumbRoot')}
         onBack={onBack}
-        icon={packageArtwork(pkg.name)}
+        icon={<PackageArtwork key={pkg.meta?.icon} src={pkg.meta?.icon} />}
         actions={(
           <div className={css.detailActions}>
             {pkg.installed
diff --git a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
index 2226aa0476..d85336cf1a 100644
--- a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
+++ b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
@@ -285,6 +285,38 @@ describe('PluginManagerPage', () => {
     }
   })
 
+  it('renders manifest icons for arbitrary bundles and rows, with decode fallback and source recovery', () => {
+    const icon = 'data:image/svg+xml;base64,PHN2Zy8+'
+    const updatedIcon = 'data:image/png;base64,cG5n'
+    const bundle = pkg({ meta: { icon }, rows: [row({ meta: { icon } }), row({ entryId: 'plain' as PluginEntryId, rowId: 'plain', moduleName: 'plain' })] })
+    const { set } = renderTab({ packages: [bundle] }, { rows: new Set(['dsh-better-sidebar#sidebar']) })
+    const image = () => document.querySelector<HTMLImageElement>('[data-plugin-package] img, [data-plugin-detail] img')!
+    expect(image().getAttribute('src')).toBe(icon)
+    expect(image().getAttribute('alt')).toBe('')
+    expect(image().width).toBe(36)
+    fireEvent.error(image())
+    expect(document.querySelector('[data-plugin-package] img')).toBeNull()
+    expect(document.querySelector('[data-plugin-package] svg')).not.toBeNull()
+    set({ packages: [{ ...bundle, meta: { icon: updatedIcon } }] })
+    expect(image().getAttribute('src')).toBe(updatedIcon)
+    set({ packages: [bundle] })
+    expect(image().getAttribute('src')).toBe(icon)
+    fireEvent.click(screen.getByRole('button', { name: 'View dsh-better-sidebar' }))
+    expect(image().getAttribute('src')).toBe(icon)
+    const rowImage = document.querySelector<HTMLImageElement>('[data-plugin-row] img')!
+    expect(rowImage.getAttribute('src')).toBe(icon)
+    expect(rowImage.width).toBe(30)
+    expect(document.querySelector('[data-plugin-row="plain"] img')).toBeNull()
+    expect(document.querySelector('[data-plugin-row="plain"] svg')).not.toBeNull()
+    fireEvent.error(rowImage)
+    expect(document.querySelector('[data-plugin-row] img')).toBeNull()
+    expect(document.querySelector('[data-plugin-row] svg')).not.toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: 'Configure dsh-better-sidebar' }))
+    const detailImage = document.querySelector<HTMLImageElement>('[data-plugin-row-detail] img')!
+    expect(detailImage.getAttribute('src')).toBe(icon)
+    expect(detailImage.width).toBe(36)
+  })
+
   it('shows metadata diagnostics without blocking management or displaying legacy descriptions', () => {
     const error = 'locale/zh.json: invalid title'
     const { actions, set, setLanguage } = renderTab({
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index d8df0b30d6..e6884489fc 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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-primitives/README.md
-README.md: 51ad53a79a676f013b61213764479a1247de522c
-README.zh.md: c41d19af1855c8ab1582fa92b956ef283d3466cf
+README.md: f17f80d877a76d61b55b502edb05781f8e05cee4
+README.zh.md: 8540a82389b4dced4e6b6048980f4278ec5722d7
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 51ad53a79a..f17f80d877 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -57,7 +57,7 @@ Check this table before writing a control in a feature package. A plugin cannot
 | `TerminalBlock`, `ReadBlock`, `DiffBlock`, `SearchBlock`, `WebBlock` | The agent-output card matching each tool-result intent. |
 | `icons/*`, `FishLogo`, `BrandWordmark`, `ReferenceIconRegular`/`ReferenceIconMedium`, `LinkIconRegular`/`LinkIconMedium` | Glyphs and brand marks. Use `LinkIconMedium` for 14px clickable-link categories and known-site marks. |
 | `PermissionIconReadOnlyRegular`/`Medium`, `PermissionIconWorkspaceWriteRegular`/`Medium`, `PermissionIconFullAccessRegular`/`Medium` | Permission-mode glyphs for read-only, workspace-write, and full-access choices. |
-| `PluginArtworkTeam`/`Terminal`/`Loop`/`Subagent`/`Search`/`Default` | Fixed-palette 36×36 plugin artwork for the plugin-management surfaces; `Default` marks plugins without artwork of their own. Def ids are per-instance, so the same artwork repeats safely on one page. |
+| `PluginArtworkTerminal`/`Loop`/`Subagent`/`Search`/`Default` | Fixed-palette 36×36 plugin artwork for the plugin-management surfaces; `Default` marks plugins without artwork of their own. Def ids are per-instance, so the same artwork repeats safely on one page. |
 | `FileTypeIcon`, `classifyFileType`, `fileExtension` | A category-colored 28px file or folder glyph and the shared case-insensitive filename mapping behind it. Code and configuration files use detailed full-color technology glyphs; use `LinkIconMedium` for link-leading glyphs and image previews for image content. |
 | `languageForPath`, `CODE_HIGHLIGHT_EXTENSIONS`, `useCodeHighlighter` | The filename grammar selection and lazy line-token highlighter shared by code preview and diff review. |
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index c41d19af18..8540a82389 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -57,7 +57,7 @@ kind: "package-library"
 | `TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock`、`WebBlock` | 与各类工具结果意图对应的 agent 输出卡片。 |
 | `icons/*`、`FishLogo`、`BrandWordmark`、`ReferenceIconRegular`/`ReferenceIconMedium`、`LinkIconRegular`/`LinkIconMedium` | 字形与品牌标识。`LinkIconMedium` 用于 14px 的可点击链接分类及已知站点标记。 |
 | `PermissionIconReadOnlyRegular`/`Medium`、`PermissionIconWorkspaceWriteRegular`/`Medium`、`PermissionIconFullAccessRegular`/`Medium` | 只读、工作区写入与完全访问选项使用的权限模式图形。 |
-| `PluginArtworkTeam`/`Terminal`/`Loop`/`Subagent`/`Search`/`Default` | 插件管理界面使用的固定配色 36×36 插件插画；`Default` 用于没有自有插画的插件。def id 按实例生成，同一插画可在一页中安全重复。 |
+| `PluginArtworkTerminal`/`Loop`/`Subagent`/`Search`/`Default` | 插件管理界面使用的固定配色 36×36 插件插画；`Default` 用于没有自有插画的插件。def id 按实例生成，同一插画可在一页中安全重复。 |
 | `FileTypeIcon`、`classifyFileType`、`fileExtension` | 按类别着色的 28px 文件或文件夹图形，以及它背后共享的不区分大小写文件名映射。代码与配置文件使用细分的全彩技术图形；链接前置图形使用 `LinkIconMedium`，图片内容使用图片预览。 |
 | `languageForPath`、`CODE_HIGHLIGHT_EXTENSIONS`、`useCodeHighlighter` | 代码预览与 diff review 共用的文件名 grammar 选择和惰性逐行 token 高亮。 |
 
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index 2ad31f82b4..d98ad76158 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -83,5 +83,5 @@ export { extractMarkdownPlainText } from './markdown/plain-text.ts'
 export type { MarkdownPlainTextMode, MarkdownPlainTextOptions } from './markdown/plain-text.ts'
 export * from './icons/index.tsx'
 export {
-  PluginArtworkTeam, PluginArtworkTerminal, PluginArtworkLoop, PluginArtworkSubagent, PluginArtworkSearch, PluginArtworkDefault,
+  PluginArtworkTerminal, PluginArtworkLoop, PluginArtworkSubagent, PluginArtworkSearch, PluginArtworkDefault,
 } from './plugin-artwork.tsx'
diff --git a/packages/client/ui-primitives/src/plugin-artwork.tsx b/packages/client/ui-primitives/src/plugin-artwork.tsx
index ec54304d3c..c5a774ca81 100644
--- a/packages/client/ui-primitives/src/plugin-artwork.tsx
+++ b/packages/client/ui-primitives/src/plugin-artwork.tsx
@@ -12,25 +12,6 @@ import type { IconProps } from './icons/props.ts'
  */
 const useArtworkId = (): string => `dsh_plugin_art_${useId().replaceAll(':', '')}`
 
-/** Agent-team plugin artwork (four interlocking quadrants). */
-export const PluginArtworkTeam = ({ size = 36, className }: IconProps) => {
-  const uid = useArtworkId()
-  return (
-    <svg width={size} height={size} className={className} viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
-      <path d="M13.3027 17.1077H9.03125V12.8372H13.3027V17.1077ZM17.5742 12.8372C17.574 15.1958 15.6623 17.1075 13.3037 17.1077V8.56567H17.5742V12.8372Z" fill={`url(#${uid}a)`} />
-      <path d="M18.5229 12.8372V8.56567H22.7944V12.8372H27.0659V17.1077H22.7944C20.4357 17.1077 18.5232 15.1959 18.5229 12.8372Z" fill="#F2AF63" />
-      <path d="M17.5742 26.6072H13.3037V18.0642C15.6625 18.0644 17.5742 19.9769 17.5742 22.3357V26.6072ZM13.3027 22.3357H9.03125V18.0642H13.3027V22.3357Z" fill="#7CB7FF" />
-      <path d="M22.7944 26.6072H18.5229V22.3357C18.5229 19.9768 20.4355 18.0642 22.7944 18.0642H27.0659V22.3357H22.7944V26.6072Z" fill="#45D9E7" />
-      <defs>
-        <linearGradient id={`${uid}a`} x1="16.1247" y1="6.6613" x2="9.03125" y2="19.2206" gradientUnits="userSpaceOnUse">
-          <stop stopColor="#7CB7FF" />
-          <stop offset="1" stopColor="#145AF3" />
-        </linearGradient>
-      </defs>
-    </svg>
-  )
-}
-
 /** Terminal plugin artwork (prompt chevron and cursor bar). */
 export const PluginArtworkTerminal = ({ size = 36, className }: IconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
diff --git a/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx b/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx
index 0df9c9a573..5db7f79cb8 100644
--- a/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx
@@ -2,13 +2,12 @@
 import { cleanup, render } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
 import {
-  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTeam, PluginArtworkTerminal,
+  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTerminal,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 
 afterEach(cleanup)
 
 const artworks = {
-  PluginArtworkTeam,
   PluginArtworkTerminal,
   PluginArtworkLoop,
   PluginArtworkSubagent,
diff --git a/packages/experimental/agent-team-profile/README.i18n.yaml b/packages/experimental/agent-team-profile/README.i18n.yaml
index 12faf98360..9f2ca6ce41 100644
--- a/packages/experimental/agent-team-profile/README.i18n.yaml
+++ b/packages/experimental/agent-team-profile/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/experimental/agent-team-profile/README.md
-README.md: 2d94b4d1c0e7de9079ac28945f1e79594b17bb76
-README.zh.md: b1126a266c472d5548b0adbc4139d701ac5b4f6f
+README.md: 053f44b673552e7bb7d63ed944652ea6fb87145a
+README.zh.md: bd6837339298fc13908e077833f75aa9c3a6696e
diff --git a/packages/experimental/agent-team-profile/README.md b/packages/experimental/agent-team-profile/README.md
index 2d94b4d1c0..053f44b673 100644
--- a/packages/experimental/agent-team-profile/README.md
+++ b/packages/experimental/agent-team-profile/README.md
@@ -48,7 +48,7 @@ In an existing profile’s `package.json`, keep `@deepseek-ai/dsh-experimental-a
 
 The layer adds the Agent Teams domain and its scoped creation, roster, messaging, interruption, waiting, and task-board tools. Direct delegation uses `spawn_teammate`, which supports fresh and fork context. The `subagent` and `subagent_fork` tools and overlapping global child controls are disabled. Workflow retains the base profile’s `spawn` provider, while the underlying Subagent services and both providers remain available to teammates and workflow.
 
-In Web and Desktop conversations, the [Team UI](../client-ui-agent-team/README.md) displays the member roster and shared task board and opens teammate sessions. The same bundle switch controls the tools and browser UI.
+In Web and Desktop conversations, the [Team UI](../client-ui-agent-team/README.md) displays the member roster and shared task board and opens teammate sessions. The same bundle switch controls the tools and browser UI. The Plugins page reads the bundle's [icon](icon.svg) from its `package.json.icon` declaration, including while the bundle is disabled.
 
 -----
 
diff --git a/packages/experimental/agent-team-profile/README.zh.md b/packages/experimental/agent-team-profile/README.zh.md
index b1126a266c..bd68373392 100644
--- a/packages/experimental/agent-team-profile/README.zh.md
+++ b/packages/experimental/agent-team-profile/README.zh.md
@@ -48,7 +48,7 @@ dsh plugin --profile web add @deepseek-ai/dsh-experimental-agent-team-profile
 
 本层会添加 Agent Teams domain，以及 Team-scoped 创建、roster、消息、interrupt、等待与任务板工具。直接委派使用支持 fresh 和 fork 上下文的 `spawn_teammate`。`subagent`、`subagent_fork` 工具和名称重叠的全局 child control 均被禁用。Workflow 保留 base profile 的 `spawn` 提供方，底层 Subagent 服务和两个提供方仍供 teammate 与 workflow 使用。
 
-在 Web 和 Desktop 会话中，[Team UI](../client-ui-agent-team/README.zh.md) 显示成员列表与共享任务看板，并可打开成员会话。同一个组合包开关控制工具与浏览器 UI。
+在 Web 和 Desktop 会话中，[Team UI](../client-ui-agent-team/README.zh.md) 显示成员列表与共享任务看板，并可打开成员会话。同一个组合包开关控制工具与浏览器 UI。插件页通过组合包的 `package.json.icon` 声明读取其[图标](icon.svg)，组合包禁用时也会显示。
 
 -----
 
diff --git a/packages/experimental/agent-team-profile/icon.svg b/packages/experimental/agent-team-profile/icon.svg
new file mode 100644
index 0000000000..488848231e
--- /dev/null
+++ b/packages/experimental/agent-team-profile/icon.svg
@@ -0,0 +1,12 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M13.3027 17.1077H9.03125V12.8372H13.3027V17.1077ZM17.5742 12.8372C17.574 15.1958 15.6623 17.1075 13.3037 17.1077V8.56567H17.5742V12.8372Z" fill="url(#a)" />
+  <path d="M18.5229 12.8372V8.56567H22.7944V12.8372H27.0659V17.1077H22.7944C20.4357 17.1077 18.5232 15.1959 18.5229 12.8372Z" fill="#F2AF63" />
+  <path d="M17.5742 26.6072H13.3037V18.0642C15.6625 18.0644 17.5742 19.9769 17.5742 22.3357V26.6072ZM13.3027 22.3357H9.03125V18.0642H13.3027V22.3357Z" fill="#7CB7FF" />
+  <path d="M22.7944 26.6072H18.5229V22.3357C18.5229 19.9768 20.4355 18.0642 22.7944 18.0642H27.0659V22.3357H22.7944V26.6072Z" fill="#45D9E7" />
+  <defs>
+    <linearGradient id="a" x1="16.1247" y1="6.6613" x2="9.03125" y2="19.2206" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#7CB7FF" />
+      <stop offset="1" stop-color="#145AF3" />
+    </linearGradient>
+  </defs>
+</svg>
diff --git a/packages/experimental/agent-team-profile/package.json b/packages/experimental/agent-team-profile/package.json
index 73999ee5d4..fcc06fcf37 100644
--- a/packages/experimental/agent-team-profile/package.json
+++ b/packages/experimental/agent-team-profile/package.json
@@ -2,6 +2,7 @@
   "name": "@deepseek-ai/dsh-experimental-agent-team-profile",
   "description": "Agent Teams collaboration, tools, and Web UI in one experimental bundle",
   "version": "0.1.6-alpha.2",
+  "icon": "./icon.svg",
   "publishConfig": {
     "access": "public"
   },
@@ -24,6 +25,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "icon.svg",
     "locale/*.json",
     "lib/index.js",
     "cordis.patch.yml",
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index bcaa7cde77..69e75dd00b 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -5365,7 +5365,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'PluginLocalizedMeta',
-    declaration: 'export interface PluginLocalizedMeta {\n    readonly title?: LocalizedText;\n    readonly description?: LocalizedText;\n    readonly error?: string;\n}',
+    declaration: 'export interface PluginLocalizedMeta {\n    readonly title?: LocalizedText;\n    readonly description?: LocalizedText;\n    readonly icon?: string;\n    readonly error?: string;\n}',
   },
   {
     name: 'PluginRegistries',
diff --git a/packages/util/package-manifest/README.i18n.yaml b/packages/util/package-manifest/README.i18n.yaml
index dee2ad6293..6aa6fb0107 100644
--- a/packages/util/package-manifest/README.i18n.yaml
+++ b/packages/util/package-manifest/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/package-manifest/README.md
-README.md: 86121432ba12329e111f2c796679ae019e403d7e
-README.zh.md: d4d9d8b5b7787ac9531918fb1f7084c7c8a7a8d1
+README.md: 95dbbb729792872a9d41716db4fb4f2e8ac763b5
+README.zh.md: 02c21647f085af09472cca9f8c2e1a06be4e1124
diff --git a/packages/util/package-manifest/README.md b/packages/util/package-manifest/README.md
index 86121432ba..95dbbb7297 100644
--- a/packages/util/package-manifest/README.md
+++ b/packages/util/package-manifest/README.md
@@ -52,7 +52,7 @@ The following metadata fields are optional. Omitting them leaves the format vers
 | `dsh.manifestVersion` | Manifest format identifier; the declared format is `1`, independent of the npm package version and Session format version. |
 | `engines.dsh` | Author-declared compatible DSH versions as a SemVer range, including exact prerelease versions. This field sits beside `engines.node` and `engines.npm`; an engines object may omit `dsh`. |
 
-`LocalizedText` carries literal text or a language map with a required English fallback. `PluginLocalizedMeta` carries optional display title and description fields, or a metadata diagnostic, for installed plugins. [App boot](../../boot/app-boot/README.md) reads these values; this package only supplies their types.
+`LocalizedText` carries literal text or a language map with a required English fallback. `PluginLocalizedMeta` carries optional display title, description, an image data URL resolved from `package.json.icon`, and metadata diagnostics for installed plugins. [App boot](../../boot/app-boot/README.md) reads these values; this package only supplies their types.
 
 Public composition declarations are defined in [`src/types.ts`](src/types.ts). Internal `configTrees`, `sessionFormatMigration`, and generated `moduleFallback` metadata remain owned by their image-packer, catalog, and launcher readers; the public types do not expose them.
 
diff --git a/packages/util/package-manifest/README.zh.md b/packages/util/package-manifest/README.zh.md
index d4d9d8b5b7..02c21647f0 100644
--- a/packages/util/package-manifest/README.zh.md
+++ b/packages/util/package-manifest/README.zh.md
@@ -52,7 +52,7 @@ const manifest: DshPackageManifest = {
 | `dsh.manifestVersion` | manifest（元数据清单）格式标识；声明的格式为 `1`，独立于 npm 包版本和 Session 格式版本。 |
 | `engines.dsh` | 作者声明的兼容 DSH 版本，使用 SemVer 范围，也可填写精确的预发布版本。此字段与 `engines.node`、`engines.npm` 并列；engines 对象可省略 `dsh`。 |
 
-`LocalizedText` 携带字面文本或带必需英文回退值的语言映射。`PluginLocalizedMeta` 携带已安装插件的可选展示标题与描述字段，或元信息诊断。[App boot](../../boot/app-boot/README.zh.md) 读取这些值；本包只提供其类型。
+`LocalizedText` 携带字面文本或带必需英文回退值的语言映射。`PluginLocalizedMeta` 携带已安装插件的可选展示标题、描述、从 `package.json.icon` 解析的图片 data URL，以及元信息诊断。[App boot](../../boot/app-boot/README.zh.md) 读取这些值；本包只提供其类型。
 
 公共组合声明定义在 [`src/types.ts`](src/types.ts) 中。内部 `configTrees`、`sessionFormatMigration` 和生成的 `moduleFallback` 元数据分别由镜像打包器、目录生成器和启动器读取方拥有；公共类型不暴露这些字段。
 
diff --git a/packages/util/package-manifest/src/types.ts b/packages/util/package-manifest/src/types.ts
index d6f161f97e..a028c71b02 100644
--- a/packages/util/package-manifest/src/types.ts
+++ b/packages/util/package-manifest/src/types.ts
@@ -12,6 +12,8 @@ export interface DshPackageManifest {
   version: string
   /** Package summary for discovery and display. */
   description?: string
+  /** SVG, PNG, JPEG, or WebP file relative to this manifest's directory, at most 256 KiB and contained there after realpath resolution. */
+  icon?: string
   /** Prevent npm publication, for example for local profile projects. */
   private?: boolean
   /** Packages installed alongside this package. */
@@ -39,12 +41,14 @@ export interface DshManifest {
 /** Literal text or translations indexed by lowercase language id, with a required English fallback. */
 export type LocalizedText = string | { readonly en: string; readonly [locale: string]: string }
 
-/** Validated plugin display fields or a diagnostic from reading exported locale files. */
+/** Validated plugin display fields and diagnostics from exported locales, manifests, or icon files. */
 export interface PluginLocalizedMeta {
   /** Display title; omission preserves the consumer's technical-name fallback. */
   readonly title?: LocalizedText
   /** Display introduction after locale and package-field fallback. */
   readonly description?: LocalizedText
+  /** Base64 image data URL read from the manifest's icon file; render as an image, not inline markup. */
+  readonly icon?: string
   /** Unmodified local metadata diagnostic; the plugin remains manageable. */
   readonly error?: string
 }
diff --git a/scripts/check-workspace-constraints.spec.ts b/scripts/check-workspace-constraints.spec.ts
index 0a06641c14..7d012f6440 100644
--- a/scripts/check-workspace-constraints.spec.ts
+++ b/scripts/check-workspace-constraints.spec.ts
@@ -164,6 +164,20 @@ describe('dsh family version coherence', () => {
 })
 
 describe('package payload constraints', () => {
+  it.each(['./art/icon.svg', 'art/icon.svg'])('includes declared icon %s in the canonical payload', (icon) => {
+    expect(expectedDshPackageFiles({ icon, exports: { './locale/*.json': './locale/*.json' } })).toEqual([
+      'art/icon.svg', 'locale/*.json', 'lib/index.js', 'lib/types/**/*.d.ts',
+    ])
+  })
+
+  it('accepts the Agent Team icon payload and rejects its omission', () => {
+    const dir = 'packages/experimental/agent-team-profile'
+    const manifest = JSON.parse(readFileSync(new URL(`../${dir}/package.json`, import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
+    expect(checkWorkspaceManifest({ dir, manifest })).toEqual([])
+    expect(checkWorkspaceManifest({ dir, manifest: { ...manifest, files: manifest.files!.filter(file => file !== 'icon.svg') } }))
+      .toEqual([expect.stringContaining('package.json files must be')])
+  })
+
   it.each([
     { exports: { './locale/*.json': './locale/*.json' }, resources: ['locale/*.json'] },
     { exports: { './search/locale/*.json': './resources/search/*.json' }, resources: ['resources/search/*.json'] },
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 2372546421..aeb4415b97 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -90,6 +90,7 @@ export interface PackageManifest {
     | undefined
   >
   files?: string[]
+  icon?: string
   publishConfig?: { access?: string }
   repository?: { type?: string; url?: string; directory?: string }
   peerDependencies?: Record<string, string>
@@ -210,9 +211,9 @@ function sameStringList(actual: readonly string[] | undefined, expected: readonl
 }
 
 /**
- * Compute canonical publication patterns, including explicitly exported locale JSON resources.
+ * Compute canonical publication patterns, including the declared icon and exported locale JSON resources.
  * @param manifest - workspace package manifest.
- * @returns deduplicated locale targets followed by the package's runtime and declaration payloads.
+ * @returns the icon and deduplicated locale targets followed by runtime and declaration payloads.
  */
 export function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
   const localeFiles = new Set<string>()
@@ -228,6 +229,7 @@ export function expectedDshPackageFiles(manifest: PackageManifest): readonly str
     ...(manifest.name ? packageFileExtras[manifest.name] ?? [] : []),
   ]
   return [
+    ...typeof manifest.icon === 'string' ? [manifest.icon.replace(/^\.\//u, '')] : [],
     ...[...localeFiles].sort(),
     'lib/index.js',
     // Packages with an invariant export publish its runtime as a separate
diff --git a/scripts/verify-package-meta.spec.ts b/scripts/verify-package-meta.spec.ts
index fbdd05daf8..ac82e7e511 100644
--- a/scripts/verify-package-meta.spec.ts
+++ b/scripts/verify-package-meta.spec.ts
@@ -44,6 +44,57 @@ it('does not require locale resources for exported package name and description'
   expect(packageMetaProblems(root)).toEqual([])
 })
 
+it.each([undefined, ['art'], ['art/*.svg'], ['./art/icon.svg']])('accepts a published package icon without locale resources: %j', (files) => {
+  manifest({ icon: './art/icon.svg', files })
+  file('art/icon.svg', '<svg/>')
+  expect(packageMetaProblems(root)).toEqual([])
+})
+
+it.each([{ files: ['lib'] }, { files: ['art', '!art/icon.svg'] }])('rejects an icon omitted from package publication: %j', ({ files }) => {
+  manifest({ icon: './art/icon.svg', files })
+  file('art/icon.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('files must include art/icon.svg')
+})
+
+it.each([null, false, 1, '', './icon.gif', '/tmp/icon.svg', './missing.png', '../outside.svg'])('validates icon declarations without locale resources: %j', (icon) => {
+  manifest({ icon })
+  file('../outside.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('Plugin metadata for @test/plugin:')
+})
+
+it('requires the root icon declaration to be exported', () => {
+  manifest({ icon: './icon.svg', exports: { '.': './entry.js' }, files: ['icon.svg'] })
+  file('icon.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('exports must expose its icon declaration through @test/plugin/package.json')
+})
+
+it.each([
+  { './search/package.json': './resources/search/manifest.json' },
+  { './*/package.json': './resources/*/manifest.json' },
+  { './*': './resources/*' },
+])('validates icons of independent exported manifests: %j', (exports) => {
+  manifest({ exports, files: ['resources'] })
+  const document = './*' in exports ? 'resources/search/package.json' : 'resources/search/manifest.json'
+  json(document, { icon: './icon.webp' })
+  file('resources/search/icon.webp', 'webp')
+  expect(packageMetaProblems(root)).toEqual([])
+  json(document, { icon: './missing.png' })
+  expect(packageMetaProblems(root).join('\n')).toContain('missing.png')
+})
+
+it('requires publication of both an exported icon manifest and its image', () => {
+  manifest({ exports: { './search/package.json': './resources/search.json' }, files: ['resources/icon.svg'] })
+  json('resources/search.json', { icon: './icon.svg' })
+  file('resources/icon.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('files must include resources/search.json')
+})
+
+it('ignores icon-like fields in unrelated source JSON', () => {
+  manifest()
+  json('data.json', { icon: false })
+  expect(packageMetaProblems(root)).toEqual([])
+})
+
 it('excludes tests, installed dependencies, and build output from metadata discovery', () => {
   manifest({ exports: { '.': './lib/index.js' }, files: ['lib'] })
   json('tests/fixtures/locale/en.json', { meta: { title: false } })
@@ -91,6 +142,30 @@ it.each(['en', 'zh'])('rejects %s metadata resolved into build output without re
   expect(problems).not.toContain('Plugin metadata for')
 })
 
+it('does not read built locale JSON while checking a source icon declaration', () => {
+  manifest({
+    icon: './icon.svg', files: ['icon.svg'],
+    exports: { './package.json': './package.json', './locale/en.json': './lib/locale/en.json' },
+  })
+  file('icon.svg', '<svg/>')
+  file('lib/locale/en.json', '{')
+  json('locale/en.json', { meta: { title: 'Plugin' } })
+  const problems = packageMetaProblems(root).join('\n')
+  expect(problems).toContain('exports must expose locale/en.json')
+  expect(problems).not.toContain('Plugin metadata for')
+})
+
+it.each(['lib', 'tests'])('rejects an icon declaration when its only locale is excluded source: %s', (directory) => {
+  manifest({
+    icon: './missing.svg', files: ['lib'],
+    exports: { './package.json': './package.json', './locale/en.json': `./${directory}/locale/en.json` },
+  })
+  file(`${directory}/locale/en.json`, '{}')
+  const problems = packageMetaProblems(root).join('\n')
+  expect(problems).toContain('@test/plugin: icon metadata requires locale resources to resolve to source JSON')
+  expect(problems).not.toContain('Plugin metadata for')
+})
+
 it('reads static metadata without evaluating the plugin entry', () => {
   manifest({ exports: { '.': './entry.js', './locale/*.json': './locale/*.json' } })
   file('entry.js', "import { writeFileSync } from 'node:fs'; writeFileSync(new URL('./executed', import.meta.url), 'yes'); throw new Error('plugin entry executed')")
diff --git a/scripts/verify-package-meta.ts b/scripts/verify-package-meta.ts
index f5a486678f..de5720c6db 100644
--- a/scripts/verify-package-meta.ts
+++ b/scripts/verify-package-meta.ts
@@ -9,12 +9,14 @@ interface Manifest {
   name: string
   exports?: unknown
   files?: string[]
+  icon?: unknown
 }
 
 interface SourceJson {
   file: string
   metadata: boolean
   invalid: boolean
+  icon?: unknown
 }
 
 function sourceJsonFiles(dir: string): SourceJson[] {
@@ -29,7 +31,7 @@ function sourceJsonFiles(dir: string): SourceJson[] {
     if (typeof contents !== 'object' || contents === null || Array.isArray(contents)) {
       return { file, metadata: false, invalid: true }
     }
-    return { file, metadata: Object.hasOwn(contents, 'meta'), invalid: false }
+    return { file, metadata: Object.hasOwn(contents, 'meta'), invalid: false, icon: 'icon' in contents ? contents.icon : undefined }
   })
 }
 
@@ -77,7 +79,10 @@ function packageProblems(manifestPath: string): string[] {
   const exported = typeof pkg.exports === 'object' && pkg.exports !== null ? Object.entries(pkg.exports) : []
   for (const [key, target] of exported) {
     if (!key.startsWith('.')) continue
-    if (!key.includes('*')) candidates.add(key)
+    if (!key.includes('*')) {
+      candidates.add(key)
+      if (key.endsWith('/package.json')) candidates.add(key.slice(0, -'/package.json'.length))
+    }
     const plugin = pluginOf(key)
     if (plugin !== undefined && !plugin.includes('*')) candidates.add(plugin)
     for (const pattern of targetsOf(target)) {
@@ -85,6 +90,7 @@ function packageProblems(manifestPath: string): string[] {
         const value = substitution(pattern, `./${document.file}`)
         if (value === undefined) continue
         const request = key.replaceAll('*', value)
+        if (request.endsWith('/package.json')) candidates.add(request.slice(0, -'/package.json'.length))
         const owner = pluginOf(request)
         if (owner === undefined) continue
         candidates.add(owner)
@@ -116,6 +122,26 @@ function packageProblems(manifestPath: string): string[] {
       const file = lookup(resourceOf(filename))
       return file === undefined ? [] : [{ filename, file }]
     })
+    const iconManifest = lookup(`${specifier}/package.json`)
+    const iconDocument = iconManifest === undefined ? undefined : byPath.get(iconManifest)
+    let iconChecked = false
+    if (candidate === '.' && pkg.icon !== undefined && iconManifest !== join(dir, 'package.json')) {
+      problems.push(`${manifestPath}: exports must expose its icon declaration through ${pkg.name}/package.json`)
+    }
+    if (iconDocument?.icon !== undefined && resources.every(({ file }) => byPath.has(file))) {
+      iconChecked = true
+      const meta = readPluginMeta(specifier, parentURL)
+      if (meta?.error !== undefined) problems.push(meta.error)
+      if (meta?.icon !== undefined && typeof iconDocument.icon === 'string') {
+        const iconFile = relative(dir, resolve(dirname(join(dir, iconDocument.file)), iconDocument.icon)).replaceAll('\\', '/')
+        if (pkg.files !== undefined && !published(iconFile, pkg.files)) problems.push(`${manifestPath}: files must include ${iconFile}`)
+        if (iconDocument.file !== 'package.json' && pkg.files !== undefined && !published(iconDocument.file, pkg.files)) {
+          problems.push(`${manifestPath}: files must include ${iconDocument.file}`)
+        }
+      }
+    } else if (iconDocument?.icon !== undefined) {
+      problems.push(`${specifier}: icon metadata requires locale resources to resolve to source JSON`)
+    }
     if (!resources.some(({ file }) => byPath.get(file)?.metadata || byPath.get(file)?.invalid)) continue
     for (const { file } of resources) claimed.add(file)
     const english = lookup(resourceOf('en.json'))
@@ -138,7 +164,7 @@ function packageProblems(manifestPath: string): string[] {
         problems.push(`${resourceOf(filename)}: ${file} must share the English locale directory ${directory}`)
       }
     }
-    if (sourceResources) {
+    if (sourceResources && !iconChecked) {
       const meta = readPluginMeta(specifier, parentURL)
       if (meta?.error !== undefined) problems.push(meta.error)
     }