@indigoai-us/hq-cli 5.98.2 → 5.99.0

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

@@ -0,0 +1,572 @@
+/**
+ * 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 { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { classifyCaseStatus, looksLikeFixture, } from "../fixtures/schema.js";
+import { HOOK_TESTS_RELDIR, registeredHookIds } from "../fixtures/discover.js";
+import { isSideEffectingHookId } from "./classify.js";
+import { captureEffectBaseline, describeEffect, defaultGitProbe, evaluateEffects, parseEffectExpectations, } from "./effects.js";
+/** Default per-case time bound. No latency target, but no case may hang. */
+export const DEFAULT_PER_CASE_TIMEOUT_MS = 15_000;
+/** Every precondition the default seeder knows how to provide. */
+export const KNOWN_PRECONDITIONS = [
+    "git-repo",
+    "session-metadata",
+    "company-scaffold",
+];
+/**
+ * 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 const SANDBOX_SEED_RELPATHS = [
+    ".claude/hooks",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".codex/hooks",
+    ".codex/hooks.json",
+    ".grok",
+    "core",
+];
+/** A slug for the throwaway company the `company-scaffold` precondition seeds. */
+const SANDBOX_COMPANY_SLUG = "sandbox-co";
+/** `*.yaml` files under core/hook-tests that are configuration, not fixtures. */
+const NON_FIXTURE_FILES = new Set(["allowed-divergence.yaml"]);
+// --- sandbox lifecycle --------------------------------------------------------
+const trackedSandboxes = new Set();
+let sandboxExitHandlerRegistered = false;
+/** Remove every side-effect sandbox still on disk. Safe to call repeatedly. */
+export function cleanupAllSandboxes() {
+    for (const root of trackedSandboxes)
+        removeTree(root);
+    trackedSandboxes.clear();
+}
+/** The sandbox roots this process is still tracking (for tests). */
+export function trackedSandboxRoots() {
+    return [...trackedSandboxes];
+}
+function ensureSandboxExitHandler() {
+    if (sandboxExitHandlerRegistered)
+        return;
+    sandboxExitHandlerRegistered = true;
+    // Fires on normal exit and after a crash/interrupt alike — the guarantee that
+    // no sandbox survives even when a case throws or the process is torn down.
+    process.on("exit", cleanupAllSandboxes);
+}
+function removeTree(root) {
+    try {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort: cleanup must never mask a test's real failure.
+    }
+}
+/** Remove one sandbox and stop tracking it. Idempotent. */
+export function destroySandbox(root) {
+    removeTree(root);
+    trackedSandboxes.delete(root);
+}
+/**
+ * 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 function seedSandbox(hqRoot, opts = {}) {
+    ensureSandboxExitHandler();
+    const relpaths = opts.seedRelpaths ?? SANDBOX_SEED_RELPATHS;
+    const intended = new Set(opts.preconditions ?? KNOWN_PRECONDITIONS);
+    const prefix = opts.prefix ?? "hq-doctor-sandbox-";
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+    trackedSandboxes.add(root);
+    try {
+        copyTreeEntries(hqRoot, root, relpaths);
+        const seeded = new Set();
+        const sessionId = `hq-doctor-sandbox-${path.basename(root)}`;
+        if (intended.has("session-metadata")) {
+            seedSessionMetadata(root, sessionId);
+            seeded.add("session-metadata");
+        }
+        if (intended.has("company-scaffold")) {
+            seedCompanyScaffold(root);
+            seeded.add("company-scaffold");
+        }
+        // git LAST, so the initial commit captures everything else that was seeded.
+        if (intended.has("git-repo") && seedGitRepo(root)) {
+            seeded.add("git-repo");
+        }
+        return { root, seeded, sessionId };
+    }
+    catch (error) {
+        destroySandbox(root);
+        throw error;
+    }
+}
+function copyTreeEntries(hqRoot, root, relpaths) {
+    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 });
+        // cpSync preserves mode bits, so hooks and the gate stay executable.
+        fs.cpSync(src, dest, { recursive: true });
+    }
+}
+function seedSessionMetadata(root, sessionId) {
+    // The on-disk shape a session-aware hook expects: a state dir plus a workspace
+    // scaffold. The session id itself is carried in the payload and the run env.
+    fs.mkdirSync(path.join(root, ".claude", "state"), { recursive: true });
+    fs.mkdirSync(path.join(root, "workspace", "threads"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".claude", "state", `session-${sessionId}`), `${sessionId}\n`);
+}
+function seedCompanyScaffold(root) {
+    const companiesDir = path.join(root, "companies");
+    fs.mkdirSync(path.join(companiesDir, SANDBOX_COMPANY_SLUG), { recursive: true });
+    fs.writeFileSync(path.join(companiesDir, "manifest.yaml"), `companies:\n  - slug: ${SANDBOX_COMPANY_SLUG}\n    name: Sandbox Co\n`);
+}
+/**
+ * Initialise a git repo with a single baseline commit, so a hook that commits
+ * advances the count from a known 1. Returns false (git-repo not seeded) when git
+ * is unavailable or a step fails, rather than throwing — an absent repo surfaces
+ * as UNKNOWN for a commit case, not a false failure.
+ */
+function seedGitRepo(root) {
+    if (git(root, ["init", "-q", "-b", "main"]) !== 0)
+        return false;
+    // Identity straight into .git/config, matching the reference harness — no
+    // dependency on the runner's global git config.
+    fs.appendFileSync(path.join(root, ".git", "config"), "[user]\n\temail = hq-doctor-sandbox@example.com\n\tname = hq-doctor-sandbox\n" +
+        "[commit]\n\tgpgsign = false\n");
+    // Guarantee there is always something to commit, even with an empty seed set.
+    fs.writeFileSync(path.join(root, ".hq-sandbox-baseline"), "seeded\n");
+    if (git(root, ["add", "-A"]) !== 0)
+        return false;
+    return git(root, ["commit", "-q", "-m", "sandbox baseline"]) === 0;
+}
+function git(root, args) {
+    const res = spawnSync("git", args, { cwd: root, encoding: "utf8" });
+    return res.status;
+}
+/**
+ * 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 const defaultHookRunner = (input) => {
+    const result = spawnSync("bash", [input.hookScriptPath], {
+        input: input.payload,
+        cwd: input.cwd,
+        timeout: input.timeoutMs,
+        killSignal: "SIGKILL",
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+        env: {
+            ...process.env,
+            CLAUDE_PROJECT_DIR: input.cwd,
+            HQ_ROOT: input.cwd,
+            CLAUDE_SESSION_ID: input.sessionId,
+            HQ_SESSION_ID: input.sessionId,
+        },
+    });
+    const errno = result.error?.code;
+    return {
+        timedOut: errno === "ETIMEDOUT",
+        exitCode: result.status,
+        stderr: result.stderr ?? "",
+    };
+};
+/**
+ * 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 function discoverSideEffectFixtures(hqRoot) {
+    const dir = path.join(hqRoot, HOOK_TESTS_RELDIR);
+    const fixtures = [];
+    const invalid = [];
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return { fixtures, invalid };
+    }
+    for (const name of names.sort()) {
+        if (!/\.ya?ml$/i.test(name))
+            continue;
+        if (NON_FIXTURE_FILES.has(name))
+            continue;
+        const relpath = path.join(HOOK_TESTS_RELDIR, name);
+        const defaultHookId = name.replace(/\.ya?ml$/i, "");
+        let doc;
+        try {
+            doc = yaml.load(fs.readFileSync(path.join(dir, name), "utf8"));
+        }
+        catch (error) {
+            // A YAML syntax error is only ours to report if the file is meant to be a
+            // side-effecting fixture — which we cannot tell without parsing it. The
+            // stem is the best hint; if it names a side-effecting hook, flag it.
+            if (isSideEffectingHookId(defaultHookId)) {
+                invalid.push({
+                    hookId: defaultHookId,
+                    relpath,
+                    message: `not valid YAML: ${error.message}`,
+                });
+            }
+            continue;
+        }
+        if (!looksLikeFixture(doc))
+            continue;
+        const hookId = resolveHookId(doc, defaultHookId);
+        if (!isSideEffectingHookId(hookId))
+            continue;
+        const parsed = parseSideEffectCases(doc);
+        if (typeof parsed === "string") {
+            invalid.push({ hookId, relpath, message: parsed });
+            continue;
+        }
+        fixtures.push({ hookId, relpath, cases: parsed });
+    }
+    return { fixtures, invalid };
+}
+function resolveHookId(doc, defaultHookId) {
+    if (isRecord(doc)) {
+        const declared = doc.hookId;
+        if (typeof declared === "string" && declared.trim() !== "")
+            return declared;
+    }
+    return defaultHookId;
+}
+/** Parse a fixture doc's `cases` into side-effect cases, or an error string. */
+function parseSideEffectCases(doc) {
+    if (!isRecord(doc))
+        return "fixture is not a mapping";
+    if (!("cases" in doc) || !Array.isArray(doc.cases)) {
+        return "fixture `cases` must be a list";
+    }
+    const cases = [];
+    const seen = new Set();
+    for (let i = 0; i < doc.cases.length; i++) {
+        const parsed = parseSideEffectCase(doc.cases[i], i);
+        if (typeof parsed === "string")
+            return parsed;
+        if (seen.has(parsed.name))
+            return `duplicate case name "${parsed.name}"`;
+        seen.add(parsed.name);
+        cases.push(parsed);
+    }
+    return cases;
+}
+function parseSideEffectCase(raw, index) {
+    const where = `case #${index + 1}`;
+    if (!isRecord(raw))
+        return `${where} is not a mapping`;
+    const name = raw.name;
+    if (typeof name !== "string" || name.trim() === "") {
+        return `${where} is missing a non-empty \`name\``;
+    }
+    const label = `case "${name}"`;
+    const event = raw.event;
+    if (typeof event !== "string" || event.trim() === "") {
+        return `${label} is missing a non-empty \`event\``;
+    }
+    const tool = raw.tool;
+    if (typeof tool !== "string" || tool.trim() === "") {
+        return `${label} is missing a non-empty \`tool\``;
+    }
+    if (!("input" in raw))
+        return `${label} is missing a tool \`input\` payload`;
+    if (!("effects" in raw)) {
+        return `${label} is missing an \`effects\` list (a side-effecting case asserts effects, not exit codes)`;
+    }
+    const effects = parseEffectExpectations(raw.effects);
+    if (typeof effects === "string")
+        return `${label}: ${effects}`;
+    const requires = parseRequires(raw.requires);
+    if (typeof requires === "string")
+        return `${label}: ${requires}`;
+    const expectedFailure = parseExpectedFailure(raw.expectedFailure);
+    if (typeof expectedFailure === "string")
+        return `${label}: ${expectedFailure}`;
+    const parsedCase = {
+        name,
+        event,
+        tool,
+        input: raw.input,
+        effects,
+        requires,
+    };
+    if (expectedFailure)
+        parsedCase.expectedFailure = expectedFailure;
+    return parsedCase;
+}
+function parseRequires(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        return "`requires` must be a list of precondition names";
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || item.trim() === "") {
+            return "`requires` entries must be non-empty strings";
+        }
+        out.push(item);
+    }
+    return out;
+}
+function parseExpectedFailure(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw))
+        return "`expectedFailure` must be a mapping with a `reason`";
+    const reason = raw.reason;
+    if (typeof reason !== "string" || reason.trim() === "") {
+        return "`expectedFailure` requires a non-empty `reason`";
+    }
+    return { reason };
+}
+/**
+ * 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 async function runSideEffectTests(context, options = {}) {
+    const hqRoot = context.hqRoot;
+    const timeoutMs = options.perCaseTimeoutMs ?? DEFAULT_PER_CASE_TIMEOUT_MS;
+    const runner = options.runner ?? defaultHookRunner;
+    const git = options.gitProbe ?? defaultGitProbe;
+    const seeder = options.seeder ??
+        ((root) => seedSandbox(root, {
+            seedRelpaths: options.seedRelpaths,
+            preconditions: options.preconditions,
+        }));
+    const registered = new Set(registeredHookIds(hqRoot));
+    const discovery = discoverSideEffectFixtures(hqRoot);
+    const results = [];
+    // A malformed side-effecting fixture is surfaced (WARN) but never executed.
+    for (const bad of discovery.invalid) {
+        results.push({
+            status: "WARN",
+            checkId: "hooks.deep.effects.invalid",
+            target: bad.relpath,
+            message: `Side-effecting fixture ${bad.relpath} is malformed and was skipped: ${bad.message}.`,
+            remediation: `Correct ${bad.relpath} (each case needs an \`effects\` list; see core/hook-tests/README.md).`,
+        });
+    }
+    const env = { hqRoot, timeoutMs, runner, git, seeder, keepSandbox: options.keepSandbox === true };
+    for (const fixture of discovery.fixtures) {
+        // A fixture whose hook is registered nowhere is not executed here; the
+        // coverage tier (US-007) owns orphan reporting.
+        if (!registered.has(fixture.hookId))
+            continue;
+        for (const testCase of fixture.cases) {
+            results.push(runCase(fixture, testCase, env));
+        }
+    }
+    return results;
+}
+/**
+ * Run one side-effecting case in its own sandbox and classify the observed
+ * effects. Guarantees the sandbox is torn down whatever happens.
+ */
+function runCase(fixture, testCase, env) {
+    const target = `${fixture.hookId}:${testCase.name}`;
+    // A `commit-created` effect cannot be observed without a git repo, so it
+    // implicitly requires one — a sandbox with no git yields UNKNOWN, not FAIL.
+    const required = new Set(testCase.requires);
+    if (testCase.effects.some((e) => e.kind === "commit-created")) {
+        required.add("git-repo");
+    }
+    let seed;
+    try {
+        seed = env.seeder(env.hqRoot, fixture.hookId);
+    }
+    catch (error) {
+        // Rule 4: one hook's setup failure is reported, but the run continues.
+        return {
+            status: "UNKNOWN",
+            checkId: "hooks.deep.effects.sandbox-setup-failed",
+            target,
+            message: `Sandbox setup for "${fixture.hookId}" failed, so case "${testCase.name}" could not be run: ${oneLine(error.message)}. Remaining hooks are unaffected.`,
+            remediation: `Investigate the sandbox seeding failure for "${fixture.hookId}".`,
+        };
+    }
+    try {
+        // Rule 3: a precondition the sandbox did not seed is UNKNOWN, not FAIL.
+        const missing = [...required].filter((r) => !seed.seeded.has(r));
+        if (missing.length > 0) {
+            return {
+                status: "UNKNOWN",
+                checkId: "hooks.deep.effects.precondition-missing",
+                target,
+                message: `Cannot verify "${fixture.hookId}" case "${testCase.name}": the sandbox did not seed the required precondition${missing.length === 1 ? "" : "s"} ${formatList(missing)}. Reported UNKNOWN rather than FAIL so a thin sandbox does not manufacture a false failure.`,
+                remediation: `Seed ${formatList(missing)} in the sandbox, or drop it from the fixture case's \`requires\`.`,
+            };
+        }
+        const scriptPath = path.join(seed.root, ".claude", "hooks", `${fixture.hookId}.sh`);
+        if (!fs.existsSync(scriptPath)) {
+            return {
+                status: "UNKNOWN",
+                checkId: "hooks.deep.effects.script-missing",
+                target,
+                message: `Cannot verify "${fixture.hookId}": its script .claude/hooks/${fixture.hookId}.sh is absent from the sandbox, so no effect can be observed.`,
+            };
+        }
+        const baseline = captureEffectBaseline(seed.root, testCase.effects, env.git);
+        const run = env.runner({
+            hookScriptPath: scriptPath,
+            payload: buildPayload(testCase, seed.root, seed.sessionId),
+            cwd: seed.root,
+            sessionId: seed.sessionId,
+            timeoutMs: env.timeoutMs,
+        });
+        if (run.timedOut) {
+            return {
+                status: "FAIL",
+                checkId: "hooks.deep.effects.timeout",
+                target,
+                message: `Case "${testCase.name}" for "${fixture.hookId}" exceeded the ${env.timeoutMs}ms per-case time bound; a hook that does not return within the bound is treated as a failure, not left to hang the command.`,
+                remediation: `Investigate why "${fixture.hookId}" does not return within ${env.timeoutMs}ms.`,
+            };
+        }
+        const evaluations = evaluateEffects(seed.root, testCase.effects, baseline, env.git);
+        return classifyEffects(fixture, testCase, evaluations, run);
+    }
+    finally {
+        if (!env.keepSandbox)
+            destroySandbox(seed.root);
+    }
+}
+/**
+ * Turn the per-effect evaluations into a single case result, applying the
+ * `expectedFailure` rule (shared with US-008 via {@link classifyCaseStatus}).
+ */
+function classifyEffects(fixture, testCase, evaluations, run) {
+    const target = `${fixture.hookId}:${testCase.name}`;
+    const allMet = evaluations.every((e) => e.met);
+    const status = classifyCaseStatus(allMet, testCase.expectedFailure);
+    const effectList = formatList(testCase.effects.map(describeEffect));
+    if (status === "PASS") {
+        return {
+            status,
+            checkId: "hooks.deep.effects.case",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" produced the expected observable effect${testCase.effects.length === 1 ? "" : "s"} in the sandbox: ${effectList}.`,
+        };
+    }
+    if (status === "WARN") {
+        // Pinned as a defect, yet every effect now happens — the marker is stale.
+        return {
+            status,
+            checkId: "hooks.deep.effects.stale-expected-failure",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" is marked expectedFailure (${testCase.expectedFailure?.reason ?? ""}) but now produces every expected effect (${effectList}); remove the stale marker.`,
+            remediation: `Delete the expectedFailure marker from case "${testCase.name}" in core/hook-tests/${fixture.hookId}.yaml.`,
+        };
+    }
+    // FAIL or KNOWN-DEFECT: name each effect that did not happen, plus the hook's
+    // exit code and stderr for diagnosis.
+    const unmet = evaluations
+        .filter((e) => !e.met)
+        .map((e) => `${describeEffect(e.expectation)} — ${e.detail}`)
+        .join("; ");
+    const stderr = run.stderr.trim();
+    const base = `Case "${testCase.name}" for "${fixture.hookId}" did not produce the expected effect${evaluations.filter((e) => !e.met).length === 1 ? "" : "s"}: ${unmet} (hook exit ${formatExit(run.exitCode)}${stderr ? `, stderr: ${oneLine(stderr)}` : ", no stderr"}).`;
+    if (status === "KNOWN-DEFECT") {
+        return {
+            status,
+            checkId: "hooks.deep.effects.case",
+            target,
+            message: `${base} Tracked as a known defect: ${testCase.expectedFailure?.reason ?? ""}.`,
+        };
+    }
+    return {
+        status: "FAIL",
+        checkId: "hooks.deep.effects.case",
+        target,
+        message: base,
+        remediation: `Verify "${fixture.hookId}" performs ${effectList} for case "${testCase.name}", or correct the fixture.`,
+    };
+}
+/**
+ * The Claude/Codex payload the hook reads on stdin: the fixture's event, tool,
+ * and opaque input, plus the sandbox cwd and the seeded session id.
+ */
+function buildPayload(testCase, cwd, sessionId) {
+    return JSON.stringify({
+        hook_event_name: testCase.event,
+        tool_name: testCase.tool,
+        tool_input: testCase.input,
+        cwd,
+        session_id: sessionId,
+    });
+}
+// --- message helpers ----------------------------------------------------------
+/** Render a list as "a", "a and b", or "a, b and c". */
+function formatList(items) {
+    if (items.length <= 1)
+        return items.join("");
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function formatExit(exitCode) {
+    return exitCode === null ? "none" : String(exitCode);
+}
+/** Collapse a string to a single trimmed, length-capped line for a message. */
+function oneLine(text) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > 200 ? `${collapsed.slice(0, 197)}…` : collapsed;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/lib/doctor/fix/apply.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `hq doctor --fix` — apply the allowlisted safe repairs (US-011).
+ *
+ * Read-by-default is the doctor's whole safety posture, so the write path is
+ * wrapped in guardrails that are NOT polish — each is a PRD acceptance criterion:
+ *
+ *   1. Dirty-tree refusal. If the working tree has uncommitted changes under
+ *      `.claude/`, `.codex/`, or `.grok/`, `--fix` refuses and exits non-zero
+ *      unless `--force`, so a repair can never be tangled up with unrelated
+ *      in-flight edits to the security layer.
+ *   2. Allowlist only. It repairs exactly three classes — restore an execute
+ *      bit, add a hook id to the gate profiles it is missing from, re-register a
+ *      script present on disk — and NEVER rewrites a hook body or deletes a file.
+ *      Classification is owned by {@link deriveRemediation}; a content-drift
+ *      finding is manual-only and simply never appears in the fixable set.
+ *   3. Preview + confirmation. Every change is shown diff-style and requires
+ *      confirmation, with `--yes` for non-interactive use.
+ *   4. Backup first. Before any write, the affected files are copied under
+ *      `workspace/doctor/backups/<timestamp>/` and the restore command is
+ *      printed on completion.
+ *   5. Re-verify. After applying, the affected checks are re-run and their
+ *      post-fix status reported, so the user sees the real result rather than an
+ *      assumed success.
+ *
+ * The applier resolves nothing about the host: the caller passes the HQ root
+ * (the command resolves it once), keeping this module decoupled from the CLI and
+ * trivially testable against a fake tree.
+ */
+import type { DoctorStatus } from "../types.js";
+import { type GateProfile } from "../hook-gate-profiles.js";
+import { type FixClass } from "./remediation.js";
+/** The tree subtrees whose uncommitted changes block a `--fix` run. */
+export declare const HOOK_CONFIG_DIRS: readonly [".claude", ".codex", ".grok"];
+/** Options for {@link applyFixes}. Everything is injectable for hermetic tests. */
+export interface ApplyFixesOptions {
+    /** The resolved HQ root the repairs run against. Required. */
+    hqRoot: string;
+    /** Skip the interactive confirmation (the `--yes` flag). Default: false. */
+    yes?: boolean;
+    /** Override the dirty-tree refusal (the `--force` flag). Default: false. */
+    force?: boolean;
+    /** stdout sink. Default: `process.stdout.write`. */
+    stdout?: (chunk: string) => void;
+    /** stderr sink. Default: `process.stderr.write`. */
+    stderr?: (chunk: string) => void;
+    /**
+     * The interactive confirmation. Called only when `yes` is false. Default reads
+     * a y/N answer from the TTY; a non-interactive default declines. Injected in
+     * tests to accept or reject without a terminal.
+     */
+    confirm?: () => boolean | Promise<boolean>;
+    /** Clock for the backup directory name. Default: `new Date()`. */
+    now?: () => Date;
+    /**
+     * The dirty-tree probe: the changed paths under {@link HOOK_CONFIG_DIRS}, or
+     * [] when clean or not a git repo. Default shells out to `git status`.
+     */
+    dirtyCheck?: (hqRoot: string) => string[];
+}
+/** One applied (or attempted) repair, with its post-fix re-check status. */
+export interface AppliedFix {
+    /** The check id of the finding that was repaired. */
+    checkId: string;
+    /** The safe class applied. */
+    fixClass: FixClass;
+    /** The file path or hook id acted on. */
+    target: string;
+    /** One-line human summary of the change. */
+    summary: string;
+    /** The status of the re-run check for this target, or null if not found. */
+    postStatus: DoctorStatus | null;
+}
+/** The outcome of an {@link applyFixes} run. */
+export interface ApplyFixesResult {
+    /** 0 on success or a clean no-op; 1 when the run was refused. */
+    exitCode: number;
+    /** Whether any file was written. */
+    wrote: boolean;
+    /** Why the run wrote nothing, when it did not: refusal reason or null. */
+    refused: "dirty-tree" | "declined" | null;
+    /** How many findings were auto-fixable. */
+    fixableCount: number;
+    /** The backup directory, or null when nothing was written. */
+    backupDir: string | null;
+    /** The restore command, or null when nothing was written. */
+    restoreCommand: string | null;
+    /** The applied repairs with their post-fix status. */
+    applied: AppliedFix[];
+}
+/**
+ * Apply every auto-fixable finding, honouring the dirty-tree refusal, the
+ * preview/confirmation gate, the pre-write backup, and the post-fix re-check.
+ * Returns a structured result rather than throwing so both the CLI and tests can
+ * assert on it.
+ */
+export declare function applyFixes(options: ApplyFixesOptions): Promise<ApplyFixesResult>;
+/**
+ * The uncommitted changes under {@link HOOK_CONFIG_DIRS}, one porcelain line
+ * each. Returns [] when the tree is clean OR when `hqRoot` is not a git repo
+ * (git exits non-zero): with no VCS there is no in-flight change to protect, and
+ * the backup still covers the write.
+ */
+export declare function uncommittedHookConfigChanges(hqRoot: string): string[];
+/**
+ * Insert a new `case` arm allowlisting `hookId` (leading to `return 0`) at the
+ * top of each named profile function's `case "$1" in` block. Additive: it never
+ * rewrites an existing arm, so an id already present in another profile is
+ * untouched and the parser recognises the new arm exactly as it would a
+ * hand-written one. A profile whose function or case block cannot be located is
+ * left unchanged rather than corrupted.
+ */
+export declare function addHookIdToGateProfiles(source: string, hookId: string, profiles: readonly GateProfile[]): string;
+/**
+ * Append a `type: command` hook registration to `settings.hooks[event]`,
+ * creating the `hooks` map and the event array as needed. Tolerant of a
+ * non-object `hooks` value — it is replaced rather than trusted.
+ */
+export declare function registerHookInSettings(settings: unknown, event: string, command: string): Record<string, unknown>;
+//# sourceMappingURL=apply.d.ts.map