@fullstackhouse/cerber 0.23.0 → 0.24.1

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
@@ -371,6 +384,13 @@ shadow mode for a while: every would-send decision lands in
 verdicts and comments survive your review — enable auto-send when its 90%
 actually means 90%.
 
+## How it works
+
+[**docs/lifecycle.md**](docs/lifecycle.md) is the reference behind everything
+above: the seven statuses and what sets each, which tab a PR lands in and why,
+when the poll files or archives a row on its own, when a re-review happens and
+what it will not overwrite, and what gets written to disk at each step.
+
 ## Development
 
 ```bash

package/dist/cli/index.js

@@ -8,8 +8,9 @@ import { configPath, loadConfig, saveConfig } from "../core/config.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { parsePrRef, searchAwaitingMe, submitReview } from "../core/gh.js";
 import { buildReviewPayload, computeCalibration, eventForRecommendation } from "../core/send.js";
-import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, updateArtifactByKey, } from "../core/state.js";
+import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, reconcileRunning, updateArtifactByKey, } from "../core/state.js";
 import { pool, reviewPr } from "../runner/review.js";
+import { isReviewRunning } from "../runner/inflight.js";
 import { startDaemon } from "../server/daemon.js";
 import { startServer } from "../server/index.js";
 const program = new Command();
@@ -135,6 +136,15 @@ program
         console.error(`Already sent at ${artifact.sent.at}${artifact.sent.url ? ` — ${artifact.sent.url}` : ""}`);
         process.exit(1);
     }
+    // The persisted status is the only signal here: a run started by `serve` or
+    // by another terminal is invisible to this process. Sending mid-run vouches
+    // for a draft that is being replaced as you read it.
+    if (artifact.status === "running") {
+        console.error(`A review of ${id} is running — wait for it to finish, then send. ` +
+            `If nothing is actually running, the last run died mid-flight: re-run it, or restart \`cerber serve\`, ` +
+            `either of which clears the stale status.`);
+        process.exit(1);
+    }
     const event = (opts.event ??
         (artifact.verdict ? eventForRecommendation(artifact.verdict.recommendation) : "COMMENT")).toUpperCase();
     if (!["APPROVE", "COMMENT", "REQUEST_CHANGES"].includes(event)) {
@@ -313,6 +323,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, [])
@@ -351,6 +362,13 @@ program
             `matching PRs, with nobody watching. Pass --no-trust to keep every review read-only, ` +
             `or --no-auto-review to only review on click.`);
     }
+    // Before anything polls. Reconciliation is what makes "nothing is running"
+    // true after an unclean shutdown, and the daemon's first tick fires the
+    // moment it is constructed — so starting it first put both of them on the
+    // same leftover artifact with no ordering between them.
+    const cleared = await reconcileRunning({ inUse: isReviewRunning });
+    if (cleared > 0)
+        console.log(`Cleared ${cleared} interrupted run(s) left by a previous process.`);
     const daemon = opts.poll
         ? startDaemon({
             repos: opts.repo.length > 0 ? opts.repo : d.repos,
@@ -361,6 +379,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

@@ -97,6 +97,17 @@ export const RunInfoSchema = z.object({
      * be filed away automatically and one that must not be.
      */
     trigger: z.enum(["daemon", "user"]).nullable().default(null),
+    /**
+     * The head commit this run actually read, set when it finishes.
+     *
+     * `pr.headSha` cannot answer that question: a refresh moves it forward to
+     * keep the comments anchored to current code, without anybody re-reading
+     * anything. The freshness guard compares against *this* instead, so merely
+     * opening a draft after a push no longer convinces the poll that the draft
+     * is up to date. Null on runs recorded before this existed, and on one still
+     * in flight — both fall back to the old comparison.
+     */
+    reviewedSha: z.string().nullable().default(null),
 });
 export const SentInfoSchema = z.object({
     at: z.string(),

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/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/core/refresh.js

@@ -34,21 +34,48 @@ export function refreshArtifact(artifact, pr, diff) {
     };
 }
 /**
- * Comments a human put work into: their own, and AI ones they rewrote.
- * A re-review regenerates everything the AI said, but must not silently bin
- * these — see carryOverComments.
+ * Is this artifact's status the user's to keep, rather than the run's to set?
+ *
+ * A send or a settle is a decision about the PR; a run finishing is a fact
+ * about the code. Whichever way the run went — a draft or an error — it does
+ * not get to reopen one, which is the same rule `SETTLED_BY_YOU` applies to
+ * starting a run in the first place.
  */
-export function humanComments(artifact) {
-    return artifact.comments.filter((c) => c.origin === "user" || c.editedByUser);
+export function userOwnsStatus(a) {
+    return a.sent !== null || a.status === "reviewed" || a.status === "skipped";
 }
 /**
- * Carry a previous review's human comments into a fresh one, re-anchored to
- * the new diff. AI comments are dropped: the new run just regenerated them.
+ * Fold a finished review run onto whatever the artifact says now.
+ *
+ * A run takes minutes and the cockpit stays live throughout, so by the time one
+ * lands the artifact may have moved under it. Saving the result wholesale
+ * silently undid whatever had happened in between — the same mistake
+ * `mergeConcurrentEdits` exists to stop a chat turn making.
+ *
+ * `fresh` is what the run produced; `current` is what is on disk now. The run
+ * owns the draft — summary, chapters, verdict, comments — and that includes
+ * replacing comments the user wrote: a re-review starts fresh by design, and
+ * `docs/lifecycle.md` says so plainly rather than leaving anyone to count on
+ * work surviving one. What it does *not* own are the decisions:
+ *
+ *   - **a send** stands, and takes the status with it. Without this a run
+ *     finishing after a send wrote `sent: null` back over the record, and the
+ *     "already sent" guard would then wave a second submission through.
+ *   - **a settle** stands too: `reviewed` and `skipped` are decisions about the
+ *     PR, not facts about the code, so a run completing does not reopen one.
+ *     The fresh draft still lands underneath, which is what the row shows if
+ *     the user changes their mind.
+ *   - **the conversation** is the user's writing, snapshot and all.
  */
-export function carryOverComments(previous, fresh) {
-    const human = humanComments(previous);
-    if (human.length === 0)
-        return { comments: fresh.comments, carried: 0, drifted: 0 };
-    const { comments, drifted } = reanchorComments(human, previous.diff, fresh.diff);
-    return { comments: [...fresh.comments, ...comments], carried: comments.length, drifted };
+export function mergeRunResult(fresh, current) {
+    return {
+        ...fresh,
+        status: userOwnsStatus(current) ? current.status : fresh.status,
+        sent: current.sent,
+        calibration: current.calibration,
+        filed: current.filed,
+        chat: current.chat,
+        preChat: current.preChat,
+        pendingChat: current.pendingChat,
+    };
 }

package/dist/core/state.js

@@ -98,11 +98,21 @@ export async function updateArtifactByKey(key, mutate) {
  * this it stays wedged forever, with no way to retry it from the cockpit. A
  * `cerber review` running in another terminal is the one false positive; it
  * overwrites the artifact when it finishes anyway.
+ *
+ * `inUse` names the runs this process genuinely owns, and they are left alone.
+ * Callers should still reconcile before starting anything that polls — but
+ * ordering alone is a promise about wiring, and this is the guard that holds
+ * whatever order they are started in: without it, reconciliation racing a
+ * daemon's first tick could stamp "interrupted" over a review that had just
+ * legitimately begun.
  */
-export async function reconcileRunning() {
+export async function reconcileRunning(opts = {}) {
+    const inUse = opts.inUse ?? (() => false);
     const artifacts = await listArtifacts();
     let cleared = 0;
     for (const artifact of artifacts) {
+        if (inUse(artifact.id))
+            continue;
         const stuckRun = artifact.status === "running";
         const stuckChat = artifact.pendingChat && artifact.pendingChat.error == null ? artifact.pendingChat : null;
         if (!stuckRun && !stuckChat)

package/dist/runner/review.js

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { AiReviewSchema, SCHEMA_VERSION, artifactId, } from "../core/artifact.js";
+import { AiReviewSchema, SCHEMA_VERSION, artifactId, artifactKey, } from "../core/artifact.js";
 import { createRunDir, evictOldCheckouts, prepareCheckout, removeRunDir } from "../core/checkout.js";
 import { fetchPrDiff, fetchPrInfo, isOrgMember, isTeamMember } from "../core/gh.js";
-import { carryOverComments } from "../core/refresh.js";
-import { loadArtifact, saveArtifact } from "../core/state.js";
+import { mergeRunResult, userOwnsStatus } from "../core/refresh.js";
+import { loadArtifact, saveArtifact, updateArtifactByKey } from "../core/state.js";
 import { loadConfig } from "../core/config.js";
 import { decideTrust, membershipQueries, parseTrustRules } from "../core/trust.js";
 import { extractJson, runClaude, unauthenticatedEnv } from "./claude.js";
@@ -91,10 +91,15 @@ async function runReview(ref, opts) {
             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.`);
+        // The sha the AI *read*, not the one the artifact happens to mention.
+        // `pr.headSha` is moved forward by the refresh that runs whenever a review
+        // is opened, so comparing against it meant that merely looking at a draft
+        // after a push convinced this guard the draft was current, and the poll
+        // never re-reviewed it again. Older artifacts have no `reviewedSha` and
+        // fall back to the old comparison.
+        const reviewedSha = existing.run?.reviewedSha ?? existing.pr.headSha;
+        if (HEAD_SENSITIVE.has(existing.status) && reviewedSha !== "" && reviewedSha === pr.headSha) {
+            log(`Up to date (reviewed at ${reviewedSha.slice(0, 7)}, status ${existing.status}) — skipping. Use --force to re-review.`);
             return { artifact: existing, skipped: true };
         }
     }
@@ -120,6 +125,14 @@ async function runReview(ref, opts) {
                 `reviewing from the diff alone.`);
         }
     }
+    // A re-review regenerates the draft, comments and all — deliberately, and
+    // including any the user wrote. Carrying them across is a feature this tool
+    // has decided not to have, so nothing here tries to half-keep them: they go
+    // when the run starts, whichever way it ends. `docs/lifecycle.md` says so
+    // where a reader would otherwise assume otherwise.
+    if (existing && existing.comments.length > 0) {
+        log(`Replacing the previous draft's ${existing.comments.length} comment(s) — a re-review starts fresh.`);
+    }
     let artifact = {
         schemaVersion: SCHEMA_VERSION,
         id: artifactId(pr),
@@ -142,6 +155,7 @@ async function runReview(ref, opts) {
             trusted: trusted && source !== null,
             sessionId: null,
             trigger: opts.trigger ?? "user",
+            reviewedSha: null,
         },
         sent: null,
         refresh: null,
@@ -204,34 +218,37 @@ async function runReview(ref, opts) {
                 // whose working directory was empty has nothing a chat turn could read.
                 sessionId: source ? review.sessionId : null,
                 trigger: artifact.run.trigger,
+                // What this run actually read — the thing the freshness guard needs
+                // and `pr.headSha` cannot say, because a refresh moves that forward
+                // without anybody re-reading the code.
+                reviewedSha: pr.headSha,
             },
         };
-        // A re-review regenerates the AI's comments, but the human's own comments
-        // and their rewrites of AI ones are work the run must not throw away.
-        if (existing) {
-            const { comments, carried, drifted } = carryOverComments(existing, artifact);
-            if (carried > 0) {
-                artifact = { ...artifact, comments };
-                log(`Carried over ${carried} comment(s) you wrote or edited` +
-                    (drifted > 0 ? `; ${drifted} no longer match the diff and will post in the body.` : "."));
-            }
-        }
     }
     catch (err) {
-        artifact = {
-            ...artifact,
-            status: "failed",
-            updatedAt: now(),
-            run: {
-                ...artifact.run,
-                finishedAt: now(),
-                error: err instanceof Error ? err.message : String(err),
-            },
+        const run = {
+            ...artifact.run,
+            finishedAt: now(),
+            error: err instanceof Error ? err.message : String(err),
         };
-        await saveArtifact(artifact);
+        // Onto what is on disk, not over it: the artifact this run built holds none
+        // of the comments or marks that may have landed while it ran, and a failure
+        // is no reason to lose them — nor to reopen a decision the user made.
+        const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => ({
+            ...a,
+            status: userOwnsStatus(a) ? a.status : "failed",
+            run,
+        }));
+        artifact = saved ?? { ...artifact, status: "failed", run, updatedAt: now() };
+        if (!saved)
+            await saveArtifact(artifact);
         throw err;
     }
-    await saveArtifact(artifact);
+    const merged = await updateArtifactByKey(artifactKey(artifact.id), (current) => mergeRunResult(artifact, current));
+    if (merged)
+        artifact = merged;
+    else
+        await saveArtifact(artifact);
     return { artifact, skipped: false };
 }
 /** Run tasks with bounded concurrency, preserving order of results. */

package/dist/server/daemon.js

@@ -2,6 +2,7 @@ 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, 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";
@@ -140,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,
@@ -178,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) {
@@ -195,7 +199,7 @@ 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
@@ -333,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.
      *
@@ -410,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;
@@ -428,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 =
@@ -435,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);
         }