Merge remote-tracking branch 'origin/master' into cross-family-fs-sandbox

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/events.md
#	docs/cordis-catalog/services.md
#	docs/event-producer-consumer.md
#	docs/persistence-catalog.md
#	examples/acp-agent/cordis.yml
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
#	examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
#	examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
#	examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
#	examples/acp-agent/tests/snapshots/skill-load/session.jsonl
#	examples/acp-agent/tests/snapshots/text-turn/session.jsonl
#	packages/bash/bash-sandbox/src/index.ts
#	packages/bash/bash/src/types.ts
#	packages/bash/tool-bash/src/index.ts
#	packages/fs/fs/src/index.ts
#	packages/sandbox/sandbox-policy/src/session-mode.ts
#	packages/ui/permission/src/index.ts
#	packages/ui/permission/tests/permission.spec.ts
#	scripts/doc-budgets.manifest.json

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

@@ -1,43 +1,9 @@
 /**
- * `SandboxBashExecutor`: the sandbox-consuming implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Every spawned command is wrapped by
- * the `ctx.sandbox` provider (`@deepseek-ai/dsh-sandbox`) according to the
- * configured {@link SandboxMode}: the executor hands the provider the exact
- * `['bash', '-c', command]` argv it is about to spawn and spawns the wrapped
- * argv instead. WHICH platform runner confines it — and whether one is
- * usable at all (the provider fails CLOSED with a structured
- * `SANDBOX_UNAVAILABLE` error rather than passing the argv through) — is the
- * provider's concern (`@deepseek-ai/dsh-sandbox-local` first).
- *
- * Extends `LocalBashExecutor` so all process mechanics — spawn, process-group
- * kills, timeout escalation, output collection and spill files, background
- * tasks, the credential scrub — are the local implementation's, verbatim.
- * This package adds only the seam consumption and the result facts, which is
- * exactly the split the capability seam was designed for (a sandboxing
- * executor replaces `dsh-bash-local` without touching `dsh-tool-bash`, and
- * swapping the confinement backend never touches this package).
- *
- * A failed run whose stderr carries the selected backend's own denial
- * dialect (the signatures the provider stamps on every wrap) is classified
- * as a sandbox denial on `BashRunResult.sandbox`, and every confined result
- * also carries how completely the selected runner enforces the mode
- * (`sandbox.enforcement`, from the provider's wrap). A failure carrying the
- * backend's RUNNER-FAILURE signature instead means the sandbox itself broke
- * and the command never ran: the foreground path re-throws it as the
- * structured fail-closed `SANDBOX_UNAVAILABLE` error (late twin of the
- * provider's confine-time throw), a settled background task stamps
- * `sandbox.runnerFailed` — either way a broken sandbox can never read as a
- * failing command, and the command never slips through unconfined.
- *
- * Deny-only at the seam, escalation at the tool: a denial is a reported FACT
- * here, and the one-shot user-approved escalated retry of a denied action
- * (docs/rfc/implemented/feature/2026-07-06-sandbox.md) is driven by
- * `dsh-tool-bash` through `ctx.approval` — this executor's contribution is the
- * per-call `sandboxMode` override it honors in {@link resolve}: an escalated
- * call runs (and classifies, and reports) under ITS granted mode while every
- * neighboring call keeps its session's standing mode (or the configured
- * default when that session has no override).
- *
+ * Sandbox-consuming bash executor. It wraps the exact local bash argv through
+ * `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
+ * tasks carry `runnerFailed`. The tool owns approval and passes per-call modes.
  * @module @deepseek-ai/dsh-bash-sandbox
  */
 
@@ -71,24 +37,11 @@ export function shellQuote(text: string): string {
 }
 
 /**
- * Conservative sandbox-denial classifier: a run counts as denied only when it
- * FAILED (nonzero exit — a signal kill is not a denial) and its stderr
- * carries one of the SELECTED BACKEND's own denial signatures — the dialect
- * the provider stamps on every wrap (`ConfinedArgv.denialSignatures`:
- * `Read-only file system` under bwrap's EROFS mounts, `Permission denied`
- * under Landlock's EACCES, `Operation not permitted` under Seatbelt's
- * EPERM). Matching the backend's dialect rather than a cross-backend union
- * keeps the classifier from claiming denials the active backend never
- * produces (bare EPERM text under a Linux runner names non-file boundaries —
- * mount, kill, ptrace — that fail the same way unsandboxed). Text inference
- * is the fallback signal until a runner provides a structured one (which
- * wins once it exists); it errs toward NOT claiming a denial, and its known
- * residual imprecision is non-sandbox text in the active dialect (an ssh
- * auth failure reads as a denial under Landlock, a refused `kill` under
- * Seatbelt).
+ * Conservatively classify a nonzero, non-signal run using only the selected
+ * backend's denial signatures. Text inference may miss a denial or match
+ * unrelated stderr in that dialect; it never uses another backend's terms.
  * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's denial dialect, case-insensitive
- *   stderr substrings.
+ * @param signatures - the active wrap's denial dialect, case-insensitive stderr substrings.
  * @returns whether the run's failure reads as a sandbox denial.
  */
 export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
@@ -96,17 +49,9 @@ export function classifyDenial(result: BashRunResult, signatures: readonly strin
 }
 
 /**
- * Runner-failure classifier: a failed run whose stderr carries the SELECTED
- * BACKEND's own runner-failure signature (`ConfinedArgv.
- * runnerFailureSignatures`: the runner's error prefix, which also matches
- * the shell's runner-not-found message) means the SANDBOX itself failed and
- * the command never ran. Checked BEFORE {@link classifyDenial} — a runner's
- * error text can contain denial words (an unopenable grant root reports
- * `Permission denied`) — and surfaced as the fail-closed
- * `SANDBOX_UNAVAILABLE` error on the foreground path, `sandbox.runnerFailed`
- * on a settled background task. Same conservative-text-inference stance and
- * residual imprecision as the denial classifier (a failing task that itself
- * prints the runner's prefix reads as a runner failure).
+ * Classify a nonzero run using the selected backend's runner-failure
+ * signatures. Callers check this before denial because runner diagnostics may
+ * contain denial words; the command did not run.
  * @param result - the settled foreground run to classify.
  * @param signatures - the active wrap's runner-failure signatures,
  *   case-insensitive stderr substrings.
@@ -129,15 +74,13 @@ function matchesSignature(exitCode: number | null, stderr: string, signatures: r
 }
 
 /**
- * Sandbox-consuming bash executor. Registers as `ctx.bash` (loading it
- * INSTEAD OF `dsh-bash-local`, together with a `ctx.sandbox` provider, is
- * the whole swap — the tool layer is untouched). Its configured mode is the
- * fallback exposed by {@link sandboxMode}; `dsh-tool-bash` folds a session's
- * durable `sandbox/mode` override and stamps the effective mode onto each
- * request, while an approved escalation may stamp a strictly wider mode for
- * one call. The tool's per-agent prompt section states that same effective
- * mode, and each run's `result.sandbox` reports what actually executed plus
- * enforcement completeness.
+ * 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, from
+ * `ctx.sandboxPolicy`) 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.
  */
 export class SandboxBashExecutor extends LocalBashExecutor {
   static inject = ['sandbox', 'sandboxPolicy']
@@ -149,15 +92,9 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   private readonly mode: SandboxMode
   private readonly workspaceRoot: string
   /**
-   * Per-task facts, keyed by task id from `start()` until the settle stamp
-   * consumes them: the mode the task runs under (per-call — an escalated task
-   * differs from its neighbors) plus its wrap facts. The seam returns facts
-   * PER WRAP — a provider may legally vary enforcement or dialect between
-   * calls — so overlapping background tasks must each classify against their
-   * OWN wrap; a single latest-wrap field would let a later `start()` clobber
-   * an earlier task's facts before it settles. A `danger-full-access` task
-   * has NO entry (nothing confined it), which is what the settle stamp keys
-   * off.
+   * Per-task mode and wrap facts retained until settlement. Overlapping tasks
+   * may use different modes or provider facts, so one latest-wrap field would
+   * misclassify earlier completions.
    */
   private readonly taskFacts = new Map<BashTaskId, {
     mode: ConfinedSandboxMode
@@ -200,11 +137,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     }
     const confined = this.confine(spec.command, mode)
     const result = await super.run({ ...spec, command: confined.command })
-    // Runner failure outranks denial: the sandbox itself failed and the
-    // command NEVER RAN — surface the same structured fail-closed error a
-    // confine-time discovery throws (late detection, same outcome), with
-    // the runner's own first stderr line as the cause. Returning it as a
-    // task result would let a broken sandbox read as a failing 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.
     if (classifyRunnerFailure(result, confined.runnerFailureSignatures)) {
       throw new SandboxUnavailableError(mode, result.stderr.text.trim().split('\n')[0])
     }
@@ -215,11 +149,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     // Same stamped-by-resolve invariant as run().
     const mode = spec.sandboxMode as SandboxMode
     if (mode === 'danger-full-access') return super.start(spec)
-    // Sandbox facts are stamped at settle time by {@link notifyTaskDone}
-    // (denial classification runs against the settled task's collected
-    // stderr). The map entry lands synchronously after spawn, strictly
-    // before the earliest possible settle (a process exit reaches us no
-    // sooner than the next tick).
+    // Classification needs settled stderr. Store facts synchronously after
+    // spawn, before the earliest process completion can be observed.
     const confined = this.confine(spec.command, mode)
     const task = super.start({ ...spec, command: confined.command })
     const { enforcement, denialSignatures, runnerFailureSignatures } = confined
@@ -228,27 +159,16 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   }
 
   /**
-   * Stamp the sandbox facts BEFORE completion listeners run: the base
-   * executor notifies from inside the task's settle path, so overriding the
-   * notification point is what makes `task.sandbox` visible to `onTaskDone`
-   * consumers and `done` awaiters alike. Each task classifies against the
-   * facts of ITS OWN wrap and reports ITS OWN mode (consumed from the
-   * per-task map here — settle is the entry's end of life): with per-call
-   * escalation, tasks under different modes settle side by side, so keying
-   * anything off the configured default would misreport them. A
-   * `danger-full-access` task has no map entry and carries no facts (nothing
-   * confined it); a signal-killed task (null exit code) is never a denial,
-   * mirroring the foreground classifier.
+   * Stamp per-task sandbox facts before completion listeners and `done` settle.
+   * Full-access tasks have no facts; signal deaths are not denials.
    */
   protected override notifyTaskDone(task: BashTask): void {
     const facts = this.taskFacts.get(task.id)
     if (facts !== undefined) {
       this.taskFacts.delete(task.id)
       const stderr = this.collectedStderr(task.id)
-      // Runner failure outranks denial (the command never ran; the runner's
-      // own error text can contain denial words). A settled task has no
-      // error channel left, so the fact IS the surface here — the foreground
-      // path throws instead.
+      // Runner failure outranks denial. Background settlement has no throw
+      // channel, so this fact is its counterpart to the foreground exception.
       const runnerFailed = matchesSignature(task.exitCode, stderr, facts.runnerFailureSignatures)
       task.sandbox = {
         mode: facts.mode,