dsh-win-multi-bash 0.1.2 → 0.3.0

package/lib/bash-git/index.js

@@ -254,7 +254,10 @@ var GitBashExecutor = class extends LocalBashExecutor {
 	internals = {};
 	sandboxStance;
 	probeTimeoutMs;
-	confinedVerdict;
+	/** Memoized probe promise; the provider's `confine` is async as of 0.1.7. */
+	confinedProbe;
+	/** The verdict `resolveSandboxMode` settled on, read back by the sync getter. */
+	sandboxModeVerdict;
 	constructor(ctx, config) {
 		super(ctx, config);
 		const entry = config;
@@ -264,14 +267,24 @@ var GitBashExecutor = class extends LocalBashExecutor {
 	}
 	/**
 	 * The capability fact: the policy default mode while confinement is usable.
-	 * With `requireSandbox`, the mode is declared even when the probe fails, so
-	 * the tool layer advertises escalation (`sandbox_permissions`) and the
-	 * executor can refuse unconfined runs outside danger-full-access.
+	 * The probe is async (the provider's `confine` returns a promise), so the
+	 * tool layer awaits {@link resolveSandboxMode} before reading this; until
+	 * then the mode is undeclared.
 	 */
 	get sandboxMode() {
-		if (this.sandboxStance === "none") return void 0;
-		if (this.requireSandbox) return this.ctx.sandboxPolicy.defaultMode;
-		return this.probeConfinedOnce() ? this.ctx.sandboxPolicy.defaultMode : void 0;
+		return this.sandboxModeVerdict;
+	}
+	/**
+	 * Settle this executor's advertised sandbox mode. With `requireSandbox`,
+	 * the mode is declared even when the probe fails, so the tool layer
+	 * advertises escalation (`sandbox_permissions`) and the executor can refuse
+	 * unconfined runs outside danger-full-access.
+	 * @returns the mode to advertise, or `undefined` for an unconfining deployment.
+	 */
+	async resolveSandboxMode() {
+		if (this.sandboxStance === "none") return this.sandboxModeVerdict = void 0;
+		if (this.requireSandbox) return this.sandboxModeVerdict = this.ctx.sandboxPolicy.defaultMode;
+		return this.sandboxModeVerdict = await this.probeConfinedOnce() ? this.ctx.sandboxPolicy.defaultMode : void 0;
 	}
 	/** The exact argv every (un)confined command runs through. */
 	gitArgv(spec) {
@@ -291,25 +304,29 @@ var GitBashExecutor = class extends LocalBashExecutor {
 	bashPath() {
 		const path = this.tryBashPath();
 		if (path !== void 0) return path;
-		throw new Error(`bash-git: Git Bash was not found (probed ${candidateBashPaths().join(", ")} and the GitForWindows registry). Install Git for Windows or set gitBash.bashPath in the shell-select config.`);
+		throw new Error(`bash-git: Git Bash was not found (probed ${candidateBashPaths().join(", ")} and the GitForWindows registry). Install Git for Windows or set gitBash.bashPath on the git_bash tool row.`);
 	}
 	/**
 	* Probe whether the windows-acl runner can launch bash.exe, once per
-	* executor lifetime (lazy: the first sandboxMode read or the first routed
-	* command). Runs a trivial confined `exit 0` synchronously (mirroring
-	* sandbox-local's defaultProbeWindowsAcl shape); a spawn rejection, a
-	* runner-failure exit, or a missing bash.exe all mean no confinement.
+	* executor lifetime (lazy: the first {@link resolveSandboxMode} await or the
+	* first routed command). Wraps a trivial `exit 0` through the provider and
+	* runs it (mirroring sandbox-local's defaultProbeWindowsAcl shape); a wrap
+	* rejection, a spawn rejection, or a non-zero exit all mean no confinement.
+	* @returns the memoized verdict.
 	*/
 	probeConfinedOnce() {
-		if (this.confinedVerdict !== void 0) return this.confinedVerdict;
+		this.confinedProbe ??= this.probeConfined();
+		return this.confinedProbe;
+	}
+	async probeConfined() {
 		const probe = this.internals.probeConfined;
-		if (probe !== void 0) return this.confinedVerdict = probe();
+		if (probe !== void 0) return probe();
 		const bashPath = this.tryBashPath();
-		if (bashPath === void 0) return this.confinedVerdict = false;
+		if (bashPath === void 0) return false;
 		const root = this.ctx.sandboxPolicy.resolve().workspaceRoot;
 		let confined;
 		try {
-			confined = this.ctx.sandbox.confine([
+			confined = await this.ctx.sandbox.confine([
 				bashPath,
 				"-c",
 				"exit 0"
@@ -318,93 +335,115 @@ var GitBashExecutor = class extends LocalBashExecutor {
 				workspaceRoot: root
 			});
 		} catch {
-			return this.confinedVerdict = false;
+			return false;
 		}
 		const runner = confined.argv[0];
-		if (runner === void 0) return this.confinedVerdict = false;
+		if (runner === void 0) return false;
 		const probeRun = spawnSync(runner, confined.argv.slice(1), {
 			timeout: this.probeTimeoutMs,
 			cwd: root,
 			stdio: "ignore"
 		});
-		return this.confinedVerdict = probeRun.status === 0;
+		return probeRun.status === 0;
 	}
 	confinedPolicy(spec) {
 		return spec.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
 	}
-	async run(spec) {
+	/** Per-process confinement facts retained until settlement (bash-sandbox pattern). */
+	processFacts = /* @__PURE__ */ new Map();
+	/**
+	 * Execute one resolved spec through the confined (or unconfined) Git Bash
+	 * argv. Foreground is a property of awaiting `result()`, not of the call —
+	 * one handle serves both call styles, as the 0.1.7 seam defines it.
+	 * Confinement is probe-gated; runner evidence at execution time falls back
+	 * to an unconfined run (the documented lazy contract) so a windows-acl
+	 * runner that cannot launch MSYS bash never bricks the backend.
+	 * @param spec - the resolved execution spec from {@link resolve}.
+	 * @returns the live handle; sandbox facts land on both `proc.sandbox` (at
+	 *   settlement) and the decorated `result()`.
+	 */
+	async execute(spec) {
 		const policy = this.confinedPolicy(spec);
-		if (policy.mode === "danger-full-access") return {
-			...await this.runArgv(spec, this.gitArgv(spec)),
+		if (policy.mode === "danger-full-access") return GitBashExecutor.decorateResult(await this.executeArgv(spec, this.gitArgv(spec)), (result) => ({
+			...result,
 			sandbox: {
 				mode: "danger-full-access",
 				denied: false
 			}
-		};
-		if (this.sandboxStance === "none") return this.runArgv(spec, this.gitArgv(spec));
-		if (!this.probeConfinedOnce()) {
+		}));
+		if (this.sandboxStance === "none") return this.executeArgv(spec, this.gitArgv(spec));
+		if (!await this.probeConfinedOnce()) {
 			if (this.requireSandbox) throw new Error("bash-git: sandbox unavailable — the windows-acl runner cannot confine MSYS bash (probe failed); refusing to run unconfined under " + policy.mode + " mode. Fix the sandbox or retry the command with sandbox_permissions: \"danger-full-access\" and a justification.");
-			return this.runArgv(spec, this.gitArgv(spec));
+			return this.executeArgv(spec, this.gitArgv(spec));
 		}
-		const confined = this.ctx.sandbox.confine(this.gitArgv(spec), {
-			...policy,
-			mode: policy.mode
-		});
-		let result;
-		try {
-			result = await this.runArgv(spec, confined.argv);
-		} catch (error) {
-			if (spec.signal?.aborted === true) spec.signal.throwIfAborted();
-			if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) return this.runArgv(spec, this.gitArgv(spec));
-			throw error;
-		}
-		if (classifyRunnerFailure(result.exitCode, result.stderr.text, confined.runnerFailureRules) !== void 0) return this.runArgv(spec, this.gitArgv(spec));
-		return {
-			...result,
-			sandbox: {
+		let confined;
+		const proc = await this.executeArgv(spec, async (signal) => {
+			confined = await this.ctx.sandbox.confine(this.gitArgv(spec), {
+				...policy,
+				mode: policy.mode
+			}, signal);
+			return confined.argv;
+		}, (started) => {
+			const facts = confined;
+			if (facts === void 0) return;
+			this.processFacts.set(started, {
 				mode: policy.mode,
-				denied: classifyDenial(result, confined.denialSignatures),
-				enforcement: confined.enforcement
-			}
-		};
-	}
-	/** Per-process confinement facts retained until settlement (bash-sandbox pattern). */
-	processFacts = /* @__PURE__ */ new Map();
-	start(spec) {
-		const policy = this.confinedPolicy(spec);
-		if (policy.mode === "danger-full-access") return this.startArgv(spec, this.gitArgv(spec));
-		if (this.sandboxStance === "none") return this.startArgv(spec, this.gitArgv(spec));
-		if (!this.probeConfinedOnce()) {
-			if (this.requireSandbox) throw new Error("bash-git: sandbox unavailable — the windows-acl runner cannot confine MSYS bash (probe failed); refusing to run unconfined under " + policy.mode + " mode. Fix the sandbox or retry the command with sandbox_permissions: \"danger-full-access\" and a justification.");
-			return this.startArgv(spec, this.gitArgv(spec));
-		}
-		const confined = this.ctx.sandbox.confine(this.gitArgv(spec), {
-			...policy,
-			mode: policy.mode
+				enforcement: facts.enforcement,
+				denialSignatures: facts.denialSignatures,
+				runnerFailureRules: facts.runnerFailureRules,
+				runnerProgram: facts.argv[0],
+				workdir: spec.workdir
+			});
 		});
-		let proc;
-		try {
-			proc = this.startArgv(spec, confined.argv);
-		} catch (error) {
-			if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) return this.startArgv(spec, this.gitArgv(spec));
+		/** Re-run the command unconfined after runner evidence proved confinement unavailable. */
+		const unconfinedFallback = async () => (await this.executeArgv(spec, this.gitArgv(spec))).result();
+		return GitBashExecutor.decorateResult(proc, async (result) => {
+			if (confined === void 0) return {
+				...result,
+				sandbox: {
+					mode: policy.mode,
+					denied: false
+				}
+			};
+			if (classifyRunnerFailure(result.exitCode, result.stderr.text, confined.runnerFailureRules) !== void 0) return unconfinedFallback();
+			return {
+				...result,
+				sandbox: {
+					mode: policy.mode,
+					denied: classifyDenial(result, confined.denialSignatures),
+					enforcement: confined.enforcement
+				}
+			};
+		}, async (error) => {
+			if (spec.signal?.aborted === true) spec.signal.throwIfAborted();
+			if (confined !== void 0 && isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) return unconfinedFallback();
 			throw error;
-		}
-		this.processFacts.set(proc, {
-			mode: policy.mode,
-			enforcement: confined.enforcement,
-			denialSignatures: confined.denialSignatures,
-			runnerFailureRules: confined.runnerFailureRules,
-			runnerProgram: confined.argv[0],
-			workdir: spec.workdir
 		});
+	}
+	/**
+	 * Decorate the handle's foreground projection in place, memoized once. The
+	 * handle keeps its identity (never wrapped in a second object) because the
+	 * per-process facts and `onProcessDone` key on the exact instance.
+	 * @param proc - the live execution handle.
+	 * @param map - maps the settled result.
+	 * @param mapError - maps a provider rejection.
+	 * @returns the same handle, with `result()` decorated.
+	 */
+	static decorateResult(proc, map, mapError) {
+		const base = proc.result.bind(proc);
+		let decorated;
+		proc.result = () => {
+			decorated ??= base().then(map, mapError);
+			return decorated;
+		};
 		return proc;
 	}
 	/** Stamp per-process sandbox facts before `done` settles (bash-sandbox semantics). */
-	onProcessDone(proc, stderr, spawnFailed, spawnError) {
+	onProcessDone(proc, stderr, providerRejected, providerError) {
 		const facts = this.processFacts.get(proc);
 		if (facts !== void 0) {
 			this.processFacts.delete(proc);
-			proc.sandbox = (spawnFailed ? isRunnerSpawnFailure(spawnError, facts.runnerProgram, facts.workdir) : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== void 0) ? {
+			proc.sandbox = (providerRejected ? isRunnerSpawnFailure(providerError, facts.runnerProgram, facts.workdir) : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== void 0) ? {
 				mode: facts.mode,
 				denied: false,
 				enforcement: facts.enforcement,
@@ -415,7 +454,7 @@ var GitBashExecutor = class extends LocalBashExecutor {
 				enforcement: facts.enforcement
 			};
 		}
-		super.onProcessDone(proc, stderr, spawnFailed, spawnError);
+		super.onProcessDone(proc, stderr, providerRejected, providerError);
 	}
 	resolve(request) {
 		const bashPath = this.tryBashPath();

package/lib/bash-wsl/index.js

@@ -165,6 +165,16 @@ var WslBashExecutor = class extends LocalBashExecutor {
 		if (this.requireSandbox) return this.ctx.sandboxPolicy.defaultMode;
 		return this.requireBwrapUsable() ? this.ctx.sandboxPolicy.defaultMode : void 0;
 	}
+	/**
+	 * The awaitable form of {@link sandboxMode}. The bwrap probe spawns
+	 * `wsl.exe` synchronously, so the verdict is already available; this exists
+	 * so both backends present the tool layer the same contract (git-bash's
+	 * provider probe is genuinely async).
+	 * @returns the mode to advertise, or `undefined` for an unconfining deployment.
+	 */
+	async resolveSandboxMode() {
+		return this.sandboxMode;
+	}
 	/** Auto: false means run unconfined. Explicit bwrap: a failed probe throws loud. */
 	requireBwrapUsable() {
 		if (this.probeBwrapOnce()) return true;
@@ -223,19 +233,26 @@ var WslBashExecutor = class extends LocalBashExecutor {
 	payload(command) {
 		return `echo ${Buffer.from(command, "utf8").toString("base64")} | base64 -d | bash`;
 	}
-	/** The workdir `resolve()` fills when a request omits one. */
-	defaultWorkdir() {
-		return this.config.cwd ?? process.cwd();
-	}
 	/**
-	* The plain WSL argv for one spec (no sandbox). `--cd` is passed only when
-	* the workdir differs from the default, so the subprocess cwd and the WSL
-	* start directory agree without a redundant wsl.exe translation; a Linux
-	* workdir passes through verbatim.
+	* The plain WSL argv for one spec (no sandbox).
+	*
+	* `--cd` always carries the resolved workdir. That is the auto-cd contract:
+	* a command the caller started without an explicit `workdir` still lands in
+	* the WSL view of the session directory (`/mnt/<drive>/...`) rather than
+	* wherever the distro happens to default to. wsl.exe does translate an
+	* inherited Windows cwd on its own, but only for a path it can translate
+	* and only under the distro's automount settings — passing the workdir
+	* explicitly keeps the start directory a property of the spec instead of a
+	* property of the distro. A Linux workdir passes through verbatim.
+	*
+	* (This used to skip `--cd` when the workdir equaled the configured
+	* default. That branch was dead — it compared against the `cwd` volatile
+	* *wrapper* rather than its value, so it never matched — and skipping is
+	* not worth reviving: the explicit form is what the auto-cd feature is
+	* specified as, and it is the behaviour every deployment already runs.)
 	*/
 	argv(spec) {
-		const head = [this.wslPath()];
-		if (spec.workdir !== this.defaultWorkdir()) head.push("--cd", spec.workdir);
+		const head = [this.wslPath(), "--cd", spec.workdir];
 		const distro = this.distro();
 		if (distro !== void 0) head.push("-d", distro);
 		head.push("--", "bash", "-c", this.payload(spec.command));
@@ -248,8 +265,7 @@ var WslBashExecutor = class extends LocalBashExecutor {
 	bwrapArgv(spec) {
 		const policy = this.confinedPolicy(spec);
 		const linuxRoot = toWslPath(policy.workspaceRoot);
-		const head = [this.wslPath()];
-		if (spec.workdir !== this.defaultWorkdir()) head.push("--cd", spec.workdir);
+		const head = [this.wslPath(), "--cd", spec.workdir];
 		const distro = this.distro();
 		if (distro !== void 0) head.push("-d", distro);
 		const mode = policy.mode;
@@ -259,22 +275,37 @@ var WslBashExecutor = class extends LocalBashExecutor {
 		}), "bash", "-c", this.payload(spec.command));
 		return head;
 	}
-	async run(spec) {
+	/** Per-process confinement facts retained until settlement (bash-sandbox pattern). */
+	processFacts = /* @__PURE__ */ new Map();
+	/**
+	 * Execute one resolved spec through the bwrap-wrapped (or plain) WSL argv.
+	 * Foreground is a property of awaiting `result()`, not of the call — one
+	 * handle serves both call styles, as the 0.1.7 seam defines it. A runner
+	 * failure is stamped as `runnerFailed` rather than retried: unlike the
+	 * windows-acl probe, a distro missing bubblewrap is evidence the deployment
+	 * has no confinement at all, and the spec's error contract surfaces it.
+	 * @param spec - the resolved execution spec from {@link resolve}.
+	 * @returns the live handle; sandbox facts land on both `proc.sandbox` (at
+	 *   settlement) and the decorated `result()`.
+	 */
+	async execute(spec) {
 		const policy = this.confinedPolicy(spec);
-		if (policy.mode === "danger-full-access") return {
-			...await this.runArgv(spec, this.argv(spec)),
+		if (policy.mode === "danger-full-access") return WslBashExecutor.decorateResult(await this.executeArgv(spec, this.argv(spec)), (result) => ({
+			...result,
 			sandbox: {
 				mode: "danger-full-access",
 				denied: false
 			}
-		};
-		if (this.sandboxStance === "none") return this.runArgv(spec, this.argv(spec));
+		}));
+		if (this.sandboxStance === "none") return this.executeArgv(spec, this.argv(spec));
 		if (!this.requireBwrapUsable()) {
 			if (this.requireSandbox) throw new Error("bash-wsl: sandbox unavailable — bwrap was not found in the WSL distro; refusing to run unconfined under " + policy.mode + " mode. Install bubblewrap or retry the command with sandbox_permissions: \"danger-full-access\" and a justification.");
-			return this.runArgv(spec, this.argv(spec));
+			return this.executeArgv(spec, this.argv(spec));
 		}
-		const result = await this.runArgv(spec, this.bwrapArgv(spec));
-		if (classifyRunnerFailure(result.exitCode, result.stderr.text, BWRAP_RUNNER_FAILURE_RULES) !== void 0) return {
+		const proc = await this.executeArgv(spec, this.bwrapArgv(spec), (started) => {
+			this.processFacts.set(started, { mode: policy.mode });
+		});
+		return WslBashExecutor.decorateResult(proc, (result) => classifyRunnerFailure(result.exitCode, result.stderr.text, BWRAP_RUNNER_FAILURE_RULES) !== void 0 ? {
 			...result,
 			sandbox: {
 				mode: policy.mode,
@@ -282,32 +313,35 @@ var WslBashExecutor = class extends LocalBashExecutor {
 				enforcement: "full",
 				runnerFailed: true
 			}
-		};
-		return {
+		} : {
 			...result,
 			sandbox: {
 				mode: policy.mode,
 				denied: classifyDenial(result, BWRAP_DENIAL_SIGNATURES),
 				enforcement: "full"
 			}
-		};
+		});
 	}
-	/** Per-process confinement facts retained until settlement (bash-sandbox pattern). */
-	processFacts = /* @__PURE__ */ new Map();
-	start(spec) {
-		const policy = this.confinedPolicy(spec);
-		if (policy.mode === "danger-full-access") return this.startArgv(spec, this.argv(spec));
-		if (this.sandboxStance === "none") return this.startArgv(spec, this.argv(spec));
-		if (!this.requireBwrapUsable()) {
-			if (this.requireSandbox) throw new Error("bash-wsl: sandbox unavailable — bwrap was not found in the WSL distro; refusing to run unconfined under " + policy.mode + " mode. Install bubblewrap or retry the command with sandbox_permissions: \"danger-full-access\" and a justification.");
-			return this.startArgv(spec, this.argv(spec));
-		}
-		const proc = this.startArgv(spec, this.bwrapArgv(spec));
-		this.processFacts.set(proc, { mode: policy.mode });
+	/**
+	 * Decorate the handle's foreground projection in place, memoized once. The
+	 * handle keeps its identity (never wrapped in a second object) because the
+	 * per-process facts and `onProcessDone` key on the exact instance.
+	 * @param proc - the live execution handle.
+	 * @param map - maps the settled result.
+	 * @param mapError - maps a provider rejection.
+	 * @returns the same handle, with `result()` decorated.
+	 */
+	static decorateResult(proc, map, mapError) {
+		const base = proc.result.bind(proc);
+		let decorated;
+		proc.result = () => {
+			decorated ??= base().then(map, mapError);
+			return decorated;
+		};
 		return proc;
 	}
 	/** Stamp per-process sandbox facts before `done` settles (bash-sandbox semantics). */
-	onProcessDone(proc, stderr, spawnFailed, spawnError) {
+	onProcessDone(proc, stderr, providerRejected, providerError) {
 		const facts = this.processFacts.get(proc);
 		if (facts !== void 0) {
 			this.processFacts.delete(proc);
@@ -322,7 +356,7 @@ var WslBashExecutor = class extends LocalBashExecutor {
 				enforcement: "full"
 			};
 		}
-		super.onProcessDone(proc, stderr, spawnFailed, spawnError);
+		super.onProcessDone(proc, stderr, providerRejected, providerError);
 	}
 	resolve(request) {
 		return {

package/lib/index.js

@@ -4,16 +4,19 @@
 // DeepSeek Harness project's shell packages (see THIRD_PARTY_NOTICES),
 // compiled to plain ESM JS:
 //
-//   lib/shell-select/   — ShellSelectExecutor (the ctx.shell selector)
 //   lib/bash-git/       — GitBashExecutor (MSYS / Git for Windows)
 //   lib/bash-wsl/       — WslBashExecutor (WSL distros, base64 payloads)
-//   lib/tool-bash/      — defineShellTool factory + git_bash / wsl_bash instances
-//   lib/vendor/         — helpers.js (bash-sandbox classification) and
-//                         bwrap-profiles.js (bwrap rules/args) — the two
-//                         helper modules not exported by the base runtime.
+//   lib/tool-bash/      — defineShellTool factory + git_bash / wsl_bash
+//                         instances, each owning its own executor
+//                         (types/backend.js) instead of sharing the ctx.shell
+//                         seat: dsh 0.1.7 removed ShellExecRequest.shell, the
+//                         routing field the old shell-select design used.
+//   lib/vendor/         — helpers.js (bash-sandbox classification, including the
+//                         anchored runner-failure rule the base runtime does
+//                         not export) and bwrap-profiles.js (bwrap rules/args).
 //
 // Only published @deepseek-ai base packages are imported (dsh-shell,
-// dsh-sandbox, dsh-pwsh-sandbox, dsh-tools, dsh-llm, ...), so the plugin runs
+// dsh-sandbox, dsh-bash-local, dsh-tools, dsh-llm, ...), so the plugin runs
 // on any standard deployment — no additional runtime packages required.
 //
 // The composition wiring lives in cordis.patch.yml.

package/lib/tool-bash/types/backend.js

@@ -0,0 +1,41 @@
+/**
+ * Backend ownership for the bundled shell tools.
+ *
+ * dsh 0.1.7 removed the routing field from the shell seam: `ShellExecRequest`
+ * no longer carries `shell`, so the pre-0.1.7 design — one selector executor
+ * occupying `ctx.shell` and dispatching each request to a named backend — has
+ * no routing input left. The tool is what knows which shell it wants, so each
+ * tool now owns exactly one executor instance and drives it directly. The
+ * `ctx.shell` seat is left entirely to the base bundle's own executor
+ * (`pwsh-sandbox` on win32), which also frees every plugin that injects
+ * `shell` (dsh's `tool-pwsh`, `permission-presets`, …) from waiting on us.
+ *
+ * `ShellExecutor` is a cordis `Service`: constructing one registers it under
+ * `shell` on the context it is handed, and a second registration on the same
+ * context throws (cordis' standard duplicate-service behavior). An owned
+ * executor is therefore built on a child fiber whose `shell` scope is
+ * isolated, so it never contends for the seat.
+ *
+ * @module dsh-win-multi-bash/tool-bash/backend
+ */
+
+/** Services every bundled executor needs before it can be constructed. */
+const EXECUTOR_INJECT = ['subprocess', 'sandbox', 'sandboxPolicy'];
+
+/**
+ * Build one executor instance on an isolated child fiber.
+ * @param ctx - the owning tool's context; the tool must already inject
+ *   {@link EXECUTOR_INJECT} so those services are present here.
+ * @param Executor - the executor class to construct.
+ * @param config - the executor's resolved config partition.
+ * @returns the instance plus the fiber that owns it; dispose the fiber to tear
+ *   the backend down with the tool.
+ */
+export function ownExecutor(ctx, Executor, config) {
+    const fiber = ctx.plugin({
+        inject: EXECUTOR_INJECT,
+        apply: () => {},
+    });
+    const backendCtx = fiber.ctx.isolate('shell', Symbol(Executor.name));
+    return { executor: new Executor(backendCtx, config), fiber };
+}

package/lib/tool-bash/types/background.js

@@ -22,4 +22,70 @@ export function processOutcome(proc) {
     }
     return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` };
 }
+/**
+ * The process's non-consuming stream readers as registry pull sources. They
+ * bind lazily because the process is spawned inside the starter, after the
+ * registry admitted the job; a read before the spawn yields nothing, and the
+ * pump keeps the model's consuming cursor untouched. A rejected spawn's
+ * stderr reader carries the provider's `subprocess failed before reporting an
+ * outcome: …` note.
+ *
+ * As of dsh 0.1.7 the registry owns the output ring and pumps these sources
+ * itself; a background handle no longer hands its reads back through the
+ * starter's return value.
+ * @param proc - the started process, once the starter has spawned it (or `undefined` before).
+ * @returns one source per stream, stdout first.
+ */
+export function processSources(proc) {
+    const source = (channel) => ({
+        channel,
+        read: (fromByte) => {
+            const live = proc();
+            return live === undefined
+                ? { text: '', nextOffset: fromByte, lossy: false }
+                : live.observed[channel].readFrom(fromByte);
+        },
+    });
+    return [source('stdout'), source('stderr')];
+}
+/**
+ * Adapt asynchronous shell preparation after job admission without exposing a
+ * partial process. The returned hooks settle only once preparation AND the
+ * process have; a cancel before the spawn aborts preparation, and a cancel
+ * after it kills the process.
+ * @param start - starts the process with the job-owned cancellation signal.
+ * @param outcome - projects the settled process into the job outcome.
+ * @returns synchronous job hooks whose `done` includes preparation and settlement.
+ */
+export function processJob(start, outcome) {
+    const controller = new AbortController();
+    let process;
+    return {
+        cancel: (reason) => {
+            if (controller.signal.aborted)
+                return;
+            controller.abort(reason);
+            process?.kill();
+        },
+        done: (async () => {
+            try {
+                process = await start(controller.signal);
+                try {
+                    if (controller.signal.aborted)
+                        process.kill();
+                }
+                finally {
+                    await process.done;
+                }
+                return outcome(process);
+            }
+            catch (error) {
+                return {
+                    status: controller.signal.aborted && process === undefined ? 'killed' : 'failed',
+                    detail: error instanceof Error ? error.message : String(error),
+                };
+            }
+        })(),
+    };
+}
 //# sourceMappingURL=background.js.map