@cruxy/cli 0.29.3 → 0.29.4

package/dist/agent/loop.js

@@ -1,6 +1,7 @@
 import { CruxyError, providerUnsupported } from "../errors/index.js";
 import { resolveTaskModel, } from "../routing/index.js";
 import { buildSystemPrompt } from "./prompts.js";
+import { resolveShell } from "../tools/shell/resolve-shell.js";
 /** Tools whose successful call is a file change (drives the `on-file-change`
  * hook). Kept in sync with the file-mutating tool set. */
 const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "apply_patch"]);
@@ -45,6 +46,10 @@ async function driveLoop(args, renderer, routed) {
     let messages = [...args.messages];
     const usage = { input_tokens: 0, output_tokens: 0 };
     const maxIterations = config.agent.maxIterations;
+    // Resolve the host shell up front (JC#8) so a Windows box with no usable shell
+    // fails loud NOW (CRUXY_E_NO_SHELL) rather than mid-task, and the model gets the
+    // dialect directive from turn 1. Memoized, so run_command / run_tests reuse it.
+    const shellPlan = resolveShell(config.shell);
     // The tool catalogue and environment are stable across the loop, so build the
     // system prompt once. The builder degrades gracefully when git is null.
     const system = buildSystemPrompt({
@@ -60,6 +65,7 @@ async function driveLoop(args, renderer, routed) {
         recalledMemory: args.recalledMemory ?? null,
         planMode: args.planMode ?? false,
         subagent: args.subagent ?? false,
+        shellDialect: shellPlan.dialect,
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {

package/dist/agent/prompts.d.ts

@@ -6,6 +6,7 @@
  * dynamic environment block, so the model always knows where it is, what it
  * can do, and how it's expected to behave.
  */
+import type { ShellDialect } from "../tools/shell/resolve-shell.js";
 export interface ToolSummary {
     name: string;
 }
@@ -38,6 +39,13 @@ export interface PromptContext {
     planMode?: boolean;
     /** Subagent run (C.14): inject the bounded-subtask directive. */
     subagent?: boolean;
+    /**
+     * The resolved shell's command dialect (from resolve-shell.ts). When it is not
+     * a POSIX shell — e.g. PowerShell, because no Git Bash was found on Windows —
+     * a directive tells the model to emit that dialect instead of bash. Absent /
+     * "posix" → no directive (bash-isms are correct there; a nudge would be wrong).
+     */
+    shellDialect?: ShellDialect;
 }
 /** Assemble the full system prompt for a session. */
 export declare function buildSystemPrompt(ctx: PromptContext): string;

package/dist/agent/prompts.js

@@ -70,6 +70,29 @@ function renderEnvironment(ctx) {
     }
     return `## Environment\n${lines.join("\n")}`;
 }
+/**
+ * The command-dialect directive (JC#4). Emitted ONLY for a non-POSIX shell:
+ * under bash / Git Bash the model's default bash syntax is correct, so a "use
+ * PowerShell" nudge would be actively wrong. Keeps the model from emitting
+ * bash-isms that a Windows PowerShell/cmd shell would silently mis-run.
+ */
+function renderShellDialect(dialect) {
+    if (!dialect || dialect === "posix")
+        return null;
+    if (dialect === "powershell") {
+        return `## Shell dialect
+\`run_command\` and \`run_tests\` execute through **PowerShell**, not a POSIX/bash shell. Emit native PowerShell:
+- Sequence with \`;\`; run-on-success with \`if ($?) { ... }\` — NOT bash \`&&\` / \`||\`.
+- Environment variables are \`$env:NAME\` (read) and \`$env:NAME = "v"\` (set) — never \`$NAME\` or \`export NAME=\`.
+- Discard output with \`2>$null\` / \`| Out-Null\`, not \`2>/dev/null\`; no heredocs or single-quote-escaping tricks.
+Cross-platform tools (npm, pnpm, git, cargo, node, python) take the same arguments here as anywhere.`;
+    }
+    return `## Shell dialect
+\`run_command\` and \`run_tests\` execute through **cmd.exe**, not a POSIX/bash shell. Emit native cmd:
+- Sequence with \`&\`; environment variables are \`%NAME%\`; set them with \`set NAME=value\`.
+- No bash constructs (\`export\`, single-quoted strings, \`2>/dev/null\`, heredocs).
+Cross-platform tools (npm, git, cargo, node) take the same arguments here as anywhere.`;
+}
 function renderTools(tools) {
     if (tools.length === 0) {
         return "## Tools\nNo tools are available this session; respond in text only.";
@@ -89,6 +112,9 @@ export function buildSystemPrompt(ctx) {
     const approval = "Side-effecting actions (file writes, shell commands) require the user's approval; destructive or irreversible actions are flagged distinctly.";
     const core = CORE.replace("${APPROVAL_CLAUSE}", approval);
     const sections = [core, renderEnvironment(ctx), renderTools(ctx.tools)];
+    const dialect = renderShellDialect(ctx.shellDialect);
+    if (dialect)
+        sections.push(dialect);
     if (ctx.planMode)
         sections.push(PLAN_MODE_SECTION);
     if (ctx.subagent)

package/dist/cli/commands/test.js

@@ -25,6 +25,7 @@ export function testCommand() {
             cwd,
             timeoutMs: config.shell.timeoutMs,
             captureBytes: config.test.captureBytes,
+            shell: config.shell,
         });
         const seconds = (result.durationMs / 1000).toFixed(1);
         if (result.passed) {

package/dist/config/schema.d.ts

@@ -105,13 +105,34 @@ export declare const ShellConfigSchema: z.ZodObject<{
     timeoutMs: z.ZodDefault<z.ZodNumber>;
     /** Cap on combined stdout+stderr bytes captured; the rest is truncated. */
     maxOutputBytes: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Explicit shell to run commands through, overriding platform detection. A
+     * path (`/bin/bash`, `C:\\Program Files\\Git\\bin\\bash.exe`, `pwsh`). When
+     * set it WINS over the Git Bash → PowerShell tiering (see resolve-shell.ts):
+     * the user owns the choice. Unset → POSIX uses the default shell; Windows
+     * probes for Git Bash, then PowerShell, then fails loud (CRUXY_E_NO_SHELL).
+     */
+    executable: z.ZodOptional<z.ZodString>;
+    /**
+     * The command dialect of `executable`, so the model is told which syntax to
+     * emit. Only sniffed automatically for unambiguous basenames (bash/sh →
+     * posix, pwsh/powershell → powershell, cmd → cmd); set this for anything else
+     * or the override is rejected (CRUXY_E_CONFIG_INVALID). Ignored without
+     * `executable`.
+     */
+    dialect: z.ZodOptional<z.ZodEnum<["posix", "powershell", "cmd"]>>;
 }, "strict", z.ZodTypeAny, {
     timeoutMs: number;
     maxOutputBytes: number;
+    executable?: string | undefined;
+    dialect?: "posix" | "powershell" | "cmd" | undefined;
 }, {
     timeoutMs?: number | undefined;
     maxOutputBytes?: number | undefined;
+    executable?: string | undefined;
+    dialect?: "posix" | "powershell" | "cmd" | undefined;
 }>;
+export type ShellConfig = z.infer<typeof ShellConfigSchema>;
 /** Context-window management: when to compact the running conversation. */
 export declare const ContextConfigSchema: z.ZodObject<{
     /** Approximate model context budget, in tokens (heuristic estimate). */
@@ -1096,12 +1117,32 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         /** Cap on combined stdout+stderr bytes captured; the rest is truncated. */
         maxOutputBytes: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Explicit shell to run commands through, overriding platform detection. A
+         * path (`/bin/bash`, `C:\\Program Files\\Git\\bin\\bash.exe`, `pwsh`). When
+         * set it WINS over the Git Bash → PowerShell tiering (see resolve-shell.ts):
+         * the user owns the choice. Unset → POSIX uses the default shell; Windows
+         * probes for Git Bash, then PowerShell, then fails loud (CRUXY_E_NO_SHELL).
+         */
+        executable: z.ZodOptional<z.ZodString>;
+        /**
+         * The command dialect of `executable`, so the model is told which syntax to
+         * emit. Only sniffed automatically for unambiguous basenames (bash/sh →
+         * posix, pwsh/powershell → powershell, cmd → cmd); set this for anything else
+         * or the override is rejected (CRUXY_E_CONFIG_INVALID). Ignored without
+         * `executable`.
+         */
+        dialect: z.ZodOptional<z.ZodEnum<["posix", "powershell", "cmd"]>>;
     }, "strict", z.ZodTypeAny, {
         timeoutMs: number;
         maxOutputBytes: number;
+        executable?: string | undefined;
+        dialect?: "posix" | "powershell" | "cmd" | undefined;
     }, {
         timeoutMs?: number | undefined;
         maxOutputBytes?: number | undefined;
+        executable?: string | undefined;
+        dialect?: "posix" | "powershell" | "cmd" | undefined;
     }>>;
     context: z.ZodDefault<z.ZodObject<{
         /** Approximate model context budget, in tokens (heuristic estimate). */
@@ -1830,6 +1871,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     shell: {
         timeoutMs: number;
         maxOutputBytes: number;
+        executable?: string | undefined;
+        dialect?: "posix" | "powershell" | "cmd" | undefined;
     };
     agent: {
         maxIterations: number;
@@ -1985,6 +2028,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     shell?: {
         timeoutMs?: number | undefined;
         maxOutputBytes?: number | undefined;
+        executable?: string | undefined;
+        dialect?: "posix" | "powershell" | "cmd" | undefined;
     } | undefined;
     agent?: {
         maxIterations?: number | undefined;

package/dist/config/schema.js

@@ -85,6 +85,22 @@ export const ShellConfigSchema = z
     timeoutMs: z.number().int().positive().default(120000),
     /** Cap on combined stdout+stderr bytes captured; the rest is truncated. */
     maxOutputBytes: z.number().int().positive().default(102400),
+    /**
+     * Explicit shell to run commands through, overriding platform detection. A
+     * path (`/bin/bash`, `C:\\Program Files\\Git\\bin\\bash.exe`, `pwsh`). When
+     * set it WINS over the Git Bash → PowerShell tiering (see resolve-shell.ts):
+     * the user owns the choice. Unset → POSIX uses the default shell; Windows
+     * probes for Git Bash, then PowerShell, then fails loud (CRUXY_E_NO_SHELL).
+     */
+    executable: z.string().min(1).optional(),
+    /**
+     * The command dialect of `executable`, so the model is told which syntax to
+     * emit. Only sniffed automatically for unambiguous basenames (bash/sh →
+     * posix, pwsh/powershell → powershell, cmd → cmd); set this for anything else
+     * or the override is rejected (CRUXY_E_CONFIG_INVALID). Ignored without
+     * `executable`.
+     */
+    dialect: z.enum(["posix", "powershell", "cmd"]).optional(),
 })
     .strict();
 /** Context-window management: when to compact the running conversation. */

package/dist/errors/types.d.ts

@@ -207,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

@@ -228,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
@@ -360,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/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/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 { killTree, spawnTree } from "../utils/process-tree.js";
+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,10 +16,11 @@ export class CommandTestRunner {
             const capture = new TailCapture(opts.captureBytes);
             let child;
             try {
-                // Same killable-tree discipline as run_command: `spawnTree` groups the
-                // shell (POSIX process group / win32 OS tree) so a timeout can reap the
-                // whole tree via `killTree`.
-                child = spawnTree(command, [], { shell: true, cwd: opts.cwd });
+                // 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));

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 { killTree, spawnTree } from "../../utils/process-tree.js";
+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,10 +51,12 @@ async function runSandboxed(command, ctx) {
 function runBounded(command, ctx) {
     const { timeoutMs, maxOutputBytes } = ctx.config.shell;
     return new Promise((resolve) => {
-        // `spawnTree` makes the child 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 on timeout via `killTree`.
-        const child = spawnTree(command, [], { shell: true, cwd: ctx.cwd });
+        // `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;

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/process-tree.js

@@ -15,10 +15,13 @@ import { spawn, } from "node:child_process";
  *   could never do on Windows (it would kill only the direct child and orphan
  *   the grandchildren).
  *
- * This module exists because that pairing used to be copy-pasted — three
+ * This module exists because that pairing used to be copy-pasted — four
  * POSIX-only `killTree` variants (run_command, the test runner, the LSP/MCP
- * backstop), each of which silently orphaned grandchildren on Windows. There is
- * now one implementation; a change to the kill discipline changes every path.
+ * backstop, and the docker client), each of which silently orphaned
+ * grandchildren on Windows. There is now one implementation; a change to the
+ * kill discipline changes every path. Spawn sites likewise route through
+ * `spawnTree` (run_command, run_tests, LSP, MCP, docker) so none re-introduces
+ * the win32 `detached` console-flash the grouping logic exists to avoid.
  */
 const isWindows = process.platform === "win32";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.29.3",
+  "version": "0.29.4",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {