@fullstackhouse/cerber 0.9.1 → 0.10.0

package/README.md

@@ -199,6 +199,42 @@ get its opinion of the new code, hit **Re-review at the new head** in the
 cockpit (or `cerber review <pr> --force`) — comments you wrote or rewrote are
 carried into the fresh review.
 
+### Arguing with the review before you send it
+
+A draft you disagree with used to leave two options: rewrite it by hand, or
+re-review and hope. Neither lets you say *what was wrong*. So every review has
+a conversation attached — **Talk to the reviewer**, at the bottom of the
+walkthrough.
+
+Ask it why it said something, and it answers. Tell it the summary is restating
+the author's claims rather than what it verified, and it rewrites the summary.
+The reviewer revises the draft as it answers: there is no accept step, because
+you already asked for the change. What it changed shows up in the transcript
+(*"✎ rewrote the summary"*, *"✎ dropped the comment on line 250"*).
+
+- **It is the same reviewer.** A turn resumes the Claude session the review ran
+  in, so it still holds everything it read. Asking "did you actually check
+  that?" gets an answer from the run that did or didn't — not from a fresh
+  agent re-deriving an opinion from the diff.
+- **It reads the code to answer you.** The checkout cache is small, so by the
+  time you argue with a review its source is usually evicted; a turn re-clones
+  it. If it can't, the turn still runs and the reviewer is told it is working
+  blind rather than left to describe files from memory.
+- **It can say no.** The prompt tells it not to fold under push-back. If you
+  are wrong about something it checked, it says so and changes nothing.
+- **Your words are yours.** Comments you wrote or edited are off limits: it
+  will tell you one of them needs changing rather than rewriting it. Say so
+  explicitly and it will.
+- **Point at things.** *discuss* on any comment, chapter, or the summary drops
+  a reference into your next message.
+- **Reset** puts the review back the way the AI first wrote it and keeps the
+  conversation — you lose the edits, not the reasoning.
+
+Nothing in the conversation reaches GitHub. Send still builds its payload from
+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.
+
 ## Status / roadmap
 
 Early, but all six planned phases have shipped.

package/dist/core/artifact.js

@@ -66,6 +66,11 @@ export const RunInfoSchema = z.object({
     withSource: z.boolean().default(false),
     /** The user vouched for this PR, so the reviewer could also run commands. */
     trusted: z.boolean().default(false),
+    /**
+     * The Claude session this review ran in. Chat turns resume it, so the
+     * reviewer answering a question still holds everything it read.
+     */
+    sessionId: z.string().nullable().default(null),
 });
 export const SentInfoSchema = z.object({
     at: z.string(),
@@ -94,6 +99,59 @@ export const CalibrationSchema = z.object({
     aiCommentsEdited: z.number().int(),
     userCommentsAdded: z.number().int(),
 });
+/**
+ * One edit a chat turn made to the review it is about.
+ *
+ * The agent revises the draft directly — there is no accept step — so these are
+ * a record of what already happened, rendered in the transcript, not a proposal
+ * awaiting a click. The user's escape hatch is the conversation itself, plus
+ * the one pre-chat snapshot.
+ */
+export const RevisionSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("summary"), body: z.string() }),
+    z.object({ kind: z.literal("verdict"), verdict: VerdictSchema }),
+    z.object({ kind: z.literal("chapter"), chapterId: z.string(), title: z.string().optional(), explanation: z.string().optional() }),
+    z.object({ kind: z.literal("comment-edit"), commentId: z.string(), body: z.string() }),
+    z.object({ kind: z.literal("comment-drop"), commentId: z.string() }),
+    z.object({
+        kind: z.literal("comment-add"),
+        path: z.string(),
+        line: z.number().int().positive().nullable(),
+        body: z.string(),
+        chapterId: z.string().nullable().default(null),
+    }),
+]);
+/** A revision the run declined to make, and why — shown in the transcript. */
+export const RefusalSchema = z.object({
+    revision: RevisionSchema,
+    reason: z.string(),
+});
+export const ChatTurnSchema = z.object({
+    id: z.string(),
+    role: z.enum(["user", "assistant"]),
+    at: z.string(),
+    body: z.string(),
+    /** What the user pointed at with "discuss this" — user turns only. */
+    refs: z
+        .array(z.object({
+        target: z.enum(["summary", "verdict", "chapter", "comment"]),
+        id: z.string().nullable().default(null),
+    }))
+        .default([]),
+    /** Edits this turn made to the review. Assistant turns only. */
+    revisions: z.array(RevisionSchema).default([]),
+    /** Edits this turn asked for but the artifact would not accept. */
+    refused: z.array(RefusalSchema).default([]),
+    costUsd: z.number().nullable().default(null),
+});
+/** The parts of a review a chat turn may rewrite — the reset target. */
+export const ReviewSnapshotSchema = z.object({
+    at: z.string(),
+    summary: z.string(),
+    chapters: z.array(ChapterSchema),
+    comments: z.array(CommentSchema),
+    verdict: VerdictSchema.nullable(),
+});
 export const ArtifactSchema = z.object({
     schemaVersion: z.literal(SCHEMA_VERSION),
     /** "owner/repo#123" */
@@ -115,6 +173,10 @@ export const ArtifactSchema = z.object({
     /** Last time this review was pulled forward onto a newer head commit. */
     refresh: RefreshInfoSchema.nullable().default(null),
     calibration: CalibrationSchema.nullable().default(null),
+    /** The conversation about this review. Never sent to GitHub. */
+    chat: z.array(ChatTurnSchema).default([]),
+    /** The review as it stood before the first chat turn — "reset" restores this. */
+    preChat: ReviewSnapshotSchema.nullable().default(null),
 });
 /** What the AI must return. Subset of the artifact; cerber owns the rest. */
 export const AiReviewSchema = z.object({
@@ -133,6 +195,11 @@ export const AiReviewSchema = z.object({
     })),
     verdict: VerdictSchema,
 });
+/** What a chat turn must return: something to say, and what it changed. */
+export const AiChatTurnSchema = z.object({
+    reply: z.string(),
+    revisions: z.array(RevisionSchema).default([]),
+});
 export function artifactId(pr) {
     return `${pr.owner}/${pr.repo}#${pr.number}`;
 }

package/dist/core/revise.js

@@ -0,0 +1,166 @@
+import { randomUUID } from "node:crypto";
+/** The review as it stands, for restoring later. */
+export function snapshotReview(artifact, at) {
+    return {
+        at,
+        summary: artifact.summary,
+        chapters: artifact.chapters,
+        comments: artifact.comments,
+        verdict: artifact.verdict,
+    };
+}
+/** Put a review back the way the snapshot found it. Chat history is untouched. */
+export function restoreReview(artifact, snapshot) {
+    return {
+        ...artifact,
+        summary: snapshot.summary,
+        chapters: snapshot.chapters,
+        comments: snapshot.comments,
+        verdict: snapshot.verdict,
+    };
+}
+/**
+ * Fold a finished chat turn back onto whatever the artifact says now.
+ *
+ * A turn takes minutes, and the cockpit stays live throughout: the user can
+ * edit, drop or add a comment while waiting for the answer. Writing the turn's
+ * result wholesale would silently undo that, which is the one thing a run must
+ * never do to the user's own work.
+ *
+ * `before` is the artifact the turn started from, `after` is what it produced,
+ * `current` is what is on disk now. Anything the user changed between `before`
+ * and `current` wins; everything else comes from the turn.
+ */
+export function mergeConcurrentEdits(before, after, current) {
+    const wasThere = new Map(before.comments.map((c) => [c.id, c]));
+    const fromTurn = new Map(after.comments.map((c) => [c.id, c]));
+    const userTouched = (id, now) => {
+        const then = wasThere.get(id);
+        // Absent from `before` means the user added it while the turn ran.
+        if (!then)
+            return true;
+        return then.body !== now.body || then.status !== now.status;
+    };
+    const merged = current.comments.map((now) => userTouched(now.id, now) ? now : fromTurn.get(now.id) ?? now);
+    // Comments the turn itself added are not in `current` yet. Only those: a
+    // comment present in both `before` and `after` but missing from `current` is
+    // one the user deleted while the turn ran, and pushing it back would undo
+    // the deletion — the very thing this function exists to prevent. (Delete
+    // removes the row outright; drop only marks it, so drops survive above.)
+    const seen = new Set(merged.map((c) => c.id));
+    for (const c of after.comments) {
+        if (!wasThere.has(c.id) && !seen.has(c.id))
+            merged.push(c);
+    }
+    return {
+        ...after,
+        comments: merged,
+        // The turn never sets a queue status, so a "mark reviewed" clicked while it
+        // ran is the user's and stands. The verdict it can change, so the turn wins
+        // there only when it actually revised one.
+        status: current.status,
+        verdict: after.verdict === before.verdict ? current.verdict : after.verdict,
+    };
+}
+export function applyRevisions(artifact, revisions, opts = {}) {
+    const newId = opts.newId ?? randomUUID;
+    const applied = [];
+    const refused = [];
+    let next = artifact;
+    const refuse = (revision, reason) => refused.push({ revision, reason });
+    /** A comment the user authored or rewrote is theirs, not the run's to redo. */
+    const isUsers = (id) => {
+        const c = next.comments.find((x) => x.id === id);
+        return c ? c.origin === "user" || c.editedByUser : false;
+    };
+    for (const revision of revisions) {
+        switch (revision.kind) {
+            case "summary": {
+                next = { ...next, summary: revision.body };
+                applied.push(revision);
+                break;
+            }
+            case "verdict": {
+                next = { ...next, verdict: revision.verdict };
+                applied.push(revision);
+                break;
+            }
+            case "chapter": {
+                const chapter = next.chapters.find((ch) => ch.id === revision.chapterId);
+                if (!chapter) {
+                    refuse(revision, `no chapter "${revision.chapterId}" in this review`);
+                    break;
+                }
+                next = {
+                    ...next,
+                    chapters: next.chapters.map((ch) => ch.id === revision.chapterId
+                        ? {
+                            ...ch,
+                            title: revision.title ?? ch.title,
+                            explanation: revision.explanation ?? ch.explanation,
+                        }
+                        : ch),
+                };
+                applied.push(revision);
+                break;
+            }
+            case "comment-edit": {
+                if (!next.comments.some((c) => c.id === revision.commentId)) {
+                    refuse(revision, `no comment ${revision.commentId} in this review`);
+                    break;
+                }
+                if (isUsers(revision.commentId) && !opts.allowUserComments) {
+                    refuse(revision, "that comment is the user's own writing — ask before rewriting it");
+                    break;
+                }
+                next = {
+                    ...next,
+                    comments: next.comments.map((c) => c.id === revision.commentId ? { ...c, body: revision.body } : c),
+                };
+                applied.push(revision);
+                break;
+            }
+            case "comment-drop": {
+                if (!next.comments.some((c) => c.id === revision.commentId)) {
+                    refuse(revision, `no comment ${revision.commentId} in this review`);
+                    break;
+                }
+                if (isUsers(revision.commentId) && !opts.allowUserComments) {
+                    refuse(revision, "that comment is the user's own writing — ask before dropping it");
+                    break;
+                }
+                // Dropped, not deleted: `status` is what Send already reads, and the
+                // cockpit shows a dropped comment struck through rather than vanished.
+                next = {
+                    ...next,
+                    comments: next.comments.map((c) => c.id === revision.commentId ? { ...c, status: "dropped" } : c),
+                };
+                applied.push(revision);
+                break;
+            }
+            case "comment-add": {
+                next = {
+                    ...next,
+                    comments: [
+                        ...next.comments,
+                        {
+                            id: newId(),
+                            path: revision.path,
+                            line: revision.line,
+                            body: revision.body,
+                            chapterId: revision.chapterId,
+                            origin: "ai",
+                            status: "draft",
+                            editedByUser: false,
+                            originalLine: null,
+                            drifted: false,
+                        },
+                    ],
+                };
+                applied.push(revision);
+                break;
+            }
+        }
+    }
+    return { artifact: next, applied, refused };
+}

package/dist/runner/chat.js

@@ -0,0 +1,215 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { AiChatTurnSchema, } from "../core/artifact.js";
+import { createRunDir, prepareCheckout, removeRunDir, sourceDir } from "../core/checkout.js";
+import { applyRevisions, snapshotReview } from "../core/revise.js";
+import { extractJson, runClaude, unauthenticatedEnv } from "./claude.js";
+import { beginReview, endReview } from "./inflight.js";
+import { buildChatPrompt } from "./prompt.js";
+/**
+ * One turn of a conversation about a drafted review.
+ *
+ * The turn resumes the review's own Claude session where it can, so the model
+ * answering "did you actually check that?" is the one that did or didn't. The
+ * agent revises the draft directly — no accept step — because the user asked
+ * for the change and asking again would be friction wearing safety's coat.
+ *
+ * Everything a review run is denied, a chat turn is denied identically: it has
+ * no GitHub credentials, treats the checkout as untrusted content, and never
+ * gets Edit or Write. It is one step from the only path that writes to GitHub,
+ * so the isolation is the same isolation.
+ */
+/** All an untrusted turn needs from a checkout — everything else stays off. */
+const READ_TOOLS = ["Read", "Grep", "Glob"];
+const OFF_TOOLS = ["Bash", "Edit", "Write", "NotebookEdit", "Task", "WebFetch", "WebSearch"];
+const TRUSTED_TOOLS = [...READ_TOOLS, "Bash", "WebFetch", "WebSearch"];
+const TRUSTED_OFF_TOOLS = ["Edit", "Write", "NotebookEdit"];
+/**
+ * Put the reviewed source back under the chat turn, or say plainly that we
+ * could not.
+ *
+ * The checkout cache is small and evicts by least-recent use, so by the time
+ * someone argues with a review its source is often already gone. That matters
+ * more here than anywhere else: the turn resumes a session whose transcript
+ * still describes files it read, and Claude sessions are keyed by working
+ * directory. Resuming into a deleted one leaves a model that believes it can
+ * open the file and will otherwise describe it from memory.
+ *
+ * `prepareCheckout` is idempotent and restores the same deterministic path, so
+ * re-cloning is enough to make resume whole again. It also touches the
+ * directory, which is what keeps a checkout alive through a long conversation:
+ * eviction is by mtime, so every turn renews it.
+ */
+export async function ensureChatSource(artifact, opts = {}) {
+    const log = opts.log ?? (() => { });
+    const prepare = opts.prepare ?? prepareCheckout;
+    // A review that never had a checkout has nothing to restore, and re-cloning
+    // now would give the conversation context the review itself never had.
+    if (!artifact.run?.withSource)
+        return { dir: null, sha: null, recloned: false };
+    const ref = {
+        owner: artifact.pr.owner,
+        repo: artifact.pr.repo,
+        number: artifact.pr.number,
+    };
+    const existed = await isCheckedOut(sourceDir(ref));
+    try {
+        // The same trust the review ran under: a checkout prepared as trusted keeps
+        // the PR's own CLAUDE.md in place, and re-preparing with the wrong flag
+        // would either un-quarantine it or quarantine what the review could read.
+        const checkout = await prepare(ref, { log, trusted: artifact.run.trusted });
+        if (!existed)
+            log("The checkout had been evicted — re-cloned it so this turn can read the code.");
+        return { dir: checkout.dir, sha: checkout.sha, recloned: !existed };
+    }
+    catch (err) {
+        log(`Could not restore the source (${err instanceof Error ? err.message : err}) — ` +
+            `this turn works from the review, the diff and the conversation alone.`);
+        return { dir: null, sha: null, recloned: false };
+    }
+}
+async function isCheckedOut(dir) {
+    return fs
+        .stat(dir)
+        .then((s) => s.isDirectory())
+        .catch(() => false);
+}
+/**
+ * Append the user's message and the reviewer's answer, applying whatever the
+ * answer revised. Claims the artifact's inflight slot for the duration: the
+ * daemon's timer and the cockpit's re-review button write the same file.
+ */
+export async function runChatTurn(artifact, message, opts = {}) {
+    beginReview(artifact.id);
+    try {
+        return await turn(artifact, message, opts);
+    }
+    finally {
+        endReview(artifact.id);
+    }
+}
+async function turn(artifact, message, opts) {
+    const now = opts.now ?? (() => new Date().toISOString());
+    const newId = opts.newId ?? randomUUID;
+    const run = opts.run ?? runClaude;
+    const log = opts.onProgress ?? (() => { });
+    // Restore the checkout unless the caller already resolved one (or asked for
+    // none). Doing it here, rather than making the cockpit remember, is what
+    // stops "the cache evicted it" from silently degrading every later turn.
+    const resolved = opts.source === undefined
+        ? await ensureChatSource(artifact, { log })
+        : { dir: opts.source, sha: opts.sourceSha ?? null, recloned: false };
+    const source = resolved.dir;
+    const trusted = (opts.trusted ?? artifact.run?.trusted ?? false) && source !== null;
+    // A re-cloned checkout follows the PR, not the review: if the author pushed
+    // since, the files under the model are newer than the draft it is defending.
+    const moved = source !== null && resolved.sha !== null && artifact.pr.headSha !== "" && resolved.sha !== artifact.pr.headSha
+        ? `Note: the review was written against ${artifact.pr.headSha.slice(0, 7)}, but the checkout is now at ${resolved.sha.slice(0, 7)} — the author has pushed since. Code you read may not be the code the review is about; say so when it matters.`
+        : undefined;
+    if (moved)
+        log(moved);
+    // The session is only worth resuming into the directory it was created in.
+    // Without the checkout the transcript survives but Read and Grep do not, and
+    // a model that thinks it can still open the file will describe code from
+    // memory — worse than one that knows it is working blind.
+    const resumeSessionId = source && artifact.run?.sessionId ? artifact.run.sessionId : undefined;
+    if (artifact.run?.sessionId && !source) {
+        log("The checkout is gone — this turn works from the review, the diff and the conversation.");
+    }
+    const { prompt } = buildChatPrompt(artifact, message, {
+        refs: opts.refs,
+        source: source !== null,
+        trusted,
+        resumed: Boolean(resumeSessionId),
+        sourceNote: moved,
+    });
+    const empty = await createRunDir();
+    const claudeOpts = {
+        model: opts.model,
+        cwd: source ?? empty,
+        env: unauthenticatedEnv(process.env, empty),
+        allowedTools: source ? (trusted ? TRUSTED_TOOLS : READ_TOOLS) : undefined,
+        disallowedTools: source
+            ? trusted
+                ? TRUSTED_OFF_TOOLS
+                : OFF_TOOLS
+            : [...OFF_TOOLS, ...READ_TOOLS],
+        isolateWorkspace: !(source && trusted),
+        resumeSessionId,
+    };
+    let reply;
+    let costUsd;
+    let sessionId;
+    try {
+        const first = await run(prompt, claudeOpts);
+        try {
+            reply = AiChatTurnSchema.parse(extractJson(first.text));
+            costUsd = first.costUsd;
+            sessionId = first.sessionId;
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            log("Model output failed validation — retrying once…");
+            // Resume the turn we just had rather than the review: the retry is about
+            // the JSON shape, and re-sending the whole prompt would say it all twice.
+            const second = await run(retryPrompt(first.text, detail), {
+                ...claudeOpts,
+                resumeSessionId: first.sessionId ?? resumeSessionId,
+            });
+            reply = AiChatTurnSchema.parse(extractJson(second.text));
+            const total = (first.costUsd ?? 0) + (second.costUsd ?? 0);
+            costUsd = total > 0 ? total : null;
+            sessionId = second.sessionId ?? first.sessionId;
+        }
+    }
+    finally {
+        await removeRunDir(empty);
+    }
+    // The first turn snapshots the review, so "reset" always has somewhere to go
+    // back to. Later turns leave that snapshot alone: it is the pre-chat draft,
+    // not the previous turn's.
+    const at = now();
+    const preChat = artifact.preChat ?? snapshotReview(artifact, at);
+    const userTurn = {
+        id: newId(),
+        role: "user",
+        at,
+        body: message,
+        refs: opts.refs ?? [],
+        revisions: [],
+        refused: [],
+        costUsd: null,
+    };
+    const revised = applyRevisions(artifact, reply.revisions, {
+        newId,
+        allowUserComments: opts.allowUserComments,
+    });
+    const assistantTurn = {
+        id: newId(),
+        role: "assistant",
+        at: now(),
+        body: reply.reply,
+        refs: [],
+        revisions: revised.applied,
+        refused: revised.refused,
+        costUsd,
+    };
+    return {
+        artifact: {
+            ...revised.artifact,
+            updatedAt: assistantTurn.at,
+            preChat,
+            chat: [...artifact.chat, userTurn, assistantTurn],
+            run: artifact.run ? { ...artifact.run, sessionId: sessionId ?? artifact.run.sessionId } : null,
+        },
+        applied: revised.applied,
+        refused: revised.refused,
+    };
+}
+function retryPrompt(badOutput, error) {
+    return `Your previous response could not be parsed as the required JSON.
+Error: ${error}
+Previous response (truncated): ${badOutput.slice(0, 2_000)}
+
+Respond again with ONLY the valid JSON object described earlier: an object with "reply" and "revisions".`;
+}

package/dist/runner/claude.js

@@ -40,6 +40,8 @@ export const DEFAULT_TIMEOUT_MS = 30 * 60_000;
 const SIGKILL_GRACE_MS = 5_000;
 export function buildClaudeArgs(opts) {
     const args = ["-p", "--output-format", "json"];
+    if (opts.resumeSessionId)
+        args.push("--resume", opts.resumeSessionId);
     if (opts.model)
         args.push("--model", opts.model);
     if (opts.allowedTools?.length)
@@ -107,6 +109,7 @@ export function runClaude(prompt, opts = {}) {
                     text: wrapper.result ?? "",
                     costUsd: typeof wrapper.total_cost_usd === "number" ? wrapper.total_cost_usd : null,
                     model: wrapper.modelUsage ? Object.keys(wrapper.modelUsage)[0] ?? null : null,
+                    sessionId: typeof wrapper.session_id === "string" ? wrapper.session_id : null,
                 });
             }
             catch {

package/dist/runner/prompt.js

@@ -93,6 +93,138 @@ ${diffBody}
 `;
     return { prompt, truncated };
 }
+/** Human names for what the user pointed at, so the model can find it. */
+function describeRefs(artifact, refs) {
+    if (refs.length === 0)
+        return "";
+    const lines = refs.map((ref) => {
+        if (ref.target === "summary")
+            return "- the summary";
+        if (ref.target === "verdict")
+            return "- the verdict";
+        if (ref.target === "chapter") {
+            const ch = artifact.chapters.find((c) => c.id === ref.id);
+            return `- the chapter "${ch?.title ?? ref.id}" (chapterId: ${ref.id})`;
+        }
+        const c = artifact.comments.find((x) => x.id === ref.id);
+        return c
+            ? `- the comment on ${c.path}:${c.line ?? "file"} (commentId: ${c.id})`
+            : `- comment ${ref.id}`;
+    });
+    return `\n## What the user is pointing at\n\n${lines.join("\n")}\n`;
+}
+/** The review as it stands right now, with the ids a revision has to name. */
+function renderReview(artifact) {
+    const chapters = artifact.chapters
+        .map((ch) => `- ${ch.id} — ${ch.title}\n  ${ch.explanation}`)
+        .join("\n");
+    const comments = artifact.comments
+        .map((c) => {
+        const mine = c.origin === "user" || c.editedByUser ? " [THE USER'S OWN WRITING]" : "";
+        const dropped = c.status === "dropped" ? " [dropped]" : "";
+        return `- ${c.id} — ${c.path}:${c.line ?? "file-level"}${mine}${dropped}\n  ${c.body}`;
+    })
+        .join("\n");
+    const verdict = artifact.verdict
+        ? `${artifact.verdict.recommendation} (confidence ${artifact.verdict.confidence})\n${artifact.verdict.reasoning}`
+        : "(none)";
+    return `## The review as it stands
+
+### Summary
+
+${artifact.summary || "(empty)"}
+
+### Chapters
+
+${chapters || "(none)"}
+
+### Comments
+
+${comments || "(none)"}
+
+### Verdict
+
+${verdict}
+`;
+}
+function renderTranscript(chat) {
+    if (chat.length === 0)
+        return "";
+    const turns = chat
+        .map((t) => `${t.role === "user" ? "User" : "You"}: ${t.body}`)
+        .join("\n\n");
+    return `\n## The conversation so far\n\n${turns}\n`;
+}
+/**
+ * The prompt for one turn of a conversation about a drafted review.
+ *
+ * The point of this over a one-shot "redo it" is that the turn resumes the
+ * review's own session, so the model can answer *why* it said something rather
+ * than re-deriving an opinion. When resume is unavailable the transcript and
+ * the review come along anyway, and the model is told it is arriving cold —
+ * confidently citing a file it cannot open is the failure mode to avoid.
+ */
+export function buildChatPrompt(artifact, message, opts = {}) {
+    const needsDiff = !opts.resumed;
+    const truncated = needsDiff && artifact.diff.length > MAX_DIFF_CHARS;
+    const diffSection = needsDiff
+        ? `\n## Diff\n\n\`\`\`diff\n${truncated ? artifact.diff.slice(0, MAX_DIFF_CHARS) + "\n[... diff truncated ...]" : artifact.diff}\n\`\`\`\n`
+        : "";
+    const note = opts.sourceNote ? `\n${opts.sourceNote}\n` : "";
+    const sourceSection = opts.source
+        ? (opts.trusted ? TRUSTED_SECTION : SOURCE_SECTION) + note + "\n"
+        : `## No source checkout
+
+The repository is NOT available to you. Every tool is off. Answer from the diff, the review, and this conversation — and when the honest answer is "I would have to look at the file to be sure", say that rather than describing code you cannot open.
+`;
+    const cold = opts.resumed
+        ? ""
+        : `\nYou are picking this review up cold: it was written in an earlier session you no longer hold. Everything you know about it is below. Do not claim to remember reading something — if the review asserts a thing you cannot now confirm, say so.\n`;
+    const prompt = `You are the code reviewer who wrote the review below, talking to the user who is about to send it.
+
+They are not asking you to re-review the PR. They are questioning the draft you produced. Answer them honestly — defend what you actually checked, concede what you did not, and revise the review where they are right.
+
+Respond with ONLY a JSON object (no markdown fences, no prose before or after) matching exactly this shape:
+
+{
+  "reply": "markdown — what you say back to the user. Plain, direct, 1-3 short paragraphs.",
+  "revisions": [
+    { "kind": "summary", "body": "the rewritten summary" },
+    { "kind": "verdict", "verdict": { "recommendation": "approve" | "comment" | "request_changes", "confidence": 0-100, "reasoning": "..." } },
+    { "kind": "chapter", "chapterId": "...", "title": "optional new title", "explanation": "optional new explanation" },
+    { "kind": "comment-edit", "commentId": "...", "body": "the rewritten comment" },
+    { "kind": "comment-drop", "commentId": "..." },
+    { "kind": "comment-add", "path": "path/to/file.ts", "line": 42, "body": "...", "chapterId": "..." }
+  ]
+}
+
+Rules:
+- Revise when the user is right, and only then. "revisions" is usually empty or has one entry; an empty array with a reply that explains your reasoning is a perfectly good turn.
+- Do NOT revise merely to seem agreeable. If you checked something and the user is wrong about it, say so and change nothing. A reviewer that folds under every push-back is worthless.
+- Never revise something the user did not raise. Fix what they pointed at, not everything you would now write differently.
+- Comments marked [THE USER'S OWN WRITING] are theirs. Do not edit or drop them. If one of them is what needs changing, say so in your reply and let them do it.
+- Every "commentId" and "chapterId" must be one listed below. Never invent one.
+- "line" is a line in the NEW version of the file and must appear in the diff. Use null for a file-level comment.
+- Your reply is prose to a person, not a changelog. The cockpit already shows what you changed — do not list your own edits back to them.
+
+Writing style:
+- Plain words, short sentences, no jargon. Someone who has NOT read the diff should follow you.
+- Lead with the point. State the claim first, support it after.
+- Do NOT imitate the PR description's writing style, and do not restate the author's claims as your own findings. If the description asserts something, it is a claim to check, not a fact to repeat.
+${cold}
+${sourceSection}## Pull request
+
+Repo: ${artifact.pr.owner}/${artifact.pr.repo}
+PR #${artifact.pr.number}: ${artifact.pr.title}
+Author: ${artifact.pr.author}
+
+${renderReview(artifact)}${describeRefs(artifact, opts.refs ?? [])}${renderTranscript(artifact.chat)}${diffSection}
+## The user's message
+
+${message}
+`;
+    return { prompt, truncated };
+}
 export function buildRetryPrompt(originalPrompt, badOutput, error) {
     return `${originalPrompt}