dsh-plugin-guide 0.3.42 → 0.4.1

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

@@ -1,13 +0,0 @@
-# Bilingual-pair consistency record for settings.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/settings.md
-/plugin-configuration-forms:
-  en: 74ad41299fc3ad10
-  zh: 1c3f316e99e5ec8b
-/plugin-configuration-forms/identity-and-values:
-  en: 7fabd502b5dcbe5b
-  zh: 5d7bfbc57f823719
-/plugin-configuration-forms/edits:
-  en: 1d97c98a8634bfe7
-  zh: 70d6dbec0d9679c6

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

@@ -1,155 +0,0 @@
-# Plugin Configuration Forms
-
-English | [中文](settings.zh.md)
-
-The [settings service](../../packages/settings/settings/README.md) projects volatile Config fields from active profile entries. The [configuration editor](../../packages/boot/config-editor/README.md) persists edits through Cordis patches. Business consumers read `.get()` on their own Config references.
-
-## Identity and values
-
-A form namespace is the local id of a uniquely addressed entry in the active profile. Multiple plugin instances have separate forms when their entry ids differ. Ordinary fields are excluded. Descriptors carry resolved values, inherited values, explicit profile overrides, and an optimistic revision.
-
-## Edits
-
-`update` merges submitted fields. `replace` resets live fields to inherited configuration before applying submitted fields. `mutate` addresses individual paths, preserving secrets absent from a client response. Every write validates the complete Config and refuses stale revisions before persistence.
-
-`settings/document-updated` invalidates form descriptors after Loader configuration changes. It is a UI notification; consumers use `loader/volatile-update` only when they need to refresh registration facts.
-
-<!-- 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="ctxsettings--settingsforms"></a>
-
-### `ctx.settings` — `SettingsForms`
-
-Project Config schemas into forms and own optional instance-level UI policy.
-
-```ts cordis-catalog
-/** Register the calling plugin instance's page policy without changing its Config.
- * @param presentation Automatic-page policy for this instance; `auto` defaults to true.
- * @param owner Plugin instance the policy belongs to; defaults to the calling fiber.
- * @returns Disposer; register it with the calling plugin's effects.
- * @throws If this instance already has a registered policy.
- */
-configure(presentation: { auto?: boolean }, owner: Fiber = this.ctx.fiber): () => void
-
-/** Locate the profile patch for native editing.
- * @returns The existing profile patch path.
- */
-prepareDocument(): Promise<string>
-
-/** Read active plugin schemas and their live values.
- * @param options Redaction required for remote callers.
- * @returns Forms keyed by unique profile entry ids.
- */
-describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
-
-/** Merge editable fields into an entry's config.
- * @param ns Profile entry id.
- * @param patch Fields to merge.
- * @param expectedRevision Revision returned by describe.
- */
-async update(ns: string, patch: object, expectedRevision?: number): Promise<void>
-
-/** Reset all live fields, then set the supplied fields; ordinary config is preserved.
- * @param ns Profile entry id.
- * @param section Complete form values.
- * @param expectedRevision Revision returned by describe.
- */
-async replace(ns: string, section: object, expectedRevision?: number): Promise<void>
-
-/** Apply field edits without restating redacted secrets; unsetting an array index removes its element.
- * @param ns Profile entry id.
- * @param ops Ordered form edits.
- * @param expectedRevision Revision returned by describe.
- */
-async mutate(ns: string, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
-```
-
-Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
-
-<a id="ctxsettingscontroller--settingscontroller"></a>
-
-### `ctx.settingsController` — `SettingsController`
-
-Host service backing the generated `ctx.remote.settings` namespace. Every remote read uses `redactSecrets: true`, so a `role('secret')` field cannot ride a response. Writes expose the settings service's merge, replacement, and path-addressed operations, and classify every provider refusal as `settings/conflict` or `settings/rejected` with the service's message.
-
-```ts cordis-catalog
-/**
- * Describe every registered namespace for a configuration page: redacted
- * layered values plus the serialized schema the page renders its form from.
- * @returns provider writability, local-document presence, and one view per namespace.
- * @throws RemoteError when no settings provider is mounted.
- */
-@Remote describe(): SettingsDescribeValue
-
-/**
- * Merge a patch into one namespace's stored user section.
- * @param ns - namespace key to write.
- * @param patch - fields to merge into the user section.
- * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
- * @returns the namespace's redacted view after the write.
- * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
- */
-@Remote update( ns: string, patch: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
-
-/**
- * Replace one namespace's stored user section wholesale.
- * @param ns - namespace key to write.
- * @param section - complete replacement user section.
- * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
- * @returns the namespace's redacted view after the write.
- * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
- */
-@Remote replace( ns: string, section: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
-
-/**
- * Apply path-addressed edits to one namespace's user section, resolved against
- * the section as stored rather than against whatever the caller last read,
- * then answer with that namespace's new redacted view.
- * @param ns - namespace key to write.
- * @param ops - the edits to apply, in order.
- * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
- * @returns the namespace's redacted view after the write.
- * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
- */
-@Remote async mutate( ns: string, ops: SettingsPathOpView[], expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
-
-/**
- * Materialize the provider-owned settings document and open it in a native text editor.
- * @param signal - caller lifetime; abort terminates preparation or the native command.
- * @returns confirmation after the native opener accepts the document.
- * @throws RemoteError when no document exists, preparation fails, or opening fails.
- */
-@Remote async openSettingsDocument(signal: AbortSignal): Promise<SettingsDocumentOpenValue>
-```
-
-Source: [`packages/api/settings-controller/src/index.ts`](../../packages/api/settings-controller/src/index.ts)
-
-<a id="settings-events"></a>
-
-### `settings/*` events
-
-<a id="settingsdocument-updated--emit"></a>
-
-#### `settings/document-updated` — emit
-
-One profile entry's form values, availability, or page policy changed. Form clients re-read its schema, resolved values, and revision.
-
-```ts cordis-catalog
-/**
- * One profile entry's form values, availability, or page policy changed.
- * Form clients re-read its schema, resolved values, and revision.
- * @param ns Profile entry id.
- * @param revision The entry's new revision.
- * @mode emit
- */
-'settings/document-updated'(ns: SettingsNamespace, revision: number): void
-```
-
-Source: [`packages/settings/settings/src/types.ts`](../../packages/settings/settings/src/types.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/settings.zh.md

@@ -1,155 +0,0 @@
-# 插件配置表单
-
-[English](settings.md) | 中文
-
-[设置服务](../../packages/settings/settings/README.zh.md) 从活动 profile 条目投影 volatile Config 字段。[配置编辑器](../../packages/boot/config-editor/README.zh.md) 通过 Cordis patch 持久化编辑。业务消费者对自己的 Config 引用调用 `.get()`。
-
-## 标识与值
-
-表单命名空间是当前 profile 中可唯一定位条目的本地 id。多个插件实例在条目 id 不同时拥有独立表单。普通字段被排除。描述符包含实际值、继承值、显式 profile 覆盖值和乐观修订号。
-
-## 编辑
-
-`update` 合并提交的字段。`replace` 先将即时字段重置为继承配置，再应用提交的字段。`mutate` 操作独立路径，保留客户端响应中未包含的秘密值。每次写入都会验证完整 Config，并在持久化前拒绝过期修订号。
-
-`settings/document-updated` 在 Loader 配置变化后使表单描述符失效。这是 UI 通知；消费者仅在需要刷新注册信息时使用 `loader/volatile-update`。
-
-<!-- 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="ctxsettings--settingsforms"></a>
-
-### `ctx.settings` — `SettingsForms`
-
-Project Config schemas into forms and own optional instance-level UI policy.
-
-```ts cordis-catalog
-/** Register the calling plugin instance's page policy without changing its Config.
- * @param presentation Automatic-page policy for this instance; `auto` defaults to true.
- * @param owner Plugin instance the policy belongs to; defaults to the calling fiber.
- * @returns Disposer; register it with the calling plugin's effects.
- * @throws If this instance already has a registered policy.
- */
-configure(presentation: { auto?: boolean }, owner: Fiber = this.ctx.fiber): () => void
-
-/** Locate the profile patch for native editing.
- * @returns The existing profile patch path.
- */
-prepareDocument(): Promise<string>
-
-/** Read active plugin schemas and their live values.
- * @param options Redaction required for remote callers.
- * @returns Forms keyed by unique profile entry ids.
- */
-describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
-
-/** Merge editable fields into an entry's config.
- * @param ns Profile entry id.
- * @param patch Fields to merge.
- * @param expectedRevision Revision returned by describe.
- */
-async update(ns: string, patch: object, expectedRevision?: number): Promise<void>
-
-/** Reset all live fields, then set the supplied fields; ordinary config is preserved.
- * @param ns Profile entry id.
- * @param section Complete form values.
- * @param expectedRevision Revision returned by describe.
- */
-async replace(ns: string, section: object, expectedRevision?: number): Promise<void>
-
-/** Apply field edits without restating redacted secrets; unsetting an array index removes its element.
- * @param ns Profile entry id.
- * @param ops Ordered form edits.
- * @param expectedRevision Revision returned by describe.
- */
-async mutate(ns: string, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
-```
-
-Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
-
-<a id="ctxsettingscontroller--settingscontroller"></a>
-
-### `ctx.settingsController` — `SettingsController`
-
-Host service backing the generated `ctx.remote.settings` namespace. Every remote read uses `redactSecrets: true`, so a `role('secret')` field cannot ride a response. Writes expose the settings service's merge, replacement, and path-addressed operations, and classify every provider refusal as `settings/conflict` or `settings/rejected` with the service's message.
-
-```ts cordis-catalog
-/**
- * Describe every registered namespace for a configuration page: redacted
- * layered values plus the serialized schema the page renders its form from.
- * @returns provider writability, local-document presence, and one view per namespace.
- * @throws RemoteError when no settings provider is mounted.
- */
-@Remote describe(): SettingsDescribeValue
-
-/**
- * Merge a patch into one namespace's stored user section.
- * @param ns - namespace key to write.
- * @param patch - fields to merge into the user section.
- * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
- * @returns the namespace's redacted view after the write.
- * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
- */
-@Remote update( ns: string, patch: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
-
-/**
- * Replace one namespace's stored user section wholesale.
- * @param ns - namespace key to write.
- * @param section - complete replacement user section.
- * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
- * @returns the namespace's redacted view after the write.
- * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
- */
-@Remote replace( ns: string, section: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
-
-/**
- * Apply path-addressed edits to one namespace's user section, resolved against
- * the section as stored rather than against whatever the caller last read,
- * then answer with that namespace's new redacted view.
- * @param ns - namespace key to write.
- * @param ops - the edits to apply, in order.
- * @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
- * @returns the namespace's redacted view after the write.
- * @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
- */
-@Remote async mutate( ns: string, ops: SettingsPathOpView[], expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
-
-/**
- * Materialize the provider-owned settings document and open it in a native text editor.
- * @param signal - caller lifetime; abort terminates preparation or the native command.
- * @returns confirmation after the native opener accepts the document.
- * @throws RemoteError when no document exists, preparation fails, or opening fails.
- */
-@Remote async openSettingsDocument(signal: AbortSignal): Promise<SettingsDocumentOpenValue>
-```
-
-Source: [`packages/api/settings-controller/src/index.ts`](../../packages/api/settings-controller/src/index.ts)
-
-<a id="settings-events"></a>
-
-### `settings/*` events
-
-<a id="settingsdocument-updated--emit"></a>
-
-#### `settings/document-updated` — emit
-
-One profile entry's form values, availability, or page policy changed. Form clients re-read its schema, resolved values, and revision.
-
-```ts cordis-catalog
-/**
- * One profile entry's form values, availability, or page policy changed.
- * Form clients re-read its schema, resolved values, and revision.
- * @param ns Profile entry id.
- * @param revision The entry's new revision.
- * @mode emit
- */
-'settings/document-updated'(ns: SettingsNamespace, revision: number): void
-```
-
-Source: [`packages/settings/settings/src/types.ts`](../../packages/settings/settings/src/types.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,25 +0,0 @@
-# Bilingual-pair consistency record for shell.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/shell.md
-/shell-executor:
-  en: c9aba02120c42608
-  zh: f76b6b9745015993
-/shell-executor/managed-shell-environment-namespace:
-  en: f04b6ee0f2ec23d5
-  zh: 8c3104d8ce6c70e6
-/shell-executor/request-vs-spec-the-resolve-split:
-  en: a4f7d0ff18dce0c6
-  zh: d956cc599948fae8
-/shell-executor/foreground-runs-shellrunresult:
-  en: 471d328907ef0761
-  zh: d6b0b8e66e427394
-/shell-executor/file-sandbox-shellsandboxinfo:
-  en: 7f84b75c4128768c
-  zh: cf389bfa6c8d24f3
-/shell-executor/background-processes-shellprocess:
-  en: e5530a4d2b8f3aa3
-  zh: 72e4fd736c1a6d9d
-/shell-executor/the-service:
-  en: b850ffb5f5b75ac6
-  zh: 796e57ae77e0e41f

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

@@ -1,314 +0,0 @@
-# Shell Executor
-
-English | [中文](shell.zh.md)
-
-The shell execution seam uses [dsh-shell](../../packages/shell/shell) as its Service Definition on `ctx.shell`. The [shell package group](../../packages/shell/README.md) lists its Bash and PowerShell providers and model-facing Consumers. Generic background-job ids, ownership, and controls live in [jobs.md](jobs.md); this seam returns a process handle without job registration. Managed-range mechanics live behind the [subprocess seam](subprocess.md).
-
-Source: [`packages/shell/shell/src/types.ts`](../../packages/shell/shell/src/types.ts)
-
-## Managed shell environment namespace
-
-`DSH_*` variables are Harness-owned child-process facts. The model-facing bash tool collects them through `ctx.shellEnv` and passes them through `ShellExecRequest.dshEnv`; the subprocess service removes inherited `DSH_*` names before merging the current snapshot. The `DshEnvironmentKey`/`DshEnvironment` vocabulary is owned by the [subprocess seam](subprocess.md) and re-exported by `dsh-shell`.
-
-## Request vs. spec: the `resolve()` split
-
-The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.shell.resolve(request)` between them (the repo's "explicit > implicit at package boundaries" rule); a `ShellExecSpec` carries resolved values.
-
-```ts type-equiv
-/**
- * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
- * filled by {@link ShellExecutor.resolve} from the implementation's config.
- * This is the model-/plugin-facing shape; pass it to `resolve()` to obtain a
- * fully-resolved {@link ShellExecSpec}.
- */
-interface ShellExecRequest {
-  command: string
-  /** Working directory override (default: implementation-configured). */
-  workdir?: string | undefined
-  /** Timeout override in milliseconds (implementations cap it). */
-  timeoutMs?: number | undefined
-  /** Deadline policy at `timeoutMs` expiry (default `'kill'`). */
-  onExpiry?: ShellExpiryPolicy | undefined
-  /**
-   * Foreground stdout capture budget in bytes. Absent uses the executor's
-   * default output cap. Trusted in-process consumers use this when they must
-   * parse complete stdout up to their own bounded limit; the model-facing bash
-   * tool does not expose it as a parameter.
-   */
-  stdoutMaxBytes?: number | undefined
-  /** Abort signal — implementations kill the command when it fires, and treat a signal that is already aborted as fired. */
-  signal?: AbortSignal | undefined
-  /**
-   * Bytes to write to the command's stdin, then close it. Absent leaves stdin
-   * closed/empty (the default for model-driven tool calls). Set by in-process
-   * plugins (e.g. the hooks bridges, which write a hook command's JSON payload
-   * to its stdin); the model-facing bash tool does not expose it as a parameter
-   * (a model that needs stdin uses shell syntax like a heredoc or a pipe).
-   */
-  stdin?: string | undefined
-  /**
-   * Ordinary environment entries for the command, merged after the credential
-   * scrub. Managed facts belong in {@link dshEnv}, which merges after this
-   * map, so an entry here can never displace one. Set by in-process plugins
-   * (the hooks bridges set `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the
-   * model-facing bash tool does not expose it as a parameter.
-   */
-  env?: Record<string, string> | undefined
-  /**
-   * Harness-owned `DSH_*` variables for this execution (typed to managed
-   * keys). Executors discard ambient `DSH_*` entries before merging this
-   * snapshot last, so an unavailable current fact cannot inherit a stale
-   * value from the harness process and a caller {@link env} entry cannot
-   * displace a managed one.
-   */
-  dshEnv?: DshEnvironment | undefined
-  /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
-  sandboxPolicy?: SandboxExecutionPolicy | undefined
-}
-```
-
-```ts type-equiv
-/**
- * A resolved execution spec. {@link ShellExecutor.resolve} fills and caps the
- * required fields; under `onExpiry: 'none'` the resolved `timeoutMs` arms no
- * timer and is only echoed into {@link ShellRunResult.timeoutMs}.
- */
-interface ShellExecSpec {
-  command: string
-  workdir: string
-  timeoutMs: number
-  /** Deadline policy at `timeoutMs` expiry ({@link ShellExecutor.resolve} defaults it to `'kill'`). */
-  onExpiry: ShellExpiryPolicy
-  /**
-   * Resolved stdout capture budget in bytes, applied to every execution's
-   * stdout; stderr keeps the executor's own output cap.
-   */
-  stdoutMaxBytes: number
-  /** Abort signal — implementations kill the command when it fires, and treat a signal that is already aborted as fired. */
-  signal?: AbortSignal | undefined
-  /** Bytes to write to stdin before closing it; absent means no stdin. */
-  stdin?: string | undefined
-  /**
-   * Ordinary environment entries carried through from
-   * {@link ShellExecRequest.env}; {@link dshEnv} still merges after them.
-   * OPTIONAL on the spec for the same reason as `stdin`: absent means no
-   * ordinary extra environment.
-   */
-  env?: Record<string, string> | undefined
-  /** Managed `DSH_*` snapshot (typed to managed keys); merges after {@link env}. */
-  dshEnv?: DshEnvironment | undefined
-  /** Resolved sandbox policy; ignored by executors that do not confine. */
-  sandboxPolicy: SandboxExecutionPolicy | undefined
-}
-```
-
-`stdin` and `env` are trusted in-process plugin inputs and are not exposed by `dsh-tool-bash`. The local executor scrubs ambient credentials before merging explicit caller-supplied env.
-
-`stdoutMaxBytes` is also trusted-plugin-only. It lets a foreground consumer request complete stdout up to a bounded parser budget without changing stderr, background jobs, or the model-facing bash tool's ordinary output cap.
-
-## Foreground runs: `ShellRunResult`
-
-The outcome of one completed (or killed) foreground run. Orthogonal outcomes are reported **independently** — a process can both time out AND exit 0 because it trapped the signal — so `timedOut`, `aborted`, `signal`, and `exitCode` are each their own field; a caller never reads a cut-short run as a clean success.
-
-```ts type-equiv
-/** The outcome of a foreground run, including timeout during preparation. */
-interface ShellRunResult {
-  /** Exit code; null when preparation expired or the process died from a signal. */
-  exitCode: number | null
-  /** Terminating signal, or null when none was reported, including preparation expiry. */
-  signal: NodeJS.Signals | null
-  /**
-   * True when the executor's own timeout was the FIRST cause to cut the command
-   * short. Mutually exclusive with {@link aborted}: one fused deadline drives
-   * both the timeout and the caller's cancellation, so a timeout and an abort
-   * racing before process close report the single first-abort cause, not both
-   * (see the [timeout-library Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
-   */
-  timedOut: boolean
-  /**
-   * True when the caller's `AbortSignal` was the FIRST cause to kill the command
-   * (and it was not the executor's own timeout). Mutually exclusive with
-   * {@link timedOut} — see there for the first-cause classification.
-   */
-  aborted: boolean
-  /** The effective timeout applied to this run (after defaulting/capping). */
-  timeoutMs: number
-  stdout: CollectedOutput
-  stderr: CollectedOutput
-  /** Sandbox execution facts, absent for an unsandboxed executor. */
-  sandbox?: ShellSandboxInfo
-}
-```
-
-Each stream is a `CollectedOutput` — the (possibly truncated) text plus recovery info; when truncated, `text` is the **tail** and the complete stream spills to a private file. The fields are owned by the [subprocess seam](subprocess.md) and re-exported by `dsh-shell`.
-
-## File sandbox: `ShellSandboxInfo`
-
-A sandbox-consuming executor exposes its configured mode fallback through `ShellExecutor.sandboxMode`. The tool layer asks [`@deepseek-ai/dsh-sandbox-policy`](../../packages/sandbox/sandbox-policy/README.md) to resolve each calling session's durable `sandbox/mode` override and immutable cwd into `ShellExecRequest.sandboxPolicy`; a user-approved strictly wider call replaces only the mode. The mode/root/enforcement vocabulary is owned by the [`@deepseek-ai/dsh-sandbox` seam](sandbox.md); modes govern file effects only.
-
-A sandboxed run reports its mode, conservative denial classification, and enforcement completeness. `runnerFailed` marks a sandbox runner failure before the command ran; foreground execution throws `SANDBOX_UNAVAILABLE`, while a settled background process has only its facts channel.
-
-```ts type-equiv
-/**
- * Sandbox facts for one run, present iff a sandboxing executor handled it.
- * Facts are reported independently of process exit status so callers can
- * distinguish command failures from policy denials and runner failures.
- */
-interface ShellSandboxInfo {
-  /** The mode the command actually ran under. */
-  mode: SandboxMode
-  /** Whether the sandbox denied a file operation. */
-  denied: boolean
-  /** How completely the selected runner enforced the requested mode. */
-  enforcement?: SandboxEnforcement
-  /** Whether the sandbox runner failed before the command could run. */
-  runnerFailed?: boolean
-}
-```
-
-The `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws — and the executor propagates — when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background job records `runnerFailed`. The model receives denial/runner facts in results, learns the effective mode only when a denial marker names it, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox reference](../../packages/sandbox/sandbox-policy/README.md).
-
-## Background processes: `ShellProcess`
-
-`start()` resolves with a handle after asynchronous launch preparation; cancellation or preparation failure rejects before publication. The handle has no id or owner. `dsh-tool-bash` adapts it into `ctx.jobs.start()` hooks; the generic runtime then owns job identity and lifecycle. `done` resolves when the underlying process settles and never rejects; a subprocess provider rejection becomes a `killed` process with a stage-neutral error on stderr. Reads remain valid after settlement, and sandbox facts are stamped before `done` resolves.
-
-```ts type-equiv
-/**
- * A background process handle returned by {@link ShellExecutor.start}. It is the
- * only access path; buffered output remains readable after exit. Composition
- * teardown (the subprocess service's disposal) kills running processes and
- * awaits {@link done}; an executor-only reload leaves them running.
- */
-interface ShellProcess {
-  /** Process lifecycle state (settled exactly once). */
-  status: ShellProcessStatus
-  /** Exit code once finished (null = killed by signal / still running). */
-  exitCode: number | null
-  /** Terminating signal name, when signal-killed. */
-  signal: NodeJS.Signals | null
-  /**
-   * Resolves when the underlying process settles (never rejects — provider
-   * rejection settles as `killed` with a stage-neutral error on stderr).
-   */
-  readonly done: Promise<void>
-  /** Sandbox facts, stamped once a confined process settles. */
-  sandbox?: ShellSandboxInfo
-  /**
-   * Read output produced since the previous read (consuming — consecutive
-   * reads never re-deliver). Reads that lost data flag `lossy` and point at
-   * full-stream spill files when available.
-   */
-  readOutput(): ShellProcessRead
-  /**
-   * Non-consuming offset readers over the same captured streams the consuming
-   * {@link readOutput} cursor drains, including the provider-failure note a
-   * rejected spawn leaves on stderr. Independent observers read here at their
-   * own offsets without stealing bytes from `readOutput`.
-   */
-  observed: ShellObservedStreams
-  /**
-   * Terminate the provider-managed range. Returns false when it had already finished
-   * (no-op); idempotent.
-   */
-  kill(): boolean
-}
-```
-
-`readOutput()` returns the incremental delta and spill recovery facts:
-
-```ts type-equiv
-/** One incremental {@link ShellProcess.readOutput} read. */
-interface ShellProcessRead {
-  /** Output produced since the previous read (stderr in a marked section). */
-  delta: string
-  /** True when truncation dropped unread bytes the delta cannot include. */
-  lossy: boolean
-  /** Full stdout spill file, when stdout truncation occurred and a safe path is available. */
-  stdoutSpillPath?: string
-  /** Full stderr spill file, when stderr truncation occurred and a safe path is available. */
-  stderrSpillPath?: string
-}
-```
-
-## The service
-
-`ShellExecutor` owns `resolve`, foreground `run`, background-process `start`, and the `sandboxMode` capability fact. `dsh-bash-local` owns command defaulting, timeout/abort classification, the terminal environment, and the background read merge; managed-range termination, bounded collectors, spill files, credential scrubbing, and disposal quiescence are the [subprocess service](subprocess.md)'s. `dsh-tool-bash` owns model-facing rendering and adapts background handles into the [generic job runtime](jobs.md). `dsh-shell` owns the shell tools' shared exit-status contract: the exported `parseExitStatus`/`ParsedExitStatus` inverts the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append, and both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill.
-
-<!-- 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="ctxshell--shellexecutor-abstract-seam"></a>
-
-### `ctx.shell` — `ShellExecutor` (abstract seam)
-
-Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.shell` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-execute resolves with the process handle after preparation. "Foreground" is a property of what the caller awaits, not of the spawn — a caller that awaits ShellExecution.result ran the command in the foreground; one that keeps the handle ran it in the background. A caller that waits only for a while runs the command under `onExpiry: 'none'` and bounds its own wait; the handle stays valid after the caller stops waiting.
-
-Implementations must honor these semantics:
-
-- ShellExecution.result rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a descriptive result: first-cause `timedOut`/`aborted`, the spec's `timeoutMs` echoed.
-- The handle is published after preparation. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on the read path, while `result()` carries the same failure as its rejection.
-- `onExpiry: 'none'` arms no deadline; `'kill'` kills at expiry. Expiry during preparation returns a settled timed-out handle without output.
-- ShellProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
-- A still-running process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a process survives an executor-only reload.
-
-```ts cordis-catalog
-/**
- * Apply implementation-owned defaults and caps to a request before execution.
- * @param request - the caller's request; omitted fields get this
- *   implementation's defaults, capped fields are clamped.
- * @returns the fully-specified spec to hand to {@link execute}.
- */
-abstract resolve(request: ShellExecRequest): ShellExecSpec
-
-/**
- * Prepare and spawn the command under its resolved deadline.
- * @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the prepared handle, including its result projection;
- *   preparation timeout yields an already-settled handle with no output.
- * @throws on preparation failure or caller cancellation before process publication.
- */
-abstract execute(spec: ShellExecSpec): Promise<ShellExecution>
-```
-
-Source: [`packages/shell/shell/src/index.ts`](../../packages/shell/shell/src/index.ts)
-
-<a id="ctxshellenv--shellenvregistry"></a>
-
-### `ctx.shellEnv` — `ShellEnvRegistry`
-
-Registry (`ctx.shellEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
-
-```ts cordis-catalog
-/**
- * Register one environment contributor. Names and keys are unique; built-in
- * keys are reserved. Registration is disposed with the calling plugin fiber.
- * @param contributor - declared key ownership and per-execution resolver.
- * @returns the disposer that unregisters the contribution.
- */
-register(contributor: BashEnvContributor): () => void
-
-/**
- * Build the trusted `DSH_*` snapshot for one shell tool execution.
- * @param execution - the current tool execution.
- * @returns an immutable environment overlay containing built-ins and current contributions.
- */
-collect(execution: ToolExecution): DshEnvironment
-
-/**
- * Enumerate plugin-contributed variables without executing their resolvers.
- * @returns declarations sorted by environment variable name.
- */
-list(): BashEnvVariableInfo[]
-```
-
-Types: [DshEnvironment](subprocess.md) · [ToolExecution](tools.md)
-
-Source: [`packages/shell/shell-env/src/index.ts`](../../packages/shell/shell-env/src/index.ts)
-<!-- END GENERATED cordis-surface -->