@fullstackhouse/cerber 0.33.0 → 0.34.0

package/README.md

@@ -10,10 +10,12 @@ comments, and a verdict with a confidence score. You read it in a local web
 cockpit, keep or rewrite or drop each comment, then press Send when you agree
 with it.
 
-**Nothing reaches GitHub until you explicitly say so.** Cerber's only GitHub
-write is the Send button (plus opt-in daemon auto-send you turn on yourself) —
-reviewing is 100% local and read-only. Reviews go out under your own account,
-as your review, because you decided each line of it should.
+**Nothing reaches GitHub until you explicitly say so.** Reviewing is 100% local
+and read-only; three things can write, each one a click you make — the Send
+button, opt-in daemon auto-send you turn on yourself, and handing a review to
+somebody else. A review only ever goes out under your own account because you
+decided it should: Send posts the one you vouched for, and a handoff posts the
+draft only if you ticked the box to send it along, always as a comment.
 
 That gate is the whole point, and the reason this is not another review bot:
 
@@ -86,6 +88,7 @@ and apply on the next poll.
 
 - [What a review looks like](#what-a-review-looks-like) — what Claude writes and how you walk it
 - [The inbox](#the-inbox) — what the queue shows, what settles a row, the notifications
+- [Handing a review to somebody else](#handing-a-review-to-somebody-else)
 - [It reviews the code, not just the diff](#it-reviews-the-code-not-just-the-diff)
 - [Trusted PRs: reviews that can run things](#trusted-prs-reviews-that-can-run-things)
 - [When the PR moves under you](#when-the-pr-moves-under-you)
@@ -152,7 +155,9 @@ all, since the repo is read-only and a review could never be sent.
 
 Settling a review is your decision, not GitHub's: skip a PR, or mark one
 reviewed without sending, and GitHub still holds its review request open,
-because nothing cerber does here reaches it. Those rows stay marked where they
+because nothing in that decision reaches it. (The one decision that does reach
+it is [handing the review to somebody else](#handing-a-review-to-somebody-else),
+which moves the request rather than leaving it behind.) Those rows stay marked where they
 sit, counted on the tab they went into, and named in place of the empty
 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
@@ -227,6 +232,55 @@ 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?".
 
+## Handing a review to somebody else
+
+Some reviews are not yours. Wrong part of the stack, wrong week, somebody else
+wrote half of it — and the honest answer is a name, not a skip. **Hand off** is
+in the send panel next to *mark reviewed* and *skip*. It opens with the people
+who can take it already listed — whoever this repo assigns work to, with anyone
+you have handed to before at the top — so in the ordinary case you pick a name
+rather than typing one. Then:
+
+- they are added as a requested reviewer and you are taken off,
+- a short note goes on the PR saying so — prefilled with their name so they get
+  the notification, editable, and clearable if you would rather say nothing,
+- the drafted review goes up with it, if you tick the box for it (below),
+- the row is filed under settled here, tagged `handed to @them` — or under
+  sent, if you sent the review with it.
+
+That is the whole of it, and it is the one thing on the queue that genuinely
+*finishes* a review request instead of just filing it: a skip leaves GitHub
+asking you forever, and this does not. If they run cerber too, their next poll
+picks the PR up and drafts a review for them — nothing has to be sent anywhere
+for that to work.
+
+**You can send the draft with it.** Tick *also post the review* and what Claude
+found goes up at the same time — the same body and the same inline comments the
+Send button would post, so the next reviewer and the author start from something
+rather than nothing.
+
+It posts as a **comment**, never an approval or a change request. You are handing
+the judgement over, so making it on the way out would be odd. The findings keep
+their grades, so a blocker still reads as a blocker — what that means for the
+merge is now the next reviewer's call.
+
+That box starts unticked, and it is the one thing here that isn't on by default.
+You can hand off a PR you never opened, where the draft is whatever the overnight
+poll wrote, and publishing that under your name is the thing the Send button
+exists to prevent. Ticking it shows you the body first. Leave it alone and the
+draft just stays here, openable and still sendable.
+
+If GitHub refuses the swap — they are not a collaborator, or you cannot request
+reviews on that repo — nothing happens at all: no note on the PR, no change
+here. And if it moves them on but cannot take you off, the row says that too,
+rather than claiming you are done with it.
+
+The list is a convenience, not a gate: it is GitHub's assignable-users list, not
+its rule for who may review, so you can always type a login it doesn't mention —
+and on a repo cerber can't read that list for, the box says so and still works.
+
+Handing to a team isn't supported — a room being asked is not somebody taking it.
+
 ## It reviews the code, not just the diff
 
 Cerber checks the PR's head out locally and lets the review read it. That

package/dist/core/artifact.js

@@ -149,6 +149,36 @@ export const FiledInfoSchema = z.object({
         .nullable()
         .default(null),
 });
+/**
+ * You gave this review to somebody else.
+ *
+ * The opposite of `filed` in every way that matters: that one is a record of
+ * cerber noticing GitHub had moved past a draft, this one is a decision of
+ * yours that *moved* GitHub — the review request is theirs now and no longer
+ * yours. It is why the row is settled, so it outranks the status wherever the
+ * queue tags one.
+ *
+ * `note` is the comment that went on the PR announcing it, and null when none
+ * did — either you cleared the text, or posting it failed after the request had
+ * already moved, which is one of the half-done states a handoff can end in.
+ *
+ * The draft may go with it, if you ticked the box for that, in which case the
+ * row carries a `sent` record too. It posts as a COMMENT and never anything
+ * else: handing a PR over hands the judgement over with it, so a handoff forms
+ * no verdict of its own.
+ */
+export const HandoffInfoSchema = z.object({
+    at: z.string(),
+    /** The login GitHub now asks for. */
+    to: z.string(),
+    /** Whether cerber also took your own review request off the PR. */
+    withdrewYours: z.boolean().default(true),
+    /** The note posted on the PR, if one was. */
+    note: z
+        .object({ body: 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({
     at: z.string(),
@@ -292,6 +322,8 @@ 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),
+    /** Set when you gave this review to somebody else. Mutually exclusive with `filed`. */
+    handoff: HandoffInfoSchema.nullable().default(null),
     /**
      * When this review was settled — marked `reviewed` or `skipped`, by you or by
      * cerber filing it. Null on anything not settled.

package/dist/core/gh.js

@@ -448,9 +448,107 @@ export async function searchAwaitingMe(repoFilter, limit = 50) {
     return mapSearchResults(JSON.parse(out));
 }
 /**
- * THE ONLY GITHUB WRITE IN CERBER.
- * Submits a review in one shot. Must only ever be called from an explicit
- * user action (cockpit Send button / `cerber send` after confirmation).
+ * Who this repo will let you put on a PR — the list behind the handoff's
+ * suggestions.
+ *
+ * The `assignees` endpoint rather than `collaborators`: they answer nearly the
+ * same question, but collaborators needs push access, which is exactly what a
+ * reviewer on somebody else's repo does not have. This one needs only read, so
+ * the suggestions work wherever cerber can see the PR at all.
+ *
+ * Bots are dropped. A bot cannot take a review off you, and a list that offers
+ * one is a list you have to read past every time.
+ *
+ * Not authoritative, and nothing treats it as such: GitHub's own rule for who
+ * may be *requested* is its own, so the name box stays free text and a login
+ * this never mentions can still be handed to. These are suggestions.
+ */
+export async function fetchAssignableUsers(ref) {
+    const out = await gh([
+        "api",
+        // The page size goes in the path, not in a `-f`/`-F` field: `gh api`
+        // switches the method to POST the moment any field is present, and
+        // `POST …/assignees` is a 404. A query string keeps this the GET it is,
+        // and `--paginate` carries it onto every following page.
+        `repos/${ref.owner}/${ref.repo}/assignees?per_page=100`,
+        "--paginate",
+        "--jq",
+        '.[] | select(.type != "Bot") | .login',
+    ]);
+    return out
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+/**
+ * Move the review request to somebody else: ask GitHub for their review, then
+ * take yours off.
+ *
+ * Order matters and is the whole of the error handling. Asking first means a
+ * refusal — not a collaborator, no permission to request reviews — leaves the
+ * PR exactly as it was, with you still on the hook and nothing to undo. The
+ * reverse order could drop the request on the floor: you off it, them never on
+ * it, and nobody looking at the PR at all.
+ *
+ * Withdrawing yours is then allowed to fail on its own, and says so rather than
+ * throwing. Two requested reviewers is a state GitHub already understands and
+ * the person you asked is asked either way, so unpicking a request that worked
+ * would be undoing the half that succeeded to tidy up the half that didn't.
+ */
+export async function handOffReview(ref, to, 
+/**
+ * Your login, to take off the PR — or null when it is already off, which is
+ * the case on a second handoff. Asking GitHub to withdraw a request that does
+ * not exist would fail, and this would then report you still listed when the
+ * truth is that you were taken off the first time.
+ */
+from) {
+    const endpoint = `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}/requested_reviewers`;
+    await gh(["api", endpoint, "--method", "POST", "-f", `reviewers[]=${to}`]);
+    if (from === null)
+        return { withdrewYours: true, withdrawError: null };
+    try {
+        await gh(["api", endpoint, "--method", "DELETE", "-f", `reviewers[]=${from}`]);
+        return { withdrewYours: true, withdrawError: null };
+    }
+    catch (err) {
+        return { withdrewYours: false, withdrawError: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Post a plain comment in the PR conversation.
+ *
+ * The `issues` endpoint on purpose: that is the one shape of writing on a PR
+ * that GitHub does not count as a review. A `pulls/…/reviews` POST with an
+ * event of COMMENT would look the same in the thread and be a review
+ * everywhere it matters — in the PR's review list, in `fetchOwnReview`, in
+ * whether the request is satisfied — and the only thing that may speak for a
+ * review here is Send.
+ */
+export async function postIssueComment(ref, body) {
+    const out = await gh([
+        "api",
+        `repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments`,
+        "--method",
+        "POST",
+        "-f",
+        `body=${body}`,
+    ]);
+    try {
+        return { url: JSON.parse(out).html_url ?? null };
+    }
+    catch {
+        return { url: null };
+    }
+}
+/**
+ * THE ONLY GITHUB WRITE THAT SPEAKS AS A REVIEW.
+ * Submits a review in one shot. Must only ever be called from a human act:
+ * the cockpit's Send button, `cerber send` after confirmation, opt-in
+ * auto-send, or a handoff that was ticked to carry the draft — which composes
+ * through this same path and always as COMMENT.
+ * The two writes above are the other things that reach GitHub — a handoff's
+ * request swap and its note — and neither of those is a review.
  */
 export async function submitReview(ref, payload) {
     const args = [

package/dist/core/history.js

@@ -177,6 +177,12 @@ export function describeChange(before, after) {
     if (after.filed && after.filed.at !== before?.filed?.at) {
         lines.push(`filed under settled — ${FILED_PHRASE[after.filed.reason] ?? after.filed.reason}`);
     }
+    if (after.handoff && after.handoff.at !== before?.handoff?.at) {
+        const h = after.handoff;
+        lines.push(`handed to @${h.to} — GitHub asks them for this review now` +
+            `${h.withdrewYours ? "" : ", and still asks you too"}` +
+            `${h.note ? ", with a note on the PR" : ""}`);
+    }
     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` +

package/dist/core/refresh.js

@@ -80,6 +80,11 @@ export function mergeRunResult(fresh, current) {
         notified: current.notified,
         calibration: current.calibration,
         filed: current.filed,
+        // A decision of the user's, like the status above it: a handoff that landed
+        // while the run worked has already moved the request on GitHub, and a run
+        // that wrote `null` over it would leave the row reading "skipped" with
+        // nothing anywhere saying who has the PR now.
+        handoff: current.handoff,
         chat: current.chat,
         preChat: current.preChat,
         pendingChat: current.pendingChat,

package/dist/core/revise.js

@@ -66,6 +66,10 @@ export function mergeConcurrentEdits(before, after, current) {
         // Nor does a turn announce anything: the ledger is the poll's, and a turn
         // takes minutes, which is long enough for a poll to have stamped it.
         notified: current.notified,
+        // Nor does it hand a review to anybody. A handoff that landed while the
+        // turn ran has already moved the request on GitHub, so restoring the
+        // pre-turn `null` would erase the only local record of where the PR went.
+        handoff: current.handoff,
     };
 }
 export function applyRevisions(artifact, revisions, opts = {}) {

package/dist/runner/review.js

@@ -193,6 +193,7 @@ async function performReview(ref, pr, existing, opts, log) {
         sent: null,
         refresh: null,
         filed: null,
+        handoff: null,
         settledAt: null,
         calibration: null,
         // The conversation is the user's writing, so a re-review keeps it — the

package/dist/server/daemon.js

@@ -47,6 +47,7 @@ export function stubArtifact(ref) {
         sent: null,
         refresh: null,
         filed: null,
+        handoff: null,
         settledAt: null,
         // Null, not absent: the poll found this PR, so it owes the machine a tap
         // for it — once there is something to tap you about (§9.8).
@@ -365,8 +366,14 @@ export function startDaemon(opts) {
             // those calls 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 }
+                    // this row was settled is not the story of a row that is back. So
+                    // does `handoff`, and for a sharper reason: every line it prints
+                    // says GitHub is asking somebody else and no longer asking you,
+                    // which is the one fact a reopen has just disproved. Left behind it
+                    // would also tell the next handoff your request was already
+                    // withdrawn, and that one skips the withdrawal — so the row would
+                    // claim you were taken off a PR you are still on.
+                    { ...a, status: reopenedStatus(a), settledAt: null, filed: null, handoff: 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.

package/dist/server/index.js

@@ -9,7 +9,7 @@ import { randomUUID } from "node:crypto";
 import { isPureStub } from "./daemon.js";
 import { ArtifactStatusSchema, SCHEMA_VERSION, SeveritySchema, VerdictSchema, artifactId, artifactKey, } from "../core/artifact.js";
 import { toMarkdown } from "../core/export.js";
-import { fetchPrDiff, fetchPrInfo, parsePrRef, submitReview } from "../core/gh.js";
+import { currentLogin, fetchAssignableUsers, fetchPrDiff, fetchPrInfo, handOffReview, parsePrRef, postIssueComment, submitReview, } from "../core/gh.js";
 import { z } from "zod";
 import { DaemonConfigSchema, configPath, loadConfig, saveConfig } from "../core/config.js";
 import { refreshArtifact, userOwnsStatus } from "../core/refresh.js";
@@ -29,6 +29,33 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * own decision about a PR. Everything else is a fact some other path owns.
  */
 const SETTLEABLE = ["reviewed", "skipped"];
+/**
+ * What a handoff needs: one person, a note to post, and a confirmation.
+ *
+ * A login and not a team. `@org/team` reaches GitHub through a different field
+ * (`team_reviewers`), and "take your own request off" means nothing next to a
+ * room being asked — so it is refused in words rather than half-handled.
+ */
+const HandoffSchema = z.object({
+    to: z
+        .string()
+        .transform((s) => s.trim().replace(/^@/, ""))
+        .refine((s) => /^[A-Za-z0-9](?:[A-Za-z0-9_-]{0,37}[A-Za-z0-9])?$/.test(s), {
+        message: "`to` must be one GitHub login — a handoff names a person, and asking a team is a different thing cerber does not do yet",
+    }),
+    /** The comment to post on the PR. Blank or absent posts nothing. */
+    note: z.string().max(65536).optional(),
+    /**
+     * Send the draft along with it, as a COMMENT review.
+     *
+     * Off unless asked for: a draft the poll wrote and nobody has read is exactly
+     * what the send path exists to keep off GitHub, and a handoff is reachable
+     * from a row you never opened. Asking for it is the human act that makes it
+     * a send like any other.
+     */
+    postReview: z.boolean().optional(),
+    confirm: z.boolean().optional(),
+});
 /**
  * Is an AI run rewriting this draft right now?
  *
@@ -193,6 +220,10 @@ export async function buildApp(opts) {
             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,
+            // And when it was settled by giving it away. Carried in the list because
+            // it is what the row's tag reads, and because an open request GitHub has
+            // not caught up on yet is explained by this and nothing else.
+            handoff: a.handoff,
         })));
     });
     // ---- Pull a PR in: review anything, not just what the inbox found ----
@@ -289,6 +320,7 @@ export async function buildApp(opts) {
             sent: null,
             refresh: null,
             filed: null,
+            handoff: null,
             settledAt: null,
             calibration: null,
             chat: [],
@@ -672,7 +704,7 @@ export async function buildApp(opts) {
         c.header("Content-Disposition", `attachment; filename="review-${artifactKey(artifact.id)}.md"`);
         return c.body(toMarkdown(artifact));
     });
-    // ---- Send: THE ONLY GITHUB WRITE. Explicit user action from the cockpit. ----
+    // ---- Send: the only write that speaks as a review. Explicit user action. ----
     app.post("/api/reviews/:key/send", async (c) => {
         const { event, confirm } = await c.req.json();
         if (confirm !== true) {
@@ -717,6 +749,189 @@ export async function buildApp(opts) {
         const event = (c.req.query("event") ?? "COMMENT");
         return c.json(buildReviewPayload(artifact, event));
     });
+    /**
+     * Who this review could be handed to — the handoff's suggestions.
+     *
+     * Read-only, and allowed to come back empty: the name box works without it,
+     * and a repo cerber cannot list people for is a repo you can still hand a PR
+     * to by typing the name. So a failure here is reported as a line in the
+     * dialog, not as an error that stops it.
+     *
+     * Two logins are dropped because GitHub would refuse them anyway: your own,
+     * and the PR author's — nobody reviews their own pull request.
+     */
+    app.get("/api/reviews/:key/reviewers", async (c) => {
+        const artifact = await loadArtifactByKey(c.req.param("key"));
+        if (!artifact)
+            return c.json({ error: "not found" }, 404);
+        let logins;
+        try {
+            logins = await fetchAssignableUsers({
+                owner: artifact.pr.owner,
+                repo: artifact.pr.repo,
+                number: artifact.pr.number,
+            });
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 502);
+        }
+        // Not knowing who you are costs the exclusion, not the list: you would
+        // simply see yourself offered, and the handoff refuses that anyway.
+        const me = await currentLogin().catch(() => null);
+        const drop = new Set([me, artifact.pr.author].filter(Boolean).map((l) => l.toLowerCase()));
+        return c.json({
+            logins: logins.filter((l) => !drop.has(l.toLowerCase())).sort((a, b) => a.localeCompare(b)),
+        });
+    });
+    /**
+     * Give this review to somebody else: GitHub's review request moves to them, a
+     * note in the conversation says so, and the row settles here.
+     *
+     * Up to three writes. Two are never a review: the request swap, and the note,
+     * which is a plain issue comment. The third is the draft, and only when
+     * `postReview` asked for it — composed and submitted by the send path itself
+     * rather than a second composition, and always as COMMENT, because handing a
+     * PR over hands the judgement over with it.
+     */
+    app.post("/api/reviews/:key/handoff", async (c) => {
+        const parsed = HandoffSchema.safeParse(await c.req.json().catch(() => null));
+        if (!parsed.success) {
+            return c.json({ error: parsed.error.issues.map((i) => i.message).join("; ") }, 400);
+        }
+        const { to, confirm } = parsed.data;
+        const note = parsed.data.note?.trim() ?? "";
+        const postReview = parsed.data.postReview === true;
+        if (confirm !== true) {
+            return c.json({ error: "a handoff requires an explicit confirm: true" }, 400);
+        }
+        const key = c.req.param("key");
+        const artifact = await loadArtifactByKey(key);
+        if (!artifact)
+            return c.json({ error: "not found" }, 404);
+        // Not while a run is rewriting the draft. The handoff settles the row, and
+        // settling one out from under a run that is about to report on it is the
+        // same race the send path refuses.
+        if (inFlight(artifact)) {
+            return c.json({ error: "a review of this PR is running — wait for it to finish" }, 409);
+        }
+        // Nor while a chat turn is being answered. A turn's result is folded onto
+        // whatever the artifact says when it lands, and the fold is written for a
+        // row nobody gave away mid-turn: every field a handoff sets would have to
+        // survive it. One of them does now, and refusing here is what keeps the
+        // rest — the send record above all — from needing to.
+        if (turnInFlight(artifact)) {
+            return c.json({ error: "the reviewer is answering a question about this review — wait for it to land" }, 409);
+        }
+        let me;
+        try {
+            me = await currentLogin();
+        }
+        catch (err) {
+            // Without this there is nobody to take off the PR, and a handoff that
+            // only adds a reviewer leaves you on the hook while the row says
+            // otherwise — so it does not happen at all.
+            return c.json({ error: `cerber could not ask gh who you are: ${err instanceof Error ? err.message : String(err)}` }, 502);
+        }
+        if (to.toLowerCase() === me.toLowerCase()) {
+            return c.json({ error: `@${to} is you — a handoff needs somebody else` }, 400);
+        }
+        const ref = { owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number };
+        let swap;
+        try {
+            swap = await handOffReview(ref, to, artifact.handoff?.withdrewYours ? null : me);
+        }
+        catch (err) {
+            // Nothing was written here and nothing was posted: the request swap goes
+            // first precisely so its refusal — not a collaborator, no permission —
+            // leaves the PR and this row exactly as they were.
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 502);
+        }
+        if (swap.withdrawError) {
+            console.error(`[handoff ${artifact.id}] could not withdraw your request: ${swap.withdrawError}`);
+        }
+        // The note goes last, and is allowed to fail on its own — as is the review
+        // above it. The request has already moved by now: they are being asked for
+        // this review whether or not the conversation says why, so a failure in
+        // either is recorded and reported rather than rolled back into a lie about
+        // where the PR is.
+        // The draft, when it was asked for, and always as a COMMENT: handing a PR
+        // over is handing over the judgement with it, so an approve or a change
+        // request here would be cerber ruling on a review it is giving away. The
+        // grades stay on the findings, which is where they were anyway — the
+        // verdict is the part that is now @to's to make.
+        //
+        // Re-read from disk first, and not out of caution: the artifact above was
+        // loaded before the request swap, which is two GitHub calls ago, and a Send
+        // in another tab or an auto-send landing in that window would make this the
+        // second review on the PR. The snapshot cannot see that; the file can.
+        let sendError = null;
+        let sent = null;
+        let payload = null;
+        const alreadySent = postReview ? ((await loadArtifactByKey(key))?.sent ?? artifact.sent) : null;
+        // And there has to be a review to post. The dialog only offers the box on a
+        // row that has one, but the dialog is not the guard: a stale tab or a direct
+        // call would otherwise submit a body that is nothing but cerber's footer,
+        // under the user's name, on a PR nobody has drafted a word about.
+        const somethingToSay = artifact.summary !== "" || artifact.comments.some((cm) => cm.status !== "dropped");
+        if (postReview && !alreadySent && somethingToSay) {
+            payload = buildReviewPayload(artifact, "COMMENT");
+            try {
+                const { url } = await submitReview(ref, {
+                    event: payload.event,
+                    body: payload.body,
+                    comments: payload.comments,
+                    commitId: payload.commitId,
+                });
+                sent = { at: new Date().toISOString(), event: payload.event, url, auto: false };
+            }
+            catch (err) {
+                sendError = err instanceof Error ? err.message : String(err);
+                console.error(`[handoff ${artifact.id}] the review did not post: ${sendError}`);
+            }
+        }
+        let noteError = null;
+        let posted = null;
+        if (note) {
+            try {
+                const { url } = await postIssueComment(ref, note);
+                posted = { body: note, url };
+            }
+            catch (err) {
+                noteError = err instanceof Error ? err.message : String(err);
+                console.error(`[handoff ${artifact.id}] the note did not post: ${noteError}`);
+            }
+        }
+        const at = new Date().toISOString();
+        const updated = await updateArtifactByKey(key, (a) => {
+            // Three ways this row can end, and the status follows what actually
+            // reached GitHub. A review that went is the strongest thing true about
+            // it; a row already sent keeps the standing it had; anything else is you
+            // deciding not to review this one, which is a skip.
+            const settles = !sent && !a.sent;
+            return {
+                ...a,
+                status: sent ? "sent" : a.sent ? a.status : "skipped",
+                settledAt: settles ? at : a.settledAt,
+                // Cerber's account of why a row is filed away cannot stand next to your
+                // own: you did this, and `handoff` is what the queue tags the row from.
+                filed: a.sent ? a.filed : null,
+                // The disk's record wins: a send that landed while this handoff was
+                // talking to GitHub is a review that went, and ours — if there is one
+                // at all — came after it.
+                sent: a.sent ?? sent,
+                calibration: sent && payload ? computeCalibration(a, payload.event) : a.calibration,
+                handoff: {
+                    at,
+                    to,
+                    withdrewYours: swap.withdrewYours,
+                    note: posted,
+                },
+            };
+        });
+        if (!updated)
+            return c.json({ error: "not found" }, 404);
+        return c.json({ artifact: updated, noteError, sendError });
+    });
     // Static cockpit build. In the published package web/dist ships alongside dist/.
     // __dirname is src/server (dev via tsx) or dist/server (built) — both are two levels below the repo root.
     const webDist = path.resolve(__dirname, "../../web/dist");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "keywords": [