Merge origin/master into codex/sqlite-metadata-contracts

packages/bash/tool-bash/tests/integration.spec.ts

@@ -109,7 +109,7 @@ describe('bash tool through the agent loop', () => {
     const location = ctx.sessionPersistence.locate(agent.session.header)
     expect(location?.kind).toBe('jsonl')
 
-    agent.send([{ type: 'text', text: 'inspect the current session' }])
+    agent.followup([{ type: 'text', text: 'inspect the current session' }])
     await waitForIdle(ctx, agent)
 
     const result = findEvent(events(agent), 'tool/result')
@@ -128,7 +128,7 @@ describe('bash tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-fg'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'run echo integration-ok' }])
+    agent.followup([{ type: 'text', text: 'run echo integration-ok' }])
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
@@ -160,7 +160,7 @@ describe('bash tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-exit'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'run exit 9' }])
+    agent.followup([{ type: 'text', text: 'run exit 9' }])
     await waitForIdle(ctx, agent)
 
     const toolResult = findEvent(events(agent), 'tool/result')
@@ -168,7 +168,7 @@ describe('bash tool through the agent loop', () => {
     expect(resultText(toolResult)).toContain('[exit code: 9]')
   })
 
-  it('background: start ack → completion notice as context/message → task_output collects it', async () => {
+  it('background: start ack → completion notice as user/message → task_output collects it', async () => {
     // The task id is deterministic (a fresh TaskService counts per kind from 1),
     // so the script can name `bash-1` without threading a generated id.
     const adapter = new MockAdapter([
@@ -180,7 +180,7 @@ describe('bash tool through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-bg'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'run echo bg-ok in the background' }])
+    agent.followup([{ type: 'text', text: 'run echo bg-ok in the background' }])
     await waitForIdle(ctx, agent)
 
     const firstResult = findEvent(events(agent), 'tool/result')
@@ -188,17 +188,19 @@ describe('bash tool through the agent loop', () => {
     expect(resultText(firstResult)).toBe('started background task bash-1')
 
     // The task settles on its own; the tool-tasks notice listener injects a
-    // durable context/message into the owning agent's session (settlement may
-    // race turn end, so poll for it).
-    await pollUntil(() => events(agent).some(event => event.type === 'context/message'))
-    const notice = findEvent(events(agent), 'context/message')
+    // durable plugin-sourced user/message into the owning agent's session
+    // (settlement may race turn end, so poll for it).
+    const isNotice = (e: SessionEvent): e is SessionEvent<'user/message'> =>
+      e.type === 'user/message' && e.data.source.kind === 'plugin'
+    await pollUntil(() => events(agent).some(isNotice))
+    const notice = events(agent).find(isNotice)!
     expect(notice.data.content.some(
       block => block.type === 'text' && block.text.includes('background task bash-1 (bash: echo bg-ok) finished'),
     )).toBe(true)
     expect(notice.data.source).toEqual({ kind: 'plugin', plugin: 'tool-tasks' })
 
     // The next turn collects the output through the generic task tool.
-    agent.send([{ type: 'text', text: 'collect it' }])
+    agent.followup([{ type: 'text', text: 'collect it' }])
     await waitForIdle(ctx, agent)
     const readResult = findEvent(events(agent), 'tool/result', 'last')
     expect(readResult.data.isError).toBe(false)

packages/client/connection/src/client/fixture.ts

@@ -76,7 +76,7 @@ function buildAlphaLog(): SessionEvent[] {
       })
     }
     if (turn % 9 === 4) {
-      push({ type: 'context/message', surfaceOp: 'append', data: { content: text(`[fixture] 上下文注入（turn ${turn}）`), source: { kind: 'plugin', plugin: 'fixture' } } })
+      push({ type: 'user/message', surfaceOp: 'append', data: { content: text(`[fixture] 上下文注入（turn ${turn}）`), source: { kind: 'plugin', plugin: 'fixture' } } })
     }
     push({ type: 'step/start', data: { turn, step: 0 } })
     const withTool = turn % 5 === 2

packages/client/runtime/src/client/sessions/conversation.ts

@@ -42,6 +42,8 @@ export function toAssistantBlock(block: ContentBlock): AssistantBlock {
 export interface UserMessageNode {
   kind: 'user'
   seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
   content: readonly ContentBlock[]
   source: unknown
 }
@@ -50,6 +52,8 @@ export interface UserMessageNode {
 export interface AssistantMessageNode {
   kind: 'assistant'
   seq: number
+  /** Unix epoch ms from the source session event (or turn/end when frozen from a partial). */
+  time: number
   turn: number
   step: number
   blocks: readonly AssistantBlock[]
@@ -63,6 +67,8 @@ export interface AssistantMessageNode {
 export interface SteeringMessageNode {
   kind: 'steering'
   seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
   turn: number
   content: readonly ContentBlock[]
   source: unknown
@@ -72,6 +78,8 @@ export interface SteeringMessageNode {
 export interface ContextMessageNode {
   kind: 'context'
   seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
   content: readonly ContentBlock[]
   source: unknown
   meta?: unknown
@@ -81,9 +89,13 @@ export interface ContextMessageNode {
 export interface ToolResultNode {
   kind: 'tool-result'
   seq: number
+  /** Unix epoch ms from the tool/result session event. */
+  time: number
   callId: string
   /** Call head backfilled from the in-window tool/call; null when window truncation left the call outside (card head shows callId). */
   call: { name: string; argsRaw: string } | null
+  /** Unix epoch ms of the paired tool/call when the call is still in-window; used for call-row duration. */
+  callTime: number | null
   content: readonly ContentBlock[]
   isError: boolean
   error?: { name: string; code: string }
@@ -98,6 +110,8 @@ export interface ToolResultNode {
 export interface UnknownSurfaceNode {
   kind: 'unknown'
   seq: number
+  /** Unix epoch ms from the source session event when known. */
+  time: number
   type: string
   data: unknown
 }
@@ -118,6 +132,8 @@ export interface RunningToolCall {
   argsRaw: string
   turn: number
   step: number
+  /** Unix epoch ms when the tool/call event was logged. */
+  time: number
   /** Host-computed render intent riding the tool/call frame; null = generic JSON card. */
   callView: ToolCallView | null
 }

packages/client/runtime/src/client/sessions/fold-adapter.ts

@@ -18,6 +18,8 @@ export interface CallIndexEntry {
   argsRaw: string
   turn: number
   step: number
+  /** Unix epoch ms of the tool/call event. */
+  time: number
   /** Wire view riding the tool/call (envelope-level; never inside the event). */
   callView: ToolCallView | null
 }
@@ -38,24 +40,37 @@ function materializeNode(
 ): ConversationNode {
   switch (event.type) {
     case 'user/message':
-      return { kind: 'user', seq: event.seq, content: event.data.content, source: event.data.source }
+      // Injected context (plugin/goal source) folds to a context node, not a
+      // user message; only a direct human prompt is a user node.
+      if (event.data.source.kind !== 'user') {
+        return {
+          kind: 'context', seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
+          meta: event.data.meta,
+        }
+      }
+      return {
+        kind: 'user', seq: event.seq, time: event.time,
+        content: event.data.content, source: event.data.source,
+      }
     case 'assistant/message':
       return {
-        kind: 'assistant', seq: event.seq, turn: event.data.turn, step: event.data.step,
+        kind: 'assistant', seq: event.seq, time: event.time,
+        turn: event.data.turn, step: event.data.step,
         blocks: toAssistantBlocks(event.data.content), usage: event.data.usage,
       }
     case 'steering/message':
-      return { kind: 'steering', seq: event.seq, turn: event.data.turn, content: event.data.content, source: event.data.source }
-    case 'context/message':
       return {
-        kind: 'context', seq: event.seq, content: event.data.content, source: event.data.source,
-        meta: event.data.meta,
+        kind: 'steering', seq: event.seq, time: event.time, turn: event.data.turn,
+        content: event.data.content, source: event.data.source,
       }
     case 'tool/result': {
       const call = callIndex.get(String(event.data.callId))
       return {
-        kind: 'tool-result', seq: event.seq, callId: String(event.data.callId),
+        kind: 'tool-result', seq: event.seq, time: event.time,
+        callId: String(event.data.callId),
         call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
+        callTime: call?.time ?? null,
         content: event.data.content, isError: event.data.isError,
         ...(event.data.error !== undefined ? { error: event.data.error } : {}),
         meta: event.data.meta,
@@ -63,11 +78,14 @@ function materializeNode(
         resultView,
       }
     }
-    /* v8 ignore next 2 -- defensive arm: fold output only carries the five
+    /* v8 ignore next 2 -- defensive arm: fold output only carries the four
     surface-eligible types, and each has a case above; reachable only if core
     adds an eligible type. */
     default:
-      return { kind: 'unknown', seq: event.seq, type: event.type, data: (event as { data?: unknown }).data }
+      return {
+        kind: 'unknown', seq: event.seq, time: event.time,
+        type: event.type, data: (event as { data?: unknown }).data,
+      }
   }
 }
 
@@ -186,6 +204,7 @@ export class FoldAdapter {
     if (event.type !== 'tool/call') return
     this.callIdx.set(String(event.data.callId), {
       name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
+      time: event.time,
       callView: view?.for === 'call' ? view.view : null,
     })
     // No backfill into already-materialized tool-result nodes for this callId

packages/client/runtime/src/client/sessions/service.ts

@@ -95,9 +95,10 @@ export class SessionsService {
   /**
    * Persisted selection cell (the durable half of `list.current`). Private on
    * purpose: reads go through the list snapshot; writes through {@link
-   * SessionsService.open}. Projection validates it against the live list
-   * instead of destructively pruning, so a selection survives transient list
-   * states (reconnect re-pull) and resurfaces when its session returns.
+   * SessionsService.open} / {@link SessionsService.clear}. Projection
+   * validates it against the live list instead of destructively pruning, so a
+   * selection survives transient list states (reconnect re-pull) and
+   * resurfaces when its session returns.
    */
   private readonly selection: SnapshotStore<{ sessionId?: SessionId }>
 
@@ -116,7 +117,7 @@ export class SessionsService {
    * @param ctx - client root context (scope fibers mount under it).
    * @param api - wire client shared with every Session.
    */
-  constructor(private readonly rootCtx: Context, api: IApiClient) {
+  constructor(private readonly rootCtx: Context, private readonly api: IApiClient) {
     this.manager = new SessionManager(api)
     this.selection = createSnapshotStore<{ sessionId?: SessionId }>(
       {},
@@ -137,7 +138,7 @@ export class SessionsService {
 
   /**
    * Select a session as current. Unknown ids fail loud instead of navigating
-   * nowhere (the sole selection write path).
+   * nowhere.
    * @param id - session id (must exist in the list store).
    */
   open(id: SessionId): void {
@@ -148,6 +149,17 @@ export class SessionsService {
     this.list.update((draft) => { draft.current = id })
   }
 
+  /**
+   * Clear the current selection so the layout shows the no-session empty
+   * state. Wipes the persisted selection too — a reload stays on empty until
+   * the user opens or starts a session. Staging holds the previous occupant
+   * across the blank (same masked-gap rule as a transient list miss).
+   */
+  clear(): void {
+    this.selection.set({})
+    this.list.update((draft) => { draft.current = undefined })
+  }
+
   /**
    * Create a session on the host.
    * @param opts - creation options (project directory).
@@ -159,6 +171,27 @@ export class SessionsService {
     return result.value.sessionId
   }
 
+  /**
+   * Create a workspace folder under the host process cwd and a session in it.
+   * Name is a single path segment (no separators); the host mkdir runs inside
+   * session.create. Caller opens the returned id when it wants the session staged.
+   * @param name - workspace folder basename.
+   * @returns the new session id.
+   */
+  async createWorkspace(name: string): Promise<SessionId> {
+    const trimmed = name.trim()
+    if (trimmed === '') throw new Error('sessions.createWorkspace: name is required')
+    if (/[/\\]/.test(trimmed)) {
+      throw new Error('sessions.createWorkspace: name must not contain path separators')
+    }
+    const { result } = await this.api.host.describe({})
+    if (!result.ok) {
+      throw new Error(`host.describe failed: ${result.error.code}: ${result.error.message}`)
+    }
+    const hostCwd = result.value.cwd.replace(/[/\\]+$/, '')
+    return this.create({ cwd: `${hostCwd}/${trimmed}` })
+  }
+
   /**
    * Resolve a session-scoped context view (use-and-discard).
    * @param id - session id.

packages/client/runtime/src/client/sessions/session.ts

@@ -434,7 +434,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
       case 'tool/call': {
         this.openCalls.set(String(event.data.callId), {
           callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
-          turn: event.data.turn, step: event.data.step,
+          turn: event.data.turn, step: event.data.step, time: event.time,
           callView: view?.for === 'call' ? view.view : null,
         })
         this.callsRev++
@@ -455,7 +455,8 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
           if (visible) {
             // Fractional seq: strictly after every event of this turn (all < turn/end seq), before the next turn.
             this.frozenNodes.push({
-              kind: 'assistant', seq: event.seq - 0.9, turn: this.partial.turn, step: this.partial.step,
+              kind: 'assistant', seq: event.seq - 0.9, time: event.time,
+              turn: this.partial.turn, step: this.partial.step,
               blocks, interrupted: true,
             })
             this.frozenRev++
@@ -469,8 +470,10 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
           this.callsRev++
           // The spinner card becomes an interrupted terminal card (never vanishes mid-flow).
           this.frozenNodes.push({
-            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, callId,
+            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, time: event.time,
+            callId,
             call: { name: call.name, argsRaw: call.argsRaw },
+            callTime: call.time,
             content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
             callView: call.callView, resultView: null,
           })

packages/client/runtime/tests/fold-adapter.spec.ts

@@ -40,7 +40,7 @@ describe('FoldAdapter', () => {
       ev.user(0, '用户'),
       ev.assistant(1, 0, '助手'),
       at(2, { type: 'steering/message', surfaceOp: 'append', data: { turn: 0, content: [{ type: 'text', text: '插话' }], source: { kind: 'user' } } }),
-      at(3, { type: 'context/message', surfaceOp: 'append', data: { content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' } } }),
+      at(3, { type: 'user/message', surfaceOp: 'append', data: { content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' } } }),
       ev.toolCall(4, 0, 'c1', 'echo', '{"x":1}'),
       ev.toolResult(5, 0, 'c1', '结果'),
     ]

packages/client/runtime/tests/sessions-service.spec.ts

@@ -133,6 +133,26 @@ describe('current selection (migrated from ui-layout, arbitrated into the list s
     expect(b.svc.list.getSnapshot().current).toBe('s1') // failed open leaves the selection alone
   })
 
+  it('clear() blanks list.current and the persisted selection', async () => {
+    const storage = new Map<string, string>()
+    vi.stubGlobal('localStorage', {
+      getItem: (k: string) => storage.get(k) ?? null,
+      setItem: (k: string, v: string) => { storage.set(k, v) },
+      removeItem: (k: string) => { storage.delete(k) },
+      clear: () => { storage.clear() },
+    })
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    b.svc.open(sid('s1'))
+    expect(storage.get('dsh.sessions.current')).toContain('s1')
+    b.svc.clear()
+    expect(b.svc.list.getSnapshot().current).toBeUndefined()
+    // Persisted wipe: a fresh service with the same storage stays on empty.
+    const again = bench()
+    await feedList(again, [{ id: 's1' }])
+    expect(again.svc.list.getSnapshot().current).toBeUndefined()
+  })
+
   it('masks (not destroys) the selection while its session is off the list', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }, { id: 's2' }])
@@ -277,6 +297,27 @@ describe('create', () => {
   })
 })
 
+describe('createWorkspace', () => {
+  it('joins host.describe cwd with the name and creates there', async () => {
+    const b = bench()
+    b.api.onDescribe = () => Promise.resolve(ok({ version: '0', cwd: '/host/root', attachedSessions: 0 }))
+    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('ws') }))
+    await expect(b.svc.createWorkspace('My Proj')).resolves.toBe('ws')
+    expect(b.api.callsOf('session.create')).toEqual([{ cwd: '/host/root/My Proj' }])
+  })
+
+  it('rejects empty names and path separators; surfaces describe failures', async () => {
+    const b = bench()
+    await expect(b.svc.createWorkspace('  ')).rejects.toThrow(/name is required/)
+    await expect(b.svc.createWorkspace('a/b')).rejects.toThrow(/path separators/)
+    b.api.onDescribe = () => Promise.resolve({
+      rpcId: 'e' as never,
+      result: { ok: false as const, error: { code: 'internal' as const, message: 'down', details: {} } },
+    } as never)
+    await expect(b.svc.createWorkspace('ok')).rejects.toThrow(/host.describe failed/)
+  })
+})
+
 describe('coverage tails (branch duals)', () => {
   it('displayTitleOf falls back to the id for empty and separator-only cwd', async () => {
     const b = bench()

packages/client/ui-conversation/src/client/apply.ts

@@ -160,6 +160,10 @@ export function apply(ctx: Context): void {
         if (conversation === undefined) throw new Error('ui-conversation: conversation service unavailable')
         return conversation.startSession(opts)
       },
+      createWorkspaceSession: async (name) => {
+        const id = await sessions.createWorkspace(name)
+        sessions.open(id)
+      },
     }),
   }, EmptyState)
 }

packages/client/ui-conversation/src/client/contract/slots.ts

@@ -164,6 +164,11 @@ export type DetailsSlotProps = PropsRuntime<'details'> & PropsStore<ChatStore> &
 export interface EmptyStateInjected {
   /** The create → navigate → first-send chain, in one service call. */
   startSession(opts: { cwd?: string; text: string; mode: 'queue' | 'steer' }): Promise<void>
+  /**
+   * Create a workspace folder under the host cwd, mint a session there, and
+   * open it (Create-new modal success path).
+   */
+  createWorkspaceSession(name: string): Promise<void>
 }
 
 /** Full empty-state component props (root slot: no store; cwd options derive from useSessions in-component). */

packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css

@@ -1,6 +1,6 @@
-/* NEW SESSION hero: headline over the shared InputBar card, centered in the
-   conversation column. The card is the same component as the composer —
-   only positioning lives here. */
+/* NEW SESSION hero (figma Input_Bottom 75:8208): fish + title, workspace chip
+   above the shared InputBar card. The input itself is InputBar — only stack
+   geometry and the chip live here. */
 
 .root {
   display: flex;
@@ -11,58 +11,154 @@
   padding: 24px;
 }
 
-/* figma hero group 34:10409: headline block sits 36px above the input card. */
-.card {
+/* Cap matches InputBar card width (800). Glow may paint past the sides. */
+.stack {
   display: flex;
   flex-direction: column;
-  gap: 36px;
+  align-items: stretch;
+  /* figma 75:8208: 12 between title block / workspace / card. */
+  gap: 12px;
   width: 100%;
-  max-width: 776px;
+  max-width: 800px;
+  overflow: visible;
 }
 
-/* figma 34:10411: fish + title row, gap 10, centered; title 26/32 wt600 (34:10414). */
+/* figma 34:10411: fish + title, gap 10, centered; 26/32 wt600; title block
+   keeps 36px below the headline before the flex gap. */
 .headline {
   display: flex;
   align-items: center;
   justify-content: center;
   gap: 10px;
+  padding-bottom: 36px;
   font-size: 26px;
   line-height: 32px;
   font-weight: 600;
   color: var(--dsw-alias-label-primary);
 }
 
-/* figma 34:10412/10413: brand-blue vector. */
+/* figma fish fill rides business blue. */
 .fish {
   flex: none;
   color: var(--dsw-alias-state-business-primary);
 }
 
-.picker {
+/* Workspace row sits 12px above the input card (figma y80 → y112). Glow is
+   centered on this block so it stays under the picker + InputBar together. */
+.body {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  min-width: 0;
+  overflow: visible;
+}
+
+/* Design input 776 → glow SVG 1051×468 (ellipse 851×268 + blur pad). */
+.glow {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  z-index: 0;
+  width: calc(100% * 1051 / 776);
+  aspect-ratio: 1051 / 468;
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+}
+
+.body > :not(.glow) {
+  position: relative;
+  z-index: 1;
+}
+
+/* Must beat `.body > :not(.glow)` specificity so the open Menu (and its
+   right-hand submenu) paints above the InputBar card. */
+.body > .workspaceRow {
+  z-index: 10;
   display: flex;
   align-items: center;
   min-width: 0;
+  /* figma 75:8208 workspace row: px 8 above the card. */
+  padding-left: 8px;
 }
 
-.select,
-.customInput {
-  max-width: 320px;
-  padding: 4px 10px;
-  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+/* Folder + label + chevron — transparent at rest; fill only on hover / open. */
+.workspace {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  max-width: 100%;
+  min-height: 28px;
+  padding: 0 8px;
+  border: none;
   border-radius: 12px;
-  background: var(--dsw-alias-bg-base);
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
   font-size: 13px;
   line-height: 20px;
-  color: var(--dsw-alias-label-secondary);
+  font-weight: 500;
+  cursor: pointer;
 }
 
-.customInput {
-  width: 320px;
-  outline: none;
+.workspace:hover,
+.workspace[aria-expanded='true'] {
+  background: var(--dsw-alias-interactive-bg-hover);
 }
 
-.customInput:focus {
-  /* Business blue, not brand-primary: that token resolves to ink in this sheet. */
-  border-color: var(--dsw-alias-state-business-primary);
+.folder {
+  flex: none;
   color: var(--dsw-alias-label-primary);
 }
+
+.workspaceLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.chevron {
+  flex: none;
+  color: var(--dsw-alias-label-caption);
+}
+
+/* Workspace menu width tracks the longest basename in the Figma frame. */
+.workspaceMenu :global([role='menu']) {
+  min-width: 240px;
+}
+
+/* Dialog field (figma 451:18655 Input): h44, r22, px 14, caption placeholder. */
+.modalInput {
+  width: 100%;
+  height: 44px;
+  padding: 0 14px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 22px;
+  outline: none;
+  background: transparent;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.modalInput::placeholder {
+  color: var(--dsw-alias-label-caption);
+}
+
+.modalInput:focus {
+  border-color: var(--dsw-alias-state-business-primary);
+}
+
+.modalInput:disabled {
+  color: var(--dsw-alias-label-dimmed);
+}
+
+.modalAction {
+  min-width: 72px;
+}
+
+.modalError {
+  margin-top: 8px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-error-primary);
+}

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

@@ -1,21 +1,37 @@
-// EmptyState (figma NEW SESSION screen): centered hero card built around the
-// SAME InputBar component the resident composer uses (the empty→content
-// transition is one component changing position, never a swap). Project
-// picker: cwd set derived in-component from the standard useSessions hook
-// (subscription is the framework's, derivation is a pure function — design
-// §6) plus a free-form new-directory input; submit runs the startSession
-// chain (create → open → send) in one service call.
+// EmptyState (figma NEW SESSION screen): centered hero — fish + title,
+// workspace picker row (MenuDropdown 122:9481 + New Workspace submenu
+// 419:16920 + Dialog 451:18655), then the SAME InputBar the resident
+// composer uses (empty→content is a position move, never a swap). Project
+// options derive in-component from useSessions; Create new runs
+// createWorkspaceSession (host mkdir + session.create + open).
 
-import { useMemo, useState } from 'react'
-import { FishLogo } from '@deepseek-ai/dsh-client-ui-primitives'
+import { useId, useMemo, useState } from 'react'
+import {
+  Button,
+  FishLogo,
+  IconChevronDownOutline14,
+  IconFolderClose16,
+  IconFolderOpen16,
+  IconPlusOutline16,
+  Menu,
+  Modal,
+  type MenuEntry,
+} from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
 import type { EmptyStateSlotProps } from '../contract/slots.ts'
 import { InputBar } from './InputBar.tsx'
 import type { InputBarError } from './InputBar.tsx'
 import css from './EmptyState.module.css'
 
-/** Select sentinel for the free-form directory entry (impossible as a real path: not absolute). */
-const NEW_DIR = '::new-directory'
+/** Menu id for "New Workspace" (opens submenu; not a cwd). */
+const NEW_WORKSPACE = '::new-workspace'
+/** Submenu: path modal (figma 451:18655 copy). */
+const USE_EXISTING = '::use-existing'
+/** Submenu: create-workspace modal → mkdir + default session. */
+const CREATE_NEW = '::create-new'
+
+/** Which full-page dialog is open (null = none). */
+type ModalKind = 'path' | 'create' | null
 
 /** Full props composed by reference from the contract (runtime share & injected share; no store). */
 export type EmptyStateProps = EmptyStateSlotProps
@@ -30,16 +46,30 @@ function deriveCwds(state: SessionListState): readonly string[] {
   return [...seen]
 }
 
-export function EmptyState({ useSessions, startSession }: EmptyStateProps) {
+/** Basename for the workspace chip / menu row; empty → the design's "New Workspace" label. */
+function workspaceLabel(cwd: string): string {
+  if (cwd === '') return 'New Workspace'
+  const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
+  return base !== undefined && base !== '' ? base : cwd
+}
+
+export function EmptyState({ useSessions, startSession, createWorkspaceSession }: EmptyStateProps) {
   const list = useSessions(s => s)
   const cwds = useMemo(() => deriveCwds(list), [list])
   // Local viewing state: the empty state owns no session, so its draft is
   // ephemeral by design (drafts are keyed by session id; there is none yet).
   const [draft, setDraft] = useState('')
-  const [cwd, setCwd] = useState<string>('')
-  const [custom, setCustom] = useState(false)
+  const [cwd, setCwd] = useState('')
+  const [menuOpen, setMenuOpen] = useState(false)
+  const [modalKind, setModalKind] = useState<ModalKind>(null)
+  const [pathDraft, setPathDraft] = useState('')
+  const [workspaceName, setWorkspaceName] = useState('New WorkSpace')
+  const [creating, setCreating] = useState(false)
+  const [modalError, setModalError] = useState<string | null>(null)
   const [sending, setSending] = useState(false)
   const [error, setError] = useState<InputBarError | null>(null)
+  // Stable filter id so multiple EmptyState mounts do not collide in the DOM.
+  const glowFilterId = `empty-glow-${useId().replace(/:/g, '')}`
 
   const submit = (mode: 'queue' | 'steer'): void => {
     const text = draft.trim()
@@ -58,62 +88,218 @@ export function EmptyState({ useSessions, startSession }: EmptyStateProps) {
     // Success needs no cleanup: the session selection swaps this slot out for the session body.
   }
 
-  const picker = (
-    <div className={css.picker}>
-      {custom
-        ? (
-            <input
-              className={css.customInput}
-              value={cwd}
-              autoFocus
-              placeholder="目录路径，如 /home/me/proj"
-              onChange={(e) => { setCwd(e.target.value) }}
-            />
-          )
-        : (
-            <select
-              className={css.select}
-              value={cwd}
-              aria-label="项目目录"
-              onChange={(e) => {
-                if (e.target.value === NEW_DIR) {
-                  setCustom(true)
-                  setCwd('')
-                } else {
-                  setCwd(e.target.value)
-                }
-              }}
-            >
-              <option value="">默认目录</option>
-              {cwds.map(c => <option key={c} value={c}>{c}</option>)}
-              <option value={NEW_DIR}>新目录…</option>
-            </select>
-          )}
-    </div>
-  )
+  const items: MenuEntry[] = [
+    ...cwds.map(c => ({
+      id: c,
+      label: workspaceLabel(c),
+      icon: <IconFolderClose16 size={16} />,
+    })),
+    ...(cwds.length > 0 ? [{ type: 'separator' as const, id: 'sep-new' }] : []),
+    {
+      id: NEW_WORKSPACE,
+      label: 'New Workspace',
+      icon: <IconPlusOutline16 size={16} />,
+      submenu: [
+        { id: USE_EXISTING, label: 'Use a existing folder' },
+        { id: CREATE_NEW, label: 'Create new' },
+      ],
+    },
+  ]
+
+  const closeModal = (): void => {
+    if (creating) return
+    setModalKind(null)
+    setModalError(null)
+  }
+
+  const openPathModal = (): void => {
+    setPathDraft(cwd)
+    setModalError(null)
+    setModalKind('path')
+  }
+
+  const openCreateModal = (): void => {
+    setWorkspaceName('New WorkSpace')
+    setModalError(null)
+    setModalKind('create')
+  }
+
+  const confirmPath = (): void => {
+    const next = pathDraft.trim()
+    if (next === '') return
+    setCwd(next)
+    setModalKind(null)
+  }
+
+  const confirmCreate = (): void => {
+    if (creating) return
+    setCreating(true)
+    setModalError(null)
+    createWorkspaceSession(workspaceName)
+      .catch((reason: unknown) => {
+        setModalError(reason instanceof Error ? reason.message : String(reason))
+        setCreating(false)
+      })
+    // Success swaps this slot out for the new session body — no local cleanup.
+  }
+
+  const modalBusy = creating
+  const isPath = modalKind === 'path'
+  const isCreate = modalKind === 'create'
 
   return (
     <div className={css.root}>
-      <div className={css.card}>
+      <div className={css.stack}>
         <div className={css.headline}>
-          {/* figma 34:10412: fish 34x25 leading the headline, gap 10. */}
+          {/* figma 34:10412: fish 34×25 leading the headline, gap 10. */}
           <FishLogo size={34} className={css.fish} />
           Let&apos;s start building
         </div>
-        <InputBar
-          draft={draft}
-          running={false}
-          disabled={sending}
-          error={error}
-          variant="hero"
-          placeholder="Message to run task, plan and build"
-          accessory={picker}
-          onDraftChange={setDraft}
-          onSend={submit}
-          /* v8 ignore next -- structural noop: hero never passes running=true, so stop is unreachable. */
-          onStop={() => {}}
-        />
+        <div className={css.body}>
+          {/* figma 313:14109: soft ellipse behind workspace + InputBar; width
+              tracks the card (glow asset 1051 vs design card 776) so blur
+              scales in userSpace with it. */}
+          <svg className={css.glow} viewBox="0 0 1051 468" fill="none" aria-hidden="true">
+            <defs>
+              <filter
+                id={glowFilterId}
+                x="0"
+                y="0"
+                width="1051"
+                height="468"
+                filterUnits="userSpaceOnUse"
+                colorInterpolationFilters="sRGB"
+              >
+                <feFlood floodOpacity="0" result="BackgroundImageFix" />
+                <feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape" />
+                <feGaussianBlur stdDeviation="50" result="effect1_foregroundBlur" />
+              </filter>
+            </defs>
+            <g filter={`url(#${glowFilterId})`}>
+              <ellipse cx="525.5" cy="234" rx="425.5" ry="134" fill="#6187D8" fillOpacity="0.1" />
+            </g>
+          </svg>
+          <div className={css.workspaceRow}>
+            <Menu
+              open={menuOpen}
+              onClose={() => { setMenuOpen(false) }}
+              {...(cwd !== '' ? { selectedId: cwd } : {})}
+              items={items}
+              side="top"
+              className={css.workspaceMenu!}
+              onSelect={(id) => {
+                if (id === USE_EXISTING) {
+                  setMenuOpen(false)
+                  openPathModal()
+                  return
+                }
+                if (id === CREATE_NEW) {
+                  setMenuOpen(false)
+                  openCreateModal()
+                  return
+                }
+                setCwd(id)
+                setMenuOpen(false)
+              }}
+              anchor={(
+                <button
+                  type="button"
+                  className={css.workspace}
+                  aria-label="项目目录"
+                  aria-haspopup="menu"
+                  aria-expanded={menuOpen}
+                  onClick={() => { setMenuOpen(!menuOpen) }}
+                >
+                  <IconFolderOpen16 className={css.folder} size={16} />
+                  <span className={css.workspaceLabel}>{workspaceLabel(cwd)}</span>
+                  <IconChevronDownOutline14 className={css.chevron} size={12} />
+                </button>
+              )}
+            />
+          </div>
+          <InputBar
+            draft={draft}
+            running={false}
+            disabled={sending}
+            error={error}
+            variant="hero"
+            placeholder="Message to run task, plan and build, enter for / commands"
+            onDraftChange={setDraft}
+            onSend={submit}
+            /* v8 ignore next -- structural noop: hero never passes running=true, so stop is unreachable. */
+            onStop={() => {}}
+          />
+        </div>
       </div>
+      <Modal
+        open={isPath}
+        onClose={closeModal}
+        title="Enter an existing folder path"
+        footer={(
+          <>
+            <Button variant="outline" className={css.modalAction!} onClick={closeModal}>Cancel</Button>
+            <Button
+              variant="primary"
+              className={css.modalAction!}
+              disabled={pathDraft.trim() === ''}
+              onClick={confirmPath}
+            >
+              Open Folder
+            </Button>
+          </>
+        )}
+      >
+        <input
+          className={css.modalInput}
+          value={pathDraft}
+          aria-label="Folder path"
+          autoFocus
+          placeholder="ex. User/Documents/Harness/Space"
+          onChange={(e) => { setPathDraft(e.target.value) }}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault()
+              confirmPath()
+            }
+          }}
+        />
+      </Modal>
+      <Modal
+        open={isCreate}
+        onClose={closeModal}
+        title="Create new workspace"
+        footer={(
+          <>
+            <Button variant="outline" className={css.modalAction!} disabled={modalBusy} onClick={closeModal}>
+              Cancel
+            </Button>
+            <Button
+              variant="primary"
+              className={css.modalAction!}
+              disabled={modalBusy || workspaceName.trim() === ''}
+              onClick={confirmCreate}
+            >
+              Create
+            </Button>
+          </>
+        )}
+      >
+        <input
+          className={css.modalInput}
+          value={workspaceName}
+          aria-label="Workspace name"
+          autoFocus
+          disabled={modalBusy}
+          onChange={(e) => { setWorkspaceName(e.target.value) }}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault()
+              confirmCreate()
+            }
+          }}
+        />
+        {modalError !== null && <div className={css.modalError} role="alert">{modalError}</div>}
+      </Modal>
     </div>
   )
 }

packages/client/ui-conversation/src/client/skeleton/InputBar.module.css

@@ -1,7 +1,7 @@
-/* Floating capsule input (figma Input_Bottom 34:11445): card floats above the
+/* Floating capsule input (figma Input_Bottom 75:8208): card floats above the
    viewport bottom inside the centered message column; textarea on top, action
    row below, one primary circle button bottom-right. Input width rides the
-   column (776 is a cap, not a fixed size — layout rule: the box shrinks with
+   column (800 is a cap, not a fixed size — layout rule: the box shrinks with
    the center column keeping its padding). Hero variant = the same card
    centered in the empty state; the transition between the two is a position
    move of one component. */
@@ -10,8 +10,8 @@
   display: flex;
   flex-direction: column;
   align-items: center;
-  /* figma Input_Bottom 34:11445: pad L32/R32/B12; the bottom gradient mask is
-     owned by the chat scroller. Top 8 hosts the error strip's breathing room. */
+  /* figma Input_Bottom: pad L32/R32/B12; the bottom gradient mask is owned by
+     the chat scroller. Top 8 hosts the error strip's breathing room. */
   padding: 8px 32px 12px;
 }
 
@@ -21,7 +21,7 @@
 
 .error {
   width: 100%;
-  max-width: 776px;
+  max-width: 800px;
   margin-bottom: 6px;
   padding: 4px 8px;
   border-radius: 8px;
@@ -34,10 +34,12 @@
 .card {
   display: flex;
   flex-direction: column;
-  /* figma Input 34:11458: 12px between the text area and the button row. */
+  /* figma Input 75:8208: 12px between the text area and the button row; 10px
+     top pad on the card before .InputText. */
   gap: 12px;
   width: 100%;
-  max-width: 776px;
+  max-width: 800px;
+  padding-top: 10px;
   /* Input stroke: black/0.10 light, white/0.06 dark (figma darkmode note says
      the input border is one notch weaker than buttons) — exactly the
      l2-darkmode-thin pair. Fill: the input surface token (elevated in dark). */
@@ -49,11 +51,6 @@
   line-height: 24px;
 }
 
-/* New-session state rounds up (figma: r24 and a taller box). */
-.hero .card {
-  border-radius: 24px;
-}
-
 .accessory {
   display: flex;
   align-items: center;
@@ -85,7 +82,8 @@
 
 .input,
 .mirror {
-  padding: 12px 16px 0;
+  /* figma .InputText 34:10434: pl 16 / pr 12 / pt 4. */
+  padding: 4px 12px 0 16px;
   font-size: inherit;
   line-height: inherit;
   white-space: pre-wrap;
@@ -108,23 +106,98 @@
 .mirror {
   visibility: hidden;
   pointer-events: none;
-  /* 2-line floor: 2 × 24px line + 12px top padding; 14-line cap (336px). */
-  min-height: 60px;
+  /* figma min-h 52 (= ~2 × 24 line + 4pt); 14-line cap (336px). */
+  min-height: 52px;
   max-height: 336px;
   overflow: hidden;
 }
 
-.hero .mirror {
-  /* New-session box is taller at rest (figma 118px input area). */
-  min-height: 84px;
-}
-
-/* figma Frame 1123 (34:11463): pad 12/0/10/10, buttons vertically centered. */
+/* Toolbar: attach + Plan + Read-only on the left; model + send on the right
+   (figma Input_Bottom chrome). */
 .row {
   display: flex;
   align-items: center;
-  justify-content: flex-end;
-  padding: 0 10px 10px 12px;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 0 10px 10px 10px;
+  min-width: 0;
+}
+
+.tools,
+.modes,
+.trailing {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+/* figma 75:8208: 16 between + and the mode chips; 4 between Plan / Read-only. */
+.tools {
+  gap: 16px;
+}
+
+.modes {
+  gap: 4px;
+}
+
+.trailing {
+  flex: none;
+  gap: 12px;
+}
+
+/* Attach circle (figma + control): 28px, selector fill, primary glyph. */
+.add {
+  display: grid;
+  place-items: center;
+  flex: none;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 999px;
+  background: var(--dsw-specific-selector);
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+}
+
+.add:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover-solid);
+}
+
+.add:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+/* Plan / Read-only / model — native <select>, chip-like closed chrome
+   (figma ToggleButton: 13/20 medium secondary, 12px chevron). */
+.select {
+  max-width: 220px;
+  height: 28px;
+  padding: 0 20px 0 8px;
+  border: none;
+  border-radius: 8px;
+  outline: none;
+  background-color: transparent;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12' fill='none'%3E%3Cpath d='M3 4.5L6 7.5L9 4.5' stroke='%2381858C' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 4px center;
+  background-size: 12px 12px;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  white-space: nowrap;
+  cursor: pointer;
+  appearance: none;
+}
+
+.select:hover:not(:disabled) {
+  background-color: var(--dsw-alias-interactive-bg-hover);
+}
+
+.select:disabled {
+  opacity: 0.5;
+  cursor: default;
 }
 
 /* Primary send (figma IconButton 34:10465): 34px circle, #3964FE light /
@@ -133,6 +206,7 @@
 .primary {
   display: grid;
   place-items: center;
+  flex: none;
   width: 34px;
   height: 34px;
   border: none;

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

@@ -4,10 +4,14 @@
 // position move of this component, never a swap (layout ruling). Running
 // LOCKS the input: textarea disabled with the draft visible, stop is the only
 // action; the turn ending re-enables and refocuses.
+//
+// Bottom chrome (attach / Plan / Read-only / model) is visual-only for now —
+// local native <select> state, no host wiring.
 
-import { useEffect, useRef } from 'react'
-import type { KeyboardEvent, MouseEvent, ReactNode } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import type { ChangeEvent, KeyboardEvent, MouseEvent, ReactNode } from 'react'
 import clsx from 'clsx'
+import { IconPlusOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './InputBar.module.css'
 
 /** Prompt failure surface (mirrors the session snapshot's promptError shape). */
@@ -24,13 +28,33 @@ export interface InputBarProps {
   /** Hero = empty-state centered card; composer = resident bottom bar. */
   variant: 'hero' | 'composer'
   placeholder?: string
-  /** Optional leading accessory row content (the empty state mounts its cwd picker here). */
+  /** Optional leading accessory row above the textarea (kept for callers; empty state no longer uses it). */
   accessory?: ReactNode
   onDraftChange: (text: string) => void
   onSend: (mode: 'queue' | 'steer') => void
   onStop: () => void
 }
 
+interface SelectOption {
+  id: string
+  label: string
+}
+
+const PLAN_OPTIONS: readonly SelectOption[] = [
+  { id: 'plan', label: 'Plan' },
+  { id: 'agent', label: 'Agent' },
+]
+
+const READONLY_OPTIONS: readonly SelectOption[] = [
+  { id: 'readonly', label: 'Read-only' },
+  { id: 'readwrite', label: 'Read-write' },
+]
+
+const MODEL_OPTIONS: readonly SelectOption[] = [
+  { id: 'v4-pro-high', label: 'DeepSeek-V4-Pro High' },
+  { id: 'v4-pro', label: 'DeepSeek-V4-Pro' },
+]
+
 export function InputBar({
   draft, running, disabled, error, variant, placeholder, accessory, onDraftChange, onSend, onStop,
 }: InputBarProps) {
@@ -48,6 +72,11 @@ export function InputBar({
     }, 10)
   }
 
+  // Placeholder chrome: selection is local until plan/mode/model seams land.
+  const [planId, setPlanId] = useState('plan')
+  const [readonlyId, setReadonlyId] = useState('readonly')
+  const [modelId, setModelId] = useState('v4-pro-high')
+
   // Locked while running: the browser drops keystrokes AND focus on a disabled
   // textarea — no sending mid-turn, stop or wait.
   const locked = disabled || running
@@ -88,6 +117,25 @@ export function InputBar({
     if (!empty && !disabled) onSend('queue')
   }
 
+  const renderSelect = (
+    aria: string,
+    value: string,
+    options: readonly SelectOption[],
+    onPick: (id: string) => void,
+  ): ReactNode => (
+    <select
+      className={css.select}
+      aria-label={aria}
+      value={value}
+      disabled={locked}
+      onChange={(e: ChangeEvent<HTMLSelectElement>) => { onPick(e.target.value) }}
+    >
+      {options.map(opt => (
+        <option key={opt.id} value={opt.id}>{opt.label}</option>
+      ))}
+    </select>
+  )
+
   return (
     <div className={clsx(css.root, variant === 'hero' && css.hero)}>
       {error !== null && (
@@ -116,25 +164,44 @@ export function InputBar({
           <div aria-hidden className={css.mirror}>{`${draft}\n`}</div>
         </div>
         <div className={css.row}>
-          <button
-            type="button"
-            className={clsx(css.primary, running && css.stopping)}
-            aria-label={primaryLabel}
-            title={running ? '停止本轮' : '发送（Enter）'}
-            disabled={!running && (empty || disabled)}
-            onMouseDown={keepFocus}
-            onClick={onPrimary}
-          >
-            {running ? (
-              <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
-                <rect x="4" y="4" width="8" height="8" rx="1.5" fill="currentColor" />
-              </svg>
-            ) : (
-              <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
-                <path d="M8 13V3.8M8 3.8L3.8 8M8 3.8L12.2 8" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" fill="none" />
-              </svg>
-            )}
-          </button>
+          <div className={css.tools}>
+            <button
+              type="button"
+              className={css.add}
+              aria-label="添加"
+              title="添加"
+              disabled={locked}
+              onMouseDown={keepFocus}
+            >
+              <IconPlusOutline16 size={14} />
+            </button>
+            <div className={css.modes}>
+              {renderSelect('Plan mode', planId, PLAN_OPTIONS, setPlanId)}
+              {renderSelect('Access mode', readonlyId, READONLY_OPTIONS, setReadonlyId)}
+            </div>
+          </div>
+          <div className={css.trailing}>
+            {renderSelect('Model', modelId, MODEL_OPTIONS, setModelId)}
+            <button
+              type="button"
+              className={clsx(css.primary, running && css.stopping)}
+              aria-label={primaryLabel}
+              title={running ? '停止本轮' : '发送（Enter）'}
+              disabled={!running && (empty || disabled)}
+              onMouseDown={keepFocus}
+              onClick={onPrimary}
+            >
+              {running ? (
+                <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
+                  <rect x="4" y="4" width="8" height="8" rx="1.5" fill="currentColor" />
+                </svg>
+              ) : (
+                <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
+                  <path d="M8 13V3.8M8 3.8L3.8 8M8 3.8L12.2 8" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" fill="none" />
+                </svg>
+              )}
+            </button>
+          </div>
         </div>
       </div>
     </div>

packages/client/ui-conversation/tests/apply-inject.spec.tsx

@@ -78,6 +78,7 @@ async function bench() {
     cell: () => undefined,
     scopeOf,
     create: vi.fn(() => Promise.resolve(ROOT)),
+    createWorkspace: vi.fn(() => Promise.resolve(ROOT)),
     open: vi.fn(),
   }
   ctx.provide('sessions', sessionsFake)
@@ -239,16 +240,20 @@ describe('details and empty inject surfaces', () => {
     expect(details).toBe(conv)
   })
 
-  it('empty injects the startSession chain only (no store, cwds derive in-component)', async () => {
+  it('empty injects startSession and createWorkspaceSession (no store, cwds derive in-component)', async () => {
     const b = await bench()
     const entry = b.entryOf('conversation.empty')
     expect(entry.store).toBeUndefined()
     const injected = (entry.inject as unknown as () => EmptyStateInjected)()
-    expect(Object.keys(injected)).toEqual(['startSession'])
+    expect(Object.keys(injected).sort()).toEqual(['createWorkspaceSession', 'startSession'])
     await injected.startSession({ text: 'go', mode: 'queue' })
     expect(b.sessionsFake.create).toHaveBeenCalled()
     expect(b.sessionsFake.open).toHaveBeenCalledWith(ROOT)
     expect(b.sessionFake.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'go' }], 'queue')
+    b.sessionsFake.open.mockClear()
+    await injected.createWorkspaceSession('Fresh')
+    expect(b.sessionsFake.createWorkspace).toHaveBeenCalledWith('Fresh')
+    expect(b.sessionsFake.open).toHaveBeenCalledWith(ROOT)
   })
 
   it('startSession fails loud on a torn boot (conversation service fiber gone)', async () => {

packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx

@@ -20,7 +20,7 @@ afterEach(cleanup)
 const SID = 's1' as SessionId
 
 const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessageNode => ({
-  kind: 'assistant', seq, turn, step: seq, blocks: [{ kind: 'text', text: `t${seq}` }],
+  kind: 'assistant', seq, time: seq * 1_000, turn, step: seq, blocks: [{ kind: 'text', text: `t${seq}` }],
   ...(usage === undefined ? {} : { usage }),
 })
 
@@ -65,7 +65,7 @@ describe('deriveStats', () => {
 
   it('cache hit stays null with no cache accounting; non-assistant nodes ignored', () => {
     const tool: ToolResultNode = {
-      kind: 'tool-result', seq: 5, callId: 'c', call: null, content: [],
+      kind: 'tool-result', seq: 5, time: 5_000, callId: 'c', call: null, callTime: null, content: [],
       isError: false, callView: null, resultView: null,
     }
     const stats = deriveStats([tool, assistant(1, 1)])
@@ -112,8 +112,9 @@ describe('bash sample row', () => {
   const CHILD = 'child-1' as SessionId
 
   const result = (callId: string): ToolResultNode => ({
-    kind: 'tool-result', seq: 3, callId,
+    kind: 'tool-result', seq: 3, time: 3_000, callId,
     call: { name: 'bash', argsRaw: '{"command":"make build","description":"Build"}' },
+    callTime: 2_000,
     content: [], isError: false, callView: null, resultView: null,
   })
 

packages/client/ui-conversation/tests/chat-tool-row.spec.tsx

@@ -12,12 +12,13 @@ import type { ToolRowOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}',
-  turn: 1, step: 1, callView: null, ...over,
+  turn: 1, step: 1, time: 1_000, callView: null, ...over,
 })
 
 const result = (over?: Partial<ToolResultNode>): ToolResultNode => ({
-  kind: 'tool-result', seq: 10, callId: 'c1',
+  kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1',
   call: { name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}' },
+  callTime: 1_000,
   content: [], isError: false, callView: null, resultView: null, ...over,
 })
 

packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx

@@ -31,8 +31,9 @@ beforeEach(() => {
 })
 
 const toolResult = (seq: number, callId: string, name: string, args = '{"command":"make build","description":"Build"}'): ToolResultNode => ({
-  kind: 'tool-result', seq, callId,
+  kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: args },
+  callTime: seq * 1_000 - 500,
   content: [], isError: false, callView: null, resultView: null,
 })
 

packages/client/ui-conversation/tests/chat-view.spec.tsx

@@ -54,18 +54,19 @@ function makeSource(init?: Partial<ConversationSnapshot>) {
 }
 
 const user = (seq: number, text: string): UserMessageNode => ({
-  kind: 'user', seq, content: [{ type: 'text', text }] as never, source: null,
+  kind: 'user', seq, time: seq * 1_000, content: [{ type: 'text', text }] as never, source: null,
 })
 const assistant = (seq: number, text: string): AssistantMessageNode => ({
-  kind: 'assistant', seq, turn: 1, step: 1, blocks: [{ kind: 'text', text }],
+  kind: 'assistant', seq, time: seq * 1_000, turn: 1, step: 1, blocks: [{ kind: 'text', text }],
 })
 const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
-  kind: 'tool-result', seq, callId,
+  kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
+  callTime: seq * 1_000 - 500,
   content: [], isError: false, callView: null, resultView: null,
 })
 const runningCall = (callId: string, name = 'bash'): RunningToolCall => ({
-  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, callView: null,
+  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null,
 })
 
 /** Empty sessions-list hook stub (the global standard-kit seat; engines carry no hook since the store migration — bind here). */

packages/client/ui-conversation/tests/coverage-tails.spec.tsx

@@ -62,8 +62,9 @@ describe('tails', () => {
 
   it('a settled others-variant row renders the sparkle icon in the leading slot', () => {
     const settled: ToolResultNode = {
-      kind: 'tool-result', seq: 2, callId: 'c5',
+      kind: 'tool-result', seq: 2, time: 2_000, callId: 'c5',
       call: { name: 'todo_write', argsRaw: '{"note":"x"}' },
+      callTime: 1_000,
       content: [], isError: false, callView: null, resultView: null,
     }
     const props: ToolRowOwnerProps = {
@@ -77,8 +78,9 @@ describe('tails', () => {
 
   it('BashRow shows the failed pill on error results (root session arm)', () => {
     const errorResult: ToolResultNode = {
-      kind: 'tool-result', seq: 1, callId: 'c1',
+      kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1',
       call: { name: 'bash', argsRaw: '{"command":"boom"}' },
+      callTime: 500,
       content: [], isError: true, callView: null, resultView: null,
     }
     // Root session (no parentId): the global arm renders, error pill visible.

packages/client/ui-conversation/tests/input-bar.spec.tsx

@@ -19,7 +19,10 @@ function setup(over?: Partial<InputBarProps>) {
   }
   const view = render(<InputBar {...props} />)
   const textarea = view.container.querySelector('textarea')!
-  const button = view.container.querySelector('button')!
+  // aria-label (not role name): title also contains 发送/停止 and would double-match.
+  const button = view.container.querySelector<HTMLButtonElement>(
+    `button[aria-label="${over?.running === true ? '停止' : '发送'}"]`,
+  )!
   return { view, textarea, button, props }
 }
 
@@ -97,7 +100,7 @@ describe('running lock and primary button', () => {
     const textarea = view.container.querySelector('textarea')!
     expect(document.activeElement).toBe(textarea)
     textarea.blur()
-    fireEvent.mouseDown(view.container.querySelector('button')!)
+    fireEvent.mouseDown(view.container.querySelector('button[aria-label="发送"]')!)
     expect(document.activeElement).toBe(textarea)
   })
 
@@ -129,3 +132,38 @@ describe('error strip and variants', () => {
     expect(view.container.querySelector('[class*="hero"]')).not.toBeNull()
   })
 })
+
+describe('placeholder chrome', () => {
+  it('renders attach / Plan / Read-only / model controls', () => {
+    const { view } = setup()
+    expect(view.getByLabelText('添加')).toBeTruthy()
+    expect((view.getByLabelText('Plan mode') as HTMLSelectElement).value).toBe('plan')
+    expect((view.getByLabelText('Access mode') as HTMLSelectElement).value).toBe('readonly')
+    expect((view.getByLabelText('Model') as HTMLSelectElement).value).toBe('v4-pro-high')
+  })
+
+  it('native select change updates the selected option', () => {
+    const { view } = setup()
+    const plan = view.getByLabelText('Plan mode') as HTMLSelectElement
+    fireEvent.change(plan, { target: { value: 'agent' } })
+    expect(plan.value).toBe('agent')
+    const access = view.getByLabelText('Access mode') as HTMLSelectElement
+    fireEvent.change(access, { target: { value: 'readwrite' } })
+    expect(access.value).toBe('readwrite')
+  })
+
+  it('model select can drop the High option', () => {
+    const { view } = setup()
+    const model = view.getByLabelText('Model') as HTMLSelectElement
+    fireEvent.change(model, { target: { value: 'v4-pro' } })
+    expect(model.value).toBe('v4-pro')
+    expect(model.selectedOptions[0]?.textContent).toBe('DeepSeek-V4-Pro')
+  })
+
+  it('running locks the chrome selects and attach control', () => {
+    const { view } = setup({ running: true })
+    expect((view.getByLabelText('添加') as HTMLButtonElement).disabled).toBe(true)
+    expect((view.getByLabelText('Plan mode') as HTMLSelectElement).disabled).toBe(true)
+    expect((view.getByLabelText('Model') as HTMLSelectElement).disabled).toBe(true)
+  })
+})

packages/client/ui-conversation/tests/skeleton-branches.spec.tsx

@@ -3,7 +3,7 @@
 // acceptance flows), four-share props form: breadcrumb ancestry derivation +
 // error strip in ConversationRoot, DetailsPanel non-JSON args / non-text
 // result blocks / error-only results over the shared store, EmptyState
-// failure surface and custom-directory swap with in-component cwd derivation.
+// failure surface and path-modal confirm with in-component cwd derivation.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, waitFor } from '@testing-library/react'
@@ -165,7 +165,7 @@ describe('DetailsPanel branches', () => {
 
   it('shows non-JSON args verbatim (streaming fragment path)', () => {
     const view = panel({ turnSeq: 1, callId: 'c1', toolName: 'bash' }, {
-      runningCalls: [{ callId: 'c1', name: 'bash', argsRaw: '{"cmd": tru', turn: 1, step: 1, callView: null }],
+      runningCalls: [{ callId: 'c1', name: 'bash', argsRaw: '{"cmd": tru', turn: 1, step: 1, time: 1_000, callView: null }],
     })
     expect(view.getByText('{"cmd": tru')).toBeTruthy()
   })
@@ -176,7 +176,7 @@ describe('DetailsPanel branches', () => {
   })
 
   it('snapshot updates re-run the material selector through the shallow equality arm', () => {
-    let snap = { ...snapshotBase(), runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{"a":1}', turn: 1, step: 1, callView: null }] } as ConversationSnapshot
+    let snap = { ...snapshotBase(), runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{"a":1}', turn: 1, step: 1, time: 1_000, callView: null }] } as ConversationSnapshot
     const subs = new Set<() => void>()
     const source = {
       getSnapshot: () => snap,
@@ -238,10 +238,16 @@ describe('DetailsPanel branches', () => {
 })
 
 describe('EmptyState branches', () => {
+  const noopCreate = () => Promise.resolve()
+
   it('keeps the draft and surfaces a local error strip when startSession rejects', async () => {
     const startSession = vi.fn(() => Promise.reject(new Error('create down')))
     const view = render(
-      <EmptyState useSessions={listHook([{ id: 'a', title: 'a', cwd: '/proj' }])} startSession={startSession} />,
+      <EmptyState
+        useSessions={listHook([{ id: 'a', title: 'a', cwd: '/proj' }])}
+        startSession={startSession}
+        createWorkspaceSession={noopCreate}
+      />,
     )
     const textarea = view.container.querySelector('textarea')!
     fireEvent.change(textarea, { target: { value: 'first task' } })
@@ -253,7 +259,11 @@ describe('EmptyState branches', () => {
   it('non-Error rejection reasons stringify into the error strip', async () => {
     const startSession = vi.fn(() => Promise.reject('plain-string'))
     const view = render(
-      <EmptyState useSessions={listHook([])} startSession={startSession} />,
+      <EmptyState
+        useSessions={listHook([])}
+        startSession={startSession}
+        createWorkspaceSession={noopCreate}
+      />,
     )
     const textarea = view.container.querySelector('textarea')!
     fireEvent.change(textarea, { target: { value: 'go' } })
@@ -261,7 +271,7 @@ describe('EmptyState branches', () => {
     await waitFor(() => expect(view.getByText(/发送失败：plain-string/)).toBeTruthy())
   })
 
-  it('cwd derivation skips blank cwds; select picks, swaps to free-form, submits the typed path', async () => {
+  it('cwd derivation skips blank cwds; menu picks, path modal confirms, submits the typed path', async () => {
     const startSession = vi.fn(() => Promise.resolve())
     const view = render(
       <EmptyState
@@ -270,19 +280,39 @@ describe('EmptyState branches', () => {
           { id: 'b', title: 'b' }, // no cwd: filtered from the option set
         ])}
         startSession={startSession}
+        createWorkspaceSession={noopCreate}
       />,
     )
-    const select = view.container.querySelector('select')!
-    expect([...(select as HTMLSelectElement).options].map(o => o.value))
-      .toEqual(['', '/proj', '::new-directory'])
-    fireEvent.change(select, { target: { value: '/proj' } })
-    expect((select as HTMLSelectElement).value).toBe('/proj')
-    fireEvent.change(select, { target: { value: '::new-directory' } })
-    const custom = view.container.querySelector('input')!
+    fireEvent.click(view.getByRole('button', { name: '项目目录' }))
+    expect([...view.getByRole('menu').querySelectorAll('[role="menuitem"]')].map(el => el.textContent))
+      .toEqual(['proj', 'New Workspace'])
+    fireEvent.click(view.getByRole('menuitem', { name: 'proj' }))
+    expect(view.getByRole('button', { name: '项目目录' }).textContent).toContain('proj')
+    fireEvent.click(view.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(view.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(view.getByRole('menuitem', { name: 'Use a existing folder' }))
+    const custom = view.getByLabelText('Folder path')
     fireEvent.change(custom, { target: { value: '/typed/dir' } })
+    fireEvent.click(view.getByRole('button', { name: 'Open Folder' }))
     const textarea = view.container.querySelector('textarea')!
     fireEvent.change(textarea, { target: { value: 'task' } })
     fireEvent.keyDown(textarea, { key: 'Enter' })
     await waitFor(() => expect(startSession).toHaveBeenCalledWith({ text: 'task', mode: 'queue', cwd: '/typed/dir' }))
   })
+
+  it('Create modal surfaces inject failures inline', async () => {
+    const createWorkspaceSession = vi.fn(() => Promise.reject(new Error('mkdir blocked')))
+    const view = render(
+      <EmptyState
+        useSessions={listHook([])}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={createWorkspaceSession}
+      />,
+    )
+    fireEvent.click(view.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(view.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(view.getByRole('menuitem', { name: 'Create new' }))
+    fireEvent.click(view.getByRole('button', { name: 'Create' }))
+    await waitFor(() => expect(view.getByRole('alert').textContent).toContain('mkdir blocked'))
+  })
 })

packages/client/ui-conversation/tests/skeleton.spec.tsx

@@ -28,13 +28,33 @@ const sid = (s: string): SessionId => s as SessionId
 
 afterEach(cleanup)
 beforeEach(() => {
-  localStorage.clear()
+  // jsdom normally provides localStorage; some host Node builds surface it as undefined.
+  globalThis.localStorage?.clear()
 })
 
 /** Minimal conversation snapshot slice the skeleton reads. */
 interface FakeSnapshot {
-  nodes: readonly { kind: string; callId?: string; call?: { name: string; argsRaw: string } | null; content?: readonly { type: string; text?: string }[]; isError?: boolean }[]
-  runningCalls: readonly { callId: string; name: string; argsRaw: string }[]
+  nodes: readonly {
+    kind: string
+    seq?: number
+    time?: number
+    callId?: string
+    call?: { name: string; argsRaw: string } | null
+    callTime?: number | null
+    content?: readonly { type: string; text?: string }[]
+    isError?: boolean
+    callView?: null
+    resultView?: null
+  }[]
+  runningCalls: readonly {
+    callId: string
+    name: string
+    argsRaw: string
+    turn?: number
+    step?: number
+    time?: number
+    callView?: null
+  }[]
   running: boolean
   removed: boolean
   promptError: { op: 'send' | 'stop'; error: { message: string; code: string } } | null
@@ -66,6 +86,8 @@ function fakeSessions(rows: { id: string; title: string; cwd?: string; parentId?
 const SessionProviderStub: ConversationRootProps['SessionProvider'] = ({ children }) => <>{children(sid('s1'))}</>
 
 describe('EmptyState', () => {
+  const noopCreate = () => Promise.resolve()
+
   it('derives cwd options from the sessions list, submits startSession, failure surfaces locally', async () => {
     const { useSessions } = fakeSessions([
       { id: 'a', title: 'a', cwd: '/w/app' },
@@ -74,13 +96,21 @@ describe('EmptyState', () => {
     ])
     let reject!: (e: Error) => void
     const startSession = vi.fn(() => new Promise<void>((_res, rej) => { reject = rej }))
-    render(<EmptyState useSessions={useSessions} startSession={startSession} />)
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={startSession}
+        createWorkspaceSession={noopCreate}
+      />,
+    )
 
-    const select = screen.getByRole('combobox', { name: '项目目录' })
-    expect([...(select as HTMLSelectElement).options].map(o => o.value))
-      .toEqual(['', '/w/app', '/w/lib', '::new-directory'])
-    fireEvent.change(select, { target: { value: '/w/app' } })
-    const box = screen.getByPlaceholderText('Message to run task, plan and build')
+    const trigger = screen.getByRole('button', { name: '项目目录' })
+    fireEvent.click(trigger)
+    const menu = screen.getByRole('menu')
+    expect([...menu.querySelectorAll('[role="menuitem"]')].map(el => el.textContent))
+      .toEqual(['app', 'lib', 'New Workspace'])
+    fireEvent.click(screen.getByRole('menuitem', { name: 'app' }))
+    const box = screen.getByPlaceholderText('Message to run task, plan and build, enter for / commands')
     fireEvent.change(box, { target: { value: '造一个轮子' } })
     fireEvent.keyDown(box, { key: 'Enter' })
     expect(startSession).toHaveBeenCalledWith({ text: '造一个轮子', mode: 'queue', cwd: '/w/app' })
@@ -91,13 +121,64 @@ describe('EmptyState', () => {
     expect((box as HTMLTextAreaElement).value).toBe('造一个轮子')
   })
 
-  it('new-directory option swaps the select for a free-form input', () => {
+  it('Use a existing folder opens the path modal and Open Folder sets the chip', () => {
     const { useSessions } = fakeSessions([])
-    render(<EmptyState useSessions={useSessions} startSession={() => Promise.resolve()} />)
-    fireEvent.change(screen.getByRole('combobox'), { target: { value: '::new-directory' } })
-    const custom = screen.getByPlaceholderText(/目录路径/)
-    fireEvent.change(custom, { target: { value: '/tmp/fresh' } })
-    expect((custom as HTMLInputElement).value).toBe('/tmp/fresh')
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={noopCreate}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: '项目目录' }))
+    const newWs = screen.getByRole('menuitem', { name: 'New Workspace' })
+    fireEvent.mouseEnter(newWs.parentElement as HTMLElement)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Use a existing folder' }))
+    expect(screen.getByRole('dialog', { name: 'Enter an existing folder path' })).toBeTruthy()
+    const path = screen.getByLabelText('Folder path') as HTMLInputElement
+    fireEvent.change(path, { target: { value: '/tmp/fresh' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Open Folder' }))
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(screen.getByRole('button', { name: '项目目录' }).textContent).toContain('fresh')
+  })
+
+  it('Create new opens the modal and createWorkspaceSession succeeds', async () => {
+    const { useSessions } = fakeSessions([])
+    const createWorkspaceSession = vi.fn(() => Promise.resolve())
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={createWorkspaceSession}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(screen.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Create new' }))
+    expect(screen.getByRole('dialog', { name: 'Create new workspace' })).toBeTruthy()
+    const name = screen.getByLabelText('Workspace name') as HTMLInputElement
+    expect(name.value).toBe('New WorkSpace')
+    fireEvent.change(name, { target: { value: 'My Proj' } })
+    fireEvent.keyDown(name, { key: 'Enter' })
+    await vi.waitFor(() => expect(createWorkspaceSession).toHaveBeenCalledWith('My Proj'))
+  })
+
+  it('Create modal Cancel dismisses without calling createWorkspaceSession', () => {
+    const { useSessions } = fakeSessions([])
+    const createWorkspaceSession = vi.fn(() => Promise.resolve())
+    render(
+      <EmptyState
+        useSessions={useSessions}
+        startSession={() => Promise.resolve()}
+        createWorkspaceSession={createWorkspaceSession}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: '项目目录' }))
+    fireEvent.mouseEnter(screen.getByRole('menuitem', { name: 'New Workspace' }).parentElement as HTMLElement)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Create new' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(createWorkspaceSession).not.toHaveBeenCalled()
   })
 })
 
@@ -234,10 +315,11 @@ describe('DetailsPanel', () => {
   it('renders the selected call args and result off the shared store; close fires the injected callback', () => {
     const { closeDetails } = benchDetails({
       nodes: [{
-        kind: 'tool-result', callId: 'c1',
+        kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1',
         call: { name: 'bash', argsRaw: '{"cmd":"ls"}' },
+        callTime: 500,
         content: [{ type: 'text', text: 'file-a\nfile-b' }],
-        isError: false,
+        isError: false, callView: null, resultView: null,
       }],
     }, { turnSeq: 1, callId: 'c1' })
     expect(screen.getByText('bash')).toBeTruthy()
@@ -248,10 +330,10 @@ describe('DetailsPanel', () => {
   })
 
   it('shows the empty hint without a selection and the running state for open calls', () => {
-    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}' }] }, null)
+    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}', turn: 1, step: 1, time: 1_000, callView: null }] }, null)
     expect(screen.getByText(/点击消息流中的工具行/)).toBeTruthy()
     cleanup()
-    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}' }] }, { turnSeq: 1, callId: 'c9' })
+    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}', turn: 1, step: 1, time: 1_000, callView: null }] }, { turnSeq: 1, callId: 'c9' })
     expect(screen.getByText('运行中…')).toBeTruthy()
   })
 

packages/client/ui-primitives/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-ui-primitives
 
-Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Input, markdown family (MessageText/MarkdownText/JsonBlock). Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, markdown family (MessageText/MarkdownText/JsonBlock). Contract: api-contracts v3 §8.
 
 ## Markdown rendering
 

packages/client/ui-primitives/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-primitives",
-  "description": "Pure React atoms for the dsh web UI: StateDot, ic_ds_* icon set, Button/Pill/Menu/Input, markdown family (zero cordis)",
+  "description": "Pure React atoms for the dsh web UI: StateDot, ic_ds_* icon set, Button/Pill/Menu/Modal/Input, markdown family (zero cordis)",
   "version": "0.0.1",
   "private": true,
   "type": "module",

packages/client/ui-primitives/src/Button.module.css

@@ -56,6 +56,20 @@
   background: var(--dsw-alias-interactive-bg-active);
 }
 
+/* Dialog Cancel (figma 451:18655): bordered capsule on transparent fill. */
+.outline {
+  border: 1px solid var(--dsw-alias-border-l2);
+  background: transparent;
+}
+
+.outline:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.outline:disabled {
+  border-color: var(--dsw-alias-border-l1);
+}
+
 .toolbar {
   background: var(--dsw-alias-button-tool-bar-fill);
 }

packages/client/ui-primitives/src/Button.tsx

@@ -6,7 +6,7 @@ import clsx from 'clsx'
 import css from './Button.module.css'
 
 /** Visual variant, each backed by its --dsw-alias-button-* token family. */
-export type ButtonVariant = 'primary' | 'ghost' | 'toolbar'
+export type ButtonVariant = 'primary' | 'ghost' | 'outline' | 'toolbar'
 
 /**
  * Render a button.

packages/client/ui-primitives/src/Menu.module.css

@@ -3,21 +3,32 @@
   display: inline-flex;
 }
 
-/* Dropdown card (figma MenuDropdown 122:10096): white card, r12, no border,
- * layered drop shadows via the shadow token, 4px inset padding. */
+/* Dropdown card (figma MenuDropdown 122:9481 / 419:16920): menu surface,
+ * r12, inverted hairline border, shadow-lv3, 4px inset padding. */
+.list,
+.submenu {
+  padding: 4px;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 12px;
+  background: var(--dsw-specific-menu);
+  box-shadow: var(--dsw-shadow-lv3);
+}
+
 .list {
   position: absolute;
   top: calc(100% + 4px);
   left: 0;
   z-index: 100;
   min-width: 130px;
-  padding: 4px;
-  display: flex;
-  flex-direction: column;
-  gap: 0;
-  border-radius: 12px;
-  background: var(--dsw-alias-bg-layer-1);
-  box-shadow: var(--dsw-shadow-lv2);
+}
+
+/* Open above the anchor (empty-state workspace chip: figma 122:9481). */
+.sideTop {
+  top: auto;
+  bottom: calc(100% + 4px);
 }
 
 .alignEnd {
@@ -25,12 +36,18 @@
   right: 0;
 }
 
-/* Menu cell (figma .Menu_cell 27:5169): r10, pad 10/8, 14/22 primary text,
+.itemWrap {
+  position: relative;
+}
+
+/* Menu cell (figma .Menu_cell): min-h 40, r10, pad 10/8, 14/22 primary,
  * gap 8 between leading icon / label / trailing check. */
 .item {
   display: flex;
   align-items: center;
   gap: 8px;
+  width: 100%;
+  min-height: 40px;
   padding: 8px 10px;
   border: none;
   border-radius: 10px;
@@ -51,9 +68,22 @@
   cursor: not-allowed;
 }
 
+.itemIcon {
+  display: inline-flex;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  align-items: center;
+  justify-content: center;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 .itemLabel {
   flex: 1;
   min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .check {
@@ -66,3 +96,34 @@
 .selected {
   background: transparent;
 }
+
+/* Separator cell (figma 122:9481): py 4 / px 2 around the hairline. */
+.separator {
+  height: 1px;
+  margin: 4px 2px;
+  background: var(--dsw-alias-border-l1);
+}
+
+/* Nested card to the right of the parent row (figma 419:16920).
+ * Bottom-aligned with the parent menu card (grows upward): itemWrap sits in
+ * .list's 4px pad, so bottom: -4px matches the list's outer bottom edge.
+ * Horizontal: list pad (4px) + 6px card gap = 10px past itemWrap — plain
+ * `100% + 6px` collapses to ~2px between outer card edges.
+ * ::before bridges the full gap so the pointer can cross without mouseLeave. */
+.submenu {
+  position: absolute;
+  top: auto;
+  bottom: -4px;
+  left: calc(100% + 10px);
+  z-index: 101;
+  min-width: 160px;
+}
+
+.submenu::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: -10px;
+  width: 10px;
+}

packages/client/ui-primitives/src/Menu.tsx

@@ -1,46 +1,69 @@
 // Menu: minimal controlled dropdown (group-by pickers, project selectors).
 // Pure CSS positioning relative to the anchor wrapper — no portal, no popper.
 // The owner controls `open`; outside-click closing uses one document listener
-// active only while open.
+// active only while open. Submenus open on hover/focus inside the same root.
 
-import { useEffect, useRef } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import clsx from 'clsx'
 import { IconCheckOutline16 } from './icons/index.tsx'
 import css from './Menu.module.css'
 
-/** One selectable menu row. */
+/** Selectable row (optionally with a nested submenu). */
 export interface MenuItem {
   id: string
   label: ReactNode
   disabled?: boolean
+  /** Leading icon (figma .Menu_cell gap 8). */
+  icon?: ReactNode
+  /** Nested card opened to the right on hover/focus. */
+  submenu?: readonly MenuItem[]
+}
+
+/** Hairline between item groups (not selectable). */
+export interface MenuSeparator {
+  type: 'separator'
+  id: string
+}
+
+/** One primary-menu entry: a row or a separator. */
+export type MenuEntry = MenuItem | MenuSeparator
+
+function isSeparator(entry: MenuEntry): entry is MenuSeparator {
+  return 'type' in entry && entry.type === 'separator'
 }
 
 /**
  * Render an anchored dropdown menu.
  * @param props.open - whether the list is showing (owner-controlled).
  * @param props.anchor - the trigger element (rendered in place).
- * @param props.items - selectable rows.
+ * @param props.items - selectable rows and optional separators.
  * @param props.selectedId - row shown as selected.
- * @param props.onSelect - row click callback (not called for disabled rows).
+ * @param props.onSelect - row click callback (not called for disabled rows or submenu parents that only open children).
  * @param props.onClose - invoked on outside click or Escape.
  * @param props.align - list alignment against the anchor (default 'start').
+ * @param props.side - open below (`bottom`, default) or above (`top`) the anchor.
  * @returns anchor wrapper with the conditional list.
  */
-export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align = 'start', className }: {
+export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align = 'start', side = 'bottom', className }: {
   open: boolean
   anchor: ReactNode
-  items: readonly MenuItem[]
+  items: readonly MenuEntry[]
   selectedId?: string
   onSelect: (id: string) => void
   onClose: () => void
   align?: 'start' | 'end'
+  side?: 'bottom' | 'top'
   className?: string
 }) {
   const rootRef = useRef<HTMLSpanElement>(null)
+  const [openSubmenuId, setOpenSubmenuId] = useState<string | null>(null)
 
   useEffect(() => {
-    if (!open) return
+    if (!open) {
+      setOpenSubmenuId(null)
+      return
+    }
     const onPointerDown = (e: PointerEvent) => {
       if (rootRef.current && e.target instanceof Node && !rootRef.current.contains(e.target)) onClose()
     }
@@ -59,21 +82,61 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align
     <span ref={rootRef} className={clsx(css.root, className)}>
       {anchor}
       {open && (
-        <div className={clsx(css.list, align === 'end' && css.alignEnd)} role="menu">
-          {items.map(item => (
-            <button
-              key={item.id}
-              type="button"
-              role="menuitem"
-              className={clsx(css.item, item.id === selectedId && css.selected)}
-              disabled={item.disabled}
-              onClick={() => onSelect(item.id)}
-            >
-              <span className={css.itemLabel}>{item.label}</span>
-              {/* Selection marker is a trailing check (figma .Menu_cell), not a fill. */}
-              {item.id === selectedId && <IconCheckOutline16 className={css.check} />}
-            </button>
-          ))}
+        <div className={clsx(css.list, side === 'top' && css.sideTop, align === 'end' && css.alignEnd)} role="menu">
+          {items.map(entry => {
+            if (isSeparator(entry)) {
+              return <div key={entry.id} className={css.separator} role="separator" />
+            }
+            const hasSub = entry.submenu !== undefined && entry.submenu.length > 0
+            const subOpen = hasSub && openSubmenuId === entry.id
+            return (
+              <div
+                key={entry.id}
+                className={css.itemWrap}
+                onMouseEnter={() => { setOpenSubmenuId(hasSub ? entry.id : null) }}
+                onMouseLeave={() => { setOpenSubmenuId(null) }}
+              >
+                <button
+                  type="button"
+                  role="menuitem"
+                  className={clsx(css.item, entry.id === selectedId && css.selected)}
+                  disabled={entry.disabled}
+                  aria-haspopup={hasSub ? 'menu' : undefined}
+                  aria-expanded={hasSub ? subOpen : undefined}
+                  onFocus={() => { setOpenSubmenuId(hasSub ? entry.id : null) }}
+                  onClick={() => {
+                    if (hasSub) {
+                      setOpenSubmenuId(entry.id)
+                      return
+                    }
+                    onSelect(entry.id)
+                  }}
+                >
+                  {entry.icon !== undefined && <span className={css.itemIcon}>{entry.icon}</span>}
+                  <span className={css.itemLabel}>{entry.label}</span>
+                  {/* Selection marker is a trailing check (figma .Menu_cell), not a fill. */}
+                  {entry.id === selectedId && <IconCheckOutline16 className={css.check} />}
+                </button>
+                {subOpen && entry.submenu !== undefined && (
+                  <div className={css.submenu} role="menu">
+                    {entry.submenu.map(sub => (
+                      <button
+                        key={sub.id}
+                        type="button"
+                        role="menuitem"
+                        className={css.item}
+                        disabled={sub.disabled}
+                        onClick={() => { onSelect(sub.id) }}
+                      >
+                        {sub.icon !== undefined && <span className={css.itemIcon}>{sub.icon}</span>}
+                        <span className={css.itemLabel}>{sub.label}</span>
+                      </button>
+                    ))}
+                  </div>
+                )}
+              </div>
+            )
+          })}
         </div>
       )}
     </span>

packages/client/ui-primitives/src/Modal.module.css

@@ -0,0 +1,79 @@
+/* Full-viewport layer (figma Mask + Dialog 451:18655): mask + centered card. */
+.root {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+}
+
+/* User/spec mask: rgba(0,0,0,0.24) + blur(2px) via --dsw-alias-bg-mask-1 /
+   --dsw-mask-blur (light); dark theme raises mask opacity. */
+.mask {
+  position: absolute;
+  inset: 0;
+  background: var(--dsw-alias-bg-mask-1);
+  backdrop-filter: var(--dsw-mask-blur);
+}
+
+/* Dialog card: r24, shadow-lv3, layer-2 fill, inverted border, pb 24. */
+.dialog {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  width: min(380px, 100%);
+  padding: 0 0 24px;
+  overflow: hidden;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 24px;
+  background: var(--dsw-alias-bg-layer-2);
+  box-shadow: var(--dsw-shadow-lv3);
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+/* Header pad (figma Title row): pt 22 / pl 24 / pr 14 / pb 12. */
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 22px 14px 12px 24px;
+}
+
+.title {
+  margin: 0;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.description {
+  margin: 0;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  padding: 0 24px;
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 0 24px;
+}

packages/client/ui-primitives/src/Modal.tsx

@@ -0,0 +1,62 @@
+// Modal: controlled full-viewport dialog (create-workspace and similar).
+// Fixed overlay in the React tree (no react-dom portal) so ui-primitives
+// stays free of a react-dom dependency; mask tokens match figma 451:18655.
+
+import { useEffect } from 'react'
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import css from './Modal.module.css'
+
+/**
+ * Render a centered modal over a blurred page mask.
+ * @param props.open - whether the dialog is showing.
+ * @param props.onClose - Escape or mask click.
+ * @param props.title - dialog heading.
+ * @param props.description - optional supporting sentence under the title.
+ * @param props.children - body (inputs, etc.).
+ * @param props.footer - action row (Cancel / Create).
+ * @returns null when closed; otherwise the overlay tree.
+ */
+export function Modal({ open, onClose, title, description, children, footer, className }: {
+  open: boolean
+  onClose: () => void
+  title: string
+  description?: string
+  children?: ReactNode
+  footer?: ReactNode
+  className?: string
+}) {
+  useEffect(() => {
+    if (!open) return
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKeyDown)
+    return () => { document.removeEventListener('keydown', onKeyDown) }
+  }, [open, onClose])
+
+  if (!open) return null
+
+  return (
+    <div className={css.root} role="presentation">
+      <div className={css.mask} aria-hidden="true" onClick={onClose} />
+      <div
+        className={clsx(css.dialog, className)}
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+      >
+        <div className={css.content}>
+          <div className={css.header}>
+            <h2 className={css.title}>{title}</h2>
+            {description !== undefined && description !== '' && (
+              <p className={css.description}>{description}</p>
+            )}
+          </div>
+          {children !== undefined && <div className={css.body}>{children}</div>}
+        </div>
+        {footer !== undefined && <div className={css.footer}>{footer}</div>}
+      </div>
+    </div>
+  )
+}

packages/client/ui-primitives/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * Pure React atoms (zero cordis): StateDot, icons, Button/Pill/Menu/Input,
+ * Pure React atoms (zero cordis): StateDot, icons, Button/Pill/Menu/Modal/Input,
  * markdown family, ConnectionBanner. Everything consumes props plus --dsw-*
  * token vars only. Contract: api-contracts v3 section 8.
  */
@@ -11,7 +11,8 @@ export type { ButtonVariant } from './Button.tsx'
 export { Pill } from './Pill.tsx'
 export { Input } from './Input.tsx'
 export { Menu } from './Menu.tsx'
-export type { MenuItem } from './Menu.tsx'
+export type { MenuEntry, MenuItem, MenuSeparator } from './Menu.tsx'
+export { Modal } from './Modal.tsx'
 export { ConnectionBanner } from './ConnectionBanner.tsx'
 export { FishLogo } from './FishLogo.tsx'
 export { BrandWordmark } from './BrandWordmark.tsx'

packages/client/ui-primitives/tests/atoms.spec.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { Button, ConnectionBanner, Input, Menu, Pill } from '@deepseek-ai/dsh-client-ui-primitives'
+import { Button, ConnectionBanner, Input, Menu, Modal, Pill } from '@deepseek-ai/dsh-client-ui-primitives'
 
 afterEach(cleanup)
 
@@ -21,6 +21,11 @@ describe('Button', () => {
     fireEvent.click(screen.getByRole('button'))
     expect(onClick).not.toHaveBeenCalled()
   })
+
+  it('outline variant renders a bordered cancel-style button', () => {
+    render(<Button variant="outline">Cancel</Button>)
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeDefined()
+  })
 })
 
 describe('Pill', () => {
@@ -91,11 +96,12 @@ describe('Menu', () => {
     expect(onClose).not.toHaveBeenCalled()
   })
 
-  it('selected item shows the trailing check; align=end and className apply', () => {
+  it('selected item shows the trailing check; align=end, side=top, and className apply', () => {
     const { container } = render(
       <Menu
         open
         align="end"
+        side="top"
         className="x"
         anchor={<span>trigger</span>}
         items={items}
@@ -104,12 +110,89 @@ describe('Menu', () => {
         onClose={() => {}}
       />)
     expect((container.firstElementChild as HTMLElement).classList.contains('x')).toBe(true)
+    const menu = screen.getByRole('menu')
+    expect(menu.className).toMatch(/sideTop|alignEnd/)
     const selected = screen.getByRole('menuitem', { name: 'Alpha' })
     expect(selected.querySelector('svg')).not.toBeNull()
     const other = screen.getByRole('menuitem', { name: 'Beta' })
     expect(other.querySelector('svg')).toBeNull()
     fireEvent.keyDown(document, { key: 'a' })
   })
+
+  it('renders a leading icon and a separator between groups', () => {
+    render(
+      <Menu
+        open
+        anchor={<span>trigger</span>}
+        items={[
+          { id: 'a', label: 'Alpha', icon: <svg data-testid="ic" /> },
+          { type: 'separator', id: 's1' },
+          { id: 'c', label: 'Create' },
+        ]}
+        onSelect={() => {}}
+        onClose={() => {}}
+      />)
+    expect(screen.getByTestId('ic')).toBeDefined()
+    expect(screen.getByRole('separator')).toBeDefined()
+  })
+
+  it('opens a submenu on hover and selects a nested item', () => {
+    const onSelect = vi.fn()
+    render(
+      <Menu
+        open
+        anchor={<span>trigger</span>}
+        items={[
+          { id: 'plain', label: 'Plain' },
+          {
+            id: 'new',
+            label: 'New Workspace',
+            submenu: [
+              { id: 'ok', label: 'Create ok', icon: <svg data-testid="sub-ic" /> },
+            ],
+          },
+        ]}
+        onSelect={onSelect}
+        onClose={() => {}}
+      />)
+    const plain = screen.getByRole('menuitem', { name: 'Plain' })
+    fireEvent.mouseEnter(plain.parentElement as HTMLElement)
+    fireEvent.focus(plain)
+    const parent = screen.getByRole('menuitem', { name: 'New Workspace' })
+    const wrap = parent.parentElement as HTMLElement
+    fireEvent.click(parent)
+    expect(onSelect).not.toHaveBeenCalled()
+    fireEvent.focus(parent)
+    fireEvent.mouseEnter(wrap)
+    expect(screen.getByTestId('sub-ic')).toBeDefined()
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Create ok' }))
+    expect(onSelect).toHaveBeenCalledWith('ok')
+    fireEvent.mouseLeave(wrap)
+    expect(screen.queryByRole('menuitem', { name: 'Create ok' })).toBeNull()
+  })
+})
+
+describe('Modal', () => {
+  it('is absent while closed; Escape and mask click call onClose', () => {
+    const onClose = vi.fn()
+    const { rerender } = render(
+      <Modal open={false} onClose={onClose} title="Create new workspace">body</Modal>)
+    expect(screen.queryByRole('dialog')).toBeNull()
+    rerender(
+      <Modal open onClose={onClose} title="Create new workspace" description="Name it." footer={<button type="button">Create</button>}>
+        <input aria-label="name" />
+      </Modal>)
+    expect(screen.getByRole('dialog', { name: 'Create new workspace' })).toBeDefined()
+    expect(screen.getByText('Name it.')).toBeDefined()
+    fireEvent.keyDown(document, { key: 'a' })
+    expect(onClose).not.toHaveBeenCalled()
+    fireEvent.keyDown(document, { key: 'Escape' })
+    expect(onClose).toHaveBeenCalledTimes(1)
+    // Mask is the presentation sibling behind the dialog.
+    const mask = document.querySelector('[aria-hidden="true"]') as HTMLElement
+    fireEvent.click(mask)
+    expect(onClose).toHaveBeenCalledTimes(2)
+  })
 })
 
 describe('ConnectionBanner', () => {

packages/client/ui-sidebar/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-ui-sidebar
 
-Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Collapse is a slide + crossfade into the layout-owned 56px rail (open / new session / new workspace / search — search expands and focuses the search box — plus the settings foot): the expanded content freezes at its width and fades in place while the column slides over it, then the rail — whale mark resting, panel icon on hover, tooltips on every control — crossfades in at settle as the wide content unmounts. Contract: the [slot system standard](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md).
+Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Top-level New Session / New Workspace clear the selection onto `conversation.empty`; per-project "+" still create-then-opens. Collapse is a slide + crossfade into the layout-owned 56px rail (open / new session / new workspace / search — search expands and focuses the search box — plus the settings foot): the expanded content freezes at its width and fades in place while the column slides over it, then the rail — whale mark resting, panel icon on hover, tooltips on every control — crossfades in at settle as the wide content unmounts. Contract: the [slot system standard](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md).
 
 `src/client/contract/slots.ts` is the single-domain contract file: `SidebarRootInjected` (the registrant's own injected share — plain service callbacks: onOpen/onCreate/onToggleSidebar) and `SidebarRootComponentProps = PropsRuntime<'sidebar'> & SidebarRootInjected` (owner `{collapsed,width}` plus the standard `useSessions` hook, resolved off ui-layout's SlotMap declaration, never re-stated). `apply` registers SidebarRoot cast-free against that composition; the inject factory closes over the plugin's own ctx.
 

packages/client/ui-sidebar/src/client/contract/slots.ts

@@ -25,8 +25,8 @@ export type SidebarRootInjected = {
   /** Open (switch to) a session. */
   onOpen: (id: SessionId) => void
   /**
-   * Create a session and open it; cwd targets a project group (the
-   * sidebar's three creation entries all land in the new session).
+   * New-session affordance: no cwd clears selection onto the empty-state
+   * launch; a cwd create-then-opens a session in that project group.
    */
   onCreate: (cwd?: string) => void
   /** Collapse the sidebar column (layout service action; owner share stays {collapsed,width}). */

packages/client/ui-sidebar/src/client/index.ts

@@ -27,9 +27,15 @@ export function apply(ctx: ClientContext): void {
     // list snapshot); layout keeps only panel geometry.
     onOpen: (id) => { ctx.sessions.open(id) },
     onCreate: (cwd) => {
-      // Create-then-open: the sidebar's three creation entries all land
-      // in the new session (empty-state first-send stays with ui-conversation).
-      void ctx.sessions.create(cwd === undefined ? {} : { cwd })
+      // Top-level New Session / New Workspace: clear selection so AppFrame
+      // shows conversation.empty (EmptyState + shared InputBar). Per-project
+      // "+" still create-then-opens into that cwd until workspace seeding
+      // reaches the empty-state picker.
+      if (cwd === undefined) {
+        ctx.sessions.clear()
+        return
+      }
+      void ctx.sessions.create({ cwd })
         .then((id: SessionId) => { ctx.sessions.open(id) })
     },
     onToggleSidebar: () => { ctx.layout.toggleSidebar() },

packages/client/ui-sidebar/tests/apply.spec.tsx

@@ -26,7 +26,12 @@ async function bench() {
     byId: { [sid('a')]: { id: sid('a'), title: 'alpha', displayTitle: 'alpha', cwd: '/proj', running: false, updatedAt: 1 } },
     current: undefined,
   })
-  const sessions = { list, create: vi.fn(async () => sid('minted')), open: vi.fn() }
+  const sessions = {
+    list,
+    create: vi.fn(async () => sid('minted')),
+    open: vi.fn(),
+    clear: vi.fn(),
+  }
   const layout = { toggleSidebar: vi.fn() }
   ctx.provide('sessions', sessions)
   ctx.provide('layout', layout)
@@ -91,14 +96,15 @@ describe('apply', () => {
     expect(sessions.open).toHaveBeenCalledWith('a')
 
     injected.onCreate()
-    expect(sessions.create).toHaveBeenCalledWith({})
+    expect(sessions.clear).toHaveBeenCalledOnce()
+    expect(sessions.create).not.toHaveBeenCalled()
+
+    injected.onCreate('/proj')
+    expect(sessions.create).toHaveBeenCalledWith({ cwd: '/proj' })
     // create-then-open lands after the create promise resolves.
     await Promise.resolve()
     await Promise.resolve()
     expect(sessions.open).toHaveBeenCalledWith('minted')
-
-    injected.onCreate('/proj')
-    expect(sessions.create).toHaveBeenCalledWith({ cwd: '/proj' })
   })
 
   it('teardown unregisters the slot entry', async () => {

packages/client/ui-theme/src/styles/design-platform.css

@@ -169,6 +169,7 @@ body {
   --dsw-alias-border-l3: rgba(0, 0, 0, 0.12);
   --dsw-alias-border-l4: rgba(0, 0, 0, 0.16);
   --dsw-alias-brand-primary-invert: var(--dsw-static-neutral-bluish-1000);
+  --dsw-alias-brand-primary-new-colorprimary-new-color: rgb(65, 118, 230);
   --dsw-alias-brand-primary: var(--dsw-static-neutral-bluish-1000);
   --dsw-alias-brand-text: var(--dsw-static-neutral-bluish-1000);
   --dsw-alias-button-contrast-fill: var(--dsw-static-neutral-bluish-700);
@@ -217,6 +218,7 @@ body {
   --dsw-alias-state-error-secondary: var(--dsw-static-red-400);
   --dsw-alias-state-success-primary: var(--dsw-static-green-500);
   --dsw-alias-state-success-secondary: var(--dsw-static-green-400);
+  --dsw-alias-state-success-tertiary: var(--dsw-static-green-100);
   --dsw-alias-state-warn-label: var(--dsw-static-amber-600);
   --dsw-alias-state-warn-primary: var(--dsw-static-amber-500);
   --dsw-alias-state-warn-secondary: var(--dsw-static-amber-400);
@@ -257,11 +259,12 @@ body[data-ds-dark-theme] {
   --dsw-alias-border-l3: rgba(255, 255, 255, 0.16);
   --dsw-alias-border-l4: rgba(255, 255, 255, 0.2);
   --dsw-alias-brand-primary-invert: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-brand-primary-new-colorprimary-new-color: var(--dsw-static-deepseek-450);
   --dsw-alias-brand-primary: var(--dsw-static-neutral-bluish-50);
   --dsw-alias-brand-text: var(--dsw-static-neutral-bluish-50);
   --dsw-alias-button-contrast-fill: var(--dsw-static-neutral-bluish-50);
   --dsw-alias-button-elevated-fill: var(--dsw-static-neutral-bluish-750);
-  --dsw-alias-button-floating-fill: var(--dsw-static-neutral-bluish-950);
+  --dsw-alias-button-floating-fill: var(--dsw-static-neutral-bluish-850);
   --dsw-alias-button-floating-hover: var(--dsw-static-neutral-bluish-800);
   --dsw-alias-button-ghost-active-border: var(--dsw-static-neutral-bluish-600);
   --dsw-alias-button-ghost-active-fill: var(--dsw-static-neutral-bluish-750);

packages/client/ui-trajectory/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-ui-trajectory
 
-Trajectory/Waterfall placeholder views; the pure-consumer minimal plugin exemplar (registers two view tabs into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge). Contract: api-contracts v3 §8.
+Trajectory turn-list chrome (sticky Turn / Message·Step groups / step cells) plus Waterfall placeholder; the pure-consumer minimal plugin exemplar (registers two view tabs into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge). Contract: api-contracts v3 §8.
 
 ## Model Experience
 
@@ -12,4 +12,4 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Both views are placeholders by charter** — coarse span derivation with no visual acceptance bar; the real implementations, anchor deep-linking, and span-click selection handoff are the P-III project.
+- **In-flight Time stays blank** — `partial` / `runningCalls` rows render with `—` until a live clock policy lands; selected styling is local-only (not wired to chat details); anchor deep-linking remains deferred.

packages/client/ui-trajectory/src/client/TrajectoryCell.module.css

@@ -0,0 +1,93 @@
+/* Trajectory step cell — 38px row: index · kind tag · text · optional message
+ * metrics · elapsed time. */
+
+.root {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 38px;
+  padding: 0 8px 0 20px;
+  gap: 24px;
+  border-radius: 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  background: var(--dsw-alias-bg-layer-3);
+  min-width: 0;
+}
+
+.selected {
+  border-color: transparent;
+  box-shadow: inset 0 0 0 2px var(--dsw-alias-brand-primary-new-colorprimary-new-color);
+}
+
+.index {
+  flex: none;
+  width: 24px;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.tagSlot {
+  flex: none;
+  width: 80px;
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+.tag {
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 22px;
+  max-width: 100%;
+  padding: 0 4px;
+  border-radius: 6px;
+  font: var(--dsw-font-xs-strong-13);
+  white-space: nowrap;
+}
+
+.tagUser {
+  color: var(--dsw-alias-state-success-primary);
+  background: var(--dsw-alias-state-success-tertiary);
+}
+
+.tagMessage {
+  color: var(--dsw-alias-brand-primary-new-colorprimary-new-color);
+  background: var(--dsw-specific-bubble);
+}
+
+.tagTool {
+  color: var(--dsw-alias-state-warn-label);
+  background: var(--dsw-alias-state-warn-tertiary);
+}
+
+.text {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Same column geometry as TrajectoryTurnHeader: 4×71 + 3×12 = 320. */
+.trailing {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  width: 320px;
+  gap: 12px;
+  min-width: 0;
+}
+
+.metric,
+.time {
+  flex: none;
+  width: 71px;
+  text-align: left;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+  white-space: nowrap;
+}

packages/client/ui-trajectory/src/client/TrajectoryCell.tsx

@@ -0,0 +1,99 @@
+// TrajectoryCell: one step row in the trajectory list — index, kind tag,
+// ellipsis text, optional Message token metrics, and own-duration time.
+
+import type { HTMLAttributes } from 'react'
+import css from './TrajectoryCell.module.css'
+
+/** Closed set of trajectory step kinds (call+result fold into Tool; no Think). */
+export type TrajectoryCellKind = 'user' | 'message' | 'tool'
+
+/** Display label per kind (matches the design tags). */
+const KIND_LABEL: Record<TrajectoryCellKind, string> = {
+  user: 'User',
+  message: 'Message',
+  tool: 'Tool',
+}
+
+const TAG_CLASS: Record<TrajectoryCellKind, string> = {
+  user: css.tagUser!,
+  message: css.tagMessage!,
+  tool: css.tagTool!,
+}
+
+export interface TrajectoryCellProps extends HTMLAttributes<HTMLDivElement> {
+  /** 1-based step index shown as `#N`. */
+  index: number
+  kind: TrajectoryCellKind
+  /** Single-line summary; CSS ellipsis when it overflows. */
+  text: string
+  /**
+   * Own duration in seconds. `null` means no duration to show (em dash) —
+   * used for in-flight tools and tools missing callTime.
+   */
+  timeSeconds: number | null
+  /** Message-only: prompt token count. */
+  input?: number
+  /** Message-only: completion token count. */
+  output?: number
+  /** Message-only: reasoning token count (usage column, not a Think cell). */
+  think?: number
+  /** Selected: 2px inset brand-primary-new-color ring (not wired to chat selection yet). */
+  selected?: boolean
+}
+
+/**
+ * Format own-duration for the trailing time column: `—` when unknown, `+Ns`
+ * or `+N.1s` otherwise.
+ * @param seconds - duration seconds, or null when absent.
+ * @returns display string.
+ */
+export function formatElapsedSeconds(seconds: number | null): string {
+  if (seconds === null || !Number.isFinite(seconds)) return '—'
+  const rounded = Math.round(seconds * 10) / 10
+  if (Number.isInteger(rounded)) return `+${rounded}s`
+  return `+${rounded.toFixed(1)}s`
+}
+
+/**
+ * Render one trajectory step cell.
+ * @param props - index, kind, text, time, and optional Message metrics.
+ * @returns the cell element.
+ */
+export function TrajectoryCell({
+  index,
+  kind,
+  text,
+  timeSeconds,
+  input,
+  output,
+  think,
+  selected = false,
+  className,
+  ...rest
+}: TrajectoryCellProps) {
+  const rootClass = [
+    css.root,
+    selected ? css.selected : undefined,
+    className,
+  ].filter((c): c is string => c !== undefined).join(' ')
+  const showMetrics = kind === 'message'
+  return (
+    <div className={rootClass} data-kind={kind} data-selected={selected || undefined} {...rest}>
+      <span className={css.index}>#{index}</span>
+      <span className={css.tagSlot}>
+        <span className={`${css.tag} ${TAG_CLASS[kind]}`}>{KIND_LABEL[kind]}</span>
+      </span>
+      <span className={css.text}>{text}</span>
+      <span className={css.trailing}>
+        {showMetrics ? (
+          <>
+            <span className={css.metric}>{input ?? ''}</span>
+            <span className={css.metric}>{output ?? ''}</span>
+            <span className={css.metric}>{think ?? ''}</span>
+          </>
+        ) : null}
+        <span className={css.time}>{formatElapsedSeconds(timeSeconds)}</span>
+      </span>
+    </div>
+  )
+}

packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.module.css

@@ -0,0 +1,27 @@
+/* Message / Step group title row inside a turn body. */
+
+.root {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 36px;
+  padding: 0 20px;
+  gap: 24px;
+  min-width: 0;
+}
+
+.title {
+  flex: none;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-primary);
+}
+
+.description {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}

packages/client/ui-trajectory/src/client/TrajectoryGroupHeader.tsx

@@ -0,0 +1,26 @@
+// TrajectoryGroupHeader: "Message" or "Step N" row with optional description.
+
+import css from './TrajectoryGroupHeader.module.css'
+
+export interface TrajectoryGroupHeaderProps {
+  /** Group title (`Message`, `Step 1`, …). */
+  title: string
+  /** Secondary summary (`49s`, `2.2s skill`, …). */
+  description?: string
+}
+
+/**
+ * Render a Message/Step group header inside a turn body.
+ * @param props - title and optional description.
+ * @returns the group header element.
+ */
+export function TrajectoryGroupHeader({ title, description }: TrajectoryGroupHeaderProps) {
+  return (
+    <div className={css.root}>
+      <span className={css.title}>{title}</span>
+      {description !== undefined && description !== ''
+        ? <span className={css.description}>{description}</span>
+        : null}
+    </div>
+  )
+}

packages/client/ui-trajectory/src/client/TrajectoryTurn.module.css

@@ -0,0 +1,16 @@
+/* One turn block: sticky header + padded body with 10px item gap. */
+
+.root {
+  width: 100%;
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 8px 16px 22px;
+}

packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx

@@ -0,0 +1,26 @@
+// TrajectoryTurn: sticky Turn header plus the padded Message/Step body.
+
+import type { ReactNode } from 'react'
+import { TrajectoryTurnHeader } from './TrajectoryTurnHeader.tsx'
+import css from './TrajectoryTurn.module.css'
+
+export interface TrajectoryTurnProps {
+  /** 1-based turn index for the sticky header. */
+  turn: number
+  /** Message / Step headers and TrajectoryCell rows. */
+  children?: ReactNode
+}
+
+/**
+ * Render one turn section (sticky header + body).
+ * @param props - turn index and body children.
+ * @returns the turn section element.
+ */
+export function TrajectoryTurn({ turn, children }: TrajectoryTurnProps) {
+  return (
+    <section className={css.root} data-turn={turn}>
+      <TrajectoryTurnHeader turn={turn} />
+      <div className={css.body}>{children}</div>
+    </section>
+  )
+}

packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.module.css

@@ -0,0 +1,48 @@
+/* Sticky turn bar: full-bleed ghost-active fill across the panel; title +
+ * metric labels sit in a centered 880 content lane (4×71 + 3×12 = 320). */
+
+.root {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  box-sizing: border-box;
+  width: 100%;
+  height: 44px;
+  background: var(--dsw-alias-button-ghost-active-fill);
+}
+
+.inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 880px;
+  height: 100%;
+  margin: 0 auto;
+  padding: 0 16px;
+}
+
+.title {
+  flex: none;
+  font: var(--dsw-font-xs-strong-13);
+  color: var(--dsw-alias-label-primary);
+}
+
+.columns {
+  flex: none;
+  display: flex;
+  align-items: center;
+  width: 320px;
+  gap: 12px;
+  /* Match cell padding-right: 8 so Time lines up with the trailing lane. */
+  margin-right: 8px;
+}
+
+.column {
+  flex: none;
+  width: 71px;
+  text-align: left;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-secondary);
+}

packages/client/ui-trajectory/src/client/TrajectoryTurnHeader.tsx

@@ -0,0 +1,30 @@
+// TrajectoryTurnHeader: sticky per-turn bar with Input/Output/Think/Time labels.
+
+import css from './TrajectoryTurnHeader.module.css'
+
+const COLUMN_LABELS = ['Input', 'Output', 'Think', 'Time'] as const
+
+export interface TrajectoryTurnHeaderProps {
+  /** 1-based turn index shown as `Turn N`. */
+  turn: number
+}
+
+/**
+ * Render the sticky turn header row.
+ * @param props.turn - turn index.
+ * @returns the sticky header element.
+ */
+export function TrajectoryTurnHeader({ turn }: TrajectoryTurnHeaderProps) {
+  return (
+    <div className={css.root}>
+      <div className={css.inner}>
+        <span className={css.title}>Turn {turn}</span>
+        <div className={css.columns} aria-hidden="true">
+          {COLUMN_LABELS.map((label) => (
+            <span key={label} className={css.column}>{label}</span>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}

packages/client/ui-trajectory/src/client/TrajectoryView.tsx

@@ -1,30 +1,40 @@
-// TrajectoryView: P-I placeholder body for the trajectory tab — span stats
-// header over a per-turn span list with node-count weights (no timing data
-// exists yet; deviation ledger #3 defers real rendering to P-III).
+// TrajectoryView: sticky Turn sections with Message/Step groups and step cells.
 
 import { useMemo } from 'react'
 import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { deriveSpans } from './spans.ts'
-import { TrajectoryStatsHeader } from './TrajectoryStatsHeader.tsx'
+import { TrajectoryCell } from './TrajectoryCell.tsx'
+import { TrajectoryGroupHeader } from './TrajectoryGroupHeader.tsx'
+import { TrajectoryTurn } from './TrajectoryTurn.tsx'
+import { deriveTrajectoryLayout } from './layout.ts'
 import css from './views.module.css'
 
 export function TrajectoryView({ useSession }: ConvViewProps) {
   const nodes = useSession((s) => s.nodes)
-  const spans = useMemo(() => deriveSpans(nodes), [nodes])
-  if (spans.length === 0) return <div className={css.root}><p className={css.empty}>暂无轨迹数据</p></div>
+  const partial = useSession((s) => s.partial)
+  const runningCalls = useSession((s) => s.runningCalls)
+  const turns = useMemo(
+    () => deriveTrajectoryLayout({ nodes, partial, runningCalls }),
+    [nodes, partial, runningCalls],
+  )
+  if (turns.length === 0) {
+    return <div className={css.root}><p className={css.empty}>暂无轨迹数据</p></div>
+  }
   return (
-    <>
-      <TrajectoryStatsHeader useSession={useSession} />
-      <div className={css.root}>
-        {spans.map((span) => (
-          <div key={span.turn} className={css.row}>
-            <span className={css.turnTag}>turn {span.turn}</span>
-            <span className={css.meta}>
-              {span.steps} steps · {span.calls} calls · {span.nodes} nodes
-            </span>
-          </div>
-        ))}
-      </div>
-    </>
+    <div className={css.root}>
+      {turns.map((turn) => (
+        <TrajectoryTurn key={turn.turn} turn={turn.turn}>
+          {turn.groups.flatMap((group) => [
+            <TrajectoryGroupHeader
+              key={`${group.title}-h`}
+              title={group.title}
+              {...(group.description !== undefined ? { description: group.description } : {})}
+            />,
+            ...group.cells.map((cell) => (
+              <TrajectoryCell key={cell.index} {...cell} />
+            )),
+          ])}
+        </TrajectoryTurn>
+      ))}
+    </div>
   )
 }

packages/client/ui-trajectory/src/client/index.ts

@@ -24,8 +24,8 @@ export const inject = ['slots', 'conversation']
 /**
  * Client plugin body: register the trajectory and waterfall view tabs. The
  * registrations ride the slot service's effect wrapper (plugin unload
- * removes both tabs); the span stats header renders inside each view body
- * (the chrome attachment mechanism retired with the view ring).
+ * removes both tabs). Trajectory owns its turn list in-body; Waterfall keeps
+ * the span stats header inside its body (chrome attachment retired).
  * @param ctx - client root context.
  */
 export function apply(ctx: Context): void {

packages/client/ui-trajectory/src/client/layout.ts

@@ -0,0 +1,418 @@
+/**
+ * Trajectory list fold: expand assistant blocks, attach usage to Message,
+ * own-duration times, in-flight partial/runningCalls, and group descriptions.
+ */
+import type {
+  AssistantMessageNode,
+  ConversationSnapshot,
+  ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { TrajectoryCellProps } from './TrajectoryCell.tsx'
+
+/** One Message or Step group inside a turn. */
+export interface TrajectoryGroupModel {
+  title: string
+  description?: string
+  cells: readonly TrajectoryCellProps[]
+}
+
+/** One sticky-turn section. */
+export interface TrajectoryTurnModel {
+  turn: number
+  groups: readonly TrajectoryGroupModel[]
+}
+
+/** Snapshot slice the trajectory view folds. */
+export interface TrajectoryLayoutInput {
+  nodes: ConversationSnapshot['nodes']
+  partial: ConversationSnapshot['partial']
+  runningCalls: ConversationSnapshot['runningCalls']
+}
+
+interface UsageLike {
+  inputTokens?: number
+  outputTokens?: number
+  reasoningTokens?: number
+}
+
+/** Cell plus absolute ms for group wall-span descriptions. */
+interface LaidCell {
+  cell: TrajectoryCellProps
+  absTime: number | null
+  toolName?: string
+  callId?: string
+}
+
+/**
+ * Fold a snapshot into turn → Message/Step groups with expanded cells.
+ * @param input - nodes plus in-flight partial/runningCalls.
+ * @returns turns ordered by first appearance.
+ */
+export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly TrajectoryTurnModel[] {
+  const { nodes, partial, runningCalls } = input
+  const resultByCall = indexResults(nodes)
+  const turns = new Map<number, { message: LaidCell[]; steps: Map<number, LaidCell[]> }>()
+  let index = 0
+  let prevAbsTime: number | null = null
+  let lastAssistantTurn: number | null = null
+
+  const bucket = (turn: number) => {
+    let entry = turns.get(turn)
+    if (entry === undefined) {
+      entry = { message: [], steps: new Map() }
+      turns.set(turn, entry)
+    }
+    return entry
+  }
+
+  const pushMessage = (turn: number, laid: LaidCell) => {
+    bucket(turn).message.push(laid)
+  }
+  const pushStep = (turn: number, step: number, laid: LaidCell) => {
+    const steps = bucket(turn).steps
+    const list = steps.get(step) ?? []
+    list.push(laid)
+    steps.set(step, list)
+  }
+
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i]
+    /* v8 ignore next -- dense-array guard: i stays within nodes.length, so the undefined arm needs a sparse array no caller builds. */
+    if (node === undefined) continue
+    if (node.kind === 'user' || node.kind === 'steering') {
+      // user/message has no turn on the wire; enclose it in the next assistant
+      // (or partial) turn, else open the turn after the last assistant.
+      const turn = node.kind === 'steering'
+        ? node.turn
+        : enclosingUserTurn(nodes, i, partial, lastAssistantTurn)
+      pushMessage(turn, {
+        absTime: finiteTime(node.time),
+        cell: {
+          index: ++index, kind: 'user', text: summarizeContent(node.content),
+          timeSeconds: 0,
+        },
+      })
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+      continue
+    }
+    if (node.kind === 'assistant') {
+      const laidList = expandAssistant(node, index + 1, prevAbsTime, resultByCall)
+      for (const laid of laidList) {
+        if (node.step > 0) pushStep(node.turn, node.step, laid)
+        else pushMessage(node.turn, laid)
+      }
+      const last = laidList[laidList.length - 1]
+      if (last !== undefined) index = last.cell.index
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+      lastAssistantTurn = node.turn
+      continue
+    }
+    if (node.kind === 'context') {
+      // No trajectory cell, but the surface still advances the duration cursor.
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+      continue
+    }
+    if (node.kind === 'tool-result') {
+      if (!callEmittedInAssistant(nodes, node.callId)) {
+        const toolName = node.call?.name
+        pushStep(0, 1, {
+          absTime: finiteTime(node.callTime ?? node.time),
+          ...(toolName !== undefined ? { toolName } : {}),
+          callId: node.callId,
+          cell: {
+            index: ++index,
+            kind: 'tool',
+            text: node.call !== null
+              ? summarizeCall(node.call.name, node.call.argsRaw)
+              : summarizeResult(node),
+            timeSeconds: durationSeconds(node.time, node.callTime),
+          },
+        })
+      }
+      prevAbsTime = finiteTime(node.time) ?? prevAbsTime
+    }
+  }
+
+  if (partial !== null) {
+    const fake: AssistantMessageNode = {
+      kind: 'assistant', seq: Number.MAX_SAFE_INTEGER, time: 0,
+      turn: partial.turn, step: partial.step, blocks: partial.blocks,
+    }
+    const laidList = expandAssistant(fake, index + 1, prevAbsTime, resultByCall, { streaming: true })
+    for (const laid of laidList) {
+      if (partial.step > 0) pushStep(partial.turn, partial.step, laid)
+      else pushMessage(partial.turn, laid)
+    }
+    const last = laidList[laidList.length - 1]
+    if (last !== undefined) index = last.cell.index
+  }
+
+  const seenCalls = collectCallIds(turns)
+  for (const call of runningCalls) {
+    if (seenCalls.has(call.callId)) continue
+    pushStep(call.turn, call.step > 0 ? call.step : 1, {
+      absTime: null,
+      toolName: call.name,
+      callId: call.callId,
+      cell: {
+        index: ++index,
+        kind: 'tool',
+        text: summarizeCall(call.name, call.argsRaw),
+        timeSeconds: null,
+      },
+    })
+  }
+
+  // Orphan turn-0 cells (orphaned tools / steering turn 0) fold into Turn 1.
+  const prologue = turns.get(0)
+  if (prologue !== undefined) {
+    turns.delete(0)
+    const emptyTurn = (): { message: LaidCell[]; steps: Map<number, LaidCell[]> } => ({
+      message: [],
+      steps: new Map(),
+    })
+    const first = turns.get(1) ?? emptyTurn()
+    first.message = [...prologue.message, ...first.message]
+    for (const [step, cells] of prologue.steps) {
+      const existing = first.steps.get(step) ?? []
+      first.steps.set(step, [...cells, ...existing])
+    }
+    turns.set(1, first)
+  }
+
+  return [...turns.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([turn, entry]) => toTurnModel(turn, entry))
+}
+
+function toTurnModel(
+  turn: number,
+  entry: { message: LaidCell[]; steps: Map<number, LaidCell[]> },
+): TrajectoryTurnModel {
+  const groups: TrajectoryGroupModel[] = []
+  if (entry.message.length > 0) {
+    const description = groupDescription(entry.message)
+    groups.push({
+      title: 'Message',
+      ...(description !== undefined ? { description } : {}),
+      cells: entry.message.map(l => l.cell),
+    })
+  }
+  for (const step of [...entry.steps.keys()].sort((a, b) => a - b)) {
+    const laid = entry.steps.get(step) ?? []
+    const description = groupDescription(laid)
+    groups.push({
+      title: `Step ${step}`,
+      ...(description !== undefined ? { description } : {}),
+      cells: laid.map(l => l.cell),
+    })
+  }
+  return { turn, groups }
+}
+
+/** Wall-span duration + tool histogram, e.g. `1.5s bash×6`. */
+function groupDescription(laid: readonly LaidCell[]): string | undefined {
+  const parts: string[] = []
+  // Tool rows contribute start (absTime) and end (start + own duration) so a
+  // single Tool cell still spans call→result for the group wall clock.
+  const times: number[] = []
+  for (const l of laid) {
+    if (l.absTime === null || !Number.isFinite(l.absTime)) continue
+    times.push(l.absTime)
+    if (l.cell.kind === 'tool' && l.cell.timeSeconds !== null && Number.isFinite(l.cell.timeSeconds)) {
+      times.push(l.absTime + l.cell.timeSeconds * 1000)
+    }
+  }
+  if (times.length >= 2) {
+    const span = formatGroupDuration((Math.max(...times) - Math.min(...times)) / 1000)
+    if (span !== undefined) parts.push(span)
+  } else if (times.length === 1) {
+    const own = laid.find(l => l.absTime === times[0])?.cell.timeSeconds
+    const span = own !== null && own !== undefined ? formatGroupDuration(own) : undefined
+    if (span !== undefined) parts.push(span)
+  }
+  const tools = new Map<string, number>()
+  for (const l of laid) {
+    if (l.toolName === undefined || l.cell.kind !== 'tool') continue
+    tools.set(l.toolName, (tools.get(l.toolName) ?? 0) + 1)
+  }
+  for (const [name, count] of tools) {
+    parts.push(count > 1 ? `${name}×${count}` : name)
+  }
+  return parts.length === 0 ? undefined : parts.join(' ')
+}
+
+function formatGroupDuration(seconds: number): string | undefined {
+  if (!Number.isFinite(seconds)) return undefined
+  const rounded = Math.round(seconds * 10) / 10
+  if (Number.isInteger(rounded)) return `${rounded}s`
+  return `${rounded.toFixed(1)}s`
+}
+
+/** Own-duration seconds from two epoch-ms stamps; null when either is unusable. */
+function durationSeconds(later: number, earlier: number | null): number | null {
+  if (earlier === null || !Number.isFinite(later) || !Number.isFinite(earlier)) return null
+  return Math.max(0, (later - earlier) / 1000)
+}
+
+/** Epoch-ms usable as an absolute time, else null. */
+function finiteTime(time: number): number | null {
+  return Number.isFinite(time) ? time : null
+}
+
+function expandAssistant(
+  node: AssistantMessageNode,
+  startIndex: number,
+  prevAbsTime: number | null,
+  results: Map<string, ToolResultNode>,
+  opts?: { streaming?: boolean },
+): LaidCell[] {
+  const out: LaidCell[] = []
+  let index = startIndex - 1
+  const usage = node.usage as UsageLike | undefined
+  const streaming = opts?.streaming === true
+  const messageDuration = streaming ? null : durationSeconds(node.time, prevAbsTime)
+  const nodeAbs = streaming ? null : finiteTime(node.time)
+  let usageAttached = false
+
+  for (const block of node.blocks) {
+    // Reasoning blocks are skipped: no block-level clock, so no Think cell.
+    if (block.kind === 'reasoning') continue
+    if (block.kind === 'text') {
+      if (block.text === '' && streaming) continue
+      const cell: TrajectoryCellProps = {
+        index: ++index, kind: 'message', text: summarizeText(block.text),
+        timeSeconds: messageDuration,
+      }
+      if (!usageAttached) {
+        attachUsage(cell, usage)
+        usageAttached = usage !== undefined
+      }
+      out.push({ absTime: nodeAbs, cell })
+      continue
+    }
+    if (block.kind === 'tool-call') {
+      const result = results.get(block.callId)
+      const toolDuration = streaming || result === undefined
+        ? null
+        : durationSeconds(result.time, result.callTime)
+      const callAbs = streaming
+        ? null
+        : (result?.callTime !== null && result?.callTime !== undefined && Number.isFinite(result.callTime)
+          ? result.callTime
+          : nodeAbs)
+      out.push({
+        absTime: callAbs,
+        toolName: block.name,
+        callId: block.callId,
+        cell: {
+          index: ++index, kind: 'tool',
+          text: summarizeCall(block.name, block.argsRaw),
+          timeSeconds: toolDuration,
+        },
+      })
+    }
+  }
+
+  if (out.length === 0 && !streaming) {
+    // Reasoning-only / empty success still owns provider usage on the Message row.
+    const cell: TrajectoryCellProps = {
+      index: ++index, kind: 'message', text: '', timeSeconds: messageDuration,
+    }
+    attachUsage(cell, usage)
+    out.push({ absTime: nodeAbs, cell })
+  }
+  return out
+}
+
+/**
+ * Turn that encloses a user/message: next assistant/steering turn, else the
+ * in-flight partial, else the turn after the last finalized assistant (or 1).
+ */
+function enclosingUserTurn(
+  nodes: ConversationSnapshot['nodes'],
+  userIndex: number,
+  partial: ConversationSnapshot['partial'],
+  lastAssistantTurn: number | null,
+): number {
+  for (let i = userIndex + 1; i < nodes.length; i++) {
+    const n = nodes[i]
+    /* v8 ignore next -- dense-array guard: i stays within nodes.length, so the undefined arm needs a sparse array no caller builds. */
+    if (n === undefined) continue
+    if (n.kind === 'assistant' || n.kind === 'steering') return n.turn
+  }
+  if (partial !== null) return partial.turn
+  if (lastAssistantTurn !== null) return lastAssistantTurn + 1
+  return 1
+}
+
+/** Copy provider usage onto a Message cell when present. */
+function attachUsage(cell: TrajectoryCellProps, usage: UsageLike | undefined): void {
+  if (usage === undefined) return
+  if (usage.inputTokens !== undefined) cell.input = usage.inputTokens
+  if (usage.outputTokens !== undefined) cell.output = usage.outputTokens
+  if (usage.reasoningTokens !== undefined) cell.think = usage.reasoningTokens
+}
+
+function indexResults(nodes: ConversationSnapshot['nodes']): Map<string, ToolResultNode> {
+  const map = new Map<string, ToolResultNode>()
+  for (const node of nodes) {
+    if (node.kind === 'tool-result') map.set(node.callId, node)
+  }
+  return map
+}
+
+function callEmittedInAssistant(nodes: ConversationSnapshot['nodes'], callId: string): boolean {
+  for (const node of nodes) {
+    if (node.kind !== 'assistant') continue
+    if (node.blocks.some(b => b.kind === 'tool-call' && b.callId === callId)) return true
+  }
+  return false
+}
+
+function collectCallIds(
+  turns: Map<number, { message: LaidCell[]; steps: Map<number, LaidCell[]> }>,
+): Set<string> {
+  const ids = new Set<string>()
+  for (const entry of turns.values()) {
+    for (const laid of entry.message) {
+      if (laid.callId !== undefined) ids.add(laid.callId)
+    }
+    for (const list of entry.steps.values()) {
+      for (const laid of list) {
+        if (laid.callId !== undefined) ids.add(laid.callId)
+      }
+    }
+  }
+  return ids
+}
+
+function summarizeCall(name: string, argsRaw: string): string {
+  const args = argsRaw.replace(/\s+/g, ' ').trim()
+  if (args === '') return name
+  const clipped = args.length > 72 ? `${args.slice(0, 71)}…` : args
+  return `${name} · ${clipped}`
+}
+
+function summarizeResult(node: ToolResultNode): string {
+  if (node.isError) {
+    return node.error?.code ?? 'error'
+  }
+  for (const block of node.content) {
+    if (block.type === 'text' && typeof block.text === 'string' && block.text !== '') {
+      return summarizeText(block.text)
+    }
+  }
+  return node.call?.name ?? node.callId
+}
+
+function summarizeContent(content: readonly { type: string; text?: string }[]): string {
+  for (const block of content) {
+    if (block.type === 'text' && typeof block.text === 'string') return summarizeText(block.text)
+  }
+  return ''
+}
+
+function summarizeText(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}

packages/client/ui-trajectory/src/client/views.module.css

@@ -1,25 +1,34 @@
+/* Full-bleed scroll host so Turn sticky bars can paint edge-to-edge;
+ * cell content width is capped on the turn body (max 880). */
 .root {
-  padding: 16px;
   overflow-y: auto;
+  height: 100%;
+  min-height: 0;
+  width: 100%;
+  box-sizing: border-box;
   color: var(--dsw-alias-label-primary);
-  font-size: 13px;
+  background: var(--dsw-specific-sidebar-fill);
 }
 
 .empty {
+  padding: 16px;
   color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xs-13);
 }
 
+/* Waterfall placeholder rows (shared module). */
 .row {
   display: flex;
   align-items: center;
   gap: 8px;
-  padding: 4px 0;
+  padding: 4px 16px;
 }
 
 .turnTag {
   flex: none;
   width: 64px;
   color: var(--dsw-alias-label-secondary);
+  font: var(--dsw-font-xs-13);
 }
 
 .bar {
@@ -29,9 +38,10 @@
 }
 
 .barCalls {
-  background: var(--dsw-alias-brand-primary);
+  background: var(--dsw-alias-brand-primary-new-colorprimary-new-color);
 }
 
 .meta {
   color: var(--dsw-alias-label-caption);
+  font: var(--dsw-font-xs-13);
 }

packages/client/ui-trajectory/tests/cell.spec.tsx

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+/**
+ * TrajectoryCell presentation: kind tags, ellipsis-hosting text, Message
+ * metric columns, own-duration formatting, and selected ring.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import {
+  formatElapsedSeconds,
+  TrajectoryCell,
+  type TrajectoryCellKind,
+} from '../src/client/TrajectoryCell.tsx'
+
+afterEach(cleanup)
+
+describe('formatElapsedSeconds', () => {
+  it('formats known durations and uses an em dash when absent', () => {
+    expect(formatElapsedSeconds(null)).toBe('—')
+    expect(formatElapsedSeconds(235)).toBe('+235s')
+    expect(formatElapsedSeconds(235.0)).toBe('+235s')
+    expect(formatElapsedSeconds(235.2)).toBe('+235.2s')
+    expect(formatElapsedSeconds(235.25)).toBe('+235.3s')
+    expect(formatElapsedSeconds(0)).toBe('+0s')
+    expect(formatElapsedSeconds(Number.NaN)).toBe('—')
+  })
+})
+
+describe('TrajectoryCell', () => {
+  it('renders index, kind tag, text, and time for a Tool row', () => {
+    render(
+      <TrajectoryCell
+        index={6}
+        kind="tool"
+        text="bash · Read src/index.ts"
+        timeSeconds={5}
+      />,
+    )
+    expect(screen.getByText('#6')).toBeTruthy()
+    expect(screen.getByText('Tool')).toBeTruthy()
+    expect(screen.getByText('bash · Read src/index.ts')).toBeTruthy()
+    expect(screen.getByText('+5s')).toBeTruthy()
+  })
+
+  it('Message rows expose Input / Output / Think metric columns before time', () => {
+    const { container } = render(
+      <TrajectoryCell
+        index={3}
+        kind="message"
+        text="Let me now read the actual source files to understa..."
+        timeSeconds={235.2}
+        input={136}
+        output={381}
+        think={155}
+      />,
+    )
+    expect(screen.getByText('Message')).toBeTruthy()
+    expect(screen.getByText('136')).toBeTruthy()
+    expect(screen.getByText('381')).toBeTruthy()
+    expect(screen.getByText('155')).toBeTruthy()
+    expect(screen.getByText('+235.2s')).toBeTruthy()
+    const texts = [...container.querySelectorAll('span')].map((el) => el.textContent)
+    expect(texts.indexOf('136')).toBeLessThan(texts.indexOf('381'))
+    expect(texts.indexOf('381')).toBeLessThan(texts.indexOf('155'))
+    expect(texts.indexOf('155')).toBeLessThan(texts.indexOf('+235.2s'))
+  })
+
+  it('selected marks the row for the brand-primary inset ring', () => {
+    const { container } = render(
+      <TrajectoryCell index={15} kind="message" text="pictur..." timeSeconds={123.6} selected />,
+    )
+    expect(container.firstElementChild?.getAttribute('data-selected')).toBe('true')
+  })
+
+  it.each([
+    ['user', 'User'],
+    ['tool', 'Tool'],
+  ] as const)('kind %s shows the %s tag and no metric columns', (kind: TrajectoryCellKind, label: string) => {
+    const { container } = render(
+      <TrajectoryCell index={1} kind={kind} text="summary" timeSeconds={kind === 'user' ? 0 : null} input={1} output={2} think={3} />,
+    )
+    expect(screen.getByText(label)).toBeTruthy()
+    expect(container.querySelector('[data-kind]')?.getAttribute('data-kind')).toBe(kind)
+    expect(screen.queryByText('1')).toBeNull()
+    expect(screen.queryByText('2')).toBeNull()
+    expect(screen.queryByText('3')).toBeNull()
+  })
+})

packages/client/ui-trajectory/tests/layout.spec.tsx

@@ -0,0 +1,206 @@
+// @vitest-environment jsdom
+/**
+ * Trajectory turn chrome and layout fold: expand blocks, usage on Message,
+ * tool own-duration, group wall-span descriptions, in-flight rows.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import { TrajectoryGroupHeader } from '../src/client/TrajectoryGroupHeader.tsx'
+import { TrajectoryTurn } from '../src/client/TrajectoryTurn.tsx'
+import { TrajectoryTurnHeader } from '../src/client/TrajectoryTurnHeader.tsx'
+import { deriveTrajectoryLayout } from '../src/client/layout.ts'
+
+afterEach(cleanup)
+
+describe('TrajectoryTurnHeader', () => {
+  it('renders Turn N and the four metric column labels', () => {
+    render(<TrajectoryTurnHeader turn={1} />)
+    expect(screen.getByText('Turn 1')).toBeTruthy()
+    expect(screen.getByText('Input')).toBeTruthy()
+    expect(screen.getByText('Output')).toBeTruthy()
+    expect(screen.getByText('Think')).toBeTruthy()
+    expect(screen.getByText('Time')).toBeTruthy()
+  })
+})
+
+describe('TrajectoryGroupHeader', () => {
+  it('renders title and optional description', () => {
+    render(<TrajectoryGroupHeader title="Step 1" description="2.2s skill" />)
+    expect(screen.getByText('Step 1')).toBeTruthy()
+    expect(screen.getByText('2.2s skill')).toBeTruthy()
+  })
+
+  it('omits the description node when absent', () => {
+    const { container } = render(<TrajectoryGroupHeader title="Message" />)
+    expect(screen.getByText('Message')).toBeTruthy()
+    expect(container.querySelectorAll('span')).toHaveLength(1)
+  })
+})
+
+describe('TrajectoryTurn', () => {
+  it('wraps a sticky header and body children', () => {
+    render(
+      <TrajectoryTurn turn={3}>
+        <TrajectoryGroupHeader title="Message" description="49s" />
+      </TrajectoryTurn>,
+    )
+    expect(screen.getByText('Turn 3')).toBeTruthy()
+    expect(screen.getByText('Message')).toBeTruthy()
+    expect(screen.getByText('49s')).toBeTruthy()
+  })
+})
+
+describe('deriveTrajectoryLayout', () => {
+  it('expands assistant blocks, hangs usage on Message, and folds call+result into Tool', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'hello' }], source: null },
+      {
+        kind: 'assistant', seq: 2, time: 6_000, turn: 1, step: 1,
+        blocks: [
+          { kind: 'reasoning', text: 'thinking…' },
+          { kind: 'text', text: 'I will run bash' },
+          { kind: 'tool-call', callId: 'c1', name: 'bash', argsRaw: '{"command":"ls"}' },
+        ],
+        usage: { inputTokens: 10, outputTokens: 20, reasoningTokens: 5 },
+      },
+      {
+        kind: 'tool-result', seq: 3, time: 7_500, callId: 'c1',
+        call: { name: 'bash', argsRaw: '{"command":"ls"}' }, callTime: 6_200,
+        content: [{ type: 'text', text: 'a.txt' }], isError: false, callView: null, resultView: null,
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    expect(turns).toHaveLength(1)
+    expect(turns[0]?.turn).toBe(1)
+    const kinds = turns[0]?.groups.flatMap((g) => g.cells.map((c) => c.kind))
+    expect(kinds).toEqual(['user', 'message', 'tool'])
+    const message = turns[0]?.groups.flatMap((g) => g.cells).find((c) => c.kind === 'message')
+    expect(message).toMatchObject({
+      input: 10, output: 20, think: 5, timeSeconds: 5,
+    })
+    const tool = turns[0]?.groups.flatMap((g) => g.cells).find((c) => c.kind === 'tool')
+    expect(tool?.text).toBe('bash · {"command":"ls"}')
+    expect(tool?.timeSeconds).toBe(1.3)
+  })
+
+  it('adds runningCalls not already present and leaves their time blank', () => {
+    const turns = deriveTrajectoryLayout({
+      nodes: [] as unknown as ConversationSnapshot['nodes'],
+      partial: null,
+      runningCalls: [{
+        callId: 'r1', name: 'bash', argsRaw: '{"command":"pwd"}',
+        turn: 1, step: 2, time: 9_000, callView: null,
+      }],
+    })
+    expect(turns[0]?.groups.map((g) => g.title)).toEqual(['Step 2'])
+    expect(turns[0]?.groups[0]?.cells[0]).toMatchObject({
+      kind: 'tool', text: 'bash · {"command":"pwd"}', timeSeconds: null,
+    })
+  })
+
+  it('omits duration when node times are missing instead of rendering NaN', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, content: [{ type: 'text', text: 'hi' }], source: null },
+      {
+        kind: 'assistant', seq: 2, turn: 1, step: 1,
+        blocks: [
+          { kind: 'reasoning', text: '…' },
+          { kind: 'text', text: 'ok' },
+        ],
+        usage: { inputTokens: 1, outputTokens: 2, reasoningTokens: 3 },
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    const cells = turns[0]?.groups.flatMap((g) => g.cells) ?? []
+    expect(cells.find((c) => c.kind === 'message')?.timeSeconds).toBeNull()
+    expect(turns[0]?.groups.find((g) => g.title === 'Step 1')?.description).toBeUndefined()
+  })
+
+  it('builds a wall-span step description with a tool histogram', () => {
+    const nodes = [
+      {
+        kind: 'assistant', seq: 1, time: 1_000, turn: 1, step: 1,
+        blocks: [
+          { kind: 'tool-call', callId: 'a', name: 'bash', argsRaw: '{}' },
+          { kind: 'tool-call', callId: 'b', name: 'bash', argsRaw: '{}' },
+        ],
+      },
+      {
+        kind: 'tool-result', seq: 2, time: 2_500, callId: 'a',
+        call: { name: 'bash', argsRaw: '{}' }, callTime: 1_100,
+        content: [], isError: false, callView: null, resultView: null,
+      },
+      {
+        kind: 'tool-result', seq: 3, time: 4_000, callId: 'b',
+        call: { name: 'bash', argsRaw: '{}' }, callTime: 2_600,
+        content: [], isError: false, callView: null, resultView: null,
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    expect(turns[0]?.groups[0]?.description).toBe('2.9s bash×2')
+  })
+
+  it('assigns each user message to its enclosing turn instead of pooling into Turn 1', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'first' }], source: null },
+      {
+        kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 0,
+        blocks: [{ kind: 'text', text: 'ok1' }],
+      },
+      { kind: 'user', seq: 3, time: 3_000, content: [{ type: 'text', text: 'second' }], source: null },
+      {
+        kind: 'assistant', seq: 4, time: 4_000, turn: 2, step: 0,
+        blocks: [{ kind: 'text', text: 'ok2' }],
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    expect(turns.map((t) => t.turn)).toEqual([1, 2])
+    expect(turns[0]?.groups.flatMap((g) => g.cells.map((c) => c.text))).toEqual(['first', 'ok1'])
+    expect(turns[1]?.groups.flatMap((g) => g.cells.map((c) => c.text))).toEqual(['second', 'ok2'])
+  })
+
+  it('keeps usage on the fallback Message row when assistant has no text block', () => {
+    const nodes = [
+      {
+        kind: 'assistant', seq: 1, time: 5_000, turn: 1, step: 0,
+        blocks: [{ kind: 'reasoning', text: '…' }],
+        usage: { inputTokens: 11, outputTokens: 22, reasoningTokens: 3 },
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    const message = turns[0]?.groups.flatMap((g) => g.cells).find((c) => c.kind === 'message')
+    expect(message).toMatchObject({
+      text: '', input: 11, output: 22, think: 3,
+    })
+  })
+
+  it('advances the duration cursor over context nodes', () => {
+    const nodes = [
+      { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'hi' }], source: null },
+      {
+        kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 1,
+        blocks: [{ kind: 'tool-call', callId: 'c1', name: 'bash', argsRaw: '{}' }],
+      },
+      {
+        kind: 'tool-result', seq: 3, time: 3_000, callId: 'c1',
+        call: { name: 'bash', argsRaw: '{}' }, callTime: 2_100,
+        content: [], isError: false, callView: null, resultView: null,
+      },
+      {
+        kind: 'context', seq: 4, time: 9_000,
+        content: [{ type: 'text', text: 'extra' }], source: null,
+      },
+      {
+        kind: 'assistant', seq: 5, time: 10_000, turn: 1, step: 0,
+        blocks: [{ kind: 'text', text: 'done' }],
+      },
+    ] as unknown as ConversationSnapshot['nodes']
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
+    const message = turns[0]?.groups
+      .flatMap((g) => g.cells)
+      .find((c) => c.kind === 'message' && c.text === 'done')
+    // From context at 9s, not from the earlier user/tool surfaces.
+    expect(message?.timeSeconds).toBe(1)
+  })
+})

packages/client/ui-trajectory/tests/views.spec.tsx

@@ -3,9 +3,9 @@
  * View registration acceptance on the real framework stack: the plugin fiber
  * registers trajectory/waterfall into a real SlotsService view ring, tabs
  * switch inside ConversationRoot (renderSlot share driven by the same tab
- * projection apply uses) without collapsing chat, the span stats header
- * renders inside both view bodies, and fiber disposal removes both tabs.
- * Span derivation edge cases ride along.
+ * projection apply uses) without collapsing chat, trajectory renders the
+ * turn-list chrome (no span stats bar), waterfall keeps in-body stats, and
+ * fiber disposal removes both tabs. Span derivation edge cases ride along.
  */
 import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -36,19 +36,26 @@ afterEach(cleanup)
 // The chat store persists under its declared key; clear so one case's active
 // view cannot rehydrate into the next.
 beforeEach(() => {
-  localStorage.clear()
+  // Node 22+ exposes an experimental localStorage global that is undefined
+  // without --localstorage-file; only clear when a real Storage is present.
+  if (typeof localStorage !== 'undefined') localStorage.clear()
 })
 
 /** Node fixture: user prologue, two turns, one tool result inside turn 1. */
 const NODES = [
-  { kind: 'user', seq: 1, content: [], source: null },
-  { kind: 'assistant', seq: 2, turn: 1, step: 1, blocks: [] },
-  { kind: 'tool-result', seq: 3, callId: 'c1', call: null, content: [], isError: false, callView: null, resultView: null },
-  { kind: 'assistant', seq: 4, turn: 2, step: 1, blocks: [] },
+  { kind: 'user', seq: 1, time: 1_000, content: [], source: null },
+  { kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 1, blocks: [] },
+  {
+    kind: 'tool-result', seq: 3, time: 3_000, callId: 'c1', call: null, callTime: null,
+    content: [], isError: false, callView: null, resultView: null,
+  },
+  { kind: 'assistant', seq: 4, time: 4_000, turn: 2, step: 1, blocks: [] },
 ] as unknown as ConversationSnapshot['nodes']
 
 function fakeSession(nodes: ConversationSnapshot['nodes']) {
-  const store = createSnapshotStore<{ nodes: ConversationSnapshot['nodes'] }>({ nodes })
+  const store = createSnapshotStore({
+    nodes, partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'],
+  })
   return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession<ConversationSnapshot> }
 }
 
@@ -99,8 +106,9 @@ function tabsOf(slots: SlotsService): ViewTab[] {
 
 /** Mount ConversationRoot over the ring ledger with an outlet-faithful renderSlot. */
 function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES) {
-  const sessionSnapshot = createSnapshotStore<{ running: boolean; removed: boolean; promptError: null; nodes: ConversationSnapshot['nodes'] }>({
+  const sessionSnapshot = createSnapshotStore({
     running: false, removed: false, promptError: null, nodes,
+    partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'],
   })
   const useSession = bindSnapshotSelector(sessionSnapshot) as unknown as UseSession<ConversationSnapshot>
   const chat = createChatStore().create()
@@ -158,17 +166,20 @@ describe('plugin registration', () => {
 })
 
 describe('tab switching in ConversationRoot', () => {
-  it('renders all three tabs, defaults to chat, and switches to trajectory with its header stats', async () => {
+  it('renders all three tabs, defaults to chat, and switches to trajectory without stats chrome', async () => {
     const b = await bench()
     mount(b.slots)
     expect(screen.getByTestId('chat-body')).toBeTruthy()
     expect(screen.getAllByRole('tab').map((t) => t.textContent)).toEqual(['Chat', 'Trajectory', 'Waterfall'])
 
     fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
-    // In-body header stats over NODES: turns 0/1/2, 2 assistant steps, 1 tool call.
-    expect(screen.getByText('3 turns · 2 steps · 1 tool calls')).toBeTruthy()
-    expect(screen.getByText('turn 0')).toBeTruthy()
-    expect(screen.getByText('1 steps · 1 calls · 2 nodes')).toBeTruthy()
+    // Trajectory no longer mounts the span stats bar; the turn-list chrome owns the body.
+    expect(screen.queryByText(/turns ·/)).toBeNull()
+    expect(screen.getByText('Turn 1')).toBeTruthy()
+    expect(screen.getByText('Turn 2')).toBeTruthy()
+    expect(screen.getAllByText('Message').length).toBeGreaterThan(0)
+    expect(screen.getAllByText('Step 1').length).toBeGreaterThan(0)
+    expect(screen.getAllByText('Input').length).toBeGreaterThan(0)
     expect(screen.queryByTestId('chat-body')).toBeNull()
   })
 

packages/compact/compact-basic/tests/compact-basic.spec.ts

@@ -563,7 +563,10 @@ describe('pressure measurement and retention', () => {
     const result = await compactIfNeeded(compact, session)
     expect(result).not.toBeNull()
     expect(prefix).toHaveLength(1)
-    expect(session.events.some(event => event.type === 'context/message')).toBe(false)
+    // The routed request prefix must not reach the surface as its own message
+    // (the compaction summary itself is an expected plugin-sourced checkpoint).
+    expect(session.events.some(event => event.type === 'user/message'
+      && event.data.content.some(block => block.type === 'text' && block.text.includes('p'.repeat(600))))).toBe(false)
   })
 
   it('uses the latest logged request envelope without an AgentOptions override', async () => {
@@ -959,7 +962,7 @@ describe('compaction region transaction', () => {
     const compact = service()
     const session = conversation(2)
     compact.mutateDuringSummary = () => {
-      session.append('context/message', {
+      session.append('user/message', {
         content: [{ type: 'text', text: 'concurrent surface mutation' }],
         source: { kind: 'plugin', plugin: 'test' },
       }, { surfaceOp: 'append' })

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -197,7 +197,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
         provider: 'unconfigured-agent-fallback',
         model: 'unconfigured-agent-fallback',
       })
-      agent.send([{ type: 'text', text: 'do a routed multi-step task' }])
+      agent.followup([{ type: 'text', text: 'do a routed multi-step task' }])
       await waitForIdle(ctx, agent)
 
       expect(agent.session.requestHeader()?.config.model).toBe('mock')
@@ -215,7 +215,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
     const { ctx } = await harness(8)
     try {
       const agent = ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'do tool work' }])
+      agent.followup([{ type: 'text', text: 'do tool work' }])
       await waitForIdle(ctx, agent)
 
       const events = [...agent.session.events]
@@ -241,7 +241,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
     const { ctx } = await harness(8)
     try {
       const agent = ctx.agentLoop.create(SessionId('repro'), { provider: 'mock', model: 'mock' })
-      agent.send([{ type: 'text', text: 'do a long multi-step task' }])
+      agent.followup([{ type: 'text', text: 'do a long multi-step task' }])
       await waitForIdle(ctx, agent)
 
       const events = [...agent.session.events]
@@ -297,7 +297,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
         })
         seedOverflowHistory(agent)
 
-        agent.send([{ type: 'text', text: 'continue from history' }])
+        agent.followup([{ type: 'text', text: 'continue from history' }])
         await agent.whenIdle()
 
         expect(adapter.conversationRequests).toHaveLength(2)
@@ -360,7 +360,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
     try {
       const agent = ctx.agentLoop.create(SessionId('alternating-recovery'), { provider: 'mock', model: 'mock' })
       seedOverflowHistory(agent)
-      agent.send([{ type: 'text', text: 'continue from history' }])
+      agent.followup([{ type: 'text', text: 'continue from history' }])
       await agent.whenIdle()
 
       expect(adapter.conversationRequests).toHaveLength(3)

packages/compact/compact/README.md

@@ -33,7 +33,7 @@ The private per-session cache is keyed by `session.surface.replaceGeneration` an
 
 ## Surface contract
 
-`SurfaceEventType` is a closed union — only `user/message`, `assistant/message`, `tool/result`, `context/message`, and `steering/message` may carry `surfaceOp`. A `compact/*` event therefore **cannot** appear on the surface. A successful compaction instead:
+`SurfaceEventType` is a closed union — only `user/message`, `assistant/message`, `tool/result`, and `steering/message` may carry `surfaceOp`. A `compact/*` event therefore **cannot** appear on the surface. A successful compaction instead:
 
 1. appends `compact/start` (log-only) — acquires the lock,
 2. summarizes the range,

packages/compact/compact/tests/tool-pairing.spec.ts

@@ -96,23 +96,23 @@ describe('tool-pairing boundaries', () => {
       content: [{ type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }],
       provenance: { provider: 'mock', model: 'mock' },
     }, SURFACE)
-    midStep.append('context/message', {
+    midStep.append('user/message', {
       content: [{ type: 'text', text: 'background update' }],
       source: { kind: 'plugin', plugin: 'test' },
     }, SURFACE)
     midStep.append('tool/result', {
       turn: 1, step: 1, callId: CallId('c1'), content: [], isError: false,
     }, SURFACE)
-    expect(before(midStep, 'context/message')).toBe(false)
-    expect(after(midStep, 'context/message')).toBe(false)
+    expect(before(midStep, 'user/message')).toBe(false)
+    expect(after(midStep, 'user/message')).toBe(false)
 
     const free = new Session(SessionId('neutral-free'))
-    free.append('context/message', {
+    free.append('user/message', {
       content: [{ type: 'text', text: 'idle injection' }],
       source: { kind: 'user' },
     }, SURFACE)
-    expect(before(free, 'context/message')).toBe(true)
-    expect(after(free, 'context/message')).toBe(true)
+    expect(before(free, 'user/message')).toBe(true)
+    expect(after(free, 'user/message')).toBe(true)
   })
 })
 

packages/context/session-reference/README.md

@@ -5,7 +5,7 @@
 ## Public API
 
 - `listCandidates(agent, query?, limit?)` lists sessions other than `agent.id`, filters case-insensitively by id or cwd, and ranks same-cwd, cwd-less, then other-cwd records while preserving `listSessions()` creation order within each group. Each selected candidate uses its latest log-backed title as the mention label and falls back to the session id; titles and message bodies are not searched.
-- `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated `HookContext`. Any invalid reference, failed read, cancellation, or budget failure rejects before the host calls `send()` or `steer()`.
+- `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated `HookContext`. Any invalid reference, failed read, cancellation, or budget failure rejects before the host calls `followup()` or `steer()`.
 - `encodeSessionReferenceUri()` and `decodeSessionReferenceUri()` implement `dsh-session:<base64url(JSON.stringify(sessionId))>` so every JavaScript string id round-trips exactly. `formatSessionReferenceMention()` emits `@[label](uri)`, and `parseSessionReferenceText()` replaces Markdown mentions or bare canonical URIs with readable `@label` text while returning structured references. Explicit Markdown mentions reject every malformed URI; bare text is considered a reference only when a non-empty base64url-shaped payload follows the scheme, and a matching noncanonical candidate still fails. Empty or punctuation-only scheme mentions remain ordinary discussion text.
 
 ## Snapshot semantics

packages/context/session-reference/src/projection.ts

@@ -57,7 +57,6 @@ function projectSessionConversation(snapshot: SessionSurfaceSnapshot): Projected
         break
       }
       case 'tool/result':
-      case 'context/message':
         break
       /* v8 ignore next 2 -- SurfaceEventType is closed and every variant is handled above. */
       default:

packages/context/session-reference/tests/session-reference.spec.ts

@@ -75,7 +75,7 @@ function appendConversation(session: Session): void {
     { surfaceOp: 'append' },
   )
   session.append(
-    'context/message',
+    'user/message',
     { content: [{ type: 'text', text: 'workspace secret' }], source: { kind: 'plugin', plugin: 'workspace' } },
     { surfaceOp: 'append' },
   )

packages/context/time-context/README.md

@@ -18,9 +18,9 @@ When `timeZone` is omitted, the plugin resolves the Node process's system zone o
 
 ## Timing semantics
 
-The plugin prepends an `agent/pre-step` listener. When an injection is due, it appends one `context/message` through `agent.inject()` before `step/start` and ordinary automatic compaction, with source `{ kind: 'plugin', plugin: 'time-context' }`. A suppressed attempt appends nothing.
+The plugin prepends an `agent/pre-step` listener. When an injection is due, it appends one injected `user/message` through `agent.inject()` before `step/start` and ordinary automatic compaction, with source `{ kind: 'plugin', plugin: 'time-context' }`. A suppressed attempt appends nothing.
 
-Positive-interval scheduling scans the raw durable session events for the latest `context/message` with that source, including a reading shadowed by compaction. The schedule therefore applies across turns and resumed processes without process-local cache state. It reduces append frequency and history growth but never removes an existing reading, and sessions schedule independently.
+Positive-interval scheduling scans the raw durable session events for the latest `user/message` with that source, including a reading shadowed by compaction. The schedule therefore applies across turns and resumed processes without process-local cache state. It reduces append frequency and history growth but never removes an existing reading, and sessions schedule independently.
 
 Step 1 measures from the latest preceding model-visible message, including the prompt that opened the turn. Later steps measure from the preceding time-context event in the same turn. Both baselines use durable session-event timestamps; backward wall-clock movement clamps elapsed time to zero. A missing first-step baseline, or a later step with no earlier same-turn reading because interval suppression skipped it, reports `unavailable`.
 

packages/context/time-context/src/index.ts

@@ -64,7 +64,6 @@ function precedingMessageTime(agent: Agent): number | undefined {
       case 'user/message':
       case 'assistant/message':
       case 'tool/result':
-      case 'context/message':
       case 'steering/message':
         return event.time
       default:
@@ -79,7 +78,7 @@ function precedingMessageTime(agent: Agent): number | undefined {
 function precedingStepContextTime(agent: Agent, turn: number): number | undefined {
   for (const event of [...agent.session.events].reverse()) {
     if (event.type === 'turn/start' && event.data.turn === turn) return undefined
-    if (event.type === 'context/message'
+    if (event.type === 'user/message'
       && event.data.source.kind === 'plugin'
       && event.data.source.plugin === name) {
       return event.time
@@ -91,7 +90,7 @@ function precedingStepContextTime(agent: Agent, turn: number): number | undefine
 /** Find this plugin's latest durable injection, including a shadowed surface event. */
 function latestInjectionTime(agent: Agent): number | undefined {
   for (const event of [...agent.session.events].reverse()) {
-    if (event.type === 'context/message'
+    if (event.type === 'user/message'
       && event.data.source.kind === 'plugin'
       && event.data.source.plugin === name) {
       return event.time

packages/context/time-context/src/invariant.ts

@@ -48,7 +48,7 @@ function preparationPosition(history: readonly SessionEvent[], fail: InvariantFa
 /** Validate one plugin-attributed time reading against its session position and timestamp. */
 function validateReading(
   history: readonly SessionEvent[],
-  event: SessionEvent<'context/message'>,
+  event: SessionEvent<'user/message'>,
   fail: InvariantFailure,
 ): void {
   const [block] = event.data.content
@@ -84,7 +84,7 @@ function validateReading(
 /** Validate all package-owned readings already present in one session. */
 function validateSession(session: Session, fail: InvariantFailure): void {
   for (const [index, event] of session.events.entries()) {
-    if (event.type !== 'context/message'
+    if (event.type !== 'user/message'
       || event.data.source.kind !== 'plugin'
       || event.data.source.plugin !== SOURCE_NAME) continue
     validateReading(session.events.slice(0, index), event, fail)
@@ -97,7 +97,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
   ctx.on('internal/dispatch', (_mode, eventName, args) => {
     if (eventName !== 'session/event') return
     const [session, event] = args as [Session, SessionEvent]
-    if (event.type !== 'context/message'
+    if (event.type !== 'user/message'
       || event.data.source.kind !== 'plugin'
       || event.data.source.plugin !== SOURCE_NAME) return
     validateReading(session.events, event, fail)

packages/context/time-context/tests/invariant.spec.ts

@@ -17,7 +17,7 @@ async function setup(): Promise<Context> {
 
 function event(text: string, time = SECOND + 456, content?: unknown[]): SessionEvent {
   return {
-    type: 'context/message',
+    type: 'user/message',
     seq: 0,
     time,
     data: {
@@ -56,7 +56,7 @@ function preparing(turn: number, step: number): Session {
 }
 
 function appendReading(session: Session, text: string): void {
-  session.append('context/message', {
+  session.append('user/message', {
     content: [{ type: 'text', text }],
     source: { kind: 'plugin', plugin: 'time-context' },
   }, { surfaceOp: 'append' })
@@ -162,7 +162,7 @@ describe('time-context invariants', () => {
 
   it('ignores context messages owned by another package', async () => {
     const ctx = await setup()
-    const other = event('unrelated') as SessionEvent<'context/message'>
+    const other = event('unrelated') as SessionEvent<'user/message'>
     other.data.source = { kind: 'plugin', plugin: 'other' }
     expect(() => { ctx.emit('session/event', preparing(1, 1), other) }).not.toThrow()
     other.data.source = { kind: 'user' }

packages/context/time-context/tests/time-context.e2e.ts

@@ -48,7 +48,8 @@ describe('time-context through a real headless cordis.yml', () => {
     expect(stderr).not.toContain('UNHANDLED')
     expect(events.filter(event => event.type === 'turn/end')).toHaveLength(2)
 
-    const contexts = events.filter(event => event.type === 'context/message')
+    const contexts = events.filter(
+      (event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind === 'plugin')
     const starts = events.filter(event => event.type === 'step/start')
     expect(contexts).toHaveLength(2)
     expect(starts).toHaveLength(2)

packages/context/time-context/tests/time-context.spec.ts

@@ -3,8 +3,8 @@ import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { agentEvents, AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
 import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -42,14 +42,17 @@ function sessionAgent(session: Session, id = 'agent'): Agent {
     session,
     status: 'running',
     ctx: new Context(),
-    send() {},
-    steer() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
     inject(content, options) {
-      session.append('context/message', {
+      session.append('user/message', {
         content,
         source: options?.source ?? { kind: 'user' },
       }, { surfaceOp: 'append' })
+      return AgentMessageId('stub')
     },
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle: () => Promise.resolve(),
   }
@@ -66,7 +69,7 @@ function openMessageTurn(session: Session, turn: number): void {
 function contextTexts(session: Session): string[] {
   const texts: string[] = []
   for (const event of session.events) {
-    if (event.type === 'context/message'
+    if (event.type === 'user/message'
       && event.data.source.kind === 'plugin'
       && event.data.source.plugin === 'time-context') {
       texts.push(event.data.content.find(block => block.type === 'text')?.text ?? '')
@@ -151,8 +154,8 @@ describe('durable step context', () => {
       + 'Elapsed since the preceding model-visible message: 1d 1h 1m 1s.',
     ])
     const event = session.events.at(-1)
-    expect(event?.type).toBe('context/message')
-    if (event?.type !== 'context/message') throw new Error('missing time context')
+    expect(event?.type).toBe('user/message')
+    if (event?.type !== 'user/message') throw new Error('missing time context')
     expect(event.data.source).toEqual({ kind: 'plugin', plugin: 'time-context' })
     expect(event.surfaceOp).toBe('append')
   })
@@ -230,10 +233,10 @@ describe('durable step context', () => {
     const original = new Session(SessionId('seed-source'))
     openMessageTurn(original, 1)
     await fire(ctx, sessionAgent(original), 1, 1)
-    const user = original.events.find(event => event.type === 'user/message')
-    const reading = original.events.find(event => event.type === 'context/message')
+    const user = original.events.find(event => event.type === 'user/message' && event.data.source.kind === 'user')
+    const reading = original.events.find(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
     if (user === undefined || reading === undefined) throw new Error('missing source surface events')
-    original.append('context/message', {
+    original.append('user/message', {
       content: [{ type: 'text', text: 'compacted history' }],
       source: { kind: 'plugin', plugin: 'compact-basic' },
     }, {
@@ -292,7 +295,7 @@ describe('durable step context', () => {
     openMessageTurn(session, 1)
     let ordinarySawContext = false
     ctx.on('agent/pre-step', (subject) => {
-      ordinarySawContext = subject.session.events.some(event => event.type === 'context/message')
+      ordinarySawContext = subject.session.events.some(event => event.type === 'user/message')
     })
 
     await fire(ctx, agent, 1, 1)
@@ -371,7 +374,7 @@ describe('real agent-loop request history', () => {
     })
     const agent = ctx.agentLoop.create(SessionId(`late-${mode}`), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'start' }])
+    agent.followup([{ type: 'text', text: 'start' }])
     await agent.whenIdle()
 
     expect(laterSawReading).toBe(true)
@@ -397,11 +400,12 @@ describe('real agent-loop request history', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('loop'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'start' }])
+    agent.followup([{ type: 'text', text: 'start' }])
     await agent.whenIdle()
 
     expect(adapter.requests).toHaveLength(2)
-    const contexts = agent.session.events.filter(event => event.type === 'context/message')
+    const contexts = agent.session.events.filter(
+      (event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind === 'plugin')
     const starts = agent.session.events.filter(event => event.type === 'step/start')
     expect(contexts).toHaveLength(adapter.requests.length)
     expect(starts).toHaveLength(adapter.requests.length)

packages/context/workspace-context/README.md

@@ -28,7 +28,7 @@ Instructions from: AGENTS.md
 </system-reminder>
 ```
 
-Newly reached scopes use a durable raw `context/message`:
+Newly reached scopes use a durable injected `user/message` (plugin source):
 
 ```md
 <system-reminder>
@@ -42,11 +42,11 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 A same-file edit starts with `Updated instructions from: <path>` and says to use the new content instead of the previously loaded content. When a candidate disappears or becomes a per-directory duplicate of an earlier candidate, the message is `Instructions removed: <path>` followed by `The previously loaded instructions from this file no longer apply.` Literal `</system-reminder>` text inside an instruction file is escaped so file content cannot close the plugin-owned frame.
 
-The plugin owns the complete `<system-reminder>` framing, and every `context/message` (from this plugin or any other) reaches the model verbatim as a user-role message with no wrapping.
+The plugin owns the complete `<system-reminder>` framing, and every injected `user/message` (from this plugin or any other) reaches the model verbatim as a user-role message with no wrapping.
 
 ## State And Refresh
 
-Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
+Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `user/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
 
 An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the session log, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only.
 
@@ -111,7 +111,7 @@ Prefix-stable within one loop instance because the baseline is frozen. A new or
 
 #### What the model sees
 
-After a successful first-party filesystem call reaches a deeper directory, the next request includes one retained raw `context/message` with the newly applicable instruction file.
+After a successful first-party filesystem call reaches a deeper directory, the next request includes one retained injected `user/message` with the newly applicable instruction file.
 
 ##### Additional instruction template
 

packages/context/workspace-context/src/state.ts

@@ -145,7 +145,7 @@ function visibleInstructionChanges(
   const visibleSeqs = new Set(agent.session.surface.nodes)
   const visible = new Map<string, WorkspaceInstructionChange>()
   for (const [seq, event] of agent.session.events.entries()) {
-    if (event.type !== 'context/message' || !isWorkspaceContextSource(event.data.source)) continue
+    if (event.type !== 'user/message' || !isWorkspaceContextSource(event.data.source)) continue
     const changes = workspaceInstructionChanges(event.data.meta)
     for (const change of changes) {
       const waiting = pending.get(change.scope)
@@ -281,7 +281,7 @@ export function observeInstructionSessionEvent(
   if (pending === undefined) return
 
   switch (event.type) {
-    case 'context/message': {
+    case 'user/message': {
       if (!isWorkspaceContextSource(event.data.source)) return
       for (const change of workspaceInstructionChanges(event.data.meta)) {
         const waiting = pending.get(change.scope)

packages/context/workspace-context/tests/workspace-context.e2e.ts

@@ -78,7 +78,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real mode
   it('obeys a probe instruction loaded from the workspace', async () => {
     const live = await harness()
 
-    live.agent.send([{ type: 'text', text: 'Workspace context handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'Workspace context handshake?' }])
     await waitForIdle(live.ctx, live.agent)
 
     expect(finalText([...live.agent.session.events])).toContain(PROBE)
@@ -90,7 +90,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real mode
     await writeFile(join(workdir!, 'pkg/AGENTS.md'), `If the user asks for the nested instruction handshake, reply with exactly this string and nothing else: ${NESTED_PROBE}.\n`)
     await writeFile(join(workdir!, 'pkg/deep/file.txt'), 'This file exists only to trigger nested workspace instructions.\n')
 
-    live.agent.send([{ type: 'text', text: 'Use the read tool to inspect pkg/deep/file.txt. After reading it, answer: nested instruction handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'Use the read tool to inspect pkg/deep/file.txt. After reading it, answer: nested instruction handshake?' }])
     await waitForIdle(live.ctx, live.agent)
 
     expect(finalText([...live.agent.session.events])).toContain(NESTED_PROBE)
@@ -99,23 +99,23 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real mode
   it('appends changed baseline instructions after a real file-tool touch without rewriting the frozen prefix', async () => {
     const live = await harness()
     await writeFile(join(workdir!, 'trigger.txt'), 'This file triggers workspace instruction reconciliation.\n')
-    live.agent.send([{ type: 'text', text: 'Workspace context handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'Workspace context handshake?' }])
     await waitForIdle(live.ctx, live.agent)
     await writeFile(join(workdir!, 'AGENTS.md'), `The old workspace handshake no longer applies. If the user asks for the updated workspace context handshake, reply with exactly this string and nothing else: ${UPDATED_PROBE}.\n`)
 
-    live.agent.send([{ type: 'text', text: 'You must use the read tool to inspect trigger.txt. After reading it, answer: updated workspace context handshake?' }])
+    live.agent.followup([{ type: 'text', text: 'You must use the read tool to inspect trigger.txt. After reading it, answer: updated workspace context handshake?' }])
     await waitForIdle(live.ctx, live.agent)
 
     const events = [...live.agent.session.events]
-    const update = events.find(event => event.type === 'context/message'
+    const update = events.find(event => event.type === 'user/message'
       && typeof event.data.meta === 'object'
       && event.data.meta !== null
       && !Array.isArray(event.data.meta)
       && event.data.meta.kind === 'workspace-instructions')
-    expect(update?.type === 'context/message' && update.data.meta).toMatchObject({
+    expect(update?.type === 'user/message' && update.data.meta).toMatchObject({
       changes: [{ action: 'replace', scope: candidateScopeKey('.', 'AGENTS.md'), path: 'AGENTS.md' }],
     })
-    const updateText = update?.type === 'context/message'
+    const updateText = update?.type === 'user/message'
       ? update.data.content.filter(block => block.type === 'text').map(block => block.text).join('')
       : ''
     expect(updateText).toContain('Updated instructions from: AGENTS.md')

packages/context/workspace-context/tests/workspace-context.spec.ts

@@ -7,7 +7,7 @@ import Loader from '@cordisjs/plugin-loader'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import LlmService, { CallId, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId, SESSION_FORMAT_VERSION, type SessionEvent } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentMessageId, type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -177,15 +177,18 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
     options: {},
     session,
     status: 'idle',
-    send() {},
-    steer() {},
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
     inject(content, options) {
-      session.append('context/message', {
+      session.append('user/message', {
         content,
         source: options?.source ?? { kind: 'user' },
         ...options?.meta !== undefined ? { meta: options.meta } : {},
       }, { surfaceOp: 'append' })
+      return AgentMessageId('stub')
     },
+    send: () => AgentMessageId('stub'),
     cancel() {},
     whenIdle: () => Promise.resolve(),
   }
@@ -222,7 +225,7 @@ function workspaceChangeContext(scope: string, digest: string): HookContext {
 function appendAdditionalContexts(agent: Agent, result: { additionalContexts?: HookContext[] }): number | undefined {
   let lastSeq: number | undefined
   for (const context of result.additionalContexts ?? []) {
-    lastSeq = agent.session.append('context/message', {
+    lastSeq = agent.session.append('user/message', {
       content: context.content,
       source: context.source,
       ...context.meta !== undefined ? { meta: context.meta } : {},
@@ -976,7 +979,7 @@ describe('workspace context request injection', () => {
       const second = await composeBaselinePrefix(ctx, agent)
 
       expect(second).toEqual(first)
-      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(0)
+      expect(agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toHaveLength(0)
       expect(derivedText(agent)).toContain('repo rule')
     } finally {
       await rm(root, { recursive: true, force: true })
@@ -1148,7 +1151,7 @@ describe('workspace context request injection', () => {
 
       await composeBaselinePrefix(ctx, agent)
 
-      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(0)
+      expect(agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toHaveLength(0)
       expect(derivedText(agent)).not.toContain('workspace-context:')
     } finally {
       await rm(root, { recursive: true, force: true })
@@ -1714,14 +1717,14 @@ describe('dynamic nested workspace context injection', () => {
         },
       }))
 
-      agent.send([{ type: 'text', text: 'read and abort' }])
+      agent.followup([{ type: 'text', text: 'read and abort' }])
       await agent.whenIdle()
-      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(1)
+      expect(agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toHaveLength(1)
 
-      agent.send([{ type: 'text', text: 'retry the read' }])
+      agent.followup([{ type: 'text', text: 'retry the read' }])
       await agent.whenIdle()
 
-      const contexts = agent.session.events.filter(event => event.type === 'context/message')
+      const contexts = agent.session.events.filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
       // The aborted batch drained its accepted context before step close, so the
       // retry sees durable history without producing a duplicate instruction.
       expect(contexts).toHaveLength(1)
@@ -2496,10 +2499,7 @@ describe('dynamic nested workspace context injection', () => {
         agent,
       })
       appendAdditionalContexts(agent, first)
-      const resumed = {
-        ...agent,
-        session: new Session(agent.session.id, [...agent.session.events], agent.session.header),
-      }
+      const resumed = stubAgent(root, [...agent.session.events])
 
       const afterResume = await ctx.tools.execute({
         signal: testToolSignal,
@@ -2537,11 +2537,11 @@ describe('dynamic nested workspace context injection', () => {
 
       await composeBaselinePrefix(ctx, resumed)
 
-      const update = resumed.session.events.findLast(event => event.type === 'context/message')
-      expect(update?.type === 'context/message' && update.data.meta).toMatchObject({
+      const update = resumed.session.events.findLast(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(update?.type === 'user/message' && update.data.meta).toMatchObject({
         changes: [{ action: 'replace', scope: sk('pkg', 'AGENTS.md'), path: join('pkg', 'AGENTS.md') }],
       })
-      expect(update?.type === 'context/message' && blocksText(update.data.content)).toContain('new nested rule after resume')
+      expect(update?.type === 'user/message' && blocksText(update.data.content)).toContain('new nested rule after resume')
     } finally {
       await rm(root, { recursive: true, force: true })
       await rm(home, { recursive: true, force: true })
@@ -2687,7 +2687,7 @@ describe('dynamic nested workspace context injection', () => {
       const ctx = new Context()
       await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
       const agent = stubAgent(root)
-      agent.session.append('context/message', {
+      agent.session.append('user/message', {
         content: [
           { type: 'reasoning', text: 'Additional instructions from: pkg/AGENTS.md' },
           { type: 'text', text: 'Updated instructions from: pkg/AGENTS.md' },
@@ -2704,12 +2704,12 @@ describe('dynamic nested workspace context injection', () => {
           ],
         },
       }, { surfaceOp: 'append' })
-      agent.session.append('context/message', {
+      agent.session.append('user/message', {
         content: [{ type: 'text', text: 'stale metadata version' }],
         source: { kind: 'plugin', plugin: 'workspace-context' },
         meta: { kind: 'workspace-instructions', version: 0, changes: [] },
       }, { surfaceOp: 'append' })
-      agent.session.append('context/message', {
+      agent.session.append('user/message', {
         content: [{ type: 'text', text: 'foreign plugin context' }],
         source: { kind: 'plugin', plugin: 'other' },
         meta: {
@@ -3237,14 +3237,14 @@ describe('workspace context pending state', () => {
       path: join('pkg', 'AGENTS.md'), version: FsVersion('v1'), digest: 'one', trimmedDigest: 'one',
     }]]))
 
-    const unrelated = agent.session.append('context/message', {
+    const unrelated = agent.session.append('user/message', {
       content: [], source: { kind: 'plugin', plugin: 'other' },
     }, { surfaceOp: 'append' })
     observeInstructionSessionEvent(agent.session, unrelated, pending, versions)
     expect(pending.get(agent.session)?.has('pkg')).toBe(true)
 
     const otherContext = workspaceChangeContext('other', 'other')
-    const otherWorkspaceEvent = agent.session.append('context/message', {
+    const otherWorkspaceEvent = agent.session.append('user/message', {
       content: otherContext.content,
       source: otherContext.source,
       ...otherContext.meta !== undefined ? { meta: otherContext.meta } : {},
@@ -3253,7 +3253,7 @@ describe('workspace context pending state', () => {
     expect(pending.get(agent.session)?.has('pkg')).toBe(true)
 
     const context = workspaceChangeContext('pkg', 'one')
-    const confirmed = agent.session.append('context/message', {
+    const confirmed = agent.session.append('user/message', {
       content: context.content,
       source: context.source,
       ...context.meta !== undefined ? { meta: context.meta } : {},

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -498,6 +498,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'listSessions(): Promise<SessionRecord[]>',
         jsDoc: '/**\n * List the complete logical corpus using live-preferred records.\n * @returns deterministic newest-first cloned session records.\n */',
       },
+      {
+        signature: 'async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>',
+        jsDoc: '/**\n * Read and replay-validate one complete logical session log without making it live.\n * @param sessionId - live or persisted session id to read.\n * @returns cloned header and complete raw event log from one observation.\n * @throws when persistence, header compatibility, or replay validation fails.\n */',
+      },
       {
         signature: 'async filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]>',
         jsDoc: '/**\n * Filter the complete logical corpus with provider-independent predicates.\n * @param filters - ANDed session metadata and availability clauses.\n * @returns matching cloned records in deterministic newest-first order.\n */',
@@ -881,6 +885,27 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * A step or turn errored. The loop reports a failure here (plus the logger)\n * even when the error has no in-turn position for a session `error` event.\n * @param agent - the agent whose turn errored.\n * @param turn - the turn in which the failure surfaced.\n * @param step - the step at which the failure surfaced.\n * @param error - the failure, verbatim.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A step or turn errored.',
   },
+  {
+    name: 'agent/inbox/dequeue',
+    mode: 'emit',
+    signature: '\'agent/inbox/dequeue\'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void',
+    jsDoc: '/**\n * The driver claimed one item out of the inbox: a queued item at a turn\n * boundary, or steering drained between steps. Fires after the item leaves\n * its FIFO and before it becomes a durable message.\n * @param agent - the agent whose inbox item was claimed.\n * @param message - the claimed message (matching the `id` from its `agent/inbox/enqueue`).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    summary: 'The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps.',
+  },
+  {
+    name: 'agent/inbox/discard',
+    mode: 'emit',
+    signature: '\'agent/inbox/discard\'(this: Scoped<Agent>, agent: Agent, messages: AgentMessage[]): void',
+    jsDoc: '/**\n * Pending inbox items were dropped without delivering them, so every\n * enqueued id receives exactly one terminal `agent/inbox/dequeue` OR\n * `agent/inbox/discard`. Emitters: `cancel()` without `keepInbox` (after\n * `agent/cancel-requested`, before the abort); a terminal `agent/turn-stop`\n * dropping pending steering (in-turn and on the post-turn late-steering\n * drain); and disposal of any still-pending items (before\n * `agent/status(\'disposed\')`). Fires once per drop with every dropped item.\n * @param agent - the agent whose inbox items were dropped.\n * @param messages - the discarded messages in FIFO order (queued then steering); never empty.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    summary: 'Pending inbox items were dropped without delivering them, so every enqueued id receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`.',
+  },
+  {
+    name: 'agent/inbox/enqueue',
+    mode: 'emit',
+    signature: '\'agent/inbox/enqueue\'(this: Scoped<Agent>, agent: Agent, message: AgentMessage): void',
+    jsDoc: '/**\n * A detached, frozen item entered the agent\'s inbox (queued or steering\n * FIFO). Source defaults are already applied, so `message` holds the exact\n * accepted values. This is the enqueue-time live signal; the durable record\n * is the eventual `user/message`/`steering/message`. Injection through\n * `agent.inject()` or equivalent `send()` routing bypasses the FIFOs\n * and does not emit this.\n * @param agent - the agent whose inbox received the item.\n * @param message - the accepted message (its returned `id`, content, source, contexts, steering, and wakeup facts).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    summary: 'A detached, frozen item entered the agent\'s inbox (queued or steering FIFO).',
+  },
   {
     name: 'agent/post-step',
     mode: 'serial',
@@ -902,13 +927,6 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * Allow, rewrite, or block one claimed prompt before it becomes a user\n * message. Call `next()` for the unchanged default. A listener wrapping a\n * downstream `allow` must preserve its `content` and `additionalContexts`\n * unless it intentionally replaces them. The signal controls only this turn;\n * listeners may cooperate with it but must not retain it to control another\n * turn. Steering messages do not dispatch this event; they join an open turn\n * at a steering checkpoint.\n * @param agent - the agent whose turn claimed the message.\n * @param content - the claimed message\'s blocks, as queued.\n * @param source - the message\'s resolved source.\n * @param signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Allow, rewrite, or block one claimed prompt before it becomes a user message.',
   },
-  {
-    name: 'agent/queued',
-    mode: 'emit',
-    signature: '\'agent/queued\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; contexts: HookContext[]; steering: boolean }): void',
-    jsDoc: '/**\n * Detached, frozen content entered the agent\'s inbox. Source defaults have\n * already been applied, so these are the exact values retained for the log.\n * @param agent - the agent whose inbox received the message.\n * @param content - the accepted content blocks retained by the inbox.\n * @param info - the accepted source, contexts, and whether it entered as steering.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
-    summary: 'Detached, frozen content entered the agent\'s inbox.',
-  },
   {
     name: 'agent/request',
     mode: 'waterfall',
@@ -941,7 +959,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/status',
     mode: 'emit',
     signature: '\'agent/status\'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void',
-    jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does\n * not enter `running` synchronously; drive lifecycle from this event.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`, or → `disposed`). A waking\n * delivery does not enter `running` synchronously; drive lifecycle from this event.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'Agent status changed (`idle` ⇄ `running`, or → `disposed`).',
   },
   {
@@ -1167,7 +1185,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
 export const TYPE_API: readonly TypeApiEntry[] = [
   {
     name: 'Agent',
-    declaration: 'export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    send(content: ContentBlock[], options?: SendOptions): void;\n    steer(content: ContentBlock[], options?: SendOptions): void;\n    inject(content: ContentBlock[], options?: InjectOptions): void;\n    cancel(cause?: AgentCancelCause): void;\n    whenIdle(): Promise<void>;\n}',
+    declaration: 'export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    followup(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n    queue(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n    steer(content: ContentBlock[], options?: SendOptions): AgentMessageId;\n    inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId;\n    send(input: ResolvedAgentInput): AgentMessageId;\n    cancel(cause?: AgentCancelCause, options?: CancelOptions): void;\n    whenIdle(): Promise<void>;\n}',
   },
   {
     name: 'AgentCancelCause',
@@ -1181,6 +1199,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'AgentHandle',
     declaration: 'export interface AgentHandle {\n    agent: Agent;\n    dispose(): Promise<void>;\n}',
   },
+  {
+    name: 'AgentMessageId',
+    declaration: 'export type AgentMessageId = Branded<\'AgentMessageId\'>;',
+  },
   {
     name: 'AgentOptions',
     declaration: 'export interface AgentOptions {\n    provider?: string;\n    model?: string;\n}',
@@ -1281,6 +1303,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'CallId',
     declaration: 'export type CallId = Branded<\'CallId\'>;',
   },
+  {
+    name: 'CancelOptions',
+    declaration: 'export interface CancelOptions {\n    keepInbox?: boolean;\n}',
+  },
   {
     name: 'CodeBindingErrorClass',
     declaration: 'export interface CodeBindingErrorClass {\n    name: string;\n    memberNameProperty: string;\n}',
@@ -1499,7 +1525,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InjectOptions',
-    declaration: 'export interface InjectOptions extends Omit<SendOptions, \'contexts\'> {\n    meta?: JsonValue;\n}',
+    declaration: 'export interface InjectOptions {\n    source?: MessageSource;\n    meta?: JsonValue;\n}',
   },
   {
     name: 'InvariantFailure',
@@ -1525,6 +1551,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'JsonValue',
     declaration: 'export type JsonValue = null | boolean | number | string | JsonValue[] | {\n    [key: string]: JsonValue;\n};',
   },
+  {
+    name: 'LlmAdapter',
+    declaration: 'export abstract class LlmAdapter {\n    providerInfo(provider: string): LlmProviderInfo;\n    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;\n    resolveModelContext(_provider: string, _model: string): Promise<LlmModelContext | undefined>;\n    abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}',
+  },
   {
     name: 'LlmCallConfig',
     declaration: 'export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}',
@@ -1587,7 +1617,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'PromptMessageData',
-    declaration: 'export interface PromptMessageData {\n    content: ContentBlock[];\n    source: MessageSource;\n    envelope?: PromptMessageEnvelope;\n}',
+    declaration: 'export interface PromptMessageData {\n    content: ContentBlock[];\n    source: MessageSource;\n    envelope?: PromptMessageEnvelope;\n    meta?: JsonValue;\n}',
   },
   {
     name: 'PromptMessageEnvelope',
@@ -1689,6 +1719,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ReasoningBlock',
     declaration: 'export interface ReasoningBlock {\n    type: \'reasoning\';\n    text: string;\n}',
   },
+  {
+    name: 'RequestHeaderReason',
+    declaration: 'export type RequestHeaderReason = \'initial\' | \'resume\' | \'change\';',
+  },
+  {
+    name: 'ResolvedAgentInput',
+    declaration: 'export type ResolvedAgentInput = {\n    content: ContentBlock[];\n    source: MessageSource;\n    meta: JsonValue | undefined;\n} & ({\n    target: \'next-turn\';\n    wakeup: boolean;\n    contexts: HookContext[];\n} | {\n    target: \'next-step\';\n    wakeup: true;\n    contexts: HookContext[];\n} | {\n    target: \'next-step\';\n    wakeup: false;\n    contexts: [\n    ];\n});',
+  },
   {
     name: 'ResumeAgentOptions',
     declaration: 'export interface ResumeAgentOptions {\n    readonly resumeSessionId: SessionId;\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
@@ -1723,7 +1761,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SendOptions',
-    declaration: 'export interface SendOptions {\n    source?: MessageSource;\n    contexts?: HookContext[];\n}',
+    declaration: 'export interface SendOptions {\n    source?: MessageSource;\n    contexts?: HookContext[];\n    meta?: JsonValue;\n}',
+  },
+  {
+    name: 'Session',
+    declaration: 'export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    get id(): SessionId;\n    constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n    get events(): readonly SessionEvent[];\n    get seq(): number;\n    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n        opts: SurfaceIntent\n    ] : [\n    ]): SessionEvent<T>;\n    requestHeader(): EpochHeader | undefined;\n    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}',
   },
   {
     name: 'SessionAvailability',
@@ -1735,7 +1777,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEventMap',
-    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': PromptMessageData;\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        meta?: JsonValue;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        provenance: AssistantProvenance;\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: JsonValue;\n    };\n    \'steering/message\': PromptMessageData & {\n        turn: number;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: EpochHeader;\n        reason: R /* …truncated — full shape in source */',
+    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': PromptMessageData;\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        provenance: AssistantProvenance;\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: JsonValue;\n    };\n    \'steering/message\': PromptMessageData & {\n        turn: number;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: EpochHeader;\n        reason: RequestHeaderReason;\n    };\n}',
   },
   {
     name: 'SessionEventMetadataFilter',
@@ -1809,6 +1851,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionLocation',
     declaration: 'export interface SessionLocation {\n    readonly kind: string;\n    readonly path: string;\n}',
   },
+  {
+    name: 'SessionLogSnapshot',
+    declaration: 'export interface SessionLogSnapshot {\n    session: SessionHeader;\n    events: SessionEvent[];\n}',
+  },
   {
     name: 'SessionPersistenceRevision',
     declaration: 'export type SessionPersistenceRevision = Branded<\'SessionPersistenceRevision\'>;',
@@ -1857,6 +1903,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionSearchRequest',
     declaration: 'export interface SessionSearchRequest {\n    query: string;\n    sessionFilters?: readonly SessionResultFilter[];\n    eventFilters?: readonly SessionEventMetadataFilter[];\n    limit?: number;\n    cursor?: SessionSearchCursor;\n}',
   },
+  {
+    name: 'SessionSurface',
+    declaration: 'export interface SessionSurface {\n    readonly nodes: readonly number[];\n    readonly replaceGeneration: number;\n}',
+  },
   {
     name: 'SessionSurfaceSnapshot',
     declaration: 'export interface SessionSurfaceSnapshot {\n    session: SessionHeader;\n    capturedThroughSeq: number | null;\n    events: SurfaceEvent[];\n}',
@@ -1987,7 +2037,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SurfaceEventType',
-    declaration: 'export type SurfaceEventType = \'user/message\' | \'assistant/message\' | \'tool/result\' | \'context/message\' | \'steering/message\';',
+    declaration: 'export type SurfaceEventType = \'user/message\' | \'assistant/message\' | \'tool/result\' | \'steering/message\';',
+  },
+  {
+    name: 'SurfaceIntent',
+    declaration: 'export interface SurfaceIntent {\n    surfaceOp: SurfaceOp;\n    sourceEventSeqs?: number[];\n}',
   },
   {
     name: 'SurfaceOp',

packages/cordis/tool-cordis/tests/inspect.spec.ts

@@ -61,6 +61,8 @@ describe('cordis_inspect', () => {
     // generated TYPE_API — a consumer can see field types, not just names).
     expect(report).toContain('type shapes (referenced by the signatures above')
     expect(report).toContain('export interface ToolExecution')
+    expect(report).toContain('export class Session')
+    expect(report).toContain('export interface SessionSurface')
     // A type only reachable through a NOT-live service (e.g. bash) is scoped out.
     expect(report).not.toContain('export interface BashRunResult')
     // The inherited ctx surface closes the section.

packages/cordis/tool-cordis/tests/integration.spec.ts

@@ -47,7 +47,7 @@ describe('cordis tools through the agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('it-cordis'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
+    agent.followup([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
     await waitForIdle(ctx, agent)
 
     const log = agent.session.events

packages/core/agent-loop/README.md

@@ -50,9 +50,9 @@ Configured agents start automatically. A model call requires both `provider` and
 
 ### Internal concrete driver
 
-The concrete `Agent` class, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.
+The concrete `ReactLoopAgent` adapter, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.
 
-Each concrete `send()` materializes content, resolved source, and attached contexts once as a detached, deeply frozen lossless-JSON FIFO item. If claimed, it is the sole ordinary message in its turn; its contexts are the prompt waterfall's default additional contexts and therefore materialize only after admission. Absent or `separate` placement appends an independent `context/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. Open-turn `inject()` uses the same accepted-value boundary but defers in a FIFO while the current step executes assistant tool calls; successful batches place it after all results, and interrupted batches drain it before turn close. Malformed data throws before enqueue or append.
+`ReactLoopAgent.send()` implements the public fully resolved acceptance path. The `followup()`/`queue()`/`steer()`/`inject()` helpers resolve every optional field before delegating to it; direct callers provide mandatory content, source, contexts, metadata, target, and wakeup facts through `ResolvedAgentInput`. `followup()` and `queue()` join the ordinary FIFO, respectively waking or leaving an idle driver parked. If claimed, an ordinary item is the sole message in its turn, and its contexts are the prompt waterfall's default additional contexts that materialize only after admission. Absent or `separate` placement appends an independent injected `user/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` or equivalent `send()` routing enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. `inject()` and non-waking next-step acceptance require an empty context tuple, bypass both FIFOs, and append durable context directly: an open-turn injection defers in a FIFO while the current step executes assistant tool calls (successful batches place it after all results, interrupted batches drain it before turn close), and an idle injection wraps a one-shot `injection` turn. Every FIFO enqueue publishes `agent/inbox/enqueue`; the driver's claims publish `agent/inbox/dequeue`, and `cancel()` without `keepInbox` publishes `agent/inbox/discard`. Malformed data throws before enqueue or append.
 
 ### Loop lifecycle (`loop.ts`)
 

packages/core/agent-loop/src/agent.ts

@@ -6,15 +6,25 @@
  * @module dsh-agent-loop/agent
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
-import { agentEvents } from '@deepseek-ai/dsh-agent'
-import type { AgentCancelCause, AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents, AgentMessageId } from '@deepseek-ai/dsh-agent'
+import type {
+  Agent,
+  AgentCancelCause,
+  AgentOptions,
+  AgentStatus,
+  CancelOptions,
+  HookContext,
+  InjectOptions,
+  ResolvedAgentInput,
+  SendOptions,
+} from '@deepseek-ai/dsh-agent'
 import { deepFreeze, errorChain } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { snapshotJsonValue, type Session, type SessionId } from '@deepseek-ai/dsh-session'
 import { DISPOSED_INTERRUPT_REASON, TurnCancellation } from './cancellation.ts'
-import { Inbox, type InboxMessage } from './inbox.ts'
+import { Inbox, agentMessage, type InboxMessage } from './inbox.ts'
 import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts'
 
 /** Sessions already claimed by a concrete driver construction. */
@@ -190,19 +200,17 @@ export class ReactLoopAgent implements Agent {
     for (const resolve of waiters) resolve()
   }
 
-  private resolveSource(options?: SendOptions): MessageSource {
-    return options?.source ?? { kind: 'user' }
-  }
-
   /**
    * Accept one public message payload as a detached record. Lossless-JSON
    * materialization reads every nested field once; deep freeze prevents later
    * caller mutation before an inbox or deferred-injection queue drains it.
    */
-  private acceptMessage(content: ContentBlock[], options?: SendOptions): InboxMessage {
-    const source = this.resolveSource(options)
-    const contexts = options?.contexts ?? []
-    const accepted = snapshotJsonValue({ content, source, contexts })
+  private snapshotMessage(id: AgentMessageId, input: ResolvedAgentInput): InboxMessage {
+    const { content, source, contexts, wakeup, meta } = input
+    const accepted = snapshotJsonValue({
+      id, content, source, contexts, wakeup,
+      ...meta !== undefined ? { meta } : {},
+    })
     if (accepted === undefined) {
       throw new TypeError('agent message content, source, and contexts must be losslessly JSON-serializable')
     }
@@ -223,33 +231,81 @@ export class ReactLoopAgent implements Agent {
     if (this._status === 'disposed') throw new Error(`agent "${this.id}" is disposed`)
   }
 
-  send(content: ContentBlock[], options?: SendOptions): void {
+  /** Accept one fully resolved agent input through the concrete driver's routing matrix. */
+  send(input: ResolvedAgentInput): AgentMessageId {
     this.assertNotDisposed()
-    const accepted = this.acceptMessage(content, options)
-    this.#inbox.enqueue(accepted)
-    const info = { source: accepted.source, contexts: accepted.contexts, steering: false } as const
-    agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
+    const id = AgentMessageId(randomUUID())
+    const { target, wakeup } = input
+    // next-step/no-wakeup is injection: durable context without running the model.
+    if (target === 'next-step' && !wakeup) { this.injectContext(input); return id }
+    // next-step/wakeup is steering into the running turn; idle falls back to a
+    // waking ordinary turn (there is no active turn to attach to).
+    const steering = target === 'next-step' && this._status === 'running'
+    const accepted = this.snapshotMessage(id, input)
+    if (steering) {
+      this.#inbox.steer(accepted)
+    } else {
+      this.#inbox.enqueue(accepted, wakeup)
+    }
+    agentEvents(this.loopCtx, this).emit('agent/inbox/enqueue', agentMessage(accepted, steering))
+    return id
   }
 
-  steer(content: ContentBlock[], options?: SendOptions): void {
-    this.assertNotDisposed()
-    if (this._status !== 'running') { this.send(content, options); return }
-    const accepted = this.acceptMessage(content, options)
-    this.#inbox.steer(accepted)
-    const info = { source: accepted.source, contexts: accepted.contexts, steering: true } as const
-    agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
+  followup(content: ContentBlock[], options?: SendOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-turn',
+      wakeup: true,
+      source: options?.source ?? { kind: 'user' },
+      contexts: options?.contexts ?? [],
+      meta: options?.meta,
+    })
   }
 
-  inject(content: ContentBlock[], options?: InjectOptions): void {
-    this.assertNotDisposed()
-    const source = this.resolveSource(options)
-    const context = {
+  queue(content: ContentBlock[], options?: SendOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-turn',
+      wakeup: false,
+      source: options?.source ?? { kind: 'user' },
+      contexts: options?.contexts ?? [],
+      meta: options?.meta,
+    })
+  }
+
+  steer(content: ContentBlock[], options?: SendOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-step',
+      wakeup: true,
+      source: options?.source ?? { kind: 'user' },
+      contexts: options?.contexts ?? [],
+      meta: options?.meta,
+    })
+  }
+
+  inject(content: ContentBlock[], options?: InjectOptions): AgentMessageId {
+    return this.send({
+      content,
+      target: 'next-step',
+      wakeup: false,
+      source: options?.source ?? { kind: 'plugin', plugin: '' },
+      contexts: [],
+      meta: options?.meta,
+    })
+  }
+
+  /** The `next-step`/no-wakeup injection path: durable context, no FIFO, no run. */
+  private injectContext(input: Extract<ResolvedAgentInput, { target: 'next-step'; wakeup: false }>): void {
+    const { content, source, meta } = input
+    // Detach and validate the payload before any append, so malformed input
+    // cannot open a one-shot turn or otherwise mutate the session.
+    const accepted = this.acceptContext({
       content,
       source,
-      ...options?.meta !== undefined ? { meta: options.meta } : {},
-    }
+      ...meta !== undefined ? { meta } : {},
+    })
     if (isTurnOpen(this.session)) {
-      const accepted = this.acceptContext(context)
       // Provider protocols require every assistant tool-call batch to be
       // followed only by its tool results. Historical interrupted batches do
       // not own new context; only the currently executing batch may defer it.
@@ -257,27 +313,29 @@ export class ReactLoopAgent implements Agent {
         this.deferredInjections.push(accepted)
         return
       }
-      this.session.append('context/message', accepted, { surfaceOp: 'append' })
+      this.session.append('user/message', accepted, { surfaceOp: 'append' })
       return
     }
     // No turn open: wrap the injection in a one-shot turn so every event stays
-    // turn-enclosed (the durability/replay boundary is the turn).
+    // turn-enclosed (the durability/replay boundary is the turn). The payload is
+    // validated above, but `Session.append` can still reject a turn/start
+    // pre-commit (append re-entrancy from a session/event listener, or an
+    // internal-dispatch veto), so the finally owes a turn/end only when
+    // turn/start actually committed.
     const turn = lastTurnNumber(this.session) + 1
-    // Once turn/start enters the log, a turn/end is owed even if the message
-    // append fails acceptance or pre-commit validation. The finally re-checks
-    // the log and closes only a turn that actually opened; post-commit observers
-    // are contained by Session and cannot create a false append failure.
     try {
       this.session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-      this.session.append('context/message', context, { surfaceOp: 'append' })
+      this.session.append('user/message', accepted, { surfaceOp: 'append' })
     } finally {
       // Close the turn if turn/start made it into the log. A pre-commit veto
       // must escape rather than being mistaken for a committed turn/end.
       if (isTurnOpen(this.session)) {
         this.session.append('turn/end', { turn, reason: { kind: 'completed' } })
       }
-      // Decide the durability checkpoint from the log: an accepted one-shot
-      // turn must be flushed even when its message append was the failing step.
+      // Checkpoint only an accepted one-shot turn: a turn/start rejected
+      // pre-commit recorded nothing, so it owes no flush (and a spurious flush
+      // would emit a phantom-turn agent/error). The payload is validated up
+      // front, so a committed turn/start is always followed by its user/message.
       const turnRecorded = this.session.events.some(e => e.type === 'turn/start' && e.data.turn === turn)
       // Keep inject() synchronous: report checkpoint failures live instead of
       // rejecting the caller, and track the task so disposal still drains it.
@@ -301,7 +359,7 @@ export class ReactLoopAgent implements Agent {
   private drainDeferredInjections(): void {
     const pending = this.deferredInjections.splice(0)
     for (const accepted of pending) {
-      this.session.append('context/message', accepted, { surfaceOp: 'append' })
+      this.session.append('user/message', accepted, { surfaceOp: 'append' })
     }
   }
 
@@ -325,10 +383,14 @@ export class ReactLoopAgent implements Agent {
     }
   }
 
-  cancel(cause?: AgentCancelCause): void {
+  cancel(cause?: AgentCancelCause, options?: CancelOptions): void {
     const resolvedCause = cause ?? { kind: 'user' }
+    const keepInbox = options?.keepInbox ?? false
     const cancellation = this.turnCancellation
-    const preRun = cancellation === undefined && (this.#inbox.hasQueued || this.#inbox.hasSteering)
+    // keepInbox preserves pending work, so un-started items must not arm the
+    // pre-run cancel path that would otherwise drop the next queued turn.
+    const preRun = !keepInbox && cancellation === undefined
+      && (this.#inbox.hasQueued || this.#inbox.hasSteering)
     if (cancellation !== undefined || preRun) {
       if (preRun) this.preRunCancelled = true
       // Coordination consumers must update their own state before this call
@@ -336,9 +398,24 @@ export class ReactLoopAgent implements Agent {
       // contained by the fused dispatcher and cannot veto cancellation.
       agentEvents(this.loopCtx, this).emit('agent/cancel-requested', resolvedCause)
     }
-    // Clear work already present before abort observers run. A replacement
-    // synchronously enqueued by an observer belongs to the next turn.
-    this.#inbox.clear()
+    if (!keepInbox) {
+      // Snapshot before clearing so the discard notification carries the exact
+      // dropped items; a replacement synchronously enqueued by an
+      // `agent/cancel-requested` observer belongs to the next turn, not here.
+      const discarded = this.#inbox.pending()
+      // Clear work already present before abort observers run.
+      this.#inbox.clear()
+      if (discarded.length > 0) {
+        const items = discarded.map(({ message, steering }) => agentMessage(message, steering))
+        agentEvents(this.loopCtx, this).emit('agent/inbox/discard', items)
+      }
+      // No idle-waiter settle here: a `whenIdle` waiter exists only while the
+      // agent is `running` or a waking item is queued, and neither is left
+      // quiescent by clearing the inbox — a lone quiet item takes `whenIdle`'s
+      // fast path (no waiter), a waking item keeps the woken driver running,
+      // and a running agent owns its own idle transition (including the
+      // post-turn flush window).
+    }
     cancellation?.request(resolvedCause)
   }
 
@@ -349,7 +426,9 @@ export class ReactLoopAgent implements Agent {
    */
   whenIdle(): Promise<void> {
     if (this._status === 'disposed') return this.done
-    if (this._status !== 'running' && !this.#inbox.hasQueued) return Promise.resolve()
+    // A lone quiet (`wakeup:false`) queued item leaves the agent quiescent — the
+    // driver stays parked — so gate on hasWakingQueued, not hasQueued.
+    if (this._status !== 'running' && !this.#inbox.hasWakingQueued) return Promise.resolve()
     // Agent-owned waiters survive concurrent fiber disposal.
     return new Promise<void>((resolve) => {
       this.idleWaiters.push(() => {
@@ -407,8 +486,21 @@ export class ReactLoopAgent implements Agent {
    */
   private [stopDriver](): Promise<void> | void {
     if (this._status !== 'disposed') {
+      // Snapshot any still-pending inbox items, then CLEAR and mark disposed
+      // BEFORE emitting the discard — mirroring cancel()'s snapshot→clear→emit
+      // order so a re-entrant followup()/cancel() from a discard listener throws
+      // `disposed` (or finds an empty inbox) instead of leaking or double-
+      // discarding an id. `followup()` emits enqueue unconditionally, so the discard
+      // is unconditional too (even on an unpublished rollback) to keep every
+      // enqueued id matched.
+      const discarded = this.#inbox.pending()
+      this.#inbox.clear()
       this._status = 'disposed'
       this.resolveDisposed()
+      if (discarded.length > 0) {
+        const items = discarded.map(({ message, steering }) => agentMessage(message, steering))
+        agentEvents(this.loopCtx, this).emit('agent/inbox/discard', items)
+      }
       // Release whenIdle waiters BEFORE the (guarded) event emit — they are
       // internal state that must settle even if a listener throws below. Each
       // waiter chains `done`, so it resolves only once the loop actually exits.

packages/core/agent-loop/src/inbox.ts

@@ -1,54 +1,91 @@
 /**
  * Per-agent message inbox: queued and steering FIFOs. Purely an in-memory
- * mechanism of the loop driver — the public surface is `Agent.send()` and
- * `Agent.steer()`.
+ * mechanism of the loop driver — callers use `Agent`'s intent-named delivery
+ * methods instead.
  *
  * @module dsh-agent-loop/inbox
  */
 
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
-import type { HookContext } from '@deepseek-ai/dsh-agent'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { AgentMessage, AgentMessageId, HookContext } from '@deepseek-ai/dsh-agent'
 
-/** One message waiting in an agent's inbox. */
+/** One message waiting in an agent's inbox; `id` is the value its accepting delivery method returned. */
 export interface InboxMessage {
+  id: AgentMessageId
   content: ContentBlock[]
   source: MessageSource
   contexts: HookContext[]
+  /** Whether the item is marked to wake the driver or force a continuation. */
+  wakeup: boolean
+  /** Opaque durable JSON state retained on the durable message but hidden from the model. */
+  meta?: JsonValue
+}
+
+/**
+ * Build the `agent/inbox/*` event payload for one inbox item.
+ * @param message - the accepted inbox record.
+ * @param steering - whether the item is in the steering FIFO (`next-step`).
+ * @returns the live-event message for enqueue/dequeue/discard.
+ */
+export function agentMessage(message: InboxMessage, steering: boolean): AgentMessage {
+  // Frozen: the fused emitter passes this exact object to every listener in
+  // turn, so one listener must not be able to mutate a field (`id`, `steering`,
+  // `content`, …) a later listener then observes. `message` is already a frozen
+  // inbox record, so its nested fields need no re-clone.
+  return Object.freeze({
+    id: message.id, content: message.content, source: message.source,
+    contexts: message.contexts, steering, wakeup: message.wakeup,
+  })
 }
 
 /**
  * Per-agent inbox: a queued FIFO (dequeued once per turn start) and a steering FIFO
  * (drained between steps of a running turn). Purely an in-memory mechanism of
- * the loop — the public surface is `Agent.send()` / `Agent.steer()`.
+ * the loop — the public surface is `Agent`'s intent-named delivery methods.
  */
 export class Inbox {
   private queuedMessages: InboxMessage[] = []
   private steeringMessages: InboxMessage[] = []
   private wakeup: (() => void) | undefined
 
-  /** True while queued messages are pending — read by the idle wait's fast path and the loop's turn-start checks. */
+  /** True while any queued message is pending — read by cancellation's discard snapshot and the turn-start dequeue guard. */
   get hasQueued(): boolean {
     return this.queuedMessages.length > 0
   }
 
+  /**
+   * True while a queued message wants to wake the driver — the "should the loop
+   * run" signal read by the idle wait's fast path, the loop's idle-publish
+   * check, and `whenIdle`. A `wakeup:false` (quiet) item alone leaves this
+   * false, so the driver stays parked until a waking follow-up (or a waking item
+   * ahead of it in FIFO order) drives the loop; the quiet item then rides along.
+   */
+  get hasWakingQueued(): boolean {
+    return this.queuedMessages.some(message => message.wakeup)
+  }
+
   /** True while steering messages are pending — read by cancellation and the loop's stop-override check. */
   get hasSteering(): boolean {
     return this.steeringMessages.length > 0
   }
 
   /**
-   * Add a message to the queued FIFO and wake a parked {@link waitForQueued}.
+   * Add a message to the queued FIFO, waking a parked {@link waitForQueued}
+   * unless the item opted out. A non-waking item still runs once any woken
+   * item or later wakeup drives the parked loop.
    * @param message - the message to queue for the next turn start.
+   * @param wake - whether to wake a parked idle wait (default true).
    */
-  enqueue(message: InboxMessage): void {
+  enqueue(message: InboxMessage, wake = true): void {
     this.queuedMessages.push(message)
-    this.wakeup?.()
+    if (wake) this.wakeup?.()
   }
 
   /**
    * Add a message to the steering FIFO. Deliberately no wakeup: steering is
    * drained between steps of a running turn, never by the idle wait —
-   * `Agent.steer()` on an idle agent falls back to `send()` instead.
+   * `Agent.steer()` on an idle agent falls back to a waking ordinary turn instead.
    * @param message - the message to inject between steps of the running turn.
    */
   steer(message: InboxMessage): void {
@@ -71,6 +108,18 @@ export class Inbox {
     return this.steeringMessages.splice(0)
   }
 
+  /**
+   * Snapshot the pending items (queued then steering, FIFO order) without
+   * removing them — the discard notification's payload source.
+   * @returns the pending items paired with whether each is steering.
+   */
+  pending(): { message: InboxMessage; steering: boolean }[] {
+    return [
+      ...this.queuedMessages.map(message => ({ message, steering: false })),
+      ...this.steeringMessages.map(message => ({ message, steering: true })),
+    ]
+  }
+
   /**
    * Discard all pending messages (queued + steering) without delivering them —
    * used by `cancel()`, which drops un-started work rather than draining it into
@@ -88,7 +137,7 @@ export class Inbox {
    *   loop can exit).
    */
   waitForQueued(cancel: Promise<void>): Promise<void> {
-    if (this.hasQueued) return Promise.resolve()
+    if (this.hasWakingQueued) return Promise.resolve()
     const { promise, resolve } = Promise.withResolvers<void>()
     this.wakeup = resolve
     void cancel.then(resolve)

packages/core/agent-loop/src/loop.ts

@@ -5,11 +5,12 @@
  * @module dsh-agent-loop/loop
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
 import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, LlmFailure, Message } from '@deepseek-ai/dsh-llm'
 import { isDeepStrictEqual } from 'node:util'
 import { BlockAssembler, HarnessError, LlmError, assertNever, deepFreeze, errorChain, llmFailureOf, markAgentLoopRequest } from '@deepseek-ai/dsh-llm'
-import { agentEvents, agentInterruptReasonOf, assembleContextFor } from '@deepseek-ai/dsh-agent'
+import { agentEvents, agentInterruptReasonOf, assembleContextFor, AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
 import type { PromptMessageData, Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
@@ -19,7 +20,7 @@ import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
 import { executeToolCalls } from './tool-calls.ts'
-import type { Inbox } from './inbox.ts'
+import { agentMessage, type Inbox, type InboxMessage } from './inbox.ts'
 import type { TurnCancellation } from './cancellation.ts'
 
 /** Normalize thrown values while preserving an existing error code. */
@@ -201,9 +202,11 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
   while (!handle.isDisposed()) {
     // An idle listener can enqueue and cancel replacement work before the next
     // wait is installed. Consume that empty marker before parking the driver.
+    // A quiet (`wakeup:false`) item alone must not un-park the loop, so gate on
+    // hasWakingQueued, not hasQueued.
     if (handle.isPreRunCancelled()) {
       handle.clearPreRunCancel()
-      if (!handle.inbox.hasQueued) {
+      if (!handle.inbox.hasWakingQueued) {
         handle.settleIdle()
         handle.setStatus('idle')
         continue
@@ -217,7 +220,7 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
     // a replacement prompt still runs before the eventual idle transition.
     if (handle.isPreRunCancelled()) {
       handle.clearPreRunCancel()
-      if (!handle.inbox.hasQueued) {
+      if (!handle.inbox.hasWakingQueued) {
         // Settle before publishing idle: the already-idle path has no status
         // transition, while an idle listener can register waiters for new work.
         handle.settleIdle()
@@ -234,10 +237,11 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
     }
 
     // A synchronous `running` listener can cancel before `runTurn`; balance the
-    // status only when no replacement prompt was queued by that listener.
+    // status only when no waking replacement prompt was queued by that listener
+    // (a lone quiet item parks at idle rather than driving a turn).
     if (cancellation.signal.aborted) {
       handle.clearTurnCancellation(cancellation)
-      if (!handle.inbox.hasQueued) {
+      if (!handle.inbox.hasWakingQueued) {
         handle.setStatus('idle')
         continue
       }
@@ -260,12 +264,22 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
       handle.clearTurnCancellation(cancellation)
     }
 
-    // Late steering becomes queued input unless terminal policy stopped the turn.
-    for (const message of handle.inbox.drainSteering()) {
-      if (!terminalStopped) handle.inbox.enqueue(message)
+    // Late steering (arriving after runTurn returns, e.g. during the post-turn
+    // flush) becomes queued input — unless terminal policy stopped the turn, in
+    // which case it is dropped and must publish a discard so its enqueue is
+    // still matched (the invariant only catches a NEGATIVE count, not a leak).
+    const lateSteering = handle.inbox.drainSteering()
+    if (terminalStopped) {
+      if (lateSteering.length > 0) {
+        events.emit('agent/inbox/discard', lateSteering.map(message => agentMessage(message, true)))
+      }
+    } else {
+      for (const message of lateSteering) handle.inbox.enqueue(message)
     }
 
-    if (!handle.inbox.hasQueued) handle.setStatus('idle')
+    // Park at idle unless a waking item still wants the model to run; a lone
+    // quiet (`wakeup:false`) item stays queued but does not keep the loop busy.
+    if (!handle.inbox.hasWakingQueued) handle.setStatus('idle')
   }
 }
 
@@ -279,10 +293,14 @@ async function runTurn(
   const drainSteering = (): boolean => {
     const messages = handle.inbox.drainSteering()
     for (const message of messages) {
+      events.emit('agent/inbox/dequeue', agentMessage(message, true))
       const prepared = preparePromptMessage(message.content, message.source, message.contexts)
-      session.append('steering/message', { turn, ...prepared.data }, { surfaceOp: 'append' })
+      session.append('steering/message', {
+        turn, ...prepared.data,
+        ...message.meta === undefined ? {} : { meta: message.meta },
+      }, { surfaceOp: 'append' })
       for (const context of prepared.separateContexts) {
-        session.append('context/message', {
+        session.append('user/message', {
           content: context.content,
           source: context.source,
           ...context.meta === undefined ? {} : { meta: context.meta },
@@ -296,6 +314,7 @@ async function runTurn(
   const message = handle.inbox.dequeueQueued()
   /* v8 ignore next 3 -- invariant guard: runLoop only calls runTurn when hasQueued */
   if (!message) throw new Error('runTurn invariant violated: no queued message at turn start')
+  events.emit('agent/inbox/dequeue', agentMessage(message, false))
   const trigger: TurnTrigger = { kind: 'message', source: message.source }
 
   let reason: TurnEndReason = { kind: 'completed' }
@@ -361,7 +380,10 @@ async function runTurn(
       // `allow.content` REPLACES the prompt bytes (a rewrite); absent keeps them.
       const content = promptDecision.content ?? message.content
       const prepared = preparePromptMessage(content, message.source, promptDecision.additionalContexts ?? [])
-      session.append('user/message', prepared.data, { surfaceOp: 'append' })
+      session.append('user/message', {
+        ...prepared.data,
+        ...message.meta === undefined ? {} : { meta: message.meta },
+      }, { surfaceOp: 'append' })
       // Separate contexts still enter THIS turn through inject(). Prefix
       // contexts are already baked into the user/message with their durable
       // display envelope, so appending them again would duplicate model input.
@@ -536,9 +558,21 @@ async function runTurn(
         break
       }
 
-      // A continuation reason becomes next-step steering.
+      // A continuation reason becomes next-step steering. Publish the same
+      // enqueue event a public steer would, so the inbox ledger stays balanced
+      // (every FIFO entry has a matching enqueue before its dequeue/discard).
       if (decision.action === 'continue' && decision.reason) {
-        handle.inbox.steer({ content: decision.reason.content, source: decision.reason.source, contexts: [] })
+        // Detach and freeze the listener-owned reason like a public steer, so an
+        // enqueue listener or the producer cannot mutate the durable/model-visible
+        // steering message before it drains.
+        const item: InboxMessage = deepFreeze({
+          id: AgentMessageId(randomUUID()),
+          content: structuredClone(decision.reason.content),
+          source: structuredClone(decision.reason.source),
+          contexts: [], wakeup: true,
+        })
+        handle.inbox.steer(item)
+        events.emit('agent/inbox/enqueue', agentMessage(item, true))
       }
       let shouldContinue = decision.action === 'continue'
 
@@ -562,7 +596,13 @@ async function runTurn(
       if (terminalStop) {
         terminalStopped = true
         // Terminal stop discards steering but preserves ordinary queued prompts.
-        handle.inbox.drainSteering()
+        // Publish a discard for every dropped steering item so the enqueue ⇒
+        // dequeue-or-discard ledger stays balanced (the outstanding-count
+        // invariant and correlation consumers must not be left with dangling ids).
+        const dropped = handle.inbox.drainSteering()
+        if (dropped.length > 0) {
+          events.emit('agent/inbox/discard', dropped.map(item => agentMessage(item, true)))
+        }
         shouldContinue = false
       }
 

packages/core/agent-loop/tests/agent-initiator.spec.ts

@@ -41,7 +41,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string): void {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 /** Adapter that holds both drivers at the same awaited continuation. */

packages/core/agent-loop/tests/agent.spec.ts

@@ -48,7 +48,7 @@ function waitForStatus(ctx: Context, agent: Agent, expected: Agent['status']): P
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('Agent', () => {
@@ -83,7 +83,41 @@ describe('Agent', () => {
     await ctx.fiber.dispose()
   })
 
-  it('send() throws after disposal', async () => {
+  it('send exposes the fully resolved delivery path without applying helper defaults', async () => {
+    const adapter = new MockAdapter([textResponse('accepted')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const enqueued = Promise.withResolvers<{ id: string; source: unknown; wakeup: boolean }>()
+    ctx.on('agent/inbox/enqueue', (subject, message) => {
+      if (subject === agent) enqueued.resolve(message)
+    })
+
+    const id = agent.send({
+      content: [{ type: 'text', text: 'advanced input' }],
+      source: { kind: 'plugin', plugin: 'advanced-caller' },
+      contexts: [],
+      meta: { caller: 'advanced' },
+      target: 'next-turn',
+      wakeup: true,
+    })
+    await waitForIdle(ctx, agent)
+
+    expect(await enqueued.promise).toMatchObject({
+      id,
+      source: { kind: 'plugin', plugin: 'advanced-caller' },
+      wakeup: true,
+    })
+    expect(agent.session.events.find(event => event.type === 'user/message'))
+      .toMatchObject({
+        data: {
+          source: { kind: 'plugin', plugin: 'advanced-caller' },
+          meta: { caller: 'advanced' },
+        },
+      })
+    await ctx.fiber.dispose()
+  })
+
+  it('followup() throws after disposal', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
     let agent!: Agent
@@ -95,7 +129,28 @@ describe('Agent', () => {
     await fiber.dispose()
     await driverDone(agent)
 
-    expect(() => { agent.send([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
+    expect(() => { agent.followup([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
+  })
+
+  it('disposal discards still-pending inbox items so every id gets a terminal event', async () => {
+    const adapter = new MockAdapter(['hang'])
+    const ctx = await harness(adapter)
+    let agent!: Agent
+    const discarded: string[] = []
+    ctx.on('agent/inbox/discard', (subject, messages) => {
+      if (subject === agent) discarded.push(...messages.map(m => m.id))
+    })
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
+    }, { inject: ['agentLoop'] }))
+
+    // A quiet (non-waking) item stays parked in the inbox; disposal must drop it
+    // WITH a discard so its enqueued id is not left dangling forever.
+    const id = agent.queue([{ type: 'text', text: 'never runs' }])
+    await fiber.dispose()
+    await driverDone(agent)
+
+    expect(discarded).toEqual([id])
   })
 
   it('steer() throws after disposal', async () => {
@@ -139,7 +194,7 @@ describe('Agent', () => {
     agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     agent.inject([{ type: 'text', text: 'mid' }], { source: { kind: 'plugin', plugin: 'p' } })
     expect(agent.session.events.filter(e => e.type === 'turn/start')).toHaveLength(1)
-    expect(agent.session.events.at(-1)!.type).toBe('context/message')
+    expect(agent.session.events.at(-1)!.type).toBe('user/message')
 
     // Close the turn; now inject must wrap its own one-shot injection turn.
     agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
@@ -151,6 +206,16 @@ describe('Agent', () => {
     expect(agent.session.events.at(-1)!.type).toBe('turn/end') // turn-enclosed
   })
 
+  it('inject() defaults its source to an empty plugin, never user', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    agent.inject([{ type: 'text', text: 'no explicit source' }])
+    const injected = agent.session.events.at(-1)!
+    expect(injected.type === 'user/message' && injected.data.source).toEqual({ kind: 'plugin', plugin: '' })
+  })
+
   it('idle inject() contains a failing flush (logs, does not throw into the caller)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
@@ -167,24 +232,54 @@ describe('Agent', () => {
     warn.mockRestore()
   })
 
-  it('idle inject() closes its one-shot turn AND still checkpoints even if the append throws', async () => {
+  it('idle inject() validates its payload BEFORE opening a turn, so invalid input appends nothing', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
 
-    // Non-serializable injected content makes Session.append throw AFTER
-    // turn/start was recorded. The turn/end must still be appended (finally),
-    // AND the durability checkpoint must still fire — the balanced turn is in
-    // memory and a crash before the next turn/dispose would otherwise lose it.
+    // Non-serializable injected content is rejected by the up-front snapshot
+    // BEFORE any append (the unified send contract: invalid input throws before
+    // mutating the log). No one-shot turn opens and no durability checkpoint fires.
     expect(() => {
       agent.inject([{ type: 'text', text: 'x', bad: 1n } as never], { source: { kind: 'plugin', plugin: 'p' } })
-    }).toThrow(/non-JSON-serializable/)
-    const types = agent.session.events.map(e => e.type)
-    expect(types).toEqual(['turn/start', 'turn/end']) // balanced, no open turn
-    await new Promise(r => setTimeout(r, 10)) // let the fire-and-forget flush run
-    expect(flushes).toBe(1) // checkpoint fired despite the throw
+    }).toThrow(/losslessly JSON-serializable/)
+    expect(agent.session.events).toHaveLength(0)
+    await new Promise(r => setTimeout(r, 10)) // give any (erroneous) flush a chance
+    expect(flushes).toBe(0) // nothing was appended, so no checkpoint
+  })
+
+  it('idle inject() re-entered from a session/event listener is rejected pre-commit and opens no turn', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    let flushes = 0
+    ctx.on('session/flush', () => { flushes += 1 })
+    // Injecting from inside a session/event listener re-enters Session.append,
+    // which rejects pre-commit — so turn/start never commits. The finally sees
+    // no open turn (closes nothing) and no recorded turn (no checkpoint), and
+    // the reentrant throw is contained by Session's post-commit dispatch.
+    // Fire on turn/end: at that instant the outer one-shot turn is closed (no
+    // turn open), so the reentrant inject takes the idle one-shot-turn path and
+    // its turn/start append re-enters Session and is rejected pre-commit.
+    let reentered = false
+    ctx.on('session/event', (_s, event) => {
+      if (!reentered && event.type === 'turn/end') {
+        reentered = true
+        agent.inject([{ type: 'text', text: 'reentrant' }], { source: { kind: 'plugin', plugin: 'p' } })
+      }
+    })
+
+    agent.inject([{ type: 'text', text: 'outer' }], { source: { kind: 'plugin', plugin: 'p' } })
+    // The outer injection's own one-shot turn is balanced; the reentrant one
+    // opened no turn (its turn/start was rejected pre-commit).
+    const turnStarts = agent.session.events.filter(e => e.type === 'turn/start')
+    expect(turnStarts).toHaveLength(1)
+    const injected = agent.session.events.filter(e => e.type === 'user/message')
+    expect(injected).toHaveLength(1) // the reentrant user/message never committed
+    await new Promise(r => setTimeout(r, 10))
+    expect(flushes).toBe(1) // only the outer accepted turn checkpointed
   })
 
   it('idle inject() still checkpoints when a listener throws on the synthetic turn/end', async () => {
@@ -202,7 +297,7 @@ describe('Agent', () => {
 
     expect(() => { agent.inject([{ type: 'text', text: 'notice' }], { source: { kind: 'plugin', plugin: 'p' } }) }).not.toThrow()
     const types = agent.session.events.map(e => e.type)
-    expect(types).toEqual(['turn/start', 'context/message', 'turn/end']) // balanced
+    expect(types).toEqual(['turn/start', 'user/message', 'turn/end']) // balanced
     await new Promise(r => setTimeout(r, 10))
     expect(flushes).toBe(1) // checkpoint fired despite the throwing turn/end listener
   })
@@ -234,13 +329,11 @@ describe('Agent', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    // A non-serializable source makes the turn/start append throw BEFORE the
-    // event is pushed (Session.append validates before push), so NO turn opens.
-    // The finally's isTurnOpen() guard sees no open turn and appends nothing —
-    // the log stays empty, not left with a dangling turn/start.
+    // A non-serializable source is rejected by the up-front snapshot BEFORE any
+    // append, so NO turn opens and the log stays empty.
     expect(() => {
       agent.inject([{ type: 'text', text: 'x' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
-    }).toThrow(/non-JSON-serializable/)
+    }).toThrow(/losslessly JSON-serializable/)
     expect(agent.session.events).toHaveLength(0)
   })
 
@@ -397,7 +490,7 @@ describe('Agent', () => {
     const { agent } = prepared
     prepared.markPublished()
     const dispose = prepared.startDriver()
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await new Promise(r => setTimeout(r, 30))
     expect(agent.status).toBe('running')
 

packages/core/agent-loop/tests/cancel.spec.ts

@@ -33,7 +33,7 @@ async function harness(adapter: MockAdapter) {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 /** Resolve on the agent's next idle transition (event-based, not status poll). */
@@ -63,7 +63,7 @@ describe('Agent.cancel()', () => {
     ctx.on('agent/cancel-requested', (subject, cause) => {
       if (subject !== agent) return
       seen.push(`first:${cause.kind}`)
-      subject.send([{ type: 'text', text: 'queued by cancel observer' }])
+      subject.followup([{ type: 'text', text: 'queued by cancel observer' }])
       throw new Error('observer failed')
     })
     ctx.on('agent/cancel-requested', (subject, cause) => {
@@ -98,6 +98,57 @@ describe('Agent.cancel()', () => {
     expect(agent.session.events.some(e => e.type === 'turn/end')).toBe(true)
   })
 
+  it('cancel({ keepInbox: true }) preserves queued work and emits no discard', async () => {
+    const adapter = new MockAdapter([textResponse('reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const discards: unknown[] = []
+    ctx.on('agent/inbox/discard', (subject, items) => { if (subject === agent) discards.push(items) })
+
+    // Queue a turn WITHOUT waking the driver, so it sits in the inbox.
+    agent.queue([{ type: 'text', text: 'preserved' }])
+    // keepInbox cancel: no active turn, work preserved, no discard event.
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    expect(discards).toEqual([])
+
+    // The preserved item still runs once the driver is woken by a later send.
+    send(agent, 'wake it')
+    await waitForIdle(ctx, agent)
+    expect(userTexts(agent)).toEqual(['preserved', 'wake it'])
+  })
+
+  it('a lone queued message leaves the agent parked at idle', async () => {
+    const adapter = new MockAdapter([textResponse('reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    // A quiet item alone must NOT wake the driver: no turn runs and whenIdle
+    // resolves (the agent is quiescent), leaving the item queued.
+    agent.queue([{ type: 'text', text: 'quiet' }])
+    await agent.whenIdle()
+    expect(agent.status).toBe('idle')
+    expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
+
+    // A later waking send drives the loop, and the quiet item rides along first.
+    send(agent, 'wake')
+    await waitForIdle(ctx, agent)
+    expect(userTexts(agent)).toEqual(['quiet', 'wake'])
+  })
+
+  it('cancelling a parked quiet item settles a pending whenIdle() without a later send', async () => {
+    const adapter = new MockAdapter([textResponse('reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.queue([{ type: 'text', text: 'quiet' }])
+    const idle = agent.whenIdle()
+    // Cancel reaches quiescence with no status transition and no waking send;
+    // whenIdle must still resolve (previously it hung until the next send).
+    agent.cancel({ kind: 'user' })
+    await idle
+    expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
+  })
+
   it('pre-step cancel drops the about-to-start turn (no turn is opened)', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -98,7 +98,7 @@ describe('config-driven session id', () => {
       first = ctx.agents.get(SessionId('config-exact-reload'))
     }
     expect(first).toBeDefined()
-    first!.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
+    first!.followup([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
     await waitForIdle(ctx, first!)
     await firstLoop.dispose()
 
@@ -110,7 +110,7 @@ describe('config-driven session id', () => {
     }
     expect(second).toBeDefined()
     expect(JSON.stringify(second!.session.deriveMessages())).toContain('remember me')
-    second!.send([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } })
+    second!.followup([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } })
     await waitForIdle(ctx, second!)
     await ctx.sessions.flush(second!.session)
     const loaded = await ctx.sessionPersistence.load(SessionId('config-exact-reload'))
@@ -335,7 +335,7 @@ describe('config-driven session id', () => {
     expect(a1.id).toBe(a1.session.id)
     expect(a1.session.id).toMatch(idPattern)
     expect(ctx1.agents.get(SessionId('cfg'))).toBeUndefined()
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -354,7 +354,7 @@ describe('config-driven session id', () => {
     expect(a2.id).toBe(a2.session.id)
     expect(a2.session.id).toMatch(idPattern)
     expect(a2.session.id).not.toBe(a1.session.id)
-    a2.send([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
+    a2.followup([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
     await waitForIdle(ctx2, a2)
     await ctx2.fiber.dispose()
   })
@@ -375,7 +375,7 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SessionPersistenceJsonl, { root })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first')]))
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('sticky-1') })).agent
-    a1.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -50,7 +50,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('session log records what agent/step-result actually produced', () => {
@@ -275,7 +275,9 @@ describe('abort during tool execution ends the turn', () => {
           order.push(`tool/result:${event.data.callId}:${outcome}`)
           break
         }
-        case 'context/message': order.push('context/message'); break
+        // Injected context is a plugin-sourced user/message; the direct human
+        // prompt (user source) is not tracked in this ordering.
+        case 'user/message': if (event.data.source.kind !== 'user') order.push('context/message'); break
         case 'steering/message': order.push('steering/message'); break
         case 'step/end': order.push('step/end'); break
         case 'turn/end': {
@@ -354,13 +356,14 @@ describe('abort during tool execution ends the turn', () => {
     await waitForIdle(ctx, agent)
 
     const events = [...agent.session.events]
+    const isInjected = (e: SessionEvent): e is SessionEvent<'user/message'> => e.type === 'user/message' && e.data.source.kind !== 'user'
     expect(events
-      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
+      .filter(event => event.type === 'tool/result' || isInjected(event)
         || event.type === 'step/end' || event.type === 'turn/end')
-      .map(event => event.type))
+      .map(event => isInjected(event) ? 'context/message' : event.type))
       .toEqual(['tool/result', 'context/message', 'context/message', 'step/end', 'turn/end'])
     expect(events
-      .filter(event => event.type === 'context/message')
+      .filter(isInjected)
       .map(event => event.data.content))
       .toEqual([
         [{ type: 'text', text: 'accepted before abort' }],
@@ -410,12 +413,13 @@ describe('abort during tool execution ends the turn', () => {
     await waitForIdle(ctx, agent)
 
     const events = [...agent.session.events]
+    const isInjected = (e: SessionEvent): e is SessionEvent<'user/message'> => e.type === 'user/message' && e.data.source.kind !== 'user'
     expect(events
-      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
+      .filter(event => event.type === 'tool/result' || isInjected(event)
         || event.type === 'step/end' || event.type === 'turn/end')
-      .map(event => event.type))
+      .map(event => isInjected(event) ? 'context/message' : event.type))
       .toEqual(['tool/result', 'tool/result', 'context/message', 'step/end', 'turn/end'])
-    expect(events.find(event => event.type === 'context/message')?.data.content)
+    expect(events.find(isInjected)?.data.content)
       .toEqual([{ type: 'text', text: 'accepted after first result' }])
   })
 
@@ -456,7 +460,7 @@ describe('abort during tool execution ends the turn', () => {
     await fiber.dispose()
 
     expect(agent.session.events
-      .filter(event => event.type === 'context/message')
+      .filter((event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind !== 'user')
       .map(event => event.data.content))
       .toEqual([
         [{ type: 'text', text: 'accepted before disposal' }],
@@ -507,7 +511,7 @@ describe('abort during tool execution ends the turn', () => {
     send(agent, 'start a text-only turn')
     await waitForIdle(ctx, agent)
 
-    expect(agent.session.events.find(event => event.type === 'context/message')?.data.content)
+    expect(agent.session.events.find((event): event is SessionEvent<'user/message'> => event.type === 'user/message' && event.data.source.kind !== 'user')?.data.content)
       .toEqual([{ type: 'text', text: 'new turn context' }])
     expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('new turn context')
   })
@@ -763,7 +767,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     expect(agent.session.deriveMessages().at(-1)?.content).toEqual([{ type: 'text', text: 'routed' }])
   })
 
-  it('agent/queued carries the resolved source; steering/message records its source', async () => {
+  it('agent/inbox/enqueue carries the resolved source; steering/message records its source', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -778,7 +782,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     }))
 
     const queuedSources: { source: MessageSource; contexts: HookContext[]; steering: boolean }[] = []
-    ctx.on('agent/queued', (_agent, _content, info) => void queuedSources.push(info))
+    ctx.on('agent/inbox/enqueue', (_agent, info) => void queuedSources.push({ source: info.source, contexts: info.contexts, steering: info.steering }))
 
     send(agent, 'go') // no explicit source → default {kind:'user'} must be visible
     await waitForIdle(ctx, agent)
@@ -800,11 +804,11 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     let notifiedContent: ContentBlock[] | undefined
     let notifiedSource: MessageSource | undefined
     let notifiedContexts: HookContext[] | undefined
-    ctx.on('agent/queued', (subject, acceptedContent, info) => {
+    ctx.on('agent/inbox/enqueue', (subject, info) => {
       if (subject !== agent || info.steering) return
       // Retain the exact notification references: cloning here would test the
       // listener's copy rather than the event/inbox ownership boundary.
-      notifiedContent = acceptedContent
+      notifiedContent = info.content
       notifiedSource = info.source
       notifiedContexts = info.contexts
     })
@@ -814,7 +818,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
       source: { kind: 'plugin', plugin: 'context-source' },
       meta: { version: 1 },
     }]
-    agent.send(content, { source, contexts })
+    agent.followup(content, { source, contexts })
     content[0]!.text = 'caller-mutated-send'
     source.plugin = 'caller-mutated-source'
     contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-context' }
@@ -863,14 +867,14 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     let notifiedContent: ContentBlock[] | undefined
     let notifiedSource: MessageSource | undefined
     let notifiedContexts: HookContext[] | undefined
-    ctx.on('agent/queued', (subject, acceptedContent, info) => {
+    ctx.on('agent/inbox/enqueue', (subject, info) => {
       if (subject !== agent || !info.steering) return
-      notifiedContent = acceptedContent
+      notifiedContent = info.content
       notifiedSource = info.source
       notifiedContexts = info.contexts
     })
 
-    agent.send([{ type: 'text', text: 'start' }])
+    agent.followup([{ type: 'text', text: 'start' }])
     await entered.promise
     expect(agent.status).toBe('running')
     const content = [{ type: 'text' as const, text: 'accepted-steer' }]
@@ -951,7 +955,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     expect(request).not.toContain('caller-mutated-steering-context-without-meta')
 
     const steeringIndex = agent.session.events.findIndex(event => event.type === 'steering/message')
-    const contextIndex = agent.session.events.findIndex(event => event.type === 'context/message'
+    const contextIndex = agent.session.events.findIndex(event => event.type === 'user/message'
       && event.data.source.kind === 'plugin' && event.data.source.plugin === 'steering-context')
     expect(steeringIndex).toBeGreaterThanOrEqual(0)
     expect(contextIndex).toBe(steeringIndex + 1)
@@ -987,7 +991,7 @@ describe('turn numbering continues across seeded sessions', () => {
 
     const turns: number[] = []
     ctx2.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
-    forked.send([{ type: 'text', text: 'continue' }])
+    forked.followup([{ type: 'text', text: 'continue' }])
     await new Promise<void>((resolve) => {
       ctx2.on('agent/status', (subject, status) => {
         if (subject === forked && status === 'idle') resolve()

packages/core/agent-loop/tests/coverage-edges.spec.ts

@@ -38,7 +38,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('inbox acceptance', () => {
@@ -47,13 +47,13 @@ describe('inbox acceptance', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let queued = 0
-    ctx.on('agent/queued', () => { queued += 1 })
+    ctx.on('agent/inbox/enqueue', () => { queued += 1 })
 
     expect(() => {
-      agent.send([{ type: 'text', text: 'first', bad: 1n } as never])
+      agent.followup([{ type: 'text', text: 'first', bad: 1n } as never])
     }).toThrow(/losslessly JSON-serializable/)
     expect(() => {
-      agent.send([{ type: 'text', text: 'first' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
+      agent.followup([{ type: 'text', text: 'first' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
     }).toThrow(/losslessly JSON-serializable/)
     expect(queued).toBe(0)
     expect(agent.session.events).toHaveLength(0)

packages/core/agent-loop/tests/inbox-invariant.spec.ts

@@ -0,0 +1,155 @@
+/**
+ * Regression: the dsh-agent FIFO-conservation invariant must stay balanced on
+ * the loop-authored continuation-reason steering path. A continue-with-reason
+ * decision enters the steering FIFO and later drains (or is discarded by
+ * cancel); both must be matched by an enqueue event so the invariant's
+ * outstanding count never goes negative.
+ * @module dsh-agent-loop/tests/inbox-invariant
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse } from './mock-adapter.ts'
+
+async function harness(adapter: MockAdapter) {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(AgentInvariant)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') { dispose(); resolve() }
+    })
+  })
+}
+
+describe('inbox FIFO-conservation invariant', () => {
+  it('stays balanced when a continuation reason enters and drains the steering FIFO', async () => {
+    const adapter = new MockAdapter([textResponse('step 1'), textResponse('step 2')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    let forced = false
+    ctx.on('agent/turn-continuation', async (_agent, _turn, _default, _signal, next) => {
+      if (forced) return next()
+      forced = true
+      return { action: 'continue' as const, reason: { content: [{ type: 'text', text: 'keep going' }], source: { kind: 'plugin', plugin: 'loop' } } }
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(2)
+    // The continuation reason drained as a steering/message on the second step.
+    expect(agent.session.events.some(e => e.type === 'steering/message')).toBe(true)
+    // No invariant violation was logged.
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+
+  it('stays balanced when cancel discards a pending continuation reason', async () => {
+    const adapter = new MockAdapter([textResponse('only step')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    // Force a continuation reason, then cancel from the same checkpoint so the
+    // reason sits in the steering FIFO when the inbox is discarded.
+    ctx.on('agent/turn-continuation', async (subject, _turn, _default, _signal, next) => {
+      if (subject !== agent) return next()
+      queueMicrotask(() => { agent.cancel({ kind: 'user' }) })
+      return { action: 'continue' as const, reason: { content: [{ type: 'text', text: 'keep going' }], source: { kind: 'plugin', plugin: 'loop' } } }
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+
+  it('stays balanced when a terminal stop discards pending steering', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    const discards: number[] = []
+    ctx.on('agent/inbox/discard', (subject, messages) => { if (subject === agent) discards.push(messages.length) })
+
+    // A continuation reason enqueues a steering item; a terminal stop then drops
+    // it. The drop must emit a discard so the enqueue ⇒ dequeue-or-discard
+    // ledger stays balanced (no dangling outstanding id).
+    ctx.on('agent/turn-continuation', async (subject, _turn, _default, _signal, next) => {
+      if (subject !== agent) return next()
+      return { action: 'continue' as const, reason: { content: [{ type: 'text', text: 'keep going' }], source: { kind: 'plugin', plugin: 'loop' } } }
+    })
+    let stopped = false
+    ctx.on('agent/turn-stop', (subject) => {
+      if (subject !== agent || stopped) return undefined
+      stopped = true
+      return { action: 'stop' as const }
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(discards).toEqual([1]) // the dropped steering item was reported
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+
+  it('stays balanced when late steering lands after a terminal stop (post-turn flush window)', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    let enqueues = 0
+    const discards: number[] = []
+    ctx.on('agent/inbox/enqueue', (subject) => { if (subject === agent) enqueues += 1 })
+    ctx.on('agent/inbox/discard', (subject, messages) => { if (subject === agent) discards.push(messages.length) })
+
+    // Terminal-stop the turn, then steer during the post-turn flush window
+    // (status is still running). That late steer is drained by runLoop and
+    // dropped because the turn terminally stopped; it must still be discarded so
+    // its enqueue is matched (the drain sits on a different code path than the
+    // in-turn terminal-stop drop).
+    ctx.on('agent/turn-stop', subject => (subject === agent ? { action: 'stop' as const } : undefined))
+    let steered = false
+    ctx.on('session/flush', (session) => {
+      if (session !== agent.session || steered) return
+      steered = true
+      agent.steer([{ type: 'text', text: 'late' }], { source: { kind: 'plugin', plugin: 'late' } })
+    })
+
+    agent.followup([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    // The prompt plus the late steer both enqueued; both are matched (the prompt
+    // dequeued, the late steer discarded) so no id is left outstanding.
+    expect(enqueues).toBe(2)
+    expect(discards).toEqual([1])
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('agent/inbox'))).toBe(false)
+    expect(warn.mock.calls.flat().some(arg => String(arg).includes('INVARIANT'))).toBe(false)
+  })
+})

packages/core/agent-loop/tests/inbox.spec.ts

@@ -1,10 +1,20 @@
 import { describe, expect, it } from 'vitest'
-import { Inbox } from '../src/inbox.ts'
+import { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import { Inbox, agentMessage } from '../src/inbox.ts'
 
 function message(text: string) {
-  return { content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [] }
+  return { id: AgentMessageId(text), content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [], wakeup: true }
 }
 
+describe('agentMessage', () => {
+  it('returns a frozen payload so a listener cannot mutate it for later listeners', () => {
+    const payload = agentMessage(message('m'), false)
+    expect(Object.isFrozen(payload)).toBe(true)
+    expect(() => { (payload as { id: string }).id = 'mutated' }).toThrow()
+    expect(payload.id).toBe(AgentMessageId('m'))
+  })
+})
+
 function resolverPair() {
   let r!: () => void
   const p = new Promise<void>((resolve) => { r = resolve })
@@ -25,6 +35,32 @@ describe('Inbox', () => {
     expect(inbox.dequeueQueued()).toBeUndefined()
   })
 
+  it('enqueue(msg, false) queues without waking a parked waiter', async () => {
+    const inbox = new Inbox()
+    let woke = false
+    const waiter = inbox.waitForQueued(new Promise(() => {})).then(() => { woke = true })
+    inbox.enqueue(message('quiet'), false)
+    // The item is queued, but the parked waiter was not resolved by it.
+    expect(inbox.hasQueued).toBe(true)
+    await Promise.resolve()
+    expect(woke).toBe(false)
+    // A later waking enqueue resolves the same waiter.
+    inbox.enqueue(message('loud'))
+    await waiter
+    expect(woke).toBe(true)
+  })
+
+  it('pending() snapshots queued then steering without removing them', () => {
+    const inbox = new Inbox()
+    inbox.enqueue(message('q'))
+    inbox.steer(message('s'))
+    const pending = inbox.pending()
+    expect(pending.map(p => p.steering)).toEqual([false, true])
+    // Snapshot does not drain the FIFOs.
+    expect(inbox.hasQueued).toBe(true)
+    expect(inbox.hasSteering).toBe(true)
+  })
+
   it('pushes and drains steering messages separately from queued', () => {
     const inbox = new Inbox()
     inbox.steer(message('steer'))

packages/core/agent-loop/tests/interception.spec.ts

@@ -42,7 +42,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 function events(agent: Agent): SessionEvent[] {
@@ -87,7 +87,7 @@ describe('agent/prompt-submit', () => {
     expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('original')
   })
 
-  it('allow with additionalContexts injects separate context/message events into the turn', async () => {
+  it('allow with additionalContexts injects separate injected-context user messages into the turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -107,12 +107,12 @@ describe('agent/prompt-submit', () => {
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
-    const userMsg = log.find(e => e.type === 'user/message')
-    const ctxMsg = log.find(e => e.type === 'context/message')
+    const userMsg = log.find(e => e.type === 'user/message' && e.data.source.kind === 'user')
+    const ctxMsg = log.find(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
     expect(userMsg).toBeDefined()
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }])
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.meta).toEqual(meta)
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }])
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.meta).toEqual(meta)
     const sent = JSON.stringify(adapter.requests[0]!.messages)
     expect(sent).toContain('extra ctx')
   })
@@ -128,7 +128,7 @@ describe('agent/prompt-submit', () => {
         ? downstream
         : { ...downstream, content: [{ type: 'text', text: 'rewritten request' }] }
     })
-    agent.send([{ type: 'text', text: 'original request' }], {
+    agent.followup([{ type: 'text', text: 'original request' }], {
       contexts: [{
         content: [{ type: 'text', text: 'untrusted prefix' }],
         source: { kind: 'plugin', plugin: 'prefix' },
@@ -155,7 +155,7 @@ describe('agent/prompt-submit', () => {
         }],
       },
     })
-    expect(log.some(event => event.type === 'context/message')).toBe(false)
+    expect(log.some(event => event.type === 'user/message' && event.data.source.kind === 'plugin')).toBe(false)
     expect(adapter.requests[0]?.messages.at(-1)).toEqual({
       role: 'user',
       content: [
@@ -203,7 +203,7 @@ describe('agent/prompt-submit', () => {
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
 
-    agent.send([{ type: 'text', text: 'do something' }], {
+    agent.followup([{ type: 'text', text: 'do something' }], {
       contexts: [{ content: [{ type: 'text', text: 'must be dropped' }], source: { kind: 'plugin', plugin: 'test' } }],
     })
     await waitForIdle(ctx, agent)
@@ -215,7 +215,6 @@ describe('agent/prompt-submit', () => {
     expect(log.some(e => e.type === 'turn/start')).toBe(true)
     expect(log.some(e => e.type === 'turn/end')).toBe(true)
     expect(log.some(e => e.type === 'user/message')).toBe(false)
-    expect(log.some(e => e.type === 'context/message')).toBe(false)
     expect(log.some(e => e.type === 'step/start')).toBe(false)
     // the veto is recorded durably as a prompt/blocked in the open turn
     const blocked = log.find(e => e.type === 'prompt/blocked')
@@ -340,8 +339,8 @@ describe('agent/session-start', () => {
     // the injected context reached the model on the first (only) request
     expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('session preamble')
     // and is recorded with the plugin source, never mislabeled as a user prompt
-    const ctxMsg = events(agent).find(e => e.type === 'context/message')
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
+    const ctxMsg = events(agent).find(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
   })
 
   it('a throwing session-start listener does not abort agent construction', async () => {
@@ -624,23 +623,22 @@ describe('tool additionalContexts buffering across a step', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    // Event order in the log: both tool/results, THEN both context/messages —
+    // Event order in the log: both tool/results, THEN both injected contexts —
     // never interleaved (which would break tool-call/result adjacency).
-    const types = events(agent).map(e => e.type)
-    const firstResult = types.indexOf('tool/result')
-    const lastResult = types.lastIndexOf('tool/result')
-    const firstCtx = types.indexOf('context/message')
+    const injected = events(agent).filter(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
+    const seqs = events(agent)
+    const firstResult = seqs.findIndex(e => e.type === 'tool/result')
+    const lastResult = seqs.map(e => e.type).lastIndexOf('tool/result')
+    const firstCtx = seqs.findIndex(e => e === injected[0])
     expect(firstResult).toBeGreaterThanOrEqual(0)
     expect(lastResult).toBeGreaterThan(firstResult) // two results
     expect(firstCtx).toBeGreaterThan(lastResult)    // context only after ALL results
     // both contexts present
-    const ctxTexts = events(agent)
-      .filter(e => e.type === 'context/message')
-      .flatMap(e => (e.type === 'context/message' ? e.data.content : []))
+    const ctxTexts = injected
+      .flatMap(e => (e.type === 'user/message' ? e.data.content : []))
       .map(b => (b.type === 'text' ? b.text : ''))
     expect(ctxTexts).toEqual(['ctx-c1', 'ctx-c2'])
-    const contextEvents = events(agent).filter(e => e.type === 'context/message')
-    expect(contextEvents.map(e => e.type === 'context/message' && e.data.meta)).toEqual([{ callId: 'c1' }, { callId: 'c2' }])
+    expect(injected.map(e => e.type === 'user/message' && e.data.meta)).toEqual([{ callId: 'c1' }, { callId: 'c2' }])
   })
 
   it('appends multiple contexts deferred by one composite tool after its outer result', async () => {
@@ -661,14 +659,14 @@ describe('tool additionalContexts buffering across a step', () => {
 
     const log = events(agent)
     const resultIndex = log.findIndex(event => event.type === 'tool/result')
-    const contextEvents = log.filter(event => event.type === 'context/message')
+    const contextEvents = log.filter(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
     expect(resultIndex).toBeGreaterThanOrEqual(0)
     expect(log.findIndex(event => event === contextEvents[0])).toBeGreaterThan(resultIndex)
-    expect(contextEvents.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+    expect(contextEvents.map(event => event.type === 'user/message' && event.data.source)).toEqual([
       { kind: 'plugin', plugin: 'a' },
       { kind: 'plugin', plugin: 'b' },
     ])
-    expect(contextEvents.map(event => event.type === 'context/message' && event.data.meta)).toEqual([{ order: 1 }, { order: 2 }])
+    expect(contextEvents.map(event => event.type === 'user/message' && event.data.meta)).toEqual([{ order: 1 }, { order: 2 }])
   })
 })
 
@@ -750,13 +748,13 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
 
     const log = events(agent)
     // session-start preamble injected
-    expect(log.some(e => e.type === 'context/message'
+    expect(log.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('policy active (started: startup)')))).toBe(true)
-    // prompt allowed → user/message recorded
-    expect(log.some(e => e.type === 'user/message')).toBe(true)
+    // prompt allowed → user-sourced user/message recorded
+    expect(log.some(e => e.type === 'user/message' && e.data.source.kind === 'user')).toBe(true)
     // tool ran (echo allowed) and post-execute attached "audited" context
     expect(log.some(e => e.type === 'tool/result' && !e.data.isError)).toBe(true)
-    expect(log.some(e => e.type === 'context/message'
+    expect(log.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin'
       && e.data.content.some(b => b.type === 'text' && b.text === 'audited'))).toBe(true)
     // NO hook/* events — a native plugin needs none
     expect(log.some(e => e.type.startsWith('hook/'))).toBe(false)

packages/core/agent-loop/tests/invariant.spec.ts

@@ -42,7 +42,7 @@ describe('request-reconstruction invariant', () => {
 
   it('uses the step boundary rather than content appended afterward', async () => {
     const { ctx, session, boundary } = await requestSetup()
-    session.append('context/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
+    session.append('user/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
     const options = loopRequest({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
     expect(() => { dispatch(ctx, options) }).not.toThrow()
   })

packages/core/agent-loop/tests/loop.spec.ts

@@ -42,7 +42,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 describe('agent loop', () => {
@@ -391,7 +391,7 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.inject([{ type: 'text', text: 'file changed: a.ts' }], { source: { kind: 'plugin', plugin: 'watcher' } })
-    // The idle inject records a self-contained turn (turn/start → context/message
+    // The idle inject records a self-contained turn (turn/start → user/message
     // → turn/end) so the event stays turn-enclosed, but does NOT run the model.
     await new Promise(r => setTimeout(r, 20))
     expect(agent.status).toBe('idle')
@@ -427,8 +427,8 @@ describe('agent loop', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    const contextEvent = agent.session.events.find(event => event.type === 'context/message')
-    expect(contextEvent?.type === 'context/message' && contextEvent.data).toMatchObject({ meta })
+    const contextEvent = agent.session.events.find(event => event.type === 'user/message' && event.data.source.kind === 'plugin')
+    expect(contextEvent?.type === 'user/message' && contextEvent.data).toMatchObject({ meta })
     const requestText = JSON.stringify(adapter.requests[0]!.messages)
     expect(requestText).toContain('Additional instructions from: pkg/AGENTS.md')
     expect(requestText).not.toContain('<context source=')
@@ -456,7 +456,7 @@ describe('agent loop', () => {
         })
         first.text = 'mutated after inject'
         agent.inject([{ type: 'text', text: 'second notice' }], { source: { kind: 'plugin', plugin: 'x' } })
-        visibleDuringTool = agent.session.events.some(e => e.type === 'context/message')
+        visibleDuringTool = agent.session.events.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
         return [{ type: 'text', text: 'ok' }]
       },
     }))
@@ -473,13 +473,13 @@ describe('agent loop', () => {
     const ts0 = turnStarts[0]!
     expect(ts0.type === 'turn/start' && ts0.data.trigger.kind).toBe('message')
     const result = agent.session.events.find(e => e.type === 'tool/result')!
-    const contexts = agent.session.events.filter(e => e.type === 'context/message')
+    const contexts = agent.session.events.filter(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
     expect(contexts).toHaveLength(2)
     expect(result.seq).toBeLessThan(contexts[0]!.seq)
-    expect(contexts[0]?.type === 'context/message' && contexts[0].data).toMatchObject({
+    expect(contexts[0]?.type === 'user/message' && contexts[0].data).toMatchObject({
       meta,
     })
-    expect(contexts.flatMap(event => event.type === 'context/message' ? event.data.content : []))
+    expect(contexts.flatMap(event => event.type === 'user/message' ? event.data.content : []))
       .toEqual([
         { type: 'text', text: 'mid-turn notice' },
         { type: 'text', text: 'second notice' },
@@ -523,7 +523,29 @@ describe('agent loop', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    expect(agent.session.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(agent.session.events.some(event => event.type === 'user/message' && event.data.source.kind === 'plugin')).toBe(false)
+  })
+
+  it('preserves SendOptions.meta on the durable user/message and steering/message', async () => {
+    const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineContentToolFixture({
+      name: 'noop', description: '', parameters: {},
+      async execute() {
+        // Running steer carries its own meta onto the durable steering/message.
+        agent.steer([{ type: 'text', text: 's' }], { source: { kind: 'plugin', plugin: 'p' }, meta: { steer: 1 } })
+        return []
+      },
+    }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.followup([{ type: 'text', text: 'go' }], { meta: { prompt: 1 } })
+    await waitForIdle(ctx, agent)
+
+    const user = agent.session.events.find(e => e.type === 'user/message')
+    expect(user?.type === 'user/message' && user.data.meta).toEqual({ prompt: 1 })
+    const steering = agent.session.events.find(e => e.type === 'steering/message')
+    expect(steering?.type === 'steering/message' && steering.data.meta).toEqual({ steer: 1 })
   })
 
   it('agent/turn-continuation can force-continue (/loop pattern) and force-stop', async () => {
@@ -632,7 +654,7 @@ describe('agent loop', () => {
     ctx.on('agent/pre-step', (subject) => {
       if (subject === agent && !injected) {
         injected = true
-        subject.session.append('context/message', {
+        subject.session.append('user/message', {
           content: [{ type: 'text', text: 'INJECTED-IN-PRE-STEP' }],
           source: { kind: 'plugin', plugin: 'test' },
         }, { surfaceOp: 'append' })
@@ -650,7 +672,7 @@ describe('agent loop', () => {
     // And the injected event sits BEFORE the first step/start in the log —
     // the seam fired outside the step.
     const events = agent.session.events
-    const injectedSeq = events.find(e => e.type === 'context/message')!.seq
+    const injectedSeq = events.find(e => e.type === 'user/message' && e.data.source.kind === 'plugin')!.seq
     const firstStepStartSeq = events.find(e => e.type === 'step/start')!.seq
     expect(injectedSeq).toBeLessThan(firstStepStartSeq)
   })
@@ -1028,13 +1050,13 @@ describe('agent loop', () => {
     expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('turn-end listener message')
   })
 
-  it('keeps a reentrant agent/queued send as the next independent turn', async () => {
+  it('keeps a reentrant agent/inbox/enqueue send as the next independent turn', async () => {
     const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let nested = false
-    ctx.on('agent/queued', (subject) => {
+    ctx.on('agent/inbox/enqueue', (subject) => {
       if (subject !== agent || nested) return
       nested = true
       send(agent, 'queued listener message')
@@ -1061,9 +1083,9 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const idle = waitForIdle(ctx, agent)
-    agent.send([{ type: 'text', text: 'user message' }])
+    agent.followup([{ type: 'text', text: 'user message' }])
     await Promise.resolve()
-    agent.send(
+    agent.followup(
       [{ type: 'text', text: 'plugin message' }],
       { source: { kind: 'plugin', plugin: 'test' } },
     )

packages/core/agent-loop/tests/properties.spec.ts

@@ -115,7 +115,7 @@ describe('agent loop scheduling properties', () => {
           const { seen: trace } = recordStatus(ctx, agent)
           const idle = nextIdle(ctx, agent)
           // Send all in one synchronous tick: they queue before the loop wakes.
-          for (const text of texts) agent.send([{ type: 'text', text }])
+          for (const text of texts) agent.followup([{ type: 'text', text }])
           await idle
 
           // No message lost: every send appears as a user/message, in order.
@@ -142,7 +142,7 @@ describe('agent loop scheduling properties', () => {
           const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           for (const text of texts) {
             const idle = nextIdle(ctx, agent)
-            agent.send([{ type: 'text', text }])
+            agent.followup([{ type: 'text', text }])
             await idle
           }
           // Each send was drained at a separate turn start: N turns, 1..N.
@@ -171,7 +171,7 @@ describe('agent loop scheduling properties', () => {
           for (const step of steps) {
             const idle = nextIdle(ctx, agent)
             lastIdle = idle
-            agent.send([{ type: 'text', text: step.text }])
+            agent.followup([{ type: 'text', text: step.text }])
             if (step.settle) await idle
           }
           await lastIdle

packages/core/agent-loop/tests/request-cache.e2e.ts

@@ -73,10 +73,10 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('log-derived request cache hits (
     const agent = ctx.agentLoop.create(SessionId('cache-e2e'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     // Turn 1: forces a tool call → at least two steps (two model requests).
-    agent.send([{ type: 'text', text: 'Look up the key "deploy-color" with the lookup tool and tell me the value.' }])
+    agent.followup([{ type: 'text', text: 'Look up the key "deploy-color" with the lookup tool and tell me the value.' }])
     await waitForIdle(ctx, agent)
     // Turn 2: a follow-up over the same (longer) prefix.
-    agent.send([{ type: 'text', text: 'Thanks. Repeat that value one more time.' }])
+    agent.followup([{ type: 'text', text: 'Thanks. Repeat that value one more time.' }])
     await waitForIdle(ctx, agent)
 
     const usages = [...agent.session.events]

packages/core/agent-loop/tests/request-reconstruction.spec.ts

@@ -41,7 +41,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent, text: string) {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
 }
 
 /** Assert `previous` is a strict value-prefix of `current`. */
@@ -118,7 +118,7 @@ describe('request stability across the loop', () => {
       preStep()
       const session = agent.session
       const nodes = session.surface.nodes
-      session.append('context/message', {
+      session.append('user/message', {
         content: [{ type: 'text', text: '[summary of turn 1]' }],
         source: { kind: 'plugin', plugin: 'test-compact' },
       }, {
@@ -180,7 +180,7 @@ describe('request stability across the loop', () => {
     const first = adapter.requests[0]!
     // The inject landed in the log after the boundary: not in THIS request…
     expect(first.messages.some(m => m.content.some(b => b.type === 'text' && b.text.includes('[late context]')))).toBe(false)
-    expect(agent.session.events.some(e => e.type === 'context/message')).toBe(true)
+    expect(agent.session.events.some(e => e.type === 'user/message' && e.data.source.kind === 'plugin')).toBe(true)
 
     send(agent, 'second')
     await waitForIdle(ctx, agent)

packages/core/agent-loop/tests/request-recovery.spec.ts

@@ -114,7 +114,7 @@ function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
 }
 
 function send(agent: Agent): void {
-  agent.send([{ type: 'text', text: 'go' }])
+  agent.followup([{ type: 'text', text: 'go' }])
 }
 
 function contextError(message = 'context too large'): LlmError {
@@ -154,12 +154,15 @@ describe('agent post-step and request-error lifecycle', () => {
     const agent = ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
     const order: string[] = []
     ctx.on('session/event', (_session, event) => {
+      // Injected context is a plugin-sourced user/message; the direct human
+      // prompt (user source) stays untracked as before.
+      const isInjected = event.type === 'user/message' && event.data.source.kind !== 'user'
       if (
         event.type === 'assistant/message' || event.type === 'tool/call'
-        || event.type === 'tool/result' || event.type === 'context/message'
+        || event.type === 'tool/result' || isInjected
         || event.type === 'steering/message' || event.type === 'step/end'
       ) {
-        if (!('step' in event.data) || event.data.step === 1) order.push(event.type)
+        if (!('step' in event.data) || event.data.step === 1) order.push(isInjected ? 'context/message' : event.type)
       }
     })
     ctx.on('agent/post-step', (subject, turn, step, signal) => {
@@ -271,7 +274,7 @@ describe('agent post-step and request-error lifecycle', () => {
       expect({ turn, step, code: error.code }).toEqual({ turn: 1, step: 1, code: CONTEXT_WINDOW_EXCEEDED_CODE })
       expect(facts.code).toBe(CONTEXT_WINDOW_EXCEEDED_CODE)
       attempts.push(history.length)
-      subject.session.append('context/message', {
+      subject.session.append('user/message', {
         content: [{ type: 'text', text: 'RECOVERY SURFACE MUTATION' }],
         source: { kind: 'plugin', plugin: 'test-recovery' },
       }, { surfaceOp: 'append' })
@@ -288,7 +291,7 @@ describe('agent post-step and request-error lifecycle', () => {
     const ends = agent.session.events.filter(event => event.type === 'step/end')
     expect(starts.map(event => event.data.step)).toEqual([1, 2])
     expect(ends.map(event => event.data.step)).toEqual([1, 2])
-    const recovery = agent.session.events.find(event => event.type === 'context/message')!
+    const recovery = agent.session.events.find(event => event.type === 'user/message' && event.data.source.kind === 'plugin')!
     expect(ends[0]!.seq).toBeLessThan(recovery.seq)
     expect(recovery.seq).toBeLessThan(starts[1]!.seq)
   })

packages/core/agent-loop/tests/resume.spec.ts

@@ -146,7 +146,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('nocwd-sess') })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -174,7 +174,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     ctx1.on('agent/session-start', (_agent, source) => void sources1.push(source))
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('start-sess') })).agent
     expect(sources1).toEqual(['startup'])
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
 
@@ -480,7 +480,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
     // Let inject()'s fire-and-forget flush settle (NO explicit flush/dispose).
@@ -503,7 +503,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
     await ctx1.sessions.flush(a1.session)
@@ -531,7 +531,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('first answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })).agent
-    a1.send([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
+    a1.followup([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     const events1 = [...a1.session.events]
     const seqs1 = events1.map(e => e.seq)
@@ -558,7 +558,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     expect(a2.session.deriveMessages()).toEqual(replay.deriveMessages())
 
     // …and a new turn continues numbering (turn 2) with contiguous seqs.
-    a2.send([{ type: 'text', text: 'second question' }], { source: { kind: 'user' } })
+    a2.followup([{ type: 'text', text: 'second question' }], { source: { kind: 'user' } })
     await waitForIdle(ctx2, a2)
     const allSeqs = a2.session.events.map(e => e.seq)
     expect(allSeqs).toEqual(allSeqs.map((_, i) => i)) // 0..N contiguous, no duplicates

packages/core/agent-loop/tests/scope-lifecycle.spec.ts

@@ -203,11 +203,11 @@ describe('agent scope lifecycle', () => {
       if (event.type === 'user/message') heard.push('a-sees:user-message')
     })
 
-    b.send(text('for b'))
+    b.followup(text('for b'))
     await waitForIdle(ctx, b)
     expect(heard).toEqual([]) // nothing of b's leaked into a's scope
 
-    a.send(text('for a'))
+    a.followup(text('for a'))
     await waitForIdle(ctx, a)
     expect(heard).toContain('a-sees:a:running')
     expect(heard).toContain('a-sees:user-message')
@@ -934,7 +934,7 @@ describe('agent scope lifecycle', () => {
         if (event.type === 'turn/start') { off(); resolve() }
       })
     })
-    agent.send(text('work'))
+    agent.followup(text('work'))
     await turnOpen
     await owner.dispose()
     expect(order).toEqual(['turn-end', 'disposed(listed=false)', 'session-still-stored=true'])

packages/core/agent-loop/tests/tool-calls.spec.ts

@@ -105,7 +105,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 3)
     expect(gated.started).toEqual(['1', '2', '3'])
     gated.release('1'); gated.release('2'); gated.release('3')
@@ -133,7 +133,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
       async execute(args) { order.push(`w-${args.id}`); return [{ type: 'text', text: 'w' }] },
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(order).toEqual(['r-start-A1', 'r-end-A1', 'w-A2', 'r-start-A3', 'r-end-A3'])
@@ -169,7 +169,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => replacement.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
     expect(replacement.started).toEqual(['1'])
@@ -200,7 +200,7 @@ describe('tool-call scheduler: grouping and barriers', () => {
     })
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => initial.started.length === 2)
     initial.release('1')
     await until(() => events(agent).some(event =>
@@ -226,7 +226,7 @@ describe('tool-call scheduler: model-order results despite out-of-order settleme
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     gated.release('2')
     await new Promise(r => setTimeout(r, 5))
@@ -248,7 +248,7 @@ describe('tool-call scheduler: model-order results despite out-of-order settleme
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     gated.release('2'); gated.release('1')
     await waitForIdle(ctx, agent)
@@ -294,7 +294,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     await new Promise(r => setTimeout(r, 5))
     expect(gated.started).toEqual(['1', '2'])
@@ -323,7 +323,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
     expect(gated.started).toEqual(['1'])
@@ -349,7 +349,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>
     const gated = gatedParallelTool('p')
     ctx.tools.register(gated.tool)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 1)
     await new Promise(r => setTimeout(r, 5))
     expect(gated.started).toEqual(['1'])
@@ -376,7 +376,7 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
     ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => { post.push(String(exec.callId)); return next() })
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 3)
     gated.release('3'); gated.release('2'); gated.release('1')
     await waitForIdle(ctx, agent)
@@ -397,17 +397,17 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
       ({ kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }] }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     gated.release('2'); gated.release('1')
     await waitForIdle(ctx, agent)
 
     const log = events(agent)
-    const contextTexts = log.filter(e => e.type === 'context/message')
-      .map(e => (e.data.content[0] as { text: string }).text)
+    const contextTexts = log.filter(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
+      .map(e => ((e.data as { content: { text: string }[] }).content[0]!).text)
     expect(contextTexts).toEqual(['ctx-c1', 'ctx-c2'])
     const lastResult = log.findLastIndex(e => e.type === 'tool/result')
-    const firstContext = log.findIndex(e => e.type === 'context/message')
+    const firstContext = log.findIndex(e => e.type === 'user/message' && e.data.source.kind === 'plugin')
     expect(lastResult).toBeLessThan(firstContext)
   })
 
@@ -435,7 +435,7 @@ describe('tool-call scheduler: ordered middleware and additional contexts', () =
     })
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 1)
     gated.release('1')
     await waitForIdle(ctx, agent)
@@ -465,7 +465,7 @@ describe('tool-call scheduler: abort handling', () => {
       }
     })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(gated.started).toEqual([])
@@ -497,7 +497,7 @@ describe('tool-call scheduler: abort handling', () => {
       return next()
     })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
     expect(gated.started).toEqual([])
@@ -527,7 +527,7 @@ describe('tool-call scheduler: abort handling', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     agent.cancel({ kind: 'user' })
     gated.release('1')
@@ -548,10 +548,11 @@ describe('tool-call scheduler: abort handling', () => {
         { callId: CallId('c3'), isError: true, errorInfo: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
         { callId: CallId('c4'), isError: true, errorInfo: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } },
       ])
-    const settled = events(agent).filter(e => e.type === 'tool/result' || e.type === 'context/message')
+    const settled = events(agent).filter(e => e.type === 'tool/result'
+      || (e.type === 'user/message' && e.data.source.kind === 'plugin'))
     expect(settled.map(e => e.type))
-      .toEqual(['tool/result', 'tool/result', 'tool/result', 'tool/result', 'context/message', 'context/message'])
-    expect(settled.filter(e => e.type === 'context/message')
+      .toEqual(['tool/result', 'tool/result', 'tool/result', 'tool/result', 'user/message', 'user/message'])
+    expect(settled.filter(e => e.type === 'user/message')
       .map(e => (e.data.content[0] as { text: string }).text))
       .toEqual(['ctx-c1', 'ctx-c2'])
   })
@@ -577,7 +578,7 @@ describe('tool-call scheduler: abort handling', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await until(() => gated.started.length === 2)
     agent.cancel({ kind: 'user' })
     gated.release('1')

packages/core/agent-loop/tests/tool-order.spec.ts

@@ -58,7 +58,7 @@ async function runTurn(registrationOrder: string[], toolOrder?: SystemPromptConf
   const ctx = await harness(adapter, toolOrder)
   for (const name of registrationOrder) registerNamed(ctx, name)
   const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-  agent.send([{ type: 'text', text: 'go' }])
+  agent.followup([{ type: 'text', text: 'go' }])
   await waitForIdle(ctx, agent)
   return { ctx, agent, adapter }
 }
@@ -100,7 +100,7 @@ describe('loop-level canonical tool order', () => {
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    agent.send([{ type: 'text', text: 'go' }])
+    agent.followup([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(0)
     expect(errors.map(e => e.message)).toEqual(['toolOrder lists unregistered tool "ghost"; known tools: alpha'])

packages/core/agent-loop/tests/turn-stop.spec.ts

@@ -34,7 +34,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
 }
 
 function send(agent: Agent, text = 'go'): Promise<void> {
-  agent.send([{ type: 'text', text }])
+  agent.followup([{ type: 'text', text }])
   return agent.whenIdle()
 }
 
@@ -116,7 +116,7 @@ describe('agent/turn-stop', () => {
     ctx.on('session/flush', (session) => {
       if (session !== agent.session || queued) return
       queued = true
-      agent.send([{ type: 'text', text: 'ordinary queued follow-up' }])
+      agent.followup([{ type: 'text', text: 'ordinary queued follow-up' }])
     })
 
     await send(agent)

packages/core/agent/README.md

@@ -48,18 +48,20 @@ The lifecycle edges have two important local caveats. `agent/created` runs after
 
 Most interception points are cooperative waterfalls returning seam-specific decisions. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. The signal remains authoritative through terminal policy and is retired immediately before `turn/end` publication, so terminal observers and the following durability flush cannot cancel completed turn work. `agent/pre-step` and `agent/post-step` are serial checkpoints around a step's durable work, while `agent/request-error` is the failed-model-request recovery waterfall: it receives the exact error, normalized failure facts, immutable prior-retried facts, and signal after the failed step closes; a retry opens a new numbered step. `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
 
-`PromptDecision.additionalContexts` is an array so every context keeps its own source, metadata, and placement. `SendOptions.contexts` binds the same shape to one queued message before prompt interception: the default allow decision carries it forward, while a blocked prompt records no context. Absent or `separate` placement writes an independent `context/message`; `prompt-prefix` writes the context, `## My request:` delimiter, and effective prompt into one `user/message` or `steering/message`, whose model-hidden envelope retains the direct prompt and context descriptors for human replay. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; the returned allow is authoritative. A `ContinuationDecision` reason is narrower: it becomes a `steering/message` without attached context metadata.
+`PromptDecision.additionalContexts` is an array so every context keeps its own source, metadata, and placement. `SendOptions.contexts` binds the same shape to one queued message before prompt interception: the default allow decision carries it forward, while a blocked prompt records no context. Absent or `separate` placement writes an independent injected `user/message` (plugin/goal source); `prompt-prefix` writes the context, `## My request:` delimiter, and effective prompt into one `user/message` or `steering/message`, whose model-hidden envelope retains the direct prompt and context descriptors for human replay. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; the returned allow is authoritative. A `ContinuationDecision` reason is narrower: it becomes a `steering/message` without attached context metadata.
 
 Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md).
 
 ### Agent interface (`types.ts`)
 
-The handle every plugin programs against:
+`Agent` is a structural interface. `followup()`, `queue()`, `steer()`, and `inject()` name common caller intents; `send(ResolvedAgentInput)` exposes the same acceptance path when a caller already has exact routing facts ([decision](../../../.agents/notes/implemented/architecture/2026-07-24-intent-named-agent-delivery.md)). Every `ResolvedAgentInput` field is mandatory, and its discriminated union excludes attached contexts from non-waking next-step injection. FIFO acceptance returns an opaque `AgentMessageId` carried by that item's `agent/inbox/enqueue`/`dequeue`/`discard` events. The driver snapshots content, resolved source, attached contexts, and model-hidden metadata as one detached, deeply frozen lossless-JSON record before notification and enqueue; invalid data throws synchronously. The helpers apply defaults: omitting `options.source` on `followup()`, `queue()`, or `steer()` attests direct human input as `{ kind: 'user' }`, so every non-human producer labels its content.
 
-- `agent.send(content, options?)` — queue one independent FIFO item. If claimed, that item becomes the sole ordinary message in its turn; a claimed FIFO successor waits for that turn's checkpoint to settle. Broad cancellation, disposal, or a pre-start failure may instead drop it without a turn. Omitting `options.source` attests direct human input as `{ kind: 'user' }` and may authorize policy consumers, so plugins, schedulers, and other non-human producers provide their own source. Content, resolved source, and `options.contexts` become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input. After admission, separate contexts become `context/message` events, while prompt-prefix contexts are baked before the effective request in the same `user/message`; a block or replacement of the default additional-context decision can discard them. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
-- `agent.steer(content, options?)` — while running, queue steering for the next checkpoint without dispatching `agent/prompt-submit`; when idle, delegate to `send()`. Attached contexts remain in the same frozen record; separate contexts append immediately after the steering event, while prompt-prefix contexts are baked into that steering event. Both survive late-steering conversion to queued input and disappear with their message on cancellation or terminal discard. Policy can still stop before another step; after turn close and its checkpoint, remaining steering becomes later queued input unless terminal turn policy, cancellation, or disposal discards it.
-- `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `context/message` with `content` rendered verbatim as a user-role message. `options.meta` persists opaque JSON state without rendering it. While a turn is open it joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)).
-- `agent.cancel(cause?)` — cancel ALL pending work: an omitted cause means `{ kind: 'user' }`; TypeScript restricts callers to the `user | parent` union, and an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; observers may synchronize state but cannot veto cancellation. The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`.
+- `agent.followup(content, options?)` — queue one independent FIFO message as its own turn and wake the driver. After admission, separate contexts become injected `user/message` events, while prompt-prefix contexts are baked before the effective request in the same `user/message`; a block or replacement of the default additional-context decision can discard them. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
+- `agent.queue(content, options?)` — queue the same ordinary message without waking an idle driver. A lone queued item leaves `whenIdle()` resolved and rides along before the next waking message.
+- `agent.steer(content, options?)` — while running, queue steering for the next checkpoint without dispatching `agent/prompt-submit`; while idle, create a waking ordinary turn. Attached contexts remain in the same frozen record; separate contexts append immediately after the steering event, while prompt-prefix contexts are baked into that event. Both survive late-steering conversion to queued input and disappear with their message on cancellation or terminal discard. Policy can still stop before another step; after turn close and its checkpoint, remaining steering becomes later queued input unless terminal turn policy, cancellation, or disposal discards it.
+- `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `user/message` (default plugin source) with `content` rendered verbatim as a user-role message. `InjectOptions` deliberately has no attached contexts. `options.meta` persists opaque JSON state without rendering it. While a turn is open the injection joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)). Injection bypasses the FIFOs and emits no `agent/inbox/*` event.
+- `agent.send(input)` — accept a fully specified route without helper defaults. `next-turn` targets the ordinary FIFO; `next-step` with wakeup targets steering and falls back to a waking ordinary turn while idle; `next-step` without wakeup is injection and requires `contexts: []`. Callers provide `meta: undefined` explicitly when they have no metadata.
+- `agent.cancel(cause?, options?)` — cancel the active turn and, unless `options.keepInbox`, ALL pending work: an omitted cause means `{ kind: 'user' }`; TypeScript restricts callers to the `user | parent` union, and an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; dropped items are reported on `agent/inbox/discard`, and observers may synchronize state but cannot veto cancellation. `keepInbox: true` aborts the turn but preserves queued and steering items (no discard, and un-started work is not dropped). The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`.
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`
 
@@ -77,7 +79,7 @@ The handle every plugin programs against:
 
 #### What the model sees
 
-`send`, `steer`, and `inject` feed the owning session. `agent/prompt-submit`, `agent/session-prefix`, and other declared events let plugins block a prompt or add request material; this interface contributes no fixed prose itself.
+The four intent helpers and fully resolved `send` path feed the owning session. `agent/prompt-submit`, `agent/session-prefix`, and other declared events let plugins block a prompt or add request material; this interface contributes no fixed prose itself.
 
 #### Token effect
 
@@ -107,6 +109,6 @@ Prefix-stable while an agent's scoped registrations are unchanged. Setup or relo
 - **Ambient identity may outlive liveness** — consumers still check `agent.status`, cancellation, and the owning capability contract before lifecycle-sensitive work.
 - **Inter-agent channels beyond delegation** — shared state, streaming child output, and background/poll semantics remain outside the current synchronous `ctx.subagents` seam.
 - **`agent/session-start` cannot gate startup** — it remains a synchronous, veto-less notification; async composition that must finish before publication belongs in the factory's `setup(agentCtx)` transaction instead.
-- **No public step-only abort** — `cancel()` clears ALL pending work (queued + steering + in-flight); an abort that preserves queued prompts returns only with a named consumer ([stop-surface Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
+- **`cancel()` clears the inbox by default** — it aborts the in-flight turn plus queued and steering work; `cancel(cause, { keepInbox: true })` aborts only the turn and preserves pending items. There is still no step-only abort that keeps the in-flight turn running ([stop-surface Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
 - **`HookContext` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source; mixed provenance is unrepresentable.
 - **`SessionStartSource` reserves `'clear'`/`'compact'` with no emitter yet** — only `'startup'`/`'resume'` occur until the driving subsystems land (`TODO(compaction)`).

packages/core/agent/src/invariant.ts

@@ -24,6 +24,27 @@ const install: InvariantInstaller = (ctx, fail) => {
     }
     lastStatus.set(agent, status)
   }, { global: true })
+
+  // Inbox FIFO conservation: an item leaves the inbox (dequeue) or is dropped
+  // (discard) only after it entered (enqueue), so the live outstanding count
+  // per agent can never go negative. Injection bypasses the FIFOs entirely and
+  // never appears on these events.
+  const outstanding = new WeakMap<Agent, number>()
+  ctx.on('agent/inbox/enqueue', (agent) => {
+    outstanding.set(agent, (outstanding.get(agent) ?? 0) + 1)
+  }, { global: true })
+  ctx.on('agent/inbox/dequeue', (agent) => {
+    const count = outstanding.get(agent) ?? 0
+    if (count <= 0) fail('agent/inbox/dequeue without a matching prior enqueue')
+    outstanding.set(agent, count - 1)
+  }, { global: true })
+  ctx.on('agent/inbox/discard', (agent, items) => {
+    const count = outstanding.get(agent) ?? 0
+    if (items.length > count) {
+      fail(`agent/inbox/discard dropped ${items.length} items but only ${count} were outstanding`)
+    }
+    outstanding.set(agent, count - items.length)
+  }, { global: true })
 }
 
 /**