@fullstackhouse/cerber 0.33.0 → 0.35.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:
 
@@ -23,6 +25,9 @@ That gate is the whole point, and the reason this is not another review bot:
 
 Named after Cerberus, the gatekeeper: cerber guards what gets merged.
 
+Why it exists, and the four things I tried first:
+[AI drafts the review. I decide what gets sent.](https://www.fullstack.house/blog/cerber?utm_source=github&utm_medium=readme)
+
 **The whole loop in seventeen seconds** — five PRs already drafted when you sit
 down, the one that isn't an approval, straight to its blocker, arguing with the
 reviewer until it rewrites its own finding, dropping the comment you disagree
@@ -86,6 +91,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 +158,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 +235,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/cli/index.js

@@ -9,8 +9,8 @@ import { configPath, loadConfig, saveConfig } from "../core/config.js";
 import { formatBlockers, isBlocking, preflight } from "../core/preflight.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";
+import { parsePrRef, postReplies, searchAwaitingMe, submitReview } from "../core/gh.js";
+import { buildReviewPayload, computeCalibration, describeReplyFailures, eventForRecommendation, recordReplies, } from "../core/send.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";
@@ -21,6 +21,13 @@ const program = new Command();
  * The published version, read from the manifest rather than typed here — a
  * hand-maintained copy drifted to 0.5.0 while 0.30.0 shipped, and `--version`
  * is the first thing anyone runs to decide whether a project is alive.
+ *
+ * In the published package that manifest is the one the release bumped, so this
+ * is the real version wherever anyone installed cerber. In a clone it reads
+ * `0.0.0-development`, because nothing commits the bump back to `main` and a
+ * number left behind there would quietly describe the release before last. A
+ * sentinel cannot drift: it says "built from source", which is true, instead of
+ * naming a version this build is not.
  */
 const { version } = createRequire(import.meta.url)("../../package.json");
 /**
@@ -208,6 +215,14 @@ program
             `either of which clears the stale status.`);
         process.exit(1);
     }
+    // The same wait the cockpit makes. A check run by `serve` leaves the status
+    // `ready`, so the guard above cannot see it — and sending now would post
+    // the duplicates it is about to find.
+    if (artifact.raisedCheck?.checkingSince) {
+        console.error(`cerber is checking which findings of ${id} other reviewers already raised — send once it finishes. ` +
+            `If nothing is running, restart \`cerber serve\`, which clears a check that died mid-flight.`);
+        process.exit(1);
+    }
     const event = (opts.event ??
         (artifact.verdict ? eventForRecommendation(artifact.verdict.recommendation) : "COMMENT")).toUpperCase();
     if (!["APPROVE", "COMMENT", "REQUEST_CHANGES"].includes(event)) {
@@ -221,6 +236,16 @@ program
     if (payload.folded.length > 0) {
         console.log(`  comments folded into body (no diff anchor): ${payload.folded.length}`);
     }
+    if (payload.replies.length > 0) {
+        console.log(`  replies in another reviewer's thread: ${payload.replies.length}`);
+    }
+    if (payload.held.length > 0) {
+        console.log(`  left out — already raised by another reviewer: ${payload.held.length}` +
+            ` (decide in the cockpit to post or reply instead)`);
+    }
+    if (artifact.raisedCheck?.error) {
+        console.log(`  ⚠ could not check what others already raised: ${artifact.raisedCheck.error}`);
+    }
     console.log(`  body: ${payload.body.length} chars\n`);
     if (!opts.yes) {
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -244,6 +269,16 @@ program
         calibration: computeCalibration(a, event),
     }));
     console.log(`✔ Review sent${url ? `: ${url}` : "."}`);
+    const outcomes = await postReplies(ref, payload.replies);
+    await updateArtifactByKey(artifactKey(id), (a) => recordReplies(a, outcomes));
+    const replyError = describeReplyFailures(outcomes);
+    if (replyError) {
+        console.error(`✖ ${replyError}`);
+        process.exitCode = 1;
+    }
+    else if (outcomes.length > 0) {
+        console.log(`✔ ${outcomes.length} ${outcomes.length === 1 ? "reply" : "replies"} posted in existing threads.`);
+    }
 });
 program
     .command("trust")

package/dist/core/artifact.js

@@ -8,6 +8,63 @@ export const SCHEMA_VERSION = 1;
  * is not a finding at all — a question, a note, praise — not "unknown".
  */
 export const SeveritySchema = z.enum(["blocker", "minor", "nit"]);
+/**
+ * Where on the PR somebody else already made a point: an inline thread, or the
+ * body of a review — some bots put their findings there and nowhere else.
+ */
+export const RaisedPlaceSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("thread"),
+        path: z.string(),
+        /** Null once GitHub can no longer place the thread on the current diff. */
+        line: z.number().int().positive().nullable(),
+        /** Outdated: the code it was on has changed since. Resolved wins over outdated. */
+        state: z.enum(["open", "resolved", "outdated"]),
+        /** REST id of the thread's first comment — what a reply is posted against. */
+        replyTo: z.string(),
+    }),
+    z.object({ kind: z.literal("review") }),
+]);
+/**
+ * Another reviewer — a person or a bot, never you — already raised the same
+ * defect on the PR.
+ *
+ * Found after the review, never shown to it: a review that has read earlier
+ * comments anchors on them, and they are third-party text the prompt would
+ * have to treat as hostile. So the draft is written blind, and this is the
+ * comparison afterwards (`src/runner/raised.ts`).
+ *
+ * It changes what Send does with the comment and nothing else — the comment
+ * stays in the draft, as written. What Send does is `decision`, and while it
+ * is null the default for the place applies (`sendTreatment` in
+ * `src/core/raised.ts`): left out, unless the thread was resolved, because a
+ * problem somebody marked settled that is still in the code is news.
+ */
+export const AlreadyRaisedSchema = z.object({
+    /** GitHub node id of the thread or review — how the next check finds it again. */
+    remarkId: z.string(),
+    by: z.string(),
+    at: z.string(),
+    url: z.string().nullable().default(null),
+    where: RaisedPlaceSchema,
+    /** Why the two are the same defect, in a sentence — and what this one adds, if anything. */
+    reason: z.string(),
+    /**
+     * What you chose: post it as a comment of its own anyway, or answer in their
+     * thread. Null is "not decided", which Send reads as the default above. Drop
+     * is not here: dropping is the comment's own `status`, as for any comment.
+     */
+    decision: z.enum(["send", "reply"]).nullable().default(null),
+    /** The reply Send posted into their thread. */
+    replied: z.object({ at: z.string(), url: z.string().nullable().default(null) }).nullable().default(null),
+    /**
+     * The other remarks that raised the same thing, behind the one shown. Kept
+     * because each was compared once and will not be asked about again: if the
+     * one shown is deleted, the next best takes its place instead of the
+     * finding quietly posting as new.
+     */
+    others: z.array(z.object({ remarkId: z.string(), reason: z.string() })).default([]),
+});
 /** A draft inline comment. Never sent to GitHub unless the user explicitly sends the review. */
 export const CommentSchema = z.object({
     id: z.string(),
@@ -26,6 +83,32 @@ export const CommentSchema = z.object({
     originalLine: z.number().int().positive().nullable().default(null),
     /** The commented line no longer exists in the diff — it can't post inline. */
     drifted: z.boolean().default(false),
+    /** Somebody else already raised this on the PR. AI comments only. */
+    alreadyRaised: AlreadyRaisedSchema.nullable().default(null),
+});
+/**
+ * The last comparison of the draft against what others already said on the PR.
+ *
+ * It is incremental, and these lists are why: a check compares only what is
+ * new since the last one — a remark nobody has looked at yet, or a finding a
+ * chat turn added — so opening a review costs one read of GitHub and no model
+ * call unless something actually changed.
+ */
+export const RaisedCheckSchema = z.object({
+    /**
+     * When the last check that changed anything finished, or failed. A check
+     * that found nothing new writes nothing (`raisedChanged`). Null while the
+     * first is still running.
+     */
+    at: z.string().nullable().default(null),
+    /** Set while a check runs detached, so the cockpit knows to wait for it. */
+    checkingSince: z.string().nullable().default(null),
+    /** GitHub node ids of every remark compared so far. */
+    remarks: z.array(z.string()).default([]),
+    /** Ids of every finding compared so far. */
+    findings: z.array(z.string()).default([]),
+    /** Why the last check could not finish. The matches from before it stand. */
+    error: z.string().nullable().default(null),
 });
 /** A logical group of changes — the unit of the review walkthrough. */
 export const ChapterSchema = z.object({
@@ -149,6 +232,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 +405,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.
@@ -332,6 +447,8 @@ export const ArtifactSchema = z.object({
         .optional(),
     /** Last time this review was pulled forward onto a newer head commit. */
     refresh: RefreshInfoSchema.nullable().default(null),
+    /** The last check for findings somebody else already raised. Null: never checked. */
+    raisedCheck: RaisedCheckSchema.nullable().default(null),
     calibration: CalibrationSchema.nullable().default(null),
     /** The conversation about this review. Never sent to GitHub. */
     chat: z.array(ChatTurnSchema).default([]),

package/dist/core/autosend.js

@@ -1,7 +1,14 @@
+import { sendTreatment } from "./raised.js";
 /**
  * Auto-send policy — deliberately narrow:
  * only APPROVE verdicts, at or above the confidence threshold, never a
  * re-send. COMMENT and REQUEST_CHANGES always wait for a human.
+ *
+ * Findings somebody else already raised go the way Send's default sends them:
+ * an undecided one is left out, and the reason says how many were. Nobody is
+ * there to decide, and the default is the side that posts less. A reply into
+ * someone's thread is never auto-sent — that is a decision only a person makes,
+ * and auto-send posts one review and nothing else.
  */
 export function evaluateAutoSend(artifact, threshold) {
     if (artifact.sent)
@@ -31,5 +38,34 @@ export function evaluateAutoSend(artifact, threshold) {
             reason: `confidence ${artifact.verdict.confidence}% < threshold ${threshold}%`,
         };
     }
-    return { eligible: true, reason: `approve at ${artifact.verdict.confidence}% ≥ ${threshold}%` };
+    // Nobody is watching an auto-send, so a check that never ran, is still
+    // running, or failed is not the same as one that found nothing: each would
+    // post every duplicate it missed. Only a finished, clean check will do.
+    const check = artifact.raisedCheck;
+    if (check?.error) {
+        return {
+            eligible: false,
+            reason: `could not check which findings other reviewers already raised (${check.error})`,
+        };
+    }
+    if (check == null || check.at == null || check.checkingSince != null) {
+        return {
+            eligible: false,
+            reason: "the check for findings other reviewers already raised has not finished",
+        };
+    }
+    const live = artifact.comments.filter((c) => c.status !== "dropped");
+    const replies = live.filter((c) => sendTreatment(c) === "reply").length;
+    if (replies > 0) {
+        return {
+            eligible: false,
+            reason: `${replies} finding(s) marked to reply in another reviewer's thread — only a human Send posts replies`,
+        };
+    }
+    const held = live.filter((c) => sendTreatment(c) === "hold").length;
+    return {
+        eligible: true,
+        reason: `approve at ${artifact.verdict.confidence}% ≥ ${threshold}%` +
+            (held > 0 ? `; ${held} finding(s) already raised by another reviewer left out` : ""),
+    };
 }

package/dist/core/export.js

@@ -38,7 +38,7 @@ export function toMarkdown(artifact) {
             lines.push("");
             const comments = artifact.comments.filter((c) => c.chapterId === ch.id && c.status !== "dropped");
             for (const c of comments) {
-                lines.push(`> **${c.path}${c.line != null ? `:${c.line}` : ""}** — ${withGrade(c.body, c.severity).replace(/\n/g, "\n> ")}`);
+                lines.push(renderComment(c));
                 lines.push("");
             }
         }
@@ -49,9 +49,15 @@ export function toMarkdown(artifact) {
         lines.push("## Other comments");
         lines.push("");
         for (const c of orphans) {
-            lines.push(`> **${c.path}${c.line != null ? `:${c.line}` : ""}** — ${withGrade(c.body, c.severity).replace(/\n/g, "\n> ")}`);
+            lines.push(renderComment(c));
             lines.push("");
         }
     }
     return lines.join("\n");
 }
+function renderComment(c) {
+    const text = `> **${c.path}${c.line != null ? `:${c.line}` : ""}** — ${withGrade(c.body, c.severity).replace(/\n/g, "\n> ")}`;
+    // Said here too, so a reader of the export does not take a repeat for news.
+    const raised = c.alreadyRaised;
+    return raised ? `${text}\n>\n> _Already raised by @${raised.by}: ${raised.reason}_` : text;
+}

package/dist/core/gh.js

@@ -424,6 +424,105 @@ export async function fetchLastReviewRequest(ref, login) {
     const raw = JSON.parse(out);
     return lastRequestOf(raw.data?.repository?.pullRequest?.timelineItems?.nodes ?? [], login);
 }
+/**
+ * Everything others have said on the PR in review form: the inline threads, by
+ * their first comment, and the review bodies.
+ *
+ * Yours are left out — what you already said is not something a draft of yours
+ * repeats from somebody else — and so are the author's: a thread the author
+ * opens on their own PR is an explanation, not a finding. Bots stay in. A bot
+ * is very often the first to raise a thing, and some put their findings only in
+ * the review body, which is why bodies are read at all.
+ *
+ * Replies inside a thread are not read. The finding is what opened the thread;
+ * the rest is the conversation about it.
+ */
+export function priorRemarks(raw, people) {
+    const skip = new Set([people.you.toLowerCase(), people.author.toLowerCase()]);
+    const remarks = [];
+    for (const t of raw.threads) {
+        const first = t.comments.nodes[0];
+        // GitHub's own deleted-user placeholder, so a thread whose author left is
+        // still a thing somebody raised.
+        const by = first?.author?.login ?? "ghost";
+        if (!first || first.fullDatabaseId == null || skip.has(by.toLowerCase()))
+            continue;
+        remarks.push({
+            kind: "thread",
+            id: t.id,
+            by,
+            bot: first.author?.__typename === "Bot",
+            at: first.createdAt,
+            body: first.body ?? "",
+            url: first.url,
+            path: t.path,
+            line: t.line,
+            state: t.isResolved ? "resolved" : t.isOutdated ? "outdated" : "open",
+            replyTo: String(first.fullDatabaseId),
+        });
+    }
+    for (const r of raw.reviews) {
+        const by = r.author?.login ?? "ghost";
+        // An empty body is a review whose whole say is in its threads, read above.
+        // A pending one is a draft nobody else can see.
+        if (!r.body?.trim() || r.submittedAt == null || skip.has(by.toLowerCase()))
+            continue;
+        remarks.push({
+            kind: "review",
+            id: r.id,
+            by,
+            bot: r.author?.__typename === "Bot",
+            at: r.submittedAt,
+            body: r.body,
+            url: r.url,
+        });
+    }
+    return remarks;
+}
+// The last 100 of each, in one call. A PR past 100 threads loses its oldest
+// from the comparison — accepted rather than paginated, because the failure is
+// the conservative one: a duplicate that posts, which is what happened before
+// there was any comparison at all.
+const PRIOR_REMARKS_QUERY = `query($owner:String!,$repo:String!,$number:Int!){
+  repository(owner:$owner,name:$repo){
+    pullRequest(number:$number){
+      reviewThreads(last:100){
+        nodes{ id isResolved isOutdated path line
+          comments(first:1){ nodes{ fullDatabaseId url createdAt body author{ login __typename } } }
+        }
+      }
+      reviews(last:100){
+        nodes{ id state submittedAt url body author{ login __typename } }
+      }
+    }
+  }
+}`;
+/**
+ * Read what others have already said on a PR in review form.
+ *
+ * GraphQL because REST has no thread resolution: `pulls/N/comments` returns the
+ * comments but not whether anybody resolved the thread they are in, and that is
+ * the fact that decides what Send does with a match.
+ */
+export async function fetchPriorRemarks(ref, people) {
+    const out = await gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${PRIOR_REMARKS_QUERY}`,
+        "-F",
+        `owner=${ref.owner}`,
+        "-F",
+        `repo=${ref.repo}`,
+        "-F",
+        `number=${ref.number}`,
+    ]);
+    const raw = JSON.parse(out);
+    const pr = raw.data?.repository?.pullRequest;
+    if (!pr)
+        throw new Error(`GitHub returned no pull request for ${ref.owner}/${ref.repo}#${ref.number}`);
+    return priorRemarks({ threads: pr.reviewThreads?.nodes ?? [], reviews: pr.reviews?.nodes ?? [] }, people);
+}
 export function searchAwaitingArgs(repoFilter, limit = 50) {
     const args = [
         "search",
@@ -448,9 +547,157 @@ 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 };
+    }
+}
+/**
+ * Answer an existing review thread — a finding of yours that somebody else
+ * already raised, posted where they raised it instead of as a second thread.
+ *
+ * Part of Send and never anything on its own: it is called only by
+ * `postReplies`, after `submitReview` has posted the review it goes with, and
+ * only for comments the user marked "reply in their thread". GitHub files each
+ * reply under a small review of its own, which is GitHub's bookkeeping and not
+ * a second verdict: it carries no event, and the review that carries yours has
+ * already landed.
+ */
+export async function replyInThread(ref, replyTo, body) {
+    const out = await gh([
+        "api",
+        `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}/comments/${replyTo}/replies`,
+        "--method",
+        "POST",
+        "-f",
+        `body=${body}`,
+    ]);
+    try {
+        return { url: JSON.parse(out).html_url ?? null };
+    }
+    catch {
+        return { url: null };
+    }
+}
+/**
+ * Post a Send's replies, one by one, each allowed to fail on its own.
+ *
+ * After the review, never before it: the review is the thing the user vouched
+ * for, and a review that failed must leave nothing behind for the retry to post
+ * twice. A reply that fails once the review is up is reported against its
+ * comment rather than rolled back into a claim that nothing was sent.
+ */
+export async function postReplies(ref, replies) {
+    const outcomes = [];
+    for (const r of replies) {
+        const at = new Date().toISOString();
+        try {
+            const { url } = await replyInThread(ref, r.replyTo, r.body);
+            outcomes.push({ commentId: r.commentId, at, url, error: null });
+        }
+        catch (err) {
+            outcomes.push({ commentId: r.commentId, at, url: null, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return outcomes;
+}
+/**
+ * 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 other writes are a handoff's request swap and its note, neither of them
+ * a review, and the thread replies a Send carries for findings somebody else
+ * already raised (`replyInThread`).
  */
 export async function submitReview(ref, payload) {
     const args = [