@fullstackhouse/cerber 0.39.1 → 0.40.0

package/README.md

@@ -429,8 +429,31 @@ cockpit (or `cerber review <pr> --force`).
 > starts and they do not come back, on success or on failure. This is a
 > decision, not a bug ([`docs/lifecycle.md`](docs/lifecycle.md)): the run owns
 > the draft. If you have written comments you want to keep, send the review or
-> copy them out first. Your *decisions* do survive — a send, a `reviewed` or
-> `skipped` you set, and the chat transcript are all kept.
+> copy them out first. Your *decisions* do survive — a `reviewed` or `skipped`
+> you set and the chat transcript are kept, and a send is kept as a record of
+> what went to GitHub (see the next section).
+
+### Re-reviewing one you already sent
+
+Sending freezes the draft — it is the record of what GitHub has, so nothing
+can edit it afterwards. What you can do is replace it. The same **Re-review at
+head** button works on a sent review, and on a PR whose author has pushed
+since it is the only thing that does: the review you sent answers a commit
+that is gone, and cerber will not rewrite a review that is already public.
+
+The run drafts against the current head and hands you an ordinary unsent
+review again — editable, arguable, sendable. What you sent is kept beside it:
+a note above the draft says what you posted and when, with a link, and the
+line over the Send button says the next click would be review 2. **Nothing on
+GitHub changes** — a second review sits beside the first; cerber never edits
+or withdraws what it posted.
+
+The poll does this on its own, too, for a sent review whose PR moved on and
+whose author has asked you for another look. The two things that can reach
+GitHub without you both stand down on a row like that: auto-send will not
+approve a PR you have already reviewed yourself, and a handoff stops offering
+to carry the draft — it is a new draft, but sending it would still be your
+second review on that PR.
 
 ## Arguing with the review before you send it
 
@@ -488,7 +511,8 @@ the exchange went anywhere near GitHub.
 Nothing in the conversation reaches GitHub. Send still builds its payload from
 the summary, comments and verdict alone, and is still one deliberate click. A
 review that has already been sent can't be argued with: that artifact is the
-record of what GitHub has.
+record of what GitHub has — re-review it first, and the new draft is open to
+the conversation like any other.
 
 ## Every row remembers what happened to it
 

package/dist/cli/index.js

@@ -231,6 +231,18 @@ program
     }
     const payload = buildReviewPayload(artifact, event);
     console.log(`About to send to ${artifact.pr.url}:`);
+    // Said before anything else about the payload: on a PR you have already
+    // reviewed, "what is in this review" is the second question. The cockpit's
+    // send panel says the same thing in the same place (SPEC §8.3).
+    const posted = artifact.priorSends;
+    if (posted.length > 0) {
+        const last = posted[posted.length - 1];
+        const when = new Date(last.at).toLocaleDateString();
+        console.log(`  ⚠ you already sent ${posted.length === 1 ? "a review" : `${posted.length} reviews`}` +
+            ` on this PR${posted.length === 1 ? "" : ", the last"} on ${when}` +
+            ` as ${last.event.toLowerCase().replace("_", " ")}${last.url ? ` (${last.url})` : ""}.` +
+            ` This would be review ${posted.length + 1}; it sits beside them, replacing nothing.`);
+    }
     console.log(`  event: ${event}`);
     console.log(`  inline comments: ${payload.comments.length}`);
     if (payload.folded.length > 0) {

package/dist/core/artifact.js

@@ -403,6 +403,22 @@ export const ArtifactSchema = z.object({
     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),
+    /**
+     * Reviews posted from this row that a later re-review has since replaced,
+     * oldest first.
+     *
+     * `sent` means "the draft on this page is the one that went to GitHub", and
+     * every guard in cerber reads it that way — the send path's "already sent"
+     * refusal most of all. So when a re-review replaces that draft the send
+     * cannot stay in the field (the new draft was never sent) and must not simply
+     * go (it is on the PR, under the user's name, for good). It moves here.
+     *
+     * What it buys is a cockpit that can say "you reviewed this on the 14th" over
+     * a draft of the 16th, and a send panel that says the next click posts a
+     * second review rather than a first. The GitHub URL rides along, because the
+     * record is only useful if the thing it names can be opened.
+     */
+    priorSends: z.array(SentInfoSchema).default([]),
     /** Set when cerber filed this draft away itself, and why. Never on a sent one. */
     filed: FiledInfoSchema.nullable().default(null),
     /** Set when you gave this review to somebody else. Mutually exclusive with `filed`. */

package/dist/core/autosend.js

@@ -13,6 +13,14 @@ import { sendTreatment } from "./raised.js";
 export function evaluateAutoSend(artifact, threshold) {
     if (artifact.sent)
         return { eligible: false, reason: "already sent" };
+    // The same rule, for a send a re-review has since superseded. `sent` only
+    // ever describes the draft on the row, so once one moves to `priorSends`
+    // that guard stops seeing it — and "never a re-send" would quietly come to
+    // mean "never twice in a row". A PR this user has already reviewed is the
+    // last place to post unattended: the second review is theirs to send.
+    if (artifact.priorSends.length > 0) {
+        return { eligible: false, reason: "a review was already sent on this PR — the next one is yours to send" };
+    }
     if (artifact.status !== "ready")
         return { eligible: false, reason: `status is ${artifact.status}` };
     if (!artifact.verdict)

package/dist/core/history.js

@@ -174,6 +174,11 @@ export function describeChange(before, after) {
         lines.push(`sent to GitHub as ${after.sent.event.toLowerCase().replace("_", " ")}` +
             `${after.sent.auto ? ", by auto-send" : ""}`);
     }
+    // The one state change nothing else on this list would record: the row went
+    // from "this draft is on GitHub" back to "this draft has never been sent".
+    if (after.priorSends.length > (before?.priorSends.length ?? 0)) {
+        lines.push("a new draft took over from the review that was sent — what was sent stays on GitHub");
+    }
     if (after.filed && after.filed.at !== before?.filed?.at) {
         lines.push(`filed under settled — ${FILED_PHRASE[after.filed.reason] ?? after.filed.reason}`);
     }

package/dist/core/refresh.js

@@ -44,6 +44,19 @@ export function refreshArtifact(artifact, pr, diff) {
 export function userOwnsStatus(a) {
     return a.sent !== null || a.status === "reviewed" || a.status === "skipped";
 }
+/**
+ * This row's sends, with the one a starting run is about to supersede folded in.
+ *
+ * The only way back into a review that was sent is a new draft, and `sent`
+ * describes a draft that is about to stop existing — so it cannot stay where
+ * it is. It also cannot simply go: that review is on the PR under the user's
+ * name, and a cockpit that forgets it would offer a second one as if it were
+ * the first. Called by the claim at the top of a run, which is the one moment
+ * a send stops covering what is on the page.
+ */
+export function supersede(a) {
+    return a.sent ? [...a.priorSends, a.sent] : a.priorSends;
+}
 /**
  * Fold a finished review run onto whatever the artifact says now.
  *
@@ -76,6 +89,9 @@ export function mergeRunResult(fresh, current) {
         // the stamp away with the status.
         settledAt: userOwnsStatus(current) ? current.settledAt : fresh.settledAt,
         sent: current.sent,
+        // Written by this run's own claim (`supersede`), or by an earlier one —
+        // either way the disk is the only copy; `fresh` was built before the claim.
+        priorSends: current.priorSends,
         // Disk wins: the ledger is the poll's, and the run knows nothing about it.
         notified: current.notified,
         calibration: current.calibration,

package/dist/core/state.js

@@ -197,11 +197,18 @@ export async function reconcileRunning(opts = {}) {
         const stuckCheck = artifact.raisedCheck?.checkingSince != null;
         if (!stuckRun && !stuckChat && !stuckCheck)
             continue;
+        // A row still carrying its send was interrupted before the run claimed it,
+        // so the draft on it is untouched — and it is the one that went to GitHub.
+        // "failed" would hide a sent review behind a broken re-review, and the
+        // interruption belongs to the re-review rather than to the run block,
+        // which still describes the review that was posted. It goes to the history
+        // instead, which is where a thing that happened *to* a row belongs.
+        const interruptedSend = stuckRun && artifact.sent != null;
         await saveArtifact({
             ...artifact,
-            status: stuckRun ? "failed" : artifact.status,
+            status: stuckRun ? (artifact.sent ? "sent" : "failed") : artifact.status,
             updatedAt: new Date().toISOString(),
-            run: stuckRun && artifact.run
+            run: stuckRun && artifact.run && !interruptedSend
                 ? { ...artifact.run, error: "interrupted — cerber restarted while this review was running" }
                 : artifact.run,
             pendingChat: stuckChat
@@ -211,6 +218,9 @@ export async function reconcileRunning(opts = {}) {
             // report, and the next open starts another.
             raisedCheck: artifact.raisedCheck && { ...artifact.raisedCheck, checkingSince: null },
         });
+        if (interruptedSend) {
+            await noteHistory(artifact.id, "re-review interrupted — cerber restarted; the sent review is untouched");
+        }
         cleared++;
     }
     return cleared;

package/dist/runner/review.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { AiReviewSchema, SCHEMA_VERSION, artifactId, artifactKey, } from "../core/artifact.js";
 import { createRunDir, evictOldCheckouts, prepareCheckout, removeRunDir } from "../core/checkout.js";
 import { fetchPrDiff, fetchPrInfo, isOrgMember, isTeamMember } from "../core/gh.js";
-import { mergeRunResult, userOwnsStatus } from "../core/refresh.js";
+import { mergeRunResult, supersede, userOwnsStatus } from "../core/refresh.js";
 import { loadArtifact, noteHistory, saveArtifact, updateArtifactByKey } from "../core/state.js";
 import { withWriter } from "../core/history.js";
 import { loadConfig } from "../core/config.js";
@@ -191,13 +191,19 @@ async function performReview(ref, pr, existing, opts, log) {
             trigger: opts.trigger ?? "user",
             reviewedSha: null,
         },
+        // Both filled in at the claim below, from the row as it stands then: a
+        // send this run supersedes moves to `priorSends` rather than vanishing.
         sent: null,
+        priorSends: [],
         refresh: null,
         // A new draft has new findings, compared afresh once the run has written them.
         raisedCheck: null,
         filed: null,
         handoff: null,
         settledAt: null,
+        // Carried at the claim, not reset: it describes a review that really was
+        // sent, and `cerber stats` is the only reader. Dropping it here
+        // would quietly delete one data point every time a sent PR is re-reviewed.
         calibration: null,
         // The conversation is the user's writing, so a re-review keeps it — the
         // chat prompt replays the transcript, which is what makes it survive the
@@ -222,10 +228,23 @@ async function performReview(ref, pr, existing, opts, log) {
     // (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.
+    //
+    // A send is the one decision the claim takes *over* rather than leaves
+    // alone, because the only way to reopen a sent row is to replace the draft
+    // that was sent. It is not discarded: `supersede` files it under
+    // `priorSends`, so the cockpit can still say what went to GitHub and when,
+    // and the send panel knows the next click would post a second review.
+    // Read from `current` rather than `existing`, which is minutes old.
     const decided = existing ? userOwnsStatus(existing) : false;
     const claimed = await updateArtifactByKey(artifactKey(artifact.id), (current) => !decided && userOwnsStatus(current)
         ? current
-        : { ...artifact, notified: current.notified, viewed: current.viewed });
+        : {
+            ...artifact,
+            notified: current.notified,
+            viewed: current.viewed,
+            priorSends: supersede(current),
+            calibration: current.calibration,
+        });
     const held = claimed !== null && !decided && userOwnsStatus(claimed);
     if (!held) {
         if (claimed)

package/dist/server/daemon.js

@@ -46,6 +46,7 @@ export function stubArtifact(ref) {
         run: null,
         sent: null,
         refresh: null,
+        priorSends: [],
         filed: null,
         handoff: null,
         raisedCheck: null,

package/dist/server/index.js

@@ -18,7 +18,7 @@ import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../co
 import { buildReviewPayload, computeCalibration, describeReplyFailures, recordReplies, } from "../core/send.js";
 import { raisedChanged, rewriteFinding, startRaisedCheck } from "../core/raised.js";
 import { checkAlreadyRaised, claimRaisedCheck, finishRaisedCheck, isRaisedCheckRunning, prepareRaisedCheck, releaseRaisedCheck, } from "../runner/raised.js";
-import { listArtifacts, loadArtifact, loadArtifactByKey, saveArtifact, updateArtifactByKey, } from "../core/state.js";
+import { listArtifacts, loadArtifact, loadArtifactByKey, noteHistory, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { isReviewRunning } from "../runner/inflight.js";
 import { reviewPr } from "../runner/review.js";
 import { runChatTurn } from "../runner/chat.js";
@@ -342,6 +342,7 @@ export async function buildApp(opts) {
             },
             sent: null,
             refresh: null,
+            priorSends: [],
             filed: null,
             handoff: null,
             raisedCheck: null,
@@ -568,8 +569,14 @@ export async function buildApp(opts) {
         const stale = artifact.pr.headSha !== "" && artifact.pr.headSha !== pr.headSha;
         // A sent review is a record of what was posted — never rewrite it. A running
         // one is mid-run and would be overwritten from under the runner.
+        //
+        // `headSha` rides on the answer either way, and it is the only thing a
+        // declined refresh can tell the cockpit: on a sent row nothing is written,
+        // so the artifact handed back still names the commit that was reviewed,
+        // and the page would have nothing to say about a PR that has moved past a
+        // review the user cannot edit but can replace.
         if (!stale || artifact.sent || artifact.status === "running") {
-            return c.json({ stale, changed: false, prState: pr.state, artifact });
+            return c.json({ stale, changed: false, prState: pr.state, headSha: pr.headSha, artifact });
         }
         try {
             const diff = await fetchPrDiff(ref);
@@ -598,6 +605,7 @@ export async function buildApp(opts) {
                 stale: true,
                 changed: applied && result.changed,
                 prState: pr.state,
+                headSha: pr.headSha,
                 moved: applied ? result.moved : 0,
                 drifted: applied ? result.drifted : 0,
                 artifact: saved,
@@ -613,8 +621,13 @@ export async function buildApp(opts) {
         const artifact = await loadArtifactByKey(key);
         if (!artifact)
             return c.json({ error: "not found" }, 404);
-        if (artifact.sent)
-            return c.json({ error: `already sent at ${artifact.sent.at}` }, 409);
+        // A sent row may be re-reviewed, and this is the only way back into one.
+        // The author pushed again, somebody asked for another look, the review
+        // went out at a commit that no longer exists — none of that is answered by
+        // the review already on the PR, and refusing here left the cockpit with no
+        // move at all while `cerber review --force` did it from a terminal. What
+        // was sent is kept (`supersede`), the new draft is sendable in its own
+        // right, and the send panel says it would be a second review.
         if (isReviewRunning(artifact.id)) {
             return c.json({ error: busy(artifact, "a review of this PR is already running") }, 409);
         }
@@ -625,21 +638,29 @@ export async function buildApp(opts) {
         const withSource = sourceParam == null ? opts.withSource : sourceParam !== "0";
         // Mark it running before responding, so the cockpit's next poll can't catch
         // the old "ready" status and conclude the run already finished.
+        //
+        // The run block is left alone while the row still carries its send: that
+        // block describes the review on GitHub — its model, its cost, the commit
+        // it read — and a stub written here would erase all of it minutes before
+        // the runner's claim writes a real one, with nothing able to bring it back
+        // if the run never gets that far. The claim replaces it either way.
         const running = await updateArtifactByKey(key, (a) => ({
             ...a,
             status: "running",
-            run: {
-                model: null,
-                startedAt: new Date().toISOString(),
-                finishedAt: null,
-                costUsd: null,
-                error: null,
-                withSource: withSource !== false,
-                trusted: false,
-                sessionId: null,
-                trigger: "user",
-                reviewedSha: null,
-            },
+            run: a.sent
+                ? a.run
+                : {
+                    model: null,
+                    startedAt: new Date().toISOString(),
+                    finishedAt: null,
+                    costUsd: null,
+                    error: null,
+                    withSource: withSource !== false,
+                    trusted: false,
+                    sessionId: null,
+                    trigger: "user",
+                    reviewedSha: null,
+                },
         }));
         // Minutes-long: run it detached and let the cockpit poll the artifact.
         void reviewPr(ref, {
@@ -654,9 +675,20 @@ export async function buildApp(opts) {
             // The runner marks the artifact failed once it owns it; a failure before
             // that (fetching the PR, or a run already in flight) would otherwise
             // leave it stuck at "running" with nothing to clear it.
-            await updateArtifactByKey(key, (a) => a.status === "running"
-                ? { ...a, status: "failed", run: a.run ? { ...a.run, error: message } : null }
-                : a).catch(() => { });
+            //
+            // A row that still carries its send never got as far as the claim, so
+            // the draft on it is the one that went to GitHub and nothing about it
+            // has changed: it goes back to `sent`, untouched. The failure is the
+            // re-review's, not that review's, so it goes in the history rather
+            // than onto a run block that describes something else entirely.
+            const back = await updateArtifactByKey(key, (a) => a.status === "running"
+                ? a.sent
+                    ? { ...a, status: "sent" }
+                    : { ...a, status: "failed", run: a.run ? { ...a.run, error: message } : null }
+                : a).catch(() => null);
+            if (back?.sent) {
+                await noteHistory(back.id, `re-review did not start: ${message}`).catch(() => { });
+            }
         });
         return c.json(running, 202);
     });
@@ -1017,12 +1049,36 @@ export async function buildApp(opts) {
         let sendError = null;
         let sent = null;
         let payload = null;
-        const alreadySent = postReview ? ((await loadArtifactByKey(key))?.sent ?? artifact.sent) : null;
+        //
+        // A send a re-review has since superseded counts here too. It is not on
+        // this draft, but it is on the PR under the user's name, and this guard
+        // exists to stop a handoff being the second review — which it would be.
+        const onDisk = postReview ? await loadArtifactByKey(key) : null;
+        const alreadySent = postReview
+            ? (onDisk?.sent ??
+                artifact.sent ??
+                (onDisk ?? artifact).priorSends.at(-1) ??
+                null)
+            : null;
         // And there has to be a review to post. The dialog only offers the box on a
         // row that has one, but the dialog is not the guard: a stale tab or a direct
         // call would otherwise submit a body that is nothing but cerber's footer,
         // under the user's name, on a PR nobody has drafted a word about.
         const somethingToSay = artifact.summary !== "" || artifact.comments.some((cm) => cm.status !== "dropped");
+        // A decline here has to say so. The dialog's own line promises "this row
+        // goes under sent, with the review on the PR"; letting the guard refuse in
+        // silence walks the user to the next review believing it posted.
+        if (postReview && alreadySent) {
+            // Phrased to read after the cockpit's own "the review did not post:",
+            // which is what wraps every `sendError` on the way to the user.
+            sendError =
+                `a review was already sent on this PR on ${alreadySent.at.slice(0, 10)}` +
+                    `${alreadySent.url ? ` (${alreadySent.url})` : ""}, and a second one is yours to send.` +
+                    ` The draft is untouched.`;
+        }
+        else if (postReview && !somethingToSay) {
+            sendError = "there is no draft on this row — only cerber's footer would have gone up.";
+        }
         if (postReview && !alreadySent && somethingToSay) {
             payload = buildReviewPayload(artifact, "COMMENT");
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "keywords": [