@fullstackhouse/cerber 0.24.1 → 0.26.0

package/dist/server/daemon.js

@@ -1,12 +1,13 @@
 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 { withWriter } from "../core/history.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 { appendAutoSendLog, deleteArtifact, listArtifacts, loadArtifact, noteHistory, 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 +46,7 @@ export function stubArtifact(ref) {
         sent: null,
         refresh: null,
         filed: null,
+        settledAt: null,
         calibration: null,
         chat: [],
         preChat: null,
@@ -122,7 +124,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 +215,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 +239,70 @@ 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`);
+                // The status change alone says a row moved; this says why it moved,
+                // which is the whole reason a settle is allowed to be undone at all.
+                await noteHistory(artifact.id, `back in the inbox: your review was requested again on ${at.slice(0, 10)}, after you settled it`);
+            }
+        }
         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 +318,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 +353,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`);
             }
@@ -265,15 +378,21 @@ export function startDaemon(opts) {
             }
             // Anything but silence from you leaves the row alone: `them` is somebody
             // answering a comment of yours, which is the opposite of settled.
-            if (classifyReply(conversation, me) !== "none")
+            if (classifyReply(conversation, me) !== "none") {
+                await noteHistory(artifact.id, "someone has answered you on the PR — the draft stays out for you");
                 return;
+            }
             if (!filedByWithdrawnRequest(artifact))
                 return;
             // The awaiting search says nobody is asking, and here that is the entire
             // case — so confirm it against the PR itself before acting on it. The
             // other two reasons stand on a fact of their own and need no such check.
-            if (stillRequested(await fetchReviewRequests(artifact.pr), me))
+            if (stillRequested(await fetchReviewRequests(artifact.pr), me)) {
+                // The one fact GitHub cannot be asked for later: what its search index
+                // said at this minute, and that the PR itself disagreed with it.
+                await noteHistory(artifact.id, "gone from the awaiting search, but GitHub still lists you as a requested reviewer — left alone");
                 return;
+            }
             await file({ at: new Date().toISOString(), reason: "request-withdrawn", review: null, reply: null }, "nobody is asking for this review any more", filedByWithdrawnRequest);
         }
         const awaitingIds = new Set(refs.map((r) => artifactId(r)));
@@ -434,7 +553,10 @@ export function startDaemon(opts) {
         });
         return { reviewed, skipped, failed };
     }
-    async function poll() {
+    /** Everything a poll writes is the poll's — including the reviews it starts,
+     *  which stamp themselves as runs from inside this. */
+    const poll = () => withWriter({ by: "daemon", cause: "poll" }, runPoll);
+    async function runPoll() {
         if (status.polling)
             return;
         status.polling = true;

package/dist/server/index.js

@@ -13,6 +13,7 @@ import { fetchPrDiff, fetchPrInfo, parsePrRef, submitReview } from "../core/gh.j
 import { z } from "zod";
 import { DaemonConfigSchema, configPath, loadConfig, saveConfig } from "../core/config.js";
 import { refreshArtifact } 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";
 import { listArtifacts, loadArtifact, loadArtifactByKey, saveArtifact, updateArtifactByKey, } from "../core/state.js";
@@ -39,6 +40,11 @@ const SETTLEABLE = ["reviewed", "skipped"];
 const inFlight = (a) => a.status === "running" || isReviewRunning(a.id);
 export async function buildApp(opts) {
     const app = new Hono();
+    // Whatever any route writes to an artifact is stamped with the request that
+    // caused it — once, here, rather than route by route, so a route added later
+    // is labelled without knowing that history exists. A detached run started by
+    // a request re-labels its own writes for itself.
+    app.use("*", (c, next) => withWriter({ by: "cockpit", cause: `${c.req.method} ${new URL(c.req.url).pathname}` }, next));
     if (opts.token) {
         const token = opts.token;
         app.use("*", async (c, next) => {
@@ -270,6 +276,7 @@ export async function buildApp(opts) {
             sent: null,
             refresh: null,
             filed: null,
+            settledAt: null,
             calibration: null,
             chat: [],
             preChat: null,
@@ -311,6 +318,16 @@ export async function buildApp(opts) {
             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 = {

package/package.json

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