fix(web): honor the terminal view's description and resolved workdir

Three review findings, each verified against the presentation contract:

The call view's `description` was dropped, so a presenter that authors one
(`terminal_send` declares `Terminal <id>`) lost the contract's above-card text
and the row fell back to an unrelated args-derived summary. It now rides the
same derivation and outranks that summary.

A relative workdir was concatenated but never normalized, while the bash
executor resolves it before running: with session cwd `/w/app` and workdir
`..` the command runs in `/w`, yet the card displayed the label `..`. The
resolved path now collapses `.`/`..` segments, drops a `..` that would climb
past a root the way a filesystem does, and keeps a Windows path's separators
since the value is only ever displayed.

`run_code` sub-dispatches carry no presenter views on the shipped wire —
`session.ts` folds `tool/code-dispatch(-start)` with null views and the host's
`viewFor` presents only top-level call/result events — so a nested bash call
cannot reach a terminal card. The existing test only passed by injecting views
that path cannot produce; it now says so, and a second arm pins the no-view
shape the wire actually delivers.

Restoring master's fixture also fixed the todo snapshot lane, which my earlier
merge had broken by dropping the projection support the todo dock reads. The
terminal sample turn moved ahead of the todo turn, because the standing plan
retires at the next `turn/start` and a turn appended after it emptied the dock.

The card props are now nested under `card` so a render site spreads exactly the
primitive's own surface, and the fixture reads each sample's authored exit
status instead of re-implementing the bash tool's `parseExitStatus`.

packages/client/ui-conversation/src/client/chat/ToolRow.tsx

@@ -157,7 +157,7 @@ export function ToolRow({
         )}
       </div>
       {open && (terminalBody !== null
-        ? <TerminalBlock {...terminalBody} maxLines={CHAT_TERMINAL_MAX_LINES} className={css.terminalBody} />
+        ? <TerminalBlock {...terminalBody.card} maxLines={CHAT_TERMINAL_MAX_LINES} className={css.terminalBody} />
         : variant === 'code'
           ? <CodeBlock code={text} lang="typescript" className={css.codeBody} />
           : <div className={css.body}>{text}</div>)}

packages/client/ui-conversation/src/client/contract/terminal-card-model.ts

@@ -28,10 +28,21 @@ export const CHAT_TERMINAL_MAX_LINES = 8
  * client has no home path for the session host (a cwd renders as its last
  * path segment), and `maxLines`/`className` belong to each render site.
  */
-export type TerminalCardModel = Pick<
-  TerminalBlockProps,
-  'command' | 'cwd' | 'output' | 'exitCode' | 'signal' | 'running'
->
+export interface TerminalCardModel {
+  /**
+   * The props {@link TerminalBlock} draws. Held as a nested object so a render
+   * site spreads exactly the primitive's own surface and can never leak a
+   * neighbouring field into it.
+   */
+  card: Pick<TerminalBlockProps, 'command' | 'cwd' | 'output' | 'exitCode' | 'signal' | 'running'>
+  /**
+   * The call view's model-authored description, which the contract defines as
+   * rendering ABOVE the card (the card itself has no description slot). Absent
+   * when the presenter supplied none, or when the window dropped the call side;
+   * a row then keeps its args-derived summary.
+   */
+  description: string | undefined
+}
 
 /**
  * Resolve a terminal view's working directory the way the render-intent
@@ -47,8 +58,41 @@ export type TerminalCardModel = Pick<
  */
 function resolveTerminalCwd(viewCwd: string | undefined, sessionCwd: string | undefined): string | undefined {
   if (viewCwd === undefined || viewCwd === '') return sessionCwd
-  if (sessionCwd === undefined || sessionCwd === '') return viewCwd
-  return resolveToolPath(sessionCwd, viewCwd)
+  if (sessionCwd === undefined || sessionCwd === '') return normalizeSegments(viewCwd)
+  return normalizeSegments(resolveToolPath(sessionCwd, viewCwd))
+}
+
+/**
+ * Collapse `.` and `..` segments so the prompt label names the directory the
+ * command actually ran in. The bash executor resolves the workdir before
+ * running, so a joined `/w/app/..` must display as `w`, not as `..`. Separators
+ * are preserved as authored (a Windows path keeps its backslashes) because this
+ * value is only ever displayed; a `..` that would climb past the root is
+ * dropped, which is what a filesystem does with it.
+ * @param path - a joined or absolute path, possibly carrying `.`/`..` segments.
+ * @returns the same path with those segments resolved.
+ */
+function normalizeSegments(path: string): string {
+  if (!/(?:^|[/\\])\.\.?(?:[/\\]|$)/.test(path)) return path
+  const backslashed = path.includes('\\') && !path.includes('/')
+  const separator = backslashed ? '\\' : '/'
+  const leading = /^[/\\]/.test(path) ? separator : ''
+  const drive = /^[A-Za-z]:/.exec(path)?.[0] ?? ''
+  const kept: string[] = []
+  for (const segment of path.slice(drive.length).split(/[/\\]/)) {
+    if (segment === '' || segment === '.') continue
+    if (segment === '..') {
+      // Nothing to climb from: at a root the segment is dropped, matching the
+      // filesystem; on a relative path the `..` has to stay, since it is still
+      // meaningful against a cwd this function cannot see.
+      if (kept.length > 0 && kept[kept.length - 1] !== '..') kept.pop()
+      else if (leading === '' && drive === '') kept.push(segment)
+      continue
+    }
+    kept.push(segment)
+  }
+  const body = kept.join(separator)
+  return drive === '' ? `${leading}${body}` : `${drive}${leading === '' ? separator : leading}${body}`
 }
 
 /**
@@ -82,25 +126,31 @@ export function terminalCardModel(block: ToolCallBlock, sessionCwd?: string): Te
   if (!('kind' in block)) {
     // Running: the call view exists, the result view does not yet.
     return call === null ? null : {
-      command: call.title,
-      cwd: resolveTerminalCwd(call.cwd, sessionCwd),
-      output: undefined,
-      exitCode: undefined,
-      signal: undefined,
-      running: true,
+      description: call.description,
+      card: {
+        command: call.title,
+        cwd: resolveTerminalCwd(call.cwd, sessionCwd),
+        output: undefined,
+        exitCode: undefined,
+        signal: undefined,
+        running: true,
+      },
     }
   }
   const result = block.resultView?.card === 'terminal' ? block.resultView : null
   if (result === null) return null
   return {
-    // The result's title REPLACES the pending one when the tool supplies it
-    // (the presentation contract's replacement-title rule); the call title is
-    // what a result without one keeps.
-    command: result.title ?? call?.title ?? '',
-    cwd: resolveTerminalCwd(call?.cwd, sessionCwd),
-    output: result.output,
-    exitCode: result.exitCode,
-    signal: result.signal,
-    running: false,
+    description: call?.description,
+    card: {
+      // The result's title REPLACES the pending one when the tool supplies it
+      // (the presentation contract's replacement-title rule); the call title is
+      // what a result without one keeps.
+      command: result.title ?? call?.title ?? '',
+      cwd: resolveTerminalCwd(call?.cwd, sessionCwd),
+      output: result.output,
+      exitCode: result.exitCode,
+      signal: result.signal,
+      running: false,
+    },
   }
 }

packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx

@@ -135,7 +135,7 @@ export function DetailsPanel({ useSession, useSessions, sessionId, useStore, clo
  */
 function OutputBody({ material, cwd }: { material: CallMaterial; cwd: string | undefined }) {
   const terminal = terminalCardModel(material.block, cwd)
-  if (terminal !== null) return <TerminalBlock {...terminal} className={css.terminal} />
+  if (terminal !== null) return <TerminalBlock {...terminal.card} className={css.terminal} />
   // A settled call always carries the result node the flattened form needs;
   // the running shape has no result to flatten.
   if (!('kind' in material.block)) return <div className={css.empty}>运行中…</div>

packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx

@@ -64,10 +64,12 @@ export function BashRow({ toolName, block, sessionId, useSessions }: ToolRowProp
         {isChild && <span className={css.scopeBadge}>scoped</span>}
         <span className={css.title}>{model.title}</span>
         <span className={css.sep} aria-hidden />
-        <span className={css.summary}>{model.summary}</span>
+        {/* The terminal presenter's description is the contractual
+            above-card summary; it outranks the args-derived one. */}
+        <span className={css.summary}>{terminal?.description ?? model.summary}</span>
       </div>
       {terminal !== null && (
-        <TerminalBlock {...terminal} maxLines={CHAT_TERMINAL_MAX_LINES} className={css.terminal} />
+        <TerminalBlock {...terminal.card} maxLines={CHAT_TERMINAL_MAX_LINES} className={css.terminal} />
       )}
     </div>
   )

packages/client/ui-conversation/tests/terminal-card.spec.tsx

@@ -63,8 +63,11 @@ const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
 describe('terminalCardModel', () => {
   it('derives a running card from the call view alone', () => {
     expect(terminalCardModel(running({ callView: callTerminal({ cwd: '/projects/app' }) }))).toEqual({
-      command: 'ls -la', cwd: '/projects/app', output: undefined,
-      exitCode: undefined, signal: undefined, running: true,
+      description: 'List files',
+      card: {
+        command: 'ls -la', cwd: '/projects/app', output: undefined,
+        exitCode: undefined, signal: undefined, running: true,
+      },
     })
   })
 
@@ -73,12 +76,15 @@ describe('terminalCardModel', () => {
       callView: callTerminal({ cwd: '/projects/app' }),
       resultView: resultTerminal({ output: 'boom\n', exitCode: 2 }),
     }))).toEqual({
-      command: 'ls -la', cwd: '/projects/app', output: 'boom\n',
-      exitCode: 2, signal: undefined, running: false,
+      description: 'List files',
+      card: {
+        command: 'ls -la', cwd: '/projects/app', output: 'boom\n',
+        exitCode: 2, signal: undefined, running: false,
+      },
     })
     expect(terminalCardModel(settled({
       resultView: { card: 'terminal', output: '', signal: 'SIGTERM' },
-    }))?.signal).toBe('SIGTERM')
+    }))?.card.signal).toBe('SIGTERM')
   })
 
   it('takes the result view\'s replacement title over the pending one', () => {
@@ -87,30 +93,75 @@ describe('terminalCardModel', () => {
     expect(terminalCardModel(settled({
       callView: callTerminal({ title: 'pnpm run check' }),
       resultView: resultTerminal({ title: 'pnpm run check --filter web' }),
-    }))?.command).toBe('pnpm run check --filter web')
+    }))?.card.command).toBe('pnpm run check --filter web')
     // Without one, the call's title is what the card keeps.
-    expect(terminalCardModel(settled())?.command).toBe('ls -la')
+    expect(terminalCardModel(settled())?.card.command).toBe('ls -la')
   })
 
   it('resolves the cwd against the session workspace the way the bridge must', () => {
     // Omitted workdir — the common bash call — IS the session workspace.
-    expect(terminalCardModel(settled(), '/w/app')?.cwd).toBe('/w/app')
+    expect(terminalCardModel(settled(), '/w/app')?.card.cwd).toBe('/w/app')
     // A relative workdir joins under it.
     expect(terminalCardModel(settled({
       callView: callTerminal({ cwd: 'packages/ui' }),
-    }), '/w/app')?.cwd).toBe('/w/app/packages/ui')
+    }), '/w/app')?.card.cwd).toBe('/w/app/packages/ui')
     // An absolute one is used as-is.
     expect(terminalCardModel(settled({
       callView: callTerminal({ cwd: '/srv/other' }),
-    }), '/w/app')?.cwd).toBe('/srv/other')
+    }), '/w/app')?.card.cwd).toBe('/srv/other')
     // With no session cwd there is nothing to resolve against: a relative path
     // stays as authored and an omitted one stays absent (a bare `$` prompt).
     expect(terminalCardModel(settled({
       callView: callTerminal({ cwd: 'packages/ui' }),
-    }))?.cwd).toBe('packages/ui')
-    expect(terminalCardModel(settled())?.cwd).toBeUndefined()
+    }))?.card.cwd).toBe('packages/ui')
+    expect(terminalCardModel(settled())?.card.cwd).toBeUndefined()
     // The running arm resolves identically.
-    expect(terminalCardModel(running(), '/w/app')?.cwd).toBe('/w/app')
+    expect(terminalCardModel(running(), '/w/app')?.card.cwd).toBe('/w/app')
+  })
+
+  it('normalizes a relative workdir so the label names the directory actually used', () => {
+    // The bash executor resolves the workdir before running, so `..` against
+    // /w/app runs in /w — the card must say `w`, not `..`.
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: '..' }),
+    }), '/w/app')?.card.cwd).toBe('/w')
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: '.' }),
+    }), '/w/app')?.card.cwd).toBe('/w/app')
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: '../sibling' }),
+    }), '/w/app')?.card.cwd).toBe('/w/sibling')
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: './nested/../other' }),
+    }), '/w/app')?.card.cwd).toBe('/w/app/other')
+    // A `..` that would climb past the root is dropped, as a filesystem does.
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: '../../..' }),
+    }), '/w')?.card.cwd).toBe('/')
+    // An absolute path carrying segments normalizes too.
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: '/srv/./app/../other' }),
+    }), '/w/app')?.card.cwd).toBe('/srv/other')
+    // A Windows path keeps its separators.
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: 'C:\\ws\\app\\..' }),
+    }), '/w')?.card.cwd).toBe('C:\\ws')
+    // Without a session cwd a relative `..` has nothing to resolve against, so
+    // it survives as authored rather than being silently dropped.
+    expect(terminalCardModel(settled({
+      callView: callTerminal({ cwd: '../elsewhere' }),
+    }))?.card.cwd).toBe('../elsewhere')
+  })
+
+  it('carries the call view\'s description, which the contract renders above the card', () => {
+    expect(terminalCardModel(settled())?.description).toBe('List files')
+    expect(terminalCardModel(running())?.description).toBe('List files')
+    // A presenter that supplies none, and a window-truncated call side, both
+    // leave it absent so the row keeps its args-derived summary.
+    expect(terminalCardModel(settled({
+      callView: { card: 'terminal', title: 'ls' },
+    }))?.description).toBeUndefined()
+    expect(terminalCardModel(settled({ call: null, callView: null }))?.description).toBeUndefined()
   })
 
   it('a window-truncated call side falls back to the result title, then to an empty command', () => {
@@ -118,8 +169,8 @@ describe('terminalCardModel', () => {
     const truncated = { call: null, callView: null }
     expect(terminalCardModel(settled({
       ...truncated, resultView: resultTerminal({ title: 'ls -la' }),
-    }))).toMatchObject({ command: 'ls -la', cwd: undefined, running: false })
-    expect(terminalCardModel(settled(truncated))).toMatchObject({ command: '', cwd: undefined })
+    }))?.card).toMatchObject({ command: 'ls -la', cwd: undefined, running: false })
+    expect(terminalCardModel(settled(truncated))?.card).toMatchObject({ command: '', cwd: undefined })
   })
 
   it('returns null for every non-terminal call: no views, generic views, unknown cards', () => {
@@ -244,6 +295,23 @@ describe('BashRow terminal card', () => {
     expect(runStateOf(settledView.container)).toBe('done')
   })
 
+  it('shows the terminal presenter\'s description instead of the args summary', () => {
+    // `terminal_send`-style presenters author a description the args do not
+    // repeat; the contract puts it above the card, which is this row's summary.
+    const view = render(<BashRow {...rowProps(settled({
+      callView: callTerminal({ description: 'Terminal 3' }),
+    }))} />)
+    expect(view.getByText('Terminal 3')).toBeTruthy()
+    expect(view.queryByText('List files')).toBeNull()
+  })
+
+  it('keeps the args-derived summary when the presenter authored no description', () => {
+    const view = render(<BashRow {...rowProps(settled({
+      callView: { card: 'terminal', title: 'ls -la' },
+    }))} />)
+    expect(view.getByText('List files')).toBeTruthy()
+  })
+
   it('a non-terminal bash call (background start) renders the summary row alone', () => {
     const view = render(<BashRow {...rowProps(settled({
       callView: { card: 'generic', title: 'sleep 30', kind: 'execute' },
@@ -358,13 +426,31 @@ describe('DetailsPanel Output section', () => {
     expect(pre?.textContent).toBe('permission denied')
   })
 
-  it('a run_code sub-dispatch resolves to its own terminal card', () => {
+  // The panel resolves a sub-dispatch through the same material as a native
+  // call, so a sub-call that DID carry terminal views would render the card.
+  // The shipped wire cannot produce that yet: `session.ts` folds
+  // `tool/code-dispatch(-start)` with `callView: null`/`resultView: null`, and
+  // the host's `viewFor` only presents top-level `tool/call`/`tool/result`. This
+  // pins the resolution path with views injected directly, and the arm below
+  // pins what the shipped path actually shows today.
+  it('a run_code sub-dispatch resolves to its own terminal card once views reach it', () => {
     const view = mount(snapshot({
       codeDispatches: new Map([['p1', [settled({ callId: 'c1' })]]]),
     }), target)
     expect(view.getByText('a.ts  b.ts', RAW)).toBeTruthy()
   })
 
+  it('a sub-dispatch as the wire actually delivers it (no views) keeps the flattened form', () => {
+    const view = mount(snapshot({
+      codeDispatches: new Map([['p1', [settled({ callId: 'c1', callView: null, resultView: null })]]]),
+    }), target)
+    // No terminal card: the generic path renders the result text in the Output
+    // section's <pre> (the Input section has its own, hence the scoping).
+    expect(view.container.querySelector('[data-terminal]')).toBeNull()
+    const output = view.getByText('Output').closest('section')
+    expect(output?.querySelector('pre')?.textContent).toContain('a.ts  b.ts')
+  })
+
   it('a running run_code sub-dispatch resolves through the running material', () => {
     const view = mount(snapshot({
       // The leading non-matching sub-call exercises the scan's skip.