@fullstackhouse/cerber 0.29.0 → 0.30.0

package/README.md

@@ -88,17 +88,30 @@ 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.
-
-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
+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
+notifications from "Cerber" — because a notification can only open the app that
+posted it, and one posted the usual way belongs to Script Editor, which is
+where the click would otherwise land. A `notify-send` tap on Linux announces
+the PR but has no click to give.
+
+The cockpit has a bell of its own, which does the same from the page. 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

package/assets/cerber-icon.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024">
+  <!-- The app icon for the notifier bundle cerber builds under ~/.cerber, and
+       the source the committed assets/cerber.icns is rendered from (see the
+       note in src/core/notify.ts). Same paw as web/public/favicon.svg — an app
+       icon is a squircle on the shelf, so the mark is set on the brand tile
+       rather than floated on nothing, which at notification size reads as a
+       missing icon. -->
+  <defs>
+    <linearGradient id="tile" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#5f6ef2" />
+      <stop offset="1" stop-color="#2f3bbd" />
+    </linearGradient>
+  </defs>
+  <rect x="100" y="100" width="824" height="824" rx="185" fill="url(#tile)" />
+  <g fill="#fff" transform="translate(200 188) scale(26)">
+    <circle cx="6.1" cy="8.9" r="2.5" />
+    <circle cx="12" cy="6.7" r="2.7" />
+    <circle cx="17.9" cy="8.9" r="2.5" />
+    <ellipse cx="12" cy="16.6" rx="5.4" ry="4.3" />
+  </g>
+</svg>

package/dist/cli/index.js

@@ -13,7 +13,7 @@ import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, reconcileRunn
 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";
+import { cockpitUrl, startServer } from "../server/index.js";
 const program = new Command();
 program
     .name("cerber")
@@ -358,7 +358,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, [])
@@ -415,6 +415,13 @@ program
             trust: opts.trust ? undefined : false,
             autoReview: opts.autoReview,
             notify: opts.notify,
+            // The address as asked for, which the server corrects to the one it
+            // bound (`cockpitAt`) a moment later. Both, because neither alone
+            // is enough: the daemon's first poll runs while the port is still
+            // being bound, and a PR discovered on it would otherwise be
+            // announced with nowhere to click — while `--port 0` has no
+            // answer here at all, since the OS has not chosen yet.
+            cockpitUrl: cockpitUrl({ host: opts.host, port: Number(opts.port), token }) ?? undefined,
             autoSend: opts.autoSend ? "on" : "shadow",
             autoSendThreshold: threshold,
         })

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/notify.js

@@ -4,14 +4,37 @@
 // 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'`
+// posts as Script Editor — that is the app macOS sees making the call — so
+// clicking the tap opens Script Editor, an app the user never asked for and a
+// dead end from a notification about a PR. A notification can only open what
+// posted it, so cerber posts its own: a small app bundle built once under
+// `~/.cerber`, which opens the review in the cockpit when clicked. Where it
+// can't be built, the plain `osascript` tap is still better than silence.
 //
 // 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 { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { artifactId, artifactKey } from "./artifact.js";
+import { cerberHome } from "./state.js";
 const execFileAsync = promisify(execFile);
 /**
  * How long a notifier gets before the poll stops waiting for it.
@@ -25,23 +48,123 @@ 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"}`;
+}
 /**
- * One popup for one poll's arrivals — a batch is one interruption, not five.
+ * 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
+ * collapse to a space rather than splitting a line the applet reads back by
+ * line, or ending a string literal early.
+ */
+const flatten = (value) => value.replace(/[\u0000-\u001f\u007f]+/g, " ");
+/**
+ * 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.
+ *
+ * `cockpit` is where clicking it lands: the review itself when the notice is
+ * about exactly one PR, the queue when it is about several. It must be an
+ * 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) {
-    if (arrived.length === 0)
+export function notice(news, cockpit) {
+    if (news.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 base = cockpit || null;
+    if (news.length === 1) {
+        const a = news[0];
+        const key = artifactKey(artifactId(a));
+        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,
     };
 }
 /**
@@ -54,13 +177,15 @@ export function notice(arrived) {
  * 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}`)}"`;
+    return `"${flatten(value).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.
+ *
+ * On macOS this is the fallback rather than the first choice — see
+ * `ensureNotifierApp` for the one whose click opens the review.
  */
 export function notifyCommand(n, platform = process.platform) {
     if (platform === "darwin") {
@@ -83,6 +208,275 @@ export function notifyCommand(n, platform = process.platform) {
     }
     return null;
 }
+/**
+ * What the notification centre knows cerber by. Permission is granted to this
+ * identifier, once, by the user — so it has to survive every rebuild, or each
+ * new version of cerber would ask for notifications again as a stranger.
+ */
+export const BUNDLE_ID = "house.fullstack.cerber";
+/** Bumped whenever the applet or its plist changes, so an installed app is replaced. */
+const APP_BUILD = "3";
+const ICON = fileURLToPath(new URL("../../assets/cerber.icns", import.meta.url));
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+/**
+ * The app's whole job, in the only language a bundle this small can be written
+ * in without a compiler on the user's machine.
+ *
+ * It is launched twice per notification and has to tell the two apart with no
+ * arguments, because a click gives it none: macOS just opens the app that
+ * posted the notification. The pending file is what distinguishes them, and
+ * reading it is destructive — a launch that finds a notice posts it, a launch
+ * that finds none is the click on the last one, and opens where that one
+ * pointed. Nothing else can put the app in either state, so the two can't be
+ * confused.
+ *
+ * The paths are baked in rather than derived from the home folder, so a cerber
+ * running under CERBER_HOME talks to the app it actually built.
+ */
+export function appletSource(dir) {
+    const pending = appleScriptLiteral(path.join(dir, "pending.txt"));
+    const landing = appleScriptLiteral(path.join(dir, "url.txt"));
+    // `on run` is a launch from cold, `on reopen` a click while it is still up
+    // after posting — same job either way.
+    return `on run
+	tap()
+end run
+
+on reopen
+	tap()
+end reopen
+
+on tap()
+	set pendingFile to ${pending}
+	set urlFile to ${landing}
+	try
+		set raw to do shell script "cat " & quoted form of pendingFile & " 2>/dev/null; rm -f " & quoted form of pendingFile
+	on error
+		set raw to ""
+	end try
+	if raw is "" then
+		try
+			set target to do shell script "cat " & quoted form of urlFile & " 2>/dev/null"
+		on error
+			set target to ""
+		end try
+		-- Consumed on the way out, the same way the notice was: what is left
+		-- behind is what cerber reads as "an earlier notification is still
+		-- sitting there unclicked".
+		if target is not "" then
+			do shell script "open " & quoted form of target & "; rm -f " & quoted form of urlFile
+		else
+			do shell script "rm -f " & quoted form of urlFile
+		end if
+		return
+	end if
+	-- do shell script hands back the lines separated by return, not linefeed.
+	set AppleScript's text item delimiters to return
+	set parts to text items of raw
+	if (count of parts) < 2 then return
+	set target to ""
+	if (count of parts) > 2 then set target to item 3 of parts
+	-- umask, because the target carries the cockpit's token: nothing here is
+	-- another account's business to read.
+	do shell script "umask 077; printf %s " & quoted form of target & " > " & quoted form of urlFile
+	display notification (item 2 of parts) with title (item 1 of parts)
+end tap
+`;
+}
+/**
+ * Where a notice may point, given whether an earlier one is still sitting
+ * unclicked in Notification Centre.
+ *
+ * A click reaches the app with no arguments — macOS just opens whatever posted
+ * the notification — so one app can hold exactly one click target, and two
+ * outstanding notifications cannot be told apart. Pointing both at the newest
+ * review would open the wrong PR from the older notification, silently and
+ * convincingly. So the second one drops its fragment and both land on the
+ * queue, where every arrival is a row: less specific, never wrong.
+ *
+ * It heals itself. The target is consumed by the click that follows it, so the
+ * next notice after any click deep-links again; only a run of notifications
+ * nobody touches stays on the queue.
+ */
+export function clickTarget(url, outstanding) {
+    if (!url || !outstanding)
+        return url;
+    const fragment = url.indexOf("#");
+    return fragment < 0 ? url : url.slice(0, fragment);
+}
+/**
+ * The notice, as the app reads it back: title, body and click target, one line
+ * each. Flattened first — a newline in a PR title would otherwise shift every
+ * line after it, and the body would arrive as the URL.
+ */
+export function pendingPayload(n) {
+    return `${flatten(n.title)}\n${flatten(n.body)}\n${flatten(n.url ?? "")}\n`;
+}
+async function run(file, args) {
+    await execFileAsync(file, args, { timeout: NOTIFY_TIMEOUT_MS });
+}
+/**
+ * Set a key in the applet's Info.plist whether or not it is already there.
+ *
+ * `plutil -replace` is documented as overwriting an *existing* value — it does
+ * create a missing key in practice, but on undocumented behaviour, and every
+ * key this sets is one `osacompile` may or may not have written. A failure
+ * here fails the build and silently costs the click, so the documented
+ * inserting form is the fallback rather than the assumption.
+ */
+async function setPlistValue(plist, key, type, value) {
+    const flags = [key, type, value, plist];
+    await run("plutil", ["-replace", ...flags]).catch(() => run("plutil", ["-insert", ...flags]));
+}
+/**
+ * Build the app cerber posts through, into `~/.cerber/Cerber.app`.
+ *
+ * Three things here are load-bearing, each learned the way macOS teaches them —
+ * by dropping the notification and saying nothing:
+ *
+ *  - **A bundle identifier.** `osacompile` leaves the applet without one, and
+ *    a bundle with no identity gets its notifications denied.
+ *  - **A signature that matches.** Editing `Info.plist` invalidates the ad-hoc
+ *    signature `osacompile` writes, and a bundle whose seal is broken is denied
+ *    just as flatly. So it is re-signed, ad-hoc, after the edits.
+ *  - **A path LaunchServices will register.** A bundle under `/tmp` is never
+ *    resolved to an app, so the request for permission is never even asked.
+ *    `~/.cerber` is fine, and `lsregister` makes sure it is known before the
+ *    first notification rather than after it.
+ */
+async function buildNotifierApp(app, dir) {
+    // 0700: the notices left here hold the cockpit's URL, token and all.
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const source = path.join(dir, "applet.applescript");
+    await fs.writeFile(source, appletSource(dir));
+    // Staged in the one place LaunchServices refuses to register — the same
+    // refusal that makes a bundle under /tmp undeliverable also makes it
+    // unlaunchable, which is what a half-built app must be. Staged beside the
+    // real one it is a second app with cerber's own bundle identifier, and a
+    // launch that reaches it mid-build finds an applet with no script yet and
+    // puts up AppleScript's "Press Run to run this script" dialog.
+    //
+    // The name still ends in .app because osacompile picks what it writes from
+    // the extension, and anything else gets a bare script file with no bundle
+    // around it — no Info.plist, nothing to sign, nothing to post.
+    const stagingDir = await fs.mkdtemp(path.join(os.tmpdir(), "cerber-notifier-"));
+    try {
+        await assemble(path.join(stagingDir, "Cerber.app"), app, source);
+    }
+    finally {
+        // Every attempt, not just the ones that worked: a machine with no
+        // osacompile fails here once per process, and each failure would otherwise
+        // leave its half-built bundle behind for good.
+        await fs.rm(stagingDir, { recursive: true, force: true });
+    }
+}
+/** Everything between an empty staging directory and an installed, signed app. */
+async function assemble(staged, app, source) {
+    await run("osacompile", ["-o", staged, source]);
+    const plist = path.join(staged, "Contents", "Info.plist");
+    await setPlistValue(plist, "CFBundleIdentifier", "-string", BUNDLE_ID);
+    // An agent, not an app: cerber's notifier has no window and no business in
+    // the Dock or the app switcher for the second it spends posting.
+    await setPlistValue(plist, "LSUIElement", "-bool", "true");
+    // The applet ships an asset catalogue holding the generic script icon, and a
+    // catalogue wins over anything in Resources/ — so the paw only lands once the
+    // catalogue and the name it answers to are both gone.
+    const resources = path.join(staged, "Contents", "Resources");
+    await fs.rm(path.join(resources, "Assets.car"), { force: true });
+    await run("plutil", ["-remove", "CFBundleIconName", plist]).catch(() => { });
+    await fs.copyFile(ICON, path.join(resources, "applet.icns")).catch(() => {
+        // No icon is a generic icon, not a failure — the tap still works.
+    });
+    await run("codesign", ["--force", "--sign", "-", staged]);
+    // Not atomic, because a directory swap can't be: the window between these two
+    // is a few milliseconds in which a notification would fall back to osascript.
+    await fs.rm(app, { recursive: true, force: true });
+    try {
+        await fs.rename(staged, app);
+    }
+    catch {
+        // A CERBER_HOME on another volume: rename can't cross one, and a copy
+        // carries the signature with it — it lives in the bundle's own files.
+        await fs.cp(staged, app, { recursive: true });
+    }
+    await run(LSREGISTER, ["-f", app]).catch(() => {
+        // Best effort: `open` registers the bundle too, just later than we'd like.
+    });
+}
+/**
+ * One build attempt per home per process, whatever the answer.
+ *
+ * The poll awaits `announce`, so retrying a hopeless build every time a PR
+ * lands would spend a timeout apiece on a machine that is never going to have
+ * `osacompile`. A remembered failure falls back to the plain tap instead.
+ */
+const builds = new Map();
+export function ensureNotifierApp() {
+    // Resolved, because the paths go *into* the app: CERBER_HOME may be
+    // relative, and an app LaunchServices launches on a click inherits none of
+    // the daemon's working directory to resolve it against.
+    const home = path.resolve(cerberHome());
+    let building = builds.get(home);
+    if (!building) {
+        building = installNotifierApp(home).catch(() => null);
+        builds.set(home, building);
+    }
+    return building;
+}
+async function installNotifierApp(home) {
+    const app = path.join(home, "Cerber.app");
+    const dir = path.join(home, "notify");
+    const stamp = path.join(dir, "build");
+    const want = `${APP_BUILD} ${app}\n`;
+    const built = await fs
+        .stat(path.join(app, "Contents", "Info.plist"))
+        .then(() => true)
+        .catch(() => false);
+    if (built && (await fs.readFile(stamp, "utf8").catch(() => null)) === want)
+        return app;
+    await buildNotifierApp(app, dir);
+    await fs.writeFile(stamp, want);
+    return app;
+}
+/**
+ * Hand the notice to cerber's own app, so a click on it opens the review.
+ * False means the app couldn't take it and the caller should fall back — the
+ * tap matters more than which app posts it.
+ */
+async function postThroughApp(n) {
+    const app = await ensureNotifierApp();
+    if (!app)
+        return false;
+    // Beside the app that was actually built, rather than wherever CERBER_HOME
+    // points now — the paths the applet reads were baked into it at build time.
+    const dir = path.join(path.dirname(app), "notify");
+    const file = path.join(dir, "pending.txt");
+    const tmp = path.join(dir, `pending.${process.pid}.tmp`);
+    try {
+        // A target the app hasn't consumed means the notification it belongs to is
+        // still there to be clicked, and two of them cannot be told apart.
+        const outstanding = await fs
+            .stat(path.join(dir, "url.txt"))
+            .then(() => true)
+            .catch(() => false);
+        // tmp+rename, so the app can never read half a notice: it reads the file
+        // the instant `open` wakes it, and a partial one would post a PR title cut
+        // in two or a URL that leads nowhere.
+        // 0600 for the same reason the app's own write is: this line is the
+        // cockpit URL, and the cockpit URL carries the token that gets in.
+        await fs.writeFile(tmp, pendingPayload({ ...n, url: clickTarget(n.url, outstanding) }), {
+            mode: 0o600,
+        });
+        await fs.rename(tmp, file);
+        // -g, so a PR landing doesn't pull focus out of whatever you're doing.
+        await run("open", ["-g", app]);
+        return true;
+    }
+    catch {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        return false;
+    }
+}
 /**
  * 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
@@ -91,8 +485,10 @@ export function notifyCommand(n, platform = process.platform) {
  * 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);
+export async function notify(n, platform = process.platform) {
+    if (platform === "darwin" && (await postThroughApp(n)))
+        return true;
+    const cmd = notifyCommand(n, platform);
     if (!cmd)
         return false;
     try {

package/dist/core/refresh.js

@@ -76,6 +76,8 @@ export function mergeRunResult(fresh, current) {
         // the stamp away with the status.
         settledAt: userOwnsStatus(current) ? current.settledAt : fresh.settledAt,
         sent: current.sent,
+        // Disk wins: the ledger is the poll's, and the run knows nothing about it.
+        notified: current.notified,
         calibration: current.calibration,
         filed: current.filed,
         chat: current.chat,

package/dist/core/revise.js

@@ -63,6 +63,9 @@ export function mergeConcurrentEdits(before, after, current) {
         // A turn never writes a send body, so one written while it ran is the
         // user's and stands — as does clearing one.
         bodyOverride: current.bodyOverride,
+        // Nor does a turn announce anything: the ledger is the poll's, and a turn
+        // takes minutes, which is long enough for a poll to have stamped it.
+        notified: current.notified,
     };
 }
 export function applyRevisions(artifact, revisions, opts = {}) {