@indigoai-us/hq-cli 5.98.2 → 5.99.0

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/doctor/__testing__/fake-hq-tree.d.ts

@@ -0,0 +1,194 @@
+/**
+ * buildFakeHqTree — a reusable test harness that materialises a fake HQ tree in
+ * the OS temp directory from a declarative spec.
+ *
+ * Every `hq doctor` check is fundamentally a function of the on-disk shape of an
+ * HQ tree: which hooks exist, whether they are executable, whether they are
+ * registered in settings, which `hook-gate.sh` profiles list them, and whether
+ * the Codex mirror still matches its Claude original. This helper lets a test
+ * declare that shape — including its deliberately-broken variants — and get back
+ * a throwaway tree plus a manifest describing exactly what was written, without
+ * ever touching the real HQ tree.
+ *
+ * Design notes:
+ *   - Everything is written under a `mkdtempSync` root inside `os.tmpdir()`. The
+ *     real HQ tree is never read or written.
+ *   - The root path is canonicalised with `realpathSync` so callers can assert
+ *     containment under the temp dir on platforms (macOS) where the temp dir is
+ *     a symlink (`/var` -> `/private/var`).
+ *   - Cleanup is automatic: the first build registers a single `process` exit
+ *     handler that removes every tracked root, so nothing survives a test run,
+ *     including on test failure. `tree.cleanup()` is also exposed for eager
+ *     removal, and is idempotent.
+ *
+ * The reference for this pattern is core/scripts/test-codex-hook-adapter.sh,
+ * which stands up a throwaway HQ tree with `mktemp -d` and stubbed hook scripts.
+ */
+/** Claude/Codex lifecycle events a hook can be registered against. */
+export type HookEventName = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "SessionStart" | "Stop" | "SubagentStop" | "PreCompact" | "Notification";
+/** The three `hook-gate.sh` allowlist profiles. */
+export type GateProfile = "minimal" | "standard" | "strict";
+/** Canonical ordering of the gate profiles. */
+export declare const GATE_PROFILES: readonly GateProfile[];
+/**
+ * Declares a Codex mirror of a Claude hook. Claude and Grok both execute the
+ * canonical `.claude/hooks/` scripts; only Codex runs duplicated copies, so the
+ * Codex mirror is the entire drift surface the doctor has to watch.
+ */
+export interface FakeCodexMirrorSpec {
+    /** Whether the mirror file is written to `.codex/hooks/`. Default: true. */
+    present?: boolean;
+    /**
+     * Script body for the mirror. Defaults to the Claude original's body (an
+     * identical, healthy mirror). Supply a different string to model content
+     * drift between the Codex copy and its Claude original.
+     */
+    body?: string;
+    /** Whether the mirror file carries the executable bit. Default: true. */
+    executable?: boolean;
+    /** Explicit file mode override (masked to 0o777). Overrides `executable`. */
+    mode?: number;
+    /** Whether the mirror is registered in `.codex/hooks.json`. Default: true. */
+    registered?: boolean;
+    /** Optional settings matcher (e.g. "Bash", "Glob"). */
+    matcher?: string;
+}
+/** Declares a single hook and its cross-platform state. */
+export interface FakeHookSpec {
+    /** Hook id, e.g. "detect-secrets". Also names the `<id>.sh` file. */
+    id: string;
+    /** Script body. Default: a trivial pass-through that exits 0. */
+    body?: string;
+    /**
+     * Whether the `.claude/hooks/<id>.sh` file is written to disk. Default: true.
+     * Set false to model a missing hook file (combine with `registered: true` for
+     * a hook that is registered in settings but absent from disk).
+     */
+    present?: boolean;
+    /**
+     * Whether the hook file carries the executable bit. Default: true. Set false
+     * to model a present-but-not-executable hook (mode 0o644).
+     */
+    executable?: boolean;
+    /** Explicit file mode override (masked to 0o777). Overrides `executable`. */
+    mode?: number;
+    /** Whether the hook is registered in `.claude/settings.json`. Default: true. */
+    registered?: boolean;
+    /** Events the hook registers against. Default: ["PreToolUse"]. */
+    events?: HookEventName[];
+    /** Optional settings matcher (e.g. "Bash", "Glob"). */
+    matcher?: string;
+    /**
+     * Which `hook-gate.sh` profiles list this id. Default: all three. Pass a
+     * subset (e.g. ["minimal"]) to model a hook id present in only some of the
+     * three profiles — the exact defect the three-profile check exists to catch.
+     */
+    profiles?: GateProfile[];
+    /**
+     * Codex mirror configuration. When omitted, a healthy identical mirror is
+     * created. Pass `false` to model a Claude hook with no Codex counterpart, or
+     * an object to override the mirror (e.g. `{ body }` to model content drift).
+     */
+    codex?: FakeCodexMirrorSpec | false;
+}
+/** Declares the `.grok/hooks/` state. */
+export interface FakeGrokSpec {
+    /** Whether the `.grok/hooks/` scaffold is created at all. Default: true. */
+    present?: boolean;
+    /** Whether `hq-grok-hook-adapter.sh` carries the executable bit. Default: true. */
+    adapterExecutable?: boolean;
+    /**
+     * Whether the user-global bridge under `~/.grok/hooks/` is recorded as
+     * installed. The real bridge lives in the home dir and cannot be simulated in
+     * a project-local temp tree, so this is a manifest flag only. Default: true.
+     */
+    bridgeInstalled?: boolean;
+}
+/** The declarative spec passed to {@link buildFakeHqTree}. */
+export interface FakeHqTreeSpec {
+    /** Hooks to materialise. Default: none. */
+    hooks?: FakeHookSpec[];
+    /** Extra top-level keys merged into `.claude/settings.json`. */
+    claudeSettings?: Record<string, unknown>;
+    /** Grok scaffold config, or `false` to omit `.grok/`. Default: healthy. */
+    grok?: FakeGrokSpec | false;
+    /** Initialise a git repo at the tree root. Default: false. */
+    git?: boolean;
+    /** temp-dir name prefix. Default: "hq-doctor-fake-". */
+    prefix?: string;
+}
+/** Manifest entry describing a materialised Codex mirror. */
+export interface FakeCodexManifestEntry {
+    /** Absolute path where the mirror lives (whether or not it was written). */
+    scriptPath: string;
+    /** Whether the mirror file exists on disk. */
+    present: boolean;
+    /** On-disk mode bits (0o777-masked), or null when absent. */
+    mode: number | null;
+    /** Whether the mirror carries the executable bit. */
+    executable: boolean;
+    /** Whether the mirror is registered in `.codex/hooks.json`. */
+    registered: boolean;
+    /** Whether the mirror's content differs from its Claude original. */
+    drifted: boolean;
+}
+/** Manifest entry describing a materialised hook across all platforms. */
+export interface FakeHookManifestEntry {
+    id: string;
+    /** Absolute path of the Claude script (whether or not it was written). */
+    scriptPath: string;
+    /** Whether the Claude hook file exists on disk. */
+    present: boolean;
+    /** On-disk mode bits (0o777-masked), or null when absent. */
+    mode: number | null;
+    /** Whether the Claude hook carries the executable bit. */
+    executable: boolean;
+    /** Whether the hook is registered in `.claude/settings.json`. */
+    registered: boolean;
+    /** Events the hook is registered against. */
+    events: HookEventName[];
+    /** Optional settings matcher (e.g. "Bash", "Glob"), or null when unset. */
+    matcher: string | null;
+    /** Which `hook-gate.sh` profiles list this id. */
+    profiles: GateProfile[];
+    /** The Codex mirror, or null when the hook has no Codex counterpart. */
+    codex: FakeCodexManifestEntry | null;
+}
+/** A structured description of everything {@link buildFakeHqTree} wrote. */
+export interface FakeHqTreeManifest {
+    root: string;
+    claudeSettingsPath: string;
+    claudeHooksDir: string;
+    claudeHookGatePath: string;
+    codexHooksJsonPath: string;
+    codexHooksDir: string;
+    codexHookGatePath: string;
+    grokDir: string | null;
+    grokAdapterPath: string | null;
+    grokRegistrationPath: string | null;
+    grokBridgeInstalled: boolean;
+    gitInitialised: boolean;
+    hooks: FakeHookManifestEntry[];
+}
+/** The handle returned by {@link buildFakeHqTree}. */
+export interface FakeHqTree {
+    /** Absolute, canonicalised tree root under the OS temp dir. */
+    root: string;
+    /** Structured description of everything that was written. */
+    manifest: FakeHqTreeManifest;
+    /** Join a path relative to the tree root. */
+    path: (...segments: string[]) => string;
+    /** Remove this tree from disk. Idempotent. */
+    cleanup: () => void;
+}
+/** Remove every fake HQ tree still on disk. Safe to call repeatedly. */
+export declare function cleanupAllFakeHqTrees(): void;
+/** The set of tree roots this process is still tracking for cleanup. */
+export declare function trackedFakeHqTreeRoots(): string[];
+/**
+ * Materialise a fake HQ tree from `spec` and return its root, manifest, and a
+ * cleanup handle. The tree lives under `os.tmpdir()` and is swept automatically
+ * when the process exits.
+ */
+export declare function buildFakeHqTree(spec?: FakeHqTreeSpec): FakeHqTree;
+//# sourceMappingURL=fake-hq-tree.d.ts.map