@indigoai-us/hq-cli 5.98.3 → 5.99.1

package/dist/lib/core-utils/soft-timeout.js

@@ -0,0 +1,205 @@
+/**
+ * `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";
+import { basename } from "node:path";
+import { constants as osConstants } from "node:os";
+/** Parse a duration spec (Ns / Nm / Nh / bare N=seconds) to integer seconds. */
+export function parseDurationSecs(spec) {
+    const m = /^([0-9]+)([smh]?)$/.exec(spec);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "":
+        case "s":
+            return n;
+        case "m":
+            return n * 60;
+        case "h":
+            return n * 3600;
+        default:
+            return null;
+    }
+}
+/** Parse the `hq core soft-timeout` argv. Throws a plain Error on misuse. */
+export function parseSoftTimeoutArgs(argv) {
+    const args = [...argv];
+    if (args.length === 0 || args[0].startsWith("--")) {
+        throw new Error("soft-timeout: first argument must be the warn interval");
+    }
+    const intervalSecs = parseDurationSecs(args.shift());
+    if (intervalSecs === null || intervalSecs <= 0) {
+        throw new Error("soft-timeout: interval must be a positive duration (e.g. 120, 2m)");
+    }
+    let hardCapSecs = null;
+    let label = null;
+    // Consume our own options; the FIRST non-option token (or an explicit `--`)
+    // begins the wrapped command. `--` is optional because Commander strips a
+    // single leading `--` before these args reach us — so `hq core soft-timeout
+    // 30 -- sleep 60` arrives here as `30 sleep 60`, and treating the first
+    // non-option as the command start makes both forms parse identically.
+    while (args.length > 0) {
+        const tok = args[0];
+        if (tok === "--") {
+            args.shift();
+            break;
+        }
+        if (tok === "--hard-cap") {
+            args.shift();
+            const spec = args.shift();
+            const secs = spec ? parseDurationSecs(spec) : null;
+            if (secs === null || secs <= 0)
+                throw new Error(`soft-timeout: invalid --hard-cap '${spec ?? ""}'`);
+            hardCapSecs = secs;
+        }
+        else if (tok === "--label") {
+            args.shift();
+            label = args.shift() ?? null;
+            if (label === null)
+                throw new Error("soft-timeout: --label needs a value");
+        }
+        else {
+            break; // first non-option token: the wrapped command starts here
+        }
+    }
+    if (args.length === 0) {
+        throw new Error("soft-timeout: no command given (expected: soft-timeout <interval> [...] -- cmd)");
+    }
+    return { intervalSecs, hardCapSecs, label: label ?? null, command: args };
+}
+function hhmmss(now) {
+    return now.toISOString().slice(11, 19);
+}
+/**
+ * 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 function runSoftTimeout(parsed, deps = {}) {
+    const spawnFn = deps.spawnFn ?? spawn;
+    const err = deps.stderr ?? process.stderr;
+    const now = deps.now ?? (() => new Date());
+    const killGroup = deps.killGroup ?? ((pid, sig) => process.kill(-pid, sig));
+    const { intervalSecs, hardCapSecs, command } = parsed;
+    const label = parsed.label ?? basename(command[0]);
+    return new Promise((resolve, reject) => {
+        // detached: the child leads its own process group so a hard cap can signal
+        // the WHOLE group (child + descendants), not just the child — otherwise an
+        // orphaned grandchild (e.g. run-project's builder) keeps running after the
+        // wrapper returns. stdio inherited so the command's stdin/stdout/stderr —
+        // including piped or interactive input — pass through unchanged.
+        const child = spawnFn(command[0], command.slice(1), { stdio: "inherit", detached: true });
+        let capped = false;
+        let ticks = 0;
+        // Signal the child's process group when we can (detached leader), else the
+        // child alone. Guarded: the group may already be gone.
+        const signalTree = (sig) => {
+            try {
+                if (typeof child.pid === "number")
+                    killGroup(child.pid, sig);
+                else
+                    child.kill(sig);
+            }
+            catch {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        };
+        const warner = setInterval(() => {
+            ticks += 1;
+            const elapsed = ticks * intervalSecs;
+            err.write(`[${hhmmss(now())}] SOFT-TIMEOUT: ${label} still running after ${elapsed}s ` +
+                `(${ticks}× ${intervalSecs}s window) — exceeded its window; NOT killed. ` +
+                `Decide: wait / background / kill (kill ${child.pid}).\n`);
+        }, intervalSecs * 1000);
+        // The hard cap runs on its OWN timer, independent of the warning interval,
+        // so a cap shorter than (or not a multiple of) the interval still fires on
+        // time rather than at the next interval boundary.
+        let capTimer = null;
+        let killTimer = null;
+        if (hardCapSecs !== null) {
+            capTimer = setTimeout(() => {
+                capped = true;
+                err.write(`[${hhmmss(now())}] SOFT-TIMEOUT: ${label} hit hard cap ${hardCapSecs}s — sending SIGTERM.\n`);
+                signalTree("SIGTERM");
+                killTimer = setTimeout(() => signalTree("SIGKILL"), 5000);
+            }, hardCapSecs * 1000);
+        }
+        const cleanup = () => {
+            clearInterval(warner);
+            if (capTimer)
+                clearTimeout(capTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
+        child.on("error", (e) => {
+            cleanup();
+            reject(e);
+        });
+        child.on("exit", (code, signal) => {
+            cleanup();
+            if (capped) {
+                resolve(124);
+            }
+            else if (code !== null) {
+                resolve(code);
+            }
+            else {
+                // Killed by a signal (external SIGINT/SIGHUP/SIGTERM/…): mirror the
+                // shell convention of 128 + signal number for whichever signal it was,
+                // so callers keep the real termination status (e.g. 130 for SIGINT).
+                const n = signal ? osConstants.signals[signal] : undefined;
+                resolve(typeof n === "number" ? 128 + n : 1);
+            }
+        });
+    });
+}
+/**
+ * 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 async function softTimeoutCommand(argv) {
+    let parsed;
+    try {
+        parsed = parseSoftTimeoutArgs(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    try {
+        return await runSoftTimeout(parsed);
+    }
+    catch (e) {
+        process.stderr.write(`soft-timeout: failed to run command: ${e.message}\n`);
+        return 127;
+    }
+}
+//# sourceMappingURL=soft-timeout.js.map

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

@@ -0,0 +1,62 @@
+/**
+ * `hq core timeout-guard` — PreToolUse decision for the foreground-timeout guard.
+ *
+ * The hook logic that used to live in
+ * `.claude/hooks/block-foreground-timeout-over-harness-ceiling.sh` now lives
+ * here so it can be maintained (and gated) in one place; the shipped hook is a
+ * thin shim that pipes the PreToolUse JSON to this command and blocks iff it
+ * exits 2.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events): a
+ * FOREGROUND shell tool call is SIGTERM'd at the harness's outer deadline
+ * (~2 min default, 10 min max) regardless of any longer timeout it declares, so
+ * the in-flight work is lost (exit 143). We can't change the harness, so the
+ * guard blocks a long foreground declaration and steers it to a background run
+ * (no outer deadline, auto-notifies). It fires for Claude, Codex, and Grok —
+ * their shell tool calls all reach the hook normalized to `tool_input.command`.
+ *
+ * Rollout gate: for now the guard only acts for `@getindigo.ai` HQ users; every
+ * other identity (and machine identities / logged-out) is allowed through.
+ *
+ * Exit codes: 0 = allow, 2 = block.
+ */
+/**
+ * Worst-case inner deadline (seconds) declared in a command: a `timeout` /
+ * `gtimeout` prefix (matched by executable BASENAME, so `/usr/bin/timeout`
+ * counts) or a `perl -e 'alarm(N)…'` deadline. Segment on shell separators and
+ * only treat a segment's LEADING command word as an invocation, so the word
+ * `timeout` inside a quoted argument (e.g. `printf 'uses timeout 601s'`) does
+ * not trip it.
+ */
+export declare function parseInnerDeadlineSecs(command: string): number;
+export interface TimeoutGuardInput {
+    command: string;
+    toolTimeoutMs?: number;
+    runInBackground?: boolean;
+}
+export interface GuardVerdict {
+    block: boolean;
+    reason?: string;
+}
+/**
+ * Pure decision: does this foreground declaration exceed the deadline it can
+ * actually secure? Compares the inner deadline against the EFFECTIVE ceiling —
+ * the declared tool timeout (capped at the harness max) or the 2-minute default
+ * when none is declared — rather than always against the 10-minute max.
+ */
+export declare function evaluateTimeoutGuard(input: TimeoutGuardInput): GuardVerdict;
+export interface TimeoutGuardDeps {
+    /** Resolve the current HQ user email for the rollout gate. Default: cached id token. */
+    getEmail?: () => string | undefined;
+    env?: NodeJS.ProcessEnv;
+    stderr?: NodeJS.WritableStream;
+}
+/** Whether the guard is active for this identity (rollout gate). */
+export declare function isGatedUser(email: string | undefined): boolean;
+/**
+ * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
+ * return the exit code (0 allow / 2 block). Never throws — a parse failure or a
+ * missing identity fails OPEN (allow), because a hook must not break tool calls.
+ */
+export declare function timeoutGuardCommand(stdin: string, deps?: TimeoutGuardDeps): number;
+//# sourceMappingURL=timeout-guard.d.ts.map

package/dist/lib/core-utils/timeout-guard.js

@@ -0,0 +1,207 @@
+/**
+ * `hq core timeout-guard` — PreToolUse decision for the foreground-timeout guard.
+ *
+ * The hook logic that used to live in
+ * `.claude/hooks/block-foreground-timeout-over-harness-ceiling.sh` now lives
+ * here so it can be maintained (and gated) in one place; the shipped hook is a
+ * thin shim that pipes the PreToolUse JSON to this command and blocks iff it
+ * exits 2.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events): a
+ * FOREGROUND shell tool call is SIGTERM'd at the harness's outer deadline
+ * (~2 min default, 10 min max) regardless of any longer timeout it declares, so
+ * the in-flight work is lost (exit 143). We can't change the harness, so the
+ * guard blocks a long foreground declaration and steers it to a background run
+ * (no outer deadline, auto-notifies). It fires for Claude, Codex, and Grok —
+ * their shell tool calls all reach the hook normalized to `tool_input.command`.
+ *
+ * Rollout gate: for now the guard only acts for `@getindigo.ai` HQ users; every
+ * other identity (and machine identities / logged-out) is allowed through.
+ *
+ * Exit codes: 0 = allow, 2 = block.
+ */
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { peekIdToken } from "../../utils/id-token.js";
+// Observed Claude Code Bash-tool bounds. The tool `timeout` (ms) raises the
+// deadline up to the max; with none declared the default applies.
+const HARNESS_DEFAULT_MS = 120_000; // 2 min
+const HARNESS_MAX_MS = 600_000; // 10 min
+const GATE_DOMAIN = "@getindigo.ai";
+function basename(token) {
+    const i = token.lastIndexOf("/");
+    return i >= 0 ? token.slice(i + 1) : token;
+}
+/** Duration spec (Ns / Nm / Nh / Nd / bare N=seconds) → seconds, or 0. */
+function durationToSecs(tok) {
+    const m = /^([0-9]+)([smhd]?)$/.exec(tok);
+    if (!m)
+        return 0;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "":
+        case "s":
+            return n;
+        case "m":
+            return n * 60;
+        case "h":
+            return n * 3600;
+        case "d":
+            return n * 86400;
+        default:
+            return 0;
+    }
+}
+/**
+ * Worst-case inner deadline (seconds) declared in a command: a `timeout` /
+ * `gtimeout` prefix (matched by executable BASENAME, so `/usr/bin/timeout`
+ * counts) or a `perl -e 'alarm(N)…'` deadline. Segment on shell separators and
+ * only treat a segment's LEADING command word as an invocation, so the word
+ * `timeout` inside a quoted argument (e.g. `printf 'uses timeout 601s'`) does
+ * not trip it.
+ */
+export function parseInnerDeadlineSecs(command) {
+    let worst = 0;
+    for (const rawSeg of command.split(/[;|&()]/)) {
+        const seg = rawSeg.trim();
+        if (!seg)
+            continue;
+        const words = seg.split(/\s+/);
+        let i = 0;
+        while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
+            i++; // skip env assigns
+        if (i >= words.length)
+            continue;
+        const cmd = basename(words[i]);
+        if (cmd !== "timeout" && cmd !== "gtimeout")
+            continue;
+        i++;
+        let dur = "";
+        while (i < words.length) {
+            const t = words[i];
+            if (t === "--foreground" || t === "--preserve-status" || t === "-v" || t === "--verbose") {
+                i++;
+                continue;
+            }
+            if (t === "-s" || t === "--signal" || t === "-k" || t === "--kill-after") {
+                i += 2;
+                continue;
+            }
+            if (t.startsWith("-")) {
+                i++;
+                continue;
+            }
+            dur = t;
+            break;
+        }
+        if (dur)
+            worst = Math.max(worst, durationToSecs(dur));
+    }
+    // perl alarm() — spans separators, so match on the raw command.
+    const mMin = /alarm\(\s*([0-9]+)\s*\*\s*60/.exec(command);
+    if (mMin)
+        worst = Math.max(worst, Number(mMin[1]) * 60);
+    else {
+        const mSec = /alarm\(?\s*([0-9]+)/.exec(command);
+        if (mSec)
+            worst = Math.max(worst, Number(mSec[1]));
+    }
+    return worst;
+}
+/**
+ * Pure decision: does this foreground declaration exceed the deadline it can
+ * actually secure? Compares the inner deadline against the EFFECTIVE ceiling —
+ * the declared tool timeout (capped at the harness max) or the 2-minute default
+ * when none is declared — rather than always against the 10-minute max.
+ */
+export function evaluateTimeoutGuard(input) {
+    const { command, toolTimeoutMs } = input;
+    if (input.runInBackground)
+        return { block: false };
+    if (toolTimeoutMs !== undefined && toolTimeoutMs > HARNESS_MAX_MS) {
+        return {
+            block: true,
+            reason: `the Bash tool 'timeout' parameter is ${toolTimeoutMs}ms (> the ${HARNESS_MAX_MS}ms / 10-minute harness ceiling)`,
+        };
+    }
+    const effectiveMs = toolTimeoutMs !== undefined ? Math.min(toolTimeoutMs, HARNESS_MAX_MS) : HARNESS_DEFAULT_MS;
+    const innerSecs = parseInnerDeadlineSecs(command);
+    if (innerSecs > 0 && innerSecs * 1000 > effectiveMs) {
+        const ceilingDesc = toolTimeoutMs !== undefined
+            ? `the declared ${Math.round(effectiveMs / 1000)}s tool deadline`
+            : `the ~${HARNESS_DEFAULT_MS / 1000}s default foreground deadline`;
+        return {
+            block: true,
+            reason: `an inner ${innerSecs}s deadline (timeout/gtimeout/alarm) exceeds ${ceilingDesc}`,
+        };
+    }
+    return { block: false };
+}
+const BLOCK_MESSAGE = (reason) => `BLOCKED: this FOREGROUND command declares a timeout past the harness ceiling —
+${reason}.
+
+A foreground shell tool call is SIGTERM'd at the harness's outer deadline
+(~2 min default, 10 min max) regardless of any longer timeout you declared. It
+will die with exit 143 ("timed out after 10m 0s") and lose whatever it was doing
+— the largest harness-friction cluster in the 2026-08-10 team analysis
+(finding 2.1, 1,393 events).
+
+Do this instead: launch it as a background task (run_in_background: true).
+Background tasks survive turn boundaries, have no outer deadline, and auto-notify
+on completion. (\`hq core soft-timeout\` warns without killing for work you
+supervise yourself.)
+
+Policy: hq-foreground-timeout-killed-by-harness-deadline.
+Bypass for one sanctioned foreground run: prefix HQ_ALLOW_LONG_FOREGROUND=1.`;
+function defaultEmail() {
+    try {
+        const cached = loadCachedTokens();
+        if (!cached)
+            return undefined;
+        const email = peekIdToken(cached.idToken).email;
+        return typeof email === "string" ? email : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the guard is active for this identity (rollout gate). */
+export function isGatedUser(email) {
+    return typeof email === "string" && email.toLowerCase().endsWith(GATE_DOMAIN);
+}
+/**
+ * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
+ * return the exit code (0 allow / 2 block). Never throws — a parse failure or a
+ * missing identity fails OPEN (allow), because a hook must not break tool calls.
+ */
+export function timeoutGuardCommand(stdin, deps = {}) {
+    const env = deps.env ?? process.env;
+    const err = deps.stderr ?? process.stderr;
+    let payload;
+    try {
+        payload = JSON.parse(stdin);
+    }
+    catch {
+        return 0;
+    }
+    const ti = payload?.tool_input ?? {};
+    const command = typeof ti.command === "string" ? ti.command : "";
+    if (!command)
+        return 0;
+    // The inline escape hatch and the env escape hatch both bypass.
+    if (env.HQ_ALLOW_LONG_FOREGROUND === "1")
+        return 0;
+    if (/(^|\s)HQ_ALLOW_LONG_FOREGROUND=1(\s|$)/.test(command))
+        return 0;
+    // Rollout gate: only act for @getindigo.ai identities.
+    const getEmail = deps.getEmail ?? defaultEmail;
+    if (!isGatedUser(getEmail()))
+        return 0;
+    const runInBackground = ti.run_in_background === true;
+    const toolTimeoutMs = typeof ti.timeout === "number" ? ti.timeout : undefined;
+    const verdict = evaluateTimeoutGuard({ command, toolTimeoutMs, runInBackground });
+    if (!verdict.block)
+        return 0;
+    err.write(`${BLOCK_MESSAGE(verdict.reason ?? "declared timeout exceeds the harness ceiling")}\n`);
+    return 2;
+}
+//# sourceMappingURL=timeout-guard.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