dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/kb/site/en/reference/subsystems/settings.md

@@ -1,172 +1,22 @@
 ---
 editSource: "docs/subsystems/settings.md"
+rawMarkdownPath: "en/reference/subsystems/settings.md"
 outline: [2,3]
 ---
 
-# User Settings
+# Plugin Configuration Forms
 
-The user-settings seam of [dsh-settings](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/settings/settings) holds one user-owned document of per-namespace sections and resolves each registered namespace as schema defaults, then the registrant's composition `base`, then the user section. Providers such as [dsh-settings-file](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/settings/settings-file) store the raw document and push external edits; consumer plugins register a schema and read or observe the resolved value. Composition config stays in `cordis.yml` — a namespace carries only the user-editable subset.
+The [settings service](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/settings/settings/README.md) projects volatile Config fields from active profile entries. The [configuration editor](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/config-editor/README.md) persists edits through Cordis patches. Business consumers read `.get()` on their own Config references.
 
-Source: [`packages/settings/settings/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/settings/settings/src/index.ts)
-
-## Identity
-
-A namespace names one plugin-owned section of the user document. The brand prevents callers from mixing settings namespaces with other ids passed between packages or processes; construction validates lowercase kebab-case syntax.
-
-```ts type-equiv
-/** Nominal id of one registered settings namespace. */
-type SettingsNamespace = Branded<'SettingsNamespace'>
-```
-
-## Registration
-
-Registration binds a schemastery schema to a namespace on the calling plugin's fiber — disposing that fiber removes the namespace and its observers. The options carry the composition layer, the owner's effect timing, and an optional check for what the schema cannot express.
-
-```ts type-equiv
-/** Registration options beyond the namespace schema. */
-interface SettingsRegisterOptions<T> {
-  /** Composition-layer values resolved below the user layer (entry-config subset). */
-  base?: Partial<T>
-  /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
-  applies?: SettingsApplies
-  /**
-   * Reject a resolved section the owner could not act on, for constraints its
-   * schema cannot express — a cross-field requirement, or one field's validity
-   * depending on another's. Throwing here refuses the *write* that produced the
-   * value, so a caller learns at `update`/`replace`/`mutate` instead of storing
-   * something that would silently disable the owner.
-   *
-   * Kept separate from the schema because the schema is also what a
-   * configuration surface renders and what an absent section resolves through;
-   * folding a cross-field check into it would change both.
-   *
-   * Once the owner is registered, a stored section that fails this keeps the
-   * namespace's last good value and warns, exactly as a schema failure does,
-   * so an externally edited document cannot strand a running owner. At
-   * registration there is no last good value yet, so a stored section that
-   * already fails rejects the registration itself — again exactly as a schema
-   * failure does.
-   * @param value - the resolved section, schema-valid by construction.
-   */
-  validate?: (value: T) => void
-}
-```
-
-`validate` runs after the schema admits a value, so it sees defaults and the composition base exactly as the owner will. `dsh-llm-pi-ai` uses it to refuse a provider profile it could not serve at the write that produced it, rather than storing one that would disable every route in its namespace.
-
-`applies` is a UI hint, not a mechanism: a `restart` owner never watches, so its value is read once at construction and configuration surfaces can badge the pending change.
-
-```ts type-equiv
-/** When a namespace's changes take effect for its owner. */
-type SettingsApplies = 'live' | 'restart'
-```
-
-## Owner scope
-
-The scope is the owner-facing handle. `update` merges a sparse patch over the user section only (never into `base`); `replace` sets the section wholesale, which is the removal/reset path — keys absent from the replacement re-inherit `base` and schema defaults. Writes to one namespace are serialized in call order, and resolved values are deep-frozen snapshots.
-
-```ts type-equiv
-/** Owner-facing handle for one registered namespace. */
-interface SettingsScope<T> {
-  /** Current resolved value: schema defaults, then `base`, then the user layer. */
-  get(): T
-  /**
-   * Observe committed changes to this namespace's resolved value. Invocations
-   * of one callback run asynchronously, one at a time, in commit order; a
-   * rejection is contained and logged like a sync throw. After the disposer
-   * returns, no further invocation starts — one already queued is skipped;
-   * one already started still settles, and service disposal waits for it.
-   * @param callback - invoked after each commit with the next and previous values.
-   * @returns the disposer removing this observer.
-   */
-  watch(callback: (next: T, prev: T) => void | Promise<void>): () => void
-  /**
-   * Merge a partial patch into this namespace's user layer and persist it.
-   * @param patch - plain-object patch over the user section; JSON-compatible data
-   * only (non-JSON values reject with their path before anything persists).
-   */
-  update(patch: object): Promise<void>
-  /**
-   * Replace this namespace's user section wholesale; absent keys re-inherit
-   * the composition `base` and schema defaults (`replace({})` resets all).
-   * @param section - the complete next user section; JSON-compatible data only,
-   * as for {@link update}.
-   */
-  replace(section: object): Promise<void>
-}
-```
+## Identity and values
 
-## Descriptors
-
-`describe()` serializes every registered namespace for configuration surfaces: the schemastery `toJSON()` envelope drives schema-rendered forms, the resolved value fills them, and the detached `base`/`user` layers let a form mark user-overridden fields by presence. `describe({ redactSecrets: true })` — mandatory on every wire surface — strips `role('secret')` fields from all three layers and enumerates their `{path, set}` slots so a page can render write-only inputs without ever receiving a secret.
-
-```ts type-equiv
-/** One registered namespace as surfaced to configuration UIs. */
-interface SettingsDescriptor {
-  /** The registered namespace. */
-  ns: SettingsNamespace
-  /** Serialized schemastery schema (`schema.toJSON()`). */
-  schema: unknown
-  /** Current resolved value. */
-  value: unknown
-  /**
-   * Monotonic revision of the raw user section this descriptor was read at.
-   * Send it back as `expectedRevision` on a write to refuse a stale one.
-   */
-  revision: number
-  /** Registrant's composition `base` layer (detached), when one was declared. */
-  base?: unknown
-  /**
-   * Raw user section from the stored document (detached), when one exists and
-   * is well-formed; a field's presence here is what marks it user-overridden.
-   */
-  user?: unknown
-  /** Owner's declared effect timing. */
-  applies: SettingsApplies
-  /** Schema-declared secret positions; present only under `redactSecrets`. */
-  secrets?: RedactedSecret[]
-}
-```
+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.
 
-A caller that holds only the redacted descriptor cannot safely rebuild a section, so removals travel as path ops instead. Each descriptor also carries a `revision` over the raw section; a write may send it back as `expectedRevision`, and one that no longer matches is refused rather than applied over the writer that landed first.
-```ts type-equiv
-/**
- * One path-addressed edit to a namespace's user section. Path mutation exists
- * for a caller holding an INCOMPLETE view of the section — a configuration UI
- * reads the redacted descriptor, which by construction never received the
- * `role('secret')` fields. Such a caller can name the field it means without
- * restating the section: a wholesale `replace` rebuilt from a redacted
- * document silently deletes every secret the wire never returned.
- */
-type SettingsPathOp =
-  | { op: 'set'; path: readonly string[]; value: unknown }
-  | { op: 'unset'; path: readonly string[] }
-```
+## Edits
 
-```ts type-equiv
-/** Options for {@link SettingsProvider.describe}. */
-interface SettingsDescribeOptions {
-  /**
-   * Strip `role('secret')` fields from `value`/`base`/`user` and enumerate
-   * them in each descriptor's `secrets`. Every wire surface MUST pass this;
-   * the verbatim default exists for same-process configuration UIs only.
-   */
-  redactSecrets?: boolean
-}
-```
-
-## Change commits
+`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.
 
-Every committed change — an in-process write or an externally observed provider edit — emits `settings/updated (ns, next, prev, source)` after the new value is authoritative, and never when the resolved value is deep-equal. The source tag separates the two entry paths.
-
-```ts type-equiv
-/** Origin of one committed settings change. */
-type SettingsUpdateSource = 'update' | 'provider'
-```
-
-## Native document operations
-
-`SettingsDocumentOpenValue` confirms that `settings/openSettingsDocument` prepared the provider-owned document and handed it to the native text editor. `AgentPresetDirectoryOpenValue` reports either a completed native handoff or the resolved user-preset directory when desktop opening is unavailable. Neither operation accepts a browser-selected Host path.
+`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 -->
 
@@ -176,105 +26,52 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 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--settingsprovider-abstract-seam"></a>
+<a id="ctxsettings--settingsforms"></a>
 
-### `ctx.settings` — `SettingsProvider` (abstract seam)
+### `ctx.settings` — `SettingsForms`
 
-Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
+Project Config schemas into forms and own optional instance-level UI policy.
 
 ```ts cordis-catalog
-/**
- * Prepare the provider's user-editable document for a native editor. File
- * providers may materialize an absent document before returning its path;
- * non-file providers return undefined.
- * @returns the absolute local document path, or undefined for non-file storage.
- */
-prepareDocument(): Promise<string | undefined>
-
-/**
- * Register a namespace schema and receive its owner scope. The registration
- * is an effect on the calling plugin's fiber: disposing that fiber removes
- * the namespace and its observers. An invalid stored section fails the
- * registration itself — the earliest point where the schema can judge it.
- * @param ns - unique namespace; duplicate registration fails loud.
- * @param schema - schemastery schema resolving this namespace's value.
- * @param options - composition `base` layer and effect timing.
- * @returns the owner scope for reads, observation, and updates.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** 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.
  */
-register<const Namespace extends string, T>( ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, options?: SettingsRegisterOptions<T>, ): SettingsScope<T>
+configure(presentation: { auto?: boolean }, owner: Fiber = this.ctx.fiber): () => void
 
-/**
- * Attach one optional-settings consumer to this provider. The consumer
- * registers its composition entry as the base layer while this provider is
- * present, then falls back to that entry if the provider detaches.
- * @param owner - consumer context whose unload suppresses fallback work.
- * @param ns - consumer-owned settings namespace.
- * @param schema - schema resolving the namespace.
- * @param entry - composition entry used as the base and fallback value.
- * @param hooks - source sink, change notification, and optional validation.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** Locate the profile patch for native editing.
+ * @returns The existing profile patch path.
  */
-installSection<const Namespace extends string, T>( owner: Context, ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>, ): void
+prepareDocument(): Promise<string>
 
-/**
- * Describe every registered namespace for configuration surfaces, including
- * the composition `base` and raw user layers so a form can mark which fields
- * the user overrode (presence in `user`) and what a reset returns to.
- * @param options - redaction switch; wire surfaces must redact.
- * @returns one descriptor per registered namespace, in registration order.
+/** 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[]
 
-/**
- * Read one registered namespace's resolved value.
- * @param ns - the namespace to read.
- * @returns the resolved value, or `undefined` while unregistered.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** Merge editable fields into an entry's config.
+ * @param ns Profile entry id.
+ * @param patch Fields to merge.
+ * @param expectedRevision Revision returned by describe.
  */
-get<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>): unknown
+async update(ns: string, patch: object, expectedRevision?: number): Promise<void>
 
-/**
- * Merge a patch into one registered namespace's user layer, validate the
- * resolved candidate, persist through the provider, then commit and emit.
- * A validation failure rejects before anything is persisted. Writes to one
- * namespace are serialized: concurrent updates apply in call order, each
- * merging over the previous write's committed section.
- * @param ns - the registered namespace to update.
- * @param patch - plain-object patch over the user section.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** 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 update<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, patch: object, expectedRevision?: number, ): Promise<void>
+async replace(ns: string, section: object, expectedRevision?: number): Promise<void>
 
-/**
- * Replace one registered namespace's user section wholesale, validate,
- * persist, then commit and emit. Keys absent from `section` fall back to the
- * composition `base` and schema defaults — this is the removal/reset path a
- * merge-only patch cannot express (`replace({})` re-inherits everything).
- * @param ns - the registered namespace to replace.
- * @param section - the complete next user section.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** 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 replace<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, section: object, expectedRevision?: number, ): Promise<void>
-
-/**
- * Apply path-addressed edits to one registered namespace's user section,
- * validate, persist, then commit and emit. The ops are applied to the
- * section as it stands when the write reaches the front of the queue, so a
- * caller never has to restate fields it did not touch — and, crucially,
- * cannot delete fields it never saw. This is the write path for any caller
- * holding a redacted view; `replace` remains the wholesale reset.
- * @param ns - the registered namespace to edit.
- * @param ops - ordered path edits; later ops observe earlier ones.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
- */
-async mutate<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, ops: readonly SettingsPathOp[], expectedRevision?: number, ): Promise<void>
+async mutate(ns: string, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
 ```
 
 Source: [`packages/settings/settings/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/settings/settings/src/index.ts)
@@ -294,12 +91,6 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
  */
 @Remote describe(): SettingsDescribeValue
 
-/**
- * Report whether this deployment can open an authored Agent preset directory natively.
- * @returns true when the matching open operation is available.
- */
-@Remote canOpenAgentPresetDirectory(): boolean
-
 /**
  * Merge a patch into one namespace's stored user section.
  * @param ns - namespace key to write.
@@ -339,15 +130,6 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
  * @throws RemoteError when no document exists, preparation fails, or opening fails.
  */
 @Remote async openSettingsDocument(signal: AbortSignal): Promise<SettingsDocumentOpenValue>
-
-/**
- * Open one user-authored Agent preset directory or return its path when no native opener exists.
- * @param agentPreset - preset id resolved against Host-owned roots.
- * @param signal - caller lifetime; abort terminates the native command.
- * @returns an opened confirmation or the resolved directory for text display.
- * @throws RemoteError when the preset is missing, read-only, invalid, or cannot be opened.
- */
-@Remote async openAgentPresetDirectory( agentPreset: string, signal: AbortSignal, ): Promise<AgentPresetDirectoryOpenValue>
 ```
 
 Source: [`packages/api/settings-controller/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/api/settings-controller/src/index.ts)
@@ -360,49 +142,18 @@ Source: [`packages/api/settings-controller/src/index.ts`](https://github.com/dee
 
 #### `settings/document-updated` — emit
 
-One registered namespace's RAW user section changed, whether or not the resolved value did. `settings/updated` is the consumer-facing event and stays deep-equal-gated; this one exists for configuration surfaces, which must learn that a field went from inherited to overridden (same resolved value, different meaning) and that their held revision is stale. Listener containment matches `settings/updated`.
+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 registered namespace's RAW user section changed, whether or not the
- * resolved value did. `settings/updated` is the consumer-facing event and
- * stays deep-equal-gated; this one exists for configuration surfaces,
- * which must learn that a field went from inherited to overridden (same
- * resolved value, different meaning) and that their held revision is
- * stale. Listener containment matches `settings/updated`.
- * @param ns - the namespace whose stored section changed.
- * @param revision - the namespace's new revision.
+ * 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`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/settings/settings/src/types.ts)
-
-<a id="settingsupdated--emit"></a>
-
-#### `settings/updated` — emit
-
-Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
-
-```ts cordis-catalog
-/**
- * Committed change to one registered namespace's resolved value. Emitted
- * after the provider persisted (for `update`) or published (`provider`)
- * the change; never emitted when the resolved value is deep-equal.
- * Listener failures are contained and logged — a sync throw and an async
- * rejection alike — except `INVARIANT`-coded failures, which rethrow
- * after every listener ran; that rethrow reaches the emitter only from
- * synchronous listeners, so invariant checks on this event must not be
- * async functions.
- * @param ns - the namespace whose resolved value changed.
- * @param next - the new resolved value.
- * @param prev - the previous resolved value.
- * @param source - whether the change entered through `update()` or the provider.
- * @mode emit
- */
-'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
-```
-
 Source: [`packages/settings/settings/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/settings/settings/src/types.ts)
 <!-- END GENERATED cordis-surface -->

package/kb/site/en/reference/subsystems/shell.md

@@ -1,11 +1,12 @@
 ---
 editSource: "docs/subsystems/shell.md"
+rawMarkdownPath: "en/reference/subsystems/shell.md"
 outline: [2,3]
 ---
 
-# Bash Executor
+# Shell Executor
 
-The bash execution seam is split across a Service Definition ([dsh-shell](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/shell/shell), `ctx.shell`), Service Providers ([dsh-bash-local](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/shell/bash-local) and [dsh-bash-sandbox](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/shell/bash-sandbox)), and Consumer ([dsh-tool-bash](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/shell/tool-bash), the `bash` schema). Generic background-job ids, ownership, and controls live in [jobs.md](./jobs.md); this seam returns a task-free process handle. Managed-range mechanics live behind the [subprocess seam](./subprocess.md).
+The shell execution seam uses [dsh-shell](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/shell/shell) as its Service Definition on `ctx.shell`. The [shell package group](https://github.com/deepseek-ai/deepseek-harness/blob/master/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`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/shell/shell/src/types.ts)
 
@@ -30,6 +31,8 @@ interface ShellExecRequest {
   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
@@ -37,7 +40,7 @@ interface ShellExecRequest {
    * tool does not expose it as a parameter.
    */
   stdoutMaxBytes?: number | undefined
-  /** Abort signal — implementations kill the command when it fires. */
+  /** 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
@@ -71,19 +74,21 @@ interface ShellExecRequest {
 ```ts type-equiv
 /**
  * A resolved execution spec. {@link ShellExecutor.resolve} fills and caps the
- * required fields; {@link ShellExecutor.start} ignores `timeoutMs` because
- * background processes have no executor timeout.
+ * 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 foreground stdout capture budget in bytes. `run()` uses it for
-   * stdout; background jobs and stderr keep the executor's own output cap.
+   * 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. */
+  /** 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
@@ -110,11 +115,11 @@ interface ShellExecSpec {
 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 one completed (or killed) foreground run. */
+/** The outcome of a foreground run, including timeout during preparation. */
 interface ShellRunResult {
-  /** Exit code; null when the process died from a signal. */
+  /** Exit code; null when preparation expired or the process died from a signal. */
   exitCode: number | null
-  /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
+  /** 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
@@ -165,11 +170,11 @@ interface ShellSandboxInfo {
 }
 ```
 
-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 Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+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](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/README.md).
 
 ## Background processes: `ShellProcess`
 
-`start()` returns a handle with 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.
+`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
 /**
@@ -198,6 +203,13 @@ interface ShellProcess {
    * 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.
@@ -240,36 +252,33 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 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:
 
-- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a ShellRunResult.
-- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
+- 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 background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.
+- 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 run}/{@link start}.
+ * @returns the fully-specified spec to hand to {@link execute}.
  */
 abstract resolve(request: ShellExecRequest): ShellExecSpec
 
 /**
- * Run a command in the foreground; resolves when it finishes.
- * @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the outcome; nonzero exits, timeout kills, and abort kills
- *   resolve with a descriptive result rather than reject.
- */
-abstract run(spec: ShellExecSpec): Promise<ShellRunResult>
-
-/**
- * Start a background process and return its handle immediately.
+ * Prepare and spawn the command under its resolved deadline.
  * @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the live process handle (reads, kill, quiescence promise).
+ * @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 start(spec: ShellExecSpec): ShellProcess
+abstract execute(spec: ShellExecSpec): Promise<ShellExecution>
 ```
 
 Source: [`packages/shell/shell/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/shell/shell/src/index.ts)