@indigoai-us/hq-cli 5.98.3 → 5.99.0

package/dist/lib/doctor/deep/classify.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Classify a hook — via the fixture that guards it — as a PURE GUARD or a
+ * SIDE-EFFECTING hook (US-008).
+ *
+ * `hq doctor --deep-test` proves that a blocking hook actually blocks by firing
+ * it with crafted inputs through the real `hook-gate.sh` path and reading the
+ * verdict. That is only sound for hooks whose entire observable behaviour is a
+ * decision — block, allow, or a stderr pattern — and which produce no filesystem
+ * or git effects when they run. Those are PURE GUARDS, and they are the only
+ * hooks US-008 executes.
+ *
+ * A hook that writes files or makes commits (autocommit, checkpoint, journal,
+ * reindex, …) cannot be verified by exit code and MUST NOT be fired against
+ * anything but a throwaway, effect-asserting sandbox. That is US-009's job, so
+ * this module marks such hooks SIDE-EFFECTING and the executor skips them; the
+ * classification is exported so US-009 can pick exactly those up.
+ *
+ * The current fixture schema (US-007) can only express decision outcomes
+ * (`block` / `allow` / `stderr`), so the operative signal here is the hook id's
+ * family: the four side-effecting families US-009 enumerates are matched by a
+ * marker substring, and everything else is a pure guard. When the schema later
+ * grows effect-based expectations, {@link classifyFixture} is where a fixture
+ * carrying one would additionally be classed side-effecting — the seam is kept
+ * here so the executor never has to know the difference.
+ */
+import type { HookFixture } from "../fixtures/schema.js";
+/** A hook's deep-test class: verifiable by verdict, or effect-bearing. */
+export type HookClass = "pure-guard" | "side-effecting";
+/**
+ * Substrings that mark a hook id as belonging to a side-effecting family. This
+ * is the seed set US-009 names — autocommit, checkpoint, journal, reindex — and
+ * is deliberately matched as a case-insensitive substring so every member of a
+ * family is caught (`hq-autocommit`, `auto-checkpoint-precompact`,
+ * `journal-due`, …) without enumerating each id. US-009 extends this list as it
+ * brings more side-effecting hooks under sandboxed execution.
+ */
+export declare const SIDE_EFFECTING_ID_MARKERS: readonly string[];
+/** A classification verdict together with the reason behind it. */
+export interface Classification {
+    /** Whether the hook is a pure guard or side-effecting. */
+    hookClass: HookClass;
+    /** Human-readable reason, for messages and debugging. */
+    reason: string;
+}
+/**
+ * Classify a bare hook id. Side-effecting when the id contains one of
+ * {@link SIDE_EFFECTING_ID_MARKERS} (case-insensitive), pure guard otherwise.
+ */
+export declare function classifyHookId(hookId: string): Classification;
+/**
+ * Classify the hook a fixture guards. Currently a function of the hook id alone
+ * (see the module comment); the fixture is taken by value so a future
+ * effect-based expectation can be folded into the verdict here without changing
+ * any caller.
+ */
+export declare function classifyFixture(fixture: HookFixture): Classification;
+/** Whether a fixture's hook is a pure guard — the ones `--deep-test` executes. */
+export declare function isPureGuard(fixture: HookFixture): boolean;
+/** Whether a hook id names a side-effecting hook (US-009's execution surface). */
+export declare function isSideEffectingHookId(hookId: string): boolean;
+//# sourceMappingURL=classify.d.ts.map

package/dist/lib/doctor/deep/classify.js

@@ -0,0 +1,75 @@
+/**
+ * Classify a hook — via the fixture that guards it — as a PURE GUARD or a
+ * SIDE-EFFECTING hook (US-008).
+ *
+ * `hq doctor --deep-test` proves that a blocking hook actually blocks by firing
+ * it with crafted inputs through the real `hook-gate.sh` path and reading the
+ * verdict. That is only sound for hooks whose entire observable behaviour is a
+ * decision — block, allow, or a stderr pattern — and which produce no filesystem
+ * or git effects when they run. Those are PURE GUARDS, and they are the only
+ * hooks US-008 executes.
+ *
+ * A hook that writes files or makes commits (autocommit, checkpoint, journal,
+ * reindex, …) cannot be verified by exit code and MUST NOT be fired against
+ * anything but a throwaway, effect-asserting sandbox. That is US-009's job, so
+ * this module marks such hooks SIDE-EFFECTING and the executor skips them; the
+ * classification is exported so US-009 can pick exactly those up.
+ *
+ * The current fixture schema (US-007) can only express decision outcomes
+ * (`block` / `allow` / `stderr`), so the operative signal here is the hook id's
+ * family: the four side-effecting families US-009 enumerates are matched by a
+ * marker substring, and everything else is a pure guard. When the schema later
+ * grows effect-based expectations, {@link classifyFixture} is where a fixture
+ * carrying one would additionally be classed side-effecting — the seam is kept
+ * here so the executor never has to know the difference.
+ */
+/**
+ * Substrings that mark a hook id as belonging to a side-effecting family. This
+ * is the seed set US-009 names — autocommit, checkpoint, journal, reindex — and
+ * is deliberately matched as a case-insensitive substring so every member of a
+ * family is caught (`hq-autocommit`, `auto-checkpoint-precompact`,
+ * `journal-due`, …) without enumerating each id. US-009 extends this list as it
+ * brings more side-effecting hooks under sandboxed execution.
+ */
+export const SIDE_EFFECTING_ID_MARKERS = [
+    "autocommit",
+    "checkpoint",
+    "journal",
+    "reindex",
+];
+/**
+ * Classify a bare hook id. Side-effecting when the id contains one of
+ * {@link SIDE_EFFECTING_ID_MARKERS} (case-insensitive), pure guard otherwise.
+ */
+export function classifyHookId(hookId) {
+    const lower = hookId.toLowerCase();
+    const marker = SIDE_EFFECTING_ID_MARKERS.find((m) => lower.includes(m));
+    if (marker) {
+        return {
+            hookClass: "side-effecting",
+            reason: `hook id "${hookId}" matches the side-effecting family marker "${marker}"; deep execution is deferred to the sandboxed effect tier`,
+        };
+    }
+    return {
+        hookClass: "pure-guard",
+        reason: `hook id "${hookId}" is a decision-only guard with no known filesystem or git side effects`,
+    };
+}
+/**
+ * Classify the hook a fixture guards. Currently a function of the hook id alone
+ * (see the module comment); the fixture is taken by value so a future
+ * effect-based expectation can be folded into the verdict here without changing
+ * any caller.
+ */
+export function classifyFixture(fixture) {
+    return classifyHookId(fixture.hookId);
+}
+/** Whether a fixture's hook is a pure guard — the ones `--deep-test` executes. */
+export function isPureGuard(fixture) {
+    return classifyFixture(fixture).hookClass === "pure-guard";
+}
+/** Whether a hook id names a side-effecting hook (US-009's execution surface). */
+export function isSideEffectingHookId(hookId) {
+    return classifyHookId(hookId).hookClass === "side-effecting";
+}
+//# sourceMappingURL=classify.js.map

package/dist/lib/doctor/deep/effects.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Observable-effect expectations for side-effecting hooks (US-009).
+ *
+ * A pure guard (US-008) is fully described by a decision — block, allow, or a
+ * stderr pattern — so its fixture cases assert exit-code outcomes. A hook that
+ * WRITES FILES or MAKES COMMITS (autocommit, checkpoint, journal, reindex, …)
+ * cannot be verified that way: a `git commit` hook that exits 0 tells you
+ * nothing about whether a commit was actually made. So its fixture cases assert
+ * OBSERVABLE EFFECTS instead — this module owns that data contract and the
+ * before/after evaluation that decides whether an effect happened.
+ *
+ * The three effect kinds the PRD names, and nothing more (the schema grows
+ * deliberately, one kind at a time):
+ *
+ *   - `fileCreated: <path>`     — a file appeared at <path> that was not there
+ *                                 before the hook ran.
+ *   - `commitCreated`           — the sandbox git repo has more commits after the
+ *                                 hook than before.
+ *   - `fileUnmodified: <path>`  — a named file's bytes are identical before and
+ *                                 after (the negative assertion: the hook did NOT
+ *                                 touch something it must leave alone).
+ *
+ * Evaluation is a strict before/after diff so it cannot be fooled by a file that
+ * merely already existed: {@link captureEffectBaseline} snapshots exactly what
+ * each expectation needs (git commit count, file existence, file hashes) BEFORE
+ * the hook runs, and {@link evaluateEffects} compares against the same paths
+ * afterwards. All git access goes through an injectable {@link GitProbe} so the
+ * evaluation is unit-testable and a non-git sandbox degrades to a null count
+ * rather than throwing.
+ *
+ * This module is pure data + comparison; the sandbox that seeds the tree and
+ * runs the hook is sandbox.ts. It reuses only type-level helpers from the
+ * fixture schema (US-007) and never mutates anything but is handed paths to read.
+ */
+/**
+ * A single observable effect a side-effecting hook's case expects. Exactly one
+ * of the three kinds the PRD enumerates.
+ */
+export type EffectExpectation = {
+    kind: "file-created";
+    path: string;
+} | {
+    kind: "commit-created";
+} | {
+    kind: "file-unmodified";
+    path: string;
+};
+/**
+ * Parse a fixture case's `effects:` field into a list of {@link
+ * EffectExpectation}. Returns the list, or an error string naming what was
+ * wrong (never throws). A side-effecting case MUST declare at least one effect —
+ * an empty or absent list is an error, because a case that asserts no effect
+ * proves nothing.
+ *
+ * Accepted YAML shapes per entry (each entry names exactly one effect):
+ *   - `{ fileCreated: "<path>" }`
+ *   - `{ commitCreated: true }`  (any truthy value, or the bare string
+ *     `"commitCreated"`)
+ *   - `{ fileUnmodified: "<path>" }`
+ */
+export declare function parseEffectExpectations(raw: unknown): EffectExpectation[] | string;
+/** Human phrase for an effect, used in result messages. */
+export declare function describeEffect(effect: EffectExpectation): string;
+/**
+ * The minimal git surface the effect evaluation needs. Injectable so the
+ * comparison logic is unit-testable without a real repo, and so a non-git
+ * sandbox returns `null` (an honest "cannot tell") rather than throwing.
+ */
+export interface GitProbe {
+    /** Number of commits reachable from HEAD, or null when there is no repo/HEAD. */
+    commitCount(root: string): number | null;
+}
+/** The real probe: `git rev-list --count HEAD` in `root`. */
+export declare const defaultGitProbe: GitProbe;
+/**
+ * A snapshot of exactly the state the declared effects need to compare against,
+ * taken BEFORE the hook runs. Everything is captured up front so the evaluation
+ * is a pure diff and cannot be fooled by pre-existing state.
+ */
+export interface EffectBaseline {
+    /** Commits reachable from HEAD before the run, or null when not a git repo. */
+    commitCount: number | null;
+    /** Per `file-created` path: did it exist before the run. */
+    existedBefore: Map<string, boolean>;
+    /** Per `file-unmodified` path: its content hash before the run (null if absent). */
+    hashBefore: Map<string, string | null>;
+}
+/**
+ * Snapshot the tree state the given expectations will be compared against. Reads
+ * only; touches nothing.
+ */
+export declare function captureEffectBaseline(root: string, expectations: readonly EffectExpectation[], git?: GitProbe): EffectBaseline;
+/** The outcome of checking one expectation against the post-run tree. */
+export interface EffectEvaluation {
+    /** The expectation that was checked. */
+    expectation: EffectExpectation;
+    /** Whether the observed after-state satisfied the expectation. */
+    met: boolean;
+    /** Human detail of what was observed, for result messages. */
+    detail: string;
+}
+/**
+ * Compare the post-run tree against the baseline for every expectation. Pure and
+ * read-only; the returned list is in the same order as `expectations`.
+ */
+export declare function evaluateEffects(root: string, expectations: readonly EffectExpectation[], baseline: EffectBaseline, git?: GitProbe): EffectEvaluation[];
+//# sourceMappingURL=effects.d.ts.map

package/dist/lib/doctor/deep/effects.js

@@ -0,0 +1,229 @@
+/**
+ * Observable-effect expectations for side-effecting hooks (US-009).
+ *
+ * A pure guard (US-008) is fully described by a decision — block, allow, or a
+ * stderr pattern — so its fixture cases assert exit-code outcomes. A hook that
+ * WRITES FILES or MAKES COMMITS (autocommit, checkpoint, journal, reindex, …)
+ * cannot be verified that way: a `git commit` hook that exits 0 tells you
+ * nothing about whether a commit was actually made. So its fixture cases assert
+ * OBSERVABLE EFFECTS instead — this module owns that data contract and the
+ * before/after evaluation that decides whether an effect happened.
+ *
+ * The three effect kinds the PRD names, and nothing more (the schema grows
+ * deliberately, one kind at a time):
+ *
+ *   - `fileCreated: <path>`     — a file appeared at <path> that was not there
+ *                                 before the hook ran.
+ *   - `commitCreated`           — the sandbox git repo has more commits after the
+ *                                 hook than before.
+ *   - `fileUnmodified: <path>`  — a named file's bytes are identical before and
+ *                                 after (the negative assertion: the hook did NOT
+ *                                 touch something it must leave alone).
+ *
+ * Evaluation is a strict before/after diff so it cannot be fooled by a file that
+ * merely already existed: {@link captureEffectBaseline} snapshots exactly what
+ * each expectation needs (git commit count, file existence, file hashes) BEFORE
+ * the hook runs, and {@link evaluateEffects} compares against the same paths
+ * afterwards. All git access goes through an injectable {@link GitProbe} so the
+ * evaluation is unit-testable and a non-git sandbox degrades to a null count
+ * rather than throwing.
+ *
+ * This module is pure data + comparison; the sandbox that seeds the tree and
+ * runs the hook is sandbox.ts. It reuses only type-level helpers from the
+ * fixture schema (US-007) and never mutates anything but is handed paths to read.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Parse a fixture case's `effects:` field into a list of {@link
+ * EffectExpectation}. Returns the list, or an error string naming what was
+ * wrong (never throws). A side-effecting case MUST declare at least one effect —
+ * an empty or absent list is an error, because a case that asserts no effect
+ * proves nothing.
+ *
+ * Accepted YAML shapes per entry (each entry names exactly one effect):
+ *   - `{ fileCreated: "<path>" }`
+ *   - `{ commitCreated: true }`  (any truthy value, or the bare string
+ *     `"commitCreated"`)
+ *   - `{ fileUnmodified: "<path>" }`
+ */
+export function parseEffectExpectations(raw) {
+    if (!Array.isArray(raw)) {
+        return "`effects` must be a non-empty list of effect expectations";
+    }
+    if (raw.length === 0) {
+        return "`effects` is empty; a side-effecting case must assert at least one observable effect";
+    }
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const parsed = parseOneEffect(raw[i], i);
+        if (typeof parsed === "string")
+            return parsed;
+        out.push(parsed);
+    }
+    return out;
+}
+function parseOneEffect(raw, index) {
+    const where = `effect #${index + 1}`;
+    // Bare-string forms: only the no-argument `commitCreated` supports it.
+    if (raw === "commitCreated")
+        return { kind: "commit-created" };
+    if (!isRecord(raw)) {
+        return `${where} must be a mapping such as { fileCreated: <path> }, { commitCreated: true }, or { fileUnmodified: <path> }`;
+    }
+    if ("fileCreated" in raw) {
+        const p = raw.fileCreated;
+        if (typeof p !== "string" || p.trim() === "") {
+            return `${where}: fileCreated must be a non-empty path string`;
+        }
+        return { kind: "file-created", path: p };
+    }
+    if ("fileUnmodified" in raw) {
+        const p = raw.fileUnmodified;
+        if (typeof p !== "string" || p.trim() === "") {
+            return `${where}: fileUnmodified must be a non-empty path string`;
+        }
+        return { kind: "file-unmodified", path: p };
+    }
+    if ("commitCreated" in raw) {
+        // Any truthy value means "expect a commit"; a false value is a no-op that
+        // would assert nothing, so it is rejected rather than silently dropped.
+        if (raw.commitCreated)
+            return { kind: "commit-created" };
+        return `${where}: commitCreated must be true (drop the entry to assert nothing)`;
+    }
+    return `${where} names no known effect (expected fileCreated, commitCreated, or fileUnmodified)`;
+}
+/** Human phrase for an effect, used in result messages. */
+export function describeEffect(effect) {
+    switch (effect.kind) {
+        case "file-created":
+            return `a file created at ${effect.path}`;
+        case "commit-created":
+            return "a git commit created";
+        case "file-unmodified":
+            return `${effect.path} left unmodified`;
+    }
+}
+/** The real probe: `git rev-list --count HEAD` in `root`. */
+export const defaultGitProbe = {
+    commitCount(root) {
+        const res = spawnSync("git", ["rev-list", "--count", "HEAD"], {
+            cwd: root,
+            encoding: "utf8",
+        });
+        if (res.status !== 0)
+            return null;
+        const n = Number.parseInt((res.stdout ?? "").trim(), 10);
+        return Number.isFinite(n) ? n : null;
+    },
+};
+/**
+ * Snapshot the tree state the given expectations will be compared against. Reads
+ * only; touches nothing.
+ */
+export function captureEffectBaseline(root, expectations, git = defaultGitProbe) {
+    const existedBefore = new Map();
+    const hashBefore = new Map();
+    let needsCommitCount = false;
+    for (const effect of expectations) {
+        switch (effect.kind) {
+            case "file-created":
+                existedBefore.set(effect.path, fs.existsSync(path.join(root, effect.path)));
+                break;
+            case "file-unmodified":
+                hashBefore.set(effect.path, hashFile(path.join(root, effect.path)));
+                break;
+            case "commit-created":
+                needsCommitCount = true;
+                break;
+        }
+    }
+    return {
+        commitCount: needsCommitCount ? git.commitCount(root) : null,
+        existedBefore,
+        hashBefore,
+    };
+}
+/**
+ * Compare the post-run tree against the baseline for every expectation. Pure and
+ * read-only; the returned list is in the same order as `expectations`.
+ */
+export function evaluateEffects(root, expectations, baseline, git = defaultGitProbe) {
+    return expectations.map((expectation) => evaluateOne(root, expectation, baseline, git));
+}
+function evaluateOne(root, expectation, baseline, git) {
+    switch (expectation.kind) {
+        case "file-created": {
+            const abs = path.join(root, expectation.path);
+            const existedBefore = baseline.existedBefore.get(expectation.path) ?? false;
+            const existsAfter = fs.existsSync(abs);
+            if (existedBefore) {
+                return {
+                    expectation,
+                    met: false,
+                    detail: `${expectation.path} already existed before the run, so its presence is not a created effect`,
+                };
+            }
+            return {
+                expectation,
+                met: existsAfter,
+                detail: existsAfter
+                    ? `${expectation.path} was created`
+                    : `${expectation.path} does not exist after the run`,
+            };
+        }
+        case "file-unmodified": {
+            const abs = path.join(root, expectation.path);
+            const before = baseline.hashBefore.get(expectation.path) ?? null;
+            const after = hashFile(abs);
+            const unchanged = before === after;
+            return {
+                expectation,
+                met: unchanged,
+                detail: unchanged
+                    ? `${expectation.path} was left unmodified`
+                    : before === null
+                        ? `${expectation.path} was created by the run but was expected to be untouched`
+                        : after === null
+                            ? `${expectation.path} was deleted by the run but was expected to be untouched`
+                            : `${expectation.path} was modified by the run`,
+            };
+        }
+        case "commit-created": {
+            const after = git.commitCount(root);
+            const before = baseline.commitCount;
+            if (before === null || after === null) {
+                return {
+                    expectation,
+                    met: false,
+                    detail: "commit count could not be read (the sandbox is not a git repository)",
+                };
+            }
+            const made = after - before;
+            return {
+                expectation,
+                met: made > 0,
+                detail: made > 0
+                    ? `${made} commit${made === 1 ? "" : "s"} were created`
+                    : "no new commit was created",
+            };
+        }
+    }
+}
+// --- low-level helpers ---------------------------------------------------------
+/** sha256 of a file's bytes, or null when the file is absent / unreadable. */
+function hashFile(abs) {
+    try {
+        return createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=effects.js.map

package/dist/lib/doctor/deep/executor.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `--deep-test` execution for pure guard hooks (US-008).
+ *
+ * Default `hq doctor` proves a hook is *wired*. Deep test proves it *works*: for
+ * every pure-guard fixture (US-007 schema, {@link isPureGuard} classification)
+ * it replays each case through the REAL `hook-gate.sh` and checks the verdict
+ * against the fixture's expectation. Four rules make this trustworthy rather
+ * than theatre:
+ *
+ *   1. Route through the gate, never the hook directly. A hook can pass direct
+ *      invocation and still silently no-op under the active gate profile — the
+ *      documented `block-hq-root-git-mutation` incident did exactly that. So
+ *      each case runs `hook-gate.sh <id> <script>` with a payload on stdin, and
+ *      under ALL THREE profiles (minimal, standard, strict). A profile whose
+ *      outcome differs from the expectation is a FAIL naming that profile: an
+ *      expected block that no-ops to exit 0 under standard is caught here and
+ *      nowhere else.
+ *
+ *   2. Sandbox, never the live tree. The gate and hooks are copied into a
+ *      throwaway temp tree and every case executes there, so a diagnosis can
+ *      never mutate the user's real setup. A test asserts the live tree is
+ *      byte-identical before and after a run.
+ *
+ *   3. Time-bound every case. A hook that hangs must fail its case, not the
+ *      command — each execution is spawned with a per-case timeout and a
+ *      timeout is reported as FAIL, never left to block the run.
+ *
+ *   4. Never fire a hook in default mode. This module runs only when the caller
+ *      asks for it (the command wires it behind `--deep-test`); the default
+ *      registry does not include it. A test asserts no hook process is spawned
+ *      without the flag.
+ *
+ * Expectation matching and the `expectedFailure` rule are owned by
+ * {@link outcomeMatches} / {@link classifyCaseStatus} in the fixture schema, so
+ * a case outcome means the same thing here as in the coverage tier. The Claude
+ * block protocol (a non-zero gate exit is a block) is the only one this story
+ * handles; Grok's stdout-`deny` protocol is US-010's parity replay.
+ */
+import type { CheckContext, CheckResult } from "../types.js";
+import { type GateProfile } from "../hook-gate-profiles.js";
+/** The id of the deep-test family the command appends under `--deep-test`. */
+export declare const DEEP_FAMILY_ID = "deep";
+/** Human title of the deep-test family. */
+export declare const DEEP_FAMILY_TITLE = "Deep guard-hook tests";
+/** Default per-case time bound. Deep test has no latency target, but no case
+ * may hang the command, so every execution is capped. */
+export declare const DEFAULT_PER_CASE_TIMEOUT_MS = 10000;
+/**
+ * The tree entries copied into the sandbox. Deliberately a curated set, not the
+ * whole tree: the live `.claude/` carries worktrees and session state that can
+ * run to hundreds of megabytes, whereas the gate only needs the hook scripts,
+ * the settings a hook might read, the Codex/Grok mirrors, and `core/` (where the
+ * gate finds `hook-lib.sh` and hooks find their helpers). Missing entries are
+ * skipped, so a partial tree still sandboxes cleanly.
+ */
+export declare const SANDBOX_COPY_RELPATHS: readonly string[];
+/** One gate execution's inputs. */
+export interface GateRunInput {
+    /** Absolute path to the sandboxed `hook-gate.sh`. */
+    gatePath: string;
+    /** Absolute path to the sandboxed hook script the gate delegates to. */
+    hookScriptPath: string;
+    /** The gated hook id (the gate's first argument). */
+    hookId: string;
+    /** The gate profile to run under, via `HQ_HOOK_PROFILE`. */
+    profile: GateProfile;
+    /** The JSON payload piped to the gate's stdin. */
+    payload: string;
+    /** Working directory (the sandbox root) the gate runs in. */
+    cwd: string;
+    /** The per-case time bound in milliseconds. */
+    timeoutMs: number;
+}
+/** One gate execution's observed outcome. */
+export interface GateRunResult {
+    /** True when the execution exceeded {@link GateRunInput.timeoutMs}. */
+    timedOut: boolean;
+    /** Gate exit code, or null when it did not exit normally (timeout/signal). */
+    exitCode: number | null;
+    /** Captured stderr (empty string when none). */
+    stderr: string;
+}
+/** Executes one gate invocation. Injectable so the aggregation is unit-testable. */
+export type GateRunner = (input: GateRunInput) => GateRunResult;
+/**
+ * The real runner: spawn `bash hook-gate.sh <id> <script>` with the payload on
+ * stdin, `HQ_HOOK_PROFILE` set, and a hard timeout. A timeout is detected by the
+ * `ETIMEDOUT` error code spawnSync reports; the process is killed with SIGKILL so
+ * a hook cannot ignore the bound.
+ */
+export declare const defaultGateRunner: GateRunner;
+/** Options for {@link runDeepGuardTests}. All are injectable for testing. */
+export interface DeepTestOptions {
+    /** Per-case time bound. Default: {@link DEFAULT_PER_CASE_TIMEOUT_MS}. */
+    perCaseTimeoutMs?: number;
+    /** Tree entries copied into the sandbox. Default: {@link SANDBOX_COPY_RELPATHS}. */
+    sandboxRelpaths?: readonly string[];
+    /** Gate runner. Default: {@link defaultGateRunner}. */
+    runner?: GateRunner;
+    /** Leave the sandbox on disk (debugging). Default: false — it is removed. */
+    keepSandbox?: boolean;
+}
+/** Remove every sandbox still on disk. Safe to call repeatedly. */
+export declare function cleanupAllDeepSandboxes(): void;
+/**
+ * Execute every pure-guard fixture's cases through the real gate under all three
+ * profiles and return the per-case results. Read-only against the live tree;
+ * all execution happens in a sandbox that is removed before returning. Returns
+ * an empty list — creating no sandbox — when there is nothing to run.
+ */
+export declare function runDeepGuardTests(context: CheckContext, options?: DeepTestOptions): Promise<CheckResult[]>;
+//# sourceMappingURL=executor.d.ts.map