diff --git a/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.i18n.yaml
index ddd6d80912..5a918c8cc1 100644
--- a/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.i18n.yaml
@@ -9,8 +9,8 @@
en: ab63c8127d68d294
zh: d3f99489c96ff1d4
/agent-note-open-the-session-when-migration-is-required/decision:
- en: 32627d744a6e7410
- zh: 2836a95ee5390111
+ en: 310ff84cece51901
+ zh: a9a29e3ba30e03a8
/agent-note-open-the-session-when-migration-is-required/alternatives-considered:
en: baea781018a49252
zh: bcc452029bf229fd
diff --git a/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.md b/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.md
index 84b30b6cb4..c452ae85ae 100644
--- a/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.md
+++ b/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.md
@@ -18,7 +18,7 @@ Other fork callers omit that option and allow automatic migration.
The `formatStatus` returned by `stat` carries the migration library's existing classification; `header` remains the current logical format. It describes the stored format, not migration-task progress or prepared in-memory history.
-When migration is required and `subagentCatalog` is absent, Web marks the Session's row “Migration required” and keeps its history-opening actions without descendant expansion or changing its subagent mode. Opening the Session supplies its catalog through history and control projections. Available catalogs remain usable, including empty catalogs. Session-list lineage resolves navigation addresses, not missing catalog membership. Ordinary loading, cancellation, and storage errors do not become this migration branch.
+When migration is required and `subagentCatalog` is absent, Web keeps the Session row's history-opening actions without a format notice, descendant expansion, or changing its subagent mode. Opening the Session supplies its catalog through history and control projections. Available catalogs remain usable, including empty catalogs. Session-list lineage resolves navigation addresses, not missing catalog membership. Ordinary loading, cancellation, and storage errors do not become this migration branch.
Create/adopt, full-text search, and ordinary history opening allow automatic migration.
diff --git a/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.zh.md b/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.zh.md
index 31925f7a9f..e68747a9b6 100644
--- a/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-29-explicit-session-history-preparation.zh.md
@@ -18,7 +18,7 @@ WorkspaceBrowser 行菜单的 fork 请求携带 `allowMigration: false`,由 Ho
`stat` 返回的 `formatStatus` 携带迁移库已有的分类;`header` 仍是当前逻辑格式。它描述存储格式,不描述迁移任务进度或内存准备缓存。
-在需要迁移且缺少 `subagentCatalog` 时,Web 将该会话行标为“需要迁移”,保留打开历史的操作,但不能展开下级,也不改变子会话的 mode。打开会话后,历史与 control 投影提供其目录。已有目录仍可使用,包括空目录。会话列表的谱系用于解析导航地址,不用于补齐缺失的目录成员。普通加载、取消和存储错误不转换成这一迁移分支。
+在需要迁移且缺少 `subagentCatalog` 时,Web 保留该会话行打开历史的操作,不显示格式提示,不展开下级,也不改变子会话的 mode。打开会话后,历史与 control 投影提供其目录。已有目录仍可使用,包括空目录。会话列表的谱系用于解析导航地址,不用于补齐缺失的目录成员。普通加载、取消和存储错误不转换成这一迁移分支。
create/adopt、全文搜索和普通历史打开允许自动迁移。
diff --git a/apps/web/tests/expected/subagent-conversation/migration-required-child.expected.md b/apps/web/tests/expected/subagent-conversation/migration-required-child.expected.md
index b60114ef0f..b86fcda5f5 100644
--- a/apps/web/tests/expected/subagent-conversation/migration-required-child.expected.md
+++ b/apps/web/tests/expected/subagent-conversation/migration-required-child.expected.md
@@ -1,13 +1,13 @@
# Before opening the child
- tree "Subagent sessions":
- - treeitem "historical researcher migration-catalog-child · Migration required · not running" [level=1]:
- - text: historical researcher migration-catalog-child Migration required
+ - treeitem "historical researcher migration-catalog-child · continuable · not running" [level=1]:
+ - text: historical researcher migration-catalog-child
- button "Open historical researcher in sidebar"
# After opening the child
- tree "Subagent sessions":
- - treeitem "historical editor migration-catalog-grandchild · Migration required · not running" [level=1]:
- - text: historical editor migration-catalog-grandchild Migration required
+ - treeitem "historical editor migration-catalog-grandchild · continuable · not running" [level=1]:
+ - text: historical editor migration-catalog-grandchild
- button "Open historical editor in sidebar"
diff --git a/apps/web/tests/forge-panel.e2e.ts b/apps/web/tests/forge-panel.e2e.ts
index f66c449b52..b732d7dea5 100644
--- a/apps/web/tests/forge-panel.e2e.ts
+++ b/apps/web/tests/forge-panel.e2e.ts
@@ -547,10 +547,14 @@ it.skipIf(MODE === 'record')('automatically shows a numbered PR when gh JSON omi
await change.getByText('等待评审 · 1 条未解决讨论', { exact: true }).waitFor()
await compareOrRefreshGolden(join(EXPECTED, 'reference.expected.md'),
await captureStableAria(page, `[data-forge-change="${PULL}"]`, scaffold.workspaceCwd), MODE)
- expect(events.flatMap((event) => {
- const record = pluginRecordOf(event)
- return record?.type === 'plugin:forge-session/binding' ? [record.data] : []
- })).toEqual([{ action: 'reference', url: PULL }])
+ await expect.poll(async () => {
+ await scaffold.ctx.sessionPersistence.flush()
+ const boundEvents = await readPersistedEvents(scaffold, sessionId)
+ return boundEvents.flatMap((event) => {
+ const record = pluginRecordOf(event)
+ return record?.type === 'plugin:forge-session/binding' ? [record.data] : []
+ })
+ }).toEqual([{ action: 'reference', url: PULL }])
const calls = (await readFile(join(project, '.fixture-bin', 'calls.jsonl'), 'utf8')).trim().split('\n').map(line => JSON.parse(line) as string[])
expect(calls).toContainEqual(['pr', 'view', '7', '--repo', 'octo/demo', '--json', 'url'])
expect(tripwire.pageErrors).toEqual([])
diff --git a/apps/web/tests/subagent-conversation.e2e.ts b/apps/web/tests/subagent-conversation.e2e.ts
index 9690154afe..a3345c93bf 100644
--- a/apps/web/tests/subagent-conversation.e2e.ts
+++ b/apps/web/tests/subagent-conversation.e2e.ts
@@ -365,6 +365,61 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
if (failures.length > 1) throw new AggregateError(failures, 'subagent Web teardown failed')
})
+ it('retries a failed cold catalog and discovers descendants without reopening the menu', async () => {
+ onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-unread-catalog'))
+ const reads = apiCalls.filter(path => path === '/api/session/projections').length
+ const observe = vi.spyOn(scaffold.ctx.sessionQuery, 'observeSession')
+ const projections = vi.spyOn(scaffold.ctx.sessionController, 'projections')
+ try {
+ const trigger = page.getByRole('button', { name: '2 subagents', exact: true })
+ await page.locator('[data-composer-input]').first().hover()
+ await trigger.hover()
+ const tree = page.getByRole('tree', { name: 'Subagent sessions' })
+ const child = tree.getByRole('treeitem', { name: new RegExp(LABEL) })
+ await child.waitFor()
+ expect(await child.getAttribute('aria-expanded')).toBeNull()
+ expect(await tree.getByRole('button', { name: /^(Expand|Collapse) /u }).count()).toBe(0)
+ expect(await tree.getByText(/Loading subagents|unknown/u).count()).toBe(0)
+ expect(apiCalls.filter(path => path === '/api/session/projections')).toHaveLength(reads)
+ expect(observe).not.toHaveBeenCalled()
+ const parentUrl = page.url()
+ await page.route('**/api/session/projections', route => route.abort('failed'), { times: 1 })
+ await trigger.click()
+ const retry = tree.getByRole('button', { name: 'Retry', exact: true })
+ await retry.waitFor()
+ expect(await tree.getByRole('button', { name: /^(Expand|Collapse) /u }).count()).toBe(0)
+ expect(apiCalls.filter(path => path === '/api/session/projections')).toHaveLength(reads + 1)
+ expect(projections).not.toHaveBeenCalled()
+ await retry.click()
+ await retry.waitFor({ state: 'detached' })
+ const expand = page.getByRole('button', { name: `Expand ${LABEL} descendants`, exact: true })
+ await expand.waitFor()
+ await expect.poll(() => projections.mock.calls.map(([request]) => request.sessionId)).toEqual([parentId, childId, oneShotId])
+ expect(observe.mock.calls.some(([id]) => id === grandchildId)).toBe(false)
+ const lastRead = page.waitForResponse('**/api/session/projections')
+ await expand.click()
+ await (await lastRead).finished()
+ await expect.poll(() => projections.mock.calls.map(([request]) => request.sessionId))
+ .toEqual([parentId, childId, oneShotId, grandchildId])
+ const grandchild = tree.getByRole('treeitem', { name: new RegExp(NESTED_LABEL) })
+ await grandchild.waitFor()
+ expect(await grandchild.getAttribute('aria-expanded')).toBeNull()
+ await compareOrRefreshGolden(
+ TREE_EXPECTED,
+ await captureStableAria(page, '[role="tree"][aria-label="Subagent sessions"]', scaffold.workspaceCwd), MODE,
+ )
+ expect(page.url()).toBe(parentUrl)
+ expect(scaffold.ctx.agents.get(childId)).toBeUndefined()
+ expect(scaffold.ctx.agents.get(grandchildId)).toBeUndefined()
+ await page.keyboard.press('Escape')
+ await page.locator('[data-subagent-panel]').waitFor({ state: 'detached' })
+ } finally {
+ await page.unroute('**/api/session/projections')
+ observe.mockRestore()
+ projections.mockRestore()
+ }
+ })
+
it('lists direct subagents by label in the reference menu', async () => {
onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-reference-title'))
expect(liveReferenceOptions.some(text => text.includes(LABEL))).toBe(true)
@@ -424,7 +479,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
}
expect(await row.getAttribute('aria-label')).toContain(`${LABEL} ${CHILD_NAME} `)
expect(await row.getByRole('button', { name: /description/u }).count()).toBe(0)
- expect(await row.getByRole('button', { name: `Expand ${LABEL} descendants`, exact: true }).count()).toBe(1)
+ await row.getByRole('button', { name: `Expand ${LABEL} descendants`, exact: true }).waitFor()
expect(await row.getByRole('button', { name: `Open ${LABEL} in sidebar`, exact: true }).count()).toBe(1)
expect(page.url()).toBe(originalUrl)
expect(await page.getByRole('tooltip').count()).toBe(0)
@@ -438,9 +493,34 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
}
})
- it('recovers a current-format cold child catalog cache miss without activating either level', async () => {
+ it('expands locally available cold catalogs without requesting or activating either level', async () => {
onTestFailed(() => saveFailureShot(page, 'screenshots/non-migrating-session-reads/web-e2e-subagent-tree'))
- await page.getByRole('button', { name: '2 subagents' }).hover()
+ const warningStart = tripwire.warnings.length
+ await page.reload({ waitUntil: 'load' })
+ const trigger = page.getByRole('button', { name: '2 subagents', exact: true })
+ await trigger.waitFor()
+ acknowledgeReloadConnectionLoss(tripwire, warningStart)
+ const siblingsRead = page.waitForResponse((response) => {
+ if (!response.url().endsWith('/api/session/projections')) return false
+ const body = response.request().postDataJSON() as { payload: { args: { request: { sessionId: SessionId } } } }
+ return body.payload.args.request.sessionId === oneShotId
+ })
+ await trigger.click()
+ await (await siblingsRead).finished()
+ const expand = page.getByRole('button', { name: `Expand ${LABEL} descendants`, exact: true })
+ await expand.waitFor()
+ const descendantsRead = page.waitForResponse((response) => {
+ if (!response.url().endsWith('/api/session/projections')) return false
+ const body = response.request().postDataJSON() as { payload: { args: { request: { sessionId: SessionId } } } }
+ return body.payload.args.request.sessionId === grandchildId
+ })
+ await expand.click()
+ await (await descendantsRead).finished()
+ await page.keyboard.press('Escape')
+ await page.locator('[data-subagent-panel]').waitFor({ state: 'detached' })
+ const catalogReads = apiCalls.filter(path => path === '/api/session/projections').length
+ await page.locator('[data-composer-input]').first().hover()
+ await trigger.hover()
const catalogTree = page.getByRole('tree', { name: 'Subagent sessions' })
expect(await catalogTree.evaluate((element) => {
const rect = element.getBoundingClientRect()
@@ -453,6 +533,10 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
name: `Expand ${ONE_SHOT_LABEL} descendants`,
})
expect(await oneShotDisclosure.count()).toBe(0)
+ await compareOrRefreshGolden(
+ fileURLToPath(new URL('../../../snapshots/web/subagent-conversation/disclosures.expected.md', import.meta.url)),
+ await captureStableAria(page, '[role="tree"][aria-label="Subagent sessions"]', scaffold.workspaceCwd), MODE,
+ )
const oneShotRow = page.getByRole('treeitem', { name: new RegExp(ONE_SHOT_LABEL) })
expect(await oneShotRow.locator('[data-state="done"]').count()).toBe(1)
expect(await oneShotRow.getByText('~6mo 12d', { exact: true }).count()).toBe(1)
@@ -501,18 +585,13 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
expect(await page.getByText(PARENT_PROMPT, { exact: true }).isVisible()).toBe(true)
expect(await page.locator('[data-sidebar-chat]').count()).toBe(0)
}
- const observe = vi.spyOn(scaffold.ctx.sessionQuery, 'observeSession')
- try {
- const projections = page.waitForResponse(response => new URL(response.url()).pathname === '/api/session/projections')
- await clickDisclosureGutter(3)
- await projections
- await page.getByRole('treeitem', { name: new RegExp(NESTED_LABEL) }).waitFor({ timeout: 15_000 })
- expect(await sectionHeader.count()).toBe(0)
- expect(observe.mock.calls.some(([id]) => id === childId)).toBe(true)
- expect(observe.mock.calls.some(([id]) => id === grandchildId)).toBe(false)
- } finally {
- observe.mockRestore()
- }
+ await clickDisclosureGutter(3)
+ const grandchildRow = page.getByRole('treeitem', { name: new RegExp(NESTED_LABEL) })
+ await grandchildRow.waitFor({ timeout: 15_000 })
+ expect(await catalogTree.getByText('Loading subagents…', { exact: true }).count()).toBe(0)
+ expect(await grandchildRow.getAttribute('aria-expanded')).toBeNull()
+ expect(await grandchildRow.getByRole('button', { name: `Expand ${NESTED_LABEL} descendants` }).count()).toBe(0)
+ expect(await sectionHeader.count()).toBe(0)
await clickDisclosureGutter(26)
await page.getByRole('treeitem', { name: new RegExp(NESTED_LABEL) }).waitFor({ state: 'detached' })
expect(await childRow.getAttribute('aria-expanded')).toBe('false')
@@ -571,6 +650,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
scaffold.workspaceCwd,
)
await compareOrRefreshGolden(TREE_EXPECTED, snapshot, MODE)
+ expect(apiCalls.filter(path => path === '/api/session/projections')).toHaveLength(catalogReads)
await page.getByRole('treeitem', { name: new RegExp(NESTED_LABEL) }).getByText(grandchildId, { exact: true }).click()
await page.getByText(NESTED_PROMPT).waitFor()
const hierarchy = page.getByRole('navigation', { name: 'Session hierarchy' })
@@ -994,10 +1074,9 @@ describe('web e2e: migration-required subagent catalog', () => {
const tree = page.getByRole('tree', { name: 'Subagent sessions' })
const childRow = tree.getByRole('treeitem', { name: new RegExp(childLabel) })
await childRow.waitFor()
- await expect.poll(() => childRow.textContent()).toContain('Migration required')
await expect.poll(() => childRow.getByRole('button', { name: `Expand ${childLabel} descendants`, exact: true }).count()).toBe(0)
expect(await childRow.getAttribute('aria-expanded')).toBeNull()
- expect(await childRow.textContent()).toContain('Migration required')
+ expect(await childRow.textContent()).not.toContain('Migration required')
expect(await childRow.textContent()).not.toContain('unknown mode')
expect(await childRow.getByRole('button', { name: `Open ${childLabel} in sidebar`, exact: true }).isEnabled()).toBe(true)
expect(await tree.getByRole('treeitem').count()).toBe(1)
@@ -1015,7 +1094,7 @@ describe('web e2e: migration-required subagent catalog', () => {
await page.getByRole('button', { name: '1 subagent', exact: true }).hover()
const grandchildRow = tree.getByRole('treeitem', { name: new RegExp(grandchildLabel) })
await grandchildRow.waitFor()
- expect(await grandchildRow.textContent()).toContain('Migration required')
+ expect(await grandchildRow.textContent()).not.toContain('Migration required')
expect(await grandchildRow.getAttribute('aria-expanded')).toBeNull()
expect(await grandchildRow.getByRole('button', { name: `Expand ${grandchildLabel} descendants`, exact: true }).count()).toBe(0)
expect(projections).not.toHaveBeenCalled()
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index 32d15ae638..7381b1f9d5 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/README.i18n.yaml
@@ -15,11 +15,11 @@
en: d152484eb41ac6b4
zh: 09388d293f9be9cb
/deepseek-ai-dsh-client-ui-subagent/use-this-package:
- en: bc1c5164849937a8
- zh: e03adf54d2d5a668
+ en: c7a9485c0cdcd9de
+ zh: 903ad54e44d79eae
/deepseek-ai-dsh-client-ui-subagent/use-this-package/browsing-the-tree:
- en: 5ea28139189887e9
- zh: f5a51f041c39b0fa
+ en: 35e983f0276188d0
+ zh: df588dc1523031da
/deepseek-ai-dsh-client-ui-subagent/use-this-package/continuing-a-conversation:
en: e4ec261d3b122eb5
zh: 320bb2efc93dccdc
@@ -30,8 +30,8 @@
en: c158f12dcaed87b7
zh: e5d315e7b1fb4fa9
/deepseek-ai-dsh-client-ui-subagent/understand-the-implementation/catalog-derivation:
- en: 45772c086f8a55f1
- zh: c80584bf49897b8f
+ en: 3c06acc93d7d4d59
+ zh: b967155aec39df0c
/deepseek-ai-dsh-client-ui-subagent/understand-the-implementation/duration-completion-and-tokens:
en: dcbc58d4cad47fa8
zh: e962a8cbdfd4a914
@@ -57,8 +57,8 @@
en: de2762a99572475f
zh: 9b41107ad14ebf8a
/deepseek-ai-dsh-client-ui-subagent/known-limitations-and-deferred-work:
- en: ee310ff3cd487639
- zh: 23793aa1c28a23af
+ en: ea983111988e4b9b
+ zh: c0ed7a583d2cad52
/deepseek-ai-dsh-client-ui-subagent/known-limitations-and-deferred-work/dev-note:
en: e67f633dc6fe7773
zh: 3bb0c20c93f16f98
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index 764025ddfa..555c6fd2d9 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -25,7 +25,7 @@ Browse local subagent conversations and external tasks from the parent header. L
## Use this package
-The session header uses the session title for ordinary breadcrumbs. Subagent breadcrumbs prefer the original creation description (`entry.label`), then the agent name (`entry.name`), then the Session id. Ordinary and subagent breadcrumb titles both use 14px text with a 20px line height. When the session's direct catalog has entries or a read has failed, the descendant-count trigger renders after the preset label in the header actions band, with no breadcrumb separator. An absent or empty catalog hides the count trigger unless the root Session has an enabled, available Team board with shared tasks or a task-record error. Enabling Team mode alone does not show an empty entry. The trigger opens that direct catalog, uses the total count as its accessible name and the running count as its accessible description, and loads nested catalogs only when their rows expand. Select a local child at any depth to open that child's conversation with its exact `{parentSessionId, childSessionId, mode}` address, or use a noncurrent local row's trailing arrow to open the same address in the right Sidebar, preferring a separate pane when room permits.
+The session header uses the session title for ordinary breadcrumbs. Subagent breadcrumbs prefer the original creation description (`entry.label`), then the agent name (`entry.name`), then the Session id. Ordinary and subagent breadcrumb titles both use 14px text with a 20px line height. When the session's direct catalog has entries or a read has failed, the descendant-count trigger renders after the preset label in the header actions band, with no breadcrumb separator. An absent or empty catalog hides the count trigger unless the root Session has an enabled, available Team board with shared tasks or a task-record error. Enabling Team mode alone does not show an empty entry. The trigger opens that direct catalog, uses the total count as its accessible name and the running count as its accessible description, and discovers the next level on explicit activation. Select a local child at any depth to open that child's conversation with its exact `{parentSessionId, childSessionId, mode}` address, or use a noncurrent local 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/?parent=&mode=` resource and builtin Sidebar tab type. The resource retains the child `SessionReference` directly from its address without refreshing the parent catalog, 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.
@@ -39,7 +39,7 @@ The wide root count trigger shows a 14px Users icon in its 14px slot when no chi
Count, owner, and sidebar-action tooltips appear after 500ms of hover. Hovering a text-visible trigger opens its catalog after 150ms; leaving both trigger and catalog closes it after 120ms. Clicking the descendant-count trigger opens and pins its catalog, or closes an already pinned catalog. The icon-only count trigger does not open on hover, including when a pending hover crosses into the narrow layout. Clicking toggles its pinned menu; ArrowDown opens and pins the menu and focuses its first row. Outside click or Escape dismisses a pinned menu. Clicking moves focus into the panel, where ArrowDown/Home enters the first tree row and ArrowUp/End enters the last; Escape returns focus when it was inside. Breadcrumb-title clicks navigate to the corresponding conversation.
-Rows show the creation description, or an available Session title, above the agent name, which is unique among its siblings. Entries recorded without a name show the Session id in its place. Without either description, the row shows only the name or Session id. Navigation, row identity, and Sidebar addresses always use the Session id. Local rows use compact 4px vertical padding; their clickable content uses 6px horizontal padding and 7px gaps, aligned with shared-task rows while retaining the tree's left offset. A decorative trailing check marks the current conversation and is not an action; other local rows retain the sidebar arrow. Primary titles use 13px text and secondary names use 12px. All rows wrap descriptions and names in full, including on touch screens. 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 text-visible 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 show the creation description, or an available Session title, above the agent name, which is unique among its siblings. Entries recorded without a name show the Session id in its place. Without either description, the row shows only the name or Session id. Navigation, row identity, and Sidebar addresses always use the Session id. Local rows use compact 4px vertical padding; their clickable content uses 6px horizontal padding and 7px gaps, aligned with shared-task rows while retaining the tree's left offset. A decorative trailing check marks the current conversation and is not an action; other local rows retain the sidebar arrow. Primary titles use 13px text and secondary names use 12px. All rows wrap descriptions and names in full, including on touch screens. 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 text-visible 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. Only rows with confirmed children show an expansion arrow. Clicking or keyboard-opening the menu reads its catalog and its direct children; expanding a branch does the same for that branch. Each activation reads direct children sequentially through the existing projection reader, which reuses completed reads and merges in-flight requests. It does not recursively discover deeper descendants. Hover and rendering do not initiate reads. Once started, a level read may finish after the menu closes. Missing catalogs show no expansion arrow or unknown marker; shared projection updates reveal confirmed branches while preserving the agent activity marker. Failed reads keep navigation available and offer Retry.
### Continuing a conversation
@@ -61,11 +61,11 @@ The [subagent runtime](../../subagent/subagent/README.md) owns continuation and
### Catalog derivation
-The header lineage renderer reads `projectionsBySession` through the standard `useSessions` hook. The renderer selects `subagentCatalog` from each Session’s shared values for membership, disclosure, and counts. Activity prefers the unified UI status and falls back to Session summaries; summaries supply titles and usage. Expanding a row reads its target's projections, including ordinary cold history. A list row with `formatStatus: migration-required` displays “Migration required” before expansion and keeps its history-opening actions without descendant expansion or changing its subagent mode; a projection read requiring migration without a catalog supplies the same notice. Opening the Session supplies its catalog through history and control projections. Otherwise, an available catalog remains usable, including an explicit empty catalog. Live projection frames update every loaded level without menu subscriptions or repeated membership queries. Other rows remain expandable while their catalogs are absent, loading, or failed, and become known leaves after ready empty catalogs. External rows are always leaves and do not load child Sessions.
+The header lineage renderer reads `subagentCatalog` only from `projectionsBySession` through the standard `useSessions` hook. The Session object layer merges list-cache hints, explicit reads, and the Host-wide control stream into these shared values; live frames update loaded levels without per-menu subscriptions. Activity prefers the unified UI status and falls back to Session summaries; summaries also supply titles and usage. Rendering and hovering use only local projections and never request missing catalogs. An unread empty menu says “Subagents not loaded”; the loading notice appears only during a request. Missing and explicitly empty catalogs have no expansion arrow; a later shared projection with children makes the arrow available. Failures require explicit retry. Migration-required rows keep their history-opening actions without a format notice or descendant expansion; opening the Session supplies its catalog through history and control projections. External rows are always leaves and do not load child Sessions.
Each header entry declares a footer slot below its tree. Optional UI contributes there within the same scroll container; the catalog owns opening and dismissal. CSS anchors keep the panel attached to its trigger within layout-viewport size limits. Browser zoom and panning move it with the page, so it may extend beyond the visual viewport. Internal scrolling, hover behavior, pinned opening, and focus restoration remain independent.
-Opening a catalog dropdown does not request its root catalog. Child-catalog expansion and failed-read retries call `refreshProjection`; shared projection-value changes update the display automatically.
+Explicit menu activation, branch expansion, and failed-read retries call `prepareCatalog` to read the current catalog and its direct children. Ancestor-title clicks navigate to that Session. The Session object layer deduplicates reads and refreshes previously requested projections after reconnect.
Breadcrumb addresses derive from the Provider-bound Session address, loaded parent catalogs, or already-listed subagent lineage, including never-selected ancestors.
@@ -123,6 +123,8 @@ Append-only. This package never edits earlier request tokens.
These limits define what the catalog can show and what `@` references mean; they are current package constraints.
- **Non-completed inactive outcomes remain grouped** — the catalog distinguishes a latest normal completion from other inactive states, but does not distinguish failure, cancellation, refusal, token exhaustion, or a child with no closed turn; the UI exposes no Activation identity, and stopping is limited to the composer's current-turn Stop for a running continuable child.
+- **Ancestor menus require keyboard activation for uncached branches** — hovering does not read, and clicking the ancestor title navigates. Focus the title and press ArrowDown to prepare that level without leaving the current Session.
+- **Level discovery stops on interruption** — an unexpected read rejection stops later siblings and is logged to the console. A reconnect can interrupt discovery before direct children are read; explicitly reopen the menu to prepare the level again.
- **`@` references remain display-title text** — duplicate or renamed labels are ambiguous, so they intentionally do not acquire continuation semantics.
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index 52d9abc110..056fad6cde 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
## 使用本包
-会话页头的普通面包屑使用会话标题。subagent 面包屑优先使用创建时的原始描述(`entry.label`),其次使用智能体名称(`entry.name`),最后回退到 Session id。普通与 subagent 面包屑标题均使用 14px 文字和 20px 行高。当会话的直接目录有子项或读取失败时,后代数量触发器渲染在页头操作区中预设标签之后,不带任何面包屑分隔符。目录缺席或为空时隐藏数量触发器,除非根 Session 已开启且可用的 Team 任务板有共享任务或任务记录错误。仅开启 Team 模式不会显示空入口。触发器打开该直接目录,以总数作为无障碍名称、运行数作为无障碍描述,并且只在行展开时加载嵌套目录。选择任意深度,即可用该子会话的确切 `{parentSessionId, childSessionId, mode}` 地址打开其对话;也可以使用非当前本地行的行尾箭头在右侧 Sidebar 打开同一地址,并在空间允许时优先使用独立分栏。
+会话页头的普通面包屑使用会话标题。subagent 面包屑优先使用创建时的原始描述(`entry.label`),其次使用智能体名称(`entry.name`),最后回退到 Session id。普通与 subagent 面包屑标题均使用 14px 文字和 20px 行高。当会话的直接目录有子项或读取失败时,后代数量触发器渲染在页头操作区中预设标签之后,不带任何面包屑分隔符。目录缺席或为空时隐藏数量触发器,除非根 Session 已开启且可用的 Team 任务板有共享任务或任务记录错误。仅开启 Team 模式不会显示空入口。触发器打开该直接目录,以总数作为无障碍名称、运行数作为无障碍描述,并在用户显式打开时发现下一层目录。选择任意深度,即可用该子会话的确切 `{parentSessionId, childSessionId, mode}` 地址打开其对话;也可以使用非当前本地行的行尾箭头在右侧 Sidebar 打开同一地址,并在空间允许时优先使用独立分栏。
本包注册 `dsh-resource://subagentchat/session/?parent=&mode=` 资源与 builtin Sidebar tab 类型。资源直接根据地址保留 child 的 `SessionReference`,不刷新 parent 目录,并在 tab 记录关闭时释放 reference。tab 通过 `sidebar.chat.conversation` 渲染共享 `conversation.content` Factory,把局部 View 固定为 Chat,并省略主 Conversation 的 Header 与宽度控制。
@@ -39,7 +39,7 @@ kind: "package-reference"
数量、负责人及侧边栏操作的工具提示在悬停 500ms 后显示。悬停文字可见的触发器 150ms 后打开目录;指针离开触发器和目录后,经过 120ms 关闭。点击后代数量触发器会打开并固定目录,或关闭已固定的目录。纯图标数量触发器不会因悬停而打开,包括等待悬停打开期间切换到窄布局的情况。点击可切换固定菜单的开关状态;ArrowDown 会打开并固定菜单,并将焦点移至首行。点击外部或按 Escape 可关闭已固定的菜单。点击会将焦点移入面板,此时 ArrowDown/Home 进入首个树行,ArrowUp/End 进入最后一个树行;Escape 在焦点原本位于面板内时将其送回。点击面包屑标题会导航至对应会话。
-目录行在智能体名称上方显示创建描述,缺少创建描述时使用可用的 Session title;名称在同级子智能体中唯一。没有名称的历史目录项在相同位置显示 Session id。两者均缺少时,该行仅显示名称或 Session id。导航、行身份与 Sidebar 地址始终使用 Session id。本地行使用紧凑的 4px 垂直内边距;可点击内容使用 6px 水平内边距和 7px 间距,与共享任务行对齐,同时保留树的左侧偏移。当前对话在行尾显示装饰性对勾,该对勾不是操作控件;其他本地行保留侧边栏箭头。主标题使用 13px 文字,次级名称使用 12px。所有行均将描述与名称换行完整展示,包括在触屏上。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。只有一行自身的目录加载为空后,它才是已知叶子。
+目录行在智能体名称上方显示创建描述,缺少创建描述时使用可用的 Session title;名称在同级子智能体中唯一。没有名称的历史目录项在相同位置显示 Session id。两者均缺少时,该行仅显示名称或 Session id。导航、行身份与 Sidebar 地址始终使用 Session id。本地行使用紧凑的 4px 垂直内边距;可点击内容使用 6px 水平内边距和 7px 间距,与共享任务行对齐,同时保留树的左侧偏移。当前对话在行尾显示装饰性对勾,该对勾不是操作控件;其他本地行保留侧边栏箭头。主标题使用 13px 文字,次级名称使用 12px。所有行均将描述与名称换行完整展示,包括在触屏上。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。只有确认存在下级的行才显示展开箭头。点击或通过键盘打开菜单时,读取当前目录及其直属子节点的目录;展开分支时对该分支执行相同操作。每次打开操作通过现有投影读取器依次读取直接子节点,复用已完成的读取并合并进行中的请求,不递归发现更深层后代。悬停与渲染不触发读取。已开始的单层读取可能在菜单关闭后完成。缺少目录的行不显示展开箭头或未知标记;共享投影更新确认存在下级后显示箭头,并保持 agent 活动状态图标。读取失败时保留导航操作并提供重试。
### 续接对话
@@ -61,11 +61,11 @@ kind: "package-reference"
### 目录派生
-页头谱系 renderer 通过标准 `useSessions` 钩子读取 `projectionsBySession`。renderer 从每个 Session 的共享值中选择 `subagentCatalog`,用于成员关系、展开控件与数量。活动状态优先使用统一 UI status,缺少时使用 Session 摘要;摘要提供标题与用量。展开行读取目标投影,包括普通冷历史。列表行的 `formatStatus` 为 `migration-required` 时,行在展开前即显示“需要迁移”,保留打开历史的操作,但不能展开下级,也不改变子会话的 mode;投影读取需要迁移且缺少目录时,也显示同一提示。打开会话后,历史与 control 投影提供其目录。其他情况下,已有目录仍可使用,包括显式空目录。实时 projection 帧更新所有已加载层级,无需菜单订阅或重复成员查询。其他行在目录缺席、加载中或失败时保持可展开,并在目录就绪且为空后成为已知叶子。外部行始终为叶子,不加载子 Session。
+页头谱系 renderer 通过标准 `useSessions` 钩子,仅从 `projectionsBySession` 读取 `subagentCatalog`。Session 对象层将列表缓存提示、显式读取和 Host 全局 control 流合并到这些共享值;实时帧更新已加载层级,无需每个菜单单独订阅。活动状态优先使用统一 UI status,缺少时使用 Session 摘要;摘要还提供标题与用量。渲染与悬停仅使用本地投影,不会请求缺失目录。尚未读取的空菜单显示“尚未加载子智能体”;仅请求进行中显示加载提示。缺失或显式为空的目录没有展开箭头;后续共享投影包含下级时才显示箭头。读取失败后需要显式重试。需要迁移的行保留打开历史的操作,不显示格式提示,也不展开下级;打开 Session 后,历史与 control 投影提供其目录。外部行始终为叶子,不加载子 Session。
每个页头入口在树下方声明 footer 插槽。可选 UI 通过该插槽加入同一滚动容器;目录负责打开和关闭。CSS 锚点让面板跟随触发器,并按布局视口限制尺寸。浏览器缩放和平移时面板随页面移动,因此可以超出视觉视口。内部滚动、悬停行为、点击固定展开和焦点恢复保持独立。
-打开目录下拉菜单不会请求其根目录。展开子节点目录或重试失败读取时调用 `refreshProjection`;共享投影值的变化会自动更新显示。
+显式激活菜单、展开分支或重试失败读取时,`prepareCatalog` 读取当前目录及其直接子节点。点击祖先标题会导航到该 Session。Session 对象层合并重复读取,并在重连后刷新之前请求过的投影。
面包屑地址从 Provider 所绑定的 Session 地址、已加载的 parent 目录或已列出的 subagent 谱系推导,也包括从未选中过的祖先。
@@ -123,6 +123,8 @@ one-shot 和模式未知的 child 选用只读编辑器。可继续 child 经由
这些限制定义目录能显示什么、`@` 引用意味着什么;它们是当前包约束。
- **非完成的 inactive 结果仍合并显示**:目录能区分最近一次正常完成与其他 inactive 状态,但不区分失败、取消、拒绝、token 耗尽或尚无已结束轮次的 child;UI 不公开 Activation 身份,停止能力仅限编辑器上针对运行中可继续 child 的当前轮次 Stop。
+- **祖先菜单的未缓存分支需要键盘激活**:悬停不读取,点击祖先标题会导航。聚焦标题后按 ArrowDown,可在不离开当前 Session 的情况下准备这一层。
+- **单层发现会在中断后停止**:意外的读取拒绝会停止后续兄弟节点,并记录到控制台。重连可能在直接子节点读取前中断发现;需再次显式打开菜单来准备这一层。
- **`@` 引用仍是显示标题文本**:重复或改名后的 label 会有歧义,因此它们刻意不获得继续执行语义。
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
index d3f58ad409..c450098395 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
@@ -350,8 +350,7 @@
}
.label,
-.secondaryLabel,
-.summary {
+.secondaryLabel {
white-space: normal;
overflow-wrap: anywhere;
}
@@ -370,14 +369,10 @@
color: var(--dsw-alias-label-tertiary);
}
-.summary,
.metrics {
color: var(--dsw-alias-label-tertiary);
font-size: 10px;
line-height: 15px;
-}
-
-.metrics {
display: grid;
grid-template-rows: 17px 15px;
flex: none;
@@ -455,10 +450,6 @@
height: 23px;
}
-.children[aria-busy='true']::before {
- content: none;
-}
-
.children > .node::before {
top: 0;
bottom: 0;
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
index 92a802ac66..8cbb5be217 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
@@ -19,7 +19,7 @@ import type {} from './slots.ts'
import css from './SubagentHeaderLineage.module.css'
type SubagentCatalogSnapshot = Omit & {
- state: 'loading' | 'ready' | 'migration-required' | 'error'
+ state: 'idle' | 'loading' | 'ready' | 'migration-required' | 'error'
entries: (SessionProjectionMap['subagentCatalog'][number] & { activity: 'running' | 'inactive' })[]
}
type Catalogs = Readonly>
@@ -29,6 +29,8 @@ export type SubagentCatalogInjected = {
openChild: (address: SubagentAddress) => void
openChildAside: (address: SubagentAddress) => void
refreshProjection: (parentSessionId: SessionId) => void
+ /** Read this catalog and its direct children after explicit activation or retry. */
+ prepareCatalog: (parentSessionId: SessionId) => Promise
}
/** Root catalog actions and availability of its optional footer. */
@@ -203,9 +205,11 @@ function CatalogLoadingRows({ t }: { t: TranslateNS }) {
return
{t('loading.label')}
}
-/** A child becomes a known leaf only after its own authoritative catalog loads empty. */
-function isKnownLeaf(catalog: SubagentCatalogSnapshot | undefined): boolean {
- return catalog?.state === 'ready' && catalog.entries.length === 0
+/** Only confirmed child membership exposes a branch disclosure. */
+function canExpandCatalog(entry: SubagentCatalogSnapshot['entries'][number], catalogs: Catalogs, summaries: CatalogRowsProps['summaries']): boolean {
+ return entry.mode !== 'external' && (catalogs[entry.id]?.entries.length ?? 0) > 0
+ && summaries[entry.id]?.formatStatus !== 'migration-required'
+ && catalogs[entry.id]?.state !== 'migration-required'
}
/** The agent name unique among the row's siblings, or the Session ID for entries recorded without one. */
@@ -252,12 +256,12 @@ function CatalogRows({
return () => { clearInterval(timer) }
}, [running])
const emptyLoading = catalog.state === 'loading' && catalog.entries.length === 0
- const reserveDisclosure = catalog.entries.some(entry =>
- entry.mode !== 'external' && !isKnownLeaf(catalogs[entry.id])
- && summaries[entry.id]?.formatStatus !== 'migration-required'
- && catalogs[entry.id]?.state !== 'migration-required')
+ const reserveDisclosure = catalog.entries.some(entry => canExpandCatalog(entry, catalogs, summaries))
return (
<>
+ {catalog.state === 'idle' && catalog.entries.length === 0 && (
+