@fullstackhouse/cerber 0.24.0 → 0.24.1

package/README.md

@@ -384,6 +384,13 @@ shadow mode for a while: every would-send decision lands in
 verdicts and comments survive your review — enable auto-send when its 90%
 actually means 90%.
 
+## How it works
+
+[**docs/lifecycle.md**](docs/lifecycle.md) is the reference behind everything
+above: the seven statuses and what sets each, which tab a PR lands in and why,
+when the poll files or archives a row on its own, when a re-review happens and
+what it will not overwrite, and what gets written to disk at each step.
+
 ## Development
 
 ```bash

package/dist/cli/index.js

@@ -8,8 +8,9 @@ import { configPath, loadConfig, saveConfig } from "../core/config.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { parsePrRef, searchAwaitingMe, submitReview } from "../core/gh.js";
 import { buildReviewPayload, computeCalibration, eventForRecommendation } from "../core/send.js";
-import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, updateArtifactByKey, } from "../core/state.js";
+import { cerberHome, listArtifacts, loadArtifact, readAutoSendLog, reconcileRunning, updateArtifactByKey, } from "../core/state.js";
 import { pool, reviewPr } from "../runner/review.js";
+import { isReviewRunning } from "../runner/inflight.js";
 import { startDaemon } from "../server/daemon.js";
 import { startServer } from "../server/index.js";
 const program = new Command();
@@ -135,6 +136,15 @@ program
         console.error(`Already sent at ${artifact.sent.at}${artifact.sent.url ? ` — ${artifact.sent.url}` : ""}`);
         process.exit(1);
     }
+    // The persisted status is the only signal here: a run started by `serve` or
+    // by another terminal is invisible to this process. Sending mid-run vouches
+    // for a draft that is being replaced as you read it.
+    if (artifact.status === "running") {
+        console.error(`A review of ${id} is running — wait for it to finish, then send. ` +
+            `If nothing is actually running, the last run died mid-flight: re-run it, or restart \`cerber serve\`, ` +
+            `either of which clears the stale status.`);
+        process.exit(1);
+    }
     const event = (opts.event ??
         (artifact.verdict ? eventForRecommendation(artifact.verdict.recommendation) : "COMMENT")).toUpperCase();
     if (!["APPROVE", "COMMENT", "REQUEST_CHANGES"].includes(event)) {
@@ -352,6 +362,13 @@ program
             `matching PRs, with nobody watching. Pass --no-trust to keep every review read-only, ` +
             `or --no-auto-review to only review on click.`);
     }
+    // Before anything polls. Reconciliation is what makes "nothing is running"
+    // true after an unclean shutdown, and the daemon's first tick fires the
+    // moment it is constructed — so starting it first put both of them on the
+    // same leftover artifact with no ordering between them.
+    const cleared = await reconcileRunning({ inUse: isReviewRunning });
+    if (cleared > 0)
+        console.log(`Cleared ${cleared} interrupted run(s) left by a previous process.`);
     const daemon = opts.poll
         ? startDaemon({
             repos: opts.repo.length > 0 ? opts.repo : d.repos,

package/dist/core/artifact.js

@@ -97,6 +97,17 @@ export const RunInfoSchema = z.object({
      * be filed away automatically and one that must not be.
      */
     trigger: z.enum(["daemon", "user"]).nullable().default(null),
+    /**
+     * The head commit this run actually read, set when it finishes.
+     *
+     * `pr.headSha` cannot answer that question: a refresh moves it forward to
+     * keep the comments anchored to current code, without anybody re-reading
+     * anything. The freshness guard compares against *this* instead, so merely
+     * opening a draft after a push no longer convinces the poll that the draft
+     * is up to date. Null on runs recorded before this existed, and on one still
+     * in flight — both fall back to the old comparison.
+     */
+    reviewedSha: z.string().nullable().default(null),
 });
 export const SentInfoSchema = z.object({
     at: z.string(),

package/dist/core/refresh.js

@@ -34,21 +34,48 @@ export function refreshArtifact(artifact, pr, diff) {
     };
 }
 /**
- * Comments a human put work into: their own, and AI ones they rewrote.
- * A re-review regenerates everything the AI said, but must not silently bin
- * these — see carryOverComments.
+ * Is this artifact's status the user's to keep, rather than the run's to set?
+ *
+ * A send or a settle is a decision about the PR; a run finishing is a fact
+ * about the code. Whichever way the run went — a draft or an error — it does
+ * not get to reopen one, which is the same rule `SETTLED_BY_YOU` applies to
+ * starting a run in the first place.
  */
-export function humanComments(artifact) {
-    return artifact.comments.filter((c) => c.origin === "user" || c.editedByUser);
+export function userOwnsStatus(a) {
+    return a.sent !== null || a.status === "reviewed" || a.status === "skipped";
 }
 /**
- * Carry a previous review's human comments into a fresh one, re-anchored to
- * the new diff. AI comments are dropped: the new run just regenerated them.
+ * Fold a finished review run onto whatever the artifact says now.
+ *
+ * A run takes minutes and the cockpit stays live throughout, so by the time one
+ * lands the artifact may have moved under it. Saving the result wholesale
+ * silently undid whatever had happened in between — the same mistake
+ * `mergeConcurrentEdits` exists to stop a chat turn making.
+ *
+ * `fresh` is what the run produced; `current` is what is on disk now. The run
+ * owns the draft — summary, chapters, verdict, comments — and that includes
+ * replacing comments the user wrote: a re-review starts fresh by design, and
+ * `docs/lifecycle.md` says so plainly rather than leaving anyone to count on
+ * work surviving one. What it does *not* own are the decisions:
+ *
+ *   - **a send** stands, and takes the status with it. Without this a run
+ *     finishing after a send wrote `sent: null` back over the record, and the
+ *     "already sent" guard would then wave a second submission through.
+ *   - **a settle** stands too: `reviewed` and `skipped` are decisions about the
+ *     PR, not facts about the code, so a run completing does not reopen one.
+ *     The fresh draft still lands underneath, which is what the row shows if
+ *     the user changes their mind.
+ *   - **the conversation** is the user's writing, snapshot and all.
  */
-export function carryOverComments(previous, fresh) {
-    const human = humanComments(previous);
-    if (human.length === 0)
-        return { comments: fresh.comments, carried: 0, drifted: 0 };
-    const { comments, drifted } = reanchorComments(human, previous.diff, fresh.diff);
-    return { comments: [...fresh.comments, ...comments], carried: comments.length, drifted };
+export function mergeRunResult(fresh, current) {
+    return {
+        ...fresh,
+        status: userOwnsStatus(current) ? current.status : fresh.status,
+        sent: current.sent,
+        calibration: current.calibration,
+        filed: current.filed,
+        chat: current.chat,
+        preChat: current.preChat,
+        pendingChat: current.pendingChat,
+    };
 }

package/dist/core/state.js

@@ -98,11 +98,21 @@ export async function updateArtifactByKey(key, mutate) {
  * this it stays wedged forever, with no way to retry it from the cockpit. A
  * `cerber review` running in another terminal is the one false positive; it
  * overwrites the artifact when it finishes anyway.
+ *
+ * `inUse` names the runs this process genuinely owns, and they are left alone.
+ * Callers should still reconcile before starting anything that polls — but
+ * ordering alone is a promise about wiring, and this is the guard that holds
+ * whatever order they are started in: without it, reconciliation racing a
+ * daemon's first tick could stamp "interrupted" over a review that had just
+ * legitimately begun.
  */
-export async function reconcileRunning() {
+export async function reconcileRunning(opts = {}) {
+    const inUse = opts.inUse ?? (() => false);
     const artifacts = await listArtifacts();
     let cleared = 0;
     for (const artifact of artifacts) {
+        if (inUse(artifact.id))
+            continue;
         const stuckRun = artifact.status === "running";
         const stuckChat = artifact.pendingChat && artifact.pendingChat.error == null ? artifact.pendingChat : null;
         if (!stuckRun && !stuckChat)

package/dist/runner/review.js

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { AiReviewSchema, SCHEMA_VERSION, artifactId, } from "../core/artifact.js";
+import { AiReviewSchema, SCHEMA_VERSION, artifactId, artifactKey, } from "../core/artifact.js";
 import { createRunDir, evictOldCheckouts, prepareCheckout, removeRunDir } from "../core/checkout.js";
 import { fetchPrDiff, fetchPrInfo, isOrgMember, isTeamMember } from "../core/gh.js";
-import { carryOverComments } from "../core/refresh.js";
-import { loadArtifact, saveArtifact } from "../core/state.js";
+import { mergeRunResult, userOwnsStatus } from "../core/refresh.js";
+import { loadArtifact, saveArtifact, updateArtifactByKey } from "../core/state.js";
 import { loadConfig } from "../core/config.js";
 import { decideTrust, membershipQueries, parseTrustRules } from "../core/trust.js";
 import { extractJson, runClaude, unauthenticatedEnv } from "./claude.js";
@@ -91,10 +91,15 @@ async function runReview(ref, opts) {
             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.`);
+        // The sha the AI *read*, not the one the artifact happens to mention.
+        // `pr.headSha` is moved forward by the refresh that runs whenever a review
+        // is opened, so comparing against it meant that merely looking at a draft
+        // after a push convinced this guard the draft was current, and the poll
+        // never re-reviewed it again. Older artifacts have no `reviewedSha` and
+        // fall back to the old comparison.
+        const reviewedSha = existing.run?.reviewedSha ?? existing.pr.headSha;
+        if (HEAD_SENSITIVE.has(existing.status) && reviewedSha !== "" && reviewedSha === pr.headSha) {
+            log(`Up to date (reviewed at ${reviewedSha.slice(0, 7)}, status ${existing.status}) — skipping. Use --force to re-review.`);
             return { artifact: existing, skipped: true };
         }
     }
@@ -120,6 +125,14 @@ async function runReview(ref, opts) {
                 `reviewing from the diff alone.`);
         }
     }
+    // A re-review regenerates the draft, comments and all — deliberately, and
+    // including any the user wrote. Carrying them across is a feature this tool
+    // has decided not to have, so nothing here tries to half-keep them: they go
+    // when the run starts, whichever way it ends. `docs/lifecycle.md` says so
+    // where a reader would otherwise assume otherwise.
+    if (existing && existing.comments.length > 0) {
+        log(`Replacing the previous draft's ${existing.comments.length} comment(s) — a re-review starts fresh.`);
+    }
     let artifact = {
         schemaVersion: SCHEMA_VERSION,
         id: artifactId(pr),
@@ -142,6 +155,7 @@ async function runReview(ref, opts) {
             trusted: trusted && source !== null,
             sessionId: null,
             trigger: opts.trigger ?? "user",
+            reviewedSha: null,
         },
         sent: null,
         refresh: null,
@@ -204,34 +218,37 @@ async function runReview(ref, opts) {
                 // whose working directory was empty has nothing a chat turn could read.
                 sessionId: source ? review.sessionId : null,
                 trigger: artifact.run.trigger,
+                // What this run actually read — the thing the freshness guard needs
+                // and `pr.headSha` cannot say, because a refresh moves that forward
+                // without anybody re-reading the code.
+                reviewedSha: pr.headSha,
             },
         };
-        // A re-review regenerates the AI's comments, but the human's own comments
-        // and their rewrites of AI ones are work the run must not throw away.
-        if (existing) {
-            const { comments, carried, drifted } = carryOverComments(existing, artifact);
-            if (carried > 0) {
-                artifact = { ...artifact, comments };
-                log(`Carried over ${carried} comment(s) you wrote or edited` +
-                    (drifted > 0 ? `; ${drifted} no longer match the diff and will post in the body.` : "."));
-            }
-        }
     }
     catch (err) {
-        artifact = {
-            ...artifact,
-            status: "failed",
-            updatedAt: now(),
-            run: {
-                ...artifact.run,
-                finishedAt: now(),
-                error: err instanceof Error ? err.message : String(err),
-            },
+        const run = {
+            ...artifact.run,
+            finishedAt: now(),
+            error: err instanceof Error ? err.message : String(err),
         };
-        await saveArtifact(artifact);
+        // Onto what is on disk, not over it: the artifact this run built holds none
+        // of the comments or marks that may have landed while it ran, and a failure
+        // is no reason to lose them — nor to reopen a decision the user made.
+        const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => ({
+            ...a,
+            status: userOwnsStatus(a) ? a.status : "failed",
+            run,
+        }));
+        artifact = saved ?? { ...artifact, status: "failed", run, updatedAt: now() };
+        if (!saved)
+            await saveArtifact(artifact);
         throw err;
     }
-    await saveArtifact(artifact);
+    const merged = await updateArtifactByKey(artifactKey(artifact.id), (current) => mergeRunResult(artifact, current));
+    if (merged)
+        artifact = merged;
+    else
+        await saveArtifact(artifact);
     return { artifact, skipped: false };
 }
 /** Run tasks with bounded concurrency, preserving order of results. */

package/dist/server/index.js

@@ -15,7 +15,7 @@ import { DaemonConfigSchema, configPath, loadConfig, saveConfig } from "../core/
 import { refreshArtifact } from "../core/refresh.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
-import { listArtifacts, loadArtifact, loadArtifactByKey, reconcileRunning, saveArtifact, updateArtifactByKey, } from "../core/state.js";
+import { listArtifacts, loadArtifact, loadArtifactByKey, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { isReviewRunning } from "../runner/inflight.js";
 import { reviewPr } from "../runner/review.js";
 import { runChatTurn } from "../runner/chat.js";
@@ -23,6 +23,20 @@ import { mergeConcurrentEdits, restoreReview } from "../core/revise.js";
 import { progressWriter } from "./progress.js";
 import { ChatTurnSchema } from "../core/artifact.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * The statuses `PATCH /api/reviews/:key` will set: the two that are the user's
+ * own decision about a PR. Everything else is a fact some other path owns.
+ */
+const SETTLEABLE = ["reviewed", "skipped"];
+/**
+ * Is an AI run rewriting this draft right now?
+ *
+ * Two questions, because neither alone is enough: `isReviewRunning` is an
+ * in-memory claim and cannot see a `cerber review` going in another terminal,
+ * while the persisted status cannot see a run this process started moments ago
+ * that has not written yet.
+ */
+const inFlight = (a) => a.status === "running" || isReviewRunning(a.id);
 export async function buildApp(opts) {
     const app = new Hono();
     if (opts.token) {
@@ -251,6 +265,7 @@ export async function buildApp(opts) {
                 trusted: false,
                 sessionId: null,
                 trigger: "user",
+                reviewedSha: null,
             },
             sent: null,
             refresh: null,
@@ -284,6 +299,14 @@ export async function buildApp(opts) {
     // ---- Mutations (all local — artifact edits only) ----
     app.patch("/api/reviews/:key", async (c) => {
         const body = await c.req.json();
+        // Only the two statuses that are the user's own decision. The schema
+        // permits all seven, and taking them all meant this endpoint would happily
+        // write `status: "sent"` with no `sent` record and nothing submitted —
+        // a row that claims a review reached GitHub, which no honest path produces.
+        // `running`/`ready`/`failed` belong to the runner, `sent` to the send path.
+        if (body.status !== undefined && !SETTLEABLE.includes(body.status)) {
+            return c.json({ error: `status must be one of ${SETTLEABLE.join(", ")} — got ${body.status}` }, 400);
+        }
         const updated = await updateArtifactByKey(c.req.param("key"), (a) => {
             const next = { ...a };
             if (body.status !== undefined) {
@@ -429,6 +452,7 @@ export async function buildApp(opts) {
                 trusted: false,
                 sessionId: null,
                 trigger: "user",
+                reviewedSha: null,
             },
         }));
         // Minutes-long: run it detached and let the cockpit poll the artifact.
@@ -589,6 +613,13 @@ export async function buildApp(opts) {
         if (artifact.sent) {
             return c.json({ error: `already sent at ${artifact.sent.at}` }, 409);
         }
+        // Not while a run is rewriting this draft. Vouching for a review that is
+        // being replaced under you is reason enough on its own; on top of that the
+        // run used to save `sent: null` back over the record when it landed, so the
+        // guard above would wave a *second* submission through afterwards.
+        if (inFlight(artifact)) {
+            return c.json({ error: "a review of this PR is running — wait for it to finish" }, 409);
+        }
         const payload = buildReviewPayload(artifact, event);
         try {
             const { url } = await submitReview({ owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number }, { event: payload.event, body: payload.body, comments: payload.comments, commitId: payload.commitId });
@@ -628,11 +659,13 @@ export async function buildApp(opts) {
     }
     return app;
 }
+/**
+ * Serve the cockpit. `reconcileRunning` is deliberately *not* called here: the
+ * caller must have done it before starting the daemon, because the daemon polls
+ * as soon as it is constructed. Doing it here as well would have marked that
+ * poll's own fresh run as an interrupted leftover.
+ */
 export async function startServer(opts) {
-    const cleared = await reconcileRunning();
-    if (cleared > 0) {
-        console.log(`Cleared ${cleared} AI run(s) left in flight by a previous process — start them again from the cockpit.`);
-    }
     const app = await buildApp(opts);
     serve({ fetch: app.fetch, port: opts.port, hostname: opts.host }, (info) => {
         const tokenHint = opts.token ? `/?token=${opts.token}` : "";

package/package.json

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