docs: trim generated prose

packages/sandbox/sandbox/src/index.ts

@@ -1,24 +1,7 @@
 /**
- * The process-sandbox seam (`ctx.sandbox`): an abstract service defining WHAT
- * platform confinement does — wrap a subprocess argv so it executes under a
- * file-effect policy — without saying HOW. Implementations subclass
- * {@link SandboxProvider} and register as the `sandbox` service;
- * `@deepseek-ai/dsh-sandbox-local` (per-platform chains: Linux `bwrap` then the
- * npm-distributed `landlock-run` launcher, macOS `sandbox-exec`/Seatbelt) is
- * the first.
- * Consumers hand over the exact argv they are about to spawn
- * (`@deepseek-ai/dsh-bash-sandbox` wraps `['bash', '-c', command]`; a
- * subagent backend wraps its child-agent argv) and spawn the returned argv
- * instead.
- *
- * The seam confines SAME-WORLD subprocesses only: a backend shares the
- * host's filesystem and kernel, and the policy's `workspaceRoot` names a
- * real host path. Containers, microVMs, and remote executors are NOT
- * backends of this seam — they are sibling implementations of whole
- * capability seams (`ctx.bash`, `ctx.fs`), deployed as environment-coherent
- * groups; the boundary is recorded in
- * docs/rfc/implemented/feature/2026-07-06-sandbox.md.
- *
+ * The process-sandbox seam (`ctx.sandbox`): an abstract service defining what platform
+ * confinement does — wrap a subprocess argv so it executes under a file-effect policy —
+ * without saying how.
  * @module @deepseek-ai/dsh-sandbox
  */
 
@@ -27,24 +10,6 @@ import { HarnessError } from '@deepseek-ai/dsh-llm'
 
 /**
  * File-effect policy a sandbox backend enforces on confined processes.
- *
- * - `read-only` — the process cannot write the filesystem anywhere; a
- *   write-shaped `/dev/null` sink stays available so `>/dev/null` redirects
- *   keep working (HOW is the backend's choice: bwrap mounts a fresh `/dev`,
- *   the Landlock launcher and Seatbelt grant the single `/dev/null` node).
- * - `workspace-write` — writes are allowed only under the policy's
- *   workspace root and `/tmp`; everything else stays read-only. Which `/tmp`
- *   is backend-specific — an ephemeral mount under bwrap, the HOST `/tmp`
- *   under the Landlock launcher, the host `/private/tmp` plus the per-user
- *   darwin temp dir under Seatbelt: the seam promises the write boundary,
- *   not the mount's nature.
- * - `danger-full-access` — no confinement; a consumer configured with it
- *   spawns its argv unwrapped and never calls the provider.
- *
- * The mode governs FILE effects only: network and process visibility are not
- * restricted (a backend that cannot honestly enforce them must not pretend
- * to). How completely the file effects themselves are enforced is likewise a
- * reported fact, not an assumption — see {@link SandboxEnforcement}.
  */
 export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
 
@@ -52,18 +17,7 @@ export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
 export type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>
 
 /**
- * How completely the selected backend enforces a confined mode's file
- * effects.
- *
- * - `full` — every file effect the mode promises to block is governed: the
- *   `bwrap` mount profile, a Landlock kernel enforcing the launcher's whole
- *   ruleset, or an operator-configured runner (configuring one asserts full
- *   enforcement along with existence).
- * - `partial` — the backend is active but the kernel governs only the subset
- *   of accesses its ABI knows (an older Landlock ABI: path-based truncate is
- *   ungoverned before ABI v3), so a file effect the mode promises to block
- *   may still land. A caller that needs the mode's promise to be absolute
- *   must treat `partial` as outside that promise.
+ * How completely the selected backend enforces a confined mode's file effects.
  */
 export type SandboxEnforcement = 'full' | 'partial'
 
@@ -103,17 +57,10 @@ export interface ConfinedArgv {
    */
   denialSignatures: readonly string[]
   /**
-   * How the RUNNER ITSELF failing identifies itself: case-insensitive stderr
-   * substrings produced when the sandbox binary is missing, refuses its
-   * profile, or fails closed before exec'ing the command (`bwrap: `,
-   * `landlock-run: `, `sandbox-exec: ` — each covers both the runner's own
-   * error prefix and the shell's runner-not-found message). ORTHOGONAL to
-   * {@link denialSignatures}: a denial is the confined COMMAND being blocked
-   * (the sandbox working as designed); a runner failure means the command
-   * NEVER RAN and must surface as a sandbox failure, not a task failure —
-   * consumers check these signatures FIRST (a runner's own error text may
-   * contain denial words, e.g. an unopenable grant root reporting
-   * `Permission denied`).
+   * How the RUNNER ITSELF failing identifies itself: case-insensitive stderr substrings
+   * produced when the sandbox binary is missing, refuses its profile, or fails closed before
+   * exec'ing the command (`bwrap: `, `landlock-run: `, `sandbox-exec: ` — each covers both the
+   * runner's own error prefix and the shell's runner-not-found message).
    */
   runnerFailureSignatures: readonly string[]
 }
@@ -155,27 +102,9 @@ declare module 'cordis' {
 }
 
 /**
- * Abstract process-sandbox service. Subclass, implement {@link confine}, and
- * load the subclass as a plugin — it registers as `ctx.sandbox` (one
- * implementation per context; loading a second throws, cordis' standard
- * duplicate-service behavior).
- *
- * Semantics every implementation must honor:
- * - {@link confine} either returns an argv whose runner ENFORCES the policy
- *   or fails closed — at `confine` time with {@link SandboxUnavailableError}
- *   (no backend for this host), or at EXECUTION time by the runner itself
- *   refusing to run the command (exiting without exec'ing it, identified by
- *   {@link ConfinedArgv.runnerFailureSignatures}). A silent unconfined
- *   passthrough is never a legal outcome on either path.
- * - Probing exists to ARBITRATE between multiple candidate backends and may
- *   be skipped when a platform has exactly one: the sole candidate is
- *   selected directly and the runner's exec-time fail-closed refusal carries
- *   the safety property. When probing does run, it is functional (actually
- *   enforcing a profile, not a version check), at most once per provider
- *   lifetime; `confine` itself spawns nothing beyond that one-time probing.
- * - The returned {@link ConfinedArgv.enforcement} states the backend's
- *   actual completeness for THIS host; `partial` is reported, never silently
- *   upgraded to `full`.
+ * Abstract process-sandbox service. Subclass, implement {@link confine}, and load the subclass
+ * as a plugin — it registers as `ctx.sandbox` (one implementation per context; loading a
+ * second throws, cordis' standard duplicate-service behavior).
  */
 export abstract class SandboxProvider extends Service {
   constructor(ctx: Context) {