@fullstackhouse/cerber 0.24.0 → 0.25.0

package/README.md

@@ -384,6 +384,13 @@ shadow mode for a while: every would-send decision lands in
 verdicts and comments survive your review — enable auto-send when its 90%
 actually means 90%.
 
+## How it works
+
+[**docs/lifecycle.md**](docs/lifecycle.md) is the reference behind everything
+above: the seven statuses and what sets each, which tab a PR lands in and why,
+when the poll files or archives a row on its own, when a re-review happens and
+what it will not overwrite, and what gets written to disk at each step.
+
 ## Development
 
 ```bash

package/dist/cli/index.js

@@ -8,8 +8,9 @@ import { configPath, loadConfig, saveConfig } from "../core/config.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { parsePrRef, searchAwaitingMe, submitReview } from "../core/gh.js";
 import { buildReviewPayload, computeCalibration, eventForRecommendation } from "../core/send.js";
-import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, updateArtifactByKey, } from "../core/state.js";
+import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, reconcileRunning, updateArtifactByKey, } from "../core/state.js";
 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";
 const program = new Command();
@@ -135,6 +136,15 @@ program
         console.error(`Already sent at ${artifact.sent.at}${artifact.sent.url ? ` — ${artifact.sent.url}` : ""}`);
         process.exit(1);
     }
+    // The persisted status is the only signal here: a run started by `serve` or
+    // by another terminal is invisible to this process. Sending mid-run vouches
+    // for a draft that is being replaced as you read it.
+    if (artifact.status === "running") {
+        console.error(`A review of ${id} is running — wait for it to finish, then send. ` +
+            `If nothing is actually running, the last run died mid-flight: re-run it, or restart \`cerber serve\`, ` +
+            `either of which clears the stale status.`);
+        process.exit(1);
+    }
     const event = (opts.event ??
         (artifact.verdict ? eventForRecommendation(artifact.verdict.recommendation) : "COMMENT")).toUpperCase();
     if (!["APPROVE", "COMMENT", "REQUEST_CHANGES"].includes(event)) {
@@ -352,6 +362,13 @@ program
             `matching PRs, with nobody watching. Pass --no-trust to keep every review read-only, ` +
             `or --no-auto-review to only review on click.`);
     }
+    // Before anything polls. Reconciliation is what makes "nothing is running"
+    // true after an unclean shutdown, and the daemon's first tick fires the
+    // moment it is constructed — so starting it first put both of them on the
+    // same leftover artifact with no ordering between them.
+    const cleared = await reconcileRunning({ inUse: isReviewRunning });
+    if (cleared > 0)
+        console.log(`Cleared ${cleared} interrupted run(s) left by a previous process.`);
     const daemon = opts.poll
         ? startDaemon({
             repos: opts.repo.length > 0 ? opts.repo : d.repos,

package/dist/core/artifact.js

@@ -97,6 +97,17 @@ export const RunInfoSchema = z.object({
      * be filed away automatically and one that must not be.
      */
     trigger: z.enum(["daemon", "user"]).nullable().default(null),
+    /**
+     * The head commit this run actually read, set when it finishes.
+     *
+     * `pr.headSha` cannot answer that question: a refresh moves it forward to
+     * keep the comments anchored to current code, without anybody re-reading
+     * anything. The freshness guard compares against *this* instead, so merely
+     * opening a draft after a push no longer convinces the poll that the draft
+     * is up to date. Null on runs recorded before this existed, and on one still
+     * in flight — both fall back to the old comparison.
+     */
+    reviewedSha: z.string().nullable().default(null),
 });
 export const SentInfoSchema = z.object({
     at: z.string(),
@@ -267,6 +278,18 @@ export const ArtifactSchema = z.object({
     sent: SentInfoSchema.nullable().default(null),
     /** Set when cerber filed this draft away itself, and why. Never on a sent one. */
     filed: FiledInfoSchema.nullable().default(null),
+    /**
+     * When this review was settled — marked `reviewed` or `skipped`, by you or by
+     * cerber filing it. Null on anything not settled.
+     *
+     * A settle answers the request that was open at the time. It cannot answer
+     * one that came afterwards, so the poll needs to know which side of it a
+     * review request falls on before deciding a settled row stays settled
+     * (`askedAgainAfterSettling` in `src/server/daemon.ts`). `updatedAt` cannot
+     * stand in for this: opening a settled review refreshes it, which moves that
+     * field forward long after the decision it is meant to date.
+     */
+    settledAt: z.string().nullable().default(null),
     /** 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/gh.js

@@ -254,6 +254,58 @@ export async function fetchReviewRequests(ref) {
 export function stillRequested(requests, login) {
     return requests.teams.length > 0 || requests.users.includes(login);
 }
+export function lastRequestOf(events, login) {
+    const mine = events.filter((e) => e.requestedReviewer?.__typename === "User" && e.requestedReviewer.login === login);
+    if (mine.length === 0)
+        return null;
+    return mine.reduce((a, b) => (b.createdAt > a.createdAt ? b : a)).createdAt;
+}
+// 100 is the page maximum, and it costs exactly what a smaller window would:
+// one call. It wants to be big because the recent events are not the useful
+// ones — a PR that cycled through a dozen reviewers can push the request that
+// named *you* past a short window, and the answer would come back "nobody
+// asked", silently restoring the bug this exists to fix.
+//
+// It is still a window, not a guarantee: a PR carrying more than 100 review
+// requests would lose the oldest, and that is accepted rather than paginated.
+// Paginating would cost one call per extra page on every settled row on every
+// poll, to cover a PR that does not realistically exist — and the failure mode
+// is the conservative one, a row left settled rather than one wrongly reopened.
+const LAST_REQUEST_QUERY = `query($owner:String!,$repo:String!,$number:Int!){
+  repository(owner:$owner,name:$repo){
+    pullRequest(number:$number){
+      timelineItems(last:100,itemTypes:[REVIEW_REQUESTED_EVENT]){
+        nodes{... on ReviewRequestedEvent{createdAt requestedReviewer{__typename ... on User{login}}}}
+      }
+    }
+  }
+}`;
+/**
+ * Ask GitHub when your review was last requested on a PR.
+ *
+ * GraphQL rather than the REST timeline on purpose: this runs on rows the queue
+ * already holds, poll after poll, and the REST timeline of a busy PR is hundreds
+ * of events across several pages — every one of them fetched to find the handful
+ * that are review requests. Filtering server-side to the one event type turns
+ * that into a single call; the window it reads is bounded, as the query above
+ * explains.
+ */
+export async function fetchLastReviewRequest(ref, login) {
+    const out = await gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${LAST_REQUEST_QUERY}`,
+        "-F",
+        `owner=${ref.owner}`,
+        "-F",
+        `repo=${ref.repo}`,
+        "-F",
+        `number=${ref.number}`,
+    ]);
+    const raw = JSON.parse(out);
+    return lastRequestOf(raw.data?.repository?.pullRequest?.timelineItems?.nodes ?? [], login);
+}
 export function searchAwaitingArgs(repoFilter, limit = 50) {
     const args = [
         "search",

package/dist/core/refresh.js

@@ -34,21 +34,52 @@ export function refreshArtifact(artifact, pr, diff) {
     };
 }
 /**
- * Comments a human put work into: their own, and AI ones they rewrote.
- * A re-review regenerates everything the AI said, but must not silently bin
- * these — see carryOverComments.
+ * Is this artifact's status the user's to keep, rather than the run's to set?
+ *
+ * A send or a settle is a decision about the PR; a run finishing is a fact
+ * about the code. Whichever way the run went — a draft or an error — it does
+ * not get to reopen one, which is the same rule `SETTLED_BY_YOU` applies to
+ * starting a run in the first place.
  */
-export function humanComments(artifact) {
-    return artifact.comments.filter((c) => c.origin === "user" || c.editedByUser);
+export function userOwnsStatus(a) {
+    return a.sent !== null || a.status === "reviewed" || a.status === "skipped";
 }
 /**
- * Carry a previous review's human comments into a fresh one, re-anchored to
- * the new diff. AI comments are dropped: the new run just regenerated them.
+ * Fold a finished review run onto whatever the artifact says now.
+ *
+ * A run takes minutes and the cockpit stays live throughout, so by the time one
+ * lands the artifact may have moved under it. Saving the result wholesale
+ * silently undid whatever had happened in between — the same mistake
+ * `mergeConcurrentEdits` exists to stop a chat turn making.
+ *
+ * `fresh` is what the run produced; `current` is what is on disk now. The run
+ * owns the draft — summary, chapters, verdict, comments — and that includes
+ * replacing comments the user wrote: a re-review starts fresh by design, and
+ * `docs/lifecycle.md` says so plainly rather than leaving anyone to count on
+ * work surviving one. What it does *not* own are the decisions:
+ *
+ *   - **a send** stands, and takes the status with it. Without this a run
+ *     finishing after a send wrote `sent: null` back over the record, and the
+ *     "already sent" guard would then wave a second submission through.
+ *   - **a settle** stands too: `reviewed` and `skipped` are decisions about the
+ *     PR, not facts about the code, so a run completing does not reopen one.
+ *     The fresh draft still lands underneath, which is what the row shows if
+ *     the user changes their mind.
+ *   - **the conversation** is the user's writing, snapshot and all.
  */
-export function carryOverComments(previous, fresh) {
-    const human = humanComments(previous);
-    if (human.length === 0)
-        return { comments: fresh.comments, carried: 0, drifted: 0 };
-    const { comments, drifted } = reanchorComments(human, previous.diff, fresh.diff);
-    return { comments: [...fresh.comments, ...comments], carried: comments.length, drifted };
+export function mergeRunResult(fresh, current) {
+    return {
+        ...fresh,
+        status: userOwnsStatus(current) ? current.status : fresh.status,
+        // Travels with the status it dates. A settle that landed while the run
+        // worked keeps both halves of itself, and a run that reopens the row takes
+        // the stamp away with the status.
+        settledAt: userOwnsStatus(current) ? current.settledAt : fresh.settledAt,
+        sent: current.sent,
+        calibration: current.calibration,
+        filed: current.filed,
+        chat: current.chat,
+        preChat: current.preChat,
+        pendingChat: current.pendingChat,
+    };
 }

package/dist/core/state.js

@@ -98,11 +98,21 @@ export async function updateArtifactByKey(key, mutate) {
  * this it stays wedged forever, with no way to retry it from the cockpit. A
  * `cerber review` running in another terminal is the one false positive; it
  * overwrites the artifact when it finishes anyway.
+ *
+ * `inUse` names the runs this process genuinely owns, and they are left alone.
+ * Callers should still reconcile before starting anything that polls — but
+ * ordering alone is a promise about wiring, and this is the guard that holds
+ * whatever order they are started in: without it, reconciliation racing a
+ * daemon's first tick could stamp "interrupted" over a review that had just
+ * legitimately begun.
  */
-export async function reconcileRunning() {
+export async function reconcileRunning(opts = {}) {
+    const inUse = opts.inUse ?? (() => false);
     const artifacts = await listArtifacts();
     let cleared = 0;
     for (const artifact of artifacts) {
+        if (inUse(artifact.id))
+            continue;
         const stuckRun = artifact.status === "running";
         const stuckChat = artifact.pendingChat && artifact.pendingChat.error == null ? artifact.pendingChat : null;
         if (!stuckRun && !stuckChat)

package/dist/runner/review.js

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { AiReviewSchema, SCHEMA_VERSION, artifactId, } from "../core/artifact.js";
+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 { carryOverComments } from "../core/refresh.js";
-import { loadArtifact, saveArtifact } from "../core/state.js";
+import { mergeRunResult, userOwnsStatus } from "../core/refresh.js";
+import { loadArtifact, saveArtifact, updateArtifactByKey } from "../core/state.js";
 import { loadConfig } from "../core/config.js";
 import { decideTrust, membershipQueries, parseTrustRules } from "../core/trust.js";
 import { extractJson, runClaude, unauthenticatedEnv } from "./claude.js";
@@ -32,7 +32,7 @@ const HEAD_SENSITIVE = new Set(["ready", "sent"]);
  * as cerber overruling you — and on a busy PR it happens every few minutes.
  * The way back in is the way you got out: press re-review, which forces.
  */
-const SETTLED_BY_YOU = new Set(["reviewed", "skipped"]);
+export const SETTLED_BY_YOU = new Set(["reviewed", "skipped"]);
 /**
  * Fetch a PR, run the AI review, persist the artifact at each stage.
  * Everything stays local — nothing is ever written to GitHub.
@@ -91,10 +91,15 @@ async function runReview(ref, opts) {
             log(`You marked this ${existing.status} — leaving it alone. Use --force to re-review.`);
             return { artifact: existing, skipped: true };
         }
-        if (HEAD_SENSITIVE.has(existing.status) &&
-            existing.pr.headSha !== "" &&
-            existing.pr.headSha === pr.headSha) {
-            log(`Up to date (head ${pr.headSha.slice(0, 7)}, status ${existing.status}) — skipping. Use --force to re-review.`);
+        // The sha the AI *read*, not the one the artifact happens to mention.
+        // `pr.headSha` is moved forward by the refresh that runs whenever a review
+        // is opened, so comparing against it meant that merely looking at a draft
+        // after a push convinced this guard the draft was current, and the poll
+        // never re-reviewed it again. Older artifacts have no `reviewedSha` and
+        // fall back to the old comparison.
+        const reviewedSha = existing.run?.reviewedSha ?? existing.pr.headSha;
+        if (HEAD_SENSITIVE.has(existing.status) && reviewedSha !== "" && reviewedSha === pr.headSha) {
+            log(`Up to date (reviewed at ${reviewedSha.slice(0, 7)}, status ${existing.status}) — skipping. Use --force to re-review.`);
             return { artifact: existing, skipped: true };
         }
     }
@@ -120,6 +125,14 @@ async function runReview(ref, opts) {
                 `reviewing from the diff alone.`);
         }
     }
+    // A re-review regenerates the draft, comments and all — deliberately, and
+    // including any the user wrote. Carrying them across is a feature this tool
+    // has decided not to have, so nothing here tries to half-keep them: they go
+    // when the run starts, whichever way it ends. `docs/lifecycle.md` says so
+    // where a reader would otherwise assume otherwise.
+    if (existing && existing.comments.length > 0) {
+        log(`Replacing the previous draft's ${existing.comments.length} comment(s) — a re-review starts fresh.`);
+    }
     let artifact = {
         schemaVersion: SCHEMA_VERSION,
         id: artifactId(pr),
@@ -142,10 +155,12 @@ async function runReview(ref, opts) {
             trusted: trusted && source !== null,
             sessionId: null,
             trigger: opts.trigger ?? "user",
+            reviewedSha: null,
         },
         sent: null,
         refresh: null,
         filed: null,
+        settledAt: null,
         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
@@ -204,34 +219,37 @@ async function runReview(ref, opts) {
                 // whose working directory was empty has nothing a chat turn could read.
                 sessionId: source ? review.sessionId : null,
                 trigger: artifact.run.trigger,
+                // What this run actually read — the thing the freshness guard needs
+                // and `pr.headSha` cannot say, because a refresh moves that forward
+                // without anybody re-reading the code.
+                reviewedSha: pr.headSha,
             },
         };
-        // A re-review regenerates the AI's comments, but the human's own comments
-        // and their rewrites of AI ones are work the run must not throw away.
-        if (existing) {
-            const { comments, carried, drifted } = carryOverComments(existing, artifact);
-            if (carried > 0) {
-                artifact = { ...artifact, comments };
-                log(`Carried over ${carried} comment(s) you wrote or edited` +
-                    (drifted > 0 ? `; ${drifted} no longer match the diff and will post in the body.` : "."));
-            }
-        }
     }
     catch (err) {
-        artifact = {
-            ...artifact,
-            status: "failed",
-            updatedAt: now(),
-            run: {
-                ...artifact.run,
-                finishedAt: now(),
-                error: err instanceof Error ? err.message : String(err),
-            },
+        const run = {
+            ...artifact.run,
+            finishedAt: now(),
+            error: err instanceof Error ? err.message : String(err),
         };
-        await saveArtifact(artifact);
+        // Onto what is on disk, not over it: the artifact this run built holds none
+        // of the comments or marks that may have landed while it ran, and a failure
+        // is no reason to lose them — nor to reopen a decision the user made.
+        const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => ({
+            ...a,
+            status: userOwnsStatus(a) ? a.status : "failed",
+            run,
+        }));
+        artifact = saved ?? { ...artifact, status: "failed", run, updatedAt: now() };
+        if (!saved)
+            await saveArtifact(artifact);
         throw err;
     }
-    await saveArtifact(artifact);
+    const merged = await updateArtifactByKey(artifactKey(artifact.id), (current) => mergeRunResult(artifact, current));
+    if (merged)
+        artifact = merged;
+    else
+        await saveArtifact(artifact);
     return { artifact, skipped: false };
 }
 /** Run tasks with bounded concurrency, preserving order of results. */

package/dist/server/daemon.js

@@ -1,12 +1,12 @@
 import { SCHEMA_VERSION, artifactId, artifactKey } from "../core/artifact.js";
 import { evaluateAutoSend } from "../core/autosend.js";
 import { loadConfig } from "../core/config.js";
-import { classifyReply, currentLogin, fetchConversation, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
+import { classifyReply, currentLogin, fetchConversation, fetchLastReviewRequest, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
 import { notice, notify } from "../core/notify.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
 import { appendAutoSendLog, deleteArtifact, listArtifacts, loadArtifact, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { ReviewInProgressError } from "../runner/inflight.js";
-import { pool, reviewPr } from "../runner/review.js";
+import { SETTLED_BY_YOU, pool, reviewPr } from "../runner/review.js";
 /**
  * A pure discovery stub: enough artifact for the queue to show an awaiting row.
  * The AI run that follows (automatic or clicked) replaces it wholesale.
@@ -45,6 +45,7 @@ export function stubArtifact(ref) {
         sent: null,
         refresh: null,
         filed: null,
+        settledAt: null,
         calibration: null,
         chat: [],
         preChat: null,
@@ -122,7 +123,58 @@ export function filedByWithdrawnRequest(artifact) {
         return false;
     return artifact.run?.trigger === "daemon";
 }
-/** How many open-PR artifacts to re-check against GitHub per poll, and how often each. */
+/**
+ * When a settled row was settled, as well as cerber can date it — or null if it
+ * isn't settled at all, or a send already spoke for it.
+ *
+ * `settledAt` is the record and the only exact answer. Rows settled before that
+ * field existed fall back to the latest moment cerber can prove the decision
+ * came after: cerber filed it (`filed.at`), or you settled a draft, which you
+ * cannot have done before the draft existed (`run.finishedAt`). Both are lower
+ * bounds, so a stale one can only make this read a request as newer than it
+ * really was — one row coming back into the inbox once, against leaving every
+ * pre-existing settled row permanently unreachable, which is the bug.
+ *
+ * Not `updatedAt`: opening a settled review refreshes it onto the new head,
+ * which moves that field forward long after the decision it would be dating.
+ */
+export function settledAtOf(a) {
+    if (!SETTLED_BY_YOU.has(a.status) || a.sent)
+        return null;
+    return a.settledAt ?? a.filed?.at ?? a.run?.finishedAt ?? null;
+}
+/**
+ * Whether a review request is a *new* ask rather than the one you settled.
+ *
+ * A skip says "I am done with this PR", and a push does not undo that — the
+ * whole point of `SETTLED_BY_YOU`. Somebody asking you again is a different
+ * event: your skip answered the request that was open when you made it, and it
+ * cannot have answered one that came after. Withdrawn-then-re-added is the
+ * shape this catches, and it is not exotic — an author who pulls the request
+ * while you are mid-look and puts it back with the next push leaves the inbox
+ * silent about a review someone is now actively waiting on.
+ *
+ * Parsed, not compared as text, for the reason `filedByYourAct` gives: our
+ * timestamps carry milliseconds and GitHub's do not, and "…:00.500Z" sorts
+ * before "…:00Z".
+ */
+export function askedAgainAfterSettling(a, requestedAt) {
+    if (requestedAt === null)
+        return false;
+    const settled = settledAtOf(a);
+    return settled !== null && Date.parse(requestedAt) > Date.parse(settled);
+}
+/**
+ * What a reopened row goes back to being: the draft it has, or a row waiting
+ * for one. A run that failed left no draft to show, so it reopens as `awaiting`
+ * and the poll drafts it again.
+ */
+export function reopenedStatus(a) {
+    return a.run?.finishedAt && !a.run.error ? "ready" : "awaiting";
+}
+/** How many artifacts each of the poll's GitHub re-checks — the open-PR state
+ *  refresh, and the settled rows it asks about again — may spend per poll, and
+ *  how often any one artifact is re-asked about. */
 const STATE_REFRESH_CAP = 10;
 const STATE_REFRESH_MIN_MS = 30 * 60_000;
 /**
@@ -162,6 +214,9 @@ export function startDaemon(opts) {
     /** When GitHub last confirmed an artifact's PR state, by artifact id. In-memory:
      *  a restart just re-checks sooner, which is harmless. */
     const stateCheckedAt = new Map();
+    /** When GitHub was last asked whether a settled row has been re-requested, by
+     *  artifact id. In-memory for the same reason: a restart just asks sooner. */
+    const requestCheckedAt = new Map();
     async function discover() {
         const filters = opts.repos.length > 0 ? opts.repos : [undefined];
         const seen = new Set();
@@ -183,9 +238,67 @@ export function startDaemon(opts) {
      */
     async function syncQueue(refs) {
         const discovered = [];
+        /** Reopen checks spent this poll — the same cap the state refresh below obeys. */
+        let reopenChecks = 0;
+        // Asked once per pass, and only if a row actually reaches a check that
+        // needs it. Undefined is "not asked yet"; null is "gh could not say", which
+        // attributes nothing to you rather than guessing.
+        let login;
+        /**
+         * Put a settled row back in the inbox when somebody has asked you again.
+         *
+         * The mirror of `fileIfSettledElsewhere`: that one files rows away once
+         * GitHub has moved past them, this one brings one back when GitHub has
+         * moved *to* it. Both exist because the queue's picture of who is waiting
+         * on what is local, and the thing it is a picture of lives on github.com.
+         *
+         * Only rows GitHub is asking about right now get here at all — the caller
+         * is looping over the awaiting search — so the extra read is one call for
+         * one question: was that request made after you settled?
+         */
+        async function reopenIfAskedAgain(artifact) {
+            if (settledAtOf(artifact) === null)
+                return;
+            const last = requestCheckedAt.get(artifact.id) ?? 0;
+            if (reopenChecks >= STATE_REFRESH_CAP || Date.now() - last < STATE_REFRESH_MIN_MS)
+                return;
+            reopenChecks++;
+            requestCheckedAt.set(artifact.id, Date.now());
+            if (login === undefined)
+                login = await currentLogin().catch(() => null);
+            if (login === null)
+                return;
+            let requestedAt;
+            try {
+                requestedAt = await fetchLastReviewRequest(artifact.pr, login);
+            }
+            catch {
+                // A read that failed is not evidence of anything, so nothing happens to
+                // the row. It is not re-asked about until the leash above expires: the
+                // stamp is spent before the call on purpose, so gh being down cannot
+                // turn every settled row into a retry on every poll.
+                return;
+            }
+            if (requestedAt === null || !askedAgainAfterSettling(artifact, requestedAt))
+                return;
+            const at = requestedAt;
+            // Re-read from disk: a re-review or a send may have started in the time
+            // that call took, and neither wants its status rewritten underneath it.
+            const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => askedAgainAfterSettling(a, at)
+                ? // `filed` goes with the status it explained: cerber's account of why
+                    // this row was settled is not the story of a row that is back.
+                    { ...a, status: reopenedStatus(a), settledAt: null, filed: null }
+                : a);
+            // The status is what says the write landed. `settledAt` cannot: a legacy
+            // row never had one, so a mutation that declined would read as a reopen.
+            if (saved && !SETTLED_BY_YOU.has(saved.status)) {
+                log(`[${artifact.id}] your review was requested again on ${at.slice(0, 10)} — back in the inbox`);
+            }
+        }
         for (const ref of refs) {
             const existing = await loadArtifact(artifactId(ref));
             if (existing) {
+                await reopenIfAskedAgain(existing);
                 // The search result is what the PR is right now; the artifact can
                 // predate a draft→ready flip. Refresh from it — it costs nothing, it's
                 // already in hand — or the queue keeps calling a ready PR a draft until
@@ -201,10 +314,6 @@ export function startDaemon(opts) {
             await saveArtifact(stubArtifact(ref));
             discovered.push(ref);
         }
-        // Asked once per pass, and only if a row actually reaches the check that
-        // needs it. Undefined is "not asked yet"; null is "gh could not say", which
-        // attributes nothing to you rather than guessing.
-        let login;
         /**
          * File a draft away once GitHub has moved past it without cerber's help.
          *
@@ -240,7 +349,7 @@ export function startDaemon(opts) {
             /** Re-reads from disk: a run or a send may have started in the seconds
              *  these reads took, and neither wants filing out from under it. */
             async function file(filed, note, stillFilable) {
-                const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => stillFilable(a) ? { ...a, status: "reviewed", filed } : a);
+                const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => stillFilable(a) ? { ...a, status: "reviewed", filed, settledAt: filed.at } : a);
                 if (saved?.filed)
                     log(`[${artifact.id}] ${note} — filed as reviewed`);
             }

package/dist/server/index.js

@@ -15,7 +15,7 @@ import { DaemonConfigSchema, configPath, loadConfig, saveConfig } from "../core/
 import { refreshArtifact } from "../core/refresh.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
-import { listArtifacts, loadArtifact, loadArtifactByKey, reconcileRunning, saveArtifact, updateArtifactByKey, } from "../core/state.js";
+import { listArtifacts, loadArtifact, loadArtifactByKey, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { isReviewRunning } from "../runner/inflight.js";
 import { reviewPr } from "../runner/review.js";
 import { runChatTurn } from "../runner/chat.js";
@@ -23,6 +23,20 @@ import { mergeConcurrentEdits, restoreReview } from "../core/revise.js";
 import { progressWriter } from "./progress.js";
 import { ChatTurnSchema } from "../core/artifact.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * The statuses `PATCH /api/reviews/:key` will set: the two that are the user's
+ * own decision about a PR. Everything else is a fact some other path owns.
+ */
+const SETTLEABLE = ["reviewed", "skipped"];
+/**
+ * Is an AI run rewriting this draft right now?
+ *
+ * Two questions, because neither alone is enough: `isReviewRunning` is an
+ * in-memory claim and cannot see a `cerber review` going in another terminal,
+ * while the persisted status cannot see a run this process started moments ago
+ * that has not written yet.
+ */
+const inFlight = (a) => a.status === "running" || isReviewRunning(a.id);
 export async function buildApp(opts) {
     const app = new Hono();
     if (opts.token) {
@@ -251,10 +265,12 @@ export async function buildApp(opts) {
                 trusted: false,
                 sessionId: null,
                 trigger: "user",
+                reviewedSha: null,
             },
             sent: null,
             refresh: null,
             filed: null,
+            settledAt: null,
             calibration: null,
             chat: [],
             preChat: null,
@@ -284,10 +300,28 @@ export async function buildApp(opts) {
     // ---- Mutations (all local — artifact edits only) ----
     app.patch("/api/reviews/:key", async (c) => {
         const body = await c.req.json();
+        // Only the two statuses that are the user's own decision. The schema
+        // permits all seven, and taking them all meant this endpoint would happily
+        // write `status: "sent"` with no `sent` record and nothing submitted —
+        // a row that claims a review reached GitHub, which no honest path produces.
+        // `running`/`ready`/`failed` belong to the runner, `sent` to the send path.
+        if (body.status !== undefined && !SETTLEABLE.includes(body.status)) {
+            return c.json({ error: `status must be one of ${SETTLEABLE.join(", ")} — got ${body.status}` }, 400);
+        }
         const updated = await updateArtifactByKey(c.req.param("key"), (a) => {
             const next = { ...a };
             if (body.status !== undefined) {
                 next.status = ArtifactStatusSchema.parse(body.status);
+                // Dated on the way in, because nothing else can date it later: the poll
+                // asks whether a review request came before or after this decision, and
+                // `updatedAt` moves every time the review is opened and refreshed.
+                next.settledAt = new Date().toISOString();
+                // And cerber's own account of why this row was settled goes with the
+                // status it explained. `filed` outranks the status wherever the queue
+                // tags a row (`rowTag`, `requestTag`), on the grounds that "reviewed"
+                // would otherwise read as a click nobody made — which stops being true
+                // the moment you click. Same rule the poll's reopen follows.
+                next.filed = null;
             }
             if (body.verdictRecommendation !== undefined && next.verdict) {
                 next.verdict = {
@@ -429,6 +463,7 @@ export async function buildApp(opts) {
                 trusted: false,
                 sessionId: null,
                 trigger: "user",
+                reviewedSha: null,
             },
         }));
         // Minutes-long: run it detached and let the cockpit poll the artifact.
@@ -589,6 +624,13 @@ export async function buildApp(opts) {
         if (artifact.sent) {
             return c.json({ error: `already sent at ${artifact.sent.at}` }, 409);
         }
+        // Not while a run is rewriting this draft. Vouching for a review that is
+        // being replaced under you is reason enough on its own; on top of that the
+        // run used to save `sent: null` back over the record when it landed, so the
+        // guard above would wave a *second* submission through afterwards.
+        if (inFlight(artifact)) {
+            return c.json({ error: "a review of this PR is running — wait for it to finish" }, 409);
+        }
         const payload = buildReviewPayload(artifact, event);
         try {
             const { url } = await submitReview({ owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number }, { event: payload.event, body: payload.body, comments: payload.comments, commitId: payload.commitId });
@@ -628,11 +670,13 @@ export async function buildApp(opts) {
     }
     return app;
 }
+/**
+ * Serve the cockpit. `reconcileRunning` is deliberately *not* called here: the
+ * caller must have done it before starting the daemon, because the daemon polls
+ * as soon as it is constructed. Doing it here as well would have marked that
+ * poll's own fresh run as an interrupted leftover.
+ */
 export async function startServer(opts) {
-    const cleared = await reconcileRunning();
-    if (cleared > 0) {
-        console.log(`Cleared ${cleared} AI run(s) left in flight by a previous process — start them again from the cockpit.`);
-    }
     const app = await buildApp(opts);
     serve({ fetch: app.fetch, port: opts.port, hostname: opts.host }, (info) => {
         const tokenHint = opts.token ? `/?token=${opts.token}` : "";

package/package.json

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