diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.i18n.yaml
index ac38a7465f..233e1ce72a 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.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
-2026-07-26-code-mode-trajectory-waterfall-spans.md: 54449bcf8612a39461a769173d7f60c742f67ad8
-2026-07-26-code-mode-trajectory-waterfall-spans.zh.md: fbfb26c3a62554d60a6cb561ead78e10cd4115cd
+2026-07-26-code-mode-trajectory-waterfall-spans.md: fe4dcc25dbf211cf69e0d33937cf87a7482852e2
+2026-07-26-code-mode-trajectory-waterfall-spans.zh.md: aaae06b1fca1b5587d06aa7704adec421d2b2c27
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.md
index 54449bcf86..fe4dcc25db 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.md
@@ -15,7 +15,7 @@ Trajectory and waterfall still rendered a `run_code` turn as one opaque Tool cel
**Trajectory: `subtool` cells interleaved after their parent Tool cell. Waterfall: real-time sub-lanes under the owning turn row.**
- **Trajectory**: the layout fold takes the snapshot's `codeDispatches` index; after each Tool cell whose `callId` has dispatches (assistant-block calls, orphan results, and running calls alike), it interleaves one `subtool` cell per sub-dispatch in start order — indexes stay sequential across the interleave. A settled sub-call's duration is its start/settle pair (`durationSeconds(sub.time, sub.callTime)`); a running one shows the em dash, exactly the native in-flight convention. The new cell kind wears a `Sub` tag (business tint) and a 28px indent so nesting reads at a glance.
-- **Waterfall**: `deriveSubSpans` folds the dispatch index into per-turn lanes with REAL timing — each parent's dispatch window is first start → last settle, and every lane's offset/width is its fraction of that window, so parallel sub-calls (PR3) visibly overlap. Running lanes extend to the window end at reduced opacity with a null duration. Lanes draw under the owning turn's bar row, scaled into a fixed lane budget.
+- **Waterfall**: `deriveSubSpans` folds the dispatch index into per-turn lanes with REAL timing — each parent's dispatch window is first start → last settle, and every lane's offset/width is its fraction of that window, so parallel sub-calls (PR3) visibly overlap. Each lane carries a `timing` provenance tag: `measured` (pair observed), `running` (settle pending — extends to the window end at reduced opacity), or `unknown` (settle-only replay window, `callTime: null` — drawn hollow and titled "duration unknown", never a fabricated 0 ms). Lanes draw under the owning turn's bar row, scaled into a fixed lane budget.
- Both views read `codeDispatches` through the standard snapshot hook — no new wire data, no new stores; replay renders identically to live by construction.
## Alternatives considered
@@ -28,4 +28,4 @@ Trajectory and waterfall still rendered a `run_code` turn as one opaque Tool cel
## Consequences
-The waterfall carries the first REAL wall-time rendering in the client (turn bars remain node-count stand-ins — the contrast is deliberate and labeled by hover titles). Trajectory cell indexes now count sub-calls, so `#N` totals grow on Code Mode turns. Specs pin the interleave order and durations, the running em-dash arm, window fractions (offsets/widths), the running-lane extension, and the rendered lane under the turn row.
+The waterfall carries the first REAL wall-time rendering in the client (turn bars remain node-count stand-ins — the contrast is deliberate and labeled by hover titles). Trajectory cell indexes now count sub-calls, so `#N` totals grow on Code Mode turns. Specs pin the interleave order and durations, the running em-dash arm, window fractions (offsets/widths), the running-lane extension, the unknown-timing (settle-only) lane, and the rendered lane under the turn row; the built-client Code Mode fixture snapshot additionally pins both tabs' assembled rendering (sub-cells with real +0.8s durations, measured lanes).
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.zh.md
index fbfb26c3a6..aaae06b1fc 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-trajectory-waterfall-spans.zh.md
@@ -15,7 +15,7 @@ trajectory 过去仍把一个 `run_code` 轮次渲染为单个不透明的 Tool
**trajectory：`subtool` 单元格穿插在其父 Tool 单元格之后。waterfall：所属轮次行之下、带真实计时的子泳道（sub-lane）。**
- **trajectory**：布局 fold 接收快照的 `codeDispatches` 索引；凡某个 Tool 单元格的 `callId` 名下存在分发（assistant 块内的调用、孤儿结果与运行中的调用一视同仁），fold 就在该单元格之后按启动顺序为每个子分发穿插一个 `subtool` 单元格，索引在整个穿插序列中保持连续编号。已结算子调用的耗时来自其 start/settle 事件对（`durationSeconds(sub.time, sub.callTime)`）；运行中的子调用则显示破折号，与原生的进行中约定完全一致。新增的单元格类型带有 `Sub` 标签（business 色调）与 28px 缩进，嵌套关系一眼可辨。
-- **waterfall**：`deriveSubSpans` 把分发索引折叠成带真实计时的逐轮次泳道：每个父调用的分发窗口为首个 start → 最后一个 settle，每条泳道的偏移/宽度即其在该窗口中的占比，因此并行的子调用（PR3）会肉眼可见地重叠。运行中的泳道以较低的不透明度延伸至窗口末端，耗时为 null。泳道绘制在所属轮次的条形行之下，并缩放进固定的泳道预算。
+- **waterfall**：`deriveSubSpans` 把分发索引折叠成带真实计时的逐轮次泳道：每个父调用的分发窗口为首个 start → 最后一个 settle，每条泳道的偏移/宽度即其在该窗口中的占比，因此并行的子调用（PR3）会肉眼可见地重叠。每条泳道带有 `timing` 来源标记：`measured`（观察到了成对事件）、`running`（settle 未到 — 以较低不透明度延伸至窗口末端）或 `unknown`（回放窗口只含 settle、`callTime: null` — 画成空心并以「duration unknown」为悬停标题，绝不伪造 0 ms）。泳道绘制在所属轮次的条形行之下，并缩放进固定的泳道预算。
- 两个视图都经由标准的快照 hook 读取 `codeDispatches`：没有新的 wire 数据，也没有新的 store；回放的渲染由构造保证与实时完全一致。
## 曾考虑的替代方案
@@ -28,4 +28,4 @@ trajectory 过去仍把一个 `run_code` 轮次渲染为单个不透明的 Tool
## 后果
-waterfall 承载了 client 中第一处真实的墙钟时间渲染（轮次条仍是节点计数的占位；这一反差是有意为之，并由悬停标题标注）。trajectory 的单元格索引现在会把子调用计入，因此 Code Mode 轮次上的 `#N` 总数会随之增大。spec 锁定穿插顺序与耗时、运行中的破折号分支、窗口占比（偏移/宽度）、运行中泳道的延伸，以及轮次行之下实际渲染出的泳道。
+waterfall 承载了 client 中第一处真实的墙钟时间渲染（轮次条仍是节点计数的占位；这一反差是有意为之，并由悬停标题标注）。trajectory 的单元格索引现在会把子调用计入，因此 Code Mode 轮次上的 `#N` 总数会随之增大。spec 锁定穿插顺序与耗时、运行中的破折号分支、窗口占比（偏移/宽度）、运行中泳道的延伸、unknown 计时（仅 settle）泳道，以及轮次行之下实际渲染出的泳道；构建产物级的 Code Mode fixture 快照另行锁定两个标签页的组装后渲染（带真实 +0.8s 耗时的子单元格、measured 泳道）。
diff --git a/apps/web/tests/code-mode-fixture.snapshot.ts b/apps/web/tests/code-mode-fixture.snapshot.ts
index 5abf8bc6c0..e042e857c0 100644
--- a/apps/web/tests/code-mode-fixture.snapshot.ts
+++ b/apps/web/tests/code-mode-fixture.snapshot.ts
@@ -5,7 +5,8 @@
// the code-variant parent row titled by the model-authored description, its
// three always-visible nested sub-rows (bash through the sample registration,
// read through GenericToolCard, the failing read wearing the error state),
-// the expanded program body, and details-panel resolution of a sub-callId.
+// the expanded program body, details-panel resolution of a sub-callId, and
+// the trajectory/waterfall tabs' sub-call cells and timing lanes.
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-library/react'
@@ -177,3 +178,64 @@ it('expands the code row into the program body and resolves a sub-row through th
}
`)
})
+
+it('trajectory and waterfall surface the run_code sub-calls with real timing', async () => {
+ boot()
+ await openFixtureSession()
+
+ // Switch to the trajectory tab (same slot ring the chat view registers in).
+ fireEvent.click(await screen.findByRole('tab', { name: 'Trajectory' }))
+ await waitFor(() => {
+ expect(document.querySelector('[data-kind="subtool"]')).not.toBeNull()
+ }, { timeout: 10_000 })
+ const subCells = [...document.querySelectorAll('[data-kind="subtool"]')]
+ expect({
+ // Three Sub cells nested under the run_code Tool cell, in dispatch order,
+ // each with a real +N.Ns own-duration off the start/settle pair (the
+ // fixture spaces every event 800ms apart — never the em dash).
+ subCells: subCells.map(cell => visibleText(cell)),
+ }).toMatchInlineSnapshot(`
+ {
+ "subCells": [
+ "#53Subbash · {"command":"ls notes","description":"List notes"}+0.8s",
+ "#54Subread · {"path":"notes/demo.txt"}+0.8s",
+ "#55Subread · {"path":"notes/missing.txt"}+0.8s",
+ ],
+ }
+ `)
+
+ // Waterfall: each sub-call draws a measured lane scaled into the parent
+ // turn's dispatch window.
+ fireEvent.click(screen.getByRole('tab', { name: 'Waterfall' }))
+ await waitFor(() => {
+ expect(document.querySelector('[data-subspan]')).not.toBeNull()
+ }, { timeout: 10_000 })
+ const lanes = [...document.querySelectorAll('[data-subspan]')]
+ expect({
+ lanes: lanes.map(lane => ({
+ label: visibleText(lane.querySelector('[class*="subTag"]') ?? lane),
+ title: lane.querySelector('[data-timing]')?.getAttribute('title'),
+ timing: lane.querySelector('[data-timing]')?.getAttribute('data-timing'),
+ })),
+ }).toMatchInlineSnapshot(`
+ {
+ "lanes": [
+ {
+ "label": "bash",
+ "timing": "measured",
+ "title": "bash · 0.80s",
+ },
+ {
+ "label": "read",
+ "timing": "measured",
+ "title": "read · 0.80s",
+ },
+ {
+ "label": "read",
+ "timing": "measured",
+ "title": "read · 0.80s",
+ },
+ ],
+ }
+ `)
+})
diff --git a/packages/client/ui-trajectory/src/client/WaterfallView.tsx b/packages/client/ui-trajectory/src/client/WaterfallView.tsx
index 09f26a9425..ad81845fb9 100644
--- a/packages/client/ui-trajectory/src/client/WaterfallView.tsx
+++ b/packages/client/ui-trajectory/src/client/WaterfallView.tsx
@@ -55,12 +55,15 @@ export function WaterfallView({ useSession, pxPerNode }: ConvViewProps & Waterfa
{lane.name}
))}
diff --git a/packages/client/ui-trajectory/src/client/spans.ts b/packages/client/ui-trajectory/src/client/spans.ts
index d7c86faa9d..585a336333 100644
--- a/packages/client/ui-trajectory/src/client/spans.ts
+++ b/packages/client/ui-trajectory/src/client/spans.ts
@@ -9,8 +9,14 @@ import type { ConversationNode, ConversationSnapshot } from '@deepseek-ai/dsh-cl
export interface SubSpanLane {
callId: string
name: string
- /** Wall duration in ms; null while running (start seen, settle not). */
+ /** Wall duration in ms; null unless both endpoints were observed (`timing: 'measured'`). */
durationMs: number | null
+ /**
+ * Timing provenance: `measured` = start/settle pair observed; `running` =
+ * start seen, settle pending; `unknown` = settle-only replay window (the
+ * start fell outside), so no duration claim is possible.
+ */
+ timing: 'measured' | 'running' | 'unknown'
/** Start offset as a fraction of the parent turn's dispatch window [0, 1). */
offsetFraction: number
/** Width as a fraction of the window (running lanes extend to the window end). */
@@ -106,6 +112,9 @@ export function deriveSubSpans(
for (const [parent, subs] of codeDispatches) {
if (subs.length === 0) continue
const turn = turnByCall.get(parent) ?? currentTurn
+ // A settle-only entry (callTime null: its start fell outside the replay
+ // window) anchors the window by its settle time — a real observation —
+ // but must never masquerade as a measured zero-duration span.
const starts: number[] = []
const ends: number[] = []
for (const sub of subs) {
@@ -119,12 +128,14 @@ export function deriveSubSpans(
const windowSpan = windowEnd - windowStart
const lanes: SubSpanLane[] = subs.map((sub, i) => {
const settled = 'kind' in sub
+ const timing = settled ? (sub.callTime === null ? 'unknown' as const : 'measured' as const) : 'running' as const
const start = starts[i] ?? windowStart
const end = settled ? sub.time : windowEnd
return {
callId: sub.callId,
name: settled ? sub.call?.name ?? sub.callId : sub.name,
- durationMs: settled ? Math.max(0, sub.time - start) : null,
+ durationMs: timing === 'measured' ? Math.max(0, end - start) : null,
+ timing,
offsetFraction: (start - windowStart) / windowSpan,
widthFraction: Math.max((end - start) / windowSpan, 0.02),
}
diff --git a/packages/client/ui-trajectory/src/client/views.module.css b/packages/client/ui-trajectory/src/client/views.module.css
index 920478b1f0..16a853c441 100644
--- a/packages/client/ui-trajectory/src/client/views.module.css
+++ b/packages/client/ui-trajectory/src/client/views.module.css
@@ -71,6 +71,12 @@
background: var(--dsw-alias-state-business-primary);
}
-.barSub[data-running] {
+.barSub[data-timing='running'] {
opacity: 0.45;
}
+
+/* Settle-only replay entries: no measured span — hollow, not a solid bar. */
+.barSub[data-timing='unknown'] {
+ background: transparent;
+ border: 1px dashed var(--dsw-alias-state-business-primary);
+}
diff --git a/packages/client/ui-trajectory/tests/views.spec.tsx b/packages/client/ui-trajectory/tests/views.spec.tsx
index 8559991889..485db395eb 100644
--- a/packages/client/ui-trajectory/tests/views.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.spec.tsx
@@ -288,7 +288,7 @@ describe('deriveSubSpans (waterfall lanes)', () => {
const turn3 = lanes.get(3)
expect(turn3).toHaveLength(2)
// Window = 6200..8200 (2000ms). bash: 0..0.4; read: 0.4..1.0.
- expect(turn3?.[0]).toMatchObject({ name: 'bash', durationMs: 800, offsetFraction: 0 })
+ expect(turn3?.[0]).toMatchObject({ name: 'bash', durationMs: 800, timing: 'measured', offsetFraction: 0 })
expect(turn3?.[0]?.widthFraction).toBeCloseTo(0.4)
expect(turn3?.[1]).toMatchObject({ name: 'read', durationMs: 1200 })
expect(turn3?.[1]?.offsetFraction).toBeCloseTo(0.4)
@@ -305,11 +305,23 @@ describe('deriveSubSpans (waterfall lanes)', () => {
]]]) as unknown as ConversationSnapshot['codeDispatches']
const lanes = deriveSubSpans(dispatchNodes, codeDispatches)
const running = lanes.get(3)?.find((lane) => lane.name === 'grep')
- expect(running).toMatchObject({ durationMs: null })
+ expect(running).toMatchObject({ durationMs: null, timing: 'running' })
// Extends from its start to the window end.
expect(running!.offsetFraction + running!.widthFraction).toBeCloseTo(1)
})
+ it('a settle-only entry (null callTime) is unknown timing, never a measured 0 ms', () => {
+ const codeDispatches = new Map([['p1', [
+ {
+ kind: 'tool-result', seq: 101, time: 8_000, callId: 'p1:code:1',
+ call: { name: 'bash', argsRaw: '{}' }, callTime: null,
+ content: [], isError: false, callView: null, resultView: null,
+ },
+ ]]]) as unknown as ConversationSnapshot['codeDispatches']
+ const lane = deriveSubSpans(dispatchNodes, codeDispatches).get(3)?.[0]
+ expect(lane).toMatchObject({ durationMs: null, timing: 'unknown' })
+ })
+
it('waterfall renders sub-span lanes under the owning turn row', () => {
const codeDispatches = new Map([['p1', [
{
@@ -333,5 +345,30 @@ describe('deriveSubSpans (waterfall lanes)', () => {
expect(lane).not.toBeNull()
expect(lane!.textContent).toContain('bash')
expect(lane!.querySelector('[title*="1.80s"]')).not.toBeNull()
+ expect(lane!.querySelector('[data-timing="measured"]')).not.toBeNull()
+ })
+
+ it('waterfall labels a settle-only lane as duration unknown', () => {
+ const codeDispatches = new Map([['p1', [
+ {
+ kind: 'tool-result', seq: 101, time: 8_000, callId: 'p1:code:1',
+ call: { name: 'read', argsRaw: '{}' }, callTime: null,
+ content: [], isError: false, callView: null, resultView: null,
+ },
+ ]]]) as unknown as ConversationSnapshot['codeDispatches']
+ const store = createSnapshotStore({
+ nodes: dispatchNodes, partial: null,
+ runningCalls: [] as ConversationSnapshot['runningCalls'], codeDispatches,
+ })
+ const props = {
+ sessionId: SID,
+ useSession: bindSnapshotSelector(store) as unknown as UseSession,
+ useSessions: emptySessions(),
+ useWorkspaces: emptyWorkspaces(),
+ } as unknown as ConvViewProps
+ const view = render(createElement(WaterfallView as FC, props))
+ const bar = view.container.querySelector('[data-timing="unknown"]')
+ expect(bar).not.toBeNull()
+ expect(bar!.getAttribute('title')).toContain('duration unknown')
})
})