@fullstackhouse/cerber 0.29.0 → 0.30.0

package/dist/runner/review.js

@@ -162,6 +162,13 @@ async function performReview(ref, pr, existing, opts, log) {
         status: "running",
         createdAt: existing?.createdAt ?? now(),
         updatedAt: now(),
+        // The announcement ledger belongs to the row, not to the run: a PR the poll
+        // found and has not told you about yet is still owed that tap when this
+        // draft lands (`notified` in artifact.ts). Seeded from the row this run
+        // starts on, and re-read from disk on the way out of both writes below —
+        // `existing` was loaded minutes ago, and a poll may have announced the row
+        // since.
+        notified: existing?.notified,
         pr,
         diff,
         summary: "",
@@ -196,7 +203,30 @@ async function performReview(ref, pr, existing, opts, log) {
         preChat: null,
         pendingChat: null,
     };
-    await saveArtifact(artifact);
+    // Not a plain save. The fetch and checkout above take minutes, and the row on
+    // disk may have moved twice over in that window:
+    //
+    //   - a poll may have announced it, writing a ledger entry `existing` cannot
+    //     know about. Writing the stale one back would spend the tap twice.
+    //   - the user may have settled or sent it, which is a decision this run does
+    //     not get to overwrite by marking the row `running`. The run goes on and
+    //     folds its draft underneath at the end (`mergeRunResult`) — the same
+    //     line that function already holds, now held by the claim as well.
+    //
+    // Which settle it is matters, and `existing` is what tells them apart: a row
+    // already settled when this run *started* is one you took back deliberately
+    // (the guard above only lets a forced re-review that far), and claiming it is
+    // how the reopen happens at all. A settle that appeared since is the one this
+    // must not touch.
+    const decided = existing ? userOwnsStatus(existing) : false;
+    const claimed = await updateArtifactByKey(artifactKey(artifact.id), (current) => !decided && userOwnsStatus(current) ? current : { ...artifact, notified: current.notified });
+    const held = claimed !== null && !decided && userOwnsStatus(claimed);
+    if (!held) {
+        if (claimed)
+            artifact = claimed;
+        else
+            await saveArtifact(artifact);
+    }
     const { prompt, truncated } = buildReviewPrompt(pr, diff, { source: source !== null, trusted });
     if (truncated)
         log("Warning: diff exceeds the context budget and was truncated.");

package/dist/server/daemon.js

@@ -3,7 +3,7 @@ import { evaluateAutoSend } from "../core/autosend.js";
 import { loadConfig } from "../core/config.js";
 import { classifyReply, currentLogin, fetchConversation, fetchLastReviewRequest, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastMentionOfYou, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
 import { withWriter } from "../core/history.js";
-import { notice, notify } from "../core/notify.js";
+import { pendingNews, notice, notify } from "../core/notify.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
 import { appendAutoSendLog, deleteArtifact, listArtifacts, loadArtifact, noteHistory, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { ReviewInProgressError } from "../runner/inflight.js";
@@ -48,6 +48,9 @@ export function stubArtifact(ref) {
         refresh: null,
         filed: null,
         settledAt: null,
+        // Null, not absent: the poll found this PR, so it owes the machine a tap
+        // for it — once there is something to tap you about (§9.8).
+        notified: null,
         calibration: null,
         chat: [],
         preChat: null,
@@ -538,6 +541,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.
@@ -551,20 +556,48 @@ export function startDaemon(opts) {
      */
     let notifierWorks = null;
     /**
-     * Tap this machine when a PR lands in the queue.
+     * Tap this machine about every row that has become worth walking back to,
+     * once each.
      *
-     * 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.
+     * `notified` on the artifact is the ledger this rides on: the poll writes it
+     * null when it first stubs a PR ("owed a tap"), and stamps it here. So a
+     * restart re-announces nothing, a PR that arrived while `serve` was down is
+     * still news the next time it runs — and, unlike announcing straight off the
+     * discovery, a tap the daemon is holding back survives the wait. The cockpit's
+     * bell works off the same rule (`isNews`), which is why it stands down when
+     * this is on and both are on one machine.
+     *
+     * Stamped whether or not the notifier worked, and whether or not it was even
+     * asked (`tell` is the notify toggle). A machine with no notifier would
+     * otherwise re-try every row every poll, and a toggle switched on after a
+     * quiet week would announce that whole week at once — the same reason the
+     * browser bell records what it stays quiet about.
      */
-    async function announce(arrivals) {
-        const n = notice(arrivals);
+    async function announce(autoReview, tell) {
+        const owed = (await listArtifacts()).flatMap((a) => {
+            const news = pendingNews(a, autoReview);
+            return news ? [{ id: a.id, news }] : [];
+        });
+        // `cockpitUrl` is where a click lands, and it is read here rather than
+        // captured: `serve` hands it over once its port is bound, which can be
+        // after the first poll has already started.
+        const n = notice(owed.map((o) => o.news), cockpitUrl);
         if (!n)
             return;
-        notifierWorks = await notify(n);
-        if (notifierWorks)
+        if (tell)
+            notifierWorks = await notify(n);
+        const at = new Date().toISOString();
+        // Stamped after the tap, not before: a crash in between costs a repeated
+        // notification, and the other order costs the only one there was going
+        // to be. What was said is stamped along with it, because "told you it
+        // failed" and "told you about the draft" are different news.
+        for (const { id, news } of owed) {
+            await updateArtifactByKey(artifactKey(id), (current) => 
+            // Absent means the row was replaced mid-poll by one nobody meant to
+            // announce (a hand-pulled review) — don't re-open a ledger for it.
+            current.notified === undefined ? current : { ...current, notified: { at, drafted: Boolean(news.draft) } });
+        }
+        if (!tell || notifierWorks)
             return;
         if (notifierMissing)
             return;
@@ -599,6 +632,49 @@ export function startDaemon(opts) {
             }
         });
     }
+    /**
+     * Write a run's failure onto the row when the runner never got far enough to
+     * do it itself.
+     *
+     * A review that falls over before it owns the artifact — the PR read, the
+     * diff fetch — leaves the row sitting at `awaiting`, which reads as "a draft
+     * is coming" to everything downstream: the tap waits for one that will never
+     * be written, and the cockpit's own bell, which has only the row to go on,
+     * waits forever. Recording it is what keeps the two halves telling one story;
+     * the alternative, a set of ids the poll passes to its own notifier, is a
+     * fact the daemon knows and nobody else can see.
+     *
+     * Only a row still sitting at `awaiting` with nothing in flight on it is
+     * rewritten. A settle that landed while the run worked is a decision, and a
+     * failure is no reason to overrule it — the same line `mergeRunResult` holds.
+     * The run test is "not in flight" rather than "absent" because a row that was
+     * settled and then reopened keeps the run it had (`reopenedStatus`): reading
+     * that leftover as a live run would refuse to record the new failure, and the
+     * row would sit at `awaiting` forever waiting on a draft nobody is writing —
+     * the exact silence this function exists to break.
+     */
+    async function recordEarlyFailure(id, error) {
+        await updateArtifactByKey(artifactKey(id), (a) => a.status === "awaiting" && (a.run === null || a.run.finishedAt !== null)
+            ? {
+                ...a,
+                status: "failed",
+                run: {
+                    model: opts.model ?? null,
+                    startedAt: new Date().toISOString(),
+                    finishedAt: new Date().toISOString(),
+                    costUsd: null,
+                    error,
+                    withSource: opts.withSource !== false,
+                    trusted: false,
+                    sessionId: null,
+                    trigger: "daemon",
+                    reviewedSha: null,
+                },
+            }
+            : a).catch(() => {
+            // Book-keeping: a row we could not write is one the next poll retries.
+        });
+    }
     async function reviewAll(refs) {
         let reviewed = 0;
         let skipped = 0;
@@ -628,7 +704,9 @@ export function startDaemon(opts) {
                 }
                 failed++;
                 status.errors++;
-                log(`[${label}] failed: ${err instanceof Error ? err.message : err}`);
+                const message = err instanceof Error ? err.message : String(err);
+                await recordEarlyFailure(label, message);
+                log(`[${label}] failed: ${message}`);
             }
         });
         return { reviewed, skipped, failed };
@@ -677,16 +755,6 @@ 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 =
@@ -696,6 +764,19 @@ export function startDaemon(opts) {
             else {
                 status.lastSummary = `${refs.length} awaiting${discovered.length > 0 ? `, ${discovered.length} new` : ""} (auto-review off)`;
             }
+            // After the drafting, not before it. The arrival is not the news when
+            // cerber is about to write the review itself: a tap that lands on "no run
+            // yet" makes the walk back to the cockpit for nothing, and by the time
+            // there *is* something to read the PR is no longer new. So the tap waits
+            // for the draft — and for a PR nobody is drafting (auto-review off, or a
+            // run that failed) it goes out here all the same. `isNews` is the rule,
+            // and the cockpit's bell reads the same one.
+            await announce(autoReview, notifyOn);
+            // 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();
             log(status.lastSummary);
         }
         catch (err) {
@@ -756,6 +837,9 @@ export function startDaemon(opts) {
     void poll();
     return {
         status: () => ({ ...status }),
+        cockpitAt: (url) => {
+            cockpitUrl = url;
+        },
         stop: () => {
             stopped = true;
             if (timer)

package/dist/server/index.js

@@ -12,7 +12,7 @@ import { toMarkdown } from "../core/export.js";
 import { fetchPrDiff, fetchPrInfo, parsePrRef, submitReview } from "../core/gh.js";
 import { z } from "zod";
 import { DaemonConfigSchema, configPath, loadConfig, saveConfig } from "../core/config.js";
-import { refreshArtifact } from "../core/refresh.js";
+import { refreshArtifact, userOwnsStatus } from "../core/refresh.js";
 import { withWriter } from "../core/history.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
@@ -180,6 +180,12 @@ export async function buildApp(opts) {
             blockerCount: a.comments.filter((cm) => cm.status !== "dropped" && cm.severity === "blocker")
                 .length,
             gradedCount: a.comments.filter((cm) => cm.severity != null).length,
+            // Whether the machine ever meant to announce this row (§9.8's ledger:
+            // absent means nobody did — a review pulled in by hand). The browser
+            // bell has only the list to go on, so without this it would announce
+            // rows the daemon deliberately stays silent about, and the two bells
+            // would stop telling one story.
+            announceable: a.notified !== undefined,
             costUsd: a.run?.costUsd ?? null,
             withSource: a.run?.withSource ?? null,
             trusted: a.run?.trusted ?? null,
@@ -255,6 +261,12 @@ export async function buildApp(opts) {
             status: "running",
             createdAt: now,
             updatedAt: now,
+            // Kept from the stub this replaces, when there is one: the poll found
+            // that PR and owes the machine a tap for it once the draft lands. Absent
+            // on a PR pasted into the cockpit — nobody asked to be told about that
+            // one, and it is on screen already. Re-read from disk at the write below,
+            // since `fetchPrInfo` gave a poll time to announce the stub.
+            notified: existing?.notified,
             pr,
             diff: "",
             summary: "",
@@ -283,7 +295,19 @@ export async function buildApp(opts) {
             preChat: null,
             pendingChat: null,
         };
-        await saveArtifact(artifact);
+        // A settle or a send that landed while `fetchPrInfo` was in flight is a
+        // decision, and claiming the row for a run would erase it — the detached
+        // run below folds its draft under whatever the row says instead
+        // (`mergeRunResult`), which is the same line every other writer holds.
+        const claimed = await updateArtifactByKey(artifactKey(artifact.id), (current) => userOwnsStatus(current) ? current : { ...artifact, notified: current.notified });
+        // Declining the claim is only half the job: the run below forces, and a
+        // forced run reopens a settled row on purpose. So the decision ends the
+        // request — hand it back and start nothing.
+        if (claimed && userOwnsStatus(claimed)) {
+            return c.json({ ...claimed, key: artifactKey(claimed.id) }, 200);
+        }
+        if (!claimed)
+            await saveArtifact(artifact);
         void reviewPr(ref, {
             force: true,
             withSource,
@@ -438,13 +462,32 @@ export async function buildApp(opts) {
         try {
             const diff = await fetchPrDiff(ref);
             const result = refreshArtifact(artifact, pr, diff);
-            const saved = await updateArtifactByKey(c.req.param("key"), () => result.artifact);
+            // `result` was built from a snapshot taken before the PR read and the
+            // diff fetch, so it is written back only onto a row that is still the one
+            // it describes. The guard above asked the same question minutes ago; a
+            // settle, a send or a run that started since would be undone by writing
+            // this over them, and the ledger is the poll's in either case.
+            // Taken over, in any of the three ways that matter: a decision was made,
+            // a run owns the row now, or it simply is not the row this refresh was
+            // computed from any more. The last test is what catches a run that both
+            // started *and* finished inside this handler's own fetches — it leaves
+            // `ready`, which neither of the other two tests would refuse, and writing
+            // the pre-fetch snapshot over it would drop a whole finished draft.
+            // `updatedAt` is the version: every write through the store bumps it.
+            const taken = (a) => userOwnsStatus(a) || a.status === "running" || a.updatedAt !== artifact.updatedAt;
+            // Read inside the mutation rather than from its result: the store stamps
+            // `updatedAt` on the way out, so the saved row always looks "moved".
+            let applied = false;
+            const saved = await updateArtifactByKey(c.req.param("key"), (current) => {
+                applied = !taken(current);
+                return applied ? { ...result.artifact, notified: current.notified } : current;
+            });
             return c.json({
                 stale: true,
-                changed: result.changed,
+                changed: applied && result.changed,
                 prState: pr.state,
-                moved: result.moved,
-                drifted: result.drifted,
+                moved: applied ? result.moved : 0,
+                drifted: applied ? result.drifted : 0,
                 artifact: saved,
             });
         }
@@ -690,6 +733,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
@@ -701,6 +777,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.29.0",
+  "version": "0.30.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "author": "Full Stack House (https://fullstack.house)",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "web/dist",
+    "assets",
     "README.md",
     "LICENSE"
   ],