@fullstackhouse/cerber 0.21.0 → 0.23.0

package/README.md

@@ -98,6 +98,11 @@ the record of what has been announced are per-browser, kept in that browser
 rather than in `~/.cerber/config.json` — the permission they gate is the
 browser's, so a second browser starts its own record.
 
+The tab itself says it too, without asking anyone: while the inbox holds
+anything, the favicon wears a red dot, and it goes away when the last review is
+dealt with. No permission, no switch — just the paw with a mark on it, so a
+glance at the tab strip answers "is there anything for me?".
+
 ## What a review looks like
 
 Each review is a plain JSON artifact in `~/.cerber/reviews/` (override with

package/dist/core/artifact.js

@@ -108,19 +108,34 @@ export const SentInfoSchema = z.object({
 /**
  * Why a draft was filed away without ever being sent.
  *
- * The only cause today is the one the queue could not see before: you reviewed
- * the PR through GitHub itself, so cerber's draft is a second opinion on a
- * conversation you already had. It is a record, not a decision to defend — the
- * review is untouched, still openable and still sendable.
+ * All three causes are the same shape of fact: the inbox was still holding a
+ * row out for you that GitHub had already moved past. You reviewed the PR
+ * through GitHub itself; you answered in the conversation and nobody has
+ * answered back; or whoever asked for the review took the request away. It is
+ * a record, not a decision to defend — the review is untouched, still openable
+ * and still sendable.
+ *
+ * `reason` defaults to the one that shipped first, so artifacts written before
+ * the other two existed load unchanged and keep saying what they always said.
  */
+export const FiledReasonSchema = z.enum(["own-review", "own-reply", "request-withdrawn"]);
 export const FiledInfoSchema = z.object({
     at: z.string(),
-    /** The review of yours GitHub had, which is what settled this one. */
-    review: z.object({
+    reason: FiledReasonSchema.default("own-review"),
+    /** The review of yours GitHub had. Set when `reason` is "own-review". */
+    review: z
+        .object({
         at: z.string(),
         state: z.enum(["APPROVED", "CHANGES_REQUESTED", "COMMENTED"]),
         url: z.string().nullable().default(null),
-    }),
+    })
+        .nullable()
+        .default(null),
+    /** The comment that gave you the last word. Set when `reason` is "own-reply". */
+    reply: z
+        .object({ at: z.string(), url: z.string().nullable().default(null) })
+        .nullable()
+        .default(null),
 });
 /** Result of pulling a review forward onto a newer head commit. */
 export const RefreshInfoSchema = z.object({

package/dist/core/gh.js

@@ -132,7 +132,7 @@ export async function fetchConversation(ref) {
         "--paginate",
         `repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments`,
         "--jq",
-        '.[] | {author: .user.login, at: .created_at, bot: (.user.type == "Bot")}',
+        '.[] | {author: .user.login, at: .created_at, bot: (.user.type == "Bot"), url: .html_url}',
     ]);
     // --jq streams one object per line rather than a JSON array.
     return out
@@ -158,6 +158,21 @@ export function classifyReply(comments, login) {
     // answer to it, so only strictly-later comments hand the move back.
     return human.some((c) => c.author !== login && c.at > lastMine) ? "them" : "you";
 }
+/**
+ * The comment that gave you the last word, or null if it isn't yours.
+ *
+ * Answers "you have said your piece and nobody has answered since" with the
+ * comment that says it, so a draft filed on the strength of it can point at
+ * the thing on GitHub it was filed for. Routed through `classifyReply` rather
+ * than re-deriving the rule, so the tag on a row and the reason it was filed
+ * can never disagree about who spoke last.
+ */
+export function lastWordOfYours(comments, login) {
+    if (classifyReply(comments, login) !== "you")
+        return null;
+    const mine = comments.filter((c) => !isBot(c) && c.author === login);
+    return mine[mine.length - 1] ?? null;
+}
 /**
  * The last review of your own that still stands, or null.
  *
@@ -206,6 +221,39 @@ export function currentLogin() {
 export function resetLoginCache() {
     cachedLogin = null;
 }
+export async function fetchReviewRequests(ref) {
+    const out = await gh([
+        "pr",
+        "view",
+        String(ref.number),
+        "--repo",
+        `${ref.owner}/${ref.repo}`,
+        "--json",
+        "reviewRequests",
+    ]);
+    const raw = JSON.parse(out);
+    const users = [];
+    const teams = [];
+    for (const r of raw.reviewRequests ?? []) {
+        if (r.login)
+            users.push(r.login);
+        else if (r.slug ?? r.name)
+            teams.push((r.slug ?? r.name));
+    }
+    return { users, teams };
+}
+/**
+ * Whether GitHub might still be asking *you*, specifically.
+ *
+ * A team request names the team and not its members, so it can never rule you
+ * out — and a membership lookup to settle it would be a third call to answer a
+ * question whose only use is deciding not to act. Treating any team request as
+ * possibly-you costs one draft left in the inbox; the other way round files
+ * away a review someone is waiting on.
+ */
+export function stillRequested(requests, login) {
+    return requests.teams.length > 0 || requests.users.includes(login);
+}
 export function searchAwaitingArgs(repoFilter, limit = 50) {
     const args = [
         "search",

package/dist/runner/review.js

@@ -16,8 +16,23 @@ const OFF_TOOLS = ["Bash", "Edit", "Write", "NotebookEdit", "Task", "WebFetch",
 /** A trusted reviewer may run things. It still may not rewrite the PR. */
 const TRUSTED_TOOLS = [...READ_TOOLS, "Bash", "WebFetch", "WebSearch"];
 const TRUSTED_OFF_TOOLS = ["Edit", "Write", "NotebookEdit"];
-/** Statuses that a fresh artifact can keep without a re-run. */
-const FRESH_STATUSES = new Set(["ready", "reviewed", "sent", "skipped"]);
+/**
+ * Statuses a re-review may overwrite once the PR has moved on. A draft nobody
+ * has acted on should track the current head, and a sent review has cleared
+ * GitHub's request — a fresh one only ever arrives because the author asked
+ * again, which is exactly when a new draft is the point.
+ */
+const HEAD_SENSITIVE = new Set(["ready", "sent"]);
+/**
+ * Statuses that are your decision, not a fact about the code.
+ *
+ * Marking a review reviewed or skipped says you are done with this PR. New
+ * commits do not undo that: the author pushing again would otherwise drag the
+ * row back into the inbox with a fresh draft on top, which is the same thing
+ * 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"]);
 /**
  * Fetch a PR, run the AI review, persist the artifact at each stage.
  * Everything stays local — nothing is ever written to GitHub.
@@ -71,9 +86,12 @@ async function runReview(ref, opts) {
     log(`Fetching ${ref.owner}/${ref.repo}#${ref.number}…`);
     const pr = await fetchPrInfo(ref);
     const existing = await loadArtifact(artifactId(pr));
-    if (!opts.force) {
-        if (existing &&
-            FRESH_STATUSES.has(existing.status) &&
+    if (existing && !opts.force) {
+        if (SETTLED_BY_YOU.has(existing.status)) {
+            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.`);

package/dist/server/daemon.js

@@ -1,7 +1,7 @@
 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, searchAwaitingMe, submitReview, } from "../core/gh.js";
+import { classifyReply, currentLogin, fetchConversation, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.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";
@@ -67,21 +67,25 @@ export function isPureStub(artifact) {
     return artifact.status === "awaiting" && artifact.comments.length === 0 && artifact.run === null;
 }
 /**
- * Whether a review of yours on GitHub settles this draft.
+ * Whether something you did on GitHub at `at` settles this draft.
  *
  * Two facts have to hold. GitHub must have stopped asking you — the caller has
  * already established that, since this only runs on artifacts absent from the
- * awaiting search — and you must have submitted a review of your own, which is
- * the half cerber could not see before: a review clears the request whether it
- * went through Send or through GitHub's own button, and only the first left a
- * trace here. Together they mean the PR is back with its author, while the
- * inbox went on listing the draft as work still waiting on you.
+ * awaiting search — and you must have had your say, which is the half cerber
+ * could not see before: it happens on github.com and leaves no trace here.
+ * Together they mean the PR is back with its author, while the inbox went on
+ * listing the draft as work still waiting on you.
+ *
+ * Having your say is a review of your own or a comment nobody has answered
+ * since. GitHub counts only the first as a review — a comment leaves the
+ * request standing — but the question here is not what GitHub counts, it is
+ * whether the row is still work. Somebody waiting on the author is not.
  *
  * The trigger test is what keeps this from undoing a deliberate act. A draft
  * you asked for — pasted the URL in, pressed re-review — after you had already
- * reviewed the PR is a second opinion you went and requested, so filing it
- * away would answer a question you had just posed. A draft the poll wrote on
- * its own carries no such intent: it is exactly the row this is here to close.
+ * spoken is a second opinion you went and requested, so filing it away would
+ * answer a question you had just posed. A draft the poll wrote on its own
+ * carries no such intent: it is exactly the row this is here to close.
  *
  * A run recorded before the trigger was kept is treated as the poll's, which is
  * the deliberate choice: the alternative leaves every draft written before this
@@ -89,15 +93,33 @@ export function isPureStub(artifact) {
  * is one legacy draft filed once — and the re-review that un-files it records a
  * trigger, so it cannot happen to the same row twice.
  */
-export function filedByOwnReview(artifact, review) {
-    if (artifact.status !== "ready" || artifact.sent || !review)
+export function filedByYourAct(artifact, at) {
+    if (artifact.status !== "ready" || artifact.sent || at === null)
         return false;
     const run = artifact.run;
     // Parsed, not compared as text. `startedAt` carries milliseconds and GitHub's
     // `submitted_at` does not, and "…:00.500Z" sorts *before* "…:00Z" — so a run
     // that began half a second after your review would read as older than it, and
     // the second opinion this guard exists to protect would be filed away.
-    return !(run?.trigger === "user" && Date.parse(run.startedAt) >= Date.parse(review.at));
+    return !(run?.trigger === "user" && Date.parse(run.startedAt) >= Date.parse(at));
+}
+/**
+ * Whether a review request that simply went away settles this draft.
+ *
+ * The other two reasons rest on something you did; this one rests on something
+ * that stopped being true, which is a weaker kind of evidence and gets a
+ * stricter guard for it. Only a draft the poll wrote on its own can be filed
+ * this way: the poll only ever writes one because GitHub asked you, so the
+ * request going away is the whole of that draft's reason for existing going
+ * away. A draft you pasted in or asked for was never in that search to begin
+ * with, and `null` — a run older than the trigger field — cannot be told from
+ * one, so neither qualifies. Unlike the own-review case there is no second
+ * fact to fall back on, so an unknown here has to mean no.
+ */
+export function filedByWithdrawnRequest(artifact) {
+    if (artifact.status !== "ready" || artifact.sent)
+        return false;
+    return artifact.run?.trigger === "daemon";
 }
 /** How many open-PR artifacts to re-check against GitHub per poll, and how often each. */
 const STATE_REFRESH_CAP = 10;
@@ -180,15 +202,28 @@ export function startDaemon(opts) {
         // attributes nothing to you rather than guessing.
         let login;
         /**
-         * File a draft away once GitHub says you already reviewed the PR yourself.
+         * File a draft away once GitHub has moved past it without cerber's help.
+         *
+         * The queue lists what you have not dealt with locally, and everything that
+         * happens on github.com is invisible to it — so a PR you answered days ago
+         * sat in the inbox as if it still wanted you. Three ways that happens, in
+         * the order of how much they say:
+         *
+         *   1. You submitted a review there. The strongest: GitHub itself counts it.
+         *   2. You commented and nobody has answered since. Not a review as far as
+         *      GitHub is concerned, but the ball is still in the author's court.
+         *   3. Nobody is asking any more. You never said anything; whoever
+         *      requested you took the request back, or the PR got its reviews
+         *      elsewhere. Nothing left here is work.
+         *
+         * Someone answering your comment (`them`) is the case that deliberately
+         * files nothing: that is a reply addressed to you, sitting on a PR whose
+         * draft is right here.
          *
-         * The queue lists what you have not dealt with locally, and a review
-         * submitted on github.com never reached it — so a PR you answered days ago
-         * sat in the inbox as if it still wanted you. This is the one read that
-         * closes that gap, on the same 30-minute-per-artifact leash as the state
-         * check it rides along with.
+         * All of it rides the same 30-minute-per-artifact leash as the state check
+         * it hangs off, so a queue of a hundred rows is still a handful of calls.
          */
-        async function fileIfYouReviewedItYourself(artifact) {
+        async function fileIfSettledElsewhere(artifact) {
             // Only a finished, unsent draft can be filed — checked here too, so a row
             // that could never qualify costs no GitHub call at all.
             if (artifact.status !== "ready" || artifact.sent)
@@ -197,17 +232,45 @@ export function startDaemon(opts) {
                 login = await currentLogin().catch(() => null);
             if (login === null)
                 return;
-            const review = await fetchOwnReview(artifact.pr, login);
-            if (!review || !filedByOwnReview(artifact, review))
+            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) {
+                const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => stillFilable(a) ? { ...a, status: "reviewed", filed } : a);
+                if (saved?.filed)
+                    log(`[${artifact.id}] ${note} — filed as reviewed`);
+            }
+            const review = await fetchOwnReview(artifact.pr, me);
+            if (review) {
+                // A review of yours is the answer either way: if the guard rejects it,
+                // this is a second opinion you asked for, not a row to keep looking for
+                // another reason to file.
+                if (filedByYourAct(artifact, review.at)) {
+                    await file({ at: new Date().toISOString(), reason: "own-review", review, reply: null }, `you reviewed this on GitHub on ${review.at.slice(0, 10)}`, (a) => filedByYourAct(a, review.at));
+                }
+                return;
+            }
+            const conversation = await fetchConversation(artifact.pr);
+            const mine = lastWordOfYours(conversation, me);
+            if (mine) {
+                if (filedByYourAct(artifact, mine.at)) {
+                    const reply = { at: mine.at, url: mine.url };
+                    await file({ at: new Date().toISOString(), reason: "own-reply", review: null, reply }, `you replied on GitHub on ${mine.at.slice(0, 10)} and nobody has answered since`, (a) => filedByYourAct(a, mine.at));
+                }
                 return;
-            const filed = { at: new Date().toISOString(), review };
-            const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => 
-            // Re-read from disk: a run or a send may have started in the seconds
-            // this read took, and neither wants filing out from under it.
-            filedByOwnReview(a, review) ? { ...a, status: "reviewed", filed } : a);
-            if (saved?.filed) {
-                log(`[${artifact.id}] you reviewed this on GitHub on ${review.at.slice(0, 10)} — filed as reviewed`);
             }
+            // 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")
+                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))
+                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)));
         let refreshed = 0;
@@ -262,7 +325,7 @@ export function startDaemon(opts) {
                 if (pr.state !== "OPEN")
                     log(`[${artifact.id}] ${pr.state.toLowerCase()} — archived`);
                 else
-                    await fileIfYouReviewedItYourself(artifact);
+                    await fileIfSettledElsewhere(artifact);
             }
             catch {
                 // Same: book-keeping can wait for the next poll.

package/package.json

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