@fullstackhouse/cerber 0.20.0 → 0.22.0

package/README.md

@@ -60,6 +60,20 @@ inbox — cerber never tells you nothing awaits you while its own poll says
 otherwise. It is a report, not a nag: what you decided here stands, and the
 mark clears itself the moment GitHub hears from you.
 
+### Except when you reviewed it on GitHub
+
+There is one thing you never have to settle by hand. Review a PR the ordinary
+way — GitHub's own review button, cerber not involved — and the review request
+clears, but nothing here hears about it: the draft cerber wrote for that PR
+goes on sitting in the inbox as work still waiting on you, days after the PR
+went back to its author. So the poll asks the other question too. When GitHub
+has stopped requesting your review *and* already holds one of yours, the draft
+is filed under settled, tagged `reviewed on GitHub` with the date it was
+submitted. Nothing else happens to it — it was never sent, and it is still
+yours to open, re-review or send. The one draft this leaves alone is one you
+asked for *after* that review: a second opinion you went and requested is not
+a row the queue forgot to close.
+
 ### Whose move is it
 
 An open request doesn't mean the ball is yours, though. You may have argued the
@@ -84,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

@@ -89,6 +89,14 @@ export const RunInfoSchema = z.object({
      * reviewer answering a question still holds everything it read.
      */
     sessionId: z.string().nullable().default(null),
+    /**
+     * Who asked for this run: the inbox poll, or a person — the cockpit's review
+     * button, a pasted URL, `cerber review`. Null on runs recorded before this
+     * was kept. It is what tells a draft the queue produced on its own from one
+     * you deliberately asked for, which is the difference between a row that can
+     * be filed away automatically and one that must not be.
+     */
+    trigger: z.enum(["daemon", "user"]).nullable().default(null),
 });
 export const SentInfoSchema = z.object({
     at: z.string(),
@@ -97,6 +105,23 @@ export const SentInfoSchema = z.object({
     /** True when the daemon auto-sent this review (opt-in --auto-send). */
     auto: z.boolean().default(false),
 });
+/**
+ * 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.
+ */
+export const FiledInfoSchema = z.object({
+    at: z.string(),
+    /** The review of yours GitHub had, which is what settled this one. */
+    review: z.object({
+        at: z.string(),
+        state: z.enum(["APPROVED", "CHANGES_REQUESTED", "COMMENTED"]),
+        url: z.string().nullable().default(null),
+    }),
+});
 /** Result of pulling a review forward onto a newer head commit. */
 export const RefreshInfoSchema = z.object({
     at: z.string(),
@@ -225,6 +250,8 @@ export const ArtifactSchema = z.object({
     run: RunInfoSchema.nullable().default(null),
     /** Set once the review was sent to GitHub (explicitly, or via opt-in auto-send). */
     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),
     /** 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

@@ -158,6 +158,38 @@ 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 last review of your own that still stands, or null.
+ *
+ * PENDING is a draft on GitHub's side and has no `submitted_at`, so it is not
+ * a review anyone has seen. DISMISSED is one a maintainer explicitly struck
+ * off; taking it as "you have had your say" would file work away on the
+ * strength of a review GitHub no longer counts.
+ */
+const STANDS = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED"]);
+export function latestOwnReview(rows, login) {
+    const mine = rows.filter((r) => r.author === login && r.at != null && STANDS.has(r.state));
+    if (mine.length === 0)
+        return null;
+    const last = mine.reduce((a, b) => (b.at > a.at ? b : a));
+    return { at: last.at, state: last.state, url: last.url };
+}
+/** Ask GitHub whether you have reviewed this PR yourself. */
+export async function fetchOwnReview(ref, login) {
+    const out = await gh([
+        "api",
+        "--paginate",
+        `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}/reviews`,
+        "--jq",
+        ".[] | {author: .user.login, at: .submitted_at, state: .state, url: .html_url}",
+    ]);
+    // --jq streams one object per line rather than a JSON array.
+    const rows = out
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => JSON.parse(line));
+    return latestOwnReview(rows, login);
+}
 /** The login `@me` resolves to. Asked once — it cannot change mid-process. */
 let cachedLogin = null;
 export function currentLogin() {

package/dist/runner/review.js

@@ -123,9 +123,11 @@ async function runReview(ref, opts) {
             withSource: source !== null,
             trusted: trusted && source !== null,
             sessionId: null,
+            trigger: opts.trigger ?? "user",
         },
         sent: null,
         refresh: null,
+        filed: 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
@@ -183,6 +185,7 @@ async function runReview(ref, opts) {
                 // Only worth keeping when there is a checkout to resume into: a session
                 // whose working directory was empty has nothing a chat turn could read.
                 sessionId: source ? review.sessionId : null,
+                trigger: artifact.run.trigger,
             },
         };
         // A re-review regenerates the AI's comments, but the human's own comments

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, fetchPrInfo, searchAwaitingMe, submitReview, } from "../core/gh.js";
+import { classifyReply, currentLogin, fetchConversation, fetchOwnReview, fetchPrInfo, searchAwaitingMe, 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";
@@ -43,6 +43,7 @@ export function stubArtifact(ref) {
         run: null,
         sent: null,
         refresh: null,
+        filed: null,
         calibration: null,
         chat: [],
         preChat: null,
@@ -65,6 +66,39 @@ export function stubArtifact(ref) {
 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * shipped stuck in the inbox forever, which is the bug. The cost of being wrong
+ * 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)
+        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));
+}
 /** How many open-PR artifacts to re-check against GitHub per poll, and how often each. */
 const STATE_REFRESH_CAP = 10;
 const STATE_REFRESH_MIN_MS = 30 * 60_000;
@@ -141,6 +175,40 @@ export function startDaemon(opts) {
             await saveArtifact(stubArtifact(ref));
             discovered++;
         }
+        // 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 says you already reviewed the PR yourself.
+         *
+         * 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.
+         */
+        async function fileIfYouReviewedItYourself(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)
+                return;
+            if (login === undefined)
+                login = await currentLogin().catch(() => null);
+            if (login === null)
+                return;
+            const review = await fetchOwnReview(artifact.pr, login);
+            if (!review || !filedByOwnReview(artifact, review))
+                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`);
+            }
+        }
         const awaitingIds = new Set(refs.map((r) => artifactId(r)));
         let refreshed = 0;
         for (const artifact of await listArtifacts()) {
@@ -193,6 +261,8 @@ export function startDaemon(opts) {
                 }
                 if (pr.state !== "OPEN")
                     log(`[${artifact.id}] ${pr.state.toLowerCase()} — archived`);
+                else
+                    await fileIfYouReviewedItYourself(artifact);
             }
             catch {
                 // Same: book-keeping can wait for the next poll.
@@ -237,6 +307,7 @@ export function startDaemon(opts) {
             try {
                 const result = await reviewPr(ref, {
                     model: opts.model,
+                    trigger: "daemon",
                     withSource: opts.withSource,
                     trust: opts.trust,
                     onProgress: (m) => log(`[${label}] ${m}`),

package/dist/server/index.js

@@ -165,6 +165,8 @@ export async function buildApp(opts) {
             trusted: a.run?.trusted ?? null,
             runError: a.run?.error ?? null,
             sent: a.sent ? { at: a.sent.at, event: a.sent.event, url: a.sent.url, auto: a.sent.auto ?? false } : null,
+            // Why a settled row is settled, when cerber settled it rather than you.
+            filed: a.filed,
         })));
     });
     // ---- Pull a PR in: review anything, not just what the inbox found ----
@@ -248,9 +250,11 @@ export async function buildApp(opts) {
                 withSource: withSource !== false,
                 trusted: false,
                 sessionId: null,
+                trigger: "user",
             },
             sent: null,
             refresh: null,
+            filed: null,
             calibration: null,
             chat: [],
             preChat: null,
@@ -424,6 +428,7 @@ export async function buildApp(opts) {
                 withSource: withSource !== false,
                 trusted: false,
                 sessionId: null,
+                trigger: "user",
             },
         }));
         // Minutes-long: run it detached and let the cockpit poll the artifact.

package/package.json

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