@indigoai-us/hq-cli 5.98.2 → 5.99.0

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

@@ -0,0 +1,355 @@
+/**
+ * Cross-platform parity replay (US-010).
+ *
+ * The payoff of the declarative fixture format: one case, three executions,
+ * automatic drift detection. Under `--deep-test`, every pure-guard fixture case
+ * is normalised into the Claude, Codex, and Grok payload shapes (payload-shapes.ts)
+ * and replayed through each platform's REAL adapter path, and their verdicts are
+ * compared. Platform drift — a Codex mirror whose logic diverged from its Claude
+ * original — becomes a test result instead of a manual audit.
+ *
+ * The three "real adapter paths", matching how each platform is actually wired:
+ *
+ *   - Claude runs the canonical `.claude/hooks/<id>.sh` through
+ *     `.claude/hooks/hook-gate.sh`, exactly as `.claude/settings.json` registers
+ *     it. A block is a non-zero gate exit.
+ *   - Codex runs its DUPLICATED `.codex/hooks/<id>.sh` mirror through
+ *     `.codex/hooks/hook-gate.sh`, exactly as `.codex/hooks.json` registers it.
+ *     This is the entire drift surface: only Codex runs copies, so a mirror whose
+ *     logic differs is caught precisely here. A block is a non-zero gate exit.
+ *   - Grok drives `.grok/hooks/hq-grok-hook-adapter.sh` with the camelCase
+ *     payload; the adapter maps the Grok tool alias back to canonical and routes
+ *     through the same `.claude/` gate. A block is a stdout `deny` decision
+ *     and/or a non-zero exit (payload-shapes `interpretGrokBlock`).
+ *
+ * Three rules keep the replay honest:
+ *
+ *   1. Disagreement is a FAIL that names every platform's verdict side by side,
+ *      so a reviewer sees `claude=block, codex=allow, grok=block` rather than a
+ *      bare failure.
+ *   2. Grok's passive events (everything but PreToolUse) cannot inject
+ *      model-facing context or emit a decision, so a case on such an event is
+ *      NA — never PASS or FAIL — with the platform limitation named.
+ *   3. A platform whose script/adapter is absent, or whose case timed out, is an
+ *      honest UNKNOWN (never PASS): an exec failure must not be misread as a
+ *      block, and a platform we could not run cannot be declared in agreement.
+ *
+ * Parity replay runs ONLY under `--deep-test`; the command appends it there, not
+ * in the default registry, so a plain `hq doctor` never fires a hook. It reuses
+ * the same pure-guard selection as US-008's executor and its own sandbox, so the
+ * live tree is only ever read from.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { discoverFixtures, registeredHookIds } from "../fixtures/discover.js";
+import { isPureGuard } from "./classify.js";
+import { SANDBOX_COPY_RELPATHS } from "./executor.js";
+import { grokCanBlock, grokToSnakePayload, interpretExitBlock, interpretGrokBlock, PARITY_PLATFORMS, toClaudePayload, toCodexPayload, toGrokPayload, } from "../payload-shapes.js";
+/** The id of the parity family the command appends under `--deep-test`. */
+export const PARITY_FAMILY_ID = "deep-parity";
+/** Human title of the parity family. */
+export const PARITY_FAMILY_TITLE = "Cross-platform parity replay";
+/** Default per-case, per-platform time bound. */
+export const DEFAULT_PARITY_TIMEOUT_MS = 10_000;
+/** The gate profile the replay runs each hook under. Strict is the broadest
+ * allowlist, so profile gating never suppresses the hook whose LOGIC is being
+ * compared across platforms — profile-specific behaviour is US-008's concern. */
+export const PARITY_GATE_PROFILE = "strict";
+/** The session id stamped onto every replay payload. */
+export const PARITY_SESSION_ID = "hq-doctor-parity-replay";
+function spawnWithStdin(command, args, stdin, input) {
+    const result = spawnSync(command, args, {
+        input: stdin,
+        cwd: input.sandbox,
+        timeout: input.timeoutMs,
+        killSignal: "SIGKILL",
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+        env: {
+            ...process.env,
+            HQ_HOOK_PROFILE: PARITY_GATE_PROFILE,
+            CLAUDE_PROJECT_DIR: input.sandbox,
+            HQ_ROOT: input.sandbox,
+        },
+    });
+    const errno = result.error?.code;
+    return {
+        timedOut: errno === "ETIMEDOUT",
+        exitCode: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+/** Run one hook through a platform's own gate + script copy (Claude/Codex). */
+function runThroughGate(input, platformDir, payload) {
+    const gatePath = path.join(input.sandbox, platformDir, "hooks", "hook-gate.sh");
+    const scriptPath = path.join(input.sandbox, platformDir, "hooks", `${input.hookId}.sh`);
+    if (!fs.existsSync(gatePath)) {
+        return unavailable(`${platformDir}/hooks/hook-gate.sh is absent`);
+    }
+    if (!fs.existsSync(scriptPath)) {
+        return unavailable(`${input.platform} has no ${platformDir}/hooks/${input.hookId}.sh to run`);
+    }
+    const spawned = spawnWithStdin("bash", [gatePath, input.hookId, scriptPath], payload, input);
+    return { ...spawned };
+}
+/** The real Claude runner: the canonical script through the Claude gate. */
+export const defaultClaudeRunner = (input) => runThroughGate(input, ".claude", JSON.stringify(toClaudePayload(input.testCase, {
+    cwd: input.sandbox,
+    sessionId: PARITY_SESSION_ID,
+})));
+/** The real Codex runner: the duplicated mirror through the Codex gate. */
+export const defaultCodexRunner = (input) => runThroughGate(input, ".codex", JSON.stringify(toCodexPayload(input.testCase, {
+    cwd: input.sandbox,
+    sessionId: PARITY_SESSION_ID,
+})));
+/**
+ * The real Grok runner. Grok shares the canonical `.claude/hooks/` scripts with
+ * Claude — it has no mirror of its own — and its adapter's whole job is to read
+ * the camelCase payload, map the tool alias back to canonical, build the Claude
+ * JSON, and pipe it to the same `hook-gate.sh`. We reproduce that routing here
+ * (via {@link toGrokPayload} + {@link grokToSnakePayload}) rather than spawn the
+ * adapter directly, for two reasons: the live adapter runs a whole tool
+ * *sequence* where the replay needs one isolated hook, and its user-global
+ * bridge cannot be simulated from a project-local run (US-005 keeps bridge
+ * presence a wiring check). The Grok block protocol still applies — the gate's
+ * non-zero exit is what the adapter would translate into a stdout `deny`
+ * ({@link interpretGrokBlock} in verdictFor recognises both).
+ */
+export const defaultGrokRunner = (input) => {
+    const grokPayload = toGrokPayload(input.testCase, {
+        cwd: input.sandbox,
+        sessionId: PARITY_SESSION_ID,
+    });
+    const snake = grokToSnakePayload(grokPayload);
+    return runThroughGate(input, ".claude", JSON.stringify(snake));
+};
+/** The default real runner set wired to each platform's real adapter path. */
+export const defaultPlatformRunners = {
+    claude: defaultClaudeRunner,
+    codex: defaultCodexRunner,
+    grok: defaultGrokRunner,
+};
+function unavailable(reason) {
+    return { unavailable: { reason }, timedOut: false, exitCode: null, stdout: "", stderr: "" };
+}
+// --- sandbox lifecycle ---------------------------------------------------------
+const trackedParitySandboxes = new Set();
+let parityExitHandlerRegistered = false;
+/** Remove every parity sandbox still on disk. Safe to call repeatedly. */
+export function cleanupAllParitySandboxes() {
+    for (const root of trackedParitySandboxes)
+        removeTree(root);
+    trackedParitySandboxes.clear();
+}
+function ensureParityExitHandler() {
+    if (parityExitHandlerRegistered)
+        return;
+    parityExitHandlerRegistered = true;
+    process.on("exit", cleanupAllParitySandboxes);
+}
+function removeTree(root) {
+    try {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort: cleanup must never mask a real test failure.
+    }
+}
+/**
+ * Copy the curated {@link SANDBOX_COPY_RELPATHS} from the live tree into a fresh
+ * temp root. Replay only reads through the adapters; the live tree is never
+ * written, so one sandbox serves the whole run.
+ */
+function createParitySandbox(hqRoot, relpaths) {
+    ensureParityExitHandler();
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "hq-doctor-parity-")));
+    trackedParitySandboxes.add(root);
+    for (const rel of relpaths) {
+        const segments = rel.split("/");
+        const src = path.join(hqRoot, ...segments);
+        if (!fs.existsSync(src))
+            continue;
+        const dest = path.join(root, ...segments);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.cpSync(src, dest, { recursive: true });
+    }
+    return root;
+}
+// --- entry point ---------------------------------------------------------------
+/**
+ * Replay every pure-guard fixture case through all three platform adapters and
+ * report the per-case parity verdict. 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 replay.
+ */
+export async function runParityReplay(context, options = {}) {
+    const hqRoot = context.hqRoot;
+    const timeoutMs = options.perCaseTimeoutMs ?? DEFAULT_PARITY_TIMEOUT_MS;
+    const runners = {
+        ...defaultPlatformRunners,
+        ...options.runners,
+    };
+    const copyRelpaths = options.sandboxRelpaths ?? SANDBOX_COPY_RELPATHS;
+    const runnable = selectRunnableFixtures(hqRoot);
+    if (runnable.length === 0)
+        return [];
+    const sandbox = createParitySandbox(hqRoot, copyRelpaths);
+    try {
+        const results = [];
+        for (const fixture of runnable) {
+            for (const testCase of fixture.cases) {
+                results.push(replayCase(fixture, testCase, { sandbox, timeoutMs, runners }));
+            }
+        }
+        return results;
+    }
+    finally {
+        if (!options.keepSandbox) {
+            removeTree(sandbox);
+            trackedParitySandboxes.delete(sandbox);
+        }
+    }
+}
+/**
+ * The pure-guard fixtures worth replaying: valid, registered, non-empty, and not
+ * side-effecting (those are US-009's sandboxed effect tier and must never be
+ * fired through an adapter). Mirrors US-008's executor selection so parity
+ * replays exactly the set `--deep-test` executes.
+ */
+function selectRunnableFixtures(hqRoot) {
+    const registered = new Set(registeredHookIds(hqRoot));
+    const discovery = discoverFixtures(hqRoot);
+    const runnable = [];
+    for (const discovered of discovery.fixtures) {
+        if (discovered.parsed.status !== "ok")
+            continue;
+        const fixture = discovered.parsed.fixture;
+        if (!registered.has(fixture.hookId))
+            continue;
+        if (fixture.cases.length === 0)
+            continue;
+        if (!isPureGuard(fixture))
+            continue;
+        runnable.push(fixture);
+    }
+    return runnable;
+}
+/**
+ * Replay one case through all three platforms and classify the aggregate:
+ *   - any platform NA (Grok passive event) -> NA, naming the limitation.
+ *   - any platform error (missing/timeout)  -> UNKNOWN, never PASS.
+ *   - all comparable verdicts agree          -> PASS.
+ *   - they disagree                          -> FAIL, verdicts side by side.
+ */
+function replayCase(fixture, testCase, env) {
+    const target = `${fixture.hookId}:${testCase.name}`;
+    const verdicts = PARITY_PLATFORMS.map((platform) => verdictFor(platform, fixture, testCase, env));
+    const sideBySide = verdicts.map((v) => `${v.platform}=${v.kind}`).join(", ");
+    // Grok passive-event limitation dominates: the case cannot be compared, so it
+    // is NA (never PASS or FAIL), and we name the limitation explicitly.
+    const na = verdicts.find((v) => v.kind === "na");
+    if (na) {
+        return {
+            status: "NA",
+            checkId: "hooks.parity.passive-event",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" runs under the ${testCase.event} event, ` +
+                `which is passive under Grok: the Grok adapter runs it but cannot inject model-facing context ` +
+                `or emit a block decision, so its verdict cannot be compared with Claude and Codex. ` +
+                `Observed: ${describeVerdicts(verdicts)}.`,
+        };
+    }
+    // A platform we could not run (missing script/adapter or timeout) cannot be
+    // declared in agreement — honest UNKNOWN rather than a false PASS.
+    const errors = verdicts.filter((v) => v.kind === "error");
+    if (errors.length > 0) {
+        return {
+            status: "UNKNOWN",
+            checkId: "hooks.parity.unavailable",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" could not be compared across all platforms — ` +
+                `${errors.map((e) => `${e.platform}: ${e.detail}`).join("; ")}. ` +
+                `Observed: ${describeVerdicts(verdicts)}.`,
+            remediation: `Ensure every platform has a runnable copy of "${fixture.hookId}" (Claude gate + hook, ` +
+                `Codex mirror, Grok adapter), then re-run the parity replay.`,
+        };
+    }
+    // Every platform gave a comparable block/allow verdict; compare them.
+    const kinds = new Set(verdicts.map((v) => v.kind));
+    if (kinds.size === 1) {
+        const agreed = verdicts[0].kind;
+        return {
+            status: "PASS",
+            checkId: "hooks.parity.case",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" agreed across all three platforms (${sideBySide}); every adapter ${agreed === "block" ? "blocked" : "allowed"} it.`,
+        };
+    }
+    // Disagreement: the drift this whole story exists to catch. Name each verdict.
+    return {
+        status: "FAIL",
+        checkId: "hooks.parity.case",
+        target,
+        message: `Platform drift on case "${testCase.name}" for "${fixture.hookId}": the three adapters disagree — ${sideBySide}. ` +
+            `${describeVerdicts(verdicts)}.`,
+        remediation: `Reconcile the diverging platform copies of "${fixture.hookId}" so all three adapters produce the same verdict ` +
+            `(most often a Codex mirror in .codex/hooks/ whose logic drifted from the .claude/hooks/ original).`,
+    };
+}
+/** Run one platform and interpret its block protocol into a {@link Verdict}. */
+function verdictFor(platform, fixture, testCase, env) {
+    // Grok cannot emit a decision on a passive event — do not even run it.
+    if (platform === "grok" && !grokCanBlock(testCase.event)) {
+        return {
+            platform,
+            kind: "na",
+            detail: `${testCase.event} is a passive Grok event (no model-facing context injection or block decision)`,
+        };
+    }
+    const output = env.runners[platform]({
+        platform,
+        sandbox: env.sandbox,
+        hookId: fixture.hookId,
+        testCase,
+        timeoutMs: env.timeoutMs,
+    });
+    if (output.unavailable) {
+        return { platform, kind: "error", detail: output.unavailable.reason };
+    }
+    if (output.timedOut) {
+        return {
+            platform,
+            kind: "error",
+            detail: `timed out after ${env.timeoutMs}ms`,
+        };
+    }
+    const blocked = platform === "grok"
+        ? interpretGrokBlock({ exitCode: output.exitCode, stdout: output.stdout })
+        : interpretExitBlock(output.exitCode);
+    return {
+        platform,
+        kind: blocked ? "block" : "allow",
+        detail: describeRun(output),
+    };
+}
+// --- message helpers -----------------------------------------------------------
+function describeRun(output) {
+    const exit = output.exitCode === null ? "none" : String(output.exitCode);
+    const err = output.stderr.trim() ? `, stderr: ${oneLine(output.stderr)}` : "";
+    const dec = output.stdout.trim() ? `, stdout: ${oneLine(output.stdout)}` : "";
+    return `exit ${exit}${dec}${err}`;
+}
+function describeVerdicts(verdicts) {
+    return verdicts
+        .map((v) => `${v.platform} ${v.kind} (${v.detail})`)
+        .join("; ");
+}
+/** Collapse text to a single trimmed, length-capped line for a message. */
+function oneLine(text) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > 160 ? `${collapsed.slice(0, 157)}…` : collapsed;
+}
+//# sourceMappingURL=parity.js.map

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

@@ -0,0 +1,190 @@
+/**
+ * Sandboxed execution for side-effecting hooks (US-009).
+ *
+ * US-008 proves a PURE GUARD works by firing it through the gate and reading the
+ * verdict. That is unsound for a hook that WRITES FILES or MAKES COMMITS: you
+ * cannot fire `hq-autocommit` at the user's real tree to see if it commits. So
+ * every side-effecting hook (classified in classify.ts: autocommit, checkpoint,
+ * journal, reindex, …) runs here instead, inside a THROWAWAY HQ tree, and its
+ * fixture cases assert OBSERVABLE EFFECTS (effects.ts) rather than exit codes.
+ *
+ * Four rules make this trustworthy rather than dangerous:
+ *
+ *   1. Never the live tree. Each case runs in a fresh temp tree seeded with the
+ *      hook scripts, a real git repository, session metadata, and a minimum
+ *      company scaffold. A commit or a file the hook makes lands in the sandbox
+ *      and nowhere the user can see. A fresh sandbox PER CASE keeps one case's
+ *      writes from being mistaken for the next case's effect.
+ *
+ *   2. Always torn down. Every sandbox is tracked and removed in a `finally`, and
+ *      a process-exit handler sweeps any that a crash or interrupt skipped — so
+ *      no temp tree survives, on success, failure, or SIGINT alike.
+ *
+ *   3. A thin sandbox reports UNKNOWN, never FAIL. If a case needs a precondition
+ *      the sandbox did not seed (session metadata, a company, …), it is reported
+ *      UNKNOWN naming that precondition — because a sandbox that manufactures a
+ *      false FAIL for its own gap erodes trust in the doctor faster than no tool.
+ *      A `commit-created` effect implicitly needs a git repo, so a sandbox with
+ *      no git yields UNKNOWN for it, not a false failure.
+ *
+ *   4. One bad setup does not abort the run. If seeding one hook's sandbox
+ *      throws, that hook is reported (UNKNOWN) and the remaining hooks still run.
+ *
+ * The effect data contract and before/after comparison live in effects.ts; this
+ * module owns the filesystem: seeding, discovery of side-effecting fixtures,
+ * running the hook, and turning the evaluation into {@link CheckResult}s.
+ */
+import type { CheckContext, CheckResult } from "../types.js";
+import { type ExpectedFailure } from "../fixtures/schema.js";
+import { type EffectExpectation, type GitProbe } from "./effects.js";
+/** Default per-case time bound. No latency target, but no case may hang. */
+export declare const DEFAULT_PER_CASE_TIMEOUT_MS = 15000;
+/**
+ * The preconditions a sandbox can seed. A fixture case names the ones it needs in
+ * its `requires:` list; anything a case needs that is not in the seeded set makes
+ * the case UNKNOWN (never FAIL). Open to extension as more side-effecting hooks
+ * come under sandboxed execution.
+ */
+export type Precondition = "git-repo" | "session-metadata" | "company-scaffold";
+/** Every precondition the default seeder knows how to provide. */
+export declare const KNOWN_PRECONDITIONS: readonly Precondition[];
+/**
+ * Tree entries copied from the live tree into every sandbox — the same curated
+ * set US-008 uses: the hook scripts and gate, the settings a hook may read, the
+ * Codex/Grok mirrors, and `core/` (helpers hooks source). Missing entries are
+ * skipped so a partial tree still sandboxes cleanly.
+ */
+export declare const SANDBOX_SEED_RELPATHS: readonly string[];
+/** Remove every side-effect sandbox still on disk. Safe to call repeatedly. */
+export declare function cleanupAllSandboxes(): void;
+/** The sandbox roots this process is still tracking (for tests). */
+export declare function trackedSandboxRoots(): string[];
+/** Remove one sandbox and stop tracking it. Idempotent. */
+export declare function destroySandbox(root: string): void;
+/** The outcome of seeding one sandbox. */
+export interface SeedResult {
+    /** Absolute, realpath'd sandbox root under the OS temp dir. */
+    root: string;
+    /** The preconditions actually seeded (a subset of the intended set). */
+    seeded: Set<Precondition>;
+    /** A synthetic session id, seeded when `session-metadata` is provided. */
+    sessionId: string;
+}
+/** Options for {@link seedSandbox}. */
+export interface SeedOptions {
+    /** Tree entries copied from the live tree. Default: {@link SANDBOX_SEED_RELPATHS}. */
+    seedRelpaths?: readonly string[];
+    /** Which preconditions to seed. Default: {@link KNOWN_PRECONDITIONS}. */
+    preconditions?: readonly Precondition[];
+    /** temp-dir name prefix. Default: `hq-doctor-sandbox-`. */
+    prefix?: string;
+}
+/**
+ * Seed a fresh throwaway HQ tree: copy the curated hook scripts, then provide the
+ * requested preconditions. Returns the root and the set of preconditions that
+ * were actually seeded (a precondition that could not be provided — e.g. git is
+ * unavailable — is simply absent from the set, which surfaces as UNKNOWN for any
+ * case needing it, never a false failure).
+ *
+ * On any failure AFTER the temp dir is created, the partial tree is removed and
+ * the error rethrown so a setup failure never leaks a directory.
+ */
+export declare function seedSandbox(hqRoot: string, opts?: SeedOptions): SeedResult;
+/** One hook execution's inputs. */
+export interface HookRunInput {
+    /** Absolute path to the sandboxed hook script. */
+    hookScriptPath: string;
+    /** The JSON payload piped to the hook's stdin. */
+    payload: string;
+    /** Working directory (the sandbox root) the hook runs in. */
+    cwd: string;
+    /** The synthetic session id, exported to the hook's environment. */
+    sessionId: string;
+    /** The per-case time bound in milliseconds. */
+    timeoutMs: number;
+}
+/** One hook execution's observed result (exit code is diagnostic only). */
+export interface HookRunResult {
+    /** True when the execution exceeded {@link HookRunInput.timeoutMs}. */
+    timedOut: boolean;
+    /** Exit code, or null when it did not exit normally (timeout/signal). */
+    exitCode: number | null;
+    /** Captured stderr (empty string when none). */
+    stderr: string;
+}
+/** Runs one hook. Injectable so the tier's aggregation is unit-testable. */
+export type HookRunner = (input: HookRunInput) => HookRunResult;
+/**
+ * The real runner: fire the hook script directly with the payload on stdin, its
+ * cwd and session env pointed at the sandbox, and a hard timeout. Unlike a pure
+ * guard (US-008), a side-effecting hook is run directly rather than through the
+ * gate — its exit code is irrelevant here; what matters is the effect it leaves
+ * on the sandbox, which effects.ts reads afterwards.
+ */
+export declare const defaultHookRunner: HookRunner;
+/** One parsed side-effecting fixture case (its own shape, not the US-007 schema). */
+export interface SideEffectCase {
+    name: string;
+    event: string;
+    tool: string;
+    input: unknown;
+    /** The observable effects the case asserts (non-empty). */
+    effects: EffectExpectation[];
+    /** Preconditions the case needs the sandbox to seed. */
+    requires: string[];
+    /** Present only when the case pins a known, unfixed defect. */
+    expectedFailure?: ExpectedFailure;
+}
+/** A validated side-effecting fixture. */
+export interface SideEffectFixture {
+    hookId: string;
+    relpath: string;
+    cases: SideEffectCase[];
+}
+/** A side-effecting fixture that could not be parsed. */
+export interface SideEffectFixtureError {
+    hookId: string | null;
+    relpath: string;
+    message: string;
+}
+/** The outcome of discovering side-effecting fixtures. */
+export interface SideEffectDiscovery {
+    fixtures: SideEffectFixture[];
+    invalid: SideEffectFixtureError[];
+}
+/**
+ * Discover and parse every side-effecting fixture under `core/hook-tests/`. Only
+ * fixtures whose hook id classifies as side-effecting are returned — pure guards
+ * are US-008's and are ignored here. Malformed side-effecting fixtures are
+ * collected separately so the tier can surface them without aborting.
+ */
+export declare function discoverSideEffectFixtures(hqRoot: string): SideEffectDiscovery;
+/** Options for {@link runSideEffectTests}. All injectable for testing. */
+export interface SideEffectTestOptions {
+    /** Per-case time bound. Default: {@link DEFAULT_PER_CASE_TIMEOUT_MS}. */
+    perCaseTimeoutMs?: number;
+    /** Tree entries copied into each sandbox. Default: {@link SANDBOX_SEED_RELPATHS}. */
+    seedRelpaths?: readonly string[];
+    /** Preconditions the sandbox seeds. Default: {@link KNOWN_PRECONDITIONS}. */
+    preconditions?: readonly Precondition[];
+    /** Hook runner. Default: {@link defaultHookRunner}. */
+    runner?: HookRunner;
+    /** Git probe used for commit-count effects. Default: {@link defaultGitProbe}. */
+    gitProbe?: GitProbe;
+    /**
+     * Sandbox seeder override. Default seeds from `seedRelpaths` / `preconditions`.
+     * Injected in tests to model a seeding failure for one hook (which must not
+     * abort the run).
+     */
+    seeder?: (hqRoot: string, hookId: string) => SeedResult;
+    /** Leave each sandbox on disk (debugging). Default: false — every one is removed. */
+    keepSandbox?: boolean;
+}
+/**
+ * Execute every registered side-effecting hook's fixture cases in per-case
+ * sandboxes and return the effect verdicts. Read-only against the live tree; all
+ * writes and commits happen in throwaway trees that are always torn down.
+ * Returns an empty list when there is nothing side-effecting to run.
+ */
+export declare function runSideEffectTests(context: CheckContext, options?: SideEffectTestOptions): Promise<CheckResult[]>;
+//# sourceMappingURL=sandbox.d.ts.map