@fullstackhouse/cerber 0.7.0 → 0.9.0

package/README.md

@@ -28,10 +28,18 @@ npx @fullstackhouse/cerber review 123 124 --repo owner/repo
 # See what's in the queue
 npx @fullstackhouse/cerber list
 
-# Open the cockpit
+# Open the cockpit — it's an inbox: it polls GitHub for PRs awaiting your
+# review and drafts a review for each, so they're ready when you arrive
 npx @fullstackhouse/cerber serve        # → http://127.0.0.1:4820
 ```
 
+`serve` does the whole loop by default: discover → draft → wait for you.
+Sending stays a human click. Tame it with `--no-auto-review` (list awaiting
+PRs, review on click) or `--no-poll` (no GitHub polling at all) — or flip the
+same two switches in the cockpit's Settings, which persist in
+`~/.cerber/config.json` and apply on the next poll. Merged and closed PRs are
+archived out of the queue automatically.
+
 ## What a review looks like
 
 Each review is a plain JSON artifact in `~/.cerber/reviews/` (override with
@@ -44,10 +52,138 @@ Each review is a plain JSON artifact in `~/.cerber/reviews/` (override with
   human's time
 - **Verdict** — approve / comment / request changes, with a 0–100 confidence
   score and reasoning
+- **Run metadata** — model, whether it read the source or only the diff, and
+  the token spend as an API-rate equivalent
 
 The cockpit (`cerber serve`) renders the queue and the per-PR walkthrough with
 diffs. Artifacts are plain JSON you can `cat`, edit, or pipe into anything.
 
+### It reviews the code, not just the diff
+
+Cerber checks the PR's head out locally and lets the review read it. That
+matters because a reviewer holding only a diff hedges over things it could have
+just looked up — *"I can't see the enclosing function, so this could be
+wrong"* — and burns its confidence score on missing context instead of on real
+uncertainty. With the source there, it opens the enclosing function, follows
+callers of a changed signature, checks whether a helper already exists, and
+sees whether a test covers the new path.
+
+On one real PR, same commit, the difference was: a speculative "this *looks
+like* it sits after an early return" became a concrete finding; a permission
+check the diff showed as a tidy gate turned out to hide a value the API
+response still ships; confidence went 72% → 82%. It burned 3.3× the tokens and
+took three minutes instead of one.
+
+Cerber rides your `claude` login, so a review isn't billed per run: on a Claude
+subscription it draws on your usage limits. The `≈$` figures in the CLI and
+cockpit are what those tokens would cost at API token rates — read them as
+"how much of the plan did this eat", not as an invoice.
+
+If you want the old behaviour — faster, lighter, blind past the changed lines:
+
+```bash
+cerber review owner/repo#123 --no-source
+cerber serve --no-source
+```
+
+The cockpit labels every review "read the full source" or "read the diff only",
+and offers a one-click **Re-review with full source** on the diff-only ones.
+
+Details worth knowing:
+
+- The checkout is a shallow (`--depth=1`) fetch of `refs/pull/N/head` from the
+  base repo, so fork PRs work with no extra remotes. Auth rides `gh`'s
+  credential helper, set on that clone only — your git config is untouched.
+- If git or `gh` can't produce a checkout, the run says so and reviews the diff
+  alone. A missing checkout never fails a review.
+- The run is read-only unless you have trusted the PR (see below): `Read`,
+  `Grep` and `Glob` are the only tools it gets. Without a checkout it gets none,
+  and runs in an empty directory, so it can never read whatever project cerber
+  happens to be started from and mistake it for the PR.
+- PR content is untrusted, and `claude -p` skips the workspace-trust prompt, so
+  cerber does the distrusting itself: a `.claude/settings.json` or `.mcp.json`
+  in the checkout is renamed aside (still readable, no longer loaded), hooks
+  and non-cerber MCP servers are off, and the prompt tells the reviewer that
+  instructions found in files are material to review, not directions to follow.
+  What a hostile PR can still do is skew the review text — it cannot run
+  anything, write anything, or reach the network. Read the verdict, don't
+  rubber-stamp it. (All of this applies to PRs you have *not* trusted; a
+  trusted one is deliberately given the run of the place.)
+- Checkouts live in `~/.cerber/src/<owner>__<repo>__<n>` and are reused by later
+  re-reviews. A big monorepo is a few hundred MB per PR, so the cache keeps only
+  the 8 most recently reviewed and evicts the rest as it goes — never one a
+  review is currently reading. `cerber prune` reclaims the space now;
+  `cerber prune --all` takes the ones for reviews still awaiting you too.
+
+### Trusted PRs: reviews that can run things
+
+Reading beats guessing, but running beats reading. A review that ran the test
+covering the change reports what happened; one that only read it guesses. So
+for PRs you already trust — a teammate's, or anything in your own repos —
+cerber can let the review run commands in the checkout: the test suite, a
+typecheck, `git log`/`git blame`, a build.
+
+Trust is about the *people*, and only about people — cerber has no way to
+trust a repository, because anyone can open a PR against one:
+
+```bash
+cerber trust @fullstackhouse/*      # anyone in the org
+cerber trust @fullstackhouse/devs   # anyone on that GitHub team
+cerber trust @teammate              # one person, by login
+cerber trust                        # show who is trusted today
+```
+
+Membership is resolved against GitHub when the review runs (your `gh` login
+needs `read:org`), and a lookup that fails counts as "not a member" — a check
+cerber could not complete never reads as trust. Writing a repo instead of a
+person is rejected, in the CLI, the cockpit, and on config load:
+
+```
+$ cerber trust acme/widgets
+"acme/widgets" is not a trust rule. Trust is about people, not repositories —
+anyone can open a PR against a repo you own, so trusting the repo would trust
+them too. Use @acme/* for everyone in that org, @acme/team for one team, or
+@login for a person.
+```
+
+Rules live in `~/.cerber/config.json`, and the cockpit has a **settings**
+screen that reads and writes the same file — each rule shown with what it
+actually grants. A `!` rule denies and beats every grant, so `@fullstackhouse/*`
+plus `!@fullstackhouse/contractors` does what it looks like. `--trust` and
+`--no-trust` override the config for one run; `cerber trust <pattern> --delete`
+removes a rule.
+
+A trusted review gets `Bash`, `WebFetch` and `WebSearch` on top of reading, and
+the repo's own `.claude` config applies — it behaves as if you had checked the
+branch out and opened it yourself. The cockpit labels it "ran the code" so you
+know which kind you are reading.
+
+It is handed no GitHub credentials, and that part is *enforced* rather than
+requested. `GH_CONFIG_DIR` points at a fresh empty directory, `GH_TOKEN` and
+`GITHUB_TOKEN` are blanked, the fetch credential rides the fetch command
+instead of being stored in the checkout, git's global and system config are
+switched off so a keychain helper cannot stand in, and the ssh route is closed
+too — no agent, no `~/.ssh/config`, no default identity — since otherwise a run
+could point the remote at `git@github.com` and ride your keys. Measured from
+inside a checkout: `git push` over https and over ssh, and `gh pr comment`, all
+fail to authenticate, while `git log` still works.
+
+**It is not a sandbox, and you should not read it as one.** A trusted run has
+`Bash` and your filesystem: it can write files in the checkout, and a
+determined one could read a key straight out of `~/.ssh` and use it itself.
+What cerber guarantees is that it *hands* the run nothing. The rest is what
+trusting a person means — which is why trust is spelled `@org/team`, and why
+the default is a review that cannot run anything at all.
+
+**What you are accepting.** A trusted review executes code from that PR on your
+machine — the branch's scripts, its dependencies, its test suite. That is the
+same exposure as checking the branch out and running the tests yourself, which
+is what you would otherwise do; it is not the same as reading a diff. Trust
+orgs and people, not the whole of GitHub. And note that `cerber serve` reviews
+unattended by default: with trust rules set, it will run matching PRs' code
+with nobody watching. It warns at startup, the cockpit shows a ⚡ badge while
+it's the case, and `--no-trust` (or `--no-auto-review`) turns it off.
+
 ### When the PR moves under you
 
 A review is written against one commit, but authors keep pushing. Opening a
@@ -72,9 +208,8 @@ Early, but all six planned phases have shipped.
    only GitHub write in the codebase) + `cerber export` to markdown
 3. ✅ `--awaiting-me` discovery, parallel runs (`--parallel`, default 3),
    freshness skip (same head SHA → no re-run; `--force` overrides), queue stats
-4. ✅ Daemon/VPS mode: `cerber serve --daemon` polls for PRs awaiting your
-   review and reviews them automatically (read-only); token auth for
-   non-localhost binds
+4. ✅ Inbox mode (now the default): `cerber serve` polls for PRs awaiting your
+   review and reviews them automatically; token auth for non-localhost binds
 5. ✅ Confidence calibration (`cerber stats`), shadow-mode auto-send (default
    in daemon: logs what would be sent), opt-in `--auto-send` (approve-only,
    `--auto-send-threshold`, default 90%)
@@ -85,11 +220,11 @@ Early, but all six planned phases have shipped.
 ## Running on a VPS
 
 ```bash
-cerber serve --daemon --host 0.0.0.0 --token "$(openssl rand -hex 16)" \
+cerber serve --host 0.0.0.0 --token "$(openssl rand -hex 16)" \
   --repo you/repo-a --repo you/repo-b --interval 10
 ```
 
-The daemon polls GitHub, reviews anything new (skipping PRs whose artifact
+The server polls GitHub, reviews anything new (skipping PRs whose artifact
 already matches the head SHA), and the cockpit is always warm — open it any
 minute and see pending/ready/sent reviews. Auth: `?token=…` once in the
 browser (sets a cookie) or `Authorization: Bearer …`. Binding a non-localhost

package/dist/cli/index.js

@@ -2,7 +2,10 @@
 import { Command } from "commander";
 import readline from "node:readline/promises";
 import { artifactId, artifactKey } from "../core/artifact.js";
+import { listCheckouts, removeCheckout } from "../core/checkout.js";
 import { toMarkdown } from "../core/export.js";
+import { configPath, loadConfig, saveConfig } from "../core/config.js";
+import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { parsePrRef, searchAwaitingMe, submitReview } from "../core/gh.js";
 import { buildReviewPayload, computeCalibration, eventForRecommendation } from "../core/send.js";
 import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, updateArtifactByKey, } from "../core/state.js";
@@ -23,6 +26,9 @@ program
     .option("-a, --awaiting-me", "discover and review all open PRs awaiting your review")
     .option("-P, --parallel <n>", "how many reviews to run concurrently", "3")
     .option("-f, --force", "re-review even if the artifact is up to date with the PR head")
+    .option("--no-source", "review the diff alone: skip the local checkout of the PR head. Faster and cheaper, but the AI cannot see past the changed lines")
+    .option("-t, --trust", "let the review run commands in the checkout (tests, typecheck, git log) whatever the trust config says")
+    .option("--no-trust", "keep the review read-only even if a trust rule matches")
     .action(async (prs, opts) => {
     let refs;
     if (opts.awaitingMe) {
@@ -52,6 +58,8 @@ program
             const { artifact, skipped } = await reviewPr(ref, {
                 model: opts.model,
                 force: opts.force,
+                withSource: opts.source,
+                trust: opts.trust,
                 onProgress: (m) => console.log(`[${label}] ${m}`),
             });
             if (skipped) {
@@ -61,7 +69,7 @@ program
             const v = artifact.verdict;
             rows.push(`✔ ${label.padEnd(40)} ${v ? `${v.recommendation} ${v.confidence}%` : "?"}`.padEnd(65) +
                 `${artifact.comments.length} comment(s)` +
-                (artifact.run?.costUsd != null ? `, $${artifact.run.costUsd.toFixed(2)}` : ""));
+                (artifact.run?.costUsd != null ? `, ≈$${artifact.run.costUsd.toFixed(2)}` : ""));
         }
         catch (err) {
             failures++;
@@ -74,6 +82,9 @@ program
     if (skips > 0)
         console.log(`(${skips} already up to date — use --force to re-review)`);
     console.log(`\nArtifacts in ${cerberHome()}/reviews — view with: cerber serve`);
+    if (rows.some((r) => r.includes("≈$"))) {
+        console.log("(≈$ is what the tokens would cost at API rates — on a Claude subscription they draw on your usage limits, not your card.)");
+    }
     if (failures > 0)
         process.exitCode = 1;
 });
@@ -161,6 +172,94 @@ program
     }));
     console.log(`✔ Review sent${url ? `: ${url}` : "."}`);
 });
+program
+    .command("trust")
+    .description("Show, add, or remove the people whose PRs a review may run (~/.cerber/config.json)")
+    .argument("[pattern]", "@org/*, @org/team, @login, or !pattern to deny — omit to list what is trusted today")
+    .option("-d, --delete", "remove this rule instead of adding it")
+    .action(async (pattern, opts) => {
+    const config = await loadConfig();
+    if (pattern) {
+        let rule;
+        try {
+            rule = parseTrustRule(pattern);
+        }
+        catch (err) {
+            console.error(err instanceof TrustRuleError ? err.message : String(err));
+            process.exit(1);
+        }
+        if (!rule) {
+            console.error(`Not a trust rule: "${pattern}"`);
+            process.exit(1);
+        }
+        const canonical = describeRule(rule);
+        const without = config.trust.filter((line) => {
+            const parsed = parseTrustRule(line);
+            return !parsed || describeRule(parsed) !== canonical;
+        });
+        if (opts.delete) {
+            if (without.length === config.trust.length) {
+                console.error(`Not in the trust list: ${canonical}`);
+                process.exit(1);
+            }
+            await saveConfig({ ...config, trust: without });
+            console.log(`Removed ${canonical}. Those PRs are reviewed read-only again.`);
+            return;
+        }
+        await saveConfig({ ...config, trust: [...without, canonical] });
+        console.log(`Trusted: ${explainRule(rule)}\n  → ${configPath()}`);
+        console.log("Reviews of matching PRs may run tests, typechecks and git commands in the checkout.");
+        return;
+    }
+    if (config.trust.length === 0) {
+        console.log(`Nothing is trusted: every review reads the checkout and runs nothing.\n` +
+            `Trust people — never a repo, since anyone can open a PR against one:\n` +
+            `  cerber trust @your-org/*         # everyone in the org\n` +
+            `  cerber trust @your-org/devs      # one GitHub team\n` +
+            `  cerber trust @teammate           # one person\n` +
+            `Rules live in ${configPath()}, and in the cockpit under Settings.`);
+        return;
+    }
+    console.log(`Trusted people (${configPath()}):`);
+    for (const line of config.trust) {
+        const rule = parseTrustRule(line);
+        if (rule)
+            console.log(`  ${describeRule(rule).padEnd(28)} ${explainRule(rule)}`);
+    }
+    console.log("\nEveryone else's PRs are reviewed read-only. Remove one with: cerber trust <pattern> --delete");
+});
+program
+    .command("prune")
+    .description("Delete cached source checkouts in ~/.cerber/src (they re-fetch on the next --with-source review)")
+    .option("--all", "delete every checkout, including ones for reviews still awaiting you")
+    .action(async (opts) => {
+    const checkouts = await listCheckouts();
+    if (checkouts.length === 0) {
+        console.log(`No source checkouts in ${cerberHome()}/src.`);
+        return;
+    }
+    const artifacts = new Map((await listArtifacts()).map((a) => [a.id, a]));
+    const mb = (bytes) => {
+        const value = bytes / 1024 / 1024;
+        return `${value.toFixed(value < 10 ? 1 : 0)} MB`;
+    };
+    let freed = 0;
+    let kept = 0;
+    for (const checkout of checkouts) {
+        const artifact = artifacts.get(checkout.id);
+        // A review you have not sent yet is still live work — its checkout makes
+        // the next re-review cheap, so only --all takes it.
+        const done = !artifact || artifact.sent != null || artifact.pr.state !== "OPEN";
+        if (!opts.all && !done) {
+            kept++;
+            continue;
+        }
+        await removeCheckout(checkout.dir);
+        freed += checkout.bytes;
+        console.log(`removed ${checkout.id.padEnd(40)} ${mb(checkout.bytes)}`);
+    }
+    console.log(`\nFreed ${mb(freed)}${kept > 0 ? `; kept ${kept} for open reviews (--all removes them too)` : ""}.`);
+});
 program
     .command("stats")
     .description("How well-calibrated the AI reviews are: verdict agreement and comment survival by confidence")
@@ -206,16 +305,21 @@ program
     }
 });
 program
-    .command("serve")
-    .description("Start the review cockpit; --daemon keeps the queue warm by polling GitHub")
+    .command("serve", { isDefault: true })
+    .description("Start the review cockpit — an inbox: it polls GitHub for PRs awaiting your review and drafts " +
+    "a review for each, so they're ready when you open it. --no-poll / --no-auto-review to tame it.")
     .option("-p, --port <port>", "port", "4820")
     .option("-H, --host <host>", "host to bind (0.0.0.0 for VPS — requires --token)", "127.0.0.1")
     .option("-t, --token <token>", "require this token on every request (env: CERBER_TOKEN)")
-    .option("-d, --daemon", "poll for PRs awaiting your review and auto-review them (read-only)")
-    .option("-i, --interval <minutes>", "daemon poll interval", "5")
-    .option("-R, --repo <owner/repo>", "repo(s) the daemon watches (repeatable; default: all)", collect, [])
-    .option("-P, --parallel <n>", "daemon review concurrency", "3")
-    .option("-m, --model <model>", "Claude model override for daemon reviews")
+    .option("--no-poll", "don't poll GitHub for PRs awaiting your review (also disables auto-review)")
+    .option("--no-auto-review", "list awaiting PRs but don't review them until you click review")
+    .option("-d, --daemon", "(deprecated no-op — polling and auto-review are now the default)")
+    .option("-i, --interval <minutes>", "poll interval (default: config daemon.intervalMinutes, 5)")
+    .option("-R, --repo <owner/repo>", "repo(s) to watch (repeatable; default: config daemon.repos, all)", collect, [])
+    .option("-P, --parallel <n>", "review concurrency (default: config daemon.parallel, 3)")
+    .option("-m, --model <model>", "Claude model override for unattended reviews")
+    .option("--no-source", "review the diff alone, with no local checkout of the PR head (applies to daemon runs and cockpit re-reviews)")
+    .option("--no-trust", "ignore the configured trust rules: every review here stays read-only, even for repos you trust")
     .option("--auto-send", "ACTUALLY auto-send APPROVE verdicts at/above --auto-send-threshold (default: shadow mode, which only logs what would be sent)")
     .option("--auto-send-threshold <pct>", "confidence needed to auto-send", "90")
     .option("--insecure", "allow binding a non-localhost host without a token (NOT recommended)")
@@ -232,17 +336,46 @@ program
         console.log(`⚠ auto-send is ON: APPROVE verdicts with confidence ≥ ${threshold}% will be sent to GitHub as you, without a per-review confirmation.\n` +
             `  Every decision is logged to ${cerberHome()}/autosend.ndjson. COMMENT/REQUEST_CHANGES always wait for a human.`);
     }
-    const daemon = opts.daemon
+    if (opts.daemon) {
+        console.log("Note: --daemon is deprecated — polling and auto-review are on by default now.");
+    }
+    // Config holds the defaults and is re-read by the daemon on every poll
+    // (so the cockpit's Settings toggles apply live); a --no-* flag caps
+    // this run only, and --no-poll skips the loop entirely.
+    const config = await loadConfig();
+    const d = config.daemon;
+    // Trust means "run this PR's code". A human clicking review accepted that
+    // per PR; auto-review does it unattended, on whatever lands in the queue.
+    if (opts.poll && d.poll && opts.autoReview && d.autoReview && opts.trust && config.trust.length > 0) {
+        console.log(`⚠ ${config.trust.length} trust rule(s) in ${configPath()}: unattended reviews will run commands from ` +
+            `matching PRs, with nobody watching. Pass --no-trust to keep every review read-only, ` +
+            `or --no-auto-review to only review on click.`);
+    }
+    const daemon = opts.poll
         ? startDaemon({
-            repos: opts.repo,
-            intervalMs: Math.max(1, Number(opts.interval) || 5) * 60_000,
-            parallel: Math.max(1, Number(opts.parallel) || 1),
+            repos: opts.repo.length > 0 ? opts.repo : d.repos,
+            intervalMs: Math.max(1, opts.interval !== undefined ? Number(opts.interval) || d.intervalMinutes : d.intervalMinutes) *
+                60_000,
+            parallel: Math.max(1, opts.parallel !== undefined ? Number(opts.parallel) || d.parallel : d.parallel),
             model: opts.model,
+            withSource: opts.source,
+            trust: opts.trust ? undefined : false,
+            autoReview: opts.autoReview,
             autoSend: opts.autoSend ? "on" : "shadow",
             autoSendThreshold: threshold,
         })
         : undefined;
-    await startServer({ port: Number(opts.port), host: opts.host, token, daemon });
+    if (!opts.poll) {
+        console.log("Polling is off (--no-poll) — the queue only shows what you review by hand.");
+    }
+    await startServer({
+        port: Number(opts.port),
+        host: opts.host,
+        token,
+        daemon,
+        withSource: opts.source,
+        trust: opts.trust ? undefined : false,
+    });
 });
 function collect(value, previous) {
     return [...previous, value];

package/dist/core/artifact.js

@@ -62,6 +62,10 @@ export const RunInfoSchema = z.object({
     finishedAt: z.string().nullable().default(null),
     costUsd: z.number().nullable().default(null),
     error: z.string().nullable().default(null),
+    /** The reviewer could read the repo at the PR head, not just the diff. */
+    withSource: z.boolean().default(false),
+    /** The user vouched for this PR, so the reviewer could also run commands. */
+    trusted: z.boolean().default(false),
 });
 export const SentInfoSchema = z.object({
     at: z.string(),

package/dist/core/checkout.js

@@ -0,0 +1,201 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { cerberHome } from "./state.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Config files a checked-out repo could use to make the reviewing agent run
+ * code. `claude -p` skips the workspace-trust prompt, so a PR that adds a hook
+ * here would otherwise execute on the reviewer's machine.
+ */
+export const AGENT_CONFIG_FILES = [
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".mcp.json",
+];
+const QUARANTINE_SUFFIX = ".cerber-quarantined";
+/**
+ * Auth for the fetch, passed per command and never written to the clone.
+ * Persisting it would leave a working push credential lying inside a directory
+ * a trusted review is about to run commands in.
+ */
+const FETCH_AUTH = ["-c", "credential.helper=!gh auth git-credential"];
+const realDeps = {
+    git: async (args, cwd) => {
+        try {
+            const { stdout } = await execFileAsync("git", args, { cwd, maxBuffer: 16 * 1024 * 1024 });
+            return stdout;
+        }
+        catch (err) {
+            const e = err;
+            throw new Error(`git ${args.slice(0, 2).join(" ")} failed: ${e.stderr?.trim() || e.message}`);
+        }
+    },
+    isRepo: (dir) => fs
+        .access(path.join(dir, ".git"))
+        .then(() => true)
+        .catch(() => false),
+    mkdir: async (dir) => {
+        await fs.mkdir(dir, { recursive: true });
+    },
+    quarantine: async (from, to) => {
+        try {
+            await fs.rename(from, to);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+    },
+    touch: async (dir) => {
+        const now = new Date();
+        await fs.utimes(dir, now, now).catch(() => { });
+    },
+};
+/** One shallow working tree per PR, under ~/.cerber/src — a cache, safe to delete. */
+export function sourceDir(ref) {
+    return path.join(cerberHome(), "src", `${ref.owner}__${ref.repo}__${ref.number}`);
+}
+/**
+ * A fresh empty directory for one review run: the cwd of a diff-only run, and
+ * the throwaway `GH_CONFIG_DIR` of every run.
+ *
+ * Per run, not shared, because both uses assume "empty" and a run can write.
+ * A trusted run has `Bash`; given one directory reused forever, it could leave
+ * a `CLAUDE.md` there that every later diff-only run would then load as its
+ * own memory. Delete it with {@link removeRunDir} when the run ends.
+ */
+export async function createRunDir() {
+    const root = path.join(cerberHome(), "run");
+    await fs.mkdir(root, { recursive: true });
+    await sweepStaleRunDirs(root);
+    return fs.mkdtemp(path.join(root, "run-"));
+}
+export async function removeRunDir(dir) {
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => { });
+}
+/** A crashed run leaves its directory behind; don't accumulate them forever. */
+async function sweepStaleRunDirs(root) {
+    const cutoff = Date.now() - 24 * 60 * 60_000;
+    const entries = await fs.readdir(root).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.startsWith("run-"))
+            continue;
+        const full = path.join(root, entry);
+        const stat = await fs.stat(full).catch(() => null);
+        if (stat && stat.mtimeMs < cutoff)
+            await removeRunDir(full);
+    }
+}
+/**
+ * Put the PR's head commit on disk so the reviewer can read the code around the
+ * diff. Fetches `refs/pull/N/head` from the base repo, which resolves fork PRs
+ * too, at depth 1 — cerber never needs the history, only the tree.
+ *
+ * Read-only towards GitHub. Auth rides `gh`'s credential helper, set locally on
+ * this clone so nothing in the user's git config is touched.
+ */
+export async function prepareCheckout(ref, opts = {}) {
+    const deps = { ...realDeps, ...opts.deps };
+    const log = opts.log ?? (() => { });
+    const dir = sourceDir(ref);
+    if (!(await deps.isRepo(dir))) {
+        log(`Preparing a source checkout in ${dir}…`);
+        await deps.mkdir(dir);
+        await deps.git(["init", "-q"], dir);
+        await deps.git(["remote", "add", "origin", `https://github.com/${ref.owner}/${ref.repo}.git`], dir);
+    }
+    // Clones made before the credential moved out of the config still carry one.
+    await deps.git(["config", "--unset-all", "credential.helper"], dir).catch(() => "");
+    await deps.git([...FETCH_AUTH, "fetch", "-q", "--depth=1", "--no-tags", "origin", `refs/pull/${ref.number}/head`], dir);
+    await deps.git(["checkout", "-q", "--force", "--detach", "FETCH_HEAD"], dir);
+    // A previous head may have left untracked files behind; they would read as
+    // part of this commit's tree. This also wipes any quarantine an earlier run
+    // left, which is why the loop below never has to undo one: every run starts
+    // from the commit's own files, whether or not the last one was trusted.
+    await deps.git(["clean", "-qfdx"], dir);
+    if (!opts.trusted) {
+        // Renamed rather than deleted: the reviewer can still read and comment on
+        // these files, but Claude Code won't load them as its own configuration.
+        for (const file of AGENT_CONFIG_FILES) {
+            const live = path.join(dir, file);
+            if (await deps.quarantine(live, live + QUARANTINE_SUFFIX)) {
+                log(`Quarantined ${file} from the checkout — PR config never configures the reviewer.`);
+            }
+        }
+    }
+    const sha = (await deps.git(["rev-parse", "HEAD"], dir)).trim();
+    await deps.touch(dir);
+    return { dir, sha };
+}
+async function listCheckoutDirs() {
+    const root = path.join(cerberHome(), "src");
+    let entries;
+    try {
+        entries = await fs.readdir(root);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const found = [];
+    for (const entry of entries) {
+        const parsed = entry.match(/^(.+)__(.+)__(\d+)$/);
+        if (!parsed)
+            continue;
+        const dir = path.join(root, entry);
+        const usedAt = await fs.stat(dir).then((s) => s.mtimeMs, () => 0);
+        found.push({ id: `${parsed[1]}/${parsed[2]}#${parsed[3]}`, dir, usedAt });
+    }
+    return found;
+}
+/** Every checkout currently on disk, with what it costs. Walks each tree. */
+export async function listCheckouts() {
+    const entries = await listCheckoutDirs();
+    const found = [];
+    for (const entry of entries) {
+        found.push({ id: entry.id, dir: entry.dir, bytes: await dirSize(entry.dir) });
+    }
+    return found.sort((a, b) => b.bytes - a.bytes);
+}
+/**
+ * Checkouts are the default now, so the cache has to stop growing on its own —
+ * a daemon watching a busy repo would otherwise clone every PR it ever sees and
+ * keep them all. Drops the least recently used, and never one being reviewed.
+ */
+export const MAX_CACHED_CHECKOUTS = 8;
+export async function evictOldCheckouts(opts = {}) {
+    const keep = opts.keep ?? MAX_CACHED_CHECKOUTS;
+    const inUse = opts.inUse ?? (() => false);
+    const entries = (await listCheckoutDirs()).sort((a, b) => b.usedAt - a.usedAt);
+    const evicted = [];
+    let kept = 0;
+    for (const entry of entries) {
+        if (inUse(entry.id) || kept < keep) {
+            kept++;
+            continue;
+        }
+        await removeCheckout(entry.dir);
+        evicted.push(entry.id);
+    }
+    return evicted;
+}
+export async function removeCheckout(dir) {
+    await fs.rm(dir, { recursive: true, force: true });
+}
+async function dirSize(dir) {
+    let total = 0;
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            total += await dirSize(full);
+        else if (entry.isFile())
+            total += await fs.stat(full).then((s) => s.size, () => 0);
+    }
+    return total;
+}