@fullstackhouse/cerber 0.24.1 → 0.26.0

package/README.md

@@ -355,12 +355,36 @@ the summary, comments and verdict alone, and is still one deliberate click. A
 review that has already been sent can't be argued with: that artifact is the
 record of what GitHub has.
 
+### Every row remembers what happened to it
+
+A review keeps one "last updated" time, which means every write erases the
+answer to *when did I skip this, and did they ask again afterwards?* So each
+one also keeps a history: the status changes with their timestamps, every push
+it saw, each run and what it cost, sends, refreshes — and which part of cerber
+did it, whether that was you in the cockpit, the CLI, an AI run or the poll.
+
+The poll's silences are in there too. When it looks at a row and deliberately
+leaves it alone — you settled it, so a new push does not reopen it; or GitHub
+still lists you as a requested reviewer even though its own search has stopped
+saying so — it writes that down instead of passing without a trace. That is
+usually the answer when a PR is not where you expected it to be.
+
+It's at the foot of every review in the cockpit, and:
+
+```bash
+cerber history owner/repo#123
+```
+
+Nothing about GitHub's own timeline is copied here — GitHub keeps that, and
+`gh` can be asked for it again. This is cerber's side of the story.
+
 ## Status
 
 Early, but whole: everything described above has shipped — reviewing,
 editing and the gated Send, inbox discovery with parallel runs, confidence
 calibration (`cerber stats`), shadow-mode and opt-in auto-send, re-anchoring
-onto new commits, source-backed and trusted runs, and the reviewer chat.
+onto new commits, source-backed and trusted runs, the reviewer chat, and a
+per-review history of everything that touched it (`cerber history`).
 `cerber export` writes a review out as markdown if you want it elsewhere.
 
 ## Running on a VPS

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { artifactId, artifactKey } from "../core/artifact.js";
 import { listCheckouts, removeCheckout } from "../core/checkout.js";
 import { toMarkdown } from "../core/export.js";
 import { configPath, loadConfig, saveConfig } from "../core/config.js";
+import { withWriter } from "../core/history.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";
@@ -103,6 +104,40 @@ program
         console.log(`${a.status.padEnd(8)} ${a.id.padEnd(40)} ${v.padEnd(20)} ${a.pr.title}`);
     }
 });
+program
+    .command("history")
+    .description("Everything that has happened to a review: what changed, when, which part of cerber did it — and the decisions the poll took to leave it alone")
+    .argument("<pr>", "PR URL, owner/repo#number, or number (with --repo)")
+    .option("-R, --repo <owner/repo>", "repository for bare PR numbers")
+    .action(async (input, opts) => {
+    const ref = parsePrRef(input, opts.repo);
+    const artifact = await loadArtifact(artifactId(ref));
+    if (!artifact) {
+        console.error(`No review found for ${artifactId(ref)}. Run: cerber review ${input}`);
+        process.exit(1);
+    }
+    console.log(`${artifact.id} — ${artifact.pr.title}\n`);
+    const history = artifact.history ?? [];
+    if (history.length === 0) {
+        console.log("Nothing recorded. This review predates cerber keeping a history — it starts at the next thing that happens to it.");
+        return;
+    }
+    const stamp = (at) => {
+        const d = new Date(at);
+        return Number.isNaN(d.getTime())
+            ? at
+            : `${d.toLocaleDateString(undefined, { month: "short", day: "2-digit" })} ${d.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" })}`;
+    };
+    // The stamp's width is the locale's business, not ours — measure it.
+    const stampWidth = Math.max(...history.map((e) => stamp(e.at).length)) + 2;
+    for (const entry of history) {
+        // The cause names the path that made the change — which endpoint, which
+        // command — and is the whole point on a row two paths could have written.
+        console.log(`${stamp(entry.at).padEnd(stampWidth)}${entry.by.padEnd(9)}${entry.what}` +
+            `${entry.cause ? `  ·  ${entry.cause}` : ""}`);
+    }
+    console.log(`\n(times are local · ${history.length} entr${history.length === 1 ? "y" : "ies"})`);
+});
 program
     .command("export")
     .description("Print a review as markdown (never touches GitHub)")
@@ -399,7 +434,10 @@ program
 function collect(value, previous) {
     return [...previous, value];
 }
-program.parseAsync().catch((err) => {
+// Every artifact write under this command is stamped with the command that
+// made it. Nested contexts win, so `serve` labels its requests, its poll and
+// its runs for themselves rather than all of them "cli".
+withWriter({ by: "cli", cause: process.argv[2] ?? null }, () => program.parseAsync()).catch((err) => {
     console.error(err instanceof Error ? err.message : err);
     process.exit(1);
 });

package/dist/core/artifact.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { HistoryEntrySchema } from "./history.js";
 export const SCHEMA_VERSION = 1;
 /**
  * How hard a finding presses on the merge. The words carry their own
@@ -278,6 +279,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),
@@ -287,6 +300,16 @@ export const ArtifactSchema = z.object({
     pendingChat: PendingChatSchema.nullable().default(null),
     /** The review as it stood before the first chat turn — "reset" restores this. */
     preChat: ReviewSnapshotSchema.nullable().default(null),
+    /**
+     * Everything that has happened to this review, oldest first.
+     *
+     * Optional, and with no default: nothing outside `saveArtifact` writes this,
+     * so absent means absent — an artifact from before it was kept, which the
+     * cockpit and the CLI say so about rather than showing as an empty history.
+     * Hand one in and it is ignored; the log on disk is the only current copy.
+     * See `history.ts` for what is recorded and what is deliberately left out.
+     */
+    history: z.array(HistoryEntrySchema).optional(),
 });
 /** What the AI must return. Subset of the artifact; cerber owns the rest. */
 export const AiReviewSchema = z.object({

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/history.js

@@ -0,0 +1,226 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { z } from "zod";
+/**
+ * What happened to a review, and when — cerber's side of the story.
+ *
+ * An artifact keeps one `updatedAt`, so every write erases the answer to "when
+ * did this become skipped?". This is the record that survives: one line per
+ * thing that changed, appended by `saveArtifact` itself rather than by its
+ * callers, so no write path can forget to keep it.
+ *
+ * It deliberately records only what cerber did and saw. GitHub keeps its own
+ * timeline of pushes, requests and reviews, and `gh` can always be asked for it
+ * again — mirroring it here would be a database wearing a different hat. The
+ * one thing worth writing down is what the poll *saw* at a given minute, since
+ * a search index cannot be asked what it said an hour ago.
+ *
+ * The chat is the other deliberate omission: a conversation already carries its
+ * own turns, timestamps and revisions.
+ */
+export const HistoryActorSchema = z.enum(["daemon", "cockpit", "cli", "runner", "unknown"]);
+export const HistoryEntrySchema = z.object({
+    at: z.string(),
+    /** Which part of cerber wrote it. "unknown" when nothing claimed the write. */
+    by: HistoryActorSchema.default("unknown"),
+    /** What happened, in plain words: "status ready → skipped". */
+    what: z.string(),
+    /** What was being done at the time: "PATCH /api/reviews/…", "poll", "review". */
+    cause: z.string().nullable().default(null),
+});
+/**
+ * How many entries one review keeps.
+ *
+ * Entries are ~100 bytes next to a diff that is routinely a hundred times
+ * that, and a watchlist plus note de-duplication keeps a busy PR to a few
+ * dozen — so this is a backstop against a pathological row, not a budget.
+ */
+export const MAX_ENTRIES = 500;
+/**
+ * Who is writing right now.
+ *
+ * Ambient rather than a parameter on every write: there are twenty-odd call
+ * sites and the useful answer is the same for all the writes one request, poll
+ * or run makes. Set it once at each entry point — the HTTP middleware, the
+ * poll, the CLI, an AI run — and every artifact write underneath is labelled,
+ * including ones added later that never think about history at all. Nesting
+ * works the obvious way: a run started by a request labels its own writes.
+ */
+const writer = new AsyncLocalStorage();
+export function withWriter(w, fn) {
+    return writer.run({ by: w.by, cause: w.cause ?? null }, fn);
+}
+export function currentWriter() {
+    return writer.getStore() ?? { by: "unknown", cause: null };
+}
+const short = (sha) => (sha.length > 7 ? sha.slice(0, 7) : sha);
+const FILED_PHRASE = {
+    "own-review": "you had already reviewed it on GitHub",
+    "own-reply": "you answered on the PR and nobody has answered back",
+    "request-withdrawn": "nobody is asking for this review any more",
+};
+/** The shape of a run, said once at the top of it: what it could read, who asked. */
+function runShape(run) {
+    const parts = [run.model ?? "default model", run.withSource ? "reading the source" : "diff only"];
+    if (run.trusted)
+        parts.push("trusted — may run commands");
+    if (run.trigger)
+        parts.push(run.trigger === "daemon" ? "asked for by the poll" : "asked for by you");
+    return parts.join(", ");
+}
+/** Comment churn as one line: what a re-review, a chat turn or your own edits did. */
+function describeComments(before, after) {
+    const was = new Map(before.map((c) => [c.id, c]));
+    const is = new Map(after.map((c) => [c.id, c]));
+    let fromReview = 0;
+    let yours = 0;
+    let edited = 0;
+    let regraded = 0;
+    let dropped = 0;
+    let restored = 0;
+    for (const c of after) {
+        const old = was.get(c.id);
+        if (!old) {
+            if (c.origin === "user")
+                yours++;
+            else
+                fromReview++;
+            continue;
+        }
+        if (old.body !== c.body)
+            edited++;
+        if (old.severity !== c.severity)
+            regraded++;
+        if (old.status !== "dropped" && c.status === "dropped")
+            dropped++;
+        if (old.status === "dropped" && c.status !== "dropped")
+            restored++;
+    }
+    const gone = before.filter((c) => !is.has(c.id)).length;
+    const parts = [];
+    if (fromReview)
+        parts.push(`+${fromReview} from the review`);
+    if (yours)
+        parts.push(`+${yours} you wrote`);
+    if (edited)
+        parts.push(`${edited} edited`);
+    if (regraded)
+        parts.push(`${regraded} re-graded`);
+    if (dropped)
+        parts.push(`${dropped} dropped`);
+    if (restored)
+        parts.push(`${restored} restored`);
+    if (gone)
+        parts.push(`${gone} gone`);
+    return parts.length > 0 ? `comments: ${parts.join(", ")}` : null;
+}
+/**
+ * What changed between two versions of a review, in plain words.
+ *
+ * A watchlist, not a deep diff. A generic comparison would bury the timeline
+ * under a running turn's narration, which is rewritten to the artifact every
+ * couple of seconds and says nothing about where the review got to.
+ */
+export function describeChange(before, after) {
+    const lines = [];
+    if (!before) {
+        lines.push(after.status === "awaiting"
+            ? "appeared in the inbox — GitHub is asking you for a review"
+            : `first written here (${after.status})`);
+    }
+    else {
+        if (before.status !== after.status)
+            lines.push(`status ${before.status} → ${after.status}`);
+        if (before.pr.headSha !== after.pr.headSha && after.pr.headSha) {
+            lines.push(before.pr.headSha
+                ? `head moved ${short(before.pr.headSha)} → ${short(after.pr.headSha)}`
+                : `head is ${short(after.pr.headSha)}`);
+        }
+        if (before.pr.state !== after.pr.state) {
+            lines.push(after.pr.state === "OPEN" ? "PR reopened" : `PR ${after.pr.state.toLowerCase()}`);
+        }
+        if (before.pr.isDraft !== after.pr.isDraft) {
+            lines.push(after.pr.isDraft ? "turned back into a draft" : "marked ready for review");
+        }
+    }
+    const wasRun = before?.run ?? null;
+    const run = after.run;
+    if (run && run.startedAt !== wasRun?.startedAt)
+        lines.push(`review started (${runShape(run)})`);
+    if (run?.finishedAt && run.finishedAt !== wasRun?.finishedAt && !run.error) {
+        lines.push(`review finished${run.reviewedSha ? ` at ${short(run.reviewedSha)}` : ""}` +
+            `${run.costUsd != null ? ` (≈$${run.costUsd.toFixed(2)} at API rates)` : ""}`);
+    }
+    if (run?.error && run.error !== wasRun?.error)
+        lines.push(`review failed: ${run.error}`);
+    const wasVerdict = before?.verdict ?? null;
+    const verdict = after.verdict;
+    if (verdict &&
+        (!wasVerdict ||
+            wasVerdict.recommendation !== verdict.recommendation ||
+            wasVerdict.confidence !== verdict.confidence)) {
+        lines.push(`verdict ${wasVerdict ? "changed to" : "set to"} ${verdict.recommendation.replace("_", " ")}` +
+            ` (${verdict.confidence}% sure of the findings)`);
+    }
+    const comments = describeComments(before?.comments ?? [], after.comments);
+    if (comments)
+        lines.push(comments);
+    if (after.sent && after.sent.at !== before?.sent?.at) {
+        lines.push(`sent to GitHub as ${after.sent.event.toLowerCase().replace("_", " ")}` +
+            `${after.sent.auto ? ", by auto-send" : ""}`);
+    }
+    if (after.filed && after.filed.at !== before?.filed?.at) {
+        lines.push(`filed under settled — ${FILED_PHRASE[after.filed.reason] ?? after.filed.reason}`);
+    }
+    if (after.refresh && after.refresh.at !== before?.refresh?.at) {
+        const r = after.refresh;
+        lines.push(`pulled forward onto ${short(r.toSha)} — ${r.moved} comment(s) followed the code` +
+            `${r.drifted > 0 ? `, ${r.drifted} drifted` : ""}`);
+    }
+    return lines;
+}
+/**
+ * Would this note be dropped as a repeat of the last thing said?
+ *
+ * The rule belongs to `appendHistory`, which drops such a note; this is the
+ * same question asked ahead of time, so a caller can skip a write that would
+ * change nothing. Exported rather than inferred from the result: at the cap an
+ * appended entry trims an older one, so the log's *length* is not evidence of
+ * anything having been added, and a caller comparing lengths would silently
+ * stop recording notes the moment a review reached `MAX_ENTRIES`.
+ */
+export function noteIsRepeat(prior, note) {
+    return (prior?.history ?? []).at(-1)?.what === note;
+}
+/**
+ * The history to write, given what is on disk and what is about to replace it.
+ *
+ * Whatever history the caller is holding is ignored: several write paths
+ * legitimately hand over an artifact built minutes ago, and their copy of the
+ * log is stale by definition. Disk is the only source.
+ */
+export function appendHistory(prior, next, opts = {}) {
+    const kept = prior?.history ?? [];
+    const { by, cause } = currentWriter();
+    const at = new Date().toISOString();
+    const what = opts.unreadable
+        ? ["history restarts here — the previous file could not be read"]
+        : opts.note
+            ? // A note explains a decision the poll re-takes every few minutes. Said
+                // once: repeating it until something else happens is noise, and the
+                // entry it would duplicate already says the same thing.
+                noteIsRepeat(prior, opts.note)
+                    ? []
+                    : [opts.note]
+            : describeChange(prior, next);
+    const all = [...kept, ...what.map((w) => ({ at, by, cause, what: w }))];
+    if (all.length <= MAX_ENTRIES)
+        return all;
+    const [oldest, ...rest] = all.slice(-(MAX_ENTRIES - 1));
+    if (!oldest)
+        return all;
+    return [
+        { at: oldest.at, by: "unknown", cause: null, what: "… earlier entries dropped" },
+        oldest,
+        ...rest,
+    ];
+}

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/core/state.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { ArtifactSchema, artifactKey } from "./artifact.js";
+import { appendHistory, noteIsRepeat } from "./history.js";
 export function cerberHome() {
     return process.env.CERBER_HOME ?? path.join(os.homedir(), ".cerber");
 }
@@ -11,14 +12,91 @@ function reviewsDir() {
 function artifactPath(id) {
     return path.join(reviewsDir(), `${artifactKey(id)}.json`);
 }
-export async function saveArtifact(artifact) {
+/**
+ * Read whatever is on disk, tolerating anything.
+ *
+ * These files are the user's to edit, so a broken one has to be survivable:
+ * before, a save simply overwrote it. It still does — but the timeline says so
+ * rather than quietly claiming the review began at that moment.
+ */
+async function readPrior(file) {
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { artifact: null, unreadable: false };
+        return { artifact: null, unreadable: true };
+    }
+    try {
+        return { artifact: ArtifactSchema.parse(JSON.parse(raw)), unreadable: false };
+    }
+    catch {
+        return { artifact: null, unreadable: true };
+    }
+}
+/**
+ * Write an artifact, and record what changed about it.
+ *
+ * The history is appended here rather than by the caller on purpose. Around
+ * twenty places write artifacts and several of them overwrite one wholesale
+ * from a copy built minutes earlier — a log any of them had to remember to
+ * carry would be lost by the first one that didn't. Appending at the one place
+ * every write goes through makes the record a property of writing.
+ *
+ * The read here is not skippable, even for a caller that has just done one of
+ * its own. Two writers share these files — the poll's timer and the cockpit's
+ * button — so a caller's copy can be out of date by the time it writes, and
+ * appending to *that* would drop whatever the other one recorded in between.
+ * The rest of the artifact is lost in that race either way; the history need
+ * not be, and the extra read is one file next to a write of the same file.
+ *
+ * `note` records a decision that changed nothing, which is the only kind of
+ * history a diff cannot see. It does not touch `updatedAt` — that belongs to
+ * `updateArtifactByKey`.
+ */
+export async function saveArtifact(artifact, opts = {}) {
     await fs.mkdir(reviewsDir(), { recursive: true });
     const file = artifactPath(artifact.id);
+    const prior = await readPrior(file);
+    const next = {
+        ...artifact,
+        history: appendHistory(prior.artifact, artifact, {
+            note: opts.note,
+            unreadable: prior.unreadable,
+        }),
+    };
     const tmp = `${file}.tmp`;
-    await fs.writeFile(tmp, JSON.stringify(artifact, null, 2));
+    await fs.writeFile(tmp, JSON.stringify(next, null, 2));
     await fs.rename(tmp, file);
     return file;
 }
+/**
+ * Write down a decision that changed nothing.
+ *
+ * The poll's silences are the hardest thing to debug about it — it looks at a
+ * settled row, decides deliberately to leave it alone, and leaves no trace of
+ * having looked. This is that trace. It is not a change to the review, so
+ * `updatedAt` stays put: a note must not reorder the queue.
+ *
+ * Missing artifacts are ignored, and a note identical to the last entry is
+ * dropped, so a decision re-taken every poll is recorded once.
+ */
+export async function noteHistory(id, what) {
+    const prior = await loadArtifact(id).catch(() => null);
+    if (!prior)
+        return;
+    // Nothing to add means nothing to write: the poll re-takes these decisions
+    // every few minutes, and rewriting a whole artifact, diff and all, to change
+    // nothing is the expensive half of saying it again. The rule for "nothing to
+    // add" is `appendHistory`'s, so ask it rather than knowing it twice — and ask
+    // it directly, because at the cap an appended note trims an older entry and
+    // leaves the length exactly as it was.
+    if (noteIsRepeat(prior, what))
+        return;
+    await saveArtifact(prior, { note: what });
+}
 export async function loadArtifact(id) {
     try {
         const raw = await fs.readFile(artifactPath(id), "utf8");

package/dist/runner/review.js

@@ -3,7 +3,8 @@ import { AiReviewSchema, SCHEMA_VERSION, artifactId, artifactKey, } from "../cor
 import { createRunDir, evictOldCheckouts, prepareCheckout, removeRunDir } from "../core/checkout.js";
 import { fetchPrDiff, fetchPrInfo, isOrgMember, isTeamMember } from "../core/gh.js";
 import { mergeRunResult, userOwnsStatus } from "../core/refresh.js";
-import { loadArtifact, saveArtifact, updateArtifactByKey } from "../core/state.js";
+import { loadArtifact, noteHistory, saveArtifact, updateArtifactByKey } from "../core/state.js";
+import { withWriter } from "../core/history.js";
 import { loadConfig } from "../core/config.js";
 import { decideTrust, membershipQueries, parseTrustRules } from "../core/trust.js";
 import { extractJson, runClaude, unauthenticatedEnv } from "./claude.js";
@@ -32,7 +33,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.
@@ -80,15 +81,28 @@ async function resolveTrust(pr, opts, log) {
         log(`Trusted (${decision.reason}): the review may run commands in the checkout.`);
     return decision.trusted;
 }
+/**
+ * Decide whether to run, then run.
+ *
+ * The two halves are deliberately not in the same writer context. Everything
+ * down to the guards belongs to whoever asked — the poll's timer, you at a
+ * terminal, the cockpit's button — and that is the whole value of the notes
+ * they write: a review that did not happen has no runner to blame, and "who
+ * wanted one" is the fact worth keeping. Only the run itself is the runner's.
+ */
 async function runReview(ref, opts) {
     const log = opts.onProgress ?? (() => { });
-    const now = () => new Date().toISOString();
     log(`Fetching ${ref.owner}/${ref.repo}#${ref.number}…`);
     const pr = await fetchPrInfo(ref);
     const existing = await loadArtifact(artifactId(pr));
     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.`);
+            // Written down because it is the poll's most confusing silence: a row
+            // the author keeps pushing to, that never comes back into the inbox.
+            // Only a push, now — somebody asking again does reopen it, and says so
+            // for itself (`reopenIfAskedAgain`).
+            await noteHistory(existing.id, `left alone: you marked it ${existing.status}, so a new push does not reopen it`);
             return { artifact: existing, skipped: true };
         }
         // The sha the AI *read*, not the one the artifact happens to mention.
@@ -100,9 +114,18 @@ async function runReview(ref, opts) {
         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.`);
+            // Carries the sha, so it says itself again the next time the head moves
+            // and this guard stops being the reason nothing happened.
+            await noteHistory(existing.id, `already reviewed at ${reviewedSha.slice(0, 7)} — not re-reviewed`);
             return { artifact: existing, skipped: true };
         }
     }
+    // The run owns its writes from here, whoever asked for it: a re-review
+    // started from a cockpit click is still the runner rewriting the draft.
+    return await withWriter({ by: "runner", cause: "review" }, () => performReview(ref, pr, existing, opts, log));
+}
+async function performReview(ref, pr, existing, opts, log) {
+    const now = () => new Date().toISOString();
     const diff = await fetchPrDiff(ref);
     const trusted = await resolveTrust(pr, opts, log);
     // A checkout is an optimisation, never a precondition: if git or gh can't
@@ -160,6 +183,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