@fullstackhouse/cerber 0.29.1 → 0.31.0

package/README.md

@@ -1,18 +1,38 @@
 # cerber 🐕
 
 [![npm](https://img.shields.io/npm/v/%40fullstackhouse%2Fcerber)](https://www.npmjs.com/package/@fullstackhouse/cerber)
+[![CI](https://github.com/fullstackhouse/cerber/actions/workflows/ci.yml/badge.svg)](https://github.com/fullstackhouse/cerber/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-**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.
+**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 read it in a local web
+cockpit, keep or rewrite or drop each comment, then press Send when you agree
+with it.
 
 **Nothing reaches GitHub until you explicitly say so.** Cerber's only GitHub
 write is the Send button (plus opt-in daemon auto-send you turn on yourself) —
-reviewing is 100% local and read-only.
+reviewing is 100% local and read-only. Reviews go out under your own account,
+as your review, because you decided each line of it should.
+
+That gate is the whole point, and the reason this is not another review bot:
+
+> Reviewing pull requests with an AI model creates a specific danger: a system
+> that can both draft opinions and hold GitHub credentials will eventually post
+> one without a human deciding it should.
 
 Named after Cerberus, the gatekeeper: cerber guards what gets merged.
 
+**A drafted review, as you read it** — verdict and confidence beside the PR
+title, the walkthrough rail on the left, a summary written for someone who has
+not read the diff:
+
+![A review opened in the cockpit: the verdict pill by the PR title, a walkthrough rail listing chapters and their comments on the left, and a summary written in sections — problem first, then the fix, then details.](docs/walkthrough.png)
+
+**And the queue they arrive in** — `cerber serve` polls GitHub for PRs awaiting
+your review and drafts one for each, so they are written by the time you get
+there:
+
 ![The queue: three drafted reviews, each with a verdict and confidence in its row; under the cursor, a strip quotes the selected review's own reasoning so it can be judged without opening it.](docs/queue.png)
 
 *Every screenshot in this README is cerber reviewing cerber's own pull
@@ -20,11 +40,25 @@ requests.*
 
 ## 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.
+Requires Node 20+, an authenticated [`gh`](https://cli.github.com/), `git`, and
+a logged-in [`claude`](https://claude.com/claude-code) CLI. No API keys, no
+config, no database.
+
+**Claude Code is a hard requirement, and a paid one.** Cerber drafts reviews by
+running `claude` as you: it rides your existing Claude Code login and draws on
+that plan's usage limits, so you need a Claude subscription that includes Claude
+Code. There is no `ANTHROPIC_API_KEY` path — not as a fallback, not at all.
+GitHub only; no GitLab or Bitbucket. Notifications are macOS and Linux.
+
+Run `cerber doctor` first — it checks all three tools and tells you which one to
+fix, instead of letting a missing login turn into an empty cockpit later.
 
 ```bash
-# Review a PR (writes a local artifact to ~/.cerber, nothing else)
+# Open the cockpit — this is the whole product
+npx @fullstackhouse/cerber serve        # → http://127.0.0.1:4820
+
+# Or review one PR from the terminal (writes a local artifact to ~/.cerber,
+# nothing else)
 npx @fullstackhouse/cerber review https://github.com/owner/repo/pull/123
 
 # Review several
@@ -33,22 +67,79 @@ npx @fullstackhouse/cerber review 123 124 --repo owner/repo
 
 # See what's in the queue
 npx @fullstackhouse/cerber list
-
-# 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 those
 switches in the cockpit's Settings, which persist in `~/.cerber/config.json`
-and apply on the next poll. The queue only lists what
-still wants you: anything you have settled moves to the filed tabs right of
-the thin rule in the filter row — reviews you sent, ones you marked reviewed
-or skipped, merged and closed PRs — each tab appearing only while it holds
-something. PRs in archived repos are never picked up at all, since the repo
-is read-only and a review could never be sent.
+and apply on the next poll.
+
+## Contents
+
+- [What a review looks like](#what-a-review-looks-like) — what Claude writes and how you walk it
+- [The inbox](#the-inbox) — what the queue shows, what settles a row, the notifications
+- [It reviews the code, not just the diff](#it-reviews-the-code-not-just-the-diff)
+- [Trusted PRs: reviews that can run things](#trusted-prs-reviews-that-can-run-things)
+- [When the PR moves under you](#when-the-pr-moves-under-you)
+- [Arguing with the review before you send it](#arguing-with-the-review-before-you-send-it)
+- [Every row remembers what happened to it](#every-row-remembers-what-happened-to-it)
+- [Status](#status) · [Running on a VPS](#running-on-a-vps) · [How it works](#how-it-works) · [Development](#development)
+
+## 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. Findings are graded **blocker / minor / nit** — the words mean
+  what they mean everywhere, and only a blocker stands between the PR and
+  approval; a question or note carries no grade at all
+- **Verdict** — approve / comment / request changes, with a 0–100 confidence
+  score and reasoning that names the worst finding still standing
+- **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. Draft comments sit inline in the diff, anchored to the line they're
+about, each waiting for you to keep, rewrite, or drop it:
+
+![A chapter of the walkthrough: the diff with a draft comment card anchored under the line it discusses, explaining the finding in plain words.](docs/comment.png)
+
+Any line of the diff is one click away from being talked about: hover it and a
+`+` appears in the gutter, the way it does on GitHub. What opens is one box
+with two exits — write the comment yourself, or ask the reviewer about that
+line and get the answer in the conversation below. A line the PR removes can be
+asked about too; a comment on one posts on the file, since GitHub only takes
+inline comments on the new side of a diff.
+
+A markdown file the PR **adds** opens as the document it is, not as a thousand
+rows of `+ ## Heading` — because reviewing a new spec means reading it, and
+every line being an addition means the diff's markers say nothing. It is still
+the review: the draft comments sit in the document under the paragraph they
+point at, and any paragraph takes a comment or a question where it stands. A
+markdown file the PR only *edits* stays a diff — there the change is the point
+— with "read as a document" in its header when you want the prose instead.
+
+Artifacts are plain JSON you can `cat`, edit, or pipe into anything.
+
+The queue is meant to be walked, not clicked through: `j`/`k` move the cursor
+and the strip under the table explains whatever it lands on — the verdict's own
+reasoning, what the run read, how it sits against the auto-send bar — so most
+rows can be judged without opening them. `↵` opens one, `r` drafts (or
+re-drafts) it. Inside a review, `[` and `]` walk to the previous/next PR still
+awaiting you, `n` steps through the chapters, and `s` sends.
+
+## The inbox
+
+The queue only lists what still wants you: anything you have settled moves to
+the filed tabs right of the thin rule in the filter row — reviews you sent,
+ones you marked reviewed or skipped, merged and closed PRs — each tab appearing
+only while it holds something. PRs in archived repos are never picked up at
+all, since the repo is read-only and a review could never be sent.
 
 ### Settled means you settled it
 
@@ -88,13 +179,20 @@ who did is the one mistake worth designing against.
 
 ### It taps you on the shoulder
 
-When a PR lands in the queue you get a desktop notification naming it, folded
-into one popup when several arrive at once. The tap comes from the poll that
-found the PR, so it reaches you with the cockpit closed, in another Space, or
-after a browser restart — `cerber serve` is the only thing that has to be
-running. It goes to whatever this machine already has (Notification Centre on
-macOS, `notify-send` on Linux) and stays quiet where there is neither. Off with
-`daemon.notify` in `~/.cerber/config.json`, or the checkbox in Settings.
+When a PR is ready for you, you get a desktop notification naming it, folded
+into one popup when several land at once. Ready means *there is something to
+read*: cerber drafts the review itself, so the tap waits for the draft and says
+what it found — "widgets#7 draft ready · requests changes · 2 blockers" — rather
+than walking you back to a row that says "no run yet". A PR nobody is going to
+draft (auto-review off, or a run that failed) is announced as it arrives, since
+that is all the news there will be — and if a retry drafts it after all, that is
+new news and you are told. Nothing else is: a PR whose draft you have been told
+about stays quiet however its next re-review ends. The tap comes from the poll, so it reaches
+you with the cockpit closed, in another Space, or after a browser restart —
+`cerber serve` is the only thing that has to be running. It goes to whatever
+this machine already has (Notification Centre on macOS, `notify-send` on Linux)
+and stays quiet where there is neither. Off with `daemon.notify` in
+`~/.cerber/config.json`, or the checkbox in Settings.
 
 **On macOS, clicking it opens that review** in the cockpit. It takes a small app
 cerber builds once under `~/.cerber` — the first tap asks you to allow
@@ -122,56 +220,7 @@ anything, the favicon wears a red dot, and it goes away when the last review is
 dealt with. No permission, no switch — just the paw with a mark on it, so a
 glance at the tab strip answers "is there anything for me?".
 
-## 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. Findings are graded **blocker / minor / nit** — the words mean
-  what they mean everywhere, and only a blocker stands between the PR and
-  approval; a question or note carries no grade at all
-- **Verdict** — approve / comment / request changes, with a 0–100 confidence
-  score and reasoning that names the worst finding still standing
-- **Run metadata** — model, whether it read the source or only the diff, and
-  the token spend as an API-rate equivalent
-
-![A review opened in the cockpit: the verdict pill by the PR title, a walkthrough rail listing chapters and their comments on the left, and a summary written in sections — problem first, then the fix, then details.](docs/walkthrough.png)
-
-The cockpit (`cerber serve`) renders the queue and the per-PR walkthrough with
-diffs. Draft comments sit inline in the diff, anchored to the line they're
-about, each waiting for you to keep, rewrite, or drop it:
-
-![A chapter of the walkthrough: the diff with a draft comment card anchored under the line it discusses, explaining the finding in plain words.](docs/comment.png)
-
-Any line of the diff is one click away from being talked about: hover it and a
-`+` appears in the gutter, the way it does on GitHub. What opens is one box
-with two exits — write the comment yourself, or ask the reviewer about that
-line and get the answer in the conversation below. A line the PR removes can be
-asked about too; a comment on one posts on the file, since GitHub only takes
-inline comments on the new side of a diff.
-
-A markdown file the PR **adds** opens as the document it is, not as a thousand
-rows of `+ ## Heading` — because reviewing a new spec means reading it, and
-every line being an addition means the diff's markers say nothing. It is still
-the review: the draft comments sit in the document under the paragraph they
-point at, and any paragraph takes a comment or a question where it stands. A
-markdown file the PR only *edits* stays a diff — there the change is the point
-— with "read as a document" in its header when you want the prose instead.
-
-Artifacts are plain JSON you can `cat`, edit, or pipe into anything.
-
-The queue is meant to be walked, not clicked through: `j`/`k` move the cursor
-and the strip under the table explains whatever it lands on — the verdict's own
-reasoning, what the run read, how it sits against the auto-send bar — so most
-rows can be judged without opening them. `↵` opens one, `r` drafts (or
-re-drafts) it. Inside a review, `[` and `]` walk to the previous/next PR still
-awaiting you, `n` steps through the chapters, and `s` sends.
-
-### It reviews the code, not just the diff
+## 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
@@ -228,7 +277,7 @@ Details worth knowing:
   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
+## 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
@@ -297,7 +346,7 @@ 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
+## When the PR moves under you
 
 A review is written against one commit, but authors keep pushing. Opening a
 review checks the PR's head and pulls the review forward: comments follow their
@@ -308,10 +357,17 @@ commit's SHA, so inline comments land where they were written.
 
 The AI's summary and verdict still describe the commit that was reviewed. To
 get its opinion of the new code, hit **Re-review at the new head** in the
-cockpit (or `cerber review <pr> --force`) — comments you wrote or rewrote are
-carried into the fresh review.
+cockpit (or `cerber review <pr> --force`).
+
+> ⚠️ **A re-review replaces the whole draft — including comments you wrote or
+> rewrote, and a send body you wrote yourself.** They are dropped when the run
+> starts and they do not come back, on success or on failure. This is a
+> decision, not a bug ([`docs/lifecycle.md`](docs/lifecycle.md)): the run owns
+> the draft. If you have written comments you want to keep, send the review or
+> copy them out first. Your *decisions* do survive — a send, a `reviewed` or
+> `skipped` you set, and the chat transcript are all kept.
 
-### Arguing with the review before you send it
+## Arguing with the review before you send it
 
 A draft you disagree with used to leave two options: rewrite it by hand, or
 re-review and hope. Neither lets you say *what was wrong*. So every review has
@@ -369,7 +425,7 @@ the summary, comments and verdict alone, and is still one deliberate click. A
 review that has already been sent can't be argued with: that artifact is the
 record of what GitHub has.
 
-### Every row remembers what happened to it
+## Every row remembers what happened to it
 
 A review keeps one "last updated" time, which means every write erases the
 answer to *when did I skip this, and did they ask again afterwards?* So each
@@ -448,6 +504,15 @@ 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`).
 
+## Contributing and security
+
+Patches welcome — [`CONTRIBUTING.md`](./CONTRIBUTING.md) has the gate
+(`pnpm typecheck && pnpm test`) and the one rule that is not negotiable.
+
+Cerber holds your GitHub credentials and, on a trusted PR, runs that PR's code.
+[`SECURITY.md`](./SECURITY.md) says exactly what that means, what is stripped
+from a trusted run, and where to report a vulnerability privately.
+
 ## License
 
 MIT © [Full Stack House](https://fullstack.house)

package/dist/cli/index.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import { createRequire } from "node:module";
 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 { formatBlockers, isBlocking, preflight } from "../core/preflight.js";
 import { withWriter } from "../core/history.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { parsePrRef, searchAwaitingMe, submitReview } from "../core/gh.js";
@@ -15,10 +17,34 @@ import { isReviewRunning } from "../runner/inflight.js";
 import { startDaemon } from "../server/daemon.js";
 import { cockpitUrl, startServer } from "../server/index.js";
 const program = new Command();
+/**
+ * The published version, read from the manifest rather than typed here — a
+ * hand-maintained copy drifted to 0.5.0 while 0.30.0 shipped, and `--version`
+ * is the first thing anyone runs to decide whether a project is alive.
+ */
+const { version } = createRequire(import.meta.url)("../../package.json");
+/**
+ * Stop before the work starts when a tool cerber shells out to is missing or
+ * logged out, rather than letting it surface as an empty queue or a retrying
+ * poll. `allowDegraded` is for `serve --no-poll`, which is still useful for
+ * reading artifacts already on disk.
+ */
+async function requireTools(allowDegraded = false) {
+    const checks = await preflight();
+    if (!checks.some(isBlocking))
+        return;
+    const message = formatBlockers(checks);
+    if (allowDegraded) {
+        console.warn(`\n${message}\n`);
+        return;
+    }
+    console.error(`\n${message}\n`);
+    process.exit(1);
+}
 program
     .name("cerber")
     .description("AI code-review cockpit. Claude reviews PRs into local artifacts; nothing reaches GitHub until you explicitly send it.")
-    .version("0.5.0");
+    .version(version);
 program
     .command("review")
     .description("Run an AI review of one or more PRs (local artifact only — no GitHub writes)")
@@ -32,6 +58,7 @@ program
     .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) => {
+    await requireTools();
     let refs;
     if (opts.awaitingMe) {
         const found = await searchAwaitingMe(opts.repo);
@@ -349,6 +376,31 @@ program
             `${wouldSend} shadow candidate(s), ${autoSent} auto-sent.`);
     }
 });
+program
+    .command("doctor")
+    .description("Check that everything cerber needs is installed and logged in")
+    .action(async () => {
+    const checks = await preflight();
+    for (const c of checks) {
+        if (c.status === "ok") {
+            console.log(`  ✔ ${c.name.padEnd(22)} ${c.detail ?? ""}`.trimEnd());
+        }
+        else {
+            console.log(`  ✗ ${c.name.padEnd(22)} ${c.status === "missing" ? "not installed" : "not logged in"}`);
+            if (c.fix)
+                console.log(`    ${c.fix}`);
+        }
+    }
+    const bad = checks.filter(isBlocking);
+    console.log("");
+    if (bad.length === 0) {
+        console.log("Ready. `cerber serve` opens the cockpit.");
+    }
+    else {
+        console.log(`${bad.length} thing(s) to fix before cerber can review anything.`);
+        process.exitCode = 1;
+    }
+});
 program
     .command("serve", { isDefault: true })
     .description("Start the review cockpit — an inbox: it polls GitHub for PRs awaiting your review and drafts " +
@@ -358,7 +410,7 @@ program
     .option("-t, --token <token>", "require this token on every request (env: CERBER_TOKEN)")
     .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("--no-notify", "don't notify this machine when a PR lands in the queue")
+    .option("--no-notify", "don't notify this machine when a review is ready for you")
     .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, [])
@@ -377,6 +429,9 @@ program
             `Pass --token <secret> (or CERBER_TOKEN), or --insecure if the network is trusted.`);
         process.exit(1);
     }
+    // Without `gh` the cockpit binds, polls into an error loop and shows an
+    // empty queue; `--no-poll` is the one shape that still works offline.
+    await requireTools(!opts.poll);
     const threshold = Math.min(100, Math.max(50, Number(opts.autoSendThreshold) || 90));
     if (opts.autoSend) {
         console.log(`⚠ auto-send is ON: APPROVE verdicts with confidence ≥ ${threshold}% will be sent to GitHub as you, without a per-review confirmation.\n` +

package/dist/core/artifact.js

@@ -304,6 +304,32 @@ export const ArtifactSchema = z.object({
      * field forward long after the decision it is meant to date.
      */
     settledAt: z.string().nullable().default(null),
+    /**
+     * The announcement ledger: what this machine has already told you about this
+     * row — see `pendingNews` in `src/core/notify.ts` for what is worth telling.
+     *
+     * Three states, not two. `null` is "the poll found this and owes you a tap";
+     * a record is "already told". **Absent** is neither: nobody ever meant to
+     * announce this row — a review you pulled in by hand, or one written before
+     * the ledger existed — so it is never news, and an upgrade doesn't announce
+     * a queue the user has been looking at for weeks. Only `stubArtifact` writes
+     * the null.
+     *
+     * It records *what* was said, not just that something was, because the two
+     * things cerber can say about a row are different news: "nobody is drafting
+     * this" and "here is the draft". A run that fails is announced as the first,
+     * is retried on the next poll, and may then succeed — and a ledger that only
+     * remembered "told" would swallow the draft-ready tap, leaving the user with
+     * the one notification that had nothing to read behind it.
+     */
+    notified: z
+        .object({
+        at: z.string(),
+        /** True when what was announced was a finished draft. */
+        drafted: z.boolean(),
+    })
+        .nullable()
+        .optional(),
     /** Last time this review was pulled forward onto a newer head commit. */
     refresh: RefreshInfoSchema.nullable().default(null),
     calibration: CalibrationSchema.nullable().default(null),

package/dist/core/config.js

@@ -23,9 +23,10 @@ export const DaemonConfigSchema = z.object({
     /** Draft an AI review for whatever lands in the queue. Never sends. */
     autoReview: z.boolean().default(true),
     /**
-     * Tap this machine's notification centre when a PR lands in the queue. The
-     * cockpit's bell needs a tab open and permitted; this one only needs `serve`
-     * running, which is the point of it.
+     * Tap this machine's notification centre when a PR is worth coming back for
+     * — the draft landing, or the arrival itself when nothing is going to be
+     * drafted (`isNews` in `core/notify.ts`). The cockpit's bell needs a tab open
+     * and permitted; this one only needs `serve` running, which is the point.
      */
     notify: z.boolean().default(true),
     intervalMinutes: z.number().int().positive().default(5),

package/dist/core/gh.js

@@ -68,8 +68,13 @@ export async function fetchPrInfo(ref) {
 }
 /**
  * Org and team membership, for `@org/*` and `@org/team` trust rules. A 404 is
- * GitHub's "no" and the answer we want; anything else (no `read:org` scope, an
- * outage) throws, so a broken check can never read as "trusted".
+ * GitHub's "no"; anything else (an outage, a rate limit) throws. Either way the
+ * answer is never "trusted", which is the property that matters.
+ *
+ * Note that a token without `read:org` also gets a 404 rather than a 403 — so a
+ * missing scope reads as "not a member" and silently narrows trust instead of
+ * announcing itself. Fail-closed, but quiet: if a rule you expect to match
+ * doesn't, check the scope before the rule.
  */
 export async function isOrgMember(org, login) {
     return membershipCheck(["api", `orgs/${org}/members/${login}`, "--silent"]);

package/dist/core/notify.js

@@ -4,8 +4,16 @@
 // one when it can ring: it names the PR and opens that review when you click
 // it. But it is a page notification, so it needs a tab that is open, alive and
 // permitted — which is exactly what you don't have while you're in an editor
-// all afternoon. This half rides the poll that discovers the PR instead, so the
-// tap survives a closed cockpit, a denied permission and a browser restart.
+// all afternoon. This half rides the poll instead, so the tap survives a closed
+// cockpit, a denied permission and a browser restart.
+//
+// It taps you once per piece of news, at the moment that news is worth walking
+// back for. With auto-review on — the default — that is when the draft is
+// written, not when the PR lands: a tap that leads to "no run yet, press r" is
+// a tap that costs you the walk back and gives you nothing. `isNews` decides
+// whether there is news at all, `pendingNews` whether it is news you have
+// already been told. A PR has at most two: "nobody is drafting this", and
+// "here is the draft" — and it only gets the second if it got the first.
 //
 // A click has to land in the same place either way, which on macOS is the whole
 // difference between the two paths below. `osascript -e 'display notification'`
@@ -40,6 +48,22 @@ const execFileAsync = promisify(execFile);
  */
 export const NOTIFY_TIMEOUT_MS = 5_000;
 const slug = (a) => `${a.repo}#${a.number}`;
+const VERDICT_WORDS = {
+    approve: "approves",
+    comment: "comments",
+    request_changes: "requests changes",
+};
+/**
+ * What a finished draft says, in the few words a popup gets: the verdict, and
+ * the count the verdict rests on. A draft that graded nothing and left no
+ * verdict still gets a line — "drafted" is the news there.
+ */
+function draftLine(d) {
+    const verdict = d.recommendation ? VERDICT_WORDS[d.recommendation] : "drafted";
+    if (d.blockers === 0)
+        return verdict;
+    return `${verdict} · ${d.blockers} blocker${d.blockers === 1 ? "" : "s"}`;
+}
 /**
  * Text a notification body or an AppleScript literal can actually hold. A PR
  * title is somebody else's text and can carry anything; control characters
@@ -48,7 +72,7 @@ const slug = (a) => `${a.repo}#${a.number}`;
  */
 const flatten = (value) => value.replace(/[\u0000-\u001f\u007f]+/g, " ");
 /**
- * One popup for one poll's arrivals — a batch is one interruption, not five.
+ * One popup for one poll's news — a batch is one interruption, not five.
  * Deliberately the same shape and wording the cockpit's bell uses, so the two
  * channels never read as two different pieces of news about one PR.
  *
@@ -57,27 +81,92 @@ const flatten = (value) => value.replace(/[\u0000-\u001f\u007f]+/g, " ");
  * origin with no fragment of its own — the deep link is a fragment, and the
  * cockpit is a hash-routed page.
  */
-export function notice(arrived, cockpit) {
-    if (arrived.length === 0)
+export function notice(news, cockpit) {
+    if (news.length === 0)
         return null;
     const base = cockpit || null;
-    if (arrived.length === 1) {
-        const a = arrived[0];
+    if (news.length === 1) {
+        const a = news[0];
         const key = artifactKey(artifactId(a));
-        return {
-            title: `${slug(a)} awaits your review`,
-            body: `${a.title} — ${a.author}`,
-            url: base && `${base}#/r/${encodeURIComponent(key)}`,
-        };
+        const url = base && `${base}#/r/${encodeURIComponent(key)}`;
+        // The draft is the news when there is one, so the popup leads with what it
+        // found rather than with the PR having arrived — which, by then, it did
+        // minutes ago.
+        if (a.draft)
+            return { title: `${slug(a)} draft ready`, body: `${draftLine(a.draft)} — ${a.title}`, url };
+        return { title: `${slug(a)} awaits your review`, body: `${a.title} — ${a.author}`, url };
     }
-    const named = arrived.slice(0, 3).map(slug);
-    const rest = arrived.length - named.length;
+    const named = news.slice(0, 3).map(slug);
+    const rest = news.length - named.length;
     return {
-        title: `${arrived.length} PRs await your review`,
+        // A drafted PR awaits you too, so the general wording is true of any batch;
+        // the better headline is only claimed when every one of them is drafted.
+        title: news.every((n) => n.draft) ? `${news.length} drafts ready` : `${news.length} PRs await your review`,
         body: rest > 0 ? `${named.join(", ")} and ${rest} more` : named.join(", "),
         url: base,
     };
 }
+/**
+ * Whether this row is news *yet*.
+ *
+ * The one rule behind the tap's timing, and the cockpit's bell mirrors it
+ * (`web/src/notify.ts`). A row cerber is about to draft, or is drafting, is not
+ * news: the tap would arrive minutes before there is anything to read, and the
+ * one after it would never come. So it waits — unless nothing is coming, which
+ * is the case when auto-review is off (nobody will draft this until you say so)
+ * or the run failed (nobody will draft it at all).
+ *
+ * A row you have settled is not news either, whatever else happened to it: you
+ * already answered it.
+ */
+export function isNews(a, autoReview) {
+    if (a.pr.state !== "OPEN")
+        return false;
+    if (a.status === "running")
+        return false;
+    if (a.status === "awaiting")
+        return !autoReview;
+    return a.status === "ready" || a.status === "failed";
+}
+/**
+ * What this row has to say that it has not said already, or null for silence.
+ *
+ * `isNews` answers "is there news at all"; this one also weighs it against the
+ * ledger, which is where the two things cerber can say about a row stop being
+ * interchangeable. A run that failed is announced as "nobody is drafting this",
+ * is retried on the next poll, and may then succeed — so the draft is news
+ * *again*, to someone who was told the opposite five minutes ago. The reverse
+ * is not: a row that had a draft and now has a broken re-review is a PR the
+ * user already knows about, and a second tap there is noise.
+ */
+export function pendingNews(a, autoReview) {
+    // Absent, not null: nobody ever meant to announce this row.
+    if (a.notified === undefined)
+        return null;
+    if (!isNews(a, autoReview))
+        return null;
+    const news = newsOf(a);
+    if (a.notified === null)
+        return news;
+    return news.draft && !a.notified.drafted ? news : null;
+}
+/** What that row would say, for the one notice a poll sends. */
+export function newsOf(a) {
+    return {
+        // The click target is built from the ref, so the owner travels with it.
+        owner: a.pr.owner,
+        repo: a.pr.repo,
+        number: a.pr.number,
+        title: a.pr.title,
+        author: a.pr.author,
+        draft: a.status === "ready"
+            ? {
+                recommendation: a.verdict?.recommendation ?? null,
+                blockers: a.comments.filter((c) => c.status !== "dropped" && c.severity === "blocker").length,
+            }
+            : null,
+    };
+}
 /**
  * A PR title, as an AppleScript string literal.
  *