@indigoai-us/hq-cli 5.98.3 → 5.99.1

package/dist/commands/doctor.js

@@ -0,0 +1,228 @@
+/**
+ * `hq doctor` — verify HQ's hook guardrails are wired and firing.
+ *
+ * US-002 builds the command skeleton and the extensible check registry:
+ *   - HQ root resolution walks up from the working directory looking for the
+ *     marker directories that identify an HQ tree, and exposes the resolved root
+ *     to every check.
+ *   - Running outside any HQ tree exits non-zero with a message naming exactly
+ *     what it looked for — never a throw, never a false PASS.
+ *   - The command performs no network calls and needs no authentication; it is
+ *     purely a function of the on-disk shape of the tree.
+ *
+ * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
+ * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
+ * fail); `--verbose` also prints PASS results; `--json` emits the versioned,
+ * machine-readable document; and text output carries no ANSI when stdout is not
+ * a TTY. The rendering and contract live in ../lib/doctor/report.ts and
+ * ../lib/doctor/json-output.ts; this command wires them to the CLI.
+ *
+ * The detected platform is a placeholder (UNKNOWN_PLATFORM) until host platform
+ * detection (US-003) lands and injects the real value through `platform`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createDefaultRegistry, } from "../lib/doctor/registry.js";
+import { computeExitCode, renderText, UNKNOWN_PLATFORM, } from "../lib/doctor/report.js";
+import { buildDoctorJson, renderJson } from "../lib/doctor/json-output.js";
+import { detectPlatform } from "../lib/doctor/platform.js";
+import { DEEP_FAMILY_ID, DEEP_FAMILY_TITLE, runDeepGuardTests, } from "../lib/doctor/deep/executor.js";
+import { PARITY_FAMILY_ID, PARITY_FAMILY_TITLE, runParityReplay, } from "../lib/doctor/deep/parity.js";
+import { applyFixes } from "../lib/doctor/fix/apply.js";
+import * as readline from "node:readline";
+import { runSideEffectTests } from "../lib/doctor/deep/sandbox.js";
+/**
+ * Marker directories that identify an HQ tree root. A directory is an HQ root
+ * only when it contains ALL of these. `.claude` + `core` are present in both
+ * the real HQ tree and the synthetic fixture trees the doctor is tested
+ * against, and are absent from an arbitrary directory — so requiring both
+ * avoids a false positive on a random repo that merely carries a `.claude/`
+ * folder.
+ */
+export const HQ_ROOT_MARKERS = [".claude", "core"];
+/**
+ * Walk up from `startDir` (default: the current working directory) looking for
+ * the nearest ancestor that contains every {@link HQ_ROOT_MARKERS} entry as a
+ * directory. Returns the resolved (realpath'd) root, or `null` when no ancestor
+ * qualifies — i.e. the caller is not inside an HQ tree.
+ */
+export function resolveHqRoot(startDir = process.cwd()) {
+    let dir;
+    try {
+        dir = fs.realpathSync(startDir);
+    }
+    catch {
+        dir = path.resolve(startDir);
+    }
+    // Walk to the filesystem root. `path.dirname("/") === "/"` is the loop's
+    // terminal fixed point.
+    for (;;) {
+        if (isHqRoot(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function isHqRoot(dir) {
+    return HQ_ROOT_MARKERS.every((marker) => {
+        try {
+            return fs.statSync(path.join(dir, marker)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Resolve the HQ root, run every registered check family against it, and render
+ * a plain-text summary. Makes no network calls and needs no authentication.
+ */
+export async function runDoctor(options = {}) {
+    const write = options.stdout ?? ((chunk) => void process.stdout.write(chunk));
+    const writeErr = options.stderr ?? ((chunk) => void process.stderr.write(chunk));
+    const hqRoot = options.root ?? resolveHqRoot(options.cwd);
+    if (!hqRoot) {
+        const from = options.cwd ?? process.cwd();
+        writeErr(`hq doctor: not inside an HQ tree.\n` +
+            `  Searched upward from: ${from}\n` +
+            `  Looking for a directory containing all of: ${HQ_ROOT_MARKERS.join(", ")}\n` +
+            `  Run hq doctor from inside your HQ root.\n`);
+        return { exitCode: 1, hqRoot: null, families: [] };
+    }
+    const registry = options.registry ?? createDefaultRegistry();
+    const platform = options.platform ?? UNKNOWN_PLATFORM;
+    // The detected platform and the session id are exposed to every check so the
+    // host-specific runtime probe (US-006) can decide UNKNOWN vs FAIL vs UNTESTED.
+    const context = {
+        hqRoot,
+        platform: { id: platform.id, evidence: platform.evidence },
+        sessionId: options.sessionId,
+    };
+    const families = await registry.run(context);
+    // `--deep-test` (US-008): after the read-only tiers, actually fire pure-guard
+    // fixtures through the real gate in a sandbox and append the verdicts as their
+    // own family. Run only when asked — appending here, not in the default
+    // registry, is what keeps `hq doctor` from ever spawning a hook without the
+    // flag. Any FAIL/UNKNOWN it produces flows through computeExitCode below.
+    if (options.deepTest) {
+        const deepResults = await runDeepGuardTests(context);
+        // US-009: side-effecting hooks (autocommit, checkpoint, journal, reindex, …)
+        // cannot be verified by verdict, so they run in throwaway sandboxes and their
+        // fixture cases assert observable effects. Their verdicts join the same deep
+        // family and flow through computeExitCode below.
+        const effectResults = await runSideEffectTests(context);
+        families.push({
+            family: { id: DEEP_FAMILY_ID, title: DEEP_FAMILY_TITLE },
+            results: [...deepResults, ...effectResults],
+        });
+        // Cross-platform parity replay (US-010): replay every pure-guard fixture
+        // case through the Claude, Codex, and Grok adapters and compare verdicts, so
+        // platform drift surfaces as a test result. Also gated behind --deep-test,
+        // and it too runs only in its own sandbox — never the live tree.
+        const parityResults = await runParityReplay(context);
+        families.push({
+            family: { id: PARITY_FAMILY_ID, title: PARITY_FAMILY_TITLE },
+            results: parityResults,
+        });
+    }
+    if (options.json) {
+        write(renderJson(buildDoctorJson({ hqRoot, families, platform })));
+    }
+    else {
+        write(renderText({
+            hqRoot,
+            families,
+            platform,
+            verbose: options.verbose ?? false,
+            color: options.color ?? false,
+        }));
+    }
+    // The exit-code contract: 0 unless some result is FAIL or UNKNOWN. WARN,
+    // UNTESTED, NA, and KNOWN-DEFECT are reported but never fail the command.
+    return { exitCode: computeExitCode(families), hqRoot, families };
+}
+/** Register the top-level `hq doctor` command so it appears in `hq --help`. */
+export function registerDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Verify HQ hook guardrails are wired and firing (read-only, offline).")
+        .option("--json", "Emit the machine-readable JSON document (no colour).")
+        .option("--verbose", "Also print every PASS result in text output.")
+        .option("--no-color", "Disable ANSI colour even on a TTY.")
+        .option("--session-id <id>", "Scope the runtime probe's ledger check to this exact session.")
+        .option("--deep-test", "Also fire pure-guard hooks through the real gate under all three profiles (sandboxed).")
+        .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
+        .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
+        .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
+        .action(async (opts) => {
+        // `--fix` is the only write path. It resolves the tree, applies the
+        // allowlisted repairs behind a backup + confirmation, and returns its own
+        // exit code; the read-only report below never runs in this branch.
+        if (opts.fix === true) {
+            const hqRoot = resolveHqRoot();
+            if (!hqRoot) {
+                process.stderr.write(`hq doctor --fix: not inside an HQ tree.\n` +
+                    `  Looking for a directory containing all of: ${HQ_ROOT_MARKERS.join(", ")}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            const fixResult = await applyFixes({
+                hqRoot,
+                yes: opts.yes === true,
+                force: opts.force === true,
+                confirm: promptYesNo,
+            });
+            process.exitCode = fixResult.exitCode;
+            return;
+        }
+        const json = opts.json === true;
+        // Colour only when writing text to an interactive terminal, and never
+        // when NO_COLOR is set. A non-TTY (pipe, file, CI) gets no ANSI at all.
+        const color = !json &&
+            opts.color !== false &&
+            process.stdout.isTTY === true &&
+            !process.env.NO_COLOR;
+        // Detect the host once, here at the CLI boundary, and hand it to the run.
+        // The runtime probe (US-006) needs the real host to tell an app/SDK
+        // runtime that never dispatches hooks apart from a CLI that does.
+        const detection = detectPlatform();
+        const platform = {
+            id: detection.platform,
+            evidence: detection.evidence,
+        };
+        const result = await runDoctor({
+            json,
+            verbose: opts.verbose === true,
+            color,
+            platform,
+            sessionId: opts.sessionId,
+            deepTest: opts.deepTest === true,
+        });
+        // Set the exit code rather than calling process.exit, so the CLI's
+        // normal shutdown (telemetry flush) still runs. Non-zero means either an
+        // out-of-tree run or a FAIL/UNKNOWN result.
+        process.exitCode = result.exitCode;
+    });
+}
+/**
+ * Interactive y/N confirmation for `--fix`. Resolves false on a non-TTY stdin
+ * (so a piped run without `--yes` writes nothing) and on anything other than an
+ * explicit yes.
+ */
+function promptYesNo() {
+    if (!process.stdin.isTTY)
+        return Promise.resolve(false);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question("Apply these repairs? [y/N] ", (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/scaffold-fast.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Fast-path manifest for relocated scaffold scripts, kept deliberately
+ * dependency-light.
+ *
+ * `main.ts` eagerly imports the CLI's entire (~60-module) command graph, so any
+ * command routed through it pays seconds of startup — fine for a human typing a
+ * command, ruinous for the hot plumbing this hosts: `hq core hq-session` is
+ * called several times per skill/hook, and `hq core checkpoint-stop-gate` runs
+ * on every turn's Stop. The entrypoint routes those directly to
+ * `runBundledScript` instead, and this module holds the tiny parser + table that
+ * routing needs WITHOUT importing anything heavy. `core.ts` names the same
+ * assets, and a test pins the two lists together so they cannot drift.
+ */
+export type FastScaffoldScript = {
+    /** Direct subcommand name — `hq core <name>`. */
+    name: string;
+    /** Path under `assets/scaffold/`, e.g. `core/scripts/foo.sh`. */
+    asset: string;
+};
+/** The relocated scripts that qualify for the entrypoint fast path. */
+export declare const FAST_SCAFFOLD_SCRIPTS: readonly FastScaffoldScript[];
+export type ParsedFastCore = {
+    /** The bundled asset to run. */
+    asset: string;
+    /** `--hq-root <path>` value, if the caller passed the group option. */
+    hqRootArg?: string;
+    /** Everything after the command name, passed to the script verbatim. */
+    args: string[];
+};
+/**
+ * Parse `hq core [--hq-root <path>] <name> [args...]` when `<name>` is a
+ * fast-path script. Returns null for anything else so the caller defers to the
+ * full CLI. Mirrors the `core` group's single `--hq-root` option (both the
+ * `--hq-root <path>` and `--hq-root=<path>` forms) and its `root: "live"`
+ * binding; every remaining token is passed through untouched, exactly as the
+ * commander registration does with allowUnknownOption + a variadic argument.
+ */
+export declare function parseFastCore(argv: readonly string[]): ParsedFastCore | null;
+/** Whether this invocation is a fast-path scaffold dispatch. */
+export declare function isFastCoreRequest(argv: readonly string[]): boolean;
+//# sourceMappingURL=scaffold-fast.d.ts.map

package/dist/commands/scaffold-fast.js

@@ -0,0 +1,57 @@
+/**
+ * Fast-path manifest for relocated scaffold scripts, kept deliberately
+ * dependency-light.
+ *
+ * `main.ts` eagerly imports the CLI's entire (~60-module) command graph, so any
+ * command routed through it pays seconds of startup — fine for a human typing a
+ * command, ruinous for the hot plumbing this hosts: `hq core hq-session` is
+ * called several times per skill/hook, and `hq core checkpoint-stop-gate` runs
+ * on every turn's Stop. The entrypoint routes those directly to
+ * `runBundledScript` instead, and this module holds the tiny parser + table that
+ * routing needs WITHOUT importing anything heavy. `core.ts` names the same
+ * assets, and a test pins the two lists together so they cannot drift.
+ */
+/** The relocated scripts that qualify for the entrypoint fast path. */
+export const FAST_SCAFFOLD_SCRIPTS = [
+    { name: "checkpoint-stop-gate", asset: "core/scripts/checkpoint-stop-gate.sh" },
+    { name: "hq-session", asset: "core/scripts/hq-session.sh" },
+];
+/**
+ * Parse `hq core [--hq-root <path>] <name> [args...]` when `<name>` is a
+ * fast-path script. Returns null for anything else so the caller defers to the
+ * full CLI. Mirrors the `core` group's single `--hq-root` option (both the
+ * `--hq-root <path>` and `--hq-root=<path>` forms) and its `root: "live"`
+ * binding; every remaining token is passed through untouched, exactly as the
+ * commander registration does with allowUnknownOption + a variadic argument.
+ */
+export function parseFastCore(argv) {
+    // argv is process.argv: [node, hq, core, ...rest].
+    if (argv[2] !== "core")
+        return null;
+    let i = 3;
+    let hqRootArg;
+    const head = argv[i];
+    if (head === "--hq-root") {
+        const value = argv[i + 1];
+        if (typeof value !== "string")
+            return null;
+        hqRootArg = value;
+        i += 2;
+    }
+    else if (typeof head === "string" && head.startsWith("--hq-root=")) {
+        hqRootArg = head.slice("--hq-root=".length);
+        i += 1;
+    }
+    const name = argv[i];
+    if (typeof name !== "string")
+        return null;
+    const entry = FAST_SCAFFOLD_SCRIPTS.find((candidate) => candidate.name === name);
+    if (!entry)
+        return null;
+    return { asset: entry.asset, hqRootArg, args: argv.slice(i + 1) };
+}
+/** Whether this invocation is a fast-path scaffold dispatch. */
+export function isFastCoreRequest(argv) {
+    return parseFastCore(argv) !== null;
+}
+//# sourceMappingURL=scaffold-fast.js.map

package/dist/fast-core.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fast-path dispatcher for relocated scaffold scripts.
+ *
+ * Reached from the entrypoint BEFORE `main.ts` (and its heavy command graph) is
+ * ever imported, so a hot `hq core hq-session` / `hq core checkpoint-stop-gate`
+ * dispatches in roughly node's own startup time. It imports only the light root
+ * resolver and the bundled-script runner. The slower commander registration in
+ * `core.ts` remains the complete path for any invocation this does not match.
+ */
+/**
+ * Run the fast-path scaffold script named in `argv` and exit with its code.
+ * Only call when {@link isFastCoreRequest} is true; a non-match returns without
+ * doing anything.
+ */
+export declare function runFastCore(argv: readonly string[]): void;
+//# sourceMappingURL=fast-core.d.ts.map

package/dist/fast-core.js

@@ -0,0 +1,47 @@
+/**
+ * Fast-path dispatcher for relocated scaffold scripts.
+ *
+ * Reached from the entrypoint BEFORE `main.ts` (and its heavy command graph) is
+ * ever imported, so a hot `hq core hq-session` / `hq core checkpoint-stop-gate`
+ * dispatches in roughly node's own startup time. It imports only the light root
+ * resolver and the bundled-script runner. The slower commander registration in
+ * `core.ts` remains the complete path for any invocation this does not match.
+ */
+import { resolveLiveRoot } from "./utils/hq-roots.js";
+import { runBundledScript } from "./utils/run-bundled-script.js";
+import { parseFastCore } from "./commands/scaffold-fast.js";
+/**
+ * Run the fast-path scaffold script named in `argv` and exit with its code.
+ * Only call when {@link isFastCoreRequest} is true; a non-match returns without
+ * doing anything.
+ */
+export function runFastCore(argv) {
+    const parsed = parseFastCore(argv);
+    if (!parsed)
+        return;
+    // `root: "live"` — resolve the live HQ root and run the script in it, exactly
+    // as core.ts's runEntry does. Fail soft: if no root can be resolved, run the
+    // script anyway with the inherited environment (the hook already carries
+    // CLAUDE_PROJECT_DIR, and each script has its own root fallback) rather than
+    // crashing a Stop hook on a resolution error.
+    let hqRoot;
+    try {
+        hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
+    }
+    catch {
+        hqRoot = undefined;
+    }
+    // Keep the CHILD in the caller's cwd, unlike the generic "live" dispatch. The
+    // relocated scripts read their data tree from the injected root, not cwd, and
+    // hq-session's Work Mesh registration serializes $PWD — so changing directory
+    // to the HQ root would mislabel a bind made from inside a project/worktree.
+    const { code } = runBundledScript({
+        asset: parsed.asset,
+        args: parsed.args,
+        cwd: process.cwd(),
+        hqRoot,
+    });
+    // Propagate verbatim: these scripts use their exit code as their interface.
+    process.exit(code);
+}
+//# sourceMappingURL=fast-core.js.map

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import "./node-preflight.js";
 import "./node-network-compat.js";
+import { isFastCoreRequest } from "./commands/scaffold-fast.js";
 declare function isVersionRequest(argv: readonly string[]): boolean;
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
+    isFastCoreRequest: typeof isFastCoreRequest;
 };
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,6 +4,9 @@
 import "./node-preflight.js";
 import "./node-network-compat.js";
 import { CLI_VERSION } from "./cli-version.js";
+// Dependency-light: a pure parser + table, no command graph. Safe to load on
+// every path (including --version) without reintroducing the heavy startup.
+import { isFastCoreRequest } from "./commands/scaffold-fast.js";
 function isVersionRequest(argv) {
     const args = argv.slice(2);
     return args.length === 1 && (args[0] === "--version" || args[0] === "-V" || args[0] === "-v");
@@ -11,6 +14,12 @@ function isVersionRequest(argv) {
 if (isVersionRequest(process.argv)) {
     process.stdout.write(`${CLI_VERSION}\n`);
 }
+else if (isFastCoreRequest(process.argv)) {
+    // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)
+    // dispatches straight to the bundled-script runner, so it never pays for the
+    // ~60-module command graph main.ts imports. See src/commands/scaffold-fast.ts.
+    void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
+}
 else {
     // Keep the command lifecycle detached from module evaluation, as it was
     // before the fast --version split. Some best-effort teardown work uses
@@ -19,5 +28,5 @@ else {
     // Rejections still become unhandled and preserve a genuine non-zero failure.
     void import("./main.js").then(({ runCli }) => runCli());
 }
-export const __test__ = { isVersionRequest };
+export const __test__ = { isVersionRequest, isFastCoreRequest };
 //# sourceMappingURL=index.js.map

package/dist/lib/core-utils/soft-timeout.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+ *
+ * Run a command under a SOFT timeout: WARN, don't kill. This is the CLI-hosted
+ * form of the shell primitive `core/scripts/lib/soft-timeout.sh`, so HQ scripts
+ * and hooks can call `hq core soft-timeout …` directly instead of shelling out
+ * to a bundled script.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events):
+ * a fixed deadline SIGTERMs an operation still making progress and loses the
+ * in-flight work. The fix is warn-and-continue — on each interval the command
+ * keeps running and a SOFT-TIMEOUT notice is written to stderr so whoever is
+ * watching decides (wait / background / kill), instead of the runner deciding
+ * by killing progressing work.
+ *
+ * Contract (identical to the shell primitive):
+ *   - `<interval>` — warn every interval. Bare number = seconds; 90s / 2m / 1h.
+ *   - `--hard-cap <spec>` — OPTIONAL safety ceiling for unattended callers.
+ *     Pure soft has no cap and never terminates. At the cap the command is
+ *     SIGTERM'd, then SIGKILL'd after a short grace, and the exit code is 124.
+ *   - `--label <name>` — name shown in the notice (default: the command basename).
+ *   - Exit status: the command's own, verbatim — except 124 on a hard-cap.
+ *     A soft warning alone never changes the exit status.
+ */
+import { spawn } from "node:child_process";
+/** Parse a duration spec (Ns / Nm / Nh / bare N=seconds) to integer seconds. */
+export declare function parseDurationSecs(spec: string): number | null;
+export interface ParsedSoftTimeoutArgs {
+    intervalSecs: number;
+    hardCapSecs: number | null;
+    label: string | null;
+    command: string[];
+}
+/** Parse the `hq core soft-timeout` argv. Throws a plain Error on misuse. */
+export declare function parseSoftTimeoutArgs(argv: string[]): ParsedSoftTimeoutArgs;
+export interface RunSoftTimeoutDeps {
+    spawnFn?: typeof spawn;
+    stderr?: NodeJS.WritableStream;
+    now?: () => Date;
+    /** Signal a whole process group by (leader) pid. Defaults to process.kill(-pid). */
+    killGroup?: (pid: number, sig: NodeJS.Signals) => void;
+}
+/**
+ * Execute the command under the soft timeout. Resolves to the exit code the
+ * process should exit with. Never rejects on a timeout — a warning is only a
+ * stderr line. Rejects only on spawn failure.
+ */
+export declare function runSoftTimeout(parsed: ParsedSoftTimeoutArgs, deps?: RunSoftTimeoutDeps): Promise<number>;
+/**
+ * Entry point for the `hq core soft-timeout` command. Parses argv, runs, and
+ * returns the exit code (never throws for a timeout; throws only on misuse or
+ * spawn failure, which the caller maps to a non-zero exit).
+ */
+export declare function softTimeoutCommand(argv: string[]): Promise<number>;
+//# sourceMappingURL=soft-timeout.d.ts.map