@diffohq/diffo 0.1.0 → 0.3.0

package/dist/cli.mjs

@@ -94,6 +94,18 @@ function untouchedAgentVoice(thread) {
 function undeliveredThreadIds(threads) {
 	return threads.filter((t) => (t.state === "sent" || t.state === "addressed") && t.unanswered !== true && t.withheld !== true && t.messages.at(-1)?.author === "reviewer").sort((a, b) => (a.sentAt ?? "").localeCompare(b.sentAt ?? "")).map((t) => t.id);
 }
+/**
+* Whatever the agent sent, made fit to be a tab's name: controls stripped,
+* whitespace collapsed to one line, capped. Null for anything that isn't a
+* usable title — the caller then leaves the existing name alone rather than
+* blanking it.
+*/
+function normalizeTitle(raw) {
+	if (typeof raw !== "string") return null;
+	const line = raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim();
+	if (line === "") return null;
+	return line.length > 40 ? `${line.slice(0, 39).trimEnd()}…` : line;
+}
 const EMPTY_REVIEW = {
 	version: 1,
 	threads: []
@@ -193,6 +205,7 @@ function buildCliCommands(cli) {
 	return {
 		open: cli,
 		poll: `${cli} poll`,
+		firstPoll: `${cli} poll --title "<the change, in 2-3 words>"`,
 		reply: `${cli} reply <threadId> --message "<your reply>"`,
 		comment: `${cli} comment [<file>] [--line <line>] --message "<comment>"`,
 		guide: `${cli} comment --message "<what the change does>"`,
@@ -217,14 +230,37 @@ const INSTALL_SKILL = {
 * restates how to hold the poll — attended, never detached. Mirrors the skill.
 */
 const POLL_STANCE = "a tracked background task if your harness has one, the foreground if not — never a detached process";
-const JOIN_PROMPT = `join the diffo review: run \`${CLI_COMMANDS.poll}\` (${POLL_STANCE}) and follow the JSON payload it prints — each payload carries its own instructions`;
+/**
+* The tab-title doctrine — the few words an agent hands its first poll, which
+* become the browser tab's name. Stated once and interpolated into every
+* surface that teaches it (the skill, `help agent`, the open-time next step),
+* the same way GUIDE and POLL_STANCE keep their rules from drifting apart.
+*
+* It exists because a reviewer keeps several reviews open and every tab reads
+* "Diffo": the agent is the only party that knows which is which at the moment
+* it starts listening.
+*/
+const TAB_TITLE = {
+	/** What to write — and how little room there is to write it in. */
+	what: "two or three words naming what the change IS, not what you did to it — about 20 characters, because that is all a browser tab shows",
+	/** Why it is worth a flag at all — the reviewer's problem, stated once. */
+	why: "it becomes the name of the reviewer's browser tab, and a reviewer with several reviews open sees every one of them titled \"Diffo\"",
+	/** How to order the words, given where they are read. */
+	shape: "the tab cuts off everything past that, so the word telling this review apart from another goes first, not last",
+	/** When to send it — and when not to bother. */
+	when: "on your first poll of a review; on a later one only if the changeset has become something the old title no longer names",
+	/** Two to copy the register from — both fit a tab whole. */
+	examples: "\"tab titles\", \"flaky upload retries\""
+};
+const JOIN_PROMPT = `join the diffo review: run \`${CLI_COMMANDS.firstPoll}\` (${POLL_STANCE}; the title is ${TAB_TITLE.what} — ${TAB_TITLE.why}) and follow the JSON payload it prints — each payload carries its own instructions`;
 function nextStepFor(kind, actionable) {
-	if (kind === "cleared") return `Post the guide if this changeset warrants one, then run \`${CLI_COMMANDS.poll}\` again to keep listening (${POLL_STANCE}).`;
+	if (kind === "cleared") return `Post the guide if this changeset warrants one, then run \`${CLI_COMMANDS.firstPoll}\` again to keep listening (${POLL_STANCE}) — this is a fresh round, so give it a fresh title.`;
 	if (kind === "finish" && actionable === 0) return `Nothing to act on — run \`${CLI_COMMANDS.poll}\` again to keep listening (${POLL_STANCE}); the reviewer may follow up.`;
 	return `${kind === "finish" ? "The reviewer is done reading — work the whole batch. " : ""}Act on each thread, reply with \`${CLI_COMMANDS.reply}\`, then run \`${CLI_COMMANDS.poll}\` again to keep listening.`;
 }
 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}\`.`,
 	end: "Detached. Do not reopen or re-poll this review unless the user asks — deliver anything remaining directly in the conversation."
 };
@@ -250,9 +286,15 @@ const GUIDE = {
 * The skill teaches the same step, but this line is what an agent WITHOUT the
 * skill sees — payloads and command output must stand alone (see POLL_STANCE).
 */
+/**
+* The URL goes out before the guide, never after: composing a guide is the
+* slowest step of an open (a diagram takes real thought), and a reviewer who
+* is waiting for a link should not wait on it. The guide lands live at the top
+* of their review while they are still opening the page.
+*/
 function guideNudge(hasGuide) {
 	if (hasGuide) return null;
-	return `orient the reviewer before sharing the URL, if this changeset needs it (${GUIDE.when}): post a guide — one comment on the whole changeset: ${GUIDE.what}: \`${CLI_COMMANDS.guide}\` (no file, so it anchors to the changeset). ${GUIDE.stance}.`;
+	return `share the URL above with the user right now, as a message line, before anything else. Then, while they open it, orient them if this changeset needs it (${GUIDE.when}): post a guide — one comment on the whole changeset: ${GUIDE.what}: \`${CLI_COMMANDS.guide}\` (no file, so it anchors to the changeset; it appears live at the top of their review). ${GUIDE.stance}.`;
 }
 /**
 * Printed to stderr when a poll takes the review over and the review already
@@ -271,6 +313,11 @@ const INTENT_CONTRACT = {
 	fix: "- `issue` threads want a code change. Address each one, or push back in the thread with your reasoning."
 };
 const UNLABELED_CONTRACT = "- Unlabeled threads: judge from the text — a question wants an answer, not an edit.";
+/** The agent spoke last: the thread is answered until the reviewer says more.
+* A reply that promised a follow-up (`--more`) is not an answer yet. */
+function answeredByAgent(thread) {
+	return thread.messages.at(-1)?.author === "agent" && thread.awaitingFollowUp !== true;
+}
 /** The closing note is the reviewer summing up, so it earns an answer even when it
 * asks nothing — a note with no reply is the review's one dead end. */
 const CLOSING_CONTRACT = "- The closing note speaks for the whole review: read it first, and reply to it — briefly if it only sums up, in full if it asks something.";
@@ -281,9 +328,34 @@ function intentContract(threads) {
 	if (threads.some((t) => t.closingNote)) lines.push(CLOSING_CONTRACT);
 	return lines;
 }
-function replyProtocol(threads) {
+/**
+* The short form, for a session that already received the full protocol this
+* attachment (tracked per session pid by the DeliveryQueue). The full text is
+* ~580 tokens and re-shipping it with every delivery was the loop's largest
+* recurring cost; the compact form keeps only the per-batch contract — intent
+* rules, the reply command, the re-poll — plus the pointer that reprints the rest.
+*/
+function compactProtocol(threads) {
+	return `## How to respond
+
+Same protocol as your earlier deliveries (\`${CLI} help agent\` reprints it in full):
+
+1. Act on each thread.
+${intentContract(threads).map((line) => `   ${line}`).join("\n")}
+2. Reply per thread as soon as it is handled — what changed and where (\`file:line\`), verify it the cheapest honest way first:
+
+   ${CLI_COMMANDS.reply}
+
+3. When every thread is handled, run \`${CLI_COMMANDS.poll}\` again to keep listening.
+
+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.`;
+}
+function replyProtocol(threads, mode = "full") {
+	if (mode === "compact") return compactProtocol(threads);
 	const batchNote = threads.length > 1 ? "\nRead every thread before you start editing — threads can touch the same\ncode, and an edit for one can move what another is anchored to.\n" : "";
-	const answeredNote = threads.some((t) => t.messages.at(-1)?.author === "agent") ? ["   - Some threads end with your own earlier reply — if nothing new was asked since, don't reply to them again."] : [];
+	const answeredNote = threads.some((t) => answeredByAgent(t)) ? ["   - Some threads end with your own earlier reply — if nothing new was asked since, don't reply to them again."] : [];
 	return `## How to respond
 
 Diffo is running locally; talk to it through its CLI.
@@ -303,6 +375,10 @@ ${[...intentContract(threads).map((line) => `   ${line}`), ...answeredNote].join
    is fixed, verify it the cheapest honest way (run the relevant test, re-read
    the change) and mention what you checked.
    Reply as soon as a thread is handled; don't save replies for the end.
+   A reply that only promises a follow-up ("I'll investigate and report
+   back") is not an answer — post it with \`--more\` so the reviewer keeps
+   seeing you at work on that thread, then post the real answer as a plain
+   reply (no \`--more\`) before your next poll.
    Replies and comment threads render GitHub-flavored markdown, and a
    \`\`\`mermaid fence renders as a diagram — use one when a flow, sequence,
    or state picture explains the change better than prose. Keep it small
@@ -418,6 +494,7 @@ function snapshotBlock(thread) {
 	}
 	const lines = codeContext.split("\n");
 	const where = thread.anchor.kind === "changeset" ? "the file" : `\`${thread.anchor.path}\``;
+	if (thread.deliveredThrough) return [`(diff snapshot delivered to you earlier — read the current ${where} instead)`];
 	if (!anchored) return [
 		"The commented change:",
 		"```diff",
@@ -457,7 +534,7 @@ function buildThreadPrompt(thread, ctx) {
 		threadBlock(thread, 0),
 		"",
 		...siblings ? [siblings, ""] : [],
-		replyProtocol([thread]),
+		replyProtocol([thread], ctx.protocol),
 		""
 	].join("\n");
 }
@@ -469,7 +546,7 @@ function buildCoalescedPrompt(threads, ctx) {
 		...ctx.changeset ? [specLine(ctx.changeset), ""] : [],
 		...threads.map((t, i) => `${threadBlock(t, i)}\n`),
 		...siblings ? [siblings, ""] : [],
-		replyProtocol(threads),
+		replyProtocol(threads, ctx.protocol),
 		""
 	].join("\n");
 }
@@ -494,7 +571,9 @@ function buildFinishPrompt(threads, ctx, coverage) {
 	const repo = ctx.repo;
 	const sent = threads.filter((t) => t.state === "sent");
 	const closing = sent.find((t) => t.closingNote);
-	const actionable = closing ? [closing, ...sent.filter((t) => t !== closing)] : sent;
+	const ordered = closing ? [closing, ...sent.filter((t) => t !== closing)] : sent;
+	const answered = ordered.filter((t) => t !== closing && answeredByAgent(t));
+	const actionable = ordered.filter((t) => !answered.includes(t));
 	const changed = coverage.changedFiles ?? [];
 	const commented = coverage.commentedUnread ?? [];
 	const filtered = coverage.filteredOut ?? [];
@@ -523,11 +602,12 @@ function buildFinishPrompt(threads, ctx, coverage) {
 		"",
 		...owedLines
 	];
+	if (answered.length > 0) parts.push(`${answered.length} thread${answered.length === 1 ? "" : "s"} you already answered, with nothing new since — no reply owed, not repeated here:`, ...answered.map((t) => `- ${t.id} — ${describeAnchor(t.anchor)}`), "");
 	if (coverage.skippedFiles.length > 0) parts.push("The reviewer left the not-marked-read files unread. If any of them hide", "a risky or subtle change you made, say so in a comment thread", `(\`${CLI_COMMANDS.comment}\`) — the reviewer replies to take it up, or resolves it.`, "");
 	if (actionable.length === 0) {
 		const fullRead = coverage.totalHunks > 0 && coverage.viewedHunks >= coverage.totalHunks && changed.length === 0 && commented.length === 0 && filtered.length === 0 && coverage.skippedFiles.length === 0;
 		parts.push(fullRead && coverage.note === void 0 ? "They read everything and left nothing to address — take it as a green light to proceed." : "No open review threads — nothing to act on.", `Run \`${CLI_COMMANDS.poll}\` again to keep listening (${POLL_STANCE});`, "the reviewer may follow up.", "");
-	} else parts.push(`${actionable.length} review thread${actionable.length === 1 ? "" : "s"} to act on:`, "", ...actionable.map((t, i) => `${threadBlock(t, i)}\n`), replyProtocol(actionable), "");
+	} else parts.push(`${actionable.length} review thread${actionable.length === 1 ? "" : "s"} to act on:`, "", ...actionable.map((t, i) => `${threadBlock(t, i)}\n`), replyProtocol(actionable, ctx.protocol), "");
 	return parts.join("\n");
 }
 //#endregion
@@ -549,6 +629,8 @@ For the reviewer:
 For the agent (the AI that wrote the change):
   poll               Wait for the reviewer's feedback (blocking long-poll;
                      prints one JSON payload; safe to re-run any time)
+                     (--title "<what the change is>" on the first poll names
+                     the reviewer's browser tab)
   reply <threadId>   Post a reply to a review thread
                      (--message "<text>", or pipe the text on stdin)
   comment [<file>]   Start a comment thread as the agent — on a line (--line),
@@ -588,23 +670,36 @@ The loop:
 
 1. Open: run \`diffo --no-open\` from inside the repo. It returns straight
    away, leaving a background server watching the working tree. Never open a
-   browser at the reviewer — end your message with the printed URL instead,
-   and keep ending every message with it while you stay attached.
-2. Guide (only when the changeset needs it — ${GUIDE.when}): before sharing
-   the URL, post ONE comment on the whole changeset (\`diffo comment -m "…"\`,
-   no file): ${GUIDE.what}.
-   ${GUIDE.stance}. If the changeset later shifts under the guide,
-   ${GUIDE.update}.
-3. Listen: run \`diffo poll\` — it blocks until the reviewer acts, then prints
-   one JSON payload naming the threads to act on. Run it attended:
-   ${POLL_STANCE}.
+   browser at the reviewer — share the printed URL instead, the moment it
+   prints: a message line right after this command, before the guide, the
+   poll, or anything else. Then end your message with it too, and keep
+   ending every message with it while you stay attached.
+   Attached without ever seeing the URL (a takeover, a fresh session)?
+   \`diffo status\` prints it.
+2. Guide — post one only when the changeset needs orientation:
+   ${GUIDE.when}.
+   Right after sharing the URL, while the reviewer opens the page, post ONE
+   comment on the whole changeset (\`diffo comment -m "…"\`, no file),
+   containing: ${GUIDE.what}.
+   ${GUIDE.stance}.
+   It lands live at the top of their review — never hold the URL back for it.
+   If the changeset later shifts under the guide, ${GUIDE.update}.
+3. Listen: run \`${CLI_COMMANDS.firstPoll}\` — it blocks until the reviewer
+   acts, then prints one JSON payload naming the threads to act on. Run it
+   attended: ${POLL_STANCE}.
+   The title is ${TAB_TITLE.what}: ${TAB_TITLE.why}. Write it the way it is
+   read — ${TAB_TITLE.shape} (${TAB_TITLE.examples}). Send it ${TAB_TITLE.when};
+   every other poll is a plain \`diffo poll\`.
    Killed or timed out? Re-run it; feedback is held in the review, not the
    poll.
 4. Act: \`[issue]\` threads want a code change; \`[question]\` threads want an
    answer in the reply and no edit. Your edits reach the reviewer live.
 5. Reply: \`diffo reply <threadId> --message "<text>"\` (pipe long replies on
    stdin) — concise, addressed to the reviewer. Markdown renders; a
-   \`\`\`mermaid fence draws a diagram.
+   \`\`\`mermaid fence draws a diagram. A reply that only promises a
+   follow-up ("I'll investigate and report back") goes out with \`--more\` —
+   the reviewer keeps seeing you at work — and the real answer follows as a
+   plain reply before the next poll.
 6. Comment (sparingly): \`diffo comment [<file>] [--line <n>] -m "<text>"\`
    starts a thread in your voice — a concern, or context that helps the read.
 7. Poll again only when the whole batch is handled — a new poll tells the
@@ -615,11 +710,13 @@ Rules:
 - Change only what the threads ask about — the reviewer is mid-read, and an
   unrelated edit moves the diff under them.
 - One attached agent at a time: the newest poll carries the review; don't
-  re-poll to take it back from another session — tell the user instead.
+  re-poll to take it back from another session — tell the user instead. When
+  a poll says it took the review over, or returns status "superseded", say so
+  to the user: their feedback moved with it.
 - Resolving a thread is the reviewer's call, never yours.`,
 	poll: `diffo poll — wait for the reviewer's feedback
 
-Usage: diffo poll
+Usage: diffo poll [--title "<what the change is>"]
 
 Blocks (streaming whitespace heartbeats) until the reviewer acts, then prints
 one JSON payload naming the review threads to act on, and exits. Run it
@@ -628,10 +725,15 @@ payload that reaches a process nobody is listening to never reaches you.
 Safe to re-run any time: feedback is held in the review itself, so
 nothing is lost when a poll is killed or times out — the next poll gets it.
 
+--title is ${TAB_TITLE.what}: ${TAB_TITLE.why}. Write it the way it is read —
+${TAB_TITLE.shape} (${TAB_TITLE.examples}). Send it ${TAB_TITLE.when}; the
+newest title wins, and a poll without one leaves the name it finds alone.
+
 Output: one JSON object, e.g.
   {"status":"feedback","threadIds":["t-3"],"prompt":"…what to do…"}
 
-Example:
+Examples:
+  diffo poll --title "tab titles from the agent"
   diffo poll`,
 	reply: `diffo reply — post a reply to a review thread
 
@@ -640,6 +742,10 @@ Usage: diffo reply <threadId> --message "<text>"
 
 Thread ids arrive in poll payloads. Each run posts one message, so don't
 re-run a reply that succeeded.
+--more marks the reply as interim: you are still working, and a follow-up
+reply on this thread is promised. The reviewer keeps seeing the thread as
+"with the agent" until your next plain reply; going quiet instead marks it
+unanswered.
 Messages render GitHub-flavored markdown; a \`\`\`mermaid fence renders as a
 diagram in the review.
 
@@ -878,6 +984,8 @@ function parseVerb(verb, rest) {
 				short: "m"
 			},
 			line: { type: "string" },
+			title: { type: "string" },
+			more: { type: "boolean" },
 			json: { type: "boolean" },
 			help: {
 				type: "boolean",
@@ -898,6 +1006,14 @@ function parseVerb(verb, rest) {
 		kind: "error",
 		message: `'${verb}' takes no --json`
 	};
+	if (values.more && verb !== "reply") return {
+		kind: "error",
+		message: `'${verb}' takes no --more`
+	};
+	if (values.title !== void 0 && verb !== "poll") return {
+		kind: "error",
+		message: `'${verb}' takes no --title`
+	};
 	if (verb === "poll" || verb === "end" || verb === "setup" || verb === "status" || verb === "stop") {
 		if (positionals.length > 0) return {
 			kind: "error",
@@ -911,6 +1027,17 @@ function parseVerb(verb, rest) {
 			kind: "status",
 			json: values.json === true
 		};
+		if (verb === "poll") {
+			const title = normalizeTitle(values.title);
+			if (values.title !== void 0 && title === null) return {
+				kind: "error",
+				message: "--title needs a few words naming the change"
+			};
+			return {
+				kind: "poll",
+				title
+			};
+		}
 		return { kind: verb };
 	}
 	if (verb === "reply") {
@@ -930,7 +1057,8 @@ function parseVerb(verb, rest) {
 		return {
 			kind: "reply",
 			threadId,
-			message: values.message ?? null
+			message: values.message ?? null,
+			more: values.more === true
 		};
 	}
 	const file = positionals[0] ?? null;
@@ -1531,7 +1659,8 @@ var DiffoDb = class {
 			const known = /* @__PURE__ */ new Set([
 				"reviews",
 				"servers",
-				"repo_ports"
+				"repo_ports",
+				"ui_settings"
 			]);
 			const tables = this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all();
 			for (const { name } of tables) if (!known.has(name)) this.db.exec(`DROP TABLE IF EXISTS "${name.replaceAll("\"", "\"\"")}"`);
@@ -1556,6 +1685,10 @@ var DiffoDb = class {
         repo_path TEXT PRIMARY KEY,
         port      INTEGER NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS ui_settings (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
       PRAGMA user_version = ${SCHEMA_VERSION};
     `);
 		this.pruneVanishedRepos();
@@ -1631,6 +1764,16 @@ var DiffoDb = class {
 		this.db.prepare(`INSERT INTO repo_ports (repo_path, port) VALUES (?, ?)
          ON CONFLICT(repo_path) DO UPDATE SET port = excluded.port`).run(repoPath, port);
 	}
+	/** Reviewer preferences that must outlive one server's origin — every repo is
+	* served from its own port, so localStorage alone can't hold a choice like
+	* the theme. Keyed blobs, no scope: these are per-human, not per-repo. */
+	getUiSetting(key) {
+		return this.db.prepare("SELECT value FROM ui_settings WHERE key = ?").get(key)?.value ?? null;
+	}
+	setUiSetting(key, value) {
+		this.db.prepare(`INSERT INTO ui_settings (key, value) VALUES (?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(key, value);
+	}
 	getServer(repoPath) {
 		const row = this.db.prepare("SELECT port, pid, started_at FROM servers WHERE repo_path = ?").get(repoPath);
 		return row ? {
@@ -1710,6 +1853,11 @@ var DeliveryQueue = class DeliveryQueue {
 		reason: "no-agent"
 	};
 	owner = null;
+	/** The session pid that last received the full reply protocol. Later
+	* deliveries to the same session carry the compact form — the full text is
+	* the loop's largest recurring token cost. A takeover (new pid) or an
+	* anonymous session (null pid) always gets the full form again. */
+	protocolPid = null;
 	batch = null;
 	batchWatch = null;
 	waiterWatch = null;
@@ -1770,6 +1918,12 @@ var DeliveryQueue = class DeliveryQueue {
 	ownerPid() {
 		return this.ownerConnected() ? this.owner : null;
 	}
+	needsFullProtocol() {
+		return this.owner === null || this.owner !== this.protocolPid;
+	}
+	markProtocolSent() {
+		this.protocolPid = this.owner;
+	}
 	/**
 	* A poll attaches for its session; the newest poll always carries the review.
 	* Returns the pid of a still-live session it took the review from, so both
@@ -2045,10 +2199,19 @@ var DeliveryQueue = class DeliveryQueue {
 		this.notify();
 	}
 	/** The agent replied on a thread. Returns how long since that thread's feedback
-	* was delivered, or null when the reply wasn't an answer to a delivery. */
-	agentReplied(threadId) {
+	* was delivered, or null when the reply wasn't an answer to a delivery.
+	* `interim` (a `--more` reply) keeps the thread on the clock: a follow-up is
+	* still owed, so the spinner stays and a batch that closes without the
+	* follow-up counts the thread unanswered. */
+	agentReplied(threadId, interim = false) {
 		const at = this.deliveredAt.get(threadId);
-		this.deliveredAt.delete(threadId);
+		if (!interim) this.deliveredAt.delete(threadId);
+		else if (at === void 0 && this.batch) {
+			this.deliveredAt.set(threadId, Date.now());
+			if (!this.batch.threadIds.includes(threadId)) this.batch.threadIds.push(threadId);
+			this.awaitingReply = true;
+			this.clearGrace();
+		}
 		if (this.batch) this.batch.sawReply = true;
 		if (this.deliveredAt.size > 0) {
 			if (this.awaitingReply) {
@@ -2328,7 +2491,7 @@ 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) {
+	addMessage(threadId, author, text, withheld = false, seenThroughMs, followUp = false) {
 		return this.update(threadId, ({ unanswered: _answered, ...thread }) => {
 			const message = {
 				id: randomUUID(),
@@ -2336,9 +2499,11 @@ var ReviewStore = class {
 				text,
 				at: (/* @__PURE__ */ new Date()).toISOString()
 			};
-			const raced = author === "agent" && seenThroughMs !== void 0 ? thread.messages.findIndex((m) => Date.parse(m.at) > seenThroughMs) : -1;
+			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;
 			return {
-				...thread,
+				...author === "agent" ? settled : thread,
+				...author === "agent" && followUp ? { awaitingFollowUp: true } : {},
 				...withheld && author === "reviewer" ? { withheld: true } : {},
 				messages: raced === -1 ? [...thread.messages, message] : [
 					...thread.messages.slice(0, raced),
@@ -2387,7 +2552,7 @@ var ReviewStore = class {
 		const threads = this.state.threads.map((thread) => {
 			if (!wanted.has(thread.id) || !applies(thread)) return thread;
 			changed = true;
-			const { unanswered: _was, ...rest } = thread;
+			const { unanswered: _was, awaitingFollowUp: _promised, ...rest } = thread;
 			return thread.unanswered ? rest : {
 				...rest,
 				unanswered: true
@@ -2401,8 +2566,9 @@ var ReviewStore = class {
 		this.commit();
 	}
 	setState(threadId, state) {
-		return this.update(threadId, (thread) => ({
+		return this.update(threadId, ({ awaitingFollowUp: promised, ...thread }) => ({
 			...thread,
+			...promised && state !== "resolved" ? { awaitingFollowUp: true } : {},
 			state,
 			...state === "sent" && !thread.sentAt ? { sentAt: (/* @__PURE__ */ new Date()).toISOString() } : {},
 			...state === "resolved" ? { codeContext: null } : {}
@@ -2419,16 +2585,18 @@ var ReviewStore = class {
 		return true;
 	}
 	/**
-	* Start the review over: threads, the last-finish record, and the landed
-	* marker all go. Not just the threads — a kept `lastFinish` would carry hunk
-	* ids from the dead changeset into the next review's "since last review"
-	* lens, reporting everything as new. `seenHead` survives: it describes the
+	* Start the review over: threads, the last-finish record, the landed marker,
+	* and the tab title all go. Not just the threads — a kept `lastFinish` would
+	* carry hunk ids from the dead changeset into the next review's "since last
+	* review" lens, reporting everything as new, and a kept title would name the
+	* work that just ended. The cleared agent is woken (see the DELETE route), so
+	* its next poll names the new round. `seenHead` survives: it describes the
 	* repo, not the review being discarded.
 	*/
 	reset() {
 		const ids = this.state.threads.map((t) => t.id);
-		if (ids.length === 0 && !this.state.lastFinish && !this.state.landed) return [];
-		const { lastFinish: _finish, landed: _landed, ...rest } = this.state;
+		if (ids.length === 0 && !this.state.lastFinish && !this.state.landed && !this.state.title) return [];
+		const { lastFinish: _finish, landed: _landed, title: _title, ...rest } = this.state;
 		this.state = {
 			...rest,
 			threads: []
@@ -2436,6 +2604,16 @@ var ReviewStore = class {
 		this.commit();
 		return ids;
 	}
+	/** The agent's name for this changeset, carried by its poll. The newest one
+	* wins: a change that grows a second subject renames its own tab. */
+	setTitle(title) {
+		if (this.state.title === title) return;
+		this.state = {
+			...this.state,
+			title
+		};
+		this.commit();
+	}
 	/** The base the work under review sits on — see `ReviewState.seenHead` for
 	* when the caller must NOT move it. */
 	noteHead(sha) {
@@ -2606,9 +2784,11 @@ function parseReview(raw) {
 	const migrated = Array.isArray(parsed.suggestions) ? parsed.suggestions.map((s) => migrateLegacySuggestion(s, now)).filter((t) => t !== null) : [];
 	const lastFinish = normalizeLastFinish(parsed.lastFinish, now);
 	const landed = normalizeLanded(parsed.landed, now);
+	const title = normalizeTitle(parsed.title);
 	return {
 		version: 1,
 		threads: [...valid, ...migrated],
+		...title ? { title } : {},
 		...lastFinish ? { lastFinish } : {},
 		...typeof parsed.seenHead === "string" && parsed.seenHead !== "" ? { seenHead: parsed.seenHead } : {},
 		...landed ? { landed } : {}
@@ -2746,6 +2926,7 @@ function normalizeThread(value, now) {
 		...anchored ? { anchored } : {},
 		codeChanged: t.codeChanged === true,
 		...t.unanswered === true ? { unanswered: true } : {},
+		...t.awaitingFollowUp === true && t.unanswered !== true ? { awaitingFollowUp: true } : {},
 		...t.closingNote === true ? { closingNote: true } : {},
 		...typeof t.sentAt === "string" ? { sentAt: t.sentAt } : {},
 		messages,
@@ -3231,6 +3412,22 @@ function createApp(ctx, store, review, queue) {
 			note: "shutting down"
 		});
 	});
+	const THEME_VALUES = /* @__PURE__ */ new Set([
+		"system",
+		"light",
+		"dark"
+	]);
+	app.get("/api/settings", (c) => {
+		const theme = ctx.uiSettings?.get("theme") ?? null;
+		return c.json({ theme: theme !== null && THEME_VALUES.has(theme) ? theme : null });
+	});
+	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);
+		return c.json({ ok: true });
+	});
 	const repoInfo = () => store?.get().repo ?? {
 		path: resolve(ctx.root),
 		name: "",
@@ -3298,9 +3495,10 @@ function createApp(ctx, store, review, queue) {
 			const id = c.req.param("id");
 			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 waitedMs = queue?.agentReplied(id) ?? null;
+			const more = body?.more === true;
+			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);
+			const thread = review.addMessage(id, "agent", text, false, seenThroughMs, more);
 			if (!thread) return c.json({ error: "no such thread" }, 404);
 			if (waitedMs !== null) review.annotateAgentReplies([thread.id], waitedMs);
 			return c.json({
@@ -3311,6 +3509,7 @@ function createApp(ctx, store, review, queue) {
 		const deliver = body?.deliver !== false;
 		let thread = review.addMessage(c.req.param("id"), "reviewer", text, !deliver);
 		if (!thread) return c.json({ error: "no such thread" }, 404);
+		if (deliver && thread.state === "open" && startedByAgent(thread)) thread = review.send(thread.id) ?? thread;
 		let delivered = false;
 		if (deliver && (thread.state === "sent" || thread.state === "addressed")) {
 			delivered = deliverThreads([thread.id]);
@@ -3360,8 +3559,9 @@ function createApp(ctx, store, review, queue) {
 		const handedOver = thread.state === "sent" || thread.state === "addressed" && thread.withheld === true;
 		const delivered = handedOver ? deliverThreads([thread.id]) : false;
 		if (handedOver) review.clearWithheld([thread.id]);
+		const current = review.get().threads.find((t) => t.id === thread.id) ?? thread;
 		return c.json({
-			thread,
+			thread: current,
 			prompt,
 			delivered,
 			presence
@@ -3479,6 +3679,7 @@ function createApp(ctx, store, review, queue) {
 	});
 	const pollPayload = (snapshot) => {
 		const threads = review?.get().threads ?? [];
+		const protocol = queue?.needsFullProtocol() === false ? "compact" : void 0;
 		if (snapshot.kind === "cleared") return {
 			status: "feedback",
 			kind: "cleared",
@@ -3493,15 +3694,22 @@ function createApp(ctx, store, review, queue) {
 			return {
 				status: "feedback",
 				kind: "finish",
-				threadIds: batch.filter((t) => t.state === "sent" && t.messages.at(-1)?.author === "reviewer").map((t) => t.id),
+				threadIds: batch.filter((t) => t.state === "sent" && !answeredByAgent(t)).map((t) => t.id),
 				prompt: buildFinishPrompt(batch, {
 					repo: repoInfo(),
-					changeset: store?.get() ?? null
+					changeset: store?.get() ?? null,
+					protocol
 				}, snapshot.coverage)
 			};
 		}
 		const delivered = threads.filter((t) => snapshot.threadIds.includes(t.id));
-		const prompt = delivered.length === 1 ? buildThreadPrompt(delivered[0], promptCtx(delivered[0].id)) : buildCoalescedPrompt(delivered, promptCtx(...snapshot.threadIds));
+		const prompt = delivered.length === 1 ? buildThreadPrompt(delivered[0], {
+			...promptCtx(delivered[0].id),
+			protocol
+		}) : buildCoalescedPrompt(delivered, {
+			...promptCtx(...snapshot.threadIds),
+			protocol
+		});
 		return {
 			status: "feedback",
 			kind: "threads",
@@ -3514,6 +3722,8 @@ function createApp(ctx, store, review, queue) {
 		if (!c.req.header("x-diffo-agent") && !c.req.header("x-diffo-session-pid")) return c.json({ error: "agent polls must send the x-diffo-agent header — use `diffo poll`" }, 403);
 		const tookOverFrom = queue.claimSession(parseSessionPid(c.req.header("x-diffo-session-pid")));
 		if (tookOverFrom !== null) c.header("x-diffo-took-over-from", String(tookOverFrom));
+		const title = normalizeTitle(c.req.query("title"));
+		if (title) review.setTitle(title);
 		const heartbeatMs = ctx.pollHeartbeatMs ?? POLL_HEARTBEAT_MS;
 		return stream(c, async (s) => {
 			let aborted = false;
@@ -3579,6 +3789,7 @@ function createApp(ctx, store, review, queue) {
 					await s.write(JSON.stringify(payload));
 					if (aborted) return;
 					queue.confirm(snapshot, payload.threadIds);
+					if (payload.threadIds.length > 0) queue.markProtocolSent();
 					review.markDelivered(payload.threadIds);
 					review.clearUnanswered(payload.threadIds);
 					if (snapshot.kind === "finish") review.markFinishCollected();
@@ -3737,6 +3948,8 @@ function markDevIndex(html, isDev) {
 	return html.replace(/<title>[^<]*<\/title>/, "<title>diffo-dev</title>").replace(/<\/head>/, "    <meta name=\"diffo-env\" content=\"development\" />\n  </head>");
 }
 function rehydrateQueue(review, queue) {
+	const promised = review.get().threads.filter((t) => t.awaitingFollowUp === true).map((t) => t.id);
+	if (promised.length > 0) review.markUnanswered(promised);
 	const state = review.get();
 	queue.enqueueThreads(undeliveredThreadIds(state.threads));
 	const finish = state.lastFinish;
@@ -3808,7 +4021,11 @@ function startServer(options) {
 	const app = createApp({
 		...options,
 		idle,
-		onShutdownRequest: options.onShutdownRequest ?? (() => process.exit(0))
+		onShutdownRequest: options.onShutdownRequest ?? (() => process.exit(0)),
+		uiSettings: {
+			get: (key) => db.getUiSetting(key),
+			set: (key, value) => db.setUiSetting(key, value)
+		}
 	}, store, review, queue);
 	const server = serve({
 		fetch: app.fetch,
@@ -4631,9 +4848,10 @@ if (command.kind === "stop") {
 }
 if (command.kind === "poll") {
 	const port = await requireServer();
-	process.stderr.write("diffo: waiting for the reviewer — keep this process attended: a tracked\nbackground task or the foreground, never detached.\nIf it is killed or times out, just re-run it: what the reviewer sent is\nheld in the review, so it outlives this poll and the server both.\n");
+	process.stderr.write("diffo: waiting for the reviewer — keep this process attended: a tracked\nbackground task or the foreground, never detached. If it dies, just\nre-run it — feedback is held in the review and survives.\n");
 	try {
-		const res = await fetch(apiUrl(port, "/api/agent/poll"), { headers: sessionHeaders() });
+		const path = command.title === null ? "/api/agent/poll" : `/api/agent/poll?title=${encodeURIComponent(command.title)}`;
+		const res = await fetch(apiUrl(port, path), { headers: sessionHeaders() });
 		if (!res.ok) fail(`poll failed (${res.status})`);
 		const tookOverFrom = res.headers.get("x-diffo-took-over-from");
 		if (tookOverFrom) {
@@ -4654,7 +4872,8 @@ if (command.kind === "reply") {
 	if (!message) fail("reply needs a message — pass --message \"<text>\" or pipe it on stdin");
 	const { status, body } = await postJson(await requireServer(), `/api/review/threads/${encodeURIComponent(command.threadId)}/messages`, {
 		author: "agent",
-		text: message
+		text: message,
+		...command.more ? { more: true } : {}
 	});
 	if (status === 404) fail(`no thread with id '${command.threadId}'`);
 	if (status !== 200) fail(`reply failed (${status})`);
@@ -4663,7 +4882,7 @@ if (command.kind === "reply") {
 		ok: true,
 		threadId: thread.id,
 		state: thread.state,
-		next_step: ACK_NEXT_STEP.reply
+		next_step: command.more ? ACK_NEXT_STEP.replyMore : ACK_NEXT_STEP.reply
 	}));
 	process.exit(0);
 }
@@ -4711,7 +4930,7 @@ async function printAgentNextStep(port) {
 	const review = await fetchReviewState(port);
 	const nudge = review ? guideNudge(findGuideThread(review) !== void 0) : null;
 	if (nudge) console.log(`first: ${nudge}`);
-	console.log("next: run `diffo poll` to receive the reviewer's feedback (`diffo help agent` prints the whole loop)");
+	console.log(`next: run \`${CLI_COMMANDS.firstPoll}\` to receive the reviewer's feedback — the title is ${TAB_TITLE.what} (${TAB_TITLE.examples}): ${TAB_TITLE.why} (\`diffo help agent\` prints the whole loop)`);
 }
 /**
 * Dev builds serve the client from the checkout's `dist/client`, which nothing