@fullstackhouse/cerber 0.25.0 → 0.27.0

package/dist/server/daemon.js

@@ -1,10 +1,11 @@
 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, fetchLastReviewRequest, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.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 { 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 { SETTLED_BY_YOU, pool, reviewPr } from "../runner/review.js";
 /**
@@ -144,25 +145,40 @@ export function settledAtOf(a) {
     return a.settledAt ?? a.filed?.at ?? a.run?.finishedAt ?? null;
 }
 /**
- * Whether a review request is a *new* ask rather than the one you settled.
+ * Whether an ask is a *new* one 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.
+ * event: your skip answered whatever was open when you made it, and it cannot
+ * have answered something that came after. Withdrawn-then-re-added is one 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. The other shape is the
+ * same author typing it instead (`Ask`).
  *
  * 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)
+export function askedAgainAfterSettling(a, askedAt) {
+    if (askedAt === null)
         return false;
     const settled = settledAtOf(a);
-    return settled !== null && Date.parse(requestedAt) > Date.parse(settled);
+    return settled !== null && Date.parse(askedAt) > Date.parse(settled);
+}
+/**
+ * What the daemon says about a reopen, in the log and in the row's history.
+ *
+ * One place, so the line the user reads in the terminal and the line they read
+ * on the review months later cannot tell different stories about why a decision
+ * of theirs was undone — which is the only thing that makes undoing it fair.
+ */
+export function askWording(ask) {
+    const day = ask.at.slice(0, 10);
+    const what = ask.how === "requested"
+        ? `your review was requested again on ${day}`
+        : `${ask.by} asked for you by name on ${day}`;
+    return { log: `${what} — back in the inbox`, history: `back in the inbox: ${what}, after you settled it` };
 }
 /**
  * What a reopened row goes back to being: the draft it has, or a row waiting
@@ -244,6 +260,11 @@ export function startDaemon(opts) {
         // needs it. Undefined is "not asked yet"; null is "gh could not say", which
         // attributes nothing to you rather than guessing.
         let login;
+        async function who() {
+            if (login === undefined)
+                login = await currentLogin().catch(() => null);
+            return login;
+        }
         /**
          * Put a settled row back in the inbox when somebody has asked you again.
          *
@@ -252,9 +273,17 @@ export function startDaemon(opts) {
          * 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?
+         * Two ways to be asked, because people use both. GitHub's re-request button
+         * leaves a dated event and is read first: it is the strongest evidence and
+         * the cheapest call. Failing that, the conversation is read for the last
+         * comment naming you — "@you this is ready for another look", which is the
+         * same ask with no event behind it. Reading only the button was the bug:
+         * a settled row sat invisible while its author waited, having said so in
+         * plain words on the PR.
+         *
+         * Only rows GitHub is still asking about get here — the caller is looping
+         * over the awaiting search. A row whose request is gone (you reviewed on
+         * github.com) is caught by `reopenIfAskedInWords` on the other loop instead.
          */
         async function reopenIfAskedAgain(artifact) {
             if (settledAtOf(artifact) === null)
@@ -264,26 +293,72 @@ export function startDaemon(opts) {
                 return;
             reopenChecks++;
             requestCheckedAt.set(artifact.id, Date.now());
-            if (login === undefined)
-                login = await currentLogin().catch(() => null);
-            if (login === null)
+            const me = await who();
+            if (me === null)
                 return;
-            let requestedAt;
+            let ask;
             try {
-                requestedAt = await fetchLastReviewRequest(artifact.pr, login);
+                const requestedAt = await fetchLastReviewRequest(artifact.pr, me);
+                const request = requestedAt === null ? null : { at: requestedAt, how: "requested" };
+                // The words are only worth a second call when the button did not
+                // already answer: a live re-request says everything a comment could.
+                ask = askedAgainAfterSettling(artifact, request?.at ?? null)
+                    ? request
+                    : await askedInWords(artifact, me);
             }
             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.
+                // turn every settled row into a retry on every poll. Only the reads are
+                // guarded: a write that fails is a real fault and belongs to the caller.
                 return;
             }
-            if (requestedAt === null || !askedAgainAfterSettling(artifact, requestedAt))
+            await reopen(artifact, ask);
+        }
+        /**
+         * The same reopen for a settled row GitHub is *not* asking about.
+         *
+         * The case is ordinary: you reviewed on github.com, which clears the
+         * request and drops the PR out of the awaiting search, and the author then
+         * pushes and writes "@you ready for another look". No request exists to
+         * re-read, so the words are the whole of the evidence — and without this
+         * the mention check would only work for the rows that happen to still carry
+         * an open request, which is a fix that half-works.
+         *
+         * Rides the state-refresh leash rather than one of its own: the caller has
+         * already spent that artifact's slot for this half-hour, and a settled row
+         * never reaches `fileIfSettledElsewhere`, so this costs the poll one call
+         * on rows that were costing it one already.
+         */
+        async function reopenIfAskedInWords(artifact) {
+            if (settledAtOf(artifact) === null)
                 return;
-            const at = requestedAt;
+            const me = await who();
+            if (me === null)
+                return;
+            let ask;
+            try {
+                ask = await askedInWords(artifact, me);
+            }
+            catch {
+                // Same as above: a failed read changes nothing and waits for the leash.
+                return;
+            }
+            await reopen(artifact, ask);
+        }
+        /** The conversation's answer to "has anybody asked for me again", or null. */
+        async function askedInWords(artifact, me) {
+            const mention = lastMentionOfYou(await fetchConversation(artifact.pr), me);
+            return mention === null ? null : { at: mention.at, how: "mentioned", by: mention.author };
+        }
+        /** Undo the settle, if the ask really is newer than it. */
+        async function reopen(artifact, ask) {
+            if (ask === null || !askedAgainAfterSettling(artifact, ask.at))
+                return;
+            const at = ask.at;
             // 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.
+            // those calls 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.
@@ -292,7 +367,11 @@ export function startDaemon(opts) {
             // 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`);
+                const said = askWording(ask);
+                log(`[${artifact.id}] ${said.log}`);
+                // 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, said.history);
             }
         }
         for (const ref of refs) {
@@ -341,11 +420,9 @@ export function startDaemon(opts) {
             // that could never qualify costs no GitHub call at all.
             if (artifact.status !== "ready" || artifact.sent)
                 return;
-            if (login === undefined)
-                login = await currentLogin().catch(() => null);
-            if (login === null)
+            const me = await who();
+            if (me === null)
                 return;
-            const me = login;
             /** 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) {
@@ -374,15 +451,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)));
@@ -437,8 +520,14 @@ export function startDaemon(opts) {
                 }
                 if (pr.state !== "OPEN")
                     log(`[${artifact.id}] ${pr.state.toLowerCase()} — archived`);
-                else
+                else {
+                    // Exactly one of these two spends a call: the first only looks at
+                    // settled rows, the second only at finished drafts. They are the same
+                    // question from opposite sides — has GitHub moved past this, or back
+                    // to it — and a row can only be on one side of it.
+                    await reopenIfAskedInWords(artifact);
                     await fileIfSettledElsewhere(artifact);
+                }
             }
             catch {
                 // Same: book-keeping can wait for the next poll.
@@ -543,7 +632,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) => {

package/package.json

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