@cruxy/cli 0.29.2 → 0.29.4

package/dist/errors/constructors.js

@@ -142,6 +142,33 @@ export function authInvalid(underlying) {
         underlying,
     });
 }
+/**
+ * A credential could not be persisted with owner-only permissions, so it was
+ * NOT written (C.27c). Chiefly a Windows case: the store's ACL could not be
+ * restricted to the current user (non-NTFS filesystem, `icacls`/SID
+ * unavailable), and we refuse to leave a secret at inheritable permissions while
+ * claiming otherwise. Provider keys point at the env-var fallback; MCP tokens
+ * have no such fallback, so the message says so plainly.
+ */
+export function credentialsUnprotected(kind, path, underlying) {
+    const nextSteps = kind === "provider"
+        ? [
+            "set the key via the CRUXY_API_KEY environment variable instead — env is never written to disk and always wins",
+            "or store it on a filesystem that supports owner-only permissions (NTFS, not FAT/exFAT)",
+        ]
+        : [
+            "an MCP bearer token has no environment fallback — it can only live in the owner-only store",
+            "store it on a filesystem that supports owner-only permissions (NTFS, not FAT/exFAT)",
+        ];
+    return new CruxyError({
+        code: ErrorCode.CredentialsUnprotected,
+        title: `refusing to write a credential that cannot be made owner-only: ${path}`,
+        cause: scrubbedMessageOf(underlying),
+        nextSteps,
+        underlying,
+        meta: { path, kind },
+    });
+}
 // ── network (exit 5) ──────────────────────────────────────────────────────────
 export function gatewayUnreachable(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -29,6 +29,12 @@ export declare const ErrorCode: {
     readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
     readonly AuthInvalid: "CRUXY_E_AUTH_INVALID";
     readonly ForgeAuth: "CRUXY_E_FORGE_AUTH";
+    /** A credential could not be persisted with owner-only permissions (C.27c) —
+     * e.g. on Windows the store's ACL could not be restricted to the current user
+     * (non-NTFS filesystem, `icacls`/SID unavailable). Refused loudly rather than
+     * written world-inheritable: a secret is never persisted at permissions we
+     * could not verify as owner-only. */
+    readonly CredentialsUnprotected: "CRUXY_E_CREDENTIALS_UNPROTECTED";
     readonly GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE";
     readonly GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED";
     readonly Api: "CRUXY_E_API";
@@ -201,6 +207,12 @@ export declare const ErrorCode: {
      * `jobs.enabled` is false. The feature is opt-in; surfaced with how to enable it
      * rather than pretending there are simply no jobs. */
     readonly JobsDisabled: "CRUXY_E_JOBS_DISABLED";
+    /** No usable host shell was found to run commands through. On Windows this
+     * means neither Git Bash nor PowerShell could be located and no
+     * `shell.executable` override was set. Fail loud at session start — NEVER
+     * silently fall back to cmd.exe running bash-shaped commands (which
+     * mis-parses `;`/`&&`/quoting and can report a false success). */
+    readonly NoShell: "CRUXY_E_NO_SHELL";
     /** A one-shot `cruxy run` ended WITHOUT completing the task: the agent loop hit
      * a hard stop (the iteration cap or a token budget) or was cancelled, rather
      * than finishing on its own. Fail loud with a non-zero exit so CI never reads a

package/dist/errors/types.js

@@ -33,6 +33,12 @@ export const ErrorCode = {
     AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY",
     AuthInvalid: "CRUXY_E_AUTH_INVALID",
     ForgeAuth: "CRUXY_E_FORGE_AUTH",
+    /** A credential could not be persisted with owner-only permissions (C.27c) —
+     * e.g. on Windows the store's ACL could not be restricted to the current user
+     * (non-NTFS filesystem, `icacls`/SID unavailable). Refused loudly rather than
+     * written world-inheritable: a secret is never persisted at permissions we
+     * could not verify as owner-only. */
+    CredentialsUnprotected: "CRUXY_E_CREDENTIALS_UNPROTECTED",
     // network (exit 5)
     GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE",
     GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED",
@@ -222,6 +228,13 @@ export const ErrorCode = {
      * `jobs.enabled` is false. The feature is opt-in; surfaced with how to enable it
      * rather than pretending there are simply no jobs. */
     JobsDisabled: "CRUXY_E_JOBS_DISABLED",
+    // host shell (exit 21) — the run_command / run_tests execution substrate
+    /** No usable host shell was found to run commands through. On Windows this
+     * means neither Git Bash nor PowerShell could be located and no
+     * `shell.executable` override was set. Fail loud at session start — NEVER
+     * silently fall back to cmd.exe running bash-shaped commands (which
+     * mis-parses `;`/`&&`/quoting and can report a false success). */
+    NoShell: "CRUXY_E_NO_SHELL",
     // one-shot run outcome (exit 20)
     /** A one-shot `cruxy run` ended WITHOUT completing the task: the agent loop hit
      * a hard stop (the iteration cap or a token budget) or was cancelled, rather
@@ -249,6 +262,7 @@ const EXIT_CODES = {
     [ErrorCode.AuthMissingKey]: 4,
     [ErrorCode.AuthInvalid]: 4,
     [ErrorCode.ForgeAuth]: 4,
+    [ErrorCode.CredentialsUnprotected]: 4,
     [ErrorCode.GatewayUnreachable]: 5,
     [ErrorCode.GitPushFailed]: 5,
     [ErrorCode.Api]: 6,
@@ -353,6 +367,10 @@ const EXIT_CODES = {
     // cancelled) without completing gets its own greppable exit code, so CI can tell
     // "the agent gave up" apart from a provider/auth/config failure.
     [ErrorCode.AgentIncomplete]: 20,
+    // Host shell. No usable shell to execute commands through — a fail-loud
+    // execution-substrate stop (kin to CRUXY_E_SANDBOX_UNAVAILABLE, but for the
+    // host path), with its own greppable exit code.
+    [ErrorCode.NoShell]: 21,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/indexing/service.js

@@ -131,7 +131,10 @@ async function openStore(root, kind, logger) {
         // an in-memory index with a warning (no quality loss, just no persistence).
         if (kind === "sqlite")
             throw indexStoreUnavailable(err);
-        logger.warn(`sqlite index unavailable (${err.message}); using an in-memory index`);
+        logger.warn(`persistent index unavailable (${err.message}); using an ephemeral ` +
+            `in-memory index — it reindexes from scratch each session. To enable persistence, ` +
+            `let better-sqlite3 build (install your platform's C/C++ build tools) or run on Node ≥22 ` +
+            `(which ships a prebuilt binary).`);
         return { store: new InMemoryVectorStore(), storePath: null };
     }
 }

package/dist/lsp/transport.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawnTree } from "../utils/process-tree.js";
 import { killTree, killTrackedTrees, registerForCleanup, trackedTreeCount, } from "../utils/child-tree.js";
 // Re-exported under their historical LSP names so callers and tests keep
 // importing them from here; the machinery now lives in the shared child-tree
@@ -31,11 +31,11 @@ export class StdioTransport {
     /** Deregisters this process from the process-exit kill-tree backstop. */
     unregisterCleanup;
     constructor(spec, root) {
-        // `detached` makes the child a process-group leader so the whole tree can be
-        // killed via a negative-PID signal — same discipline as run_command (C.16).
-        this.child = spawn(spec.command, spec.args, {
+        // `spawnTree` heads a killable tree with the platform-correct grouping —
+        // POSIX process group, or win32 `windowsHide` (NOT `detached`, which opens a
+        // console there) — so `killTree` reaps the whole server tree on either OS.
+        this.child = spawnTree(spec.command, spec.args, {
             cwd: root,
-            detached: true,
             stdio: ["pipe", "pipe", "pipe"],
         });
         this.unregisterCleanup = registerForCleanup(this.child.pid);

package/dist/mcp/transport.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawnTree } from "../utils/process-tree.js";
 import { killTree, registerForCleanup } from "../utils/child-tree.js";
 /**
  * JSON-RPC 2.0 over an MCP server's stdio (C.27). Owns the child process: spawns
@@ -30,12 +30,12 @@ export class McpStdioTransport {
     disposed = false;
     unregisterCleanup;
     constructor(spec, root) {
-        // `detached` makes the child a process-group leader so the whole tree can be
-        // killed via a negative-PID signal — same discipline as run_command (C.16)
-        // and the LSP transport (C.12).
-        this.child = spawn(spec.command, spec.args, {
+        // `spawnTree` heads a killable tree with the platform-correct grouping —
+        // POSIX process group, or win32 `windowsHide` (NOT `detached`, which opens a
+        // console there) — same discipline as run_command (C.16) and the LSP
+        // transport (C.12); `killTree` reaps the whole server tree on either OS.
+        this.child = spawnTree(spec.command, spec.args, {
             cwd: root,
-            detached: true,
             stdio: ["pipe", "pipe", "pipe"],
             env: { ...process.env, ...(spec.env ?? {}) },
         });

package/dist/memory/types.d.ts

@@ -45,14 +45,14 @@ export declare const MemoryEntrySchema: z.ZodObject<{
     /** ISO 8601 timestamp the entry was recorded. */
     createdAt: z.ZodString;
 }, "strict", z.ZodTypeAny, {
-    id: string;
     kind: "fact" | "decision" | "preference";
+    id: string;
     createdAt: string;
     content: string;
     scope: "project" | "user";
 }, {
-    id: string;
     kind: "fact" | "decision" | "preference";
+    id: string;
     createdAt: string;
     content: string;
     scope: "project" | "user";

package/dist/sandbox/docker-runtime.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { killTree, spawnTree } from "../utils/process-tree.js";
 import { sandboxExec, sandboxImage } from "../errors/index.js";
 /**
  * The shipped {@link SandboxRuntime}: shells out to the `docker` CLI (no SDK —
@@ -62,8 +63,11 @@ export class DockerRuntime {
             const capture = new OutputCapture(opts.maxOutputBytes, opts.capture);
             let child;
             try {
-                // `detached` groups the docker client so a timeout kills the whole tree.
-                child = spawn(this.bin, argv, { detached: true });
+                // `spawnTree` groups the docker client (POSIX process group / win32 OS
+                // tree) so a timeout reaps the whole tree via `killTree` on either OS —
+                // the docker CLIENT runs on the host, so on Windows this needs the
+                // taskkill walk, not a POSIX-only negative-PID signal.
+                child = spawnTree(this.bin, argv);
             }
             catch (err) {
                 reject(sandboxExec(err));
@@ -121,9 +125,8 @@ export class DockerRuntime {
     /** Best-effort container teardown after a timeout kill. */
     forceRemove(container) {
         try {
-            const rm = spawn(this.bin, ["rm", "-f", container], {
+            const rm = spawnTree(this.bin, ["rm", "-f", container], {
                 stdio: "ignore",
-                detached: true,
             });
             rm.on("error", () => { });
             rm.unref();
@@ -253,14 +256,3 @@ class OutputCapture {
         return { output: all.toString("utf8"), truncated: this.truncated };
     }
 }
-/** Kill the docker client's process group (POSIX; matches run_command). */
-function killTree(pid) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, "SIGKILL");
-    }
-    catch {
-        // Already exited, or no group — nothing to kill.
-    }
-}

package/dist/testing/run-tests-tool.js

@@ -141,6 +141,7 @@ export function makeRunTestsTool(deps = {}) {
                 cwd: ctx.cwd,
                 timeoutMs: ctx.config.shell.timeoutMs,
                 captureBytes: ctx.config.test.captureBytes,
+                shell: ctx.config.shell,
             });
             budget.record(result.passed);
             const payload = renderResult(result, resolved, {

package/dist/testing/runner.js

@@ -1,4 +1,5 @@
-import { spawn } from "node:child_process";
+import { killTree } from "../utils/process-tree.js";
+import { spawnShell } from "../tools/shell/resolve-shell.js";
 import { parseFailures } from "./parse.js";
 /**
  * The shipped {@link TestRunner}: spawn the command via the system shell (the
@@ -15,11 +16,11 @@ export class CommandTestRunner {
             const capture = new TailCapture(opts.captureBytes);
             let child;
             try {
-                child = spawn(command, {
-                    shell: true,
-                    cwd: opts.cwd,
-                    detached: true,
-                });
+                // Same seam as run_command: `spawnShell` routes through the resolved
+                // shell (Git Bash / PowerShell on Windows) and groups it as a killable
+                // tree (POSIX process group / win32 OS tree) so a timeout reaps the whole
+                // tree via `killTree`.
+                child = spawnShell(command, opts.shell, { cwd: opts.cwd });
             }
             catch (err) {
                 resolve(failed(null, err.message, startedAt));
@@ -111,14 +112,3 @@ export class TailCapture {
         return this.truncated ? `… [earlier output truncated]\n${body}` : body;
     }
 }
-/** Kill the whole process group (POSIX; matches run_command's behavior). */
-function killTree(pid) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, "SIGKILL");
-    }
-    catch {
-        // Already exited, or no group — nothing to kill.
-    }
-}

package/dist/testing/types.d.ts

@@ -4,6 +4,7 @@
  * under a hard cap. The cardinal rule lives in `runner.ts`: **passed is
  * derived from the exit code and nothing else.**
  */
+import type { ShellSelection } from "../tools/shell/resolve-shell.js";
 /** A resolved test command and where it came from — shown, never guessed. */
 export interface TestCommand {
     command: string;
@@ -40,10 +41,14 @@ export interface TestRunOptions {
     timeoutMs: number;
     /** Cap on captured output bytes (tail-biased). */
     captureBytes: number;
+    /** Shell selection, so the host runner routes through the resolved shell (Git
+     * Bash / PowerShell on Windows) — the same seam as run_command. The sandbox
+     * runner ignores it (the container has its own shell). */
+    shell: ShellSelection;
 }
 /**
  * The swappable execution seam (same discipline as VectorStore/ForgeProvider):
- * the shipped {@link CommandTestRunner} spawns the command via the system
+ * the shipped {@link CommandTestRunner} spawns the command via the resolved
  * shell; tests inject fakes, and a future framework-native runner (e.g. a
  * vitest API runner) slots in without touching the tool.
  */

package/dist/tools/shell/exec.js

@@ -1,4 +1,5 @@
-import { spawn } from "node:child_process";
+import { killTree } from "../../utils/process-tree.js";
+import { spawnShell } from "./resolve-shell.js";
 /**
  * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
  * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
@@ -50,9 +51,12 @@ async function runSandboxed(command, ctx) {
 function runBounded(command, ctx) {
     const { timeoutMs, maxOutputBytes } = ctx.config.shell;
     return new Promise((resolve) => {
-        // `detached` makes the child its own process-group leader so the whole tree
-        // (the shell plus anything it spawns) can be killed on timeout.
-        const child = spawn(command, { shell: true, cwd: ctx.cwd, detached: true });
+        // `spawnShell` routes through the resolved shell (POSIX default shell, Git
+        // Bash, or PowerShell — see resolve-shell.ts) as the head of a killable tree
+        // (its own process group on POSIX; the OS parent-PID tree on win32), so the
+        // whole tree — the shell plus anything it spawns — can be killed via
+        // `killTree`. A win32 host with no usable shell threw at session start.
+        const child = spawnShell(command, ctx.config.shell, { cwd: ctx.cwd });
         const chunks = [];
         let captured = 0;
         let truncated = false;
@@ -150,18 +154,3 @@ function runBounded(command, ctx) {
         });
     });
 }
-/**
- * Kill the command's entire process group. POSIX-specific (negative pid targets
- * the group); fine on our darwin/linux targets. Swallows errors — the process
- * may already be gone.
- */
-function killTree(pid) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, "SIGKILL");
-    }
-    catch {
-        // Already exited, or no group — nothing to kill.
-    }
-}

package/dist/tools/shell/resolve-shell.d.ts

@@ -0,0 +1,81 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+/**
+ * WHICH shell a host command runs through, and — just as important — WHICH
+ * dialect the model must emit for it. `run_command` and `run_tests` both spawn
+ * with the platform default shell (`{ shell: true }` → `/bin/sh` on POSIX,
+ * `%ComSpec%`/cmd.exe on win32). The model emits bash, so on Windows a command
+ * like `echo x; exit 1` runs as a single `echo`, exits 0, and reads as a false
+ * success. This module makes Windows host execution first-class instead:
+ *
+ *  Tier 0  `shell.executable` override → use it verbatim (the user owns it).
+ *  Tier 1  Git Bash (Git for Windows) → full POSIX parity, no model changes.
+ *  Tier 2  PowerShell (pwsh, else powershell.exe) → the model is told, via a
+ *          system-prompt directive keyed on {@link ShellPlan.dialect}, to emit
+ *          native PowerShell.
+ *  Tier 3  nothing usable → throw CRUXY_E_NO_SHELL. We NEVER hand bash-shaped
+ *          strings to cmd.exe silently — that is the exact false-green above.
+ *
+ * A non-default shell is ALWAYS invoked with explicit argv (`bash -c <cmd>`,
+ * `powershell -NoProfile -Command <cmd>`), never Node's `shell: <path>` string
+ * form: Node builds that command line with cmd.exe quoting rules, which mangle a
+ * command bound for bash/PowerShell. POSIX with no override keeps `shell: true`
+ * verbatim — a zero-change path off Windows.
+ */
+export type ShellDialect = "posix" | "powershell" | "cmd";
+export type ShellSource = "default" | "config" | "git-bash" | "powershell";
+/**
+ * The shell-selection fields the resolver reads — a structural subset of the
+ * config's `ShellConfig` (which also carries `timeoutMs`/`maxOutputBytes`). Kept
+ * narrow so callers and tests pass only what selection needs.
+ */
+export interface ShellSelection {
+    executable?: string;
+    dialect?: ShellDialect;
+}
+/** How to spawn a host command, and which dialect the model should emit for it. */
+export type ShellPlan = 
+/** POSIX default: `spawn(command, { shell: true })`, byte-identical to before. */
+{
+    kind: "system";
+    dialect: "posix";
+    source: "default";
+}
+/** Explicit shell binary + fixed flags; the command is the final argv element. */
+ | {
+    kind: "explicit";
+    file: string;
+    flags: readonly string[];
+    dialect: ShellDialect;
+    source: ShellSource;
+};
+/** Injected so the resolver's win32 logic is unit-testable on a POSIX CI host. */
+export interface ShellEnv {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    exists: (candidate: string) => boolean;
+}
+/**
+ * Infer a dialect from a shell path's basename, but ONLY for the unambiguous
+ * names — anything exotic (`nu`, `fish`, `xonsh`, …) returns undefined so the
+ * caller demands an explicit `shell.dialect` rather than guessing wrong.
+ */
+export declare function sniffDialect(executable: string): ShellDialect | undefined;
+/**
+ * Resolve the shell PLAN from config + environment. Pure over its injected
+ * {@link ShellEnv}, so the win32 tiers are exercised on any CI host. Throws
+ * CRUXY_E_NO_SHELL (no usable shell) or CRUXY_E_CONFIG_INVALID (an override
+ * whose dialect can't be determined) — both fail loud, never a silent fallback.
+ */
+export declare function computeShellPlan(shell: ShellSelection, env?: ShellEnv): ShellPlan;
+/** The memoized production resolver. Throws (fail loud) exactly as compute does. */
+export declare function resolveShell(shell: ShellSelection): ShellPlan;
+/** Test hook: drop the memoized plan so the next resolve re-detects. */
+export declare function __resetShellResolution(): void;
+/**
+ * Spawn `command` through the resolved shell as a killable process tree — the
+ * single seam both `run_command` and `run_tests` route through. `system` keeps
+ * the exact `{ shell: true }` spawn; every other plan invokes the shell binary
+ * with explicit argv so the command reaches bash/PowerShell unmangled (see the
+ * module header).
+ */
+export declare function spawnShell(command: string, shell: ShellSelection, options?: SpawnOptions): ChildProcess;

package/dist/tools/shell/resolve-shell.js

@@ -0,0 +1,158 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { spawnTree } from "../../utils/process-tree.js";
+import { CruxyError, ErrorCode } from "../../errors/types.js";
+const realEnv = {
+    platform: process.platform,
+    env: process.env,
+    exists: existsSync,
+};
+/** The invocation flags for each dialect (the command follows as one argv slot). */
+function flagsFor(dialect) {
+    switch (dialect) {
+        case "powershell":
+            // `-NoProfile` skips slow/interfering user profiles; `-Command` takes the
+            // command as one string argument.
+            return ["-NoProfile", "-Command"];
+        case "cmd":
+            return ["/d", "/s", "/c"];
+        case "posix":
+            return ["-c"];
+    }
+}
+function explicit(file, dialect, source) {
+    return { kind: "explicit", file, flags: flagsFor(dialect), dialect, source };
+}
+/**
+ * Infer a dialect from a shell path's basename, but ONLY for the unambiguous
+ * names — anything exotic (`nu`, `fish`, `xonsh`, …) returns undefined so the
+ * caller demands an explicit `shell.dialect` rather than guessing wrong.
+ */
+export function sniffDialect(executable) {
+    // Split on either separator so a POSIX or a Windows path both reduce to the
+    // bare shell name, then drop a trailing `.exe`.
+    const base = executable.split(/[\\/]/).pop() ?? executable;
+    const name = base.toLowerCase().replace(/\.exe$/, "");
+    switch (name) {
+        case "bash":
+        case "sh":
+            return "posix";
+        case "pwsh":
+        case "powershell":
+            return "powershell";
+        case "cmd":
+            return "cmd";
+        default:
+            return undefined;
+    }
+}
+/** True for the WSL launcher (`C:\Windows\System32\bash.exe`) — a Linux shell
+ * with `/mnt/c` path semantics, never Git Bash. Explicitly rejected. */
+function isWslBash(candidate) {
+    return /\\system32\\/i.test(candidate);
+}
+/** Probe the well-known Git-for-Windows install locations for `bash.exe`. */
+function findGitBash(env) {
+    const roots = [
+        env.env["ProgramFiles"],
+        env.env["ProgramW6432"],
+        env.env["ProgramFiles(x86)"],
+        env.env["LOCALAPPDATA"] &&
+            path.win32.join(env.env["LOCALAPPDATA"], "Programs"),
+    ].filter((r) => Boolean(r));
+    for (const root of roots) {
+        const candidate = path.win32.join(root, "Git", "bin", "bash.exe");
+        // Path-probe only — never `where bash`, which resolves the WSL launcher.
+        if (isWslBash(candidate))
+            continue;
+        if (env.exists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Resolve a bare executable name against PATH (+ the win32 PATH dir walk). */
+function onWindowsPath(name, env) {
+    const raw = env.env["PATH"] ?? env.env["Path"] ?? "";
+    for (const dir of raw.split(";").filter(Boolean)) {
+        const full = path.win32.join(dir, name);
+        if (env.exists(full))
+            return full;
+    }
+    return undefined;
+}
+/** PowerShell 7+ (`pwsh`) preferred; Windows PowerShell 5.1 the guaranteed floor. */
+function findPowerShell(env) {
+    return onWindowsPath("pwsh.exe", env) ?? onWindowsPath("powershell.exe", env);
+}
+/**
+ * Resolve the shell PLAN from config + environment. Pure over its injected
+ * {@link ShellEnv}, so the win32 tiers are exercised on any CI host. Throws
+ * CRUXY_E_NO_SHELL (no usable shell) or CRUXY_E_CONFIG_INVALID (an override
+ * whose dialect can't be determined) — both fail loud, never a silent fallback.
+ */
+export function computeShellPlan(shell, env = realEnv) {
+    // Tier 0: explicit override always wins, on every platform.
+    if (shell.executable) {
+        const dialect = shell.dialect ?? sniffDialect(shell.executable);
+        if (!dialect) {
+            throw new CruxyError({
+                code: ErrorCode.ConfigInvalid,
+                title: "Cannot determine the dialect of the configured shell",
+                cause: `shell.executable is "${shell.executable}", but its command dialect could not be inferred from its name.`,
+                nextSteps: ["Set shell.dialect to one of: posix, powershell, cmd."],
+            });
+        }
+        return explicit(shell.executable, dialect, "config");
+    }
+    // POSIX with no override: the historical default shell, byte-for-byte.
+    if (env.platform !== "win32") {
+        return { kind: "system", dialect: "posix", source: "default" };
+    }
+    // Tier 1: Git Bash → full POSIX parity, model unchanged.
+    const bash = findGitBash(env);
+    if (bash)
+        return explicit(bash, "posix", "git-bash");
+    // Tier 2: PowerShell → the model is told to emit PowerShell (see prompts.ts).
+    const ps = findPowerShell(env);
+    if (ps)
+        return explicit(ps, "powershell", "powershell");
+    // Tier 3: nothing usable — fail loud, never cmd.exe-pretends-to-be-bash.
+    throw new CruxyError({
+        code: ErrorCode.NoShell,
+        title: "No usable shell found to run commands",
+        cause: "On Windows, cruxy runs commands through Git Bash or PowerShell; neither was found, and no shell.executable override is set.",
+        nextSteps: [
+            "Install Git for Windows (https://git-scm.com/download/win) to get Git Bash.",
+            "Or set shell.executable in your cruxy config to a shell of your choice (and shell.dialect if its name is non-standard).",
+        ],
+    });
+}
+// Resolve once per process (JC#8): detection touches the filesystem, and the
+// answer is stable for a session. `computeShellPlan` stays the injectable,
+// un-memoized unit the tests drive.
+let cached;
+/** The memoized production resolver. Throws (fail loud) exactly as compute does. */
+export function resolveShell(shell) {
+    return (cached ??= computeShellPlan(shell));
+}
+/** Test hook: drop the memoized plan so the next resolve re-detects. */
+export function __resetShellResolution() {
+    cached = undefined;
+}
+/**
+ * Spawn `command` through the resolved shell as a killable process tree — the
+ * single seam both `run_command` and `run_tests` route through. `system` keeps
+ * the exact `{ shell: true }` spawn; every other plan invokes the shell binary
+ * with explicit argv so the command reaches bash/PowerShell unmangled (see the
+ * module header).
+ */
+export function spawnShell(command, shell, options = {}) {
+    const plan = resolveShell(shell);
+    if (plan.kind === "system") {
+        return spawnTree(command, [], { ...options, shell: true });
+    }
+    return spawnTree(plan.file, [...plan.flags, command], {
+        ...options,
+        shell: false,
+    });
+}

package/dist/utils/child-tree.d.ts

@@ -1,9 +1,11 @@
 /**
- * Shared no-orphan machinery for long-lived child processes (C.12 LSP servers,
- * C.27 MCP servers). A child is spawned `detached` so it leads its own process
- * group; every kill here uses a **negative-PID** `SIGKILL` so the whole tree —
- * the child AND any grandchildren it forked (gopls's `go`, an MCP server's
- * helper) — dies together.
+ * The process-EXIT backstop for long-lived child trees (C.12 LSP servers, C.27
+ * MCP servers). The platform-aware spawn/kill primitives themselves now live in
+ * {@link ./process-tree.js} — {@link killTree} is re-exported here unchanged so
+ * existing LSP/MCP importers keep their import path, and so this backstop and
+ * those transports reap trees the SAME way on every platform (negative-PID
+ * `SIGKILL` on POSIX, `taskkill /T /F` on win32 — no more orphaned grandchildren
+ * on Windows).
  *
  * A per-session graceful shutdown covers the normal path, but a hard exit
  * (Ctrl-C, an uncaught throw) would otherwise orphan these trees. So every live
@@ -15,12 +17,8 @@
  * and MCP (newline-delimited JSON) share the SAME backstop, so `killTrackedTrees`
  * on exit reaps both and there is a single source of truth for "no orphans".
  */
-/**
- * Kill a process's entire group (POSIX negative-PID `SIGKILL`), falling back to
- * a direct kill when there is no group (or on win32). Swallows errors — the
- * process may already be gone.
- */
-export declare function killTree(pid: number | undefined): void;
+import { killTree } from "./process-tree.js";
+export { killTree };
 /**
  * Force-kill the process group of every tracked-but-not-yet-shut-down child,
  * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`