@krelborn/markdown-review 0.3.0 → 0.4.0

package/dist/cli.js

@@ -7,6 +7,7 @@ import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import path from "node:path";
 import { z } from "zod";
 import os from "node:os";
+import { parseDocument } from "yaml";
 import openInBrowser from "open";
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
@@ -43,7 +44,7 @@ function createProcessTerminal() {
 //#region src/server/runtime/packageVersion.ts
 var packageVersion = {
 	name: "@krelborn/markdown-review",
-	version: "0.3.0",
+	version: "0.4.0",
 	description: "Review agent-written markdown in the browser and hand the comments back to the agent",
 	homepage: "https://github.com/Krelborn/markdown-review#readme",
 	bugs: { "url": "https://github.com/Krelborn/markdown-review/issues" },
@@ -82,6 +83,7 @@ var packageVersion = {
 		"hono": "^4.13.13",
 		"markdown-it": "^15.0.2",
 		"open": "^11.0.4",
+		"yaml": "^2.9.1",
 		"zod": "^4.6.5"
 	},
 	devDependencies: {
@@ -113,8 +115,7 @@ var packageVersion = {
 		"shiki": "^4.5.0",
 		"typescript": "^7.0.2",
 		"vite": "^8.3.3",
-		"vitest": "^5.0.3",
-		"yaml": "^2.9.1"
+		"vitest": "^5.0.3"
 	},
 	engines: { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
 	packageManager: "pnpm@10.18.3"
@@ -292,6 +293,24 @@ var anchorSchema = z.discriminatedUnion("kind", [
 	passageAnchorSchema
 ]);
 //#endregion
+//#region src/shared/review/reviewRoundSchema.ts
+var verdictSchema = z.enum([
+	"revise",
+	"go-ahead",
+	"hand-back"
+]);
+var nextTaskSchema = z.string().trim().min(1).max(200).refine((text) => !/[\n\r\u2028\u2029]/.test(text), "must be one line");
+var reviewRoundSchema = z.strictObject({
+	documents: z.array(documentPathSchema),
+	lastOpenedAt: z.iso.datetime(),
+	nextTask: nextTaskSchema.nullable(),
+	startedAt: z.iso.datetime(),
+	verdict: z.strictObject({
+		at: z.iso.datetime(),
+		kind: verdictSchema
+	}).nullable()
+});
+//#endregion
 //#region src/shared/review/threadSchema.ts
 var messageBodySchema = z.string().refine((body) => body.trim() !== "", "must not be blank");
 var messageSchema = z.strictObject({
@@ -318,11 +337,6 @@ var threadSchema = z.strictObject({
 }).refine((thread) => thread.status === "draft" === (thread.messages.length === 0), { message: "must have messages unless it is a draft" }).refine((thread) => thread.status !== "draft" || thread.draft !== void 0, { message: "must hold its comment as a draft while it is a draft" });
 //#endregion
 //#region src/shared/api/apiResponseSchemas.ts
-var reviewStateSchema = z.strictObject({
-	approved: z.boolean(),
-	approvedAt: z.iso.datetime().nullable(),
-	requestedAt: z.iso.datetime().nullable()
-});
 /**
 * Not strict, so a newer server that reports more fields is still recognised by its protocol rather than mistaken for
 * no server
@@ -336,13 +350,13 @@ var healthSchema = z.object({
 });
 var threadsSnapshotSchema = z.strictObject({
 	problems: z.array(z.string()),
-	review: reviewStateSchema,
+	round: reviewRoundSchema.nullable(),
 	threads: z.array(threadSchema)
 });
 var pollResponseSchema = threadsSnapshotSchema.extend({ timedOut: z.boolean() });
 var agentOpenResponseSchema = z.strictObject({
 	navigated: z.boolean(),
-	review: reviewStateSchema,
+	round: reviewRoundSchema.nullable(),
 	url: z.string()
 });
 var agentThreadResponseSchema = z.strictObject({
@@ -364,6 +378,10 @@ z.strictObject({
 	path: documentPathSchema,
 	source: z.string()
 });
+z.strictObject({
+	availableVersion: z.string().nullable(),
+	command: z.string().nullable()
+});
 var apiErrorSchema = z.strictObject({ error: z.strictObject({
 	message: z.string(),
 	reason: z.string()
@@ -402,14 +420,22 @@ var ServerClient = class {
 	health() {
 		return this.request("GET", "/api/health", healthSchema, { signal: AbortSignal.timeout(healthTimeoutMilliseconds) });
 	}
-	open(document) {
-		return this.request("POST", "/api/agent/open", agentOpenResponseSchema, { body: document === null ? {} : { path: document } });
+	/**
+	* @param document the doc to show, or null for the docs list
+	* @param nextTask what the agent will do once the user says go ahead; null keeps a joined round's task and leaves a
+	*   new round without one
+	*/
+	open(document, nextTask) {
+		return this.request("POST", "/api/agent/open", agentOpenResponseSchema, { body: {
+			...document === null ? {} : { path: document },
+			...nextTask === null ? {} : { nextTask }
+		} });
 	}
 	inbox(document) {
 		return this.request("GET", `/api/inbox${documentQuery(document)}`, threadsSnapshotSchema);
 	}
 	/**
-	* Waits for the review to be approved, a thread to need the agent, or the timeout
+	* Waits for the user to end the review round, a thread to need the agent, or the timeout
 	*/
 	poll(document, timeoutSeconds, signal) {
 		const query = new URLSearchParams({ timeout: String(timeoutSeconds) });
@@ -480,11 +506,11 @@ async function findServer(root) {
 		return { kind: "absent" };
 	}
 	if (health.root !== root) return { kind: "absent" };
-	if (health.protocol < 1) return {
+	if (health.protocol < 2) return {
 		client,
 		kind: "older"
 	};
-	return health.protocol > 1 ? {
+	return health.protocol > 2 ? {
 		health,
 		kind: "newer"
 	} : {
@@ -661,6 +687,18 @@ async function findRoot(directory, outsideGitDirectory = directory) {
 	}
 }
 //#endregion
+//#region src/shared/review/roundOutcome.ts
+/**
+* Tells how the user ended a review round
+*
+* @param round the round, or null before any review was opened
+* @returns the verdict that ended the round, or null while it goes on
+*/
+function roundOutcome(round) {
+	const kind = round?.verdict?.kind;
+	return kind === "go-ahead" || kind === "hand-back" ? kind : null;
+}
+//#endregion
 //#region src/cli/formatIdList.ts
 /**
 * Lists thread IDs the way the CLI's sentences name them
@@ -684,7 +722,9 @@ var waitForCommentsStep = `Run \`markdown-review poll\` to wait for the user's c
 function waitForCommentsInRootStep(root) {
 	return `This doc belongs to the repository at ${root}, so run markdown-review commands from that directory. ` + waitForCommentsStep;
 }
-var approvedStep = "The user approved the review. Carry on with your task; do not run `markdown-review poll` again for this review.";
+var wentAheadStep = "The user said go ahead. Carry on with your task; do not run `markdown-review poll` again for this review.";
+var handedBackStep = "Stop here: do not edit the docs, run `markdown-review poll` or carry on with your task. Tell the user in the chat that you have stopped, and wait for their instructions.";
+var handedBackFinishedStep = "The user handed the review back. Tell them what you changed and wait for their instructions. Only if they ask you to continue the review, run `markdown-review open <path> --next-task \"<what you will do once the user says go ahead>\"`, then `markdown-review poll`.";
 /**
 * @param ids the threads that need the agent, at least one
 */
@@ -692,11 +732,23 @@ function addressThreadsStep(ids) {
 	return `Edit the docs, then run \`markdown-review resolve <id> "<what changed>"\` for ${formatIdList(ids)}, or \`markdown-review reply <id> "<question>"\` if you need input. Then run \`markdown-review poll\` to wait for the next round.`;
 }
 /**
-* @param ids the threads the user commented on when approving, at least one
+* @param ids the threads the user commented on when saying go ahead, at least one
 */
-function approvedWithCommentsStep(ids) {
+function wentAheadWithCommentsStep(ids) {
 	const resolveCommand = ids.length === 1 ? `\`markdown-review resolve ${ids[0]} "<what changed>"\`` : "`markdown-review resolve <id> \"<what changed>\"` for each";
-	return `The user approved the review with comments. Address ${formatIdList(ids)} and run ${resolveCommand}, then carry on with your task; do not run \`markdown-review poll\` again for this review.`;
+	return `The user said go ahead, with comments. Address ${formatIdList(ids)} and run ${resolveCommand}, then carry on with your task; do not run \`markdown-review poll\` again for this review.`;
+}
+/**
+* @param ids the threads still needing the agent after the user handed the review back, at least one
+*/
+function handedBackThreadsLeftStep(ids) {
+	return `The user handed the review back, so act on ${formatIdList(ids)} only as they ask in the chat.`;
+}
+/**
+* @param ids the threads the user commented on when handing the review back, at least one
+*/
+function handedBackWithCommentsStep(ids) {
+	return `Stop here: do not edit the docs, resolve or reply to ${formatIdList(ids)}, run \`markdown-review poll\` or carry on with your task. Tell the user in the chat that you have stopped and what their comments say, and wait for their instructions.`;
 }
 //#endregion
 //#region src/cli/formatAgentAction.ts
@@ -709,10 +761,21 @@ function approvedWithCommentsStep(ids) {
 */
 function formatAgentAction(action, { inbox, thread }) {
 	const done = action === "resolved" ? `Resolved #${thread.id}.` : `Replied to #${thread.id}; it waits for the user.`;
+	const outcome = roundOutcome(inbox.round);
 	const remaining = inbox.threads.map((remainingThread) => remainingThread.id);
-	if (remaining.length > 0) return `${done}\n${remaining.length === 1 ? "1 thread still needs you" : `${remaining.length} threads still need you`}: ${formatIdList(remaining)}.\n\nnext_step: Address ${formatIdList(remaining)}, then run \`markdown-review resolve <id> "<what changed>"\`, or \`markdown-review reply <id> "<question>"\` if you need input.
-`;
-	return `${done} No threads need you now.\n\nnext_step: ${inbox.review.approved ? approvedStep : "Run `markdown-review poll` to wait for the user's next round of comments."}\n`;
+	if (remaining.length > 0) {
+		const count = remaining.length === 1 ? "1 thread still needs you" : `${remaining.length} threads still need you`;
+		const step = outcome === "hand-back" ? handedBackThreadsLeftStep(remaining) : `Address ${formatIdList(remaining)}, then run \`markdown-review resolve <id> "<what changed>"\`, or \`markdown-review reply <id> "<question>"\` if you need input.`;
+		return `${done}\n${count}: ${formatIdList(remaining)}.\n\nnext_step: ${step}\n`;
+	}
+	return `${done} No threads need you now.\n\nnext_step: ${finishedStep(outcome)}\n`;
+}
+function finishedStep(outcome) {
+	switch (outcome) {
+		case "go-ahead": return wentAheadStep;
+		case "hand-back": return handedBackFinishedStep;
+		case null: return "Run `markdown-review poll` to wait for the user's next round of comments.";
+	}
 }
 //#endregion
 //#region src/cli/readMessageBody.ts
@@ -792,16 +855,20 @@ var quoteStartLength = 120;
 /**
 * Describes the agent's inbox as compact text for the agent to read
 *
-* @param snapshot the review state and the threads that need the agent
-* @returns the summary, each thread grouped by doc with its messages, any store problems, and a final `next_step`
+* @param snapshot the review round and the threads that need the agent
+* @param notices lines to put just before `next_step`, each ending in a newline
+* @returns the summary, which says how the user ended the round if they have, each thread grouped by doc with its
+*   messages, any store problems, the notices, and a final `next_step`
 */
-function formatInbox({ problems, review, threads }) {
+function formatInbox({ problems, round, threads }, notices = []) {
+	const outcome = roundOutcome(round);
 	const ordered = orderByDocument(threads);
 	const ids = ordered.map((thread) => thread.id);
-	const sections = [summaryLine(review.approved, ordered)];
+	const sections = [summaryLine(outcome, ordered)];
 	if (ordered.length > 0) sections.push(ordered.map(formatThread).join("\n\n"));
 	if (problems.length > 0) sections.push(problems.map((problem) => `warning: ${indentContinuation(problem, "  ")}`).join("\n"));
-	sections.push(`next_step: ${nextStep(review.approved, ids)}`);
+	if (notices.length > 0) sections.push(notices.join("").trimEnd());
+	sections.push(`next_step: ${nextStep(outcome, ids)}`);
 	return `${sections.join("\n\n")}\n`;
 }
 function formatThread(thread) {
@@ -828,20 +895,40 @@ function describeAnchor({ anchor, id }) {
 		}
 	}
 }
-function summaryLine(approved, threads) {
-	if (threads.length === 0) return approved ? "Review approved. No threads need you." : "No threads need you.";
+function summaryLine(outcome, threads) {
+	if (threads.length === 0) return noThreadsSummary(outcome);
+	const breakdown = countByGroup(threads);
+	const needs = threads.length === 1 ? "1 thread needs you" : `${threads.length} threads need you`;
+	switch (outcome) {
+		case "go-ahead": return `The user said go ahead, ${needs} (${breakdown})`;
+		case "hand-back": return `The user asked to hand back to you, with comments on ${countThreads(threads.length)} (${breakdown})`;
+		case null: return `${needs} (${breakdown})`;
+	}
+}
+function countByGroup(threads) {
 	const counts = /* @__PURE__ */ new Map();
 	for (const thread of threads) {
 		const group = thread.anchor.kind === "review" ? "review" : thread.anchor.document;
 		counts.set(group, (counts.get(group) ?? 0) + 1);
 	}
-	const breakdown = [...counts].map(([group, count]) => `${group}: ${count}`).join(", ");
-	const needs = threads.length === 1 ? "1 thread needs you" : `${threads.length} threads need you`;
-	return approved ? `Review approved, ${needs} (${breakdown})` : `${needs} (${breakdown})`;
+	return [...counts].map(([group, count]) => `${group}: ${count}`).join(", ");
 }
-function nextStep(approved, ids) {
-	if (ids.length === 0) return approved ? approvedStep : waitForCommentsStep;
-	return approved ? approvedWithCommentsStep(ids) : addressThreadsStep(ids);
+function countThreads(count) {
+	return count === 1 ? "1 thread" : `${count} threads`;
+}
+function noThreadsSummary(outcome) {
+	switch (outcome) {
+		case "go-ahead": return "The user said go ahead. No threads need you.";
+		case "hand-back": return "The user asked to hand back to you. No threads need you.";
+		case null: return "No threads need you.";
+	}
+}
+function nextStep(outcome, ids) {
+	switch (outcome) {
+		case "go-ahead": return ids.length === 0 ? wentAheadStep : wentAheadWithCommentsStep(ids);
+		case "hand-back": return ids.length === 0 ? handedBackStep : handedBackWithCommentsStep(ids);
+		case null: return ids.length === 0 ? waitForCommentsStep : addressThreadsStep(ids);
+	}
 }
 function orderByDocument(threads) {
 	const groupOf = (thread) => thread.anchor.kind === "review" ? "￿" : thread.anchor.document;
@@ -882,21 +969,319 @@ async function readDocumentOption(root, workingDirectory, value) {
 	return value === void 0 ? null : toRepositoryPath(root, path.resolve(await realpath(workingDirectory), value));
 }
 //#endregion
+//#region src/server/update/semanticVersions.ts
+var versionPattern = /^(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)(?:-(?<prerelease>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+/**
+* Orders two semantic versions by semver precedence
+*
+* @param left a version such as "0.4.0" or "0.4.0-beta.1"
+* @param right another version
+* @returns a negative number when `left` comes first, a positive number when `right` does, 0 when they are equal,
+*   and null when either is not a semantic version
+*/
+function compareVersions(left, right) {
+	const parsedLeft = parseVersion(left);
+	const parsedRight = parseVersion(right);
+	if (parsedLeft === null || parsedRight === null) return null;
+	const [leftMajor, leftMinor, leftPatch] = parsedLeft.release;
+	const [rightMajor, rightMinor, rightPatch] = parsedRight.release;
+	return leftMajor - rightMajor || leftMinor - rightMinor || leftPatch - rightPatch || comparePrereleases(parsedLeft.prerelease, parsedRight.prerelease);
+}
+/**
+* @param version a version such as "0.4.0-beta.1"
+* @returns whether it is a semantic version with a pre-release part
+*/
+function isPrerelease(version) {
+	return (parseVersion(version)?.prerelease.length ?? 0) > 0;
+}
+function parseVersion(version) {
+	const groups = versionPattern.exec(version)?.groups;
+	if (groups === void 0) return null;
+	return {
+		prerelease: groups.prerelease?.split(".") ?? [],
+		release: [
+			Number(groups.major),
+			Number(groups.minor),
+			Number(groups.patch)
+		]
+	};
+}
+function comparePrereleases(left, right) {
+	if (left.length === 0 || right.length === 0) return right.length - left.length;
+	for (const [i, leftIdentifier] of left.entries()) {
+		const rightIdentifier = right[i];
+		if (rightIdentifier === void 0) break;
+		const difference = compareIdentifiers(leftIdentifier, rightIdentifier);
+		if (difference !== 0) return difference;
+	}
+	return left.length - right.length;
+}
+function compareIdentifiers(left, right) {
+	const leftIsNumeric = /^\d+$/u.test(left);
+	const rightIsNumeric = /^\d+$/u.test(right);
+	if (leftIsNumeric && rightIsNumeric) return Number(left) - Number(right);
+	if (leftIsNumeric !== rightIsNumeric) return leftIsNumeric ? -1 : 1;
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+//#endregion
+//#region src/server/update/findAvailableUpdate.ts
+/**
+* Picks the published version to offer in place of the running one
+*
+* @param current the running version
+* @param distTags the registry's `latest` and `next` tags
+* @returns the version to offer and its dist-tag, or null when none is newer or a version cannot be read
+*/
+function findAvailableUpdate(current, distTags) {
+	const distTagNames = isPrerelease(current) ? ["latest", "next"] : ["latest"];
+	let best = null;
+	for (const distTag of distTagNames) {
+		const version = distTags[distTag];
+		if (version !== void 0 && (compareVersions(version, best?.version ?? current) ?? 0) > 0) best = {
+			distTag,
+			version
+		};
+	}
+	return best;
+}
+//#endregion
+//#region src/server/update/installCommands.ts
+/**
+* @param cliPath the real path of the running `dist/cli.js`
+* @returns how that copy of markdown-review was installed
+*/
+function findInstallKind(cliPath) {
+	return cliPath.split(path.sep).includes("_npx") ? "npx" : "global";
+}
+/**
+* @param versionOrTag the version or dist-tag to run, e.g. "latest" or "0.4.0"
+* @returns the npx command that runs that markdown-review
+*/
+function npxCommand(versionOrTag) {
+	return `npx @krelborn/markdown-review@${versionOrTag}`;
+}
+/**
+* @param kind how markdown-review is installed
+* @param args the command and its arguments, e.g. "install-skill --global"
+* @param versionOrTag for npx, the version or dist-tag to run; a global install runs whichever is installed
+* @returns the shell command that runs markdown-review with those arguments
+*/
+function cliCommand(kind, args, versionOrTag) {
+	return `${kind === "npx" ? npxCommand(versionOrTag) : "markdown-review"} ${args}`;
+}
+/**
+* @param distTag the dist-tag to install, e.g. "latest"
+* @returns the shell command that updates a global install to that dist-tag's version
+*/
+function globalInstallCommand(distTag) {
+	return `npm install --global @krelborn/markdown-review@${distTag}`;
+}
+/**
+* @param distTag the dist-tag to install, e.g. "latest"
+* @param root the repo whose review server is running the old version
+* @returns a POSIX shell command that updates a global install, then stops that repo's server from wherever it is run
+*/
+function globalUpdateCommand(distTag, root) {
+	return `${globalInstallCommand(distTag)} && (cd ${quoteForShell(root)} && markdown-review stop)`;
+}
+function quoteForShell(text) {
+	return `'${text.replaceAll("'", "'\\''")}'`;
+}
+//#endregion
+//#region src/server/update/updateCheckFileSchema.ts
+/**
+* The registry's dist-tags that matter here; any others are dropped
+*/
+var distTagsSchema = z.object({
+	latest: z.string().optional(),
+	next: z.string().optional()
+});
+/**
+* The user's update check cache: when the registry was last asked, and the dist-tags it last gave
+*/
+var updateCheckFileSchema = z.strictObject({
+	checkedAt: z.iso.datetime(),
+	distTags: distTagsSchema
+});
+//#endregion
+//#region src/server/update/readUpdateCheckFile.ts
+/**
+* Reads the user's update check cache
+*
+* @param filePath the cache file
+* @returns the cache, or null when it is missing, unreadable or invalid
+*/
+async function readUpdateCheckFile(filePath) {
+	try {
+		const result = await readStoreFile(filePath, updateCheckFileSchema);
+		return result.kind === "valid" ? result.value : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/server/update/updateCheckSettings.ts
+var defaultRegistryUrl = "https://registry.npmjs.org";
+/**
+* @param env the environment, for `XDG_CACHE_HOME` and `HOME`
+* @returns the user's update check cache file, shared by every repo
+*/
+function updateCheckFilePath(env) {
+	const cacheHome = env.XDG_CACHE_HOME;
+	const cacheDirectory = cacheHome !== void 0 && path.isAbsolute(cacheHome) ? cacheHome : path.join(env.HOME ?? os.homedir(), ".cache");
+	return path.join(cacheDirectory, "markdown-review", "update-check.json");
+}
+/**
+* @param env the environment, for `MARKDOWN_REVIEW_REGISTRY_URL`
+* @returns the npm registry to ask for dist-tags, without a trailing slash
+*/
+function registryUrl(env) {
+	return (env.MARKDOWN_REVIEW_REGISTRY_URL ?? defaultRegistryUrl).replace(/\/+$/u, "");
+}
+/**
+* @param env the environment
+* @returns whether the user or CI has opted out of update checks, through `MARKDOWN_REVIEW_NO_UPDATE_CHECK=1`,
+*   `NO_UPDATE_NOTIFIER` or `CI`
+*/
+function updateChecksDisabled(env) {
+	return env.MARKDOWN_REVIEW_NO_UPDATE_CHECK === "1" || (env.NO_UPDATE_NOTIFIER ?? "") !== "" || (env.CI ?? "") !== "";
+}
+//#endregion
+//#region src/cli/skillInstallPath.ts
+/**
+* @param base the repo root, or the home directory for a global install
+* @returns where `install-skill` writes the skill under that directory
+*/
+function skillInstallPath(base) {
+	return path.join(base, ".claude", "skills", "markdown-review", "SKILL.md");
+}
+//#endregion
+//#region src/cli/skillStamps.ts
+var frontmatterPattern = /^---\r?\n(?<frontmatter>[\s\S]*?\r?\n)---\r?\n/u;
+/**
+* @param skill the bundled skill
+* @param version the running markdown-review's version
+* @returns the skill as `install-skill` writes it, with the version that wrote it in its frontmatter's
+*   `metadata.version`
+* @throws when the skill has no frontmatter
+*/
+function stampSkill(skill, version) {
+	const match = frontmatterPattern.exec(skill);
+	const frontmatter = match?.groups?.frontmatter;
+	if (match === null || frontmatter === void 0) throw new TypeError("The skill has no frontmatter to stamp");
+	const document = parseDocument(frontmatter);
+	document.setIn(["metadata", "version"], version);
+	return `---\n${document.toString({ lineWidth: 0 })}---\n${skill.slice(match[0].length)}`;
+}
+/**
+* @param installed an installed copy of the skill
+* @returns the version that installed it, or null when the copy carries none
+*/
+function readSkillStamp(installed) {
+	const frontmatter = frontmatterPattern.exec(installed)?.groups?.frontmatter;
+	if (frontmatter === void 0) return null;
+	const version = parseDocument(frontmatter).getIn(["metadata", "version"]);
+	return typeof version === "string" ? version : null;
+}
+//#endregion
+//#region src/cli/findInstalledSkills.ts
+/**
+* Finds the copies of the skill installed in the repo and in the home directory
+*
+* @param root the repo root
+* @param home the home directory
+* @returns each installed copy, the repo's first; a copy that cannot be read counts as not installed
+*/
+async function findInstalledSkills(root, home) {
+	const locations = [{
+		isGlobal: false,
+		path: skillInstallPath(root)
+	}, {
+		isGlobal: true,
+		path: skillInstallPath(home)
+	}];
+	const installed = [];
+	for (const location of locations) {
+		const contents = await readTextFileOrNull(location.path).catch(() => null);
+		if (contents !== null) installed.push({
+			...location,
+			version: readSkillStamp(contents)
+		});
+	}
+	return installed;
+}
+//#endregion
+//#region src/cli/formatUpdateNotices.ts
+/**
+* Describes a newer markdown-review and outdated copies of the skill for the agent
+*
+* @returns the `update_available` and `skill_outdated` lines, each ending in a newline; empty when there is nothing to say
+*/
+function formatUpdateNotices({ availableUpdate, currentVersion, installKind, skills, wentAhead }) {
+	if (availableUpdate !== null) {
+		const news = `update_available: markdown-review ${availableUpdate.version} is out; this is ${currentVersion}.`;
+		if (!wentAhead) return [`${news} Tell the user, and offer to update once they say go ahead.\n`];
+		return [`${news} Ask the user whether to update. If they agree, ${describeUpdate(installKind, availableUpdate, skills)}\n`];
+	}
+	const when = wentAhead ? "Run" : "Once the user says go ahead, run";
+	return skills.filter((skill) => isOlderThan(skill, currentVersion)).map((skill) => `skill_outdated: The markdown-review skill at ${skill.path} is older than this version (${currentVersion}). ${when} \`${installSkillCommand$1(installKind, currentVersion, skill)}\`. The new skill loads in the next agent session.\n`);
+}
+function describeUpdate(installKind, { distTag, version }, skills) {
+	const steps = `run ${[
+		...installKind === "global" ? [globalInstallCommand(distTag)] : [],
+		cliCommand(installKind, "stop", distTag),
+		...skills.filter((skill) => isOlderThan(skill, version)).map((skill) => installSkillCommand$1(installKind, distTag, skill))
+	].map((command) => `\`${command}\``).join(", then ")}`;
+	return installKind === "npx" ? `${steps}, and from now on run markdown-review as \`${npxCommand(distTag)}\`.` : `${steps}.`;
+}
+function installSkillCommand$1(installKind, versionOrTag, skill) {
+	return cliCommand(installKind, skill.isGlobal ? "install-skill --global" : "install-skill", versionOrTag);
+}
+function isOlderThan(skill, version) {
+	return skill.version === null || (compareVersions(skill.version, version) ?? -1) < 0;
+}
+//#endregion
+//#region src/cli/readUpdateNotices.ts
+/**
+* Works out what to tell the agent about a newer markdown-review and outdated copies of the skill, from the update
+* check cache and the installed skills, without contacting the registry
+*
+* @param context the CLI's path and environment
+* @param root the repo root, where a repo copy of the skill lives
+* @param wentAhead whether the user said go ahead
+* @returns the notice lines, each ending in a newline
+*/
+async function readUpdateNotices({ cliPath, terminal }, root, wentAhead) {
+	const { env } = terminal;
+	const cached = updateChecksDisabled(env) ? null : await readUpdateCheckFile(updateCheckFilePath(env));
+	const realCliPath = await realpath(cliPath).catch(() => cliPath);
+	return formatUpdateNotices({
+		availableUpdate: findAvailableUpdate(packageVersion, cached?.distTags ?? {}),
+		currentVersion: packageVersion,
+		installKind: findInstallKind(realCliPath),
+		skills: await findInstalledSkills(root, env.HOME ?? os.homedir()),
+		wentAhead
+	});
+}
+//#endregion
 //#region src/cli/commands/inboxCommand.ts
-async function inboxCommand(args, { cliPath, terminal }) {
+async function inboxCommand(args, context) {
+	const { cliPath, terminal } = context;
 	const { values } = parseArgs({
 		args,
 		options: { document: { type: "string" } }
 	});
 	const root = await findRoot(terminal.workingDirectory);
 	const document = await readDocumentOption(root, terminal.workingDirectory, values.document);
-	const client = await connectToServer(root, cliPath);
-	terminal.stdout(formatInbox(await client.inbox(document)));
+	const inbox = await (await connectToServer(root, cliPath)).inbox(document);
+	const notices = roundOutcome(inbox.round) === "go-ahead" ? await readUpdateNotices(context, root, true) : [];
+	terminal.stdout(formatInbox(inbox, notices));
 	return 0;
 }
 //#endregion
 //#region skills/markdown-review/SKILL.md?raw
-var SKILL_default = "---\nname: markdown-review\ndescription: Hands markdown docs you wrote, such as plans, specs and design notes, to the user to review in their browser, then reads their comments back so you can edit the docs and answer each one. Use when the user asks you to have a doc reviewed, or when a doc you wrote needs their sign-off before you carry on.\n---\n\n# Markdown Review\n\nThe user reviews your markdown in a browser and comments on passages, blocks, whole docs or the review as a whole. You read the comments with the `markdown-review` command, edit the docs, and answer each comment.\n\nIf the `markdown-review` command is not found, install it with `npm install --global @krelborn/markdown-review`.\n\n## The review loop\n\n1. Run `markdown-review open <doc.md>`. It starts a review round and shows the doc in the user's browser.\n2. Run `markdown-review poll`. It waits until the user submits, then prints each comment: its thread ID, file, line range, the quoted text and the user's words.\n   - Give the shell command a timeout of at least 600000 ms. `poll` gives up after 540 seconds by default; run it again if it says there are no comments yet.\n   - In Claude Code, run it with `run_in_background` and `--timeout 7080`, and a Bash timeout of 7200000 ms. A submit still ends it at once.\n3. Edit the docs. Then answer every thread:\n   - `markdown-review resolve <id> \"<what changed>\"` when you have addressed it.\n   - `markdown-review reply <id> \"<question>\"` when you need the user's input.\n   - For a long message, put it in a file and pass `--file <path>`, or pass `--file -` and write it to standard input.\n4. Run `markdown-review poll` again for the next round.\n\n`markdown-review inbox` prints what `poll` would, without waiting, for picking comments up later.\n\n## Approval\n\nThe review ends when the user approves it, and `poll` and `inbox` then start with \"Review approved\". Address any comments that came with the approval, then carry on with your task. Do not run `poll` again for that review.\n\n## Good to know\n\n- A quote is the text as the browser shows it, not the markdown source. The line range is exact, so use it to find the passage.\n- If `poll` is stopped before the user submits, nothing is lost: run it again.\n- Every command ends with a `next_step` line that says what to do next. `markdown-review --help` lists the commands.\n- Run `markdown-review stop` to stop the review server when you have finished.\n";
+var SKILL_default = "---\nname: markdown-review\ndescription: Hands markdown docs you wrote, such as plans, specs and design notes, to the user to review in their browser, then reads their comments back so you can edit the docs and answer each one. Use when the user asks you to have a doc reviewed, or when a doc you wrote needs their sign-off before you carry on.\n---\n\n# Markdown Review\n\nThe user reviews your markdown in a browser and comments on passages, blocks, whole docs or the review as a whole. You read the comments with the `markdown-review` command, edit the docs, and answer each comment.\n\nIf the `markdown-review` command is not found, install it with `npm install --global @krelborn/markdown-review`.\n\n## The review loop\n\n1. Run `markdown-review open <doc.md> --next-task \"<what you will do once the user says go ahead>\"`, for example `--next-task \"implement the plan in src/server\"`. It starts a review round and shows the doc in the user's browser, with your next task under Go ahead.\n2. Run `markdown-review poll`. It waits until the user submits, then prints each comment: its thread ID, file, line range, the quoted text and the user's words.\n   - Give the shell command a timeout of at least 600000 ms. `poll` gives up after 540 seconds by default; run it again if it says there are no comments yet.\n   - In Claude Code, run it with `run_in_background` and `--timeout 7080`, and a Bash timeout of 7200000 ms. A submit still ends it at once.\n3. Edit the docs. Then answer every thread:\n   - `markdown-review resolve <id> \"<what changed>\"` when you have addressed it.\n   - `markdown-review reply <id> \"<question>\"` when you need the user's input.\n   - For a long message, put it in a file and pass `--file <path>`, or pass `--file -` and write it to standard input.\n4. Run `markdown-review poll` again for the next round.\n\n`markdown-review inbox` prints what `poll` would, without waiting, for picking comments up later.\n\n## How a review ends\n\nThe user ends a review in one of two ways, and `poll` and `inbox` say which on their first line.\n\n- **Go ahead** (\"The user said go ahead\"): address any comments that came with it, then carry on with your task. Do not run `poll` again for that review.\n- **Hand back** (\"The user asked to hand back to you\"): stop. Do not edit the docs, answer the threads, run `poll` or carry on with your task. Tell the user in the chat that you have stopped and what their comments say, and wait for their instructions. If they ask you to continue the review, run `markdown-review open <doc.md> --next-task \"<what you will do once the user says go ahead>\"`, then `markdown-review poll`.\n\n## Updates\n\n- `open` may print `update_available` when a newer markdown-review is out. Tell the user, and carry on with the review.\n- Once the user says go ahead, `poll` and `inbox` print `update_available` again with the commands to run. Ask the user whether to update, and run them only if they agree. If they install packages another way, such as with pnpm or under `sudo`, adapt the install command and keep the rest.\n- `skill_outdated` means an installed copy of this skill is from an older version. Once the user says go ahead, run the command it gives and tell the user.\n\n## Good to know\n\n- A quote is the text as the browser shows it, not the markdown source. The line range is exact, so use it to find the passage.\n- If `poll` is stopped before the user submits, nothing is lost: run it again.\n- Every command ends with a `next_step` line that says what to do next. `markdown-review --help` lists the commands.\n- Run `markdown-review stop` to stop the review server when you have finished.\n";
 //#endregion
 //#region src/cli/commands/installSkillCommand.ts
 /**
@@ -907,37 +1292,47 @@ async function installSkillCommand(args, { terminal }) {
 		args,
 		options: { global: { type: "boolean" } }
 	});
-	const base = values.global === true ? terminal.env.HOME ?? os.homedir() : await findRoot(terminal.workingDirectory);
-	const skillPath = path.join(base, ".claude", "skills", "markdown-review", "SKILL.md");
+	const skillPath = skillInstallPath(values.global === true ? terminal.env.HOME ?? os.homedir() : await findRoot(terminal.workingDirectory));
+	const stamped = stampSkill(SKILL_default, packageVersion);
 	const installed = await readTextFileOrNull(skillPath);
 	await mkdir(path.dirname(skillPath), { recursive: true });
-	await writeFile(skillPath, SKILL_default);
-	const outcome = installed === null ? "Installed" : installed === "---\nname: markdown-review\ndescription: Hands markdown docs you wrote, such as plans, specs and design notes, to the user to review in their browser, then reads their comments back so you can edit the docs and answer each one. Use when the user asks you to have a doc reviewed, or when a doc you wrote needs their sign-off before you carry on.\n---\n\n# Markdown Review\n\nThe user reviews your markdown in a browser and comments on passages, blocks, whole docs or the review as a whole. You read the comments with the `markdown-review` command, edit the docs, and answer each comment.\n\nIf the `markdown-review` command is not found, install it with `npm install --global @krelborn/markdown-review`.\n\n## The review loop\n\n1. Run `markdown-review open <doc.md>`. It starts a review round and shows the doc in the user's browser.\n2. Run `markdown-review poll`. It waits until the user submits, then prints each comment: its thread ID, file, line range, the quoted text and the user's words.\n   - Give the shell command a timeout of at least 600000 ms. `poll` gives up after 540 seconds by default; run it again if it says there are no comments yet.\n   - In Claude Code, run it with `run_in_background` and `--timeout 7080`, and a Bash timeout of 7200000 ms. A submit still ends it at once.\n3. Edit the docs. Then answer every thread:\n   - `markdown-review resolve <id> \"<what changed>\"` when you have addressed it.\n   - `markdown-review reply <id> \"<question>\"` when you need the user's input.\n   - For a long message, put it in a file and pass `--file <path>`, or pass `--file -` and write it to standard input.\n4. Run `markdown-review poll` again for the next round.\n\n`markdown-review inbox` prints what `poll` would, without waiting, for picking comments up later.\n\n## Approval\n\nThe review ends when the user approves it, and `poll` and `inbox` then start with \"Review approved\". Address any comments that came with the approval, then carry on with your task. Do not run `poll` again for that review.\n\n## Good to know\n\n- A quote is the text as the browser shows it, not the markdown source. The line range is exact, so use it to find the passage.\n- If `poll` is stopped before the user submits, nothing is lost: run it again.\n- Every command ends with a `next_step` line that says what to do next. `markdown-review --help` lists the commands.\n- Run `markdown-review stop` to stop the review server when you have finished.\n" ? "Reinstalled" : "Updated";
+	await writeFile(skillPath, stamped);
+	const outcome = installed === null ? "Installed" : installed === stamped ? "Reinstalled" : "Updated";
 	terminal.stdout(`${outcome} the markdown-review skill at ${skillPath}\n\nnext_step: The skill loads when an agent session starts. To start a review now, run \`markdown-review open <doc.md>\`.
 `);
 	return 0;
 }
 //#endregion
 //#region src/cli/commands/openCommand.ts
-async function openCommand(args, { cliPath, terminal }) {
-	const { positionals } = parseArgs({
+async function openCommand(args, context) {
+	const { cliPath, terminal } = context;
+	const { positionals, values } = parseArgs({
 		allowPositionals: true,
 		args,
-		options: {}
+		options: { "next-task": { type: "string" } }
 	});
 	if (positionals.length > 1) throw new CliError("open takes at most one path", "Run `markdown-review open [path]`.", 2);
+	const nextTask = readNextTask(values["next-task"]);
 	const target = positionals[0];
 	const workingRoot = await findRoot(terminal.workingDirectory);
 	const { document, root } = target === void 0 ? {
 		document: null,
 		root: workingRoot
 	} : await locate(terminal.workingDirectory, target);
-	const { navigated, url } = await (await connectToServer(root, cliPath)).open(document);
+	const { navigated, url } = await (await connectToServer(root, cliPath)).open(document, nextTask);
 	const shown = navigated ? "Shown in the browser tab that was already open." : await openUrl(url, terminal.env);
 	const nextStep = root === workingRoot ? waitForCommentsStep : waitForCommentsInRootStep(root);
-	terminal.stdout(`Opened ${document ?? "the docs list"} for review: ${url}\n${shown}\n\nnext_step: ${nextStep}\n`);
+	const notices = await readUpdateNotices(context, root, false);
+	const noticeSection = notices.length > 0 ? `${notices.join("")}\n` : "";
+	terminal.stdout(`Opened ${document ?? "the docs list"} for review: ${url}\n${shown}\n\n${noticeSection}next_step: ${nextStep}\n`);
 	return 0;
 }
+function readNextTask(value) {
+	if (value === void 0) return null;
+	const result = nextTaskSchema.safeParse(value);
+	if (!result.success) throw new CliError("--next-task must be one line of at most 200 characters", "Run `markdown-review open <doc.md> --next-task \"<what you will do once the user says go ahead>\"`.", 2);
+	return result.data;
+}
 async function locate(workingDirectory, target) {
 	const absolutePath = path.resolve(workingDirectory, target);
 	const found = await stat(absolutePath).catch(() => null);
@@ -964,7 +1359,8 @@ var interruptedExitCodes = {
 	SIGINT: 130,
 	SIGTERM: 143
 };
-async function pollCommand(args, { cliPath, terminal }) {
+async function pollCommand(args, context) {
+	const { cliPath, terminal } = context;
 	const { values } = parseArgs({
 		args,
 		options: {
@@ -987,8 +1383,12 @@ async function pollCommand(args, { cliPath, terminal }) {
 	try {
 		terminal.stderr(`Waiting up to ${timeoutSeconds}s for review comments. If this is interrupted, run \`markdown-review poll\` again; nothing is lost.\n`);
 		const result = await client.poll(document, timeoutSeconds, abort.signal);
-		if (result.timedOut && result.threads.length === 0 && !result.review.approved) terminal.stdout(`No comments yet.\n\nnext_step: Run \`markdown-review poll\` again to keep waiting. ${pollTimeoutAdvice}\n`);
-		else terminal.stdout(formatInbox(result));
+		const outcome = roundOutcome(result.round);
+		if (result.timedOut && result.threads.length === 0 && outcome === null) terminal.stdout(`No comments yet.\n\nnext_step: Run \`markdown-review poll\` again to keep waiting. ${pollTimeoutAdvice}\n`);
+		else {
+			const notices = outcome === "go-ahead" ? await readUpdateNotices(context, root, true) : [];
+			terminal.stdout(formatInbox(result, notices));
+		}
 		return 0;
 	} catch (error) {
 		if (interruptedBy !== void 0) {
@@ -1108,10 +1508,13 @@ var StoreError = class extends Error {
 };
 //#endregion
 //#region src/shared/api/apiRequestSchemas.ts
-var agentOpenRequestSchema = z.strictObject({ path: documentPathSchema.optional() });
+var agentOpenRequestSchema = z.strictObject({
+	nextTask: nextTaskSchema.optional(),
+	path: documentPathSchema.optional()
+});
 var messageRequestSchema = z.strictObject({ body: messageBodySchema });
 var resolveRequestSchema = z.strictObject({ body: messageBodySchema.nullable() });
-var submitRequestSchema = z.strictObject({ verdict: z.enum(["request-changes", "approve"]) });
+var submitRequestSchema = z.strictObject({ verdict: verdictSchema });
 //#endregion
 //#region src/server/files/resolveRepositoryPath.ts
 /**
@@ -1241,19 +1644,19 @@ function registerAgentRoutes(app, dependencies) {
 		return context.json({ stopping: true });
 	});
 	app.post("/api/agent/open", async (context) => {
-		const { path } = await readJsonBody(context, agentOpenRequestSchema);
+		const { nextTask, path } = await readJsonBody(context, agentOpenRequestSchema);
 		if (path !== void 0) {
 			await checkDocumentPath(root, path, false);
 			recentDocuments.add(path);
 			watchDocument(path);
 		}
-		const review = await store.requestReview();
+		const round = await store.openRound(path ?? null, nextTask ?? null);
 		events.publish({ type: "threads-changed" });
 		const pagePath = path === void 0 ? "" : `document/${path.split("/").map(encodeURIComponent).join("/")}`;
 		const url = `http://127.0.0.1:${port()}/${pagePath}`;
 		const response = {
 			navigated: tabs.navigateLatest(url),
-			review,
+			round,
 			url
 		};
 		return context.json(response);
@@ -1466,7 +1869,7 @@ function registerHealthRoutes(app, { root, version }) {
 		const health = {
 			name: "markdown-review",
 			pid: process.pid,
-			protocol: 1,
+			protocol: 2,
 			root,
 			version
 		};
@@ -1476,7 +1879,7 @@ function registerHealthRoutes(app, { root, version }) {
 //#endregion
 //#region src/server/http/waitForInbox.ts
 /**
-* Waits until the review is approved or a thread needs the agent
+* Waits until the user ends the review round or a thread needs the agent
 *
 * @returns the inbox as soon as it has something for the agent, or as it stands when the time runs out or the
 *   request is aborted, with `timedOut` set
@@ -1486,7 +1889,7 @@ async function waitForInbox({ document, events, signal, store, timeoutMillisecon
 	for (;;) {
 		const nextSubmit = waitForSubmit(events, deadline - Date.now(), signal);
 		const inbox = await store.readInbox(document);
-		if (inbox.review.approved || inbox.threads.length > 0) {
+		if (roundOutcome(inbox.round) !== null || inbox.threads.length > 0) {
 			nextSubmit.cancel();
 			return {
 				...inbox,
@@ -1722,6 +2125,18 @@ function withAppearance(html, { mode, palette }) {
 	return html.replace("<html", `<html data-sui-mode="${mode}" data-sui-palette="${palette}"`);
 }
 //#endregion
+//#region src/server/http/updateRoutes.ts
+function registerUpdateRoutes(app, { installKind, root, updateChecker, version }) {
+	app.get("/api/update", async (context) => {
+		const update = updateChecker === null ? null : findAvailableUpdate(version, await updateChecker.distTags());
+		const response = {
+			availableVersion: update?.version ?? null,
+			command: update !== null && installKind === "global" ? globalUpdateCommand(update.distTag, root) : null
+		};
+		return context.json(response);
+	});
+}
+//#endregion
 //#region src/server/http/createApp.ts
 var statusForStoreError = {
 	"invalid-file": 500,
@@ -1777,6 +2192,7 @@ function createApp(dependencies) {
 	registerBrowserRoutes(app, dependencies);
 	registerEventRoutes(app, dependencies);
 	registerFileRoutes(app, dependencies);
+	registerUpdateRoutes(app, dependencies);
 	registerShellRoutes(app, dependencies);
 	return app;
 }
@@ -1796,6 +2212,21 @@ var RecentDocuments = class {
 	}
 };
 //#endregion
+//#region src/shared/review/isDraftInRound.ts
+/**
+* Tells whether a submit sends a thread's draft
+*
+* @param thread the thread
+* @param round the current round, or null before any review was opened
+* @returns false when the thread has no draft; otherwise true when there is no round, or the draft is on the whole
+*   review, on a doc opened this round, or written since the round began
+*/
+function isDraftInRound(thread, round) {
+	if (thread.draft === void 0) return false;
+	if (round === null || thread.anchor.kind === "review") return true;
+	return round.documents.includes(thread.anchor.document) || Date.parse(thread.draft.at) >= Date.parse(round.startedAt);
+}
+//#endregion
 //#region src/shared/markdown/fenceLanguage.ts
 /**
 * Reads the language of a fenced code block from its info string
@@ -2363,12 +2794,53 @@ function reanchorDocumentThreads(threads, source) {
 //#endregion
 //#region src/server/store/emptyReviewFile.ts
 var emptyReviewFile = {
-	approvedAt: null,
-	requestedAt: null,
+	round: null,
 	threads: [],
-	version: 1
+	version: 2
 };
 //#endregion
+//#region src/server/store/joinOrStartRound.ts
+var roundExpiryMilliseconds = 432e5;
+/**
+* Adds a doc to the review round going on, or starts the next round
+*
+* @param round the current round, or null before any review was opened
+* @param path the doc the agent opened, or null for the docs list
+* @param nextTask what the agent will do once the user says go ahead; null keeps a joined round's task and leaves a
+*   new round without one
+* @param at the current time, ISO 8601
+* @returns the round joined when it has not ended and had an open or a submit in the last 12 hours, otherwise a new
+*   round, which starts when the user handed the previous one back if that was in the last 12 hours
+*/
+function joinOrStartRound(round, path, nextTask, at) {
+	if (round !== null && roundOutcome(round) === null && isRecent(lastActivity(round), at)) return {
+		...round,
+		documents: path === null || round.documents.includes(path) ? round.documents : [...round.documents, path],
+		lastOpenedAt: at,
+		nextTask: nextTask ?? round.nextTask
+	};
+	return {
+		documents: path === null ? [] : [path],
+		lastOpenedAt: at,
+		nextTask,
+		startedAt: recentHandBack(round, at) ?? at,
+		verdict: null
+	};
+}
+function lastActivity({ lastOpenedAt, verdict }) {
+	return verdict !== null && Date.parse(verdict.at) > Date.parse(lastOpenedAt) ? verdict.at : lastOpenedAt;
+}
+/**
+* @returns when the user handed the round back, no later than `at`, or null when they did not or it was 12 hours ago
+*/
+function recentHandBack(round, at) {
+	if (round?.verdict?.kind !== "hand-back" || !isRecent(round.verdict.at, at)) return null;
+	return Date.parse(round.verdict.at) < Date.parse(at) ? round.verdict.at : at;
+}
+function isRecent(earlier, at) {
+	return Date.parse(at) - Date.parse(earlier) < roundExpiryMilliseconds;
+}
+//#endregion
 //#region src/server/store/needsAgent.ts
 /**
 * Tells whether a thread is waiting for the agent
@@ -2451,12 +2923,12 @@ var documentThreadsFileSchema = z.strictObject({
 }).refine((file) => file.threads.every((thread) => thread.anchor.kind !== "review" && thread.anchor.document === file.document), { message: "must hold only threads anchored to its own doc" });
 //#endregion
 //#region src/shared/review/reviewFileSchema.ts
+var reviewThreadsSchema = z.array(threadSchema).refine((threads) => threads.every((thread) => thread.anchor.kind === "review"), { message: "must hold only threads on the whole review" });
 var reviewFileSchema = z.strictObject({
-	approvedAt: z.iso.datetime().nullable(),
-	requestedAt: z.iso.datetime().nullable(),
-	threads: z.array(threadSchema),
-	version: z.literal(1)
-}).refine((file) => file.threads.every((thread) => thread.anchor.kind === "review"), { message: "must hold only threads on the whole review" });
+	round: reviewRoundSchema.nullable(),
+	threads: reviewThreadsSchema,
+	version: z.literal(2)
+});
 //#endregion
 //#region src/server/files/writeTextFileUnlessExists.ts
 /**
@@ -2480,6 +2952,44 @@ async function writeTextFileUnlessExists(filePath, contents) {
 	}
 }
 //#endregion
+//#region src/server/store/storedReviewFileSchema.ts
+var reviewFileVersion1Schema = z.strictObject({
+	approvedAt: z.iso.datetime().nullable(),
+	requestedAt: z.iso.datetime().nullable(),
+	threads: reviewThreadsSchema,
+	version: z.literal(1)
+});
+/**
+* Reads `review.json` as written by any version, giving the current version
+*/
+var storedReviewFileSchema = z.discriminatedUnion("version", [reviewFileSchema, reviewFileVersion1Schema]).transform((file) => file.version === 1 ? upgradeVersion1(file) : file);
+/**
+* @param file a version 1 file, which recorded when the agent last opened the review and when the user last approved
+* @returns the same threads, with no round when no review was opened, otherwise a round on no docs that started at the
+*   last open and ended with Go ahead when the approval came after it
+*/
+function upgradeVersion1({ approvedAt, requestedAt, threads }) {
+	if (requestedAt === null) return {
+		round: null,
+		threads,
+		version: 2
+	};
+	return {
+		round: {
+			documents: [],
+			lastOpenedAt: requestedAt,
+			nextTask: null,
+			startedAt: requestedAt,
+			verdict: approvedAt !== null && Date.parse(approvedAt) > Date.parse(requestedAt) ? {
+				at: approvedAt,
+				kind: "go-ahead"
+			} : null
+		},
+		threads,
+		version: 2
+	};
+}
+//#endregion
 //#region src/server/store/StoreFiles.ts
 /**
 * Reads and writes the files of one root's `.markdown-review/` directory and the docs they refer to
@@ -2500,7 +3010,7 @@ var StoreFiles = class {
 	* @returns the review file, or an empty one when it does not exist yet
 	*/
 	async readReviewFile() {
-		const result = await readStoreFile(reviewFilePath(this.root), reviewFileSchema);
+		const result = await readStoreFile(reviewFilePath(this.root), storedReviewFileSchema);
 		return result.kind === "valid" ? {
 			kind: "valid",
 			value: result.value ?? emptyReviewFile
@@ -2683,21 +3193,6 @@ function withoutDraft(thread) {
 	return next;
 }
 //#endregion
-//#region src/server/store/toReviewState.ts
-/**
-* Works out whether the current review round is approved
-*
-* @param reviewFile the review's stored timestamps
-* @returns the timestamps and whether the approval came after the latest request
-*/
-function toReviewState({ approvedAt, requestedAt }) {
-	return {
-		approved: approvedAt !== null && (requestedAt === null || Date.parse(approvedAt) > Date.parse(requestedAt)),
-		approvedAt,
-		requestedAt
-	};
-}
-//#endregion
 //#region src/server/store/ReviewStore.ts
 /**
 * Holds one root's review threads and carries out every change to them, one at a time
@@ -2725,18 +3220,22 @@ var ReviewStore = class {
 		});
 	}
 	/**
-	* Starts a review round, so an earlier approval no longer counts
+	* Adds a doc to the review round going on, or starts the next round
 	*
-	* @returns the review state after the request
+	* @param path the doc the agent opened, or null for the docs list
+	* @param nextTask what the agent will do once the user says go ahead; null keeps a joined round's task and leaves a
+	*   new round without one
+	* @returns the round the doc is now in
 	*/
-	requestReview() {
+	openRound(path, nextTask) {
 		return this.queue.enqueue(async () => {
-			const next = {
-				...requireValid(await this.files.readReviewFile()),
-				requestedAt: (/* @__PURE__ */ new Date()).toISOString()
-			};
-			await this.files.writeReviewFile(next);
-			return toReviewState(next);
+			const review = requireValid(await this.files.readReviewFile());
+			const round = joinOrStartRound(review.round, path, nextTask, (/* @__PURE__ */ new Date()).toISOString());
+			await this.files.writeReviewFile({
+				...review,
+				round
+			});
+			return round;
 		});
 	}
 	/**
@@ -2794,31 +3293,40 @@ var ReviewStore = class {
 		return this.changeThread(id, "user", resolveAsUser);
 	}
 	/**
-	* Submits every draft in the repo and records the user's verdict on the review round
+	* Submits the drafts that belong to the review round, leaving the rest as drafts, and records the user's verdict on
+	* the round, starting one when no review was opened
 	*
-	* @param verdict "approve" ends the round; "request-changes" needs at least one draft
-	* @returns the IDs of the threads that received a submitted message, and the review state after the submit
-	* @throws StoreError "invalid-state" when requesting changes with no drafts
+	* @param verdict "go-ahead" and "hand-back" end the round; "revise" needs at least one draft to submit
+	* @returns the IDs of the threads that received a submitted message, and the round after the submit
+	* @throws StoreError "invalid-state" when asking for revisions with no drafts to submit
 	*/
 	submit(verdict) {
 		return this.queue.enqueue(async () => {
 			const at = (/* @__PURE__ */ new Date()).toISOString();
 			const review = requireValid(await this.files.readReviewFile());
-			const documentFiles = await this.readDocumentFilesWithDrafts();
-			const submittedThreadIds = [...review.threads, ...documentFiles.flatMap((file) => file.threads)].filter((thread) => thread.draft !== void 0).map((thread) => thread.id).sort((left, right) => left - right);
-			if (verdict === "request-changes" && submittedThreadIds.length === 0) throw new StoreError("invalid-state", "There are no drafts to submit");
+			const isSent = (thread) => isDraftInRound(thread, review.round);
+			const send = (thread) => isSent(thread) ? submitDraft(thread, at) : thread;
+			const documentFiles = await this.readDocumentFilesToSubmit(isSent);
+			const submittedThreadIds = [...review.threads, ...documentFiles.flatMap((file) => file.threads)].filter(isSent).map((thread) => thread.id).sort((left, right) => left - right);
+			if (verdict === "revise" && submittedThreadIds.length === 0) throw new StoreError("invalid-state", "There are no drafts to submit");
 			for (const file of documentFiles) await this.files.writeDocumentFile({
 				...file,
-				threads: file.threads.map((thread) => submitDraft(thread, at))
+				threads: file.threads.map(send)
 			});
-			const next = {
-				...review,
-				approvedAt: verdict === "approve" ? at : null,
-				threads: review.threads.map((thread) => submitDraft(thread, at))
+			const round = {
+				...review.round ?? joinOrStartRound(null, null, null, at),
+				verdict: {
+					at,
+					kind: verdict
+				}
 			};
-			await this.files.writeReviewFile(next);
+			await this.files.writeReviewFile({
+				...review,
+				round,
+				threads: review.threads.map(send)
+			});
 			return {
-				review: toReviewState(next),
+				round,
 				submittedThreadIds
 			};
 		});
@@ -2842,7 +3350,7 @@ var ReviewStore = class {
 	* Reads threads for the browser, first re-anchoring any doc that changed since its threads were last anchored
 	*
 	* @param document the doc whose threads to read, alongside the review's, or null for every thread
-	* @returns the review state, the threads in ID order, and any store files that could not be read
+	* @returns the review round, the threads in ID order, and any store files that could not be read
 	* @throws StoreError "invalid-input" when the doc path is not a repo-relative POSIX path
 	*/
 	readThreads(document) {
@@ -2852,7 +3360,7 @@ var ReviewStore = class {
 	* Reads what the agent has to act on, first re-anchoring any doc that changed since its threads were last anchored
 	*
 	* @param document the doc to limit the threads to, or null for every thread including the review's
-	* @returns the review state and the threads that need the agent
+	* @returns the review round and the threads that need the agent
 	* @throws StoreError "invalid-input" when the doc path is not a repo-relative POSIX path
 	*/
 	readInbox(document) {
@@ -2874,7 +3382,7 @@ var ReviewStore = class {
 		for (const name of documents) threads.push(...await this.readDocumentThreadsOrReport(name, problems));
 		return {
 			problems,
-			review: toReviewState(review),
+			round: review.round,
 			threads: threads.sort((left, right) => left.id - right.id)
 		};
 	}
@@ -2959,12 +3467,12 @@ var ReviewStore = class {
 			problems
 		};
 	}
-	async readDocumentFilesWithDrafts() {
+	async readDocumentFilesToSubmit(isSent) {
 		const files = [];
 		for (const document of await this.files.listDocuments()) {
 			const result = await this.files.readDocumentFile(document);
 			if (result.kind === "invalid") this.logger.warn(`Drafts in ${document} were not submitted. ${result.problem}`);
-			else if (result.value?.threads.some((thread) => thread.draft !== void 0)) files.push((await this.readCurrentDocumentFile(document)).file);
+			else if (result.value?.threads.some(isSent)) files.push((await this.readCurrentDocumentFile(document)).file);
 		}
 		return files;
 	}
@@ -3029,6 +3537,139 @@ function requireValid(result) {
 	return result.value;
 }
 //#endregion
+//#region src/server/update/RegistryRequestError.ts
+/**
+* A dist-tags request the npm registry answered with an error status
+*/
+var RegistryRequestError = class extends Error {
+	status;
+	constructor(url, status) {
+		super(`${url} answered ${status}`);
+		this.name = "RegistryRequestError";
+		this.status = status;
+	}
+};
+//#endregion
+//#region src/server/update/fetchDistTags.ts
+var packageName = "@krelborn/markdown-review";
+/**
+* Asks the registry for the package's dist-tags
+*
+* @param registry the registry's URL, without a trailing slash
+* @param fetchUrl the fetch to send the request with
+* @param timeoutMilliseconds how long to wait for the whole response
+* @returns the `latest` and `next` tags, when the registry has them
+* @throws when the request fails, times out, or the response is not a dist-tags object
+*/
+async function fetchDistTags(registry, fetchUrl, timeoutMilliseconds) {
+	const url = `${registry}/-/package/${encodeURIComponent(packageName)}/dist-tags`;
+	const response = await fetchUrl(url, { signal: AbortSignal.timeout(timeoutMilliseconds) });
+	if (!response.ok) throw new RegistryRequestError(url, response.status);
+	return distTagsSchema.parse(await response.json());
+}
+//#endregion
+//#region src/server/update/UpdateChecker.ts
+var dayMilliseconds = 864e5;
+var minuteMilliseconds = 6e4;
+/**
+* Asks the npm registry for markdown-review's dist-tags about once a day for the user, keeping the answer in a cache
+* file that every repo's server and the CLI read
+*/
+var UpdateChecker = class {
+	cachePath;
+	checking;
+	fetch;
+	isStarted = false;
+	logger;
+	now;
+	recorded = null;
+	registry;
+	timer;
+	timeoutMilliseconds;
+	constructor({ cachePath, fetch: fetchUrl = fetch, logger, now = () => /* @__PURE__ */ new Date(), registry, timeoutMilliseconds = 3e3 }) {
+		this.cachePath = cachePath;
+		this.fetch = fetchUrl;
+		this.logger = logger;
+		this.now = now;
+		this.registry = registry;
+		this.timeoutMilliseconds = timeoutMilliseconds;
+	}
+	/**
+	* Asks the registry unless the cache is less than a day old; never rejects
+	*
+	* @returns once the cache is up to date, or the check has failed
+	*/
+	check() {
+		this.checking ??= this.refresh().finally(() => {
+			this.checking = void 0;
+		});
+		return this.checking;
+	}
+	/**
+	* @returns the dist-tags last recorded, after any check in progress ends; empty when none are known
+	*/
+	async distTags() {
+		await this.checking;
+		return (await this.readLatest())?.distTags ?? {};
+	}
+	/**
+	* Checks now, then whenever the cache turns a day old while the process runs
+	*/
+	start() {
+		this.isStarted = true;
+		this.checkAndSchedule();
+	}
+	stop() {
+		this.isStarted = false;
+		clearTimeout(this.timer);
+	}
+	async checkAndSchedule() {
+		await this.check();
+		if (!this.isStarted) return;
+		const cached = await this.readLatest();
+		const untilStale = cached === null ? dayMilliseconds : Date.parse(cached.checkedAt) + dayMilliseconds - this.now().getTime();
+		const delay = Math.min(Math.max(untilStale, minuteMilliseconds), dayMilliseconds);
+		clearTimeout(this.timer);
+		this.timer = setTimeout(() => void this.checkAndSchedule(), delay);
+		this.timer.unref();
+	}
+	async refresh() {
+		const cached = await this.readLatest();
+		const now = this.now();
+		if (isFresh(cached, now)) return;
+		let distTags;
+		try {
+			distTags = await fetchDistTags(this.registry, this.fetch, this.timeoutMilliseconds);
+		} catch (error) {
+			this.logger.warn("Could not check the npm registry for a newer markdown-review", error);
+			const latest = await this.readLatest();
+			if (isFresh(latest, now)) return;
+			distTags = latest?.distTags ?? {};
+		}
+		const file = {
+			checkedAt: now.toISOString(),
+			distTags
+		};
+		this.recorded = file;
+		try {
+			await writeJsonAtomically(this.cachePath, file);
+		} catch (error) {
+			this.logger.warn(`Could not write ${this.cachePath}`, error);
+		}
+	}
+	/**
+	* The cache file, or this checker's own last check when that is newer, as it is when the file could not be written
+	*/
+	async readLatest() {
+		const cached = await readUpdateCheckFile(this.cachePath);
+		if (cached === null || this.recorded !== null && Date.parse(this.recorded.checkedAt) > Date.parse(cached.checkedAt)) return this.recorded;
+		return cached;
+	}
+};
+function isFresh(file, now) {
+	return file !== null && now.getTime() - Date.parse(file.checkedAt) < dayMilliseconds;
+}
+//#endregion
 //#region src/server/runtime/ActivityMonitor.ts
 /**
 * Tracks connected tabs and waiting polls, reports whether the agent is waiting, and notices when the server is idle
@@ -3164,7 +3805,7 @@ function preferredPort(root) {
 *
 * @returns the running server; it removes `server.json` when it stops
 */
-async function runServer({ idleMilliseconds = 18e5, logger, pollKeepAliveMilliseconds = 15e3, root, webDirectory }) {
+async function runServer({ idleMilliseconds = 18e5, logger, pollKeepAliveMilliseconds = 15e3, root, updateChecker = createUpdateChecker(logger), webDirectory }) {
 	const store = new ReviewStore(root, logger);
 	await store.initialize();
 	const events = new ServerEvents();
@@ -3199,6 +3840,7 @@ async function runServer({ idleMilliseconds = 18e5, logger, pollKeepAliveMillise
 	const app = createApp({
 		activity,
 		events,
+		installKind: findInstallKind(process.argv[1] ?? ""),
 		logger,
 		pollKeepAliveMilliseconds,
 		port: () => port,
@@ -3208,16 +3850,18 @@ async function runServer({ idleMilliseconds = 18e5, logger, pollKeepAliveMillise
 		store,
 		tabs: new BrowserTabs(),
 		token,
+		updateChecker,
 		version: packageVersion,
 		watchDocument: (document) => watcher.watch(document),
 		webDirectory
 	});
+	updateChecker?.start();
 	const server = createServer(getRequestListener(app.fetch));
 	port = await listen(server, preferredPort(root));
 	const serverFile = {
 		pid: process.pid,
 		port,
-		protocol: 1,
+		protocol: 2,
 		root,
 		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		token,
@@ -3228,6 +3872,7 @@ async function runServer({ idleMilliseconds = 18e5, logger, pollKeepAliveMillise
 	logger.info(`Serving ${root} on http://127.0.0.1:${port}`);
 	async function stop() {
 		activity.stop();
+		updateChecker?.stop();
 		await watcher.close();
 		await closeServer(server);
 		await removeServerFile(root);
@@ -3240,6 +3885,14 @@ async function runServer({ idleMilliseconds = 18e5, logger, pollKeepAliveMillise
 		port
 	};
 }
+function createUpdateChecker(logger) {
+	if (updateChecksDisabled(process.env)) return null;
+	return new UpdateChecker({
+		cachePath: updateCheckFilePath(process.env),
+		logger,
+		registry: registryUrl(process.env)
+	});
+}
 async function listen(server, port) {
 	try {
 		return await listenOn(server, port);
@@ -3333,16 +3986,21 @@ async function stopCommand(args, { terminal }) {
 //#endregion
 //#region src/cli/helpText.ts
 var commandHelp = {
-	inbox: ["markdown-review inbox [--document <path>]", "  Print whether the review is approved and the threads that need you, then return at once."].join("\n"),
+	inbox: ["markdown-review inbox [--document <path>]", "  Print how the user ended the review, if they have, and the threads that need you, then return at once."].join("\n"),
 	"install-skill": [
 		"markdown-review install-skill [--global]",
 		"  Install the skill that teaches agents this workflow in this repository's .claude/skills, or with --global in",
 		"  ~/.claude/skills. Claude Code and OpenCode both read skills from there."
 	].join("\n"),
-	open: ["markdown-review open [path]", "  Start a review round and show the doc (or the docs list) in the user's browser. Prints the URL."].join("\n"),
+	open: [
+		"markdown-review open [path] [--next-task <text>]",
+		"  Start a review round, or add the doc to the one in progress, and show the doc (or the docs list) in the",
+		"  user's browser. --next-task says what you will do once the user says go ahead; the user sees it.",
+		"  Prints the URL."
+	].join("\n"),
 	poll: [
 		"markdown-review poll [--document <path>] [--timeout <seconds>]",
-		"  Wait until the user submits or approves, then print what needs you. The timeout defaults to 540 seconds.",
+		"  Wait until the user submits, then print what needs you. The timeout defaults to 540 seconds.",
 		"  Give the shell command a timeout of at least 600000 ms, or in Claude Code run it with run_in_background",
 		"  and --timeout 7080."
 	].join("\n"),