@fullstackhouse/cerber 0.9.0 → 0.10.0

package/README.md

@@ -38,7 +38,8 @@ 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.
+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.
 
 ## What a review looks like
 
@@ -198,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/gh.js

@@ -114,11 +114,13 @@ export function mapSearchResults(raw) {
         ];
     });
 }
-/** Open, non-draft PRs where the current gh user's review is requested. */
-export async function searchAwaitingMe(repoFilter, limit = 50) {
+export function searchAwaitingArgs(repoFilter, limit = 50) {
     const args = [
         "search",
         "prs",
+        // An archived repo is read-only: its PRs can never merge, close, or take a
+        // review. Without this they'd sit in the inbox forever — nothing retires them.
+        "archived:false",
         "--review-requested=@me",
         "--state=open",
         "--limit",
@@ -128,7 +130,11 @@ export async function searchAwaitingMe(repoFilter, limit = 50) {
     ];
     if (repoFilter)
         args.push("--repo", repoFilter);
-    const out = await gh(args);
+    return args;
+}
+/** Open, non-draft PRs where the current gh user's review is requested. */
+export async function searchAwaitingMe(repoFilter, limit = 50) {
+    const out = await gh(searchAwaitingArgs(repoFilter, limit));
     return mapSearchResults(JSON.parse(out));
 }
 /**

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 {