@indigoai-us/hq-cli 5.345.148 → 5.345.149

package/dist/lib/windows/user-path.js

@@ -3,14 +3,28 @@
  *
  * npm writes `hq.cmd` directly under its prefix (never `<prefix>\bin`). When
  * that folder is not on the user or machine Path, a new terminal cannot find
- * `hq` even though the install succeeded. HQ detects this and prints the exact
- * fix; it never edits PATH itself.
+ * `hq` even though the install succeeded. The supported install adds that
+ * folder to the user PATH (HKCU only) and broadcasts the change. It never
+ * edits the machine PATH. When the add fails, doctor prints the exact command.
+ *
+ * Windows PowerShell 5.1 and reg.exe print piped output in the console code
+ * page, so a Path holding `C:\Users\José` comes back garbled when read as
+ * UTF-8. Reads therefore return the value as base64 of its UTF-16LE bytes, and
+ * the append is one PowerShell script that reads, checks, and writes the value
+ * without it ever leaving PowerShell.
  */
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-const USER_ENV_KEY = "HKCU\\Environment";
-const MACHINE_ENV_KEY = "HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment";
+/** The longest user Path HQ will write. Longer values break `setx` and some installers. */
+export const MAX_USER_PATH_LENGTH = 2047;
+const REPLACEMENT_CHAR = "\uFFFD";
+/**
+ * Tests on Windows point the scripts at a scratch key with this variable. The
+ * scripts accept only keys under HKCU:\Software\HQTest\ and skip the
+ * broadcast for them.
+ */
+export const USER_PATH_TEST_KEY_ENV = "HQ_USER_PATH_TEST_KEY";
 /** The npm prefix folder above the package's `node_modules`, when `hq.cmd` is there. */
 export function npmShimDir(entry, exists) {
     if (!entry)
@@ -30,23 +44,37 @@ export function expandWindowsEnv(value, env) {
         return found === undefined ? whole : found;
     });
 }
-function regPath(run, key) {
-    try {
-        const result = run("reg.exe", ["query", key, "/v", "Path"]);
-        if (result.status !== 0)
-            return null;
-        for (const line of result.stdout.split(/\r?\n/)) {
-            // An empty value prints no text after the type, which is an empty Path,
-            // not an unreadable one.
-            const match = /^\s+Path\s+REG_(?:EXPAND_)?SZ(?:\s+(.*))?$/i.exec(line);
-            if (match)
-                return (match[1] ?? "").trim();
-        }
-    }
-    catch {
-        // reg.exe missing or refused: treat as unreadable.
+const SELECT_USER_KEY = [
+    "$key = 'HKCU:\\Environment'",
+    `$test = $env:${USER_PATH_TEST_KEY_ENV}`,
+    "if ($test) { if (-not $test.StartsWith('HKCU:\\Software\\HQTest\\', [StringComparison]::OrdinalIgnoreCase)) { exit 2 }; $key = $test }",
+];
+/**
+ * Prints `U:<base64>` for the unexpanded user Path and `M:<base64>` for the
+ * machine Path, base64 of the UTF-16LE bytes, or `U-` / `M-` when a value
+ * cannot be read. Base64 is ASCII, so the console code page cannot change it.
+ */
+export const READ_PATHS_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    ...SELECT_USER_KEY,
+    "function Emit($tag, $k) { $i = Get-Item -LiteralPath $k -ErrorAction SilentlyContinue; if ($null -eq $i) { return $tag + '-' }; $v = $i.GetValue('Path', $null, 'DoNotExpandEnvironmentNames'); if ($v -isnot [string]) { return $tag + '-' }; return $tag + ':' + [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($v)) }",
+    "Write-Output (Emit 'U' $key)",
+    "Write-Output (Emit 'M' 'HKLM:\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment')",
+].join("\n");
+/** Decode READ_PATHS_SCRIPT output. Null for a value that could not be read. */
+export function parseReadPathsOutput(stdout) {
+    const out = { user: null, machine: null };
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = /^([UM]):([A-Za-z0-9+/=]*)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const value = Buffer.from(match[2], "base64").toString("utf16le");
+        if (match[1] === "U")
+            out.user = value;
+        else
+            out.machine = value;
     }
-    return null;
+    return out;
 }
 /**
  * The PATH a new terminal will get: the user Path then the machine Path, as
@@ -54,7 +82,17 @@ function regPath(run, key) {
  * be read.
  */
 export function readPersistedPath(run, env) {
-    const values = [regPath(run, USER_ENV_KEY), regPath(run, MACHINE_ENV_KEY)].filter((v) => v !== null);
+    let values = [];
+    try {
+        const result = run(READ_PATHS_SCRIPT, {});
+        if (result.status === 0) {
+            const read = parseReadPathsOutput(result.stdout);
+            values = [read.user, read.machine].filter((v) => v !== null);
+        }
+    }
+    catch {
+        // PowerShell missing or refused: treat as unreadable.
+    }
     if (values.length === 0)
         return { value: env.PATH ?? env.Path ?? "", source: "process" };
     return { value: values.map((v) => expandWindowsEnv(v, env)).join(";"), source: "registry" };
@@ -69,8 +107,15 @@ export function isDirOnPath(dir, pathValue) {
     const want = normalizeDir(dir);
     return pathValue.split(";").some((entry) => normalizeDir(entry) === want);
 }
-function defaultRun(cmd, args) {
-    const result = spawnSync(cmd, args, { encoding: "utf8", windowsHide: true, timeout: 5000 });
+/** Runs a script through Windows PowerShell. The script travels as -EncodedCommand (UTF-16LE), so quoting cannot change it. */
+function defaultPowerShell(script, extraEnv) {
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 15_000,
+        env: { ...process.env, ...extraEnv },
+    });
     return { status: result.status, stdout: result.stdout ?? "" };
 }
 /** Null when not on Windows or when hq was not installed as an npm global shim. */
@@ -80,7 +125,7 @@ export function checkShimOnPath(deps = {}) {
     const shimDir = npmShimDir(deps.entry ?? process.argv[1], deps.exists ?? fs.existsSync);
     if (!shimDir)
         return null;
-    const persisted = readPersistedPath(deps.run ?? defaultRun, deps.env ?? process.env);
+    const persisted = readPersistedPath(deps.powerShell ?? defaultPowerShell, deps.env ?? process.env);
     return { shimDir, onPath: isDirOnPath(shimDir, persisted.value), source: persisted.source };
 }
 /** Dummy user variable set and cleared so Windows tells running programs that the environment changed. */
@@ -106,9 +151,125 @@ export function shimPathWarning(check) {
         return [];
     return [
         `The folder that holds the hq command (${check.shimDir}) is not on your Windows PATH, so a new terminal will not find hq.`,
-        "To add it for your user, run this in PowerShell, then open a new terminal:",
+        "HQ could not add it automatically. To add it for your user, run this in PowerShell, then open a new terminal:",
         `  ${pathFixCommand(check.shimDir)}`,
-        "HQ does not change PATH for you.",
     ];
 }
+/**
+ * Decide the new unexpanded user Path. Membership is decided on the expanded
+ * value so `%APPDATA%\npm` counts. The stored text keeps `%VARS%`. A value
+ * that already holds U+FFFD was garbled by an earlier decode and is never
+ * written back. The ensure script applies the same rules inside PowerShell.
+ */
+export function planUserPathAppend(current, dir, env) {
+    if (isDirOnPath(dir, expandWindowsEnv(current, env)))
+        return { action: "skip", reason: "present" };
+    if (current.includes(REPLACEMENT_CHAR) || dir.includes(REPLACEMENT_CHAR) || dir.includes(";")) {
+        return { action: "skip", reason: "unsafe-value" };
+    }
+    const trimmed = current.trim().replace(/;+$/g, "");
+    const value = trimmed ? `${trimmed};${dir}` : dir;
+    if (value.length > MAX_USER_PATH_LENGTH)
+        return { action: "skip", reason: "too-long" };
+    return { action: "write", value };
+}
+/** Exit codes of ENSURE_USER_PATH_SCRIPT. */
+export const ENSURE_EXIT = {
+    written: 0,
+    badInput: 2,
+    unreadable: 3,
+    unsafeValue: 4,
+    tooLong: 5,
+    writtenNoBroadcast: 6,
+    present: 10,
+};
+/**
+ * Appends $env:HQ_SHIM_DIR to the HKCU Path as REG_EXPAND_SZ, then broadcasts
+ * the change. The value is read, checked, and written inside this script, so
+ * no console encoding touches it. Mirrors planUserPathAppend.
+ */
+export const ENSURE_USER_PATH_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    "$dir = $env:HQ_SHIM_DIR",
+    `if ([string]::IsNullOrWhiteSpace($dir) -or $dir.Contains(';') -or $dir.Contains([string][char]0xFFFD)) { exit ${ENSURE_EXIT.badInput} }`,
+    ...SELECT_USER_KEY,
+    "$item = Get-Item -LiteralPath $key -ErrorAction SilentlyContinue",
+    `if ($null -eq $item) { exit ${ENSURE_EXIT.unreadable} }`,
+    "$p = $item.GetValue('Path', '', 'DoNotExpandEnvironmentNames')",
+    `if ($p -isnot [string]) { exit ${ENSURE_EXIT.unsafeValue} }`,
+    // Same comparison as normalizeDir: unquote, use backslashes, collapse repeated
+    // separators (keeping a UNC prefix), drop trailing ones, ignore case.
+    "function Norm($s) { $t = $s.Trim(); if ($t.Length -ge 2 -and $t.StartsWith([string][char]34) -and $t.EndsWith([string][char]34)) { $t = $t.Substring(1, $t.Length - 2).Trim() }; $t = $t.Replace([char]47, [char]92); $bs = [string][char]92; $lead = ''; if ($t.StartsWith($bs + $bs)) { $lead = $bs + $bs; $t = $t.Substring(2) }; $t = $lead + [regex]::Replace($t, ($bs + $bs + '+'), $bs); return $t.TrimEnd([char]92).ToLowerInvariant() }",
+    "$want = Norm $dir",
+    `foreach ($e in [Environment]::ExpandEnvironmentVariables($p).Split(';')) { if ((Norm $e) -eq $want) { exit ${ENSURE_EXIT.present} } }`,
+    `if ($p.Contains([string][char]0xFFFD)) { exit ${ENSURE_EXIT.unsafeValue} }`,
+    "$t = $p.Trim().TrimEnd(';')",
+    "if ($t) { $new = $t + ';' + $dir } else { $new = $dir }",
+    `if ($new.Length -gt ${MAX_USER_PATH_LENGTH}) { exit ${ENSURE_EXIT.tooLong} }`,
+    "New-ItemProperty -LiteralPath $key -Name Path -PropertyType ExpandString -Force -Value $new | Out-Null",
+    `if (-not $test) { try { [Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}','1','User'); [Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}',$null,'User') } catch { exit ${ENSURE_EXIT.writtenNoBroadcast} } }`,
+    `exit ${ENSURE_EXIT.written}`,
+].join("\n");
+export function ensureExitReason(status) {
+    switch (status) {
+        case ENSURE_EXIT.written:
+        case ENSURE_EXIT.writtenNoBroadcast:
+            return { written: true, reason: "written" };
+        case ENSURE_EXIT.present:
+            return { written: false, reason: "present" };
+        case ENSURE_EXIT.unreadable:
+            return { written: false, reason: "unreadable" };
+        case ENSURE_EXIT.unsafeValue:
+        case ENSURE_EXIT.badInput:
+            return { written: false, reason: "unsafe-value" };
+        case ENSURE_EXIT.tooLong:
+            return { written: false, reason: "too-long" };
+        default:
+            return { written: false, reason: "write-failed" };
+    }
+}
+export function powershellUserPathStore(run = defaultPowerShell, extraEnv = {}) {
+    return {
+        appendUserPath(dir) {
+            try {
+                return ensureExitReason(run(ENSURE_USER_PATH_SCRIPT, { ...extraEnv, HQ_SHIM_DIR: dir }).status);
+            }
+            catch {
+                return { written: false, reason: "write-failed" };
+            }
+        },
+    };
+}
+let cachedOnPathDir = null;
+export function resetUserPathEnsureCacheForTests() {
+    cachedOnPathDir = null;
+}
+/**
+ * Add the npm shim folder to HKCU Path when it is missing. Null off Windows
+ * or when this process is not an npm global install. A failed read does not
+ * write. Machine Path is never written.
+ */
+export function ensureShimOnUserPath(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "win32")
+        return null;
+    const cacheable = deps.store === undefined && deps.powerShell === undefined && deps.platform === undefined;
+    if (cacheable && cachedOnPathDir) {
+        return { shimDir: cachedOnPathDir, written: false, onPath: true, source: "registry", reason: "present" };
+    }
+    const check = checkShimOnPath(deps);
+    if (!check)
+        return null;
+    if (check.onPath) {
+        if (cacheable)
+            cachedOnPathDir = check.shimDir;
+        return { shimDir: check.shimDir, written: false, onPath: true, source: check.source, reason: "present" };
+    }
+    const store = deps.store ?? powershellUserPathStore(deps.powerShell);
+    const applied = store.appendUserPath(check.shimDir);
+    const onPath = applied.written || applied.reason === "present";
+    if (onPath && cacheable)
+        cachedOnPathDir = check.shimDir;
+    return { shimDir: check.shimDir, written: applied.written, onPath, source: check.source, reason: applied.reason };
+}
 //# sourceMappingURL=user-path.js.map

package/dist/main.js

@@ -48,6 +48,7 @@ import { enforceVersionGate, getVersionGatePhase, isLocalDependencyInstall, reso
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
+import { argvWithoutHelpOnUnknownCommand } from "./unknown-command.js";
 import { emitCliFirstSyncNextStepOutcome, emitCliFeatureUsed, emitCliLimitNoticeEngagement, emitCliLimitNoticeExposure, emitCliInviteNudgeEvent, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, isCliLimitResourceKind, queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, takeFirstSyncStepOutcomes, takeCliFeatureUsages, takeCliLimitNoticeEngagements, takeCliLimitNoticeExposures, takeCliInviteNudgeEvents, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
@@ -308,7 +309,7 @@ export async function runCli() {
             return;
         }
         await releasePackageUseLeaseAfterCommandLoad(process.argv);
-        await program.parseAsync();
+        await program.parseAsync(argvWithoutHelpOnUnknownCommand(process.argv));
         commandParsed = true;
         if (process.exitCode === undefined || process.exitCode === 0) {
             maybeShowFirstSyncNextStep();

package/dist/unknown-command.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `hq invite --help` is not a root command. Commander treats `--help` as a
+ * request for the parent help and exits 0 before unknownCommand(). Strip help
+ * flags when the first command word is not a root, then append a nested
+ * did-you-mean when Commander has not already suggested one.
+ * A hidden root such as `daemon` is still a real command, so its `--help` stays.
+ */
+import { Command } from "commander";
+export declare function firstCommandToken(argv: readonly string[]): string | undefined;
+export declare function isKnownRootCommand(token: string): boolean;
+/** Drop `--help`/`-h` so an unknown first word is reported instead of printing root help. */
+export declare function argvWithoutHelpOnUnknownCommand(argv: readonly string[]): string[];
+/** Nested `parent child` paths whose command name or alias is `token`. Hidden commands are skipped. */
+export declare function suggestNestedCommands(token: string): string[];
+export declare function augmentUnknownCommandError(text: string): string;
+/** Wrap the current stderr writer once. A bare unknown-command line gains a nested suggestion. */
+export declare function installUnknownCommandSuggestions(program: Command): void;
+//# sourceMappingURL=unknown-command.d.ts.map

package/dist/unknown-command.js

@@ -0,0 +1,88 @@
+import { COMMAND_CATALOG } from "./command-catalog.generated.js";
+const SUGGEST = Symbol.for("hq.unknownCommandSuggest");
+const ANSI = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-?]*[ -/]*[@-~]`, "g");
+export function firstCommandToken(argv) {
+    const args = argv.slice(2);
+    for (const token of args) {
+        if (token === "--")
+            break;
+        if (token.startsWith("-"))
+            continue;
+        return token;
+    }
+    return undefined;
+}
+export function isKnownRootCommand(token) {
+    const catalog = COMMAND_CATALOG;
+    // Hidden roots are omitted from help, but they are still commands. Stripping
+    // `--help` from `hq daemon remote-control-pools --help` makes Commander print
+    // that command's usage to stderr and exit 1.
+    return catalog.some((command) => command.name === token || command.aliases.includes(token));
+}
+/** Drop `--help`/`-h` so an unknown first word is reported instead of printing root help. */
+export function argvWithoutHelpOnUnknownCommand(argv) {
+    const token = firstCommandToken(argv);
+    if (!token || token === "help" || isKnownRootCommand(token))
+        return [...argv];
+    const out = [];
+    let passthrough = false;
+    argv.forEach((arg, index) => {
+        if (index < 2) {
+            out.push(arg);
+            return;
+        }
+        if (arg === "--")
+            passthrough = true;
+        if (!passthrough && (arg === "--help" || arg === "-h"))
+            return;
+        out.push(arg);
+    });
+    return out;
+}
+/** Nested `parent child` paths whose command name or alias is `token`. Hidden commands are skipped. */
+export function suggestNestedCommands(token) {
+    const hits = new Set();
+    const walk = (entries, prefix) => {
+        for (const entry of entries) {
+            if (entry.hidden)
+                continue;
+            const next = [...prefix, entry.name];
+            if (prefix.length > 0 && (entry.name === token || entry.aliases.includes(token)))
+                hits.add(next.join(" "));
+            if (entry.subcommands.length > 0)
+                walk(entry.subcommands, next);
+        }
+    };
+    walk(COMMAND_CATALOG, []);
+    return [...hits].sort((a, b) => a.localeCompare(b));
+}
+export function augmentUnknownCommandError(text) {
+    const plain = text.replace(ANSI, "");
+    const match = /^error: unknown command '([^']+)'\n$/.exec(plain);
+    if (!match)
+        return text;
+    const suggestions = suggestNestedCommands(match[1]);
+    if (suggestions.length === 0)
+        return text;
+    const hint = suggestions.length === 1
+        ? `(Did you mean ${suggestions[0]}?)`
+        : `(Did you mean one of ${suggestions.join(", ")}?)`;
+    return `${text}${hint}\n`;
+}
+/** Wrap the current stderr writer once. A bare unknown-command line gains a nested suggestion. */
+export function installUnknownCommandSuggestions(program) {
+    const tagged = program;
+    if (tagged[SUGGEST])
+        return;
+    tagged[SUGGEST] = true;
+    const config = program._outputConfiguration;
+    const base = config?.writeErr ?? ((str) => {
+        process.stderr.write(str);
+    });
+    program.configureOutput({
+        writeErr(str) {
+            base(augmentUnknownCommandError(str));
+        },
+    });
+}
+//# sourceMappingURL=unknown-command.js.map

package/dist/utils/cognito-session.d.ts

@@ -119,6 +119,14 @@ export type EnsureCognitoTokenOptions = {
     /** Cancels bounded, non-interactive person-session refreshes. */
     signal?: AbortSignal;
 };
+/**
+ * Env switch a parent process sets so a child `hq` never opens a browser
+ * sign-in. A hook-driven helper (SessionStart's refresh-vault-access) cannot
+ * complete a browser login, and a child waiting on one outlives its caller.
+ */
+export declare const HQ_NO_BROWSER_LOGIN_ENV = "HQ_NO_BROWSER_LOGIN";
+/** An explicit `interactive` option wins; otherwise interactive unless the env switch is "1". */
+export declare function resolveInteractiveLogin(options: Pick<EnsureCognitoTokenOptions, "interactive">, env?: NodeJS.ProcessEnv): boolean;
 /**
  * True when a usable person Cognito cache file exists under the effective
  * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the

package/dist/utils/cognito-session.js

@@ -267,6 +267,18 @@ export function isMachineCredsFileEnvSet(env = process.env) {
 export function defaultMachineCredsFile(home = os.homedir()) {
     return path.join(home, ".hq-agent", "machine-creds.json");
 }
+/**
+ * Env switch a parent process sets so a child `hq` never opens a browser
+ * sign-in. A hook-driven helper (SessionStart's refresh-vault-access) cannot
+ * complete a browser login, and a child waiting on one outlives its caller.
+ */
+export const HQ_NO_BROWSER_LOGIN_ENV = "HQ_NO_BROWSER_LOGIN";
+/** An explicit `interactive` option wins; otherwise interactive unless the env switch is "1". */
+export function resolveInteractiveLogin(options, env = process.env) {
+    if (options.interactive !== undefined)
+        return options.interactive;
+    return env[HQ_NO_BROWSER_LOGIN_ENV]?.trim() !== "1";
+}
 /**
  * Align `process.env.HQ_MACHINE_CREDS_FILE` with a (possibly synthetic) `env`
  * for the duration of `fn`, so hq-cloud's `isMachineIdentity()` sees the same
@@ -971,7 +983,7 @@ export async function ensureCognitoToken(options = {}) {
     return withTokenStateDirSection(() => ensureCognitoTokenUnserialized(options));
 }
 async function ensureCognitoTokenUnserialized(options) {
-    const interactive = options.interactive ?? true;
+    const interactive = resolveInteractiveLogin(options);
     // Machine identities (company agents) mint sessions on demand via
     // USER_PASSWORD_AUTH — no refresh-token dance, no browser. The vault API's
     // JWT authorizer accepts ID tokens, and the agent's identity claims
@@ -1062,7 +1074,7 @@ export async function ensureCognitoIdToken(options = {}) {
     return withTokenStateDirSection(() => ensureCognitoIdTokenUnserialized(options));
 }
 async function ensureCognitoIdTokenUnserialized(options) {
-    const interactive = options.interactive ?? true;
+    const interactive = resolveInteractiveLogin(options);
     if (options.signal?.aborted)
         throw options.signal.reason ?? new Error("Token acquisition was aborted");
     if (wantsMachineCognitoTokens(options)) {

package/dist/utils/hook-trust.d.ts

@@ -1,3 +1,5 @@
+import { findExecutableOnPath } from './resolve-executable.js';
+import { type SpawnPlan } from './windows-spawn.js';
 export interface CodexRpcClient {
     request(method: string, params: unknown): Promise<unknown>;
     close(): Promise<void>;
@@ -49,6 +51,13 @@ export interface RuntimeHookTrustResult {
     trusted: number;
     reason?: string;
 }
+/**
+ * How to launch Codex. npm installs Codex on Windows as a `codex.cmd` shim,
+ * which `spawn('codex')` cannot find (ENOENT) and Node refuses to run without a
+ * shell, so a bare name is resolved through PATH + PATHEXT and a batch shim is
+ * routed through the escaped cmd.exe plan.
+ */
+export declare function planCodexLaunch(executable: string, args: readonly string[], env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, find?: typeof findExecutableOnPath): SpawnPlan;
 /** Start a short-lived Codex app-server and complete its JSONL handshake. */
 export declare function createCodexAppServerClient(cwd: string, executable?: string, args?: string[]): Promise<CodexRpcClient>;
 /** Trust only hooks declared by this HQ root's project `.codex/` layer. */

package/dist/utils/hook-trust.js

@@ -8,6 +8,8 @@ import * as readline from 'node:readline';
 // read->merge->write, backup before the first byte, temp+fsync+rename commit)
 // rather than a bare readFile/writeFile pair.
 import { acquireLock, atomicReplace, backupConfig, realpathOrSelf, releaseLock, restoreFromBackup, } from '../commands/mcp-registration.js';
+import { findExecutableOnPath } from './resolve-executable.js';
+import { planResolvedCommandSpawn } from './windows-spawn.js';
 /**
  * The home directory every runtime's config is resolved under.
  *
@@ -23,6 +25,11 @@ import { acquireLock, atomicReplace, backupConfig, realpathOrSelf, releaseLock,
 export function defaultHomeDir() {
     return process.env.HOME?.trim() ? process.env.HOME : os.homedir();
 }
+const RUNTIME_LABEL = {
+    codex: 'Codex',
+    grok: 'Grok',
+    claude: 'Claude Code',
+};
 const CODEX_REQUEST_TIMEOUT_MS = 10_000;
 function errorMessage(value) {
     return value instanceof Error ? value.message : String(value);
@@ -77,11 +84,32 @@ function hqProjectHooks(hqRoot, hooks) {
         !hook.isManaged &&
         isWithin(path.resolve(hook.sourcePath), codexLayer));
 }
+/**
+ * How to launch Codex. npm installs Codex on Windows as a `codex.cmd` shim,
+ * which `spawn('codex')` cannot find (ENOENT) and Node refuses to run without a
+ * shell, so a bare name is resolved through PATH + PATHEXT and a batch shim is
+ * routed through the escaped cmd.exe plan.
+ */
+export function planCodexLaunch(executable, args, env = process.env, platform = process.platform, find = findExecutableOnPath) {
+    let command = executable;
+    if (platform === 'win32' && !path.win32.isAbsolute(executable) && !/[\\/]/.test(executable)) {
+        const resolved = find(executable, env.PATH ?? env.Path ?? '', platform, env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM');
+        if (!resolved) {
+            throw new Error(`Codex CLI not found on PATH (looked for ${executable}.exe and ${executable}.cmd); install Codex or add it to PATH, then rerun \`hq reindex\``);
+        }
+        command = resolved;
+    }
+    return planResolvedCommandSpawn(command, args, env, platform);
+}
 /** Start a short-lived Codex app-server and complete its JSONL handshake. */
 export async function createCodexAppServerClient(cwd, executable = 'codex', args = ['app-server']) {
-    const child = spawn(executable, args, {
+    const plan = planCodexLaunch(executable, args);
+    const child = spawn(plan.cmd, plan.args, {
         cwd,
         stdio: ['pipe', 'pipe', 'pipe'],
+        shell: plan.shell,
+        windowsHide: true,
+        ...(plan.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
     });
     const lines = readline.createInterface({ input: child.stdout });
     const pending = new Map();
@@ -692,7 +720,7 @@ export async function trustHqRuntimeHooks(hqRoot, deps = DEFAULT_DEPS, options =
             }
         }
         else if (result.status === 'failed') {
-            console.warn(`reindex: could not trust ${result.runtime} HQ hooks: ${result.reason ?? 'unknown error'}`);
+            console.warn(`reindex: could not trust ${result.runtime} HQ hooks: ${result.reason ?? 'unknown error'}. ${RUNTIME_LABEL[result.runtime]} will not run HQ hooks until trust succeeds; fix the error above and rerun \`hq reindex\`.`);
         }
     }
     return results;

package/dist/utils/qmd-native-binding-error.js

@@ -48,7 +48,9 @@ export const QMD_NATIVE_BINDING_REMEDY = "hq's local search index can't start: i
     "not built during install. pnpm 10 skips dependency build scripts by default, " +
     "which leaves better-sqlite3 uncompiled. Approve the build and reinstall — for " +
     "a global install run `pnpm approve-builds -g better-sqlite3` (drop -g for a " +
-    "local project) — or reinstall hq with npm, then run the command again.";
+    "local project). npm 11.16 and later skip install scripts unless you opt in; reinstall with " +
+    "`npm install -g @indigoai-us/hq-cli --allow-scripts=better-sqlite3`. " +
+    "Or reinstall hq with npm, then run the command again.";
 /**
  * The text to inspect. For a QmdExitError the captured stderr/stdout is the qmd
  * process's real diagnostic; the synthesized `message` (which embeds the user's

package/dist/utils/resolve-executable.d.ts

@@ -1,2 +1,4 @@
+/** First executable file on PATH for `command` (PATHEXT-expanded on Windows), or undefined. */
+export declare function findExecutableOnPath(command: string, pathValue?: string, platform?: NodeJS.Platform, pathExt?: string): string | undefined;
 export declare function isExecutableOnPath(command: string, pathValue?: string, platform?: NodeJS.Platform, pathExt?: string): boolean;
 //# sourceMappingURL=resolve-executable.d.ts.map

package/dist/utils/resolve-executable.js

@@ -9,8 +9,9 @@ function executableCandidates(command, pathValue = process.env.PATH ?? '', platf
         : pathValue.split(platform === 'win32' ? ';' : path.delimiter).filter(Boolean).flatMap((directory) => extensions.map((extension) => path.join(directory, `${command}${extension}`)));
     return candidates;
 }
-export function isExecutableOnPath(command, pathValue = process.env.PATH ?? '', platform = process.platform, pathExt = process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM') {
-    return executableCandidates(command, pathValue, platform, pathExt).some((candidate) => {
+/** First executable file on PATH for `command` (PATHEXT-expanded on Windows), or undefined. */
+export function findExecutableOnPath(command, pathValue = process.env.PATH ?? '', platform = process.platform, pathExt = process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM') {
+    return executableCandidates(command, pathValue, platform, pathExt).find((candidate) => {
         try {
             fs.accessSync(candidate, fs.constants.X_OK);
             return fs.statSync(candidate).isFile();
@@ -20,4 +21,7 @@ export function isExecutableOnPath(command, pathValue = process.env.PATH ?? '',
         }
     });
 }
+export function isExecutableOnPath(command, pathValue = process.env.PATH ?? '', platform = process.platform, pathExt = process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM') {
+    return findExecutableOnPath(command, pathValue, platform, pathExt) !== undefined;
+}
 //# sourceMappingURL=resolve-executable.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.148",
+  "version": "5.345.149",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -42,7 +42,7 @@
     "check:lanes-module-cycles": "node scripts/check-lanes-module-cycles.mjs",
     "vitest": "vitest",
     "clean": "rm -rf dist",
-    "postinstall": "node scripts/install-hook-engine.mjs && node scripts/mesh-daemon-if-stale.mjs || node -e \"process.exit(0)\"",
+    "postinstall": "node scripts/install-hook-engine.mjs || node -e \"process.exit(0)\"",
     "prepare": "husky || true",
     "check:no-hermes": "bash scripts/check-no-hermes.sh",
     "prepack": "node scripts/hook-engine-manifest.mjs",
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.148",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.148",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.148",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.148",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.148",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.148"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.149",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.149",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.149",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.149",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.149",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.149"
   }
 }