@indigoai-us/hq-cli 5.94.0 → 5.94.2

package/dist/commands/core-checkpoint.js

@@ -13,12 +13,23 @@ import { homedir } from "node:os";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { peekIdToken } from "../utils/id-token.js";
 const DEFAULT_TRIGGER = "stop-gate";
-const BACKENDS = new Set(["auto", "claude", "codex", "none"]);
+const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
 // Pinned by operator directive 2026-07-31; change defaults here deliberately.
 const CODEX_SIBLING_MODEL = "gpt-5.6-terra";
 const CODEX_SIBLING_REASONING_EFFORT = "high";
 const CLAUDE_SIBLING_MODEL = "claude-opus-5";
 const CLAUDE_SIBLING_EFFORT = "medium";
+const GROK_SIBLING_MODEL = "grok-4.5";
+const GROK_SIBLING_EFFORT = "high";
+/**
+ * `grok -p` is single-turn by default: without a turn budget it answers with a
+ * plan and exits, having done nothing. The maintenance flow needs many turns.
+ */
+const GROK_SIBLING_MAX_TURNS = "100";
+/** Preference order for `--backend auto`, first healthy candidate wins. */
+const AUTO_BACKEND_ORDER = ["codex", "grok", "claude"];
+/** A backend that cannot answer `--version` this fast is treated as broken. */
+const BACKEND_PROBE_TIMEOUT_MS = 10_000;
 /** A sibling still holding the lock after this long is treated as abandoned. */
 const SIBLING_LOCK_TTL_MS = 60 * 60 * 1000;
 /** Newest-wins cap so a wedged sibling cannot grow an unbounded queue. */
@@ -402,21 +413,150 @@ function backendOnPath(name) {
         }
     });
 }
-function resolveBackend(requested) {
+/**
+ * An installed binary is not necessarily a working one: a partial install, a
+ * broken wrapper or a missing runtime all leave an executable on PATH that
+ * fails the moment it is asked to do anything. Ask it for its version — cheap,
+ * bounded, and enough to reject a backend before handing it a checkpoint.
+ */
+function backendResponds(name) {
+    try {
+        execFileSync(name, ["--version"], {
+            timeout: BACKEND_PROBE_TIMEOUT_MS,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Backends whose most recent run died without producing a report.
+ *
+ * A version probe cannot catch a backend that starts cleanly and then fails at
+ * runtime — an expired login, a sandbox it cannot write in, a model it is not
+ * entitled to. The evidence for that is a finished run directory with no
+ * report.md in it, so prefer a different backend for the next checkpoint. Only
+ * the newest run per backend counts: one that has since succeeded is healthy.
+ */
+function crashedBackends(siblingRoot) {
+    const crashed = new Set();
+    let runDirs;
+    try {
+        runDirs = fs
+            .readdirSync(siblingRoot)
+            .filter((entry) => entry !== "pending.jsonl")
+            .sort()
+            .reverse();
+    }
+    catch {
+        return crashed;
+    }
+    const seen = new Set();
+    for (const runDir of runDirs) {
+        const absolute = path.join(siblingRoot, runDir);
+        let backend;
+        try {
+            const payload = JSON.parse(fs.readFileSync(path.join(absolute, "payload.json"), "utf8"));
+            backend = payload.backend;
+        }
+        catch {
+            continue;
+        }
+        if (typeof backend !== "string" || !backend || seen.has(backend))
+            continue;
+        seen.add(backend);
+        if (fs.existsSync(path.join(absolute, "report.md")))
+            continue;
+        // A missing report only means a crash once the process itself is gone.
+        let pid = Number.NaN;
+        try {
+            pid = Number.parseInt(fs.readFileSync(path.join(absolute, "sibling.pid"), "utf8").trim(), 10);
+        }
+        catch {
+            // A run that never recorded a PID cannot still be running.
+        }
+        if (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))
+            continue;
+        crashed.add(backend);
+    }
+    return crashed;
+}
+function resolveBackend(requested, liveRoot) {
     const value = requested ?? "auto";
     if (!BACKENDS.has(value))
         usage(`checkpoint: unknown backend: ${value}`);
-    if (value === "auto") {
-        if (backendOnPath("codex"))
-            return "codex";
-        if (backendOnPath("claude"))
-            return "claude";
+    // An explicitly named backend is honoured as given; only `auto` shops around.
+    if (value !== "auto")
+        return value;
+    const available = AUTO_BACKEND_ORDER.filter((name) => backendOnPath(name) && backendResponds(name));
+    if (available.length === 0)
         return "none";
+    const crashed = crashedBackends(path.join(liveRoot, "workspace", "checkpoints", "sibling"));
+    // If every candidate failed last time, still try the preferred one: a stale
+    // failure is a weaker signal than running no maintenance sibling at all.
+    return available.find((name) => !crashed.has(name)) ?? available[0];
+}
+function siblingArgs(backend, prompt) {
+    switch (backend) {
+        case "claude":
+            return [
+                "-p",
+                prompt,
+                "--model",
+                CLAUDE_SIBLING_MODEL,
+                "--effort",
+                CLAUDE_SIBLING_EFFORT,
+                "--permission-mode",
+                "acceptEdits",
+            ];
+        case "grok":
+            return [
+                "-p",
+                prompt,
+                "-m",
+                GROK_SIBLING_MODEL,
+                "--reasoning-effort",
+                GROK_SIBLING_EFFORT,
+                // `acceptEdits` auto-approves edits only. A terminal command — the git
+                // scan, the journal helper — then hits an approval gate with no human
+                // attached, and grok cancels the whole run: `stopReason: cancelled,
+                // cancellationCategory: PermissionCancelled`. Unattended approval plus
+                // a sandbox is the same posture codex gets from `-s workspace-write`.
+                "--always-approve",
+                "--sandbox",
+                "workspace",
+                "--max-turns",
+                GROK_SIBLING_MAX_TURNS,
+            ];
+        case "codex":
+            return [
+                "exec",
+                "--skip-git-repo-check",
+                "-s",
+                "workspace-write",
+                "--dangerously-bypass-hook-trust",
+                "-m",
+                CODEX_SIBLING_MODEL,
+                "-c",
+                `model_reasoning_effort=${CODEX_SIBLING_REASONING_EFFORT}`,
+                prompt,
+            ];
     }
-    return value;
 }
-function siblingPayload(input, threadPath) {
+function siblingPayload(input, threadPath, backend) {
     return {
+        backend,
         summary: input.summary ?? "",
         files: input.files,
         learnings: input.learnings,
@@ -525,7 +665,7 @@ function startSibling(liveRoot, input, threadPath, backend) {
     const siblingRoot = path.join(liveRoot, "workspace", "checkpoints", "sibling");
     const pendingPath = path.join(siblingRoot, "pending.jsonl");
     const lockPath = path.join(stateDir, "checkpoint-sibling.lock");
-    const payload = siblingPayload(input, threadPath);
+    const payload = siblingPayload(input, threadPath, backend);
     const activePid = existingSiblingPid(lockPath, Date.now());
     fs.mkdirSync(siblingRoot, { recursive: true });
     if (activePid !== null) {
@@ -542,29 +682,7 @@ function startSibling(liveRoot, input, threadPath, backend) {
     fs.writeFileSync(path.join(runDir, "prompt.md"), prompt);
     const logPath = path.join(runDir, "run.log");
     const logFd = fs.openSync(logPath, "a");
-    const args = backend === "claude"
-        ? [
-            "-p",
-            prompt,
-            "--model",
-            CLAUDE_SIBLING_MODEL,
-            "--effort",
-            CLAUDE_SIBLING_EFFORT,
-            "--permission-mode",
-            "acceptEdits",
-        ]
-        : [
-            "exec",
-            "--skip-git-repo-check",
-            "-s",
-            "workspace-write",
-            "--dangerously-bypass-hook-trust",
-            "-m",
-            CODEX_SIBLING_MODEL,
-            "-c",
-            `model_reasoning_effort=${CODEX_SIBLING_REASONING_EFFORT}`,
-            prompt,
-        ];
+    const args = siblingArgs(backend, prompt);
     let child;
     try {
         child = spawn(backend, args, {
@@ -587,7 +705,10 @@ function startSibling(liveRoot, input, threadPath, backend) {
     if (!child.pid)
         throw new Error("checkpoint: sibling did not return a PID");
     fs.writeFileSync(lockPath, String(child.pid));
-    printResult(`checkpoint: sibling started (pid ${child.pid})`);
+    // Recorded per run so a later checkpoint can tell "died without a report"
+    // apart from "still working" without consulting the shared lock.
+    fs.writeFileSync(path.join(runDir, "sibling.pid"), String(child.pid));
+    printResult(`checkpoint: sibling started (${backend}, pid ${child.pid})`);
 }
 function hasGateProbeConflict(options, command) {
     return [
@@ -641,7 +762,7 @@ function runCheckpoint(options, command, group) {
     if (!input.summary?.trim()) {
         usage("checkpoint: --summary is required unless --idle or --gate-probe is used");
     }
-    const backend = resolveBackend(options.backend);
+    const backend = resolveBackend(options.backend, liveRoot);
     const now = new Date();
     const threadId = `T-${formatTimestamp(now)}-auto-${summarySlug(input.summary)}`;
     const threadPath = path.join(liveRoot, "workspace", "threads", `${threadId}.json`);
@@ -730,7 +851,7 @@ export function registerCoreCheckpointCommand(core) {
         .option("--payload <file|->", "JSON payload file, or - for stdin")
         .option("--idle", "touch stamps without a checkpoint")
         .option("--no-agent", "do not spawn the maintenance sibling")
-        .option("--backend <auto|claude|codex|none>", "sibling backend", "auto")
+        .option("--backend <auto|claude|codex|grok|none>", "sibling backend", "auto")
         .option("--gate-probe", "write the local Stop-hook eligibility verdict")
         .option("--hq-root <path>", "HQ installation to operate on")
         .option("--dry-run", "print the planned checkpoint without writing")

package/dist/commands/search.js

@@ -23,26 +23,38 @@ function relay(result) {
         process.stderr.write(result.stderr);
 }
 export function registerSearchCommand(program) {
-    const search = program.command('search').description('Search the local HQ qmd index');
-    search
-        .command('get <document>')
-        .description('Retrieve a qmd document by path or document id')
-        .option('-c, --collection <collection>', 'Restrict retrieval to a collection')
-        .action((document, options) => {
-        relay(runQmd(buildGetArgs(document, options)));
-    });
-    search
-        .command('<query>')
+    // The query is an ARGUMENT on `search` itself, not a subcommand. It was
+    // previously registered as `.command('<query>')`, which makes commander look
+    // for a subcommand literally named `<query>` — so every real query failed
+    // with "unknown command '<the query>'" and plain `hq search` never worked.
+    // Variadic so `hq search foo bar` needs no quoting; `search get` stays a
+    // subcommand and still wins when it is the first token.
+    const search = program
+        .command('search')
         .description('Search the local HQ qmd index')
+        .argument('[query...]', 'Query terms (joined with spaces)')
         .option('--mode <mode>', 'Search mode: keyword, semantic, or hybrid', 'keyword')
         .option('-c, --collection <collection>', 'Restrict search to a collection')
         .option('-n, --count <count>', 'Maximum result count', (value) => Number(value))
         .option('--json', 'Request machine-readable qmd output')
-        .action((query, options) => {
+        .action((queryParts = [], options) => {
+        const query = queryParts.join(' ').trim();
+        if (!query) {
+            search.outputHelp();
+            process.exitCode = 1;
+            return;
+        }
         if (!['keyword', 'semantic', 'hybrid'].includes(options.mode ?? 'keyword')) {
             throw new Error(`Unknown search mode '${options.mode}'. Expected keyword, semantic, or hybrid.`);
         }
         relay(runQmd(buildSearchArgs(query, options)));
     });
+    search
+        .command('get <document>')
+        .description('Retrieve a qmd document by path or document id')
+        .option('-c, --collection <collection>', 'Restrict retrieval to a collection')
+        .action((document, options) => {
+        relay(runQmd(buildGetArgs(document, options)));
+    });
 }
 //# sourceMappingURL=search.js.map

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

@@ -27,8 +27,15 @@ export type ResolveQmdBinOptions = {
     isExecutable?: (candidate: string) => boolean;
     packageBin?: () => string | undefined;
     pathBin?: () => string | undefined;
+    isUsable?: (bin: string) => boolean;
 };
-/** Return the pinned package version when qmd is supplied by this CLI. */
+/**
+ * Return the pinned package version when qmd is supplied by this CLI.
+ *
+ * Read from disk rather than `require('@tobilu/qmd/package.json')`: qmd 2.x does
+ * not export package.json, so the require form throws and the version silently
+ * disappeared from `hq index status`. Same root cause as packageLocalBin.
+ */
 export declare function resolveQmdVersion(): string | undefined;
 /** Resolve qmd without relying on a globally installed copy. */
 export declare function resolveQmdBin(options?: ResolveQmdBinOptions): string;

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

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 const require = createRequire(import.meta.url);
 export class QmdBinaryMissingError extends Error {
     name = 'QmdBinaryMissingError';
@@ -32,24 +33,68 @@ function isExecutable(candidate) {
         return false;
     }
 }
+/**
+ * Locate the bundled qmd through the dependency-bin link the package manager
+ * installs, walking up from this module.
+ *
+ * Two earlier approaches were wrong and both failed silently, so every host fell
+ * through to PATH and a machine without a global qmd reported "skipped" — which
+ * defeats the point of depending on qmd at all:
+ *
+ *   - `<pkg>/qmd` guessed a filename; the package declares `bin/qmd`.
+ *   - `require.resolve('@tobilu/qmd/package.json')` throws
+ *     ERR_PACKAGE_PATH_NOT_EXPORTED on qmd 2.x, whose `exports` map does not
+ *     expose package.json.
+ *
+ * `node_modules/.bin/qmd` is the contract every package manager honours and is
+ * independent of the dependency's own exports map.
+ */
 function packageLocalBin() {
-    try {
-        const packageJson = require.resolve('@tobilu/qmd/package.json');
-        return path.join(path.dirname(packageJson), 'qmd');
-    }
-    catch {
-        return undefined;
+    const names = process.platform === 'win32' ? ['qmd.cmd', 'qmd.exe', 'qmd'] : ['qmd'];
+    let directory = path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth++) {
+        for (const name of names) {
+            const candidate = path.join(directory, 'node_modules', '.bin', name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        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. */
+/**
+ * Return the pinned package version when qmd is supplied by this CLI.
+ *
+ * Read from disk rather than `require('@tobilu/qmd/package.json')`: qmd 2.x does
+ * not export package.json, so the require form throws and the version silently
+ * disappeared from `hq index status`. Same root cause as packageLocalBin.
+ */
 export function resolveQmdVersion() {
-    try {
-        const packageJson = require('@tobilu/qmd/package.json');
-        return typeof packageJson.version === 'string' ? packageJson.version : undefined;
-    }
-    catch {
-        return undefined;
+    // Walk for the package directory itself. Neither require() nor the .bin entry
+    // works: qmd 2.x does not export package.json, and .bin/qmd is a generated
+    // shim (not a symlink) under pnpm's hoisted linker, so resolving it lands back
+    // in this package rather than qmd's.
+    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'));
+                if (typeof parsed.version === 'string')
+                    return parsed.version;
+            }
+            catch { /* unreadable manifest: report no version rather than throwing */ }
+            return undefined;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
     }
+    return undefined;
 }
 function pathBin() {
     const paths = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
@@ -63,6 +108,27 @@ function pathBin() {
     }
     return undefined;
 }
+const usableQmdCache = new Map();
+/**
+ * Does this qmd binary actually run? `--version` is the cheapest subcommand
+ * that still loads the native module, which is exactly what fails when the
+ * bindings are missing. Cached per path so resolution stays a single spawn.
+ */
+function isUsableQmd(bin) {
+    const cached = usableQmdCache.get(bin);
+    if (cached !== undefined)
+        return cached;
+    let usable = false;
+    try {
+        const probe = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 10_000 });
+        usable = !probe.error && probe.status === 0;
+    }
+    catch {
+        usable = false;
+    }
+    usableQmdCache.set(bin, usable);
+    return usable;
+}
 /** Resolve qmd without relying on a globally installed copy. */
 export function resolveQmdBin(options = {}) {
     const env = options.env ?? process.env;
@@ -78,12 +144,27 @@ export function resolveQmdBin(options = {}) {
         probes.push('HQ_QMD_BIN (not set)');
     }
     const installed = (options.packageBin ?? packageLocalBin)();
-    if (installed && executable(installed))
-        return installed;
-    probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
     const onPath = (options.pathBin ?? pathBin)();
-    if (onPath && executable(onPath))
-        return onPath;
+    const fallback = onPath && executable(onPath) ? onPath : undefined;
+    if (installed && executable(installed)) {
+        // Executable is not the same as usable: a global install can ship a qmd
+        // whose native better-sqlite3 bindings were never compiled, so every
+        // invocation crashes. Preferring it blindly turned a dormant packaging
+        // problem into broken search on hosts that had a working qmd on PATH.
+        //
+        // The runnability probe costs a ~0.3s spawn, so only pay it when there is
+        // something to fall back TO. With no alternative the answer is the bundled
+        // binary either way, and a failure there now surfaces loudly rather than
+        // silently, so probing would buy nothing but latency on the hot path.
+        if (!fallback || (options.isUsable ?? isUsableQmd)(installed))
+            return installed;
+        probes.push(`package-local @tobilu/qmd (${installed}, present but not runnable)`);
+    }
+    else {
+        probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
+    }
+    if (fallback)
+        return fallback;
     probes.push(`qmd on PATH (${onPath ?? 'not found'})`);
     throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
 }

package/dist/main.js

@@ -73,7 +73,7 @@ import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
-import { unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
+import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
 const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
@@ -348,9 +348,13 @@ export function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies
         }
         else {
             deps.sentry.captureException(err);
-            const userMessage = unexpectedCliErrorMessage(err);
-            if (userMessage)
-                deps.stderr.write(`hq: ${userMessage}\n`);
+            // Always emit something. Printing only when unexpectedCliErrorMessage()
+            // returned a value meant every error class except IntegrationsCliError
+            // exited 1 with zero bytes on stdout AND stderr — a silent failure the
+            // caller cannot distinguish from success. The fallback runs through the
+            // same redaction chain, so this widens visibility, not disclosure.
+            const userMessage = unexpectedCliErrorMessage(err) ?? fallbackOperatorMessage(err);
+            deps.stderr.write(`hq: ${userMessage}\n`);
         }
         deps.setExitCode(1);
     }

package/dist/utils/unexpected-cli-error.d.ts

@@ -5,4 +5,20 @@
  * are not printed indiscriminately.
  */
 export declare function unexpectedCliErrorMessage(err: unknown): string | null;
+/**
+ * Apply the same redaction chain to an arbitrary error message.
+ *
+ * Exists so the top-level handler can ALWAYS emit a diagnostic. Previously it
+ * printed only when unexpectedCliErrorMessage() returned a value, and that
+ * returns null for everything except IntegrationsCliError — so any other
+ * failure (a qmd crash, for instance) exited 1 with zero bytes on both
+ * streams, which is indistinguishable from success-with-no-output.
+ */
+export declare function redactForOperator(raw: string): string;
+/**
+ * Last-resort operator message for an error the CLI has no specific handling
+ * for. Redacted through the same chain as the integrations path; falls back to
+ * a fixed string when the value carries no usable message.
+ */
+export declare function fallbackOperatorMessage(err: unknown): string;
 //# sourceMappingURL=unexpected-cli-error.d.ts.map

package/dist/utils/unexpected-cli-error.js

@@ -8,7 +8,19 @@ import { IntegrationsCliError } from "../commands/integrations.js";
 export function unexpectedCliErrorMessage(err) {
     if (!(err instanceof IntegrationsCliError) || err.expected)
         return null;
-    const message = err.message
+    return redactForOperator(err.message) || "Integration request failed";
+}
+/**
+ * Apply the same redaction chain to an arbitrary error message.
+ *
+ * Exists so the top-level handler can ALWAYS emit a diagnostic. Previously it
+ * printed only when unexpectedCliErrorMessage() returned a value, and that
+ * returns null for everything except IntegrationsCliError — so any other
+ * failure (a qmd crash, for instance) exited 1 with zero bytes on both
+ * streams, which is indistinguishable from success-with-no-output.
+ */
+export function redactForOperator(raw) {
+    return raw
         .replace(/-----BEGIN[^-]+PRIVATE KEY-----[\s\S]*?-----END[^-]+PRIVATE KEY-----/g, "[REDACTED]")
         .replace(/\p{Cc}/gu, " ")
         .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]")
@@ -19,6 +31,18 @@ export function unexpectedCliErrorMessage(err) {
         .replace(/\s+/g, " ")
         .trim()
         .slice(0, 1_000);
-    return message || "Integration request failed";
+}
+/**
+ * Last-resort operator message for an error the CLI has no specific handling
+ * for. Redacted through the same chain as the integrations path; falls back to
+ * a fixed string when the value carries no usable message.
+ */
+export function fallbackOperatorMessage(err) {
+    const raw = err instanceof Error
+        ? `${err.name}: ${err.message}`
+        : typeof err === "string"
+            ? err
+            : "";
+    return redactForOperator(raw) || "command failed with an unreported error";
 }
 //# sourceMappingURL=unexpected-cli-error.js.map

package/package.json

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