@fullstackhouse/cerber 0.24.1 → 0.25.0

package/dist/core/artifact.js

@@ -278,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

@@ -71,6 +71,10 @@ 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,

package/dist/runner/review.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.
@@ -160,6 +160,7 @@ async function runReview(ref, opts) {
         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

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

@@ -270,6 +270,7 @@ export async function buildApp(opts) {
             sent: null,
             refresh: null,
             filed: null,
+            settledAt: null,
             calibration: null,
             chat: [],
             preChat: null,
@@ -311,6 +312,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.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)",