dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/subsystems/ptc-runtime.zh.md

@@ -1,250 +0,0 @@
-# PTC 运行时
-
-[English](ptc-runtime.md) | 中文
-
-PTC 执行[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)通过 [dsh-ptc-runtime](../../packages/ptc-runtime/ptc-runtime) 提供 `ctx.ptcRuntime`。它针对 Host 绑定运行一个程序，报告输出、失败与适用的沙箱事实。PTC 执行是可选能力，不属于[智能体循环主干](core.zh.md)。[PTC 基础](../../.agents/notes/implemented/feature/2026-06-15-ptc.zh.md)负责注册表呈现，[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-ptc-typed-tool-returns.zh.md)负责绑定值，[沙箱 Node 决策](../../.agents/notes/implemented/architecture/2026-09-11-sandboxed-node-ptc-runtime.zh.md)负责已发布的执行提供方。
-
-源码：[`packages/ptc-runtime/ptc-runtime/src/types.ts`](../../packages/ptc-runtime/ptc-runtime/src/types.ts)
-
-## 运行：请求进，结果出
-
-`PtcRunRequest` 包含程序、绑定、取消和可选执行选择。提供方的 `resolve` 验证支持的选择并应用部署默认值；`run` 接收目录与截止选择明确的 `PtcRunSpec`。省略 timeout 使用提供方默认值，数值请求封顶的经过时间预算，`null` 请求不设经过时间截止。提供方在执行前拒绝不支持的选择：
-
-```ts type-equiv
-/**
- * Caller inputs for one program. The provider's resolve method validates supported
- * options and supplies directory, deadline, and authority before execution.
- */
-interface PtcRunRequest {
-  /**
-   * The program source, in the runtime's {@link ../index.ts | language}. It
-   * follows the provider's programFormat: an async function body supports
-   * top-level `await` and `return`; a REPL supports top-level declarations,
-   * `await`, and a final expression. The completion value becomes
-   * {@link PtcRunResult.value}.
-   */
-  program: string
-  /**
-   * Object-identity owner for optional in-memory state. Omission requests a fresh
-   * environment. Consumers must await runtime.release(owner) when the owner ends.
-   * Stateless providers ignore this field; retained state is never durable.
-   */
-  stateOwner?: object
-  /** Host functions exposed to the program, one global object per namespace. */
-  bindings: PtcBindingNamespace[]
-  /** Working directory in the mounted filesystem and subprocess execution world. */
-  cwd?: string
-  /**
-   * Elapsed execution budget in milliseconds. Omission uses provider defaults;
-   * null requests no deadline. Providers validate and cap numeric budgets or reject unsupported choices.
-   */
-  timeoutMs?: number | null
-  /** Resolved authority for this execution. Providers without confinement reject an explicit policy. */
-  sandboxPolicy?: SandboxExecutionPolicy
-  /**
-   * Abort the run: the runtime stops the program (hard, even mid-loop) and
-   * resolves with a {@link PtcRunFailure} of kind `'abort'`. In-flight
-   * binding calls are the CALLER's to settle — the runtime only stops asking.
-   */
-  signal?: AbortSignal
-}
-```
-
-```ts type-equiv
-/** Fully resolved execution inputs; run never supplies a missing directory or deadline choice. */
-interface PtcRunSpec extends PtcRunRequest {
-  /** Absolute directory in the provider's execution world. */
-  cwd: string
-  /** Positive finite elapsed budget in milliseconds after provider capping, or null for no deadline. */
-  timeoutMs: number | null
-}
-```
-
-```ts type-equiv
-/** File confinement applied to a program, independently of its terminal outcome. */
-interface PtcRunSandbox {
-  /** File-effect mode used for this execution. */
-  mode: SandboxMode
-  /** Program failure text matched backend diagnostics; not enforcement proof or an exhaustive denial record. */
-  denied: boolean
-  /** Completeness reported by the selected confining backend; absent for full access. */
-  enforcement?: SandboxEnforcement
-}
-```
-
-程序失败通过 `PtcRunResult.error` 返回；无效调用输入可能在执行前拒绝。沙箱模式、观察到的拒绝与强制完整性是独立事实，因此程序成功本身不能证明每项请求限制均已强制执行：
-
-```ts type-equiv
-/**
- * The outcome of one run. An error is a FIELD on a resolved result, never a
- * rejection of `run()` — reporting a failed program is the caller's job, not
- * an exception path.
- */
-interface PtcRunResult {
-  /** Applied file policy and observed denial, when the provider enforces file policy. */
-  sandbox?: PtcRunSandbox
-  /**
-   * The program's completion value (a return or final REPL expression), when it ran to
-   * completion and the value crossed the runtime's lossless-JSON boundary.
-   * Invalid or over-limit completions fail the run instead of substituting a
-   * rendered string; a failed or value-less run leaves this absent.
-   */
-  value?: PtcJsonValue
-  /**
-   * Captured text. Each source channel preserves emission order; interleaving
-   * across independent channels is backend-dependent. Bounded only as part of
-   * the outer result.
-   */
-  logs: string[]
-  /** Present iff the run failed; see {@link PtcRunFailure} for the taxonomy. */
-  error?: PtcRunFailure
-}
-```
-
-`programFormat` 区分异步函数体与 REPL 语句。`stateOwner` 是标识可选保留内存的进程内对象身份；不同对象相互隔离。消费者在所有者结束时等待 `release(owner)`；清理失败时该调用拒绝。省略所有者时仅执行一次，无状态提供方忽略所有权。[持久 Node 提供方](../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#persistent-repl)定义重置和恢复行为；保留对象不会进入持久 Session 格式。
-
-## 绑定：宿主函数作为程序全局变量
-
-每个 `PtcBindingNamespace` 成为一个异步可调用函数的全局对象；PTC 传入 `tools`。参数与返回值必须是无损 JSON。提供方强制各自的传输上限；seam 不设统一的绑定字节上限。可选错误类描述符创建程序可见的类型化拒绝，无需在运行时内点名消费方。绑定名是自有属性，因此 `__proto__` 不能遍历原型：
-
-```ts type-equiv
-/**
- * Program-visible typed rejection for one binding namespace. The runtime
- * injects a real error constructor under `name`; rejected member calls become
- * its instances and expose the exact member name through
- * `memberNameProperty`. Both strings are runtime data rather than knowledge
- * of a particular consumer such as PTC mode.
- */
-interface PtcBindingErrorClass {
-  /** Constructor global and resulting `Error.name`; same portable identifier rule as {@link PtcBindingNamespace.global}. */
-  name: string
-  /**
-   * Non-empty own property for the member name. The portable exclusion set is
-   * `RESERVED_ERROR_MEMBERS` plus dunder-form names (`__x__`, non-empty
-   * middle), enforced identically by every backend; any other name —
-   * identifiers or not — is accepted everywhere.
-   */
-  memberNameProperty: string
-}
-```
-
-```ts type-equiv
-/**
- * A named group of {@link PtcBindingFunction}s the runtime exposes to the
- * program as one global object (e.g. `tools`). Function names are arbitrary
- * strings — a runtime must treat names like `__proto__` or `constructor` as
- * ordinary own properties (null-prototype construction), never as prototype
- * collisions.
- */
-interface PtcBindingNamespace {
-  /**
-   * The global identifier the program sees. Must match the LANGUAGE-PORTABLE
-   * identifier subset `[A-Za-z_][A-Za-z0-9_]*` and no language's reserved
-   * words, so the same namespace list works against every backend regardless
-   * of `language` — a JS-only spelling like `$tools` is rejected by design,
-   * not just by the Python backend. Names that satisfy the identifier rule but
-   * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`,
-   * `__dsh_main__`) are also refused everywhere; see its declaration for the
-   * exact set and why each entry is reserved.
-   */
-  global: string
-  /** The callable members, keyed by the exact name the program calls. */
-  functions: Record<string, PtcBindingFunction>
-  /** Optional program-visible typed rejection contract for this namespace. */
-  errorClass?: PtcBindingErrorClass
-}
-```
-
-```ts type-equiv
-/** A lossless JSON value transferable through the dependency-light Service Definition. */
-type PtcJsonValue = null | boolean | number | string | PtcJsonValue[] | { [key: string]: PtcJsonValue }
-```
-
-```ts type-equiv
-/**
- * One host-side function exposed to the program as an async callable. The
- * runtime bridges calls to it (possibly across a serialization boundary), so
- * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
- * lossy or non-cloneable value with a descriptive error rather than corrupting
- * the run. No seam-level byte cap applies to a binding resolution. A rejection
- * of this function surfaces inside the program as a rejection of the
- * corresponding call.
- */
-type PtcBindingFunction = (args: unknown) => Promise<PtcJsonValue>
-```
-
-## 捕获的输出与失败分类体系
-
-日志是纯字符串。每个来源通道保留自身的发出顺序；由于通道元数据不属于 seam，相互独立的通道如何交错由后端决定。运行时捕获程序的 console 与流输出，Consumer 只渲染文本。实现会对序列化后的外层日志数组，以及完成值或失败消息的组合载荷设置上限；固定的结果封装语法与 Consumer 展示空白不计入这份可变载荷计量。超限会显式失败，而不会在值中插入替代内容。
-
-失败类型是**正交的结果，独立报告**（见 [defensive-patterns](../defensive-patterns/general.zh.md)）：预算耗尽不是异常，中止不是超时，基底崩溃（如 OOM）也不是二者中的任何一个：
-
-```ts type-equiv
-/**
- * Why a run failed. The kinds are orthogonal outcomes reported independently
- * (per docs/defensive-patterns/general.md): a budget expiry is not an exception, an
- * abort is not a timeout, and a substrate death is neither.
- *
- * - `'exception'` — the program threw or failed to parse/transform.
- * - `'timeout'` — an implementation-owned budget expired; the message says which.
- * - `'abort'` — {@link PtcRunRequest.signal} fired.
- * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
- * - `'invalid-output'` — the completion value was not lossless JSON.
- * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
- * - `'protocol'` — the program sent invalid or over-budget control traffic.
- * - `'sandbox-unavailable'` — required confinement could not be established.
- */
-interface PtcRunFailure {
-  /** The failure class (see the interface doc for each kind's meaning). */
-  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit' | 'protocol' | 'sandbox-unavailable'
-  /** Human-readable detail, suitable for feeding back to a model to self-correct. */
-  message: string
-}
-```
-
-## 服务
-
-`PtcRuntime` 定义于 [`src/index.ts`](../../packages/ptc-runtime/ptc-runtime/src/index.ts)。`resolve(request)` 返回完整执行输入，`run(spec)` 执行它们。`executionInstructions` 提供由运行时拥有的使用说明，供消费方呈现。支持逐次覆盖时，`timeout` 报告配置的经过时间默认值和上限；每次请求仍由 `resolve` 验证并截断。`language` 选择支持的程序呈现；`isolation` 描述执行基底，不作安全声明。`sandboxMode` 声明文件策略支持，不提供约束的提供方返回 `undefined`。每个实现将各次运行的程序状态分离，并在资源释放期间终止且等待活跃执行。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxptcruntime--ptcruntime-abstract-seam"></a>
-
-### `ctx.ptcRuntime` — `PtcRuntime` (abstract seam)
-
-Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate failures resolve in PtcRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate distinct state owners, and terminate and await in-flight runs during disposal.
-
-```ts cordis-catalog
-/**
- * Release an owner's retained environment and await its execution resources.
- * Stateless providers have no retained resources to release.
- * @param owner - The exact object supplied as the request's state owner.
- * @returns Completion after all owned execution resources have been released.
- * @throws When managed resource cleanup fails.
- */
-release(owner: object): Promise<void>
-
-/**
- * Resolve supported options and provider defaults before execution.
- * @param request - Program, bindings, cancellation and optional execution choices.
- * @returns Complete directory, deadline and supported authority for run.
- * @throws When an explicit choice is invalid or unsupported by this provider.
- */
-abstract resolve(request: PtcRunRequest): PtcRunSpec
-
-/**
- * Execute resolved inputs; program outcomes resolve as result fields.
- * @param spec - directory, deadline, program, bindings, cancellation and supported policy.
- * @returns Captured output and the execution outcome.
- */
-abstract run(spec: PtcRunSpec): Promise<PtcRunResult>
-```
-
-Source: [`packages/ptc-runtime/ptc-runtime/src/index.ts`](../../packages/ptc-runtime/ptc-runtime/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/sandbox.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for sandbox.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/sandbox.md
-/process-sandbox:
-  en: e0d4876306b192c3
-  zh: 63baaa0c79e87deb
-/process-sandbox/modes-and-enforcement:
-  en: 11f91b55cc317334
-  zh: 296678c4675864c1
-/process-sandbox/per-call-policy:
-  en: 7661eb4559bbc395
-  zh: 0dceeb0bba367862
-/process-sandbox/wrapped-argv-and-classification-dialects:
-  en: 2ba8930762e92e40
-  zh: 220f64da1a9e5d57
-/process-sandbox/provider-and-fail-closed-errors:
-  en: a90a38fe4b11737c
-  zh: 2397768e48712617

package/references/official-docs/docs/subsystems/sandbox.md

@@ -1,221 +0,0 @@
-# Process Sandbox
-
-English | [中文](sandbox.zh.md)
-
-The process-sandbox seam of [dsh-sandbox](../../packages/sandbox/sandbox) wraps a same-world subprocess argv in a file-effect policy without coupling consumers to a platform runner. [dsh-sandbox-local](../../packages/sandbox/sandbox-local) supplies Linux bwrap/Landlock, macOS Seatbelt, and the Windows ACL restricted-token backend; [dsh-bash-sandbox](../../packages/shell/bash-sandbox) and [dsh-pwsh-sandbox](../../packages/shell/pwsh-sandbox) consume it. [dsh-sandbox-ssh](../../packages/ssh/sandbox-ssh/README.md) applies the same policy through a remote backend paired with the SSH filesystem and subprocess providers.
-
-Source: [`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox/src/index.ts)
-
-## Modes and enforcement
-
-`SandboxMode` governs filesystem effects only. `read-only` asks the backend to deny writes — the POSIX runners additionally grant the `/dev/null` sink their shells require, while the Windows ACL runner grants no explicit writable root and reports partial enforcement for its ambient ACL gaps; `workspace-write` permits writes under the workspace root and the backend's promised temp area; `danger-full-access` bypasses confinement. Network and process visibility are outside this vocabulary.
-
-```ts type-equiv
-/**
- * File-effect policy for confined processes. `read-only` permits only required
- * sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
- * backend-defined temp area; `danger-full-access` bypasses confinement. Network
- * and process visibility are outside this vocabulary.
- */
-type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
-```
-
-Only the first two modes can be sent to a provider. A `danger-full-access` consumer spawns its original argv and does not call `ctx.sandbox`.
-
-```ts type-equiv
-/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
-type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>
-```
-
-Enforcement is a reported fact. `full` means the backend governs every file effect promised by the mode; `partial` means an active backend or older kernel ABI governs only a subset, so consumers that require the absolute promise must reject or surface that distinction. Older Landlock ABIs and the Windows ACL runner's hard-link, unconfined-read, and AppContainer-ACL boundaries are current partial cases.
-
-```ts type-equiv
-/**
- * Enforcement completeness for this host. `partial` means an active backend or
- * older kernel ABI cannot govern every promised file effect; callers requiring
- * an absolute boundary must not treat it as `full`.
- */
-type SandboxEnforcement = 'full' | 'partial'
-```
-
-## Per-call policy
-
-The complete execution policy is resolved and carried per capability call. It includes `danger-full-access` so a consumer can resolve policy once before deciding whether to bypass confinement. Normal tool calls derive `workspaceRoot` from the calling session's immutable cwd; deployment configuration is the agentless fallback. The resolver preserves absolute execution-world spelling. Enforcing providers canonicalize the root where the files exist, so a cwd containing `symlink/..` identifies the directory where the paired subprocess provider actually runs.
-
-```ts type-equiv
-/**
- * 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.
- */
-interface SandboxExecutionPolicy {
-  /** The file-effect mode this execution runs under. */
-  mode: SandboxMode
-  /** Absolute root directory `workspace-write` may write under. */
-  workspaceRoot: string
-  /**
-   * Opaque identity of the calling session (the branded `dsh-session`
-   * SessionId). Backends key per-session state off it (e.g. windows-acl gives
-   * each live session/workspace pair a random private temp directory and SID,
-   * while the workspace SID and standing grant remain per-workspace); absent
-   * for agentless calls, which fall back to per-call backend state.
-   */
-  sessionId?: SessionId
-}
-```
-
-`ctx.sandboxPolicy.resolve()` accepts the active session and, for an approved retry, an explicit mode. The service owns precedence and root fallback so bash and fs do not repeat it.
-
-```ts type-equiv
-/** Inputs that select the sandbox policy for one capability call. */
-interface SandboxPolicyRequest {
-  /** Calling session; its immutable cwd becomes the workspace boundary. */
-  session?: Session
-  /** Explicit approved mode override, which outranks session policy. */
-  mode?: SandboxMode
-}
-```
-
-Only a confined execution reaches `ctx.sandbox`; its provider policy narrows the mode while retaining the same root. This permits concurrent sessions, consumers, and one-shot escalated retries to ask the same provider for different boundaries without mutating provider state.
-
-```ts type-equiv
-/**
- * What one confined execution is allowed to touch — carried PER CALL, not
- * 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 an explicit step at
- * the consumer boundary; the provider treats the policy as fully specified.
- */
-interface SandboxPolicy extends SandboxExecutionPolicy {
-  /** The file-effect mode this execution runs under. */
-  mode: ConfinedSandboxMode
-}
-```
-
-<a id="wrapped-argv-and-classification-dialects"></a>
-
-## Wrapped argv and classification dialects
-
-`RunnerFailureRule` combines evidence that a runner failed before executing the command. A consumer requires a nonzero exit, the optional allowed-exit-code gate, and a case-insensitive fatal signature within one remaining stderr line. Case-insensitive exact full-line informational exclusions are removed first, so a benign runner notice cannot prove failure by itself. The matched line remains available as error detail; classification does not rewrite stderr.
-
-```ts type-equiv
-/**
- * Evidence that identifies a sandbox runner failing before it executes the
- * wrapped command. A consumer first applies {@link allowedExitCodes} when
- * present, removes {@link informationalLines} by case-insensitive exact line
- * equality, then matches {@link fatalSignatures} case-insensitively within
- * each remaining stderr line. Exit status alone never proves runner failure.
- */
-interface RunnerFailureRule {
-  /** Nonzero process exit codes on which this rule may match; omitted permits any nonzero exit. */
-  allowedExitCodes?: readonly number[]
-  /** Non-empty substrings identifying a fatal runner diagnostic on one stderr line. */
-  fatalSignatures: readonly string[]
-  /** Benign stderr lines excluded by exact full-line equality before fatal matching. */
-  informationalLines?: readonly string[]
-}
-```
-
-`ConfinedArgv` is what the consumer spawns. Besides the replacement argv, it carries the backend's enforcement fact and two orthogonal stderr classifiers. `denialSignatures` identify the confined command being blocked while the sandbox works correctly. `runnerFailureRules` identify the sandbox runner refusing or failing before it executes the command; consumers check these first and surface a sandbox infrastructure failure, never an ordinary task failure.
-
-```ts type-equiv
-/**
- * A {@link SandboxProvider.confine} result: the argv to spawn in place of
- * the caller's own, plus the enforcement completeness the selected backend
- * achieves for it.
- */
-interface ConfinedArgv {
-  /** The wrapped argv (runner, profile, separator, then the caller's argv). */
-  argv: string[]
-  /** How completely the selected backend enforces the policy's file effects. */
-  enforcement: SandboxEnforcement
-  /**
-   * The selected backend's denial DIALECT: the case-insensitive stderr
-   * substrings a file effect denied by THIS backend produces (EROFS text
-   * under bwrap's read-only binds, EACCES under Landlock, EPERM under
-   * Seatbelt). A consumer that infers denials from a failed run's stderr
-   * matches against exactly these rather than a cross-backend union — the
-   * union claims denials a given backend never produces.
-   */
-  denialSignatures: readonly string[]
-  /**
-   * Structured runner-failure evidence rules. Consumers require a matching
-   * fatal stderr line (after informational exclusions) and any rule-specific
-   * exit-code gate before checking denial signatures: runner failure means the
-   * command never ran, while denial means confinement worked and blocked it.
-   */
-  runnerFailureRules: readonly RunnerFailureRule[]
-}
-```
-
-The [local provider](../../packages/sandbox/sandbox-local/README.md) owns operator configuration and maps its runner dialect into these rules. The [sandboxed bash consumer](../../packages/shell/bash-sandbox/README.md) owns spawn and result attribution.
-
-## Provider and fail-closed errors
-
-`await ctx.sandbox.confine(argv, policy, signal)` resolves policy paths and returns a `ConfinedArgv` from the execution world, or rejects with `SandboxUnavailableError` and code `SANDBOX_UNAVAILABLE` when no usable backend exists. The optional signal cancels resolution before launch. Consumers may also classify a failure while spawning or observing the returned argv; that attribution belongs to the consumer contract. Silent unconfined passthrough is never legal for a confined policy.
-
-Provider selection, probing, caching, and backend-specific enforcement reports belong to the [local provider](../../packages/sandbox/sandbox-local/README.md).
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
-
-### `ctx.sandbox` — `SandboxProvider` (abstract seam)
-
-Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
-
-```ts cordis-catalog
-/**
- * Wrap `argv` so it executes confined under `policy` on this host; the
- * caller spawns the returned argv in place of its own.
- * @param argv - the exact argv the caller is about to spawn (program plus
- *   arguments), NOT a shell string — a shell-shaped consumer passes
- *   `['bash', '-c', command]`.
- * @param policy - the file-effect policy this execution runs under,
- *   carried per call (see {@link SandboxPolicy}).
- * @param signal - cancellation while the provider resolves the policy and runner.
- * @returns the argv to spawn instead, plus the enforcement completeness
- *   the selected backend achieves for it.
- */
-abstract confine(argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): Promise<ConfinedArgv>
-```
-
-Source: [`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox/src/index.ts)
-
-<a id="ctxsandboxpolicy--sandboxpolicyservice"></a>
-
-### `ctx.sandboxPolicy` — `SandboxPolicyService`
-
-The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
-
-```ts cordis-catalog
-/**
- * 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
-
-/**
- * Read the session override without applying the deployment default.
- * @param session - session whose log supplies the override.
- * @returns the last logged mode, or `undefined` without one.
- */
-overrideOf(session: Session): SandboxMode | undefined
-```
-
-Types: [Session](session.md)
-
-Source: [`packages/sandbox/sandbox-policy/src/index.ts`](../../packages/sandbox/sandbox-policy/src/index.ts)
-<!-- END GENERATED cordis-surface -->