@fullstackhouse/cerber 0.9.1 → 0.10.1

package/dist/runner/claude.js

@@ -39,7 +39,12 @@ export const DEFAULT_TIMEOUT_MS = 30 * 60_000;
 /** How long a killed run gets to exit on its own before SIGKILL. */
 const SIGKILL_GRACE_MS = 5_000;
 export function buildClaudeArgs(opts) {
-    const args = ["-p", "--output-format", "json"];
+    // stream-json, not json: the same final result arrives in the closing event,
+    // and everything before it is the run saying what it is doing. `--verbose` is
+    // not optional — the CLI refuses the combination without it.
+    const args = ["-p", "--output-format", "stream-json", "--verbose"];
+    if (opts.resumeSessionId)
+        args.push("--resume", opts.resumeSessionId);
     if (opts.model)
         args.push("--model", opts.model);
     if (opts.allowedTools?.length)
@@ -51,9 +56,39 @@ export function buildClaudeArgs(opts) {
     }
     return args;
 }
+/**
+ * Split a stream-json stdout chunk into whole events, keeping whatever trailing
+ * fragment has not been terminated yet. A tool result can be megabytes, so a
+ * single event routinely arrives across several chunks.
+ */
+export function readEvents(buffer) {
+    const lines = buffer.split("\n");
+    // The last piece has no newline after it — it may be half an event.
+    const rest = lines.pop() ?? "";
+    const events = [];
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && typeof parsed.type === "string") {
+                events.push(parsed);
+            }
+        }
+        catch {
+            // A line we can't parse is a line we don't need — the run's own result
+            // comes from the closing event, and dying here would throw away a
+            // finished review over a stray byte.
+        }
+    }
+    return { events, rest };
+}
 /**
  * Run `claude -p` headless with the prompt on stdin, return the result text.
  * Rides the user's existing Claude Code login — no API key handling here.
+ *
+ * Reads the run as a stream so {@link ClaudeOptions.onEvent} can report what it
+ * is doing while it does it; the result itself is the closing event.
  */
 export function runClaude(prompt, opts = {}) {
     const args = buildClaudeArgs(opts);
@@ -63,7 +98,10 @@ export function runClaude(prompt, opts = {}) {
             cwd: opts.cwd,
             env: opts.env,
         });
-        let stdout = "";
+        let unread = "";
+        let result = null;
+        /** Kept only to explain a failure — the events carry everything we use. */
+        let tail = "";
         let stderr = "";
         const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         let settled = false;
@@ -87,7 +125,26 @@ export function runClaude(prompt, opts = {}) {
             child.stdin.destroy();
             settle(() => reject(new Error(`claude did not finish within ${Math.round(timeoutMs / 60_000)} minutes — run killed.`)));
         }, timeoutMs);
-        child.stdout.on("data", (d) => (stdout += d));
+        const ingest = (chunk) => {
+            const read = readEvents(unread + chunk);
+            unread = read.rest;
+            for (const event of read.events) {
+                if (event.type === "result")
+                    result = event;
+                // A throwing listener must not take the run down with it: the answer is
+                // the point, the narration is not.
+                try {
+                    opts.onEvent?.(event);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        };
+        child.stdout.on("data", (d) => {
+            tail = (tail + d).slice(-2_000);
+            ingest(String(d));
+        });
         child.stderr.on("data", (d) => (stderr += d));
         child.on("error", (err) => {
             settle(() => reject(new Error(`Failed to start claude CLI: ${err.message}. Is Claude Code installed and on PATH?`)));
@@ -98,20 +155,24 @@ export function runClaude(prompt, opts = {}) {
             clearTimeout(timer);
             settled = true;
             if (code !== 0) {
-                reject(new Error(`claude exited with code ${code}: ${stderr.trim() || stdout.slice(0, 500)}`));
+                reject(new Error(`claude exited with code ${code}: ${stderr.trim() || tail.slice(-500)}`));
                 return;
             }
-            try {
-                const wrapper = JSON.parse(stdout);
-                resolve({
-                    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,
-                });
-            }
-            catch {
-                reject(new Error(`Could not parse claude output as JSON wrapper: ${stdout.slice(0, 500)}`));
+            // The last line need not be newline-terminated, and it is the one that
+            // matters: dropping it would throw away a finished review for the want
+            // of a trailing byte.
+            ingest("\n");
+            const wrapper = result;
+            if (!wrapper) {
+                reject(new Error(`claude produced no result event: ${tail.slice(-500)}`));
+                return;
             }
+            resolve({
+                text: typeof wrapper.result === "string" ? 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,
+            });
         });
         child.stdin.write(prompt);
         child.stdin.end();

package/dist/runner/progress.js

@@ -0,0 +1,88 @@
+/**
+ * Turning a run's own events into a line a human can read while they wait.
+ *
+ * A review or a chat turn takes minutes, and until now the only honest thing
+ * cerber could say about that time was "thinking…". The run already narrates
+ * itself — what it is about to read, what it concluded, what it was refused —
+ * so this says that instead, in the same plain words the review itself uses:
+ * what happened, not the wire format it happened in.
+ *
+ * Ignoring is the default. An event we don't recognise, and anything that would
+ * leak the machinery (the JSON answer, tool results, session bookkeeping),
+ * returns null and never reaches the user.
+ *
+ * Pure: no I/O, no clock.
+ */
+/** How much of any one line survives. Long enough to be useful in a sidebar. */
+const MAX = 180;
+export function describeEvent(event) {
+    if (event.type === "assistant") {
+        return (event.message?.content ?? []).flatMap((block) => {
+            if (block.type === "thinking")
+                return ["thinking…"];
+            if (block.type === "text") {
+                const text = (block.text ?? "").trim();
+                // The turn's answer is a JSON object; showing it raw would put the
+                // machinery on screen a second before the rendered version lands.
+                if (!text || looksLikeJson(text))
+                    return [];
+                return [clip(collapse(text))];
+            }
+            if (block.type === "tool_use")
+                return [describeTool(block.name ?? "", block.input ?? {})];
+            return [];
+        });
+    }
+    // Cerber denies most tools on purpose. When the run reaches for one anyway,
+    // saying so beats a silent gap in the story.
+    if (event.type === "system" && event.subtype === "permission_denied") {
+        const tool = typeof event.tool_name === "string" ? event.tool_name : "a tool";
+        return [`not allowed to use ${tool}`];
+    }
+    return [];
+}
+function describeTool(name, input) {
+    const str = (key) => (typeof input[key] === "string" ? input[key] : "");
+    switch (name) {
+        case "Read": {
+            const file = short(str("file_path"));
+            return file ? `reading ${file}` : "reading a file";
+        }
+        case "Grep": {
+            const where = short(str("path"));
+            return clip(`searching for ${str("pattern")}${where ? ` in ${where}` : ""}`);
+        }
+        case "Glob":
+            return clip(`looking for files matching ${str("pattern")}`);
+        case "Bash": {
+            // The description is the model's own words for what it is about to run;
+            // the command is what it will actually do. The command is the honest one.
+            const command = collapse(str("command"));
+            return command ? clip(`running ${command}`) : "running a command";
+        }
+        case "WebSearch":
+            return clip(`searching the web for ${str("query")}`);
+        case "WebFetch":
+            return clip(`fetching ${str("url")}`);
+        case "TodoWrite":
+            return "planning the rest of the turn";
+        default:
+            return name ? `using ${name}` : "using a tool";
+    }
+}
+/** Paths in a checkout are absolute and long; the repo-relative tail is the useful part. */
+function short(file) {
+    if (!file)
+        return "";
+    const parts = file.split("/").filter(Boolean);
+    return parts.length > 3 ? parts.slice(-3).join("/") : file;
+}
+function looksLikeJson(text) {
+    return text.startsWith("{") || text.startsWith("```");
+}
+function collapse(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function clip(text) {
+    return text.length > MAX ? `${text.slice(0, MAX - 1)}…` : text;
+}

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}
 

package/dist/runner/review.js

@@ -7,6 +7,7 @@ import { loadArtifact, saveArtifact } from "../core/state.js";
 import { loadConfig } from "../core/config.js";
 import { decideTrust, membershipQueries, parseTrustRules } from "../core/trust.js";
 import { extractJson, runClaude, unauthenticatedEnv } from "./claude.js";
+import { describeEvent } from "./progress.js";
 import { beginReview, endReview, isReviewRunning } from "./inflight.js";
 import { buildReviewPrompt, buildRetryPrompt } from "./prompt.js";
 /** All an untrusted reviewer needs from a checkout — everything else stays off. */
@@ -121,10 +122,18 @@ async function runReview(ref, opts) {
             error: null,
             withSource: source !== null,
             trusted: trusted && source !== null,
+            sessionId: null,
         },
         sent: null,
         refresh: null,
         calibration: null,
+        // The conversation is the user's writing, so a re-review keeps it — the
+        // chat prompt replays the transcript, which is what makes it survive the
+        // session change. The snapshot does NOT carry over: it describes the draft
+        // this run just replaced, and resetting to it would restore a dead review.
+        chat: existing?.chat ?? [],
+        preChat: null,
+        pendingChat: null,
     };
     await saveArtifact(artifact);
     const { prompt, truncated } = buildReviewPrompt(pr, diff, { source: source !== null, trusted });
@@ -170,6 +179,9 @@ async function runReview(ref, opts) {
                 error: null,
                 withSource: source !== null,
                 trusted: trusted && source !== null,
+                // Only worth keeping when there is a checkout to resume into: a session
+                // whose working directory was empty has nothing a chat turn could read.
+                sessionId: source ? review.sessionId : null,
             },
         };
         // A re-review regenerates the AI's comments, but the human's own comments
@@ -221,6 +233,9 @@ async function runAiReview(prompt, opts, source, trusted) {
     const empty = await createRunDir();
     const claudeOpts = {
         model: opts.model,
+        // Say what the review is doing while it does it, rather than going quiet
+        // for minutes. `cerber review` and the daemon log print these.
+        onEvent: (event) => opts.onProgress && describeEvent(event).forEach(opts.onProgress),
         cwd: source ?? empty,
         env: unauthenticatedEnv(process.env, empty),
         allowedTools: source ? (trusted ? TRUSTED_TOOLS : READ_TOOLS) : undefined,
@@ -236,17 +251,25 @@ async function runAiReview(prompt, opts, source, trusted) {
     try {
         const first = await runClaude(prompt, claudeOpts);
         try {
-            return { ai: AiReviewSchema.parse(extractJson(first.text)), costUsd: first.costUsd, model: first.model };
+            return {
+                ai: AiReviewSchema.parse(extractJson(first.text)),
+                costUsd: first.costUsd,
+                model: first.model,
+                sessionId: first.sessionId,
+            };
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             opts.onProgress?.("Model output failed validation — retrying once…");
+            // A fresh run, not a resume: the retry prompt already carries the whole
+            // original prompt, so resuming would send the diff twice.
             const second = await runClaude(buildRetryPrompt(prompt, first.text, message), claudeOpts);
             const cost = (first.costUsd ?? 0) + (second.costUsd ?? 0);
             return {
                 ai: AiReviewSchema.parse(extractJson(second.text)),
                 costUsd: cost > 0 ? cost : null,
                 model: second.model,
+                sessionId: second.sessionId ?? first.sessionId,
             };
         }
     }

package/dist/server/daemon.js

@@ -43,6 +43,9 @@ export function stubArtifact(ref) {
         sent: null,
         refresh: null,
         calibration: null,
+        chat: [],
+        preChat: null,
+        pendingChat: null,
     };
 }
 /** An artifact nothing has touched yet — safe to delete when its PR leaves the queue. */

package/dist/server/index.js

@@ -17,6 +17,10 @@ import { buildReviewPayload, computeCalibration } from "../core/send.js";
 import { listArtifacts, loadArtifactByKey, reconcileRunning, updateArtifactByKey, } from "../core/state.js";
 import { isReviewRunning } from "../runner/inflight.js";
 import { reviewPr } from "../runner/review.js";
+import { runChatTurn } from "../runner/chat.js";
+import { mergeConcurrentEdits, restoreReview } from "../core/revise.js";
+import { progressWriter } from "./progress.js";
+import { ChatTurnSchema } from "../core/artifact.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export async function buildApp(opts) {
     const app = new Hono();
@@ -294,6 +298,7 @@ export async function buildApp(opts) {
                 error: null,
                 withSource: withSource !== false,
                 trusted: false,
+                sessionId: null,
             },
         }));
         // Minutes-long: run it detached and let the cockpit poll the artifact.
@@ -315,6 +320,121 @@ export async function buildApp(opts) {
         });
         return c.json(running, 202);
     });
+    // ---- Chat: argue with the review before sending it ----
+    // Local only. The transcript never reaches GitHub — Send still builds its
+    // payload from the summary, comments and verdict alone.
+    const ChatRequestSchema = z.object({
+        message: z.string().min(1),
+        refs: ChatTurnSchema.shape.refs.optional(),
+        /** The user said, in so many words, that the run may touch their comments. */
+        allowUserComments: z.boolean().optional(),
+    });
+    const turnInFlight = (a) => a.pendingChat != null && a.pendingChat.error == null;
+    app.post("/api/reviews/:key/chat", async (c) => {
+        const key = c.req.param("key");
+        const artifact = await loadArtifactByKey(key);
+        if (!artifact)
+            return c.json({ error: "not found" }, 404);
+        // A sent review is a record of what was posted — arguing with it now would
+        // rewrite history that GitHub already has.
+        if (artifact.sent)
+            return c.json({ error: `already sent at ${artifact.sent.at}` }, 409);
+        if (isReviewRunning(artifact.id) || turnInFlight(artifact)) {
+            return c.json({ error: "a run for this PR is already in flight" }, 409);
+        }
+        let request;
+        try {
+            request = ChatRequestSchema.parse(await c.req.json());
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
+        }
+        // Record the question before responding, so the cockpit's next poll — and a
+        // reload mid-turn — finds a turn being answered rather than a message that
+        // went nowhere.
+        const pending = await updateArtifactByKey(key, (a) => ({
+            ...a,
+            pendingChat: {
+                message: request.message,
+                refs: request.refs ?? [],
+                startedAt: new Date().toISOString(),
+                progress: [],
+                error: null,
+            },
+        }));
+        // The turn narrates itself as it reads the code; those lines go onto the
+        // artifact so the cockpit's poll can show them instead of a spinner.
+        const progress = progressWriter(key);
+        // Minutes-long, like a re-review: run it detached and let the cockpit poll.
+        // Holding the request open is fine on localhost and fails behind a reverse
+        // proxy's read timeout, which tells the user it broke while the turn
+        // quietly succeeds — a worse failure than an honest error.
+        void runChatTurn(artifact, request.message, {
+            refs: request.refs,
+            allowUserComments: request.allowUserComments,
+            onProgress: (m) => {
+                console.log(`[chat ${artifact.id}] ${m}`);
+                progress.push(m);
+            },
+        })
+            .then(async (result) => {
+            // Let the narration finish writing first: an append that read the
+            // artifact before this point would otherwise land on top of the answer.
+            await progress.stop();
+            // The cockpit stays live throughout, so fold the result onto whatever
+            // is on disk now rather than overwriting it — an edit the user made
+            // while waiting must not vanish when the answer lands.
+            await updateArtifactByKey(key, (current) => ({
+                ...mergeConcurrentEdits(artifact, result.artifact, current),
+                pendingChat: null,
+            }));
+        })
+            .catch(async (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[chat ${artifact.id}] failed: ${message}`);
+            await progress.stop();
+            // Nobody is holding a response to hand this to any more, so the failure
+            // lives on the artifact against the question that caused it — under
+            // whatever the turn had managed to do before it died.
+            await updateArtifactByKey(key, (a) => ({
+                ...a,
+                pendingChat: a.pendingChat ? { ...a.pendingChat, error: message } : null,
+            })).catch(() => { });
+        });
+        return c.json(pending, 202);
+    });
+    // Clear a turn that failed. Only that: a turn still being answered would come
+    // back on the next write and the cockpit would have lied about dropping it.
+    app.delete("/api/reviews/:key/chat/pending", async (c) => {
+        const key = c.req.param("key");
+        const artifact = await loadArtifactByKey(key);
+        if (!artifact)
+            return c.json({ error: "not found" }, 404);
+        if (turnInFlight(artifact)) {
+            return c.json({ error: "that turn is still being answered" }, 409);
+        }
+        const updated = await updateArtifactByKey(key, (a) => ({ ...a, pendingChat: null }));
+        return c.json(updated);
+    });
+    // Put the review back the way it was before the conversation started. The
+    // conversation itself stays — you lose the edits, not the reasoning.
+    app.post("/api/reviews/:key/chat/reset", async (c) => {
+        const key = c.req.param("key");
+        const artifact = await loadArtifactByKey(key);
+        if (!artifact)
+            return c.json({ error: "not found" }, 404);
+        if (artifact.sent)
+            return c.json({ error: `already sent at ${artifact.sent.at}` }, 409);
+        // A turn in flight will fold its own result on top of whatever is on disk
+        // when it lands, so resetting now would be undone a minute later.
+        if (turnInFlight(artifact)) {
+            return c.json({ error: "a turn is still being answered — wait for it to land" }, 409);
+        }
+        if (!artifact.preChat)
+            return c.json({ error: "this review has not been chatted about" }, 409);
+        const updated = await updateArtifactByKey(key, (a) => a.preChat ? restoreReview(a, a.preChat) : a);
+        return c.json(updated);
+    });
     // ---- Export (local file download) ----
     app.get("/api/reviews/:key/export", async (c) => {
         const artifact = await loadArtifactByKey(c.req.param("key"));
@@ -381,7 +501,7 @@ export async function buildApp(opts) {
 export async function startServer(opts) {
     const cleared = await reconcileRunning();
     if (cleared > 0) {
-        console.log(`Cleared ${cleared} review(s) left mid-run by a previous process — re-review to retry.`);
+        console.log(`Cleared ${cleared} AI run(s) left in flight by a previous process — start them again from the cockpit.`);
     }
     const app = await buildApp(opts);
     serve({ fetch: app.fetch, port: opts.port, hostname: opts.host }, (info) => {

package/dist/server/progress.js

@@ -0,0 +1,72 @@
+import { updateArtifactByKey } from "../core/state.js";
+/**
+ * Putting a running turn's narration where the cockpit can see it.
+ *
+ * The turn is detached, so there is no connection to stream down: the artifact
+ * is the channel, exactly as it is for the pending question itself. That keeps
+ * the story on a reload and behind a proxy, and costs no new transport.
+ *
+ * Two things it must not do. It must not rewrite the whole artifact — diff and
+ * all — once per line, so lines are coalesced into one write every couple of
+ * seconds, which is as often as the cockpit polls anyway. And it must not still
+ * be writing when the turn lands: an append that read the artifact before the
+ * answer was folded in would write back the "still thinking" version on top of
+ * it. `stop()` is awaited before the result is saved, and refuses every append
+ * after that.
+ */
+/** Enough to see what it has been up to, not so much that the panel scrolls away. */
+const KEEP = 30;
+export function progressWriter(key, opts = {}) {
+    const everyMs = opts.everyMs ?? 2_000;
+    const keep = opts.keep ?? KEEP;
+    const update = opts.update ?? updateArtifactByKey;
+    let queued = [];
+    let last = null;
+    let timer = null;
+    let stopped = false;
+    // Writes chain onto each other so two flushes can never interleave their
+    // read-modify-write, and so stop() has something to await.
+    let writes = Promise.resolve();
+    const flush = () => {
+        timer = null;
+        const lines = queued;
+        queued = [];
+        if (!lines.length)
+            return;
+        writes = writes.then(() => update(key, (a) => 
+        // No pending turn means it already landed (or was dismissed) — there is
+        // nothing left for this narration to describe.
+        a.pendingChat
+            ? {
+                ...a,
+                pendingChat: {
+                    ...a.pendingChat,
+                    progress: [...a.pendingChat.progress, ...lines].slice(-keep),
+                },
+            }
+            : a).catch(() => {
+            // A line that never reaches disk is a line the user doesn't see. The
+            // turn itself is unaffected, so it is not worth failing over.
+        }));
+    };
+    return {
+        push(line) {
+            if (stopped || !line || line === last)
+                return;
+            last = line;
+            queued.push(line);
+            if (!timer)
+                timer = setTimeout(flush, everyMs);
+        },
+        async stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            // Flush what's left rather than dropping it: on the failure path the
+            // pending turn survives, and the last thing it did before dying is
+            // exactly what the user wants to see.
+            flush();
+            await writes;
+        },
+    };
+}

package/package.json

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