Merge remote-tracking branch 'origin/master' into worktree/web-bind-address

# Conflicts:
#	apps/cli/src/bin.ts

packages/bash/bash-local/src/index.ts

@@ -109,10 +109,10 @@ export class LocalBashExecutor extends BashExecutor {
       ...request.stdin !== undefined ? { stdin: request.stdin } : {},
       ...request.env !== undefined ? { env: request.env } : {},
       ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {},
-      // Carry a sandbox-mode override through verbatim: this executor never
+      // Carry a sandbox policy through verbatim: this executor never
       // confines, so the field is inert here (the seam contract) — a
       // sandboxing subclass overrides resolve() to stamp its default instead.
-      sandboxMode: request.sandboxMode,
+      sandboxPolicy: request.sandboxPolicy,
     }
   }
 

packages/bash/bash-sandbox/README.md

@@ -16,7 +16,7 @@ Semantics:
 
 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
 - **Runner failures are sandbox failures, never command failures.** Foreground execution throws `SANDBOX_UNAVAILABLE`; a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Spawn failures also pass through settlement, so confined background handles retain their mode/enforcement facts and release per-process accounting.
-- **Deployment default, per-call policy.** The DEFAULT mode + workspace root are owned by [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) (one home both enforcing families read), not this executor's config; `resolve()` stamps the default onto every spec, and an explicit request-level `sandboxMode` override — set by the tool layer only for a call whose wider mode a human granted through `ctx.approval` ([the sandbox Agent Note § Escalation](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)) — makes THAT call run, classify, and report under its own mode while every neighbor keeps the default (background facts are stamped per task at settle). The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted. The model learns of the sandbox only through result facts — the static bash tool description explains the denial marker; there is no current-mode statement in the system prompt.
+- **Deployment fallback, per-call policy.** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) resolves a complete `SandboxExecutionPolicy` for every tool call: the calling session supplies its mode override and immutable cwd root, while deployment config supplies the fallbacks for agentless calls. An approved escalation changes only that policy's mode; its session root stays attached. `resolve()` carries the policy onto the spec, so overlapping commands from different projects run, classify, and report under their own roots and modes. The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted. The model learns of the sandbox only through result facts — the static bash tool description explains the denial marker; there is no current-mode statement in the system prompt.
 - **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
 - Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
 
@@ -29,12 +29,12 @@ Deny-only at the seam: a denial is a reported fact, and this executor never nego
   name: '@deepseek-ai/dsh-sandbox-policy'
   config:
     mode: read-only
-    workspaceRoot: !!js process.cwd()
+    workspaceRoot: !!js process.cwd() # fallback for calls without a session cwd
 - id: bash
   name: '@deepseek-ai/dsh-bash-sandbox'
 ```
 
-The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, and `tests/seatbelt.e2e.ts` (the real provider + real runner driven through `ctx.bash`, world-verified, each self-skipping where its runner is absent); see [the acp-agent example's default composition](../../../examples/acp-agent/) for the runnable demo.
+The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, and `tests/seatbelt.e2e.ts` (the real provider + real runner driven through `ctx.bash`, world-verified, each self-skipping where its runner is absent). The agent-spine e2e additionally drives two concurrent sessions in one Cordis context and proves each real bash tool call can write only its own project. See [the acp-agent example's default composition](../../../examples/acp-agent/) for the runnable demo.
 
 ## Model Experience
 

packages/bash/bash-sandbox/src/index.ts

@@ -3,14 +3,15 @@
  * `ctx.sandbox`, inherits local process mechanics, and reports the selected
  * mode, enforcement, and denial facts. Runner failure means the command never
  * ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while settled background
- * processes carry `runnerFailed`. The tool owns approval and passes per-call modes.
+ * processes carry `runnerFailed`. The tool owns approval and passes a complete
+ * per-call policy.
  * @module @deepseek-ai/dsh-bash-sandbox
  */
 
 import { Context } from 'cordis'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
 import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
-import type { ConfinedSandboxMode, SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { ConfinedSandboxMode, SandboxEnforcement, SandboxExecutionPolicy, SandboxMode, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import type {} from '@deepseek-ai/dsh-sandbox-policy'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
@@ -18,21 +19,19 @@ import { classifyDenial, classifyRunnerFailure, matchesSignature, shellQuote } f
 
 /**
  * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
- * the default mode and the `workspace-write` boundary root — is NOT here: it
- * lives on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), the one
- * home both enforcing families read, so bash and fs can never confine to
- * different roots. The runner choice is likewise the `ctx.sandbox` provider's
- * config, not this executor's.
+ * the default mode and fallback `workspace-write` root — is NOT here: it lives
+ * on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), which resolves
+ * each calling session's mode and cwd for both enforcing families. The runner
+ * choice is likewise the `ctx.sandbox` provider's config, not this executor's.
  */
 export type Config = LocalConfig
 
 /**
  * Registers as `ctx.bash` in place of the local executor and requires a
  * `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer is
- * unchanged. The policy default (mode + workspace root) is the fallback,
- * while a session override or approved one-shot escalation may select each
- * call's mode. The prompt does not state the standing mode; `result.sandbox`
- * reports the mode and enforcement actually used.
+ * unchanged. Tool calls pass the calling session's resolved policy; direct
+ * calls fall back to deployment policy. The prompt does not state the standing
+ * mode; `result.sandbox` reports the mode and enforcement actually used.
  */
 export class SandboxBashExecutor extends LocalBashExecutor {
   static inject = ['sandbox', 'sandboxPolicy']
@@ -42,7 +41,6 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   // verbatim (the config catalog walks the inherited static).
 
   private readonly mode: SandboxMode
-  private readonly workspaceRoot: string
   /**
    * Per-process confinement facts retained until settlement. Providers may
    * vary enforcement and diagnostic dialect between overlapping calls, so a
@@ -58,11 +56,9 @@ export class SandboxBashExecutor extends LocalBashExecutor {
 
   constructor(ctx: Context, config: Config) {
     super(ctx, config)
-    // The sandbox default (mode + workspaceRoot) is the one shared policy home
-    // both enforcing families read; injecting sandboxPolicy guarantees it is
-    // constructed first. workspaceRoot arrives already resolved absolute.
+    // The default mode is the capability fact used for schema advertisement;
+    // actual tool executions carry their resolved per-call policy.
     this.mode = ctx.sandboxPolicy.defaultMode
-    this.workspaceRoot = ctx.sandboxPolicy.workspaceRoot
   }
 
   /** The configured default mode — the capability fact the tool layer reads. */
@@ -71,24 +67,22 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   }
 
   /**
-   * Stamp the effective mode onto the spec — the request's explicit override
-   * (an approved escalation), else this executor's configured default — so
-   * defaulting stays an explicit resolve step and `run()`/`start()` read the
-   * spec, never the config.
+   * Stamp a complete per-call policy onto the spec. Tool calls supply the
+   * calling session's resolved mode and root; lower-level callers fall back to
+   * the deployment policy.
    */
   override resolve(request: BashExecRequest): BashExecSpec {
-    return { ...super.resolve(request), sandboxMode: request.sandboxMode ?? this.mode }
+    return { ...super.resolve(request), sandboxPolicy: request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve() }
   }
 
   override async run(spec: BashExecSpec): Promise<BashRunResult> {
-    // resolve() always stamps the mode; the cast records that invariant
-    // (mirrors the constructor's config casts).
-    const mode = spec.sandboxMode as SandboxMode
+    const policy = spec.sandboxPolicy as SandboxExecutionPolicy
+    const { mode } = policy
     if (mode === 'danger-full-access') {
       const result = await super.run(spec)
       return { ...result, sandbox: { mode, denied: false } }
     }
-    const confined = this.confine(spec.command, mode)
+    const confined = this.confine(spec.command, { ...policy, mode })
     const result = await super.run({ ...spec, command: confined.command })
     // Runner failure outranks denial because the command did not run. Throw the
     // same fail-closed error as confine-time discovery with the first stderr line.
@@ -99,11 +93,11 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   }
 
   override start(spec: BashExecSpec): BashProcess {
-    // Same stamped-by-resolve invariant as run().
-    const mode = spec.sandboxMode as SandboxMode
+    const policy = spec.sandboxPolicy as SandboxExecutionPolicy
+    const { mode } = policy
     if (mode === 'danger-full-access') return super.start(spec)
     // Install facts synchronously; promise settlement cannot run before start() returns.
-    const confined = this.confine(spec.command, mode)
+    const confined = this.confine(spec.command, { ...policy, mode })
     const proc = super.start({ ...spec, command: confined.command })
     const { enforcement, denialSignatures, runnerFailureSignatures } = confined
     this.processFacts.set(proc, { mode, enforcement, denialSignatures, runnerFailureSignatures })
@@ -138,13 +132,13 @@ export class SandboxBashExecutor extends LocalBashExecutor {
    * `exec`s into the runner, so no extra shell lingers). Provider errors
    * (fail-closed `SANDBOX_UNAVAILABLE`) propagate to the caller unchanged.
    */
-  private confine(command: string, mode: ConfinedSandboxMode): {
+  private confine(command: string, policy: SandboxPolicy): {
     command: string
     enforcement: SandboxEnforcement
     denialSignatures: readonly string[]
     runnerFailureSignatures: readonly string[]
   } {
-    const confined = this.ctx.sandbox.confine(['bash', '-c', command], { mode, workspaceRoot: this.workspaceRoot })
+    const confined = this.ctx.sandbox.confine(['bash', '-c', command], policy)
     return {
       command: `exec ${confined.argv.map(shellQuote).join(' ')}`,
       enforcement: confined.enforcement,

packages/bash/bash-sandbox/tests/bwrap.e2e.ts

@@ -89,7 +89,7 @@ describe.skipIf(!bwrapUsable)('bash-sandbox: real bwrap confinement through ctx.
     expect(strict.exitCode).not.toBe(0)
     expect(strict.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' })
     expect(existsSync(join(workdir, 'escalated.txt'))).toBe(false)
-    const retried = await bash.run(bash.resolve({ command, sandboxMode: 'workspace-write' }))
+    const retried = await bash.run(bash.resolve({ command, sandboxPolicy: { mode: 'workspace-write', workspaceRoot: workdir } }))
     expect(retried.exitCode).toBe(0)
     expect(retried.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' })
     expect(readFileSync(join(workdir, 'escalated.txt'), 'utf8')).toBe('escalated')

packages/bash/bash-sandbox/tests/landlock.e2e.ts

@@ -94,7 +94,7 @@ describe.skipIf(!landlockUsable)('bash-sandbox: real Landlock confinement throug
     expect(strict.exitCode).not.toBe(0)
     expect(strict.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: enforcement })
     expect(existsSync(join(workdir, 'escalated.txt'))).toBe(false)
-    const retried = await bash.run(bash.resolve({ command, sandboxMode: 'workspace-write' }))
+    const retried = await bash.run(bash.resolve({ command, sandboxPolicy: { mode: 'workspace-write', workspaceRoot: workdir } }))
     expect(retried.exitCode).toBe(0)
     expect(retried.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: enforcement })
     expect(readFileSync(join(workdir, 'escalated.txt'), 'utf8')).toBe('escalated')

packages/bash/bash-sandbox/tests/sandbox.spec.ts

@@ -12,7 +12,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
 import { SANDBOX_UNAVAILABLE, SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
-import type { ConfinedArgv, SandboxMode, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import type { ConfinedArgv, SandboxExecutionPolicy, SandboxMode, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 import { classifyDenial, classifyRunnerFailure, shellQuote } from '../src/helpers.ts'
@@ -72,6 +72,10 @@ function runResult(exitCode: number | null, stderr: string): BashRunResult {
   return { exitCode, signal: null, timedOut: false, aborted: false, timeoutMs: 1000, stdout: output(''), stderr: output(stderr) }
 }
 
+function executionPolicy(mode: SandboxMode, workspaceRoot = resolve(process.cwd())): SandboxExecutionPolicy {
+  return { mode, workspaceRoot }
+}
+
 describe('the provider hand-off', () => {
   it('hands the provider the exact bash argv and the per-call policy, and runs the returned argv', async () => {
     const { bash, calls } = await setup()
@@ -147,30 +151,31 @@ describe('danger-full-access', () => {
   })
 })
 
-describe('per-call sandboxMode override (the escalation mechanism)', () => {
+describe('per-call sandbox policy (the session and escalation carrier)', () => {
   it('exposes the configured default as the capability fact, and resolve() stamps it', async () => {
     const { bash } = await setup()
     expect(bash.sandboxMode).toBe('read-only')
-    expect(bash.resolve({ command: 'true' }).sandboxMode).toBe('read-only')
+    expect(bash.resolve({ command: 'true' }).sandboxPolicy).toEqual(executionPolicy('read-only'))
   })
 
-  it('an explicit override outranks the default at resolve(), and the wrap policy follows it', async () => {
+  it('an explicit policy outranks the default at resolve(), and the wrap follows its mode and root', async () => {
     const { bash, calls } = await setup()
-    expect(bash.resolve({ command: 'true', sandboxMode: 'workspace-write' }).sandboxMode).toBe('workspace-write')
-    await bash.run(bash.resolve({ command: 'true', sandboxMode: 'workspace-write' }))
+    const explicit = executionPolicy('workspace-write', '/session/project')
+    expect(bash.resolve({ command: 'true', sandboxPolicy: explicit }).sandboxPolicy).toEqual(explicit)
+    await bash.run(bash.resolve({ command: 'true', sandboxPolicy: explicit }))
     await bash.run(bash.resolve({ command: 'true' }))
-    expect(calls.map(call => call.policy.mode)).toEqual(['workspace-write', 'read-only'])
+    expect(calls.map(call => call.policy)).toEqual([explicit, executionPolicy('read-only')])
   })
 
   it('an escalated run reports the mode it ACTUALLY ran under', async () => {
     const { bash } = await setup()
-    const result = await bash.run(bash.resolve({ command: 'true', sandboxMode: 'workspace-write' }))
+    const result = await bash.run(bash.resolve({ command: 'true', sandboxPolicy: executionPolicy('workspace-write') }))
     expect(result.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' })
   })
 
   it('escalating to danger-full-access bypasses the provider entirely — the grant, not a probe, is the authority there', async () => {
     const { bash, calls } = await setup()
-    const result = await bash.run(bash.resolve({ command: 'echo free', sandboxMode: 'danger-full-access' }))
+    const result = await bash.run(bash.resolve({ command: 'echo free', sandboxPolicy: executionPolicy('danger-full-access') }))
     expect(result.stdout.text).toBe('free\n')
     expect(result.sandbox).toEqual({ mode: 'danger-full-access', denied: false })
     expect(calls).toHaveLength(0)
@@ -181,7 +186,7 @@ describe('per-call sandboxMode override (the escalation mechanism)', () => {
     // once — anything keyed off the configured default would misreport the
     // escalated one at its settle stamp.
     const { bash } = await setup()
-    const escalated = bash.start(bash.resolve({ command: 'sleep 0.3; echo "x: Permission denied" >&2; exit 1', sandboxMode: 'workspace-write' }))
+    const escalated = bash.start(bash.resolve({ command: 'sleep 0.3; echo "x: Permission denied" >&2; exit 1', sandboxPolicy: executionPolicy('workspace-write') }))
     const plain = bash.start(bash.resolve({ command: 'true' }))
     await plain.done
     await escalated.done
@@ -191,7 +196,7 @@ describe('per-call sandboxMode override (the escalation mechanism)', () => {
 
   it('an escalated danger-full-access background task carries no facts (nothing confined it)', async () => {
     const { bash, calls } = await setup()
-    const task = bash.start(bash.resolve({ command: 'echo bg-free', sandboxMode: 'danger-full-access' }))
+    const task = bash.start(bash.resolve({ command: 'echo bg-free', sandboxPolicy: executionPolicy('danger-full-access') }))
     await task.done
     expect(task.sandbox).toBeUndefined()
     expect(task.readOutput().delta).toContain('bg-free')

packages/bash/bash-sandbox/tests/seatbelt.e2e.ts

@@ -91,7 +91,7 @@ describe.skipIf(!seatbeltUsable)('bash-sandbox: real Seatbelt confinement throug
     expect(strict.exitCode).not.toBe(0)
     expect(strict.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' })
     expect(existsSync(join(workdir, 'escalated.txt'))).toBe(false)
-    const retried = await bash.run(bash.resolve({ command, sandboxMode: 'workspace-write' }))
+    const retried = await bash.run(bash.resolve({ command, sandboxPolicy: { mode: 'workspace-write', workspaceRoot: workdir } }))
     expect(retried.exitCode).toBe(0)
     expect(retried.sandbox).toEqual({ mode: 'workspace-write', denied: false, enforcement: 'full' })
     expect(readFileSync(join(workdir, 'escalated.txt'), 'utf8')).toBe('escalated')

packages/bash/bash/README.md

@@ -27,7 +27,7 @@ Implementations subclass `BashExecutor` and implement the abstract methods. Disp
 
 ## Vocabulary
 
-`BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, dshEnv?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, dshEnv?, sandboxMode) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxMode` is optional on the request and required-but-nullable on the resolved spec: it carries an approved one-shot escalation or the session's standing override; a sandboxing executor stamps its configured default when absent, while a non-sandboxing executor carries the field and confines nothing.
+`BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, dshEnv?, sandboxPolicy?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, dshEnv?, sandboxPolicy) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxPolicy` is optional on the request and required-but-nullable on the resolved spec: it carries the complete per-call mode and workspace root. The sandbox tool path resolves it from the calling session through `ctx.sandboxPolicy`; a direct sandbox-executor caller falls back to deployment policy, while a non-sandboxing executor carries the field and confines nothing.
 
 The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md).
 

packages/bash/bash/src/types.ts

@@ -4,7 +4,7 @@
  * @module dsh-bash/types
  */
 
-import type { SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 
 /** Namespace prefix reserved for DeepSeek Harness-managed child environment facts. */
 export const DSH_ENV_PREFIX = 'DSH_' as const
@@ -75,8 +75,8 @@ export interface BashExecRequest {
    * reject non-`DSH_*` names supplied through this managed channel.
    */
   dshEnv?: DshEnvironment | undefined
-  /** Explicit per-call sandbox mode override. */
-  sandboxMode?: SandboxMode | undefined
+  /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
+  sandboxPolicy?: SandboxExecutionPolicy | undefined
 }
 
 /**
@@ -106,8 +106,8 @@ export interface BashExecSpec {
   env?: Record<string, string> | undefined
   /** Managed `DSH_*` snapshot; implementations reject ordinary names. */
   dshEnv?: DshEnvironment | undefined
-  /** Resolved sandbox mode; ignored by executors that do not confine. */
-  sandboxMode: SandboxMode | undefined
+  /** Resolved sandbox policy; ignored by executors that do not confine. */
+  sandboxPolicy: SandboxExecutionPolicy | undefined
 }
 
 /** One captured stream: the (possibly truncated) text plus recovery info. */

packages/bash/bash/tests/service.spec.ts

@@ -17,7 +17,7 @@ class StubExecutor extends BashExecutor {
       timeoutMs: request.timeoutMs ?? 1000,
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       ...request.signal ? { signal: request.signal } : {},
-      sandboxMode: request.sandboxMode,
+      sandboxPolicy: request.sandboxPolicy,
     }
   }
 
@@ -55,7 +55,7 @@ describe('BashExecutor service seam', () => {
     const ctx = new Context()
     await ctx.plugin(StubExecutor)
     const spec = ctx.bash.resolve({ command: 'echo hi' })
-    expect(spec).toEqual({ command: 'echo hi', workdir: '/stub', timeoutMs: 1000, stdoutMaxBytes: 64_000, sandboxMode: undefined })
+    expect(spec).toEqual({ command: 'echo hi', workdir: '/stub', timeoutMs: 1000, stdoutMaxBytes: 64_000, sandboxPolicy: undefined })
 
     const result = await ctx.bash.run(spec)
     expect(result.exitCode).toBe(0)

packages/bash/tool-bash/README.md

@@ -17,12 +17,12 @@ The plugin also contributes the `tool:bash` prompt section (order 105): check th
 | `command` | string (required) | Run via `bash -c`. No state persists between calls — use `workdir`, not `cd`. |
 | `description` | string (required) | One-line, active-voice summary of the command (5-10 words), for UI/log display only — no effect on execution. |
 | `timeoutMs` | number | Timeout override in milliseconds. The executor applies its configured default and cap. |
-| `workdir` | string | Working directory for this call. Defaults to the calling agent's session cwd (`session.header.cwd`) so each session runs in its own workspace; a relative `workdir` is resolved against that session cwd. |
+| `workdir` | string | Working directory for this call. Defaults to the filesystem identity of the calling agent's session cwd (`session.header.cwd`) so each session runs in its own workspace; a relative `workdir` is resolved against that same identity. |
 | `run_in_background` | boolean | Return a task id immediately; no timeout applies. |
 | `sandbox_permissions` | string enum | ADVERTISED ONLY when the mounted executor sandboxes (`ctx.bash.sandboxMode` reports a confining default): the wider mode a denied command needs, from the closed target vocabulary `workspace-write`/`danger-full-access` (never cut down to the executor's default — the effective mode is per-session; strict widening is checked at execution against it, and a non-widening request fails without prompting anyone). |
 | `justification` | string | Required together with `sandbox_permissions` (each without the other is a validation error): one sentence for the user explaining why this exact command needs the wider access. |
 
-`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the executor seam (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer (from the calling agent's `session.header.cwd`) BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`.
+`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the executor seam (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`. When sandbox policy is present, the tool reuses its already-canonical `workspaceRoot` as the workdir base so confinement and process launch cannot resolve the same session spelling differently.
 
 ### Managed shell environment
 

packages/bash/tool-bash/src/index.ts

@@ -18,9 +18,9 @@ import type {} from '@deepseek-ai/dsh-session-persistence'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tasks'
 import type {} from '@deepseek-ai/dsh-user-approval'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
-import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
-import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-bash'
 import type { DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-bash'
 import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-paths'
@@ -299,11 +299,18 @@ function presentBashResult(args: unknown, result: ToolResult): ToolResultView |
 }
 
 /**
- * Resolve an explicit workdir first, making a relative one session-cwd-relative;
- * otherwise use the session cwd and leave executor defaulting as the fallback.
+ * Resolve an explicit workdir first, making a relative one session-workspace-relative;
+ * otherwise use the filesystem identity of the session cwd and leave executor
+ * defaulting as the fallback. A resolved sandbox-policy root wins so workdir
+ * and confinement use the exact same per-call identity.
  */
-function resolveWorkdir(modelWorkdir: string | undefined, exec: { agent?: Agent }): string | undefined {
-  const sessionCwd = exec.agent?.session.header.cwd
+function resolveWorkdir(
+  modelWorkdir: string | undefined,
+  exec: { agent?: Agent },
+  policyWorkspaceRoot?: string,
+): string | undefined {
+  const headerCwd = exec.agent?.session.header.cwd
+  const sessionCwd = policyWorkspaceRoot ?? (headerCwd === undefined ? undefined : canonicalPath(headerCwd))
   if (modelWorkdir === undefined) return sessionCwd
   if (sessionCwd !== undefined && !isAbsolute(modelWorkdir)) {
     return resolvePath(sessionCwd, modelWorkdir)
@@ -330,9 +337,14 @@ export function apply(ctx: Context, config: Config = {}): void {
   const backgroundEnabled = config.enableRunInBackground ?? true
   const defaultMode = ctx.bash.sandboxMode
   const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS
+  const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy')
+  if (defaultMode !== undefined && sandboxPolicy === undefined) {
+    throw new Error('tool-bash: the mounted bash executor confines but ctx.sandboxPolicy is missing')
+  }
 
-  const sessionOverride = (exec: ToolExecution): SandboxMode | undefined =>
-    defaultMode === undefined || exec.agent === undefined ? undefined : effectiveSandboxMode(exec.agent.session.events)
+  /** Resolve the complete standing policy for this call when a confining executor is mounted. */
+  const resolveSandboxPolicy = (exec: ToolExecution): SandboxExecutionPolicy | undefined =>
+    sandboxPolicy?.resolve(exec.agent === undefined ? {} : { session: exec.agent.session })
 
   /**
    * Resolve a sandbox-escalation request through `ctx.approval` BEFORE
@@ -342,14 +354,19 @@ export function apply(ctx: Context, config: Config = {}): void {
    * guard (the fields are unadvertised without a sandboxing executor, yet
    * schema validation checks advertised keys only, so an unadvertised
    * `sandbox_permissions` still reaches execute) and the approval ingredients
-   * — the seam is consumed opportunistically (`ctx.get`) so a deployment
-   * without it degrades per call.
+   * The shared policy resolver is required whenever the executor advertises
+   * confinement, so a split composition fails at tool-plugin load.
    */
-  const approveBashEscalation = (mode: string, justification: string, exec: ToolExecution): Promise<SandboxMode> => {
+  const approveBashEscalation = (
+    mode: string,
+    justification: string,
+    exec: ToolExecution,
+    standingPolicy: SandboxExecutionPolicy | undefined,
+  ): Promise<SandboxMode> => {
     if (escalationModes.length === 0) {
       throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)')
     }
-    const effectiveMode = (sessionOverride(exec) ?? defaultMode) as SandboxMode
+    const effectiveMode = (standingPolicy as SandboxExecutionPolicy).mode
     return approveEscalation(
       { requestedMode: mode, justification, effectiveMode, subject: 'command' },
       {
@@ -401,17 +418,21 @@ export function apply(ctx: Context, config: Config = {}): void {
     async execute(args: BashToolArgs, exec) {
       validateBashArgs(args)
       // Description is display metadata; workdir defaults to the caller's session.
-      const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined
-        ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec)
-        : sessionOverride(exec)
-      const workdir = resolveWorkdir(args.workdir, exec)
+      const standingPolicy = resolveSandboxPolicy(exec)
+      const approvedMode = args.sandbox_permissions !== undefined && args.justification !== undefined
+        ? await approveBashEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy)
+        : undefined
+      const policy = approvedMode === undefined
+        ? standingPolicy
+        : { ...(standingPolicy as SandboxExecutionPolicy), mode: approvedMode }
+      const workdir = resolveWorkdir(args.workdir, exec, standingPolicy?.workspaceRoot)
       const dshEnv = bashEnv.collect(exec)
       const request = {
         command: args.command,
         ...workdir !== undefined ? { workdir } : {},
         ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
         dshEnv,
-        ...sandboxMode !== undefined ? { sandboxMode } : {},
+        ...policy !== undefined ? { sandboxPolicy: policy } : {},
       }
       if (args.run_in_background === true) {
         // Undeclared keys are allowed, so schema omission also needs enforcement.

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

@@ -17,6 +17,7 @@ import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
 import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import { processOutcome } from '../src/background.ts'
 import { renderProcessRead, renderResult } from '../src/render.ts'
@@ -107,12 +108,12 @@ class RecordingSandboxExecutor extends BashExecutor {
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       timeoutMs: request.timeoutMs ?? 1000,
       ...request.signal ? { signal: request.signal } : {},
-      sandboxMode: request.sandboxMode ?? 'read-only',
+      sandboxPolicy: request.sandboxPolicy ?? { mode: 'read-only', workspaceRoot: process.cwd() },
     }
   }
 
   run(spec: BashExecSpec): Promise<BashRunResult> {
-    this.modes.push(spec.sandboxMode)
+    this.modes.push(spec.sandboxPolicy?.mode)
     return Promise.resolve({
       exitCode: 0,
       signal: null,
@@ -121,18 +122,18 @@ class RecordingSandboxExecutor extends BashExecutor {
       timeoutMs: spec.timeoutMs,
       stdout: { text: 'ok', truncated: false },
       stderr: { text: '', truncated: false },
-      sandbox: { mode: spec.sandboxMode ?? 'read-only', denied: false },
+      sandbox: { mode: spec.sandboxPolicy?.mode ?? 'read-only', denied: false },
     })
   }
 
   start(spec: BashExecSpec): BashProcess {
-    this.modes.push(spec.sandboxMode)
+    this.modes.push(spec.sandboxPolicy?.mode)
     return {
       status: 'completed',
       exitCode: 0,
       signal: null,
       done: Promise.resolve(),
-      sandbox: { mode: spec.sandboxMode ?? 'read-only', denied: false },
+      sandbox: { mode: spec.sandboxPolicy?.mode ?? 'read-only', denied: false },
       readOutput: () => ({ delta: '', lossy: false }),
       kill: () => false,
     }
@@ -149,7 +150,7 @@ class CountingStartExecutor extends BashExecutor {
       workdir: request.workdir ?? '/x',
       timeoutMs: request.timeoutMs ?? 0,
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
-      sandboxMode: request.sandboxMode,
+      sandboxPolicy: request.sandboxPolicy,
     }
   }
 
@@ -175,6 +176,7 @@ async function setupSandboxed(withApproval = false) {
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(TaskService)
   await ctx.plugin(ToolTasks)
+  await ctx.plugin(SandboxPolicyService, {})
   await ctx.plugin(RecordingSandboxExecutor)
   if (withApproval) await ctx.plugin(ApprovalService)
   await ctx.plugin(ToolBash)
@@ -532,6 +534,14 @@ describe('sandbox escalation through the generic task producer', () => {
     justification: 'the command needs workspace writes',
   }
 
+  it('fails load when a confining executor has no shared sandbox-policy resolver', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(RecordingSandboxExecutor)
+    await expect(ctx.plugin(ToolBash)).rejects.toThrow('tool-bash: the mounted bash executor confines but ctx.sandboxPolicy is missing')
+  })
+
   it('advertises the sandbox fields and validates their pairing', async () => {
     const { ctx } = await setupSandboxed()
     const schema = ctx.tools.schemas().find(item => item.name === 'bash')!
@@ -993,7 +1003,7 @@ describe('the model-facing bash tool builds its request from named args only (no
         ...request.stdin !== undefined ? { stdin: request.stdin } : {},
         ...request.env !== undefined ? { env: request.env } : {},
         ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {},
-        sandboxMode: request.sandboxMode,
+        sandboxPolicy: request.sandboxPolicy,
       }
     }
     run(): Promise<BashRunResult> {

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/src/api-catalog.ts

@@ -263,12 +263,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * List direct children of a directory in stable name order. Returns resolved\n * child targets plus cheap metadata only; never reads file contents.\n * @param target - the resolved directory target.\n * @param signal - aborts the listing.\n * @returns one entry per direct child, in stable name order.\n */',
       },
       {
-        signature: 'abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxMode?: SandboxMode, ): Promise<FsWriteOutcome>',
-        jsDoc: '/**\n * Atomically create or replace UTF-8 text. `expected` guards intent and\n * staleness; omission allows unconditional overwrite.\n * @param target - the resolved target to write.\n * @param content - the full new file content.\n * @param expected - the write intent guarding the write; omit for unconditional.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxMode - the per-call sandbox mode this write runs under; a\n *   sandboxing backend fences the write by it, the bare backend ignores it.\n *   Omit to leave the backend its own default.\n * @returns the outcome, including the version the write produced.\n */',
+        signature: 'abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>',
+        jsDoc: '/**\n * Atomically create or replace UTF-8 text. `expected` guards intent and\n * staleness; omission allows unconditional overwrite.\n * @param target - the resolved target to write.\n * @param content - the full new file content.\n * @param expected - the write intent guarding the write; omit for unconditional.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this write\n *   runs under; a sandboxing backend fences the write by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the write produced.\n */',
       },
       {
-        signature: 'abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxMode?: SandboxMode, ): Promise<FsEditOutcome>',
-        jsDoc: '/**\n * Atomically edit literal text. When supplied, the version guard is checked\n * before matching so stale content reports `FS_STALE_VERSION`; omission edits\n * the current content without a freshness precondition.\n * @param target - the resolved target to edit.\n * @param edit - the literal search/replace request.\n * @param expected - the version guard; omit for an unconditional edit.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxMode - the per-call sandbox mode this edit runs under; a\n *   sandboxing backend fences the edit by it, the bare backend ignores it.\n *   Omit to leave the backend its own default.\n * @returns the outcome, including the version the edit produced.\n */',
+        signature: 'abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>',
+        jsDoc: '/**\n * Atomically edit literal text. When supplied, the version guard is checked\n * before matching so stale content reports `FS_STALE_VERSION`; omission edits\n * the current content without a freshness precondition.\n * @param target - the resolved target to edit.\n * @param edit - the literal search/replace request.\n * @param expected - the version guard; omit for an unconditional edit.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this edit runs\n *   under; a sandboxing backend fences the edit by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the edit produced.\n */',
       },
     ],
   },
@@ -399,7 +399,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   {
     key: 'sandboxPolicy',
     summary: 'The sandbox-policy service (`ctx.sandboxPolicy`).',
-    methods: [],
+    methods: [
+      {
+        signature: 'resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy',
+        jsDoc: '/**\n * Resolve the complete policy for one capability call. An approved explicit\n * mode outranks the session\'s last `sandbox/mode` event, which outranks the\n * deployment default. A session cwd is its workspace-write boundary; the\n * configured root is the fallback for agentless calls and sessions without a\n * cwd.\n * @param request - optional session and approved mode override.\n * @returns the fully resolved per-call mode and absolute workspace root.\n */',
+      },
+    ],
   },
   {
     key: 'sessionPersistence',
@@ -1148,11 +1153,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'BashExecRequest',
-    declaration: 'export interface BashExecRequest {\n    command: string;\n    workdir?: string | undefined;\n    timeoutMs?: number | undefined;\n    stdoutMaxBytes?: number | undefined;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    dshEnv?: DshEnvironment | undefined;\n    sandboxMode?: SandboxMode | undefined;\n}',
+    declaration: 'export interface BashExecRequest {\n    command: string;\n    workdir?: string | undefined;\n    timeoutMs?: number | undefined;\n    stdoutMaxBytes?: number | undefined;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    dshEnv?: DshEnvironment | undefined;\n    sandboxPolicy?: SandboxExecutionPolicy | undefined;\n}',
   },
   {
     name: 'BashExecSpec',
-    declaration: 'export interface BashExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    stdoutMaxBytes: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    dshEnv?: DshEnvironment | undefined;\n    sandboxMode: SandboxMode | undefined;\n}',
+    declaration: 'export interface BashExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    stdoutMaxBytes: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    dshEnv?: DshEnvironment | undefined;\n    sandboxPolicy: SandboxExecutionPolicy | undefined;\n}',
   },
   {
     name: 'BashProcess',
@@ -1486,13 +1491,21 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SandboxEnforcement',
     declaration: 'export type SandboxEnforcement = \'full\' | \'partial\';',
   },
+  {
+    name: 'SandboxExecutionPolicy',
+    declaration: 'export interface SandboxExecutionPolicy {\n    mode: SandboxMode;\n    workspaceRoot: string;\n}',
+  },
   {
     name: 'SandboxMode',
     declaration: 'export type SandboxMode = \'read-only\' | \'workspace-write\' | \'danger-full-access\';',
   },
   {
     name: 'SandboxPolicy',
-    declaration: 'export interface SandboxPolicy {\n    mode: ConfinedSandboxMode;\n    workspaceRoot: string;\n}',
+    declaration: 'export interface SandboxPolicy extends SandboxExecutionPolicy {\n    mode: ConfinedSandboxMode;\n}',
+  },
+  {
+    name: 'SandboxPolicyRequest',
+    declaration: 'export interface SandboxPolicyRequest {\n    session?: Session;\n    mode?: SandboxMode;\n}',
   },
   {
     name: 'SaveTextSpill',

packages/examples/agent-spine-demo/package.json

@@ -55,13 +55,18 @@
     "@cordisjs/plugin-timer": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
+    "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-goal-session": "workspace:^",
-    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
@@ -70,11 +75,13 @@
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
     "@deepseek-ai/dsh-tool-goal": "workspace:^",
     "@deepseek-ai/dsh-tool-skill": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-workspace-context": "workspace:^",
+    "node-addon-landlock-run": "0.0.0-test.0",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {

packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts

@@ -0,0 +1,243 @@
+import { spawnSync } from 'node:child_process'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
+import SandboxedFileSystem from '@deepseek-ai/dsh-fs-sandbox'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import type { ToolResult } from '@deepseek-ai/dsh-tools'
+import { launcherPath } from 'node-addon-landlock-run'
+import * as agentSpine from '../src/index.ts'
+
+const bwrapUsable = spawnSync('bwrap', [
+  '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent', '--', 'true',
+], { timeout: 5_000, stdio: 'ignore' }).status === 0
+const landlockUsable = spawnSync(launcherPath(), ['--probe'], { timeout: 5_000, stdio: 'ignore' }).status === 0
+const seatbeltUsable = process.platform === 'darwin'
+  && spawnSync('sandbox-exec', [...seatbeltProfileArgs({ mode: 'workspace-write', workspaceRoot: homedir() }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' }).status === 0
+const processSandboxUsable = bwrapUsable || landlockUsable || seatbeltUsable
+
+let ctx: Context | undefined
+let projectA: string
+let projectB: string
+const tempDirs: string[] = []
+
+async function projectDir(label: string): Promise<string> {
+  const dir = await mkdtemp(join(homedir(), `dsh-${label}-`))
+  tempDirs.push(dir)
+  return dir
+}
+
+async function expectMissing(path: string): Promise<void> {
+  await expect(readFile(path, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
+}
+
+function resultText(result: ToolResult): string {
+  return result.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n')
+}
+
+beforeEach(async () => {
+  projectA = await projectDir('project-a')
+  projectB = await projectDir('project-b')
+  const fallbackRoot = await projectDir('fallback')
+
+  ctx = new Context()
+  await ctx.plugin(LocalSandboxProvider, {})
+  await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: fallbackRoot })
+  await ctx.plugin(SandboxBashExecutor, { cwd: fallbackRoot, timeoutMs: 30_000 })
+  await ctx.plugin(SandboxedFileSystem, { cwd: fallbackRoot })
+  await ctx.plugin(agentSpine, {
+    workspaceContext: false,
+    skills: { enabled: false },
+    toolBash: { enableRunInBackground: false },
+    toolTasks: false,
+  })
+  await new Promise(resolve => setTimeout(resolve, 50))
+  await ctx.plugin(FsPolicy)
+  await ctx.plugin(ToolFs)
+})
+
+afterEach(async () => {
+  await ctx?.fiber.dispose()
+  ctx = undefined
+  await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})
+
+async function agents() {
+  const active = ctx as Context
+  const [a, b] = await Promise.all([
+    active.agents.create({ sessionId: SessionId('project-a-session'), meta: { cwd: projectA } }),
+    active.agents.create({ sessionId: SessionId('project-b-session'), meta: { cwd: projectB } }),
+  ])
+  return { active, agentA: a.agent, agentB: b.agent }
+}
+
+describe('one-context multi-project sandbox', () => {
+  it.skipIf(!processSandboxUsable)('confines concurrent bash calls to each calling session workspace', async () => {
+    const { active, agentA, agentB } = await agents()
+    const [aOwn, bOwn, aCross, bCross] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('bash-a-own'), name: 'bash', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { command: 'printf a > a-owned.txt', description: 'Write project A marker' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-b-own'), name: 'bash', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { command: 'printf b > b-owned.txt', description: 'Write project B marker' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-a-cross'), name: 'bash', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { command: `printf cross > ../${basename(projectB)}/from-a.txt`, description: 'Attempt project B write' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-b-cross'), name: 'bash', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { command: `printf cross > ../${basename(projectA)}/from-b.txt`, description: 'Attempt project A write' },
+      }),
+    ])
+
+    expect(aOwn.isError).toBe(false)
+    expect(bOwn.isError).toBe(false)
+    expect(aCross.isError).toBe(false)
+    expect(bCross.isError).toBe(false)
+    expect(resultText(aCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(resultText(bCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(await readFile(join(projectA, 'a-owned.txt'), 'utf8')).toBe('a')
+    expect(await readFile(join(projectB, 'b-owned.txt'), 'utf8')).toBe('b')
+    await expectMissing(join(projectB, 'from-a.txt'))
+    await expectMissing(join(projectA, 'from-b.txt'))
+  })
+
+  it('confines concurrent filesystem writes to each calling session workspace', async () => {
+    const { active, agentA, agentB } = await agents()
+    const [aOwn, bOwn, aCross, bCross] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('fs-a-own'), name: 'write', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { file_path: 'a-owned.txt', content: 'a' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-b-own'), name: 'write', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { file_path: 'b-owned.txt', content: 'b' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-a-cross'), name: 'write', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { file_path: join(projectB, 'from-a.txt'), content: 'cross' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-b-cross'), name: 'write', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { file_path: join(projectA, 'from-b.txt'), content: 'cross' },
+      }),
+    ])
+
+    expect(aOwn.isError).toBe(false)
+    expect(bOwn.isError).toBe(false)
+    expect(aCross.isError).toBe(true)
+    expect(bCross.isError).toBe(true)
+    expect(resultText(aCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(resultText(bCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(await readFile(join(projectA, 'a-owned.txt'), 'utf8')).toBe('a')
+    expect(await readFile(join(projectB, 'b-owned.txt'), 'utf8')).toBe('b')
+    await expectMissing(join(projectB, 'from-a.txt'))
+    await expectMissing(join(projectA, 'from-b.txt'))
+  })
+
+  it.skipIf(!processSandboxUsable)('keeps symlink-sensitive session cwd semantics aligned across bash, fs, and policy', async () => {
+    const active = ctx as Context
+    const lexicalRoot = await projectDir('lexical-workspace')
+    const physicalRoot = await projectDir('physical-workspace')
+    const physicalChild = join(physicalRoot, 'child')
+    await mkdir(physicalChild)
+    const link = join(lexicalRoot, 'link')
+    await symlink(physicalChild, link, process.platform === 'win32' ? 'junction' : 'dir')
+    const sessionCwd = `${link}/..`
+    const handle = await active.agents.create({
+      sessionId: SessionId('symlink-parent-session'),
+      meta: { cwd: sessionCwd },
+    })
+
+    const [bashOwn, bashLexical, fsOwn, fsLexical] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('bash-symlink-own'), name: 'bash', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { command: 'printf bash > bash-owned.txt', description: 'Write physical workspace marker' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-symlink-lexical'), name: 'bash', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { command: `printf escaped > ${join(lexicalRoot, 'bash-escaped.txt')}`, description: 'Attempt lexical workspace write' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-symlink-own'), name: 'write', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { file_path: 'fs-owned.txt', content: 'fs' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-symlink-lexical'), name: 'write', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { file_path: join(lexicalRoot, 'fs-escaped.txt'), content: 'escaped' },
+      }),
+    ])
+
+    expect(bashOwn.isError).toBe(false)
+    expect(resultText(bashOwn)).not.toContain('[sandbox:')
+    expect(bashLexical.isError).toBe(false)
+    expect(resultText(bashLexical)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(fsOwn.isError).toBe(false)
+    expect(fsLexical.isError).toBe(true)
+    expect(resultText(fsLexical)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(await readFile(join(physicalRoot, 'bash-owned.txt'), 'utf8')).toBe('bash')
+    expect(await readFile(join(physicalRoot, 'fs-owned.txt'), 'utf8')).toBe('fs')
+    await expectMissing(join(lexicalRoot, 'bash-escaped.txt'))
+    await expectMissing(join(lexicalRoot, 'fs-escaped.txt'))
+  })
+
+  it.skipIf(!processSandboxUsable)('resolves parent traversal from a symlinked session root consistently', async () => {
+    const active = ctx as Context
+    const lexicalRoot = await projectDir('lexical-parent')
+    const physicalRoot = await projectDir('physical-parent')
+    const physicalChild = join(physicalRoot, 'child')
+    await mkdir(physicalChild)
+    const link = join(lexicalRoot, 'link')
+    await symlink(physicalChild, link, process.platform === 'win32' ? 'junction' : 'dir')
+    await writeFile(join(lexicalRoot, 'shared.txt'), 'from-lexical-parent')
+    await writeFile(join(physicalRoot, 'shared.txt'), 'from-physical-parent')
+    const handle = await active.agents.create({
+      sessionId: SessionId('symlink-root-parent-path-session'),
+      meta: { cwd: link },
+    })
+
+    const [bashRead, fsRead] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('bash-symlink-parent-read'), name: 'bash', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { command: 'cat ../shared.txt', description: 'Read through the physical parent' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-symlink-parent-read'), name: 'read', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { file_path: '../shared.txt' },
+      }),
+    ])
+
+    expect(bashRead.isError).toBe(false)
+    expect(fsRead.isError).toBe(false)
+    expect(resultText(bashRead)).toContain('from-physical-parent')
+    expect(resultText(fsRead)).toContain('from-physical-parent')
+    expect(resultText(bashRead)).not.toContain('from-lexical-parent')
+    expect(resultText(fsRead)).not.toContain('from-lexical-parent')
+  })
+})

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

@@ -162,15 +162,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/fs/README.md

@@ -6,9 +6,9 @@ The filesystem stack: a provider seam (text IO + atomic mutation with an optiona
 |---|---|---|
 | `fs/` | Provider seam: text IO + atomic mutation primitives (optional version guard); owns the `fs/*` policy events | `ctx.fs` |
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
-| `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call sandbox mode (read-only denies, workspace-write contains to the workspace + temp roots), reads pass through | (registers `ctx.fs`) |
+| `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
-| `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); advertises the sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
+| `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
 | `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
 The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas — `fs-sandbox` is the first such replacement (an in-process path fence over the shared sandbox mode; see [the cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).

packages/fs/fs-sandbox/README.md

@@ -2,11 +2,11 @@
 
 `SandboxedFileSystem` extends [`LocalFileSystem`](../fs-local/README.md) and registers as `ctx.fs`. It inherits every text-storage mechanic verbatim (resolve, stat, read/stream, list, the atomic write, the read-match-write edit critical section) and adds only a per-call MODE fence on `writeText`/`editText`. Reads always pass through — every mode permits reading.
 
-Loading it INSTEAD OF `dsh-fs-local`, together with a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/README.md), is the whole swap; the model-facing tools (`dsh-tool-fs`) are untouched. Injects `sandboxPolicy` for the default mode and the `workspace-write` boundary root — the SAME policy home bash reads, so the two families never confine to different roots.
+Loading it INSTEAD OF `dsh-fs-local`, together with a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/README.md), is the whole swap; the model-facing tools (`dsh-tool-fs`) are untouched. The tool layer resolves the calling session's mode and cwd into the SAME per-call policy bash receives, so the two families never confine to different roots.
 
 ## The fence
 
-The per-call mode is the tool-stamped effective mode (session override or escalation grant), falling back to the deployment default:
+The per-call policy carries the effective mode (session override or escalation grant) together with the calling session's immutable cwd root, falling back to deployment policy only for calls without one:
 
 - `read-only` — denies every mutation with the structured `FS_SANDBOX_DENIED`.
 - `workspace-write` — allows a mutation only when the target canonicalizes under a writable root: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), the SAME set the Seatbelt profile grants, derived from the one [`writableRoots`](../../sandbox/README.md) function so the fs fence and the bash runner cannot drift. Canonical spellings use a lexical fast path; an identity-based ancestor fallback recognizes alias-equivalent roots such as Windows long names and 8.3 names without treating unrelated prefixes as contained. The target is re-canonicalized immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught.
@@ -30,4 +30,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **A policy fence, not a kernel boundary** — the check is trusted code over a model-controlled path, so the residual resolve-to-syscall TOCTOU is narrowed (by the in-place re-canonicalization) but not eliminated; adversarial host processes are out of scope. Kernel-grade isolation of untrusted code stays `ctx.bash`'s.
 - **Fence-vs-runner parity is derived, not asserted** — the writable set comes from `writableRoots`, shared with the Seatbelt profile and pinned by a parity test; a runner profile that changed its writable set without that function would drift.
-- **Requires `ctx.sandboxPolicy`** — the backend reads the default mode and workspace root from it and does not confine without it composed.
+- **Requires `ctx.sandboxPolicy`** — tools use it to resolve each session policy and the backend uses it for agentless-call fallbacks; the backend does not confine without it composed.

packages/fs/fs-sandbox/src/index.ts

@@ -3,7 +3,7 @@
  * `@deepseek-ai/dsh-fs` provider seam. It extends `LocalFileSystem` so all
  * text-storage mechanics — resolve, stat, read/stream, list, the atomic
  * write and the read-match-write edit critical section — are the local
- * implementation's, verbatim; this package adds only the per-call MODE fence
+ * implementation's, verbatim; this package adds only the per-call POLICY fence
  * on the two mutations. Reads pass through untouched: every mode permits
  * reading.
  *
@@ -17,9 +17,9 @@
  * syscall) is narrowed by re-canonicalizing immediately before delegating and
  * is accepted for this threat model.
  *
- * Per-call mode: `read-only` denies every mutation; `workspace-write` allows a
- * mutation only when the target canonicalizes under the workspace root or a
- * platform temp area (the SAME writable-root set the Seatbelt profile grants,
+ * Per-call policy: `read-only` denies every mutation; `workspace-write` allows
+ * a mutation only when the target canonicalizes under the policy's workspace
+ * root or a platform temp area (the SAME writable-root set Seatbelt grants,
  * derived from the one `writableRoots` function so bash and fs cannot drift);
  * `danger-full-access` delegates unfenced. A denial throws the structured
  * `FS_SANDBOX_DENIED` — no text inference is needed (unlike bash's kernel
@@ -36,15 +36,15 @@ import type { Config as LocalConfig } from '@deepseek-ai/dsh-fs-local'
 import { FsError } from '@deepseek-ai/dsh-fs'
 import type { FsEditOutcome, FsEditRequest, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from '@deepseek-ai/dsh-fs'
 import { writableRoots } from '@deepseek-ai/dsh-sandbox'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import type {} from '@deepseek-ai/dsh-sandbox-policy'
 import { isPathUnder } from './containment.ts'
 
 /**
  * Plugin config: the local backend's knobs, verbatim (only `cwd`, the resolve
  * base for relative paths). The sandbox default (mode + `workspace-write`
- * boundary root) is NOT here — it lives on `ctx.sandboxPolicy`, the one home
- * both enforcing families share.
+ * fallback root) is NOT here — `ctx.sandboxPolicy` resolves each calling
+ * session for both enforcing families.
  */
 export type Config = LocalConfig
 
@@ -52,26 +52,17 @@ export type Config = LocalConfig
  * Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it
  * INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole
  * swap — the model-facing tools are untouched). Its configured default mode is
- * the fallback exposed by {@link sandboxMode}; `dsh-tool-fs` folds a session's
- * `sandbox/mode` override and stamps the effective mode onto each mutation,
- * while an approved escalation may stamp a strictly wider mode for one call.
+ * the capability fact exposed by {@link sandboxMode}; `dsh-tool-fs` resolves
+ * each session's mode and cwd into a policy for every mutation, while an
+ * approved escalation may stamp a strictly wider mode for one call.
  */
 export class SandboxedFileSystem extends LocalFileSystem {
   static inject = ['sandboxPolicy']
 
   private readonly defaultMode: SandboxMode
-  /**
-   * The canonical roots a `workspace-write` mutation may land under, computed
-   * once (the workspace root and platform temp areas are fixed for the
-   * provider's lifetime): the same set {@link writableRoots} gives every
-   * enforcement dialect, so the fs fence and the bash runner agree.
-   */
-  private readonly writableRoots: string[]
-
   constructor(ctx: Context, config: Config) {
     super(ctx, config)
     this.defaultMode = ctx.sandboxPolicy.defaultMode
-    this.writableRoots = writableRoots({ mode: 'workspace-write', workspaceRoot: ctx.sandboxPolicy.workspaceRoot })
   }
 
   /** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
@@ -80,13 +71,14 @@ export class SandboxedFileSystem extends LocalFileSystem {
   }
 
   /**
-   * Fence the write by the per-call mode, then delegate to the inherited
+   * Fence the write by the per-call policy, then delegate to the inherited
    * atomic write. See {@link checkedTarget}.
    * @param target - the resolved target to write.
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
    * @param signal - aborts before the atomic rename takes effect.
-   * @param sandboxMode - the per-call mode; omit to use the deployment default.
+   * @param sandboxPolicy - the per-call mode and workspace root; omit to use
+   *   the deployment fallback.
    * @returns the write outcome from the inherited backend.
    */
   override async writeText(
@@ -94,19 +86,20 @@ export class SandboxedFileSystem extends LocalFileSystem {
     content: string,
     expected?: FsWriteIntent,
     signal?: AbortSignal,
-    sandboxMode?: SandboxMode,
+    sandboxPolicy?: SandboxExecutionPolicy,
   ): Promise<FsWriteOutcome> {
-    return super.writeText(await this.checkedTarget(target, sandboxMode), content, expected, signal)
+    return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal)
   }
 
   /**
-   * Fence the edit by the per-call mode, then delegate to the inherited
+   * Fence the edit by the per-call policy, then delegate to the inherited
    * atomic edit. See {@link checkedTarget}.
    * @param target - the resolved target to edit.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.
    * @param signal - aborts before the atomic rename takes effect.
-   * @param sandboxMode - the per-call mode; omit to use the deployment default.
+   * @param sandboxPolicy - the per-call mode and workspace root; omit to use
+   *   the deployment fallback.
    * @returns the edit outcome from the inherited backend.
    */
   override async editText(
@@ -114,13 +107,13 @@ export class SandboxedFileSystem extends LocalFileSystem {
     edit: FsEditRequest,
     expected?: { version: FsVersion },
     signal?: AbortSignal,
-    sandboxMode?: SandboxMode,
+    sandboxPolicy?: SandboxExecutionPolicy,
   ): Promise<FsEditOutcome> {
-    return super.editText(await this.checkedTarget(target, sandboxMode), edit, expected, signal)
+    return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal)
   }
 
   /**
-   * Enforce the per-call mode against `target` and return the EXACT target the
+   * Enforce the per-call policy against `target` and return the EXACT target the
    * mutation must use, so the checked identity is the mutated one (no
    * check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
    * re-canonicalizes NOW (`resolve` realpaths the deepest existing ancestor,
@@ -130,8 +123,9 @@ export class SandboxedFileSystem extends LocalFileSystem {
    * refusal — the tool layer maps it to the model-facing `[sandbox: …]` marker
    * and the escalation hint.
    */
-  private async checkedTarget(target: FsTarget, sandboxMode?: SandboxMode): Promise<FsTarget> {
-    const mode = sandboxMode ?? this.defaultMode
+  private async checkedTarget(target: FsTarget, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsTarget> {
+    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve()
+    const { mode } = policy
     if (mode === 'danger-full-access') return target
     if (mode === 'read-only') {
       throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, 'FS_SANDBOX_DENIED')
@@ -141,7 +135,7 @@ export class SandboxedFileSystem extends LocalFileSystem {
     // mutation delegates with THIS fresh target — never the stale one.
     const fresh = await this.resolve(target.displayPath)
     let contained = false
-    for (const root of this.writableRoots) {
+    for (const root of writableRoots(policy)) {
       if (await isPathUnder(fresh.targetKey, root)) {
         contained = true
         break

packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for the sandbox-enforcing filesystem backend: the per-call mode fence
+ * Tests for the sandbox-enforcing filesystem backend: the per-call policy fence
  * on write/edit (read-only denies, workspace-write contains, danger-full-access
  * passes through), reads always passing through, the capability fact, and the
  * containment matrix — `..` traversal, absolute paths outside, and symlink
@@ -194,12 +194,12 @@ describe('danger-full-access', () => {
   })
 })
 
-describe('the per-call mode override (escalation)', () => {
+describe('the per-call policy override (escalation)', () => {
   it('a workspace-write stamp on a read-only default lets a contained write land for that call only', async () => {
     await boot('read-only')
     const path = join(workspace, 'escalated.txt')
-    // Default read-only would deny; the per-call workspace-write stamp allows it (contained).
-    await fs.writeText(await target(path), 'granted', undefined, undefined, 'workspace-write')
+    // Default read-only would deny; the per-call workspace-write policy allows it (contained).
+    await fs.writeText(await target(path), 'granted', undefined, undefined, { mode: 'workspace-write', workspaceRoot: workspace })
     expect(await readFile(path, 'utf8')).toBe('granted')
     // A neighboring plain call still runs under the read-only default.
     await expect(fs.writeText(await target(join(workspace, 'plain.txt')), 'x'))
@@ -209,7 +209,7 @@ describe('the per-call mode override (escalation)', () => {
   it('a danger-full-access stamp bypasses the fence for that call', async () => {
     await boot('read-only')
     const path = join(outside, 'granted-full.txt')
-    await fs.writeText(await target(path), 'full', undefined, undefined, 'danger-full-access')
+    await fs.writeText(await target(path), 'full', undefined, undefined, { mode: 'danger-full-access', workspaceRoot: workspace })
     expect(await readFile(path, 'utf8')).toBe('full')
   })
 })

packages/fs/fs/src/index.ts

@@ -7,7 +7,7 @@
  */
 
 import { Context, Service } from 'cordis'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import type {
   FsDirEntry,
   FsEditOutcome,
@@ -170,9 +170,9 @@ export abstract class FileSystem extends Service {
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
    * @param signal - aborts before the atomic rename takes effect.
-   * @param sandboxMode - the per-call sandbox mode this write runs under; a
-   *   sandboxing backend fences the write by it, the bare backend ignores it.
-   *   Omit to leave the backend its own default.
+   * @param sandboxPolicy - the per-call mode and workspace root this write
+   *   runs under; a sandboxing backend fences the write by it, the bare backend
+   *   ignores it. Omit to leave the backend its own default.
    * @returns the outcome, including the version the write produced.
    */
   abstract writeText(
@@ -180,7 +180,7 @@ export abstract class FileSystem extends Service {
     content: string,
     expected?: FsWriteIntent,
     signal?: AbortSignal,
-    sandboxMode?: SandboxMode,
+    sandboxPolicy?: SandboxExecutionPolicy,
   ): Promise<FsWriteOutcome>
 
   /**
@@ -191,9 +191,9 @@ export abstract class FileSystem extends Service {
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.
    * @param signal - aborts before the atomic rename takes effect.
-   * @param sandboxMode - the per-call sandbox mode this edit runs under; a
-   *   sandboxing backend fences the edit by it, the bare backend ignores it.
-   *   Omit to leave the backend its own default.
+   * @param sandboxPolicy - the per-call mode and workspace root this edit runs
+   *   under; a sandboxing backend fences the edit by it, the bare backend
+   *   ignores it. Omit to leave the backend its own default.
    * @returns the outcome, including the version the edit produced.
    */
   abstract editText(
@@ -201,7 +201,7 @@ export abstract class FileSystem extends Service {
     edit: FsEditRequest,
     expected?: { version: FsVersion },
     signal?: AbortSignal,
-    sandboxMode?: SandboxMode,
+    sandboxPolicy?: SandboxExecutionPolicy,
   ): Promise<FsEditOutcome>
 }
 

packages/fs/tool-fs-search/tests/load-path.spec.ts

@@ -36,7 +36,7 @@ class ProbeSuccessBashExecutor extends BashExecutor {
       timeoutMs: request.timeoutMs ?? 60_000,
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       signal: request.signal,
-      sandboxMode: request.sandboxMode,
+      sandboxPolicy: request.sandboxPolicy,
     }
   }
 

packages/fs/tool-fs-search/tests/tools.spec.ts

@@ -75,7 +75,7 @@ class FakeBash extends BashExecutor {
       timeoutMs: request.timeoutMs ?? 60_000,
       stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       ...this.forwardSignal ? { signal: request.signal } : {},
-      sandboxMode: request.sandboxMode,
+      sandboxPolicy: request.sandboxPolicy,
     }
   }
   override async run(spec: BashExecSpec): Promise<BashRunResult> {

packages/fs/tool-fs/src/edit.ts

@@ -92,10 +92,10 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
     },
     async execute(args: EditToolArgs, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseEditArgs(args)
-      // Resolve the per-call sandbox mode (escalation grant > session override
-      // > backend default) BEFORE anything executes.
-      const sandboxMode = await sandbox.stampMode('edit', args, exec)
-      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
+      // Resolve the per-call sandbox policy (approved mode > session override
+      // > backend default, plus the session cwd root) BEFORE anything executes.
+      const sandboxPolicy = await sandbox.resolvePolicy('edit', args, exec)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot))
       // Single-slot decision: the policy plugin returns { version: vObserved } or
       // throws FS_NOT_OBSERVED; the bare default is undefined (unconditional edit).
       // No stat — the bare default never manufactures a version basis.
@@ -107,11 +107,11 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
           { oldString: input.oldString, newString: input.newString, replaceAll: input.replaceAll },
           intent,
           exec.signal,
-          sandboxMode,
+          sandboxPolicy,
         )
       } catch (error: unknown) {
         // A sandbox denial becomes the shared [sandbox: …] marker; any other error passes through.
-        throw sandbox.mapError(error, sandboxMode)
+        throw sandbox.mapError(error, sandboxPolicy)
       }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)

packages/fs/tool-fs/src/index.ts

@@ -64,7 +64,7 @@ export function apply(ctx: Context, config: Config): void {
     streamMinSize: resolved.readStreamMinSize,
   })
   // One escalation surface shared by both mutating tools: advertisement gating,
-  // per-call mode stamping, and denial-marker mapping, all keyed off whether
+  // per-call policy resolution, and denial-marker mapping, all keyed off whether
   // the mounted ctx.fs confines (ctx.fs.sandboxMode).
   const sandbox = new FsSandboxSurface(ctx)
   applyWriteTool(ctx, sandbox)

packages/fs/tool-fs/src/read.ts

@@ -88,7 +88,7 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
     isConcurrencySafe: () => true,
     async execute(args, exec): Promise<ContentBlock[]> {
       const input = parseReadArgs(args, caps.limit)
-      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath))
 
       // One stat: type check + size routing + the version recorded as observed.
       // A concurrent write can only make a later guarded mutation fail stale and require reread.

packages/fs/tool-fs/src/sandbox.ts

@@ -1,6 +1,6 @@
 /**
  * The sandbox-escalation surface shared by the `write` and `edit` tools: the
- * per-call mode stamp, the advertised escalation fields, and the denial-marker
+ * per-call policy resolution, the advertised escalation fields, and the denial-marker
  * mapping — all delegating the vocabulary and the fail-closed approval
  * sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
  * uses), so bash and fs escalate identically. Built ONCE per plugin from
@@ -12,9 +12,9 @@
 
 import type { Context } from 'cordis'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
-import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
+import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { FsError } from '@deepseek-ai/dsh-fs'
 
 /** The two escalation arguments a mutating tool may carry (advertised only under a confining backend). */
@@ -30,20 +30,23 @@ export interface EscalationSchemaFields {
 }
 
 /**
- * The filesystem escalation surface: advertisement gating, per-call mode
- * stamping (folding the session's `sandbox/mode` override), the one-approved
- * wider retry, and denial-marker mapping. A pure product of `ctx` at plugin
- * apply time.
+ * The filesystem escalation surface: advertisement gating, per-call policy
+ * resolution, the one-approved wider retry, and denial-marker mapping. A pure
+ * product of `ctx` at plugin apply time.
  */
 export class FsSandboxSurface {
   /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
   readonly escalationModes: readonly SandboxMode[]
-  /** The backend's default mode, or `undefined` when `ctx.fs` does not confine. */
-  private readonly defaultMode: SandboxMode | undefined
+  /** Shared per-session policy resolver, required by a confining backend. */
+  private readonly policy: SandboxPolicyService | undefined
 
   constructor(private readonly ctx: Context) {
-    this.defaultMode = ctx.fs.sandboxMode
-    this.escalationModes = this.defaultMode === undefined ? [] : ESCALATION_TARGETS
+    const defaultMode = ctx.fs.sandboxMode
+    this.escalationModes = defaultMode === undefined ? [] : ESCALATION_TARGETS
+    this.policy = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy')
+    if (defaultMode !== undefined && this.policy === undefined) {
+      throw new Error('tool-fs: the mounted filesystem confines but ctx.sandboxPolicy is missing')
+    }
   }
 
   /**
@@ -70,37 +73,29 @@ export class FsSandboxSurface {
   }
 
   /**
-   * The session's standing mode override for an ordinary (non-escalating)
-   * call — the `sandbox/mode` fold of the calling agent's log. Undefined for a
-   * non-confining backend and for agent-less callers.
-   */
-  private sessionOverride(exec: ToolExecution): SandboxMode | undefined {
-    if (this.defaultMode === undefined || exec.agent === undefined) return undefined
-    return effectiveSandboxMode(exec.agent.session.events)
-  }
-
-  /**
-   * The mode to STAMP onto this mutation: an approved escalation grant (a
+   * The policy to stamp onto this mutation: an approved escalation grant (a
    * strictly wider retry resolved through `ctx.approval` before anything
-   * executes), else the session's standing override, else `undefined` (the
-   * backend applies its own default). Validates the escalation argument
+   * executes), else the session's standing mode. The calling session's cwd is
+   * always carried as the workspace root. Validates the escalation argument
    * pairing first.
    * @param toolName - the mutating tool's name, for the approval audit trail.
    * @param args - the call's escalation arguments.
    * @param exec - the tool-execution context (agent, callId, signal).
-   * @returns the mode to pass to the mutation, or undefined for the backend default.
+   * @returns the policy to pass to the mutation, or undefined for an
+   *   unsandboxed backend.
    */
-  async stampMode(toolName: string, args: FsEscalationArgs, exec: ToolExecution): Promise<SandboxMode | undefined> {
+  async resolvePolicy(toolName: string, args: FsEscalationArgs, exec: ToolExecution): Promise<SandboxExecutionPolicy | undefined> {
     validateEscalationArgs(args.sandbox_permissions, args.justification)
+    const standingPolicy = this.policy?.resolve({ ...exec.agent ? { session: exec.agent.session } : {} })
     if (args.sandbox_permissions === undefined || args.justification === undefined) {
-      return this.sessionOverride(exec)
+      return standingPolicy
     }
     if (this.escalationModes.length === 0) {
       throw new Error('sandbox_permissions is not available in this composition (no sandboxing filesystem to escalate)')
     }
-    const effectiveMode = (this.sessionOverride(exec) ?? this.defaultMode) as SandboxMode
-    return approveEscalation(
-      { requestedMode: args.sandbox_permissions, justification: args.justification, effectiveMode, subject: 'operation' },
+    const policy = standingPolicy as SandboxExecutionPolicy
+    const approvedMode = await approveEscalation(
+      { requestedMode: args.sandbox_permissions, justification: args.justification, effectiveMode: policy.mode, subject: 'operation' },
       {
         approver: this.ctx.get('approval'),
         agent: exec.agent,
@@ -109,6 +104,7 @@ export class FsSandboxSurface {
         signal: exec.signal,
       },
     )
+    return { ...policy, mode: approvedMode }
   }
 
   /**
@@ -122,14 +118,14 @@ export class FsSandboxSurface {
    * confining backend, which always advertises the escalation fields, so the
    * hint always applies here.
    * @param error - the error thrown by the mutation.
-   * @param stampedMode - the mode stamped onto the call (names the mode in the marker).
+   * @param policy - the policy stamped onto the call (names the mode in the marker).
    * @returns the error to throw — the marker `FsError` for a sandbox denial, else the original.
    */
-  mapError(error: unknown, stampedMode: SandboxMode | undefined): unknown {
+  mapError(error: unknown, policy: SandboxExecutionPolicy | undefined): unknown {
     if (!(error instanceof FsError) || error.code !== 'FS_SANDBOX_DENIED') return error
-    // A FS_SANDBOX_DENIED only arises under a confining backend, so defaultMode
-    // (hence the resolved mode) is defined here.
-    const mode = (stampedMode ?? this.defaultMode) as SandboxMode
+    // A FS_SANDBOX_DENIED only arises under a confining backend, whose tool
+    // path always resolves a policy before mutation.
+    const mode = (policy as SandboxExecutionPolicy).mode
     return new FsError(`${sandboxDenialMarker(mode)}\n${escalationHintMarker('operation')}`, 'FS_SANDBOX_DENIED', { cause: error })
   }
 }

packages/fs/tool-fs/src/session-cwd.ts

@@ -9,23 +9,36 @@
  */
 
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import { canonicalPath } from '@deepseek-ai/dsh-sandbox'
+
+const PARENT_PATH_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/
 
 /**
  * The session workspace cwd for this call, or `undefined` when none applies.
  * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @param requestedPath - the path the provider will resolve; parent traversal
+ *   makes a symlinked cwd's filesystem identity observable.
  * @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
  */
-export function sessionCwd(exec: ToolExecution): string | undefined {
-  return exec.agent?.session.header.cwd
+export function sessionCwd(exec: ToolExecution, requestedPath: string): string | undefined {
+  const cwd = exec.agent?.session.header.cwd
+  if (cwd === undefined || (!PARENT_PATH_SEGMENT.test(cwd) && !PARENT_PATH_SEGMENT.test(requestedPath))) return cwd
+  return canonicalPath(cwd)
 }
 
 /**
  * Resolution options shared by all model-facing filesystem tools.
  * @param exec - the tool-execution context supplying session cwd and cancellation.
+ * @param requestedPath - the path the provider will resolve.
+ * @param policyWorkspaceRoot - resolved per-call root, when a mutation carries sandbox policy.
  * @returns provider resolution options for the current tool call.
  */
-export function sessionResolveOptions(exec: ToolExecution): { cwd?: string; signal?: AbortSignal } {
-  const cwd = sessionCwd(exec)
+export function sessionResolveOptions(
+  exec: ToolExecution,
+  requestedPath: string,
+  policyWorkspaceRoot?: string,
+): { cwd?: string; signal?: AbortSignal } {
+  const cwd = policyWorkspaceRoot ?? sessionCwd(exec, requestedPath)
   return {
     ...cwd !== undefined ? { cwd } : {},
     signal: exec.signal,

packages/fs/tool-fs/src/write.ts

@@ -76,21 +76,21 @@ export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
     },
     async execute(args: WriteToolArgs, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseWriteArgs(args)
-      // Resolve the per-call sandbox mode (escalation grant > session override
-      // > backend default) BEFORE anything executes; an escalating call
-      // resolves approval here and throws its distinct text on any non-grant.
-      const sandboxMode = await sandbox.stampMode('write', args, exec)
-      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
+      // Resolve the per-call sandbox policy (approved mode > session override
+      // > backend default, plus the session cwd root) BEFORE anything executes;
+      // an escalating call throws its distinct text on any non-grant.
+      const sandboxPolicy = await sandbox.resolvePolicy('write', args, exec)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot))
       // Single-slot decision: the policy plugin produces createIfAbsent/
       // replaceIfVersion; the bare default is undefined (unconditional). No stat.
       const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)
       let outcome: FsWriteOutcome
       try {
-        outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal, sandboxMode)
+        outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal, sandboxPolicy)
       } catch (error: unknown) {
         // A sandbox denial becomes the shared [sandbox: …] marker (the model
         // recognizes it from bash); any other error passes through.
-        throw sandbox.mapError(error, sandboxMode)
+        throw sandbox.mapError(error, sandboxPolicy)
       }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)

packages/fs/tool-fs/tests/tools.spec.ts

@@ -5,6 +5,9 @@
 
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, sep } from 'node:path'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -24,8 +27,10 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import { STREAM_MIN_SIZE } from '../src/read.ts'
 import { formatReadOutput } from '../src/read-render.ts'
 import type { FileReadOutcome } from '../src/read-render.ts'
+import { sessionCwd } from '../src/session-cwd.ts'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 
 const testToolSignal = new AbortController().signal
 
@@ -107,6 +112,32 @@ function text(result: { content: { type: string; text?: string }[] }): string {
   return result.content.filter(b => b.type === 'text').map(b => b.text).join('')
 }
 
+describe('session cwd resolution', () => {
+  const execution = (cwd?: string) => cwd === undefined
+    ? {}
+    : { agent: { session: { header: { cwd } } } }
+
+  it('retains ordinary spelling but resolves the cwd before parent traversal', () => {
+    const cwd = process.cwd()
+    const throughParent = `${cwd}${sep}..`
+    expect(sessionCwd(execution() as never, 'file.txt')).toBeUndefined()
+    expect(sessionCwd(execution(cwd) as never, 'file.txt')).toBe(cwd)
+    expect(sessionCwd(execution(throughParent) as never, 'file.txt')).toBe(realpathSync.native(throughParent))
+
+    const root = mkdtempSync(join(tmpdir(), 'dsh-tool-fs-session-cwd-'))
+    const physical = join(root, 'physical')
+    const link = join(root, 'link')
+    try {
+      mkdirSync(physical)
+      symlinkSync(physical, link, process.platform === 'win32' ? 'junction' : 'dir')
+      expect(sessionCwd(execution(link) as never, 'child.txt')).toBe(link)
+      expect(sessionCwd(execution(link) as never, `..${sep}parent.txt`)).toBe(realpathSync.native(link))
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})
+
 describe('registration', () => {
   it('registers read, write, and edit', async () => {
     const { ctx } = await setup()
@@ -587,9 +618,9 @@ describe('read caps are plugin config', () => {
 })
 
 describe('sandbox escalation surface (write/edit)', () => {
-  /** A confining fake `ctx.fs`: reports a default mode, records the per-call mode stamped, and can arm a sandbox denial. */
+  /** A confining fake `ctx.fs`: reports a default mode, records each per-call policy, and can arm a sandbox denial. */
   class SandboxingFakeFs extends FakeFs {
-    stamped: (SandboxMode | undefined)[] = []
+    stamped: (SandboxExecutionPolicy | undefined)[] = []
     override get sandboxMode(): SandboxMode {
       return 'workspace-write'
     }
@@ -598,9 +629,9 @@ describe('sandbox escalation surface (write/edit)', () => {
       content: string,
       expected?: FsWriteIntent,
       _signal?: AbortSignal,
-      sandboxMode?: SandboxMode,
+      sandboxPolicy?: SandboxExecutionPolicy,
     ): Promise<FsWriteOutcome> {
-      this.stamped.push(sandboxMode)
+      this.stamped.push(sandboxPolicy)
       return super.writeText(target, content, expected)
     }
     override async editText(
@@ -608,9 +639,9 @@ describe('sandbox escalation surface (write/edit)', () => {
       edit: FsEditRequest,
       expected?: { version: FsVersion },
       _signal?: AbortSignal,
-      sandboxMode?: SandboxMode,
+      sandboxPolicy?: SandboxExecutionPolicy,
     ): Promise<FsEditOutcome> {
-      this.stamped.push(sandboxMode)
+      this.stamped.push(sandboxPolicy)
       return super.editText(target, edit, expected)
     }
   }
@@ -619,6 +650,7 @@ describe('sandbox escalation surface (write/edit)', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write' })
     await ctx.plugin(SandboxingFakeFs)
     await ctx.plugin(FsPolicy)
     if (opts.approval === true) await ctx.plugin(ApprovalService)
@@ -631,7 +663,7 @@ describe('sandbox escalation surface (write/edit)', () => {
     return {
       id: 'agent-fs-esc',
       session: {
-        header: { version: 0, id: 'sess-fs-esc', createdAt: 0 },
+        header: { version: 0, id: 'sess-fs-esc', createdAt: 0, cwd: '/session-project' },
         events: [{ type: 'turn/start' }, ...events],
         append: (type: string, data: Record<string, unknown>) => { events.push({ type, data }) },
       },
@@ -644,6 +676,14 @@ describe('sandbox escalation surface (write/edit)', () => {
     return schema as unknown as { parameters: { properties: Record<string, { enum?: string[] }> } }
   }
 
+  it('fails load when a confining filesystem has no shared sandbox-policy resolver', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SandboxingFakeFs)
+    await expect(ctx.plugin(ToolFs)).rejects.toThrow('tool-fs: the mounted filesystem confines but ctx.sandboxPolicy is missing')
+  })
+
   it('advertises no escalation fields under a non-confining backend', async () => {
     const { ctx } = await setup()
     expect(ctx.fs.sandboxMode).toBeUndefined()
@@ -663,16 +703,16 @@ describe('sandbox escalation surface (write/edit)', () => {
     }
   })
 
-  it('a plain write stamps nothing (backend default) and no session override folds without one', async () => {
+  it('a plain write stamps the default mode with the calling session root', async () => {
     const { ctx, fs } = await setupConfining()
     await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent())
-    expect(fs.stamped).toEqual([undefined])
+    expect(fs.stamped).toEqual([{ mode: 'workspace-write', workspaceRoot: '/session-project' }])
   })
 
   it('a standing session override folds onto the stamp', async () => {
     const { ctx, fs } = await setupConfining()
     await call(ctx, 'write', { file_path: 'a.txt', content: 'x' }, escalationAgent([{ type: 'sandbox/mode', data: { mode: 'read-only' } }]))
-    expect(fs.stamped).toEqual(['read-only'])
+    expect(fs.stamped).toEqual([{ mode: 'read-only', workspaceRoot: '/session-project' }])
   })
 
   it('a denied write maps to the shared marker plus the escalation hint (isError)', async () => {
@@ -705,7 +745,7 @@ describe('sandbox escalation surface (write/edit)', () => {
       agent: escalationAgent() as never,
       signal: new AbortController().signal,
     })
-    expect(fs.stamped).toEqual(['danger-full-access'])
+    expect(fs.stamped).toEqual([{ mode: 'danger-full-access', workspaceRoot: '/session-project' }])
   })
 
   it('a rejected escalation fails closed with its own text and never mutates', async () => {

packages/hooks/hook-protocol/tests/runner.spec.ts

@@ -27,7 +27,7 @@ function recordingBash(run: (spec: BashExecSpec) => Promise<BashRunResult>): {
         ...request.signal ? { signal: request.signal } : {},
         ...request.stdin !== undefined ? { stdin: request.stdin } : {},
         ...request.env !== undefined ? { env: request.env } : {},
-        sandboxMode: request.sandboxMode,
+        sandboxPolicy: request.sandboxPolicy,
       }
     },
     async run(spec: BashExecSpec): Promise<BashRunResult> {

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/sandbox/README.md

@@ -1,12 +1,12 @@
 # sandbox/ — process-sandbox capability family
 
-The confinement half of the [capability-seam split](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): an abstract provider interface, platform backends, and the shared policy home. Consumers hand `ctx.sandbox` the exact argv they are about to spawn and spawn the returned (wrapped) argv instead; policy (`SandboxPolicy`: mode + workspace root) rides each call, so different consumers confine under different policies at the same instant. All **product** packages.
+The confinement half of the [capability-seam split](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): an abstract provider interface, platform backends, and the shared policy home. Consumers hand `ctx.sandbox` the exact argv they are about to spawn and spawn the returned (wrapped) argv instead; a complete `SandboxExecutionPolicy` (mode + workspace root) rides each capability call, and its confined subset becomes the provider's `SandboxPolicy`. Different sessions and consumers can therefore confine under different policies at the same instant. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
 | `sandbox/` | Abstract process-sandbox seam (the `SandboxProvider` contract + the mode/enforcement/policy vocabulary) plus the shared ESCALATION kit (`approveEscalation`, the strictly-wider ladder, the denial/hint markers) and the `writableRoots` derivation every enforcement dialect shares | `ctx.sandbox` |
 | `sandbox-local/` | Local backends by platform chain: Linux `bwrap` else the `landlock-run` launcher (the npm-distributed [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) family, built and released from its own repository), darwin `sandbox-exec`/Seatbelt — multi-candidate chains functionally probed, sole candidates selected directly, verdict cached, fail-closed | (registers `ctx.sandbox`) |
-| `sandbox-policy/` | The policy home: the deployment default (mode + `workspace-write` boundary root) and the per-session `sandbox/mode` override (event + fold + write path). Both enforcing families read it, so bash and fs can never confine to different roots | `ctx.sandboxPolicy` |
+| `sandbox-policy/` | The policy resolver: deployment fallbacks plus each session's durable mode and immutable cwd root. Both enforcing families consume its complete per-call result, so bash and fs cannot confine to different roots | `ctx.sandboxPolicy` |
 
 The seam confines SAME-WORLD subprocesses only (shared filesystem and kernel). Containers, microVMs, and remote executors are NOT backends here — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups; the boundary is recorded in [the sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
 

packages/sandbox/sandbox-policy/README.md

@@ -1,20 +1,21 @@
 # dsh-sandbox-policy — the sandbox policy home (`ctx.sandboxPolicy`)
 
-The single owner of the deployment's sandbox policy: the file-effect [`SandboxMode`](../sandbox/README.md) a session starts from, the `workspace-write` boundary root, and the per-session `sandbox/mode` override every enforcing capability family reads.
+The single owner of sandbox-policy resolution: the deployment's default [`SandboxMode`](../sandbox/README.md) and fallback root, plus each session's durable mode override and immutable workspace root. Every enforcing capability family receives one resolved mode-and-root policy per call.
 
 ## Why a shared home
 
-Two families enforce the same mode vocabulary: the sandboxed bash executor (`@deepseek-ai/dsh-bash-sandbox`) and the sandboxed filesystem provider (`@deepseek-ai/dsh-fs-sandbox`). If each held its own `mode` + `workspaceRoot` config, the two could drift into a split world — bash confined to one root while fs fences another, exactly what [the sandbox RFC](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) warns against. Both inject `ctx.sandboxPolicy` and read the SAME default instead. The [cross-family fs sandbox RFC](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) records the decision.
+Two families enforce the same mode vocabulary: the sandboxed bash executor (`@deepseek-ai/dsh-bash-sandbox`) and the sandboxed filesystem provider (`@deepseek-ai/dsh-fs-sandbox`). If each resolved its own `mode` + `workspaceRoot`, the two could drift into a split world — bash confined to one root while fs fences another, exactly what [the sandbox RFC](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) warns against. Both tool layers resolve policy through `ctx.sandboxPolicy`, and both enforcing backends consume that complete per-call result. The [cross-family fs sandbox RFC](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) records the shared-policy decision.
 
 ## Config
 
 - `mode` — the deployment default `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`), validated at load. Default `read-only` (fail-safe).
-- `workspaceRoot` — the absolute directory `workspace-write` may write under. Default `process.cwd()`, resolved absolute either way.
+- `workspaceRoot` — the fallback directory `workspace-write` may write under for agentless calls or sessions without a cwd. Default `process.cwd()`, resolved to its absolute filesystem identity either way. A normal agent call uses its session header's immutable `cwd` instead.
 
 ## Surface
 
-- `ctx.sandboxPolicy.defaultMode` / `ctx.sandboxPolicy.workspaceRoot` — the deployment default the enforcing implementations read for their resolve fallback and boundary.
-- `effectiveSandboxMode(events)` — the pure fold of a session's `sandbox/mode` events (the last switch wins, or `undefined`). The tool layers apply it to stamp each call, so neither the executor nor the provider depends on session events.
+- `ctx.sandboxPolicy.resolve({ session?, mode? })` — resolves one complete per-call policy. An explicit approved mode outranks the session's last `sandbox/mode` event, which outranks `defaultMode`; the session's immutable `cwd` is canonicalized with filesystem semantics before becoming `workspaceRoot`, otherwise the configured fallback applies. Canonicalization precedes lexical normalization so `symlink/..` agrees with process working-directory resolution.
+- `ctx.sandboxPolicy.defaultMode` / `ctx.sandboxPolicy.workspaceRoot` — the deployment default and fallback root used by `resolve()`.
+- `effectiveSandboxMode(events)` — the pure fold of a session's `sandbox/mode` events (the last switch wins, or `undefined`), used inside `resolve()`.
 - `setSandboxMode(session, mode)` — THE write path for a per-session override: appends exactly one `sandbox/mode` event. The switch IS its event; nothing mutates the mode out of band.
 - `SANDBOX_MODES` — every mode, for option advertisement and runtime validation.
 
@@ -22,7 +23,7 @@ The optional `./invariant` companion rejects a forged durable `sandbox/mode` eve
 
 ## The per-session store
 
-A runtime switch (an ACP `session/set_config_option`, a test scenario) is one log-only `sandbox/mode` event on the session it applies to. `effective = fold(events) ?? the deployment default`, so an override survives restart by replay, two sessions never see each other's state, and there is no external config store. The event is log-only (the `approval/*` precedent): the model learns the mode from the enforcing tools' denial markers, never from the event. Execution honors the fold in each tool layer, weakest-precedence beneath an escalation grant.
+A runtime switch (an ACP `session/set_config_option`, a test scenario) is one log-only `sandbox/mode` event on the session it applies to. `effective = explicit grant ?? fold(events) ?? deployment default`, so an override survives restart by replay and two sessions never see each other's state. Workspace identity does not need another event: the immutable `SessionHeader.cwd` recorded at creation is the root for every call in that session. The event is log-only (the `approval/*` precedent): the model learns the mode from the enforcing tools' denial markers, never from the event.
 
 ## Model Experience
 
@@ -34,5 +35,5 @@ No direct invalidation; the named consumers own any request-prefix changes, and
 
 ## Known Limitations and Deferred Work
 
-- **`workspaceRoot` is process-wide and fixed for the service's lifetime** — a per-session workspace root is a deferred phase of the sandbox RFC; this package centralizing the root is its groundwork, not its design.
+- **One primary workspace root per session** — policy resolves `SessionHeader.cwd`; extra writable roots are not part of `SandboxExecutionPolicy`.
 - **File-effect modes only** — `SandboxMode` governs file effects; network and process policy are outside its vocabulary, so no knob here restricts them.

packages/sandbox/sandbox-policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-sandbox-policy",
-  "description": "Sandbox policy home (ctx.sandboxPolicy) for the DeepSeek Harness: the deployment default mode + workspace root and the per-session sandbox/mode override, shared by every enforcing capability family",
+  "description": "Per-call sandbox policy resolver (ctx.sandboxPolicy): deployment fallbacks plus each session's mode and workspace root, shared by every enforcing capability family",
   "version": "0.0.1",
   "private": true,
   "type": "module",

packages/sandbox/sandbox-policy/src/index.ts

@@ -1,33 +1,33 @@
 /**
  * The sandbox POLICY home (`ctx.sandboxPolicy`): the single owner of the
- * deployment's sandbox default — the file-effect {@link SandboxMode} a session
- * starts from and the `workspace-write` boundary root — plus the per-session
- * override kit (the `sandbox/mode` event, its fold, and its write path, from
- * `./session-mode.ts`).
+ * deployment's sandbox fallbacks plus per-session resolution: the file-effect
+ * {@link SandboxMode}, the `workspace-write` root, and the override kit (the
+ * `sandbox/mode` event, its fold, and its write path, from `./session-mode.ts`).
  *
  * Both enforcing capability families read the SAME policy here: the sandboxed
  * bash executor (`@deepseek-ai/dsh-bash-sandbox`) and the sandboxed filesystem
- * provider (`@deepseek-ai/dsh-fs-sandbox`) inject `ctx.sandboxPolicy` for the
- * default mode and workspace root, so bash and fs can never confine to
- * different roots — the split world the sandbox RFC warns about. The default
- * lives here rather than on either executor's config precisely because it is
- * one fact two families share.
- *
- * This service holds only the DEFAULT; the per-session fold
- * ({@link effectiveSandboxMode}) is a pure function the tool layers apply to
- * stamp each call, so neither the executor nor the provider depends on session
- * events.
+ * provider (`@deepseek-ai/dsh-fs-sandbox`) consume the SAME resolved per-call
+ * policy, so bash and fs can never confine to different roots — the split
+ * world the sandbox RFC warns about. The service reads session state once at
+ * the tool boundary; executors and providers remain session-free.
  *
  * @module @deepseek-ai/dsh-sandbox-policy
  */
 
-import { resolve } from 'node:path'
+import { resolve as resolvePath } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { canonicalPath, type SandboxExecutionPolicy, type SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { effectiveSandboxMode } from './session-mode.ts'
 
 export { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from './session-mode.ts'
 
+/** Resolve filesystem identity before lexical normalization can erase symlink-sensitive components. */
+function resolveWorkspaceRoot(path: string): string {
+  return resolvePath(canonicalPath(path))
+}
+
 declare module 'cordis' {
   interface Context {
     sandboxPolicy: SandboxPolicyService
@@ -45,17 +45,25 @@ export interface Config {
   /** File-sandbox mode a session starts from (default: `read-only`). */
   mode?: SandboxMode
   /**
-   * Absolute root directory `workspace-write` may write under (default:
-   * `process.cwd()`). Both enforcing families fence against this SAME root.
+   * Fallback root for agentless calls and sessions without a cwd (default:
+   * `process.cwd()`). Normal agent calls use their session cwd instead.
    */
   workspaceRoot?: string
 }
 
+/** Inputs that select the sandbox policy for one capability call. */
+export interface SandboxPolicyRequest {
+  /** Calling session; its immutable cwd becomes the workspace boundary. */
+  session?: Session
+  /** Explicit approved mode override, which outranks session policy. */
+  mode?: SandboxMode
+}
+
 /**
  * The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment
- * default mode and workspace root; enforcing implementations read
- * {@link defaultMode} and {@link workspaceRoot}, and the tool layers fold each
- * session's `sandbox/mode` override with {@link effectiveSandboxMode} on top.
+ * default mode and fallback workspace root. Tool layers call {@link resolve}
+ * for each execution so a session's mode log and immutable cwd travel together
+ * to every enforcing capability.
  */
 export class SandboxPolicyService extends Service {
   // Inline schema call: the config catalog walks `static Config` statically.
@@ -68,7 +76,7 @@ export class SandboxPolicyService extends Service {
 
   /** The deployment default mode — the fallback beneath a session override. */
   readonly defaultMode: SandboxMode
-  /** The absolute `workspace-write` boundary root both families fence against. */
+  /** The absolute `workspace-write` fallback root for calls without a session cwd. */
   readonly workspaceRoot: string
 
   constructor(ctx: Context, config: Config) {
@@ -77,7 +85,24 @@ export class SandboxPolicyService extends Service {
     // runtime fact. `workspaceRoot` has NO schema default, so its fallback to
     // the process cwd is real branching, resolved absolute either way.
     this.defaultMode = config.mode as SandboxMode
-    this.workspaceRoot = resolve(config.workspaceRoot ?? process.cwd())
+    this.workspaceRoot = resolveWorkspaceRoot(config.workspaceRoot ?? process.cwd())
+  }
+
+  /**
+   * Resolve the complete policy for one capability call. An approved explicit
+   * mode outranks the session's last `sandbox/mode` event, which outranks the
+   * deployment default. A session cwd is its workspace-write boundary; the
+   * configured root is the fallback for agentless calls and sessions without a
+   * cwd.
+   * @param request - optional session and approved mode override.
+   * @returns the fully resolved per-call mode and absolute workspace root.
+   */
+  resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy {
+    const { session } = request
+    return {
+      mode: request.mode ?? (session === undefined ? undefined : effectiveSandboxMode(session.events)) ?? this.defaultMode,
+      workspaceRoot: resolveWorkspaceRoot(session?.header.cwd ?? this.workspaceRoot),
+    }
   }
 }
 

packages/sandbox/sandbox-policy/src/session-mode.ts

@@ -7,9 +7,9 @@
  * and there is no external config store. The event is log-only (the
  * `approval/*` precedent): the model learns the mode from the boundary
  * markers in the enforcing tools, never from the event itself. EXECUTION
- * honors the fold in each tool layer — it stamps the effective mode onto the
- * per-call policy carrier (a bash request's `sandboxMode`, an fs mutation's
- * `sandboxMode`), weakest-precedence beneath an escalation grant.
+ * honors the fold through `ctx.sandboxPolicy.resolve()` — it stamps the mode
+ * together with the calling session's workspace root onto each capability
+ * call, weakest-precedence beneath an escalation grant.
  *
  * The override is policy state shared by every enforcing family (bash and
  * filesystem alike), so it lives here in the policy package rather than in any

packages/sandbox/sandbox-policy/tests/policy.spec.ts

@@ -4,7 +4,9 @@
  * override kit (fold + write path) both enforcing families read.
  */
 
-import { resolve } from 'node:path'
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -16,6 +18,16 @@ async function mounted(config: { mode?: 'read-only' | 'workspace-write' | 'dange
   return ctx
 }
 
+function session(id: string, cwd?: string): Session {
+  const sessionId = SessionId(id)
+  return new Session(sessionId, undefined, {
+    version: 0,
+    id: sessionId,
+    createdAt: 0,
+    ...cwd === undefined ? {} : { cwd },
+  })
+}
+
 describe('SandboxPolicyService', () => {
   it('defaults to read-only under the process cwd', async () => {
     const ctx = await mounted()
@@ -29,6 +41,71 @@ describe('SandboxPolicyService', () => {
     expect(ctx.sandboxPolicy.workspaceRoot).toBe(resolve('/ws/../ws/./sub'))
   })
 
+  it('resolves the deployment policy for an agentless call', async () => {
+    const ctx = await mounted({ mode: 'workspace-write', workspaceRoot: '/fallback' })
+    expect(ctx.sandboxPolicy.resolve()).toEqual({
+      mode: 'workspace-write',
+      workspaceRoot: resolve('/fallback'),
+    })
+  })
+
+  it('resolves each session mode and cwd together without changing the fallback', async () => {
+    const ctx = await mounted({ mode: 'workspace-write', workspaceRoot: '/fallback' })
+    const first = session('sess-first', '/projects/first')
+    const second = session('sess-second', '/projects/second')
+    setSandboxMode(second, 'read-only')
+
+    expect(ctx.sandboxPolicy.resolve({ session: first })).toEqual({
+      mode: 'workspace-write',
+      workspaceRoot: resolve('/projects/first'),
+    })
+    expect(ctx.sandboxPolicy.resolve({ session: second })).toEqual({
+      mode: 'read-only',
+      workspaceRoot: resolve('/projects/second'),
+    })
+    expect(ctx.sandboxPolicy.resolve()).toEqual({
+      mode: 'workspace-write',
+      workspaceRoot: resolve('/fallback'),
+    })
+  })
+
+  it('resolves a symlink-sensitive session cwd with filesystem semantics', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-policy-cwd-'))
+    try {
+      const lexical = join(root, 'lexical')
+      const physical = join(root, 'physical')
+      const child = join(physical, 'child')
+      mkdirSync(lexical)
+      mkdirSync(child, { recursive: true })
+      const link = join(lexical, 'link')
+      symlinkSync(child, link, process.platform === 'win32' ? 'junction' : 'dir')
+      const cwd = `${link}${sep}..`
+      const ctx = await mounted({ mode: 'workspace-write', workspaceRoot: '/fallback' })
+
+      expect(ctx.sandboxPolicy.resolve({ session: session('sess-symlink-parent', cwd) })).toEqual({
+        mode: 'workspace-write',
+        workspaceRoot: realpathSync.native(physical),
+      })
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('lets an approved mode outrank the session mode while retaining its root', async () => {
+    const ctx = await mounted({ workspaceRoot: '/fallback' })
+    const active = session('sess-approved', '/projects/approved')
+    setSandboxMode(active, 'read-only')
+    expect(ctx.sandboxPolicy.resolve({ session: active, mode: 'danger-full-access' })).toEqual({
+      mode: 'danger-full-access',
+      workspaceRoot: resolve('/projects/approved'),
+    })
+  })
+
+  it('uses the configured root when a session has no cwd', async () => {
+    const ctx = await mounted({ workspaceRoot: '/fallback' })
+    expect(ctx.sandboxPolicy.resolve({ session: session('sess-no-cwd') }).workspaceRoot).toBe(resolve('/fallback'))
+  })
+
   it('rejects a mode outside the closed vocabulary at load', async () => {
     const ctx = new Context()
     // schemastery rejects the union violation when the plugin loads.

packages/sandbox/sandbox/README.md

@@ -1,12 +1,12 @@
 # @deepseek-ai/dsh-sandbox
 
-Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxPolicy` (per-CALL policy — mode + workspace root), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend.
+Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend.
 
 The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus two facts about the selected backend: the enforcement completeness it achieves and its denial dialect (`denialSignatures`, the stderr substrings its kernel prints on a denied file effect — what stderr-inferring consumers match instead of a cross-backend union); when no backend is usable it throws rather than passing the argv through unconfined.
 
 Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy.
 
-**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names a real host path. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names the filesystem-canonical real host directory. Workspace identity is resolved before lexical normalization, so a valid cwd containing `symlink/..` grants the directory where `chdir` actually lands rather than an unrelated lexical parent. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
 
 Implementations: [`@deepseek-ai/dsh-sandbox-local`](../sandbox-local/) (Linux: `bwrap`, else the per-platform Landlock launcher; macOS: `sandbox-exec`/Seatbelt). Consumers: [`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/) (wraps `['bash', '-c', command]`).
 

packages/sandbox/sandbox/src/index.ts

@@ -30,6 +30,18 @@ export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
 /** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
 export type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>
 
+/**
+ * The complete file-effect policy resolved for one capability call. The root
+ * is carried even under modes that do not consume it so callers can resolve
+ * policy once before choosing the enforcement path.
+ */
+export interface SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  mode: SandboxMode
+  /** Absolute root directory `workspace-write` may write under. */
+  workspaceRoot: string
+}
+
 /**
  * Enforcement completeness for this host. `partial` means an active backend or
  * older kernel ABI cannot govern every promised file effect; callers requiring
@@ -42,15 +54,12 @@ export type SandboxEnforcement = 'full' | 'partial'
  * fixed on the provider: two consumers may confine under different policies
  * at the same instant (bash under `read-only` while a confined child agent
  * needs its state directory writable), and an approved escalated retry is a
- * new call with a wider policy. Defaulting/resolution is the consumer's
- * explicit step (its config owns the fallback chain); the provider treats
- * the policy as fully specified.
+ * new call with a wider policy. Defaulting/resolution is an explicit step at
+ * the consumer boundary; the provider treats the policy as fully specified.
  */
-export interface SandboxPolicy {
+export interface SandboxPolicy extends SandboxExecutionPolicy {
   /** The file-effect mode this execution runs under. */
   mode: ConfinedSandboxMode
-  /** Absolute root directory `workspace-write` may write under. */
-  workspaceRoot: string
 }
 
 /**

packages/sandbox/sandbox/src/roots.ts

@@ -15,7 +15,7 @@
 
 import { realpathSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import type { SandboxPolicy } from './index.ts'
+import type { SandboxExecutionPolicy } from './index.ts'
 
 /**
  * Resolve a granted root to the path the enforcement layer actually compares:
@@ -29,9 +29,13 @@ import type { SandboxPolicy } from './index.ts'
  */
 export function canonicalPath(path: string): string {
   try {
-    return realpathSync(path)
+    // Node's JavaScript realpath implementation lexically collapses `..`
+    // before resolving a preceding symlink on some platforms. The native
+    // implementation follows the filesystem's component-by-component lookup,
+    // matching chdir/spawn and the enforcement layers this identity feeds.
+    return realpathSync.native(path)
   } catch {
-    // realpathSync failed: the path (or a prefix) is missing or unreadable.
+    // realpathSync.native failed: the path (or a prefix) is missing or unreadable.
     return path
   }
 }
@@ -45,7 +49,7 @@ export function canonicalPath(path: string): string {
  * @param policy - the file-effect policy to derive the allow-list from.
  * @returns the canonical writable roots; empty exactly under `read-only`.
  */
-export function writableRoots(policy: SandboxPolicy): string[] {
+export function writableRoots(policy: SandboxExecutionPolicy): string[] {
   if (policy.mode !== 'workspace-write') return []
   return [...new Set([policy.workspaceRoot, '/tmp', tmpdir()].map(canonicalPath))]
 }

packages/support/acp-snapshot/README.md

@@ -4,8 +4,8 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie
 
 Four layers, importable separately:
 
-- **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a temp cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
-- **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the expected-output and purity checks, and harvests every persisted raw JSONL session log (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo. Startup failures preserve captured agent stderr in the rejected diagnostic.
+- **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a supplied cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
+- **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the expected-output and purity checks, and harvests every persisted raw JSONL session log (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo; `workspaceParent` may move the generated child cwd from the platform temp directory when that grant is itself under test. Startup failures preserve captured agent stderr in the rejected diagnostic.
 - **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators selected as canonical `/` or host-native; `session_info_update.updatedAt` → `{{updatedAt}}`; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 - **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.expected.md` plus `tool-schemas.expected.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Refresh preserves existing volatile fields by event position and gives a newly inserted `session/title` its preceding event's time, so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
 
@@ -36,7 +36,7 @@ defineAcpSnapshotSuite({
 })
 ```
 
-A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.expected.md` and the corresponding full tool-schema sequence in generated `tool-schemas.expected.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences.
+A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. `workspaceParent` moves the generated cwd outside the platform temp area when temporary-directory grants are themselves under test; the harness still owns and removes only the generated child. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.expected.md` and the corresponding full tool-schema sequence in generated `tool-schemas.expected.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences.
 
 Every scenario compares `stdout.expected.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.expected.windows.jsonl` after the shared expected output and requires that sidecar exactly when enabled. A scenario whose driven behavior needs POSIX process semantics (e.g. cancelling a live bash call kills a detached process group) declares `posixOnly`, which skips its run test on Windows while the fixture guards keep covering its committed files everywhere.
 

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

@@ -130,7 +130,7 @@ export interface RunResult {
   stderr: string
   /** The session id the server issued (undefined if no session was created). */
   sessionId?: string
-  /** The temp cwd the session ran in (the bash workspace). */
+  /** The generated cwd the session ran in (the bash workspace). */
   cwd: string
   /**
    * Every persisted session log harvested after the run, ordered primary-first:
@@ -161,11 +161,19 @@ export interface RunOptions {
   childFiles?: string[]
   /**
    * Optional `<scenario>/workspace/` directory whose contents are copied into
-   * the temp cwd BEFORE the run — the standard way to seed files the agent
+   * the generated cwd BEFORE the run — the standard way to seed files the agent
    * operates on (a file to read, edit, or grep). Absent for scenarios that
    * start from an empty workspace.
    */
   workspaceDir?: string
+  /**
+   * Parent directory for the generated session cwd. Defaults to
+   * `os.tmpdir()`. A scenario that must distinguish its workspace from the
+   * sandbox's always-writable temporary roots can place the generated child
+   * under `os.homedir()` instead. The harness removes only that generated
+   * child, never the supplied parent.
+   */
+  workspaceParent?: string
   /**
    * Alternate LIVE config path for the boot (absolute), overriding
    * {@link AgentUnderTest.configPath} for this run. A scenario needing a
@@ -196,15 +204,15 @@ export function snapshotSpillRoot(
 
 /**
  * Run a scenario end-to-end against a freshly-spawned subprocess. Owns the
- * child and its temp dirs; always tears them down. Returns the captured stdout
+ * child and its generated dirs; always tears them down. Returns the captured stdout
  * and (record mode) the harvested session-log path.
  *
  * @param input The scenario's input script (steps + optional permission answers).
  * @param opts The agent to boot, the mode, and the fixture wiring.
- * @returns The captured stdout/stderr, session id, temp cwd, and harvested logs.
+ * @returns The captured stdout/stderr, session id, generated cwd, and harvested logs.
  */
 export async function runScenario(input: InputScript, opts: RunOptions): Promise<RunResult> {
-  const cwd = await mkdtemp(join(tmpdir(), 'acp-snap-cwd-'))
+  const cwd = await mkdtemp(join(opts.workspaceParent ?? tmpdir(), 'acp-snap-cwd-'))
   const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-'))
   // Fixed path length: spill-policy budgets the preview against the REAL path
   // before stdout normalization, so tmpdir() length differences churn expected outputs.
@@ -218,7 +226,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
   let sessionLogs: HarvestedLog[] = []
   const outcome = await (async (): Promise<RunResult> => {
     // Seed the workspace if the scenario ships one (a file the agent reads/edits).
-    // Copied into the temp cwd so the agent's bash tools see it; the expected outputs
+    // Copied into the generated cwd so the agent's bash tools see it; the expected outputs
     // normalize the cwd, so the seeded paths stay stable across runs.
     if (opts.workspaceDir !== undefined && existsSync(opts.workspaceDir)) {
       await cp(opts.workspaceDir, cwd, { recursive: true })
@@ -298,7 +306,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
     // persistence) and exits. Then await exit so the harvested log is complete.
     await active.close()
     // Harvest EVERY persisted log (parent + any subagent children) while the
-    // temp dirs still exist, ordered primary-first.
+    // generated dirs still exist, ordered primary-first.
     sessionLogs = await harvestSessionLogs(sessionsRoot)
     return {
       rawStdout: launched.rawStdout(),

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

@@ -1,5 +1,5 @@
 /**
- * Pure ACP transcript and session-log normalizers. They scrub session ids, temp cwd, RPC ids,
+ * Pure ACP transcript and session-log normalizers. They scrub session ids, run cwd, RPC ids,
  * timestamps, and hook duration while preserving deterministic event sequence numbers.
  * Request-header scrubbers stay composable so one scenario per header class can pin prompt and
  * tool-schema sidecars while retaining any model-visible prefix in the session log.
@@ -44,7 +44,7 @@ function canonicalizeEmbeddedPaths(value: string): string {
 export interface NormalizeContext {
   /** The session id(s) the run issued — replaced with `{{sessionId}}`. */
   sessionIds: string[]
-  /** The temp cwd the run used — replaced with `{{cwd}}`. */
+  /** The generated cwd the run used — replaced with `{{cwd}}`. */
   cwd: string
 }
 

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

@@ -104,6 +104,12 @@ export interface Scenario {
    * {@link headerClass}.
    */
   configPath?: string
+  /**
+   * Parent directory for the generated session cwd. Defaults to the platform
+   * temp directory; set this when temp is itself part of the behavior under
+   * test and the scenario needs an independent project location.
+   */
+  workspaceParent?: string
   /**
    * Whether Windows additionally compares stdout with native separators against
    * `stdout.expected.windows.jsonl`. The shared canonical stdout expected output is still
@@ -237,7 +243,7 @@ export function fixtureContext(fixture: string): NormalizeContext {
  * The `data.header` payload of every `request/header` event in a session
  * JSONL, in log order, with the log's volatile values scrubbed first
  * ({@link normalizeSessionLog}) so headers harvested from different runs —
- * each embedding its own temp cwd in the composed prompt — compare on equal
+ * each embedding its own generated cwd in the composed prompt — compare on equal
  * footing.
  *
  * @param rawLog The session `.jsonl` content to extract headers from.
@@ -561,6 +567,7 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
           // replays from its own script. In RECORD they are harvested, not read.
           ...!RECORDING && childFixtureFiles.length > 0 ? { childFiles: childFixtureFiles.map(file => join(dir, file)) } : {},
           ...existsSync(workspaceDir) ? { workspaceDir } : {},
+          ...scenario.workspaceParent !== undefined ? { workspaceParent: scenario.workspaceParent } : {},
           // A scenario booting an overlay tree passes its own live config; the
           // bin's replay swap derives the sibling `*cordis.snapshot.yml` from it.
           ...scenario.configPath !== undefined ? { configPath: scenario.configPath } : {},

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

@@ -1,7 +1,7 @@
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { once } from 'node:events'
 import { tmpdir } from 'node:os'
-import { delimiter, join } from 'node:path'
+import { delimiter, join, relative, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it, vi } from 'vitest'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
@@ -466,6 +466,22 @@ describe('runScenario', () => {
     expect(result.rawStdout).toContain('workspace:seeded.txt')
   })
 
+  it('creates the generated workspace under an explicit parent', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({})
+    const workspaceParent = await mkdtemp(join(tmpdir(), 'acp-snap-parent-'))
+    tempDirs.push(workspaceParent)
+
+    const result = await runScenario(
+      { steps: boot },
+      { agent: AGENT, mode: 'replay', fixtureFile, workspaceParent },
+    )
+
+    const child = relative(workspaceParent, result.cwd)
+    expect(child).not.toBe('')
+    expect(child).not.toBe('..')
+    expect(child.startsWith(`..${sep}`)).toBe(false)
+  })
+
   it('promptAndCancel waits for the streamed chunk, cancels, and settles the prompt', { timeout: 20_000 }, async () => {
     const { fixtureFile } = await scenario({ prompt: 'hang-until-cancel' })
     const result = await runScenario(

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

@@ -48,7 +48,14 @@ const RECORD_SRC = fileURLToPath(new URL('./fixtures/record-suite', import.meta.
 // Replay pins explicit header classes; recording covers the default fallback.
 const REPLAY_SCENARIOS: Scenario[] = [
   { name: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderChanges: 1, headerClass: 'main' },
-  { name: 'plain-turn', hasModelTurn: true, recorded: true, headerClass: 'main', configPath: AGENT.configPath },
+  {
+    name: 'plain-turn',
+    hasModelTurn: true,
+    recorded: true,
+    headerClass: 'main',
+    configPath: AGENT.configPath,
+    workspaceParent: tmpdir(),
+  },
   { name: 'no-model', hasModelTurn: false, recorded: false, headerClass: 'main' },
   { name: 'blocked-log', hasModelTurn: false, comparesLog: true, recorded: false, headerClass: 'main' },
   { name: 'authored-error', hasModelTurn: true, recorded: false, overridden: true, headerClass: 'main' },

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/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/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 and unknown commands produce a warning, with no automatic fallthrough to 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`, `/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
@@ -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>