@cruxy/cli 0.29.2 → 0.29.3

package/dist/cli/commands/mcp.js

@@ -131,7 +131,7 @@ export function mcpCommand() {
             ]);
         }
         const io = defaultOnboardingIO(shouldUseColor(process.stderr));
-        io.write(`${t.strong(`credential for "${server}"`)} ${t.muted(`(stored as "${ref}" in ~/.cruxy/credentials.json, 0600)`)}\n`);
+        io.write(`${t.strong(`credential for "${server}"`)} ${t.muted(`(stored as "${ref}" in ~/.cruxy/credentials.json, owner-only)`)}\n`);
         io.write(`${t.muted("paste the bearer token (input hidden): ")}`);
         const token = (await io.readSecret()).trim();
         if (!token) {

package/dist/config/credentials.d.ts

@@ -9,11 +9,10 @@ export declare function readCredential(provider: string, file?: string): string
  * secret is sourced from. Never throws.
  */
 export declare function readMcpCredential(ref: string, file?: string): string | undefined;
-/** Persist MCP bearer token for credential name `ref`. Same 0600/0700 as keys. */
+/** Persist MCP bearer token for credential name `ref`. Same owner-only guarantee. */
 export declare function writeMcpCredential(ref: string, token: string, file?: string): void;
 /**
- * Persist `key` for `provider`, merging into any existing store. The file is
- * written `0600` and its directory `0700` so the secret is owner-only — enforced
- * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ * Persist `key` for `provider`, merging into any existing store. Written
+ * owner-only (see {@link writeInto}); refuses loudly if that can't be enforced.
  */
 export declare function writeCredential(provider: string, key: string, file?: string): void;

package/dist/config/credentials.js

@@ -1,13 +1,23 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { CREDENTIALS_FILE_NAME } from "../constants.js";
+import { credentialsUnprotected } from "../errors/index.js";
+import { logger } from "../utils/logger.js";
+import { enforceOwnerOnly, isOwnerOnly } from "./owner-only.js";
 import { globalDir } from "./paths.js";
 /**
  * The credentials store (U.6) — the one place a provider API key is persisted.
  * It lives **outside** `config.json` on purpose: config is secret-free by design
  * ("the API key comes from env"), so secrets get their own file with restrictive
- * permissions (`0600`, dir `0700`), the same shape as gh/aws/npm. `resolveApiKey`
- * reads it as a fallback after the environment.
+ * permissions, the same shape as gh/aws/npm. `resolveApiKey` reads it as a
+ * fallback after the environment.
+ *
+ * "Restrictive" means **owner-only**: POSIX `0600` (dir `0700`), and on Windows
+ * an NTFS ACL granting only the current user (POSIX modes are meaningless there —
+ * see {@link enforceOwnerOnly}). The guarantee is enforced AND verified on every
+ * write; if it cannot be established the write is refused loudly
+ * (`CRUXY_E_CREDENTIALS_UNPROTECTED`) rather than persisting a secret at
+ * permissions we could not secure.
  */
 /** Bumped if the on-disk shape ever changes. */
 const CREDENTIALS_VERSION = 1;
@@ -15,6 +25,26 @@ const CREDENTIALS_VERSION = 1;
 export function credentialsPath() {
     return join(globalDir(), CREDENTIALS_FILE_NAME);
 }
+/** Paths already warned about this process, so a loose-perms warning fires once. */
+const warnedLoosePerms = new Set();
+/**
+ * Best-effort: warn (never refuse) if an existing store is readable beyond its
+ * owner, so an upgrade from a build that couldn't secure it isn't silently
+ * insecure — and isn't bricked either. Fires at most once per path per process.
+ */
+function warnIfLoosePerms(file) {
+    if (warnedLoosePerms.has(file))
+        return;
+    warnedLoosePerms.add(file);
+    try {
+        if (existsSync(file) && !isOwnerOnly(file)) {
+            logger.warn(`credentials store ${file} is not owner-only — other users on this machine may be able to read it. Re-run \`cruxy login\` (or re-store the MCP credential) to repair its permissions.`);
+        }
+    }
+    catch {
+        // Perms could not be inspected — stay silent rather than cry wolf.
+    }
+}
 /** Parse the store at `file`, or `null` if absent/unreadable/malformed. */
 function readStore(file) {
     if (!existsSync(file))
@@ -35,6 +65,7 @@ function readStore(file) {
 }
 /** The stored key for `provider`, or `undefined`. Never throws. */
 export function readCredential(provider, file = credentialsPath()) {
+    warnIfLoosePerms(file);
     const store = readStore(file);
     const key = store?.keys[provider];
     return typeof key === "string" && key !== "" ? key : undefined;
@@ -46,52 +77,74 @@ export function readCredential(provider, file = credentialsPath()) {
  * secret is sourced from. Never throws.
  */
 export function readMcpCredential(ref, file = credentialsPath()) {
+    warnIfLoosePerms(file);
     const store = readStore(file);
     const token = store?.mcp?.[ref];
     return typeof token === "string" && token !== "" ? token : undefined;
 }
-/** Persist MCP bearer token for credential name `ref`. Same 0600/0700 as keys. */
+/** Persist MCP bearer token for credential name `ref`. Same owner-only guarantee. */
 export function writeMcpCredential(ref, token, file = credentialsPath()) {
     writeInto(file, (store) => {
         store.mcp ??= {};
         store.mcp[ref] = token;
-    });
+    }, "mcp");
 }
 /**
- * Persist `key` for `provider`, merging into any existing store. The file is
- * written `0600` and its directory `0700` so the secret is owner-only — enforced
- * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ * Persist `key` for `provider`, merging into any existing store. Written
+ * owner-only (see {@link writeInto}); refuses loudly if that can't be enforced.
  */
 export function writeCredential(provider, key, file = credentialsPath()) {
     writeInto(file, (store) => {
         store.keys[provider] = key;
-    });
+    }, "provider");
 }
 /**
- * Merge `mutate` into the store and persist it owner-only: dir `0700`, file
- * `0600`, enforced with an explicit `chmod` after write (mkdir/write modes are
- * umask-masked). The one write path shared by every credential namespace.
+ * Merge `mutate` into the store and persist it owner-only. The one write path
+ * shared by every credential namespace, and the single place the owner-only
+ * guarantee is enforced:
+ *
+ *   1. The DIRECTORY is made owner-only FIRST, before any secret is written — so
+ *      the file inherits owner-only at creation (no window where it exists under
+ *      inherited permissions), and if the directory can't be secured we refuse
+ *      before a secret ever touches disk.
+ *   2. The new content is written to a temp file, made owner-only + VERIFIED,
+ *      then atomically renamed over the target. A failure removes the temp and
+ *      leaves any existing store untouched — never a torn or clobbered write.
+ *
+ * Enforcement runs on every write, so a pre-existing store with loose
+ * permissions is repaired in place. If owner-only cannot be established the write
+ * is refused with `CRUXY_E_CREDENTIALS_UNPROTECTED` (`kind` tailors the
+ * remediation: provider keys → env var; MCP tokens → no env fallback).
  */
-function writeInto(file, mutate) {
+function writeInto(file, mutate, kind) {
     const dir = dirname(file);
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    mkdirSync(dir, { recursive: true });
     try {
-        chmodSync(dir, 0o700);
+        enforceOwnerOnly(dir, { directory: true });
     }
-    catch {
-        // Best-effort on platforms without POSIX modes (e.g. Windows).
+    catch (err) {
+        // Refuse BEFORE writing any secret — nothing sensitive has hit disk yet.
+        throw credentialsUnprotected(kind, dir, err);
     }
     const store = readStore(file) ?? { version: CREDENTIALS_VERSION, keys: {} };
     store.version = CREDENTIALS_VERSION;
     mutate(store);
-    writeFileSync(file, JSON.stringify(store, null, 2) + "\n", {
+    const tmp = `${file}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", {
         encoding: "utf8",
         mode: 0o600,
     });
     try {
-        chmodSync(file, 0o600);
+        enforceOwnerOnly(tmp, { directory: false }); // sets + verifies, or throws
+        renameSync(tmp, file); // atomic replace; the owner-only ACL moves with it
     }
-    catch {
-        // Best-effort (see above).
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // The temp may already be gone; the target store is untouched regardless.
+        }
+        throw credentialsUnprotected(kind, file, err);
     }
 }

package/dist/config/owner-only.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Make `path` owner-only, or throw. On Windows the ACL is verified after the
+ * edit (both the `icacls` exit code AND a read-back), so a returned call is a
+ * genuine guarantee, never a best-effort attempt.
+ *
+ * @throws if owner-only permissions cannot be established (non-zero `icacls`,
+ *   an unresolvable SID, a filesystem without ACLs/modes, …).
+ */
+export declare function enforceOwnerOnly(path: string, opts?: {
+    directory?: boolean;
+}): void;
+/**
+ * Whether `path` is currently owner-only. POSIX: no group/other bits. Windows:
+ * best-effort — the ACL names no broad principal (Everyone / Authenticated
+ * Users / Users). Used both to verify {@link enforceOwnerOnly} and to warn on a
+ * pre-existing store with loose permissions. Returns `true` when it genuinely
+ * cannot tell (a missing tool), so a warning path never cries wolf.
+ */
+export declare function isOwnerOnly(path: string): boolean;

package/dist/config/owner-only.js

@@ -0,0 +1,114 @@
+import { execFileSync } from "node:child_process";
+import { chmodSync, statSync } from "node:fs";
+/**
+ * Cross-platform "owner-only" file/dir permissions — the one place that knows
+ * how to make a path readable by nobody but its owner, and how to check whether
+ * it already is.
+ *
+ * POSIX is `chmod` (`0600` file / `0700` dir). Windows has no POSIX modes —
+ * `fs.chmod` there only toggles the read-only attribute and never touches the
+ * NTFS ACL (a libuv limitation), so it is worthless for confidentiality. The
+ * Windows equivalent is an ACL edit via `icacls`: strip the inherited ACEs (the
+ * only source of "others" access on a fresh file) and grant Full to exactly the
+ * current user's SID.
+ *
+ * Every function here THROWS rather than swallowing a failure — the caller (the
+ * credential store) turns that into a loud refusal to persist a secret it can't
+ * secure. Nothing here silently claims success.
+ */
+const isWindows = process.platform === "win32";
+/** `undefined` = not yet resolved, `null` = resolution failed this process. */
+let cachedSid;
+/**
+ * The current user's SID (e.g. `S-1-5-21-…`) via `whoami /user`, resolved once
+ * and cached. We grant to the SID — never a name — so the ACL is correct
+ * regardless of the machine's display language (`BUILTIN\Users` etc. localise).
+ * Returns `null` if it cannot be determined.
+ */
+function currentUserSid() {
+    if (cachedSid !== undefined)
+        return cachedSid;
+    try {
+        const out = execFileSync("whoami", ["/user", "/fo", "csv", "/nh"], {
+            encoding: "utf8",
+        });
+        const m = out.match(/S-1-[0-9-]+/);
+        cachedSid = m ? m[0] : null;
+    }
+    catch {
+        cachedSid = null;
+    }
+    return cachedSid;
+}
+/**
+ * Make `path` owner-only, or throw. On Windows the ACL is verified after the
+ * edit (both the `icacls` exit code AND a read-back), so a returned call is a
+ * genuine guarantee, never a best-effort attempt.
+ *
+ * @throws if owner-only permissions cannot be established (non-zero `icacls`,
+ *   an unresolvable SID, a filesystem without ACLs/modes, …).
+ */
+export function enforceOwnerOnly(path, opts = {}) {
+    const directory = opts.directory ?? false;
+    if (isWindows) {
+        const sid = currentUserSid();
+        if (!sid) {
+            throw new Error("could not resolve the current user's SID (whoami failed) — cannot set an owner-only ACL");
+        }
+        // /inheritance:r removes inherited ACEs (where any "others" access comes
+        // from); /grant:r replaces the DACL with exactly this one grant. A directory
+        // grant carries (OI)(CI) so files created inside inherit owner-only at birth.
+        // The SID must be written `*S-1-…` — a bare token is read as an account NAME
+        // ("No mapping between account names and security IDs" otherwise).
+        const principal = `*${sid}`;
+        const grant = directory ? `${principal}:(OI)(CI)F` : `${principal}:F`;
+        try {
+            execFileSync("icacls", [path, "/inheritance:r", "/grant:r", grant], {
+                stdio: ["ignore", "ignore", "pipe"],
+            });
+        }
+        catch (err) {
+            const stderr = err.stderr?.toString().trim();
+            throw new Error(`icacls could not restrict "${path}"${stderr ? `: ${stderr}` : ""}`);
+        }
+    }
+    else {
+        chmodSync(path, directory ? 0o700 : 0o600);
+    }
+    // Verify the end state rather than trust the set — the guarantee is the point.
+    if (!isOwnerOnly(path)) {
+        throw new Error(`"${path}" is not owner-only after attempting to restrict it`);
+    }
+}
+/**
+ * Whether `path` is currently owner-only. POSIX: no group/other bits. Windows:
+ * best-effort — the ACL names no broad principal (Everyone / Authenticated
+ * Users / Users). Used both to verify {@link enforceOwnerOnly} and to warn on a
+ * pre-existing store with loose permissions. Returns `true` when it genuinely
+ * cannot tell (a missing tool), so a warning path never cries wolf.
+ */
+export function isOwnerOnly(path) {
+    if (!isWindows) {
+        return (statSync(path).mode & 0o077) === 0;
+    }
+    let out;
+    try {
+        out = execFileSync("icacls", [path], { encoding: "utf8" });
+    }
+    catch {
+        return true; // can't inspect → don't raise a false alarm
+    }
+    // `icacls <path>` resolves SIDs to names (locale-dependent on non-English
+    // Windows, hence best-effort): flag the well-known broad principals by name
+    // and by SID for the cases icacls leaves a SID unresolved.
+    const broad = [
+        /\bEveryone\b/i,
+        /\bAuthenticated Users\b/i,
+        /\bBUILTIN\\Users\b/i,
+        /\\Users:/i,
+        /S-1-1-0/, // Everyone
+        /S-1-5-11/, // Authenticated Users
+        /S-1-5-32-545/, // BUILTIN\Users
+    ];
+    return !broad.some((re) => re.test(out));
+}

package/dist/config/schema.d.ts

@@ -1796,6 +1796,22 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval: {
         mode: "prompt";
     };
+    mcp: {
+        startupTimeout: number;
+        requestTimeout: number;
+        servers: Record<string, {
+            args: string[];
+            env: Record<string, string>;
+            command?: string | undefined;
+            credentialRef?: string | undefined;
+            url?: string | undefined;
+            headers?: Record<string, string> | undefined;
+        }>;
+        enabled: boolean;
+        maxToolsPerServer: number;
+        maxDescriptionChars: number;
+        maxSchemaBytes: number;
+    };
     subagent: {
         maxDepth: number;
         maxConcurrency: number;
@@ -1879,22 +1895,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
         default?: "kavi" | "vaani" | "mira" | undefined;
     };
-    mcp: {
-        startupTimeout: number;
-        requestTimeout: number;
-        servers: Record<string, {
-            args: string[];
-            env: Record<string, string>;
-            command?: string | undefined;
-            credentialRef?: string | undefined;
-            url?: string | undefined;
-            headers?: Record<string, string> | undefined;
-        }>;
-        enabled: boolean;
-        maxToolsPerServer: number;
-        maxDescriptionChars: number;
-        maxSchemaBytes: number;
-    };
     web: {
         provider: "tavily";
         timeoutMs: number;
@@ -1951,6 +1951,22 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval?: {
         mode?: "prompt" | undefined;
     } | undefined;
+    mcp?: {
+        startupTimeout?: number | undefined;
+        requestTimeout?: number | undefined;
+        servers?: Record<string, {
+            command?: string | undefined;
+            credentialRef?: string | undefined;
+            url?: string | undefined;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }> | undefined;
+        enabled?: boolean | undefined;
+        maxToolsPerServer?: number | undefined;
+        maxDescriptionChars?: number | undefined;
+        maxSchemaBytes?: number | undefined;
+    } | undefined;
     subagent?: {
         maxDepth?: number | undefined;
         maxConcurrency?: number | undefined;
@@ -2034,22 +2050,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
         default?: "kavi" | "vaani" | "mira" | undefined;
     } | undefined;
-    mcp?: {
-        startupTimeout?: number | undefined;
-        requestTimeout?: number | undefined;
-        servers?: Record<string, {
-            command?: string | undefined;
-            credentialRef?: string | undefined;
-            url?: string | undefined;
-            args?: string[] | undefined;
-            env?: Record<string, string> | undefined;
-            headers?: Record<string, string> | undefined;
-        }> | undefined;
-        enabled?: boolean | undefined;
-        maxToolsPerServer?: number | undefined;
-        maxDescriptionChars?: number | undefined;
-        maxSchemaBytes?: number | undefined;
-    } | undefined;
     web?: {
         provider?: "tavily" | undefined;
         timeoutMs?: number | undefined;

package/dist/errors/constructors.d.ts

@@ -24,6 +24,15 @@ export declare function configParse(path: string, underlying?: unknown): CruxyEr
 export declare function configInvalid(issues: string, path?: string): CruxyError;
 export declare function authMissingKey(provider: string, envVar: string): CruxyError;
 export declare function authInvalid(underlying?: unknown): CruxyError;
+/**
+ * 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 declare function credentialsUnprotected(kind: "provider" | "mcp", path: string, underlying?: unknown): CruxyError;
 export declare function gatewayUnreachable(underlying?: unknown): CruxyError;
 export declare function apiError(underlying?: unknown): CruxyError;
 export declare function apiRateLimit(underlying?: unknown): CruxyError;

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";

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",
@@ -249,6 +255,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,

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/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/testing/runner.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { killTree, spawnTree } from "../utils/process-tree.js";
 import { parseFailures } from "./parse.js";
 /**
  * The shipped {@link TestRunner}: spawn the command via the system shell (the
@@ -15,11 +15,10 @@ export class CommandTestRunner {
             const capture = new TailCapture(opts.captureBytes);
             let child;
             try {
-                child = spawn(command, {
-                    shell: true,
-                    cwd: opts.cwd,
-                    detached: true,
-                });
+                // 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 });
             }
             catch (err) {
                 resolve(failed(null, err.message, startedAt));
@@ -111,14 +110,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/tools/shell/exec.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { killTree, spawnTree } from "../../utils/process-tree.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 +50,10 @@ 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 });
+        // `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 });
         const chunks = [];
         let captured = 0;
         let truncated = false;
@@ -150,18 +151,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/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`

package/dist/utils/child-tree.js

@@ -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,26 +17,10 @@
  * 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 function killTree(pid) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, "SIGKILL");
-    }
-    catch {
-        try {
-            process.kill(pid, "SIGKILL");
-        }
-        catch {
-            /* already exited */
-        }
-    }
-}
+import { killTree } from "./process-tree.js";
+// Re-exported so LSP/MCP transports (and their tests) keep importing `killTree`
+// from here; the implementation is the shared, platform-aware one.
+export { killTree };
 const livePids = new Set();
 let handlersInstalled = false;
 /**

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

@@ -0,0 +1,16 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+/**
+ * Spawn a child as the head of a killable process tree, applying the
+ * platform-correct grouping options on top of the caller's own (`shell`, `cwd`,
+ * `stdio`, `env`, …). Any `detached`/`windowsHide` the caller passes is
+ * overridden — grouping is this module's responsibility, not the call site's.
+ */
+export declare function spawnTree(command: string, args?: readonly string[], options?: SpawnOptions): ChildProcess;
+/**
+ * Kill a child's ENTIRE process tree — the child and every descendant it
+ * spawned. POSIX: negative-PID `SIGKILL` targets the process group created by
+ * {@link spawnTree}'s `detached`. win32: `taskkill /PID <pid> /T /F` walks the
+ * OS tree (`/T`) and force-terminates it (`/F`). Fire-and-forget and
+ * error-swallowing on both paths — the tree may already be gone.
+ */
+export declare function killTree(pid: number | undefined): void;

package/dist/utils/process-tree.js

@@ -0,0 +1,81 @@
+import { spawn, } from "node:child_process";
+/**
+ * The single platform-aware primitive for spawning a killable process tree and
+ * reaping it whole. Both halves — {@link spawnTree} and {@link killTree} — MUST
+ * come from here as a pair, because how a child is spawned decides how its tree
+ * can be killed, and the two differ by platform:
+ *
+ * - POSIX: spawn `detached` so the child leads its own process group, then kill
+ *   the whole group with a negative-PID `SIGKILL`. One signal reaps the shell
+ *   AND everything it forked (a `shell:true` grandchild, gopls's `go`, …).
+ * - win32: there is no process-group signalling to lean on. `detached` there
+ *   means "new console / new group" — the wrong semantics, and a flashing
+ *   window. So we DON'T detach (just `windowsHide`), and kill by walking the
+ *   real OS parent-PID tree with `taskkill /T /F`, which a negative-PID signal
+ *   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
+ * 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.
+ */
+const isWindows = process.platform === "win32";
+/**
+ * Spawn a child as the head of a killable process tree, applying the
+ * platform-correct grouping options on top of the caller's own (`shell`, `cwd`,
+ * `stdio`, `env`, …). Any `detached`/`windowsHide` the caller passes is
+ * overridden — grouping is this module's responsibility, not the call site's.
+ */
+export function spawnTree(command, args = [], options = {}) {
+    const grouped = isWindows
+        ? { ...options, detached: false, windowsHide: true }
+        : { ...options, detached: true };
+    return spawn(command, args, grouped);
+}
+/**
+ * Kill a child's ENTIRE process tree — the child and every descendant it
+ * spawned. POSIX: negative-PID `SIGKILL` targets the process group created by
+ * {@link spawnTree}'s `detached`. win32: `taskkill /PID <pid> /T /F` walks the
+ * OS tree (`/T`) and force-terminates it (`/F`). Fire-and-forget and
+ * error-swallowing on both paths — the tree may already be gone.
+ */
+export function killTree(pid) {
+    if (pid === undefined)
+        return;
+    if (isWindows) {
+        killTreeWindows(pid);
+        return;
+    }
+    try {
+        // Negative PID = "the whole group led by `pid`", not just `pid`.
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}
+/**
+ * Reap `pid`'s tree via `taskkill`. The killer is itself a child process, so we
+ * reap IT too: `stdio: "ignore"` gives it nothing to block on, the `error`
+ * handler swallows a missing-`taskkill`/EPIPE rejection (an unhandled `error`
+ * event would otherwise crash the process), and `unref` keeps this short-lived
+ * helper from holding the event loop open. taskkill exits on its own; we neither
+ * wait for it nor let it leak.
+ */
+function killTreeWindows(pid) {
+    try {
+        const killer = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        killer.on("error", () => {
+            // taskkill unavailable (should not happen on win32) — nothing more to do.
+        });
+        killer.unref();
+    }
+    catch {
+        // Even the spawn attempt failed — the tree, if any, outlives us. Nothing
+        // more we can do from here.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.29.2",
+  "version": "0.29.3",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -29,7 +29,6 @@
     "directory": "packages/cli"
   },
   "dependencies": {
-    "better-sqlite3": "^12.11.1",
     "commander": "^12.1.0",
     "fastembed": "^2.1.0",
     "picocolors": "^1.1.1",
@@ -39,6 +38,9 @@
     "zod-to-json-schema": "^3.23.5",
     "@cruxy/sdk": "0.2.1"
   },
+  "optionalDependencies": {
+    "better-sqlite3": "^12.11.1"
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.0",