@fullstackhouse/cerber 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Full Stack House
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# cerber 🐕
+
+**AI code-review cockpit.** Claude reviews your pull requests into local artifacts —
+a summary, a chaptered walkthrough of the changes, draft inline comments, and a
+verdict with a confidence score. You go through it in a local web cockpit.
+
+**Nothing reaches GitHub until you explicitly say so.** Cerber's only GitHub
+writes happen when you hit Send (coming in a later phase) — reviewing is 100%
+local and read-only.
+
+Named after Cerberus, the gatekeeper — and a sibling of
+[cezar](https://github.com/open-mercato/cezar): cezar runs coding agents,
+cerber guards what gets merged.
+
+## Quick start
+
+Requires Node 20+, an authenticated [`gh`](https://cli.github.com/) and a
+logged-in [`claude`](https://claude.com/claude-code) CLI. No API keys, no config, no database.
+
+```bash
+# Review a PR (writes a local artifact to ~/.cerber, nothing else)
+npx @fullstackhouse/cerber review https://github.com/owner/repo/pull/123
+
+# Review several
+npx @fullstackhouse/cerber review owner/repo#123 owner/repo#124
+npx @fullstackhouse/cerber review 123 124 --repo owner/repo
+
+# See what's in the queue
+npx @fullstackhouse/cerber list
+
+# Open the cockpit
+npx @fullstackhouse/cerber serve        # → http://127.0.0.1:4820
+```
+
+## What a review looks like
+
+Each review is a plain JSON artifact in `~/.cerber/reviews/` (override with
+`CERBER_HOME`) containing:
+
+- **Summary** — what the PR actually does and why, written top-down
+- **Chapters** — the changed files grouped into a logical walkthrough, each
+  with a title, an explanation, and its slice of the diff
+- **Draft comments** — inline, anchored to file/line, only things worth a
+  human's time
+- **Verdict** — approve / comment / request changes, with a 0–100 confidence
+  score and reasoning
+
+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.
+
+## Status / roadmap
+
+Early. Current phase: review + read-only cockpit.
+
+1. ✅ `cerber review <pr>` + artifact schema + cockpit (read-only)
+2. ✅ Comment editing in the cockpit (edit/approve/drop/add), verdict override,
+   gated **Send** (double-confirm; posts the review via your `gh` — the 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: poll for PRs awaiting your review, review them
+   automatically, cockpit always warm
+5. Confidence calibration → shadow-mode auto-send → opt-in auto-send above a
+   threshold
+
+## Development
+
+```bash
+pnpm install
+pnpm dev review <pr>     # run the CLI from source
+pnpm dev serve           # API on :4820
+pnpm --dir . typecheck && pnpm test
+pnpm build               # dist/ (CLI+server) + web/dist (cockpit)
+```
+
+Web cockpit dev with hot reload: `pnpm dev serve` in one terminal,
+`npx vite --config web/vite.config.ts` in another (proxies `/api`).
+
+## License
+
+MIT © Full Stack House

package/dist/cli/index.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import readline from "node:readline/promises";
+import { artifactId, artifactKey } from "../core/artifact.js";
+import { toMarkdown } from "../core/export.js";
+import { parsePrRef, searchAwaitingMe, submitReview } from "../core/gh.js";
+import { buildReviewPayload, eventForRecommendation } from "../core/send.js";
+import { cerberHome, listArtifacts, loadArtifact, updateArtifactByKey } from "../core/state.js";
+import { pool, reviewPr } from "../runner/review.js";
+import { startServer } from "../server/index.js";
+const program = new Command();
+program
+    .name("cerber")
+    .description("AI code-review cockpit. Claude reviews PRs into local artifacts; nothing reaches GitHub until you explicitly send it.")
+    .version("0.3.0");
+program
+    .command("review")
+    .description("Run an AI review of one or more PRs (local artifact only — no GitHub writes)")
+    .argument("[pr...]", "PR URL, owner/repo#number, or number (with --repo)")
+    .option("-R, --repo <owner/repo>", "repository for bare PR numbers / to scope --awaiting-me")
+    .option("-m, --model <model>", "Claude model override (e.g. sonnet, opus)")
+    .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")
+    .action(async (prs, opts) => {
+    let refs;
+    if (opts.awaitingMe) {
+        const found = await searchAwaitingMe(opts.repo);
+        console.log(`Found ${found.length} open PR(s) awaiting your review${opts.repo ? ` in ${opts.repo}` : ""}.`);
+        for (const f of found) {
+            console.log(`  ${f.owner}/${f.repo}#${f.number} — ${f.title}`);
+        }
+        refs = found;
+    }
+    else {
+        if (prs.length === 0) {
+            console.error("Pass PR references, or use --awaiting-me.");
+            process.exit(1);
+        }
+        refs = prs.map((input) => parsePrRef(input, opts.repo));
+    }
+    if (refs.length === 0)
+        return;
+    const parallel = Math.max(1, Number(opts.parallel) || 1);
+    let failures = 0;
+    let skips = 0;
+    const rows = [];
+    await pool(refs, parallel, async (ref) => {
+        const label = `${ref.owner}/${ref.repo}#${ref.number}`;
+        try {
+            const { artifact, skipped } = await reviewPr(ref, {
+                model: opts.model,
+                force: opts.force,
+                onProgress: (m) => console.log(`[${label}] ${m}`),
+            });
+            if (skipped) {
+                skips++;
+                return;
+            }
+            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)}` : ""));
+        }
+        catch (err) {
+            failures++;
+            rows.push(`✘ ${label} failed: ${err instanceof Error ? err.message : err}`);
+        }
+    });
+    console.log("");
+    for (const row of rows)
+        console.log(row);
+    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 (failures > 0)
+        process.exitCode = 1;
+});
+program
+    .command("list")
+    .description("List review artifacts and their statuses")
+    .action(async () => {
+    const artifacts = await listArtifacts();
+    if (artifacts.length === 0) {
+        console.log(`No reviews yet in ${cerberHome()}. Run: cerber review <pr-url>`);
+        return;
+    }
+    for (const a of artifacts) {
+        const v = a.verdict ? `${a.verdict.recommendation} ${a.verdict.confidence}%` : "-";
+        console.log(`${a.status.padEnd(8)} ${a.id.padEnd(40)} ${v.padEnd(20)} ${a.pr.title}`);
+    }
+});
+program
+    .command("export")
+    .description("Print a review as markdown (never touches GitHub)")
+    .argument("<pr>", "PR URL, owner/repo#number, or number (with --repo)")
+    .option("-R, --repo <owner/repo>", "repository for bare PR numbers")
+    .action(async (input, opts) => {
+    const ref = parsePrRef(input, opts.repo);
+    const artifact = await loadArtifact(artifactId(ref));
+    if (!artifact) {
+        console.error(`No review found for ${artifactId(ref)}. Run: cerber review ${input}`);
+        process.exit(1);
+    }
+    console.log(toMarkdown(artifact));
+});
+program
+    .command("send")
+    .description("Send a reviewed artifact to GitHub as a PR review — the ONLY command that writes to GitHub")
+    .argument("<pr>", "PR URL, owner/repo#number, or number (with --repo)")
+    .option("-R, --repo <owner/repo>", "repository for bare PR numbers")
+    .option("-e, --event <event>", "APPROVE | COMMENT | REQUEST_CHANGES (default: the artifact's verdict)")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async (input, opts) => {
+    const ref = parsePrRef(input, opts.repo);
+    const id = artifactId(ref);
+    const artifact = await loadArtifact(id);
+    if (!artifact) {
+        console.error(`No review found for ${id}. Run: cerber review ${input}`);
+        process.exit(1);
+    }
+    if (artifact.sent) {
+        console.error(`Already sent at ${artifact.sent.at}${artifact.sent.url ? ` — ${artifact.sent.url}` : ""}`);
+        process.exit(1);
+    }
+    const event = (opts.event ??
+        (artifact.verdict ? eventForRecommendation(artifact.verdict.recommendation) : "COMMENT")).toUpperCase();
+    if (!["APPROVE", "COMMENT", "REQUEST_CHANGES"].includes(event)) {
+        console.error(`Invalid event: ${event}`);
+        process.exit(1);
+    }
+    const payload = buildReviewPayload(artifact, event);
+    console.log(`About to send to ${artifact.pr.url}:`);
+    console.log(`  event: ${event}`);
+    console.log(`  inline comments: ${payload.comments.length}`);
+    if (payload.folded.length > 0) {
+        console.log(`  comments folded into body (no diff anchor): ${payload.folded.length}`);
+    }
+    console.log(`  body: ${payload.body.length} chars\n`);
+    if (!opts.yes) {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question("Send this review to GitHub? [y/N] ");
+        rl.close();
+        if (answer.trim().toLowerCase() !== "y") {
+            console.log("Aborted — nothing was sent.");
+            return;
+        }
+    }
+    const { url } = await submitReview(ref, {
+        event: payload.event,
+        body: payload.body,
+        comments: payload.comments,
+    });
+    await updateArtifactByKey(artifactKey(id), (a) => ({
+        ...a,
+        status: "sent",
+        sent: { at: new Date().toISOString(), event, url },
+    }));
+    console.log(`✔ Review sent${url ? `: ${url}` : "."}`);
+});
+program
+    .command("serve")
+    .description("Start the local review cockpit")
+    .option("-p, --port <port>", "port", "4820")
+    .option("-H, --host <host>", "host to bind", "127.0.0.1")
+    .action(async (opts) => {
+    await startServer({ port: Number(opts.port), host: opts.host });
+});
+program.parseAsync().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/core/artifact.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+export const SCHEMA_VERSION = 1;
+/** A draft inline comment. Never sent to GitHub unless the user explicitly sends the review. */
+export const CommentSchema = z.object({
+    id: z.string(),
+    path: z.string(),
+    /** Line number in the NEW version of the file; null = file-level comment. */
+    line: z.number().int().positive().nullable(),
+    body: z.string(),
+    chapterId: z.string().nullable().default(null),
+    origin: z.enum(["ai", "user"]),
+    status: z.enum(["draft", "approved", "dropped"]).default("draft"),
+});
+/** A logical group of changes — the unit of the review walkthrough. */
+export const ChapterSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    explanation: z.string(),
+    files: z.array(z.string()),
+});
+export const VerdictSchema = z.object({
+    recommendation: z.enum(["approve", "comment", "request_changes"]),
+    /** 0-100. How confident the AI is that its recommendation is right. */
+    confidence: z.number().min(0).max(100),
+    reasoning: z.string(),
+});
+export const PrInfoSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    number: z.number().int().positive(),
+    title: z.string(),
+    url: z.string(),
+    author: z.string(),
+    body: z.string().default(""),
+    baseRefName: z.string(),
+    headRefName: z.string(),
+    headSha: z.string().default(""),
+    additions: z.number().int().default(0),
+    deletions: z.number().int().default(0),
+    changedFiles: z.number().int().default(0),
+});
+export const ArtifactStatusSchema = z.enum([
+    "awaiting", // discovered, not yet reviewed by AI
+    "running", // AI review in progress
+    "ready", // AI review done, awaiting the human
+    "reviewed", // human went through it (edited/approved comments)
+    "sent", // review submitted to GitHub by explicit user action
+    "skipped", // human decided not to review
+    "failed", // AI run errored
+]);
+export const RunInfoSchema = z.object({
+    model: z.string().nullable().default(null),
+    startedAt: z.string(),
+    finishedAt: z.string().nullable().default(null),
+    costUsd: z.number().nullable().default(null),
+    error: z.string().nullable().default(null),
+});
+export const SentInfoSchema = z.object({
+    at: z.string(),
+    event: z.enum(["APPROVE", "COMMENT", "REQUEST_CHANGES"]),
+    url: z.string().nullable().default(null),
+});
+export const ArtifactSchema = z.object({
+    schemaVersion: z.literal(SCHEMA_VERSION),
+    /** "owner/repo#123" */
+    id: z.string(),
+    status: ArtifactStatusSchema,
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    pr: PrInfoSchema,
+    /** Full unified diff of the PR, as fetched at review time. */
+    diff: z.string(),
+    /** Markdown summary of what the PR does (pr-polish style). */
+    summary: z.string().default(""),
+    chapters: z.array(ChapterSchema).default([]),
+    comments: z.array(CommentSchema).default([]),
+    verdict: VerdictSchema.nullable().default(null),
+    run: RunInfoSchema.nullable().default(null),
+    /** Set once the user explicitly sent the review to GitHub. */
+    sent: SentInfoSchema.nullable().default(null),
+});
+/** What the AI must return. Subset of the artifact; cerber owns the rest. */
+export const AiReviewSchema = z.object({
+    summary: z.string(),
+    chapters: z.array(z.object({
+        id: z.string(),
+        title: z.string(),
+        explanation: z.string(),
+        files: z.array(z.string()),
+    })),
+    comments: z.array(z.object({
+        path: z.string(),
+        line: z.number().int().positive().nullable(),
+        body: z.string(),
+        chapterId: z.string().nullable().optional(),
+    })),
+    verdict: VerdictSchema,
+});
+export function artifactId(pr) {
+    return `${pr.owner}/${pr.repo}#${pr.number}`;
+}
+/** Filesystem-safe key for an artifact id: "owner/repo#123" -> "owner__repo__123" */
+export function artifactKey(id) {
+    return id.replace(/\//g, "__").replace(/#/g, "__");
+}

package/dist/core/diff.js

@@ -0,0 +1,86 @@
+export function splitDiffByFile(diff) {
+    const patches = [];
+    const lines = diff.split("\n");
+    let current = null;
+    let currentPath = null;
+    const flush = () => {
+        if (current && currentPath) {
+            patches.push({ path: currentPath, patch: current.join("\n") });
+        }
+        current = null;
+        currentPath = null;
+    };
+    for (const line of lines) {
+        if (line.startsWith("diff --git ")) {
+            flush();
+            current = [line];
+            // "diff --git a/foo b/foo" — prefer the b-side path; fall back to a-side.
+            const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+            currentPath = m ? m[2] : line.slice("diff --git ".length);
+        }
+        else if (current) {
+            current.push(line);
+            // Deleted files: b-side is /dev/null, use the a-side path instead.
+            if (line.startsWith("--- a/") && currentPath === "/dev/null") {
+                currentPath = line.slice("--- a/".length);
+            }
+            if (line === "+++ /dev/null") {
+                const minus = current.find((l) => l.startsWith("--- a/"));
+                if (minus)
+                    currentPath = minus.slice("--- a/".length);
+            }
+        }
+    }
+    flush();
+    return patches;
+}
+/** Concatenate the patches of the given files (order = diff order). */
+export function patchForFiles(diff, files) {
+    const wanted = new Set(files);
+    return splitDiffByFile(diff)
+        .filter((p) => wanted.has(p.path))
+        .map((p) => p.patch)
+        .join("\n");
+}
+/**
+ * Line numbers (new side of the diff) that a GitHub review comment can attach
+ * to, per file: added and context lines inside hunks.
+ */
+export function newSideLines(diff) {
+    const result = new Map();
+    for (const { path, patch } of splitDiffByFile(diff)) {
+        const lines = new Set();
+        let newLine = 0;
+        let inHunk = false;
+        const patchLines = patch.split("\n");
+        for (let i = 0; i < patchLines.length; i++) {
+            const line = patchLines[i];
+            const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+            if (hunk) {
+                newLine = Number(hunk[1]);
+                inHunk = true;
+                continue;
+            }
+            if (!inHunk)
+                continue;
+            if (line === "" && i === patchLines.length - 1)
+                continue; // trailing split artifact
+            if (line.startsWith("\\"))
+                continue; // ""
+            if (line.startsWith("+") || line.startsWith(" ") || line === "") {
+                lines.add(newLine);
+                newLine++;
+            }
+            // "-" lines belong to the old side only.
+        }
+        result.set(path, lines);
+    }
+    return result;
+}
+/** Paths present in the diff but not claimed by any chapter. */
+export function unclaimedFiles(diff, chapters) {
+    const claimed = new Set(chapters.flatMap((c) => c.files));
+    return splitDiffByFile(diff)
+        .map((p) => p.path)
+        .filter((p) => !claimed.has(p));
+}

package/dist/core/export.js

@@ -0,0 +1,48 @@
+/** Render an artifact as a standalone markdown review document. */
+export function toMarkdown(artifact) {
+    const lines = [];
+    const { pr, verdict } = artifact;
+    lines.push(`# Review: ${artifact.id} — ${pr.title}`);
+    lines.push("");
+    lines.push(`> ${pr.url}`);
+    lines.push(`> ${pr.author} · \`${pr.headRefName}\` → \`${pr.baseRefName}\` · ${pr.changedFiles} files +${pr.additions} -${pr.deletions}`);
+    lines.push("");
+    if (verdict) {
+        lines.push(`**Verdict: ${verdict.recommendation.replace("_", " ")}** (confidence ${verdict.confidence}%)`);
+        lines.push("");
+        lines.push(verdict.reasoning);
+        lines.push("");
+    }
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(artifact.summary || "(no summary)");
+    lines.push("");
+    if (artifact.chapters.length > 0) {
+        lines.push("## Walkthrough");
+        lines.push("");
+        for (const ch of artifact.chapters) {
+            lines.push(`### ${ch.title}`);
+            lines.push("");
+            lines.push(ch.explanation);
+            lines.push("");
+            lines.push(ch.files.map((f) => `- \`${f}\``).join("\n"));
+            lines.push("");
+            const comments = artifact.comments.filter((c) => c.chapterId === ch.id && c.status !== "dropped");
+            for (const c of comments) {
+                lines.push(`> **${c.path}${c.line != null ? `:${c.line}` : ""}** — ${c.body.replace(/\n/g, "\n> ")}`);
+                lines.push("");
+            }
+        }
+    }
+    const orphans = artifact.comments.filter((c) => c.status !== "dropped" &&
+        (!c.chapterId || !artifact.chapters.some((ch) => ch.id === c.chapterId)));
+    if (orphans.length > 0) {
+        lines.push("## Other comments");
+        lines.push("");
+        for (const c of orphans) {
+            lines.push(`> **${c.path}${c.line != null ? `:${c.line}` : ""}** — ${c.body.replace(/\n/g, "\n> ")}`);
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}

package/dist/core/gh.js

@@ -0,0 +1,140 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { PrInfoSchema } from "./artifact.js";
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 64 * 1024 * 1024;
+/**
+ * Accepts: a full PR URL, "owner/repo#123", or a bare number (requires repoFlag "owner/repo").
+ */
+export function parsePrRef(input, repoFlag) {
+    const urlMatch = input.match(/github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)/);
+    if (urlMatch) {
+        return { owner: urlMatch[1], repo: urlMatch[2], number: Number(urlMatch[3]) };
+    }
+    const shortMatch = input.match(/^([^/\s#]+)\/([^/\s#]+)#(\d+)$/);
+    if (shortMatch) {
+        return { owner: shortMatch[1], repo: shortMatch[2], number: Number(shortMatch[3]) };
+    }
+    const numMatch = input.match(/^#?(\d+)$/);
+    if (numMatch) {
+        if (!repoFlag) {
+            throw new Error(`PR "${input}" is a bare number — pass --repo owner/repo, or use a full URL / owner/repo#number.`);
+        }
+        const [owner, repo] = repoFlag.split("/");
+        if (!owner || !repo)
+            throw new Error(`Invalid --repo "${repoFlag}", expected owner/repo.`);
+        return { owner, repo, number: Number(numMatch[1]) };
+    }
+    throw new Error(`Cannot parse PR reference: "${input}"`);
+}
+async function gh(args) {
+    try {
+        const { stdout } = await execFileAsync("gh", args, { maxBuffer: MAX_BUFFER });
+        return stdout;
+    }
+    catch (err) {
+        const e = err;
+        throw new Error(`gh ${args.slice(0, 3).join(" ")} failed: ${e.stderr?.trim() || e.message}`);
+    }
+}
+export async function fetchPrInfo(ref) {
+    const out = await gh([
+        "pr",
+        "view",
+        String(ref.number),
+        "--repo",
+        `${ref.owner}/${ref.repo}`,
+        "--json",
+        "title,url,author,body,baseRefName,headRefName,headRefOid,additions,deletions,changedFiles",
+    ]);
+    const raw = JSON.parse(out);
+    return PrInfoSchema.parse({
+        owner: ref.owner,
+        repo: ref.repo,
+        number: ref.number,
+        title: raw.title,
+        url: raw.url,
+        author: raw.author?.login ?? "unknown",
+        body: raw.body ?? "",
+        baseRefName: raw.baseRefName,
+        headRefName: raw.headRefName,
+        headSha: raw.headRefOid ?? "",
+        additions: raw.additions ?? 0,
+        deletions: raw.deletions ?? 0,
+        changedFiles: raw.changedFiles ?? 0,
+    });
+}
+export async function fetchPrDiff(ref) {
+    return gh(["pr", "diff", String(ref.number), "--repo", `${ref.owner}/${ref.repo}`]);
+}
+/** Map `gh search prs` JSON output to PR refs. Drafts are excluded. */
+export function mapSearchResults(raw) {
+    return raw
+        .filter((r) => !r.isDraft)
+        .flatMap((r) => {
+        const [owner, repo] = r.repository.nameWithOwner.split("/");
+        if (!owner || !repo)
+            return [];
+        return [
+            {
+                owner,
+                repo,
+                number: r.number,
+                title: r.title,
+                url: r.url,
+                updatedAt: r.updatedAt,
+                isDraft: r.isDraft,
+            },
+        ];
+    });
+}
+/** Open, non-draft PRs where the current gh user's review is requested. */
+export async function searchAwaitingMe(repoFilter, limit = 50) {
+    const args = [
+        "search",
+        "prs",
+        "--review-requested=@me",
+        "--state=open",
+        "--limit",
+        String(limit),
+        "--json",
+        "number,title,repository,isDraft,url,updatedAt",
+    ];
+    if (repoFilter)
+        args.push("--repo", repoFilter);
+    const out = await gh(args);
+    return mapSearchResults(JSON.parse(out));
+}
+/**
+ * THE ONLY GITHUB WRITE IN CERBER.
+ * Submits a review in one shot. Must only ever be called from an explicit
+ * user action (cockpit Send button / `cerber send` after confirmation).
+ */
+export async function submitReview(ref, payload) {
+    const args = [
+        "api",
+        `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}/reviews`,
+        "--method",
+        "POST",
+        "--input",
+        "-",
+    ];
+    const { execFile: ef } = await import("node:child_process");
+    const out = await new Promise((resolve, reject) => {
+        const child = ef("gh", args, { maxBuffer: MAX_BUFFER }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error(`gh api reviews failed: ${stderr?.trim() || err.message}`));
+            else
+                resolve(stdout);
+        });
+        child.stdin.write(JSON.stringify(payload));
+        child.stdin.end();
+    });
+    try {
+        const res = JSON.parse(out);
+        return { url: res.html_url ?? null };
+    }
+    catch {
+        return { url: null };
+    }
+}