@diffohq/diffo 0.10.0 → 0.11.0

package/dist/cli.mjs

@@ -126,6 +126,29 @@ function detectHarness() {
 //#endregion
 //#region src/shared/review.ts
 const THREAD_INTENTS = ["fix", "question"];
+/** A review comment on GitHub tops out at 65 536 characters; a suggestion that
+* long is a mistake, and the reviewer edits it in a thread card. */
+const PR_COMMENT_MAX = 1e4;
+function parsePrComment(value) {
+	if (typeof value !== "string") return void 0;
+	const text = value.trim();
+	return text ? text.slice(0, PR_COMMENT_MAX) : void 0;
+}
+/**
+* The suggestion the reviewer can still act on: the latest agent message
+* carrying one, while nothing has been decided about it and the thread is
+* open. Earlier suggestions in the same thread are superseded, decided or
+* not — a redraft replaces, it never stacks.
+*/
+function liveSuggestion(thread) {
+	if (isPublic(thread) || thread.state === "resolved") return null;
+	for (let i = thread.messages.length - 1; i >= 0; i--) {
+		const m = thread.messages[i];
+		if (m.author !== "agent" || !m.prComment) continue;
+		return m.prComment.outcome === void 0 ? m : null;
+	}
+	return null;
+}
 function parseSuggestedReply(value) {
 	if (typeof value !== "string") return void 0;
 	const line = value.replace(/\s+/g, " ").trim();
@@ -166,6 +189,10 @@ function seenByAgent(thread, index) {
 function untouchedAgentVoice(thread) {
 	return startedByAgent(thread) && !thread.messages.some((m) => m.author === "reviewer");
 }
+/** The path a layer file names, without the reserved `:from-to` range. */
+function layerFilePath(file) {
+	return (typeof file === "string" ? file : file.path).replace(/:\d+-\d+$/, "");
+}
 /**
 * Feedback the reviewer is still owed an answer on — the delivery queue's contents,
 * derived rather than remembered, so a restart cannot drop an Ask nobody collected.
@@ -199,13 +226,15 @@ const EMPTY_REVIEW = {
 * Past threads are hidden, never deleted: a stash or a branch switch empties the diff
 * for a minute and must not destroy a thread.
 */
-function threadsInChangeset(files, threads) {
+function threadsInChangeset(files, threads, layers) {
 	const hunkIds = new Set(files.flatMap((f) => f.hunks.map((h) => h.id)));
 	const paths = new Set(files.flatMap((f) => f.oldPath ? [f.path, f.oldPath] : [f.path]));
+	const layerIds = new Set((layers?.items ?? []).map((l) => l.id));
 	const lives = (thread) => {
 		const anchor = thread.anchor;
 		if (anchor.kind === "changeset") return files.length > 0;
 		if (anchor.kind === "file") return paths.has(anchor.path);
+		if (anchor.kind === "layer") return layerIds.has(anchor.layerId);
 		return hunkIds.has(anchor.hunkId) || paths.has(anchor.path);
 	};
 	const active = [];
@@ -223,6 +252,7 @@ function anchorSpan(anchor) {
 function describeAnchor(anchor) {
 	if (anchor.kind === "changeset") return "the whole changeset";
 	if (anchor.kind === "file") return anchor.path;
+	if (anchor.kind === "layer") return `layer "${anchor.title}"`;
 	return `${anchor.path}:${anchorSpan(anchor)} (${anchor.side} side)`;
 }
 //#endregion
@@ -241,7 +271,19 @@ function findHunk(changeset, hunkId) {
 * — for the anchored line range — where those rows sit in it and their text.
 * Null for non-hunk anchors and for a hunk the changeset no longer has.
 */
-function captureAnchor(changeset, anchor) {
+function captureAnchor(changeset, anchor, layers) {
+	if (anchor.kind === "layer") {
+		const layer = layers?.items.find((l) => l.id === anchor.layerId);
+		if (!layer) return null;
+		return {
+			codeContext: null,
+			anchoredLayer: {
+				title: layer.title,
+				...layer.summary ? { summary: layer.summary } : {},
+				files: layer.files.map(layerFilePath)
+			}
+		};
+	}
 	if (anchor.kind !== "hunk") return null;
 	const hunk = findHunk(changeset, anchor.hunkId);
 	if (!hunk) return null;
@@ -355,6 +397,8 @@ const ACK_NEXT_STEP = {
 	reply: `When every thread is handled, run \`${CLI_COMMANDS.poll}\` again to keep listening (${POLL_STANCE}).`,
 	replyMore: "Interim reply posted — the reviewer still sees you working on this thread. Post the follow-up as a plain reply (no --more) BEFORE your next poll: re-polling closes the batch and counts the promise as never kept.",
 	comment: `It's in the review as your comment, labeled as yours — the reviewer replies to take it up, or resolves it. Continue with the review threads, then run \`${CLI_COMMANDS.poll}\`.`,
+	replyPrComment: `Reply posted, with the suggested review comment under it. The reviewer adds it to their review, edits it first, or dismisses it — nothing posts on its own, and you will hear what happened when they submit. When every thread is handled, run \`${CLI_COMMANDS.poll}\` again to keep listening (${POLL_STANCE}).`,
+	commentPrComment: `It's in the review as your comment, with the suggested review comment under it. The reviewer adds it to their review, edits it first, or dismisses it — nothing posts on its own. Continue with the review threads, then run \`${CLI_COMMANDS.poll}\`.`,
 	layers: `The outline is live in the reviewer's Layers tab, resolved against the changeset as it moves. Files you touch later land in a trailing "Since your review" layer until you re-post the whole list. Continue with the review threads, then run \`${CLI_COMMANDS.poll}\`.`,
 	layersSuggested: `The review now offers the outline to the reviewer. Mention it in your handoff too — "say layers and I'll outline it" — and post it with \`${CLI_COMMANDS.layers}\` when they ask. Then run \`${CLI_COMMANDS.poll}\`.`,
 	layersAlready: `This review already carries layers, so there is nothing to suggest — re-post the whole list with \`${CLI_COMMANDS.layers}\` if the outline is stale. Then run \`${CLI_COMMANDS.poll}\`.`,
@@ -372,6 +416,18 @@ const HELP_AGENT_PR = `Reviewing a pull request (\`diffo <PR URL | owner/repo#N
   label: read what the reviewer wants from the words. When the answer is a
   fix, put it in a \`\`\`suggestion block in your reply, not an edit to the
   worktree — the reviewer can post your reply to GitHub from there.
+- Read who each private message is for. A question ("what calls this?")
+  wants an answer. A finding stated about the code ("this resets the streak
+  on late completions") is a thought on its way to the author: write the
+  review comment they would leave, in their voice, and attach it with
+  \`--pr-comment "<text>"\` on your reply (or your comment). It shows under
+  your reply with Add to review / Edit / Dismiss; your evidence stays in the
+  reply, never in the comment. Attach one when they state a finding, when
+  their hunch proves right, when they ask you to draft it, or when a plain
+  question turns up a bug you can show. Not when they were wrong (say so
+  privately), not on pushback against your own reply — redraft the one
+  already in the thread instead — and not when asked but you have nothing
+  worth saying to the author: say so privately, never invent one.
 - The guide and layers work as above, built from the description, the commits
   and the diff; skip the guide when the description already orients.
 - When the reviewer submits, a poll returns a \`"kind": "submitted"\` notice:
@@ -442,14 +498,56 @@ const LAYERS = {
 	stance: GUIDE.stance,
 	/** A post is the whole list. */
 	replace: "a post replaces the whole list, never merges; ids are kept for titles that match, so a re-post never moves the reviewer's place",
+	/** What earns a line in a layer's `decisions`, and the bar for it. The
+	* reviewer reads these before the diff — or instead of it — so every entry
+	* must be something they could act on, never a retelling of the change. */
+	decisions: "a layer may carry up to five \"decisions\", each one short line (under eight words) with a one-sentence \"detail\" and an \"at\" — where it lives: \"path\", \"path:line\" or \"path:from-to\", or a list of up to three such places when the decision spans hunks (the rule and the test that pins it). A decision is where you chose between real alternatives a reviewer might weigh differently (a cache, a data shape, a fallback), where the code now does something the diff does not make obvious (a 400 where there was an empty list, a sort every caller sees), or where something in the repo or the environment shaped the change (no clock on the model, tests you could not run). Only what a reviewer could want done differently or would be surprised by later; nothing about naming or style; no verdicts. Write each line the way you would answer \"what did you decide here?\" to a teammate who has not seen the code: a concrete statement in plain words (\"Unknown ?due= values return 400, not an empty list\", \"Todos store a date, never a time\"), understood in a second by someone who has not read the diff — no project nicknames, no clever phrasing, no mechanism named instead of its effect. Most layers have none — a plumbing step has nothing to decide, so leave the list out",
 	/** The payload, in one line. */
-	shape: "[{ \"title\": \"…\", \"summary\": \"…\", \"kind\": \"mechanical\" (optional), \"files\": [\"src/a.ts\", { \"path\": \"src/b.ts\", \"note\": \"why this file is in this step\" }] }]"
+	shape: "[{ \"title\": \"…\", \"summary\": \"…\", \"kind\": \"mechanical\" (optional), \"files\": [\"src/a.ts\", { \"path\": \"src/b.ts\", \"note\": \"why this file is in this step\" }], \"decisions\": [{ \"text\": \"…\", \"detail\": \"…\", \"at\": \"src/a.ts:12-18\" | [\"src/a.ts:12-18\", \"test/a.test.ts:40\"] }] (optional, at most five) }]"
 };
 const AUTHOR_DOCTRINE = {
 	guide: GUIDE,
 	layers: LAYERS,
 	fix: "- `issue` threads want a code change. Address each one, or push back in the thread with your reasoning."
 };
+/**
+* The one piece of PR doctrine with no analogue for an author: the reviewer's
+* private words are often a review comment in the making, and the agent is the
+* one who can write it while the reviewer is still reading. The comment is
+* addressed to the author in the reviewer's voice; nothing of it posts until the
+* reviewer adds it to their review and submits.
+*/
+const PR_COMMENT_DOCTRINE = `## Drafting a review comment for the author
+
+The reviewer's private messages are of two kinds. A question to you ("what
+calls this?") wants an answer. A finding stated about the code ("this resets
+the streak on late completions") is a thought on its way to the author: the
+reviewer is thinking out loud at the line, and the next thing they would type
+is a review comment. Write that comment for them, attached to your reply:
+
+    ${CLI} reply <threadId> --message "<your private answer>" --pr-comment "<the comment>"
+
+Attach one when: they state a finding (always, a nit included); their hunch
+phrased as a question turns out right; they ask you to draft it ("write this
+up for the author"); or your answer to a plain question is a bug with a case
+to show. Do not attach one when they were wrong — say so privately — or when
+they are pushing back on your own reply; then redraft the comment already in
+the thread, which replaces it. Asked to suggest a change where you find
+nothing worth saying to the author, say so privately and attach nothing: a
+comment invented to fill the request is the one thing the reviewer cannot
+tell apart from a finding. On a comment of your own (\`${CLI} comment\`), the
+same flag carries a finding you can show, never a hunch.
+
+The comment is in the reviewer's voice, to the author: state the finding, why
+it matters, and what would fix it. A \`\`\`suggestion block when the fix is local
+to the anchored lines. Nothing about you, the worktree, tests you ran, or
+Diffo — that evidence goes in --message, where the reviewer reads it. Match
+how this reviewer writes: their own review comments on this pull request are
+quoted under "The reviewer's voice" when there are any.
+
+Nothing you attach reaches GitHub. It appears under your reply with Add to
+review / Edit / Dismiss; the reviewer decides, and the submit notice tells you
+what happened to each.`;
 const PR_DOCTRINE = {
 	guide: {
 		when: "the pull request description leaves a cold reader without the shape of the change — skip when the description already orients",
@@ -461,7 +559,8 @@ const PR_DOCTRINE = {
 		...LAYERS,
 		order: "the order you would explain it in after reading the description and the commits — the file that explains the rest first, mechanical consequences last; for a feature, follow the request from entry point to effect; for a refactor, contract first, then consumers"
 	},
-	fix: "- `issue` threads want a fix you cannot push: work it out in the worktree, verify it the cheapest honest way, restore the worktree (`git checkout -- .`), and reply with a ```suggestion block plus what you checked. Never commit or push to the pull request."
+	fix: "- `issue` threads want a fix you cannot push: work it out in the worktree, verify it the cheapest honest way, restore the worktree (`git checkout -- .`), and reply with a ```suggestion block plus what you checked. Never commit or push to the pull request.",
+	prComment: PR_COMMENT_DOCTRINE
 };
 function doctrineFor(changeset) {
 	return changeset?.pr ? PR_DOCTRINE : AUTHOR_DOCTRINE;
@@ -565,7 +664,7 @@ ${intentContract(threads, D).map((line) => `   ${line}`).join("\n")}
 
 Change only what these threads ask about — the reviewer is mid-read. Re-read
 the current file before editing; the code may have moved. Resolving a thread
-is the reviewer's call, never yours.`;
+is the reviewer's call, never yours.${D.prComment ? `\n\nA private message that states a finding about the code is a review comment in the making: attach the comment the reviewer would leave the author, in their voice, with \`--pr-comment "<text>"\` on your reply (evidence stays in --message). Not when they were wrong, not on pushback against your reply. \`${CLI} help agent\` has the whole rule.` : ""}`;
 }
 function replyProtocol(threads, mode = "full", D = AUTHOR_DOCTRINE) {
 	if (mode === "compact") return compactProtocol(threads, D);
@@ -618,7 +717,64 @@ Rules:
 - Each "commented change" above was frozen when the comment was written —
   re-read the current file before editing; the code may have moved since.
 - Your code edits are detected automatically and the reviewer's diff updates
-  live. Resolving a thread is the reviewer's call, never yours.`;
+  live. Resolving a thread is the reviewer's call, never yours.${D.prComment ? `\n\n${D.prComment}` : ""}`;
+}
+const VOICE_COMMENT_CAP = 5;
+const VOICE_EDIT_CAP = 3;
+const VOICE_TEXT_CAP = 400;
+function voiceQuote(text) {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length > VOICE_TEXT_CAP ? `${flat.slice(0, 399)}…` : flat;
+}
+/**
+* The reviewer's own review comments on this pull request, newest first, and
+* for each suggestion of the agent's they edited before adding, both versions.
+* The agent sees "I wrote X, they posted Y" and the next suggestion sounds like
+* the reviewer. Null when there is nothing of theirs yet.
+*/
+function voiceLines(threads) {
+	const byId = new Map(threads.map((t) => [t.id, t]));
+	const comments = threads.filter((t) => isPublic(t) && t.messages[0]?.author === "reviewer").map((t) => ({
+		at: t.createdAt,
+		line: `- ${describeAnchor(t.anchor)} — "${voiceQuote(t.messages[0].text)}"`
+	})).sort((a, b) => b.at.localeCompare(a.at)).slice(0, VOICE_COMMENT_CAP);
+	const edits = [];
+	for (const t of threads) {
+		if (isPublic(t)) continue;
+		for (const m of t.messages) {
+			const o = m.prComment?.outcome;
+			if (m.author !== "agent" || !o || o.kind !== "added" || !o.edited) continue;
+			const theirs = byId.get(o.draftThreadId)?.messages[0]?.text;
+			if (!theirs) continue;
+			edits.push({
+				at: o.at,
+				lines: [
+					`- ${describeAnchor(t.anchor)}`,
+					`  - yours: "${voiceQuote(m.prComment.text)}"`,
+					`  - theirs: "${voiceQuote(theirs)}"`
+				]
+			});
+		}
+	}
+	edits.sort((a, b) => b.at.localeCompare(a.at));
+	const pairs = edits.slice(0, VOICE_EDIT_CAP).flatMap((e) => e.lines);
+	if (comments.length === 0 && pairs.length === 0) return null;
+	return [
+		"## The reviewer's voice",
+		"",
+		...comments.length > 0 ? ["Their review comments on this pull request so far (posted or drafted):", ...comments.map((c) => c.line)] : [],
+		...pairs.length > 0 ? [
+			...comments.length > 0 ? [""] : [],
+			"What you suggested, and what they posted after editing it:",
+			...pairs
+		] : []
+	].join("\n");
+}
+/** The voice block, when the review is a pull request and the reviewer has written anything. */
+function voiceBlock(ctx) {
+	if (!ctx.changeset?.pr || !ctx.voice) return [];
+	const block = voiceLines(ctx.voice);
+	return block ? [block, ""] : [];
 }
 const FRAME_FILE_CAP = 40;
 function fileLine(file) {
@@ -693,8 +849,19 @@ function snapshotWindow(total, anchored) {
 /** The snapshot as the agent sees it: windowed on the anchored rows, each of
 * them marked with `>`. Threads from before `anchored` existed keep the old
 * head-of-hunk window. */
+/** A layer thread's stand-in for the diff snapshot: the step as the reviewer
+* read it, so the agent answers about the outline, not about a line. */
+function layerBlock(layer) {
+	return [
+		"The layer this comments on, as it was outlined when the comment was written:",
+		`- title: ${layer.title}`,
+		...layer.summary ? ["- summary:", ...layer.summary.split("\n").map((l) => `  ${l}`)] : [],
+		`- files: ${layer.files.map((f) => `\`${f}\``).join(", ")}`
+	];
+}
 function snapshotBlock(thread) {
 	const { codeContext, anchored } = thread;
+	if (thread.anchor.kind === "layer") return thread.anchoredLayer ? layerBlock(thread.anchoredLayer) : [];
 	if (!codeContext) {
 		if (!anchored) return [];
 		const shown = anchored.text.split("\n");
@@ -708,7 +875,7 @@ function snapshotBlock(thread) {
 		];
 	}
 	const lines = codeContext.split("\n");
-	const where = thread.anchor.kind === "changeset" ? "the file" : `\`${thread.anchor.path}\``;
+	const where = thread.anchor.kind === "hunk" || thread.anchor.kind === "file" ? `\`${thread.anchor.path}\`` : "the file";
 	if (thread.deliveredThrough) return [`(diff snapshot delivered to you earlier — read the current ${where} instead)`];
 	if (!anchored) return [
 		"The commented change:",
@@ -758,6 +925,7 @@ function buildThreadPrompt(thread, ctx) {
 		threadBlock(thread, 0),
 		"",
 		...siblings ? [siblings, ""] : [],
+		...voiceBlock(ctx),
 		replyProtocol([thread], ctx.protocol, D),
 		""
 	].join("\n");
@@ -773,6 +941,7 @@ function buildCoalescedPrompt(threads, ctx) {
 		...ctx.changeset ? [specLine(ctx.changeset), ""] : [],
 		...threads.map((t, i) => `${threadBlock(t, i)}\n`),
 		...siblings ? [siblings, ""] : [],
+		...voiceBlock(ctx),
 		replyProtocol(threads, ctx.protocol, D),
 		""
 	].join("\n");
@@ -781,6 +950,17 @@ function buildCoalescedPrompt(threads, ctx) {
 * The reviewer submitted the pull-request review on GitHub. Context, not work:
 * the agent learns the review ended and what it said, and owes nothing.
 */
+/** What became of the agent's suggested review comments, in one line: the
+* feedback that lets it calibrate, aggregate so it never argues for one. */
+function suggestionsLine(s) {
+	const n = (count, word) => `${count} ${word}`;
+	const parts = [
+		`${n(s.posted, "posted")}${s.edited > 0 ? ` (${s.edited} edited first)` : ""}`,
+		...s.dismissed > 0 ? [n(s.dismissed, "dismissed")] : [],
+		...s.undecided > 0 ? [`${s.undecided} left undecided (they stay private and never post)`] : []
+	];
+	return `Of the ${s.total} review comment${s.total === 1 ? "" : "s"} you suggested: ${parts.join(", ")}.`;
+}
 function buildSubmittedPrompt(ctx, submitted) {
 	const pr = ctx.changeset?.pr;
 	return [
@@ -791,6 +971,7 @@ function buildSubmittedPrompt(ctx, submitted) {
 			...submitted.body.split("\n").map((l) => `> ${l}`),
 			""
 		] : [],
+		...submitted.suggestions && submitted.suggestions.total > 0 ? [suggestionsLine(submitted.suggestions), ""] : [],
 		"Nothing to act on — this is context so you know where the review stands. Mention it to the user in one line.",
 		`Run \`${CLI_COMMANDS.poll}\` again to keep listening (${POLL_STANCE}); the reviewer may follow up. If the user is done, \`${CLI_COMMANDS.end}\`.`,
 		""
@@ -823,6 +1004,8 @@ function buildLayersRequestPrompt(ctx, existing) {
 		"",
 		`Order: ${D.layers.order}. ${D.layers.mechanical}. ${D.layers.stance}. Files are whole files, by path relative to the repo root; list every file of the changeset somewhere, or the leftovers land in "Since your review".`,
 		"",
+		`Decisions: ${D.layers.decisions}.`,
+		"",
 		`Shape: ${LAYERS.shape}`,
 		"",
 		`Post it: \`${CLI_COMMANDS.layers}\`, or pipe the JSON to \`${CLI_COMMANDS.layersStdin}\` when it is long. Nothing else is owed for this item — no reply, no comment.`,
@@ -898,6 +1081,8 @@ const SUMMARY_CAP = 4e3;
 /** A note is one line by contract — anything past the first newline is dropped,
 * and the line itself is capped so the file header stays a header. */
 const NOTE_CAP = 200;
+const DECISION_TEXT_CAP = 120;
+const DECISION_DETAIL_CAP = 400;
 const REPO_PATH = /^[^\0]+$/;
 /**
 * Paths are relative to the repo root: no leading slash, no `..` segment, no
@@ -956,6 +1141,93 @@ function oneLine(text, cap) {
 	const line = text.split("\n", 1)[0].trim();
 	return line.length > cap ? `${line.slice(0, cap - 1).trimEnd()}…` : line;
 }
+/**
+* Where a decision points: `path`, `path:line` or `path:from-to`, the same
+* spelling a file reference in a summary uses. Lines are head-side and
+* 1-based; a range is normalised so `from` never exceeds `to`.
+*/
+function parseDecisionAt(raw) {
+	const m = /^(.*?)(?::(\d+)(?:-(\d+))?)?$/.exec(raw.trim());
+	const path = m?.[1] ?? "";
+	const why = badPath(path);
+	if (why) return `"at" path "${raw}" ${why}`;
+	if (m?.[2] === void 0) return { path };
+	const a = Number.parseInt(m[2], 10);
+	const b = m[3] === void 0 ? a : Number.parseInt(m[3], 10);
+	if (a < 1 || b < 1) return `"at" line in "${raw}" must be 1 or more`;
+	const [line, endLine] = a <= b ? [a, b] : [b, a];
+	return endLine === line ? {
+		path,
+		line
+	} : {
+		path,
+		line,
+		endLine
+	};
+}
+/** The object form of `at` back as the string the agent would have written;
+* null for anything that is not that object. */
+function atToString(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+	const a = raw;
+	if (typeof a.path !== "string") return null;
+	if (a.line === void 0) return a.endLine === void 0 ? a.path : null;
+	if (typeof a.line !== "number" || !Number.isInteger(a.line)) return null;
+	if (a.endLine === void 0) return `${a.path}:${a.line}`;
+	if (typeof a.endLine !== "number" || !Number.isInteger(a.endLine)) return null;
+	return `${a.path}:${a.line}-${a.endLine}`;
+}
+function parseDecision(raw, where) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		error: `${where}: each decision is an object { text, detail?, at? }`
+	};
+	const d = raw;
+	const text = typeof d.text === "string" ? oneLine(d.text, DECISION_TEXT_CAP) : "";
+	if (text === "") return {
+		ok: false,
+		error: `${where}: needs a non-empty "text"`
+	};
+	if (d.detail !== void 0 && typeof d.detail !== "string") return {
+		ok: false,
+		error: `${where} ("${text}"): "detail" must be a string`
+	};
+	const detail = typeof d.detail === "string" ? d.detail.trim().slice(0, DECISION_DETAIL_CAP) : void 0;
+	let at;
+	if (d.at !== void 0) {
+		const raws = Array.isArray(d.at) ? d.at : [d.at];
+		if (raws.length === 0) return {
+			ok: false,
+			error: `${where} ("${text}"): "at" must name at least one place`
+		};
+		if (raws.length > 3) return {
+			ok: false,
+			error: `${where} ("${text}"): "at" names ${raws.length} places; keep it to 3 — the layer's files are the file list`
+		};
+		at = [];
+		for (const raw of raws) {
+			const str = typeof raw === "string" ? raw : atToString(raw);
+			if (str === null) return {
+				ok: false,
+				error: `${where} ("${text}"): "at" is a string — "path", "path:line" or "path:from-to" — or a list of up to 3`
+			};
+			const parsed = parseDecisionAt(str);
+			if (typeof parsed === "string") return {
+				ok: false,
+				error: `${where} ("${text}"): ${parsed}`
+			};
+			at.push(parsed);
+		}
+	}
+	return {
+		ok: true,
+		decision: {
+			text,
+			...detail ? { detail } : {},
+			...at ? { at } : {}
+		}
+	};
+}
 /** The reason behind `--suggest`, fit for the one line the empty state quotes
 * it in. Undefined when there is nothing usable — the suggestion stands alone. */
 function parseSuggestReason(raw) {
@@ -967,8 +1239,9 @@ function parseSuggestReason(raw) {
 * The whole post, or the first thing wrong with it. Titles and file lists are
 * required and non-empty; everything else is optional and normalised — a
 * summary trimmed and capped, a note cut to one line, an unknown `kind`
-* refused rather than silently dropped (the agent meant something by it). Any
-* `id` the agent sends is ignored: the server mints them.
+* refused rather than silently dropped (the agent meant something by it), a
+* decisions list checked entry by entry and refused past five. Any `id` the
+* agent sends is ignored: the server mints them.
 */
 function parseLayersInput(raw) {
 	if (!Array.isArray(raw)) return {
@@ -1017,11 +1290,29 @@ function parseLayersInput(raw) {
 			ok: false,
 			error: `${where} ("${title}"): "kind" can only be "mechanical"; leave it out otherwise`
 		};
+		let decisions;
+		if (l.decisions !== void 0) {
+			if (!Array.isArray(l.decisions)) return {
+				ok: false,
+				error: `${where} ("${title}"): "decisions" must be a list`
+			};
+			if (l.decisions.length > 5) return {
+				ok: false,
+				error: `${where} ("${title}"): keep "decisions" to 5 — the ones a reviewer could want done differently, not a retelling of the diff`
+			};
+			decisions = [];
+			for (const [j, raw] of l.decisions.entries()) {
+				const parsed = parseDecision(raw, `${where} ("${title}") decision ${j + 1}`);
+				if (!parsed.ok) return parsed;
+				decisions.push(parsed.decision);
+			}
+		}
 		items.push({
 			title,
 			files,
 			...summary !== "" ? { summary } : {},
-			...l.kind === "mechanical" ? { kind: "mechanical" } : {}
+			...l.kind === "mechanical" ? { kind: "mechanical" } : {},
+			...decisions && decisions.length > 0 ? { decisions } : {}
 		});
 	}
 	return {
@@ -1278,7 +1569,7 @@ Examples:
   diffo poll`,
 	reply: `diffo reply: post a reply to a review thread
 
-Usage: diffo reply <threadId> --message "<text>" [--suggest-reply "<one line>"]
+Usage: diffo reply <threadId> --message "<text>" [--suggest-reply "<one line>"] [--pr-comment "<text>"]
        … | diffo reply <threadId>            (long replies: pipe on stdin)
 
 Thread ids arrive in poll payloads. Each run posts one message, so don't
@@ -1292,6 +1583,12 @@ ghost text in their reply box, taken with Tab, edited or ignored at will.
 Use it when your message ends in a decision that is theirs to make
 ("want me to extract this?" → --suggest-reply "yes, extract it"); never
 on a message that only reports.
+--pr-comment, on a pull request only, attaches the review comment the
+reviewer would leave the author: in their voice, to the author, as GitHub
+will show it (Markdown; a \`\`\`suggestion block when the fix is local to the
+anchored lines). It appears under your reply with Add to review / Edit /
+Dismiss; nothing posts until the reviewer submits. Your evidence goes in
+--message, never in the comment. \`diffo help agent\` says when to attach one.
 Messages render GitHub-flavored markdown; a \`\`\`mermaid fence renders as a
 diagram in the review.
 
@@ -1301,7 +1598,7 @@ Example:
   diffo reply t-3 --message "fixed: the guard now covers the empty case"`,
 	comment: `diffo comment: start a comment thread as the agent
 
-Usage: diffo comment [<file>] [--line <n>] --message "<text>" [--suggest-reply "<one line>"]
+Usage: diffo comment [<file>] [--line <n>] --message "<text>" [--suggest-reply "<one line>"] [--pr-comment "<text>"]
        … | diffo comment [<file>] [--line <n>]  (long comments: pipe on stdin)
 
 Anchors to a line (--line), a file, or, with no file, the whole changeset.
@@ -1313,6 +1610,10 @@ Spend these sparingly; an agent that annotates everything gets skimmed.
 ghost text in their reply box, taken with Tab, edited or ignored at will.
 Use it when the comment proposes something and the call is theirs; the
 reply they take hands the thread to you like any other.
+--pr-comment, on a pull request only, attaches the review comment the
+reviewer would leave the author about this: same rules as on \`reply\`. For a
+finding you can show (a case you ran, a call site the change misses), not
+for a hunch.
 Messages render GitHub-flavored markdown; a \`\`\`mermaid fence renders as a
 diagram in the review.
 
@@ -1342,6 +1643,8 @@ accepted (the file may land later) and simply shows nothing until it does.
 Files you touch after posting land in a trailing "Since your review" layer
 until you re-post.
 
+Decisions: ${LAYERS.decisions}.
+
 Shape: ${LAYERS.shape}
 
 Output: {"ok":true,"layers":4,"next_step":"…"}
@@ -1349,7 +1652,7 @@ Output: {"ok":true,"layers":4,"next_step":"…"}
 
 Examples:
   diffo layers --suggest "the parser change explains the rest"
-  diffo layers --json '[{"title":"Parser contract","summary":"The contract the rest of the change leans on: bad input now comes back as null, not an exception.","files":["src/parse.ts"]},{"title":"Callers adapted","kind":"mechanical","summary":"Call sites following the new return type.","files":["src/cli.ts","src/api.ts"]}]'`,
+  diffo layers --json '[{"title":"Parser contract","summary":"The contract the rest of the change leans on: bad input now comes back as null, not an exception.","files":["src/parse.ts"],"decisions":[{"text":"Bad input returns null, not a throw","detail":"Callers already branch on null for a missing value; a throw would need a try at every site.","at":"src/parse.ts:41-46"}]},{"title":"Callers adapted","kind":"mechanical","summary":"Call sites following the new return type.","files":["src/cli.ts","src/api.ts"]}]'`,
 	end: `diffo end: detach from the review politely
 
 Usage: diffo end
@@ -1762,6 +2065,7 @@ function parseVerb(verb, rest) {
 			title: { type: "string" },
 			more: { type: "boolean" },
 			"suggest-reply": { type: "string" },
+			"pr-comment": { type: "string" },
 			json: { type: "boolean" },
 			help: {
 				type: "boolean",
@@ -1775,6 +2079,7 @@ function parseVerb(verb, rest) {
 	};
 	const { values, positionals } = parsed.value;
 	const suggestReply = values["suggest-reply"];
+	const prComment = values["pr-comment"];
 	if (values.help) return {
 		kind: "help",
 		topic: verb
@@ -1801,6 +2106,16 @@ function parseVerb(verb, rest) {
 			message: "--suggest-reply is one line — the reviewer completes it"
 		};
 	}
+	if (prComment !== void 0) {
+		if (verb !== "reply" && verb !== "comment") return {
+			kind: "error",
+			message: `'${verb}' takes no --pr-comment`
+		};
+		if (!prComment.trim()) return {
+			kind: "error",
+			message: "--pr-comment needs the review comment you are suggesting"
+		};
+	}
 	if (values.title !== void 0 && verb !== "poll") return {
 		kind: "error",
 		message: `'${verb}' takes no --title`
@@ -1850,7 +2165,8 @@ function parseVerb(verb, rest) {
 			threadId,
 			message: values.message ?? null,
 			more: values.more === true,
-			suggestReply: suggestReply?.trim() ?? null
+			suggestReply: suggestReply?.trim() ?? null,
+			prComment: prComment?.trim() ?? null
 		};
 	}
 	const file = positionals[0] ?? null;
@@ -1875,7 +2191,8 @@ function parseVerb(verb, rest) {
 		file,
 		line,
 		message: values.message ?? null,
-		suggestReply: suggestReply?.trim() ?? null
+		suggestReply: suggestReply?.trim() ?? null,
+		prComment: prComment?.trim() ?? null
 	};
 }
 //#endregion
@@ -3607,8 +3924,9 @@ var DeliveryQueue = class DeliveryQueue {
 	stalled = false;
 	stallTimer = null;
 	betweenPolls = false;
-	/** Why the agent is parked between polls: a reply just landed, or its poll
-	* ended on its own and the re-poll is expected. */
+	/** Why the agent is parked between polls: a reply just landed, its poll
+	* ended on its own and the re-poll is expected, or it opened the review and
+	* is still orienting itself before its first poll. */
 	parked = "replied";
 	graceTimer = null;
 	lastDetach = null;
@@ -3810,7 +4128,7 @@ var DeliveryQueue = class DeliveryQueue {
 		if (this.stallTimer !== null) clearTimeout(this.stallTimer);
 		this.stallTimer = null;
 	}
-	armGrace(why = "replied") {
+	armGrace(why = "replied", windowMs = this.replyGraceMs) {
 		this.clearGrace();
 		this.betweenPolls = true;
 		this.parked = why;
@@ -3822,7 +4140,7 @@ var DeliveryQueue = class DeliveryQueue {
 		};
 		const pid = this.owner;
 		if (pid === null) {
-			const timer = setTimeout(drop, this.replyGraceMs);
+			const timer = setTimeout(drop, windowMs);
 			timer.unref?.();
 			this.graceTimer = timer;
 			return;
@@ -3866,6 +4184,24 @@ var DeliveryQueue = class DeliveryQueue {
 		if (!(pid !== null && !isAlive(pid)) && !this.awaitingReply && this.outlining() === null) this.armGrace("repolling");
 		this.notify();
 	}
+	/**
+	* An agent's CLI opened this review. The agent reads the change and writes
+	* its guide before it ever polls, which can take minutes — and a reviewer who
+	* opened the URL meanwhile must not be told there is no agent and offered an
+	* Invite. So from the open until the first poll the agent is 'working', for
+	* the reason 'arriving': a named session is watched until its process is gone
+	* (or the cap), an anonymous one gets a fixed window. The first poll ends it
+	* the way it ends every grace. An agent already here in any state is left
+	* alone — a second open is not a second agent. Returns whether it took.
+	*/
+	agentArrived(pid) {
+		if (this.presence() !== "waiting") return false;
+		this.owner = DeliveryQueue.clean(pid);
+		this.lastDetach = null;
+		this.armGrace("arriving", this.liveness.arriveGraceMs ?? 3e5);
+		this.notify();
+		return true;
+	}
 	enqueueThreads(threadIds) {
 		const bucket = this.bucket();
 		for (const id of threadIds) bucket.threads.add(id);
@@ -4391,7 +4727,7 @@ function threadsFromGithub(pr, imported, files) {
 * body, or a conversation comment.
 */
 function githubPosition(anchor, body, files) {
-	if (anchor.kind === "changeset") return null;
+	if (anchor.kind === "changeset" || anchor.kind === "layer") return null;
 	if (anchor.kind === "file") return {
 		draft: {
 			path: anchor.path,
@@ -4472,6 +4808,37 @@ function planPublicLeg(threads, files) {
 		resolves
 	};
 }
+/**
+* What became of the agent's suggested review comments, counted at submit:
+* a suggestion is `posted` when the draft it became is still in the review
+* (a discarded draft takes the thread with it), `edited` when the reviewer
+* changed the words first. The agent hears this once, in the submit notice.
+*/
+function suggestionsSummary(threads) {
+	const ids = new Set(threads.map((t) => t.id));
+	const s = {
+		total: 0,
+		posted: 0,
+		edited: 0,
+		dismissed: 0,
+		undecided: 0
+	};
+	for (const t of threads) {
+		if (isPublic(t)) continue;
+		for (const m of t.messages) {
+			if (m.author !== "agent" || !m.prComment) continue;
+			s.total++;
+			const o = m.prComment.outcome;
+			if (!o) s.undecided++;
+			else if (o.kind === "dismissed") s.dismissed++;
+			else if (ids.has(o.draftThreadId)) {
+				s.posted++;
+				if (o.edited) s.edited++;
+			} else s.undecided++;
+		}
+	}
+	return s;
+}
 /** The dialog's rows: what will post, in words. */
 function describeLeg(leg) {
 	return {
@@ -4480,7 +4847,8 @@ function describeLeg(leg) {
 			anchor: describeAnchor(d.thread.anchor),
 			text: d.text,
 			downgraded: d.downgraded,
-			conversation: d.position === null
+			conversation: d.position === null,
+			...d.thread.origin ? { fromAgent: { edited: d.thread.origin.edited } } : {}
 		})),
 		replies: leg.replies.map((r) => ({
 			id: r.thread.id,
@@ -5001,21 +5369,67 @@ var ReviewStore = class {
 			state: "open",
 			...options.audience === "pr" ? { audience: "pr" } : intent ? { intent } : {},
 			...options.parentId ? { parentId: options.parentId } : {},
+			...options.audience === "pr" && options.origin ? { origin: options.origin } : {},
 			codeContext: capture?.codeContext ?? null,
 			...capture?.anchored ? { anchored: capture.anchored } : {},
+			...capture?.anchoredLayer ? { anchoredLayer: capture.anchoredLayer } : {},
 			codeChanged: false,
 			messages: [{
 				id: randomUUID(),
 				author,
 				text,
 				at: now,
-				...author === "agent" && options.suggestedReply ? { suggestedReply: options.suggestedReply } : {}
+				...author === "agent" && options.suggestedReply ? { suggestedReply: options.suggestedReply } : {},
+				...author === "agent" && options.prComment ? { prComment: { text: options.prComment } } : {}
 			}],
 			createdAt: now,
 			updatedAt: now
 		});
 	}
 	/**
+	* The reviewer's decision on a suggested PR comment: added to their review
+	* (the public draft it became is named) or dismissed. Stamped once — a
+	* decided suggestion is history, and the card shows it as such. Null when
+	* the thread or message is not a live suggestion.
+	*/
+	decidePrComment(threadId, messageId, outcome) {
+		const current = this.state.threads.find((t) => t.id === threadId);
+		const message = current?.messages.find((m) => m.id === messageId);
+		if (!current || !message || message.author !== "agent" || !message.prComment) return null;
+		if (message.prComment.outcome !== void 0) return null;
+		return this.setPrCommentOutcome(threadId, messageId, outcome);
+	}
+	/**
+	* The decision taken back: a dismissed suggestion returns live, with its
+	* buttons. An added one does too, but only once the draft it became is gone
+	* (discarded) — while the draft stands, reviving the suggestion would offer
+	* the same comment twice. Null when there is nothing to restore.
+	*/
+	restorePrComment(threadId, messageId) {
+		const current = this.state.threads.find((t) => t.id === threadId);
+		const message = current?.messages.find((m) => m.id === messageId);
+		const outcome = message?.prComment?.outcome;
+		if (!current || !message || !outcome) return null;
+		if (outcome.kind === "added" && this.state.threads.some((t) => t.id === outcome.draftThreadId)) return null;
+		return this.setPrCommentOutcome(threadId, messageId, void 0);
+	}
+	setPrCommentOutcome(threadId, messageId, outcome) {
+		return this.update(threadId, (thread) => ({
+			...thread,
+			messages: thread.messages.map((m) => {
+				if (m.id !== messageId) return m;
+				const { outcome: _was, ...rest } = m.prComment;
+				return {
+					...m,
+					prComment: outcome ? {
+						...rest,
+						outcome
+					} : rest
+				};
+			})
+		}));
+	}
+	/**
 	* The closing note of a Finish round, as a thread. Anchored to the changeset
 	* and opened in the reviewer's voice, so it travels the ordinary path: the
 	* agent replies to it with `diffo reply`, the queue counts it as feedback
@@ -5057,14 +5471,15 @@ var ReviewStore = class {
 	* the reviewer raced in since — appended at the end, it would render as an
 	* answer to a comment it never saw, and the raced comment would stop reading
 	* as "waiting on the agent" even though it still is. */
-	addMessage(threadId, author, text, withheld = false, seenThroughMs, followUp = false, suggestedReply) {
+	addMessage(threadId, author, text, withheld = false, seenThroughMs, followUp = false, suggestedReply, prComment) {
 		return this.update(threadId, ({ unanswered: _answered, ...thread }) => {
 			const message = {
 				id: randomUUID(),
 				author,
 				text,
 				at: (/* @__PURE__ */ new Date()).toISOString(),
-				...author === "agent" && suggestedReply ? { suggestedReply } : {}
+				...author === "agent" && suggestedReply ? { suggestedReply } : {},
+				...author === "agent" && prComment ? { prComment: { text: prComment } } : {}
 			};
 			const raced = author === "agent" && seenThroughMs !== void 0 ? thread.messages.findIndex((m) => m.author === "reviewer" && Date.parse(m.at) > seenThroughMs) : -1;
 			const { awaitingFollowUp: _promised, ...settled } = thread;
@@ -5180,13 +5595,14 @@ var ReviewStore = class {
 		}));
 	}
 	removeThread(threadId) {
-		const threads = this.state.threads.filter((t) => t.id !== threadId);
-		if (threads.length === this.state.threads.length) return false;
+		const removed = this.state.threads.find((t) => t.id === threadId);
+		if (!removed) return false;
 		this.state = {
 			...this.state,
-			threads
+			threads: this.state.threads.filter((t) => t.id !== threadId)
 		};
 		this.commit();
+		if (removed.origin) this.restorePrComment(removed.origin.threadId, removed.origin.messageId);
 		return true;
 	}
 	/**
@@ -5229,7 +5645,8 @@ var ReviewStore = class {
 		const { layersSuggested: _suggested, ...rest } = this.state;
 		this.state = {
 			...rest,
-			layers
+			layers,
+			threads: reconcileLayerThreads(rest.threads, layers)
 		};
 		this.commit();
 		return layers;
@@ -5712,9 +6129,32 @@ function migrateLegacySuggestion(value, now) {
 		updatedAt: at
 	};
 }
+/**
+* A re-post dropped a layer (its title is gone), so the threads on it have
+* nothing left to sit under — the same fate as a hunk whose id rotated: a
+* `sent` thread was overtaken and reads as addressed; an open one stays as it
+* is and the UI files it with the threads the changeset left behind.
+*/
+function reconcileLayerThreads(threads, layers) {
+	const ids = new Set(layers.items.map((l) => l.id));
+	return threads.map((thread) => thread.anchor.kind === "layer" && thread.state === "sent" && !ids.has(thread.anchor.layerId) ? {
+		...thread,
+		state: "addressed",
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	} : thread);
+}
 function parseAnchor(value) {
 	if (typeof value !== "object" || value === null) return null;
 	const anchor = value;
+	if (anchor.kind === "layer") {
+		if (typeof anchor.layerId !== "string" || anchor.layerId === "") return null;
+		if (typeof anchor.title !== "string" || anchor.title.trim() === "") return null;
+		return {
+			kind: "layer",
+			layerId: anchor.layerId,
+			title: anchor.title.trim()
+		};
+	}
 	if (anchor.kind === "hunk") {
 		if (typeof anchor.hunkId !== "string" || typeof anchor.path !== "string") return null;
 		if (anchor.side !== "old" && anchor.side !== "new") return null;
@@ -5747,6 +6187,53 @@ function normalizeAnchored(value) {
 		text: a.text
 	};
 }
+/** Dropped when malformed — the thread keeps its anchor's title regardless. */
+function normalizeAnchoredLayer(value) {
+	if (typeof value !== "object" || value === null) return null;
+	const a = value;
+	if (typeof a.title !== "string" || !Array.isArray(a.files)) return null;
+	if (!a.files.every((f) => typeof f === "string")) return null;
+	return {
+		title: a.title,
+		...typeof a.summary === "string" && a.summary !== "" ? { summary: a.summary } : {},
+		files: a.files
+	};
+}
+function normalizePrComment(value) {
+	if (typeof value !== "object" || value === null) return null;
+	const v = value;
+	if (typeof v.text !== "string" || v.text.trim() === "") return null;
+	const o = v.outcome;
+	let outcome;
+	if (typeof o === "object" && o !== null) {
+		const r = o;
+		const at = typeof r.at === "string" ? r.at : (/* @__PURE__ */ new Date()).toISOString();
+		if (r.kind === "dismissed") outcome = {
+			kind: "dismissed",
+			at
+		};
+		else if (r.kind === "added" && typeof r.draftThreadId === "string") outcome = {
+			kind: "added",
+			draftThreadId: r.draftThreadId,
+			edited: r.edited === true,
+			at
+		};
+	}
+	return {
+		text: v.text,
+		...outcome ? { outcome } : {}
+	};
+}
+function normalizeOrigin(value) {
+	if (typeof value !== "object" || value === null) return null;
+	const v = value;
+	if (typeof v.threadId !== "string" || typeof v.messageId !== "string") return null;
+	return {
+		threadId: v.threadId,
+		messageId: v.messageId,
+		edited: v.edited === true
+	};
+}
 function normalizeThread(value, now) {
 	if (typeof value !== "object" || value === null) return null;
 	const t = value;
@@ -5754,6 +6241,7 @@ function normalizeThread(value, now) {
 	const anchor = parseAnchor(t.anchor);
 	if (!anchor) return null;
 	const anchored = normalizeAnchored(t.anchored);
+	const anchoredLayer = normalizeAnchoredLayer(t.anchoredLayer);
 	if (!Array.isArray(t.messages)) return null;
 	const messages = [];
 	for (const m of t.messages) {
@@ -5770,6 +6258,7 @@ function normalizeThread(value, now) {
 			at: typeof msg.at === "string" ? msg.at : now,
 			...typeof msg.durationMs === "number" ? { durationMs: msg.durationMs } : {},
 			...msg.author === "agent" && typeof msg.suggestedReply === "string" && msg.suggestedReply ? { suggestedReply: msg.suggestedReply } : {},
+			...msg.author === "agent" && normalizePrComment(msg.prComment) ? { prComment: normalizePrComment(msg.prComment) } : {},
 			...typeof msg.editedAt === "string" ? { editedAt: msg.editedAt } : {},
 			...github ? { github } : {}
 		});
@@ -5783,10 +6272,12 @@ function normalizeThread(value, now) {
 		...t.audience === "pr" ? { audience: "pr" } : {},
 		...typeof t.parentId === "string" && t.parentId !== "" ? { parentId: t.parentId } : {},
 		...github ? { github } : {},
+		...t.audience === "pr" && normalizeOrigin(t.origin) ? { origin: normalizeOrigin(t.origin) } : {},
 		...queued ? { queued } : {},
 		...THREAD_INTENTS.includes(t.intent) ? { intent: t.intent } : {},
 		codeContext: typeof t.codeContext === "string" ? t.codeContext : null,
 		...anchored ? { anchored } : {},
+		...anchoredLayer ? { anchoredLayer } : {},
 		codeChanged: t.codeChanged === true,
 		...t.unanswered === true ? { unanswered: true } : {},
 		...t.awaitingFollowUp === true && t.unanswered !== true ? { awaitingFollowUp: true } : {},
@@ -6662,15 +7153,27 @@ function createApp(ctx, store, review, queue) {
 		"light",
 		"dark"
 	]);
+	const CRITTER_VALUES = /* @__PURE__ */ new Set(["on", "off"]);
+	const stored = (key, values) => {
+		const value = ctx.uiSettings?.get(key) ?? null;
+		return value !== null && values.has(value) ? value : null;
+	};
 	app.get("/api/settings", (c) => {
-		const theme = ctx.uiSettings?.get("theme") ?? null;
-		return c.json({ theme: theme !== null && THEME_VALUES.has(theme) ? theme : null });
+		return c.json({
+			theme: stored("theme", THEME_VALUES),
+			critter: stored("critter", CRITTER_VALUES)
+		});
 	});
 	app.put("/api/settings", async (c) => {
 		if (!ctx.uiSettings) return c.json({ error: "settings unavailable" }, 503);
-		const theme = (await c.req.json().catch(() => null))?.theme;
-		if (typeof theme !== "string" || !THEME_VALUES.has(theme)) return c.json({ error: "need {theme: \"system\" | \"light\" | \"dark\"}" }, 400);
-		ctx.uiSettings.set("theme", theme);
+		const body = await c.req.json().catch(() => null);
+		const theme = body?.theme;
+		const critter = body?.critter;
+		const themeOk = typeof theme === "string" && THEME_VALUES.has(theme);
+		const critterOk = typeof critter === "string" && CRITTER_VALUES.has(critter);
+		if (theme !== void 0 && !themeOk || critter !== void 0 && !critterOk || !(themeOk || critterOk)) return c.json({ error: "need {theme?: \"system\" | \"light\" | \"dark\", critter?: \"on\" | \"off\"}, at least one" }, 400);
+		if (themeOk) ctx.uiSettings.set("theme", theme);
+		if (critterOk) ctx.uiSettings.set("critter", critter);
 		return c.json({ ok: true });
 	});
 	const reviewKind = () => reviewKindOf(ctx.spec, ctx.pr !== void 0);
@@ -6707,6 +7210,7 @@ function createApp(ctx, store, review, queue) {
 	const promptCtx = (...excludeThreadIds) => ({
 		repo: repoInfo(),
 		changeset: store?.get() ?? null,
+		...ctx.pr && review ? { voice: review.get().threads } : {},
 		siblings: review?.get().threads.filter((t) => !excludeThreadIds.includes(t.id) && (t.state === "open" || t.state === "sent")) ?? []
 	});
 	const deliverThreads = (threadIds) => {
@@ -6750,20 +7254,67 @@ function createApp(ctx, store, review, queue) {
 			const file = typeof body?.file === "string" && body.file.trim() !== "" ? body.file.trim() : null;
 			const line = typeof body?.line === "number" && Number.isInteger(body.line) && body.line >= 1 ? body.line : null;
 			const anchor = agentAnchor(file, line);
+			const prComment = parsePrComment(body?.prComment);
+			if (body?.prComment !== void 0 && !ctx.pr) return c.json({ error: "a suggested PR comment needs a pull request under review" }, 400);
 			const capture = store ? captureAnchor(store.get(), anchor) : null;
-			return c.json(review.createThread(anchor, text, capture, void 0, "agent", { suggestedReply: parseSuggestedReply(body?.suggestedReply) }));
+			return c.json(review.createThread(anchor, text, capture, void 0, "agent", {
+				suggestedReply: parseSuggestedReply(body?.suggestedReply),
+				...prComment ? { prComment } : {}
+			}));
 		}
 		const anchor = parseAnchor(body?.anchor);
 		if (!anchor) return c.json({ error: "need {anchor, text}" }, 400);
+		const layer = anchor.kind === "layer" ? review.get().layers?.items.find((l) => l.id === anchor.layerId) : void 0;
+		if (anchor.kind === "layer") {
+			if (!layer) return c.json({ error: "that layer is not in the outline" }, 400);
+			anchor.title = layer.title;
+		}
 		const intent = THREAD_INTENTS.includes(body?.intent) ? body.intent : void 0;
 		const audience = body?.audience === "pr" ? "pr" : void 0;
 		if (audience && !ctx.pr) return c.json({ error: "public comments need a pull request under review" }, 400);
+		if (audience && anchor.kind === "layer") return c.json({ error: "a comment on a layer is for the agent, not the pull request" }, 400);
 		const parentId = typeof body?.parentId === "string" && review.get().threads.some((t) => t.id === body.parentId) ? body.parentId : void 0;
-		const capture = store ? captureAnchor(store.get(), anchor) : null;
-		return c.json(review.createThread(anchor, text, capture, intent, "reviewer", {
+		let origin;
+		if (body?.origin !== void 0) {
+			const o = body.origin;
+			const source = audience && typeof o?.threadId === "string" ? review.get().threads.find((t) => t.id === o.threadId) : void 0;
+			const message = source && typeof o?.messageId === "string" ? source.messages.find((m) => m.id === o.messageId) : void 0;
+			if (!source || !message || liveSuggestion(source)?.id !== message.id) return c.json({ error: "that suggested comment is no longer live" }, 409);
+			origin = {
+				threadId: source.id,
+				messageId: message.id,
+				edited: message.prComment.text.trim() !== text
+			};
+		}
+		const capture = store ? captureAnchor(store.get(), anchor, review.get().layers) : null;
+		const created = review.createThread(anchor, text, capture, intent, "reviewer", {
 			...audience ? { audience } : {},
-			...parentId ? { parentId } : {}
-		}));
+			...parentId ? { parentId } : {},
+			...origin ? { origin } : {}
+		});
+		if (origin) review.decidePrComment(origin.threadId, origin.messageId, {
+			kind: "added",
+			draftThreadId: created.id,
+			edited: origin.edited,
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return c.json(created);
+	});
+	app.post("/api/review/threads/:id/messages/:messageId/pr-comment", async (c) => {
+		if (!review) return c.json({ error: "review unavailable" }, 503);
+		const body = await c.req.json().catch(() => null);
+		const id = c.req.param("id");
+		const messageId = c.req.param("messageId");
+		if (body?.outcome === "restored") {
+			const thread = review.restorePrComment(id, messageId);
+			return thread ? c.json(thread) : c.json({ error: "nothing to restore there" }, 404);
+		}
+		if (body?.outcome !== "dismissed") return c.json({ error: "outcome must be \"dismissed\" or \"restored\"" }, 400);
+		const thread = review.decidePrComment(id, messageId, {
+			kind: "dismissed",
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return thread ? c.json(thread) : c.json({ error: "no live suggested comment there" }, 404);
 	});
 	app.post("/api/review/layers", async (c) => {
 		if (!review) return c.json({ error: "review unavailable" }, 503);
@@ -6800,9 +7351,11 @@ function createApp(ctx, store, review, queue) {
 			if (!review.get().threads.some((t) => t.id === id)) return c.json({ error: "no such thread" }, 404);
 			queue?.noteSession(parseSessionPid(c.req.header("x-diffo-session-pid")));
 			const more = body?.more === true;
+			const prComment = parsePrComment(body?.prComment);
+			if (body?.prComment !== void 0 && !ctx.pr) return c.json({ error: "a suggested PR comment needs a pull request under review" }, 400);
 			const waitedMs = queue?.agentReplied(id, more) ?? null;
 			const seenThroughMs = waitedMs === null ? void 0 : Date.now() - waitedMs;
-			const thread = review.addMessage(id, "agent", text, false, seenThroughMs, more, parseSuggestedReply(body?.suggestedReply));
+			const thread = review.addMessage(id, "agent", text, false, seenThroughMs, more, parseSuggestedReply(body?.suggestedReply), prComment);
 			if (!thread) return c.json({ error: "no such thread" }, 404);
 			if (waitedMs !== null) review.annotateAgentReplies([thread.id], waitedMs);
 			return c.json({
@@ -6942,7 +7495,7 @@ function createApp(ctx, store, review, queue) {
 			...note !== void 0 ? { note } : {}
 		};
 	};
-	const activeThreads = (threads) => threadsInChangeset(store?.get().files ?? [], threads).active.filter((t) => !isPublic(t));
+	const activeThreads = (threads) => threadsInChangeset(store?.get().files ?? [], threads, review?.get().layers).active.filter((t) => !isPublic(t));
 	const flushableIds = (threads) => new Set(activeThreads(threads).filter((t) => !untouchedAgentVoice(t)).map((t) => t.id));
 	const projectFinish = (threads) => {
 		const flushable = flushableIds(threads);
@@ -7004,6 +7557,7 @@ function createApp(ctx, store, review, queue) {
 			}, coverage),
 			...leg ? { public: {
 				...describeLeg(leg),
+				undecidedSuggestions: before.filter((t) => liveSuggestion(t) !== null).length,
 				canApprove: pr ? !pr.viewer.isAuthor : true,
 				pendingReview: (review.get().pr?.pendingReviewId ?? pr?.viewer.pendingReviewId ?? null) !== null
 			} } : {}
@@ -7029,7 +7583,8 @@ function createApp(ctx, store, review, queue) {
 					event,
 					comments: publicOutcome.posted,
 					body: coverage.note ?? "",
-					...publicOutcome.url ? { url: publicOutcome.url } : {}
+					...publicOutcome.url ? { url: publicOutcome.url } : {},
+					suggestions: suggestionsSummary(review.get().threads)
 				});
 				ctx.pr.refresh?.();
 			}
@@ -7212,6 +7767,16 @@ function createApp(ctx, store, review, queue) {
 			}
 		});
 	});
+	app.post("/api/agent/arrive", (c) => {
+		if (!queue) return c.json({ error: "agent queue unavailable" }, 503);
+		if (!c.req.header("x-diffo-agent") && !c.req.header("x-diffo-session-pid")) return c.json({ error: "agent arrivals must send the x-diffo-agent header" }, 403);
+		const arrived = queue.agentArrived(parseSessionPid(c.req.header("x-diffo-session-pid")));
+		return c.json({
+			ok: true,
+			arrived,
+			presence: queue.presence()
+		});
+	});
 	app.post("/api/agent/end", (c) => {
 		if (!queue) return c.json({ error: "agent queue unavailable" }, 503);
 		const sessionPid = parseSessionPid(c.req.header("x-diffo-session-pid"));
@@ -8242,6 +8807,23 @@ async function announceOpen(port) {
 		});
 	} catch {}
 }
+/**
+* An agent opened the review (piped stdout, like `printAgentNextStep`): tell
+* the server it is here before the URL prints, so the reviewer who opens the
+* page while the guide is being written sees an agent orienting itself, not
+* "no agent" and an Invite. A human's terminal open says nothing — the
+* reviewer IS the opener, and the chip must keep offering the invite.
+*/
+async function announceArrival(port) {
+	if (process.stdout.isTTY) return;
+	try {
+		await fetch(apiUrl(port, "/api/agent/arrive"), {
+			method: "POST",
+			headers: sessionHeaders(),
+			signal: AbortSignal.timeout(2e3)
+		});
+	} catch {}
+}
 async function fetchChangesetInfo(port) {
 	try {
 		return await (await fetch(apiUrl(port, "/api/changeset"), { signal: AbortSignal.timeout(2e3) })).json();
@@ -8433,16 +9015,19 @@ if (command.kind === "reply") {
 		author: "agent",
 		text: message,
 		...command.more ? { more: true } : {},
-		...command.suggestReply ? { suggestedReply: command.suggestReply } : {}
+		...command.suggestReply ? { suggestedReply: command.suggestReply } : {},
+		...command.prComment ? { prComment: command.prComment } : {}
 	});
 	if (status === 404) fail(`no thread with id '${command.threadId}'`);
+	if (status === 400) fail(`reply refused: ${body?.error ?? "bad request"}`);
 	if (status !== 200) fail(`reply failed (${status})`);
 	const thread = body.thread;
 	console.log(JSON.stringify({
 		ok: true,
 		threadId: thread.id,
 		state: thread.state,
-		next_step: command.more ? ACK_NEXT_STEP.replyMore : ACK_NEXT_STEP.reply
+		...command.prComment ? { prComment: "suggested" } : {},
+		next_step: command.more ? ACK_NEXT_STEP.replyMore : command.prComment ? ACK_NEXT_STEP.replyPrComment : ACK_NEXT_STEP.reply
 	}));
 	process.exit(0);
 }
@@ -8455,13 +9040,16 @@ if (command.kind === "comment") {
 		file: command.file,
 		line: command.line,
 		text: message,
-		...command.suggestReply ? { suggestedReply: command.suggestReply } : {}
+		...command.suggestReply ? { suggestedReply: command.suggestReply } : {},
+		...command.prComment ? { prComment: command.prComment } : {}
 	});
+	if (status === 400) fail(`comment refused: ${body?.error ?? "bad request"}`);
 	if (status !== 200) fail(`comment failed (${status})`);
 	console.log(JSON.stringify({
 		ok: true,
 		threadId: body.id,
-		next_step: ACK_NEXT_STEP.comment
+		...command.prComment ? { prComment: "suggested" } : {},
+		next_step: command.prComment ? ACK_NEXT_STEP.commentPrComment : ACK_NEXT_STEP.comment
 	}));
 	process.exit(0);
 }
@@ -8624,6 +9212,7 @@ if (existing !== null && takeOverPort === null) {
 	console.log(prOpen ? "diffo is already watching this pull request" : "diffo is already watching this repo");
 	await warnSpecMismatch(existing.port, spec);
 	await announceOpen(existing.port);
+	await announceArrival(existing.port);
 	console.log(`→ ${url}`);
 	await printAgentNextStep(existing.port, prOpen?.pr);
 	process.exit(0);
@@ -8644,6 +9233,7 @@ if (existing !== null && takeOverPort !== null) {
 if (!command.foreground) {
 	const daemonPort = await requireServer(command.port, spec.kind === "branch" ? spec.base : void 0, SRC_STAMP, prOpen ? command.target : void 0);
 	await announceOpen(daemonPort);
+	await announceArrival(daemonPort);
 	const url = reviewUrl(daemonPort);
 	await printChangesetSummary(daemonPort);
 	console.log(`→ ${url}`);