@deepseek-ai/dsh-shell 0.1.6-alpha.1 → 0.1.7-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/shell/README.md
-README.md: 9b32149691a8cf4d4d8316101f4feec6762d0846
-README.zh.md: 9d23b0c5957f9d59169c53c92b960c0b26b77a23
+README.md: b72440a38cefb67140ba0078169aac34f3ccdb19
+README.zh.md: 272ffc85f8c4880eb77348f2f5ce780a68529df6

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use `ctx.shell` to run foreground shell commands with bounded output or prepare background processes asynchronously before receiving their handles. A profile can select local or sandboxed Bash or PowerShell execution without changing callers. Resolve each request before execution to make the working directory, timeout, and output limits explicit. Command completion, nonzero exits, timeouts, and caller aborts return results; only infrastructure failures reject, while the `bash` and `pwsh` tools own model-visible rendering and sandbox guidance.
+Use `ctx.shell` to run shell commands with bounded output or keep them running as background work. One execution handle supports foreground results and background reads. A profile can select local or sandboxed Bash or PowerShell execution without changing callers. Resolve requests before execution to make the working directory, timeout, and output limits explicit. Command exits, timeouts, and caller aborts return results; only infrastructure failures reject, while the `bash` and `pwsh` tools own model-visible rendering and sandbox guidance.
 
 ## Table of Contents
 
@@ -25,24 +25,31 @@ Use `ctx.shell` to run foreground shell commands with bounded output or prepare
 <a id="use-this-package"></a>
 ## Use this package
 
-Use `ctx.shell` when an agent or an in-process plugin needs to run a shell command and read its output, or start a background process and poll it. It is the contract every shell executor and the model-facing `bash`/`pwsh` tools build on, so code written against it works over any executor implementation.
+Use `ctx.shell` when an agent or an in-process plugin needs to run a shell command and read its output, keep a process running and poll it, or hand a foreground command a way to outlive its deadline. There is one execution method — `execute(spec)` resolves with the prepared handle — and "foreground" is a property of what the caller awaits, not of the spawn. It is the contract every shell executor and the model-facing `bash`/`pwsh` tools build on, so code written against it works over any executor implementation.
 
 ### Foreground commands
 
-Call `run` with a resolved spec to execute a command in the foreground. The promise resolves when the command finishes: a nonzero exit, an executor timeout kill, or a caller abort kill is a result, never a rejection. `run` rejects only for infrastructure failures such as an unusable working directory or a missing shell. The result carries the exit code or signal, whether a timeout or an abort cut the run short, and the collected stdout/stderr with spill-file paths when a stream overflowed its budget.
+Await the handle's `result()` projection to run a command in the foreground. The promise resolves when the command finishes: a nonzero exit, an executor timeout kill, or a caller abort kill is a result, never a rejection. `result()` rejects only for infrastructure failures such as an unusable working directory or a missing shell. The result carries the exit code or signal, whether a timeout or an abort cut the run short (first-cause classification), and the collected stdout/stderr with spill-file paths when a stream overflowed its budget.
 
 ```text
-const result = await ctx.shell.run(ctx.shell.resolve({ command: 'ls -la' }))
+const execution = await ctx.shell.execute(ctx.shell.resolve({ command: 'ls -la' }))
+const result = await execution.result()
 console.log(result.exitCode, result.stdout.text)
 ```
 
 ### Background processes
 
-Await `start` with a resolved spec to launch a background process; it publishes the handle after preparation and applies no background execution timeout. Cancellation or preparation failure rejects before publication. Read output incrementally with `readOutput()` — consecutive reads never repeat output, and lossy reads point at full-stream spill files. Terminate the provider-managed range with `kill()` (returns `false` once the direct command has finished) and await `done` for direct-command settlement. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, where the tool layer registers the handle.
+Resolve the request with `onExpiry: 'none'` and await `execute` for the prepared handle: no deadline is armed, and the process runs until killed or finished. Read output incrementally with `readOutput()` — consecutive reads never repeat output, and lossy reads point at full-stream spill files. Terminate the provider-managed range with `kill()` (returns `false` once the direct command has finished) and await `done` for direct-command settlement. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, where the tool layer registers the handle. `ShellProcess.observed` exposes non-consuming offset readers over the same captured streams — for observers independent of the consuming cursor, such as the job registry's pull sources — including the `spawn failed: …` note a rejected spawn leaves on stderr.
+
+### Deadlines and bounded waits
+
+The deadline includes asynchronous preparation. Expiry before a process starts returns a settled handle whose result is `timedOut: true`, with empty output. Cancellation or preparation failure rejects `execute` before publication; late preparation cannot spawn a process.
+
+The seam has two expiry policies and no hand-over protocol. `'kill'` stops the command at the deadline and classifies the result `timedOut`; `'none'` arms no deadline, so only the caller's signal and `kill()` stop the command. A caller that wants to wait only for a while runs the command under `'none'` and bounds its own wait: the handle stays valid after the caller stops waiting, and nothing changes hands at that moment. The `bash`/`pwsh` tools do exactly this — with a job registry composed they register every command with `ctx.jobs` as it starts and wait on the job, so a foreground command that outlives its timeout simply keeps running as the job it already was.
 
 ### Requests and resolved specs
 
-Every execution starts from a `ShellExecRequest` with optional fields; the executor's `resolve()` turns it into a fully-resolved `ShellExecSpec` with explicit defaults and caps before anything runs. This request/spec split is the repository's template for explicit resolution at package boundaries: callers never rely on hidden defaults inside `run` or `start`. `resolve()` fills the working directory and timeout from the executor's configuration, caps per-call overrides, and carries optional inputs — `stdin`, ordinary `env`, and the trusted `DSH_*` snapshot — through verbatim.
+Every execution starts from a `ShellExecRequest` with optional fields; the executor's `resolve()` turns it into a fully-resolved `ShellExecSpec` with explicit defaults and caps before anything runs. This request/spec split is the repository's template for explicit resolution at package boundaries: callers never rely on hidden defaults inside `execute`. `resolve()` fills the working directory, timeout, and expiry policy (default `'kill'`) from the executor's configuration and the request, caps per-call overrides, and carries optional inputs — `stdin`, ordinary `env`, and the trusted `DSH_*` snapshot — through verbatim.
 
 ### Choosing and composing an executor
 
@@ -73,15 +80,15 @@ This section explains the design of the seam and points at the code that realize
 
 The package is one role of a standard capability seam: the Service Definition that names the executor contract, with Service Providers and Consumers split so each role evolves independently (see the [capability-seams note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). Two decisions anchor the contract:
 
-- **Explicit resolution at the boundary.** `resolve(request)` is the single place defaults and caps are applied; `run` and `start` accept only resolved specs and never re-default, so no hidden fallback lives inside an implementation.
-- **Task-free background handles.** `start` returns a `ShellProcess` with no id or owner; job identity, ownership, and lifecycle belong to the generic `ctx.jobs` runtime, keeping executors independent of sessions.
+- **Explicit resolution at the boundary.** `resolve(request)` is the single place defaults and caps are applied; `execute` accepts only resolved specs and never re-defaults, so no hidden fallback lives inside an implementation.
+- **One execution, projected views.** `execute` resolves with the prepared handle; the foreground result and the background cursor reads are projections over the same spawned process, so foreground/background is the caller's choice, never a second spawn path. The handle carries no id or owner; job identity, ownership, and lifecycle belong to the generic `ctx.jobs` runtime, keeping executors independent of sessions.
 
 ### Source map
 
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: abstract `ShellExecutor` service and the shared settings namespace |
-| [`src/types.ts`](src/types.ts) | Request/spec vocabulary, `ShellRunResult`, `ShellProcess`, and sandbox facts |
+| [`src/types.ts`](src/types.ts) | Request/spec vocabulary, `ShellExecution`, `ShellRunResult`, and sandbox facts |
 | [`src/render.ts`](src/render.ts) | `parseExitStatus`: the exit-status marker contract the shell tools share |
 | — | No runtime invariant companion is published; this stateless Service Definition owns request/result types, while executors and policy own observations. |
 
@@ -91,7 +98,7 @@ The package is one role of a standard capability seam: the Service Definition th
 
 ### Background lifecycle and ownership
 
-A background process belongs to the subprocess service, not to the executor: it survives an executor-only reload and is killed and joined when the composition tears down. Implementations must honor the seam's semantics — `run` rejects only for infrastructure failures; `start` resolves after preparation with no background execution timeout and its published handle’s `done` never rejects (a subprocess provider rejection settles as `killed` with a stage-neutral error on stderr); `readOutput` is consuming and lossy reads report spill files.
+A spawned process belongs to the subprocess service, not to the executor: it survives an executor-only reload and is killed and joined when the composition tears down. Implementations must honor the seam's semantics — `result()` rejects only for infrastructure failures; the handle is published after preparation and its `done` never rejects (provider rejections, synchronous or asynchronous, settle the handle as `killed` with a stage-neutral note on stderr while `result()` carries the same failure as its rejection; a live handle whose rejection follows the execution's own `kill()` or abort settles as its terminal outcome instead); `readOutput` is consuming and lossy reads report spill files.
 
 </details>
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用 `ctx.shell` 运行输出有界的前台 shell 命令，或异步准备后台进程后取得句柄。配置文件可选择本地或沙箱化的 Bash 或 PowerShell 执行方式，而无需更改调用方。执行前解析每个请求，以显式确定工作目录、超时和输出上限。命令完成、非零退出、超时和调用方中止都会作为结果返回；只有基础设施故障才会 reject，而模型可见的渲染与沙箱指引由 `bash` 和 `pwsh` 工具负责。
+使用 `ctx.shell` 运行输出有界的 shell 命令，或让命令作为后台工作继续运行。同一个执行句柄支持前台结果与后台读取。配置文件可以选择本地或沙箱化的 Bash 或 PowerShell 执行方式，而无需更改调用方。执行前解析请求，以显式确定工作目录、超时与输出上限。命令退出、超时和调用方中止都会作为结果返回；只有基础设施故障才会 reject，模型可见的渲染与沙箱指引由 `bash` 和 `pwsh` 工具负责。
 
 ## 目录
 
@@ -25,24 +25,31 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-当 agent（智能体）或进程内插件需要运行 shell 命令并读取输出，或启动后台进程并轮询它时，使用 `ctx.shell`。它是每个 shell 执行器与面向模型的 `bash`/`pwsh` 工具共同依赖的约定，因此基于它编写的代码可以运行在任意执行器实现之上。
+当 agent（智能体）或进程内插件需要运行 shell 命令并读取输出、保持进程运行并轮询它，或让前台命令有办法活过自己的 deadline 时，使用 `ctx.shell`。执行方法只有一个——`execute(spec)` 在准备完成后返回句柄——「前台」是调用方等待什么的属性，而不是 spawn 的属性。它是每个 shell 执行器与面向模型的 `bash`/`pwsh` 工具共同依赖的约定，因此基于它编写的代码可以运行在任意执行器实现之上。
 
 ### 前台命令
 
-用已解析的 spec 调用 `run` 即可在前台执行命令。promise 在命令结束时 resolve：非零退出、执行器超时终止或调用方中止终止都是结果，绝不是 rejection。`run` 只在基础设施失败时 reject，例如工作目录不可用或缺少 shell。结果携带退出码或信号、是超时还是中止截断了运行，以及收集到的 stdout/stderr；流超出预算时还附带 spill 文件路径。
+等待句柄的 `result()` 投影即可在前台执行命令。promise 在命令结束时 resolve：非零退出、执行器超时终止或调用方中止终止都是结果，绝不是 rejection。`result()` 只在基础设施失败时 reject，例如工作目录不可用或缺少 shell。结果携带退出码或信号、是超时还是中止截断了运行（首因归类），以及收集到的 stdout/stderr；流超出预算时还附带 spill 文件路径。
 
 ```text
-const result = await ctx.shell.run(ctx.shell.resolve({ command: 'ls -la' }))
+const execution = await ctx.shell.execute(ctx.shell.resolve({ command: 'ls -la' }))
+const result = await execution.result()
 console.log(result.exitCode, result.stdout.text)
 ```
 
 ### 后台进程
 
-用已解析的 spec 等待 `start` 即可启动后台进程；它在准备完成后发布句柄，不应用后台执行超时。取消或准备失败会在发布前拒绝调用。用 `readOutput()` 增量读取输出——连续读取绝不会重复交付，有损读取会指向完整流的 spill 文件。用 `kill()` 终止由提供方管理的进程范围（直接命令结束后返回 `false`），并等待 `done` 完成直接命令结算。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。
+以 `onExpiry: 'none'` 解析请求并保留句柄：不布置任何 deadline，进程一直跑到被 kill 或自行结束。用 `readOutput()` 增量读取输出——连续读取绝不会重复交付，有损读取会指向完整流的 spill 文件。用 `kill()` 终止由提供方管理的进程范围（直接命令结束后返回 `false`），并等待 `done` 完成直接命令结算。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。`ShellProcess.observed` 在同一份捕获流上暴露非消费的偏移读取器——供独立于消费游标的观察者使用，例如任务注册表的拉取源——包括被拒绝的 spawn 留在 stderr 上的 `spawn failed: …` 提示。
+
+### deadline 与有界等待
+
+deadline 包含异步准备耗时。进程启动前到期会返回已结算的句柄，其结果为 `timedOut: true`，输出为空。取消或准备失败会在发布句柄前拒绝 `execute`；迟到的准备结果不会启动进程。
+
+seam 只有两种到期策略，没有任何移交协议。`'kill'` 在 deadline 停下命令并把结果归类为 `timedOut`；`'none'` 不设 deadline，只有调用方的信号和 `kill()` 能停下命令。只想等一段时间的调用方以 `'none'` 运行命令并自己限定等待时长：调用方停止等待后句柄依然有效，那一刻没有任何东西易手。`bash`/`pwsh` 工具正是这样做的——组合中有 job registry 时，每条命令一启动就登记到 `ctx.jobs` 并等待该 job，所以超时后仍在运行的前台命令只是继续作为它本来就是的那个 job 运行。
 
 ### 请求与已解析 spec
 
-每次执行都从带可选字段的 `ShellExecRequest` 开始；执行器的 `resolve()` 在任何东西运行之前，把它变成默认值与上限都已显式填好的 `ShellExecSpec`。这一请求/spec 拆分正是仓库在包边界显式解析的模板：调用方绝不依赖 `run` 或 `start` 内部隐藏的默认值。`resolve()` 从执行器配置填充工作目录与超时、对每次调用的覆盖值设上限，并按原样携带可选输入——`stdin`、普通 `env` 与受信任的 `DSH_*` 快照。
+每次执行都从带可选字段的 `ShellExecRequest` 开始；执行器的 `resolve()` 在任何东西运行之前，把它变成默认值与上限都已显式填好的 `ShellExecSpec`。这一请求/spec 拆分正是仓库在包边界显式解析的模板：调用方绝不依赖 `execute` 内部隐藏的默认值。`resolve()` 从执行器配置与请求填充工作目录、超时与到期策略（默认 `'kill'`）、对每次调用的覆盖值设上限，并按原样携带可选输入——`stdin`、普通 `env` 与受信任的 `DSH_*` 快照。
 
 ### 选择并组合一个执行器
 
@@ -73,15 +80,15 @@ seam 本身不是执行器：每个组合只挂载一个提供方，工具即可
 
 本包是标准能力 seam 中的一个角色：命名执行器约定的 Service Definition，Service Provider 与 Consumer 各自拆分，使每个角色都能独立演进（见[能力 seam 笔记](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)）。两项决策锚定了该约定：
 
-- **边界处的显式解析。** `resolve(request)` 是应用默认值与上限的唯一位置；`run` 与 `start` 只接受已解析的 spec，绝不再次默认化，因此实现内部不会藏有隐藏的兜底值。
-- **无任务语义的后台句柄。** `start` 返回不带 id 或所有者的 `ShellProcess`；job 身份、所有权与生命周期属于通用 `ctx.jobs` 运行时，使执行器与会话保持独立。
+- **边界处的显式解析。** `resolve(request)` 是应用默认值与上限的唯一位置；`execute` 只接受已解析的 spec，绝不再次默认化，因此实现内部不会藏有隐藏的兜底值。
+- **一次执行，多个投影。** `execute` 在准备完成后返回句柄；前台结果与后台游标读取都是同一个已 spawn 进程上的投影，前台/后台是调用方的选择，绝不是第二条 spawn 路径。句柄不带 id 或所有者；job 身份、所有权与生命周期属于通用 `ctx.jobs` 运行时，使执行器与会话保持独立。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：抽象 `ShellExecutor` 服务与共享设置命名空间 |
-| [`src/types.ts`](src/types.ts) | 请求/spec 词汇、`ShellRunResult`、`ShellProcess` 与沙箱事实 |
+| [`src/types.ts`](src/types.ts) | 请求/spec 词汇、`ShellExecution`、`ShellRunResult` 与沙箱事实 |
 | [`src/render.ts`](src/render.ts) | `parseExitStatus`：shell 工具共享的退出状态标记约定 |
 | — | 不发布运行时不变式伴生入口；该无状态 Service Definition 负责请求／结果类型，执行器与策略负责观察。 |
 
@@ -91,7 +98,7 @@ seam 本身不是执行器：每个组合只挂载一个提供方，工具即可
 
 ### 后台生命周期与归属
 
-后台进程属于 subprocess 服务而非执行器：它能在仅重载执行器后存活，并在组合拆解时被终止并 join。实现必须遵守 seam 的语义——`run` 只在基础设施失败时 reject；`start` 在准备完成后返回且不设后台执行超时，已发布句柄的 `done` 绝不 reject（subprocess provider rejection 以 `killed` 结算，并把不声明阶段的错误写入 stderr）；`readOutput` 是消费式的，有损读取会报告 spill 文件。
+已 spawn 的进程属于 subprocess 服务而非执行器：它能在仅重载执行器后存活，并在组合拆解时被终止并 join。实现必须遵守 seam 的语义——`result()` 只在基础设施失败时 reject；句柄在准备完成后发布且其 `done` 绝不 reject（无论同步还是异步的 provider rejection 都把句柄结算为 `killed`、把不声明阶段的提示写入 stderr，同时 `result()` 以同一失败 reject；活句柄在本次执行自己的 `kill()` 或 abort 之后才到来的 rejection 则结算为其终态）；`readOutput` 是消费式的，有损读取会报告 spill 文件。
 
 </details>
 

package/lib/index.js

@@ -53,34 +53,32 @@ function parseExitStatus(text) {
 * @module @deepseek-ai/dsh-shell
 */
 /**
-* Settings namespace of this capability, owned here rather than by either
-* executor family because it names the capability, not an implementation: a
-* host composes exactly one provider of `ctx.shell` (the win32 layer swaps the
-* POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate
-* service registration), so the providers share one namespace without ever
-* registering it twice, and a settings document carried between platforms
-* keeps resolving on both.
-*/
-const SHELL_SETTINGS_NAMESPACE = "shell";
-/**
 * 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).
 *
+* {@link 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 {@link 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:
-* - {@link run} rejects only for infrastructure failures. Nonzero exits,
-*   timeout kills, and abort kills resolve with a {@link ShellRunResult}.
-* - {@link start} resolves after launch preparation; cancellation or setup failure
-*   rejects before publishing a handle. No timeout applies to background processes.
-*   Once published, `done` settles at process close and never rejects; subprocess
-*   provider failures settle as `killed` with the error on stderr.
+* - {@link 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.
 * - {@link 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.
 */
 var ShellExecutor = class extends Service {
 	constructor(ctx) {
@@ -94,4 +92,4 @@ var ShellExecutor = class extends Service {
 	get sandboxMode() {}
 };
 //#endregion
-export { DSH_ENV_PREFIX, SHELL_SETTINGS_NAMESPACE, ShellExecutor, ShellExecutor as default, parseExitStatus };
+export { DSH_ENV_PREFIX, ShellExecutor, ShellExecutor as default, parseExitStatus };

package/lib/types/index.d.ts

@@ -6,19 +6,9 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
-import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from './types.ts';
-/**
- * Settings namespace of this capability, owned here rather than by either
- * executor family because it names the capability, not an implementation: a
- * host composes exactly one provider of `ctx.shell` (the win32 layer swaps the
- * POSIX rows for the pwsh ones, and mounting both fails loud on a duplicate
- * service registration), so the providers share one namespace without ever
- * registering it twice, and a settings document carried between platforms
- * keeps resolving on both.
- */
-export declare const SHELL_SETTINGS_NAMESPACE = "shell";
+import type { ShellExecRequest, ShellExecSpec, ShellExecution } from './types.ts';
 export { DSH_ENV_PREFIX } from './types.ts';
-export type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellProcessRead, ShellProcessStatus, ShellRunResult, ShellSandboxInfo, CollectedOutput, DshEnvironment, DshEnvironmentKey, } from './types.ts';
+export type { ShellExecRequest, ShellExecSpec, ShellExecution, ShellExpiryPolicy, ShellProcess, ShellProcessRead, ShellProcessStatus, ShellRunResult, ShellSandboxInfo, CollectedOutput, DshEnvironment, DshEnvironmentKey, } from './types.ts';
 export { parseExitStatus } from './render.ts';
 export type { ParsedExitStatus } from './render.ts';
 declare module '@deepseek-ai/cordis' {
@@ -32,19 +22,27 @@ declare module '@deepseek-ai/cordis' {
  * implementation per context; loading a second throws, which is cordis'
  * standard duplicate-service behavior).
  *
+ * {@link 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 {@link 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:
- * - {@link run} rejects only for infrastructure failures. Nonzero exits,
- *   timeout kills, and abort kills resolve with a {@link ShellRunResult}.
- * - {@link start} resolves after launch preparation; cancellation or setup failure
- *   rejects before publishing a handle. No timeout applies to background processes.
- *   Once published, `done` settles at process close and never rejects; subprocess
- *   provider failures settle as `killed` with the error on stderr.
+ * - {@link 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.
  * - {@link 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.
  */
 export declare abstract class ShellExecutor extends Service {
     constructor(ctx: Context);
@@ -58,23 +56,17 @@ export declare abstract class ShellExecutor extends Service {
      * 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 preparation and the foreground command under the resolved timeout.
+     * Prepare and spawn the command under its resolved deadline.
      * @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.
+     * @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 run(spec: ShellExecSpec): Promise<ShellRunResult>;
-    /**
-     * Prepare a background process asynchronously and publish its live handle.
-     * @param spec - a resolved spec from {@link resolve}, never a raw request.
-     * @returns the live process handle after preparation; cancellation or setup failure rejects.
-     */
-    abstract start(spec: ShellExecSpec): Promise<ShellProcess>;
+    abstract execute(spec: ShellExecSpec): Promise<ShellExecution>;
 }
 export default ShellExecutor;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -7,9 +7,22 @@
  * @module dsh-shell/types
  */
 import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
-import type { CollectedOutput, DshEnvironment } from '@deepseek-ai/dsh-subprocess';
+import type { CollectedOutput, DshEnvironment, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess';
 export { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-subprocess';
-export type { CollectedOutput, DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-subprocess';
+export type { CollectedOutput, DshEnvironment, DshEnvironmentKey, SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess';
+/**
+ * Non-consuming offset readers over a background process's captured streams,
+ * for observers independent of the consuming {@link ShellProcess.readOutput}
+ * cursor. Every background process exposes both streams; a spawn that
+ * rejected produced no process output, so its stderr reader serves the
+ * `spawn failed: …` note as the whole stream.
+ */
+export interface ShellObservedStreams {
+    /** Offset reader over captured stdout. */
+    stdout: SubprocessOutputReader;
+    /** Offset reader over captured stderr (the spawn-failure note after a rejected spawn). */
+    stderr: SubprocessOutputReader;
+}
 /**
  * Sandbox facts for one run, present iff a sandboxing executor handled it.
  * Facts are reported independently of process exit status so callers can
@@ -25,6 +38,14 @@ export interface ShellSandboxInfo {
     /** Whether the sandbox runner failed before the command could run. */
     runnerFailed?: boolean;
 }
+/**
+ * What the executor does when the deadline expires: `kill` stops the command
+ * and classifies the result `timedOut` (the default), and `none` arms no
+ * deadline at all, leaving the caller's signal and {@link ShellProcess.kill}
+ * as the only ways to stop the command. A consumer that wants to keep waiting
+ * only for a while runs the command under `none` and bounds its own wait.
+ */
+export type ShellExpiryPolicy = 'kill' | 'none';
 /**
  * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
  * filled by {@link ShellExecutor.resolve} from the implementation's config.
@@ -37,6 +58,8 @@ export 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
@@ -44,7 +67,7 @@ export 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
@@ -75,19 +98,21 @@ export interface ShellExecRequest {
 }
 /**
  * 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}.
  */
 export 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;
@@ -169,10 +194,34 @@ export 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.
      */
     kill(): boolean;
 }
+/**
+ * The one execution handle {@link ShellExecutor.execute} returns: the live
+ * {@link ShellProcess} itself plus the foreground projection `result()`.
+ */
+export interface ShellExecution extends ShellProcess {
+    /**
+     * Foreground projection: settles when the process closes, with split
+     * collected streams and first-cause `timedOut`/`aborted` classification.
+     * Rejects only for infrastructure failures (a spawn that never produced a
+     * process); nonzero exits, timeout kills, and abort kills resolve with a
+     * descriptive result. Created on demand and memoized — callers that never
+     * invoke it (background producers) never observe the rejection either; the
+     * handle's `done`/read path carries the spawn-failure story for them.
+     * @returns the settled foreground result for this execution.
+     */
+    result(): Promise<ShellRunResult>;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-shell",
   "description": "Abstract bash executor seam (ctx.shell) for the DeepSeek Harness",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,15 +27,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-subprocess": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-subprocess": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3"
   }
 }