@diffohq/diffo 0.2.0 → 0.4.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,9 +205,13 @@ 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>"`,
+		layersSuggest: `${cli} layers --suggest "<why, in one line>"`,
+		layers: `${cli} layers --json '<Layer[]>'`,
+		layersStdin: `${cli} layers --stdin`,
 		end: `${cli} end`,
 		setup: `${cli} setup`
 	};
@@ -217,9 +233,32 @@ 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 === "layers") return `Post the outline with \`${CLI_COMMANDS.layers}\` (or pipe it to \`${CLI_COMMANDS.layersStdin}\`), 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.`;
 }
@@ -227,6 +266,9 @@ 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}\`.`,
+	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}\`.`,
 	end: "Detached. Do not reopen or re-poll this review unless the user asks — deliver anything remaining directly in the conversation."
 };
 /**
@@ -247,13 +289,58 @@ const GUIDE = {
 	update: "reply to your own guide thread with a short update"
 };
 /**
+* The layers doctrine — the agent's reading plan for a changeset with an order
+* worth explaining. Same single-source rule as GUIDE: the skill, `help agent`,
+* `help layers`, and the open-time nudge all interpolate these, so no surface
+* can teach a different bar for what a layer is or when to offer one.
+*
+* Layers come from the agent only. Every other tool infers a walkthrough by
+* reading the diff back; the session that wrote the code still remembers the
+* order it would explain it in, and that is the whole edge — so the doctrine is
+* about that order, and about not spending the reviewer's attention on a plan
+* a flat file list already gives them.
+*/
+const LAYERS = {
+	/** What one is. */
+	what: "one step of the change — a coherent unit you would explain in one breath — with the files that belong to it and a one- or two-sentence summary (markdown; a ```mermaid fence renders)",
+	/** How to order them. */
+	order: "the order you would explain it, not the order you wrote it — 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",
+	/** When to raise the flag at open — and that not raising it is the common case. */
+	suggest: "suggest layers when the change has an order worth explaining; a wide diff with one idea does not need them",
+	/** The one tag, and the bar for it. */
+	mechanical: "tag a layer \"kind\": \"mechanical\" only when it changes no behaviour — a rename, call sites following a signature; if unsure, don't tag",
+	/** Summaries orient reading, never pre-review: the guide's line, verbatim. */
+	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",
+	/** 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\" }] }]"
+};
+/**
 * Printed by `diffo` (open) to a piped stdout when the review has no guide yet.
 * 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 by `diffo` (open) next to the guide nudge while the review has neither
+* layers nor a suggestion. The open is the one moment the agent still holds the
+* order it would explain the change in, so the flag is raised here; the outline
+* itself waits for the reviewer to ask, because writing it is the heavy step
+* and most changesets never need it.
+*/
+function layersNudge(review) {
+	if (review.layers || review.layersSuggested) return null;
+	return `if this changeset reads better in order — ${LAYERS.suggest} — flag it: \`${CLI_COMMANDS.layersSuggest}\`, and offer it in your handoff ("say layers and I'll outline it"). Post the outline only when asked: \`${CLI_COMMANDS.layers}\` — each layer ${LAYERS.what}; ${LAYERS.order}. ${LAYERS.stance}. \`diffo help layers\` has the shape.`;
 }
 /**
 * Printed to stderr when a poll takes the review over and the review already
@@ -515,6 +602,29 @@ function buildCoalescedPrompt(threads, ctx) {
 * orientation for the fresh round, so this restates the guide doctrine the way
 * the open-time nudge does (payloads must stand alone — see POLL_STANCE).
 */
+/**
+* The reviewer pressed Outline (or refresh): the poll item that asks for the
+* layers. Standalone by the same rule as every payload — an agent with no
+* skill and no memory of `help layers` still gets the whole doctrine here.
+*/
+function buildLayersRequestPrompt(ctx, existing) {
+	const refresh = existing !== null && existing.length > 0;
+	const titles = refresh ? existing.map((l) => `"${l.title}"`).join(", ") : "";
+	return [
+		refresh ? `The reviewer asked you to refresh the layers in \`${ctx.repo.name}\` (branch \`${ctx.repo.branch}\`): the code moved since you outlined it, and files outside the outline have been gathering under "Since your review". Re-post the whole list as the change stands now.` : `The reviewer asked for layers in \`${ctx.repo.name}\` (branch \`${ctx.repo.branch}\`): outline the changeset as steps to read in order. The Layers tab reads "The agent is outlining…" until you post.`,
+		"",
+		...ctx.changeset ? [specLine(ctx.changeset), ""] : [],
+		...refresh ? [`The outline they have: ${titles}. Keep a title that still fits its step, rename or drop the ones that don't — ${LAYERS.replace}.`, ""] : [],
+		`Each layer is ${LAYERS.what}. Order: ${LAYERS.order}. ${LAYERS.mechanical}. ${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".`,
+		"",
+		`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.`,
+		"",
+		`Then run \`${CLI_COMMANDS.poll}\` again to keep listening (${POLL_STANCE}).`,
+		""
+	].join("\n");
+}
 function buildClearedPrompt(ctx) {
 	return [
 		`The reviewer cleared the review in \`${ctx.repo.name}\` (branch \`${ctx.repo.branch}\`): the previous round landed, and its threads and guide are gone. What the reviewer sees now is a fresh round.`,
@@ -570,6 +680,145 @@ function buildFinishPrompt(threads, ctx, coverage) {
 	return parts.join("\n");
 }
 //#endregion
+//#region src/shared/layers.ts
+/** A summary is one or two sentences by doctrine; this is the backstop against
+* an essay, the same cap a closing note gets. */
+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 REPO_PATH = /^[^\0]+$/;
+/**
+* Paths are relative to the repo root: no leading slash, no `..` segment, no
+* Windows drive. Unknown paths are fine — the file may land later — but a path
+* that could never name a file in this repo is a mistake worth naming now.
+*/
+function badPath(path) {
+	if (path === "" || !REPO_PATH.test(path)) return "is empty";
+	if (path.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(path)) return "is absolute — use a repo-relative path";
+	if (path.split("/").some((seg) => seg === "..")) return "escapes the repo with `..`";
+	return null;
+}
+function parseFile(raw, where) {
+	if (typeof raw === "string") {
+		const path = raw.trim();
+		const why = badPath(path.replace(/:\d+-\d+$/, ""));
+		if (why) return {
+			ok: false,
+			error: `${where}: path "${raw}" ${why}`
+		};
+		return {
+			ok: true,
+			file: path
+		};
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		error: `${where}: each file is a path string or { path, note? }`
+	};
+	const f = raw;
+	if (typeof f.path !== "string") return {
+		ok: false,
+		error: `${where}: a file object needs a "path"`
+	};
+	const path = f.path.trim();
+	const why = badPath(path.replace(/:\d+-\d+$/, ""));
+	if (why) return {
+		ok: false,
+		error: `${where}: path "${f.path}" ${why}`
+	};
+	if (f.note !== void 0 && typeof f.note !== "string") return {
+		ok: false,
+		error: `${where}: "note" on ${path} must be a string`
+	};
+	const note = typeof f.note === "string" ? oneLine(f.note, NOTE_CAP) : void 0;
+	return {
+		ok: true,
+		file: note ? {
+			path,
+			note
+		} : { path }
+	};
+}
+/** First line, trimmed, capped. Empty when nothing survives. */
+function oneLine(text, cap) {
+	const line = text.split("\n", 1)[0].trim();
+	return line.length > cap ? `${line.slice(0, cap - 1).trimEnd()}…` : line;
+}
+/** 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) {
+	if (typeof raw !== "string") return void 0;
+	const line = oneLine(raw, NOTE_CAP);
+	return line === "" ? void 0 : line;
+}
+/**
+* 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.
+*/
+function parseLayersInput(raw) {
+	if (!Array.isArray(raw)) return {
+		ok: false,
+		error: "layers must be a JSON array of layers"
+	};
+	if (raw.length === 0) return {
+		ok: false,
+		error: "layers must list at least one layer"
+	};
+	const items = [];
+	const titles = /* @__PURE__ */ new Set();
+	for (const [i, entry] of raw.entries()) {
+		const where = `layer ${i + 1}`;
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return {
+			ok: false,
+			error: `${where}: each layer is an object { title, files, summary?, kind? }`
+		};
+		const l = entry;
+		const title = typeof l.title === "string" ? oneLine(l.title, 120) : "";
+		if (title === "") return {
+			ok: false,
+			error: `${where}: needs a non-empty "title"`
+		};
+		if (titles.has(title)) return {
+			ok: false,
+			error: `${where}: title "${title}" is used twice`
+		};
+		titles.add(title);
+		if (!Array.isArray(l.files) || l.files.length === 0) return {
+			ok: false,
+			error: `${where} ("${title}"): needs a non-empty "files" list`
+		};
+		const files = [];
+		for (const f of l.files) {
+			const parsed = parseFile(f, `${where} ("${title}")`);
+			if (!parsed.ok) return parsed;
+			files.push(parsed.file);
+		}
+		if (l.summary !== void 0 && typeof l.summary !== "string") return {
+			ok: false,
+			error: `${where} ("${title}"): "summary" must be a markdown string`
+		};
+		const summary = typeof l.summary === "string" ? l.summary.trim().slice(0, SUMMARY_CAP) : "";
+		if (l.kind !== void 0 && l.kind !== "mechanical") return {
+			ok: false,
+			error: `${where} ("${title}"): "kind" can only be "mechanical" — leave it out otherwise`
+		};
+		items.push({
+			title,
+			files,
+			...summary !== "" ? { summary } : {},
+			...l.kind === "mechanical" ? { kind: "mechanical" } : {}
+		});
+	}
+	return {
+		ok: true,
+		items
+	};
+}
+//#endregion
 //#region src/cliArgs.ts
 const HELP_TEXT = `diffo — review a changeset the way you'd read a book
 
@@ -588,11 +837,16 @@ 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),
                      a file, or (with no file) the whole changeset; the
                      reviewer replies to take it up, or resolves it
+  layers             Outline the changeset as steps to read in order
+                     (--suggest ["why"] flags it at open; --json '<Layer[]>'
+                     or --stdin posts the list, replacing the last one)
   end                Detach from the review politely
   help agent         The agent's whole protocol on one page
 
@@ -627,35 +881,50 @@ 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.
+   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}.
-   Before sharing the URL, post ONE comment on the whole changeset
-   (\`diffo comment -m "…"\`, no file), containing:
-   ${GUIDE.what}.
+   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 \`diffo poll\` — it blocks until the reviewer acts, then prints
-   one JSON payload naming the threads to act on. Run it attended:
-   ${POLL_STANCE}.
+3. Layers — offer them when the changeset reads better in order:
+   ${LAYERS.suggest}.
+   Flag it at open with \`diffo layers --suggest "<why, in one line>"\` and
+   say so in your handoff ("say layers and I'll outline it"). Post the
+   outline only when the reviewer asks — in chat, or through the poll as a
+   \`"kind": "layers"\` payload: \`diffo layers --json '<Layer[]>'\`
+   (or pipe it to \`diffo layers --stdin\`). Each layer is ${LAYERS.what}.
+   Order: ${LAYERS.order}. ${LAYERS.mechanical}. ${LAYERS.stance}.
+   ${LAYERS.replace}. \`diffo help layers\` has the shape.
+4. 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
+5. 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
+6. Reply: \`diffo reply <threadId> --message "<text>"\` (pipe long replies on
    stdin) — concise, addressed to the reviewer. Markdown renders; a
    \`\`\`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>"\`
+7. 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
+8. Poll again only when the whole batch is handled — a new poll tells the
    reviewer you are done with the previous one.
-8. Detach: run \`diffo end\` when the review is over or the user moves on.
+9. Detach: run \`diffo end\` when the review is over or the user moves on.
 
 Rules:
 - Change only what the threads ask about — the reviewer is mid-read, and an
@@ -667,7 +936,7 @@ Rules:
 - 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
@@ -676,10 +945,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
 
@@ -716,6 +990,29 @@ Output: {"ok":true,"threadId":"t-1","next_step":"…"}
 
 Example:
   diffo comment src/auth.ts --line 42 --message "this branch is unreachable"`,
+	layers: `diffo layers — outline the changeset as steps to read in order
+
+Usage: diffo layers --suggest ["<why, in one line>"]   at open: this read benefits from layers
+       diffo layers --json '<Layer[]>'                 post the outline, replacing the last one
+       … | diffo layers --stdin                        the same payload, piped
+
+Each layer is ${LAYERS.what}.
+Order: ${LAYERS.order}.
+${LAYERS.mechanical}.
+${LAYERS.stance}.
+${LAYERS.replace}. Paths are relative to the repo root; an unknown path is
+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.
+
+Shape: ${LAYERS.shape}
+
+Output: {"ok":true,"layers":4,"next_step":"…"}
+        {"ok":true,"suggested":true,"next_step":"…"}
+
+Examples:
+  diffo layers --suggest "the parser change explains the rest"
+  diffo layers --json '[{"title":"Parser contract","summary":"parse() now returns null instead of throwing.","files":["src/parse.ts"]},{"title":"Callers adapted","kind":"mechanical","files":["src/cli.ts","src/api.ts"]}]'`,
 	end: `diffo end — detach from the review politely
 
 Usage: diffo end
@@ -771,6 +1068,7 @@ const VERBS = /* @__PURE__ */ new Set([
 	"poll",
 	"reply",
 	"comment",
+	"layers",
 	"end",
 	"setup",
 	"status",
@@ -920,7 +1218,78 @@ function parseCliArgs(argv) {
 		foreground: values.foreground === true
 	};
 }
+/**
+* `layers` parses on its own: its `--json` takes a value where `status --json`
+* is a switch, and its one positional is the suggestion's reason rather than a
+* file. Exactly one source per run — a post and a suggestion mean different
+* things to the review, and silently picking one would hide the other.
+*/
+function parseLayersVerb(rest) {
+	const parsed = tryParse(() => parseArgs({
+		args: rest,
+		allowPositionals: true,
+		options: {
+			json: { type: "string" },
+			stdin: { type: "boolean" },
+			suggest: { type: "boolean" },
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	}));
+	if (!parsed.ok) return {
+		kind: "error",
+		message: parsed.message
+	};
+	const { values, positionals } = parsed.value;
+	if (values.help) return {
+		kind: "help",
+		topic: "layers"
+	};
+	if ([
+		values.json !== void 0,
+		values.stdin === true,
+		values.suggest === true
+	].filter(Boolean).length !== 1) return {
+		kind: "error",
+		message: "layers takes exactly one of --json <Layer[]>, --stdin, or --suggest [\"<why>\"]"
+	};
+	if (values.suggest) {
+		if (positionals.length > 1) return {
+			kind: "error",
+			message: "--suggest takes at most one reason — quote it"
+		};
+		return {
+			kind: "layers",
+			source: {
+				kind: "suggest",
+				reason: parseSuggestReason(positionals[0]) ?? null
+			}
+		};
+	}
+	if (positionals.length > 0) return {
+		kind: "error",
+		message: "pass the layers with --json or on stdin (--stdin), not as an argument"
+	};
+	if (values.stdin) return {
+		kind: "layers",
+		source: { kind: "stdin" }
+	};
+	if (values.json.trim() === "") return {
+		kind: "error",
+		message: "--json needs a JSON array of layers — see `diffo help layers`"
+	};
+	return {
+		kind: "layers",
+		source: {
+			kind: "json",
+			text: values.json
+		}
+	};
+}
 function parseVerb(verb, rest) {
+	if (verb === "layers") return parseLayersVerb(rest);
 	const parsed = tryParse(() => parseArgs({
 		args: rest,
 		allowPositionals: true,
@@ -930,6 +1299,7 @@ function parseVerb(verb, rest) {
 				short: "m"
 			},
 			line: { type: "string" },
+			title: { type: "string" },
 			more: { type: "boolean" },
 			json: { type: "boolean" },
 			help: {
@@ -955,6 +1325,10 @@ function parseVerb(verb, rest) {
 		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",
@@ -968,6 +1342,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") {
@@ -1880,7 +2265,9 @@ var DeliveryQueue = class DeliveryQueue {
 			bucket = {
 				threads: /* @__PURE__ */ new Set(),
 				finish: null,
-				cleared: false
+				cleared: false,
+				layers: false,
+				outlining: null
 			};
 			this.buckets.set(this.scope, bucket);
 		}
@@ -1894,10 +2281,20 @@ var DeliveryQueue = class DeliveryQueue {
 	}
 	presence() {
 		if (this.awaitingReply) return "working";
+		if (this.outlining() !== null) return "working";
 		if (this.waiter) return "listening";
 		if (this.betweenPolls) return "working";
 		return "waiting";
 	}
+	/** Where the reviewer's layers request stands (see `LayersRequest`). */
+	layersRequest() {
+		if (this.outlining() !== null) return "outlining";
+		if (this.buckets.get(this.scope)?.layers) return "queued";
+		return null;
+	}
+	outlining() {
+		return this.buckets.get(this.scope)?.outlining ?? null;
+	}
 	presenceDetail() {
 		return {
 			state: this.presence(),
@@ -1907,6 +2304,7 @@ var DeliveryQueue = class DeliveryQueue {
 	}
 	reason() {
 		if (this.awaitingReply) return this.stalled ? "stalled" : "delivered";
+		if (this.outlining() !== null) return "delivered";
 		if (this.waiter) return "polling";
 		if (this.betweenPolls) return "replied";
 		return this.lastDetach ?? "no-agent";
@@ -2017,6 +2415,37 @@ var DeliveryQueue = class DeliveryQueue {
 		this.wake();
 		if (queued) this.notify();
 	}
+	/** The reviewer asked for layers — the outline, or a fresh one. Rides like
+	* the cleared heads-up: a boolean per scope, surfaced once real feedback is
+	* answered. */
+	enqueueLayers() {
+		this.bucket().layers = true;
+		const queued = this.waiter === null;
+		this.wake();
+		if (queued) this.notify();
+	}
+	/** The reviewer cleared the review: whatever request was standing is
+	* withdrawn — parked or already in the agent's hands. A post that arrives
+	* anyway still lands; the store does not consult the queue. */
+	dropLayers() {
+		const bucket = this.buckets.get(this.scope);
+		if (bucket) {
+			bucket.layers = false;
+			bucket.outlining = null;
+		}
+		this.notify();
+	}
+	/** The agent posted layers. Concludes an outstanding request; a spontaneous
+	* post concludes nothing. Returns how long the outline took, or null. */
+	layersPosted() {
+		const bucket = this.buckets.get(this.scope);
+		const since = bucket?.outlining ?? null;
+		if (bucket === void 0 || since === null) return null;
+		bucket.outlining = null;
+		if (!this.awaitingReply && !this.betweenPolls) this.armGrace();
+		this.notify();
+		return Date.now() - since;
+	}
 	drop(threadId) {
 		for (const bucket of this.buckets.values()) bucket.threads.delete(threadId);
 		this.deliveredAt.delete(threadId);
@@ -2034,6 +2463,8 @@ var DeliveryQueue = class DeliveryQueue {
 		if (this.batch !== null) {
 			if (this.batch.sawReply || Date.now() - this.batch.deliveredAt >= this.batchSettleMs) this.closeBatch("repoll");
 		}
+		const owing = this.buckets.get(this.scope);
+		if (owing !== void 0 && owing.outlining !== null && Date.now() - owing.outlining >= this.batchSettleMs) owing.outlining = null;
 		if (this.hasPending()) return Promise.resolve("data");
 		return new Promise((resolve) => {
 			const waiter = (outcome) => resolve(outcome);
@@ -2076,7 +2507,7 @@ var DeliveryQueue = class DeliveryQueue {
 	}
 	hasPending() {
 		const bucket = this.buckets.get(this.scope);
-		return bucket !== void 0 && (bucket.threads.size > 0 || bucket.finish !== null || bucket.cleared);
+		return bucket !== void 0 && (bucket.threads.size > 0 || bucket.finish !== null || bucket.cleared || bucket.layers);
 	}
 	wake() {
 		if (this.waiter === null) return;
@@ -2098,12 +2529,20 @@ var DeliveryQueue = class DeliveryQueue {
 			kind: "threads",
 			threadIds: [...bucket.threads]
 		};
+		if (bucket.layers) return { kind: "layers" };
 		if (bucket.cleared) return { kind: "cleared" };
 		return null;
 	}
 	/** The poll response for this snapshot was fully written — NOW it counts as
 	* delivered. Clears exactly what the snapshot covered. */
 	confirm(snapshot, deliveredThreadIds) {
+		if (snapshot.kind === "layers") {
+			const bucket = this.bucket();
+			bucket.layers = false;
+			bucket.outlining = Date.now();
+			this.notify();
+			return;
+		}
 		if (snapshot.kind === "cleared") {
 			const bucket = this.buckets.get(this.scope);
 			if (bucket) bucket.cleared = false;
@@ -2165,6 +2604,7 @@ var DeliveryQueue = class DeliveryQueue {
 		this.releaseWaiter("ended");
 		this.closeBatch("ended");
 		this.awaitingReply = false;
+		for (const bucket of this.buckets.values()) bucket.outlining = null;
 		this.stalled = false;
 		this.clearStall();
 		this.clearGrace();
@@ -2515,16 +2955,19 @@ 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;
+		const { lastFinish, landed, title, layers, layersSuggested } = this.state;
+		if (ids.length === 0 && !lastFinish && !landed && !title && !layers && !layersSuggested) return [];
+		const { lastFinish: _finish, landed: _landed, title: _title, layers: _layers, layersSuggested: _suggested, ...rest } = this.state;
 		this.state = {
 			...rest,
 			threads: []
@@ -2532,6 +2975,51 @@ var ReviewStore = class {
 		this.commit();
 		return ids;
 	}
+	/**
+	* Replace the reading plan — the whole list, never a merge, so the agent never
+	* has to diff its own outline. Ids are minted here and kept for any layer
+	* whose title matches an existing one: that is what holds the reviewer's
+	* active layer in place across a re-post. Posting also answers the suggestion,
+	* so it goes.
+	*/
+	setLayers(items) {
+		const kept = new Map((this.state.layers?.items ?? []).map((l) => [l.title, l.id]));
+		const layers = {
+			items: items.map((item) => ({
+				id: kept.get(item.title) ?? randomUUID(),
+				...item
+			})),
+			postedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		const { layersSuggested: _suggested, ...rest } = this.state;
+		this.state = {
+			...rest,
+			layers
+		};
+		this.commit();
+		return layers;
+	}
+	/** The agent's flag at open: this read benefits from layers. Once layers exist
+	* the flag has nothing to add, so it is refused rather than recorded. */
+	suggestLayers(reason) {
+		if (this.state.layers) return false;
+		this.state = {
+			...this.state,
+			layersSuggested: reason ? { reason } : {}
+		};
+		this.commit();
+		return true;
+	}
+	/** 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) {
@@ -2702,14 +3190,44 @@ 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);
+	const layers = normalizeLayers(parsed.layers, now);
+	const layersSuggested = normalizeSuggested(parsed.layersSuggested);
 	return {
 		version: 1,
 		threads: [...valid, ...migrated],
+		...title ? { title } : {},
 		...lastFinish ? { lastFinish } : {},
 		...typeof parsed.seenHead === "string" && parsed.seenHead !== "" ? { seenHead: parsed.seenHead } : {},
-		...landed ? { landed } : {}
+		...landed ? { landed } : {},
+		...layers ? { layers } : {},
+		...layersSuggested && !layers ? { layersSuggested } : {}
 	};
 }
+/** Stored layers go back through the same validation a post does; a list that
+* would be refused at the door is dropped whole rather than half-kept. Ids are
+* the one field a post never carries, so they are read here and re-minted only
+* when missing. */
+function normalizeLayers(value, now) {
+	if (typeof value !== "object" || value === null) return null;
+	const l = value;
+	if (!Array.isArray(l.items)) return null;
+	const parsed = parseLayersInput(l.items);
+	if (!parsed.ok) return null;
+	const ids = l.items.map((item) => typeof item === "object" && item !== null && typeof item.id === "string" ? item.id : randomUUID());
+	return {
+		items: parsed.items.map((item, i) => ({
+			id: ids[i],
+			...item
+		})),
+		postedAt: typeof l.postedAt === "string" ? l.postedAt : now
+	};
+}
+function normalizeSuggested(value) {
+	if (typeof value !== "object" || value === null) return null;
+	const reason = parseSuggestReason(value.reason);
+	return reason ? { reason } : {};
+}
 /** A landed marker without a sha can't be checked against history, so it is
 * dropped; the subject is only a caption and defaults away. */
 function normalizeLanded(value, now) {
@@ -3402,6 +3920,31 @@ function createApp(ctx, store, review, queue) {
 		const capture = store ? captureAnchor(store.get(), anchor) : null;
 		return c.json(review.createThread(anchor, text, capture, intent));
 	});
+	app.post("/api/review/layers", async (c) => {
+		if (!review) return c.json({ error: "review unavailable" }, 503);
+		const body = await c.req.json().catch(() => null);
+		if (body?.suggest === true) {
+			const suggested = review.suggestLayers(parseSuggestReason(body.reason));
+			return c.json({
+				suggested,
+				...suggested ? {} : { note: "layers are already posted — nothing to suggest" }
+			});
+		}
+		const parsed = parseLayersInput(body?.items);
+		if (!parsed.ok) return c.json({ error: parsed.error }, 400);
+		const layers = review.setLayers(parsed.items);
+		queue?.layersPosted();
+		return c.json({ layers });
+	});
+	app.post("/api/review/layers/request", (c) => {
+		if (!review || !queue) return c.json({ error: "review unavailable" }, 503);
+		queue.enqueueLayers();
+		return c.json({
+			ok: true,
+			request: queue.layersRequest(),
+			presence: queue.presence()
+		});
+	});
 	app.post("/api/review/threads/:id/messages", async (c) => {
 		if (!review) return c.json({ error: "review unavailable" }, 503);
 		const body = await c.req.json().catch(() => null);
@@ -3425,6 +3968,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]);
@@ -3450,6 +3994,7 @@ function createApp(ctx, store, review, queue) {
 		const hadRound = before.threads.length > 0 || before.lastFinish !== void 0;
 		const removed = review.reset();
 		for (const id of removed) queue?.drop(id);
+		queue?.dropLayers();
 		if (hadRound && (store?.get().files.length ?? 0) > 0) queue?.enqueueCleared();
 		return c.json({ removed: removed.length });
 	});
@@ -3474,8 +4019,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
@@ -3594,6 +4140,15 @@ 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 === "layers") return {
+			status: "feedback",
+			kind: "layers",
+			threadIds: [],
+			prompt: buildLayersRequestPrompt({
+				repo: repoInfo(),
+				changeset: store?.get() ?? null
+			}, review?.get().layers?.items ?? null)
+		};
 		if (snapshot.kind === "cleared") return {
 			status: "feedback",
 			kind: "cleared",
@@ -3636,6 +4191,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;
@@ -3790,7 +4347,8 @@ function createApp(ctx, store, review, queue) {
 					...queue.presenceDetail(),
 					workingOn: queue.deliveredThreadIds(),
 					queued: queue.queuedThreadIds(),
-					answered: queue.currentBatch()?.answered ?? []
+					answered: queue.currentBatch()?.answered ?? [],
+					layers: queue.layersRequest()
 				}),
 				id: String(id++)
 			});
@@ -3813,7 +4371,8 @@ function createApp(ctx, store, review, queue) {
 				...queue.presenceDetail(),
 				workingOn: queue.deliveredThreadIds(),
 				queued: queue.queuedThreadIds(),
-				answered: queue.currentBatch()?.answered ?? []
+				answered: queue.currentBatch()?.answered ?? [],
+				layers: queue.layersRequest()
 			}),
 			id: String(id++)
 		});
@@ -4762,7 +5321,8 @@ 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. 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) {
@@ -4815,6 +5375,44 @@ if (command.kind === "comment") {
 	}));
 	process.exit(0);
 }
+if (command.kind === "layers") {
+	const { source } = command;
+	if (source.kind === "stdin" && process.stdin.isTTY) fail("layers --stdin needs the JSON piped on stdin — or pass it with --json");
+	const port = await requireServer();
+	if (source.kind === "suggest") {
+		const { status, body } = await postJson(port, "/api/review/layers", {
+			suggest: true,
+			...source.reason === null ? {} : { reason: source.reason }
+		});
+		if (status !== 200) fail(`layers failed (${status})`);
+		const { suggested } = body;
+		console.log(JSON.stringify({
+			ok: true,
+			suggested,
+			next_step: suggested ? ACK_NEXT_STEP.layersSuggested : ACK_NEXT_STEP.layersAlready
+		}));
+		process.exit(0);
+	}
+	const text = source.kind === "json" ? source.text : await readStdin();
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		fail(`layers needs a JSON array of layers — ${err.message}`);
+	}
+	const parsed = parseLayersInput(raw);
+	if (!parsed.ok) fail(`layers: ${parsed.error}`);
+	const { status, body } = await postJson(port, "/api/review/layers", { items: parsed.items });
+	if (status === 400) fail(`layers: ${body?.error ?? "rejected"}`);
+	if (status !== 200) fail(`layers failed (${status})`);
+	const { layers } = body;
+	console.log(JSON.stringify({
+		ok: true,
+		layers: layers.items.length,
+		next_step: ACK_NEXT_STEP.layers
+	}));
+	process.exit(0);
+}
 if (command.kind === "end") {
 	const { status, body } = await postJson(await requireServer(), "/api/agent/end", {});
 	if (status !== 200) fail(`end failed (${status})`);
@@ -4841,7 +5439,9 @@ 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)");
+	const layers = review ? layersNudge(review) : null;
+	if (layers) console.log(`also: ${layers}`);
+	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