@tiphareth/dsh-hardssh 0.1.2 → 0.2.2

package/lib/subprocess.js

@@ -1,533 +1,7 @@
-import { i as shellQuote, n as readScrubbedRemoteEnvironment, o as isPathUnderAnchor, r as serializeEnvironment } from "./environment-BL1jddfB.js";
-import { randomBytes } from "node:crypto";
-import { closeSync, mkdtempSync, openSync, unlinkSync, writeSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, posix } from "node:path";
+import { i as isPathUnderAnchor } from "./ledger-D2ezq1iW.js";
+import { t as anchorRoot } from "./ledger-B-LXlftp.js";
 import { SubprocessRuntime } from "@deepseek-ai/dsh-subprocess";
 import { LocalSubprocessRuntime } from "@deepseek-ai/dsh-subprocess-local";
-import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
-import { PassThrough } from "node:stream";
-//#region src/remote/output.ts
-/**
-* Bounded host-side projection of one remote output stream with a local
-* spill file. Ported from UynajGI/dsh-ssh (MIT) — verbatim semantics.
-*/
-let spillCounter = 0;
-let defaultSpillDir;
-/** Private (0700) per-process spill directory under the OS tmpdir, created lazily. */
-function privateSpillDir() {
-	defaultSpillDir ??= mkdtempSync(join(tmpdir(), "dsh-subprocess-ssh-"));
-	return defaultSpillDir;
-}
-/**
-* Collects one remote stream with a bounded in-memory tail. On first overflow
-* a spill file is opened (when a spill cap is configured) and every chunk —
-* already-collected ones included — is appended there while the full stream
-* stays within the cap; without one, only the in-memory tail is retained.
-*/
-var SshOutputCollector = class {
-	maxBytes;
-	maxSpillBytes;
-	label;
-	spillDir;
-	chunks = [];
-	retained = 0;
-	total = 0;
-	dropped = false;
-	spillFd;
-	spillFile;
-	spillDisabled;
-	constructor(maxBytes, maxSpillBytes, label, spillDir = privateSpillDir()) {
-		this.maxBytes = maxBytes;
-		this.maxSpillBytes = maxSpillBytes;
-		this.label = label;
-		this.spillDir = spillDir;
-		this.spillDisabled = maxSpillBytes === void 0;
-	}
-	/** Append one byte-faithful remote chunk, trimming the retained tail to the cap. */
-	push(chunk) {
-		if (chunk.length === 0) return;
-		const buffer = Buffer.from(chunk);
-		this.total += buffer.length;
-		const overflows = this.retained + buffer.length > this.maxBytes;
-		if (!this.spillDisabled && (overflows || this.spillFd !== void 0)) this.spillAll(buffer);
-		this.chunks.push(buffer);
-		this.retained += buffer.length;
-		while (this.retained > this.maxBytes) {
-			const head = this.chunks[0];
-			const excess = this.retained - this.maxBytes;
-			if (head.length <= excess) {
-				this.chunks.shift();
-				this.retained -= head.length;
-			} else {
-				this.chunks[0] = head.subarray(excess);
-				this.retained -= excess;
-			}
-			this.dropped = true;
-		}
-	}
-	/** @inheritdoc */
-	readFrom(fromByte) {
-		const retained = Buffer.concat(this.chunks, this.retained);
-		const windowStart = this.total - this.retained;
-		const lossy = fromByte < windowStart;
-		const start = lossy ? 0 : Math.min(retained.length, Math.max(0, fromByte - windowStart));
-		return {
-			text: retained.subarray(start).toString("utf8"),
-			nextOffset: this.total,
-			lossy,
-			...this.spillFile !== void 0 ? { spillPath: this.spillFile } : {}
-		};
-	}
-	/** Open the spill file lazily and append one chunk (plus any prior chunks once). */
-	spillAll(chunk) {
-		if (this.maxSpillBytes !== void 0 && this.total > this.maxSpillBytes) {
-			this.discardSpill();
-			return;
-		}
-		if (this.spillFd === void 0) {
-			this.spillFile = join(this.spillDir, `dsh-subprocess-ssh-${process.pid}-${++spillCounter}-${randomBytes(6).toString("hex")}-${this.label}.log`);
-			this.spillFd = openSync(this.spillFile, "wx", 384);
-			for (const prior of this.chunks) writeSync(this.spillFd, prior);
-		}
-		writeSync(this.spillFd, chunk);
-	}
-	/** Stop spilling and remove the file once it can no longer hold the complete stream. */
-	discardSpill() {
-		const fd = this.spillFd;
-		const file = this.spillFile;
-		this.spillFd = void 0;
-		this.spillFile = void 0;
-		this.spillDisabled = true;
-		if (fd !== void 0) try {
-			closeSync(fd);
-		} catch {
-			this.spillFd = fd;
-		}
-		if (file !== void 0) try {
-			unlinkSync(file);
-		} catch {}
-	}
-	/** Close the spill file once the stream has ended; stop advertising it on a failed close. */
-	seal() {
-		if (this.spillFd === void 0) return;
-		try {
-			closeSync(this.spillFd);
-		} catch {
-			this.spillFile = void 0;
-		}
-		this.spillFd = void 0;
-	}
-	/** Seal the spill and return the final collected output. */
-	finalize() {
-		this.seal();
-		return {
-			text: Buffer.concat(this.chunks).toString("utf8"),
-			truncated: this.dropped,
-			...this.spillFile !== void 0 ? { spillPath: this.spillFile } : {}
-		};
-	}
-};
-//#endregion
-//#region src/remote/remote-process.ts
-/**
-* One asynchronously-started SSH command projected onto the subprocess seam.
-* Ported from UynajGI/dsh-ssh (MIT) — the raw ssh2 channel is replaced by the
-* engine's streaming ExecSession.
-*/
-function isCollect(mode) {
-	return mode !== "pipe" && mode !== "inherit";
-}
-/** Resolve the remote working directory for one spawn spec. */
-function resolveRemoteCwd(state, cwd) {
-	const root = state.remoteRoot;
-	if (root === void 0) throw new Error("subprocess-ssh: remote workspace root is not set");
-	if (cwd !== void 0 && cwd.startsWith("/")) return cwd;
-	return root;
-}
-/** Build the remote command text: cd, env -i scrub, exec the argv. */
-async function buildCommand(engine, alias, state, spec) {
-	const environment = serializeEnvironment(await readScrubbedRemoteEnvironment(engine, alias), spec.env);
-	const argv = spec.argv.map(shellQuote).join(" ");
-	return `cd -- ${shellQuote(resolveRemoteCwd(state, spec.cwd))} && exec env -i -- ${environment} ${argv}`;
-}
-/** SSH-backed subprocess handle. The channel does not expose a remote pid, so `pid` is `-1`. */
-var SshSubprocessHandle = class {
-	engine;
-	getState;
-	spec;
-	spillDir;
-	stdin;
-	stdout;
-	stderr;
-	collected;
-	done;
-	terminationController = new AbortController();
-	stdoutCollector;
-	stderrCollector;
-	session;
-	graceTimer;
-	settled = false;
-	constructor(engine, getState, spec, spillDir) {
-		this.engine = engine;
-		this.getState = getState;
-		this.spec = spec;
-		this.spillDir = spillDir;
-		const outMode = spec.stdio.stdout;
-		const errMode = spec.stdio.stderr;
-		this.stdout = outMode === "pipe" ? new PassThrough() : void 0;
-		this.stderr = errMode === "pipe" ? new PassThrough() : void 0;
-		this.stdoutCollector = isCollect(outMode) ? new SshOutputCollector(outMode.maxBytes, outMode.spill?.maxBytes, "stdout", spillDir) : void 0;
-		this.stderrCollector = isCollect(errMode) ? new SshOutputCollector(errMode.maxBytes, errMode.spill?.maxBytes, "stderr", spillDir) : void 0;
-		this.collected = {
-			...this.stdoutCollector !== void 0 ? { stdout: this.stdoutCollector } : {},
-			...this.stderrCollector !== void 0 ? { stderr: this.stderrCollector } : {}
-		};
-		this.stdin = spec.stdio.stdin === "pipe" ? new PassThrough() : void 0;
-		spec.signal?.addEventListener("abort", this.onAbort, { once: true });
-		this.done = this.run();
-		this.done.catch(() => {});
-		if (spec.signal?.aborted === true) this.terminate();
-	}
-	/** Remote process id; `-1` because the SSH channel does not expose one. */
-	get pid() {
-		return -1;
-	}
-	/** @inheritdoc */
-	terminate() {
-		if (this.settled || this.terminationController.signal.aborted) return;
-		this.terminationController.abort(/* @__PURE__ */ new Error("subprocess-ssh: command terminated"));
-		const session = this.session;
-		if (session !== void 0) this.signalTerm(session);
-	}
-	/** @inheritdoc */
-	waitForExit(signal) {
-		if (this.settled) return Promise.resolve(true);
-		if (signal?.aborted === true) return Promise.resolve(false);
-		if (signal === void 0) return this.done.then(() => true, () => true);
-		return new Promise((resolve) => {
-			const onAbort = () => {
-				cleanup();
-				resolve(false);
-			};
-			const cleanup = () => {
-				signal.removeEventListener("abort", onAbort);
-			};
-			signal.addEventListener("abort", onAbort, { once: true });
-			this.done.then(() => {
-				cleanup();
-				resolve(true);
-			}, () => {
-				cleanup();
-				resolve(true);
-			});
-		});
-	}
-	onAbort = () => {
-		this.terminate();
-	};
-	signalTerm(session) {
-		try {
-			session.signal("TERM");
-		} catch {}
-		this.graceTimer = setTimeout(() => {
-			try {
-				session.signal("KILL");
-			} catch {}
-		}, this.spec.graceMs);
-	}
-	settle() {
-		if (this.settled) return;
-		this.settled = true;
-		if (this.graceTimer !== void 0) clearTimeout(this.graceTimer);
-		this.graceTimer = void 0;
-		this.stdoutCollector?.seal();
-		this.stderrCollector?.seal();
-		this.spec.signal?.removeEventListener("abort", this.onAbort);
-	}
-	async run() {
-		let session;
-		try {
-			const state = this.getState();
-			if (state.mode !== "remote" || state.alias === void 0) throw new Error("subprocess-ssh: not in remote mode — switch the GUI to SSH mode first");
-			const command = await buildCommand(this.engine, state.alias, state, this.spec);
-			session = await this.engine.openExec(state.alias, command);
-		} catch (error) {
-			this.settle();
-			throw error;
-		}
-		this.session = session;
-		if (this.terminationController.signal.aborted) this.signalTerm(session);
-		this.wireStdout(session);
-		this.wireStderr(session);
-		if (this.stdin !== void 0) this.stdin.pipe({
-			write: (chunk, encoding, callback) => {
-				try {
-					session.send(chunk.toString(encoding ?? "utf8"));
-					callback?.();
-				} catch (error) {
-					callback?.(error instanceof Error ? error : new Error(String(error)));
-				}
-			},
-			end: (callback) => {
-				session.end();
-				callback?.();
-			}
-		});
-		else if (typeof this.spec.stdio.stdin === "object") session.end(this.spec.stdio.stdin.data);
-		return await new Promise((resolve, reject) => {
-			session.onExit = (code, error) => {
-				this.settle();
-				if (error !== void 0) reject(/* @__PURE__ */ new Error(`subprocess-ssh: ${error}`));
-				else resolve({
-					exitCode: code,
-					signal: null
-				});
-			};
-		});
-	}
-	wireStdout(session) {
-		const mode = this.spec.stdio.stdout;
-		session.onData = (data) => {
-			if (mode === "pipe") this.stdout?.write(data);
-			else if (mode === "inherit") process.stdout.write(data);
-			else this.stdoutCollector?.push(data);
-		};
-	}
-	wireStderr(session) {
-		const mode = this.spec.stdio.stderr;
-		session.onErrData = (data) => {
-			if (mode === "pipe") this.stderr?.write(data);
-			else if (mode === "inherit") process.stderr.write(data);
-			else this.stderrCollector?.push(data);
-		};
-	}
-};
-//#endregion
-//#region src/remote/remote-terminal.ts
-/**
-* SSH PTY allocation and process-session ownership for the subprocess seam.
-* Ported from UynajGI/dsh-ssh (MIT) — the raw ssh2 shell channel is replaced
-* by the engine's openShell session.
-*/
-/** Resolve after one duration. */
-function delay(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/** One SSH PTY and its remote login shell, projected onto the subprocess terminal seam. */
-var SshTerminalHandle = class {
-	closeChannel;
-	sendChannel;
-	signalChannel;
-	graceMs;
-	pid = -1;
-	output = new PassThrough();
-	done;
-	exitResolve;
-	topLevelExited = false;
-	cleanup;
-	constructor(closeChannel, sendChannel, signalChannel, graceMs) {
-		this.closeChannel = closeChannel;
-		this.sendChannel = sendChannel;
-		this.signalChannel = signalChannel;
-		this.graceMs = graceMs;
-		this.done = new Promise((resolve) => {
-			this.exitResolve = resolve;
-		});
-	}
-	/** Settle the exit promise (called by the runtime when the channel closes). */
-	resolveExit(outcome) {
-		this.exitResolve(outcome);
-	}
-	/** @inheritdoc */
-	write(data) {
-		if (this.topLevelExited) return Promise.reject(/* @__PURE__ */ new Error("terminal process has exited"));
-		return new Promise((resolve, reject) => {
-			try {
-				this.sendChannel(data);
-				resolve();
-			} catch (error) {
-				reject(error instanceof Error ? error : new Error(String(error)));
-			}
-		});
-	}
-	/** The SSH channel does not expose a foreground process group. */
-	inspectForeground() {
-		return Promise.resolve(void 0);
-	}
-	/** @inheritdoc */
-	signalForeground(_signal) {
-		return Promise.reject(/* @__PURE__ */ new Error("subprocess-ssh: cannot resolve the foreground process group over an SSH channel"));
-	}
-	/** @inheritdoc */
-	terminate() {
-		if (this.cleanup !== void 0) return this.cleanup;
-		const cleanup = this.closeOnce();
-		this.cleanup = cleanup;
-		cleanup.catch(() => {
-			this.cleanup = void 0;
-		});
-		return cleanup;
-	}
-	signal(name) {
-		try {
-			this.signalChannel(name);
-		} catch {}
-	}
-	async closeOnce() {
-		this.signal("TERM");
-		await Promise.race([this.done.then(() => void 0, () => void 0), delay(this.graceMs)]);
-		if (!this.topLevelExited) this.signal("KILL");
-		await Promise.race([this.done.then(() => void 0, () => void 0), delay(this.graceMs)]);
-		if (!this.topLevelExited) {
-			this.closeChannel();
-			throw new Error("subprocess-ssh: terminal cleanup failed; channel still open");
-		}
-	}
-};
-/**
-* Allocate an SSH PTY, replace its login shell with the requested argv, and
-* return the live terminal handle.
-*/
-async function spawnSshTerminal(engine, getState, spec) {
-	spec.signal?.throwIfAborted();
-	const program = spec.argv[0];
-	if (program === void 0 || program.length === 0) throw new Error("subprocess-ssh: terminal argv must contain a program");
-	const state = getState();
-	if (state.mode !== "remote" || state.alias === void 0) throw new Error("subprocess-ssh: not in remote mode — switch the GUI to SSH mode first");
-	const environment = serializeEnvironment(await readScrubbedRemoteEnvironment(engine, state.alias), spec.env);
-	const session = await engine.openShell(state.alias, {
-		cols: spec.cols,
-		rows: spec.rows
-	});
-	const root = state.remoteRoot;
-	if (root === void 0) throw new Error("subprocess-ssh: remote workspace root is not set");
-	const cwd = spec.cwd !== void 0 && spec.cwd.startsWith("/") ? spec.cwd : root;
-	const handle = new SshTerminalHandle(() => session.close(), (data) => session.send(data), (name) => session.signal(name), spec.graceMs);
-	session.onData = (data) => {
-		if (!handle.output.destroyed) handle.output.write(data);
-	};
-	session.onExit = (code, error) => {
-		handle.topLevelExited = true;
-		handle.output.end();
-		handle.resolveExit({
-			exitCode: error !== void 0 ? null : code,
-			signal: null
-		});
-	};
-	const argv = spec.argv.map(shellQuote).join(" ");
-	await handle.write(`cd ${shellQuote(cwd)} && exec env -i -- ${environment} ${argv}\r`);
-	spec.signal?.throwIfAborted();
-	return handle;
-}
-//#endregion
-//#region src/remote/remote-subprocess.ts
-/**
-* Remote subprocess provider for the `ctx.subprocess` capability seam: each
-* spawn opens a streaming exec channel (or a PTY for terminals) on the
-* current SSH-mode host through the dsh-ssh engine; output spill files stay
-* on the local host. Ported from UynajGI/dsh-ssh (MIT).
-*
-* @module dsh-hardssh/remote-subprocess
-*/
-/**
-* Enforce the seam's documented grace bound (positive, finite, one Node timer).
-*/
-function requireRepresentableGrace(graceMs) {
-	if (!Number.isFinite(graceMs) || graceMs <= 0 || graceMs > MAX_TIMER_DELAY_MS) throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
-}
-/** SSH command manager registered as `ctx.subprocess` (remote mode). */
-var SshSubprocessRuntime = class extends SubprocessRuntime {
-	engine;
-	getState;
-	live = /* @__PURE__ */ new Set();
-	terminals = /* @__PURE__ */ new Set();
-	spillDir = mkdtempSync(join(tmpdir(), "dsh-subprocess-ssh-"));
-	disposing = false;
-	constructor(ctx, engine, getState) {
-		super(ctx);
-		this.engine = engine;
-		this.getState = getState;
-		ctx.effect(() => async () => {
-			this.disposing = true;
-			const handles = [...this.live];
-			const terminals = [...this.terminals];
-			const pending = [];
-			for (const handle of handles) {
-				handle.terminate();
-				pending.push(handle.waitForExit().then(() => {
-					this.live.delete(handle);
-				}));
-			}
-			for (const terminal of terminals) pending.push(terminal.terminate().then(() => {
-				this.terminals.delete(terminal);
-			}));
-			const failures = (await Promise.allSettled(pending)).flatMap((outcome) => outcome.status === "rejected" ? [outcome.reason] : []);
-			if (failures.length === 1) throw failures[0];
-			if (failures.length > 1) throw new AggregateError(failures, "subprocess-ssh: teardown failed");
-		}, "ssh subprocess teardown");
-	}
-	/** @inheritdoc */
-	async resolveExecutable(command, env, signal) {
-		if (command.length === 0) throw new Error("subprocess-ssh: executable name must be non-empty");
-		signal?.throwIfAborted();
-		const state = this.getState();
-		if (state.mode !== "remote" || state.alias === void 0) throw new Error("subprocess-ssh: not in remote mode — switch the GUI to SSH mode first");
-		if (posix.isAbsolute(command)) {
-			const result = await this.engine.exec(state.alias, `test -f ${shellQuote(command)} -a -x ${shellQuote(command)}`, 1e4);
-			signal?.throwIfAborted();
-			if (!result.success || result.exitCode !== 0) throw new Error(`subprocess-ssh: command ${JSON.stringify(command)} is not an executable file`);
-			return command;
-		}
-		if (command.includes("/")) throw new Error(`subprocess-ssh: command ${JSON.stringify(command)} is a relative path; use an absolute path or a bare PATH name`);
-		const path = env?.PATH;
-		const prefix = path === void 0 ? "" : `PATH=${shellQuote(path)} `;
-		const result = await this.engine.exec(state.alias, `${prefix}command -v -- ${shellQuote(command)}`, 1e4);
-		signal?.throwIfAborted();
-		const executable = result.stdout.trim();
-		if (!result.success || result.exitCode !== 0 || executable.length === 0 || executable.includes("\n") || !posix.isAbsolute(executable) && !executable.includes("/")) throw new Error(`subprocess-ssh: executable ${JSON.stringify(command)} did not resolve to one absolute path`);
-		const root = state.remoteRoot;
-		if (root === void 0) throw new Error("subprocess-ssh: remote workspace root is not set");
-		return posix.isAbsolute(executable) ? executable : posix.resolve(root, executable);
-	}
-	/** @inheritdoc */
-	spawn(spec) {
-		if (this.disposing) throw new Error("subprocess-ssh: service is disposing");
-		const program = spec.argv[0];
-		if (program === void 0 || program.length === 0) throw new Error("invalid argv: expected a non-empty program name at argv[0]");
-		requireRepresentableGrace(spec.graceMs);
-		if (spec.signal?.aborted === true) throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`);
-		const handle = new SshSubprocessHandle(this.engine, this.getState, spec, this.spillDir);
-		this.live.add(handle);
-		const release = async () => {
-			await handle.waitForExit();
-			this.live.delete(handle);
-		};
-		handle.done.then(release, release).catch(() => {});
-		return handle;
-	}
-	/** @inheritdoc */
-	async spawnTerminal(spec) {
-		if (this.disposing) throw new Error("subprocess-ssh: service is disposing");
-		const program = spec.argv[0];
-		if (program === void 0 || program.length === 0) throw new Error("subprocess-ssh: terminal argv must contain a program");
-		requireRepresentableGrace(spec.graceMs);
-		spec.signal?.throwIfAborted();
-		const terminal = await spawnSshTerminal(this.engine, this.getState, spec);
-		if (this.disposing) {
-			await terminal.terminate();
-			throw new Error("subprocess-ssh: service disposed during terminal setup");
-		}
-		this.terminals.add(terminal);
-		const release = async () => {
-			await terminal.terminate();
-			this.terminals.delete(terminal);
-		};
-		terminal.done.then(release, release).catch(() => {});
-		return terminal;
-	}
-};
-//#endregion
 //#region src/switch/switch-subprocess.ts
 /**
 * The `ctx.subprocess` switching facade: routes every spawn to the execution
@@ -539,6 +13,36 @@ var SshSubprocessRuntime = class extends SubprocessRuntime {
 *
 * @module dsh-hardssh/switch-subprocess
 */
+const DEFAULT_CLIENT_TOOL_NAMES = [
+	"pwsh",
+	"powershell",
+	"cmd"
+];
+const CLIENT_EXECUTABLE_RE = /\.(exe|cmd|bat|ps1|com)$/i;
+/**
+* Client-packaged helpers that search the WORKSPACE's files (the bundled
+* ripgrep behind the glob/grep tools). They are client binaries, but they are
+* not shells: running one locally while the session's world is remote searches
+* the local anchor directory (an empty placeholder) and reports "no matches",
+* and sending the client's absolute PATH to the server cannot work either.
+* Either way the answer is wrong, so a path-shaped invocation is refused
+* loudly. A BARE `rg` is left alone: that is an ordinary server command and
+* belongs to the remote world like any other.
+*/
+const CLIENT_WORKSPACE_SEARCH_RE = /^(rg|ripgrep)(\.exe)?$/i;
+/** True for a PATH-shaped (not bare-name) invocation of a search helper. */
+function isClientSearchHelperPath(exe) {
+	if (!exe.includes("/") && !exe.includes("\\")) return false;
+	const base = exe.split(/[\\/]/).pop() ?? exe;
+	return CLIENT_WORKSPACE_SEARCH_RE.test(base);
+}
+/** A client-native executable: Windows-format path/extension, or a bare name
+*  on the declared client-tool list (remote POSIX hosts never carry these). */
+function isClientNativeExecutable(exe, names) {
+	if (exe === "") return false;
+	if (/^[a-zA-Z]:[\\/]/.test(exe) || exe.includes("\\") || CLIENT_EXECUTABLE_RE.test(exe)) return true;
+	return names.includes(exe);
+}
 /** Workspace-routing subprocess facade. */
 var SwitchSubprocessRuntime = class extends SubprocessRuntime {
 	deps;
@@ -546,55 +50,94 @@ var SwitchSubprocessRuntime = class extends SubprocessRuntime {
 		super(ctx);
 		this.deps = deps;
 	}
-	/** The runtime for one spec (by its cwd). */
+	/** The runtime for one spec (by its cwd); undefined means LOCAL. */
 	runtimeFor(cwd) {
 		return this.deps.worldFor(cwd);
 	}
+	/** Client binaries run on THIS machine even from a bound workspace — their
+	*  executables cannot exist on the remote POSIX host, and the spawn cwd is
+	*  the local anchor (which exists locally), so local execution is sound.
+	*  Everything else runs in the session's world (remote on a bound host).
+	*
+	*  ONE exception is refused rather than routed: a client-side SEARCH helper
+	*  (rg) in a remote-bound session would search the empty local anchor and
+	*  report "no matches" — a confidently wrong answer about the server's
+	*  contents. There is no way to make a local index-of-files tool read the
+	*  remote workspace, so the caller is told to use the remote tools.
+	*
+	*  Locality comes from the routing answer (`undefined`), never from an
+	*  identity comparison against `deps.local`: that comparison silently failed
+	*  once and refused local ripgrep launches for every session. */
+	effectiveRuntime(spec) {
+		const runtime = this.runtimeFor(spec.cwd);
+		if (runtime === void 0) return this.deps.local;
+		const names = this.deps.clientToolNames ?? DEFAULT_CLIENT_TOOL_NAMES;
+		const exe = spec.argv !== void 0 && spec.argv.length > 0 ? spec.argv[0] : "";
+		if (isClientSearchHelperPath(exe)) throw new Error(`dsh-hardssh: '${exe.split(/[\\/]/).pop()}' is a client-side search tool and cannot read the remote workspace bound to this session (its working directory is the local anchor placeholder, not the server). Search remote content with the remote_search tool (mode="glob" for file names, mode="grep" for content) or ssh_exec instead.`);
+		return isClientNativeExecutable(exe, names) ? this.deps.local : runtime;
+	}
 	/** @inheritdoc */
 	resolveExecutable(command, env, signal) {
 		return this.deps.local.resolveExecutable(command, env, signal);
 	}
 	/** @inheritdoc */
 	spawn(spec) {
-		return this.runtimeFor(spec.cwd).spawn(spec);
+		return this.effectiveRuntime(spec).spawn(spec);
 	}
 	/** @inheritdoc */
 	spawnTerminal(spec) {
-		return this.runtimeFor(spec.cwd).spawnTerminal(spec);
+		return this.effectiveRuntime(spec).spawnTerminal(spec);
 	}
 };
 //#endregion
 //#region src/subprocess.ts
 /** Stable cordis plugin name. */
 const name = "hardssh-subprocess";
-/** Services required: the shared workspace core (mode store + engine). */
-const inject = ["hardsshCore"];
-/** A remote runtime fixed to one SSH workspace's alias + remote root. */
-function fixedRemoteState(alias, remoteRoot) {
-	return () => ({
-		mode: "remote",
-		alias,
-		remoteRoot
-	});
+/** Workspace routing is exclusively provided by the generic core. */
+const inject = ["workspaceCore"];
+/** The record behind a router connection (sync snapshot lookup). */
+function genericRecordFor(core, id) {
+	return core.ledger.snapshotSync().records.find((record) => record.id === id);
 }
-/** Mount the switching subprocess facade. */
+/** Resolve the subprocess runtime owning a cwd, or undefined when local. */
+function genericSubprocessFor(core, cwd, reservedAnchorRoots) {
+	if (!core.isReady()) {
+		if (cwd !== void 0 && reservedAnchorRoots.some((root) => isPathUnderAnchor(root, cwd))) throw new Error("subprocess-ssh: workspace routing is unavailable while the generic workspace core is not ready (anchor path fails closed)");
+		return;
+	}
+	const connection = core.router.fromAnchor(cwd);
+	if (connection === void 0) return void 0;
+	const record = genericRecordFor(core, connection.workspaceId);
+	if (record === void 0) throw new Error(`subprocess-workspace: routed workspace '${connection.workspaceId}' is missing from the ledger`);
+	const runtime = connection.get("workspace.process");
+	if (runtime === void 0) throw new Error(`subprocess-workspace: workspace '${record.id}' provides no workspace.process capability`);
+	return runtime;
+}
+/** Mount the generic switching subprocess facade. */
 function apply(ctx) {
-	const core = ctx.hardsshCore;
 	const localCtx = ctx.isolate("subprocess");
 	const localSubprocess = new LocalSubprocessRuntime(localCtx);
-	core.seams.bindSub((record) => new SshSubprocessRuntime(ctx.isolate("subprocess"), core.engine, fixedRemoteState(record.alias, record.remoteRoot)));
-	const anchorRoot = core.ledger.anchorsRoot();
+	const ws = ctx.workspaceCore;
+	const anchorRootDir = anchorRoot();
 	let warnedUnready = false;
 	new SwitchSubprocessRuntime(ctx, {
 		local: localSubprocess,
 		worldFor: (cwd) => {
-			if (!core.seams.isReady() && !warnedUnready && cwd !== void 0 && isPathUnderAnchor(anchorRoot, cwd)) {
-				warnedUnready = true;
-				console.warn("[dsh-hardssh] subprocess routing is not ready yet (workspace ledger still loading) — running locally until the snapshot is applied");
+			if (!ws.isReady()) {
+				if (cwd !== void 0 && isPathUnderAnchor(anchorRootDir, cwd)) {
+					if (!warnedUnready) {
+						warnedUnready = true;
+						console.warn("[dsh-hardssh] subprocess routing is not ready yet (workspace core still initializing or failed) — refusing to run beneath the workspace anchor root");
+					}
+					throw new Error("subprocess-ssh: workspace routing is unavailable while the generic workspace core is not ready (anchor path fails closed)");
+				}
+				return;
 			}
-			return core.seams.runtimeForSub(cwd) ?? localSubprocess;
+			const runtime = genericSubprocessFor(ws, cwd, [anchorRootDir]);
+			if (runtime !== void 0) return runtime;
+			if (cwd !== void 0 && isPathUnderAnchor(anchorRootDir, cwd)) throw new Error(`subprocess-ssh: '${cwd}' is inside the workspace anchor root but no registered workspace owns it (fail closed)`);
 		}
 	});
 }
 //#endregion
-export { apply, inject, name };
+export { apply, genericSubprocessFor, inject, name };