@fullstackhouse/cerber 0.29.1 → 0.30.0

package/README.md

@@ -88,13 +88,20 @@ 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.
+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

package/dist/cli/index.js

@@ -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, [])

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,8 +4,16 @@
 // 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'`
@@ -40,6 +48,22 @@ 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"}`;
+}
 /**
  * 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
@@ -48,7 +72,7 @@ const slug = (a) => `${a.repo}#${a.number}`;
  */
 const flatten = (value) => value.replace(/[\u0000-\u001f\u007f]+/g, " ");
 /**
- * One popup for one poll's arrivals — a batch is one interruption, not five.
+ * 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.
  *
@@ -57,27 +81,92 @@ const flatten = (value) => value.replace(/[\u0000-\u001f\u007f]+/g, " ");
  * 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, cockpit) {
-    if (arrived.length === 0)
+export function notice(news, cockpit) {
+    if (news.length === 0)
         return null;
     const base = cockpit || null;
-    if (arrived.length === 1) {
-        const a = arrived[0];
+    if (news.length === 1) {
+        const a = news[0];
         const key = artifactKey(artifactId(a));
-        return {
-            title: `${slug(a)} awaits your review`,
-            body: `${a.title} — ${a.author}`,
-            url: base && `${base}#/r/${encodeURIComponent(key)}`,
-        };
+        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,
+    };
+}
 /**
  * A PR title, as an AppleScript string literal.
  *

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 = {}) {

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,
@@ -553,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, cockpitUrl);
+    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;
@@ -601,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;
@@ -630,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 };
@@ -679,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 =
@@ -698,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) {

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,
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.29.1",
+  "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)",