dsh-plugin-wsl-env 0.7.4 → 0.8.0

package/docs/LIMITATIONS.md

@@ -29,6 +29,12 @@ crosses the 9p share. What to know about the one substrate there is:
   syscall before the rename: a concurrent writer wins and the stale write
   refuses with `FS_STALE_VERSION`. The residual stat-then-rename pair is the
   same sliver a Linux-host session's own rename has.
+- **A write is durable against process death, not machine death.** The
+  publication fsyncs the staged file before its atomic rename, but the
+  containing directory is not fsynced afterwards: a kernel panic or power loss
+  immediately after a successful write can lose the rename, and the file
+  reverts to its pre-write content. This is stronger than the peer backend,
+  which fsyncs nothing, and short of a crash-consistent store.
 - **A Linux filename containing a backslash cannot be addressed.** The UNC
   display form (`\\wsl.localhost\<distro>\...`) is the file's identity
   everywhere - the session header, the GUI, the caches - and the backslash is
@@ -71,6 +77,13 @@ crosses the 9p share. What to know about the one substrate there is:
 - **`bubblewrap` must be installed**, or both providers fail immediately. The
   usability probe re-runs after a failure, so installing bubblewrap while the app
   runs is believed on the next command; only a success is cached.
+- **The port poller keeps the resident agent permanently warm.** The
+  `DSH_WSL_PORTS` snapshot refreshes through the shared resident agent every
+  `portsRefreshMs` (10 s by default, well inside the agent's idle timeout), so
+  while the app runs the agent never idles out: one `wsl.exe` and one
+  in-distro agent process stay resident per pinned distro even with no command
+  in flight. Raising `portsRefreshMs` past the agent's idle timeout restores
+  idle shutdown, at the cost of staler port facts.
 - **A confined command's `/tmp` is not the write tool's `/tmp`.** `workspace-write`
   mounts a fresh tmpfs at `/tmp` for the command — that is what makes it ephemeral —
   while the file tools' fence grants the distro's *real* `/tmp`. Both are writable, so

package/docs/README.zh.md

@@ -28,7 +28,7 @@ dsh --profile wsl                                  # 4. 启动
 
 然后在 GUI 里打开 `\\wsl.localhost\<子系统>\...` 下的文件夹。选择器会在根一级列出每个已安装的子系统，**New terminal** 会在子系统里打开 shell。
 
-还需要在子系统里安装 **bubblewrap**：运行 `npm run bootstrap -- <子系统> --install`（只读检测去掉 `--install`），或直接执行 `wsl.exe -d <子系统> -u root -- apt-get install -y bubblewrap`。没有它每条命令都会失败关闭，见[沙箱](#沙箱)。
+还需要在子系统里安装 **bubblewrap**：运行 `pnpm run bootstrap -- <子系统> --install`（只读检测去掉 `--install`），或直接执行 `wsl.exe -d <子系统> -u root -- apt-get install -y bubblewrap`。没有它每条命令都会失败关闭，见[沙箱](#沙箱)。
 
 卸载：`dsh plugin --profile wsl remove dsh-plugin-wsl-env`。升级：再执行一次同样的 `add` 命令。
 
@@ -68,7 +68,7 @@ dsh --profile wsl                                  # 4. 启动
 - **Git 凭据共享**：让子系统里的 git 使用 Windows 侧的 Git Credential Manager，避免每次输密码：
   `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"`
   （路径按 Windows 侧 Git 的安装位置调整；WSL2 的 localhost 转发是平台行为，子系统内监听的端口 Windows 直接可达。）
-- **路径与性能**：模型看到并操作的是子系统内的 Linux 路径（`/home/...`），写入子系统自身的 ext4；`/mnt/c` 通向 Windows 磁盘但走 9p，大批量小文件操作明显慢——重 IO 的项目请放在子系统文件系统内。`npm run bootstrap -- <子系统>` 会一并报告 ripgrep、git、inotifywait（搜索、快照与监视的后端）是否就位。
+- **路径与性能**：模型看到并操作的是子系统内的 Linux 路径（`/home/...`），写入子系统自身的 ext4；`/mnt/c` 通向 Windows 磁盘但走 9p，大批量小文件操作明显慢——重 IO 的项目请放在子系统文件系统内。`pnpm run bootstrap -- <子系统>` 会一并报告 ripgrep、git、inotifywait（搜索、快照与监视的后端）是否就位。
 - **WSLENV 透传**：WSL 只导入 `WSLENV` 中列出的变量。本插件按前缀放行托管的 `DSH_*` 命名空间，其中带 Windows 路径的两个（`DSH_HOME`、`DSH_PROFILE_DIR`）加 `/p` 让 WSL 翻译成 `/mnt/c/...`。`PATH` 故意不透传——否则 Windows 的 PATH 会覆盖子系统自身的 PATH。
 
 ## 架构
@@ -105,7 +105,7 @@ preset-wsl（wsl agent preset；其服务运行在 isolate realm 内）
 
 **bubblewrap 是必需项，缺失即失败关闭。** 没有它时，每条受限命令都报 `SANDBOX_UNAVAILABLE`，而不是不受约束地运行。要退出约束就在任一 provider 上设 `sandbox: false`，工具层会如实告诉模型这些操作没有沙箱。
 
-**上报的强制程度是 `partial` 而不是 `full`。** 子系统里的进程仍可经 WSL interop 执行 Windows 程序（例如 `/mnt/c/.../*.exe`），bubblewrap 管不到它。`npm run probe:sandbox` 会在你的机器上演示这条边界。
+**上报的强制程度是 `partial` 而不是 `full`。** 子系统里的进程仍可经 WSL interop 执行 Windows 程序（例如 `/mnt/c/.../*.exe`），bubblewrap 管不到它。`pnpm run probe:sandbox` 会在你的机器上演示这条边界。
 
 设计见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#sandbox)，插件不做的事情见 [docs/LIMITATIONS.md](LIMITATIONS.md)。
 
@@ -113,37 +113,37 @@ preset-wsl（wsl agent preset；其服务运行在 isolate realm 内）
 
 | 现象 | 原因 | 处理 |
 |---|---|---|
-| 每条命令都报 `SANDBOX_UNAVAILABLE` | 子系统里没有 `bubblewrap` | 执行 `npm run bootstrap -- <子系统> --install`，或在两个 provider 上都设 `sandbox: false` |
+| 每条命令都报 `SANDBOX_UNAVAILABLE` | 子系统里没有 `bubblewrap` | 执行 `pnpm run bootstrap -- <子系统> --install`，或在两个 provider 上都设 `sandbox: false` |
 | 命令或写入在会话目录之外被拒绝 | `workspace-write` 的预期行为 | 接受工具给出的放宽权限提示，或把会话直接开在需要的目录上 |
 | 连工作区内的写入也被拒绝 | 会处在 `read-only` 模式 | 切换权限选择器 |
 | `dsh plugin add` 提示"没有激活任何层" | 依赖之前已经装过，`add` 没有需要记录的内容 | 先执行 `dsh plugin --profile wsl remove dsh-plugin-wsl-env`，再装一次 |
 | 终端打开后仍然是 `cmd.exe` | 这一层里的 `terminal-controller` 行没有生效 | 用 `dsh --profile wsl --dump-config` 确认能看到 `shell: { path: wsl.exe, name: WSL }` |
 | 改了 `lib/` 但不生效 | ES module 缓存 | 重启应用 |
 | 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在子系统内开发时用运行时镜像，见[开发](#开发) |
-| `glob`/`grep` 很慢 | 子系统内没有 rg 时，搜索只能报 rg 自己的 "command not found"；Windows 目录的搜索走宿主原生 rg，不受影响 | 运行 `npm run bootstrap -- <子系统> --install`（安装 ripgrep）；子系统工作区的搜索始终跑子系统内的 rg，绝不遍历 9p 共享 |
+| `glob`/`grep` 很慢 | 子系统内没有 rg 时，搜索只能报 rg 自己的 "command not found"；Windows 目录的搜索走宿主原生 rg，不受影响 | 运行 `pnpm run bootstrap -- <子系统> --install`（安装 ripgrep）；子系统工作区的搜索始终跑子系统内的 rg，绝不遍历 9p 共享 |
 | 终端活动显示 `unknown` | 仅在常驻代理不可用时出现——distro 终端从子系统内部观测（`/proc` 中扫描 `DSH_TERMINAL_ID` 标记：shell 独处为 `idle`，运行任何命令为 `busy`） | 确认子系统在运行；空闲终端会在控制器的无人值守超时（默认 2 小时）后自动回收，`terminalIdleReclaim: false` 恢复手动关闭 |
 | 结果里出现 `FS_*` 码 | 码本身说明了是谁拒绝的、以及怎样解除 | 见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#error-codes) 的错误码表 |
 
 ## 开发
 
 ```bash
-npm test                     # 风格与打包检查、语法检查、单元测试
-npm run test:coverage        # 带覆盖率阈值的单元测试（需 Node 22.8+）
-npm run probe:sandbox        # 在子系统里实测 bubblewrap 能约束什么、不能约束什么
-npm run probe                # 文件系统探针，需要真实子系统（仅 Windows + WSL）
-npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
-npm run probe:terminal       # 通过终端 provider 打开一个 PTY
-npm run probe:substrate      # 用真实 wsl.exe 传输驱动 agent 文件基座（在子系统内运行）
-npm run probe:watch          # 在真实目录上装上 distro 内轮询 watcher（在子系统内运行）
-npm run probe:agent          # resident 与 one-shot 的回退不变量对比腿（在子系统内运行）
-npm run probe:exec           # agent 执行句柄：超时、杀停、cwd 失败（在子系统内运行）
-npm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）
-npm run probe:picker         # 列出选择器的根级、拒绝路径与上限（仅 Windows + WSL）
-npm run probe:mode           # 哪些 POSIX 权限事实能穿过共享层（仅需 Windows node）
-npm run probe:sandbox-off    # 验证 sandbox: false 确实解除两侧约束（仅 Windows + WSL）
+pnpm test                     # 风格与打包检查、语法检查、单元测试
+pnpm run test:coverage        # 带覆盖率阈值的单元测试（需 Node 22.8+）
+pnpm run probe:sandbox        # 在子系统里实测 bubblewrap 能约束什么、不能约束什么
+pnpm run probe                # 文件系统探针，需要真实子系统（仅 Windows + WSL）
+pnpm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
+pnpm run probe:terminal       # 通过终端 provider 打开一个 PTY
+pnpm run probe:substrate      # 用真实 wsl.exe 传输驱动 agent 文件基座（在子系统内运行）
+pnpm run probe:watch          # 在真实目录上装上 distro 内轮询 watcher（在子系统内运行）
+pnpm run probe:agent          # resident 与 one-shot 的回退不变量对比腿（在子系统内运行）
+pnpm run probe:exec           # agent 执行句柄：超时、杀停、cwd 失败（在子系统内运行）
+pnpm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）
+pnpm run probe:picker         # 列出选择器的根级、拒绝路径与上限（仅 Windows + WSL）
+pnpm run probe:mode           # 哪些 POSIX 权限事实能穿过共享层（仅需 Windows node）
+pnpm run probe:sandbox-off    # 验证 sandbox: false 确实解除两侧约束（仅 Windows + WSL）
 ```
 
-这个包没有依赖，被测模块只 import Node 内置模块，所以不需要先安装任何东西。CI 在 Linux 和 Windows 上用 Node 20、22、24 运行 `npm test`，并在 Node 24 上运行 `npm run test:coverage`。
+首次运行前先 `pnpm install` 一次，复原钉版的开发依赖：0.7.x 的测试会 import 钉版的 `@deepseek-ai/*` 包（组合与启动测试跑的是 loader 的真实 patch 算法），运行时包本身仍然保持零依赖。pnpm 由 `packageManager` 字段解析，任何开了 corepack 的 Node 都能直接用。CI 在 Linux 和 Windows 上用 Node 22、24 运行 `pnpm test`，并在 Node 24 上运行 `pnpm run test:coverage`；`engines` 与 harness 宿主自身的下限（`^22.19.0 || >=24.0.0`）保持一致。
 
 [docs/ARCHITECTURE.md](ARCHITECTURE.md) 有文件布局、挂载方式和沙箱设计；[CONTRIBUTING.md](../CONTRIBUTING.md) 有开发循环、完整质量门清单和已验证内容。
 

package/lib/agent-confined.d.ts

@@ -0,0 +1,42 @@
+import { WslAgent } from "./agent.js";
+/** One confinement request. */
+export interface ConfinedAgentRequest {
+    /** The distro to run in. */
+    distro: string;
+    /** The `wsl.exe` path. */
+    wslPath?: string;
+    /**
+     * The RESOLVED file-effect policy: the profile binds exactly what the mode
+     * grants.
+     */
+    policy: {
+        mode: string;
+        workspaceRoot: string;
+    };
+    /**
+     * Shadow `/mnt` with an empty tmpfs in the resident's profile; part of the
+     * cache key, since it changes the mount table the resident lives under.
+     */
+    maskWindowsDrive?: boolean;
+    /**
+     * Default TRUE: workspace-write binds the distro's real `/tmp` read-write
+     * into the resident's profile, so a write the fence approved lands where
+     * every reader reads. `false` restores the ephemeral tmpfs — for tests and
+     * probes, not production: a `/tmp` write behind an ephemeral mount reports
+     * success into a directory no reader can see, which is the bug this default
+     * exists to prevent.
+     */
+    realTmp?: boolean;
+}
+/**
+ * The confined agent for one distro and one resolved policy, created on first
+ * use and shared for the process lifetime. A success is remembered; a failed
+ * start is not (the agent's own rebuild rules take over from there).
+ *
+ * @param request - the confinement request.
+ * @returns the confined resident for this key.
+ */
+export declare function confinedAgent({ distro, wslPath, policy, maskWindowsDrive, realTmp }: ConfinedAgentRequest): WslAgent;
+/** Test hook: forget every confined resident (the plain agent has no factory state). */
+export declare function resetConfinedAgents(): void;
+export default confinedAgent;

package/lib/agent-confined.js

@@ -25,63 +25,47 @@
  * a third copy, so nothing compared production's command with a working one and
  * every confined mutation failed the resident's handshake.
  *
+ * This is a TypeScript source built to `lib/agent-confined.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
  * @module dsh-plugin-wsl/agent-confined
  */
 import { bwrapArgvPrefix } from "./bwrap.js";
 import { toLinuxPath } from "./paths.js";
 import { agentScriptDigest, agentScriptPath } from "./agent-shared.js";
 import { WslAgent } from "./agent.js";
-
 const confinedAgents = new Map();
-
 /**
  * The confined agent for one distro and one resolved policy, created on first
  * use and shared for the process lifetime. A success is remembered; a failed
  * start is not (the agent's own rebuild rules take over from there).
  *
- * @param {object} request - the confinement request.
- * @param {string} request.distro - the distro to run in.
- * @param {string} [request.wslPath] - the `wsl.exe` path.
- * @param {{mode: string, workspaceRoot: string}} request.policy - the RESOLVED
- *   file-effect policy: the profile binds exactly what the mode grants.
- * @param {boolean} [request.maskWindowsDrive] - shadow `/mnt` with an empty
- *   tmpfs in the resident's profile; part of the cache key, since it changes
- *   the mount table the resident lives under.
- * @param {boolean} [request.realTmp] - default TRUE: workspace-write binds the
- *   distro's real `/tmp` read-write into the resident's profile, so a write
- *   the fence approved lands where every reader reads. `false` restores the
- *   ephemeral tmpfs — for tests and probes, not production: a `/tmp` write
- *   behind an ephemeral mount reports success into a directory no reader can
- *   see, which is the bug this default exists to prevent.
- * @returns {WslAgent} the confined resident for this key.
+ * @param request - the confinement request.
+ * @returns the confined resident for this key.
  */
 export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindowsDrive = false, realTmp = true }) {
-  const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
-  let agent = confinedAgents.get(key);
-  if (agent === undefined) {
-    agent = new WslAgent({
-      distro,
-      wslPath,
-      scriptPath: toLinuxPath(agentScriptPath),
-      expectedDigest: agentScriptDigest,
-      // The prefix is a whole command from the distro's point of view — program,
-      // profile, `--` — because the transport inserts it between
-      // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
-      // `spawnDefault`). Both confinement sites share that assembly in
-      // `lib/bwrap.js`, whose module doc records what happened when they did not.
-      argvPrefix: bwrapArgvPrefix(
-        { mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) },
-        { maskWindowsDrive, realTmp },
-      ),
-    });
-    confinedAgents.set(key, agent);
-  }
-  return agent;
+    const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
+    let agent = confinedAgents.get(key);
+    if (agent === undefined) {
+        agent = new WslAgent({
+            distro,
+            wslPath,
+            scriptPath: toLinuxPath(agentScriptPath),
+            expectedDigest: agentScriptDigest,
+            // The prefix is a whole command from the distro's point of view — program,
+            // profile, `--` — because the transport inserts it between
+            // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
+            // `spawnDefault`). Both confinement sites share that assembly in
+            // `lib/bwrap.js`, whose module doc records what happened when they did not.
+            argvPrefix: bwrapArgvPrefix({ mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) }, { maskWindowsDrive, realTmp }),
+        });
+        confinedAgents.set(key, agent);
+    }
+    return agent;
 }
-
 /** Test hook: forget every confined resident (the plain agent has no factory state). */
 export function resetConfinedAgents() {
-  confinedAgents.clear();
+    confinedAgents.clear();
 }
-
 export default confinedAgent;

package/lib/agent-errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The error a {@link WslAgent} rejects with when the resident process is out
+ * for this host process — the executor's cue to fall back to the one-shot
+ * `wsl.exe` path. Deliberately its own class: callers must not confuse
+ * "the agent cannot serve" with a failure of the command itself.
+ *
+ * This is a TypeScript source built to `lib/agent-errors.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/agent-errors
+ */
+export declare class AgentUnavailableError extends Error {
+    /**
+     * @param message - why the agent is out, for the log.
+     */
+    constructor(message: string);
+}
+/**
+ * The request's workdir could not be entered inside the distro. Carries the
+ * Linux path so a caller can synthesize the same diagnostic the one-shot
+ * `wsl.exe` path produces from the relay's `chdir(...) failed` text.
+ */
+export declare class CwdError extends Error {
+    /** The path that could not be entered, in the distro's own spelling. */
+    linuxPath: string;
+    /**
+     * @param linuxPath - the path that could not be entered.
+     */
+    constructor(linuxPath: string);
+}

package/lib/agent-errors.js

@@ -4,30 +4,33 @@
  * `wsl.exe` path. Deliberately its own class: callers must not confuse
  * "the agent cannot serve" with a failure of the command itself.
  *
+ * This is a TypeScript source built to `lib/agent-errors.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
  * @module dsh-plugin-wsl/agent-errors
  */
 export class AgentUnavailableError extends Error {
-  /**
-   * @param {string} message - why the agent is out, for the log.
-   */
-  constructor(message) {
-    super(message);
-    this.name = "AgentUnavailableError";
-  }
+    /**
+     * @param message - why the agent is out, for the log.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "AgentUnavailableError";
+    }
 }
-
 /**
  * The request's workdir could not be entered inside the distro. Carries the
  * Linux path so a caller can synthesize the same diagnostic the one-shot
  * `wsl.exe` path produces from the relay's `chdir(...) failed` text.
  */
 export class CwdError extends Error {
-  /**
-   * @param {string} linuxPath - the path that could not be entered.
-   */
-  constructor(linuxPath) {
-    super(`could not enter working directory "${linuxPath}"`);
-    this.name = "CwdError";
-    this.linuxPath = linuxPath;
-  }
+    /**
+     * @param linuxPath - the path that could not be entered.
+     */
+    constructor(linuxPath) {
+        super(`could not enter working directory "${linuxPath}"`);
+        this.name = "CwdError";
+        this.linuxPath = linuxPath;
+    }
 }

package/lib/agent-exec.d.ts

@@ -0,0 +1,159 @@
+/**
+ * An agent-backed implementation of the shell execution handle.
+ *
+ * `LocalBashExecutor.executeArgv` builds its handle around a subprocess spawn:
+ * live output readers with byte offsets, spill files beyond the collect
+ * budget, a deadline that kills the Windows process tree. This module builds
+ * the SAME handle shape around one agent `exec` — the shape `dsh-tool-bash`
+ * consumes, so the tool layer cannot tell which path ran. The deliberate
+ * deviations, documented here rather than hidden:
+ *
+ * - **No spill files; the capture cap is the agent's.** The EXEC frame
+ *   carries the caller's per-stream budget and the AGENT cuts stdout and
+ *   stderr at it, so a chatty command costs bounded distro memory AND bounded
+ *   host memory; the RES line's flags say which streams were cut and the
+ *   handle reports them as `truncated: true`. What the budget spares is the
+ *   upstream spill machinery: the capture is still whole-in-memory, just
+ *   whole-at-a-bounded-size.
+ * - **Killed commands report `SIGTERM`**, not a raw exit status: the
+ *   in-distro timeout and `kill()` both mean "we stopped it", and upstream
+ *   reports its own kills the same way.
+ *
+ * Pure shaping over an injected runner, so the handle semantics are
+ * unit-testable without a distro.
+ *
+ * This is a TypeScript source built to `lib/agent-exec.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/agent-exec
+ */
+/** The request one agent `exec` carries. */
+export interface AgentExecRequest {
+    /** Linux workdir. */
+    cwd: string;
+    /** The distro-side argv. */
+    argv: string[];
+    /** Whole-command budget. */
+    timeoutMs?: number;
+    /** Extra environment for this request only. */
+    env?: Record<string, string>;
+    /** Per-stream capture ceiling. */
+    maxOutputBytes?: number;
+    /** The caller's cancellation. */
+    signal?: AbortSignal;
+}
+/** What an agent `exec` resolves with. */
+export interface AgentExecResult {
+    /** The command's exit code. */
+    exitCode: number;
+    /** The captured stdout. */
+    stdout: Buffer;
+    /** The captured stderr. */
+    stderr: Buffer;
+    /** The agent's per-stream capture-cap flags. */
+    truncated?: {
+        stdout: boolean;
+        stderr: boolean;
+    };
+}
+/** The {@link WslAgent}-like runner this module drives. */
+export interface AgentExecRunner {
+    /** Run one command. */
+    exec: (request: AgentExecRequest) => Promise<AgentExecResult>;
+}
+/** How the exec promise settled: the result, or the failure to propagate. */
+export type SettledExec = {
+    ok: true;
+    result: AgentExecResult;
+    error?: undefined;
+} | {
+    ok: false;
+    result?: undefined;
+    error: unknown;
+};
+/** The memory-reader slice of one output stream. */
+export interface OutputReader {
+    /** Read the stream from a byte offset. */
+    readFrom: (fromByte: number) => {
+        text: string;
+        lossy: boolean;
+        nextOffset: number;
+    };
+}
+/** One settled foreground command, the shape `dsh-tool-bash` consumes. */
+export interface AgentExecutionHandle {
+    /** The lifecycle state. */
+    status: "running" | "completed" | "killed";
+    /** The exit code; null until settled or when killed. */
+    exitCode: number | null;
+    /** The terminating signal; null on a clean exit. */
+    signal: string | null;
+    /** The live output readers. */
+    observed: {
+        stdout: OutputReader;
+        stderr: OutputReader;
+    };
+    /** Settles when the command settles. */
+    done: Promise<void>;
+    /** The incremental delta reader. */
+    readOutput: () => {
+        delta: string;
+        lossy: boolean;
+    };
+    /** Stop the command; true on the first call only. */
+    kill: () => boolean;
+    /** The canonical bash result. */
+    result: () => Promise<{
+        exitCode: number | null;
+        signal: string | null;
+        timedOut: boolean;
+        aborted: boolean;
+        timeoutMs: number;
+        stdout: {
+            text: string;
+            lossy: boolean;
+            truncated: boolean;
+        };
+        stderr: {
+            text: string;
+            lossy: boolean;
+            truncated: boolean;
+        };
+    }>;
+}
+/**
+ * Run one command through the agent and present it as an execution handle.
+ *
+ * @param request - the execution request.
+ * @returns the execution handle (`status`, `exitCode`, `signal`, `observed`,
+ *   `done`, `readOutput`, `kill`, `result`).
+ */
+export declare function agentExecutionHandle({ agent, cwd, argv, timeoutMs, maxOutputBytes, signal, onStarted }: {
+    /**
+     * The {@link WslAgent}-like runner: `exec` accepting
+     * `{cwd, argv, timeoutMs, signal}` and resolving `{exitCode, stdout, stderr}`;
+     * throws `AgentUnavailableError` when out.
+     */
+    agent: AgentExecRunner;
+    /** Linux workdir. */
+    cwd: string;
+    /** The distro-side argv, bwrap-wrapped when confined. */
+    argv: string[];
+    /**
+     * Whole-command budget; the agent TERMs at the ceiling second and KILLs
+     * after its grace.
+     */
+    timeoutMs?: number;
+    /**
+     * Per-stream capture ceiling the agent enforces; the handle reports a cut
+     * stream as `truncated: true`.
+     */
+    maxOutputBytes?: number;
+    /** The caller's cancellation. */
+    signal?: AbortSignal;
+    /**
+     * Provider-facts hook, called synchronously before the handle can settle.
+     */
+    onStarted?: (proc: object) => void;
+}): AgentExecutionHandle;