@fullstackhouse/cerber 0.10.0 → 0.11.0

package/README.md

@@ -8,9 +8,7 @@ verdict with a confidence score. You go through it in a local web cockpit.
 write is the Send button (plus opt-in daemon auto-send you turn on yourself) —
 reviewing is 100% local and read-only.
 
-Named after Cerberus, the gatekeeper — and a sibling of
-[cezar](https://github.com/open-mercato/cezar): cezar runs coding agents,
-cerber guards what gets merged.
+Named after Cerberus, the gatekeeper: cerber guards what gets merged.
 
 ## Quick start
 
@@ -37,9 +35,11 @@ npx @fullstackhouse/cerber serve        # → http://127.0.0.1:4820
 Sending stays a human click. Tame it with `--no-auto-review` (list awaiting
 PRs, review on click) or `--no-poll` (no GitHub polling at all) — or flip the
 same two switches in the cockpit's Settings, which persist in
-`~/.cerber/config.json` and apply on the next poll. Merged and closed PRs are
-archived out of the queue automatically, and PRs in archived repos are never
-picked up at all — the repo is read-only, so a review could never be sent.
+`~/.cerber/config.json` and apply on the next poll. The queue only lists what
+still wants you: anything you have settled drops into a drawer under it — one
+for reviews you sent, one for the ones you marked reviewed or skipped, one for
+merged and closed PRs — and PRs in archived repos are never picked up at all,
+since the repo is read-only and a review could never be sent.
 
 ## What a review looks like
 
@@ -59,6 +59,13 @@ Each review is a plain JSON artifact in `~/.cerber/reviews/` (override with
 The cockpit (`cerber serve`) renders the queue and the per-PR walkthrough with
 diffs. Artifacts are plain JSON you can `cat`, edit, or pipe into anything.
 
+The queue is meant to be walked, not clicked through: `j`/`k` move the cursor
+and the strip under the table explains whatever it lands on — the verdict's own
+reasoning, what the run read, how it sits against the auto-send bar — so most
+rows can be judged without opening them. `↵` opens one, `r` drafts (or
+re-drafts) it. Inside a review, `[` and `]` walk to the previous/next PR still
+awaiting you, `n` steps through the chapters, and `s` sends.
+
 ### It reviews the code, not just the diff
 
 Cerber checks the PR's head out locally and lets the review read it. That
@@ -222,6 +229,17 @@ you already asked for the change. What it changed shows up in the transcript
   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.
+- **The wait is not a held request.** Re-reading the code takes minutes, so a
+  turn runs detached the way a re-review does: your question appears in the
+  transcript straight away and the cockpit polls for the answer. Reload, close
+  the tab, or sit behind a proxy that times connections out at 60s — the answer
+  still lands on the review, and a turn that fails says so against the question
+  that caused it.
+- **You can watch it work.** Those minutes aren't a spinner: the run narrates
+  itself under your question — *thinking…*, *reading src/core/refresh.ts*,
+  *searching for carryOverComments in src*, *not allowed to use Bash* — so you
+  can tell a turn that is checking your claim from one that is about to answer
+  from memory. `cerber review` and the daemon log print the same lines.
 - **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.
@@ -290,4 +308,4 @@ Web cockpit dev with hot reload: `pnpm dev serve` in one terminal,
 
 ## License
 
-MIT © Full Stack House
+MIT © [Full Stack House](https://fullstack.house)

package/dist/core/artifact.js

@@ -144,6 +144,29 @@ export const ChatTurnSchema = z.object({
     refused: z.array(RefusalSchema).default([]),
     costUsd: z.number().nullable().default(null),
 });
+/**
+ * The chat turn being answered right now — or the one that failed.
+ *
+ * A turn takes minutes: the reviewer re-reads the code before it answers. So
+ * the turn runs detached and this is what the cockpit polls. The question is on
+ * the artifact from the moment it is asked, which is what makes a reload
+ * mid-turn show it still being answered rather than a conversation that lost
+ * it, and what carries a failure back to a request that already returned.
+ */
+export const PendingChatSchema = z.object({
+    /** The message being answered — shown in the transcript while we wait. */
+    message: z.string(),
+    refs: ChatTurnSchema.shape.refs,
+    startedAt: z.string(),
+    /**
+     * What the turn has been doing, in its own words — "reading src/core/diff.ts",
+     * "searching for carryOverComments". The answer takes minutes and this is the
+     * only honest account of them; it is thrown away when the answer lands.
+     */
+    progress: z.array(z.string()).default([]),
+    /** Why the turn failed. Null while it is still running. */
+    error: z.string().nullable().default(null),
+});
 /** The parts of a review a chat turn may rewrite — the reset target. */
 export const ReviewSnapshotSchema = z.object({
     at: z.string(),
@@ -175,6 +198,8 @@ export const ArtifactSchema = z.object({
     calibration: CalibrationSchema.nullable().default(null),
     /** The conversation about this review. Never sent to GitHub. */
     chat: z.array(ChatTurnSchema).default([]),
+    /** A turn in flight, or the one that failed. Null when nothing is pending. */
+    pendingChat: PendingChatSchema.nullable().default(null),
     /** The review as it stood before the first chat turn — "reset" restores this. */
     preChat: ReviewSnapshotSchema.nullable().default(null),
 });

package/dist/core/state.js

@@ -92,25 +92,31 @@ export async function updateArtifactByKey(key, mutate) {
     return updated;
 }
 /**
- * Clear "running" statuses left behind by a process that died mid-review.
- * Nothing in a freshly started process is running, so anything still marked
- * running is a leftover — without this it stays wedged forever, with no way to
- * retry it from the cockpit. A `cerber review` running in another terminal is
- * the one false positive; it overwrites the artifact when it finishes anyway.
+ * Clear AI work left in flight by a process that died mid-run — a review marked
+ * "running", or a chat turn still waiting for its answer. Nothing in a freshly
+ * started process is running, so anything still marked so is a leftover; without
+ * this it stays wedged forever, with no way to retry it from the cockpit. A
+ * `cerber review` running in another terminal is the one false positive; it
+ * overwrites the artifact when it finishes anyway.
  */
 export async function reconcileRunning() {
     const artifacts = await listArtifacts();
     let cleared = 0;
     for (const artifact of artifacts) {
-        if (artifact.status !== "running")
+        const stuckRun = artifact.status === "running";
+        const stuckChat = artifact.pendingChat && artifact.pendingChat.error == null ? artifact.pendingChat : null;
+        if (!stuckRun && !stuckChat)
             continue;
         await saveArtifact({
             ...artifact,
-            status: "failed",
+            status: stuckRun ? "failed" : artifact.status,
             updatedAt: new Date().toISOString(),
-            run: artifact.run
+            run: stuckRun && artifact.run
                 ? { ...artifact.run, error: "interrupted — cerber restarted while this review was running" }
-                : null,
+                : artifact.run,
+            pendingChat: stuckChat
+                ? { ...stuckChat, error: "interrupted — cerber restarted while this turn was running" }
+                : artifact.pendingChat,
         });
         cleared++;
     }

package/dist/runner/chat.js

@@ -5,6 +5,7 @@ import { createRunDir, prepareCheckout, removeRunDir, sourceDir } from "../core/
 import { applyRevisions, snapshotReview } from "../core/revise.js";
 import { extractJson, runClaude, unauthenticatedEnv } from "./claude.js";
 import { beginReview, endReview } from "./inflight.js";
+import { describeEvent } from "./progress.js";
 import { buildChatPrompt } from "./prompt.js";
 /**
  * One turn of a conversation about a drafted review.
@@ -126,6 +127,10 @@ async function turn(artifact, message, opts) {
     const empty = await createRunDir();
     const claudeOpts = {
         model: opts.model,
+        // The turn narrates itself while it works. Nothing waits on this — it is
+        // the difference between a minute of spinner and a minute of "reading
+        // src/core/refresh.ts".
+        onEvent: (event) => describeEvent(event).forEach(log),
         cwd: source ?? empty,
         env: unauthenticatedEnv(process.env, empty),
         allowedTools: source ? (trusted ? TRUSTED_TOOLS : READ_TOOLS) : undefined,

package/dist/runner/claude.js

@@ -39,7 +39,10 @@ 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)
@@ -53,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);
@@ -65,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;
@@ -89,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?`)));
@@ -100,21 +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,
-                    sessionId: typeof wrapper.session_id === "string" ? wrapper.session_id : 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/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. */
@@ -132,6 +133,7 @@ async function runReview(ref, opts) {
         // 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 });
@@ -231,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,

package/dist/server/daemon.js

@@ -45,6 +45,7 @@ export function stubArtifact(ref) {
         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

@@ -19,6 +19,7 @@ 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) {
@@ -143,10 +144,19 @@ export async function buildApp(opts) {
                 additions: a.pr.additions,
                 deletions: a.pr.deletions,
                 changedFiles: a.pr.changedFiles,
+                // The queue's cursor row explains itself without opening the review,
+                // so the list carries what that explanation is made of.
+                baseRefName: a.pr.baseRefName,
+                headRefName: a.pr.headRefName,
             },
             verdict: a.verdict,
             commentCount: a.comments.filter((cm) => cm.status !== "dropped").length,
+            driftedCount: a.comments.filter((cm) => cm.status !== "dropped" && cm.drifted).length,
             costUsd: a.run?.costUsd ?? null,
+            withSource: a.run?.withSource ?? null,
+            trusted: a.run?.trusted ?? null,
+            runError: a.run?.error ?? null,
+            sent: a.sent ? { at: a.sent.at, event: a.sent.event, url: a.sent.url, auto: a.sent.auto ?? false } : null,
         })));
     });
     app.get("/api/reviews/:key", async (c) => {
@@ -328,6 +338,7 @@ export async function buildApp(opts) {
         /** 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);
@@ -337,7 +348,7 @@ export async function buildApp(opts) {
         // rewrite history that GitHub already has.
         if (artifact.sent)
             return c.json({ error: `already sent at ${artifact.sent.at}` }, 409);
-        if (isReviewRunning(artifact.id)) {
+        if (isReviewRunning(artifact.id) || turnInFlight(artifact)) {
             return c.json({ error: "a run for this PR is already in flight" }, 409);
         }
         let request;
@@ -347,21 +358,72 @@ export async function buildApp(opts) {
         catch (err) {
             return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
         }
-        try {
-            const result = await runChatTurn(artifact, request.message, {
-                refs: request.refs,
-                allowUserComments: request.allowUserComments,
-                onProgress: (m) => console.log(`[chat ${artifact.id}] ${m}`),
-            });
-            // A turn takes minutes and 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.
-            const saved = await updateArtifactByKey(key, (current) => mergeConcurrentEdits(artifact, result.artifact, current));
-            return c.json({ artifact: saved, applied: result.applied, refused: result.refused });
-        }
-        catch (err) {
-            return c.json({ error: err instanceof Error ? err.message : String(err) }, 502);
+        // 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.
@@ -372,6 +434,11 @@ export async function buildApp(opts) {
             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);
@@ -443,7 +510,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,8 +1,9 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
+  "author": "Full Stack House (https://fullstack.house)",
   "repository": "github:fullstackhouse/cerber",
   "type": "module",
   "packageManager": "pnpm@10.33.2",