Merge refreshed schema DSL into canonical tool output

# Conflicts:
#	docs/config-catalog.md
#	examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
#	examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
#	examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
#	packages/context/workspace-context/tests/workspace-context.spec.ts
#	packages/core/tools/tests/tools.spec.ts
#	packages/ui/tui/src/index.ts
#	packages/ui/tui/tests/tui.snapshot.ts

packages/README.md

@@ -11,10 +11,10 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
 | [`goal/`](goal/README.md) | Persisted same-session goal state and lifecycle | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
-| [`bash/`](bash/README.md) | Bash capability family: the executor seam, a local impl, and the model-facing tool | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
+| [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
-| [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, the model-facing file tools, and the bash-backed discovery tools | Product — stable surface |
+| [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
@@ -22,9 +22,10 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
 | [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable surface |
 | [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, worker-thread engine, and model-facing `workflow` and fresh-agent `ralph` tools | Product — stable surface |
-| [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
-| [`spill/`](spill/README.md) | Spill capability family: the storage seam, a local impl, and the tool-result spill policy | Product — stable surface |
+| [`web/`](web/README.md) | Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
+| [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable surface |
 | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool | Product — stable surface |
+| [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable surface |
 | [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface |
 | [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface |
 | [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface |

packages/client/connection/src/client/api.ts

@@ -44,4 +44,3 @@ export function transportError<T>(error: unknown): RpcResult<T> {
     error: { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} },
   }
 }
-

packages/context/workspace-context/README.md

@@ -4,11 +4,11 @@ Per-session workspace instruction loading for `AGENTS.md`-compatible files. The
 
 ## Lifecycle
 
-The baseline is composed once per agent-loop instance on `agent/session-prefix`. It reads `$DSH_HOME/AGENTS.md` followed by one configured instruction candidate in each directory from the project root to `agent.session.header.cwd`. The prefix is placed before all derived history, recorded in `EpochHeader.messagePrefix`, and reused verbatim for that loop instance. Because the plugin prepends its contribution before delegating, a later-registered skills catalog appears after workspace instructions.
+The baseline is composed once per agent-loop instance on `agent/session-prefix`. It reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. The prefix is placed before all derived history, recorded in `EpochHeader.messagePrefix`, and reused verbatim for that loop instance. Because the plugin prepends its contribution before delegating, a later-registered skills catalog appears after workspace instructions.
 
-The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. A new file is attached through the result's `additionalContexts`; a changed file or candidate switch appends a replacement; a missing final candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.
+The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. Each configured candidate name is an independent scope in its directory: a newly present file is attached through the result's `additionalContexts`; a changed file appends a replacement; a file that disappears or becomes a per-directory duplicate of an earlier candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.
 
-Instruction reads use the optional `ctx.fs` provider. The plugin does not statically inject `fs`, so providerless product trees still boot and instruction loading becomes a no-op until a provider is present. It calls `ctx.fs.lstat` before resolving a candidate, rejecting a final-component symlink instead of following repository-owned links across the trust boundary. Once `lstat` identifies the winning regular-file candidate, a later resolve/stat failure makes that scope temporarily unavailable instead of falling through to a lower-priority name. Prefix cancellation and dynamic tool cancellation propagate through resolution, metadata probes, and streaming reads. A provider failure after a file was loaded is treated as temporarily unavailable, not as proof that the file was deleted.
+Instruction reads use the optional `ctx.fs` provider. The plugin does not statically inject `fs`, so providerless product trees still boot and instruction loading becomes a no-op until a provider is present. It resolves each candidate and stats the result, so a final-component symlink is followed to its target: a link to a regular file loads that target's content, while a missing path or a non-file target (including a link to a directory) is a confirmed absence. A resolve or stat exception instead marks that candidate's scope temporarily unavailable. Prefix cancellation and dynamic tool cancellation propagate through resolution, metadata probes, and streaming reads. A provider failure after a file was loaded is treated as temporarily unavailable, not as proof that the file was deleted.
 
 ## Prompt Shape
 
@@ -40,15 +40,15 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 </system-reminder>
 ```
 
-A same-file edit starts with `Updated instructions from: <path>` and says to use the new content instead of the previously loaded content. A candidate switch additionally names the old path. When no candidate remains, 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.
+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.
 
 ## 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, previousPath?, 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 `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.
 
-An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest }`: 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. 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.
+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.
 
 The frozen baseline itself is not rewritten mid-instance. Its initial path/digest map is retained as comparison state; the next successful filesystem touch appends any baseline replacement or removal. A resumed loop recomposes the current baseline and also reconciles still-visible dynamic scopes during prefix composition. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, or when a resumed loop composes its prefix.
 
@@ -61,18 +61,19 @@ export interface Config {
   maxBytes: number
   maxSourceBytes?: number
   instructionFileCandidates?: string[]
+  localInstructionFileCandidates?: string[]
 }
 ```
 
-`maxBytes` is required so each deployment makes its prompt-budget choice explicitly. `maxSourceBytes` limits each source instruction file before rendering and defaults to 1 MiB. `projectRootMarkers` defaults to `['.git']`, and `instructionFileCandidates` defaults to `['AGENTS.md', 'CLAUDE.md']`. In each project directory, the first existing candidate wins; with defaults, `AGENTS.md` is native and `CLAUDE.md` is the compatibility fallback. Candidate entries must be same-directory file names, so empty entries, `.`/`..`, and entries containing `/` or `\` are ignored.
+`maxBytes` is required so each deployment makes its prompt-budget choice explicitly. `maxSourceBytes` limits each source instruction file before rendering and defaults to 1 MiB. `projectRootMarkers` defaults to `['.git']`, and `instructionFileCandidates` defaults to `['AGENTS.md', 'CLAUDE.md']`. In each project directory every existing candidate loads, and candidates whose content matches an earlier one after trimming surrounding whitespace are dropped, so with the defaults an `AGENTS.md` and a `CLAUDE.md` that share content render once (as `AGENTS.md`) while genuinely distinct siblings both apply. `localInstructionFileCandidates` defaults to `['AGENTS.local.md', 'CLAUDE.local.md']` and loads its existing overlays alongside the base files of the same directory (rendered after them) under the same per-directory dedup; an empty list disables the overlay. Candidate entries in both lists must be same-directory file names, so empty entries, `.`/`..`, and entries containing `/` or `\` are ignored.
 
-The user-global file is always `$DSH_HOME/AGENTS.md`; the candidate list only controls project scopes. `$DSH_HOME` defaults to `~/.dsh`, and configured `~`, `~/...`, and Windows-style `~\...` prefixes are expanded against the operating-system home directory. A non-positive or non-finite render budget disables both baseline and dynamic loading; configured `maxSourceBytes` must be a positive integer.
+The user-global file is always `$DSH_HOME/AGENTS.md` with no local overlay; both candidate lists only control project scopes. `$DSH_HOME` defaults to `~/.dsh`, and configured `~`, `~/...`, and Windows-style `~\...` prefixes are expanded against the operating-system home directory. A non-positive or non-finite render budget disables both baseline and dynamic loading; configured `maxSourceBytes` must be a positive integer.
 
 ## Budgeting And Bounded Reads
 
 Rendering preserves the most specific instruction files first. It drops whole broader files before truncating the most-specific file and emits a visible `Workspace instruction budget ...` notice naming omitted and truncated paths. The rendered bytes never exceed `maxBytes`.
 
-Instruction content is read through `streamText()` under `maxSourceBytes`, even when provider metadata omits size or a file grows after its metadata probe. An oversized file is ignored without falling through to a lower-priority same-directory candidate; during dynamic reconciliation it is temporarily unavailable rather than removed. The plugin keeps no process-wide cache and never caches instruction prose. Its session-local scope cache uses provider versions only as a fast invalidation signal; after invalidation, SHA-1 over the bounded read remains the cross-provider content identity stored in structured session metadata.
+Instruction content is read through `streamText()` under `maxSourceBytes`, even when provider metadata omits size or a file grows after its metadata probe. An oversized file is ignored; during dynamic reconciliation it is temporarily unavailable rather than removed. The plugin keeps no process-wide cache and never caches instruction prose. Its session-local scope cache uses provider versions only as a fast invalidation signal; after invalidation, SHA-1 over the bounded read remains the cross-provider content identity stored in structured session metadata.
 
 ## Model Experience
 
@@ -136,7 +137,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-A changed file produces `Updated instructions from: <path>` plus its replacement content; a candidate switch also names the previous path. A removed final candidate produces the removal notice below.
+A changed file produces `Updated instructions from: <path>` plus its replacement content. A candidate that disappears or becomes a per-directory duplicate of an earlier candidate produces the removal notice below.
 
 ##### Removal notice
 
@@ -160,5 +161,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **Discovery follows structured fs tools, not shell navigation** — a `bash` command that changes directories does not trigger nested instruction discovery because shell syntax and per-call shell state are not a reliable filesystem seam.
 - **Refresh is touch-driven** — there is no watcher; external edits become visible on the next successful first-party `read`, `write`, or `edit`, or when a resumed loop recomposes its prefix.
-- **Candidate semantics stay intentionally small** — lowercase names, `.claude/rules/`, and `@path` imports are not interpreted; same-directory names such as `CLAUDE.local.md` require explicit `instructionFileCandidates` configuration.
+- **Candidate semantics stay intentionally small** — lowercase names, `.claude/rules/`, and `@path` imports are not interpreted; project scopes load `AGENTS.local.md`/`CLAUDE.local.md` overlays by default, but the user-global `$DSH_HOME` scope has no local overlay and other custom names require explicit candidate configuration.
+- **Per-directory dedup is content-based** — sibling candidates collapse only when byte-identical after trimming leading and trailing whitespace; a `CLAUDE.md` that symlinks its sibling `AGENTS.md` resolves to the same content and collapses like any duplicate, while a distinct real copy that has drifted from `AGENTS.md` loads in full alongside it.
+- **Symlinked instruction files are followed across the trust boundary** — a candidate whose final component is a symlink is resolved and its target loaded, so a cloned repository can surface off-tree file content as lower-authority workspace guidance (it never overrides system, developer, or direct user instructions). Confine `ctx.fs` with the filesystem policy gate or an OS sandbox when loading untrusted repositories.
 - **Instruction content is bounded, not summarized** — over-budget broad files are omitted and the most-specific file may be truncated; the plugin never asks a model to compress instruction prose.

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

@@ -9,6 +9,7 @@ import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 
 const DEFAULT_PROJECT_ROOT_MARKERS = ['.git'] as const
 const DEFAULT_INSTRUCTION_FILE_CANDIDATES = ['AGENTS.md', 'CLAUDE.md'] as const
+const DEFAULT_LOCAL_INSTRUCTION_FILE_CANDIDATES = ['AGENTS.local.md', 'CLAUDE.local.md'] as const
 const DEFAULT_MAX_SOURCE_BYTES = 1_048_576
 const RESERVED_PATH_SEGMENTS = new Set(['', '.', '..'])
 
@@ -22,8 +23,16 @@ export interface Config {
   maxBytes: number
   /** Maximum UTF-8 bytes read from one instruction file; larger files are ignored. */
   maxSourceBytes?: number
-  /** Ordered same-directory project candidates; the first existing regular file wins in each scope. */
+  /**
+   * Ordered same-directory project candidates; every existing file loads, with
+   * per-directory trimmed-content duplicates collapsed to the earliest candidate.
+   */
   instructionFileCandidates?: string[]
+  /**
+   * Ordered same-directory local-overlay candidates loaded after the base files
+   * under the same per-directory trimmed-content dedup; empty disables the overlay.
+   */
+  localInstructionFileCandidates?: string[]
 }
 
 export const Config: z<Config> = z.object({
@@ -32,6 +41,7 @@ export const Config: z<Config> = z.object({
   maxBytes: z.number().required(),
   maxSourceBytes: z.number().step(1).min(1).default(DEFAULT_MAX_SOURCE_BYTES),
   instructionFileCandidates: z.array(z.string()).default([...DEFAULT_INSTRUCTION_FILE_CANDIDATES]),
+  localInstructionFileCandidates: z.array(z.string()).default([...DEFAULT_LOCAL_INSTRUCTION_FILE_CANDIDATES]),
 })
 
 /** Normalized instruction discovery configuration. */
@@ -39,6 +49,7 @@ export interface ResolvedDiscoveryConfig {
   dshHome: string
   projectRootMarkers: string[]
   instructionFileCandidates: string[]
+  localInstructionFileCandidates: string[]
 }
 
 /** Normalized configuration used by discovery and reconciliation. */
@@ -66,17 +77,24 @@ export function resolveConfig(config: Config): ResolvedConfig {
  * @returns normalized home, root markers, and instruction candidates.
  */
 export function resolveDiscoveryConfig(
-  config: Pick<Config, 'dshHome' | 'projectRootMarkers' | 'instructionFileCandidates'>,
+  config: Pick<Config, 'dshHome' | 'projectRootMarkers' | 'instructionFileCandidates' | 'localInstructionFileCandidates'>,
 ): ResolvedDiscoveryConfig {
   return {
     dshHome: resolveDshHome(config.dshHome),
     projectRootMarkers: config.projectRootMarkers ?? [...DEFAULT_PROJECT_ROOT_MARKERS],
-    instructionFileCandidates: resolveInstructionFileCandidates(config.instructionFileCandidates),
+    instructionFileCandidates: resolveInstructionFileCandidates(
+      config.instructionFileCandidates,
+      DEFAULT_INSTRUCTION_FILE_CANDIDATES,
+    ),
+    localInstructionFileCandidates: resolveInstructionFileCandidates(
+      config.localInstructionFileCandidates,
+      DEFAULT_LOCAL_INSTRUCTION_FILE_CANDIDATES,
+    ),
   }
 }
 
-function resolveInstructionFileCandidates(candidates: string[] | undefined): string[] {
-  return (candidates ?? [...DEFAULT_INSTRUCTION_FILE_CANDIDATES]).filter(candidate => (
+function resolveInstructionFileCandidates(candidates: string[] | undefined, fallback: readonly string[]): string[] {
+  return (candidates ?? [...fallback]).filter(candidate => (
     !RESERVED_PATH_SEGMENTS.has(candidate) && !/[\\/]/.test(candidate)
   ))
 }

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

@@ -14,3 +14,15 @@ import { createHash } from 'node:crypto'
 export function instructionContentSha1(content: string): string {
   return createHash('sha1').update(content).digest('hex')
 }
+
+/**
+ * Compute the whitespace-insensitive identity used for per-directory duplicate
+ * suppression. Leading and trailing whitespace is trimmed before hashing so a
+ * symlinked or byte-copied sibling that differs only by surrounding whitespace
+ * still collapses to a single rendered file.
+ * @param content - exact UTF-8 instruction text.
+ * @returns SHA-1 digest of the trimmed content.
+ */
+export function trimmedInstructionDigest(content: string): string {
+  return instructionContentSha1(content.trim())
+}

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

@@ -5,13 +5,14 @@
  */
 
 import { createReadStream } from 'node:fs'
-import { lstat, stat } from 'node:fs/promises'
+import { stat } from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
-import type { FileSystem, FsInfo, FsPathInfo, FsTarget, FsVersion } from '@deepseek-ai/dsh-fs'
+import type { FileSystem, FsInfo, FsTarget, FsVersion } from '@deepseek-ai/dsh-fs'
 import { assertNever } from '@deepseek-ai/dsh-llm'
 import { dshHomeDisplay } from '@deepseek-ai/dsh-paths'
 import { resolveConfig, resolveDiscoveryConfig, type ResolvedConfig } from './config.ts'
-import { renderWorkspaceContext, type RenderedWorkspaceContext } from './render.ts'
+import { trimmedInstructionDigest } from './digest.ts'
+import { decodeScopeKey, renderWorkspaceContext, USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE, type RenderedWorkspaceContext } from './render.ts'
 
 /** An instruction candidate identified by absolute and model-facing paths. */
 export interface InstructionFile {
@@ -32,7 +33,7 @@ interface DiscoveredInstructionFile extends InstructionFile {
   version?: FsVersion
 }
 
-/** Provider metadata for a winning scope candidate before its content is read. */
+/** Provider metadata for a probed scope candidate before its content is read. */
 export interface ProbedInstructionFile extends InstructionFile {
   target: FsTarget
   version: FsVersion
@@ -44,6 +45,7 @@ interface DiscoverOptions {
   dshHome?: string
   projectRootMarkers?: string[]
   instructionFileCandidates?: string[]
+  localInstructionFileCandidates?: string[]
   signal?: AbortSignal
 }
 
@@ -86,7 +88,9 @@ function isMissingPathError(error: unknown): boolean {
 async function nodeStatFile(path: string, signal?: AbortSignal): Promise<StatFileProbe> {
   try {
     signal?.throwIfAborted()
-    const info = await lstat(path)
+    // stat (not lstat) follows a final-component symlink so a link to a regular
+    // file loads; a broken link surfaces as ENOENT and is treated as absent below.
+    const info = await stat(path)
     signal?.throwIfAborted()
     if (!info.isFile()) return { kind: 'absent' }
     return { kind: 'present', info: { size: info.size } }
@@ -101,25 +105,15 @@ async function fsStatFile(
   fileSystem: FileSystem,
   signal?: AbortSignal,
 ): Promise<StatFileProbe> {
-  // TODO(instruction-symlink-race): replace this lstat -> resolve -> read
-  // protocol, including probeScopeInstruction below, with a provider-owned
-  // atomic no-follow read so the final component cannot change after validation.
-  let pathInfo: FsPathInfo | undefined
-  try {
-    pathInfo = await fileSystem.lstat(path, undefined, signal)
-    signal?.throwIfAborted()
-  } catch {
-    signal?.throwIfAborted()
-    return { kind: 'unavailable' }
-  }
-  if (pathInfo?.type !== 'file') return { kind: 'absent' }
-
+  // resolve() follows a final-component symlink to its target's stable identity;
+  // stat then classifies that target. A link to a regular file loads, while a
+  // missing path or non-file target (including a link to a directory) is absent.
   try {
     const target = await fileSystem.resolve(path, signalOptions(signal))
     signal?.throwIfAborted()
     const info = await fileSystem.stat(target, signal)
     signal?.throwIfAborted()
-    if (info?.type !== 'file') return { kind: 'unavailable' }
+    if (info?.type !== 'file') return { kind: 'absent' }
     return {
       kind: 'present',
       info: { target, version: info.version, ...info.size === undefined ? {} : { size: info.size } },
@@ -232,33 +226,32 @@ export function relativeDisplay(root: string, path: string): string {
   return relative(root, path)
 }
 
-async function firstExistingInstructionFile(
+async function allExistingInstructionFiles(
   dir: string,
   root: string,
   instructionFileCandidates: readonly string[],
   fileSystem?: FileSystem,
   signal?: AbortSignal,
-): Promise<DiscoveredInstructionFile | undefined> {
+): Promise<DiscoveredInstructionFile[]> {
+  const found: DiscoveredInstructionFile[] = []
   for (const candidate of instructionFileCandidates) {
     const path = join(dir, candidate)
     const probe = await statFile(path, fileSystem, signal)
     switch (probe.kind) {
       case 'present':
-        return {
-          absolutePath: path,
-          displayPath: relativeDisplay(root, path),
-          ...probe.info,
-        }
-      case 'absent':
+        found.push({ absolutePath: path, displayPath: relativeDisplay(root, path), ...probe.info })
         continue
+      // A missing candidate is skipped; a transient provider failure skips only
+      // that candidate so the remaining independent candidates still load.
+      case 'absent':
       case 'unavailable':
-        return undefined
+        continue
       /* v8 ignore next 2 -- StatFileProbe is closed; this arm only makes adding a kind a compile error. */
       default:
-        return assertNever(probe, 'StatFileProbe')
+        assertNever(probe, 'StatFileProbe')
     }
   }
-  return undefined
+  return found
 }
 
 async function discoverInstructionFiles(
@@ -274,7 +267,7 @@ async function discoverInstructionFiles(
     files.push(file)
   }
 
-  const userGlobal = join(config.dshHome, 'AGENTS.md')
+  const userGlobal = join(config.dshHome, USER_GLOBAL_FILE)
   const userGlobalProbe = await statFile(userGlobal, fileSystem, options.signal)
   switch (userGlobalProbe.kind) {
     case 'present':
@@ -295,16 +288,21 @@ async function discoverInstructionFiles(
   const cwd = resolve(options.cwd)
   const projectRoot = await findProjectRoot(cwd, config.projectRootMarkers, fileSystem, options.signal)
   for (const dir of ancestorChain(projectRoot, cwd)) {
-    const file = await firstExistingInstructionFile(dir, projectRoot, config.instructionFileCandidates, fileSystem, options.signal)
-    if (file !== undefined) addFile(file)
+    for (const candidates of [config.instructionFileCandidates, config.localInstructionFileCandidates]) {
+      for (const file of await allExistingInstructionFiles(dir, projectRoot, candidates, fileSystem, options.signal)) {
+        addFile(file)
+      }
+    }
   }
   return files
 }
 
 /**
  * Discover host-visible user-global and root-to-cwd instruction candidates.
+ * All present candidates in each directory are returned; trimmed-content
+ * duplicates are collapsed later, once content is read.
  * @param options - cwd, home, root marker, and candidate configuration.
- * @returns de-duplicated instruction paths in model precedence order.
+ * @returns path-deduplicated instruction candidates in model precedence order.
  */
 export async function discoverBaselineInstructionFiles(options: DiscoverOptions): Promise<InstructionFile[]> {
   return (await discoverInstructionFiles(options)).map(({ absolutePath, displayPath }) => ({ absolutePath, displayPath }))
@@ -316,7 +314,7 @@ async function* nodeTextChunks(path: string, signal?: AbortSignal): AsyncIterabl
 }
 
 async function readBounded(
-  file: DiscoveredInstructionFile,
+  file: { absolutePath: string; target?: FsTarget; size?: number },
   maxSourceBytes: number,
   fileSystem?: FileSystem,
   signal?: AbortSignal,
@@ -347,6 +345,33 @@ async function readBounded(
   }
 }
 
+/**
+ * Drop later candidates whose trimmed content duplicates an earlier sibling in
+ * the same directory. Different directories never collapse even when identical;
+ * within one directory the earliest candidate in discovery order is kept and its
+ * original bytes are rendered. A candidate that symlinks a sibling resolves to
+ * the same content and collapses here like any byte-identical real file.
+ * @param files - loaded files in discovery order.
+ * @returns the retained files in the same order.
+ */
+export function dedupInstructionFilesByDirectory(files: LoadedInstructionFile[]): LoadedInstructionFile[] {
+  const keptDigestsByDir = new Map<string, Set<string>>()
+  const kept: LoadedInstructionFile[] = []
+  for (const file of files) {
+    const dir = dirname(file.displayPath)
+    let digests = keptDigestsByDir.get(dir)
+    if (digests === undefined) {
+      digests = new Set()
+      keptDigestsByDir.set(dir, digests)
+    }
+    const digest = trimmedInstructionDigest(file.content)
+    if (digests.has(digest)) continue
+    digests.add(digest)
+    kept.push(file)
+  }
+  return kept
+}
+
 /**
  * Discover, read, and render the baseline instruction chain.
  * @param options - discovery, source-size, byte-budget, and cancellation configuration.
@@ -386,18 +411,19 @@ export async function loadBaselineInstructionSet(
       })
     }
   }
-  if (loaded.length === 0) return undefined
-  const rendered = renderWorkspaceContext(loaded, { maxBytes: config.maxBytes })
+  const deduped = dedupInstructionFilesByDirectory(loaded)
+  if (deduped.length === 0) return undefined
+  const rendered = renderWorkspaceContext(deduped, { maxBytes: config.maxBytes })
   const omitted = new Set(rendered.omitted.map(file => file.absolutePath))
-  return { rendered, included: loaded.filter(file => !omitted.has(file.absolutePath)) }
+  return { rendered, included: deduped.filter(file => !omitted.has(file.absolutePath)) }
 }
 
 /**
- * Probe the current first-winning instruction candidate for one logical scope.
- * @param scope - `user-global`, `.`, or a project-relative directory.
+ * Probe the current provider metadata for one per-candidate instruction scope.
+ * @param scope - a {@link candidateScopeKey} identifying a directory and candidate file.
  * @param projectRoot - project root used to resolve and display project scopes.
  * @param resolved - normalized plugin configuration.
- * @param fileSystem - provider used for no-follow probing.
+ * @param fileSystem - provider used to resolve and stat scope candidates.
  * @param signal - cancellation for provider probes.
  * @returns present metadata, confirmed absence, or temporary unavailability.
  */
@@ -408,40 +434,32 @@ export async function probeScopeInstruction(
   fileSystem: FileSystem,
   signal?: AbortSignal,
 ): Promise<ScopeInstructionProbe> {
-  const dir = scope === 'user-global'
+  const { directory, candidateName } = decodeScopeKey(scope)
+  const dir = directory === USER_GLOBAL_DIRECTORY
     ? resolved.dshHome
-    : scope === '.' ? projectRoot : join(projectRoot, scope)
-  const candidates = scope === 'user-global' ? ['AGENTS.md'] : resolved.instructionFileCandidates
-  for (const candidate of candidates) {
-    const absolutePath = join(dir, candidate)
-    let pathInfo: FsPathInfo | undefined
-    try {
-      pathInfo = await fileSystem.lstat(absolutePath, undefined, signal)
-    } catch {
-      signal?.throwIfAborted()
-      return { kind: 'unavailable' }
-    }
-    if (pathInfo === undefined || pathInfo.type !== 'file') continue
-    let target: FsTarget
-    let info: FsInfo | undefined
-    try {
-      target = await fileSystem.resolve(absolutePath, signalOptions(signal))
-      info = await fileSystem.stat(target, signal)
-    } catch {
-      signal?.throwIfAborted()
-      return { kind: 'unavailable' }
-    }
-    if (info?.type !== 'file') return { kind: 'unavailable' }
-    const file: ProbedInstructionFile = {
-      absolutePath,
-      displayPath: scope === 'user-global' ? userGlobalDisplayPath(resolved.dshHome) : relativeDisplay(projectRoot, absolutePath),
-      target,
-      version: info.version,
-      ...info.size === undefined ? {} : { size: info.size },
-    }
-    return { kind: 'present', file }
+    : directory === '.' ? projectRoot : join(projectRoot, directory)
+  const absolutePath = join(dir, candidateName)
+  // resolve() follows a final-component symlink; stat then classifies the target.
+  // A non-file target (missing, or a link to a directory) is a confirmed absence;
+  // only a provider exception is reported as unavailable.
+  let target: FsTarget
+  let info: FsInfo | undefined
+  try {
+    target = await fileSystem.resolve(absolutePath, signalOptions(signal))
+    info = await fileSystem.stat(target, signal)
+  } catch {
+    signal?.throwIfAborted()
+    return { kind: 'unavailable' }
   }
-  return { kind: 'absent' }
+  if (info?.type !== 'file') return { kind: 'absent' }
+  const file: ProbedInstructionFile = {
+    absolutePath,
+    displayPath: directory === USER_GLOBAL_DIRECTORY ? userGlobalDisplayPath(resolved.dshHome) : relativeDisplay(projectRoot, absolutePath),
+    target,
+    version: info.version,
+    ...info.size === undefined ? {} : { size: info.size },
+  }
+  return { kind: 'present', file }
 }
 
 /**

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

@@ -74,6 +74,7 @@ export function apply(ctx: Context, config: Config): void {
       maxBytes: resolved.maxBytes,
       maxSourceBytes: resolved.maxSourceBytes,
       instructionFileCandidates: resolved.instructionFileCandidates,
+      localInstructionFileCandidates: resolved.localInstructionFileCandidates,
       signal,
     }, fileSystem)
     const baseline = baselineInstructionState(instructions?.included ?? [])

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

@@ -4,7 +4,7 @@
  * @module @deepseek-ai/dsh-workspace-context/render
  */
 
-import { dirname } from 'node:path'
+import { basename, dirname } from 'node:path'
 import type { InstructionFile, LoadedInstructionFile } from './files.ts'
 
 const SYSTEM_REMINDER_OPEN = '<system-reminder>'
@@ -33,7 +33,6 @@ export interface WorkspaceInstructionChange {
   action: 'set' | 'replace' | 'remove'
   scope: string
   path: string
-  previousPath?: string
   digest?: string
 }
 
@@ -62,8 +61,8 @@ function truncateUtf8(value: string, maxBytes: number): string {
 
 function escapeInstructionContent(content: string): string {
   // TODO(instruction-frame-paths): apply the same delimiter neutralization to
-  // every interpolated path, scope, and previous path; repository-controlled
-  // names can otherwise close the plugin-owned system-reminder frame.
+  // every interpolated path and scope; repository-controlled names can
+  // otherwise close the plugin-owned system-reminder frame.
   return content.replaceAll(SYSTEM_REMINDER_CLOSE, '<\\/system-reminder>')
 }
 
@@ -71,16 +70,65 @@ function sectionText(file: LoadedInstructionFile): string {
   return `Instructions from: ${file.displayPath}\n\n${escapeInstructionContent(file.content)}`
 }
 
+/** Directory component that identifies the single user-global instruction scope. */
+export const USER_GLOBAL_DIRECTORY = 'user-global'
+
+/**
+ * File name of the single user-global instruction file under `$DSH_HOME`.
+ * Discovery (`$DSH_HOME/<name>`) and reconciliation (the user-global scope key's
+ * candidate component) both key on this name, so it lives in one place: were the
+ * two to disagree, the user-global instruction would load but never reconcile.
+ */
+export const USER_GLOBAL_FILE = 'AGENTS.md'
+
 /**
  * Derive the logical instruction scope from a model-facing path.
  * @param displayPath - project-relative or user-global instruction path.
  * @returns `user-global`, `.`, or the containing project-relative directory.
  */
 export function scopeForDisplayPath(displayPath: string): string {
-  if (displayPath === '~/.dsh/AGENTS.md' || displayPath === '$DSH_HOME/AGENTS.md') return 'user-global'
+  if (displayPath === '~/.dsh/AGENTS.md' || displayPath === '$DSH_HOME/AGENTS.md') return USER_GLOBAL_DIRECTORY
   return dirname(displayPath)
 }
 
+const SCOPE_SEPARATOR = '\u0000'
+
+/**
+ * Compose the reconciliation key for one instruction candidate file.
+ * Each loaded candidate is tracked independently, so the key pairs the logical
+ * directory with the exact candidate file name behind a NUL separator that no
+ * directory path or file name can contain. Distinct candidates in one directory
+ * (`AGENTS.md` vs `CLAUDE.md`, a base file vs its `.local` overlay) therefore
+ * never collide in the scope-keyed state maps.
+ * @param directory - `user-global`, `.`, or a project-relative directory.
+ * @param candidateName - instruction file name within that directory.
+ * @returns the per-candidate logical scope key.
+ */
+export function candidateScopeKey(directory: string, candidateName: string): string {
+  return `${directory}${SCOPE_SEPARATOR}${candidateName}`
+}
+
+/**
+ * Derive the per-candidate scope key for a loaded instruction file.
+ * @param displayPath - project-relative or user-global instruction path.
+ * @returns the scope key pairing the file's directory with its name.
+ */
+export function instructionScopeKey(displayPath: string): string {
+  return candidateScopeKey(scopeForDisplayPath(displayPath), basename(displayPath))
+}
+
+/**
+ * Recover the directory and candidate name that {@link candidateScopeKey} encoded.
+ * @param scope - a per-candidate scope key.
+ * @returns the directory scope and the candidate file name within it.
+ */
+export function decodeScopeKey(scope: string): { directory: string; candidateName: string } {
+  const separator = scope.indexOf(SCOPE_SEPARATOR)
+  /* v8 ignore next -- every scope key is produced by candidateScopeKey, which always inserts the separator. */
+  if (separator < 0) return { directory: scope, candidateName: '' }
+  return { directory: scope.slice(0, separator), candidateName: scope.slice(separator + 1) }
+}
+
 function additionalSectionText(file: LoadedInstructionFile): string {
   const scope = scopeForDisplayPath(file.displayPath)
   return [
@@ -100,13 +148,10 @@ function changedSectionText(item: ChangeRenderItem): string {
   if (change.action === 'remove') {
     return `Instructions removed: ${change.path}\n\nThe previously loaded instructions from this file no longer apply.`
   }
-  const description = change.previousPath === undefined
-    ? 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.'
-    : `The instructions previously loaded from \`${change.previousPath}\` no longer apply. Use the following content for \`${change.scope}\` instead.`
   return [
     `Updated instructions from: ${change.path}`,
     '',
-    description,
+    'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.',
     '',
     escapeInstructionContent(file.content),
   ].join('\n')

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

@@ -10,7 +10,7 @@ import type { JsonValue, Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { FileSystem, FsVersion } from '@deepseek-ai/dsh-fs'
 import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 import type { ResolvedConfig } from './config.ts'
-import { instructionContentSha1 } from './digest.ts'
+import { instructionContentSha1, trimmedInstructionDigest } from './digest.ts'
 import {
   ancestorChain,
   descendantDirsBetween,
@@ -21,8 +21,12 @@ import {
   type LoadedInstructionFile,
 } from './files.ts'
 import {
+  candidateScopeKey,
+  decodeScopeKey,
+  instructionScopeKey,
   renderInstructionChanges,
-  scopeForDisplayPath,
+  USER_GLOBAL_DIRECTORY,
+  USER_GLOBAL_FILE,
   type ChangeRenderItem,
   type WorkspaceInstructionChange,
 } from './render.ts'
@@ -44,6 +48,11 @@ export interface InstructionVersionState {
   path: string
   version: FsVersion
   digest: string
+  /**
+   * Trimmed-content identity ({@link trimmedInstructionDigest}) used to suppress
+   * per-directory duplicates on the metadata fast path without re-reading a sibling.
+   */
+  trimmedDigest: string
 }
 
 /** Session-isolated fast-path state keyed by logical instruction scope. */
@@ -71,7 +80,6 @@ function workspaceContextHook(text: string, changes: WorkspaceInstructionChange[
     action: change.action,
     scope: change.scope,
     path: change.path,
-    ...change.previousPath !== undefined ? { previousPath: change.previousPath } : {},
     ...change.digest !== undefined ? { digest: change.digest } : {},
   }))
   const meta: JsonValue = { kind: 'workspace-instructions', version: 1, changes: serializedChanges }
@@ -112,13 +120,11 @@ function workspaceInstructionChanges(meta: JsonValue | undefined): WorkspaceInst
     if (!isRecord(value)) continue
     if (value.action !== 'set' && value.action !== 'replace' && value.action !== 'remove') continue
     if (typeof value.scope !== 'string' || typeof value.path !== 'string') continue
-    if (value.previousPath !== undefined && typeof value.previousPath !== 'string') continue
     if (value.digest !== undefined && typeof value.digest !== 'string') continue
     changes.push({
       action: value.action,
       scope: value.scope,
       path: value.path,
-      ...value.previousPath !== undefined ? { previousPath: value.previousPath } : {},
       ...value.digest !== undefined ? { digest: value.digest } : {},
     })
   }
@@ -129,7 +135,6 @@ function sameInstructionChange(a: WorkspaceInstructionChange, b: WorkspaceInstru
   return a.action === b.action
     && a.scope === b.scope
     && a.path === b.path
-    && a.previousPath === b.previousPath
     && a.digest === b.digest
 }
 
@@ -169,13 +174,18 @@ export function baselineInstructionState(files: LoadedInstructionFile[]): {
     const digest = instructionContentSha1(file.content)
     const change: WorkspaceInstructionChange = {
       action: 'set',
-      scope: scopeForDisplayPath(file.displayPath),
+      scope: instructionScopeKey(file.displayPath),
       path: file.displayPath,
       digest,
     }
     changes.set(change.scope, change)
     if (file.version !== undefined) {
-      versions.set(change.scope, { path: file.displayPath, version: file.version, digest })
+      versions.set(change.scope, {
+        path: file.displayPath,
+        version: file.version,
+        digest,
+        trimmedDigest: trimmedInstructionDigest(file.content),
+      })
     }
   }
   return { changes, versions }
@@ -391,34 +401,67 @@ export async function reconcileInstructionContext(
   // recomputing it after marker edits reinterprets the existing relative scope keys.
   const projectRoot = await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, options.signal)
   const scopes = new Set<string>()
-  if (options.includeBaselineScopes) {
-    scopes.add('user-global')
-    for (const dir of ancestorChain(projectRoot, cwd)) scopes.add(relativeScope(projectRoot, dir))
+  const addDirScopes = (directory: string): void => {
+    for (const candidate of resolved.instructionFileCandidates) scopes.add(candidateScopeKey(directory, candidate))
+    for (const candidate of resolved.localInstructionFileCandidates) scopes.add(candidateScopeKey(directory, candidate))
+  }
+  const addProjectScopes = (dir: string): void => {
+    addDirScopes(relativeScope(projectRoot, dir))
+  }
+  if (options.includeBaselineScopes) {
+    scopes.add(candidateScopeKey(USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE))
+    for (const dir of ancestorChain(projectRoot, cwd)) addProjectScopes(dir)
+  }
+  for (const scope of effective.keys()) {
+    const { directory } = decodeScopeKey(scope)
+    if (directory === USER_GLOBAL_DIRECTORY) scopes.add(candidateScopeKey(USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE))
+    else addDirScopes(directory)
   }
-  for (const scope of effective.keys()) scopes.add(scope)
   if (options.touchedPath !== undefined) {
-    for (const dir of descendantDirsBetween(cwd, options.touchedPath)) scopes.add(relativeScope(projectRoot, dir))
+    for (const dir of descendantDirsBetween(cwd, options.touchedPath)) addProjectScopes(dir)
   }
 
   const versions = versionStatesFor(session, versionCache)
   const seenAbsolutePaths = new Set<string>()
+  // Per-directory trimmed-content identities kept so far this pass, iterated in
+  // candidate order (base before local); a later sibling matching an earlier one
+  // is a duplicate and is dropped or removed rather than rendered twice.
+  const keptTrimmedByDir = new Map<string, Set<string>>()
+  const registerKeptTrimmed = (directory: string, digest: string): boolean => {
+    let digests = keptTrimmedByDir.get(directory)
+    if (digests === undefined) {
+      digests = new Set()
+      keptTrimmedByDir.set(directory, digests)
+    }
+    if (digests.has(digest)) return true
+    digests.add(digest)
+    return false
+  }
   const items: ChangeRenderItem[] = []
   const versionUpdates: InstructionVersionUpdate[] = []
+  const pushRemoval = (scope: string, path: string): void => {
+    const change: WorkspaceInstructionChange = { action: 'remove', scope, path }
+    items.push({ change, file: { absolutePath: `removed:${scope}`, displayPath: path, content: '' } })
+    versionUpdates.push({ change })
+  }
   for (const scope of scopes) {
+    const { directory } = decodeScopeKey(scope)
     const previous = effective.get(scope)
     const probe = await probeScopeInstruction(scope, projectRoot, resolved, fileSystem, options.signal)
-    if (probe.kind === 'unavailable') continue
-    if (probe.kind === 'absent') {
-      if (previous === undefined || previous.action === 'remove') {
-        versions.delete(scope)
-        continue
+    if (probe.kind === 'unavailable') {
+      // Last-good-state: the candidate stays effective, so its cached trimmed
+      // digest must keep occupying the directory's dedup slot — otherwise an
+      // identical later sibling would be emitted as a duplicate `set` until the
+      // next successful reconciliation removed it again.
+      const cached = versions.get(scope)
+      if (cached !== undefined && previous !== undefined && previous.action !== 'remove') {
+        registerKeptTrimmed(directory, cached.trimmedDigest)
       }
-      const change: WorkspaceInstructionChange = { action: 'remove', scope, path: previous.path }
-      items.push({
-        change,
-        file: { absolutePath: `removed:${scope}`, displayPath: previous.path, content: '' },
-      })
-      versionUpdates.push({ change })
+      continue
+    }
+    if (probe.kind === 'absent') {
+      if (previous === undefined || previous.action === 'remove') versions.delete(scope)
+      else pushRemoval(scope, previous.path)
       continue
     }
     const { file: probedFile } = probe
@@ -433,29 +476,39 @@ export async function reconcileInstructionContext(
       && previous.action !== 'remove'
       && previous.path === cached.path
       && previous.digest === cached.digest
-    ) continue
+    ) {
+      // Unchanged and previously rendered: keep it, but an earlier sibling that
+      // now matches its trimmed content makes this the duplicate to remove.
+      if (registerKeptTrimmed(directory, cached.trimmedDigest)) pushRemoval(scope, previous.path)
+      continue
+    }
 
     const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal)
     if (file === undefined) continue
     const currentDigest = instructionContentSha1(file.content)
+    const trimmedDigest = trimmedInstructionDigest(file.content)
+    if (registerKeptTrimmed(directory, trimmedDigest)) {
+      // A distinct file whose trimmed content already appeared earlier in this
+      // directory: drop it, removing any copy that was previously rendered.
+      if (previous !== undefined && previous.action !== 'remove') pushRemoval(scope, previous.path)
+      else versions.delete(scope)
+      continue
+    }
     const nextVersion: InstructionVersionState = {
       path: file.displayPath,
       version: probedFile.version,
       digest: currentDigest,
+      trimmedDigest,
     }
     if (previous !== undefined && previous.action !== 'remove' && previous.path === file.displayPath && previous.digest === currentDigest) {
       versions.set(scope, nextVersion)
       continue
     }
     const action = previous === undefined || previous.action === 'remove' ? 'set' : 'replace'
-    const previousPath = action === 'replace' && previous !== undefined && previous.path !== file.displayPath
-      ? previous.path
-      : undefined
     const change: WorkspaceInstructionChange = {
       action,
       scope,
       path: file.displayPath,
-      ...previousPath === undefined ? {} : { previousPath },
       digest: currentDigest,
     }
     items.push({ change, file })

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

@@ -12,6 +12,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import * as WorkspaceContext from '@deepseek-ai/dsh-workspace-context'
+import { candidateScopeKey } from '../src/render.ts'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
@@ -112,7 +113,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real mode
       && !Array.isArray(event.data.meta)
       && event.data.meta.kind === 'workspace-instructions')
     expect(update?.type === 'context/message' && update.data.meta).toMatchObject({
-      changes: [{ action: 'replace', scope: '.', path: 'AGENTS.md' }],
+      changes: [{ action: 'replace', scope: candidateScopeKey('.', 'AGENTS.md'), path: 'AGENTS.md' }],
     })
     const updateText = update?.type === 'context/message'
       ? update.data.content.filter(block => block.type === 'text').map(block => block.text).join('')

packages/cordis/tool-cordis/README.md

@@ -14,7 +14,7 @@ Canonical successes are the inspection string, mount `{ id, pluginName, state, p
 
 ## Trust stance
 
-The sandbox isolates globals but is not a security boundary. Node globals are absent or redirect to Cordis services such as `ctx.fs`, `ctx.web`, and `ctx.bash`, and writes to `globalThis` stay local, but host-realm helpers make escape possible. Mounted plugins receive a façade without framework internals, yet its allowed services affect the live runtime. Treat this toolset like bash access; see the [design and trust stance](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+The sandbox isolates globals but is not a security boundary. Node globals are absent or redirect to Cordis services such as `ctx.fs`, `ctx.web`, and `ctx.bash`, and writes to `globalThis` stay local, but host-realm helpers make escape possible. Mounted plugins receive a façade without framework internals, yet its allowed services affect the live runtime. Dynamic tool schemas and annotations cross the realm through iterative JSON cloning and schema normalization, so valid deep declarations are memory-bounded rather than call-stack-bounded. Treat this toolset like bash access; see the [design and trust stance](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
 
 ## Config
 

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

@@ -372,6 +372,20 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'planMode',
+    summary: '`ctx.planMode`: owns logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool.',
+    methods: [
+      {
+        signature: 'get(agent: Agent): { active: boolean; pending?: boolean }',
+        jsDoc: '/**\n * Read the logged plan state and any selected state awaiting a boundary.\n *\n * @param agent The agent to read.\n * @returns Current logged state plus a pending selection, when present.\n */',
+      },
+      {
+        signature: 'set(agent: Agent, active: boolean): void',
+        jsDoc: '/**\n * Select whether plan mode should be active from the next turn boundary.\n * Repeated selection of the current or already-pending state is a no-op.\n *\n * @param agent The agent to switch.\n * @param active Whether plan mode should be active.\n */',
+      },
+    ],
+  },
   {
     key: 'sandbox',
     summary: 'Abstract process-sandbox service.',
@@ -1098,7 +1112,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'AskUserQuestionItem',
-    declaration: 'export interface AskUserQuestionItem {\n    id: string;\n    question: string;\n    header?: string;\n    options?: AskUserQuestionOption[];\n    multiSelect?: boolean;\n}',
+    declaration: 'export interface AskUserQuestionItem {\n    id: string;\n    question: string;\n    detail?: string;\n    header?: string;\n    options?: AskUserQuestionOption[];\n    multiSelect?: boolean;\n}',
   },
   {
     name: 'AskUserQuestionOption',

packages/cordis/tool-cordis/src/guard.ts

@@ -59,45 +59,105 @@ function hasPlainArrayPrototype(value: unknown[]): boolean {
 }
 /* jscpd:ignore-end */
 
+/** Where one cloned JSON value is installed. */
+type CloneDestination =
+  | { kind: 'root' }
+  | { kind: 'array'; target: unknown[]; index: number }
+  | { kind: 'object'; target: Record<string, unknown>; key: string }
+
+/** Deferred work for stack-safe cross-realm JSON cloning. */
+type CloneTask =
+  | { kind: 'visit'; value: unknown; path: string; destination: CloneDestination }
+  | { kind: 'array-item'; source: unknown[]; index: number; path: string; target: unknown[] }
+  | { kind: 'leave'; source: object }
+
 /** Materialize realm-foreign lossless JSON without allowing JSON.stringify coercions. */
-function cloneJson(value: unknown, path: string, seen = new Set<object>()): unknown {
-  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
-  if (typeof value === 'number') {
-    if (Number.isFinite(value) && !Object.is(value, -0)) return value
-    throw new Error(`harness.defineTool ${path} must be lossless JSON data`)
-  }
-  if (typeof value !== 'object') throw new Error(`harness.defineTool ${path} must be lossless JSON data`)
-  if (seen.has(value)) throw new Error(`harness.defineTool ${path} must be lossless JSON data`)
-  seen.add(value)
-  try {
-    if (Array.isArray(value)) {
-      if (!hasPlainArrayPrototype(value) || Reflect.ownKeys(value).length !== value.length + 1) {
-        throw new Error(`harness.defineTool ${path} must be lossless JSON data`)
-      }
-      const output: unknown[] = []
-      for (let index = 0; index < value.length; index++) {
-        if (!Object.hasOwn(value, index)) throw new Error(`harness.defineTool ${path} must be lossless JSON data`)
-        output.push(cloneJson(value[index], `${path}[${index}]`, seen))
-      }
-      return output
+function cloneJson(value: unknown, path: string): unknown {
+  const ancestors = new Set<object>()
+  let root: unknown
+  const assign = (destination: CloneDestination, item: unknown): void => {
+    if (destination.kind === 'root') {
+      root = item
+      return
     }
-    if (!isPlainRecord(value)) throw new Error(`harness.defineTool ${path} must be lossless JSON data`)
-    if (Reflect.ownKeys(value).some(key => typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(value, key))) {
-      throw new Error(`harness.defineTool ${path} must be lossless JSON data`)
+    if (destination.kind === 'array') {
+      destination.target[destination.index] = item
+      return
+    }
+    Object.defineProperty(destination.target, destination.key, {
+      value: item,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+  }
+  const reject = (at: string): never => {
+    throw new Error(`harness.defineTool ${at} must be lossless JSON data`)
+  }
+
+  const tasks: CloneTask[] = [{ kind: 'visit', value, path, destination: { kind: 'root' } }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      ancestors.delete(task.source)
+      continue
+    }
+    if (task.kind === 'array-item') {
+      if (!Object.hasOwn(task.source, task.index)) reject(task.path)
+      tasks.push({
+        kind: 'visit',
+        value: task.source[task.index],
+        path: `${task.path}[${task.index}]`,
+        destination: { kind: 'array', target: task.target, index: task.index },
+      })
+      continue
+    }
+
+    const current = task.value
+    if (current === null || typeof current === 'string' || typeof current === 'boolean') {
+      assign(task.destination, current)
+      continue
+    }
+    if (typeof current === 'number') {
+      if (!Number.isFinite(current) || Object.is(current, -0)) reject(task.path)
+      assign(task.destination, current)
+      continue
+    }
+    if (typeof current !== 'object' || ancestors.has(current)) reject(task.path)
+
+    if (Array.isArray(current)) {
+      if (!hasPlainArrayPrototype(current) || Reflect.ownKeys(current).length !== current.length + 1) reject(task.path)
+      const output: unknown[] = []
+      assign(task.destination, output)
+      ancestors.add(current)
+      tasks.push({ kind: 'leave', source: current })
+      for (let index = current.length - 1; index >= 0; index--) {
+        tasks.push({ kind: 'array-item', source: current, index, path: task.path, target: output })
+      }
+      continue
+    }
+    if (!isPlainRecord(current)) reject(task.path)
+    const record = current as Record<string, unknown>
+    if (Reflect.ownKeys(record).some(key => typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(record, key))) {
+      reject(task.path)
     }
     const output: Record<string, unknown> = {}
-    for (const [key, entry] of Object.entries(value)) {
-      Object.defineProperty(output, key, {
-        value: cloneJson(entry, `${path}.${key}`, seen),
-        enumerable: true,
-        configurable: true,
-        writable: true,
+    assign(task.destination, output)
+    ancestors.add(record)
+    tasks.push({ kind: 'leave', source: record })
+    const entries = Object.entries(record)
+    for (let index = entries.length - 1; index >= 0; index--) {
+      const entry = entries[index]
+      /* v8 ignore next -- the loop is bounded by the captured entry count. */
+      if (entry === undefined) continue
+      tasks.push({
+        kind: 'visit',
+        value: entry[1],
+        path: `${task.path}.${entry[0]}`,
+        destination: { kind: 'object', target: output, key: entry[0] },
       })
     }
-    return output
-  } finally {
-    seen.delete(value)
   }
+  return root
 }
 
 /** Copy and realm-materialize the shared annotation vocabulary. */
@@ -162,111 +222,229 @@ function normalizeRequiredNames(value: unknown, properties: Record<string, unkno
   return names
 }
 
-/** Normalize one implicit property map. */
+/** Mutable holder used only while one normalized property-map root is unresolved. */
+interface NormalizeRoot {
+  value?: Record<string, unknown>
+}
+
+/** Where a normalized value node is installed. */
+type NormalizeValueDestination =
+  | { kind: 'property'; target: Record<string, unknown>; key: string }
+  | { kind: 'item'; target: Record<string, unknown> }
+  | { kind: 'one-of'; target: Record<string, unknown>[]; index: number }
+
+/** Where a normalized property map is installed. */
+type NormalizeMapDestination =
+  | { kind: 'root'; holder: NormalizeRoot }
+  | { kind: 'properties'; target: Record<string, unknown> }
+
+/** Deferred work for stack-safe sandbox schema normalization. */
+type NormalizeTask =
+  | {
+    kind: 'map'
+    entries: Record<string, unknown>
+    path: string
+    requiredNames: ReadonlySet<string>
+    raw: boolean
+    destination: NormalizeMapDestination
+  }
+  | {
+    kind: 'value'
+    value: unknown
+    path: string
+    forceRequired: boolean
+    raw: boolean
+    parameterProperty: boolean
+    destination: NormalizeValueDestination
+  }
+  | { kind: 'leave'; value: object }
+
+/** Install one normalized node without `__proto__` assignment semantics. */
+function assignNormalizedValue(destination: NormalizeValueDestination, value: Record<string, unknown>): void {
+  if (destination.kind === 'property') {
+    Object.defineProperty(destination.target, destination.key, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+  } else if (destination.kind === 'item') {
+    destination.target.items = value
+  } else {
+    destination.target[destination.index] = value
+  }
+}
+
+/** Install one normalized property map at its root or containing object. */
+function assignNormalizedMap(destination: NormalizeMapDestination, value: Record<string, unknown>): void {
+  if (destination.kind === 'root') destination.holder.value = value
+  else destination.target.properties = value
+}
+
+/** Normalize one implicit property map and all descendants with explicit work frames. */
 function normalizePropertyMap(
   entries: Record<string, unknown>,
   path: string,
   requiredNames: ReadonlySet<string>,
   raw: boolean,
 ): Record<string, unknown> {
-  const spec: Record<string, unknown> = {}
-  for (const [key, prop] of Object.entries(entries)) {
-    Object.defineProperty(spec, key, {
-      value: normalizeValueSchema(prop, `${path}.${key}`, requiredNames.has(key), raw, true),
-      enumerable: true,
-      configurable: true,
-      writable: true,
-    })
-  }
-  return spec
-}
-
-/** Normalize one property or nested value schema into the host realm. */
-function normalizeValueSchema(
-  value: unknown,
-  path: string,
-  forceRequired = false,
-  raw = false,
-  parameterProperty = false,
-): Record<string, unknown> {
-  if (!isPlainRecord(value)) {
-    throw new Error(`harness.defineTool ${path} must be a ParameterSchemaSpec property object`)
-  }
-  const requiredKey = parameterProperty && !raw ? ['required'] : []
-  if (parameterProperty && raw && Object.hasOwn(value, 'required') && value.type !== 'object') {
-    throw new Error(`harness.defineTool ${path}.required belongs to the containing raw object schema`)
-  }
-  if (parameterProperty && !raw && Object.hasOwn(value, 'required') && value.required !== true) {
-    throw new Error(`harness.defineTool ${path}.required must be true when present`)
-  }
-  const prop: Record<string, unknown> = {}
-  if (forceRequired || value.required === true) prop.required = true
-  copyAnnotations(value, prop, path)
-
-  if (Object.hasOwn(value, 'oneOf')) {
-    assertSchemaKeys(value, path, ['oneOf', ...requiredKey, ...ANNOTATION_KEYS])
-    if (!Array.isArray(value.oneOf)) throw new Error(`harness.defineTool ${path}.oneOf must contain at least two schemas`)
-    prop.oneOf = value.oneOf.map((branch, index) => normalizeValueSchema(branch, `${path}.oneOf[${index}]`, false, raw))
-    return prop
-  }
-
-  if (raw && !Object.hasOwn(value, 'type')) {
-    assertSchemaKeys(value, path, ANNOTATION_KEYS)
-    prop.type = 'json'
-    return prop
-  }
-  if (!SCHEMA_TYPES.has(value.type) || raw && value.type === 'json') {
-    throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`)
-  }
-  const type = value.type
-  prop.type = type
-
-  switch (type) {
-    case 'object': {
-      assertSchemaKeys(value, path, ['type', 'properties', 'additionalProperties', ...requiredKey, ...(raw ? ['required'] : []), ...ANNOTATION_KEYS])
-      if (!raw && (!Object.hasOwn(value, 'additionalProperties') || typeof value.additionalProperties !== 'boolean')) {
-        throw new Error(`harness.defineTool ${path}.additionalProperties must be explicitly true or false`)
-      }
-      if (raw && Object.hasOwn(value, 'additionalProperties') && typeof value.additionalProperties !== 'boolean') {
-        throw new Error(`harness.defineTool ${path}.additionalProperties must be a boolean`)
-      }
-      if (raw && Object.hasOwn(value, 'required') && value.required === undefined) {
-        throw new Error(`harness.defineTool ${path}.required must be an array of declared property names`)
-      }
-      prop.additionalProperties = raw ? value.additionalProperties ?? true : value.additionalProperties
-      if (Object.hasOwn(value, 'properties')) {
-        if (!isPlainRecord(value.properties)) throw new Error(`harness.defineTool ${path}.properties must be an object of schemas`)
-        const nestedRequired = raw ? normalizeRequiredNames(value.required, value.properties, `${path}.required`) : new Set<string>()
-        prop.properties = normalizePropertyMap(value.properties, `${path}.properties`, nestedRequired, raw)
-      } else if (raw && value.required !== undefined) {
-        normalizeRequiredNames(value.required, {}, `${path}.required`)
-      }
-      return prop
+  const holder: NormalizeRoot = {}
+  const ancestors = new Set<object>()
+  const tasks: NormalizeTask[] = [{
+    kind: 'map',
+    entries,
+    path,
+    requiredNames,
+    raw,
+    destination: { kind: 'root', holder },
+  }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      ancestors.delete(task.value)
+      continue
     }
-    case 'array':
-      assertSchemaKeys(value, path, ['type', 'items', ...requiredKey, ...ANNOTATION_KEYS])
-      if (Object.hasOwn(value, 'items')) prop.items = normalizeValueSchema(value.items, `${path}.items`, false, raw)
-      return prop
-    case 'string':
-    case 'number':
-    case 'integer':
-    case 'boolean':
-    case 'null':
-      assertSchemaKeys(value, path, ['type', 'enum', 'const', ...requiredKey, ...ANNOTATION_KEYS])
-      if (Object.hasOwn(value, 'enum')) {
-        prop.enum = Array.isArray(value.enum)
-          ? value.enum.map((entry, index) => cloneJson(entry, `${path}.enum[${index}]`))
-          : value.enum
+    if (task.kind === 'map') {
+      if (ancestors.has(task.entries)) throw new Error(`harness.defineTool ${task.path} is circular`)
+      ancestors.add(task.entries)
+      const spec: Record<string, unknown> = {}
+      assignNormalizedMap(task.destination, spec)
+      tasks.push({ kind: 'leave', value: task.entries })
+      const mapEntries = Object.entries(task.entries)
+      for (let index = mapEntries.length - 1; index >= 0; index--) {
+        const entry = mapEntries[index]
+        /* v8 ignore next -- the loop is bounded by the captured entry count. */
+        if (entry === undefined) continue
+        tasks.push({
+          kind: 'value',
+          value: entry[1],
+          path: `${task.path}.${entry[0]}`,
+          forceRequired: task.requiredNames.has(entry[0]),
+          raw: task.raw,
+          parameterProperty: true,
+          destination: { kind: 'property', target: spec, key: entry[0] },
+        })
       }
-      if (Object.hasOwn(value, 'const')) prop.const = cloneJson(value.const, `${path}.const`)
-      return prop
-    case 'json':
-      assertSchemaKeys(value, path, ['type', ...requiredKey, ...ANNOTATION_KEYS])
-      return prop
-    /* v8 ignore next 2 -- SCHEMA_TYPES narrows this closed switch before dispatch. */
-    default:
-      throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES}`)
+      continue
+    }
+
+    const { value, path } = task
+    if (!isPlainRecord(value)) {
+      throw new Error(`harness.defineTool ${path} must be a ParameterSchemaSpec property object`)
+    }
+    if (ancestors.has(value)) throw new Error(`harness.defineTool ${path} is circular`)
+    ancestors.add(value)
+    const requiredKey = task.parameterProperty && !task.raw ? ['required'] : []
+    if (task.parameterProperty && task.raw && Object.hasOwn(value, 'required') && value.type !== 'object') {
+      throw new Error(`harness.defineTool ${path}.required belongs to the containing raw object schema`)
+    }
+    if (task.parameterProperty && !task.raw && Object.hasOwn(value, 'required') && value.required !== true) {
+      throw new Error(`harness.defineTool ${path}.required must be true when present`)
+    }
+    const prop: Record<string, unknown> = {}
+    assignNormalizedValue(task.destination, prop)
+    tasks.push({ kind: 'leave', value })
+    if (task.forceRequired || value.required === true) prop.required = true
+    copyAnnotations(value, prop, path)
+
+    if (Object.hasOwn(value, 'oneOf')) {
+      assertSchemaKeys(value, path, ['oneOf', ...requiredKey, ...ANNOTATION_KEYS])
+      if (!Array.isArray(value.oneOf)) throw new Error(`harness.defineTool ${path}.oneOf must contain at least two schemas`)
+      const oneOf: Record<string, unknown>[] = []
+      prop.oneOf = oneOf
+      for (let index = value.oneOf.length - 1; index >= 0; index--) {
+        tasks.push({
+          kind: 'value',
+          value: value.oneOf[index],
+          path: `${path}.oneOf[${index}]`,
+          forceRequired: false,
+          raw: task.raw,
+          parameterProperty: false,
+          destination: { kind: 'one-of', target: oneOf, index },
+        })
+      }
+      continue
+    }
+
+    if (task.raw && !Object.hasOwn(value, 'type')) {
+      assertSchemaKeys(value, path, ANNOTATION_KEYS)
+      prop.type = 'json'
+      continue
+    }
+    if (!SCHEMA_TYPES.has(value.type) || task.raw && value.type === 'json') {
+      throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`)
+    }
+    const type = value.type
+    prop.type = type
+
+    switch (type) {
+      case 'object': {
+        assertSchemaKeys(value, path, ['type', 'properties', 'additionalProperties', ...requiredKey, ...(task.raw ? ['required'] : []), ...ANNOTATION_KEYS])
+        if (!task.raw && (!Object.hasOwn(value, 'additionalProperties') || typeof value.additionalProperties !== 'boolean')) {
+          throw new Error(`harness.defineTool ${path}.additionalProperties must be explicitly true or false`)
+        }
+        if (task.raw && Object.hasOwn(value, 'additionalProperties') && typeof value.additionalProperties !== 'boolean') {
+          throw new Error(`harness.defineTool ${path}.additionalProperties must be a boolean`)
+        }
+        if (task.raw && Object.hasOwn(value, 'required') && value.required === undefined) {
+          throw new Error(`harness.defineTool ${path}.required must be an array of declared property names`)
+        }
+        prop.additionalProperties = task.raw ? value.additionalProperties ?? true : value.additionalProperties
+        if (Object.hasOwn(value, 'properties')) {
+          const properties = value.properties
+          if (!isPlainRecord(properties)) throw new Error(`harness.defineTool ${path}.properties must be an object of schemas`)
+          const nestedRequired = task.raw
+            ? normalizeRequiredNames(value.required, properties, `${path}.required`)
+            : new Set<string>()
+          tasks.push({
+            kind: 'map',
+            entries: properties,
+            path: `${path}.properties`,
+            requiredNames: nestedRequired,
+            raw: task.raw,
+            destination: { kind: 'properties', target: prop },
+          })
+        } else if (task.raw && value.required !== undefined) {
+          normalizeRequiredNames(value.required, {}, `${path}.required`)
+        }
+        break
+      }
+      case 'array':
+        assertSchemaKeys(value, path, ['type', 'items', ...requiredKey, ...ANNOTATION_KEYS])
+        if (Object.hasOwn(value, 'items')) {
+          tasks.push({
+            kind: 'value',
+            value: value.items,
+            path: `${path}.items`,
+            forceRequired: false,
+            raw: task.raw,
+            parameterProperty: false,
+            destination: { kind: 'item', target: prop },
+          })
+        }
+        break
+      case 'string':
+      case 'number':
+      case 'integer':
+      case 'boolean':
+      case 'null':
+        assertSchemaKeys(value, path, ['type', 'enum', 'const', ...requiredKey, ...ANNOTATION_KEYS])
+        if (Object.hasOwn(value, 'enum')) {
+          prop.enum = Array.isArray(value.enum)
+            ? Array.from(value.enum, (entry, index) => cloneJson(entry, `${path}.enum[${index}]`))
+            : value.enum
+        }
+        if (Object.hasOwn(value, 'const')) prop.const = cloneJson(value.const, `${path}.const`)
+        break
+      case 'json':
+        assertSchemaKeys(value, path, ['type', ...requiredKey, ...ANNOTATION_KEYS])
+        break
+      /* v8 ignore next 2 -- SCHEMA_TYPES narrows this closed switch before dispatch. */
+      default:
+        throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES}`)
+    }
   }
+  /* v8 ignore next -- the root map task assigns before scheduling descendants. */
+  return holder.value ?? {}
 }
 
 function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition {
@@ -342,7 +520,7 @@ export function sandboxDefineTool(options: unknown): ToolDefinition {
     throw new Error('harness.defineTool output.presentationMeta must be a function when present')
   }
   if (typeof options.execute !== 'function') throw new Error('harness.defineTool execute must be a function')
-  const schema = normalizeValueSchema(output.schema, 'output.schema')
+  const schema = cloneJson(output.schema, 'output.schema')
   const rawExecute = options.execute as (args: unknown, exec: unknown) => Promise<unknown>
   const rawRender = output.render as (args: unknown, value: unknown) => unknown
   const rawPresentationMeta = output.presentationMeta as ((args: unknown, value: unknown) => unknown) | undefined

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

@@ -321,6 +321,60 @@ describe('cordis_mount', () => {
     })
   })
 
+  it('normalizes and snapshots deeply nested sandbox schemas and annotations stack-safely', async () => {
+    const ctx = await setup()
+    const depth = 5_000
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'deep-unified-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            let choice = { type: 'string' }
+            let example = 'leaf'
+            for (let index = 0; index < ${depth}; index++) {
+              choice = { oneOf: [choice, { type: 'null' }] }
+              example = [example]
+            }
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'deep_unified_schema_tool',
+              description: 'deep unified nodes',
+              parameters: {
+                choice: { ...choice, required: true },
+                any: { type: 'json', default: example },
+              },
+              ${CONTENT_OUTPUT_CODE}
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+
+    const parameters = ctx.tools.schemas().find(s => s.name === 'deep_unified_schema_tool')!.parameters as {
+      properties: Record<string, Record<string, unknown>>
+    }
+    let choice = parameters.properties.choice!
+    let choiceDepth = 0
+    while (Array.isArray(choice.oneOf)) {
+      choice = choice.oneOf[0] as Record<string, unknown>
+      choiceDepth++
+    }
+    let example: unknown = parameters.properties.any!.default
+    let exampleDepth = 0
+    while (Array.isArray(example)) {
+      example = example[0]
+      exampleDepth++
+    }
+    expect({ choiceDepth, choice, exampleDepth, example }).toEqual({
+      choiceDepth: depth,
+      choice: { type: 'string' },
+      exampleDepth: depth,
+      example: 'leaf',
+    })
+  })
+
   it('normalizes unconstrained and closed nested nodes from a raw JSON Schema wrapper', async () => {
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', {
@@ -421,6 +475,47 @@ describe('cordis_mount', () => {
     expect(text(result)).toContain(message)
   })
 
+  it.each([
+    [
+      `
+        const parameters = {}
+        const item = { type: 'array' }
+        item.items = item
+        parameters.item = item
+      `,
+      'parameters.item.items is circular',
+    ],
+    [
+      `
+        const parameters = {}
+        const item = { type: 'object', additionalProperties: true, properties: parameters }
+        parameters.item = item
+      `,
+      'parameters.item.properties is circular',
+    ],
+  ])('rejects circular sandbox schemas without exhausting the call stack', async (declaration, message) => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'circular-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            ${declaration}
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'circular_schema_tool',
+              description: 'circular',
+              parameters,
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain(message)
+  })
+
   it('preserves literal __proto__ keys in sandbox schemas and annotations', async () => {
     const ctx = await setup()
     const result = await call(ctx, 'cordis_mount', {

packages/core/tools/README.md

@@ -87,7 +87,7 @@ ctx.tools.register(defineTool({
 }))
 ```
 
-The unified schema DSL uses `ParameterSchemaSpec` for the implicit open parameter object and `ValueSchemaSpec` for any JSON-value root. It supports `string`, `number`, `integer`, `boolean`, `null`, `array`, `object`, author-only `json`, and exact-one `oneOf`; scalar `enum`/`const` values are type-correct. Every explicit DSL object declares `additionalProperties: true | false`, while the implicit parameter root and raw JSON Schema keep the standard open default.
+The unified schema DSL uses `ParameterSchemaSpec` for the implicit open parameter object and `ValueSchemaSpec` for any JSON-value root. It supports `string`, `number`, `integer`, `boolean`, `null`, `array`, `object`, author-only `json`, and exact-one `oneOf`; scalar `enum`/`const` values are type-correct. Every explicit DSL object declares `additionalProperties: true | false`, while the implicit parameter root and raw JSON Schema keep the standard open default. Compilation, validation, registry detachment, and schema-to-TypeScript rendering use explicit work stacks, so valid deep schemas are memory-bounded rather than call-stack-bounded.
 
 A `defineTool` definition validates model arguments before execution and turns missing required values, wrong primitives, invalid enum members, and nested violations into `ToolArgsError` (`INVALID_ARGS`) for the normal error-result path. It also infers the body return and pure output projectors from `output.schema`; the registry snapshots and validates the returned lossless JSON before presentation. The implicit parameter root is open; an explicit object accepts extra keys only with `additionalProperties: true`, and a closed object with no declared properties accepts only `{}`. Raw JSON Schema objects remain open unless they explicitly set `additionalProperties: false`. Defaults are not applied; open objects without `properties` and arrays without `items` receive only a container type check. Raw-registered tools own input validation but still declare and receive registry-enforced output.
 

packages/core/tools/src/index.ts

@@ -862,10 +862,14 @@ export class ToolRegistry extends Service {
   /** Project one definition onto the model-facing schema fields. */
   private schemaOf(definition: ToolDefinition, detachParameters: boolean): ToolSchema {
     const { name, description, parameters } = definition
+    const detached = detachParameters ? snapshotJsonValue(parameters) : parameters
+    if (detached === undefined) {
+      throw new Error(`tool "${name}" parameters must be lossless JSON before schema projection`)
+    }
     return {
       name,
       description,
-      parameters: detachParameters ? structuredClone(parameters) : parameters,
+      parameters: detached,
     }
   }
 

packages/core/tools/src/json-schema.ts

@@ -116,18 +116,70 @@ function scalarMatches(type: JsonSchemaScalarType, value: unknown): value is Jso
   }
 }
 
-/** Collect every violation for one raw schema node. */
-function checkSchemaNode(node: unknown, path: string, violations: string[], seen: Set<object>): void {
-  if (!isPlainJsonRecord(node)) {
-    violations.push(`${path} must be a schema object`)
-    return
+/** Deferred work for the stack-safe raw-schema walk. */
+type SchemaWalkTask =
+  | { kind: 'enter'; node: unknown; path: string }
+  | { kind: 'leave'; node: object }
+  | { kind: 'one-of-tail'; node: Record<string, unknown>; path: string }
+  | { kind: 'object-tail'; node: Record<string, unknown>; path: string; properties: unknown }
+
+/** Keywords that are invalid beside `oneOf`. */
+const ONE_OF_SIBLING_KEYWORDS = ['properties', 'required', 'additionalProperties', 'items', 'enum', 'const'] as const
+
+/** Validate object-only fields after its property schemas have been visited. */
+function checkObjectSchemaTail(
+  node: Record<string, unknown>,
+  path: string,
+  properties: unknown,
+  violations: string[],
+): void {
+  const required = node.required
+  if (Object.hasOwn(node, 'required')) {
+    if (!Array.isArray(required) || required.some(entry => typeof entry !== 'string')) {
+      violations.push(`${path}.required must be an array of strings`)
+    } else {
+      const declared = isPlainJsonRecord(properties) ? properties : {}
+      for (const key of required as string[]) {
+        if (!Object.hasOwn(declared, key)) violations.push(`${path}.required names "${key}" which is not in properties`)
+      }
+    }
   }
-  if (seen.has(node)) {
-    violations.push(`${path} is circular`)
-    return
+  if (Object.hasOwn(node, 'additionalProperties') && typeof node.additionalProperties !== 'boolean') {
+    violations.push(`${path}.additionalProperties must be a boolean`)
   }
-  seen.add(node)
-  try {
+}
+
+/** Collect every violation for one raw schema tree without using the JavaScript call stack. */
+function checkSchemaNode(root: unknown, rootPath: string, violations: string[], seen: Set<object>): void {
+  const tasks: SchemaWalkTask[] = [{ kind: 'enter', node: root, path: rootPath }]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      seen.delete(task.node)
+      continue
+    }
+    if (task.kind === 'one-of-tail') {
+      for (const key of ONE_OF_SIBLING_KEYWORDS) {
+        if (Object.hasOwn(task.node, key)) violations.push(`${task.path}.${key} is not supported beside oneOf`)
+      }
+      continue
+    }
+    if (task.kind === 'object-tail') {
+      checkObjectSchemaTail(task.node, task.path, task.properties, violations)
+      continue
+    }
+
+    const { node, path } = task
+    if (!isPlainJsonRecord(node)) {
+      violations.push(`${path} must be a schema object`)
+      continue
+    }
+    if (seen.has(node)) {
+      violations.push(`${path} is circular`)
+      continue
+    }
+    seen.add(node)
+    tasks.push({ kind: 'leave', node })
+
     for (const key of Object.keys(node)) {
       if (CONSTRAINT_KEYWORDS.has(key)) continue
       if (ANNOTATION_KEYWORDS.has(key)) {
@@ -151,28 +203,26 @@ function checkSchemaNode(node: unknown, path: string, violations: string[], seen
     const hasOneOf = Object.hasOwn(node, 'oneOf')
     if (hasType && hasOneOf) {
       violations.push(`${path} cannot declare both type and oneOf`)
-      return
+      continue
     }
     if (!hasType && !hasOneOf) {
-      for (const key of ['properties', 'required', 'additionalProperties', 'items', 'enum', 'const']) {
+      for (const key of ONE_OF_SIBLING_KEYWORDS) {
         if (Object.hasOwn(node, key)) violations.push(`${path}.${key} requires type or oneOf`)
       }
-      return
+      continue
     }
 
     if (hasOneOf) {
       const oneOf = node.oneOf
+      tasks.push({ kind: 'one-of-tail', node, path })
       if (!Array.isArray(oneOf) || oneOf.length < 2) {
         violations.push(`${path}.oneOf must be an array of at least two schemas`)
       } else {
-        for (let index = 0; index < oneOf.length; index++) {
-          checkSchemaNode(oneOf[index], `${path}.oneOf[${index}]`, violations, seen)
+        for (let index = oneOf.length - 1; index >= 0; index--) {
+          tasks.push({ kind: 'enter', node: oneOf[index], path: `${path}.oneOf[${index}]` })
         }
       }
-      for (const key of ['properties', 'required', 'additionalProperties', 'items', 'enum', 'const']) {
-        if (Object.hasOwn(node, key)) violations.push(`${path}.${key} is not supported beside oneOf`)
-      }
-      return
+      continue
     }
 
     const type = node.type
@@ -180,7 +230,7 @@ function checkSchemaNode(node: unknown, path: string, violations: string[], seen
       violations.push(Array.isArray(type)
         ? `${path}.type must be a single type string (type arrays are not supported)`
         : `${path}.type must be one of ${SCHEMA_TYPES.join('/')}`)
-      return
+      continue
     }
     const schemaType = type as JsonSchemaType
     const allowedFor: Record<string, JsonSchemaType[]> = {
@@ -200,33 +250,24 @@ function checkSchemaNode(node: unknown, path: string, violations: string[], seen
     switch (schemaType) {
       case 'object': {
         const properties = node.properties
+        tasks.push({ kind: 'object-tail', node, path, properties })
         if (Object.hasOwn(node, 'properties')) {
           if (!isPlainJsonRecord(properties)) {
             violations.push(`${path}.properties must be an object of schemas`)
           } else {
-            for (const [key, child] of Object.entries(properties)) {
-              checkSchemaNode(child, `${path}.properties.${key}`, violations, seen)
+            const entries = Object.entries(properties)
+            for (let index = entries.length - 1; index >= 0; index--) {
+              const entry = entries[index]
+              /* v8 ignore next -- the loop is bounded by the captured entry count. */
+              if (entry === undefined) continue
+              tasks.push({ kind: 'enter', node: entry[1], path: `${path}.properties.${entry[0]}` })
             }
           }
         }
-        const required = node.required
-        if (Object.hasOwn(node, 'required')) {
-          if (!Array.isArray(required) || required.some(entry => typeof entry !== 'string')) {
-            violations.push(`${path}.required must be an array of strings`)
-          } else {
-            const declared = isPlainJsonRecord(properties) ? properties : {}
-            for (const key of required as string[]) {
-              if (!Object.hasOwn(declared, key)) violations.push(`${path}.required names "${key}" which is not in properties`)
-            }
-          }
-        }
-        if (Object.hasOwn(node, 'additionalProperties') && typeof node.additionalProperties !== 'boolean') {
-          violations.push(`${path}.additionalProperties must be a boolean`)
-        }
         break
       }
       case 'array': {
-        if (Object.hasOwn(node, 'items')) checkSchemaNode(node.items, `${path}.items`, violations, seen)
+        if (Object.hasOwn(node, 'items')) tasks.push({ kind: 'enter', node: node.items, path: `${path}.items` })
         break
       }
       case 'string':
@@ -238,10 +279,8 @@ function checkSchemaNode(node: unknown, path: string, violations: string[], seen
         const enumValid = Array.isArray(allowed)
           && allowed.length > 0
           && allowed.every(entry => scalarMatches(schemaType, entry))
-        if (Object.hasOwn(node, 'enum')) {
-          if (!enumValid) {
-            violations.push(`${path}.enum must be a non-empty array of ${schemaType} values`)
-          }
+        if (Object.hasOwn(node, 'enum') && !enumValid) {
+          violations.push(`${path}.enum must be a non-empty array of ${schemaType} values`)
         }
         const constValid = scalarMatches(schemaType, node.const)
         if (Object.hasOwn(node, 'const')) {
@@ -256,8 +295,6 @@ function checkSchemaNode(node: unknown, path: string, violations: string[], seen
       /* v8 ignore next -- schemaType was narrowed from the closed SCHEMA_TYPES table above. */
       default: assertNever(schemaType, 'JsonSchemaType')
     }
-  } finally {
-    seen.delete(node)
   }
 }
 
@@ -308,81 +345,57 @@ function propertyPath(path: string, key: string): string {
   return path === '' ? key : `${path}.${key}`
 }
 
-/** Contain hostile getters/proxies so validation remains total for arbitrary values. */
-function checkValue(node: JsonSchemaNode, value: unknown, path: string): string[] {
-  if (node.type !== undefined && !(SCHEMA_TYPES as readonly unknown[]).includes(node.type)) {
-    return checkValueUnchecked(node, value, path)
-  }
-  try {
-    return checkValueUnchecked(node, value, path)
-  } catch {
-    return [`"${diagnosticPath(path)}" must be a lossless JSON value`]
+/** One child evaluation deferred by a container or exact-one union frame. */
+interface ValueChild {
+  readonly node: JsonSchemaNode
+  readonly value: unknown
+  readonly path: string
+}
+
+/** Explicit call frame for stack-safe schema-value validation. */
+interface ValueFrame {
+  readonly node: JsonSchemaNode
+  readonly value: unknown
+  readonly path: string
+  catches: boolean
+  phase: 'start' | 'children'
+  kind?: 'oneOf' | 'object' | 'array'
+  children: ValueChild[]
+  childIndex: number
+  violations: string[]
+  tailViolations: string[]
+  matches: number
+}
+
+/** The generic exception-containment diagnostic owned by one valid schema node. */
+function losslessValueViolation(path: string): string[] {
+  return [`"${diagnosticPath(path)}" must be a lossless JSON value`]
+}
+
+/** Append diagnostics without spreading a potentially wide child result as call arguments. */
+function appendViolations(target: string[], source: readonly string[]): void {
+  for (const violation of source) target.push(violation)
+}
+
+/** Initialize one validation frame with empty aggregation state. */
+function valueFrame(node: JsonSchemaNode, value: unknown, path: string): ValueFrame {
+  return {
+    node,
+    value,
+    path,
+    catches: false,
+    phase: 'start',
+    children: [],
+    childIndex: 0,
+    violations: [],
+    tailViolations: [],
+    matches: 0,
   }
 }
 
-/** Collect value violations for one trusted schema node after the exception boundary. */
-function checkValueUnchecked(node: JsonSchemaNode, value: unknown, path: string): string[] {
-  if (node.oneOf !== undefined) {
-    const matches = node.oneOf.filter(branch => checkValue(branch, value, path).length === 0).length
-    return matches === 1 ? [] : [`"${diagnosticPath(path)}" must match exactly one oneOf branch (matched ${matches})`]
-  }
-  if (node.type === undefined) {
-    return safelyIsJsonValue(value) ? [] : [`"${diagnosticPath(path)}" must be a lossless JSON value`]
-  }
-
-  switch (node.type) {
-    case 'object': {
-      if (!isPlainJsonRecord(value)) return [`"${diagnosticPath(path)}" must be an object`]
-      const violations: string[] = []
-      const properties = node.properties ?? {}
-      for (const key of node.required ?? []) {
-        if (!Object.hasOwn(value, key) || value[key] === undefined) violations.push(`missing required property "${propertyPath(path, key)}"`)
-      }
-      for (const [key, child] of Object.entries(properties)) {
-        if (!Object.hasOwn(value, key) || value[key] === undefined) continue
-        violations.push(...checkValue(child, value[key], propertyPath(path, key)))
-      }
-      if (node.additionalProperties === false) {
-        for (const key of Object.keys(value)) {
-          if (!Object.hasOwn(properties, key)) violations.push(`"${propertyPath(path, key)}" is not a declared property (additionalProperties: false)`)
-        }
-      }
-      if (violations.length > 0) return violations
-      return safelyIsJsonValue(value) ? [] : [`"${diagnosticPath(path)}" must be a lossless JSON object`]
-    }
-    case 'array': {
-      if (!Array.isArray(value)) return [`"${diagnosticPath(path)}" must be an array`]
-      const items = node.items
-      const violations = items === undefined
-        ? []
-        : value.flatMap((entry, index) => checkValue(items, entry, `${path}[${index}]`))
-      if (violations.length > 0) return violations
-      return safelyIsJsonValue(value) ? [] : [`"${diagnosticPath(path)}" must be a dense lossless JSON array`]
-    }
-    case 'string': {
-      if (typeof value !== 'string') return [`"${diagnosticPath(path)}" must be a string`]
-      break
-    }
-    case 'number': {
-      if (typeof value !== 'number') return [`"${diagnosticPath(path)}" must be a number`]
-      if (!isJsonNumber(value)) return [`"${diagnosticPath(path)}" must be a finite JSON number`]
-      break
-    }
-    case 'integer': {
-      if (!isJsonNumber(value) || !Number.isInteger(value)) return [`"${diagnosticPath(path)}" must be an integer`]
-      break
-    }
-    case 'boolean': {
-      if (typeof value !== 'boolean') return [`"${diagnosticPath(path)}" must be a boolean`]
-      break
-    }
-    case 'null': {
-      if (value !== null) return [`"${diagnosticPath(path)}" must be null`]
-      break
-    }
-    default: return assertNever(node.type, 'JsonSchemaType')
-  }
-  if (node.enum !== undefined && !node.enum.includes(value)) {
+/** Validate one scalar node after its primitive type check. */
+function checkScalarValue(node: JsonSchemaNode, value: unknown, path: string): string[] {
+  if (node.enum !== undefined && !node.enum.includes(value as JsonSchemaScalar)) {
     return [`"${diagnosticPath(path)}" must be one of ${JSON.stringify(node.enum)}`]
   }
   if (Object.hasOwn(node, 'const') && value !== node.const) {
@@ -391,6 +404,165 @@ function checkValueUnchecked(node: JsonSchemaNode, value: unknown, path: string)
   return []
 }
 
+/** Validate one trusted schema/value pair with explicit frames rather than recursive calls. */
+function checkValue(schema: JsonSchemaNode, value: unknown, path: string): string[] {
+  const frames: ValueFrame[] = [valueFrame(schema, value, path)]
+  let rootResult: string[] | undefined
+
+  const receive = (result: string[]): void => {
+    const parent = frames.at(-1)
+    if (parent === undefined) {
+      rootResult = result
+      return
+    }
+    if (parent.kind === 'oneOf') {
+      if (result.length === 0) parent.matches++
+    } else {
+      appendViolations(parent.violations, result)
+    }
+  }
+  const finish = (result: string[]): void => {
+    frames.pop()
+    receive(result)
+  }
+
+  while (frames.length > 0) {
+    const frame = frames.at(-1)
+    /* v8 ignore next -- the loop condition guarantees a current frame. */
+    if (frame === undefined) break
+    try {
+      if (frame.phase === 'children') {
+        if (frame.childIndex < frame.children.length) {
+          const child = frame.children[frame.childIndex]
+          /* v8 ignore next -- childIndex is bounded by children.length. */
+          if (child === undefined) throw new Error('missing schema-value child frame')
+          frame.childIndex++
+          frames.push(valueFrame(child.node, child.value, child.path))
+          continue
+        }
+        if (frame.kind === 'oneOf') {
+          finish(frame.matches === 1 ? [] : [`"${diagnosticPath(frame.path)}" must match exactly one oneOf branch (matched ${frame.matches})`])
+          continue
+        }
+        appendViolations(frame.violations, frame.tailViolations)
+        if (frame.violations.length > 0) {
+          finish(frame.violations)
+        } else if (frame.kind === 'object') {
+          finish(safelyIsJsonValue(frame.value) ? [] : [`"${diagnosticPath(frame.path)}" must be a lossless JSON object`])
+        } else {
+          finish(safelyIsJsonValue(frame.value) ? [] : [`"${diagnosticPath(frame.path)}" must be a dense lossless JSON array`])
+        }
+        continue
+      }
+
+      const nodeType = frame.node.type
+      frame.catches = !(nodeType !== undefined && !(SCHEMA_TYPES as readonly unknown[]).includes(nodeType))
+      const oneOf = frame.node.oneOf
+      if (oneOf !== undefined) {
+        frame.kind = 'oneOf'
+        frame.children = Array.from(oneOf, branch => ({ node: branch, value: frame.value, path: frame.path }))
+        frame.childIndex = 0
+        frame.matches = 0
+        frame.phase = 'children'
+        continue
+      }
+      if (nodeType === undefined) {
+        finish(safelyIsJsonValue(frame.value) ? [] : losslessValueViolation(frame.path))
+        continue
+      }
+
+      switch (nodeType) {
+        case 'object': {
+          if (!isPlainJsonRecord(frame.value)) {
+            finish([`"${diagnosticPath(frame.path)}" must be an object`])
+            break
+          }
+          const properties = frame.node.properties ?? {}
+          const violations: string[] = []
+          for (const key of frame.node.required ?? []) {
+            if (!Object.hasOwn(frame.value, key) || frame.value[key] === undefined) {
+              violations.push(`missing required property "${propertyPath(frame.path, key)}"`)
+            }
+          }
+          const children: ValueChild[] = []
+          for (const [key, child] of Object.entries(properties)) {
+            if (!Object.hasOwn(frame.value, key) || frame.value[key] === undefined) continue
+            children.push({ node: child, value: frame.value[key], path: propertyPath(frame.path, key) })
+          }
+          const tailViolations: string[] = []
+          if (frame.node.additionalProperties === false) {
+            for (const key of Object.keys(frame.value)) {
+              if (!Object.hasOwn(properties, key)) {
+                tailViolations.push(`"${propertyPath(frame.path, key)}" is not a declared property (additionalProperties: false)`)
+              }
+            }
+          }
+          frame.kind = 'object'
+          frame.children = children
+          frame.childIndex = 0
+          frame.violations = violations
+          frame.tailViolations = tailViolations
+          frame.phase = 'children'
+          break
+        }
+        case 'array': {
+          if (!Array.isArray(frame.value)) {
+            finish([`"${diagnosticPath(frame.path)}" must be an array`])
+            break
+          }
+          const items = frame.node.items
+          const children = items === undefined
+            ? []
+            : frame.value.flatMap((entry, index): ValueChild[] => [{ node: items, value: entry, path: `${frame.path}[${index}]` }])
+          frame.kind = 'array'
+          frame.children = children
+          frame.childIndex = 0
+          frame.violations = []
+          frame.phase = 'children'
+          break
+        }
+        case 'string':
+          finish(typeof frame.value === 'string'
+            ? checkScalarValue(frame.node, frame.value, frame.path)
+            : [`"${diagnosticPath(frame.path)}" must be a string`])
+          break
+        case 'number':
+          finish(typeof frame.value !== 'number'
+            ? [`"${diagnosticPath(frame.path)}" must be a number`]
+            : !isJsonNumber(frame.value)
+              ? [`"${diagnosticPath(frame.path)}" must be a finite JSON number`]
+              : checkScalarValue(frame.node, frame.value, frame.path))
+          break
+        case 'integer':
+          finish(!isJsonNumber(frame.value) || !Number.isInteger(frame.value)
+            ? [`"${diagnosticPath(frame.path)}" must be an integer`]
+            : checkScalarValue(frame.node, frame.value, frame.path))
+          break
+        case 'boolean':
+          finish(typeof frame.value === 'boolean'
+            ? checkScalarValue(frame.node, frame.value, frame.path)
+            : [`"${diagnosticPath(frame.path)}" must be a boolean`])
+          break
+        case 'null':
+          finish(frame.value === null
+            ? checkScalarValue(frame.node, frame.value, frame.path)
+            : [`"${diagnosticPath(frame.path)}" must be null`])
+          break
+        default:
+          finish(assertNever(nodeType, 'JsonSchemaType'))
+      }
+    } catch (error) {
+      let failed = frames.pop()
+      while (failed !== undefined && !failed.catches) failed = frames.pop()
+      if (failed === undefined) throw error
+      receive(losslessValueViolation(failed.path))
+    }
+  }
+
+  /* v8 ignore next -- every root frame finishes or throws. */
+  return rootResult ?? losslessValueViolation(path)
+}
+
 /**
  * Validate a candidate value against an asserted raw schema. The function is
  * total for arbitrary values and returns path-qualified violations.

packages/core/tools/src/schema.ts

@@ -186,66 +186,172 @@ function assertAuthorKeys(source: Record<string, unknown>, path: string, allowed
   }
 }
 
-/** Compile one implicit property map, collecting per-property requiredness. */
-function compilePropertyMap(
-  input: unknown,
-  path: string,
-  seen: Set<object>,
-): { properties: Record<string, JsonSchemaNode>; required?: string[] } {
-  if (!isPlainJsonRecord(input)) authorError(`${path} must be an object of value schemas`)
-  if (seen.has(input)) authorError(`${path} is circular`)
-  seen.add(input)
-  try {
-    const properties: Record<string, JsonSchemaNode> = {}
-    const required: string[] = []
-    for (const [key, property] of Object.entries(input)) {
-      if (!isPlainJsonRecord(property)) authorError(`${path}.${key} must be a value schema object`)
-      if (Object.hasOwn(property, 'required') && property.required !== true) {
-        authorError(`${path}.${key}.required must be true when present`)
-      }
-      Object.defineProperty(properties, key, {
-        value: compileValueSchema(property, `${path}.${key}`, seen, true),
+/** Compiled form of one implicit property map. */
+interface CompiledPropertyMap {
+  properties: Record<string, JsonSchemaNode>
+  required?: string[]
+}
+
+/** Mutable holder used only while an iterative compilation root is unresolved. */
+interface CompileRoot<T> {
+  value?: T
+}
+
+/** Where one compiled value node is installed. */
+type NodeDestination =
+  | { kind: 'root'; holder: CompileRoot<JsonSchemaNode> }
+  | { kind: 'property'; target: Record<string, JsonSchemaNode>; key: string }
+  | { kind: 'item'; target: JsonSchemaNode }
+  | { kind: 'one-of'; target: JsonSchemaNode[]; index: number }
+
+/** Where one compiled property map is installed. */
+type PropertyMapDestination =
+  | { kind: 'root'; holder: CompileRoot<CompiledPropertyMap> }
+  | { kind: 'object'; target: JsonSchemaNode }
+
+/** Deferred work for stack-safe author-schema compilation. */
+type CompileTask =
+  | { kind: 'value'; input: unknown; path: string; allowRequired: boolean; destination: NodeDestination }
+  | { kind: 'property-map'; input: unknown; path: string; destination: PropertyMapDestination }
+  | {
+    kind: 'property'
+    property: unknown
+    path: string
+    key: string
+    properties: Record<string, JsonSchemaNode>
+    required: string[]
+  }
+  | {
+    kind: 'property-map-tail'
+    compiled: CompiledPropertyMap
+    required: string[]
+    destination: PropertyMapDestination
+  }
+  | { kind: 'leave'; input: object }
+
+/** Install a compiled node without giving `__proto__` assignment semantics. */
+function assignCompiledNode(destination: NodeDestination, node: JsonSchemaNode): void {
+  switch (destination.kind) {
+    case 'root':
+      destination.holder.value = node
+      break
+    case 'property':
+      Object.defineProperty(destination.target, destination.key, {
+        value: node,
         enumerable: true,
         configurable: true,
         writable: true,
       })
-      if (property.required === true) required.push(key)
-    }
-    return required.length > 0 ? { properties, required } : { properties }
-  } finally {
-    seen.delete(input)
+      break
+    case 'item':
+      destination.target.items = node
+      break
+    case 'one-of':
+      destination.target[destination.index] = node
+      break
   }
 }
 
-/** Compile one author node without applying any consumer root restriction. */
-function compileValueSchema(
-  input: unknown,
-  path: string,
-  seen: Set<object>,
-  allowRequired = false,
-): JsonSchemaNode {
-  if (!isPlainJsonRecord(input)) authorError(`${path} must be a value schema object`)
-  if (seen.has(input)) authorError(`${path} is circular`)
-  seen.add(input)
-  try {
-    const authorKeys = [...ANNOTATION_KEYS, ...(allowRequired ? ['required'] : [])]
+/** Install a compiled property map at its root or containing object node. */
+function assignCompiledPropertyMap(destination: PropertyMapDestination, compiled: CompiledPropertyMap): void {
+  if (destination.kind === 'root') {
+    destination.holder.value = compiled
+  } else {
+    destination.target.properties = compiled.properties
+  }
+}
+
+/** Execute an author-schema compilation task graph without recursive descent. */
+function runSchemaCompiler(initial: CompileTask): void {
+  const seen = new Set<object>()
+  const tasks: CompileTask[] = [initial]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      seen.delete(task.input)
+      continue
+    }
+    if (task.kind === 'property-map-tail') {
+      if (task.required.length > 0) {
+        task.compiled.required = task.required
+        if (task.destination.kind === 'object') task.destination.target.required = task.required
+      }
+      continue
+    }
+    if (task.kind === 'property') {
+      if (!isPlainJsonRecord(task.property)) authorError(`${task.path} must be a value schema object`)
+      if (Object.hasOwn(task.property, 'required') && task.property.required !== true) {
+        authorError(`${task.path}.required must be true when present`)
+      }
+      if (task.property.required === true) task.required.push(task.key)
+      tasks.push({
+        kind: 'value',
+        input: task.property,
+        path: task.path,
+        allowRequired: true,
+        destination: { kind: 'property', target: task.properties, key: task.key },
+      })
+      continue
+    }
+    if (task.kind === 'property-map') {
+      if (!isPlainJsonRecord(task.input)) authorError(`${task.path} must be an object of value schemas`)
+      if (seen.has(task.input)) authorError(`${task.path} is circular`)
+      seen.add(task.input)
+      const compiled: CompiledPropertyMap = { properties: {} }
+      const required: string[] = []
+      assignCompiledPropertyMap(task.destination, compiled)
+      tasks.push({ kind: 'leave', input: task.input })
+      tasks.push({ kind: 'property-map-tail', compiled, required, destination: task.destination })
+      const entries = Object.entries(task.input)
+      for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index]
+        /* v8 ignore next -- the loop is bounded by the captured entry count. */
+        if (entry === undefined) continue
+        tasks.push({
+          kind: 'property',
+          property: entry[1],
+          path: `${task.path}.${entry[0]}`,
+          key: entry[0],
+          properties: compiled.properties,
+          required,
+        })
+      }
+      continue
+    }
+
+    const { input, path } = task
+    if (!isPlainJsonRecord(input)) authorError(`${path} must be a value schema object`)
+    if (seen.has(input)) authorError(`${path} is circular`)
+    seen.add(input)
+    const authorKeys = [...ANNOTATION_KEYS, ...(task.allowRequired ? ['required'] : [])]
     const node: JsonSchemaNode = {}
+    assignCompiledNode(task.destination, node)
+    tasks.push({ kind: 'leave', input })
 
     if (Object.hasOwn(input, 'oneOf')) {
       assertAuthorKeys(input, path, [...authorKeys, 'oneOf', 'type'])
       if (Object.hasOwn(input, 'type')) authorError(`${path} cannot declare both type and oneOf`)
       if (!Array.isArray(input.oneOf)) authorError(`${path}.oneOf must be an array of at least two value schemas`)
-      node.oneOf = input.oneOf.map((branch, index) => compileValueSchema(branch, `${path}.oneOf[${index}]`, seen))
+      const branches: JsonSchemaNode[] = []
+      node.oneOf = branches
       copyAnnotations(input, node)
-      return node
+      for (let index = input.oneOf.length - 1; index >= 0; index--) {
+        tasks.push({
+          kind: 'value',
+          input: input.oneOf[index],
+          path: `${path}.oneOf[${index}]`,
+          allowRequired: false,
+          destination: { kind: 'one-of', target: branches, index },
+        })
+      }
+      continue
     }
 
     switch (input.type) {
       case 'json':
         assertAuthorKeys(input, path, [...authorKeys, 'type'])
         copyAnnotations(input, node)
-        return node
-      case 'object': {
+        break
+      case 'object':
         assertAuthorKeys(input, path, [...authorKeys, 'type', 'properties', 'additionalProperties'])
         if (!Object.hasOwn(input, 'additionalProperties') || typeof input.additionalProperties !== 'boolean') {
           authorError(`${path}.additionalProperties must be explicitly true or false`)
@@ -254,18 +360,28 @@ function compileValueSchema(
         copyAnnotations(input, node)
         node.additionalProperties = input.additionalProperties
         if (Object.hasOwn(input, 'properties')) {
-          const compiled = compilePropertyMap(input.properties, `${path}.properties`, seen)
-          node.properties = compiled.properties
-          if (compiled.required !== undefined) node.required = compiled.required
+          tasks.push({
+            kind: 'property-map',
+            input: input.properties,
+            path: `${path}.properties`,
+            destination: { kind: 'object', target: node },
+          })
         }
-        return node
-      }
+        break
       case 'array':
         assertAuthorKeys(input, path, [...authorKeys, 'type', 'items'])
         node.type = 'array'
         copyAnnotations(input, node)
-        if (Object.hasOwn(input, 'items')) node.items = compileValueSchema(input.items, `${path}.items`, seen)
-        return node
+        if (Object.hasOwn(input, 'items')) {
+          tasks.push({
+            kind: 'value',
+            input: input.items,
+            path: `${path}.items`,
+            allowRequired: false,
+            destination: { kind: 'item', target: node },
+          })
+        }
+        break
       case 'string':
       case 'number':
       case 'integer':
@@ -280,15 +396,29 @@ function compileValueSchema(
             : input.enum as JsonSchemaScalar[]
         }
         if (Object.hasOwn(input, 'const')) node.const = input.const as JsonSchemaScalar
-        return node
+        break
       default:
-        return authorError(`${path}.type must be string/number/integer/boolean/null/array/object/json, or use oneOf`)
+        authorError(`${path}.type must be string/number/integer/boolean/null/array/object/json, or use oneOf`)
     }
-  } finally {
-    seen.delete(input)
   }
 }
 
+/** Compile one implicit property map, collecting per-property requiredness. */
+function compilePropertyMap(input: unknown, path: string): CompiledPropertyMap {
+  const holder: CompileRoot<CompiledPropertyMap> = {}
+  runSchemaCompiler({ kind: 'property-map', input, path, destination: { kind: 'root', holder } })
+  /* v8 ignore next -- the root task assigns before scheduling any descendants. */
+  return holder.value ?? authorError(`${path} did not compile`)
+}
+
+/** Compile one author node without applying any consumer root restriction. */
+function compileValueSchema(input: unknown, path: string): JsonSchemaNode {
+  const holder: CompileRoot<JsonSchemaNode> = {}
+  runSchemaCompiler({ kind: 'value', input, path, allowRequired: false, destination: { kind: 'root', holder } })
+  /* v8 ignore next -- the root task assigns before scheduling any descendants. */
+  return holder.value ?? authorError(`${path} did not compile`)
+}
+
 /**
  * Compile one author-facing value schema to the enforced raw JSON Schema
  * subset. The author-only `json` node becomes an annotation-only schema.
@@ -296,7 +426,7 @@ function compileValueSchema(
  * @returns The asserted raw schema projection.
  */
 export function valueSchemaSpecToJsonSchema(spec: ValueSchemaSpec): JsonSchemaNode {
-  const schema = compileValueSchema(spec, 'schema', new Set())
+  const schema = compileValueSchema(spec, 'schema')
   assertSupportedJsonSchema(schema)
   return schema
 }
@@ -307,7 +437,7 @@ export function valueSchemaSpecToJsonSchema(spec: ValueSchemaSpec): JsonSchemaNo
  * @returns An object-rooted raw schema with no implicit-root openness override.
  */
 export function parameterSchemaSpecToJsonSchema(spec: ParameterSchemaSpec): ParameterJsonSchema {
-  const compiled = compilePropertyMap(spec, 'parameters', new Set())
+  const compiled = compilePropertyMap(spec, 'parameters')
   const schema: ParameterJsonSchema = {
     type: 'object',
     properties: compiled.properties,

packages/core/tools/src/ts-types.ts

@@ -8,7 +8,7 @@
 
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 import { assertSupportedJsonSchema } from './json-schema.ts'
-import type { JsonSchemaScalar } from './json-schema.ts'
+import type { JsonSchemaNode, JsonSchemaScalar } from './json-schema.ts'
 
 /** Property names that are valid bare TS identifiers; anything else is quoted. */
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
@@ -47,9 +47,181 @@ function renderConstrainedScalar(node: Record<string, unknown>, type: string): s
   return broad
 }
 
-/** Parenthesize a union or object intersection before applying `[]`. */
-function arrayItem(type: string): string {
-  return type.includes('|') || type.includes('&') ? `(${type})[]` : `${type}[]`
+/** A composable type document that can be flattened without recursive string concatenation. */
+interface TypeDocument {
+  readonly parts: readonly (string | TypeDocument)[]
+  readonly containsUnionOrIntersection: boolean
+}
+
+/** Build one document from captured parts while retaining the legacy array-parenthesization test. */
+function typeDocumentFrom(parts: readonly (string | TypeDocument)[]): TypeDocument {
+  return {
+    parts,
+    containsUnionOrIntersection: parts.some(part => typeof part === 'string'
+      ? part.includes('|') || part.includes('&')
+      : part.containsUnionOrIntersection),
+  }
+}
+
+/** Build a small document without an intermediate array at each call site. */
+function typeDocument(...parts: (string | TypeDocument)[]): TypeDocument {
+  return typeDocumentFrom(parts)
+}
+
+/** Flatten a nested document with an explicit work stack. */
+function flattenTypeDocument(document: TypeDocument): string {
+  const chunks: string[] = []
+  const tasks: (string | TypeDocument)[] = [document]
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (typeof task === 'string') {
+      chunks.push(task)
+      continue
+    }
+    for (let index = task.parts.length - 1; index >= 0; index--) {
+      const part = task.parts[index]
+      /* v8 ignore next -- the loop is bounded by the captured part count. */
+      if (part !== undefined) tasks.push(part)
+    }
+  }
+  return chunks.join('')
+}
+
+/** One explicit call frame for stack-safe schema-to-TypeScript rendering. */
+interface SchemaRenderFrame {
+  readonly node: JsonSchemaNode
+  readonly indent: number
+  phase: 'start' | 'children'
+  kind?: 'oneOf' | 'array' | 'object'
+  children: { node: JsonSchemaNode; indent: number }[]
+  childIndex: number
+  childDocuments: TypeDocument[]
+  entries: [string, JsonSchemaNode][]
+}
+
+/** Initialize one schema-render frame with empty aggregation state. */
+function schemaRenderFrame(node: JsonSchemaNode, indent: number): SchemaRenderFrame {
+  return { node, indent, phase: 'start', children: [], childIndex: 0, childDocuments: [], entries: [] }
+}
+
+/** Render an already asserted schema to a composable document. */
+function renderSupportedSchema(schema: JsonSchemaNode, indent: number): TypeDocument {
+  const frames: SchemaRenderFrame[] = [schemaRenderFrame(schema, indent)]
+  let rootDocument: TypeDocument | undefined
+  const finish = (document: TypeDocument): void => {
+    frames.pop()
+    const parent = frames.at(-1)
+    if (parent === undefined) rootDocument = document
+    else parent.childDocuments.push(document)
+  }
+
+  while (frames.length > 0) {
+    const frame = frames.at(-1)
+    /* v8 ignore next -- the loop condition guarantees a current frame. */
+    if (frame === undefined) break
+    if (frame.phase === 'children') {
+      if (frame.childIndex < frame.children.length) {
+        const child = frame.children[frame.childIndex]
+        /* v8 ignore next -- childIndex is bounded by children.length. */
+        if (child === undefined) throw new Error('missing schema render child')
+        frame.childIndex++
+        frames.push(schemaRenderFrame(child.node, child.indent))
+        continue
+      }
+      if (frame.kind === 'oneOf') {
+        const parts: (string | TypeDocument)[] = []
+        for (let index = 0; index < frame.childDocuments.length; index++) {
+          if (index > 0) parts.push(' | ')
+          const child = frame.childDocuments[index]
+          /* v8 ignore next -- child documents correspond one-to-one with children. */
+          if (child !== undefined) parts.push(child)
+        }
+        finish(typeDocumentFrom(parts))
+        continue
+      }
+      if (frame.kind === 'array') {
+        const child = frame.childDocuments[0]
+        /* v8 ignore next -- array frames always schedule exactly one child. */
+        if (child === undefined) throw new Error('missing array item type')
+        finish(child.containsUnionOrIntersection
+          ? typeDocument('(', child, ')[]')
+          : typeDocument(child, '[]'))
+        continue
+      }
+
+      const required = new Set(frame.node.required)
+      const parts: (string | TypeDocument)[] = ['{']
+      for (let index = 0; index < frame.entries.length; index++) {
+        const entry = frame.entries[index]
+        const child = frame.childDocuments[index]
+        /* v8 ignore next -- object entries and child documents have the same length. */
+        if (entry === undefined || child === undefined) throw new Error('missing object property type')
+        const [name, prop] = entry
+        for (const line of docLines(prop.description, frame.indent + 1)) parts.push('\n', line)
+        parts.push('\n', `${pad(frame.indent + 1)}${renderKey(name)}${required.has(name) ? '' : '?'}: `, child, ';')
+      }
+      parts.push('\n', `${pad(frame.indent)}}`)
+      const declared = typeDocumentFrom(parts)
+      finish(frame.node.additionalProperties === false
+        ? declared
+        : typeDocument(declared, ' & Record<string, JsonValue>'))
+      continue
+    }
+
+    const node = frame.node
+    if (node.oneOf !== undefined) {
+      frame.kind = 'oneOf'
+      frame.children = Array.from(node.oneOf, child => ({ node: child, indent: frame.indent }))
+      frame.childIndex = 0
+      frame.childDocuments = []
+      frame.phase = 'children'
+      continue
+    }
+    if (node.type === undefined) {
+      finish(typeDocument('JsonValue'))
+      continue
+    }
+    switch (node.type) {
+      case 'string':
+      case 'number':
+      case 'integer':
+      case 'boolean':
+      case 'null':
+        finish(typeDocument(renderConstrainedScalar(node as Record<string, unknown>, node.type)))
+        break
+      case 'array':
+        if (node.items === undefined) {
+          finish(typeDocument('JsonValue[]'))
+        } else {
+          frame.kind = 'array'
+          frame.children = [{ node: node.items, indent: frame.indent }]
+          frame.childIndex = 0
+          frame.childDocuments = []
+          frame.phase = 'children'
+        }
+        break
+      case 'object': {
+        const open = node.additionalProperties !== false
+        const entries = Object.entries(node.properties ?? {})
+        if (entries.length === 0) {
+          finish(typeDocument(open ? 'Record<string, JsonValue>' : 'Record<string, never>'))
+        } else {
+          frame.kind = 'object'
+          frame.entries = entries
+          frame.children = entries.map(([, child]) => ({ node: child, indent: frame.indent + 1 }))
+          frame.childIndex = 0
+          frame.childDocuments = []
+          frame.phase = 'children'
+        }
+        break
+      }
+      /* v8 ignore next -- assertSupportedJsonSchema narrowed this closed type union. */
+      default:
+        finish(typeDocument('unknown'))
+    }
+  }
+
+  /* v8 ignore next -- every root frame produces one document. */
+  return rootDocument ?? typeDocument('unknown')
 }
 
 /**
@@ -63,43 +235,10 @@ function arrayItem(type: string): string {
 export function jsonSchemaToTs(schema: unknown, indent = 0): string {
   try {
     assertSupportedJsonSchema(schema)
+    return flattenTypeDocument(renderSupportedSchema(schema, indent))
   } catch {
     return 'unknown'
   }
-  const node = schema as Record<string, unknown>
-  if (Object.hasOwn(node, 'oneOf')) {
-    return (node.oneOf as unknown[]).map(branch => jsonSchemaToTs(branch, indent)).join(' | ')
-  }
-  if (!Object.hasOwn(node, 'type')) return 'JsonValue'
-  switch (node.type) {
-    case 'string': return renderConstrainedScalar(node, 'string')
-    case 'number': return renderConstrainedScalar(node, 'number')
-    case 'integer': return renderConstrainedScalar(node, 'integer')
-    case 'boolean': return renderConstrainedScalar(node, 'boolean')
-    case 'null': return renderConstrainedScalar(node, 'null')
-    case 'array': {
-      return arrayItem(Object.hasOwn(node, 'items') ? jsonSchemaToTs(node.items, indent) : 'JsonValue')
-    }
-    case 'object': {
-      const properties = node.properties
-      const open = node.additionalProperties !== false
-      if (properties === undefined) return open ? 'Record<string, JsonValue>' : 'Record<string, never>'
-      const entries = Object.entries(properties as Record<string, unknown>)
-      if (entries.length === 0) return open ? 'Record<string, JsonValue>' : 'Record<string, never>'
-      const required = new Set(node.required as string[] | undefined)
-      const lines: string[] = ['{']
-      for (const [name, prop] of entries) {
-        const description = (prop as Record<string, unknown>).description
-        lines.push(...docLines(description, indent + 1))
-        lines.push(`${pad(indent + 1)}${renderKey(name)}${required.has(name) ? '' : '?'}: ${jsonSchemaToTs(prop, indent + 1)};`)
-      }
-      lines.push(`${pad(indent)}}`)
-      const declared = lines.join('\n')
-      return open ? `${declared} & Record<string, JsonValue>` : declared
-    }
-    /* v8 ignore next -- assertSupportedJsonSchema narrowed this closed type union. */
-    default: return 'unknown'
-  }
 }
 
 /** The fixed model-facing usage contract rendered above the declarations (see the Code Mode Agent Note's "What the model sees"). */

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'get_goal', 'glob', 'grep', 'lsp', 'ralph', 'read', 'run_code', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'lsp', 'ralph', 'read', 'run_code', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {

packages/core/tools/tests/json-schema.spec.ts

@@ -214,6 +214,14 @@ describe('the enforced raw JSON Schema subset', () => {
       .toEqual(['schema.properties.at must be a schema object'])
   })
 
+  it('asserts deeply nested raw unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let schema: JsonSchemaNode = { type: 'string' }
+    for (let index = 0; index < depth; index++) schema = { oneOf: [schema, { type: 'null' }] }
+
+    expect(() => { assertSupportedJsonSchema(schema) }).not.toThrow()
+  })
+
   it('uses own-property semantics for required declarations', () => {
     expect(violationsOf({ type: 'object', properties: {}, required: ['toString'] }))
       .toEqual(['schema.required names "toString" which is not in properties'])
@@ -322,6 +330,17 @@ describe('validateJsonSchemaValue', () => {
     expect(validateJsonSchemaValue(overlap, 1.5)).toEqual([])
   })
 
+  it('validates deeply nested exact-one unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let schema: JsonSchemaNode = { type: 'string' }
+    for (let index = 0; index < depth; index++) schema = { oneOf: [schema, { type: 'null' }] }
+    assertSupportedJsonSchema(schema)
+
+    expect(validateJsonSchemaValue(schema, 'leaf')).toEqual([])
+    expect(validateJsonSchemaValue(schema, 42))
+      .toEqual(['"value" must match exactly one oneOf branch (matched 0)'])
+  })
+
   it('an unconstrained schema accepts only lossless JSON values', () => {
     const anyJson = asserted({})
     for (const value of [null, true, 1, 'x', [1], { x: null }]) {

packages/core/tools/tests/schema.spec.ts

@@ -92,6 +92,23 @@ describe('the unified author schema DSL', () => {
     expect(() => parameterSchemaSpecToJsonSchema(properties as ParameterSchemaSpec)).toThrow(/circular/)
   })
 
+  it('compiles deeply nested author unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let spec: unknown = { type: 'string' }
+    for (let index = 0; index < depth; index++) spec = { oneOf: [spec, { type: 'null' }] }
+
+    const compiled = valueSchemaSpecToJsonSchema(spec as ValueSchemaSpec)
+
+    let cursor = compiled
+    let layers = 0
+    while (cursor.oneOf !== undefined) {
+      cursor = cursor.oneOf[0]!
+      layers++
+    }
+    expect(layers).toBe(depth)
+    expect(cursor).toEqual({ type: 'string' })
+  })
+
   it('preserves a property literally named __proto__ as schema data', () => {
     const properties = Object.create(null) as ParameterSchemaSpec
     properties.__proto__ = { type: 'string', required: true }

packages/core/tools/tests/tools.spec.ts

@@ -8,7 +8,7 @@ import ToolRegistry, {
   defineContentToolFixture, defineTool, JsonSchemaError, parameterSchemaSpecToJsonSchema, validateArgs, ToolArgsError, ToolNotFoundError,
   TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH,
   type InferArgs, type JsonValue, type ParameterSchemaSpec, type PreToolDecision, type PostToolDecision,
-  type ToolDefinition, type ToolDispatchExecution, type ToolExecutionResult, type ToolExecutionToken,
+  type JsonSchemaNode, type ToolDefinition, type ToolDispatchExecution, type ToolExecutionResult, type ToolExecutionToken,
 } from '@deepseek-ai/dsh-tools'
 
 const testToolSignal = new AbortController().signal
@@ -1687,6 +1687,41 @@ describe('ToolRegistry', () => {
     }])
   })
 
+  it('schemas() snapshots deeply nested parameters without using structured-clone recursion', async () => {
+    const ctx = await setup()
+    const depth = 5_000
+    let nested: JsonSchemaNode = { type: 'string' }
+    for (let index = 0; index < depth; index++) nested = { oneOf: [nested, { type: 'null' }] }
+    ctx.tools.register({
+      ...echoTool,
+      name: 'deep-schema',
+      parameters: { type: 'object', properties: { nested } },
+    })
+
+    const projected = ctx.tools.schemas()[0]!.parameters as JsonSchemaNode
+
+    let cursor = projected.properties!.nested!
+    let layers = 0
+    while (cursor.oneOf !== undefined) {
+      cursor = cursor.oneOf[0]!
+      layers++
+    }
+    expect(layers).toBe(depth)
+    expect(cursor).toEqual({ type: 'string' })
+  })
+
+  it('rejects schema projection when a raw registration is not lossless JSON', async () => {
+    const ctx = await setup()
+    ctx.tools.register({
+      ...echoTool,
+      name: 'lossy-schema',
+      parameters: { type: 'object', default: Number.NaN },
+    })
+
+    expect(() => ctx.tools.schemas())
+      .toThrow('tool "lossy-schema" parameters must be lossless JSON before schema projection')
+  })
+
   it('rejects a non-positive or non-finite registration timeout', async () => {
     const ctx = await setup()
     expect(() => ctx.tools.register({ ...echoTool, name: 'zero-timeout', timeoutMs: 0 }))

packages/core/tools/tests/ts-types.spec.ts

@@ -93,6 +93,17 @@ describe('jsonSchemaToTs', () => {
     expect(rendered).not.toContain('tool-*/ over')
     expect(rendered).toContain(String.raw`tool-*\/ over`)
   })
+
+  it('renders deeply nested unions without using the JavaScript call stack', () => {
+    const depth = 5_000
+    let schema: unknown = { type: 'string' }
+    for (let index = 0; index < depth; index++) schema = { oneOf: [schema, { type: 'null' }] }
+
+    const rendered = jsonSchemaToTs(schema)
+
+    expect(rendered.startsWith('string | null')).toBe(true)
+    expect(rendered.length).toBe('string'.length + depth * ' | null'.length)
+  })
 })
 
 describe('renderToolsSdk', () => {

packages/examples/cli-demo/src/cli.ts

@@ -14,7 +14,7 @@ import { boot, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 const CLI_NAME = 'dsh-cli-demo'
 const DEFAULT_CONFIG_PATH = './cordis.yml'
 const OUTPUT_FORMATS = ['text', 'json', 'stream-json'] as const
-const USAGE = `Usage: ${CLI_NAME} [--config path] [--output-format text|json|stream-json] <task>\n`
+const USAGE = `Usage: ${CLI_NAME} [--config path] [--output-format text|json|stream-json] (-p <task> | <task>)\n`
 
 /** Supported CLI output encodings. */
 export type OutputFormat = typeof OUTPUT_FORMATS[number]
@@ -73,6 +73,7 @@ interface ParsedArguments {
     readonly config?: string
     readonly 'output-format'?: string
     readonly help?: boolean
+    readonly prompt?: string
   }
   readonly positionals: string[]
 }
@@ -129,6 +130,7 @@ export function parseCliArgs(args: readonly string[]): CliCommand {
         config: { type: 'string' },
         'output-format': { type: 'string' },
         help: { type: 'boolean' },
+        prompt: { type: 'string', short: 'p' },
       },
       allowPositionals: true,
       strict: true,
@@ -138,12 +140,16 @@ export function parseCliArgs(args: readonly string[]): CliCommand {
   }
 
   if (parsed.values.help === true) return { kind: 'help' }
-  if (parsed.positionals.length !== 1) {
-    throw new CliArgumentError(`expected exactly one positional task, received ${parsed.positionals.length}`)
+  const prompt = parsed.values.prompt
+  if (prompt !== undefined && parsed.positionals.length > 0) {
+    throw new CliArgumentError('-p/--prompt and a positional task are mutually exclusive')
   }
-  // Cardinality was checked above, so index zero exists.
+  if (prompt === undefined && parsed.positionals.length !== 1) {
+    throw new CliArgumentError(`expected exactly one positional task or -p, received ${parsed.positionals.length} positional(s)`)
+  }
+  // Cardinality was checked above, so the fallback index zero exists.
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  const task = parsed.positionals[0]!
+  const task = prompt ?? parsed.positionals[0]!
   if (task.trim().length === 0) throw new CliArgumentError('task must not be blank')
 
   const requestedFormat = parsed.values['output-format'] ?? 'text'

packages/examples/cli-demo/tests/built-bin.e2e.ts

@@ -8,6 +8,15 @@ import { fileURLToPath } from 'node:url'
 import { zstdDecompress } from 'node:zlib'
 import { afterEach, describe, expect, it } from 'vitest'
 
+/**
+ * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer.
+ * The consumer's mock model is an example-local TypeScript plugin (Node 22.19+ — the engines
+ * floor — strips types natively, so plain `node` loads it), its config carries a `disabled:
+ * true` unresolvable entry (the fail-loud entry-load guard must not mistake an intentionally
+ * fiber-less entry for a failed import), and the optional spill pair loads from the consumer
+ * install — so every passing boot proves all three alongside the CLI's own output contract.
+ */
+
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
 const cliBin = join(repoRoot, 'packages/examples/cli-demo/lib/bin.js')
 const decompress = promisify(zstdDecompress)
@@ -17,6 +26,7 @@ const dshPackages = [
   'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence', 'session-persistence/session-persistence-jsonl',
   'context/workspace-context',
+  'spill/spill', 'spill/spill-local', 'spill/spill-policy', 'util/retention',
 ]
 const vendorPackages = ['cordis', 'loader', 'include', 'timer', 'schemastery', 'cosmokit']
 
@@ -35,15 +45,18 @@ async function makeConsumer(): Promise<string> {
   const nodeModules = join(dir, 'node_modules')
   for (const rel of dshPackages) await linkPackage(join(repoRoot, 'packages', rel), nodeModules)
   for (const rel of vendorPackages) await linkPackage(join(repoRoot, 'vendor', rel), nodeModules)
-  await writeFile(join(dir, 'mock-llm.mjs'), [
-    "import { LlmAdapter } from '@deepseek-ai/dsh-llm'",
+  await writeFile(join(dir, 'mock-llm.ts'), [
+    // Real type annotations: this file exists to prove plain Node's type
+    // stripping loads an example-local TS plugin from a built consumer.
+    "import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'",
+    "import type { Context } from 'cordis'",
     'class Mock extends LlmAdapter {',
-    '  async * stream(options) {',
-    "    const text = options.messages.flatMap(message => message.content).filter(block => block.type === 'text').at(-1)?.text ?? ''",
+    '  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {',
+    "    const text: string = options.messages.flatMap(message => message.content).filter(block => block.type === 'text').at(-1)?.text ?? ''",
     "    yield { type: 'block-start', index: 0, blockType: 'text' }",
     "    if (text === 'hang') {",
     "      yield { type: 'text-delta', index: 0, text: 'partial' }",
-    '      await new Promise((resolve, reject) => {',
+    '      await new Promise<never>((resolve, reject) => {',
     "        const timer = setTimeout(() => reject(new Error('hang timeout')), 30000)",
     "        const onAbort = () => { clearTimeout(timer); reject(new Error('aborted')) }",
     '        if (options.signal.aborted) onAbort()',
@@ -60,12 +73,12 @@ async function makeConsumer(): Promise<string> {
     '}',
     "export const name = 'built-cli-mock'",
     "export const inject = ['llm']",
-    "export function apply(ctx) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
+    "export function apply(ctx: Context) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
     '',
   ].join('\n'))
   await writeFile(join(dir, 'cordis.yml'), [
     '- id: mock-llm',
-    "  name: './mock-llm.mjs'",
+    "  name: './mock-llm.ts'",
     '- id: bash',
     "  name: '@deepseek-ai/dsh-bash-local'",
     '- id: cli-agent',
@@ -76,6 +89,18 @@ async function makeConsumer(): Promise<string> {
     "    persona: 'built CLI test'",
     "    persistenceRoot: './.sessions'",
     '    workspaceContext: false',
+    '- id: spill-local',
+    "  name: '@deepseek-ai/dsh-spill-local'",
+    '- id: spill-policy',
+    "  name: '@deepseek-ai/dsh-spill-policy'",
+    '  config:',
+    '    maxInlineBytes: 50000',
+    // A `disabled: true` entry settles without a fiber by design; the fail-loud
+    // entry-load guard must not mistake it for a failed import. The nonexistent
+    // path makes that distinction observable while a clean run proves boot continued.
+    '- id: off',
+    "  name: './does-not-exist.ts'",
+    '  disabled: true',
     '',
   ].join('\n'))
   return dir

packages/examples/cli-demo/tests/cli.spec.ts

@@ -166,15 +166,19 @@ describe('parseCliArgs', () => {
       kind: 'run', configPath: 'custom.yml', outputFormat: 'stream-json', task: 'do it',
     })
     expect(parseCliArgs(['--', '-task'])).toMatchObject({ task: '-task' })
+    expect(parseCliArgs(['-p', 'flag task'])).toMatchObject({ task: 'flag task' })
+    expect(parseCliArgs(['--prompt', 'long-flag task'])).toMatchObject({ task: 'long-flag task' })
     expect(parseCliArgs(['--help', 'ignored'])).toEqual({ kind: 'help' })
   })
 
   it('rejects missing, blank, extra, invalid-format, and unsupported flags', () => {
     expect(() => parseCliArgs([])).toThrow('received 0')
     expect(() => parseCliArgs(['   '])).toThrow('must not be blank')
+    expect(() => parseCliArgs(['-p', '   '])).toThrow('must not be blank')
     expect(() => parseCliArgs(['one', 'two'])).toThrow('received 2')
+    expect(() => parseCliArgs(['-p', 'task', 'positional'])).toThrow('mutually exclusive')
     expect(() => parseCliArgs(['--output-format', 'xml', 'task'])).toThrow('unsupported output format')
-    expect(() => parseCliArgs(['-p', 'task'])).toThrow('Unknown option')
+    expect(() => parseCliArgs(['-x', 'task'])).toThrow('Unknown option')
   })
 })
 

packages/examples/tui-demo/src/bin.ts

@@ -11,8 +11,16 @@ import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/
 const NAME = 'dsh-tui-demo'
 
 /* v8 ignore start -- thin self-executing composition over the unit-tested
-   dsh-app-boot helpers; exercised end-to-end by the keyless Loader-path and
-   built-bin smokes */
+   dsh-app-boot helpers; exercised end-to-end by the tui-agent PTY smoke and
+   the built-bin fail-loud smoke */
+// Refuse pipes BEFORE booting: a compose-time throw inside the Loader tree is
+// logged per-entry rather than rethrown, so a piped launch would otherwise
+// settle into an idle UI-less process instead of exiting nonzero.
+if (!process.stdin.isTTY || !process.stdout.isTTY) {
+  process.stderr.write(`${NAME}: the TUI requires stdin and stdout to be interactive TTYs; `
+    + 'use the one-shot dsh-cli-demo bin for pipes and automation\n')
+  process.exit(1)
+}
 installFailLoud(NAME)
 loadEnv(NAME)
 await boot(NAME, resolveConfigPath(process.argv[2] ?? './cordis.yml', undefined))

packages/examples/tui-demo/src/index.ts

@@ -27,7 +27,6 @@ import * as uiTui from '@deepseek-ai/dsh-tui'
 
 export const name = 'tui-demo'
 const DEFAULT_PERSISTENCE_ROOT = './.sessions'
-const DEFAULT_WELCOME = 'ready.'
 
 /** App config routed to the spine, TUI, configured agent, and JSONL backend. */
 export interface Config {
@@ -51,8 +50,15 @@ export interface Config {
   persistenceRoot?: string
   /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
   persistenceCompression?: JsonlCompression
-  /** TUI subtitle rendered on start. Defaults to `ready.`. */
+  /** TUI transcript's optional first line; absent renders nothing on start. */
   welcome?: string
+  /**
+   * Shell command template the TUI prints on exit and lists under `/resume`,
+   * with `{session}` replaced by the live session id (forwarded to the front
+   * door). Set it to a command that resumes via this app's env var, e.g.
+   * `RESUME_SESSION_ID={session} dsh`.
+   */
+  resumeCommand?: string
   /** Full-screen TUI presentation settings. */
   ui?: uiTui.TuiConfig
   /** Skill registry, local-provider, and model-facing consumer config. */
@@ -84,7 +90,8 @@ export const Config: z<Config> = z.object({
   sessionTitle: agentCore.SessionTitleConfigSchema,
   persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
   persistenceCompression: JsonlCompressionSchema,
-  welcome: z.string().default(DEFAULT_WELCOME),
+  welcome: z.string(),
+  resumeCommand: z.string(),
   ui: uiTui.TuiConfigSchema,
   skills: agentCore.SkillConfigSchema,
   toolBash: agentCore.ToolBashConfigSchema,
@@ -115,7 +122,8 @@ export function composeTuiApp(ctx: Context, config: Config): void {
   ctx.plugin(UserInteractionService)
   ctx.plugin(uiTui, {
     ...config.ui,
-    welcome: config.welcome ?? DEFAULT_WELCOME,
+    ...config.welcome === undefined ? {} : { welcome: config.welcome },
+    ...config.resumeCommand === undefined ? {} : { resumeCommand: config.resumeCommand },
     sessionId,
   })
   ctx.plugin(agentCore, {

packages/examples/tui-demo/tests/built-bin.e2e.ts

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, mkdir, rm, symlink, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+
+/**
+ * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer.
+ * The TUI app owns no non-TTY fallback, so the piped subprocess must refuse to boot with a
+ * nonzero exit and a stderr pointer at the one-shot CLI — the bin guards BEFORE the Loader
+ * because a compose-time throw inside the tree is logged per-entry, not rethrown. The consumer
+ * links only the bin's import chain (dsh-app-boot and its vendored Loader stack): the refusal
+ * fires before any config is read, so no plugin tree is needed. Missing-config fail-loud and
+ * full-boot coverage for the shared dsh-app-boot glue live in cli-demo's built-bin suite; it
+ * skips before build, and interactive TTY behavior is PTY-covered by examples/tui-agent (the
+ * one sanctioned PTY surface).
+ */
+
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const tuiBin = join(repoRoot, 'packages/examples/tui-demo/lib/bin.js')
+
+// Symlink each package the bin imports at module load by package name so plain
+// Node resolves its built `main`, matching an installed dependency rather than
+// tsconfig paths.
+const dshPackages = ['examples/tui-demo', 'ui/app-boot']
+const vendorPackages = ['cordis', 'loader', 'include', 'schemastery', 'cosmokit']
+
+async function pkgName(absDir: string): Promise<string> {
+  const json = JSON.parse(await readFile(join(absDir, 'package.json'), 'utf8')) as { name: string }
+  return json.name
+}
+
+/** Build a temporary external consumer with built workspace/vendor links. */
+async function makeConsumer(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'tui-built-bin-'))
+  const nm = join(dir, 'node_modules')
+  for (const rel of dshPackages) {
+    const abs = join(repoRoot, 'packages', rel)
+    const target = join(nm, await pkgName(abs))
+    await mkdir(dirname(target), { recursive: true })
+    await symlink(abs, target)
+  }
+  for (const v of vendorPackages) {
+    const abs = join(repoRoot, 'vendor', v)
+    const target = join(nm, await pkgName(abs))
+    await mkdir(dirname(target), { recursive: true })
+    await symlink(abs, target)
+  }
+  return dir
+}
+
+/** Run the built bin in `cwd` with PIPED stdio; resolve with output + exit code. */
+function runBuiltBin(cwd: string): Promise<{ stdout: string; code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    // NO tsx — this is the published `node lib/bin.js` path (`--expose-internals`
+    // matches the demo command; the guard fires before the Loader needs it).
+    const child = spawn(process.execPath, ['--expose-internals', tuiBin, './cordis.yml'], {
+      cwd,
+      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (c: string) => { stdout += c })
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (c: string) => { stderr += c })
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(new Error(`built bin did not exit within 25s. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 25_000)
+    child.on('exit', (code) => { clearTimeout(timer); resolve({ stdout, code: code ?? -1, stderr }) })
+    child.on('error', (err) => { clearTimeout(timer); reject(err) })
+    child.stdin.end()
+  })
+}
+
+let consumer: string | undefined
+
+afterEach(async () => {
+  // Windows can briefly retain released handles after exit; retry removal.
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
+  consumer = undefined
+})
+
+describe.skipIf(!existsSync(tuiBin))('dsh-tui-demo BUILT bin (node lib/bin.js, no tsx)', () => {
+  it('refuses pipes LOUD (non-zero exit + stderr) before booting the Loader', async () => {
+    consumer = await makeConsumer()
+    const { stdout, code, stderr } = await runBuiltBin(consumer)
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('requires stdin and stdout to be interactive TTYs')
+    expect(stderr).toContain('dsh-cli-demo')
+    // The refusal happens before any plugin mounts: stdout stays silent.
+    expect(stdout).toBe('')
+  }, 30_000)
+})

packages/examples/tui-demo/tests/tui-agent.spec.ts

@@ -33,6 +33,7 @@ describe('dsh-tui-demo app', () => {
       persistenceRoot: '/tmp/tui-sessions',
       persistenceCompression: 'none',
       welcome: 'TUI ready',
+      resumeCommand: 'dsh --resume {session}',
       ui: { color: false, maxToolOutputLines: 3 },
       skills: { tool: { catalogDescriptionMaxLength: 8 } },
       toolBash: { enableRunInBackground: false },
@@ -52,7 +53,12 @@ describe('dsh-tui-demo app', () => {
     expect(calls[0]?.config).toBeUndefined()
     expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
     const tuiConfig = calls[4]?.config as { sessionId: string }
-    expect(tuiConfig).toMatchObject({ welcome: 'TUI ready', color: false, maxToolOutputLines: 3 })
+    expect(tuiConfig).toMatchObject({
+      welcome: 'TUI ready',
+      resumeCommand: 'dsh --resume {session}',
+      color: false,
+      maxToolOutputLines: 3,
+    })
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
     const spineConfig = calls[5]?.config as {
       readonly agents: Array<Record<string, unknown>>
@@ -88,7 +94,8 @@ describe('dsh-tui-demo app', () => {
     })
 
     expect(calls[2]?.config).toEqual({ root: './.sessions' })
-    expect(calls[4]?.config).toEqual({ welcome: 'ready.', sessionId: 'persisted-session' })
+    // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
+    expect(calls[4]?.config).toEqual({ sessionId: 'persisted-session' })
     expect((calls[5]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
       id: 'main',
       resumeSessionId: 'persisted-session',

packages/llm/llm-deepseek/src/serialize.ts

@@ -40,10 +40,15 @@ function serializeAssistant(message: Message): WireMessage {
 
   return {
     role: 'assistant',
-    // Tool-call turns send "" rather than null: the live API answers both,
-    // but the official samples replay message.content verbatim (which is ""
-    // for pure tool-call responses) and some gateways reject null outright.
-    content: text.length > 0 ? text : toolCalls.length > 0 ? '' : null,
+    // Text-less turns send "" — NEVER null. Pure tool-call turns: the
+    // official samples replay message.content verbatim (which is "") and
+    // some gateways reject null outright. Reasoning-ONLY turns (the model
+    // can answer entirely in the reasoning channel, e.g. a v4-flash
+    // greeting): the live API rejects null-content/no-tool_calls assistant
+    // messages with a 400 ("content or tool_calls must be set"), and since
+    // the message sits durably in the session log, a null here bricks every
+    // later turn of that session.
+    content: text,
     // Official passback rule (guides/thinking_mode.mdx): reasoning_content
     // must return on tool-call turns; it is ignored on plain turns, so we
     // drop it there to save tokens.

packages/llm/llm-deepseek/tests/serialize.spec.ts

@@ -187,12 +187,22 @@ describe('serializeRequest', () => {
   })
 })
 
-describe('assistant empty and tool-call content shapes', () => {
-  it('serializes a content-less, tool-call-less assistant message as null content', () => {
-    // Aborted/empty assistant turns: no text, no calls → null (the wire
-    // accepts it; "" is reserved for tool-call turns per the samples).
+describe('review fixes: assistant content shapes', () => {
+  it('serializes a content-less, tool-call-less assistant message as "" content, never null', () => {
+    // Aborted/empty assistant turns: no text, no calls → "". The earlier
+    // null shape was live-falsified: the API 400s a null-content assistant
+    // message without tool_calls ("content or tool_calls must be set").
     const wire = serializeMessages([{ role: 'assistant', content: [] }])
-    expect(wire).toEqual([{ role: 'assistant', content: null }])
+    expect(wire).toEqual([{ role: 'assistant', content: '' }])
+  })
+
+  it('serializes a reasoning-ONLY assistant message as "" content with the reasoning dropped', () => {
+    // The model can answer entirely in the reasoning channel (a v4-flash
+    // greeting did, live). The passback rule keeps reasoning_content off
+    // plain turns, and content must still be SET — a null here poisoned the
+    // session log and bricked every later turn of that session.
+    const wire = serializeMessages([{ role: 'assistant', content: [{ type: 'reasoning', text: '你好！有什么我可以帮你的吗？' }] }])
+    expect(wire).toEqual([{ role: 'assistant', content: '' }])
   })
 
   it('serializes tool-call turns with empty string content, not null', () => {

packages/llm/llm-pi-ai/package.json

@@ -33,7 +33,7 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "^0.79.1",
+    "@earendil-works/pi-ai": "^0.81.1",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {

packages/llm/llm-pi-ai/src/adapter.ts

@@ -4,13 +4,11 @@
  * @module dsh-llm-pi-ai/adapter
  */
 
-import {
-  getModels,
-  streamSimple,
-} from '@earendil-works/pi-ai'
+import { streamSimple } from '@earendil-works/pi-ai/compat'
+import { getBuiltinModels } from '@earendil-works/pi-ai/providers/all'
+import type { BuiltinProvider } from '@earendil-works/pi-ai/providers/all'
 import type {
   Api,
-  KnownProvider,
   Model,
   SimpleStreamOptions,
 } from '@earendil-works/pi-ai'
@@ -33,7 +31,7 @@ export interface PiAiAdapterOptions {
  * override, preserving the catalog's API/capability/compatibility metadata.
  */
 function resolveModel(profile: PiAiProviderProfile, modelId: string): Model<Api> {
-  const model = getModels(profile.provider as KnownProvider).find(candidate => candidate.id === modelId) as Model<Api> | undefined
+  const model = getBuiltinModels(profile.provider as BuiltinProvider).find(candidate => candidate.id === modelId) as Model<Api> | undefined
   if (model === undefined) {
     throw new LlmError(`pi-ai provider "${profile.provider}" has no catalog model "${modelId}"`, 'UNKNOWN_MODEL')
   }
@@ -82,7 +80,7 @@ export class PiAiAdapter extends LlmAdapter {
     if (profile === undefined) {
       return Promise.reject(new LlmError(`pi-ai adapter does not own provider "${provider}"`, 'NO_ADAPTER'))
     }
-    return Promise.resolve(getModels(profile.provider as KnownProvider).map(model => ({
+    return Promise.resolve(getBuiltinModels(profile.provider as BuiltinProvider).map(model => ({
       provider,
       id: model.id,
       name: model.name,

packages/llm/llm-pi-ai/src/config.ts

@@ -4,7 +4,7 @@
  * @module dsh-llm-pi-ai/config
  */
 
-import { getProviders } from '@earendil-works/pi-ai'
+import { getBuiltinProviders } from '@earendil-works/pi-ai/providers/all'
 import type { CacheRetention, ThinkingBudgets, ThinkingLevel, Transport } from '@earendil-works/pi-ai'
 import z from 'schemastery'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
@@ -62,7 +62,7 @@ const profile = z.object({
   apiKey: z.string(),
   baseURL: z.string(),
   headers: z.dict(z.string()),
-  reasoning: z.union(['minimal', 'low', 'medium', 'high', 'xhigh']),
+  reasoning: z.union(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
   thinkingBudgets,
   cacheRetention: z.union(['none', 'short', 'long']),
   transport: z.union(['sse', 'websocket', 'websocket-cached', 'auto']),
@@ -84,7 +84,7 @@ export const Config: z<Config> = z.object({
  */
 export function resolveProfiles(profiles: readonly PiAiProviderProfile[]): ResolvedPiAiProviderProfile[] {
   if (profiles.length === 0) throw new Error('llm-pi-ai: providers must contain at least one profile')
-  const supported = new Set<string>(getProviders())
+  const supported = new Set<string>(getBuiltinProviders())
   const seen = new Set<string>()
   return profiles.map((source) => {
     const legacy = source as PiAiProviderProfile & {

packages/llm/llm-pi-ai/tests/adapter.spec.ts

@@ -5,8 +5,8 @@ import { Context } from 'cordis'
 import LlmService, { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, userAgent } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
 import { PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
-import { getModels } from '@earendil-works/pi-ai'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { getBuiltinModels } from '@earendil-works/pi-ai/providers/all'
 import { resolveProfiles } from '../src/config.ts'
 import { assemble } from './assemble.ts'
 
@@ -244,7 +244,7 @@ describe('PiAiAdapter provider routing', () => {
   })
 
   it('uses the resolved catalog context window for usage-based overflow detection', async () => {
-    const model = getModels('deepseek').find(candidate => candidate.id === 'deepseek-v4-flash')
+    const model = getBuiltinModels('deepseek').find(candidate => candidate.id === 'deepseek-v4-flash')
     if (model === undefined) throw new Error('deepseek-v4-flash missing from pi-ai test catalog')
     const events = [
       '{"choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]}',

packages/llm/llm-pi-ai/tests/sdk-options.spec.ts

@@ -2,8 +2,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 
 const streamSimple = vi.hoisted(() => vi.fn())
 
-vi.mock('@earendil-works/pi-ai', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@earendil-works/pi-ai')>()
+// The 0.81 SDK moved `streamSimple` to the compat entry; the adapter imports it
+// from there, so the mock must target the same specifier.
+vi.mock('@earendil-works/pi-ai/compat', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@earendil-works/pi-ai/compat')>()
   return { ...actual, streamSimple }
 })
 

packages/lsp/lsp-local/tests/lifecycle.spec.ts

@@ -1,11 +1,11 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL, fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
-import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
+import Lsp, { type LspProvider, type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 import type { LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
@@ -38,12 +38,27 @@ function fakeServer(fakeEnv: Record<string, string> = {}, overrides: Partial<Lsp
 }
 
 /** Mount the real seam + lsp-local plugin driving one fake server. */
-async function mount(fakeEnv: Record<string, string> = {}, overrides: Partial<LspLocalServerConfig> = {}): Promise<Context> {
+async function mount(
+  fakeEnv: Record<string, string> = {},
+  overrides: Partial<LspLocalServerConfig> = {},
+  captureProvider?: (provider: LspProvider) => void,
+): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(Lsp)
-  await ctx.plugin(LspLocal, {
-    servers: { fake: fakeServer(fakeEnv, overrides) },
-  })
+  const register = ctx.lsp.registerProvider.bind(ctx.lsp)
+  const registrationSpy = captureProvider === undefined
+    ? undefined
+    : vi.spyOn(ctx.lsp, 'registerProvider').mockImplementation((provider) => {
+      captureProvider(provider)
+      return register(provider)
+    })
+  try {
+    await ctx.plugin(LspLocal, {
+      servers: { fake: fakeServer(fakeEnv, overrides) },
+    })
+  } finally {
+    registrationSpy?.mockRestore()
+  }
   return ctx
 }
 
@@ -247,10 +262,22 @@ describe('lsp-local end to end over a fake server', () => {
     // The first query succeeds, then the server exits before the second arrives, leaving a dead
     // instance in the pool. The next query must evict-and-replace it and still succeed, rather than
     // failing once on the closed connection first.
-    const ctx = await mount({ LSP_FAKE_EXIT_AFTER_REPLY: '1', LSP_FAKE_DEF: JSON.stringify(locationJson(0)) })
+    let provider: LspProvider | undefined
+    const ctx = await mount(
+      { LSP_FAKE_EXIT_AFTER_REPLY: '1', LSP_FAKE_DEF: JSON.stringify(locationJson(0)) },
+      {},
+      (registered) => { provider = registered },
+    )
     expect(await ctx.lsp.query(query('goToDefinition'))).toMatchObject({ kind: 'locations' })
-    // Wait past the fixture's post-reply exit so the pooled instance is observably dead.
-    await new Promise(resolve => setTimeout(resolve, 60))
+    if (provider === undefined) throw new Error('expected lsp-local to register a provider')
+    // This implementation-local test reaches the private pool only to synchronize with its actual
+    // close state. A fixed wall-clock sleep can expire before a CPU-starved child runs its exit timer.
+    const instances = (provider as unknown as {
+      readonly instances: ReadonlyMap<string, { readonly dead: boolean }>
+    }).instances
+    const instance = [...instances.values()][0]
+    if (instance === undefined) throw new Error('expected one pooled LSP instance')
+    await waitFor(async () => instance.dead)
     expect(await ctx.lsp.query(query('goToDefinition'))).toMatchObject({ kind: 'locations' })
     await ctx.fiber.dispose()
   })

packages/plan/README.md

@@ -0,0 +1,9 @@
+# plan/ — plan collaboration state
+
+Plan mode is one logged, per-agent collaboration state. It is a single **product** package, not a generic mode registry or a capability-seam trio.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `plan-mode/` | `plan/mode` vocabulary + fold, boundary-applied state, the `plan:policy` guidance section, `/plan [message]`, and the model-facing `exit_plan_mode` review tool | `ctx.planMode` |
+
+The active state is a pure function of the session log, so resume and fork restore it without extra machinery. The deployment supplies plan instructions through Cordis config, while `exit_plan_mode` stays registered when planning is inactive to keep the request tool catalog stable. ACP maps this capability onto its generic `default` / `plan` picker; sandbox mode and approval policy remain independent enforcement settings. Design: [plan-mode Agent Note](../../.agents/notes/implemented/feature/2026-07-07-plan-mode.md) and [plan-specific state simplification](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).

packages/plan/plan-mode/README.md

@@ -0,0 +1,88 @@
+# @deepseek-ai/dsh-plan-mode
+
+Logged, per-agent plan collaboration state with deployment-owned guidance, a direct `/plan [message]` entry command, and the reviewed `exit_plan_mode` exit. Plan mode is soft guidance; sandbox mode and approval policy remain independent enforcement axes.
+
+## Durable state
+
+`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace `SessionEventMap` member. `foldPlanMode(events)` returns the last logged value or `false`, so resume, fork, and compaction recover plan state directly from the session log. UIs observe committed flips through `session/event`.
+
+`ctx.planMode.set(agent, active)` records a pending selection and flushes it inside the next turn boundary. `get(agent)` returns `{ active, pending? }`, separating the logged state shaping the current step from a user's optimistic selection. Prompt submission, ordinary continuation, and request-recovery retry are all covered; a changed user selection contributes one `context/message` notice when the last logged request header described the other state.
+
+## Model and human surfaces
+
+While active, `plan:policy` renders the configured `section`. The plugin always registers `exit_plan_mode`, keeping tool schemas stable across the transition; its execute path accepts only active plan mode and leaves it only after an exact user approval through `ctx.userInteraction`.
+
+When `ctx.commands` is composed, the package registers `/plan [message]`. The command selects plan mode first. A non-empty argument is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance; bare `/plan` only changes state.
+
+ACP is an adapter, not the owner of this vocabulary: it advertises the fixed wire ids `default` and `plan`, maps `session/set_mode` to the boolean service, and translates committed `plan/mode` events back to `current_mode_update`.
+
+## Configuration
+
+```yaml
+- id: plan-mode
+  name: '@deepseek-ai/dsh-plan-mode'
+  config:
+    section: |
+      You are in plan mode. Explore and design before presenting the complete
+      plan through exit_plan_mode.
+```
+
+`section` is required and non-empty. Unknown keys fail at load. The package does not accept arbitrary named modes, tool filters, sandbox settings, or approval policy.
+
+Design: [plan-mode Agent Note](../../../.agents/notes/implemented/feature/2026-07-07-plan-mode.md) and [plan-specific state simplification](../../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).
+
+## Model Experience
+
+### Plan policy system prompt
+
+#### What the model sees
+
+While plan mode is active, the model sees the deployment's exact `section` text at prompt order 50; inactive mode contributes no text.
+
+##### Configuration example
+
+```markdown
+You are in plan mode. Explore and design before presenting the complete plan through exit_plan_mode.
+```
+
+#### Token effect
+
+Inactive mode adds no tokens; active mode adds the configured section to every request.
+
+#### KV Cache effect
+
+The section is stable within plan mode, but entering or leaving changes the system prompt from order 50 onward.
+
+### Optional command message
+
+#### What the model sees
+
+`/plan` and its terminal result stay outside model history; a non-empty suffix becomes one trimmed user text block through `agent.steer()` after plan mode is selected.
+
+#### Token effect
+
+The suffix costs the same history tokens as submitting that text separately; a bare command adds none.
+
+#### KV Cache effect
+
+The user block is append-only conversation growth, while entering plan mode also changes the earlier policy section.
+
+### Exit tool schema and review exchange
+
+#### What the model sees
+
+The [`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the canonical `{ approved: true }` value and renders the existing confirmation text. Rejection remains a failed call carrying review feedback.
+
+#### Token effect
+
+The stable schema is paid according to ToolRegistry mode, and each plan argument and review result remains in conversation history.
+
+#### KV Cache effect
+
+Mode transitions do not change the tool catalog; plan arguments and review results extend the conversation normally.
+
+## Known Limitations and Deferred Work
+
+- Plan mode guides rather than enforces; deployments needing a hard boundary must combine independent sandbox and approval controls.
+- A pending selection made while idle is lost if the process exits before the next boundary, so the UI must reapply it.
+- Forked agents inherit logged plan state, while newly spawned agents begin inactive; there is no creation-time plan option.

packages/plan/plan-mode/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@deepseek-ai/dsh-plan-mode",
+  "description": "Logged per-agent plan mode with deployment guidance, a direct slash command, and a user-reviewed exit",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-commands": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/plan/plan-mode/src/index.ts

@@ -0,0 +1,352 @@
+/**
+ * Plan mode is logged per-agent collaboration state: while active, a
+ * deployment-owned guidance section shapes each model request, and
+ * `exit_plan_mode` presents the completed plan for user review. It is
+ * independent of sandbox mode and approval policy; those enforcement axes do
+ * not read or write plan state.
+ *
+ * The state in force is folded from the session log (`plan/mode`, last one
+ * wins), so resume and fork restore it without a live mirror. User selections
+ * are held as pending intent until a turn boundary because every session event
+ * is turn-enclosed. The service flushes before the affected request assembly
+ * on prompt submission, ordinary continuation, and request-recovery retry.
+ *
+ * The exit tool remains registered while plan mode is inactive so crossing a
+ * boundary changes only the prompt section, not the request tool catalog.
+ *
+ * Agent Notes:
+ * - .agents/notes/implemented/feature/2026-07-07-plan-mode.md
+ * - .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
+ *
+ * @module @deepseek-ai/dsh-plan-mode
+ */
+
+import { Context, Service } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-user-interaction'
+// Type-only edge: resolves `ctx.commands` for the optional command child.
+import type {} from '@deepseek-ai/dsh-commands'
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /**
+     * Whether plan mode is in force from this point on: log-only, non-surface,
+     * whole-value replace. The last `plan/mode` wins; a log with none folds to
+     * inactive through {@link foldPlanMode}.
+     */
+    'plan/mode': { active: boolean }
+  }
+}
+
+declare module 'cordis' {
+  interface Context {
+    planMode: PlanModeService
+  }
+}
+
+/**
+ * The model-facing exit tool's name. It stays registered while plan mode is
+ * inactive so the request tool catalog is stable across transitions.
+ */
+export const EXIT_PLAN_MODE = 'exit_plan_mode'
+
+/** Deployment-owned plan guidance. */
+export interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+
+/** The review question's approve option label. */
+const APPROVE_LABEL = 'Approve'
+
+/** The review question's keep-planning option label. */
+const KEEP_PLANNING_LABEL = 'Keep planning'
+
+const EXIT_DESCRIPTION
+  = 'Use only in plan mode. Present your plan for the user\'s review and, on approval, leave plan mode. '
+  + 'Send the COMPLETE plan as markdown, starting with a # heading that names it. '
+  + 'The user may approve (carry out the plan from your next step) or keep '
+  + 'planning — their feedback comes back in the tool result; revise and present again.'
+
+/** The plan's first markdown heading (any level), or `undefined` when it has none. */
+function firstHeading(plan: string): string | undefined {
+  for (const line of plan.split('\n')) {
+    const match = /^#{1,6}\s+(.+?)\s*$/.exec(line)
+    if (match) return match[1]
+  }
+  return undefined
+}
+
+/**
+ * Validate deployment-owned plan guidance. Missing, blank, non-string, or
+ * unknown fields fail at plugin load rather than silently shaping nothing.
+ *
+ * @param config Raw plugin config.
+ * @returns A detached validated config.
+ */
+export function resolveConfig(config: PlanModeConfig): PlanModeConfig {
+  const section = (config as Partial<PlanModeConfig>).section
+  if (typeof section !== 'string') {
+    throw new Error('PlanModeConfig needs a string `section`')
+  }
+  if (section.trim() === '') {
+    throw new Error('PlanModeConfig needs a non-empty `section`')
+  }
+  const unknown = Object.keys(config).filter(key => key !== 'section')
+  if (unknown.length > 0) {
+    throw new Error(`PlanModeConfig has unknown key(s) ${unknown.join(', ')} — config is { section }`)
+  }
+  return { section }
+}
+
+/**
+ * Whether plan mode is active after the first `end` events. The last
+ * `plan/mode` wins; a prefix with none is inactive.
+ *
+ * @param events The session log or any prefix of it.
+ * @param end Fold `events[0, end)`; defaults to the whole log.
+ * @returns Whether plan mode is active.
+ */
+export function foldPlanMode(events: readonly SessionEvent[], end = events.length): boolean {
+  let active = false
+  let index = 0
+  for (const event of events) {
+    if (index >= end) break
+    index++
+    if (event.type === 'plan/mode') active = event.data.active
+  }
+  return active
+}
+
+/** Plan state at the last logged request header, or `undefined` before the first header. */
+function planModeAtLastHeader(events: readonly SessionEvent[]): boolean | undefined {
+  let lastHeader = -1
+  let index = 0
+  for (const event of events) {
+    if (event.type === 'request/header') lastHeader = index
+    index++
+  }
+  if (lastHeader < 0) return undefined
+  return foldPlanMode(events, lastHeader + 1)
+}
+
+/**
+ * `ctx.planMode`: owns logged plan state, boundary application and narration,
+ * the `plan:policy` section, the `/plan` command, and the stable exit tool.
+ * UIs observe committed flips through `session/event`; there is no live mirror.
+ */
+export class PlanModeService extends Service {
+  static inject = ['tools', 'systemPrompt']
+
+  /** Validated deployment-owned guidance. */
+  private readonly section: string
+
+  /**
+   * Latest selection per session awaiting a turn-boundary flush. `narrate` is
+   * true for user selections and false for the exit tool, whose result already
+   * narrates the transition.
+   */
+  private readonly pendingIntents = new WeakMap<Session, { active: boolean; narrate: boolean }>()
+
+  constructor(ctx: Context, config: PlanModeConfig = { section: '' }) {
+    super(ctx, 'planMode')
+    this.section = resolveConfig(config).section
+    let disposed = false
+
+    // Boundary flushes use loop interception seams, not post-commit
+    // `session/event` observation. Flush after next(): a selection arriving
+    // while a downstream async listener awaits must still shape the request
+    // this boundary precedes. Failures are contained so policy cannot block a
+    // prompt or turn; a failed append remains pending for a later boundary.
+    const flushAfter = async <T>(agent: Agent, next: () => Promise<T>): Promise<T> => {
+      const decision = await next()
+      if (!disposed) {
+        try {
+          this.onBoundary(agent)
+        } catch (error) {
+          ctx.logger.warn('dsh-plan-mode: boundary flush failed: %o', error)
+        }
+      }
+      return decision
+    }
+    ctx.on('agent/prompt-submit', (agent, _content, _source, _signal, next) =>
+      flushAfter(agent, next), { prepend: true })
+    ctx.on('agent/turn-continuation', (agent, _turn, _decision, _signal, next) =>
+      flushAfter(agent, next), { prepend: true })
+    ctx.on('agent/request-error', async (
+      agent,
+      _turn,
+      _step,
+      _error,
+      _failure,
+      _priorFailures,
+      _signal,
+      next,
+    ) => {
+      const decision = await next()
+      // A waterfall can retain this wrapper after Cordis unregisters it.
+      if (disposed || decision.action !== 'retry') return decision
+      try {
+        this.onBoundary(agent)
+      } catch (error) {
+        ctx.logger.warn('dsh-plan-mode: boundary flush failed: %o', error)
+      }
+      return decision
+    }, { prepend: true })
+    ctx.effect(() => () => { disposed = true }, 'dsh-plan-mode: close boundary lifetime')
+
+    ctx.systemPrompt.section({
+      name: 'plan:policy',
+      order: 50,
+      text: context => context.agent !== undefined && foldPlanMode(context.agent.session.events)
+        ? this.section
+        : '',
+    })
+
+    // The command child activates only when a command registry is composed.
+    ctx.inject(['commands'], (commandCtx) => {
+      commandCtx.commands.register({
+        name: 'plan',
+        description: 'Enter plan mode',
+        input: { hint: '[message]' },
+        handler: ({ agent, rawInput }) => {
+          const message = rawInput.trim()
+          this.set(agent, true)
+          if (message !== '') agent.steer([{ type: 'text', text: message }])
+          return { kind: 'success', text: 'Entering plan mode (applies from the next step).' }
+        },
+      })
+    })
+
+    ctx.tools.register(defineTool({
+      name: EXIT_PLAN_MODE,
+      description: EXIT_DESCRIPTION,
+      parameters: {
+        plan: { type: 'string', required: true, description: 'The complete plan, as markdown, starting with a # heading that names it.' },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            approved: { type: 'boolean', const: true, required: true },
+          },
+        },
+        render: () => [{ type: 'text', text: 'Plan approved — plan mode exited; carry out the plan starting with your next step.' }],
+      },
+      execute: async (args, exec) => {
+        const agent = exec.agent
+        if (agent === undefined) throw new Error(`${EXIT_PLAN_MODE} requires a calling agent (no session to switch)`)
+        if (!foldPlanMode(agent.session.events)) {
+          throw new Error(`${EXIT_PLAN_MODE} is only available in plan mode`)
+        }
+        if (!/^#\s+\S/.test(args.plan.trim())) {
+          throw new Error(`${EXIT_PLAN_MODE} requires a non-empty markdown plan starting with a # heading`)
+        }
+        const interaction = ctx.get('userInteraction')
+        if (interaction === undefined) {
+          throw new Error('no user-interaction channel is available to review the plan; ask the user to switch the session mode instead')
+        }
+        const answer = await interaction.ask({
+          questions: [{
+            id: 'plan-review',
+            header: 'Plan review',
+            question: 'Approve this plan and leave plan mode?',
+            detail: args.plan,
+            options: [
+              { label: APPROVE_LABEL, description: 'Leave plan mode; the plan is carried out from the next step.' },
+              { label: KEEP_PLANNING_LABEL, description: 'Stay in plan mode; feedback goes back to the model.' },
+            ],
+          }],
+          agent,
+          signal: exec.signal,
+        })
+        // A review may outlive this plugin fiber. Without boundary listeners,
+        // an approved result could never land, so fail and keep planning.
+        if (disposed) {
+          throw new Error('the plan-mode service was reloaded while the plan was under review; present the plan again')
+        }
+        const reviewItems = answer.answers.filter(entry => entry.id === 'plan-review')
+        const item = reviewItems.length === 1 ? reviewItems[0] : undefined
+        if (item?.selected.length !== 1 || item.selected[0] !== APPROVE_LABEL || item.custom !== undefined) {
+          const feedback = item?.custom ?? ''
+          throw new Error(feedback === ''
+            ? 'The user chose to keep planning; revise the plan and present it again.'
+            : `The user chose to keep planning; their feedback: ${feedback}`)
+        }
+        // Keep plan guidance for the rest of this assistant tool batch. The
+        // silent intent flushes after the step, before the next assembly.
+        this.pendingIntents.set(agent.session, { active: false, narrate: false })
+        return { approved: true }
+      },
+      presentCall: args => ({
+        card: 'generic',
+        title: firstHeading(args.plan) ?? 'Plan',
+        kind: 'other',
+        content: [{ type: 'text', text: args.plan }],
+      }),
+      presentResult: (_args, result) => ({
+        card: 'generic',
+        title: 'Plan review',
+        content: result.content,
+      }),
+    }))
+  }
+
+  /**
+   * Read the logged plan state and any selected state awaiting a boundary.
+   *
+   * @param agent The agent to read.
+   * @returns Current logged state plus a pending selection, when present.
+   */
+  get(agent: Agent): { active: boolean; pending?: boolean } {
+    const active = foldPlanMode(agent.session.events)
+    const pending = this.pendingIntents.get(agent.session)
+    return pending === undefined ? { active } : { active, pending: pending.active }
+  }
+
+  /**
+   * Select whether plan mode should be active from the next turn boundary.
+   * Repeated selection of the current or already-pending state is a no-op.
+   *
+   * @param agent The agent to switch.
+   * @param active Whether plan mode should be active.
+   */
+  set(agent: Agent, active: boolean): void {
+    const session = agent.session
+    const target = this.pendingIntents.get(session)?.active ?? foldPlanMode(session.events)
+    if (active === target) return
+    this.pendingIntents.set(session, { active, narrate: true })
+  }
+
+  /** Flush one pending selection before the next request assembly. */
+  private onBoundary(agent: Agent): void {
+    const session = agent.session
+    const pending = this.pendingIntents.get(session)
+    if (pending === undefined) return
+    const target = pending.active
+    if (target === foldPlanMode(session.events)) {
+      this.pendingIntents.delete(session)
+      return
+    }
+    session.append('plan/mode', { active: target })
+    // Delete only after append succeeds so a later boundary can retry a failed
+    // durable write.
+    this.pendingIntents.delete(session)
+    if (!pending.narrate) return
+    const told = planModeAtLastHeader(session.events)
+    if (told === undefined || told === target) return
+    const text = target
+      ? 'The user switched this session to plan mode.'
+      : 'The user switched this session back to the default mode.'
+    session.append('context/message', {
+      content: [{ type: 'text', text }],
+      source: { kind: 'plugin', plugin: 'plan-mode' },
+    }, { surfaceOp: 'append' })
+  }
+}
+
+export default PlanModeService

packages/plan/plan-mode/src/invariant.ts

@@ -0,0 +1,43 @@
+/** Package-owned durable plan-mode invariants. @module @deepseek-ai/dsh-plan-mode/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-plan-mode'
+
+/** Cordis companion plugin name. */
+export const name = 'plan-mode-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Validate one `plan/mode` payload before it reaches the durable log. */
+function validateEvent(event: SessionEvent, fail: InvariantFailure): void {
+  if (event.type !== 'plan/mode') return
+  const active = (event.data as { active?: unknown }).active
+  if (typeof active !== 'boolean') {
+    fail(`plan/mode carries invalid active state ${JSON.stringify(active)}; expected a boolean`)
+  }
+}
+
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Install validation for loaded and newly appended plan-mode state. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  for (const session of ctx.sessions.list()) {
+    for (const event of session.events) validateEvent(event, fail)
+  }
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'session/event') return
+    const event = (args as [Session, SessionEvent])[1]
+    validateEvent(event, fail)
+  }, { global: true })
+}, { inject: ['sessions'] })
+/* jscpd:ignore-end */
+
+/**
+ * Register the plan-mode invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/plan/plan-mode/tests/integration.spec.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import LlmService, { type StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import PlanModeService, { foldPlanMode } from '@deepseek-ai/dsh-plan-mode'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+
+const PLAN_CONFIG = { section: 'Test plan mode instructions.' }
+
+/**
+ * Full-loop integration: a scripted mock model drives the REAL plan-mode plugin
+ * through the agent loop — the pending-intent flush at the turn boundary, the
+ * assembly the soft layer shapes (the exit tool + mode section), and the
+ * `request/header` snapshots every transition leaves.
+ * Only the model is mocked; the loop, the session log, and the plugin are
+ * real.
+ */
+async function harness(adapter: MockAdapter): Promise<Context> {
+  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(AgentLoop, { agents: [] })
+  await ctx.plugin(PlanModeService, PLAN_CONFIG)
+  ctx.llm.registerAdapter(['mock'], adapter)
+  for (const name of ['read', 'write']) {
+    ctx.tools.register(defineContentToolFixture({
+      name,
+      description: `test tool ${name}`,
+      parameters: {},
+      execute: () => Promise.resolve([{ type: 'text', text: `ran ${name}` }]),
+    }))
+  }
+  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()
+      }
+    })
+  })
+}
+
+function findEvent<T extends SessionEvent['type']>(
+  log: readonly SessionEvent[],
+  type: T,
+  position: 'first' | 'last' = 'first',
+): Extract<SessionEvent, { type: T }> {
+  const found = position === 'first'
+    ? log.find(event => event.type === type)
+    : log.findLast(event => event.type === type)
+  if (!found) throw new Error(`no ${type} event in the session log`)
+  return found as Extract<SessionEvent, { type: T }>
+}
+
+describe('plan mode through the agent loop', () => {
+  it('a pre-turn set() makes the FIRST header plan-shaped, and a non-shell call is guidance-constrained only', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('call-1', 'write', {}, 'Writing during plan.'),
+      textResponse('Noted in the plan.'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('it-plan-seed'), { provider: 'mock', model: 'mock' })
+    // Selected while idle (the ACP picker shape): the pending intent flushes at
+    // the first prompt-submit, BEFORE the first assembly.
+    ctx.planMode.set(agent, true)
+
+    agent.send([{ type: 'text', text: 'explore the repo' }])
+    await waitForIdle(ctx, agent)
+
+    const log = agent.session.events
+    const planMode = findEvent(log, 'plan/mode')
+    const header = findEvent(log, 'request/header')
+    expect(planMode.seq).toBeLessThan(header.seq)
+    expect(header.data.reason).toBe('initial')
+    expect(header.data.header.tools?.map(tool => tool.name)).toEqual(['exit_plan_mode', 'read', 'write'])
+    expect(header.data.header.system).toContain('plan mode')
+
+    // No tool gate: the write RUNS — plan restrains by the section's
+    // guidance alone (enforcement lives on the independent sandbox/approval
+    // axes). The mode itself stays plan throughout.
+    const result = findEvent(log, 'tool/result')
+    expect(result.data.isError).toBe(false)
+    expect(foldPlanMode(log)).toBe(true)
+    expect(log.some(event => event.type === 'context/message')).toBe(false)
+  })
+
+  it('a user flip between turns lands at the boundary: one notice and a changed header with stable tool schemas', async () => {
+    const adapter = new MockAdapter([
+      textResponse('First turn, default mode.'),
+      textResponse('Second turn, plan mode.'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('it-plan-flip'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'hello' }])
+    await waitForIdle(ctx, agent)
+    expect(foldPlanMode(agent.session.events)).toBe(false)
+    const first = findEvent(agent.session.events, 'request/header')
+    expect(first.data.header.tools?.map(tool => tool.name)).toEqual(['exit_plan_mode', 'read', 'write'])
+
+    ctx.planMode.set(agent, true)
+    agent.send([{ type: 'text', text: 'now plan' }])
+    await waitForIdle(ctx, agent)
+
+    const log = agent.session.events
+    expect(foldPlanMode(log)).toBe(true)
+    const notices = log.filter(event => event.type === 'context/message')
+    expect(notices).toHaveLength(1)
+    expect(findEvent(log, 'context/message').data.content).toEqual([
+      { type: 'text', text: 'The user switched this session to plan mode.' },
+    ])
+    // The changed request is logged as a complete snapshot.
+    const second = findEvent(log, 'request/header', 'last')
+    expect(second.data.reason).toBe('change')
+    expect(second.data.header.tools?.map(tool => tool.name)).toEqual(['exit_plan_mode', 'read', 'write'])
+    expect(second.data.header.tools).toEqual(first.data.header.tools)
+    expect(second.data.header.system).toContain('plan mode')
+  })
+
+  it('a mode flip during request recovery shapes the retry before its assembly', async () => {
+    const failedRequest = [{
+      type: 'finish',
+      reason: { kind: 'error', failure: { message: 'temporarily unavailable', code: 'SERVER', status: 503 } },
+    }] satisfies StreamChunk[]
+    const adapter = new MockAdapter([failedRequest, textResponse('Recovered in plan mode.')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('it-plan-retry-flip'), { provider: 'mock', model: 'mock' })
+    const recoveryEntered = Promise.withResolvers<true>()
+    const releaseRecovery = Promise.withResolvers<true>()
+    ctx.on('agent/request-error', async (subject, _turn, _step, _error, _failure, _history, _signal, next) => {
+      if (subject !== agent) return next()
+      recoveryEntered.resolve(true)
+      await releaseRecovery.promise
+      return { action: 'retry' }
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    agent.send([{ type: 'text', text: 'plan after the transient failure' }])
+    await recoveryEntered.promise
+    ctx.planMode.set(agent, true)
+    releaseRecovery.resolve(true)
+    await idle
+
+    expect(adapter.requests).toHaveLength(2)
+    expect(adapter.requests[0]?.system).not.toContain(PLAN_CONFIG.section)
+    expect(adapter.requests[1]?.system).toContain(PLAN_CONFIG.section)
+    expect(adapter.requests[1]?.tools).toEqual(adapter.requests[0]?.tools)
+    const log = agent.session.events
+    const planMode = findEvent(log, 'plan/mode')
+    const firstEnd = log.find(event => event.type === 'step/end' && event.data.step === 1)
+    const retryStart = log.find(event => event.type === 'step/start' && event.data.step === 2)
+    expect(firstEnd?.seq).toBeLessThan(planMode.seq)
+    expect(planMode.seq).toBeLessThan(retryStart?.seq ?? 0)
+    expect(findEvent(log, 'request/header', 'last').data.header.system).toContain(PLAN_CONFIG.section)
+    expect(findEvent(log, 'context/message').data.content).toEqual([
+      { type: 'text', text: 'The user switched this session to plan mode.' },
+    ])
+  })
+})

packages/plan/plan-mode/tests/invariant.spec.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
+import * as PlanModeInvariant from '@deepseek-ai/dsh-plan-mode/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(InvariantService, { enabled: true })
+  await ctx.plugin(PlanModeInvariant)
+  return ctx
+}
+
+function event(active: unknown): SessionEvent {
+  return { type: 'plan/mode', seq: 0, time: 0, data: { active } } as SessionEvent
+}
+
+describe('plan-mode stream invariants', () => {
+  it('accepts either boolean state', async () => {
+    const ctx = await setup()
+    expect(() => { ctx.emit('session/event', {} as Session, event(true)) }).not.toThrow()
+    expect(() => { ctx.emit('session/event', {} as Session, event(false)) }).not.toThrow()
+  })
+
+  it.each([42, 'plan', undefined])('rejects invalid durable plan state %j', async (active) => {
+    const ctx = await setup()
+    expect(() => { ctx.emit('session/event', {} as Session, event(active)) })
+      .toThrow(/expected a boolean/)
+  })
+
+  it('ignores unrelated dispatches and session events', async () => {
+    const ctx = await setup()
+    expect(() => {
+      ctx.emit('tools/change')
+      ctx.emit('session/event', {} as Session, {
+        type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+      })
+    }).not.toThrow()
+  })
+
+  it('rejects invalid existing state on late registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    ctx.sessions.create().append('plan/mode', { active: 'plan' as unknown as boolean })
+    await ctx.plugin(InvariantService, { enabled: true })
+
+    await expect(ctx.plugin(PlanModeInvariant).then(() => undefined)).rejects.toThrow(/expected a boolean/)
+  })
+})

packages/plan/plan-mode/tests/plan-mode.spec.ts

@@ -0,0 +1,936 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { RUN_CODE_NAME, defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { agentEvents, type Agent, type RequestErrorDecision } from '@deepseek-ai/dsh-agent'
+import { createScope } from '@deepseek-ai/dsh-scope'
+import UserInteractionService, { type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-interaction'
+import CommandService from '@deepseek-ai/dsh-commands'
+import { CodeRuntime, type CodeRunRequest, type CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
+import PlanModeService, { EXIT_PLAN_MODE, foldPlanMode, resolveConfig } from '../src/index.ts'
+import type { PlanModeConfig } from '../src/index.ts'
+
+const TEST_PLAN_SECTION = 'Test plan mode instructions.'
+const PLAN_CONFIG = { section: TEST_PLAN_SECTION } satisfies PlanModeConfig
+
+/**
+ * Drives the REAL plugin: mounts `dsh-plan-mode` beside real `SystemPrompt` and
+ * `ToolRegistry` services, with fake Agents carrying real `Session`s and a
+ * real scoped `agent.ctx` minted through `createScope`.
+ * Turn boundaries are simulated by appending the real boundary events and
+ * dispatching the interception seams the loop fires there. Recovery retries
+ * exercise the separate `agent/request-error` wrapper.
+ */
+
+async function agentWithSession(ctx: Context, id = 'agent-1', { active }: { active?: boolean } = {}): Promise<Agent & { session: Session }> {
+  const session = new Session(SessionId(id))
+  const agent = { id: SessionId(id), session, options: {} } as unknown as Agent & { session: Session }
+  let scoped!: Context
+  await ctx.plugin(Object.assign((inner: Context) => { scoped = createScope(inner, agent).ctx }, {
+    inject: ['tools'],
+  }))
+  ;(agent as { ctx?: Context }).ctx = scoped
+  // Seeded plan state lands before the creation announcement, matching resume.
+  if (active !== undefined) session.append('plan/mode', { active })
+  // The loop announces creation after publication.
+  ctx.emit('agent/created', agent)
+  return agent
+}
+
+/** Assemble exactly as the loop does: the agent is both subject and scope. */
+function assembleFor(ctx: Context, agent: Agent) {
+  return ctx.systemPrompt.assemble({ agent, scope: agent })
+}
+
+async function setup(config: PlanModeConfig = PLAN_CONFIG): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(PlanModeService, config)
+  return ctx
+}
+
+/**
+ * Append a boundary event and dispatch the interception seam the loop fires
+ * there — `agent/prompt-submit` inside the just-opened turn,
+ * `agent/turn-continuation` after the step closed. Recovery retries use the
+ * separately covered `agent/request-error` wrapper; post-commit
+ * `session/event` observers remain observe-only.
+ */
+async function boundary(ctx: Context, agent: Agent & { session: Session }, type: 'turn/start' | 'step/end'): Promise<void> {
+  const events = agentEvents(ctx, agent)
+  if (type === 'turn/start') {
+    agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await events.waterfall('agent/prompt-submit', [{ type: 'text', text: 'boundary probe' }], { kind: 'user' }, new AbortController().signal, () => Promise.resolve({ kind: 'allow' }))
+    return
+  }
+  agent.session.append('step/end', { turn: 1, step: 1 })
+  await events.waterfall('agent/turn-continuation', 1, { action: 'stop' }, new AbortController().signal, () => Promise.resolve({ action: 'stop' }))
+}
+
+/** Dispatch the closed-step recovery seam with one terminal decision. */
+function recoveryBoundary(
+  ctx: Context,
+  agent: Agent & { session: Session },
+  decision: RequestErrorDecision,
+): Promise<RequestErrorDecision> {
+  return agentEvents(ctx, agent).waterfall(
+    'agent/request-error',
+    1,
+    1,
+    new Error('request failed'),
+    { message: 'request failed', code: 'SERVER' },
+    [],
+    new AbortController().signal,
+    () => Promise.resolve(decision),
+  )
+}
+
+/** Append a minimal `request/header` snapshot so the log has a "what the model was told" anchor. */
+function header(session: Session): void {
+  session.append('request/header', { header: { config: { provider: 'test', model: 'test-model' } }, reason: 'initial' })
+}
+
+function noticeTexts(session: Session): string[] {
+  return session.events
+    .filter(event => event.type === 'context/message')
+    .map(event => (event.data as { content: { type: string; text?: string }[] }).content.map(block => block.text ?? '').join(''))
+}
+
+function registerNamedTools(ctx: Context, names: string[]): void {
+  for (const name of names) {
+    ctx.tools.register(defineContentToolFixture({
+      name,
+      description: `test tool ${name}`,
+      parameters: {},
+      execute: () => Promise.resolve([{ type: 'text', text: `ran ${name}` }]),
+    }))
+  }
+}
+
+let callCounter = 0
+function execute(ctx: Context, name: string, agent?: Agent) {
+  return ctx.tools.execute({
+    callId: CallId(`call-${++callCounter}`),
+    name,
+    arguments: {},
+    signal: new AbortController().signal,
+    ...agent ? { agent } : {},
+  })
+}
+
+describe('resolveConfig', () => {
+  it('requires string, non-empty plan instructions', () => {
+    expect(() => resolveConfig({} as PlanModeConfig))
+      .toThrow('needs a string `section`')
+    expect(() => resolveConfig({ section: 5 } as unknown as PlanModeConfig))
+      .toThrow('needs a string `section`')
+    expect(() => resolveConfig({ section: '   ' }))
+      .toThrow('needs a non-empty `section`')
+  })
+
+  it('returns a detached plan config', () => {
+    const config = { section: TEST_PLAN_SECTION }
+    const resolved = resolveConfig(config)
+    expect(resolved).toEqual(config)
+    expect(resolved).not.toBe(config)
+  })
+
+  it('rejects fields outside the plan policy config', () => {
+    expect(() => resolveConfig({ section: TEST_PLAN_SECTION, tools: ['read'] } as unknown as PlanModeConfig))
+      .toThrow('unknown key(s) tools — config is { section }')
+  })
+})
+
+describe('foldPlanMode', () => {
+  it('folds an empty log to inactive and takes the last plan/mode otherwise', () => {
+    const session = new Session(SessionId('fold'))
+    expect(foldPlanMode(session.events)).toBe(false)
+    session.append('plan/mode', { active: true })
+    session.append('plan/mode', { active: false })
+    session.append('plan/mode', { active: true })
+    expect(foldPlanMode(session.events)).toBe(true)
+  })
+
+  it('folds a prefix when `end` is given', () => {
+    const session = new Session(SessionId('fold-prefix'))
+    session.append('plan/mode', { active: true })
+    session.append('plan/mode', { active: false })
+    expect(foldPlanMode(session.events, 1)).toBe(true)
+    expect(foldPlanMode(session.events, 0)).toBe(false)
+  })
+})
+
+describe('ctx.planMode: get/set', () => {
+  it('reads the folded state', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    expect(ctx.planMode.get(agent)).toEqual({ active: false })
+    agent.session.append('plan/mode', { active: true })
+    expect(ctx.planMode.get(agent)).toEqual({ active: true })
+  })
+
+  it('selects inactive as the plan exit target', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    agent.session.append('plan/mode', { active: true })
+    ctx.planMode.set(agent, false)
+    expect(ctx.planMode.get(agent)).toEqual({ active: true, pending: false })
+  })
+
+  it('drops a no-op set (target equals pending, else the current fold)', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, false)
+    expect(ctx.planMode.get(agent)).toEqual({ active: false })
+    ctx.planMode.set(agent, true)
+    ctx.planMode.set(agent, true)
+    expect(ctx.planMode.get(agent)).toEqual({ active: false, pending: true })
+  })
+})
+
+describe('the boundary flush', () => {
+  it('flushes the pending intent as a plan/mode at turn/start', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    await boundary(ctx, agent, 'turn/start')
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+    expect(ctx.planMode.get(agent)).toEqual({ active: true })
+  })
+
+  it('flushes a set() that arrives while a downstream listener is still awaiting (post-next ordering)', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    // A downstream async listener (the shipped hooks listeners' shape): the
+    // selection lands DURING its await — after this boundary began, before it
+    // returns. The prepended flush runs after next(), so the plan/mode still
+    // precedes the request this boundary gates.
+    ctx.on('agent/turn-continuation', async (_agent, _turn, decision, _signal, next) => {
+      await new Promise(resolve => setTimeout(resolve, 5))
+      ctx.planMode.set(agent, true)
+      await next()
+      return decision
+    })
+    agent.session.append('step/end', { turn: 1, step: 1 })
+    await agentEvents(ctx, agent).waterfall(
+      'agent/turn-continuation', 1, { action: 'stop' }, new AbortController().signal,
+      () => Promise.resolve({ action: 'stop' }),
+    )
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+    expect(ctx.planMode.get(agent)).toEqual({ active: true })
+  })
+
+  it('skips the flush after the plugin fiber is disposed (a captured wrapper must not write into a dead service)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    const fiber = await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    // A downstream listener captured before disposal keeps the waterfall
+    // continuation alive across the unload; the resumed wrapper must not
+    // append through the disposed service.
+    ctx.on('agent/turn-continuation', async (_agent, _turn, decision, _signal, next) => {
+      await fiber.dispose()
+      await next()
+      return decision
+    })
+    agent.session.append('step/end', { turn: 1, step: 1 })
+    await agentEvents(ctx, agent).waterfall(
+      'agent/turn-continuation', 1, { action: 'stop' }, new AbortController().signal,
+      () => Promise.resolve({ action: 'stop' }),
+    )
+    expect(agent.session.events.some(event => event.type === 'plan/mode')).toBe(false)
+  })
+
+  it('flushes at step/end too (a mid-turn flip lands on the following step)', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    await boundary(ctx, agent, 'step/end')
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('keeps the pending intent parked when recovery does not retry', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    expect(await recoveryBoundary(ctx, agent, { action: 'fail' })).toEqual({ action: 'fail' })
+    expect(ctx.planMode.get(agent)).toEqual({ active: false, pending: true })
+  })
+
+  it('contains an append failure at the retry boundary without changing its decision', async () => {
+    const ctx = await setup()
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    const original = agent.session.append.bind(agent.session)
+    agent.session.append = (((type: string, ...rest: unknown[]) => {
+      if (type === 'plan/mode') throw new Error('backend gone')
+      return (original as (...args: unknown[]) => unknown)(type, ...rest)
+    }) as unknown) as typeof agent.session.append
+
+    expect(await recoveryBoundary(ctx, agent, { action: 'retry' })).toEqual({ action: 'retry' })
+    expect(warn).toHaveBeenCalledOnce()
+    expect(ctx.planMode.get(agent)).toEqual({ active: false, pending: true })
+  })
+
+  it('nets out a flip sequence that returns to the folded mode (no append, no notice)', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    ctx.planMode.set(agent, false)
+    await boundary(ctx, agent, 'turn/start')
+    expect(agent.session.events.some(event => event.type === 'plan/mode')).toBe(false)
+    expect(noticeTexts(agent.session)).toEqual([])
+  })
+
+  it('narrates nothing before the first request header (the section is the state statement)', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    await boundary(ctx, agent, 'turn/start')
+    expect(noticeTexts(agent.session)).toEqual([])
+  })
+
+  it('narrates once when the flushed mode differs from what the last header told the model', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    header(agent.session)
+    ctx.planMode.set(agent, true)
+    await boundary(ctx, agent, 'turn/start')
+    expect(noticeTexts(agent.session)).toEqual(['The user switched this session to plan mode.'])
+    await boundary(ctx, agent, 'step/end')
+    expect(noticeTexts(agent.session)).toEqual(['The user switched this session to plan mode.'])
+  })
+
+  it('narrates a switch back to the default mode with the default wording', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    agent.session.append('plan/mode', { active: true })
+    header(agent.session)
+    ctx.planMode.set(agent, false)
+    await boundary(ctx, agent, 'step/end')
+    expect(noticeTexts(agent.session)).toEqual(['The user switched this session back to the default mode.'])
+  })
+
+  it('stays silent when the header already reflects the flushed mode', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    agent.session.append('plan/mode', { active: true })
+    header(agent.session)
+    agent.session.append('plan/mode', { active: false })
+    ctx.planMode.set(agent, true)
+    await boundary(ctx, agent, 'step/end')
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+    expect(noticeTexts(agent.session)).toEqual([])
+  })
+
+
+  it('contains an append failure instead of blocking the prompt or the turn', async () => {
+    const ctx = await setup()
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    const original = agent.session.append.bind(agent.session)
+    // Only the flush's own plan/mode append fails; the boundary event itself
+    // lands (the loop appended it before the seam fires).
+    agent.session.append = (((type: string, ...rest: unknown[]) => {
+      if (type === 'plan/mode') throw new Error('backend gone')
+      return (original as (...args: unknown[]) => unknown)(type, ...rest)
+    }) as unknown) as typeof agent.session.append
+    await boundary(ctx, agent, 'step/end')
+    expect(warn).toHaveBeenCalledOnce()
+    // The failed flush re-parks the intent (cleared only after a landed
+    // append), so the next healthy boundary converges the log with the
+    // picker's optimistic state instead of dropping the switch forever.
+    expect(ctx.planMode.get(agent)).toEqual({ active: false, pending: true })
+    agent.session.append = original
+    await boundary(ctx, agent, 'step/end')
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+    expect(ctx.planMode.get(agent).pending).toBeUndefined()
+  })
+
+  it('contains an append failure on the prompt-submit seam the same way', async () => {
+    const ctx = await setup()
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    const agent = await agentWithSession(ctx)
+    ctx.planMode.set(agent, true)
+    const original = agent.session.append.bind(agent.session)
+    agent.session.append = (((type: string, ...rest: unknown[]) => {
+      if (type === 'plan/mode') throw new Error('backend gone')
+      return (original as (...args: unknown[]) => unknown)(type, ...rest)
+    }) as unknown) as typeof agent.session.append
+    await boundary(ctx, agent, 'turn/start')
+    expect(warn).toHaveBeenCalledOnce()
+    expect(ctx.planMode.get(agent)).toEqual({ active: false, pending: true })
+  })
+})
+
+describe('the soft layer', () => {
+  it('keeps the tool schemas identical across default and plan mode', async () => {
+    const ctx = await setup()
+    registerNamedTools(ctx, ['read', 'write'])
+    const agent = await agentWithSession(ctx)
+    const defaultAssembly = await assembleFor(ctx, agent)
+    expect(defaultAssembly.tools.map(tool => tool.name)).toEqual([EXIT_PLAN_MODE, 'read', 'write'])
+    expect(defaultAssembly.sections.find(section => section.name === 'plan:policy')?.text).toBe('')
+
+    agent.session.append('plan/mode', { active: true })
+    const planAssembly = await assembleFor(ctx, agent)
+    expect(planAssembly.tools).toEqual(defaultAssembly.tools)
+    expect(planAssembly.sections.find(section => section.name === 'plan:policy')?.text).toBe(TEST_PLAN_SECTION)
+  })
+
+  it('leaves an agent-less assembly untouched', async () => {
+    const ctx = await setup()
+    registerNamedTools(ctx, ['read'])
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.tools.map(tool => tool.name)).toEqual([EXIT_PLAN_MODE, 'read'])
+    expect(assembly.sections.find(section => section.name === 'plan:policy')?.text).toBe('')
+  })
+
+  it('keeps the full toolset in plan mode and renders the configured mode section', async () => {
+    const ctx = await setup()
+    registerNamedTools(ctx, ['read', 'write', 'todo_write'])
+    const agent = await agentWithSession(ctx, 'agent-1', { active: true })
+    const assembly = await assembleFor(ctx, agent)
+    expect(assembly.tools.map(tool => tool.name).sort()).toEqual([EXIT_PLAN_MODE, 'read', 'todo_write', 'write'])
+    expect(assembly.sections.find(section => section.name === 'plan:policy')?.text).toBe(TEST_PLAN_SECTION)
+  })
+
+  it('leaves foreign assemble additions alone (no assemble-layer filtering)', async () => {
+    // Plan guidance does not filter the registry or later assembly additions.
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    ctx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+      const final = await next()
+      final.tools = [...final.tools, { name: 'added-later', description: 'added after next()', parameters: {} }]
+      return final
+    })
+    await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    registerNamedTools(ctx, ['read'])
+    const planning = await agentWithSession(ctx, 'planning', { active: true })
+    expect((await assembleFor(ctx, planning)).tools.map(tool => tool.name))
+      .toEqual(['exit_plan_mode', 'read', 'added-later'])
+    const defaulted = await agentWithSession(ctx, 'defaulted')
+    expect((await assembleFor(ctx, defaulted)).tools.map(tool => tool.name))
+      .toEqual(['exit_plan_mode', 'read', 'added-later'])
+  })
+
+  it('keeps run_code the only wire tool in plan mode under the registry Code Mode; the SDK gains the exit binding', async () => {
+    // Minimal scriptable runtime: the SDK section resolves ctx.codeRuntime at
+    // assembly time (the code-mode.spec fake's shape).
+    class FakeRuntime extends CodeRuntime {
+      readonly language = 'typescript'
+      readonly isolation = 'fake'
+      run(_request: CodeRunRequest): Promise<CodeRunResult> { return Promise.resolve({ logs: [] }) }
+    }
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry, { mode: 'code' })
+    await ctx.plugin(FakeRuntime)
+    await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    registerNamedTools(ctx, ['read', 'write'])
+    const agent = await agentWithSession(ctx, 'agent-1', { active: true })
+    const assembly = await assembleFor(ctx, agent)
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['run_code'])
+    // The SDK documents the full binding set plus the exit; plan mode never
+    // prunes capabilities and restrains through guidance alone.
+    const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? ''
+    expect(sdk).toContain('read(args:')
+    expect(sdk).toContain('write(args:')
+    expect(sdk).toContain('exit_plan_mode(args:')
+  })
+
+  it('keeps native wire schemas and the SDK in step under mode both', async () => {
+    class FakeRuntime extends CodeRuntime {
+      readonly language = 'typescript'
+      readonly isolation = 'fake'
+      run(_request: CodeRunRequest): Promise<CodeRunResult> { return Promise.resolve({ logs: [] }) }
+    }
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry, { mode: 'both' })
+    await ctx.plugin(FakeRuntime)
+    await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    registerNamedTools(ctx, ['read', 'write'])
+    const agent = await agentWithSession(ctx, 'agent-1', { active: true })
+    const assembly = await assembleFor(ctx, agent)
+    // The stable registry contribution reaches both surfaces: the exit tool
+    // is present on the wire AND in the SDK alongside the untouched toolset.
+    expect(assembly.tools.map(tool => tool.name).sort()).toEqual(['exit_plan_mode', 'read', 'run_code', 'write'])
+    const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? ''
+    expect(sdk).toContain('read(args:')
+    expect(sdk).toContain('write(args:')
+    expect(sdk).toContain('exit_plan_mode(args:')
+  })
+
+  it('keeps the Code Mode SDK byte-identical across mode switches', async () => {
+    class FakeRuntime extends CodeRuntime {
+      readonly language = 'typescript'
+      readonly isolation = 'fake'
+      run(_request: CodeRunRequest): Promise<CodeRunResult> { return Promise.resolve({ logs: [] }) }
+    }
+    const withPlanMode = new Context()
+    await withPlanMode.plugin(SystemPrompt)
+    await withPlanMode.plugin(ToolRegistry, { mode: 'code' })
+    await withPlanMode.plugin(FakeRuntime)
+    await withPlanMode.plugin(PlanModeService, PLAN_CONFIG)
+    registerNamedTools(withPlanMode, ['read', 'write'])
+    const agent = await agentWithSession(withPlanMode)
+    const defaultSdk = (await assembleFor(withPlanMode, agent)).sections.find(section => section.name === 'tools:sdk')?.text ?? ''
+    expect(defaultSdk).toContain('read(args:')
+    expect(defaultSdk).toContain('write(args:')
+    expect(defaultSdk).toContain('exit_plan_mode(args:')
+    agent.session.append('plan/mode', { active: true })
+    const planSdk = (await assembleFor(withPlanMode, agent)).sections.find(section => section.name === 'tools:sdk')?.text ?? ''
+    expect(planSdk).toBe(defaultSdk)
+
+    // Loading the plan-mode plugin deliberately adds one stable binding compared
+    // with a deployment that does not compose plan mode at all.
+    const bare = new Context()
+    await bare.plugin(SystemPrompt)
+    await bare.plugin(ToolRegistry, { mode: 'code' })
+    await bare.plugin(FakeRuntime)
+    registerNamedTools(bare, ['read', 'write'])
+    const bareSdk = (await bare.systemPrompt.assemble({ agent })).sections.find(section => section.name === 'tools:sdk')?.text ?? ''
+    expect(bareSdk).not.toContain('exit_plan_mode(args:')
+    expect(defaultSdk).not.toBe(bareSdk)
+  })
+})
+
+describe('no execution gating beyond the exit tool', () => {
+  it('passes agent-less and default-mode executions through', async () => {
+    const ctx = await setup()
+    registerNamedTools(ctx, ['write'])
+    const agentless = await execute(ctx, 'write')
+    expect(agentless.isError).toBe(false)
+    const agent = await agentWithSession(ctx)
+    const defaulted = await execute(ctx, 'write', agent)
+    expect(defaulted.isError).toBe(false)
+  })
+
+  it('runs every call in plan mode untouched — guidance and enforcement are separate axes', async () => {
+    const ctx = await setup()
+    registerNamedTools(ctx, ['read', 'write', 'bash'])
+    const agent = await agentWithSession(ctx, 'agent-1', { active: true })
+    for (const name of ['read', 'write', 'bash']) {
+      const result = await execute(ctx, name, agent)
+      expect(result.isError).toBe(false)
+    }
+  })
+})
+
+describe('/plan', () => {
+  it('registers only when a commands service is composed and optionally submits the next-step message', async () => {
+    const bare = await setup()
+    expect(bare.get('commands')).toBeUndefined()
+
+    const ctx = await setup()
+    await ctx.plugin(CommandService)
+    // The `ctx.inject` child mounts asynchronously once `commands` resolves.
+    await new Promise(resolve => setImmediate(resolve))
+    const plainAgent = await agentWithSession(ctx, 'plain-plan-command')
+    const plainSteer = vi.fn()
+    ;(plainAgent as unknown as { steer: typeof plainSteer }).steer = plainSteer
+    expect(ctx.commands.list(plainAgent)).toEqual([
+      { name: 'plan', description: 'Enter plan mode', input: { hint: '[message]' } },
+    ])
+
+    const signal = new AbortController().signal
+    expect(await ctx.commands.execute(plainAgent, '/mode', signal)).toBeUndefined()
+    expect(await ctx.commands.execute(plainAgent, '/review', signal)).toBeUndefined()
+    const plain = await ctx.commands.execute(plainAgent, '/plan', signal)
+    expect(plain).toEqual({ kind: 'success', text: 'Entering plan mode (applies from the next step).' })
+    expect(ctx.planMode.get(plainAgent)).toEqual({ active: false, pending: true })
+    expect(plainSteer).not.toHaveBeenCalled()
+
+    const messageAgent = await agentWithSession(ctx, 'message-plan-command')
+    const messageSteer = vi.fn()
+    ;(messageAgent as unknown as { steer: typeof messageSteer }).steer = messageSteer
+    const plan = await ctx.commands.execute(messageAgent, '/plan   draft the migration  ', signal)
+    expect(plan).toEqual({ kind: 'success', text: 'Entering plan mode (applies from the next step).' })
+    expect(ctx.planMode.get(messageAgent)).toEqual({ active: false, pending: true })
+    expect(messageSteer).toHaveBeenCalledExactlyOnceWith([{ type: 'text', text: 'draft the migration' }])
+  })
+
+  it('removes the contributed command when the plan-mode plugin is disposed', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(CommandService)
+    const fiber = await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    await new Promise(resolve => setImmediate(resolve))
+    const agent = await agentWithSession(ctx)
+    expect(ctx.commands.list(agent).map(command => command.name)).toEqual(['plan'])
+
+    await fiber.dispose()
+
+    expect(ctx.commands.list(agent)).toEqual([])
+  })
+})
+
+describe('exit_plan_mode', () => {
+  async function setupWithReview(answer?: { selected: string[]; custom?: string }) {
+    const ctx = await setup()
+    await ctx.plugin(UserInteractionService)
+    const asked: AskUserQuestionRequest[] = []
+    if (answer !== undefined) {
+      ctx.userInteraction.registerProvider({
+        ask: (request) => {
+          asked.push(request)
+          return Promise.resolve({ answers: [{ id: 'plan-review', ...answer }] })
+        },
+      })
+    }
+    const agent = await agentWithSession(ctx, 'agent-1', { active: true })
+    return { ctx, agent, asked }
+  }
+
+  function callExit(ctx: Context, agent: Agent | undefined, plan = '# The plan\n\ndo things') {
+    return ctx.tools.execute({
+      callId: CallId(`call-exit-${++callCounter}`),
+      name: EXIT_PLAN_MODE,
+      arguments: { plan },
+      signal: new AbortController().signal,
+      ...agent ? { agent } : {},
+    })
+  }
+
+  it('registers the tool with one required plan argument', async () => {
+    const ctx = await setup()
+    const schema = ctx.tools.schemas().find(entry => entry.name === EXIT_PLAN_MODE)
+    const parameters = schema?.parameters as { required?: string[]; properties?: Record<string, unknown> }
+    expect(schema?.description).toMatch(/^Use only in plan mode\./)
+    expect(Object.keys(parameters.properties ?? {})).toEqual(['plan'])
+    expect(parameters.required).toEqual(['plan'])
+  })
+
+  it('rejects an agent-less call', async () => {
+    const ctx = await setup()
+    const result = await callExit(ctx, undefined)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: exit_plan_mode requires a calling agent (no session to switch)' }])
+  })
+
+  it('rejects a call outside plan mode while remaining advertised', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx)
+    expect(ctx.tools.schemas().map(tool => tool.name)).toContain(EXIT_PLAN_MODE)
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: exit_plan_mode is only available in plan mode' }])
+  })
+
+  it('rejects an empty or heading-less plan before asking the reviewer', async () => {
+    const { ctx, agent, asked } = await setupWithReview({ selected: ['Approve'] })
+    for (const plan of ['', 'do things']) {
+      const result = await callExit(ctx, agent, plan)
+      expect(result.isError).toBe(true)
+      expect(result.content).toEqual([{ type: 'text', text: 'Error: exit_plan_mode requires a non-empty markdown plan starting with a # heading' }])
+    }
+    expect(asked).toHaveLength(0)
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('degrades to the manual exit when no user-interaction seam is composed', async () => {
+    const ctx = await setup()
+    const agent = await agentWithSession(ctx, 'agent-1', { active: true })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: no user-interaction channel is available to review the plan; ask the user to switch the session mode instead' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('degrades the same way when the seam has no provider (NO_PROVIDER)', async () => {
+    const { ctx, agent } = await setupWithReview()
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: no user-interaction provider is registered' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('approve: records the boundary-applied switch and confirms (the fold flips at the flush)', async () => {
+    const { ctx, agent, asked } = await setupWithReview({ selected: ['Approve'] })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected approved plan result')
+    expect(result.value).toEqual({ approved: true })
+    expect(result.content).toEqual([{ type: 'text', text: 'Plan approved — plan mode exited; carry out the plan starting with your next step.' }])
+    // Boundary-applied, not a direct append: the fold stays plan until the
+    // step's end, so the plan policy covers any remaining call of the SAME batch.
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+    expect(ctx.planMode.get(agent)).toEqual({ active: true, pending: false })
+    await boundary(ctx, agent, 'step/end')
+    expect(foldPlanMode(agent.session.events)).toBe(false)
+    expect(asked).toHaveLength(1)
+    expect(asked[0]?.agent).toBe(agent)
+    expect(asked[0]?.questions[0]?.detail).toBe('# The plan\n\ndo things')
+    expect(asked[0]?.questions[0]?.options?.map(option => option.label)).toEqual(['Approve', 'Keep planning'])
+  })
+
+  it('carries the exact plan through a Code Mode review and logs the nested dispatch', async () => {
+    const plan = '# Code Mode plan\n\nUse the existing seam.'
+    class ExitRuntime extends CodeRuntime {
+      readonly language = 'typescript'
+      readonly isolation = 'fake'
+      async run(request: CodeRunRequest): Promise<CodeRunResult> {
+        const exit = request.bindings[0]?.functions[EXIT_PLAN_MODE]
+        if (exit === undefined) throw new Error('missing exit_plan_mode binding')
+        return { logs: [], value: await exit({ plan }) }
+      }
+    }
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry, { mode: 'code' })
+    await ctx.plugin(ExitRuntime)
+    await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    await ctx.plugin(UserInteractionService)
+    const asked: AskUserQuestionRequest[] = []
+    ctx.userInteraction.registerProvider({
+      ask: (request) => {
+        asked.push(request)
+        return Promise.resolve({ answers: [{ id: 'plan-review', selected: ['Approve'] }] })
+      },
+    })
+    const agent = await agentWithSession(ctx, 'code-mode-exit', { active: true })
+
+    const result = await ctx.tools.execute({
+      callId: CallId(`call-exit-${++callCounter}`),
+      name: RUN_CODE_NAME,
+      arguments: { code: `return await tools.${EXIT_PLAN_MODE}({ plan: ${JSON.stringify(plan)} })` },
+      signal: new AbortController().signal,
+      agent,
+    })
+
+    expect(result.isError).toBe(false)
+    expect(asked).toHaveLength(1)
+    expect(asked[0]?.questions[0]).toMatchObject({
+      header: 'Plan review',
+      question: 'Approve this plan and leave plan mode?',
+      detail: plan,
+    })
+    expect(agent.session.events.find(event => event.type === 'tool/code-dispatch')?.data).toMatchObject({
+      name: EXIT_PLAN_MODE,
+      arguments: { plan },
+      isError: false,
+    })
+    expect(ctx.planMode.get(agent)).toEqual({ active: true, pending: false })
+  })
+
+  it('an approved exit keeps plan guidance until the boundary and never removes the tool', async () => {
+    const { ctx, agent } = await setupWithReview({ selected: ['Approve'] })
+    const approved = await callExit(ctx, agent)
+    expect(approved.isError).toBe(false)
+    // Calls of the SAME assistant response (no boundary between) were
+    // requested under the plan-shaped header — the fold stays plan for that
+    // whole batch; the boundary flush is what flips the next step.
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+    const assembly = await ctx.systemPrompt.assemble({ agent })
+    expect(assembly.tools.some(tool => tool.name === EXIT_PLAN_MODE)).toBe(true)
+    expect(assembly.sections.find(section => section.name === 'plan:policy')?.text).toBe(TEST_PLAN_SECTION)
+    await boundary(ctx, agent, 'step/end')
+    expect(foldPlanMode(agent.session.events)).toBe(false)
+    const afterExit = await ctx.systemPrompt.assemble({ agent })
+    expect(afterExit.tools).toEqual(assembly.tools)
+    expect(afterExit.sections.find(section => section.name === 'plan:policy')?.text).toBe('')
+  })
+
+  it('the exit flush narrates nothing — the tool result is the narration', async () => {
+    const { ctx, agent } = await setupWithReview({ selected: ['Approve'] })
+    header(agent.session)
+    await callExit(ctx, agent)
+    await boundary(ctx, agent, 'step/end')
+    expect(foldPlanMode(agent.session.events)).toBe(false)
+    expect(noticeTexts(agent.session)).toEqual([])
+  })
+
+  it('keep planning returns the corrective error carrying the feedback verbatim', async () => {
+    const { ctx, agent } = await setupWithReview({ selected: ['Keep planning'], custom: 'consider the resume path' })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; their feedback: consider the resume path' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('keep planning without feedback returns the generic corrective error', async () => {
+    const { ctx, agent } = await setupWithReview({ selected: ['Keep planning'] })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; revise the plan and present it again.' }])
+  })
+
+  it('a custom-text-only answer is feedback, never consent', async () => {
+    const { ctx, agent } = await setupWithReview({ selected: [], custom: 'add tests first' })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; their feedback: add tests first' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('requires exactly the single Approve selection', async () => {
+    const { ctx, agent } = await setupWithReview({ selected: ['Approve', 'Keep planning'] })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; revise the plan and present it again.' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('treats custom text alongside Approve as feedback, not consent', async () => {
+    const { ctx, agent } = await setupWithReview({ selected: ['Approve'], custom: 'change the tests' })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; their feedback: change the tests' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('treats duplicate review answer items as non-consent', async () => {
+    const { ctx, agent } = await setupWithReview()
+    ctx.userInteraction.registerProvider({
+      ask: () => Promise.resolve({ answers: [
+        { id: 'plan-review', selected: ['Approve'] },
+        { id: 'plan-review', selected: ['Keep planning'] },
+      ] }),
+    })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; revise the plan and present it again.' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('a missing answer item reads as keep-planning', async () => {
+    const { ctx, agent } = await setupWithReview()
+    ctx.userInteraction.registerProvider({ ask: () => Promise.resolve({ answers: [] }) })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; revise the plan and present it again.' }])
+  })
+
+  it('forwards the execution abort signal to the review question', async () => {
+    const { ctx, agent, asked } = await setupWithReview({ selected: ['Approve'] })
+    const controller = new AbortController()
+    const result = await ctx.tools.execute({
+      callId: CallId(`call-exit-${++callCounter}`),
+      name: EXIT_PLAN_MODE,
+      arguments: { plan: '# P' },
+      agent,
+      signal: controller.signal,
+    })
+    expect(result.isError).toBe(false)
+    expect(asked[0]?.signal).toBe(controller.signal)
+  })
+
+  it('fails the call when the plugin is disposed while the review awaits (no phantom exit)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    const fiber = await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    await ctx.plugin(UserInteractionService)
+    let answer!: (value: { answers: { id: string; selected: string[] }[] }) => void
+    ctx.userInteraction.registerProvider({
+      ask: () => new Promise((resolve) => { answer = resolve }),
+    })
+    const agent = await agentWithSession(ctx, 'agent-1', { active: true })
+    const pending = callExit(ctx, agent)
+    // Let execute reach the review await, then unload the plugin (HMR) and
+    // only afterwards approve. The boundary listeners are gone, so a success
+    // would claim an exit that can never flush — the call must fail instead.
+    await new Promise(resolve => setImmediate(resolve))
+    await fiber.dispose()
+    answer({ answers: [{ id: 'plan-review', selected: ['Approve'] }] })
+    const result = await pending
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: the plan-mode service was reloaded while the plan was under review; present the plan again' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('a throwing provider surfaces as the corrective isError and the mode stays plan', async () => {
+    const { ctx, agent } = await setupWithReview()
+    ctx.userInteraction.registerProvider({ ask: () => { throw new Error('review aborted') } })
+    const result = await callExit(ctx, agent)
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Error: review aborted' }])
+    expect(foldPlanMode(agent.session.events)).toBe(true)
+  })
+
+  it('presents the call as a generic card titled by the plan first heading', async () => {
+    const ctx = await setup()
+    const def = ctx.tools.get(EXIT_PLAN_MODE)!
+    expect(def.presentCall?.({ plan: '## Fix the flake\n\nsteps' })).toEqual({
+      card: 'generic',
+      title: 'Fix the flake',
+      kind: 'other',
+      content: [{ type: 'text', text: '## Fix the flake\n\nsteps' }],
+    })
+    expect(def.presentCall?.({ plan: 'no heading here' })).toEqual({
+      card: 'generic',
+      title: 'Plan',
+      kind: 'other',
+      content: [{ type: 'text', text: 'no heading here' }],
+    })
+  })
+
+  it('presents the result as a generic review card', async () => {
+    const ctx = await setup()
+    const def = ctx.tools.get(EXIT_PLAN_MODE)!
+    const content = [{ type: 'text' as const, text: 'ok' }]
+    expect(def.presentResult?.({ plan: '# P' }, { content, isError: false })).toEqual({
+      card: 'generic',
+      title: 'Plan review',
+      content,
+    })
+  })
+})
+
+describe('HMR disposal', () => {
+  it('does not flush a retry boundary that resumes after plugin disposal', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    const fiber = await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    const agent = await agentWithSession(ctx, 'disposed-in-flight-recovery')
+    const recoveryEntered = Promise.withResolvers<true>()
+    const releaseRecovery = Promise.withResolvers<true>()
+    ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _failure, _history, _signal, _next) => {
+      recoveryEntered.resolve(true)
+      await releaseRecovery.promise
+      return { action: 'retry' }
+    })
+    ctx.planMode.set(agent, true)
+
+    const recovery = recoveryBoundary(ctx, agent, { action: 'fail' })
+    await recoveryEntered.promise
+    await fiber.dispose()
+    releaseRecovery.resolve(true)
+
+    expect(await recovery).toEqual({ action: 'retry' })
+    expect(agent.session.events.some(event => event.type === 'plan/mode')).toBe(false)
+  })
+
+  it('unregisters the service, listeners, prompt section, and stable exit tool with the plugin fiber', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    const fiber = await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    const agent = await agentWithSession(ctx, 'disposed-recovery')
+    ctx.planMode.set(agent, true)
+    expect(ctx.get('planMode')).toBeInstanceOf(PlanModeService)
+    expect(ctx.tools.get(EXIT_PLAN_MODE)).toBeDefined()
+    expect((await ctx.systemPrompt.assemble()).sections.map(section => section.name)).toContain('plan:policy')
+
+    await fiber.dispose()
+    expect(ctx.get('planMode')).toBeUndefined()
+    expect(ctx.tools.get(EXIT_PLAN_MODE)).toBeUndefined()
+    expect((await ctx.systemPrompt.assemble()).sections.map(section => section.name)).not.toContain('plan:policy')
+    expect(await recoveryBoundary(ctx, agent, { action: 'retry' })).toEqual({ action: 'retry' })
+    expect(agent.session.events.some(event => event.type === 'plan/mode')).toBe(false)
+  })
+})

packages/plan/plan-mode/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../ui/user-interaction"
+    },
+    {
+      "path": "../../ui/commands"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -125,6 +125,11 @@ function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId):
   if (legacy !== undefined) {
     throw new Error(`session "${id}" contains unsupported legacy request/header-delta event at seq ${legacy.seq}`)
   }
+  const legacyModeType: string = 'mode/set'
+  const legacyMode = events.find(event => event.type === legacyModeType)
+  if (legacyMode !== undefined) {
+    throw new Error(`session "${id}" contains unsupported legacy mode/set event at seq ${legacyMode.seq}`)
+  }
   const fallback = events.find(event => event.type === 'request/header'
     && (event.data as { reason?: string }).reason === 'fallback')
   if (fallback !== undefined) {

packages/session-persistence/session-persistence/tests/persistence.spec.ts

@@ -22,6 +22,16 @@ function legacyHeaderDelta(seq = 0): SessionEvent {
   } as unknown as SessionEvent
 }
 
+/** An unsupported named-mode fixture emulating an untyped producer. */
+function legacyModeSet(seq = 0): SessionEvent {
+  return {
+    type: 'mode/set',
+    seq,
+    time: 1,
+    data: { mode: 'plan' },
+  } as unknown as SessionEvent
+}
+
 /** An obsolete full-header reason fixture from the removed delta codec. */
 function legacyFallbackHeader(seq = 0): SessionEvent {
   return {
@@ -510,6 +520,19 @@ describe('SessionPersistence service registration', () => {
     await fiber.dispose()
   })
 
+  it('rejects a stored legacy named-mode event during load', async () => {
+    const id = SessionId('legacy-mode-load')
+    const m = meta(id, '/legacy')
+    const store: MemoryStore = new Map([[id, { meta: m, events: [legacyModeSet()] }]])
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(MemoryPersistence, { store })
+
+    await expect(ctx.sessionPersistence.load(id))
+      .rejects.toThrow('unsupported legacy mode/set event at seq 0')
+    await fiber.dispose()
+  })
+
   it('retires all coordinator bookkeeping for disposed sessions', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)

packages/skill/skill-local/tests/skill-local.spec.ts

@@ -391,6 +391,9 @@ describe('LocalSkillProvider', () => {
       await empty.plugin(SkillService)
       SkillLocal.apply(empty, {})
       expect(await empty.skills.list()).toEqual([])
+
+      delete process.env.DSH_AGENTS_HOME
+      expect(new SkillLocal.LocalSkillProvider(empty, { dshHome: join(envHome, 'empty-dsh') }).name).toBe('local')
     } finally {
       if (previousDshHome === undefined) {
         delete process.env.DSH_HOME

packages/support/acp-snapshot/src/harness.ts

@@ -24,6 +24,8 @@ import { basename, dirname, join, delimiter } from 'node:path'
 import {
   ClientSideConnection,
   PROTOCOL_VERSION,
+  type CreateElicitationRequest,
+  type CreateElicitationResponse,
   type RequestPermissionRequest,
   type RequestPermissionResponse,
   type SessionNotification,
@@ -59,6 +61,8 @@ export type InputStep =
     waitForToolCallUpdate?: string
   }
   | { op: 'cancel' }
+  | { op: 'setMode'; modeId: string }
+  | { op: 'setModeExpectError'; modeId: string }
   | { op: 'setConfigOption'; configId: string; value: string }
   | { op: 'setConfigOptionExpectError'; configId: string; value: string }
 
@@ -78,6 +82,16 @@ export interface InputScript {
    * agent itself just sees `cancelled`, so it cannot absorb the bug).
    */
   permissionAnswers?: PermissionAnswer[]
+  /**
+   * Ordered answers for the agent's `elicitation/create` round-trips (the
+   * ask_user_question / plan-review forms), consumed FIFO — the Nth request
+   * gets the Nth answer. Exhaustion (or no queue) answers `cancel`, the same
+   * fail-closed stub an elicitation-free scenario relies on. Unlike permission
+   * kinds, the scripted strings are not validated against the offered form —
+   * a stray `choice` reaches the agent verbatim, which reads it as a custom
+   * (non-consenting) answer, so a scenario bug fails safe in the transcript.
+   */
+  elicitationAnswers?: ElicitationAnswer[]
 }
 
 /** One scripted answer to a permission request: which offered option kind to select. */
@@ -86,6 +100,16 @@ export interface PermissionAnswer {
   kind: 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always'
 }
 
+/** One scripted answer to an elicitation form (accept with choice/custom content, or cancel). */
+export interface ElicitationAnswer {
+  /** Accept the form with the content below, or cancel it. */
+  action: 'accept' | 'cancel'
+  /** The selected option label (the form's `choice` field). */
+  choice?: string
+  /** Free-form text (the form's `custom` field). */
+  custom?: string
+}
+
 /** One harvested session log plus the identifying facts off its header line. */
 export interface HarvestedLog {
   /** The recorded session id (header `id`). */
@@ -215,6 +239,8 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
     // Permission answers are consumed FIFO across the whole run; exhaustion
     // falls back to `cancelled` so approval-free scenarios keep the plain stub.
     const permissionQueue = [...input.permissionAnswers ?? []]
+    // Elicitation answers mirror the permission queue: FIFO, cancel on exhaustion.
+    const elicitationQueue = [...input.elicitationAnswers ?? []]
     // A scenario bug detected inside a client callback (a scripted permission
     // kind the agent never offered). It cannot fail the run from in there: a
     // callback throw only becomes a JSON-RPC error RESPONSE to the agent, and
@@ -244,6 +270,17 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
         }
         return Promise.resolve({ outcome: { outcome: 'selected', optionId: option.optionId } })
       },
+      createElicitation(_params: CreateElicitationRequest): Promise<CreateElicitationResponse> {
+        const answer = elicitationQueue.shift()
+        if (answer === undefined || answer.action !== 'accept') return Promise.resolve({ action: 'cancel' })
+        return Promise.resolve({
+          action: 'accept',
+          content: {
+            ...answer.choice !== undefined ? { choice: answer.choice } : {},
+            ...answer.custom !== undefined ? { custom: answer.custom } : {},
+          },
+        })
+      },
     })
     const active = launched
     await active.spawned
@@ -399,6 +436,24 @@ async function runStep(
       await client.cancel({ sessionId })
       return
     }
+    case 'setMode': {
+      const sessionId = getSessionId()
+      if (sessionId === undefined) throw new Error('snapshot-harness: setMode before newSession')
+      await client.setSessionMode({ sessionId, modeId: step.modeId })
+      return
+    }
+    case 'setModeExpectError': {
+      const sessionId = getSessionId()
+      if (sessionId === undefined) throw new Error('snapshot-harness: setModeExpectError before newSession')
+      // The bridge rejects an unknown/uncomposed mode id with invalidParams;
+      // that rejection IS the expected wire behavior — swallow it so the run
+      // completes and the error frame is captured in the transcript.
+      await client.setSessionMode({ sessionId, modeId: step.modeId }).then(
+        () => { throw new Error('snapshot-harness: expected session/set_mode to be rejected but it succeeded') },
+        () => { /* expected: the bridge rejected the mode id */ },
+      )
+      return
+    }
     case 'setConfigOption': {
       const sessionId = getSessionId()
       if (sessionId === undefined) throw new Error('snapshot-harness: setConfigOption before newSession')

packages/support/acp-snapshot/src/index.ts

@@ -18,6 +18,7 @@
 
 export {
   runScenario,
+  type ElicitationAnswer,
   type HarvestedLog,
   type InputScript,
   type InputStep,

packages/support/acp-snapshot/src/launcher.ts

@@ -15,6 +15,8 @@ import {
   ndJsonStream,
   type Agent as AcpAgent,
   type Client,
+  type CreateElicitationRequest,
+  type CreateElicitationResponse,
   type RequestPermissionRequest,
   type RequestPermissionResponse,
   type SessionNotification,
@@ -47,6 +49,8 @@ export interface AcpTestLaunchOptions {
   env?: NodeJS.ProcessEnv
   /** Permission handler; omitted requests fail closed as `cancelled`. */
   requestPermission?: (params: RequestPermissionRequest) => Promise<RequestPermissionResponse>
+  /** Elicitation handler; omitted requests fail closed as `cancel`. */
+  createElicitation?: (params: CreateElicitationRequest) => Promise<CreateElicitationResponse>
 }
 
 /** A running ACP test process and its captured client-side surfaces. */
@@ -152,6 +156,8 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
   }
   const requestPermission = options.requestPermission
     ?? (() => Promise.resolve({ outcome: { outcome: 'cancelled' as const } }))
+  const createElicitation = options.createElicitation
+    ?? (() => Promise.resolve({ action: 'cancel' as const }))
   const makeClient = (_agent: AcpAgent): Client => ({
     sessionUpdate(params: SessionNotification): Promise<void> {
       return trackClientCallback(() => {
@@ -175,6 +181,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
       })
     },
     requestPermission: params => trackClientCallback(() => requestPermission(params)),
+    unstable_createElicitation: params => trackClientCallback(() => createElicitation(params)),
   })
   const client = new ClientSideConnection(makeClient, stream)
   // `exit` only reports the parent process's status. Descendants may retain

packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts

@@ -1,7 +1,19 @@
 /**
- * Scripted ACP agent for snapshot-kit tests. A fixture-adjacent `behavior.json` controls the
- * subprocess reached through the real harness path; the bin reports observations over ACP and
- * writes scripted logs before exiting on stdin EOF.
+ * Scripted fake ACP agent bin for `dsh-acp-snapshot`'s unit specs. Speaks
+ * newline-delimited JSON-RPC on stdio like the real `dsh-acp-agent` bin, but
+ * every behavior — how prompts settle, whether session/new rejects, which
+ * session logs get persisted, what filesystem noise to leave — comes from a
+ * `behavior.json` sitting NEXT to the `$DSH_SNAPSHOT_FILE` fixture, so a spec
+ * scripts a whole subprocess run from data. The specs launch it through the
+ * REAL `runScenario` spawn path (tsx loader, temp cwd, env plumbing), so the
+ * harness plumbing is exercised for real; only the agent behind the protocol
+ * is scripted.
+ *
+ * The specs (not the golden tier) own this bin: it asserts nothing, echoes
+ * observable facts into `session/update` text chunks (env probe, permission
+ * outcome, seeded-workspace listing) for the spec to read off `rawStdout`, and
+ * exits 0 on stdin EOF after writing the scripted logs — mirroring the real
+ * bin's dispose-flush-exit shape.
  */
 
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
@@ -39,6 +51,10 @@ interface Behavior {
   cancelToolCallUpdate?: boolean
   /** Before responding to a prompt, send a `session/request_permission` request and echo its outcome as a chunk. */
   permissionProbe?: boolean
+  /** Before responding to a prompt, send an `elicitation/create` request and echo its response as a chunk. */
+  elicitationProbe?: boolean
+  /** How `session/set_mode` settles: an empty response (echoing the modeId as a chunk) or a JSON-RPC error. */
+  setMode?: 'respond' | 'error'
   /** Echo the `DSH_SNAPSHOT_*` env the harness set as a chunk (spec-side env-plumbing assertions). */
   echoEnv?: boolean
   /** Echo the sorted cwd listing as a chunk (spec-side workspace-seeding assertions). */
@@ -84,8 +100,8 @@ let sessionId = ''
 let sessionCwd = ''
 /** The parked prompt request id while `hang-until-cancel` waits for the cancel notification. */
 let parkedPromptId: number | string | null = null
-/** Resolvers for permission-probe responses, keyed by outbound request id. */
-const pendingPermission = new Map<number, (outcome: unknown) => void>()
+/** Resolvers for outbound probe responses (permission/elicitation), keyed by request id. */
+const pendingOutbound = new Map<number, (result: unknown) => void>()
 /** Per-run `session/set_config_option` state: config id → current value (first vocabulary entry until set). */
 const currentConfig: Record<string, string> = {}
 
@@ -160,8 +176,8 @@ async function handlePrompt(id: number | string): Promise<void> {
   }
   if (behavior.permissionProbe === true) {
     const requestId = nextOutboundId++
-    const outcome = await new Promise<unknown>((resolve) => {
-      pendingPermission.set(requestId, resolve)
+    const result = await new Promise<unknown>((resolve) => {
+      pendingOutbound.set(requestId, resolve)
       send({
         id: requestId,
         method: 'session/request_permission',
@@ -175,7 +191,24 @@ async function handlePrompt(id: number | string): Promise<void> {
         },
       })
     })
-    chunk(`permission:${JSON.stringify(outcome)}`)
+    chunk(`permission:${JSON.stringify((result as { outcome?: unknown } | undefined)?.outcome ?? null)}`)
+  }
+  if (behavior.elicitationProbe === true) {
+    const requestId = nextOutboundId++
+    const result = await new Promise<unknown>((resolve) => {
+      pendingOutbound.set(requestId, resolve)
+      send({
+        id: requestId,
+        method: 'elicitation/create',
+        params: {
+          sessionId,
+          mode: 'form',
+          message: 'Approve this plan and leave plan mode?',
+          requestedSchema: { type: 'object', title: 'Plan review', properties: { choice: { type: 'string' }, custom: { type: 'string' } }, required: [] },
+        },
+      })
+    })
+    chunk(`elicitation:${JSON.stringify(result ?? null)}`)
   }
   switch (behavior.prompt ?? 'respond') {
     case 'respond':
@@ -195,10 +228,10 @@ function handleFrame(frame: Record<string, unknown>): void {
   const method = frame.method as string | undefined
   const params = (frame.params ?? {}) as Record<string, unknown>
   // A response to one of OUR outbound requests (the permission probe).
-  if (method === undefined && id !== undefined && typeof id === 'number' && pendingPermission.has(id)) {
-    const resolve = pendingPermission.get(id) as (outcome: unknown) => void
-    pendingPermission.delete(id)
-    resolve((frame.result as { outcome?: unknown } | undefined)?.outcome ?? null)
+  if (method === undefined && id !== undefined && typeof id === 'number' && pendingOutbound.has(id)) {
+    const resolve = pendingOutbound.get(id) as (result: unknown) => void
+    pendingOutbound.delete(id)
+    resolve(frame.result)
     return
   }
   switch (method) {
@@ -219,6 +252,14 @@ function handleFrame(frame: Record<string, unknown>): void {
     case 'session/prompt':
       void handlePrompt(id as number | string)
       return
+    case 'session/set_mode':
+      if ((behavior.setMode ?? 'respond') === 'error') {
+        respondError(id as number | string, 'unknown mode')
+        return
+      }
+      chunk(`setMode:${String(params.modeId)}`)
+      respond(id as number | string, {})
+      return
     case 'session/set_config_option': {
       const vocabulary = behavior.configOptions
       const configId = params.configId as string

packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/session.1.jsonl

@@ -0,0 +1,2 @@
+{"type":"session","id":"abababab-cdcd-4efe-8ada-badabadabada","createdAt":800,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-KBQJbW","parentSession":"f6fa7fcf-dd9c-4b39-8815-b25ddcebfd88"}
+{"type":"request/header","seq":0,"time":2,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}

packages/support/acp-snapshot/tests/harness.spec.ts

@@ -95,8 +95,8 @@ describe('runScenario', () => {
     expect(clientClosed).toBe(true)
   })
 
-  it('centralizes ACP boot, captures, updates, fail-closed permissions, and shutdown', { timeout: 20_000 }, async () => {
-    const { dir, fixtureFile } = await scenario({ permissionProbe: true, echoEnv: true, stderrNote: 'launcher stderr' })
+  it('centralizes ACP boot, captures, updates, fail-closed interactions, and shutdown', { timeout: 20_000 }, async () => {
+    const { dir, fixtureFile } = await scenario({ permissionProbe: true, elicitationProbe: true, echoEnv: true, stderrNote: 'launcher stderr' })
     const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-launcher-sessions-'))
     tempDirs.push(sessionsRoot)
     const launched = launchAcpTestAgent({
@@ -120,6 +120,7 @@ describe('runScenario', () => {
     expect((await nextChunk).sessionUpdate).toBe('agent_message_chunk')
     expect(launched.updates.some(update => update.sessionUpdate === 'agent_message_chunk')).toBe(true)
     expect(launched.rawStdout()).toContain('permission:{\\"outcome\\":\\"cancelled\\"}')
+    expect(launched.rawStdout()).toContain('elicitation:{\\"action\\":\\"cancel\\"}')
     expect(launched.stderr()).toContain('launcher stderr')
     const unmatched = expect(launched.waitForUpdate(() => false)).rejects.toThrow(/update stream closed/)
     await launched.close()
@@ -716,6 +717,69 @@ describe('runScenario', () => {
     expect(result.sessionLogs).toHaveLength(0)
   })
 
+  it('drives session/set_mode and swallows the expected rejection of setModeExpectError', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({})
+    const result = await runScenario(
+      { steps: [...boot, { op: 'setMode', modeId: 'plan' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.rawStdout).toContain('setMode:plan')
+
+    const rejecting = await scenario({ setMode: 'error' })
+    const rejected = await runScenario(
+      { steps: [...boot, { op: 'setModeExpectError', modeId: 'yolo' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile: rejecting.fixtureFile },
+    )
+    expect(rejected.rawStdout).toContain('unknown mode')
+  })
+
+  it('fails the run when setModeExpectError unexpectedly succeeds, and both mode ops require a session', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({})
+    await expect(runScenario(
+      { steps: [...boot, { op: 'setModeExpectError', modeId: 'plan' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(/expected session\/set_mode to be rejected/)
+    await expect(runScenario(
+      { steps: [{ op: 'initialize' }, { op: 'setMode', modeId: 'plan' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(/setMode before newSession/)
+    await expect(runScenario(
+      { steps: [{ op: 'initialize' }, { op: 'setModeExpectError', modeId: 'plan' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(/setModeExpectError before newSession/)
+  })
+
+  it('answers elicitations from the scripted queue, falling back to cancel on exhaustion', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ elicitationProbe: true })
+    // Three prompts → three elicitations: an accept-with-choice, an
+    // accept-with-custom (feedback), then the exhausted-queue cancel.
+    const result = await runScenario(
+      {
+        steps: [...boot, { op: 'prompt', text: 'one' }, { op: 'prompt', text: 'two' }, { op: 'prompt', text: 'three' }],
+        elicitationAnswers: [
+          { action: 'accept', choice: 'Approve' },
+          { action: 'accept', custom: 'add tests first' },
+        ],
+      },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    const first = result.rawStdout.indexOf('elicitation:{\\"action\\":\\"accept\\",\\"content\\":{\\"choice\\":\\"Approve\\"}}')
+    const second = result.rawStdout.indexOf('elicitation:{\\"action\\":\\"accept\\",\\"content\\":{\\"custom\\":\\"add tests first\\"}}')
+    const third = result.rawStdout.indexOf('elicitation:{\\"action\\":\\"cancel\\"}')
+    expect(first).toBeGreaterThanOrEqual(0)
+    expect(second).toBeGreaterThan(first)
+    expect(third).toBeGreaterThan(second)
+  })
+
+  it('a scripted elicitation cancel answers cancel', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ elicitationProbe: true })
+    const result = await runScenario(
+      { steps: [...boot, { op: 'prompt', text: 'one' }], elicitationAnswers: [{ action: 'cancel' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.rawStdout).toContain('elicitation:{\\"action\\":\\"cancel\\"}')
+  })
+
   it('answers permission requests from the scripted queue by option kind, falling back to cancelled', { timeout: 20_000 }, async () => {
     const { fixtureFile } = await scenario({ permissionProbe: true })
     // Two prompts → two permission round-trips; one scripted answer, so the
@@ -744,8 +808,11 @@ describe('runScenario', () => {
 
   it('rejects the run on a scripted permission kind the agent never offered', { timeout: 20_000 }, async () => {
     const { fixtureFile } = await scenario({ permissionProbe: true })
-    // The fake offers only allow_once/reject_once. The harness must reject an impossible click,
-    // not merely send an RPC error that a tolerant agent could absorb.
+    // The fake bin offers allow_once/reject_once; scripting allow_always is a
+    // scenario bug. The agent is answered `cancelled` (it must not be able to
+    // absorb the bug as an error-means-denial), and the RUN fails: a callback
+    // throw would only reach the agent as a JSON-RPC error response, letting
+    // a tolerant agent carry on and the scenario pass — or record.
     await expect(runScenario(
       { steps: [...boot, { op: 'prompt', text: 'impossible click' }], permissionAnswers: [{ kind: 'allow_always' }] },
       { agent: AGENT, mode: 'replay', fixtureFile },

packages/support/loader-smoke/src/index.ts

@@ -138,8 +138,6 @@ export interface LoaderSmokeOptions {
   readonly mode?: ExampleMode
   /** Environment overrides layered over the parent and isolated DSH homes. */
   readonly env?: Readonly<NodeJS.ProcessEnv>
-  /** Lines written to stdin before EOF; omitted means immediate EOF. */
-  readonly stdinLines?: readonly string[]
   /** Process deadline override for harness tests. */
   readonly processTimeoutMs?: number
   /** Optional world-state setup run in the isolated cwd before process start. */
@@ -157,10 +155,10 @@ export interface LoaderSmokeResult {
 }
 
 /**
- * Boot one real Loader tree from an isolated cwd, write the requested stdin
- * script, close stdin, and await a clean exit. The helper owns process kill and
- * temp-directory cleanup on every outcome, and picks src/lib via {@link resolveExampleLaunch}.
- * @param options - example paths, mode, environment, stdin, and diagnostic identity.
+ * Boot one real Loader tree from an isolated cwd, close stdin immediately, and
+ * await a clean exit. The helper owns process kill and temp-directory cleanup on
+ * every outcome, and picks src/lib via {@link resolveExampleLaunch}.
+ * @param options - example paths, mode, environment, and diagnostic identity.
  * @returns captured stdout and stderr after a zero exit.
  */
 export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise<LoaderSmokeResult> {
@@ -220,7 +218,7 @@ export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise<Loade
       })
       /* v8 ignore stop */
 
-      child.stdin.end((options.stdinLines ?? []).map(line => `${line}\n`).join(''))
+      child.stdin.end()
     })
     await options.inspect?.(cwd)
     return result

packages/support/loader-smoke/tests/loader-smoke.spec.ts

@@ -11,7 +11,7 @@ const fixture = (name: string): string => fileURLToPath(new URL(`./fixtures/${na
 const canonicalTempPath = (path: string): string => path.replace(/^\/private(?=\/var\/)/, '')
 
 describe('runLoaderSmoke', () => {
-  it('isolates the process, writes stdin, captures output, and removes the cwd', async () => {
+  it('isolates the process, closes stdin, captures output, and removes the cwd', async () => {
     const result = await runLoaderSmoke({
       label: 'success fixture',
       tempDirPrefix: 'loader-smoke-success-',
@@ -20,7 +20,6 @@ describe('runLoaderSmoke', () => {
       tsconfigPath,
       mode: 'src',
       env: { LOADER_SMOKE_MARKER: 'present' },
-      stdinLines: ['one', 'two'],
     })
     const output = JSON.parse(result.stdout) as {
       configPath: string
@@ -35,7 +34,7 @@ describe('runLoaderSmoke', () => {
       configPath,
       args: [configPath],
       marker: 'present',
-      input: 'one\ntwo\n',
+      input: '',
     })
     expect(canonicalTempPath(output.dshHome)).toBe(canonicalTempPath(join(output.cwd, '.dsh')))
     expect(canonicalTempPath(output.agentsHome)).toBe(canonicalTempPath(join(output.cwd, '.agents')))

packages/ui/acp/acp-feature-support.md

@@ -10,7 +10,7 @@ Legend: ✅ supported · ⚠️ partial / fallback · ❌ not yet · — n/a. Th
 
 ## At a glance
 
-The bridge implements the **core prompt-turn loop** for N concurrent sessions: initialize, session new/load, prompt, cancel, streamed assistant/thought chunks, tool-call rendering (including Zed terminal cards), resumable session replay, slash commands, one-shot permission prompts, per-session model selection, and permission presets. The largest **unbuilt** areas are **MCP passthrough** and **agent plans**, plus the client **filesystem** and **terminal** method families (which the adapters mostly do NOT drive either — see rows 43-49). See [Gap summary](#gap-summary).
+The bridge implements the **core prompt-turn loop** for N concurrent sessions: initialize, session new/load, prompt, cancel, streamed assistant/thought chunks, tool-call rendering (including Zed terminal cards), resumable session replay, slash commands, one-shot permission prompts, per-session model selection and permission presets, and **session modes** (the picker, via `@deepseek-ai/dsh-plan-mode`). The largest **unbuilt** areas are **MCP passthrough** and **agent plans**, plus the client **filesystem** and **terminal** method families (which the adapters mostly do NOT drive either — see rows 43-49). See [Gap summary](#gap-summary).
 
 ## 1. Agent methods (client → agent)
 
@@ -25,7 +25,7 @@ The bridge implements the **core prompt-turn loop** for N concurrent sessions: i
 | `session/close` | S | ❌ | ✅ | ✅ | No `session/close` handler — the SDK dispatch returns `method_not_found`. The bridge tears sessions down on client disconnect / Cordis disposal (cross-cutting, see [§8](#8-cross-cutting)), but that is not the on-demand per-session method. |
 | `session/prompt` | S | ✅ | ✅ | ✅ | A flattened prompt beginning with `/` dispatches through `ctx.commands` without a model request; ordinary input maps to `agent.send`. One request is in flight per session. |
 | `session/cancel` | S | ✅ | ✅ | ✅ | Aborts the exact direct command, or applies queue-aware `agent.cancel` and settles its prompt `cancelled`, scoped to one session. |
-| `session/set_mode` | S | ❌ | ✅ | ✅ | Session modes deliberately skipped: config options are the spec's replacement and modes are slated for removal in ACP v2 (see [§6](#6-session-modes--config-options--models)). |
+| `session/set_mode` | S | ✅ | ✅ | ✅ | Composed opportunistically: with `@deepseek-ai/dsh-plan-mode` mounted, `session/new`/`session/load` advertise the fixed `default` / `plan` projection and `session/set_mode` records the boolean pending intent (optimistic `current_mode_update`; logged `plan/mode` lands at the turn boundary). Without the plugin: no `modes` advertised, `set_mode` rejected (see [§6 Modes](#6-session-modes--config-options--models)). |
 | `session/set_config_option` | S | ✅ | ✅ | ✅ | A provider/model select is present for a complete registered target; one `permission` select is added when `ctx.permission` is composed. Every response carries the complete refreshed state. |
 | model selection | S | ✅ | ✅ | ✅ | No distinct stable `session/set_model` — model is the `model`-category `session/set_config_option`. Values preserve the provider/model pair, catalogs come from `ctx.llm`, selection is per session, and `session/load` restores the last requested pair. Codex also supports the legacy `unstable_setSessionModel` ext method. |
 | `session/list` | S | ❌ | ✅ | ✅ | Gated by `sessionCapabilities.list`. The harness HAS `sessionPersistence.list()` (used internally for load-cwd validation) but does not expose it over ACP. |
@@ -85,7 +85,7 @@ These are capabilities the bridge would *drive* on the editor. The harness runs
 | `tool_call_update` | S | ✅ | ✅ | ✅ | From appended `tool/result` via `presentResult`; replacement results rewrite model context and do not duplicate or overwrite execution presentation. |
 | `plan` | S | ❌ | ✅ | ✅ | No agent plan emitted. Both adapters emit real plan entries (Codex's `CodexEventHandler.updatePlan` maps `turn/plan/updated` → `{ sessionUpdate: 'plan', entries }`). |
 | `available_commands_update` | S | ✅ | ✅ | ✅ | Full effective snapshot after create/load and registry changes; names, descriptions, and unstructured-input hints come from `ctx.commands`. |
-| `current_mode_update` | S | ❌ | ✅ | ✅ | No session modes. |
+| `current_mode_update` | S | ✅ | ✅ | ✅ | Echoed optimistically on `session/set_mode` and re-notified when a logged `plan/mode` maps to a different wire id (covers the `exit_plan_mode` tool flipping the session back). |
 | `config_option_update` | S | ❌ | ✅ | ✅ | Config options exist (advertised in `session/new`/`session/load`, switched via `session/set_config_option`), but the bridge never pushes agent-initiated changes — an operator default drift is narrated to the MODEL, not echoed to the editor. Future work in the [sandbox Agent Note § Per-session mode switching](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md). |
 | `usage_update` | S | ❌ | ✅ | ✅ | Token/cost reporting not surfaced (the harness records token usage internally on `assistant/message`). |
 | `session_info_update` | S | ❌ | ⚠️ | ⚠️ | Session title/metadata not pushed. |
@@ -111,7 +111,7 @@ Tool-call presentation is **owned by each tool** (`presentCall` / `presentResult
 
 ## 6. Session modes / config options / models
 
-Config options ✅: the bridge advertises a `model` select from the advisory LLM provider/model catalog, preserving each provider/model pair in an opaque value and grouping multiple providers. A selected pair is isolated to one session, snapshotted with the prompt for each step, applied through `agent/request`, and restored from the logged request header on load. When `ctx.permission` is composed, the bridge also advertises one `permission` select whose values come from the deployment preset table and whose current value derives from the session log; idle permission switches anchor at the next `agent/prompt-submit` inside its open turn. Session modes stay deliberately unmodeled because config options replace them in ACP v2. See the [model-catalog Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md) and [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+Session modes ✅ (the [plan-mode Agent Note](../../../.agents/notes/implemented/feature/2026-07-07-plan-mode.md)): ACP owns the fixed `default` / `plan` wire vocabulary and projects it onto `ctx.planMode`'s boolean `{ active, pending? }` state; `session/set_mode` calls `set()` and `current_mode_update` tracks the optimistic selection plus each distinct committed `plan/mode` flip. Config options ✅: the bridge advertises a `model` select from the advisory LLM provider/model catalog, preserving each provider/model pair in an opaque value and grouping multiple providers. A selected pair is isolated to one session, snapshotted with the prompt for each step, applied through `agent/request`, and restored from the logged request header on load. When `ctx.permission` is composed, the bridge also advertises one `permission` select whose values come from the deployment preset table and whose current value derives from the session log; idle permission switches anchor at the next `agent/prompt-submit` inside its open turn. The division is picker-to-collaboration-state / knobs-to-config-options: individual environment knobs and the provider/model selector are not modes. See the [model-catalog Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md) and [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
 
 ## 7. Content blocks
 

packages/ui/acp/package.json

@@ -38,6 +38,7 @@
     "@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-plan-mode": "^0.0.1",
     "@deepseek-ai/dsh-permission": "^0.0.1",
     "@deepseek-ai/dsh-sandbox": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -61,6 +62,7 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
+    "@deepseek-ai/dsh-plan-mode": "workspace:^",
     "@deepseek-ai/dsh-permission": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",

packages/ui/acp/src/index.ts

@@ -36,11 +36,14 @@ import {
   type PromptRequest,
   type PromptResponse,
   type SessionConfigOption,
+  type SessionModeState,
   type SessionConfigSelectGroup,
   type SessionConfigSelectOption,
   type SessionNotification,
   type SetSessionConfigOptionRequest,
   type SetSessionConfigOptionResponse,
+  type SetSessionModeRequest,
+  type SetSessionModeResponse,
   type Stream,
   type StopReason,
 } from '@agentclientprotocol/sdk'
@@ -65,6 +68,9 @@ import type { ToolCallView, ToolRegistry, ToolResultView, TerminalResultView } f
 // Side-effect type import: declaration-merges `ctx.sessionPersistence` onto
 // Context (the bridge injects it and reads `list()` for load cwd validation).
 import type {} from '@deepseek-ai/dsh-session-persistence'
+// Type-only edge: resolves `ctx.get('planMode')` when dsh-plan-mode is composed;
+// the runtime read stays opportunistic.
+import type {} from '@deepseek-ai/dsh-plan-mode'
 // Side-effect type import: declaration-merges prompt assembly onto Context and
 // the scoped waterfall used to keep persona variables aligned with requests.
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -95,6 +101,18 @@ function invalidParams(detail: string): RequestError {
   return RequestError.invalidParams(undefined, detail)
 }
 
+const DEFAULT_SESSION_MODE_ID = 'default'
+const PLAN_SESSION_MODE_ID = 'plan'
+const AVAILABLE_SESSION_MODES = [
+  { id: DEFAULT_SESSION_MODE_ID, name: DEFAULT_SESSION_MODE_ID },
+  { id: PLAN_SESSION_MODE_ID, name: PLAN_SESSION_MODE_ID },
+]
+
+/** Map plan state onto ACP's named collaboration-mode protocol. */
+function sessionModeId(active: boolean): string {
+  return active ? PLAN_SESSION_MODE_ID : DEFAULT_SESSION_MODE_ID
+}
+
 /** Render arbitrary thrown values without trusting their string coercion. */
 function renderThrown(value: unknown): string {
   try {
@@ -187,11 +205,14 @@ function elicitationForQuestion(
   options: AskUserQuestionOption[],
 ): CreateElicitationRequest {
   const title = question.header ?? 'Question'
+  const message = question.detail === undefined
+    ? question.question
+    : `${question.question}\n\n${question.detail}`
   if (options.length === 0) {
     return {
       sessionId,
       mode: 'form',
-      message: question.question,
+      message,
       requestedSchema: {
         type: 'object',
         title,
@@ -225,7 +246,7 @@ function elicitationForQuestion(
   return {
     sessionId,
     mode: 'form',
-    message: question.question,
+    message,
     requestedSchema: {
       type: 'object',
       title,
@@ -287,6 +308,13 @@ interface SessionRecord {
   presenter: ToolPresenter
   /** Terminal capability snapshot shared by matching call and result updates. */
   terminalEnabled: boolean
+  /**
+   * The last mode id this session sent to the client (advertised at
+   * session/new+load, echoed optimistically on session/set_mode, re-notified on
+   * each logged `plan/mode` that differs). `undefined` when dsh-plan-mode is
+   * not composed, so no mode surface is advertised or notified.
+   */
+  lastModeId: string | undefined
   /** Session-local provider/model selection and the current step snapshot. */
   target: LlmTargetRef
   /** In-flight prompt and its captured turn number for exact settlement. */
@@ -543,6 +571,21 @@ export function apply(ctx: Context, config: AcpConfig): void {
 
   // --- Stream the harness event taxonomy to ACP session/update --------------
 
+  // --- Session modes (dsh-plan-mode, opportunistic) -------------------------
+  // ACP's generic mode picker projects the one plan capability as the fixed
+  // `default` / `plan` vocabulary. A selection is echoed optimistically; the
+  // logged `plan/mode` follows at the boundary and tool-driven exits are
+  // re-notified from that event. Environment knobs remain config options.
+  const modesStateFor = (agent: Agent): SessionModeState | undefined => {
+    const planMode = ctx.get('planMode')
+    if (planMode === undefined) return undefined
+    const { active, pending } = planMode.get(agent)
+    return {
+      availableModes: AVAILABLE_SESSION_MODES,
+      currentModeId: sessionModeId(pending ?? active),
+    }
+  }
+
   // All content streaming AND the prompt settle flow through `session/event`,
   // the canonical log: every assistant/chunk and tool/call/result is logged, so
   // translating from the log makes live streaming and `session/load` replay
@@ -568,6 +611,20 @@ export function apply(ctx: Context, config: AcpConfig): void {
         cwd: session.header.cwd,
       }, { includeUserMessages: false })
     } finally {
+      // Re-notify from the EVENT's value, not from planMode.get(): the service
+      // holds one coalesced pending slot (every flush reads the latest
+      // selection, so a flush can never be stale against the picker), and for
+      // any other writer — the exit tool, a test, a foreign plugin — the logged
+      // value IS the truth the picker should track, in log order. Inside the
+      // containment `finally` like the prompt settlement: a throwing presenter
+      // must not desync the picker.
+      if (event.type === 'plan/mode') {
+        const modeId = sessionModeId(event.data.active)
+        if (modeId !== rec.lastModeId) {
+          rec.lastModeId = modeId
+          notify({ sessionId: rec.agent.session.id, update: { sessionUpdate: 'current_mode_update', currentModeId: modeId } })
+        }
+      }
       const inflight = rec.inflight
       if (inflight !== undefined && event.type === 'turn/start') {
         // The first message-triggered turn after prompt installation owns the
@@ -727,11 +784,13 @@ export function apply(ctx: Context, config: AcpConfig): void {
           await handle.dispose()
           throw internalError('connection closed during session/new')
         }
+        const modes = modesStateFor(handle.agent)
         const record: SessionRecord = {
           agent: handle.agent,
           dispose: () => handle.dispose(),
           presenter: makePresenter(handle.agent),
           terminalEnabled: terminalOutputCap,
+          lastModeId: modes?.currentModeId,
           target,
           inflight: undefined,
           commandAbort: undefined,
@@ -740,7 +799,11 @@ export function apply(ctx: Context, config: AcpConfig): void {
         sessions.set(sessionId, record)
         pendingCommandSnapshots.set(sessionId, record)
         const configOptions = configOptionsFor(handle.agent, directory)
-        return { sessionId, ...configOptions.length > 0 ? { configOptions } : {} }
+        return {
+          sessionId,
+          ...modes !== undefined ? { modes } : {},
+          ...configOptions.length > 0 ? { configOptions } : {},
+        }
       },
 
       async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
@@ -812,11 +875,13 @@ export function apply(ctx: Context, config: AcpConfig): void {
           // the replay below and the post-load live stream) so a later
           // `initialize` can't desync the call/result of a tool card.
           const terminalEnabled = terminalOutputCap
+          const modes = modesStateFor(agent)
           const record: SessionRecord = {
             agent,
             dispose: () => handle.dispose(),
             presenter: makePresenter(agent),
             terminalEnabled,
+            lastModeId: modes?.currentModeId,
             target,
             inflight: undefined,
             commandAbort: undefined,
@@ -846,12 +911,33 @@ export function apply(ctx: Context, config: AcpConfig): void {
           }
           notifyCommands(record)
           const configOptions = configOptionsFor(agent, directory)
-          return configOptions.length > 0 ? { configOptions } : {}
+          return {
+            ...modes !== undefined ? { modes } : {},
+            ...configOptions.length > 0 ? { configOptions } : {},
+          }
         } finally {
           loadingIds.delete(sessionId)
         }
       },
 
+      setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse> {
+        assertOpen()
+        const rec = requireSession(SessionId(params.sessionId))
+        const planMode = ctx.get('planMode')
+        if (planMode === undefined) throw invalidParams('session modes are not composed in this deployment')
+        if (params.modeId !== DEFAULT_SESSION_MODE_ID && params.modeId !== PLAN_SESSION_MODE_ID) {
+          throw invalidParams(`unknown session mode ${JSON.stringify(params.modeId)} — available modes: default, plan`)
+        }
+        planMode.set(rec.agent, params.modeId === PLAN_SESSION_MODE_ID)
+        // Optimistic echo: the pending mode IS the user's selection; the logged
+        // `plan/mode` lands at the next turn boundary and, matching lastModeId,
+        // is not re-notified. A no-op selection (already current) echoes too —
+        // cheap, idempotent, and the picker settles regardless.
+        rec.lastModeId = params.modeId
+        notify({ sessionId: rec.agent.session.id, update: { sessionUpdate: 'current_mode_update', currentModeId: params.modeId } })
+        return Promise.resolve({})
+      },
+
       async prompt(params: PromptRequest): Promise<PromptResponse> {
         assertOpen()
         const rec = requireSession(SessionId(params.sessionId))

packages/ui/acp/tests/bridge.spec.ts

@@ -143,15 +143,18 @@ describe('acp bridge', () => {
       questions: [{
         id: 'language',
         question: 'Which language?',
+        detail: 'Choose the implementation language for this project.',
         options: [{ label: 'TypeScript' }],
       }],
     })
 
     expect(result).toEqual({ answers: [{ id: 'language', selected: [], custom: 'Use Zig' }] })
     expect(harness.elicitationRequests[0]).toMatchObject({
+      message: 'Which language?\n\nChoose the implementation language for this project.',
       requestedSchema: {
         properties: {
           choice: {
+            title: 'Which language?',
             description: 'Choose one option, or fill a custom answer below.',
             oneOf: [{ const: 'TypeScript', title: 'TypeScript' }],
           },

packages/ui/acp/tests/harness.ts

@@ -17,6 +17,7 @@ import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
+import PlanModeService from '@deepseek-ai/dsh-plan-mode'
 import {
   ClientSideConnection,
   ndJsonStream,
@@ -191,6 +192,8 @@ export async function makeBridgeHarness(options: {
    * tool + the bridge's own todo/write→plan mapping, not a stand-in.
    */
   withTodo?: boolean
+  /** Plug the REAL `dsh-plan-mode` plugin so a test can drive the session-mode picker. */
+  withModes?: boolean
   /**
    * Plug the REAL filesystem stack (`dsh-fs-local` + `dsh-fs-policy` +
    * `dsh-tool-fs`) so a test can drive `read`/`write`/`edit` through the bridge
@@ -225,6 +228,9 @@ export async function makeBridgeHarness(options: {
   if (options.withTodo) {
     await ctx.plugin(ToolTodo)
   }
+  if (options.withModes) {
+    await ctx.plugin(PlanModeService, { section: 'Test plan mode instructions.' })
+  }
   if (options.withFs) {
     await ctx.plugin(LocalFileSystem, { cwd: options.fsCwd ?? options.storageDir })
     await ctx.plugin(FsPolicy)

packages/ui/acp/tests/modes.spec.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { makeBridgeHarness, textResponse, type BridgeHarness, type CapturedUpdate } from './harness.ts'
+
+/** The `current_mode_update` notifications, in order. */
+function modeUpdates(updates: CapturedUpdate[]): string[] {
+  return updates
+    .filter(update => update.sessionUpdate === 'current_mode_update')
+    .map(update => update.currentModeId)
+}
+
+describe('acp bridge — plan mode projection', () => {
+  let storageDir: string
+  let harness: BridgeHarness | undefined
+  let loader: BridgeHarness | undefined
+
+  beforeEach(async () => { storageDir = await mkdtemp(join(tmpdir(), 'acp-modes-')) })
+  afterEach(async () => {
+    if (harness) await harness.dispose()
+    if (loader) await loader.dispose()
+    harness = loader = undefined
+    await rm(storageDir, { recursive: true, force: true })
+  })
+
+  it('advertises no mode surface and rejects session/set_mode when plan mode is not composed', async () => {
+    harness = await makeBridgeHarness({ storageDir })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const res = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    expect(res.modes).toBeUndefined()
+    await expect(harness.client.setSessionMode({ sessionId: res.sessionId, modeId: 'plan' }))
+      .rejects.toMatchObject({ message: expect.stringContaining('session modes are not composed') as string })
+  })
+
+  it('advertises availableModes/currentModeId on session/new', async () => {
+    harness = await makeBridgeHarness({ storageDir, withModes: true })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const res = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    expect(res.modes).toEqual({
+      availableModes: [
+        { id: 'default', name: 'default' },
+        { id: 'plan', name: 'plan' },
+      ],
+      currentModeId: 'default',
+    })
+  })
+
+  it('session/set_mode records the pending intent and echoes one optimistic current_mode_update', async () => {
+    harness = await makeBridgeHarness({ storageDir, withModes: true })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    await harness.client.setSessionMode({ sessionId, modeId: 'plan' })
+    expect(modeUpdates(harness.updates)).toEqual(['plan'])
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    expect(harness.ctx.planMode.get(agent)).toEqual({ active: false, pending: true })
+  })
+
+  it('rejects an unknown ACP mode id at the adapter boundary', async () => {
+    harness = await makeBridgeHarness({ storageDir, withModes: true })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    await expect(harness.client.setSessionMode({ sessionId, modeId: 'nope' }))
+      .rejects.toMatchObject({ message: expect.stringContaining('unknown session mode "nope"') as string })
+    expect(modeUpdates(harness.updates)).toEqual([])
+  })
+
+  it('does not re-notify when the boundary flush logs the mode the picker already showed', async () => {
+    harness = await makeBridgeHarness({ storageDir, withModes: true, script: [textResponse('planning')] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    await harness.client.setSessionMode({ sessionId, modeId: 'plan' })
+    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go plan' }] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    expect(agent.session.events.some(event => event.type === 'plan/mode')).toBe(true)
+    expect(modeUpdates(harness.updates)).toEqual(['plan'])
+  })
+
+  it('re-notifies on a logged flip the picker has not seen (the tool-driven exit shape)', async () => {
+    harness = await makeBridgeHarness({ storageDir, withModes: true, script: [textResponse('planning')] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    await harness.client.setSessionMode({ sessionId, modeId: 'plan' })
+    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go plan' }] })
+    // A writer other than the picker (exit_plan_mode's execute) appends the
+    // flip back; the bridge must re-notify the client off the logged event.
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    agent.session.append('plan/mode', { active: false })
+    // The notification crosses the in-memory JSON-RPC transport asynchronously.
+    await new Promise(resolve => setTimeout(resolve, 20))
+    expect(modeUpdates(harness.updates)).toEqual(['plan', 'default'])
+  })
+
+  it('advertises the folded mode on session/load', async () => {
+    harness = await makeBridgeHarness({ storageDir, withModes: true, script: [textResponse('planning')] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    await harness.client.setSessionMode({ sessionId, modeId: 'plan' })
+    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go plan' }] })
+    await harness.dispose()
+    harness = undefined
+
+    loader = await makeBridgeHarness({ storageDir, withModes: true, script: [] })
+    await loader.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const res = await loader.client.loadSession({ sessionId, cwd: process.cwd(), mcpServers: [] })
+    expect(res.modes).toEqual({
+      availableModes: [
+        { id: 'default', name: 'default' },
+        { id: 'plan', name: 'plan' },
+      ],
+      currentModeId: 'plan',
+    })
+  })
+})

packages/ui/acp/tsconfig.json

@@ -41,6 +41,9 @@
     {
       "path": "../user-interaction"
     },
+    {
+      "path": "../../plan/plan-mode"
+    },
     {
       "path": "../../session-persistence/session-persistence"
     },

packages/ui/app-boot/README.md

@@ -5,10 +5,14 @@ Shared boot glue for the app bins ([`dsh-tui-demo`](../../examples/tui-demo/READ
 | Export | Role |
 |---|---|
 | `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 |
 | `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) |
-| `boot(binName, absoluteConfigPath)` | 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, await the whole tree, assert entries loaded, return the root context |
+| `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 |
+| `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 |
 
 Two failure classes the guards handle: `loader.await()` swallows init rejections (`Promise.allSettled`) — Node still exits non-zero on the resulting unhandled rejection, and `installFailLoud` replaces the noisy dump with one labelled line and a guaranteed `exit(1)`; a failed plugin IMPORT is only logged by the Loader (the process would otherwise exit 0 on a usable config typo), leaving a fiber-less entry that `assertEntriesLoaded` turns into a `boot()` rejection.
 
@@ -16,16 +20,27 @@ Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve
 
 This package carries no loader hooks and no dev-mode surface: the `dsh-scripts` launcher ([`sdk/scripts`](../../sdk/scripts/README.md), with the shared project model in [`sdk/helper`](../../sdk/helper/README.md)) owns process startup, tsx registration, and local-plugin source resolution, and consumes these helpers for the boot sequence itself.
 
+## Personal config
+
+A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the `dsh` CLI's TUI surface ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
+
+- **`.env`** — loaded after the invoking directory's `.env`; `process.loadEnvFile` never overrides, so precedence is ambient environment > project `.env` > personal `.env`.
+- **`config.yaml`** — loader overlay patches applied over the shipped default config, with the same semantics as an include entry's `patches` (the committed Code Mode overlay is the template): an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount — so a personal `apiKey` can reference the personal `.env`. A patch naming an entry id absent from the booted tree is skipped with a loader warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the overlay with `[]` or by deleting the file.
+
+Subprocess test launchers point `DSH_HOME` at an isolated per-test directory so a developer's personal overlay can never leak into fixtures.
+
 ## Model Experience
 
-Indirectly, through the plugin tree it loads, which determines the prompts, schemas, messages, and model adapter in the resulting application.
+Indirectly, through the plugin tree it loads, which determines the prompts, schemas, messages, and model adapter in the resulting application; the one export that contributes model-visible text, `addHarnessSourceSection`, does so only when a consumer calls it after boot.
 
 #### KV Cache effect
 
-No direct invalidation; the named consumer owns any request-prefix changes.
+No direct invalidation from `boot()`; a consumer that calls `addHarnessSourceSection` places one short line near the system prompt's head, before per-request content, so it does not invalidate the cache across turns, and any other request-prefix change is owned by the named consumer.
 
 ## Known Limitations and Deferred Work
 
 - **Bare package specifiers depend on Loader internals** — production bins need `node --expose-internals` or the Loader's optional native fallback; an in-process caller without either must use resolvable relative/file specifiers or tsx path mapping.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
 - **Environment loading is cwd-scoped and optional** — the helper loads one `.env` file and warns on failure; it does not search parents, merge profiles, or validate required variables.
+- **Personal config is patch-shaped** — an id-targeted patch replaces the entry's whole `config` rather than deep-merging, so a personal override restates the base fields it keeps.
+- **Personal patches see only the booted file's own entries** — an overlay leaf that reaches its base through a nested include entry (the Code Mode configs) resolves personal patch ids against the overlay's top-level entries, not the included subtree.

packages/ui/app-boot/package.json

@@ -26,16 +26,24 @@
     "src"
   ],
   "license": "BSD-3-Clause",
+  "dependencies": {
+    "js-yaml": "^4.2.0"
+  },
   "peerDependencies": {
     "@cordisjs/plugin-include": "^1.0.4",
     "@cordisjs/plugin-loader": "^1.0.0-rc.5",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-paths": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@cordisjs/plugin-include": "workspace:^",
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-paths": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@types/js-yaml": "^4.0.9",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/ui/app-boot/src/index.ts

@@ -1,15 +1,21 @@
 /**
  * Shared boot glue for the app bins (`dsh-tui-demo`, `dsh-cli-demo`, `dsh-acp-demo`): load the gitignored
- * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), and
- * drive the cordis Loader against a leaf `cordis.yml` until the whole tree has settled.
+ * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
+ * optional personal overlay patches from the Harness home (`~/.dsh`), and drive the cordis Loader
+ * against a leaf `cordis.yml` until the whole tree has settled.
  * @module @deepseek-ai/dsh-app-boot
  */
 
 import { pathToFileURL } from 'node:url'
-import { basename, dirname, resolve } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import * as yaml from 'js-yaml'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import Include from '@cordisjs/plugin-include'
+import Include, { type PatchOptions } from '@cordisjs/plugin-include'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+// Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
+import type {} from '@deepseek-ai/dsh-system-prompt'
 
 /**
  * Resolve the config to boot. Replay swaps a `cordis.yml` basename for
@@ -30,6 +36,50 @@ export function resolveConfigPath(
   return resolve(dir, replayName)
 }
 
+/** CLI flag the interactive surface accepts to resume a persisted session by id. */
+const RESUME_FLAG = '--resume'
+
+/**
+ * Split a leading `--resume <id>` / `--resume=<id>` flag out of a CLI argument
+ * vector, returning the resumed session id (when the flag is present) and the
+ * remaining arguments with the flag and its value removed — so a positional
+ * config path stays readable regardless of the flag's position. A `--resume`
+ * with no following id, an empty id (`--resume=`), or a repeated `--resume`
+ * throws: a mistyped resume must fail loud, never silently start a fresh
+ * session. The id is not validated here; an unknown id fails loud downstream
+ * when the session cannot load.
+ * @param argv - the CLI arguments after subcommand dispatch.
+ * @returns the parsed resume id (or `undefined`) and the flag-stripped arguments.
+ */
+export function parseResumeArg(
+  argv: readonly string[],
+): { resumeSessionId: string | undefined; rest: string[] } {
+  const rest: string[] = []
+  let resumeSessionId: string | undefined
+  let skipNext = false
+  for (const [i, arg] of argv.entries()) {
+    if (skipNext) {
+      skipNext = false
+      continue
+    }
+    const inlineValue = arg.startsWith(`${RESUME_FLAG}=`)
+    if (arg === RESUME_FLAG || inlineValue) {
+      if (resumeSessionId !== undefined) throw new Error(`${RESUME_FLAG} may be given only once`)
+      const value = inlineValue ? arg.slice(RESUME_FLAG.length + 1) : argv[i + 1]
+      // A following token that is itself resume syntax (`--resume --resume x`)
+      // is a missing id, not a session literally named `--resume…`.
+      if (value === undefined || value === '' || value === RESUME_FLAG || value.startsWith(`${RESUME_FLAG}=`)) {
+        throw new Error(`${RESUME_FLAG} requires a session id (e.g. ${RESUME_FLAG} <session-id>)`)
+      }
+      resumeSessionId = value
+      skipNext = !inlineValue // the space form consumed the following token as its value
+      continue
+    }
+    rest.push(arg)
+  }
+  return { resumeSessionId, rest }
+}
+
 /**
  * Load the optional gitignored `.env` from `dir`. Missing files fall back to the
  * ambient environment; other read failures are reported through `warn`.
@@ -51,6 +101,62 @@ export function loadEnv(
   }
 }
 
+/** File inside the Harness home holding the personal loader overlay patches. */
+export const PERSONAL_CONFIG_FILENAME = 'config.yaml'
+
+// The include's YAML dialect: `!!js` scalars become expression nodes the
+// Loader interpolates against each entry's context at mount time. Personal
+// patches are parsed with the same schema so they may reference `process.env`.
+// Load-only: this schema never dumps, so no `predicate`/`represent`.
+const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
+  kind: 'scalar',
+  resolve: data => typeof data === 'string',
+  construct: data => ({ __jsExpr: String(data) }),
+})
+const personalPatchesSchema = yaml.JSON_SCHEMA.extend(jsExprType)
+
+/**
+ * Load the optional personal overlay patches (`config.yaml` under the Harness
+ * home). The file is a top-level YAML array of loader patch entries
+ * (`@cordisjs/plugin-include`'s `PatchOptions`): id-targeted config overrides
+ * and `insert` lists, with `!!js` expressions allowed. A missing file means
+ * "no personal overlay"; an unreadable, unparsable, or non-array file throws —
+ * a present personal config that cannot apply is a misconfiguration and must
+ * fail loud at boot, never be silently skipped.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param dir - the Harness home; defaults to {@link resolveDshHome} (`$DSH_HOME` or `~/.dsh`).
+ * @returns the parsed patches, or `undefined` when the file does not exist.
+ */
+export function loadPersonalPatches(
+  binName: string, dir: string = resolveDshHome(),
+): PatchOptions[] | undefined {
+  const file = join(dir, PERSONAL_CONFIG_FILENAME)
+  let content: string
+  try {
+    content = readFileSync(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return undefined
+    throw new Error(`${binName}: failed to read personal patches ${file}: ${String(error)}`)
+  }
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content, { schema: personalPatchesSchema })
+  } catch (error) {
+    throw new Error(`${binName}: failed to parse personal patches ${file}: ${String(error)}`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${binName}: personal patches ${file} must be a top-level YAML array of loader patch entries`)
+  }
+  // A present personal config that cannot apply is a misconfiguration and must
+  // fail loud here — the include only warns per entry at mount.
+  parsed.forEach((entry, index) => {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      throw new Error(`${binName}: personal patches entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
+    }
+  })
+  return parsed as PatchOptions[]
+}
+
 /**
  * The slice of `process` {@link installFailLoud} needs — injectable so tests
  * exercise the handler without registering on (or exiting) the real process.
@@ -109,18 +215,52 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
  * @param binName - the diagnostic prefix for load-failure errors.
  * @param absoluteConfigPath - the config to include; must already be absolute
  * (see {@link resolveConfigPath}).
+ * @param patches - optional overlay patches applied over the included tree
+ * (see {@link loadPersonalPatches}); an empty list mounts none.
  * @returns the root context once every entry has started.
  */
-export async function boot(binName: string, absoluteConfigPath: string): Promise<Context> {
+export async function boot(
+  binName: string, absoluteConfigPath: string, patches?: PatchOptions[],
+): Promise<Context> {
   const ctx = new Context()
   ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
   await ctx.plugin(Loader)
   ctx.loader.builtins.include = Include
   await ctx.loader.create({
     name: 'cordis:include',
-    config: { path: pathToFileURL(absoluteConfigPath).href },
+    config: {
+      path: pathToFileURL(absoluteConfigPath).href,
+      ...patches !== undefined && patches.length > 0 ? { patches } : {},
+    },
   })
   await ctx.loader.await()
   assertEntriesLoaded(ctx, binName)
   return ctx
 }
+
+/** Prompt-section name for the harness-source location line an app bin adds after boot. */
+export const HARNESS_SOURCE_SECTION = 'harness:source'
+
+/**
+ * Add a global prompt section naming the on-disk path to the harness source
+ * checkout the running bin was launched from, so the agent knows where its own
+ * source lives (the self-referential `dsh-tool-cordis` toolset reads and edits
+ * it). Call once on the settled boot context ({@link boot}); the section orders
+ * just after the harness identity opener (`-100`) and before the deployment
+ * persona (`0`). A booted tree with no `systemPrompt` service has no prompt to
+ * augment, so this is then a no-op that returns `undefined`. The section is
+ * registered against the `systemPrompt` service's fiber, so a dev HMR reload of
+ * that plugin drops it until the next boot.
+ * @param ctx - the settled boot context whose global system prompt to augment.
+ * @param sourceRoot - the absolute path to the harness checkout root.
+ * @returns the section disposer, or `undefined` when no `systemPrompt` service is mounted.
+ */
+export function addHarnessSourceSection(ctx: Context, sourceRoot: string): (() => void) | undefined {
+  const systemPrompt = ctx.get('systemPrompt')
+  if (systemPrompt === undefined) return undefined
+  return systemPrompt.section({
+    name: HARNESS_SOURCE_SECTION,
+    order: -99,
+    text: `Your own source code is the checkout at ${sourceRoot}; you can read it there to learn how dsh works and how to extend it.`,
+  })
+}

packages/ui/app-boot/tests/app-boot.spec.ts

@@ -2,10 +2,11 @@ import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
-import type { Context } from 'cordis'
+import { Context } from 'cordis'
+import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import {
-  assertEntriesLoaded, boot, installFailLoud, loadEnv, resolveConfigPath,
-  type FailLoudProcess,
+  addHarnessSourceSection, assertEntriesLoaded, boot, HARNESS_SOURCE_SECTION,
+  installFailLoud, loadEnv, parseResumeArg, resolveConfigPath, type FailLoudProcess,
 } from '../src/index.ts'
 
 const NAME = 'dsh-test-bin'
@@ -29,6 +30,31 @@ describe('resolveConfigPath', () => {
   })
 })
 
+describe('parseResumeArg', () => {
+  it('returns no resume id and passes arguments through when the flag is absent', () => {
+    expect(parseResumeArg([])).toEqual({ resumeSessionId: undefined, rest: [] })
+    expect(parseResumeArg(['custom.yml'])).toEqual({ resumeSessionId: undefined, rest: ['custom.yml'] })
+  })
+
+  it('parses the space form, the inline form, and leaves a positional config path in any position', () => {
+    expect(parseResumeArg(['--resume', 'sess-1'])).toEqual({ resumeSessionId: 'sess-1', rest: [] })
+    expect(parseResumeArg(['--resume=sess-2'])).toEqual({ resumeSessionId: 'sess-2', rest: [] })
+    expect(parseResumeArg(['--resume', 'sess-3', 'app.yml'])).toEqual({ resumeSessionId: 'sess-3', rest: ['app.yml'] })
+    expect(parseResumeArg(['app.yml', '--resume', 'sess-4'])).toEqual({ resumeSessionId: 'sess-4', rest: ['app.yml'] })
+  })
+
+  it('fails loud on a valueless, empty, or repeated flag rather than silently starting fresh', () => {
+    expect(() => parseResumeArg(['--resume'])).toThrow('--resume requires a session id')
+    expect(() => parseResumeArg(['--resume='])).toThrow('--resume requires a session id')
+    expect(() => parseResumeArg(['--resume', 'a', '--resume', 'b'])).toThrow('--resume may be given only once')
+  })
+
+  it('rejects resume syntax used as the flag value instead of resuming a session named like the flag', () => {
+    expect(() => parseResumeArg(['--resume', '--resume', 'sess'])).toThrow('--resume requires a session id')
+    expect(() => parseResumeArg(['--resume', '--resume=sess'])).toThrow('--resume requires a session id')
+  })
+})
+
 describe('loadEnv', () => {
   it('loads variables from .env in the given dir', () => {
     const dir = tmp()
@@ -176,3 +202,56 @@ describe('boot', () => {
     await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow(`${NAME}: plugin(s) failed to load: ./missing.mjs`)
   })
 })
+
+describe('addHarnessSourceSection', () => {
+  const SOURCE_ROOT = `${sep}opt${sep}harness-src`
+  const EXPECTED = `Your own source code is the checkout at ${SOURCE_ROOT}; you can read it there to learn how dsh works and how to extend it.`
+
+  it('adds the source path between the harness identity and the deployment persona', async () => {
+    const ctx = new Context()
+    try {
+      await ctx.plugin(SystemPrompt, { persona: 'You are a coding agent.' })
+      const dispose = addHarnessSourceSection(ctx, SOURCE_ROOT)
+      expect(dispose).toBeTypeOf('function')
+      const systemPrompt = ctx.get('systemPrompt')!
+      const rendered = renderPrompt(await systemPrompt.assemble())
+      expect(rendered).toContain(EXPECTED)
+      // Harness-owned opener (-100) → source (-99) → persona (0). The >= 0 guards
+      // keep a drifted opener/persona string from a false pass through `-1 < n`.
+      const identityAt = rendered.indexOf('You are an AI agent powered by the DeepSeek Harness SDK.')
+      const sourceAt = rendered.indexOf(EXPECTED)
+      const personaAt = rendered.indexOf('You are a coding agent.')
+      expect(identityAt).toBeGreaterThanOrEqual(0)
+      expect(personaAt).toBeGreaterThanOrEqual(0)
+      expect(identityAt).toBeLessThan(sourceAt)
+      expect(sourceAt).toBeLessThan(personaAt)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('is a no-op returning undefined when no systemPrompt service is mounted', async () => {
+    const ctx = new Context()
+    try {
+      expect(addHarnessSourceSection(ctx, SOURCE_ROOT)).toBeUndefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('disposes the section it added, so a systemPrompt reload leaves no residue', async () => {
+    const ctx = new Context()
+    try {
+      await ctx.plugin(SystemPrompt, {})
+      const systemPrompt = ctx.get('systemPrompt')!
+      const dispose = addHarnessSourceSection(ctx, SOURCE_ROOT)!
+      const present = await systemPrompt.assemble()
+      expect(present.sections.some(section => section.name === HARNESS_SOURCE_SECTION)).toBe(true)
+      dispose()
+      const gone = await systemPrompt.assemble()
+      expect(gone.sections.some(section => section.name === HARNESS_SOURCE_SECTION)).toBe(false)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})

packages/ui/app-boot/tests/personal-config.spec.ts

@@ -0,0 +1,141 @@
+/**
+ * Personal-config behavior of `dsh-app-boot`: the Harness home (`~/.dsh`)
+ * `config.yaml` overlay loader and `boot()` applying the personal overlay over
+ * a real Loader tree.
+ */
+
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { Context } from 'cordis'
+import {
+  boot,
+  loadPersonalPatches,
+  PERSONAL_CONFIG_FILENAME,
+} from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-personal-config-'))
+
+describe('loadPersonalPatches', () => {
+  afterEach(() => {
+    delete process.env.DSH_HOME
+  })
+
+  it('returns undefined when no personal patches file exists', () => {
+    expect(loadPersonalPatches(NAME, tmp())).toBeUndefined()
+  })
+
+  it('parses a patch list and preserves !!js expressions as loader expression nodes', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), [
+      '- id: tui-agent',
+      "  name: '@deepseek-ai/dsh-tui-demo'",
+      '  config:',
+      '    model: !!js process.env.DSH_SPEC_MODEL',
+      '- insert:',
+      '    - id: llm',
+      "      name: '@deepseek-ai/dsh-llm-pi-ai'",
+      '',
+    ].join('\n'))
+    const patches = loadPersonalPatches(NAME, dir)
+    expect(patches).toHaveLength(2)
+    expect(patches?.[0]).toMatchObject({
+      id: 'tui-agent',
+      config: { model: { __jsExpr: 'process.env.DSH_SPEC_MODEL' } },
+    })
+    expect(patches?.[1]?.insert).toHaveLength(1)
+  })
+
+  it('defaults its directory to the Harness home ($DSH_HOME)', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), '- id: x\n  config:\n    a: 1\n')
+    process.env.DSH_HOME = dir
+    expect(loadPersonalPatches(NAME)).toHaveLength(1)
+  })
+
+  it('fails loud on an unreadable file (a present personal config is never skipped)', () => {
+    const dir = tmp()
+    mkdirSync(join(dir, PERSONAL_CONFIG_FILENAME)) // a directory: present, unreadable as a file
+    expect(() => loadPersonalPatches(NAME, dir))
+      .toThrow(new RegExp(`^${NAME}: failed to read personal patches `))
+  })
+
+  it('fails loud on unparsable YAML and on a !!js tag with no expression body', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), 'invalid: [unclosed\n')
+    expect(() => loadPersonalPatches(NAME, dir))
+      .toThrow(new RegExp(`^${NAME}: failed to parse personal patches `))
+    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), '- id: x\n  config:\n    a: !!js\n')
+    expect(() => loadPersonalPatches(NAME, dir))
+      .toThrow(new RegExp(`^${NAME}: failed to parse personal patches `))
+  })
+
+  it('fails loud when the file is not a top-level array or an entry is not an object', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), 'id: not-a-list\n')
+    expect(() => loadPersonalPatches(NAME, dir))
+      .toThrow('must be a top-level YAML array of loader patch entries')
+    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), '- just-a-string\n')
+    expect(() => loadPersonalPatches(NAME, dir))
+      .toThrow(`${NAME}: personal patches entry 1 in`)
+  })
+})
+
+describe('boot with personal patches', () => {
+  function writeTree(dir: string): string {
+    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  config:\n    value: base\n')
+    return join(dir, 'cordis.yml')
+  }
+
+  function entryConfig(ctx: Context, id: string): unknown {
+    return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
+  }
+
+  it('applies id-targeted overrides, inserts, and interpolates !!js from the environment', async () => {
+    const dir = tmp()
+    const personal = tmp()
+    writeFileSync(join(personal, PERSONAL_CONFIG_FILENAME), [
+      '- id: noop',
+      '  name: ./noop.mjs',
+      '  config:',
+      '    value: !!js process.env.DSH_APP_BOOT_PERSONAL_SPEC',
+      '- insert:',
+      '    - id: personal-extra',
+      '      name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    process.env['DSH_APP_BOOT_PERSONAL_SPEC'] = 'personal-value'
+    const ctx = await boot(NAME, writeTree(dir), loadPersonalPatches(NAME, personal))
+    try {
+      const noop = [...ctx.loader.entries()].find(entry => entry.options.id === 'noop')
+      // The mounted plugin received the interpolated environment value.
+      expect(noop?.fiber?.config).toEqual({ value: 'personal-value' })
+      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'personal-extra')).toBe(true)
+    } finally {
+      await ctx.fiber.dispose()
+      delete process.env['DSH_APP_BOOT_PERSONAL_SPEC']
+    }
+  })
+
+  it('mounts no patch layer for an absent or empty personal overlay', async () => {
+    const dir = tmp()
+    const ctx = await boot(NAME, writeTree(dir), loadPersonalPatches(NAME, tmp()))
+    try {
+      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'base' })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+    const empty = tmp()
+    writeFileSync(join(empty, PERSONAL_CONFIG_FILENAME), '[]\n')
+    const ctxEmpty = await boot(NAME, writeTree(tmp()), loadPersonalPatches(NAME, empty))
+    try {
+      expect(entryConfig(ctxEmpty, 'noop')).toEqual({ value: 'base' })
+    } finally {
+      await ctxEmpty.fiber.dispose()
+    }
+  })
+})

packages/ui/app-boot/tsconfig.json

@@ -19,6 +19,12 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../util/paths"
     }
   ]
 }

packages/ui/commands/README.md

@@ -10,7 +10,7 @@ Plugin-owned human-command registry shared by the TUI and ACP adapters. The [plu
 
 `parseCommand()` recognizes a slash at byte zero, a lowercase name containing letters, digits, `_`, or `-`, and either end-of-input or whitespace. It returns every byte after the name as `rawInput`, including separator whitespace; consumers own their command-specific grammar and may normalize only what that grammar permits.
 
-Handlers return `success` or `error` plus optional UI text. Results are rendered directly by the adapter and never enter model history. The registry races handler completion against the supplied abort signal, but an uncooperative handler may continue its own external side effects after the caller stops awaiting it.
+Handlers return `success` or `error` plus optional UI text. Results are rendered directly by the adapter and never enter model history. The registry never submits `rawInput` to the agent implicitly; a command producer may explicitly schedule model-visible work through the receiving `Agent`, in which case that producer owns the resulting message contract. The registry races handler completion against the supplied abort signal, but an uncooperative handler may continue its own external side effects after the caller stops awaiting it.
 
 ## Composition
 
@@ -22,11 +22,11 @@ The terminal and ACP app bundles mount this service with their consuming front d
 
 #### What the model sees
 
-Nothing. Known slash commands execute in the UI command plane, and their `CommandResult` text is not submitted as a user message. Unknown slash-command input is rejected by shipped adapters instead of becoming a model prompt.
+The registry itself submits nothing. Known slash commands execute in the UI command plane, and their `CommandResult` text is not submitted as a user message. Unknown slash-command input is rejected by shipped adapters instead of becoming a model prompt. A command producer may explicitly use the receiving `Agent`; for example, [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) submits the optional message in `/plan [message]` after selecting plan mode.
 
 #### Token effect
 
-Command discovery, execution, and UI output add no model tokens. A command plugin may separately mutate a model-visible domain through that domain's durable APIs.
+Command discovery, execution, and UI output add no model tokens. Explicit agent work scheduled by a command producer has the same token effect as the corresponding agent input.
 
 #### KV Cache effect
 

packages/ui/tui/README.md

@@ -1,12 +1,12 @@
 # @deepseek-ai/dsh-tui
 
-The interactive terminal front door for DeepSeek Harness agents, built on [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui). It requires stdin and stdout TTYs; scripts and Loader pipes should use the headless [`@deepseek-ai/dsh-cli-demo`](../../examples/cli-demo/README.md) app instead.
+The interactive terminal front door for DeepSeek Harness agents, built on [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui). It requires stdin and stdout TTYs; scripts and Loader pipes should use the one-shot [`@deepseek-ai/dsh-cli-demo`](../../examples/cli-demo/README.md) app instead.
 
 The implemented [TUI feature Agent Note](../../../.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md) owns the front-door decision; the [terminal-state snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md) owns its verification strategy.
 
 Interactive terminals on macOS, Linux, and Windows are supported. Windows uses pi-tui's native console VT-input handling, and the [Windows support Agent Note](../../../.agents/notes/implemented/feature/2026-07-20-windows-tui-support.md) owns the platform decision and ConPTY process verification.
 
-This package owns interactive terminal presentation and input only. It injects `agents`, [`commands`](../commands/README.md), `llm`, `systemPrompt`, `tokenMeter`, `tools`, and `userInteraction`, then drives an agent created or resumed by app or developer code. Agent lifecycle, persistence, and the model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
+This package owns interactive terminal presentation and input only. It injects `agents`, [`commands`](../commands/README.md), `llm`, `systemPrompt`, `tokenMeter`, `tools`, and `userInteraction`, optionally reads a `skills` service (present only when one is mounted), then drives an agent created or resumed by app or developer code. Agent lifecycle, persistence, and the model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
 
 The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the latest `todo/write` plan above the editor, and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes `<session title> — <configured title>`. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelContext()` for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode and the current model with reasoning state; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. Surface replacement events rebuild the transcript so compacted history does not reappear.
 
@@ -14,15 +14,23 @@ An embedding may provide `TuiRuntime.formatCwd` when its logical workspace label
 
 Before model output, session events, tool presenters, questions, configuration, or diagnostics reach pi-tui's ANSI-aware renderers or the terminal title, the TUI renders C0 and C1 controls other than line feeds as visible `\xNN` text. Those sources cannot add terminal control sequences; the TUI and pi-tui retain ownership of terminal rendering and styling.
 
-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 reaches the model. The TUI registers `/help`, `/model`, `/clear`, `/cancel`, `/reasoning`, `/tools`, `/redraw`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically. 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.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.
 
 `/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.
 
+`/reload` (EXPERIMENTAL, dev-only) re-reads every file-backed loader config tree and applies the diff to the running app — the HMR watcher's config path, invoked manually; it needs the cordis Loader in the context and degrades to a warning without one, runs only while the agent is idle, and refuses re-entry while a reload is in flight. Module-source hot reload remains watcher-owned. When a `skills` service is mounted, `/skill:<name> [instructions]` loads that skill's instructions into the conversation as a user turn; autocomplete lists the model-invocable skills, and any skill (including a model-disabled one) is loadable by its exact name.
+
+The footer sums the session's reported usage as `↑<uncached input> ↓<output>`, followed by `cache <rate>%` once any input has been billed — the share of billed prompt tokens (uncached input plus cache reads and writes) served from the provider cache, rounded to a percent. It also compares token-meter pressure with `ctx.llm.resolveModelContext()` for the current route (omitting the context share when the adapter has no capacity metadata) and shows the current model and tool-card mode; the right side clips first when the footer is narrow.
+
+`/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.
+
 ## Config
 
 | Key | Default | Meaning |
 |---|---|---|
-| `welcome` | `ready.` | Header subtitle until the session has a logged title. |
+| `welcome` | — | Banner subtitle line until the session has a logged title; unset, the banner sweeps in with no subtitle |
 | `sessionId` | `main` | Exact shared agent/session identity driven by the terminal |
 | `showReasoning` | `true` | Render reasoning blocks |
 | `maxToolOutputLines` | `6` | Output lines retained across a collapsed tool card's head/tail preview |
@@ -35,6 +43,7 @@ While the agent is running, ordinary editor submissions call `agent.steer()`; ot
 | `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 |
 
 ```yaml
 - id: terminal
@@ -58,7 +67,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. Slash commands and keybindings are TUI-only; command results remain terminal notices.
+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. 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
 
@@ -82,6 +91,20 @@ The selector adds no messages. A target change may alter interpolated system-pro
 
 Changing provider or model enters that target's cache domain; no cache reuse across distinct targets is assumed.
 
+### Manual skill invocation
+
+#### 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.
+
+#### Token effect
+
+The rendered skill block and trailing instructions are retained as one user turn under the agent loop's normal session-history and compaction rules; a repeated invocation appends the body again.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ### Interactive user-question answers
 
 #### What the model sees
@@ -100,4 +123,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **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** — automation must use the headless app rather than expecting an internal fallback.
+- **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.
+- **Manual `/skill:` invocation always reloads the full skill body** — the TUI does not detect a skill already present in the conversation, so repeated invocations append its instructions again.

packages/ui/tui/package.json

@@ -34,13 +34,23 @@
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-llm-retry": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^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",
     "@deepseek-ai/dsh-token-meter": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-user-interaction": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-skill": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@earendil-works/pi-tui": "0.80.7",
     "schemastery": "^3.18.0"
@@ -54,7 +64,9 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tool-cordis": "workspace:^",

packages/ui/tui/tests/harness.ts

@@ -8,7 +8,7 @@ import AgentRegistry, {
 } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock, LlmModelContext, LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
 import CommandService from '@deepseek-ai/dsh-commands'
-import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, type Session, type SessionHeader } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -24,11 +24,16 @@ interface FakeAgent extends Agent {
 export interface TuiHarnessOptions {
   status?: AgentStatus
   config?: Config
+  /** Leave the session event log empty instead of seeding one turn and step. */
+  omitInitialLifecycle?: boolean
+  /** Omit the harness's default `welcome`, exercising the banner sweep-reveal path. */
+  omitWelcome?: boolean
   tools?: Record<string, ToolDefinition>
   configureContext?: (ctx: Context) => Promise<void>
   beforeMount?: (session: Session) => void
   cwd?: string | null
   formatCwd?: TuiRuntime['formatCwd']
+  /** Fake-agent creation options (`provider`/`model` seed the model selector's initial target). */
   agentOptions?: AgentOptions
   contextWindow?: number
   contextTokens?: number
@@ -39,6 +44,8 @@ export interface TuiHarnessOptions {
     listModels?: (provider: string) => Promise<LlmModelInfo[]>
     resolveModelContext?: (provider: string, model: string) => Promise<LlmModelContext | undefined>
   }
+  /** Provide a fake `sessionPersistence` service so resume surfaces can list sessions. */
+  sessionPersistence?: { list(): Promise<SessionHeader[]> }
 }
 
 export interface TuiHarness<TerminalType extends Terminal, Exit extends (code: number) => void> {
@@ -74,19 +81,6 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
       { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'DeepSeek V4 Pro' },
     ],
   }
-  ctx.provide('llm', {
-    listProviders() {
-      return catalog.providers.map(provider => ({ ...provider }))
-    },
-    listModels(provider: string) {
-      return catalog.listModels?.(provider)
-        ?? Promise.resolve(catalog.models.filter(model => model.provider === provider).map(model => ({ ...model })))
-    },
-    resolveModelContext(provider: string, model: string) {
-      return catalog.resolveModelContext?.(provider, model)
-        ?? Promise.resolve({ contextWindow: options.contextWindow ?? 128_000 })
-    },
-  } as never)
   ctx.provide('tokenMeter', {
     measure() {
       return { totalTokens: options.contextTokens ?? 0 }
@@ -102,17 +96,39 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   } else {
     await options.configureContext(ctx)
   }
+  // A configureContext may mount the real LlmService; only fill the
+  // advisory-catalog stub when none was provided.
+  if (ctx.get('llm') === undefined) {
+    ctx.provide('llm', {
+      listProviders() {
+        return catalog.providers.map(provider => ({ ...provider }))
+      },
+      listModels(provider: string) {
+        return catalog.listModels?.(provider)
+          ?? Promise.resolve(catalog.models.filter(model => model.provider === provider).map(model => ({ ...model })))
+      },
+      resolveModelContext(provider: string, model: string) {
+        return catalog.resolveModelContext?.(provider, model)
+          ?? Promise.resolve({ contextWindow: options.contextWindow ?? 128_000 })
+      },
+    } as never)
+  }
   if (ctx.get('systemPrompt') === undefined) await ctx.plugin(SystemPrompt)
+  if (options.sessionPersistence !== undefined) {
+    ctx.provide('sessionPersistence', options.sessionPersistence as never)
+  }
   const sessionId = SessionId('main-session')
   const session = ctx.sessions.create(
     sessionId,
     options.cwd === null ? undefined : { meta: { cwd: options.cwd ?? '/workspace' } },
   )
-  session.append('turn/start', {
-    turn: 1,
-    trigger: { kind: 'message', source: { kind: 'user' } },
-  })
-  session.append('step/start', { turn: 1, step: 1 })
+  if (options.omitInitialLifecycle !== true) {
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    session.append('step/start', { turn: 1, step: 1 })
+  }
   options.beforeMount?.(session)
   const sent: ContentBlock[][] = []
   const steered: ContentBlock[][] = []
@@ -142,13 +158,16 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
   }
   ctx.agents.register(agent)
   const controller = createTuiChat(ctx, Object.assign({
-    welcome: 'Coding agent ready.',
+    ...options.omitWelcome === true ? {} : { welcome: 'Coding agent ready.' },
     sessionId,
     color: false,
   }, options.config), {
     terminal,
     exit,
-    now: options.now ?? (() => 0),
+    // Default to the real clock (runtime.now falls back to Date.now) so the
+    // elapsed-status suites can drive time via timers or Date.now spies; a
+    // test pins the clock only by passing `now` explicitly.
+    ...(options.now === undefined ? {} : { now: options.now }),
     ...(options.formatCwd === undefined ? {} : { formatCwd: options.formatCwd }),
   })
   return { ctx, session, agent, terminal, exit, controller }
@@ -174,7 +193,7 @@ export function appendUser(session: Session, text: string): void {
 export function appendAssistant(
   session: Session,
   content: ContentBlock[],
-  usage?: { inputTokens: number; outputTokens: number },
+  usage?: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number },
   position: { turn: number; step: number } = { turn: 1, step: 1 },
 ): void {
   session.append('assistant/message', {

packages/ui/tui/tests/snapshots/advanced-cards-collapsed.expected.txt

@@ -1,108 +1,99 @@
-terminal 100x40 buffer=normal length=41 base=1 viewport=1
+terminal 100x40 buffer=normal length=40 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=37 bufferRow=38
+cursor hidden column=1 viewportRow=36 bufferRow=36
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-99 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                                 │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 99-99 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                            │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 99-99 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                               │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 99-99 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-99 fg=bright-blue
-5| <blank>
-6| "▌ "
+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| "▌ "
   style 0-0 fg=green
-7| "▌ ✓ pnpm run test:coverage                                                                          "
+5| "▌ ✓ pnpm run test:coverage                                                                          "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-25 bold
-8| "▌ Run the coverage gate                                                                             "
+6| "▌ Run the coverage gate                                                                             "
   style 0-0 fg=green
   style 2-22 fg=bright-black
-9| "▌ /workspace/project                                                                                "
+7| "▌ /workspace/project                                                                                "
   style 0-0 fg=green
   style 2-19 dim
-10| "▌ … +4 lines (Ctrl+O to expand)                                                                     "
+8| "▌ … +4 lines (Ctrl+O to expand)                                                                     "
   style 0-0 fg=green
   style 2-30 dim
-11| "▌ [exit 0]                                                                                          "
+9| "▌ [exit 0]                                                                                          "
   style 0-0 fg=green
   style 2-9 dim
+10| "▌ "
+  style 0-0 fg=green
+11| <blank>
 12| "▌ "
   style 0-0 fg=green
-13| <blank>
-14| "▌ "
-  style 0-0 fg=green
-15| "▌ ✓ Edit renderer                                                                                   "
+13| "▌ ✓ Edit renderer                                                                                   "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-16 bold
-16| "▌ src/view.ts                                                                                       "
+14| "▌ src/view.ts                                                                                       "
   style 0-0 fg=green
   style 2-12 bold
-17| "▌ - old line                                                                                        "
+15| "▌ - old line                                                                                        "
   style 0-0 fg=green
   style 2-11 fg=red
-18| "▌ … +5 lines (Ctrl+O to expand)                                                                     "
+16| "▌ … +5 lines (Ctrl+O to expand)                                                                     "
   style 0-0 fg=green
   style 2-30 dim
-19| "▌ + expect(screen).toMatchSnapshot()                                                                "
+17| "▌ + expect(screen).toMatchSnapshot()                                                                "
   style 0-0 fg=green
   style 2-35 fg=green
+18| "▌ "
+  style 0-0 fg=green
+19| <blank>
 20| "▌ "
   style 0-0 fg=green
-21| <blank>
-22| "▌ "
-  style 0-0 fg=green
-23| "▌ ✓ Delegate renderer audit                                                                         "
+21| "▌ ✓ Delegate renderer audit                                                                         "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-26 bold
-24| "▌ The renderer has explicit lifecycle ownership.                                                    "
+22| "▌ The renderer has explicit lifecycle ownership.                                                    "
   style 0-0 fg=green
+23| "▌ "
+  style 0-0 fg=green
+24| <blank>
 25| "▌ "
   style 0-0 fg=green
-26| <blank>
-27| "▌ "
-  style 0-0 fg=green
-28| "▌ ✓ Read output from background task subagent-7                                                     "
+26| "▌ ✓ Read output from background task subagent-7                                                     "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-46 bold
-29| "▌ audit complete                                                                                    "
+27| "▌ audit complete                                                                                    "
   style 0-0 fg=green
-30| "▌ [status: completed]                                                                               "
+28| "▌ [status: completed]                                                                               "
   style 0-0 fg=green
+29| "▌ "
+  style 0-0 fg=green
+30| <blank>
 31| "▌ "
   style 0-0 fg=green
-32| <blank>
-33| "▌ "
-  style 0-0 fg=green
-34| "▌ ✓ Load skill dsh-code-review                                                                      "
+32| "▌ ✓ Load skill dsh-code-review                                                                      "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-29 bold
-35| "▌ Loaded review instructions.                                                                       "
+33| "▌ Loaded review instructions.                                                                       "
   style 0-0 fg=green
-36| "▌ "
+34| "▌ "
   style 0-0 fg=green
+35| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+36| "                                                                                                    "
+  style 1-1 inverse
 37| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-38| "                                                                                                    "
-  style 1-1 inverse
-39| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-40| "/workspace/project  ↑0 ↓0                 0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 42-99 dim
+38| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                             0% context  tools:collapsed"
+  style 0-43 dim
+  style 73-99 dim
+39| <blank>

packages/ui/tui/tests/snapshots/advanced-cards-expanded.expected.txt

@@ -1,127 +1,117 @@
-terminal 100x40 buffer=normal length=50 base=10 viewport=10
+terminal 100x40 buffer=normal length=48 base=8 viewport=8
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=37 bufferRow=47
+cursor hidden column=1 viewportRow=37 bufferRow=45
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-99 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                                 │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 99-99 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                            │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 99-99 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                               │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 99-99 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-99 fg=bright-blue
-5| <blank>
-6| "▌ "
+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| "▌ "
   style 0-0 fg=green
-7| "▌ ✓ pnpm run test:coverage                                                                          "
+5| "▌ ✓ pnpm run test:coverage                                                                          "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-25 bold
-8| "▌ Run the coverage gate                                                                             "
+6| "▌ Run the coverage gate                                                                             "
   style 0-0 fg=green
   style 2-22 fg=bright-black
-9| "▌ /workspace/project                                                                                "
+7| "▌ /workspace/project                                                                                "
   style 0-0 fg=green
   style 2-19 dim
-10| "▌ packages/ui/tui 100%                                                                              "
+8| "▌ packages/ui/tui 100%                                                                              "
   style 0-0 fg=green
-11| "▌ 4016 tests passed                                                                                 "
+9| "▌ 4016 tests passed                                                                                 "
   style 0-0 fg=green
-12| "▌ 1 test skipped                                                                                    "
+10| "▌ 1 test skipped                                                                                    "
   style 0-0 fg=green
-13| "▌ coverage complete                                                                                 "
+11| "▌ coverage complete                                                                                 "
   style 0-0 fg=green
-14| "▌ [exit 0]                                                                                          "
+12| "▌ [exit 0]                                                                                          "
   style 0-0 fg=green
   style 2-9 dim
+13| "▌ "
+  style 0-0 fg=green
+14| <blank>
 15| "▌ "
   style 0-0 fg=green
-16| <blank>
-17| "▌ "
-  style 0-0 fg=green
-18| "▌ ✓ Edit renderer                                                                                   "
+16| "▌ ✓ Edit renderer                                                                                   "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-16 bold
-19| "▌ src/view.ts                                                                                       "
+17| "▌ src/view.ts                                                                                       "
   style 0-0 fg=green
   style 2-12 bold
-20| "▌ - old line                                                                                        "
+18| "▌ - old line                                                                                        "
   style 0-0 fg=green
   style 2-11 fg=red
-21| "▌ - keep                                                                                            "
+19| "▌ - keep                                                                                            "
   style 0-0 fg=green
   style 2-7 fg=red
-22| "▌ + new line                                                                                        "
+20| "▌ + new line                                                                                        "
   style 0-0 fg=green
   style 2-11 fg=green
-23| "▌ + keep                                                                                            "
+21| "▌ + keep                                                                                            "
   style 0-0 fg=green
   style 2-7 fg=green
-24| "▌                                                                                                   "
+22| "▌                                                                                                   "
   style 0-0 fg=green
-25| "▌ tests/view.spec.ts                                                                                "
+23| "▌ tests/view.spec.ts                                                                                "
   style 0-0 fg=green
   style 2-19 bold
-26| "▌ + expect(screen).toMatchSnapshot()                                                                "
+24| "▌ + expect(screen).toMatchSnapshot()                                                                "
   style 0-0 fg=green
   style 2-35 fg=green
+25| "▌ "
+  style 0-0 fg=green
+26| <blank>
 27| "▌ "
   style 0-0 fg=green
-28| <blank>
-29| "▌ "
-  style 0-0 fg=green
-30| "▌ ✓ Delegate renderer audit                                                                         "
+28| "▌ ✓ Delegate renderer audit                                                                         "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-26 bold
-31| "▌ The renderer has explicit lifecycle ownership.                                                    "
+29| "▌ The renderer has explicit lifecycle ownership.                                                    "
   style 0-0 fg=green
+30| "▌ "
+  style 0-0 fg=green
+31| <blank>
 32| "▌ "
   style 0-0 fg=green
-33| <blank>
-34| "▌ "
-  style 0-0 fg=green
-35| "▌ ✓ Read output from background task subagent-7                                                     "
+33| "▌ ✓ Read output from background task subagent-7                                                     "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-46 bold
-36| "▌ audit complete                                                                                    "
+34| "▌ audit complete                                                                                    "
   style 0-0 fg=green
-37| "▌ [status: completed]                                                                               "
+35| "▌ [status: completed]                                                                               "
   style 0-0 fg=green
+36| "▌ "
+  style 0-0 fg=green
+37| <blank>
 38| "▌ "
   style 0-0 fg=green
-39| <blank>
-40| "▌ "
-  style 0-0 fg=green
-41| "▌ ✓ Load skill dsh-code-review                                                                      "
+39| "▌ ✓ Load skill dsh-code-review                                                                      "
   style 0-0 fg=green
   style 2-2 fg=green bold
   style 3-29 bold
-42| "▌ Loaded review instructions.                                                                       "
+40| "▌ Loaded review instructions.                                                                       "
   style 0-0 fg=green
-43| "▌ "
+41| "▌ "
   style 0-0 fg=green
-44| <blank>
-45| " Tool cards expanded.                                                                               "
+42| <blank>
+43| " Tool cards expanded.                                                                               "
   style 1-20 fg=bright-black
+44| "────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-99 dim
+45| "                                                                                                    "
+  style 1-1 inverse
 46| "────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-99 dim
-47| "                                                                                                    "
-  style 1-1 inverse
-48| "────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-99 dim
-49| "/workspace/project  ↑0 ↓0                0% context  tools:expanded  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 41-99 dim
+47| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                              0% context  tools:expanded"
+  style 0-43 dim
+  style 74-99 dim

packages/ui/tui/tests/snapshots/banner-gradient.expected.txt

@@ -0,0 +1,29 @@
+terminal 96x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=1 viewportRow=4 bufferRow=4
+viewport
+0| " DEEPSEEK HARNESS"
+  style 1-1 fg=#4d6bfe bold
+  style 2-2 fg=#4772fe bold
+  style 3-3 fg=#4278ff bold
+  style 4-4 fg=#3c7fff bold
+  style 5-5 fg=#3685ff bold
+  style 6-6 fg=#308bff bold
+  style 7-7 fg=#2a92ff bold
+  style 8-8 fg=#2498ff 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| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+4| "                                                                                                "
+  style 1-1 inverse
+5| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+6| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+7-35| <blank>

packages/ui/tui/tests/snapshots/code-mode-pending.expected.txt

@@ -1,52 +1,42 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=15 bufferRow=15
+cursor hidden column=1 viewportRow=13 bufferRow=13
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ "
+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| "▌ "
   style 0-0 fg=yellow
-7| "▌ ◌ const first = await tools.bash({ command: 'echo CODE_ONE' })                                "
+5| "▌ ◌ const first = await tools.bash({ command: 'echo CODE_ONE' })                                "
   style 0-0 fg=yellow
   style 2-2 fg=yellow bold
   style 3-95 bold
-8| "▌ const second = await tools.bas                                                                "
+6| "▌ const second = await tools.bas                                                                "
   style 0-0 fg=yellow
   style 2-31 bold
-9| "▌ const first = await tools.bash({ command: 'echo CODE_ONE' })                                  "
+7| "▌ const first = await tools.bash({ command: 'echo CODE_ONE' })                                  "
   style 0-0 fg=yellow
-10| "▌ const second = await tools.bash({ command: 'echo CODE_TWO' })                                 "
+8| "▌ const second = await tools.bash({ command: 'echo CODE_TWO' })                                 "
   style 0-0 fg=yellow
-11| "▌ console.log(first, second)                                                                    "
+9| "▌ console.log(first, second)                                                                    "
   style 0-0 fg=yellow
-12| "▌ return `${first}+${second}`                                                                   "
+10| "▌ return `${first}+${second}`                                                                   "
   style 0-0 fg=yellow
-13| "▌ "
+11| "▌ "
   style 0-0 fg=yellow
+12| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+13| "                                                                                                "
+  style 1-1 inverse
 14| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-15| "                                                                                                "
-  style 1-1 inverse
-16| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-17| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 38-95 dim
-18-35| <blank>
+15| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+16-35| <blank>

packages/ui/tui/tests/snapshots/conversation-streaming.expected.txt

@@ -3,50 +3,44 @@ lifecycle started=1 stopped=0 progress=active
 title "DSH snapshot"
 cursor hidden column=1 viewportRow=17 bufferRow=17
 viewport
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
+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| "▌ "
   style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ "
-  style 0-0 fg=bright-blue
-7| "▌ You                                                                                           "
+5| "▌ You                                                                                           "
   style 0-0 fg=bright-blue
   style 2-4 fg=bright-blue bold
-8| "▌ Show the live update.                                                                         "
+6| "▌ Show the live update.                                                                         "
   style 0-0 fg=bright-blue
-9| "▌ "
+7| "▌ "
   style 0-0 fg=bright-blue
-10| <blank>
-11| " Reasoning                                                                                      "
+8| <blank>
+9| " Reasoning                                                                                      "
   style 1-9 fg=bright-black italic
-12| " Inspecting width and styles.                                                                   "
+10| " Inspecting width and styles.                                                                   "
   style 1-28 fg=bright-black italic
-13| <blank>
-14| " Assistant                                                                                      "
+11| <blank>
+12| " Assistant                                                                                      "
   style 1-9 fg=bright-magenta bold
-15| " Streaming visible state…                                                                       "
+13| " Streaming visible state…                                                                       "
   style 11-23 bold
+14| <blank>
+15| " ⠋ Responding 0s · total 0s — Enter sends steering, Esc cancels                                 "
+  style 1-1 fg=bright-blue
+  style 3-62 fg=bright-black
 16| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 fg=bright-blue
 17| "                                                                                                "
   style 1-1 inverse
 18| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 fg=bright-blue
-19| "◒ Working · 0s                                                                     esc interrupt"
-  style 0-13 fg=bright-blue
-  style 83-95 dim
+19| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
 20-35| <blank>

packages/ui/tui/tests/snapshots/cordis-tools-pending.expected.txt

@@ -1,59 +1,49 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=18 bufferRow=18
+cursor hidden column=1 viewportRow=16 bufferRow=16
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ ◌ Inspect cordis runtime: tools                                                               "
+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| "▌ ◌ Inspect cordis runtime: tools                                                               "
   style 0-0 fg=yellow
   style 2-2 fg=yellow bold
   style 3-32 bold
-7| <blank>
-8| "▌ "
+5| <blank>
+6| "▌ "
   style 0-0 fg=yellow
-9| "▌ ◌ Mount plugin into live cordis runtime                                                       "
+7| "▌ ◌ Mount plugin into live cordis runtime                                                       "
   style 0-0 fg=yellow
   style 2-2 fg=yellow bold
   style 3-40 bold
-10| "▌ {                                                                                             "
+8| "▌ {                                                                                             "
   style 0-0 fg=yellow
-11| "▌   \"code\": \"return { name: 'snapshot-marker', apply(ctx) { ctx.provide('snapshotMarker', {     "
+9| "▌   \"code\": \"return { name: 'snapshot-marker', apply(ctx) { ctx.provide('snapshotMarker', {     "
   style 0-0 fg=yellow
-12| "▌ ready: true }) } }\"                                                                           "
+10| "▌ ready: true }) } }\"                                                                           "
   style 0-0 fg=yellow
-13| "▌ }                                                                                             "
+11| "▌ }                                                                                             "
   style 0-0 fg=yellow
-14| "▌ "
+12| "▌ "
   style 0-0 fg=yellow
-15| <blank>
-16| "▌ ◌ Unmount dyn-1                                                                               "
+13| <blank>
+14| "▌ ◌ Unmount dyn-1                                                                               "
   style 0-0 fg=yellow
   style 2-2 fg=yellow bold
   style 3-16 bold
+15| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+16| "                                                                                                "
+  style 1-1 inverse
 17| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-18| "                                                                                                "
-  style 1-1 inverse
-19| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-20| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 38-95 dim
-21-35| <blank>
+18| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+19-35| <blank>

packages/ui/tui/tests/snapshots/disposed-terminal.expected.txt

@@ -1,67 +1,63 @@
 terminal 92x32 buffer=normal length=32 base=0 viewport=0
 lifecycle started=1 stopped=1 progress=inactive
 title "DSH snapshot"
-cursor visible column=0 viewportRow=30 bufferRow=30
+cursor visible column=0 viewportRow=31 bufferRow=31
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-91 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                         │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 91-91 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                    │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 91-91 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                       │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 91-91 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-91 fg=bright-blue
-5| <blank>
-6| " Keyboard shortcuts                                                                         "
+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| " Keyboard shortcuts                                                                         "
   style 1-18 fg=bright-blue bold
-7| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
+5| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
   style 1-61 fg=bright-black
-8| " Esc cancel active turn • Ctrl+O toggle tool cards • Ctrl+R toggle reasoning                "
+6| " Esc cancel active turn • Ctrl+O toggle tool cards • Ctrl+R toggle reasoning                "
   style 1-75 fg=bright-black
-9| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
+7| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
   style 1-73 fg=bright-black
-10| "                                                                                            "
-11| " /cancel — Cancel the active turn                                                           "
-  style 1-32 fg=bright-black
-12| " /clear — Clear the transcript view (session history is unchanged)                          "
+8| "                                                                                            "
+9| " /clear — Clear the transcript view (session history is unchanged)                          "
   style 1-65 fg=bright-black
-13| " /exit — Exit after the active turn reaches idle                                            "
+10| " /exit — Exit after the active turn reaches idle                                            "
   style 1-47 fg=bright-black
-14| " /help — Show keyboard shortcuts and commands                                               "
+11| " /help — Show keyboard shortcuts and commands                                               "
   style 1-44 fg=bright-black
-15| " /model [[provider/]model] — Show or switch this session's model                            "
+12| " /model [[provider/]model] — Show or switch this session's model                            "
   style 1-63 fg=bright-black
-16| " /reasoning — Toggle reasoning blocks                                                       "
+13| " /reasoning — Toggle reasoning blocks                                                       "
   style 1-36 fg=bright-black
-17| " /redraw — Invalidate components and redraw the terminal                                    "
+14| " /redraw — Invalidate components and redraw the terminal                                    "
   style 1-55 fg=bright-black
+15| " /reload — EXPERIMENTAL (dev): re-read loader config files and apply the diff (idle only)   "
+  style 1-88 fg=bright-black
+16| " /resume — List this workspace's resumable sessions                                         "
+  style 1-50 fg=bright-black
+17| " /status — Show detailed session diagnostics                                                "
+  style 1-43 fg=bright-black
 18| " /tools — Expand or collapse all tool cards                                                 "
   style 1-42 fg=bright-black
-19| <blank>
-20| " provider stream failed after partial output                                                "
+19| " /skill:<name> [instructions] — load a skill into the conversation                          "
+  style 1-65 fg=bright-black
+20| <blank>
+21| " provider stream failed after partial output                                                "
   style 1-43 fg=red
-21| <blank>
-22| " The previous process ended during this turn.                                               "
+22| <blank>
+23| " The previous process ended during this turn.                                               "
   style 1-44 fg=yellow
-23| <blank>
-24| " Unknown command: /unknown-advanced-command                                                 "
+24| <blank>
+25| " Unknown command: /unknown-advanced-command                                                 "
   style 1-42 fg=yellow
-25| "────────────────────────────────────────────────────────────────────────────────────────────"
+26| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-26| "                                                                                            "
+27| "                                                                                            "
   style 1-1 inverse
-27| "────────────────────────────────────────────────────────────────────────────────────────────"
+28| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-28| "/workspace/project  ↑0 ↓0         0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 34-91 dim
-29-31| <blank>
+29| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                     0% context  tools:collapsed"
+  style 0-43 dim
+  style 65-91 dim
+30-31| <blank>

packages/ui/tui/tests/snapshots/dynamic-workflow-pending.expected.txt

@@ -1,56 +1,46 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=17 bufferRow=17
+cursor hidden column=1 viewportRow=15 bufferRow=15
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ "
+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| "▌ "
   style 0-0 fg=yellow
-7| "▌ ◌ workflow: tui-matrix                                                                        "
+5| "▌ ◌ workflow: tui-matrix                                                                        "
   style 0-0 fg=yellow
   style 2-2 fg=yellow bold
   style 3-23 bold
-8| "▌ phase('Inspect')                                                                              "
+6| "▌ phase('Inspect')                                                                              "
   style 0-0 fg=yellow
-9| "▌ const reports = await parallel([                                                              "
+7| "▌ const reports = await parallel([                                                              "
   style 0-0 fg=yellow
-10| "▌   () => agent('Audit layout', { label: 'layout', phase: 'Inspect' }),                         "
+8| "▌   () => agent('Audit layout', { label: 'layout', phase: 'Inspect' }),                         "
   style 0-0 fg=yellow
-11| "▌ … +1 lines (Ctrl+O to expand)                                                                 "
+9| "▌ … +1 lines (Ctrl+O to expand)                                                                 "
   style 0-0 fg=yellow
   style 2-30 dim
-12| "▌ ])                                                                                            "
+10| "▌ ])                                                                                            "
   style 0-0 fg=yellow
-13| "▌ phase('Verify')                                                                               "
+11| "▌ phase('Verify')                                                                               "
   style 0-0 fg=yellow
-14| "▌ return { reports, verdict: 'covered' }                                                        "
+12| "▌ return { reports, verdict: 'covered' }                                                        "
   style 0-0 fg=yellow
-15| "▌ "
+13| "▌ "
   style 0-0 fg=yellow
+14| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+15| "                                                                                                "
+  style 1-1 inverse
 16| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-17| "                                                                                                "
-  style 1-1 inverse
-18| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-19| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 38-95 dim
-20-35| <blank>
+17| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+18-35| <blank>

packages/ui/tui/tests/snapshots/errors-and-help.expected.txt

@@ -1,67 +1,63 @@
 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=26 bufferRow=26
+cursor hidden column=1 viewportRow=27 bufferRow=27
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-91 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                         │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 91-91 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                    │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 91-91 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                       │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 91-91 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-91 fg=bright-blue
-5| <blank>
-6| " Keyboard shortcuts                                                                         "
+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| " Keyboard shortcuts                                                                         "
   style 1-18 fg=bright-blue bold
-7| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
+5| " Enter send • Shift/Alt+Enter newline • Up/Down prompt history                              "
   style 1-61 fg=bright-black
-8| " Esc cancel active turn • Ctrl+O toggle tool cards • Ctrl+R toggle reasoning                "
+6| " Esc cancel active turn • Ctrl+O toggle tool cards • Ctrl+R toggle reasoning                "
   style 1-75 fg=bright-black
-9| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
+7| " Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                  "
   style 1-73 fg=bright-black
-10| "                                                                                            "
-11| " /cancel — Cancel the active turn                                                           "
-  style 1-32 fg=bright-black
-12| " /clear — Clear the transcript view (session history is unchanged)                          "
+8| "                                                                                            "
+9| " /clear — Clear the transcript view (session history is unchanged)                          "
   style 1-65 fg=bright-black
-13| " /exit — Exit after the active turn reaches idle                                            "
+10| " /exit — Exit after the active turn reaches idle                                            "
   style 1-47 fg=bright-black
-14| " /help — Show keyboard shortcuts and commands                                               "
+11| " /help — Show keyboard shortcuts and commands                                               "
   style 1-44 fg=bright-black
-15| " /model [[provider/]model] — Show or switch this session's model                            "
+12| " /model [[provider/]model] — Show or switch this session's model                            "
   style 1-63 fg=bright-black
-16| " /reasoning — Toggle reasoning blocks                                                       "
+13| " /reasoning — Toggle reasoning blocks                                                       "
   style 1-36 fg=bright-black
-17| " /redraw — Invalidate components and redraw the terminal                                    "
+14| " /redraw — Invalidate components and redraw the terminal                                    "
   style 1-55 fg=bright-black
+15| " /reload — EXPERIMENTAL (dev): re-read loader config files and apply the diff (idle only)   "
+  style 1-88 fg=bright-black
+16| " /resume — List this workspace's resumable sessions                                         "
+  style 1-50 fg=bright-black
+17| " /status — Show detailed session diagnostics                                                "
+  style 1-43 fg=bright-black
 18| " /tools — Expand or collapse all tool cards                                                 "
   style 1-42 fg=bright-black
-19| <blank>
-20| " provider stream failed after partial output                                                "
+19| " /skill:<name> [instructions] — load a skill into the conversation                          "
+  style 1-65 fg=bright-black
+20| <blank>
+21| " provider stream failed after partial output                                                "
   style 1-43 fg=red
-21| <blank>
-22| " The previous process ended during this turn.                                               "
+22| <blank>
+23| " The previous process ended during this turn.                                               "
   style 1-44 fg=yellow
-23| <blank>
-24| " Unknown command: /unknown-advanced-command                                                 "
+24| <blank>
+25| " Unknown command: /unknown-advanced-command                                                 "
   style 1-42 fg=yellow
-25| "────────────────────────────────────────────────────────────────────────────────────────────"
+26| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-26| "                                                                                            "
+27| "                                                                                            "
   style 1-1 inverse
-27| "────────────────────────────────────────────────────────────────────────────────────────────"
+28| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-28| "/workspace/project  ↑0 ↓0         0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 34-91 dim
-29-31| <blank>
+29| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                     0% context  tools:collapsed"
+  style 0-43 dim
+  style 65-91 dim
+30-31| <blank>

packages/ui/tui/tests/snapshots/model-selector.expected.txt

@@ -3,33 +3,23 @@ lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
 cursor hidden column=0 viewportRow=31 bufferRow=31
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-91 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                         │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 91-91 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                    │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 91-91 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                       │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 91-91 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-91 fg=bright-blue
+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| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+4| "                                                                                            "
+  style 1-1 inverse
 5| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-6| "                                                                                            "
-  style 1-1 inverse
-7| "────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-91 dim
-8| "/workspace/project  ↑0 ↓0         0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 34-91 dim
-9-12| <blank>
+6| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                     0% context  tools:collapsed"
+  style 0-43 dim
+  style 65-91 dim
+7-12| <blank>
 13| "          ╭ Select model ────────────────────────────────────────────────────────╮          "
   style 10-81 fg=bright-blue
 14| "          │ → deepseek/deepseek-v4-flash      DeepSeek V4 Flash — current        │          "

packages/ui/tui/tests/snapshots/model-switching.expected.txt

@@ -1,35 +1,25 @@
 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=8 bufferRow=8
+cursor hidden column=1 viewportRow=6 bufferRow=6
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-91 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                         │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 91-91 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                    │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 91-91 fg=bright-blue
-3| "│ deepseek-v4-pro  •  main-session                                                         │"
-  style 0-0 fg=bright-blue
-  style 2-33 dim
-  style 91-91 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-91 fg=bright-blue
-5| <blank>
-6| " Model selected: deepseek/deepseek-v4-pro. New steps will use it.                           "
+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-pro  •  main-session"
+  style 1-32 dim
+3| <blank>
+4| " Model selected: deepseek/deepseek-v4-pro. New steps will use it.                           "
   style 1-64 fg=bright-black
+5| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+6| "                                                                                            "
+  style 1-1 inverse
 7| "────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-91 dim
-8| "                                                                                            "
-  style 1-1 inverse
-9| "────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-91 dim
-10| "/workspace/project  ↑0 ↓0           0% context  tools:compact  deepseek-v4-pro(reasoning:on)"
-  style 0-24 dim
-  style 36-91 dim
-11-31| <blank>
+8| "deepseek-v4-pro  /workspace/project  ↑0 ↓0                       0% context  tools:collapsed"
+  style 0-41 dim
+  style 65-91 dim
+9-31| <blank>

packages/ui/tui/tests/snapshots/question-dialog-validation.expected.txt

@@ -3,23 +3,17 @@ lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
 cursor hidden column=56 viewportRow=17 bufferRow=17
 viewport
-0| "╭──────────────────────────────────────────────────────╮"
-  style 0-55 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                     │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 55-55 fg=bright-blue
-2| "│ Snapshot agent ready.                                │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 55-55 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                   │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 55-55 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────╯"
-  style 0-55 fg=bright-blue
+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| "────────────────────────────────────────────────────────"
+  style 0-55 dim
+4| "                                                        "
+  style 1-1 inverse
 5| "                                                        "
 6| "  Question 1/3 (3 unanswered) · Coverage                "
   style 2-39 fg=bright-black

packages/ui/tui/tests/snapshots/question-dialog.expected.txt

@@ -3,27 +3,22 @@ lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
 cursor hidden column=0 viewportRow=19 bufferRow=19
 viewport
-0| "╭──────────────────────────────────────────────────────╮"
-  style 0-55 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                     │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 55-55 fg=bright-blue
-2| "│ Snapshot agent ready.                                │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 55-55 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                   │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 55-55 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────╯"
-  style 0-55 fg=bright-blue
+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| "────────────────────────────────────────────────────────"
+  style 0-55 dim
+4| "                                                        "
+  style 1-1 inverse
 5| "────────────────────────────────────────────────────────"
   style 0-55 dim
-6| "                                                        "
-  style 1-1 inverse
+6| "deepseek-v4-flash  /workspace/project  ↑0 ↓0  0% context"
+  style 0-43 dim
+  style 46-55 dim
 7| "                                                        "
 8| "  Question 1/3 (3 unanswered) · Coverage                "
   style 2-39 fg=bright-black

packages/ui/tui/tests/snapshots/resume-sessions.expected.txt

@@ -0,0 +1,32 @@
+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
+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>

packages/ui/tui/tests/snapshots/retry-cancelled.expected.txt

@@ -1,48 +1,38 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=15 bufferRow=15
+cursor hidden column=1 viewportRow=13 bufferRow=13
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
+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| "▌ "
   style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ "
-  style 0-0 fg=bright-blue
-7| "▌ You                                                                                           "
+5| "▌ You                                                                                           "
   style 0-0 fg=bright-blue
   style 2-4 fg=bright-blue bold
-8| "▌ Start then cancel.                                                                            "
+6| "▌ Start then cancel.                                                                            "
   style 0-0 fg=bright-blue
-9| "▌ "
+7| "▌ "
   style 0-0 fg=bright-blue
-10| <blank>
-11| " Retrying model request (1/2) in 1000ms: temporary transport failure                            "
+8| <blank>
+9| " Retrying model request (1/2) in 1000ms: temporary transport failure                            "
   style 1-67 fg=yellow
-12| <blank>
-13| " Turn cancelled.                                                                                "
+10| <blank>
+11| " Turn cancelled.                                                                                "
   style 1-15 fg=yellow
+12| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+13| "                                                                                                "
+  style 1-1 inverse
 14| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-15| "                                                                                                "
-  style 1-1 inverse
-16| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-17| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 38-95 dim
-18-35| <blank>
+15| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+16-35| <blank>

packages/ui/tui/tests/snapshots/retry-exhausted.expected.txt

@@ -1,45 +1,35 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=13 bufferRow=13
+cursor hidden column=1 viewportRow=11 bufferRow=11
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
+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| "▌ "
   style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ "
-  style 0-0 fg=bright-blue
-7| "▌ You                                                                                           "
+5| "▌ You                                                                                           "
   style 0-0 fg=bright-blue
   style 2-4 fg=bright-blue bold
-8| "▌ Let the bounded policy exhaust.                                                               "
+6| "▌ Let the bounded policy exhaust.                                                               "
   style 0-0 fg=bright-blue
-9| "▌ "
+7| "▌ "
   style 0-0 fg=bright-blue
-10| <blank>
-11| " provider still unavailable                                                                     "
+8| <blank>
+9| " provider still unavailable                                                                     "
   style 1-26 fg=red
+10| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+11| "                                                                                                "
+  style 1-1 inverse
 12| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-13| "                                                                                                "
-  style 1-1 inverse
-14| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-15| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 38-95 dim
-16-35| <blank>
+13| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+14-35| <blank>

packages/ui/tui/tests/snapshots/retry-recovered.expected.txt

@@ -1,49 +1,39 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=16 bufferRow=16
+cursor hidden column=1 viewportRow=14 bufferRow=14
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
+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| "▌ "
   style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ "
-  style 0-0 fg=bright-blue
-7| "▌ You                                                                                           "
+5| "▌ You                                                                                           "
   style 0-0 fg=bright-blue
   style 2-4 fg=bright-blue bold
-8| "▌ Recover this request.                                                                         "
+6| "▌ Recover this request.                                                                         "
   style 0-0 fg=bright-blue
-9| "▌ "
+7| "▌ "
   style 0-0 fg=bright-blue
-10| <blank>
-11| " Retrying model request (1/2) in 500ms: provider rate limit                                     "
+8| <blank>
+9| " Retrying model request (1/2) in 500ms: provider rate limit                                     "
   style 1-58 fg=yellow
-12| <blank>
-13| " Assistant                                                                                      "
+10| <blank>
+11| " Assistant                                                                                      "
   style 1-9 fg=bright-magenta bold
-14| " Recovered on the next bounded attempt.                                                         "
+12| " Recovered on the next bounded attempt.                                                         "
+13| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+14| "                                                                                                "
+  style 1-1 inverse
 15| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-16| "                                                                                                "
-  style 1-1 inverse
-17| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-18| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 38-95 dim
-19-35| <blank>
+16| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+17-35| <blank>

packages/ui/tui/tests/snapshots/retry-scheduled.expected.txt

@@ -1,45 +1,35 @@
 terminal 96x36 buffer=normal length=36 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=13 bufferRow=13
+cursor hidden column=1 viewportRow=11 bufferRow=11
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-95 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                             │"
+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| "▌ "
   style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 95-95 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                        │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 95-95 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                           │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 95-95 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-95 fg=bright-blue
-5| <blank>
-6| "▌ "
-  style 0-0 fg=bright-blue
-7| "▌ You                                                                                           "
+5| "▌ You                                                                                           "
   style 0-0 fg=bright-blue
   style 2-4 fg=bright-blue bold
-8| "▌ Recover this request.                                                                         "
+6| "▌ Recover this request.                                                                         "
   style 0-0 fg=bright-blue
-9| "▌ "
+7| "▌ "
   style 0-0 fg=bright-blue
-10| <blank>
-11| " Retrying model request (1/2) in 500ms: provider rate limit                                     "
+8| <blank>
+9| " Retrying model request (1/2) in 500ms: provider rate limit                                     "
   style 1-58 fg=yellow
+10| "────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-95 dim
+11| "                                                                                                "
+  style 1-1 inverse
 12| "────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-95 dim
-13| "                                                                                                "
-  style 1-1 inverse
-14| "────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-95 dim
-15| "/workspace/project  ↑0 ↓0             0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 38-95 dim
-16-35| <blank>
+13| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                         0% context  tools:collapsed"
+  style 0-43 dim
+  style 69-95 dim
+14-35| <blank>

packages/ui/tui/tests/snapshots/status-diagnostics-narrow.expected.txt

@@ -0,0 +1,110 @@
+terminal 56x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "Inspect session diagnostics — DSH snapshot"
+cursor hidden column=1 viewportRow=32 bufferRow=32
+buffer
+0| " DEEPSEEK HARNESS"
+  style 1-8 fg=bright-blue bold
+  style 10-16 bold
+1| " Inspect session diagnostics"
+  style 1-27 fg=bright-black
+2| " deepseek-v4-pro  •  main-session"
+  style 1-32 dim
+3| <blank>
+4| "▌ "
+  style 0-0 fg=bright-blue
+5| "▌ You                                                   "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+6| "▌ inspect this session                                  "
+  style 0-0 fg=bright-blue
+7| "▌ "
+  style 0-0 fg=bright-blue
+8| <blank>
+9| " Assistant                                              "
+  style 1-9 fg=bright-magenta bold
+10| " Session inspected.                                     "
+11| <blank>
+12| "╭─ Session status ─────────────────────────────────────╮"
+  style 0-2 dim
+  style 3-16 fg=bright-blue bold
+  style 17-55 dim
+13| "│  Session:    main-session                            │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 55-55 dim
+14| "│  Title:      Inspect session diagnostics             │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 55-55 dim
+15| "│  Directory:  /workspace/project                      │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 55-55 dim
+16| "│  Model:      deepseek/deepseek-v4-pro (reasoning     │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 40-55 dim
+17| "│              shown)                                  │"
+  style 0-0 dim
+  style 15-20 dim
+  style 55-55 dim
+18| "│                                                      │"
+  style 0-0 dim
+  style 55-55 dim
+19| "│  Agent:      idle · 6 events · 1 turn · 1 step · 1   │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 55-55 dim
+20| "│              tool call                               │"
+  style 0-0 dim
+  style 55-55 dim
+21| "│                                                      │"
+  style 0-0 dim
+  style 55-55 dim
+22| "│  Tokens:     1,250 input + 340 output                │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 55-55 dim
+23| "│  KV cache:   [███████████░░░░░] 67% hit (3,000 read  │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 15-15 dim
+  style 16-26 fg=bright-blue
+  style 27-32 dim
+  style 55-55 dim
+24| "│              + 250 write)                            │"
+  style 0-0 dim
+  style 55-55 dim
+25| "│  Context:    [█████░░░░░░░░░░░] 33% used (42,000 /   │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 15-15 dim
+  style 16-20 fg=bright-blue
+  style 21-32 dim
+  style 55-55 dim
+26| "│              128,000)                                │"
+  style 0-0 dim
+  style 55-55 dim
+27| "│                                                      │"
+  style 0-0 dim
+  style 55-55 dim
+28| "│  Created:    2026-07-22 09:10:11 UTC                 │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 55-55 dim
+29| "│  Active:     2026-07-22 09:10:11 UTC                 │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 55-55 dim
+30| "╰──────────────────────────────────────────────────────╯"
+  style 0-55 dim
+31| "────────────────────────────────────────────────────────"
+  style 0-55 dim
+32| "                                                        "
+  style 1-1 inverse
+33| "────────────────────────────────────────────────────────"
+  style 0-55 dim
+34| "deepseek-v4-pro  /workspace/project  ↑1.3k ↓340  cache 6"
+  style 0-55 dim
+35| <blank>

packages/ui/tui/tests/snapshots/status-diagnostics.expected.txt

@@ -0,0 +1,99 @@
+terminal 92x32 buffer=normal length=32 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "Inspect session diagnostics — DSH snapshot"
+cursor hidden column=1 viewportRow=28 bufferRow=28
+buffer
+0| " DEEPSEEK HARNESS"
+  style 1-8 fg=bright-blue bold
+  style 10-16 bold
+1| " Inspect session diagnostics"
+  style 1-27 fg=bright-black
+2| " deepseek-v4-pro  •  main-session"
+  style 1-32 dim
+3| <blank>
+4| "▌ "
+  style 0-0 fg=bright-blue
+5| "▌ You                                                                                       "
+  style 0-0 fg=bright-blue
+  style 2-4 fg=bright-blue bold
+6| "▌ inspect this session                                                                      "
+  style 0-0 fg=bright-blue
+7| "▌ "
+  style 0-0 fg=bright-blue
+8| <blank>
+9| " Assistant                                                                                  "
+  style 1-9 fg=bright-magenta bold
+10| " Session inspected.                                                                         "
+11| <blank>
+12| "╭─ Session status ─────────────────────────────────────────────────╮"
+  style 0-2 dim
+  style 3-16 fg=bright-blue bold
+  style 17-67 dim
+13| "│  Session:    main-session                                        │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 67-67 dim
+14| "│  Title:      Inspect session diagnostics                         │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 67-67 dim
+15| "│  Directory:  /workspace/project                                  │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 67-67 dim
+16| "│  Model:      deepseek/deepseek-v4-pro (reasoning shown)          │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 40-56 dim
+  style 67-67 dim
+17| "│                                                                  │"
+  style 0-0 dim
+  style 67-67 dim
+18| "│  Agent:      idle · 6 events · 1 turn · 1 step · 1 tool call     │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 67-67 dim
+19| "│                                                                  │"
+  style 0-0 dim
+  style 67-67 dim
+20| "│  Tokens:     1,250 input + 340 output                            │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 67-67 dim
+21| "│  KV cache:   [███████████░░░░░] 67% hit (3,000 read + 250 write) │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 15-15 dim
+  style 16-26 fg=bright-blue
+  style 27-32 dim
+  style 67-67 dim
+22| "│  Context:    [█████░░░░░░░░░░░] 33% used (42,000 / 128,000)      │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 15-15 dim
+  style 16-20 fg=bright-blue
+  style 21-32 dim
+  style 67-67 dim
+23| "│                                                                  │"
+  style 0-0 dim
+  style 67-67 dim
+24| "│  Created:    2026-07-22 09:10:11 UTC                             │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 67-67 dim
+25| "│  Active:     2026-07-22 09:10:11 UTC                             │"
+  style 0-0 dim
+  style 3-12 fg=bright-black
+  style 67-67 dim
+26| "╰──────────────────────────────────────────────────────────────────╯"
+  style 0-67 dim
+27| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+28| "                                                                                            "
+  style 1-1 inverse
+29| "────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-91 dim
+30| "deepseek-v4-pro  /workspace/project  ↑1.3k ↓340  cache 67%      33% context  tools:collapsed"
+  style 0-57 dim
+  style 64-91 dim
+31| <blank>

packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.expected.txt

@@ -1,40 +1,30 @@
 terminal 44x18 buffer=normal length=18 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=11 bufferRow=11
+cursor hidden column=1 viewportRow=9 bufferRow=9
 buffer
-0| "╭──────────────────────────────────────────╮"
-  style 0-43 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                         │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 43-43 fg=bright-blue
-2| "│ Snapshot agent ready.                    │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 43-43 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session       │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 43-43 fg=bright-blue
-4| "╰──────────────────────────────────────────╯"
-  style 0-43 fg=bright-blue
-5| <blank>
-6| " Context · compact                          "
+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| " Context · compact                          "
   style 1-17 dim
-7| " Compacted summary: the prior command       "
+5| " Compacted summary: the prior command       "
   style 1-43 fg=bright-black
-8| " completed and its details were retired     "
+6| " completed and its details were retired     "
   style 1-43 fg=bright-black
-9| " from the active surface.                   "
+7| " from the active surface.                   "
   style 1-24 fg=bright-black
+8| "────────────────────────────────────────────"
+  style 0-43 dim
+9| "                                            "
+  style 1-1 inverse
 10| "────────────────────────────────────────────"
   style 0-43 dim
-11| "                                            "
-  style 1-1 inverse
-12| "────────────────────────────────────────────"
+11| "deepseek-v4-flash  /workspace/project  ↑0 ↓0"
   style 0-43 dim
-13| " 0% context  deepseek-v4-flash(reasoning:on)"
-  style 1-43 dim
-14-17| <blank>
+12-17| <blank>

packages/ui/tui/tests/snapshots/surface-after-compaction-wide.expected.txt

@@ -1,37 +1,27 @@
 terminal 104x30 buffer=normal length=30 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=1 viewportRow=9 bufferRow=9
+cursor hidden column=1 viewportRow=7 bufferRow=7
 buffer
-0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮"
-  style 0-103 fg=bright-blue
-1| "│ DEEPSEEK HARNESS                                                                                     │"
-  style 0-0 fg=bright-blue
-  style 2-9 fg=bright-blue bold
-  style 11-17 bold
-  style 103-103 fg=bright-blue
-2| "│ Snapshot agent ready.                                                                                │"
-  style 0-0 fg=bright-blue
-  style 2-22 fg=bright-black
-  style 103-103 fg=bright-blue
-3| "│ deepseek-v4-flash  •  main-session                                                                   │"
-  style 0-0 fg=bright-blue
-  style 2-35 dim
-  style 103-103 fg=bright-blue
-4| "╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯"
-  style 0-103 fg=bright-blue
-5| <blank>
-6| " Context · compact                                                                                      "
+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| " Context · compact                                                                                      "
   style 1-17 dim
-7| " Compacted summary: the prior command completed and its details were retired from the active surface.   "
+5| " Compacted summary: the prior command completed and its details were retired from the active surface.   "
   style 1-100 fg=bright-black
+6| "────────────────────────────────────────────────────────────────────────────────────────────────────────"
+  style 0-103 dim
+7| "                                                                                                        "
+  style 1-1 inverse
 8| "────────────────────────────────────────────────────────────────────────────────────────────────────────"
   style 0-103 dim
-9| "                                                                                                        "
-  style 1-1 inverse
-10| "────────────────────────────────────────────────────────────────────────────────────────────────────────"
-  style 0-103 dim
-11| "/workspace/project  ↑0 ↓0                     0% context  tools:compact  deepseek-v4-flash(reasoning:on)"
-  style 0-24 dim
-  style 46-103 dim
-12-29| <blank>
+9| "deepseek-v4-flash  /workspace/project  ↑0 ↓0                                 0% context  tools:collapsed"
+  style 0-43 dim
+  style 77-103 dim
+10-29| <blank>