@fullstackhouse/cerber 0.28.0 → 0.29.1

package/README.md

@@ -96,9 +96,15 @@ 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
+**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")
@@ -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

@@ -274,6 +274,19 @@ export const ArtifactSchema = z.object({
     chapters: z.array(ChapterSchema).default([]),
     comments: z.array(CommentSchema).default([]),
     verdict: VerdictSchema.nullable().default(null),
+    /**
+     * The review body to post, written by hand. Null — the normal case — means
+     * the body is composed from the draft at send time (§14.4: summary,
+     * walkthrough, the comments that cannot post inline, footer).
+     *
+     * Everywhere else in cerber, what GitHub gets is derived from what the
+     * cockpit shows. This is the one place the user can cut that link, so it is
+     * a field rather than a rewrite of the summary: the draft underneath stays
+     * exactly as the review wrote it, the body can always be built again, and
+     * the send panel says which of the two is about to be posted. A re-review
+     * clears it — it described a body for a draft that no longer exists.
+     */
+    bodyOverride: z.string().nullable().default(null),
     run: RunInfoSchema.nullable().default(null),
     /** Set once the review was sent to GitHub (explicitly, or via opt-in auto-send). */
     sent: SentInfoSchema.nullable().default(null),

package/dist/core/history.js

@@ -161,6 +161,12 @@ export function describeChange(before, after) {
         lines.push(`verdict ${wasVerdict ? "changed to" : "set to"} ${verdict.recommendation.replace("_", " ")}` +
             ` (${verdict.confidence}% sure of the findings)`);
     }
+    // What posts stopped following the draft, or started following it again.
+    if ((before?.bodyOverride ?? null) !== (after.bodyOverride ?? null)) {
+        lines.push(after.bodyOverride == null
+            ? "the body to post follows the review again"
+            : "the body to post was written by hand");
+    }
     const comments = describeComments(before?.comments ?? [], after.comments);
     if (comments)
         lines.push(comments);

package/dist/core/notify.js

@@ -7,11 +7,26 @@
 // 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.
 //
+// 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 +40,42 @@ const execFileAsync = promisify(execFile);
  */
 export const NOTIFY_TIMEOUT_MS = 5_000;
 const slug = (a) => `${a.repo}#${a.number}`;
+/**
+ * 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 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.
+ *
+ * `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) {
+export function notice(arrived, cockpit) {
     if (arrived.length === 0)
         return null;
+    const base = cockpit || null;
     if (arrived.length === 1) {
         const a = arrived[0];
-        return { title: `${slug(a)} awaits your review`, body: `${a.title} — ${a.author}` };
+        const key = artifactKey(artifactId(a));
+        return {
+            title: `${slug(a)} awaits your review`,
+            body: `${a.title} — ${a.author}`,
+            url: base && `${base}#/r/${encodeURIComponent(key)}`,
+        };
     }
     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(", "),
+        url: base,
     };
 }
 /**
@@ -54,13 +88,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 +119,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 +396,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/revise.js

@@ -60,6 +60,9 @@ export function mergeConcurrentEdits(before, after, current) {
         // there only when it actually revised one.
         status: current.status,
         verdict: after.verdict === before.verdict ? current.verdict : after.verdict,
+        // 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,
     };
 }
 export function applyRevisions(artifact, revisions, opts = {}) {

package/dist/core/send.js

@@ -49,7 +49,16 @@ export function buildReviewPayload(artifact, event) {
     parts.push("", "---", "_Reviewed with [cerber](https://github.com/fullstackhouse/cerber) 🐕 — drafted by AI, sent by a human._");
     return {
         event,
-        body: parts.join("\n").trim(),
+        // A body the user wrote by hand replaces the composed one outright,
+        // footer and folded notes included: it is the review's own comment, and
+        // half-honouring it — keeping a footer they deleted, re-appending notes
+        // they cut — would post something nobody wrote. It is not trimmed either,
+        // which is not fussiness: a body opening on an indented line is a markdown
+        // code block, and trimming it would silently repaint it as a paragraph.
+        // Only the composed body is trimmed — the parts above put a blank line in
+        // front of it. The composition still runs regardless, because `folded` is
+        // what the cockpit uses to say which comments have no line to land on.
+        body: artifact.bodyOverride ?? parts.join("\n").trim(),
         comments: inline,
         folded,
         commitId: artifact.pr.headSha || undefined,

package/dist/runner/review.js

@@ -168,6 +168,9 @@ async function performReview(ref, pr, existing, opts, log) {
         chapters: [],
         comments: [],
         verdict: null,
+        // Not carried over. A hand-written send body described the draft this run
+        // is replacing — the same reason the pre-chat snapshot goes.
+        bodyOverride: null,
         run: {
             model: opts.model ?? null,
             startedAt: now(),

package/dist/server/daemon.js

@@ -42,6 +42,7 @@ export function stubArtifact(ref) {
         chapters: [],
         comments: [],
         verdict: null,
+        bodyOverride: null,
         run: null,
         sent: null,
         refresh: null,
@@ -537,6 +538,8 @@ export function startDaemon(opts) {
     }
     /** Said once, not every poll: a machine with no notifier will never grow one. */
     let notifierMissing = false;
+    /** Null until `serve` is listening and says so — see `cockpitAt`. */
+    let cockpitUrl = opts.cockpitUrl ?? null;
     /**
      * What the last attempt to tap this machine actually did, or null before one
      * has been made.
@@ -559,7 +562,7 @@ export function startDaemon(opts) {
      * why it stands down when this is on and both are on one machine.
      */
     async function announce(arrivals) {
-        const n = notice(arrivals);
+        const n = notice(arrivals, cockpitUrl);
         if (!n)
             return;
         notifierWorks = await notify(n);
@@ -755,6 +758,9 @@ export function startDaemon(opts) {
     void poll();
     return {
         status: () => ({ ...status }),
+        cockpitAt: (url) => {
+            cockpitUrl = url;
+        },
         stop: () => {
             stopped = true;
             if (timer)

package/dist/server/index.js

@@ -261,6 +261,7 @@ export async function buildApp(opts) {
             chapters: [],
             comments: [],
             verdict: null,
+            bodyOverride: null,
             run: {
                 model: null,
                 startedAt: now,
@@ -314,6 +315,13 @@ export async function buildApp(opts) {
         if (body.status !== undefined && !SETTLEABLE.includes(body.status)) {
             return c.json({ error: `status must be one of ${SETTLEABLE.join(", ")} — got ${body.status}` }, 400);
         }
+        // Coercing this one would be worse than refusing it: `String({})` is
+        // "[object Object]", and this field is posted to GitHub verbatim.
+        if (body.bodyOverride !== undefined &&
+            body.bodyOverride !== null &&
+            typeof body.bodyOverride !== "string") {
+            return c.json({ error: "bodyOverride must be a string, or null to compose it" }, 400);
+        }
         const updated = await updateArtifactByKey(c.req.param("key"), (a) => {
             const next = { ...a };
             if (body.status !== undefined) {
@@ -329,6 +337,12 @@ export async function buildApp(opts) {
                 // the moment you click. Same rule the poll's reopen follows.
                 next.filed = null;
             }
+            // The review body as the user rewrote it — or `null` to hand the body
+            // back to the composition it came from. Only ever set from the send
+            // panel, where the text being replaced is on screen.
+            if (body.bodyOverride !== undefined) {
+                next.bodyOverride = body.bodyOverride;
+            }
             if (body.verdictRecommendation !== undefined && next.verdict) {
                 next.verdict = {
                     ...next.verdict,
@@ -676,6 +690,39 @@ export async function buildApp(opts) {
     }
     return app;
 }
+/**
+ * The wildcard binds, and the loopback address each one answers on.
+ *
+ * Only these two are translated. A bind to `::1`, `localhost` or a particular
+ * interface is already an address that answers here, and rewriting it would
+ * point the click somewhere nothing is listening — `serve --host ::1` serves
+ * IPv6 loopback alone, where `127.0.0.1` does not connect at all. `::` maps to
+ * IPv6 loopback rather than IPv4, because a dual-stack socket is the only
+ * reason `127.0.0.1` would work on one and it is not guaranteed to be one.
+ */
+const WILDCARD = new Map([
+    ["0.0.0.0", "127.0.0.1"],
+    ["::", "::1"],
+]);
+/**
+ * The cockpit's own address, as reached from the machine `serve` runs on — what
+ * a desktop notification opens when you click it.
+ *
+ * It is the bound host only when that host is a particular interface; a
+ * wildcard bind is every interface, and the one that always answers from here
+ * is loopback. The token rides along because a click has to land on the review
+ * rather than on a 401, and it is the same token `serve` already prints to the
+ * console on startup. Null where there is no address to name yet — port 0 is
+ * whatever the OS picks, which isn't known until it has picked it.
+ */
+export function cockpitUrl(opts) {
+    if (!Number.isInteger(opts.port) || opts.port <= 0)
+        return null;
+    const host = WILDCARD.get(opts.host) ?? opts.host;
+    const authority = host.includes(":") ? `[${host}]` : host;
+    const query = opts.token ? `?token=${encodeURIComponent(opts.token)}` : "";
+    return `http://${authority}:${opts.port}/${query}`;
+}
 /**
  * Serve the cockpit. `reconcileRunning` is deliberately *not* called here: the
  * caller must have done it before starting the daemon, because the daemon polls
@@ -687,6 +734,9 @@ export async function startServer(opts) {
     serve({ fetch: app.fetch, port: opts.port, hostname: opts.host }, (info) => {
         const tokenHint = opts.token ? `/?token=${opts.token}` : "";
         console.log(`cerber cockpit: http://${opts.host}:${info.port}${tokenHint}`);
+        // The bound port, not the asked-for one: `--port 0` is the OS's to choose,
+        // and this callback is the first moment anyone knows what it chose.
+        opts.daemon?.cockpitAt(cockpitUrl({ ...opts, port: info.port }));
         if (opts.daemon) {
             const s = opts.daemon.status();
             console.log(`inbox: polling every ${Math.round(s.intervalMs / 60_000)}m` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "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)",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "web/dist",
+    "assets",
     "README.md",
     "LICENSE"
   ],