Merge remote-tracking branch 'origin/master' into worktree/acp-automation-protocol

# Conflicts: # .agents/notes/implemented/architecture/2026-06-14-session-persistence.md # .agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md # .agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md # .agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md # .agents/notes/implemented/feature/2026-06-14-acp-multi-session.md # .agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md # .agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md # docs/architecture.i18n.yaml # docs/cookbook/extension-cookbook.i18n.yaml # docs/cookbook/extension-cookbook.md # docs/cookbook/extension-cookbook.zh.md # docs/core-data-structures/approval.md # docs/core-data-structures/user-interaction.md # docs/event-producer-consumer.md # docs/persistence-catalog.md # docs/testing.md # docs/tool-catalog.md # examples/acp-agent/tests/fixtures/live-mode-switching-2026-07-07.session.jsonl # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl # examples/acp-agent/tests/snapshots/permission-switching/session.jsonl # packages/goal/tool-goal/README.md # packages/ui/acp/README.md # packages/ui/acp/acp-feature-support.md # packages/ui/acp/src/index.ts # packages/ui/acp/tests/bridge.spec.ts # packages/ui/acp/tests/dispose.spec.ts # packages/ui/acp/tests/edges.spec.ts # packages/ui/acp/tests/turns.spec.ts
2026-07-24 23:43:10 +08:00
parent d01474d1d0 b97b1b4a3f
commit 440384fdb4
829 changed files with 23607 additions and 1815 deletions
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -6,11 +6,12 @@ Shared boot glue for the app bins ([`dsh-tui-demo`](../../examples/tui-demo/READ
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | Absolute config path; `snapshotMode === 'replay'` swaps a `cordis.yml`/`.yaml` basename for its sibling `cordis.snapshot.yml` |
 | `parseResumeArg(argv)` | Split the `--resume <id>` / `--resume=<id>` flag out of the arguments, returning `{ resumeSessionId, rest }`; a valueless, empty, or repeated flag throws so a mistyped resume fails loud instead of silently starting fresh |
+| `replaceResumeArg(argv, sessionId)` | Remove an existing resume flag and append one canonical `--resume <sessionId>` pair while preserving positional arguments |
 | `loadEnv(binName, dir?, warn?)` | Load the gitignored `.env` (Node `process.loadEnvFile`); absent file is fine, an unloadable one warns a single labelled line (default: stderr) |
 | `installFailLoud(binName, proc?)` | Turn a post-`boot()` unhandled Loader rejection into one labelled stderr line + `exit(1)`; returns the uninstaller (for tests) |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber (a plugin module that failed to import) |
 | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
-| `boot(binName, absoluteConfigPath, patches?)` | Mount the Loader, mount the statically imported include plugin as the `cordis:include` builtin (so the config may live outside `node_modules` reach), include the config by absolute `file://` URL with the optional overlay patches, await the whole tree, assert entries loaded, return the root context |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, run optional host preparation before plugins mount, then mount the Loader/include tree, await it, assert entries loaded, and return the root context |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to its own source checkout; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |

--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -80,6 +80,18 @@ export function parseResumeArg(
  return { resumeSessionId, rest }
 }

+/**
+ * Replace any existing resume flag with one canonical trailing `--resume <id>` pair.
+ * @param argv - current arguments after command dispatch.
+ * @param sessionId - selected session id.
+ * @returns flag-normalized arguments for a process replacement.
+ */
+export function replaceResumeArg(argv: readonly string[], sessionId: string): string[] {
+  if (sessionId.length === 0) throw new Error(`${RESUME_FLAG} requires a non-empty session id`)
+  const { rest } = parseResumeArg(argv)
+  return [...rest, RESUME_FLAG, sessionId]
+}
+
 /**
 * Load the optional gitignored `.env` from `dir`. Missing files fall back to the
 * ambient environment; other read failures are reported through `warn`.
@@ -216,12 +228,17 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
 * (see {@link resolveConfigPath}).
 * @param patches - optional overlay patches applied over the included tree
 * (see {@link loadPersonalPatches}); an empty list mounts none.
+ * @param prepare - optional host setup run against the root context before any Loader entry mounts.
 * @returns the root context once every entry has started.
 */
 export async function boot(
-  binName: string, absoluteConfigPath: string, patches?: PatchOptions[],
+  binName: string,
+  absoluteConfigPath: string,
+  patches?: PatchOptions[],
+  prepare?: (ctx: Context) => Promise<void> | void,
 ): Promise<Context> {
  const ctx = new Context()
+  await prepare?.(ctx)
  ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
  await ctx.plugin(Loader)
  ctx.loader.builtins.include = Include
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import {
  addHarnessSourceSection, assertEntriesLoaded, boot, HARNESS_SOURCE_SECTION,
-  installFailLoud, loadEnv, parseResumeArg, resolveConfigPath, type FailLoudProcess,
+  installFailLoud, loadEnv, parseResumeArg, replaceResumeArg, resolveConfigPath, type FailLoudProcess,
 } from '../src/index.ts'

 const NAME = 'dsh-test-bin'
@@ -55,6 +55,15 @@ describe('parseResumeArg', () => {
  })
 })

+describe('replaceResumeArg', () => {
+  it('keeps positional arguments and replaces either existing flag form', () => {
+    expect(replaceResumeArg(['app.yml'], 'next')).toEqual(['app.yml', '--resume', 'next'])
+    expect(replaceResumeArg(['--resume', 'old', 'app.yml'], 'next')).toEqual(['app.yml', '--resume', 'next'])
+    expect(replaceResumeArg(['app.yml', '--resume=old'], 'next')).toEqual(['app.yml', '--resume', 'next'])
+    expect(() => replaceResumeArg([], '')).toThrow('non-empty session id')
+  })
+})
+
 describe('loadEnv', () => {
  it('loads variables from .env in the given dir', () => {
    const dir = tmp()
@@ -196,6 +205,19 @@ describe('boot', () => {
    }
  })

+  it('runs host preparation before the Loader tree mounts', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
+    const prepared: Context[] = []
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'), undefined, (hostCtx) => { prepared.push(hostCtx) })
+    try {
+      expect(prepared).toEqual([ctx])
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
  it('rejects (never exits 0 half-empty) when a config names a plugin that cannot be imported', async () => {
    const dir = tmp()
    writeFileSync(join(dir, 'cordis.yml'), '- id: ghost\n  name: ./missing.mjs\n')
--- a/packages/ui/jsonrpc/src/server.ts
+++ b/packages/ui/jsonrpc/src/server.ts
@@ -152,7 +152,7 @@ export class HarnessSdkServer {
    rec.activePrompt = true
    try {
      rec.lastTurnEnd = undefined
-      rec.handle.agent.send(params.contentBlocks)
+      rec.handle.agent.followup(params.contentBlocks)
      await rec.handle.agent.whenIdle()
      const status = this.finishedStatus(rec.lastTurnEnd)
      this.transport.notify('session.finished', {
--- a/packages/ui/jsonrpc/tests/server.spec.ts
+++ b/packages/ui/jsonrpc/tests/server.spec.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'
+import { AgentMessageId, type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'

 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
@@ -152,7 +152,7 @@ describe('HarnessSdkServer', () => {
        meta: { cwd: storageDir },
        agentOptions: { provider: 'deepseek', model: 'dsagent-model' },
      })
-      orphanHandle.agent.send([{ type: 'text', text: 'outside the sdk session map' }])
+      orphanHandle.agent.followup([{ type: 'text', text: 'outside the sdk session map' }])
      await orphanHandle.agent.whenIdle()
      await orphanHandle.dispose()
      expect(llmServer.requests).toHaveLength(3)
@@ -170,16 +170,16 @@ describe('HarnessSdkServer', () => {
    const mainWhenIdle = vi.fn<() => Promise<void>>()
      .mockReturnValueOnce(firstMainIdle)
      .mockResolvedValue(undefined)
-    const mainSend = vi.fn()
-    const mainAgent = {
-      send: mainSend,
+    const mainFollowup = vi.fn<Agent['followup']>().mockReturnValue(AgentMessageId('main-followup'))
+    const mainAgent = ({
+      followup: mainFollowup,
      whenIdle: mainWhenIdle,
-    } as unknown as Agent
-    const otherSend = vi.fn()
-    const otherAgent = {
-      send: otherSend,
+    } satisfies Pick<Agent, 'followup' | 'whenIdle'>) as unknown as Agent
+    const otherFollowup = vi.fn<Agent['followup']>().mockReturnValue(AgentMessageId('other-followup'))
+    const otherAgent = ({
+      followup: otherFollowup,
      whenIdle: vi.fn(() => Promise.resolve()),
-    } as unknown as Agent
+    } satisfies Pick<Agent, 'followup' | 'whenIdle'>) as unknown as Agent
    const mainHandle = { agent: mainAgent, dispose: vi.fn(() => Promise.resolve()) }
    const otherHandle = { agent: otherAgent, dispose: vi.fn(() => Promise.resolve()) }
    const create = vi.fn(async (options: { sessionId: SessionId }) =>
@@ -196,7 +196,7 @@ describe('HarnessSdkServer', () => {
    })

    const first = prompt('main', 'first')
-    await vi.waitFor(() => { expect(mainSend).toHaveBeenCalledOnce() })
+    await vi.waitFor(() => { expect(mainFollowup).toHaveBeenCalledOnce() })

    await expect(prompt('main', 'overlap')).rejects.toThrow('session already has an active prompt: main')
    await expect(prompt('other', 'independent')).resolves.toEqual({ accepted: true })
@@ -208,8 +208,8 @@ describe('HarnessSdkServer', () => {
    await expect(prompt('main', 'failing')).rejects.toThrow('turn wait failed')
    await expect(prompt('main', 'after failure')).resolves.toEqual({ accepted: true })

-    expect(mainSend).toHaveBeenCalledTimes(4)
-    expect(otherSend).toHaveBeenCalledOnce()
+    expect(mainFollowup).toHaveBeenCalledTimes(4)
+    expect(otherFollowup).toHaveBeenCalledOnce()
    await server.shutdown()
    expect(mainHandle.dispose).toHaveBeenCalledOnce()
    expect(otherHandle.dispose).toHaveBeenCalledOnce()
@@ -225,9 +225,9 @@ describe('HarnessSdkServer', () => {
      shutdown(): Promise<Record<string, never>>
    }
    const session = ctx.sessions.create(SessionId('message-outcome'))
-    const agent = {
+    const agent = ({
      session,
-      send(content: { type: 'text'; text: string }[]) {
+      followup(content: { type: 'text'; text: string }[]) {
        session.append('turn/start', {
          turn: 1,
          trigger: { kind: 'message', source: { kind: 'user' } },
@@ -241,14 +241,15 @@ describe('HarnessSdkServer', () => {
          turn: 2,
          trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'late-metadata' } },
        })
-        session.append('context/message', {
+        session.append('user/message', {
          content: [{ type: 'text', text: 'late metadata' }],
          source: { kind: 'plugin', plugin: 'late-metadata' },
        }, { surfaceOp: 'append' })
        session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+        return AgentMessageId('message-outcome')
      },
      whenIdle: () => Promise.resolve(),
-    } as unknown as Agent
+    } satisfies Pick<Agent, 'session' | 'followup' | 'whenIdle'>) as unknown as Agent
    server.sessions.set('message-outcome', {
      handle: { agent, dispose: () => Promise.resolve() },
      lastTurnEnd: undefined,
--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -18,9 +18,9 @@ Before model output, session events, tool presenters, questions, configuration,

 Typing `@` at a token boundary searches files and directories under the session working directory. A bare fuzzy query uses a reusable bounded workspace index; a query containing `/` lists that directory directly, and selecting a folder keeps completion open for descent. Whitespace-bearing paths are inserted as `@"path with spaces"`. Selecting a file inserts only its path and a trailing space: the TUI does not read it, attach hidden context, or replace it with a reference object. When a model-facing `read` tool is registered, the TUI adds one fixed system-prompt instruction telling the model to read an explicit path when its contents are needed.

-When optional `ctx.sessionReferences` is mounted, the same `@` menu also offers metadata-only session candidates, inserts `@[label](dsh-session:<payload>)`, and prepares the selected snapshots before dispatch. Session references remain structured because the model has no filesystem-like tool for retrieving session snapshots later. Preparation disables duplicate submission and restores the editor input on failure. The TUI chooses `agent.steer()` or `agent.send()` from the status after that asynchronous preparation, so idle sends still dispatch `agent/prompt-submit` while in-turn steering joins at a checkpoint without that hook.
+When optional `ctx.sessionReferences` is mounted, the same `@` menu also offers metadata-only session candidates, inserts `@[label](dsh-session:<payload>)`, and prepares the selected snapshots before dispatch. Session references remain structured because the model has no filesystem-like tool for retrieving session snapshots later. Preparation disables duplicate submission and restores the editor input on failure. The TUI chooses `agent.steer()` or `agent.followup()` from the status after that asynchronous preparation, so idle follow-ups still dispatch `agent/prompt-submit` while in-turn steering joins at a checkpoint without that hook.

-While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.send()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path automatically reaches the model. A command producer may explicitly schedule agent work; [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) uses that contract for `/plan [message]`. The TUI registers `/help`, `/model`, `/clear`, `/reasoning`, `/tools`, `/redraw`, `/reload`, `/resume`, `/status`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically, as do `/skill:` completions. A status line above the editor reports the turn phase the TUI derives from session events — waiting for the first token, thinking, responding, or executing tools — with the elapsed time in that phase and the running step total, refreshed each second, and ends with the `Enter sends steering, Esc cancels` hint; while steering messages wait to reach the model it inserts a `N queued ·` badge before the hint that clears as each drains. Ctrl+C or Escape cancels a running turn. Tool cards collapse long bodies into a configurable head/tail preview; Ctrl+O toggles every card between its preview and full output. Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.
+While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.followup()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path automatically reaches the model. A command producer may explicitly schedule agent work; [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) uses that contract for `/plan [message]`. The TUI registers `/help`, `/model`, `/clear`, `/reasoning`, `/tools`, `/redraw`, `/reload`, `/resume`, `/status`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically, as do `/skill:` completions. A status line above the editor reports the turn phase the TUI derives from session events — waiting for the first token, thinking, responding, or executing tools — with the elapsed time in that phase and the running step total, refreshed each second, and ends with the `Enter sends steering, Esc cancels` hint; while steering messages wait to reach the model it inserts a `N queued ·` badge before the hint that clears as each drains. Ctrl+C or Escape cancels a running turn. Tool cards collapse long bodies into a configurable head/tail preview; Ctrl+O toggles every card between its preview and full output. Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.

 `/model` opens the advisory `ctx.llm` catalog as a keyboard selector: Up/Down moves, Enter selects, and Escape closes it. `/model <model>` still selects an unambiguous model id directly, while `/model <provider>/<model>` selects an exact target. The configured target or latest logged request header initializes the selector, and an unlisted current model remains visible because catalogs are advisory. Selection is local to this TUI session. Prompt assembly snapshots the target for one step, replaces `{{provider}}` and `{{model}}`, and applies the same pair through `agent/request`; a switch during assembly therefore starts with a later step. The request header durably records targets that reach the model, while an unused selection remains process-local.

@@ -30,7 +30,9 @@ The footer sums the session's reported usage as `↑<uncached input> ↓<output>

 `/status` adds a point-in-time diagnostics card to the transcript and remains available while the agent runs. It reports the session id, title, working directory, selected provider/model, reasoning-block visibility, agent state, event/turn/step/tool-call counts, exact input/output/cache token buckets, KV-cache hit rate, token-meter context use and capacity, creation time, and latest event time. Missing titles, models, cache input, or context capacity are labeled instead of inferred. The card is terminal-only and does not duplicate the compact footer.

-When `resumeCommand` is set and a `sessionPersistence` backend is mounted, exiting prints the resume command for the current session (once it has been persisted, so an abandoned session yields no hint), and `/resume` lists this workspace's persisted sessions newest-first, each with its resume command and a marker on the current one. `{session}` in the template expands to the session id; the TUI only prints commands to copy and never resumes in place.
+`/resume` opens a full-viewport keyboard selector over the current workspace instead of a centered dialog. Its focused search field starts immediately after the search glyph and emits pi-tui's cursor marker, so terminal IME composition remains anchored inside the field. Candidates are sorted by last logged activity and searchable by log-backed title or session id; each row reports current/live/persisted state, last turn outcome, recent provider/model, and durable goal phase when present. Up/Down and Page Up/Page Down navigate, Enter resumes, Escape clears a non-empty search before a second Escape cancels, and Ctrl+C cancels directly. The current session, a session already live in this runtime, an unreadable log, a mismatched cwd, or a session whose logged provider has no current adapter remains visible but disabled. Selection repeats those checks and requires the current agent to be idle before flushing the current session. The TUI then stops the terminal UI and calls the optional host-owned `TuiRuntime.handoffResume`; where `process.execve` is available, the shipped `dsh` host disposes the app and replaces its process. Resume restores the same `SessionId`, transcript, title, todos, and durable goal; goal activation remains disarmed and the TUI asks for human confirmation or `/goal resume`.
+
+`resumeCommand` remains the deployment-owned fallback: exiting prints it only after the current session is durable, and a host without in-place handoff shows the selected session's command. `{session}` expands to the session id. TUI code never executes the template or arbitrary shell text.

 ## Config

@@ -42,6 +44,7 @@ When `resumeCommand` is set and a `sessionPersistence` backend is mounted, exiti
 | `maxToolOutputLines` | `6` | Output lines retained across a collapsed tool card's head/tail preview |
 | `maxQuestionOptions` | `8` | Visible options in a question panel |
 | `maxModelOptions` | `8` | Visible models in the model selector |
+| `maxResumeOptions` | `8` | Visible sessions in the resume selector |
 | `questionDialogWidth` | `200` | Question-panel width in columns, clamped to the terminal |
 | `questionDialogMaxHeight` | `20` | Question-panel maximum rows |
 | `modelDialogWidth` | `72` | Model-selector width in columns |
@@ -52,7 +55,7 @@ When `resumeCommand` is set and a `sessionPersistence` backend is mounted, exiti
 | `showHardwareCursor` | `false` | Show the hardware cursor at pi-tui's IME marker |
 | `color` | `true` | Apply the built-in ANSI palette (see [Color](#color)) |
 | `title` | `DeepSeek Harness` | Product suffix for the terminal window title. |
-| `resumeCommand` | — | Shell command template for the exit hint and `/resume`, with `{session}` expanded to the session id; unset disables both. Needs a `sessionPersistence` backend |
+| `resumeCommand` | — | Shell command template for the exit hint and hosts without in-place handoff, with `{session}` expanded to the session id |

 ```yaml
 - id: terminal
@@ -77,7 +80,7 @@ The palette uses the standard 16-color ANSI foregrounds and SGR attributes, whic

 #### What the model sees

-Each non-empty ordinary editor submission becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running. A session mention becomes readable `@label` text plus the durable untrusted context defined by [`dsh-session-reference`](../../context/session-reference/README.md); its full JSON is hidden behind a compact reference card. Slash commands and keybindings are TUI-only; command results remain terminal notices. A command producer may schedule a separate agent input, such as the optional message accepted by `/plan [message]`.
+Each non-empty ordinary editor submission becomes one text block, sent with `agent.followup()` while the target agent is idle and `agent.steer()` while it is running. A session mention becomes readable `@label` text plus the durable untrusted context defined by [`dsh-session-reference`](../../context/session-reference/README.md); its full JSON is hidden behind a compact reference card. Slash commands and keybindings are TUI-only; command results remain terminal notices. A command producer may schedule a separate agent input, such as the optional message accepted by `/plan [message]`.

 #### Token effect

@@ -125,7 +128,7 @@ Changing provider or model enters that target's cache domain; no cache reuse acr

 #### What the model sees

-A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same send-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill; model-disabled skills are omitted from autocomplete but stay loadable by exact name.
+A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same followup-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill; model-disabled skills are omitted from autocomplete but stay loadable by exact name.

 #### Token effect

@@ -151,6 +154,7 @@ Append-only; newly visible content follows the reusable request prefix and does

 ## Known Limitations and Deferred Work

+- **Resume has no cross-process session lock** — the selector rejects sessions known to be live in its own runtime, but another process can resume the same persisted id before or during handoff. Deployments that can run concurrent hosts must coordinate ownership outside the TUI.
 - **One configured session owns the transcript and editor** — questions from other agents can still use the shared overlay provider, but session rendering and prompt input remain bound to `sessionId`.
 - **Tool cards are text terminal presentations** — terminal, diff, and generic cards use tool-owned titles/content, but session content currently has no image block for inline image rendering.
 - **Non-TTY operation is intentionally unsupported** — app bundles that need automation must compose a one-shot or server front door (`dsh-cli-demo`, `dsh-acp`) rather than expecting an internal fallback.
--- a/packages/ui/tui/package.json
+++ b/packages/ui/tui/package.json
@@ -33,9 +33,11 @@
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-llm-retry": "^0.0.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-session-reference": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1",
    "@deepseek-ai/dsh-session-title": "^0.0.1",
    "@deepseek-ai/dsh-skill": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -48,6 +50,9 @@
    "@deepseek-ai/dsh-session-persistence": {
      "optional": true
    },
+    "@deepseek-ai/dsh-session-query": {
+      "optional": true
+    },
    "@deepseek-ai/dsh-skill": {
      "optional": true
    }
@@ -60,6 +65,7 @@
    "@cordisjs/plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
    "@deepseek-ai/dsh-commands": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -66,13 +66,18 @@ import {
  type SessionHeader,
  type TodoItem,
 } from '@deepseek-ai/dsh-session'
+import { foldGoal, type GoalPhase } from '@deepseek-ai/dsh-goal'
 import {
  formatSessionReferenceMention,
  parseSessionReferenceText,
  type SessionReferenceService,
 } from '@deepseek-ai/dsh-session-reference'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
-// Side-effect type import: declaration-merges the optional `sessionPersistence`
+import type {
+  SessionLogSnapshot,
+  SessionRecord,
+} from '@deepseek-ai/dsh-session-query'
+// Type import also declaration-merges the optional `sessionPersistence`
 // service onto `Context` so `ctx.get('sessionPersistence')` is typed.
 import type {} from '@deepseek-ai/dsh-session-persistence'
 import type { SkillDefinition, SkillResourceBase, SkillService } from '@deepseek-ai/dsh-skill'
@@ -120,9 +125,22 @@ declare module 'cordis' {
  interface Context {
    /** Terminal-only interaction service, available only while a TUI is mounted. */
    tui: TuiExtensionService
+    /** Optional process host that can replace this TUI with a resumed session. */
+    tuiResumeHost: TuiResumeHost
  }
 }

+/** Process-lifecycle owner used by the shipped CLI for an atomic resume handoff. */
+export interface TuiResumeHost {
+  /**
+   * Dispose the current app and replace it with a runtime for `sessionId`.
+   * Success does not return. A host may reject before it commits teardown;
+   * after commit it owns fatal reporting and process exit.
+   * @param sessionId - validated persisted session selected by the user.
+   */
+  handoff(sessionId: SessionId): Promise<never>
+}
+
 /**
 * Optional terminal-local interaction service provided by one mounted TUI.
 *
@@ -162,7 +180,7 @@ export {
 } from './file-autocomplete.ts'

 export const name = 'ui-tui'
-export const inject = ['agents', 'commands', 'userInteraction', 'tools', 'llm', 'systemPrompt', 'tokenMeter']
+export const inject = ['agents', 'sessions', 'commands', 'userInteraction', 'tools', 'llm', 'systemPrompt', 'tokenMeter']

 /** Model guidance for path-only file references selected through the TUI. */
 export const FILE_REFERENCE_PROMPT = 'Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.'
@@ -177,6 +195,8 @@ export interface TuiConfig {
  maxQuestionOptions?: number
  /** Maximum models visible at once in the model selector. */
  maxModelOptions?: number
+  /** Maximum sessions visible at once in the resume selector. */
+  maxResumeOptions?: number
  /** User-question panel width in terminal columns, clamped to the terminal. */
  questionDialogWidth?: number
  /** User-question panel maximum height in terminal rows. */
@@ -210,6 +230,7 @@ const showReasoningSchema = z.boolean().default(true)
 const maxToolOutputLinesSchema = z.number().step(1).min(1).default(6)
 const maxQuestionOptionsSchema = z.number().step(1).min(1).default(8)
 const maxModelOptionsSchema = z.number().step(1).min(1).default(8)
+const maxResumeOptionsSchema = z.number().step(1).min(1).default(8)
 const questionDialogWidthSchema = z.number().step(1).min(20).default(200)
 const questionDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
 const modelDialogWidthSchema = z.number().step(1).min(20).default(72)
@@ -228,6 +249,7 @@ const tuiConfigSchemaFields = {
  maxToolOutputLines: maxToolOutputLinesSchema,
  maxQuestionOptions: maxQuestionOptionsSchema,
  maxModelOptions: maxModelOptionsSchema,
+  maxResumeOptions: maxResumeOptionsSchema,
  questionDialogWidth: questionDialogWidthSchema,
  questionDialogMaxHeight: questionDialogMaxHeightSchema,
  modelDialogWidth: modelDialogWidthSchema,
@@ -251,11 +273,10 @@ export interface Config extends TuiConfig {
  /** Exact shared agent/session identity driven by this terminal. Defaults to `main`. */
  sessionId?: string
  /**
-   * Shell command template shown for resuming this session: printed on exit and
-   * listed by `/resume`, with every `{session}` occurrence replaced by the live
-   * session id. Absent disables both surfaces. Deployments set it only when a
-   * persistence backend makes the session resumable (e.g.
-   * `RESUME_SESSION_ID={session} dsh`).
+   * Shell command fallback printed on exit or after selecting a session when
+   * the host cannot hand off in place. Every `{session}` becomes the selected
+   * id; the TUI never executes this text. Absent disables only the fallback,
+   * not the interactive selector.
   */
  resumeCommand?: string
 }
@@ -268,6 +289,7 @@ export const Config: z<Config> = z.object({
  maxToolOutputLines: tuiConfigSchemaFields.maxToolOutputLines,
  maxQuestionOptions: tuiConfigSchemaFields.maxQuestionOptions,
  maxModelOptions: tuiConfigSchemaFields.maxModelOptions,
+  maxResumeOptions: tuiConfigSchemaFields.maxResumeOptions,
  questionDialogWidth: tuiConfigSchemaFields.questionDialogWidth,
  questionDialogMaxHeight: tuiConfigSchemaFields.questionDialogMaxHeight,
  modelDialogWidth: tuiConfigSchemaFields.modelDialogWidth,
@@ -287,6 +309,7 @@ export interface ResolvedTuiConfig {
  maxToolOutputLines: number
  maxQuestionOptions: number
  maxModelOptions: number
+  maxResumeOptions: number
  questionDialogWidth: number
  questionDialogMaxHeight: number
  modelDialogWidth: number
@@ -314,6 +337,8 @@ export interface TuiRuntime {
  formatCwd?: (cwd: string | undefined) => string
  /** Monotonic-enough wall clock for elapsed status rendering. Defaults to `Date.now`. */
  now?(): number
+  /** Host-owned process handoff; absent leaves `resumeCommand` as the fallback. */
+  handoffResume?: TuiResumeHost['handoff']
 }

 /**
@@ -328,6 +353,7 @@ export function resolveTuiConfig(config: TuiConfig | undefined): ResolvedTuiConf
    maxToolOutputLines: config?.maxToolOutputLines ?? 6,
    maxQuestionOptions: config?.maxQuestionOptions ?? 8,
    maxModelOptions: config?.maxModelOptions ?? 8,
+    maxResumeOptions: config?.maxResumeOptions ?? 8,
    questionDialogWidth: config?.questionDialogWidth ?? 200,
    questionDialogMaxHeight: config?.questionDialogMaxHeight ?? 20,
    modelDialogWidth: config?.modelDialogWidth ?? 72,
@@ -367,6 +393,11 @@ function ansi(open: string, close: string, enabled: boolean): (text: string) =>
 }

 const TERMINAL_CONTROL_PATTERN = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/gu
+const TERMINAL_OSC_PATTERN = /(?:\u001B\]|\u009D)(?:(?!\u0007|\u001B\\)[\s\S])*(?:\u0007|\u001B\\|$)/gu
+const TERMINAL_CSI_PATTERN = /(?:\u001B\[|\u009B)[0-?]*[ -/]*[@-~]/gu
+const TERMINAL_ESCAPE_PATTERN = /\u001B[@-_]/gu
+const BRACKETED_PASTE_START = '\u001B[200~'
+const BRACKETED_PASTE_END = '\u001B[201~'

 /**
 * Escape external C0/C1 controls before pi-tui adds application-owned ANSI.
@@ -382,6 +413,15 @@ function displayInlineText(text: string): string {
  return displayText(text).replaceAll('\n', '\\x0a')
 }

+/** Remove terminal controls from clipboard text before an editable field stores it. */
+function sanitizePastedText(text: string): string {
+  return text
+    .replace(TERMINAL_OSC_PATTERN, '')
+    .replace(TERMINAL_CSI_PATTERN, '')
+    .replace(TERMINAL_ESCAPE_PATTERN, '')
+    .replace(TERMINAL_CONTROL_PATTERN, '')
+}
+
 /**
 * Theme-agnostic palette built from the standard 16-color ANSI set plus SGR
 * attributes, which every terminal remaps to its active color scheme. Body
@@ -1236,6 +1276,248 @@ class ModelDialog implements Component {
  }
 }

+interface ResumeRoute {
+  provider: string
+  model: string
+}
+
+interface ResumeCandidate {
+  record: SessionRecord
+  title: string
+  lastActivityAt: number
+  lastTurn: string
+  route?: ResumeRoute
+  goalPhase?: GoalPhase
+  disabledReason?: string
+}
+
+function resumeTurnLabel(snapshot: SessionLogSnapshot): string {
+  const event = snapshot.events.findLast(item => item.type === 'turn/end')
+  if (event === undefined) return 'no completed turn'
+  const reason = event.data.reason
+  switch (reason.kind) {
+    case 'completed': return `turn ${event.data.turn}: completed`
+    case 'aborted': return `turn ${event.data.turn}: cancelled`
+    case 'error': return `turn ${event.data.turn}: error`
+    case 'disposed': return `turn ${event.data.turn}: disposed`
+    case 'max-tokens': return `turn ${event.data.turn}: max tokens`
+    case 'rejected': return `turn ${event.data.turn}: rejected`
+    case 'interrupted': return `turn ${event.data.turn}: interrupted`
+    default: return `turn ${event.data.turn}: unknown result`
+  }
+}
+
+function resumeRoute(snapshot: SessionLogSnapshot): ResumeRoute | undefined {
+  const header = snapshot.events.findLast(item => item.type === 'request/header')
+  if (header?.type === 'request/header') {
+    return { provider: header.data.header.config.provider, model: header.data.header.config.model }
+  }
+  const assistant = snapshot.events.findLast(item => item.type === 'assistant/message')
+  return assistant?.type === 'assistant/message'
+    ? { provider: assistant.data.provenance.provider, model: assistant.data.provenance.model }
+    : undefined
+}
+
+function summarizeResumeCandidate(
+  record: SessionRecord,
+  snapshot: SessionLogSnapshot,
+  currentId: SessionId,
+  cwd: string | undefined,
+  availableProviders: ReadonlySet<string>,
+): ResumeCandidate {
+  const title = foldSessionTitle(snapshot.events)?.title ?? 'Untitled session'
+  const route = resumeRoute(snapshot)
+  const foldedGoal = foldGoal(snapshot.events).goal
+  let disabledReason: string | undefined
+  if (record.header.id === currentId) disabledReason = 'current session'
+  else if (record.live) disabledReason = 'session is already live in this runtime'
+  else if (record.header.cwd !== cwd) disabledReason = 'different workspace'
+  else if (route !== undefined && !availableProviders.has(route.provider)) {
+    disabledReason = `session is complete, but route is currently unavailable (${route.provider}/${route.model})`
+  }
+  return {
+    record,
+    title,
+    lastActivityAt: snapshot.events.at(-1)?.time ?? snapshot.session.createdAt,
+    lastTurn: resumeTurnLabel(snapshot),
+    ...route === undefined ? {} : { route },
+    ...foldedGoal === undefined ? {} : { goalPhase: foldedGoal.phase },
+    ...disabledReason === undefined ? {} : { disabledReason },
+  }
+}
+
+/** Full-viewport keyboard selector over detached, preflighted resume summaries. */
+class ResumePicker implements Component, Focusable {
+  private readonly search = new Input()
+  private pasteBuffer: string | undefined
+  private selectedIndex = 0
+  private error = ''
+  focused = false
+
+  constructor(
+    private readonly candidates: readonly ResumeCandidate[],
+    private readonly maxVisible: number,
+    private readonly workspaceLabel: string,
+    private readonly viewportRows: () => number,
+    private readonly palette: Palette,
+    private readonly done: (candidate: ResumeCandidate) => void,
+    private readonly cancel: () => void,
+  ) {}
+
+  invalidate(): void {
+    this.search.invalidate()
+  }
+
+  private filtered(): ResumeCandidate[] {
+    const query = this.search.getValue().trim().toLocaleLowerCase()
+    if (query === '') return [...this.candidates]
+    return this.candidates.filter(candidate => candidate.title.toLocaleLowerCase().includes(query)
+      || candidate.record.header.id.toLocaleLowerCase().includes(query))
+  }
+
+  private visibleCandidateCount(): number {
+    const candidateBudget = Math.max(1, Math.floor((Math.max(1, this.viewportRows()) - 13) / 4))
+    return Math.min(this.maxVisible, candidateBudget)
+  }
+
+  private handleBracketedPaste(data: string): boolean {
+    const start = data.indexOf(BRACKETED_PASTE_START)
+    if (this.pasteBuffer === undefined && start < 0) return false
+    if (this.pasteBuffer === undefined) {
+      const prefix = data.slice(0, start)
+      if (prefix !== '') this.handleInput(prefix)
+      this.pasteBuffer = data.slice(start + BRACKETED_PASTE_START.length)
+    } else {
+      this.pasteBuffer += data
+    }
+    const end = this.pasteBuffer.indexOf(BRACKETED_PASTE_END)
+    if (end < 0) return true
+    const pasted = sanitizePastedText(this.pasteBuffer.slice(0, end))
+    const remaining = this.pasteBuffer.slice(end + BRACKETED_PASTE_END.length)
+    this.pasteBuffer = undefined
+    const previous = this.search.getValue()
+    this.search.handleInput(`${BRACKETED_PASTE_START}${pasted}${BRACKETED_PASTE_END}`)
+    if (this.search.getValue() !== previous) {
+      this.selectedIndex = 0
+      this.error = ''
+    }
+    if (remaining !== '') this.handleInput(remaining)
+    this.invalidate()
+    return true
+  }
+
+  handleInput(data: string): void {
+    if (this.handleBracketedPaste(data)) return
+    const filtered = this.filtered()
+    if (matchesKey(data, Key.ctrl('c'))) {
+      this.cancel()
+      return
+    }
+    if (matchesKey(data, Key.escape)) {
+      if (this.search.getValue() === '') this.cancel()
+      else {
+        this.search.setValue('')
+        this.selectedIndex = 0
+        this.error = ''
+      }
+    } else if (matchesKey(data, Key.up)) {
+      this.selectedIndex = filtered.length === 0
+        ? 0
+        : (this.selectedIndex + filtered.length - 1) % filtered.length
+    } else if (matchesKey(data, Key.down)) {
+      this.selectedIndex = filtered.length === 0 ? 0 : (this.selectedIndex + 1) % filtered.length
+    } else if (matchesKey(data, Key.pageUp)) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - this.visibleCandidateCount())
+    } else if (matchesKey(data, Key.pageDown)) {
+      this.selectedIndex = Math.min(
+        Math.max(0, filtered.length - 1),
+        this.selectedIndex + this.visibleCandidateCount(),
+      )
+    } else if (matchesKey(data, Key.enter)) {
+      const selected = filtered[this.selectedIndex]
+      if (selected === undefined) this.error = 'No session matches this search.'
+      else if (selected.disabledReason !== undefined) this.error = selected.disabledReason
+      else this.done(selected)
+    } else {
+      const previous = this.search.getValue()
+      this.search.focused = this.focused
+      this.search.handleInput(data)
+      if (this.search.getValue() !== previous) {
+        this.selectedIndex = 0
+        this.error = ''
+      }
+    }
+    this.invalidate()
+  }
+
+  render(width: number): string[] {
+    this.search.focused = this.focused
+    const height = Math.max(1, this.viewportRows())
+    const horizontalPadding = width >= 12 ? 2 : 0
+    const contentWidth = Math.max(1, width - horizontalPadding * 2)
+    const indent = ' '.repeat(horizontalPadding)
+    const filtered = this.filtered()
+    if (this.selectedIndex >= filtered.length) this.selectedIndex = Math.max(0, filtered.length - 1)
+    const selected = filtered[this.selectedIndex]
+    const position = selected === undefined ? 0 : this.selectedIndex + 1
+    const lines: string[] = [
+      '',
+      `${indent}${this.palette.bold(this.palette.accent(`Resume session (${position} of ${filtered.length})`))}`,
+      '',
+    ]
+
+    const searchInnerWidth = Math.max(1, contentWidth - 4)
+    lines.push(`${indent}${this.palette.dim(`╭${'─'.repeat(Math.max(0, contentWidth - 2))}╮`)}`)
+    const searchContent = this.search.render(searchInnerWidth).join('').replace(/^> /u, '⌕ ')
+    const clippedSearch = truncateToWidth(searchContent, searchInnerWidth, '')
+    lines.push(
+      `${indent}${this.palette.dim('│')} ${clippedSearch}${' '.repeat(Math.max(0, searchInnerWidth - visibleWidth(clippedSearch)))} ${this.palette.dim('│')}`,
+      `${indent}${this.palette.dim(`╰${'─'.repeat(Math.max(0, contentWidth - 2))}╯`)}`,
+      '',
+      `${indent}${this.palette.muted(displayText(this.workspaceLabel))}`,
+      '',
+    )
+
+    const visibleCount = this.visibleCandidateCount()
+    const start = Math.max(0, Math.min(
+      this.selectedIndex - Math.floor(visibleCount / 2),
+      filtered.length - visibleCount,
+    ))
+    const end = Math.min(filtered.length, start + visibleCount)
+    const push = (line: string): void => {
+      lines.push(`${indent}${truncateToWidth(line, contentWidth, '…')}`)
+    }
+    for (let index = start; index < end; index += 1) {
+      const candidate = filtered[index] as ResumeCandidate
+      const active = index === this.selectedIndex
+      const status = [
+        candidate.disabledReason === 'current session' ? 'current' : undefined,
+        candidate.record.live ? 'live' : undefined,
+        candidate.record.persisted ? 'persisted' : undefined,
+      ].filter((value): value is string => value !== undefined).join(' · ')
+      const lead = `${active ? '❯' : ' '} ${displayText(candidate.title)}`
+      push(active ? this.palette.bold(this.palette.accent(lead)) : lead)
+      const route = candidate.route === undefined ? 'route unavailable' : `${candidate.route.provider}/${candidate.route.model}`
+      const goal = candidate.goalPhase === undefined ? '' : ` · goal ${candidate.goalPhase}`
+      push(this.palette.muted(`  ${new Date(candidate.lastActivityAt).toISOString()} · ${candidate.lastTurn} · ${route}${goal}`))
+      push(this.palette.dim(`  ${status} · ${displayText(candidate.record.header.id)}`))
+      if (candidate.disabledReason !== undefined) {
+        push(this.palette.warning(`  unavailable: ${displayText(candidate.disabledReason)}`))
+      }
+    }
+    if (filtered.length === 0) push(this.palette.warning('No matching sessions.'))
+    if (this.error !== '') {
+      lines.push('')
+      push(this.palette.error(displayText(this.error)))
+    }
+
+    const footer = `${indent}${this.palette.dim('Type to search  •  ↑/↓ navigate  •  Enter resume  •  Esc clear/cancel')}`
+    while (lines.length < height - 2) lines.push('')
+    lines.push(footer, '')
+    return lines.slice(0, height)
+  }
+}
+
 class QuestionDialog implements Component, Focusable {
  private selectedIndex = 0
  private selected = new Set<number>()
@@ -1585,6 +1867,7 @@ export function createTuiChat(
  const agent = ctx.agents.get(sessionId)
  if (agent === undefined) throw new Error(`ui-tui: session "${sessionId}" is not running`)
  const persistence = ctx.get('sessionPersistence')
+  const sessionQuery = ctx.get('sessionQuery')
  const resolved = resolveTuiConfig(config)
  const palette = createPalette(resolved.color)
  const mdTheme = markdownTheme(palette)
@@ -1601,14 +1884,15 @@ export function createTuiChat(
  let toolsExpanded = false
  let streaming: StreamingAssistantComponent | undefined
  let runningStatus: RunningStatus | undefined
-  // Steering messages queued during the running turn (`agent/queued`) that the
-  // loop has not yet drained, shown as a badge on the status line. Each entry is
-  // the queued message's serialized source: a drain (`steering/message`) removes
-  // one MATCHING entry, so loop-authored steering — continuation reasons enter
-  // the inbox without an `agent/queued` event — cannot consume a pending user
-  // message's slot. Cleared on leaving `running`, which also absorbs a
-  // cancellation that discards the queue without logging drains; the status
-  // line exists only while running, so idle carries no badge to keep current.
+  // Steering messages queued during the running turn (`agent/inbox/enqueue`
+  // with `info.steering`) that the loop has not yet drained, shown as a badge on
+  // the status line. Each entry is the queued message's serialized source: a
+  // drain (`steering/message`) removes one MATCHING entry, so a loop-authored
+  // continuation reason (which enqueues and drains under its own source) pushes
+  // and pops its own slot and cannot consume a pending user message's slot.
+  // Cleared on leaving `running`, which also absorbs a cancellation that
+  // discards the queue without logging drains; the status line exists only
+  // while running, so idle carries no badge to keep current.
  const pendingSteering: string[] = []
  let disposed = false
  let shuttingDown: Promise<void> | undefined
@@ -1631,6 +1915,9 @@ export function createTuiChat(
  const referenceControllers = new Set<AbortController>()
  let activeQuestion: PendingQuestion | undefined
  let modelOverlay: TuiOverlaySession | undefined
+  let resumeOverlay: TuiOverlaySession | undefined
+  let resumeInFlight = false
+  let resumeScan = 0
  let tuiServiceFiber: Fiber | undefined
  const target: AgentLlmTargetRef = { current: initialTarget(agent), assembled: undefined }
  let contextWindow: number | undefined
@@ -1640,6 +1927,8 @@ export function createTuiChat(
  > | undefined
  let modelCommands = Promise.resolve()
  const now = (): number => runtime.now?.() ?? Date.now()
+  const agentStatus = (): AgentStatus => agent.status
+  const isDisposed = (): boolean => disposed

  // A configured subtitle renders as a banner line; when absent, the banner has
  // no subtitle. The banner itself sweeps in on start (see startBannerReveal).
@@ -1950,6 +2239,29 @@ export function createTuiChat(
  const renderEvent = (event: SessionEvent, options: { addHistory: boolean; renderChunks: boolean }): void => {
    switch (event.type) {
      case 'user/message': {
+        // Injected context (plugin/goal source) renders as a dim context card,
+        // not a human bubble; only a direct human prompt is a user message. The
+        // boolean avoids narrowing `source`, so the label keeps its full union.
+        const source = event.data.source
+        if (source.kind !== 'user') {
+          const references = sessionReferenceCard(event.data.meta)
+          if (references !== undefined) {
+            chat.addChild(new Spacer(1))
+            chat.addChild(new Text(palette.dim(`Referenced sessions · ${references.map(displayText).join(', ')}`), 1, 0))
+            break
+          }
+          const text = displayText(contentText(event.data.content).trim())
+          if (text) {
+            // The tui type view lacks plugin-augmented source kinds (e.g. goal),
+            // so read the display label without narrowing on `kind`.
+            const labelled = source as { kind: string; plugin?: string }
+            const label = labelled.plugin ?? labelled.kind
+            chat.addChild(new Spacer(1))
+            chat.addChild(new Text(palette.dim(`Context · ${displayText(label)}`), 1, 0))
+            chat.addChild(new Text(palette.muted(text), 1, 0))
+          }
+          break
+        }
        const text = displayText(contentText(displayPromptContent(event.data)).trim())
        if (text) {
          chat.addChild(new Spacer(1))
@@ -1974,22 +2286,6 @@ export function createTuiChat(
        }
        break
      }
-      case 'context/message': {
-        const references = sessionReferenceCard(event.data.meta)
-        if (references !== undefined) {
-          chat.addChild(new Spacer(1))
-          chat.addChild(new Text(palette.dim(`Referenced sessions · ${references.map(displayText).join(', ')}`), 1, 0))
-          break
-        }
-        const text = displayText(contentText(event.data.content).trim())
-        if (text) {
-          const source = event.data.source.kind === 'plugin' ? event.data.source.plugin : event.data.source.kind
-          chat.addChild(new Spacer(1))
-          chat.addChild(new Text(palette.dim(`Context · ${displayText(source)}`), 1, 0))
-          chat.addChild(new Text(palette.muted(text), 1, 0))
-        }
-        break
-      }
      case 'prompt/blocked':
        appendNotice(`Prompt blocked: ${event.data.reason}`, 'warning')
        break
@@ -2074,7 +2370,6 @@ export function createTuiChat(
      const isSurface = event.type === 'user/message'
        || event.type === 'assistant/message'
        || event.type === 'tool/result'
-        || event.type === 'context/message'
        || event.type === 'steering/message'
      if (isSurface && !active.has(event.seq)) continue
      if (event.type === 'tool/call' && !activeCalls.has(event.data.callId)) continue
@@ -2204,7 +2499,6 @@ export function createTuiChat(
    }
    return all
      .filter(header => header.cwd === agent.session.header.cwd)
-      .sort((a, b) => b.createdAt - a.createdAt)
  }

  /**
@@ -2517,7 +2811,7 @@ export function createTuiChat(
    } else if (agent.status === 'running') {
      agent.steer(content, { contexts })
    } else {
-      agent.send(content, { contexts })
+      agent.followup(content, { contexts })
    }
  }

@@ -2597,37 +2891,156 @@ export function createTuiChat(
    })
  }

-  /**
-   * List this workspace's resumable sessions, newest first, each with its
-   * resume command and a marker on the current one. Warns when resume is not
-   * configured or no persistence backend is mounted; notes when nothing is
-   * persisted yet. The listing is asynchronous (a persistence scan), so the
-   * transcript updates once it resolves.
-   */
-  const showResume = (): void => {
-    const template = config.resumeCommand
-    if (template === undefined) {
-      appendNotice('Resume is not configured for this app.', 'warning')
-      return
+  /** Build one display candidate without letting a corrupt neighbor abort the selector. */
+  const readResumeCandidate = async (
+    record: SessionRecord,
+    providers: ReadonlySet<string>,
+  ): Promise<ResumeCandidate> => {
+    try {
+      let snapshot: SessionLogSnapshot
+      const live = ctx.sessions.get(record.header.id)
+      if (live !== undefined) {
+        snapshot = {
+          session: structuredClone(live.header),
+          events: live.events.map(event => structuredClone(event)),
+        }
+      } else {
+        /* v8 ignore next -- caller checks the optional service before mapping records */
+        if (sessionQuery === undefined) throw new Error('session query is unavailable')
+        snapshot = await sessionQuery.readSession(record.header.id)
+      }
+      return summarizeResumeCandidate(
+        record,
+        snapshot,
+        agent.session.id,
+        agent.session.header.cwd,
+        providers,
+      )
+    } catch (error: unknown) {
+      return {
+        record,
+        title: 'Unreadable session',
+        lastActivityAt: record.header.createdAt,
+        lastTurn: 'log unavailable',
+        disabledReason: `session cannot be loaded: ${errorChain(error)}`,
+      }
    }
-    if (persistence === undefined) {
-      appendNotice('Resume is not available: no persistence backend is mounted.', 'warning')
-      return
-    }
-    void listWorkspaceSessions().then((sessions) => {
-      if (sessions.length === 0) {
-        appendNotice('No resumable sessions found for this workspace yet.', 'info')
+  }
+
+  /** Re-read every mutable precondition immediately before terminal handoff. */
+  const preflightResume = async (sessionId: SessionId): Promise<ResumeCandidate> => {
+    /* v8 ignore next -- only showResume can call this closure, after proving the optional service exists */
+    if (sessionQuery === undefined) throw new Error('Resume is unavailable: session query is not mounted.')
+    const initialStatus = agentStatus()
+    if (initialStatus !== 'idle') throw new Error(`Resume requires an idle agent (status: ${initialStatus}).`)
+    const record = (await sessionQuery.listSessions()).find(candidate => candidate.header.id === sessionId)
+    if (record === undefined) throw new Error(`Session "${sessionId}" is no longer available.`)
+    const candidate = await readResumeCandidate(
+      record,
+      new Set(ctx.llm.listProviders().map(provider => provider.id)),
+    )
+    if (candidate.disabledReason !== undefined) throw new Error(candidate.disabledReason)
+    const finalStatus = agentStatus()
+    if (finalStatus !== 'idle') throw new Error(`Resume requires an idle agent (status: ${finalStatus}).`)
+    return candidate
+  }
+
+  const handoffResume = async (candidate: ResumeCandidate, overlay: TuiOverlaySession): Promise<void> => {
+    if (resumeInFlight) return
+    resumeInFlight = true
+    let terminalReleased = false
+    try {
+      const checked = await preflightResume(candidate.record.header.id)
+      const hostHandoff = runtime.handoffResume
+      if (hostHandoff === undefined) {
+        const template = config.resumeCommand
+        const fallback = template?.replaceAll('{session}', checked.record.header.id)
+        await overlay.close()
+        resumeOverlay = undefined
+        appendNotice(fallback === undefined
+          ? 'Session is resumable, but this host cannot hand it off in place.'
+          : `This host cannot hand off in place. Exit and run: ${fallback}`, 'warning')
        return
      }
-      chat.addChild(new Spacer(1))
-      chat.addChild(new Text(palette.bold(palette.accent('Resumable sessions')), 1, 0))
-      const lines = sessions.map((header) => {
-        const when = new Date(header.createdAt).toISOString().slice(0, 16).replace('T', ' ')
-        const marker = header.id === agent.session.id ? palette.success(' (current)') : ''
-        return `${palette.muted(when)}${marker}\n  ${displayText(template.replaceAll('{session}', header.id))}`
+      /* v8 ignore next -- shutdown during preflight invalidates an awaited service read or reaches this guard */
+      if (disposed) return
+      await ctx.sessions.flush(agent.session)
+      // Disposal can run while the flush promise is pending; TypeScript does not model that reentry.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (disposed) return
+      if (agent.status !== 'idle') throw new Error(`Resume requires an idle agent (status: ${agent.status}).`)
+      await overlay.close()
+      resumeOverlay = undefined
+      await runtime.terminal.drainInput(100, 20)
+      // Disposal can run while terminal draining is pending; TypeScript does not model that reentry.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (disposed) return
+      ui.stop()
+      terminalReleased = true
+      await hostHandoff(checked.record.header.id)
+      throw new Error('resume host returned without replacing the process')
+    } catch (error: unknown) {
+      if (!disposed) {
+        if (terminalReleased) {
+          ui.start()
+          ui.setFocus(editor)
+          appendNotice(`Resume handoff failed: ${errorChain(error)}`, 'error')
+        } else {
+          await overlay.close()
+          resumeOverlay = undefined
+          appendNotice(`Resume failed: ${errorChain(error)}`, 'error')
+        }
+      }
+    } finally {
+      resumeInFlight = false
+    }
+  }
+
+  /** Open the current-workspace searchable session selector. */
+  const showResume = (): void => {
+    if (agent.status !== 'idle') {
+      appendNotice('Resume requires the current turn to finish or be cancelled first.', 'warning')
+      return
+    }
+    if (sessionQuery === undefined) {
+      appendNotice('Resume is not available: session query is not mounted.', 'warning')
+      return
+    }
+    const scan = ++resumeScan
+    void resumeOverlay?.close()
+    void sessionQuery.listSessions().then(async (records) => {
+      if (isDisposed() || scan !== resumeScan) return
+      const workspace = records.filter(record => record.header.cwd === agent.session.header.cwd)
+      const providers = new Set(ctx.llm.listProviders().map(provider => provider.id))
+      const candidates = await Promise.all(workspace.map(record => readResumeCandidate(record, providers)))
+      candidates.sort((a, b) => b.lastActivityAt - a.lastActivityAt
+        || a.record.header.id.localeCompare(b.record.header.id))
+      if (isDisposed() || scan !== resumeScan) return
+      const session = overlayManager.open({
+        create: host => new ResumePicker(
+          candidates,
+          resolved.maxResumeOptions,
+          runtime.formatCwd?.(agent.session.header.cwd) ?? formatCwd(agent.session.header.cwd),
+          () => host.viewport.rows,
+          palette,
+          (candidate) => { void handoffResume(candidate, session) },
+          () => { void session.close() },
+        ),
+        options: {
+          width: '100%',
+          maxHeight: '100%',
+          anchor: 'top-left',
+          margin: 0,
+        },
+      })
+      resumeOverlay = session
+      void session.closed.then(() => {
+        /* v8 ignore next -- overlay FIFO closes this session before a replacement can become the tracked resume overlay */
+        if (resumeOverlay === session) resumeOverlay = undefined
      })
-      chat.addChild(new Text(lines.join('\n'), 1, 0))
      requestRender()
+    }, (error: unknown) => {
+      if (!disposed && scan === resumeScan) appendNotice(`Resume session scan failed: ${errorChain(error)}`, 'error')
    })
  }

@@ -2742,9 +3155,9 @@ export function createTuiChat(
    advanceTurnPhase(event)
    if (event.type === 'steering/message') {
      // A queued steering message reached the model as it drained; drop its
-      // entry from the badge. Matching by source keeps loop-authored steering
-      // (e.g. continuation reasons), which logs here without a matching
-      // `agent/queued` increment, from consuming a pending user slot.
+      // entry from the badge. Matching by source keeps a loop-authored
+      // continuation reason popping its own enqueued slot rather than a pending
+      // user message's slot.
      const drained = pendingSteering.indexOf(JSON.stringify(event.data.source))
      if (drained >= 0) {
        pendingSteering.splice(drained, 1)
@@ -2758,7 +3171,7 @@ export function createTuiChat(
    renderEvent(event, { addHistory: false, renderChunks: true })
    requestRender()
  })
-  const disposeQueued = ctx.on('agent/queued', (subject, _content, info) => {
+  const disposeQueued = ctx.on('agent/inbox/enqueue', (subject, info) => {
    if (subject !== agent || !info.steering) return
    pendingSteering.push(JSON.stringify(info.source))
    refreshStatus()
@@ -2828,6 +3241,14 @@ export function createTuiChat(
  }

  rebuildTranscript(true)
+  const restoredGoal = foldGoal(agent.session.events).goal
+  if (restoredGoal !== undefined && restoredGoal.phase !== 'complete') {
+    appendNotice(
+      `Goal restored (${restoredGoal.phase}) with automatic continuation disarmed. `
+      + 'Human confirmation is required; send “继续” or run /goal resume.',
+      'warning',
+    )
+  }
  setStatus(agent.status)
  try {
    ui.start()
@@ -2915,9 +3336,11 @@ export function apply(ctx: Context, config: Config): void {
  // Truecolor is a terminal capability, so detect it here at the process
  // boundary from COLORTERM; an explicit `truecolor` config value still wins.
  const truecolor = config.truecolor ?? ['truecolor', '24bit'].includes(process.env.COLORTERM ?? '')
+  const resumeHost = ctx.get('tuiResumeHost')
  mountTui(ctx, Object.assign({}, config, { truecolor }), {
    terminal: new ProcessTerminal(),
    exit: code => process.exit(code),
+    ...resumeHost === undefined ? {} : { handoffResume: sessionId => resumeHost.handoff(sessionId) },
  })
 }
 /* v8 ignore stop */
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -1,6 +1,7 @@
 import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
 import AgentRegistry, {
+  AgentMessageId,
  type Agent,
  type AgentCancelCause,
  type AgentOptions,
@@ -14,6 +15,7 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import { createTuiChat, type Config, type TuiRuntime } from '../src/index.ts'
+import { TestSessionQueryService } from './session-query.ts'

 interface FakeAgent extends Agent {
  status: AgentStatus
@@ -48,7 +50,13 @@ export interface TuiHarnessOptions {
    resolveModelContext?: (provider: string, model: string) => Promise<LlmModelContext | undefined>
  }
  /** Provide a fake `sessionPersistence` service so resume surfaces can list sessions. */
-  sessionPersistence?: { list(): Promise<SessionHeader[]> }
+  sessionPersistence?: {
+    list(): Promise<SessionHeader[]>
+    load?(id: ReturnType<typeof SessionId>): Promise<{ meta: SessionHeader; events: Session['events'] }>
+  }
+  handoffResume?: TuiRuntime['handoffResume']
+  /** Set false to exercise the optional session-query degradation path. */
+  mountSessionQuery?: boolean
 }

 export interface TuiHarness<TerminalType extends Terminal, Exit extends (code: number) => void> {
@@ -118,7 +126,22 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
  }
  if (ctx.get('systemPrompt') === undefined) await ctx.plugin(SystemPrompt)
  if (options.sessionPersistence !== undefined) {
-    ctx.provide('sessionPersistence', options.sessionPersistence as never)
+    const persistence = options.sessionPersistence
+    ctx.provide('sessionPersistence', {
+      ...persistence,
+      locate: () => undefined,
+      create: () => Promise.resolve(),
+      append: () => Promise.resolve(),
+      load: persistence.load === undefined
+        ? (id: ReturnType<typeof SessionId>) => Promise.reject(new Error(`session "${id}" not found`))
+        : (id: ReturnType<typeof SessionId>) => persistence.load!(id),
+      inspect: persistence.load === undefined
+        ? (id: ReturnType<typeof SessionId>) => Promise.reject(new Error(`session "${id}" not found`))
+        : (id: ReturnType<typeof SessionId>) => persistence.load!(id),
+    } as never)
+  }
+  if (options.mountSessionQuery !== false && ctx.get('sessionQuery') === undefined) {
+    await ctx.plugin(TestSessionQueryService)
  }
  const sessionId = SessionId('main-session')
  const session = ctx.sessions.create(
@@ -149,15 +172,23 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
    steered,
    steeredOptions,
    cancelled,
-    send(content, options) {
+    followup(content, options) {
      sent.push(content)
      sentOptions.push(options)
+      return AgentMessageId('stub')
+    },
+    queue(content, options) {
+      sent.push(content)
+      sentOptions.push(options)
+      return AgentMessageId('stub')
    },
    steer(content, options) {
      steered.push(content)
      steeredOptions.push(options)
+      return AgentMessageId('stub')
    },
-    inject() {},
+    inject: () => AgentMessageId('stub'),
+    send: () => AgentMessageId('stub'),
    cancel(cause = { kind: 'user' }) {
      cancelled.push(cause)
    },
@@ -178,6 +209,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
    // test pins the clock only by passing `now` explicitly.
    ...(options.now === undefined ? {} : { now: options.now }),
    ...(options.formatCwd === undefined ? {} : { formatCwd: options.formatCwd }),
+    ...(options.handoffResume === undefined ? {} : { handoffResume: options.handoffResume }),
  })
  return { ctx, session, agent, terminal, exit, controller }
 }
--- a/packages/ui/tui/tests/plugin-shape.spec.ts
+++ b/packages/ui/tui/tests/plugin-shape.spec.ts
@@ -14,6 +14,7 @@ describe('dsh-tui plugin export shape', () => {
    expect(unwrapped.name).toBe('ui-tui')
    expect(unwrapped.inject).toEqual([
      'agents',
+      'sessions',
      'commands',
      'userInteraction',
      'tools',
--- a/packages/ui/tui/tests/session-reference.snapshot.ts
+++ b/packages/ui/tui/tests/session-reference.snapshot.ts
@@ -128,7 +128,7 @@ describe('TUI session-reference snapshot', () => {
      type: 'text',
      text: '\n\n## My request:\n',
    })
-    expect(target.session.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(target.session.events.some(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toBe(false)

    const snapshot = await terminal.snapshot({ includeScrollback: true })
    if (REFRESHING) {
--- a/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
+++ b/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
@@ -1,32 +1,51 @@
 terminal 92x32 buffer=normal length=32 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=10 bufferRow=10
+cursor hidden column=6 viewportRow=4 bufferRow=4
 buffer
-0| " DEEPSEEK HARNESS"
-  style 1-8 fg=bright-blue bold
-  style 10-16 bold
-1| " Snapshot agent ready."
-  style 1-21 fg=bright-black
-2| " deepseek-v4-flash  •  main-session"
-  style 1-34 dim
-3| <blank>
-4| " Resumable sessions                                                                         "
-  style 1-18 fg=bright-blue bold
-5| " 2024-01-02 03:04 (current)                                                                 "
-  style 1-16 fg=bright-black
-  style 17-26 fg=green
-6| "   RESUME_SESSION_ID=main-session dsh                                                       "
-7| " 2024-01-01 00:00                                                                           "
-  style 1-16 fg=bright-black
-8| "   RESUME_SESSION_ID=earlier-session dsh                                                    "
-9| "────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-91 dim
-10| "                                                                                            "
-  style 1-1 inverse
-11| "────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-91 dim
-12| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                     0% context  tools:collapsed"
-  style 0-43 dim
-  style 65-91 dim
-13-31| <blank>
+0| "                                                                                            "
+1| "  Resume session (1 of 2)                                                                   "
+  style 2-24 fg=bright-blue bold
+2| "                                                                                            "
+3| "  ╭──────────────────────────────────────────────────────────────────────────────────────╮  "
+  style 2-89 dim
+4| "  │ ⌕                                                                                    │  "
+  style 2-2 dim
+  style 6-6 inverse
+  style 89-89 dim
+5| "  ╰──────────────────────────────────────────────────────────────────────────────────────╯  "
+  style 2-89 dim
+6| "                                                                                            "
+7| "  /workspace/project                                                                        "
+  style 2-19 fg=bright-black
+8| "                                                                                            "
+9| "  ❯ Untitled session                                                                        "
+  style 2-19 fg=bright-blue bold
+10| "    2026-07-23T08:00:00.000Z · no completed turn · route unavailable                        "
+  style 2-67 fg=bright-black
+11| "    current · live · main-session                                                           "
+  style 2-32 dim
+12| "    unavailable: current session                                                            "
+  style 2-31 fg=yellow
+13| "    Resume selector design                                                                  "
+14| "    2024-01-01T00:00:08.000Z · turn 1: completed · deepseek/deepseek-v4-pro                 "
+  style 2-74 fg=bright-black
+15| "    persisted · earlier-session                                                             "
+  style 2-30 dim
+16| "                                                                                            "
+17| "                                                                                            "
+18| "                                                                                            "
+19| "                                                                                            "
+20| "                                                                                            "
+21| "                                                                                            "
+22| "                                                                                            "
+23| "                                                                                            "
+24| "                                                                                            "
+25| "                                                                                            "
+26| "                                                                                            "
+27| "                                                                                            "
+28| "                                                                                            "
+29| "                                                                                            "
+30| "  Type to search  •  ↑/↓ navigate  •  Enter resume  •  Esc clear/cancel                     "
+  style 2-70 dim
+31| "                                                                                            "
--- a/packages/ui/tui/tests/tui.snapshot.ts
+++ b/packages/ui/tui/tests/tui.snapshot.ts
@@ -471,7 +471,7 @@ describe('TUI terminal-state snapshots', () => {
        session.append('todo/write', {
          todos: [{ content: `Unsafe todo ${CONTROL_PROBE}`, status: 'in_progress' }],
        })
-        session.append('context/message', {
+        session.append('user/message', {
          content: [{ type: 'text', text: `Unsafe context ${CONTROL_PROBE}` }],
          source: { kind: 'plugin', plugin: `unsafe-${CONTROL_PROBE}` },
        }, { surfaceOp: 'append' })
@@ -587,7 +587,7 @@ describe('TUI terminal-state snapshots', () => {
    await checkpoint('surface-before-compaction', harness.terminal, { includeScrollback: true })

    await renderAfter(harness, () => {
-      harness.session.append('context/message', {
+      harness.session.append('user/message', {
        content: [{ type: 'text', text: 'Compacted summary: the prior command completed and its details were retired from the active surface.' }],
        source: { kind: 'plugin', plugin: 'compact' },
      }, {
@@ -646,13 +646,27 @@ describe('TUI terminal-state snapshots', () => {
    await disposeSnapshot(harness)
  })

-  it('lists this workspace\'s resumable sessions with their commands', async () => {
+  it('opens the searchable resume selector with log-backed session summaries', async () => {
+    const dateNow = vi.spyOn(Date, 'now').mockReturnValue(Date.parse('2026-07-23T08:00:00.000Z'))
+    const earlier = { version: 0, id: SessionId('earlier-session'), createdAt: Date.parse('2024-01-01T00:00:00Z'), cwd: '/workspace/project' }
    const harness = await setupSnapshot({
      config: { resumeCommand: 'RESUME_SESSION_ID={session} dsh' },
-      sessionPersistence: { list: async () => [
-        { version: 0, id: SessionId('main-session'), createdAt: Date.parse('2024-01-02T03:04:00Z'), cwd: '/workspace/project' },
-        { version: 0, id: SessionId('earlier-session'), createdAt: Date.parse('2024-01-01T00:00:00Z'), cwd: '/workspace/project' },
-      ] },
+      sessionPersistence: {
+        list: async () => [earlier],
+        load: async () => ({
+          meta: earlier,
+          events: [
+            { type: 'turn/start', seq: 0, time: Date.parse('2024-01-01T00:00:01Z'), data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+            { type: 'user/message', seq: 1, time: Date.parse('2024-01-01T00:00:02Z'), data: { content: [{ type: 'text', text: 'restore the selector' }], source: { kind: 'user' } }, surfaceOp: 'append' },
+            { type: 'step/start', seq: 2, time: Date.parse('2024-01-01T00:00:03Z'), data: { turn: 1, step: 1 } },
+            { type: 'request/header', seq: 3, time: Date.parse('2024-01-01T00:00:04Z'), data: { header: { config: { provider: 'deepseek', model: 'deepseek-v4-pro' } }, reason: 'initial' } },
+            { type: 'assistant/message', seq: 4, time: Date.parse('2024-01-01T00:00:05Z'), data: { turn: 1, step: 1, content: [{ type: 'text', text: 'ready' }], provenance: { provider: 'deepseek', model: 'deepseek-v4-pro' } }, surfaceOp: 'append' },
+            { type: 'step/end', seq: 5, time: Date.parse('2024-01-01T00:00:06Z'), data: { turn: 1, step: 1 } },
+            { type: 'turn/end', seq: 6, time: Date.parse('2024-01-01T00:00:07Z'), data: { turn: 1, reason: { kind: 'completed' } } },
+            { type: 'session/title', seq: 7, time: Date.parse('2024-01-01T00:00:08Z'), data: { title: 'Resume selector design', messageSeqs: [1], source: { kind: 'fallback' } } },
+          ],
+        }),
+      },
    }, { columns: 92, rows: 32 })
    harness.terminal.send('/resume')
    harness.terminal.send('\r')
@@ -662,6 +676,7 @@ describe('TUI terminal-state snapshots', () => {
    await harness.terminal.flush()
    await checkpoint('resume-sessions', harness.terminal, { includeScrollback: true })
    await disposeSnapshot(harness)
+    dateNow.mockRestore()
  })

  it('pins the detailed session diagnostics card', async () => {
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
--- a/packages/ui/tui/tsconfig.json
+++ b/packages/ui/tui/tsconfig.json
@@ -20,6 +20,9 @@
    {
      "path": "../../core/agent-loop"
    },
+    {
+      "path": "../../goal/goal"
+    },
    {
      "path": "../../core/session"
    },
@@ -29,6 +32,9 @@
    {
      "path": "../../session-persistence/session-persistence"
    },
+    {
+      "path": "../../session-query/session-query"
+    },
    {
      "path": "../../session-title/session-title"
    },