@fullstackhouse/cerber 0.22.0 → 0.24.0

package/README.md

@@ -41,9 +41,9 @@ 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. The queue only lists what
+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
@@ -88,15 +88,28 @@ who did is the one mistake worth designing against.
 
 ### It taps you on the shoulder
 
-The cockpit is a background tab most of the day, so it tells you when the queue
-grows: a desktop notification naming the PR that arrived — click it to open the
-review — folded into one popup when several land at once. It stays quiet while
-you're looking straight at cerber, and no browser announces the same PR twice.
-Only the browser can grant this, and only off a click, so the bell in the top
-bar is one: click it to be asked, click it again to stop. Both the switch and
-the record of what has been announced are per-browser, kept in that browser
-rather than in `~/.cerber/config.json` — the permission they gate is the
-browser's, so a second browser starts its own record.
+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.
+
+The cockpit has a bell of its own, and it is the better one where it can ring:
+its notification **opens that review when you click it**. But it is a page
+notification — it needs a tab that is open, alive and permitted, which is
+exactly what you don't have on the afternoons this feature is for. So it stands
+down while the machine's own tap is on, rather than making one PR two popups,
+and the bell in the top bar says so. Untick the machine one and this browser
+takes over: click the bell, grant the permission, and click it again to stop.
+The switch and the record of what has been announced are per-browser — the
+permission they gate is the browser's, so a second browser starts its own
+record — and it stays quiet while you're looking straight at cerber.
+
+A cockpit served from somewhere else (`cerber serve -H 0.0.0.0 --token` on a
+VPS) keeps its bell either way: the machine's tap would land on the VPS, where
+nobody is looking.
 
 The tab itself says it too, without asking anyone: while the inbox holds
 anything, the favicon wears a red dot, and it goes away when the last review is

package/dist/cli/index.js

@@ -313,6 +313,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("-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, [])
@@ -361,6 +362,7 @@ program
             withSource: opts.source,
             trust: opts.trust ? undefined : false,
             autoReview: opts.autoReview,
+            notify: opts.notify,
             autoSend: opts.autoSend ? "on" : "shadow",
             autoSendThreshold: threshold,
         })

package/dist/core/artifact.js

@@ -108,19 +108,34 @@ export const SentInfoSchema = z.object({
 /**
  * Why a draft was filed away without ever being sent.
  *
- * The only cause today is the one the queue could not see before: you reviewed
- * the PR through GitHub itself, so cerber's draft is a second opinion on a
- * conversation you already had. It is a record, not a decision to defend — the
- * review is untouched, still openable and still sendable.
+ * All three causes are the same shape of fact: the inbox was still holding a
+ * row out for you that GitHub had already moved past. You reviewed the PR
+ * through GitHub itself; you answered in the conversation and nobody has
+ * answered back; or whoever asked for the review took the request away. It is
+ * a record, not a decision to defend — the review is untouched, still openable
+ * and still sendable.
+ *
+ * `reason` defaults to the one that shipped first, so artifacts written before
+ * the other two existed load unchanged and keep saying what they always said.
  */
+export const FiledReasonSchema = z.enum(["own-review", "own-reply", "request-withdrawn"]);
 export const FiledInfoSchema = z.object({
     at: z.string(),
-    /** The review of yours GitHub had, which is what settled this one. */
-    review: z.object({
+    reason: FiledReasonSchema.default("own-review"),
+    /** The review of yours GitHub had. Set when `reason` is "own-review". */
+    review: z
+        .object({
         at: z.string(),
         state: z.enum(["APPROVED", "CHANGES_REQUESTED", "COMMENTED"]),
         url: z.string().nullable().default(null),
-    }),
+    })
+        .nullable()
+        .default(null),
+    /** The comment that gave you the last word. Set when `reason` is "own-reply". */
+    reply: z
+        .object({ at: z.string(), url: z.string().nullable().default(null) })
+        .nullable()
+        .default(null),
 });
 /** Result of pulling a review forward onto a newer head commit. */
 export const RefreshInfoSchema = z.object({

package/dist/core/config.js

@@ -22,6 +22,12 @@ export const DaemonConfigSchema = z.object({
     poll: z.boolean().default(true),
     /** 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.
+     */
+    notify: z.boolean().default(true),
     intervalMinutes: z.number().int().positive().default(5),
     parallel: z.number().int().positive().default(3),
     /** Repos to watch (owner/repo). Empty = everything your gh account can see. */

package/dist/core/gh.js

@@ -132,7 +132,7 @@ export async function fetchConversation(ref) {
         "--paginate",
         `repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments`,
         "--jq",
-        '.[] | {author: .user.login, at: .created_at, bot: (.user.type == "Bot")}',
+        '.[] | {author: .user.login, at: .created_at, bot: (.user.type == "Bot"), url: .html_url}',
     ]);
     // --jq streams one object per line rather than a JSON array.
     return out
@@ -158,6 +158,21 @@ export function classifyReply(comments, login) {
     // answer to it, so only strictly-later comments hand the move back.
     return human.some((c) => c.author !== login && c.at > lastMine) ? "them" : "you";
 }
+/**
+ * The comment that gave you the last word, or null if it isn't yours.
+ *
+ * Answers "you have said your piece and nobody has answered since" with the
+ * comment that says it, so a draft filed on the strength of it can point at
+ * the thing on GitHub it was filed for. Routed through `classifyReply` rather
+ * than re-deriving the rule, so the tag on a row and the reason it was filed
+ * can never disagree about who spoke last.
+ */
+export function lastWordOfYours(comments, login) {
+    if (classifyReply(comments, login) !== "you")
+        return null;
+    const mine = comments.filter((c) => !isBot(c) && c.author === login);
+    return mine[mine.length - 1] ?? null;
+}
 /**
  * The last review of your own that still stands, or null.
  *
@@ -206,6 +221,39 @@ export function currentLogin() {
 export function resetLoginCache() {
     cachedLogin = null;
 }
+export async function fetchReviewRequests(ref) {
+    const out = await gh([
+        "pr",
+        "view",
+        String(ref.number),
+        "--repo",
+        `${ref.owner}/${ref.repo}`,
+        "--json",
+        "reviewRequests",
+    ]);
+    const raw = JSON.parse(out);
+    const users = [];
+    const teams = [];
+    for (const r of raw.reviewRequests ?? []) {
+        if (r.login)
+            users.push(r.login);
+        else if (r.slug ?? r.name)
+            teams.push((r.slug ?? r.name));
+    }
+    return { users, teams };
+}
+/**
+ * Whether GitHub might still be asking *you*, specifically.
+ *
+ * A team request names the team and not its members, so it can never rule you
+ * out — and a membership lookup to settle it would be a third call to answer a
+ * question whose only use is deciding not to act. Treating any team request as
+ * possibly-you costs one draft left in the inbox; the other way round files
+ * away a review someone is waiting on.
+ */
+export function stillRequested(requests, login) {
+    return requests.teams.length > 0 || requests.users.includes(login);
+}
 export function searchAwaitingArgs(repoFilter, limit = 50) {
     const args = [
         "search",

package/dist/core/notify.js

@@ -0,0 +1,105 @@
+// The machine's own shoulder-tap, for the hours the cockpit isn't open.
+//
+// The cockpit has a bell of its own (`web/src/notify.ts`), and it is the better
+// 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.
+//
+// Everything here shells out to whatever the OS already has. No dependency, no
+// daemon of its own, and a machine with no notifier is a machine cerber stays
+// quiet on rather than one it fails on.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * How long a notifier gets before the poll stops waiting for it.
+ *
+ * A notification is instant or it is broken, and the thing on the other end of
+ * this is somebody else's daemon: a wedged Notification Centre or a DBus that
+ * never answers would otherwise hang `execFile` forever. The poll awaits this
+ * call, and the daemon refuses to start a poll while one is running — so an
+ * unbounded wait here doesn't cost one notification, it stops cerber
+ * discovering PRs at all. Timing out is caught like any other failure.
+ */
+export const NOTIFY_TIMEOUT_MS = 5_000;
+const slug = (a) => `${a.repo}#${a.number}`;
+/**
+ * One popup for one poll's arrivals — 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.
+ */
+export function notice(arrived) {
+    if (arrived.length === 0)
+        return null;
+    if (arrived.length === 1) {
+        const a = arrived[0];
+        return { title: `${slug(a)} awaits your review`, body: `${a.title} — ${a.author}` };
+    }
+    const named = arrived.slice(0, 3).map(slug);
+    const rest = arrived.length - named.length;
+    return {
+        title: `${arrived.length} PRs await your review`,
+        body: rest > 0 ? `${named.join(", ")} and ${rest} more` : named.join(", "),
+    };
+}
+/**
+ * A PR title, as an AppleScript string literal.
+ *
+ * osascript takes a script, not an argument list, so the title has to go into
+ * the source — and a PR title is text somebody else wrote. Escaping the two
+ * characters a literal cannot hold, a backslash and a quote, is what stops a
+ * title from closing the string and being read as script. Control characters
+ * can't appear in a literal at all, so they collapse to a space.
+ */
+export function appleScriptLiteral(value) {
+    const flat = value.replace(/[\u0000-\u001f\u007f]+/g, " ");
+    return `"${flat.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+}
+/**
+ * The command that taps this machine's notification centre, or null where there
+ * is nothing to tap. macOS and the freedesktop notifiers cover what cerber runs
+ * on; anywhere else it stays quiet rather than pretending.
+ */
+export function notifyCommand(n, platform = process.platform) {
+    if (platform === "darwin") {
+        return {
+            file: "osascript",
+            args: [
+                "-e",
+                `display notification ${appleScriptLiteral(n.body)} with title ${appleScriptLiteral(n.title)}`,
+            ],
+        };
+    }
+    if (platform === "linux") {
+        // `--` first, because notify-send parses options before positionals. The
+        // PR's own title reaches this as the notice *body* (`notice()` builds the
+        // summary itself), so the body is the argument carrying somebody else's
+        // text — a PR titled "--help me" would be read as a flag and cost the
+        // notification. The marker ends option parsing ahead of both arguments, so
+        // neither the summary nor the body can be read as anything but text.
+        return { file: "notify-send", args: ["--app-name=cerber", "--", n.title, n.body] };
+    }
+    return null;
+}
+/**
+ * Show it, and say whether it was shown. False is an ordinary answer here —
+ * an unsupported platform, no `notify-send` installed, a headless box, a
+ * notifier that took too long — and the caller reports it once rather than
+ * every poll. Never throws and never hangs: a notification is the least
+ * important thing a poll does, so it is also the last thing allowed to stop
+ * one.
+ */
+export async function notify(n) {
+    const cmd = notifyCommand(n);
+    if (!cmd)
+        return false;
+    try {
+        await execFileAsync(cmd.file, cmd.args, { timeout: NOTIFY_TIMEOUT_MS });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runner/review.js

@@ -16,8 +16,23 @@ const OFF_TOOLS = ["Bash", "Edit", "Write", "NotebookEdit", "Task", "WebFetch",
 /** A trusted reviewer may run things. It still may not rewrite the PR. */
 const TRUSTED_TOOLS = [...READ_TOOLS, "Bash", "WebFetch", "WebSearch"];
 const TRUSTED_OFF_TOOLS = ["Edit", "Write", "NotebookEdit"];
-/** Statuses that a fresh artifact can keep without a re-run. */
-const FRESH_STATUSES = new Set(["ready", "reviewed", "sent", "skipped"]);
+/**
+ * Statuses a re-review may overwrite once the PR has moved on. A draft nobody
+ * has acted on should track the current head, and a sent review has cleared
+ * GitHub's request — a fresh one only ever arrives because the author asked
+ * again, which is exactly when a new draft is the point.
+ */
+const HEAD_SENSITIVE = new Set(["ready", "sent"]);
+/**
+ * Statuses that are your decision, not a fact about the code.
+ *
+ * Marking a review reviewed or skipped says you are done with this PR. New
+ * commits do not undo that: the author pushing again would otherwise drag the
+ * row back into the inbox with a fresh draft on top, which is the same thing
+ * as cerber overruling you — and on a busy PR it happens every few minutes.
+ * The way back in is the way you got out: press re-review, which forces.
+ */
+const SETTLED_BY_YOU = new Set(["reviewed", "skipped"]);
 /**
  * Fetch a PR, run the AI review, persist the artifact at each stage.
  * Everything stays local — nothing is ever written to GitHub.
@@ -71,9 +86,12 @@ async function runReview(ref, opts) {
     log(`Fetching ${ref.owner}/${ref.repo}#${ref.number}…`);
     const pr = await fetchPrInfo(ref);
     const existing = await loadArtifact(artifactId(pr));
-    if (!opts.force) {
-        if (existing &&
-            FRESH_STATUSES.has(existing.status) &&
+    if (existing && !opts.force) {
+        if (SETTLED_BY_YOU.has(existing.status)) {
+            log(`You marked this ${existing.status} — leaving it alone. Use --force to re-review.`);
+            return { artifact: existing, skipped: true };
+        }
+        if (HEAD_SENSITIVE.has(existing.status) &&
             existing.pr.headSha !== "" &&
             existing.pr.headSha === pr.headSha) {
             log(`Up to date (head ${pr.headSha.slice(0, 7)}, status ${existing.status}) — skipping. Use --force to re-review.`);

package/dist/server/daemon.js

@@ -1,7 +1,8 @@
 import { SCHEMA_VERSION, artifactId, artifactKey } from "../core/artifact.js";
 import { evaluateAutoSend } from "../core/autosend.js";
 import { loadConfig } from "../core/config.js";
-import { classifyReply, currentLogin, fetchConversation, fetchOwnReview, fetchPrInfo, searchAwaitingMe, submitReview, } from "../core/gh.js";
+import { classifyReply, currentLogin, fetchConversation, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
+import { notice, notify } from "../core/notify.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
 import { appendAutoSendLog, deleteArtifact, listArtifacts, loadArtifact, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { ReviewInProgressError } from "../runner/inflight.js";
@@ -67,21 +68,25 @@ export function isPureStub(artifact) {
     return artifact.status === "awaiting" && artifact.comments.length === 0 && artifact.run === null;
 }
 /**
- * Whether a review of yours on GitHub settles this draft.
+ * Whether something you did on GitHub at `at` settles this draft.
  *
  * Two facts have to hold. GitHub must have stopped asking you — the caller has
  * already established that, since this only runs on artifacts absent from the
- * awaiting search — and you must have submitted a review of your own, which is
- * the half cerber could not see before: a review clears the request whether it
- * went through Send or through GitHub's own button, and only the first left a
- * trace here. Together they mean the PR is back with its author, while the
- * inbox went on listing the draft as work still waiting on you.
+ * awaiting search — and you must have had your say, which is the half cerber
+ * could not see before: it happens on github.com and leaves no trace here.
+ * Together they mean the PR is back with its author, while the inbox went on
+ * listing the draft as work still waiting on you.
+ *
+ * Having your say is a review of your own or a comment nobody has answered
+ * since. GitHub counts only the first as a review — a comment leaves the
+ * request standing — but the question here is not what GitHub counts, it is
+ * whether the row is still work. Somebody waiting on the author is not.
  *
  * The trigger test is what keeps this from undoing a deliberate act. A draft
  * you asked for — pasted the URL in, pressed re-review — after you had already
- * reviewed the PR is a second opinion you went and requested, so filing it
- * away would answer a question you had just posed. A draft the poll wrote on
- * its own carries no such intent: it is exactly the row this is here to close.
+ * spoken is a second opinion you went and requested, so filing it away would
+ * answer a question you had just posed. A draft the poll wrote on its own
+ * carries no such intent: it is exactly the row this is here to close.
  *
  * A run recorded before the trigger was kept is treated as the poll's, which is
  * the deliberate choice: the alternative leaves every draft written before this
@@ -89,15 +94,33 @@ export function isPureStub(artifact) {
  * is one legacy draft filed once — and the re-review that un-files it records a
  * trigger, so it cannot happen to the same row twice.
  */
-export function filedByOwnReview(artifact, review) {
-    if (artifact.status !== "ready" || artifact.sent || !review)
+export function filedByYourAct(artifact, at) {
+    if (artifact.status !== "ready" || artifact.sent || at === null)
         return false;
     const run = artifact.run;
     // Parsed, not compared as text. `startedAt` carries milliseconds and GitHub's
     // `submitted_at` does not, and "…:00.500Z" sorts *before* "…:00Z" — so a run
     // that began half a second after your review would read as older than it, and
     // the second opinion this guard exists to protect would be filed away.
-    return !(run?.trigger === "user" && Date.parse(run.startedAt) >= Date.parse(review.at));
+    return !(run?.trigger === "user" && Date.parse(run.startedAt) >= Date.parse(at));
+}
+/**
+ * Whether a review request that simply went away settles this draft.
+ *
+ * The other two reasons rest on something you did; this one rests on something
+ * that stopped being true, which is a weaker kind of evidence and gets a
+ * stricter guard for it. Only a draft the poll wrote on its own can be filed
+ * this way: the poll only ever writes one because GitHub asked you, so the
+ * request going away is the whole of that draft's reason for existing going
+ * away. A draft you pasted in or asked for was never in that search to begin
+ * with, and `null` — a run older than the trigger field — cannot be told from
+ * one, so neither qualifies. Unlike the own-review case there is no second
+ * fact to fall back on, so an unknown here has to mean no.
+ */
+export function filedByWithdrawnRequest(artifact) {
+    if (artifact.status !== "ready" || artifact.sent)
+        return false;
+    return artifact.run?.trigger === "daemon";
 }
 /** How many open-PR artifacts to re-check against GitHub per poll, and how often each. */
 const STATE_REFRESH_CAP = 10;
@@ -118,6 +141,9 @@ export function startDaemon(opts) {
         repos: opts.repos,
         intervalMs: opts.intervalMs,
         pollEnabled: true,
+        // Claims nothing until a poll has read the config, so the cockpit's bell
+        // keeps its own counsel for the few seconds that takes.
+        notify: false,
         autoReview: opts.autoReview,
         trustedRuns: false,
         polls: 0,
@@ -156,7 +182,7 @@ export function startDaemon(opts) {
      * search results lag GitHub by minutes and never override them.
      */
     async function syncQueue(refs) {
-        let discovered = 0;
+        const discovered = [];
         for (const ref of refs) {
             const existing = await loadArtifact(artifactId(ref));
             if (existing) {
@@ -173,22 +199,35 @@ export function startDaemon(opts) {
                 continue;
             }
             await saveArtifact(stubArtifact(ref));
-            discovered++;
+            discovered.push(ref);
         }
         // Asked once per pass, and only if a row actually reaches the check that
         // needs it. Undefined is "not asked yet"; null is "gh could not say", which
         // attributes nothing to you rather than guessing.
         let login;
         /**
-         * File a draft away once GitHub says you already reviewed the PR yourself.
+         * File a draft away once GitHub has moved past it without cerber's help.
+         *
+         * The queue lists what you have not dealt with locally, and everything that
+         * happens on github.com is invisible to it — so a PR you answered days ago
+         * sat in the inbox as if it still wanted you. Three ways that happens, in
+         * the order of how much they say:
          *
-         * The queue lists what you have not dealt with locally, and a review
-         * submitted on github.com never reached it — so a PR you answered days ago
-         * sat in the inbox as if it still wanted you. This is the one read that
-         * closes that gap, on the same 30-minute-per-artifact leash as the state
-         * check it rides along with.
+         *   1. You submitted a review there. The strongest: GitHub itself counts it.
+         *   2. You commented and nobody has answered since. Not a review as far as
+         *      GitHub is concerned, but the ball is still in the author's court.
+         *   3. Nobody is asking any more. You never said anything; whoever
+         *      requested you took the request back, or the PR got its reviews
+         *      elsewhere. Nothing left here is work.
+         *
+         * Someone answering your comment (`them`) is the case that deliberately
+         * files nothing: that is a reply addressed to you, sitting on a PR whose
+         * draft is right here.
+         *
+         * All of it rides the same 30-minute-per-artifact leash as the state check
+         * it hangs off, so a queue of a hundred rows is still a handful of calls.
          */
-        async function fileIfYouReviewedItYourself(artifact) {
+        async function fileIfSettledElsewhere(artifact) {
             // Only a finished, unsent draft can be filed — checked here too, so a row
             // that could never qualify costs no GitHub call at all.
             if (artifact.status !== "ready" || artifact.sent)
@@ -197,17 +236,45 @@ export function startDaemon(opts) {
                 login = await currentLogin().catch(() => null);
             if (login === null)
                 return;
-            const review = await fetchOwnReview(artifact.pr, login);
-            if (!review || !filedByOwnReview(artifact, review))
+            const me = login;
+            /** Re-reads from disk: a run or a send may have started in the seconds
+             *  these reads took, and neither wants filing out from under it. */
+            async function file(filed, note, stillFilable) {
+                const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => stillFilable(a) ? { ...a, status: "reviewed", filed } : a);
+                if (saved?.filed)
+                    log(`[${artifact.id}] ${note} — filed as reviewed`);
+            }
+            const review = await fetchOwnReview(artifact.pr, me);
+            if (review) {
+                // A review of yours is the answer either way: if the guard rejects it,
+                // this is a second opinion you asked for, not a row to keep looking for
+                // another reason to file.
+                if (filedByYourAct(artifact, review.at)) {
+                    await file({ at: new Date().toISOString(), reason: "own-review", review, reply: null }, `you reviewed this on GitHub on ${review.at.slice(0, 10)}`, (a) => filedByYourAct(a, review.at));
+                }
+                return;
+            }
+            const conversation = await fetchConversation(artifact.pr);
+            const mine = lastWordOfYours(conversation, me);
+            if (mine) {
+                if (filedByYourAct(artifact, mine.at)) {
+                    const reply = { at: mine.at, url: mine.url };
+                    await file({ at: new Date().toISOString(), reason: "own-reply", review: null, reply }, `you replied on GitHub on ${mine.at.slice(0, 10)} and nobody has answered since`, (a) => filedByYourAct(a, mine.at));
+                }
                 return;
-            const filed = { at: new Date().toISOString(), review };
-            const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => 
-            // Re-read from disk: a run or a send may have started in the seconds
-            // this read took, and neither wants filing out from under it.
-            filedByOwnReview(a, review) ? { ...a, status: "reviewed", filed } : a);
-            if (saved?.filed) {
-                log(`[${artifact.id}] you reviewed this on GitHub on ${review.at.slice(0, 10)} — filed as reviewed`);
             }
+            // Anything but silence from you leaves the row alone: `them` is somebody
+            // answering a comment of yours, which is the opposite of settled.
+            if (classifyReply(conversation, me) !== "none")
+                return;
+            if (!filedByWithdrawnRequest(artifact))
+                return;
+            // The awaiting search says nobody is asking, and here that is the entire
+            // case — so confirm it against the PR itself before acting on it. The
+            // other two reasons stand on a fact of their own and need no such check.
+            if (stillRequested(await fetchReviewRequests(artifact.pr), me))
+                return;
+            await file({ at: new Date().toISOString(), reason: "request-withdrawn", review: null, reply: null }, "nobody is asking for this review any more", filedByWithdrawnRequest);
         }
         const awaitingIds = new Set(refs.map((r) => artifactId(r)));
         let refreshed = 0;
@@ -262,7 +329,7 @@ export function startDaemon(opts) {
                 if (pr.state !== "OPEN")
                     log(`[${artifact.id}] ${pr.state.toLowerCase()} — archived`);
                 else
-                    await fileIfYouReviewedItYourself(artifact);
+                    await fileIfSettledElsewhere(artifact);
             }
             catch {
                 // Same: book-keeping can wait for the next poll.
@@ -270,6 +337,41 @@ export function startDaemon(opts) {
         }
         return { discovered };
     }
+    /** Said once, not every poll: a machine with no notifier will never grow one. */
+    let notifierMissing = false;
+    /**
+     * What the last attempt to tap this machine actually did, or null before one
+     * has been made.
+     *
+     * `status.notify` is a promise to the cockpit — it stands its own bell down
+     * on the strength of it — so it has to mean "this machine gets told", not
+     * "this machine was asked to tell". A box with no `notify-send` would
+     * otherwise go on claiming the job while the browser politely declined it,
+     * and one PR would be announced by nobody at all. Untried counts as working:
+     * the alternative is both bells ringing everywhere until the first PR lands.
+     */
+    let notifierWorks = null;
+    /**
+     * Tap this machine when a PR lands in the queue.
+     *
+     * An artifact is the ledger this rides on: a PR is announced on the poll that
+     * first writes a stub for it, so a restart re-announces nothing, and a PR
+     * that arrived while `serve` was down is still news the next time it runs.
+     * The cockpit's bell announces the same arrival, off the same stub — which is
+     * why it stands down when this is on and both are on one machine.
+     */
+    async function announce(arrivals) {
+        const n = notice(arrivals);
+        if (!n)
+            return;
+        notifierWorks = await notify(n);
+        if (notifierWorks)
+            return;
+        if (notifierMissing)
+            return;
+        notifierMissing = true;
+        log("no desktop notifier here — arrivals will only show in the cockpit");
+    }
     /**
      * Whose move it is on each awaiting PR, one conversation read apiece.
      *
@@ -347,6 +449,14 @@ export function startDaemon(opts) {
             const knobs = config.daemon;
             const autoReview = opts.autoReview && knobs.autoReview;
             status.pollEnabled = knobs.poll;
+            // What the cockpit's bell defers to: a loop that isn't polling announces
+            // nothing, whatever the notify toggle says.
+            const notifyOn = opts.notify && knobs.notify;
+            // Only true while all three hold, and the third is only knowable by
+            // having tried: a notifier that isn't there is not a bell the cockpit
+            // should be standing down for.
+            const announcing = () => knobs.poll && notifyOn && notifierWorks !== false;
+            status.notify = announcing();
             status.autoReview = autoReview;
             // Recomputed too, so a trust rule added mid-run shows up in the strip.
             status.trustedRuns = autoReview && opts.trust !== false && config.trust.length > 0;
@@ -365,6 +475,16 @@ export function startDaemon(opts) {
             // A failed poll leaves the last good list up; lastPollError says so.
             status.awaiting = await classifyAll(refs);
             const { discovered } = await syncQueue(refs);
+            // Before the reviews, not after: the arrival is the news, and drafting it
+            // takes minutes. This is the same moment the cockpit's bell would ring.
+            if (notifyOn && discovered.length > 0) {
+                await announce(discovered);
+                // Recomputed on the spot rather than left to the next poll: that is
+                // minutes away, and the cockpit would spend them deferring to a tap
+                // that never came. Recomputed rather than only cleared, so a machine
+                // whose notifier comes back takes the job back with it.
+                status.notify = announcing();
+            }
             if (autoReview) {
                 const { reviewed, skipped, failed } = await reviewAll(refs);
                 status.lastSummary =
@@ -372,7 +492,7 @@ export function startDaemon(opts) {
                         `${failed > 0 ? `, ${failed} failed` : ""}`;
             }
             else {
-                status.lastSummary = `${refs.length} awaiting${discovered > 0 ? `, ${discovered} new` : ""} (auto-review off)`;
+                status.lastSummary = `${refs.length} awaiting${discovered.length > 0 ? `, ${discovered.length} new` : ""} (auto-review off)`;
             }
             log(status.lastSummary);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "author": "Full Stack House (https://fullstack.house)",