@indigoai-us/hq-cli 5.98.0 → 5.98.2

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [Unreleased]
 
+## [5.98.2] — 2026-08-11
+
+### Fixed
+
+- `hq core hq-status-summary` — and through it the `/handoff` status summary —
+  no longer crashes, or files a Sentry report, on a mature HQ root (HQ-CLI-N,
+  Sentry 7664842324). The shared `command()` helper behind the native `hq core`
+  utilities ran `spawnSync` with no `maxBuffer`, so every child inherited Node's
+  1 MiB default. `hq-status-summary` shells out to `git status --porcelain
+  --ignored`, whose output exceeds 1 MiB on any HQ root carrying the usual
+  individually-ignored files alongside tracked content; Node then killed git with
+  SIGTERM, handed back truncated stdout, and surfaced `Error: spawnSync git
+  ENOBUFS`, failing the handoff (observed once, from a single user). The helper
+  now caps captured output at 512 MiB — the same ceiling the repo already uses
+  for git reads — matching the bundled shell oracle, which redirects git straight
+  to a temp file and has no ceiling at all. Spawn errors stay fatal, so a
+  truncated status is never reported as a real summary, and an ENOBUFS above the
+  new ceiling now throws an error naming the command, its args, and the cap
+  instead of the opaque original.
+
+## [5.98.1] — 2026-08-10
+
+### Fixed
+
+- Every qmd-backed surface (`hq index`, `hq index status`, `hq search`,
+  `hq search get`, and the background reindex) no longer crashes — or files a
+  Sentry report — on Windows (HQ-CLI-M, Sentry 7663851953). The CLI resolved the
+  bundled qmd to the npm-generated batch shim `node_modules\.bin\qmd.cmd` and
+  spawned it with no shell, but since Node's CVE-2024-27980 hardening (all of
+  Node 22) Node refuses to run a `.cmd`/`.bat` without a shell and returns
+  `EINVAL`. That surfaced as an unactionable `QmdBinaryMissingError` on every
+  Windows install. The bundled qmd is now dispatched shell-free through its Node
+  launcher (`node <@tobilu/qmd>/bin/qmd`), so the `.cmd` shim — and cmd.exe — is
+  off the default path entirely and user search text is never handed to a shell.
+  A resolved `.cmd`/`.bat` that does reach a spawn (an `HQ_QMD_BIN` override or a
+  PATH shim) now goes through a properly quoted shell plan instead of a bare
+  `EINVAL` spawn, the qmd usability probe and the one-shot native-binding repair
+  path (including `prebuild-install.cmd` / `node-gyp.cmd` resolution) are fixed
+  the same way, and the resolver's diagnostics now report a spawn failure as a
+  spawn failure rather than mislabelling it "native bindings unbuilt". The one
+  Windows spawn policy (`buildSpawnPlan`) is now shared by the self-update path
+  and the qmd path, and additionally quotes the command path (not just argv) so
+  an absolute path containing spaces is passed intact.
+
 ## [5.98.0] — 2026-08-10
 
 ## [5.97.3] — 2026-08-10

package/dist/bin/hq-auth-refresh.d.ts

@@ -11,4 +11,5 @@
  * non-interactively.
  */
 import "../node-preflight.js";
+import "../node-network-compat.js";
 //# sourceMappingURL=hq-auth-refresh.d.ts.map

package/dist/bin/hq-auth-refresh.js

@@ -13,6 +13,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "../node-preflight.js";
+import "../node-network-compat.js";
 import { initSentry, Sentry } from "../sentry.js";
 import { refreshCachedSession } from "../utils/cognito-session.js";
 initSentry();

package/dist/commands/index-cmd.js

@@ -111,8 +111,12 @@ export function registerIndexCommand(program, dependencies = defaults) {
         let registered;
         let qmdStatus;
         try {
-            registered = dependencies.listRegisteredCollections(hqRoot, { bin, cwd: hqRoot });
-            qmdStatus = dependencies.runQmd(['status'], { bin, cwd: hqRoot });
+            // Dispatch WITHOUT an explicit bin so these calls resolve through the
+            // shell-free Node launcher (resolveQmdInvocation), instead of spawning
+            // the bundled `.cmd` shim bare — the exact frame that crashed on Windows
+            // with EINVAL. `bin` above stays the display/version identity only.
+            registered = dependencies.listRegisteredCollections(hqRoot, { cwd: hqRoot });
+            qmdStatus = dependencies.runQmd(['status'], { cwd: hqRoot });
         }
         catch (error) {
             if (!isQmdNativeBindingError(error))

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import "./node-preflight.js";
+import "./node-network-compat.js";
 declare function isVersionRequest(argv: readonly string[]): boolean;
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;

package/dist/index.js

@@ -2,6 +2,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
+import "./node-network-compat.js";
 import { CLI_VERSION } from "./cli-version.js";
 function isVersionRequest(argv) {
     const args = argv.slice(2);

package/dist/lib/core-utils/common.js

@@ -9,10 +9,34 @@ export function ioFor(io = {}) {
 export function line(write, value) {
     write(`${value}\n`);
 }
+/**
+ * Ceiling for a single child's captured stdout, mirroring the git-read cap the
+ * repo already uses (src/utils/large-file-guard.ts:48). spawnSync defaults
+ * maxBuffer to 1 MiB; once a child's output crosses that, Node kills it with
+ * SIGTERM and hands back TRUNCATED stdout plus an ENOBUFS error. `hq core
+ * hq-status-summary` runs `git status --porcelain --ignored`, whose output
+ * exceeds 1 MiB on any mature HQ root (the individually-ignored files that sit
+ * beside tracked content), so the default turned a routine /handoff status
+ * summary into a crash. The bundled shell oracle this module ports
+ * (assets/scaffold/core/scripts/hq-status-summary.sh:108) redirects git straight
+ * to a temp file and has no ceiling at all; an explicit, generous cap matches it.
+ */
+const MAX_SPAWN_BUFFER = 512 * 1024 * 1024;
 export function command(command, args, cwd) {
-    const result = spawnSync(command, args, { cwd, encoding: "utf8" });
-    if (result.error)
-        throw result.error;
+    const result = spawnSync(command, args, { cwd, encoding: "utf8", maxBuffer: MAX_SPAWN_BUFFER });
+    // Spawn errors stay fatal: a truncated child result must never be reported as
+    // a real one — that would silently under-count a handoff's status instead of
+    // failing loudly. Above the new ceiling ENOBUFS is still theoretically
+    // reachable, so wrap it to name the command, its args and the cap; a future
+    // recurrence then arrives in Sentry self-diagnosed instead of as the opaque
+    // "spawnSync <cmd> ENOBUFS".
+    if (result.error) {
+        const error = result.error;
+        if (error.code === "ENOBUFS") {
+            throw new Error(`spawnSync ${command} ${args.join(" ")} exceeded the ${MAX_SPAWN_BUFFER}-byte output ceiling`, { cause: error });
+        }
+        throw error;
+    }
     return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 }
 export function exists(pathname) {

package/dist/lib/search-index/index.d.ts

@@ -8,6 +8,47 @@ export type QmdProcessRunner = (bin: string, args: string[], options: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }) => QmdProcessResult;
+/**
+ * How to actually launch qmd. A bare string bin cannot express the shell-free
+ * bundled path on Windows, where npm/pnpm generate a `.cmd` batch shim that Node
+ * refuses to spawn without a shell (CVE-2024-27980 → EINVAL). So a resolved qmd
+ * is an invocation: `command` plus fixed `prefixArgs` that precede the user's
+ * argv.
+ *
+ *   - Bundled node entry (preferred): `{ command: process.execPath,
+ *     prefixArgs: [<@tobilu/qmd launcher>], execDir: <dir of node> }` — spawned
+ *     shell-free on every platform, so user search text never traverses cmd.exe.
+ *   - Every legacy path (HQ_QMD_BIN, a PATH hit, the `.bin` shim): `{ command:
+ *     bin, prefixArgs: [] }` — spawned shell-free unless it is a Windows
+ *     `.cmd`/`.bat`, which is routed through the quoted shell plan.
+ *
+ * `execDir` is set only for the node entry: qmd's launcher re-spawns the bare
+ * name `node`, so the child env PATH is prefixed with the running Node's
+ * directory (the reported install put its toolchain Node off PATH).
+ */
+export type QmdInvocation = {
+    command: string;
+    prefixArgs: string[];
+    execDir?: string;
+};
+/** Low-level spawn seam (defaults to `spawnSync`); injected in tests. */
+export type QmdSpawn = (cmd: string, args: string[], options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    encoding: 'utf8';
+    timeout?: number;
+    shell?: boolean;
+}) => {
+    status: number | null;
+    stdout?: string;
+    stderr?: string;
+    error?: Error;
+};
+/**
+ * Prefix `execDir` onto the child env PATH so a node-entry launcher can re-spawn
+ * the bare name `node`. Returns the env unchanged when there is nothing to add.
+ */
+export declare function withNodeDirOnPath(env: NodeJS.ProcessEnv | undefined, execDir: string | undefined, platform?: NodeJS.Platform): NodeJS.ProcessEnv | undefined;
 export declare class QmdBinaryMissingError extends Error {
     name: string;
 }
@@ -52,6 +93,19 @@ export type ResolveQmdBinOptions = {
  * independent of the dependency's own exports map.
  */
 export declare function packageLocalBin(): string | undefined;
+/**
+ * Locate the bundled qmd's Node LAUNCHER — `@tobilu/qmd`'s `bin.qmd` entry
+ * (`bin/qmd`, a `#!/usr/bin/env node` script) — by the same upward walk
+ * {@link resolveQmdVersion} uses to find the package. Returns the absolute
+ * launcher path only when both the manifest and the launcher file exist.
+ *
+ * This is the shell-free preferred resolution: invoking `node <launcher>`
+ * bypasses the npm-generated `.cmd` shim entirely, so the Windows CVE-2024-27980
+ * EINVAL never arises and no user-supplied search text reaches cmd.exe. A
+ * missing/partial layout returns undefined so the caller falls back to the
+ * `.bin` shim (which the shared spawn plan now makes spawnable on Windows too).
+ */
+export declare function packageLocalNodeEntry(): string | undefined;
 /**
  * Return the pinned package version when qmd is supplied by this CLI.
  *
@@ -62,7 +116,23 @@ export declare function packageLocalBin(): string | undefined;
 export declare function resolveQmdVersion(): string | undefined;
 /** Reset per-process probe/repair memoisation. Test-only. */
 export declare function __resetQmdProbeStateForTests(): void;
+/** Probe a resolved invocation, memoised per invocation; records the failure
+ * detail under the qmd bin identity so repair can read it. */
+export declare function isUsableInvocation(invocation: QmdInvocation, options?: {
+    platform?: NodeJS.Platform;
+    spawn?: QmdSpawn;
+}): boolean;
+/** Backwards-compatible string form: probe a bare bin path shell-free (or via
+ * the shell plan when it is a Windows `.cmd`/`.bat`). */
 export declare function isUsableQmd(bin: string): boolean;
+/**
+ * Honest one-line reason a package-local qmd probe failed, for the resolver's
+ * probes note. A spawn-level failure — the binary could not be executed at all
+ * (the Windows `.cmd` EINVAL, or ENOENT) — must NOT be described as "native
+ * bindings unbuilt": that wording is exactly what sent this Windows EINVAL down
+ * the native-bindings story. Only a genuine better-sqlite3 load failure keeps it.
+ */
+export declare function describeProbeFailure(detail: string): string;
 /**
  * Derive the better-sqlite3 PACKAGE directory qmd tried to load, from a bindings
  * failure. `bindings` lists every path it tried, each ending in
@@ -92,6 +162,8 @@ export type QmdRepairOptions = {
     failureDetail?: string;
     /** Injected in tests so the real build tools are never spawned. */
     spawn?: RepairSpawn;
+    /** Injectable platform so the Windows shim resolution is provable on Linux CI. */
+    platform?: NodeJS.Platform;
 };
 /**
  * Bounded, one-shot self-repair of a package-local qmd whose better-sqlite3
@@ -106,13 +178,54 @@ export type QmdRepairOptions = {
  * waits unbounded, and never touches anything outside hq's own dependency tree.
  */
 export declare function repairQmdNativeBindings(bin: string, options?: QmdRepairOptions): boolean;
+/**
+ * Resolve a dependency executable better-sqlite3 would run at install time. pnpm
+ * links a package's dependency bins into the SIBLING `.bin` of its virtual-store
+ * `node_modules` (`.pnpm/better-sqlite3@x/node_modules/.bin/<tool>`), NOT inside
+ * `better-sqlite3/node_modules/.bin`; npm's hoisted layout and some pnpm configs
+ * use the nested form. Check both so the self-repair works on the pnpm-installed
+ * hosts it exists for. Both candidates sit inside the already-confined tree.
+ */
+export declare function resolveRepairTool(betterSqlite3Dir: string, tool: string, platform?: NodeJS.Platform): string | undefined;
 /** Resolve qmd without relying on a globally installed copy. */
 export declare function resolveQmdBin(options?: ResolveQmdBinOptions): string;
+export type ResolveQmdInvocationOptions = {
+    env?: Record<string, string | undefined>;
+    isExecutable?: (candidate: string) => boolean;
+    /** Locate the bundled qmd's Node launcher (preferred). Defaults to {@link packageLocalNodeEntry}. */
+    packageNodeEntry?: () => string | undefined;
+    /** Locate the bundled qmd's `.bin` shim (fallback). Defaults to {@link packageLocalBin}. */
+    packageBin?: () => string | undefined;
+    pathBin?: () => string | undefined;
+    isUsable?: (invocation: QmdInvocation) => boolean;
+    repair?: (bin: string) => boolean;
+    /** Injectable platform / Node path so Windows resolution is provable on Linux CI. */
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    /** Low-level spawn seam threaded into the usability probe. */
+    spawn?: QmdSpawn;
+};
+/**
+ * Resolve HOW to launch qmd, preferring the shell-free Node launcher for the
+ * bundled copy so the Windows `.cmd` shim (and its CVE-2024-27980 EINVAL) is
+ * never on the default path. Mirrors {@link resolveQmdBin}'s contract — explicit
+ * HQ_QMD_BIN honoured verbatim, probe + one bounded repair, PATH fallback, and a
+ * classified (not opaque) last resort — but returns an invocation instead of a
+ * bare string.
+ */
+export declare function resolveQmdInvocation(options?: ResolveQmdInvocationOptions): QmdInvocation;
 export type RunQmdOptions = {
     bin?: string;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     runner?: QmdProcessRunner;
+    /** Low-level spawn seam (default `spawnSync`); injected in tests. */
+    spawn?: QmdSpawn;
+    /** Injectable platform / Node path so Windows dispatch is provable on Linux CI. */
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    /** Invocation resolver seam (default {@link resolveQmdInvocation}). */
+    resolveInvocation?: (options: ResolveQmdInvocationOptions) => QmdInvocation;
 };
 /** Run qmd with captured output and typed failures. */
 export declare function runQmd(args: string[], options?: RunQmdOptions): QmdProcessResult;

package/dist/lib/search-index/index.js

@@ -5,7 +5,23 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js';
+import { planCommandSpawn } from '../../utils/windows-spawn.js';
 const require = createRequire(import.meta.url);
+/** The `path` implementation for a (possibly injected) platform. */
+function pathFor(platform) {
+    return platform === 'win32' ? path.win32 : path.posix;
+}
+/**
+ * Prefix `execDir` onto the child env PATH so a node-entry launcher can re-spawn
+ * the bare name `node`. Returns the env unchanged when there is nothing to add.
+ */
+export function withNodeDirOnPath(env, execDir, platform = process.platform) {
+    if (!execDir)
+        return env;
+    const delimiter = pathFor(platform).delimiter;
+    const current = env?.PATH ?? '';
+    return { ...env, PATH: current ? `${execDir}${delimiter}${current}` : execDir };
+}
 export class QmdBinaryMissingError extends Error {
     name = 'QmdBinaryMissingError';
 }
@@ -67,6 +83,47 @@ export function packageLocalBin() {
     }
     return undefined;
 }
+/**
+ * Locate the bundled qmd's Node LAUNCHER — `@tobilu/qmd`'s `bin.qmd` entry
+ * (`bin/qmd`, a `#!/usr/bin/env node` script) — by the same upward walk
+ * {@link resolveQmdVersion} uses to find the package. Returns the absolute
+ * launcher path only when both the manifest and the launcher file exist.
+ *
+ * This is the shell-free preferred resolution: invoking `node <launcher>`
+ * bypasses the npm-generated `.cmd` shim entirely, so the Windows CVE-2024-27980
+ * EINVAL never arises and no user-supplied search text reaches cmd.exe. A
+ * missing/partial layout returns undefined so the caller falls back to the
+ * `.bin` shim (which the shared spawn plan now makes spawnable on Windows too).
+ */
+export function packageLocalNodeEntry() {
+    let directory = path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth++) {
+        const manifest = path.join(directory, 'node_modules', '@tobilu', 'qmd', 'package.json');
+        if (fs.existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+                const bin = parsed.bin;
+                const relative = typeof bin === 'string'
+                    ? bin
+                    : bin && typeof bin === 'object' && typeof bin.qmd === 'string'
+                        ? bin.qmd
+                        : undefined;
+                if (relative) {
+                    const launcher = path.join(path.dirname(manifest), relative);
+                    if (fs.existsSync(launcher))
+                        return launcher;
+                }
+            }
+            catch { /* unreadable/partial manifest: fall back to the .bin shim */ }
+            return undefined;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return undefined;
+}
 /**
  * Return the pinned package version when qmd is supplied by this CLI.
  *
@@ -130,19 +187,69 @@ export function __resetQmdProbeStateForTests() {
     lastProbeFailure.clear();
     nativeBindingRepairAttempted = false;
 }
+/** The qmd file identity of an invocation: the launcher for a node entry, else
+ * the command. Used to key probe failures and confine native-binding repair. */
+function invocationBin(invocation) {
+    return invocation.prefixArgs.length > 0
+        ? invocation.prefixArgs[invocation.prefixArgs.length - 1]
+        : invocation.command;
+}
+/** Cache key for a resolved invocation (command + fixed prefix args). */
+function invocationKey(invocation) {
+    return [invocation.command, ...invocation.prefixArgs].join('');
+}
+/** Default low-level spawn: `spawnSync` with captured utf8 output. */
+const defaultSpawn = (cmd, args, options) => {
+    const result = spawnSync(cmd, args, {
+        cwd: options.cwd,
+        env: options.env,
+        encoding: 'utf8',
+        timeout: options.timeout,
+        shell: options.shell,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? undefined,
+        stderr: result.stderr ?? undefined,
+        error: result.error,
+    };
+};
+/**
+ * Spawn a resolved qmd invocation through the shared Windows-aware plan
+ * ({@link planCommandSpawn}): shell-free everywhere except a Windows `.cmd`/`.bat`
+ * target, which is routed through the quoted shell so Node's CVE-2024-27980
+ * hardening does not reject it with EINVAL. A node-entry invocation additionally
+ * gets the running Node's directory prefixed onto the child PATH so the
+ * launcher's bare `node` re-spawn resolves.
+ */
+function spawnQmd(invocation, args, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const spawn = options.spawn ?? defaultSpawn;
+    const fullArgs = [...invocation.prefixArgs, ...args];
+    const plan = planCommandSpawn(invocation.command, fullArgs, platform);
+    const env = withNodeDirOnPath(options.env, invocation.execDir, platform);
+    return spawn(plan.cmd, plan.args, {
+        cwd: options.cwd,
+        env,
+        encoding: 'utf8',
+        timeout: options.timeout,
+        shell: plan.shell,
+    });
+}
 /**
- * Does this qmd binary actually OPEN ITS STORE? The 5.94.2 probe spawned
+ * Does this qmd invocation actually OPEN ITS STORE? The 5.94.2 probe spawned
  * `--version`, which prints and exits 0 even when better-sqlite3's native module
- * is missing — the exact false positive that let this cluster ship (HQ-CLI-J):
- * it passed on precisely the bindings-broken install it was added to reject.
- * `collection list` instead opens the SQLite database, which is the operation
- * that fails when `better_sqlite3.node` was never built.
+ * is missing — the exact false positive that let HQ-CLI-J ship. `collection
+ * list` instead opens the SQLite database, which is the operation that fails
+ * when `better_sqlite3.node` was never built. It is also spawned through the
+ * shared plan, so probing a Windows `.cmd` shim reports its real result rather
+ * than a spurious EINVAL.
  *
  * The probe is pointed at a throwaway INDEX_PATH / QMD_CONFIG_DIR / HOME so it
  * NEVER creates or mutates the user's real qmd store, and is bounded by a hard
- * timeout. Callers cache the boolean per path so resolution stays one spawn.
+ * timeout. Callers cache the boolean per invocation so resolution stays one spawn.
  */
-function probeQmd(bin) {
+function probeQmd(invocation, options = {}) {
     let scratch;
     try {
         scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-qmd-probe-'));
@@ -154,11 +261,12 @@ function probeQmd(bin) {
             XDG_CONFIG_HOME: path.join(scratch, 'xdg-config'),
             XDG_CACHE_HOME: path.join(scratch, 'xdg-cache'),
         };
-        const probe = spawnSync(bin, ['collection', 'list'], {
+        const probe = spawnQmd(invocation, ['collection', 'list'], {
             cwd: scratch,
             env,
-            encoding: 'utf8',
             timeout: PROBE_TIMEOUT_MS,
+            platform: options.platform,
+            spawn: options.spawn,
         });
         if (probe.error)
             return { usable: false, detail: probe.error.message };
@@ -178,18 +286,42 @@ function probeQmd(bin) {
         }
     }
 }
-export function isUsableQmd(bin) {
-    const cached = usableQmdCache.get(bin);
+/** Probe a resolved invocation, memoised per invocation; records the failure
+ * detail under the qmd bin identity so repair can read it. */
+export function isUsableInvocation(invocation, options = {}) {
+    const key = invocationKey(invocation);
+    const cached = usableQmdCache.get(key);
     if (cached !== undefined)
         return cached;
-    const result = probeQmd(bin);
-    usableQmdCache.set(bin, result.usable);
+    const result = probeQmd(invocation, options);
+    usableQmdCache.set(key, result.usable);
+    const bin = invocationBin(invocation);
     if (result.usable)
         lastProbeFailure.delete(bin);
     else
         lastProbeFailure.set(bin, result.detail);
     return result.usable;
 }
+/** Backwards-compatible string form: probe a bare bin path shell-free (or via
+ * the shell plan when it is a Windows `.cmd`/`.bat`). */
+export function isUsableQmd(bin) {
+    return isUsableInvocation({ command: bin, prefixArgs: [] });
+}
+/**
+ * Honest one-line reason a package-local qmd probe failed, for the resolver's
+ * probes note. A spawn-level failure — the binary could not be executed at all
+ * (the Windows `.cmd` EINVAL, or ENOENT) — must NOT be described as "native
+ * bindings unbuilt": that wording is exactly what sent this Windows EINVAL down
+ * the native-bindings story. Only a genuine better-sqlite3 load failure keeps it.
+ */
+export function describeProbeFailure(detail) {
+    if (/\b(?:EINVAL|ENOENT|EACCES|ENOEXEC)\b/.test(detail) || /^spawnSync\b/.test(detail)) {
+        return 'present but could not be spawned';
+    }
+    if (isQmdNativeBindingError(detail))
+        return 'present but native bindings unbuilt';
+    return 'present but unusable';
+}
 /** Native-binding self-repair is on unless explicitly disabled. */
 function repairEnabled(env) {
     const flag = env.HQ_QMD_NO_REPAIR;
@@ -232,12 +364,17 @@ export function repairConfinedTo(qmdBin, betterSqlite3Dir) {
     return commonAncestor.includes('node_modules') || commonAncestor.includes('.pnpm');
 }
 const defaultRepairSpawn = (cmd, args, opts) => {
-    const result = spawnSync(cmd, args, {
+    // Route through the shared plan: on Windows a repair tool is a `.cmd` shim
+    // (prebuild-install.cmd / node-gyp.cmd) that Node refuses to spawn without a
+    // shell, exactly like the qmd shim itself.
+    const plan = planCommandSpawn(cmd, args);
+    const result = spawnSync(plan.cmd, plan.args, {
         cwd: opts.cwd,
         env: opts.env,
         timeout: opts.timeout,
         encoding: 'utf8',
         stdio: 'ignore',
+        shell: plan.shell,
     });
     return { status: result.status, error: result.error };
 };
@@ -277,7 +414,7 @@ export function repairQmdNativeBindings(bin, options = {}) {
         try {
             const env = { ...process.env, ...(options.env ?? {}) };
             const spawn = options.spawn ?? defaultRepairSpawn;
-            runBetterSqlite3Install(betterSqlite3Dir, env, spawn);
+            runBetterSqlite3Install(betterSqlite3Dir, env, spawn, options.platform ?? process.platform);
         }
         finally {
             try {
@@ -321,27 +458,36 @@ function acquireRepairLock(lockDir) {
  * use the nested form. Check both so the self-repair works on the pnpm-installed
  * hosts it exists for. Both candidates sit inside the already-confined tree.
  */
-function resolveRepairTool(betterSqlite3Dir, tool) {
-    const candidates = [
-        path.join(path.dirname(betterSqlite3Dir), '.bin', tool), // pnpm virtual-store sibling
-        path.join(betterSqlite3Dir, 'node_modules', '.bin', tool), // nested (npm / some pnpm)
+export function resolveRepairTool(betterSqlite3Dir, tool, platform = process.platform) {
+    // On Windows, npm/pnpm generate a `.cmd` shim (and sometimes `.exe`) for a JS
+    // bin; the extensionless file is a POSIX sh script Node cannot spawn there.
+    // Prefer the platform-appropriate shim so the one-shot native-binding repair is
+    // reachable on Windows too, not just POSIX — otherwise the repair path hits the
+    // same EINVAL/ENOEXEC as the primary qmd spawn.
+    const names = platform === 'win32' ? [`${tool}.cmd`, `${tool}.exe`, tool] : [tool];
+    const dirs = [
+        path.join(path.dirname(betterSqlite3Dir), '.bin'), // pnpm virtual-store sibling
+        path.join(betterSqlite3Dir, 'node_modules', '.bin'), // nested (npm / some pnpm)
     ];
-    for (const candidate of candidates) {
-        if (fs.existsSync(candidate))
-            return candidate;
+    for (const dir of dirs) {
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
     }
     return undefined;
 }
 /** Run better-sqlite3's declared install step: prebuild-install, then node-gyp. */
-function runBetterSqlite3Install(dir, env, spawn) {
+function runBetterSqlite3Install(dir, env, spawn, platform) {
     const artifact = path.join(dir, 'build', 'Release', 'better_sqlite3.node');
-    const prebuild = resolveRepairTool(dir, 'prebuild-install');
+    const prebuild = resolveRepairTool(dir, 'prebuild-install', platform);
     if (prebuild) {
         spawn(prebuild, [], { cwd: dir, env, timeout: REPAIR_STEP_TIMEOUT_MS });
         if (fs.existsSync(artifact))
             return;
     }
-    const nodeGyp = resolveRepairTool(dir, 'node-gyp');
+    const nodeGyp = resolveRepairTool(dir, 'node-gyp', platform);
     if (nodeGyp) {
         spawn(nodeGyp, ['rebuild', '--release'], { cwd: dir, env, timeout: REPAIR_STEP_TIMEOUT_MS });
     }
@@ -383,7 +529,7 @@ export function resolveQmdBin(options = {}) {
                     return installed;
             }
         }
-        probes.push(`package-local @tobilu/qmd (${installed}, present but native bindings unbuilt)`);
+        probes.push(`package-local @tobilu/qmd (${installed}, ${describeProbeFailure(lastProbeFailure.get(installed) ?? '')})`);
     }
     else {
         probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
@@ -403,30 +549,130 @@ export function resolveQmdBin(options = {}) {
         return installed;
     throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
 }
-function defaultRunner(bin, args, options) {
-    const result = spawnSync(bin, args, { cwd: options.cwd, env: options.env, encoding: 'utf8' });
-    return {
+/**
+ * Resolve HOW to launch qmd, preferring the shell-free Node launcher for the
+ * bundled copy so the Windows `.cmd` shim (and its CVE-2024-27980 EINVAL) is
+ * never on the default path. Mirrors {@link resolveQmdBin}'s contract — explicit
+ * HQ_QMD_BIN honoured verbatim, probe + one bounded repair, PATH fallback, and a
+ * classified (not opaque) last resort — but returns an invocation instead of a
+ * bare string.
+ */
+export function resolveQmdInvocation(options = {}) {
+    const env = options.env ?? process.env;
+    const executable = options.isExecutable ?? isExecutable;
+    const platform = options.platform ?? process.platform;
+    const execPath = options.execPath ?? process.execPath;
+    const isUsable = options.isUsable
+        ?? ((invocation) => isUsableInvocation(invocation, { platform, spawn: options.spawn }));
+    const probes = [];
+    const override = env.HQ_QMD_BIN;
+    if (override) {
+        // An explicit user choice is honoured verbatim: never probe or repair a
+        // binary the operator pointed us at.
+        if (executable(override))
+            return { command: override, prefixArgs: [] };
+        probes.push(`HQ_QMD_BIN (${override})`);
+    }
+    else {
+        probes.push('HQ_QMD_BIN (not set)');
+    }
+    const nodeEntry = (options.packageNodeEntry ?? packageLocalNodeEntry)();
+    const shim = (options.packageBin ?? packageLocalBin)();
+    const onPath = (options.pathBin ?? pathBin)();
+    const fallback = onPath && executable(onPath) ? onPath : undefined;
+    // The bundled qmd, PREFERRING the shell-free Node launcher over the `.cmd`/`.bat`
+    // shim. `bundledBin` keeps the qmd file identity (the launcher, else the shim)
+    // for probe-failure keying and repair-tree confinement. The launcher is read by
+    // Node, not exec'd, so it needs existence (guaranteed by packageLocalNodeEntry),
+    // not the +x bit.
+    let bundled;
+    let bundledBin;
+    if (nodeEntry) {
+        bundled = { command: execPath, prefixArgs: [nodeEntry], execDir: pathFor(platform).dirname(execPath) };
+        bundledBin = nodeEntry;
+    }
+    else if (shim && executable(shim)) {
+        bundled = { command: shim, prefixArgs: [] };
+        bundledBin = shim;
+    }
+    if (bundled && bundledBin) {
+        // Executable is not the same as usable: a bundled qmd can be present yet fail
+        // to open its SQLite store (pnpm 10 skips better-sqlite3's build). ALWAYS
+        // probe, then attempt one bounded native-binding repair before giving up.
+        if (isUsable(bundled))
+            return bundled;
+        if (repairEnabled(env)) {
+            const repair = options.repair ?? repairQmdNativeBindings;
+            if (repair(bundledBin)) {
+                usableQmdCache.delete(invocationKey(bundled));
+                if (isUsable(bundled))
+                    return bundled;
+            }
+        }
+        probes.push(`package-local @tobilu/qmd (${bundledBin}, ${describeProbeFailure(lastProbeFailure.get(bundledBin) ?? '')})`);
+    }
+    else {
+        probes.push(`package-local @tobilu/qmd (${shim ?? nodeEntry ?? 'not found'})`);
+    }
+    // A working qmd on PATH is the right answer when the bundled one is broken.
+    if (fallback)
+        return { command: fallback, prefixArgs: [] };
+    probes.push(`qmd on PATH (${onPath ?? 'not found'})`);
+    // Last resort: no usable qmd anywhere, but the bundled binary IS present. Hand
+    // it back rather than throwing an opaque error — running it yields a classified
+    // failure (native-binding remedy + no Sentry) instead of an unactionable crash.
+    if (bundled)
+        return bundled;
+    throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
+}
+/** Normalise a spawn result and raise the typed qmd failures. */
+function finishRunQmd(result, bin, args) {
+    const normalized = {
         status: result.status,
         stdout: result.stdout ?? '',
         stderr: result.stderr ?? '',
         error: result.error,
     };
+    if (normalized.error) {
+        throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${normalized.error.message}`);
+    }
+    if (normalized.status === 0)
+        return normalized;
+    const detail = normalized.stderr || normalized.stdout || 'qmd returned no diagnostic output';
+    const message = `qmd ${args.join(' ')} exited with ${normalized.status ?? 'an unknown status'}: ${detail}`;
+    if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {
+        throw new QmdCollectionMissingError(message, args, normalized.status, normalized.stdout, normalized.stderr);
+    }
+    throw new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
 }
 /** Run qmd with captured output and typed failures. */
 export function runQmd(args, options = {}) {
-    const bin = options.bin ?? resolveQmdBin({ env: options.env });
-    const result = (options.runner ?? defaultRunner)(bin, args, { cwd: options.cwd, env: options.env });
-    if (result.error) {
-        throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${result.error.message}`);
-    }
-    if (result.status === 0)
-        return result;
-    const detail = result.stderr || result.stdout || 'qmd returned no diagnostic output';
-    const message = `qmd ${args.join(' ')} exited with ${result.status ?? 'an unknown status'}: ${detail}`;
-    if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {
-        throw new QmdCollectionMissingError(message, args, result.status, result.stdout, result.stderr);
+    // Legacy string-bin runner seam (tests and callers that inject a fake process):
+    // honoured exactly as before via the (bin, args, options) signature.
+    if (options.runner) {
+        const bin = options.bin ?? resolveQmdBin({ env: options.env });
+        const result = options.runner(bin, args, { cwd: options.cwd, env: options.env });
+        return finishRunQmd(result, bin, args);
     }
-    throw new QmdExitError(message, args, result.status, result.stdout, result.stderr);
+    // Default path: resolve the full invocation (shell-free Node launcher preferred)
+    // and spawn it through the shared Windows-aware plan. An explicit string bin is
+    // wrapped as a legacy invocation; a `.cmd`/`.bat` there is routed through the
+    // quoted shell plan by planCommandSpawn rather than spawned bare (EINVAL).
+    const invocation = options.bin
+        ? { command: options.bin, prefixArgs: [] }
+        : (options.resolveInvocation ?? resolveQmdInvocation)({
+            env: options.env,
+            platform: options.platform,
+            execPath: options.execPath,
+            spawn: options.spawn,
+        });
+    const result = spawnQmd(invocation, args, {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        platform: options.platform,
+        spawn: options.spawn,
+    });
+    return finishRunQmd(result, invocationBin(invocation), args);
 }
 function containsIndexedMarkdown(directory) {
     if (!fs.existsSync(directory))

package/dist/main.d.ts

@@ -3,6 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 import "./node-preflight.js";
+import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
 export declare function runCli(): Promise<void>;
 export type TopLevelErrorDependencies = {

package/dist/main.js

@@ -5,6 +5,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
+import "./node-network-compat.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";

package/dist/node-network-compat.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Node network defaults for HQ CLI entry points.
+ *
+ * Node's default 250 ms address-family attempt window can fail on hosts where
+ * IPv6 is advertised but black-holed. On affected WSL installations, undici's
+ * fetch() reaches ETIMEDOUT before its usable IPv4 path completes. A 1 second
+ * window fixes the connection while retaining Node's automatic family choice.
+ *
+ * Keep this module dependency-free and import it immediately after the Node
+ * version preflight. Operators can retain a custom value through NODE_OPTIONS
+ * or a direct Node CLI option; HQ only supplies the compatibility default when
+ * neither is present.
+ *
+ * Use a namespace import of `node:net` (not a static named import of
+ * `setDefaultAutoSelectFamilyAttemptTimeout`). Named ESM imports are linked
+ * before any entry-module body runs — including `node-preflight` — so importing
+ * a Node 18.13+/20.4+ API by name would turn unsupported runtimes into a
+ * module-link SyntaxError instead of the preflight's upgrade message.
+ */
+export declare const HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS = 1000;
+export interface NodeNetworkCompatibilityOptions {
+    nodeOptions?: string;
+    execArgv?: readonly string[];
+    /**
+     * Inject the net timeout setter (tests). Pass `null` to simulate a runtime
+     * that lacks `setDefaultAutoSelectFamilyAttemptTimeout`.
+     */
+    setAttemptTimeout?: ((milliseconds: number) => void) | null;
+}
+export declare function configureNodeNetworkCompatibility(options?: NodeNetworkCompatibilityOptions): boolean;
+//# sourceMappingURL=node-network-compat.d.ts.map

package/dist/node-network-compat.js

@@ -0,0 +1,52 @@
+/**
+ * Node network defaults for HQ CLI entry points.
+ *
+ * Node's default 250 ms address-family attempt window can fail on hosts where
+ * IPv6 is advertised but black-holed. On affected WSL installations, undici's
+ * fetch() reaches ETIMEDOUT before its usable IPv4 path completes. A 1 second
+ * window fixes the connection while retaining Node's automatic family choice.
+ *
+ * Keep this module dependency-free and import it immediately after the Node
+ * version preflight. Operators can retain a custom value through NODE_OPTIONS
+ * or a direct Node CLI option; HQ only supplies the compatibility default when
+ * neither is present.
+ *
+ * Use a namespace import of `node:net` (not a static named import of
+ * `setDefaultAutoSelectFamilyAttemptTimeout`). Named ESM imports are linked
+ * before any entry-module body runs — including `node-preflight` — so importing
+ * a Node 18.13+/20.4+ API by name would turn unsupported runtimes into a
+ * module-link SyntaxError instead of the preflight's upgrade message.
+ */
+import * as nodeNet from "node:net";
+export const HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS = 1000;
+const ATTEMPT_TIMEOUT_OPTION = "--network-family-autoselection-attempt-timeout";
+function hasExplicitAttemptTimeout(nodeOptions, execArgv) {
+    const optionPattern = new RegExp(`(?:^|\\s)${ATTEMPT_TIMEOUT_OPTION}(?:=|\\s|$)`);
+    return (optionPattern.test(nodeOptions) ||
+        execArgv.some((argument) => argument === ATTEMPT_TIMEOUT_OPTION ||
+            argument.startsWith(`${ATTEMPT_TIMEOUT_OPTION}=`)));
+}
+function resolveSetAttemptTimeout(override) {
+    if (override === null)
+        return undefined;
+    if (override)
+        return override;
+    const fn = nodeNet.setDefaultAutoSelectFamilyAttemptTimeout;
+    return typeof fn === "function" ? fn.bind(nodeNet) : undefined;
+}
+export function configureNodeNetworkCompatibility(options = {}) {
+    const nodeOptions = options.nodeOptions ?? process.env.NODE_OPTIONS ?? "";
+    const execArgv = options.execArgv ?? process.execArgv;
+    if (hasExplicitAttemptTimeout(nodeOptions, execArgv)) {
+        return false;
+    }
+    const setAttemptTimeout = resolveSetAttemptTimeout(options.setAttemptTimeout);
+    if (!setAttemptTimeout) {
+        // Runtime lacks the API (pre-Node 18.13 / preflight should already have exited).
+        return false;
+    }
+    setAttemptTimeout(HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS);
+    return true;
+}
+configureNodeNetworkCompatibility();
+//# sourceMappingURL=node-network-compat.js.map

package/dist/utils/version-gate.d.ts

@@ -27,6 +27,7 @@
  * Opt-out: `HQ_NO_UPDATE_CHECK=1` (same env as `version-check.ts` — one knob
  * to silence both check + gate).
  */
+import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
 /** Which package manager owns the running global install. */
 export type InstallManager = "npm" | "pnpm";
 export interface VersionCheckResponse {
@@ -146,26 +147,7 @@ export type UpdateResult = {
     code?: string;
 };
 type UpdateRunner = (cmd: string, args: string[]) => UpdateResult;
-/**
- * Quote an argv entry for a Windows `cmd.exe` invocation. Needed because Node
- * does NOT quote argv when spawning with `shell: true` on Windows — it joins
- * the array with spaces — so an npm prefix like `C:\Program Files\…` would be
- * split into two arguments.
- */
-export declare function quoteForWindowsShell(arg: string): string;
-/**
- * How to hand `<cmd> <args…>` to `spawnSync` on this platform.
- *
- * On Windows both `npm` and `pnpm` are `.cmd` shims, and since the
- * CVE-2024-27980 hardening Node refuses to spawn a `.cmd`/`.bat` file without
- * a shell. Without this the update would fail with EINVAL/ENOENT on every
- * Windows install — including the pnpm layouts this gate claims to detect.
- */
-export declare function buildSpawnPlan(cmd: string, args: readonly string[], platform?: NodeJS.Platform): {
-    cmd: string;
-    args: string[];
-    shell: boolean;
-};
+export { buildSpawnPlan, quoteForWindowsShell };
 export declare function runUpdateCommand(cmd: string, args: string[]): UpdateResult;
 declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner): UpdateResult;
 declare function performUpdate(command: string, runner?: UpdateRunner): UpdateResult;
@@ -243,5 +225,4 @@ export declare const __test__: {
     resolveRunningManager: typeof resolveRunningManager;
     resolveRunningPrefix: typeof resolveRunningPrefix;
 };
-export {};
 //# sourceMappingURL=version-gate.d.ts.map

package/dist/utils/version-gate.js

@@ -28,6 +28,7 @@
  * to silence both check + gate).
  */
 import { spawnSync } from "node:child_process";
+import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -280,32 +281,12 @@ async function fetchVersionDecision() {
         return null;
     }
 }
-/**
- * Quote an argv entry for a Windows `cmd.exe` invocation. Needed because Node
- * does NOT quote argv when spawning with `shell: true` on Windows — it joins
- * the array with spaces — so an npm prefix like `C:\Program Files\…` would be
- * split into two arguments.
- */
-export function quoteForWindowsShell(arg) {
-    if (arg === "")
-        return '""';
-    if (!/[\s"^&|<>()]/.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '\\"')}"`;
-}
-/**
- * How to hand `<cmd> <args…>` to `spawnSync` on this platform.
- *
- * On Windows both `npm` and `pnpm` are `.cmd` shims, and since the
- * CVE-2024-27980 hardening Node refuses to spawn a `.cmd`/`.bat` file without
- * a shell. Without this the update would fail with EINVAL/ENOENT on every
- * Windows install — including the pnpm layouts this gate claims to detect.
- */
-export function buildSpawnPlan(cmd, args, platform = process.platform) {
-    if (platform !== "win32")
-        return { cmd, args: [...args], shell: false };
-    return { cmd, args: args.map(quoteForWindowsShell), shell: true };
-}
+// The Windows spawn recipe (`buildSpawnPlan` + `quoteForWindowsShell`) lives in
+// ./windows-spawn.ts so the self-update path and the qmd spawn path share one
+// implementation. Imported at the top and re-exported here to keep this module's
+// public surface (and the `__test__` block below) stable for existing callers
+// and tests.
+export { buildSpawnPlan, quoteForWindowsShell };
 export function runUpdateCommand(cmd, args) {
     try {
         const plan = buildSpawnPlan(cmd, args);

package/dist/utils/windows-spawn.d.ts

@@ -0,0 +1,44 @@
+export type SpawnPlan = {
+    cmd: string;
+    args: string[];
+    shell: boolean;
+};
+/**
+ * Quote one entry for a Windows `cmd.exe` invocation. Node does not quote for
+ * `shell: true` on Windows — it joins the array with spaces — so a bare prefix
+ * or path like `C:\Program Files\…` would otherwise be split into two arguments,
+ * and a value containing a shell metacharacter (`&`, `|`, `^`, `<`, `>`, `(`,
+ * `)`) could be reinterpreted by the shell.
+ */
+export declare function quoteForWindowsShell(arg: string): string;
+/**
+ * How to hand `<cmd> <args…>` to `spawnSync` when the command MUST go through a
+ * shell on Windows (a bare manager name like `npm`/`pnpm` that relies on
+ * PATH/PATHEXT resolution, or a resolved `.cmd`/`.bat` file).
+ *
+ * On non-Windows this is a passthrough with `shell: false` and argv untouched.
+ * On Windows it sets `shell: true` and quotes BOTH the command and every
+ * argument. Quoting the command matters because a resolved path can be absolute
+ * and contain spaces — e.g. `C:\Users\First Last\AppData\…\qmd.cmd` — unlike the
+ * bare `npm`/`pnpm` names this helper was first written for (those quote to
+ * themselves, so their behaviour is unchanged).
+ */
+export declare function buildSpawnPlan(cmd: string, args: readonly string[], platform?: NodeJS.Platform): SpawnPlan;
+/**
+ * True when a resolved, path-qualified command is a Windows batch file
+ * (`.cmd`/`.bat`) — the shape Node refuses to spawn without a shell. Bare
+ * command NAMES (which also need a shell on Windows for PATHEXT resolution) are
+ * the caller's concern; version-gate passes bare `npm`/`pnpm` and always uses
+ * {@link buildSpawnPlan} directly.
+ */
+export declare function isWindowsBatchFile(command: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Spawn plan for a fully-resolved command (an absolute binary or interpreter
+ * path, plus its arguments). Shell-free everywhere EXCEPT a Windows `.cmd`/`.bat`
+ * target, which is routed through the quoted shell plan. This keeps user-supplied
+ * text off `cmd.exe` on the default path: an ordinary executable (a Node
+ * interpreter, an `.exe`, or a POSIX binary) is spawned directly with argv
+ * passed through untouched.
+ */
+export declare function planCommandSpawn(command: string, args: readonly string[], platform?: NodeJS.Platform): SpawnPlan;
+//# sourceMappingURL=windows-spawn.d.ts.map

package/dist/utils/windows-spawn.js

@@ -0,0 +1,74 @@
+// src/utils/windows-spawn.ts
+//
+// One Windows spawn policy for the whole CLI.
+//
+// On Windows, `npm`/`pnpm` and every npm-generated dependency bin are `.cmd`
+// batch shims, and since the CVE-2024-27980 hardening (Node 18.20.2 / 20.12.2 /
+// 21.7.3+, i.e. all of Node 22) Node refuses to spawn a `.cmd`/`.bat` file
+// without a shell — `spawnSync` reports `EINVAL` on its result. Anything that
+// must reach such a shim therefore has to go through `shell: true`, and because
+// Node quotes NEITHER the command NOR argv for `shell: true` on Windows, every
+// entry that can contain spaces or `cmd.exe` metacharacters must be quoted here.
+//
+// This module is the single implementation of that policy. The self-update path
+// (version-gate) and the qmd spawn path (search-index) both import it, so there
+// is exactly one Windows spawn recipe in the repo.
+/**
+ * Quote one entry for a Windows `cmd.exe` invocation. Node does not quote for
+ * `shell: true` on Windows — it joins the array with spaces — so a bare prefix
+ * or path like `C:\Program Files\…` would otherwise be split into two arguments,
+ * and a value containing a shell metacharacter (`&`, `|`, `^`, `<`, `>`, `(`,
+ * `)`) could be reinterpreted by the shell.
+ */
+export function quoteForWindowsShell(arg) {
+    if (arg === "")
+        return '""';
+    if (!/[\s"^&|<>()]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
+}
+/**
+ * How to hand `<cmd> <args…>` to `spawnSync` when the command MUST go through a
+ * shell on Windows (a bare manager name like `npm`/`pnpm` that relies on
+ * PATH/PATHEXT resolution, or a resolved `.cmd`/`.bat` file).
+ *
+ * On non-Windows this is a passthrough with `shell: false` and argv untouched.
+ * On Windows it sets `shell: true` and quotes BOTH the command and every
+ * argument. Quoting the command matters because a resolved path can be absolute
+ * and contain spaces — e.g. `C:\Users\First Last\AppData\…\qmd.cmd` — unlike the
+ * bare `npm`/`pnpm` names this helper was first written for (those quote to
+ * themselves, so their behaviour is unchanged).
+ */
+export function buildSpawnPlan(cmd, args, platform = process.platform) {
+    if (platform !== "win32")
+        return { cmd, args: [...args], shell: false };
+    return {
+        cmd: quoteForWindowsShell(cmd),
+        args: args.map(quoteForWindowsShell),
+        shell: true,
+    };
+}
+/**
+ * True when a resolved, path-qualified command is a Windows batch file
+ * (`.cmd`/`.bat`) — the shape Node refuses to spawn without a shell. Bare
+ * command NAMES (which also need a shell on Windows for PATHEXT resolution) are
+ * the caller's concern; version-gate passes bare `npm`/`pnpm` and always uses
+ * {@link buildSpawnPlan} directly.
+ */
+export function isWindowsBatchFile(command, platform = process.platform) {
+    return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}
+/**
+ * Spawn plan for a fully-resolved command (an absolute binary or interpreter
+ * path, plus its arguments). Shell-free everywhere EXCEPT a Windows `.cmd`/`.bat`
+ * target, which is routed through the quoted shell plan. This keeps user-supplied
+ * text off `cmd.exe` on the default path: an ordinary executable (a Node
+ * interpreter, an `.exe`, or a POSIX binary) is spawned directly with argv
+ * passed through untouched.
+ */
+export function planCommandSpawn(command, args, platform = process.platform) {
+    if (isWindowsBatchFile(command, platform))
+        return buildSpawnPlan(command, args, platform);
+    return { cmd: command, args: [...args], shell: false };
+}
+//# sourceMappingURL=windows-spawn.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.98.0",
+  "version": "5.98.2",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {