dsh-diff-approval 0.29.1 → 0.30.1

package/lib/index.js

@@ -1,11 +1,12 @@
 import { createRequire } from "node:module";
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dshHomePath, expandHomePath } from "@deepseek-ai/dsh-home-paths";
 import "@deepseek-ai/cordis";
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 //#region node_modules/.pnpm/@deepseek-ai+cosmokit@1.8.2/node_modules/@deepseek-ai/cosmokit/lib/index.js
 /** Return true when a value is `null` or `undefined`. */
 function isNullable(value) {
@@ -904,6 +905,33 @@ function sameEntry(left, right) {
 var PendingDiffStore = class {
 	entries = /* @__PURE__ */ new Map();
 	/**
+	* The content version of each entry: bumped whenever its tracked `newText` moves, and never for a
+	* change that leaves the content alone (a block keep advances `oldText` only).
+	*
+	* It is what lets derived, content-dependent state — the lines a comment's quote resolves to, read
+	* off `newText` — be cached and refreshed when the content moved rather than recomputed on every
+	* read. The versions come from one monotonic counter and are never reused, so an entry that leaves
+	* the list and comes back cannot hand back the number a stale cache was keyed to.
+	*/
+	contentVersions = /* @__PURE__ */ new Map();
+	/** The last version handed out; only ever climbs (see `contentVersions`). */
+	contentVersionCounter = 0;
+	/** Note that one path's tracked content moved, and give it a fresh version. */
+	bumpContent(path) {
+		this.contentVersions.set(pathKeyOf(path), ++this.contentVersionCounter);
+	}
+	/**
+	* The version of one path's tracked content, or 0 while it has none.
+	*
+	* Two calls that return the same number describe the same `newText`: a caller caching something
+	* derived from that content may serve its copy until the number changes.
+	* @param path - the file path (the global entry key).
+	* @returns the path's content version.
+	*/
+	contentVersion(path) {
+		return this.contentVersions.get(pathKeyOf(path)) ?? 0;
+	}
+	/**
 	* Merge one captured operation into its file's entry. A no-op (equal before
 	* and after) folds nothing.
 	* @param entry - the captured operation (id assigned by the caller).
@@ -919,6 +947,7 @@ var PendingDiffStore = class {
 		const merged = current === void 0 ? { ...entry } : this.mergeEntry(current, entry);
 		if (current !== void 0 && sameEntry(current, merged)) return false;
 		this.entries.set(pathKeyOf(merged.path), merged);
+		if (current === void 0 || current.newText !== merged.newText) this.bumpContent(merged.path);
 		return true;
 	}
 	/**
@@ -969,7 +998,10 @@ var PendingDiffStore = class {
 	* @returns whether an entry was removed.
 	*/
 	remove(path) {
-		return this.entries.delete(pathKeyOf(path));
+		const key = pathKeyOf(path);
+		const removed = this.entries.delete(key);
+		if (removed) this.contentVersions.delete(key);
+		return removed;
 	}
 	/**
 	* Advance one entry's tracked content after a block-level keep/revert. The
@@ -987,6 +1019,7 @@ var PendingDiffStore = class {
 			updatedAt: Date.now()
 		};
 		this.entries.set(pathKeyOf(path), next);
+		if (next.newText !== entry.newText) this.bumpContent(path);
 		return true;
 	}
 	/**
@@ -1000,6 +1033,7 @@ var PendingDiffStore = class {
 		const existing = this.entries.get(key);
 		if (existing !== void 0 && sameEntry(existing, entry)) return false;
 		this.entries.set(key, { ...entry });
+		if (existing === void 0 || existing.newText !== entry.newText) this.bumpContent(entry.path);
 		return true;
 	}
 	/**
@@ -1029,6 +1063,90 @@ var PendingDiffStore = class {
 	}
 };
 //#endregion
+//#region lib/types/atomic-write.js
+/**
+* Stage a JSON envelope beside its target and rename it into place, retrying the rename.
+*
+* Both stores in this plugin persist the same way — write a sibling temp file, `rename` it over the
+* real one — because a crash must leave either the old file or the new one and never a torn one. What
+* neither of them did was survive the rename itself being refused, and on Windows that is not rare:
+* replacing a file another process has open at that instant answers `EPERM`, and the readers here are
+* everyone — a second panel, a backup agent, an antivirus, the user's own editor, or this suite's own
+* 50ms `readFile` loop waiting for the write. The refusal is transient by construction (the handle that
+* caused it closes within a tick), but the write it killed was the ONLY copy of that update: the
+* pending list or a session's comment file simply kept its previous content, and the failure was
+* reported as "your threads will not survive a restart" without ever being retried.
+*
+* So the rename is attempted a few times with a short, growing pause. Measured on this machine with a
+* concurrent reader, the retry turns 6 lost writes in 12 into 0 — see `tests/atomic-write.spec.ts` for
+* the deterministic shape (an injected rename that fails once) and the commit message for the numbers.
+*
+* Failures that are NOT about a held handle (a missing directory, a full disk, a read-only mount) are
+* rethrown on the first attempt: retrying those only delays the report the caller has to make.
+*
+* The directory is `node:path`'s own `dirname`, not a scan for the last separator: on Windows the
+* storage root is `C:\Users\<user>\.dsh\diff-approval\workspaces`, which holds no forward slash at all —
+* a scan answered `.`, the `mkdir` before each write became a no-op, and the write threw ENOENT, so
+* nothing was ever persisted there.
+*
+* @module dsh-diff-approval/src/atomic-write
+*/
+/**
+* The default policy: five attempts, 25ms then 50, 100, 200 — a little over a third of a second in all.
+*
+* Long enough for the handle that refused the rename to be closed (a reader gets its next turn of the
+* loop, an antivirus finishes its scan), and short enough that a caller who is waiting on the write
+* — the panel's keep, a comment being added — cannot tell it retried at all.
+*/
+const ATOMIC_WRITE_RETRY = {
+	attempts: 5,
+	delayMs: 25
+};
+/**
+* Whether one rename error is the transient "somebody else has this file open" refusal.
+*
+* Windows answers `EPERM` for a replace whose target is open; `EACCES` and `EBUSY` are the same
+* situation seen through a network share or a mapped drive. Nothing else is retried.
+*
+* @param error - whatever the rename threw.
+* @returns whether another attempt is worth making.
+*/
+function isHeldOpen(error) {
+	const code = error?.code;
+	return code === "EPERM" || code === "EACCES" || code === "EBUSY";
+}
+/**
+* Write one JSON envelope atomically, retrying a rename that a held handle refused.
+*
+* @param file - the file to replace.
+* @param value - the value to serialise into it.
+* @param options - the fs verbs and the retry policy, for tests.
+* @throws the rename's own error when the attempts run out, or at once when it is not a held handle.
+*/
+async function writeJsonAtomic(file, value, options = {}) {
+	const io = {
+		mkdir,
+		writeFile,
+		rename,
+		remove: (staged) => rm(staged, { force: true }),
+		...options.fs
+	};
+	const retry = options.retry ?? ATOMIC_WRITE_RETRY;
+	await io.mkdir(dirname(file), { recursive: true });
+	const staged = `${file}.${process.pid}.${Date.now()}.tmp`;
+	await io.writeFile(staged, JSON.stringify(value), "utf8");
+	for (let attempt = 1;; attempt++) try {
+		await io.rename(staged, file);
+		return;
+	} catch (error) {
+		if (attempt >= retry.attempts || !isHeldOpen(error)) {
+			await io.remove(staged).catch(() => {});
+			throw error;
+		}
+		await new Promise((resolve) => setTimeout(resolve, retry.delayMs * 2 ** (attempt - 1)));
+	}
+}
+//#endregion
 //#region lib/types/persist.js
 /**
 * Durable pending-entry persistence under the harness home: one global JSON
@@ -1089,7 +1207,7 @@ function globalFileOf(file, value) {
 	};
 }
 /** Read one file's content; `undefined` when absent (the normal empty state). */
-async function readJson(file) {
+async function readJson$1(file) {
 	let raw;
 	try {
 		raw = await readFile(file, "utf8");
@@ -1103,33 +1221,6 @@ async function readJson(file) {
 		throw new Error(`pending persistence file '${file}' is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
-/** Stage a JSON envelope as a sibling temp file and atomically rename it into place. */
-async function writeJson(file, value) {
-	await mkdir(dirName(file), { recursive: true });
-	const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-	await writeFile(tmp, JSON.stringify(value), "utf8");
-	try {
-		await rename(tmp, file);
-	} catch (error) {
-		await rm(tmp, { force: true }).catch(() => {});
-		throw error;
-	}
-}
-/**
-* The directory a path names, in the platform's own spelling.
-*
-* `node:path` rather than a scan for the last `/`: on Windows the storage root is
-* `C:\Users\<user>\.dsh\diff-approval\workspaces`, which contains no forward slash at all — the
-* scan answered `.`, the `mkdir` before every write became a no-op, and the write itself threw
-* ENOENT, so no pending change was ever persisted there (the failure only reached a logger
-* warning). Both separators have to be understood, and only the platform knows which they are.
-*
-* @param file - the file whose directory is wanted.
-* @returns that directory, or `.` for a bare file name.
-*/
-function dirName(file) {
-	return dirname(file);
-}
 /**
 * File-backed pending entries, one global file keyed by path.
 */
@@ -1153,7 +1244,7 @@ var PendingPersistence = class {
 	* a save to finalize the migration).
 	*/
 	async loadAll() {
-		const global = await readJson(this.globalFile);
+		const global = await readJson$1(this.globalFile);
 		if (global !== void 0) {
 			const parsed = globalFileOf(this.globalFile, global);
 			const entries = [];
@@ -1185,7 +1276,7 @@ var PendingPersistence = class {
 	*/
 	save(entries) {
 		const task = async () => {
-			await writeJson(this.globalFile, {
+			await writeJsonAtomic(this.globalFile, {
 				version: FILE_VERSION,
 				entries
 			});
@@ -1208,7 +1299,7 @@ async function collectLegacy(root) {
 	const entries = [];
 	for (const name of names) {
 		if (name === "pending.json" || !name.endsWith(".json")) continue;
-		const value = await readJson(join(root, name));
+		const value = await readJson$1(join(root, name));
 		if (value === void 0) continue;
 		if (typeof value !== "object" || value === null) continue;
 		const { version, sessions } = value;
@@ -1239,6 +1330,1172 @@ async function removeLegacy(root) {
 	}
 }
 //#endregion
+//#region lib/types/comments.js
+/**
+* Durable comment threads, one JSON file per session under
+* `<commentsDir>/<sessionId>.json`, beside the pending-entry storage but never in
+* the same file: a comment that outlived its entry is exactly the leak this
+* module exists to prevent, so a pending write that fails must not be able to
+* take comments with it (or the other way round).
+*
+* A comment belongs to ONE pending entry (`entryId`, which is the entry's path —
+* the store's global identity) and to ONE session. It carries the annotation and
+* the identity of the turn that answered it (`messageId`, `turn`); it does NOT
+* carry the answer's text, because the session transcript stays the single source
+* of truth for what the agent said — a client reads the answer out of the
+* transcript by that id. Saves rewrite the whole session file, staged as a sibling
+* temp file and atomically renamed, so a crash leaves either the old or the new
+* file. A missing file reads as empty; unknown versions and non-JSON content throw.
+* @module dsh-diff-approval/src/comments
+*/
+/** On-disk envelope of one session's comments. */
+const COMMENT_FILE_VERSION = 1;
+/**
+* The comment directory that belongs to a pending-storage root.
+*
+* The plugin's own state directory is `<dshHome>/diff-approval`, and inside it the
+* pending file lives in `workspaces/` and comments in `comments/` — siblings, so a
+* write that fails on one side cannot take the other with it. Any OTHER root is a
+* self-contained state directory (a deployment's chosen location, a test's temp
+* dir) and keeps its comments INSIDE it: the sibling of an arbitrary directory can
+* be shared by two instances that were each pointed somewhere different, and two
+* instances writing one comment file is a leak rather than a layout choice.
+*
+* @param storageRoot - the resolved pending-storage root.
+* @returns the directory holding the comments that belong to that root.
+*/
+function commentsDirFor(storageRoot) {
+	return basename(storageRoot) === "workspaces" ? join(dirname(storageRoot), "comments") : join(storageRoot, "comments");
+}
+/** The file one session's comments are stored in (the id, made filename-safe). */
+function fileOf(root, sessionId) {
+	return join(root, `${encodeURIComponent(String(sessionId))}.json`);
+}
+/** Narrow one JSON value to a comment record; malformed rows are skipped. */
+function commentOf(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const row = value;
+	const { id, sessionId, entryId, path, anchor, quote, text, createdAt, updatedAt } = row;
+	if (typeof id !== "string" || id.length === 0) return void 0;
+	if (typeof sessionId !== "string" || sessionId.length === 0) return void 0;
+	if (typeof entryId !== "string" || entryId.length === 0) return void 0;
+	if (typeof path !== "string" || path.length === 0) return void 0;
+	if (typeof anchor !== "object" || anchor === null) return void 0;
+	const lines = anchor;
+	if (typeof lines.startLine !== "number" || typeof lines.endLine !== "number") return void 0;
+	if (typeof quote !== "string") return void 0;
+	if (typeof text !== "string") return void 0;
+	if (typeof createdAt !== "number" || typeof updatedAt !== "number") return void 0;
+	const context = row.quoteContext;
+	const quoteLines = Array.isArray(row.quoteLines) ? row.quoteLines.filter((entry) => typeof entry === "object" && entry !== null) : [];
+	const author = row.author === "agent" ? "agent" : void 0;
+	return {
+		id,
+		sessionId,
+		entryId,
+		path,
+		anchor: {
+			startLine: lines.startLine,
+			endLine: lines.endLine
+		},
+		quote,
+		text,
+		createdAt,
+		updatedAt,
+		...author === void 0 ? {} : { author },
+		...typeof context === "string" && context !== "" ? { quoteContext: context } : {},
+		...quoteLines.length > 0 ? { quoteLines } : {},
+		...asksOf(row.asks).length > 0 ? { asks: asksOf(row.asks) } : {}
+	};
+}
+/** Narrow a stored thread's questions; malformed rows are skipped. */
+function asksOf(value) {
+	if (!Array.isArray(value)) return [];
+	const asks = [];
+	for (const row of value) {
+		if (typeof row !== "object" || row === null || Array.isArray(row)) continue;
+		const record = row;
+		const requestId = record.requestId;
+		if (typeof requestId !== "string" || requestId.length === 0) continue;
+		const turn = record.turn;
+		const text = record.text;
+		asks.push({
+			requestId,
+			...typeof text === "string" && text !== "" ? { text } : {},
+			...typeof turn === "number" ? { turn } : {},
+			...record.dropped === true ? { dropped: true } : {},
+			...record.ended === true ? { ended: true } : {}
+		});
+	}
+	return asks;
+}
+/** Whether one thread holds a question with this request id that `wanted` still describes. */
+function hasAsk(comment, requestId, wanted) {
+	return (comment.asks ?? []).some((ask) => ask.requestId === requestId && wanted(ask));
+}
+/** Read one file's JSON; `undefined` when absent (the normal empty state). */
+async function readJson(file) {
+	let raw;
+	try {
+		raw = await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (error) {
+		throw new Error(`comment file '${file}' is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/** Validate a parsed comment file. */
+function commentFileOf(file, value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`comment file '${file}' is not a comment file`);
+	const { version, comments } = value;
+	if (version !== COMMENT_FILE_VERSION) throw new Error(`comment file '${file}' has unsupported version ${JSON.stringify(version)}`);
+	if (!Array.isArray(comments)) throw new Error(`comment file '${file}' has no comment list`);
+	return {
+		version,
+		comments
+	};
+}
+/** One thrown value's human text, whatever shape it arrived in. */
+function reasonOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* File-backed comment threads, one file per session.
+*
+* Every mutation is applied to memory synchronously and schedules that session's
+* file write on its own chain, so a caller removing an entry can drop its comments
+* in the same tick as the entry itself without awaiting anything — the same
+* fire-and-forget persistence the pending store uses.
+*/
+var CommentStore = class {
+	root;
+	options;
+	byId = /* @__PURE__ */ new Map();
+	tails = /* @__PURE__ */ new Map();
+	revision = 0;
+	/** Files `loadAll` could not read, in the order it met them (see `skippedFiles`). */
+	skipped = /* @__PURE__ */ new Set();
+	/**
+	* The save failure of every session that has one, keyed by that session's file and in the
+	* order the failures happened (see `persistError`). Empty while every write works.
+	*/
+	persistFailures = /* @__PURE__ */ new Map();
+	/**
+	* Sessions whose unreadable file could not even be moved aside, keyed by that file: the
+	* reason their writes are refused rather than allowed to truncate the bytes (see `save`).
+	*/
+	unmovable = /* @__PURE__ */ new Map();
+	/**
+	* @param root - directory holding one `<sessionId>.json` per session.
+	* @param options - the error seam (see {@link CommentStoreOptions}).
+	*/
+	constructor(root, options = {}) {
+		this.root = root;
+		this.options = options;
+	}
+	/**
+	* Load every session's comments. A malformed row is skipped rather than
+	* failing the load: one bad comment must not cost the whole workspace's
+	* comments (or the plugin's activation).
+	*
+	* A file that cannot be READ is skipped the same way, because the alternative is
+	* worse in both directions: the old all-or-nothing load threw, the caller logged
+	* once and carried on with an EMPTY store, and the next save then wrote that
+	* emptiness back over every good file. One unreadable file therefore cost every
+	* session's comments. Skipping keeps the other sessions' threads, and the skipped
+	* file is moved aside (`.corrupt`) rather than dropped: it is not deleted — the
+	* bytes may be the only copy — but it is also not left where the next save for
+	* that session would silently overwrite it, which would destroy them for good.
+	*
+	* When even that fails — the file cannot be moved aside — that session's writes are
+	* refused from then on (see `save`) rather than allowed to truncate the only copy.
+	* "Skipped but still writable" is exactly the shape that turns a read failure into
+	* data loss: the store would answer "added", write the memory-only view over bytes
+	* nobody could read, and lose what the skip had just refused to guess at.
+	* @returns how many comments were loaded.
+	*/
+	async loadAll() {
+		let names;
+		try {
+			names = await readdir(this.root);
+		} catch (error) {
+			if (error.code === "ENOENT") return 0;
+			throw error;
+		}
+		for (const name of names) {
+			if (!name.endsWith(".json") || name.endsWith(".tmp")) continue;
+			const file = join(this.root, name);
+			let value;
+			let comments;
+			try {
+				value = await readJson(file);
+				if (value === void 0) continue;
+				comments = commentFileOf(file, value).comments;
+			} catch (error) {
+				await this.skip(file, error);
+				continue;
+			}
+			for (const row of comments) {
+				const comment = commentOf(row);
+				if (comment !== void 0) this.byId.set(comment.id, comment);
+			}
+		}
+		this.revision += 1;
+		return this.byId.size;
+	}
+	/**
+	* The files a load skipped, so the caller can say what went missing instead of
+	* reporting a session whose comments silently vanished.
+	* @returns the skipped files' paths, in load order.
+	*/
+	skippedFiles() {
+		return [...this.skipped];
+	}
+	/**
+	* The failure the reader has to be told about, or `undefined` while every write works.
+	* This is what rides the list read so the panel can say the threads are memory-only;
+	* a later successful save retracts it, mirroring the pending half's own report.
+	*
+	* Per SESSION, not one global slot: a deployment where one session's file cannot be
+	* written and another's can is the ordinary case (a locked file, a full quota, a
+	* directory that vanished), and letting the healthy write retract the broken one's
+	* report would say the threads are safe while that session's live in memory only —
+	* the same "a failure that looks like a success" trap, one session over. A session's
+	* own success is what retracts its own entry (see `reportPersist`).
+	* @returns the most recent outstanding failure's message, or undefined.
+	*/
+	persistError() {
+		let message;
+		for (const failure of this.persistFailures.values()) message = failure;
+		return message;
+	}
+	/**
+	* Record a skipped file: keep it for the caller, name it, and move it aside so a later
+	* save for that session writes a fresh file rather than overwriting the unreadable
+	* bytes. A quarantine that itself fails is still a skip — the store must not be the
+	* reason a single bad file takes the whole load down — but that session's file is then
+	* the only copy of its threads, so its writes are refused (see `save`) instead of being
+	* allowed to truncate it.
+	* @param file - the file that could not be read.
+	* @param error - why it could not be read.
+	*/
+	async skip(file, error) {
+		this.skipped.add(file);
+		const quarantined = `${file}.corrupt`;
+		try {
+			await rename(file, quarantined);
+		} catch (failure) {
+			this.unmovable.set(file, `could not be read at load (${reasonOf(error)}) and could not be moved aside to '${quarantined}' (${reasonOf(failure)})`);
+		}
+		this.options.onLoadSkipped?.(file, error);
+	}
+	/** One session's comments, oldest first (the order threads are read in). */
+	list(sessionId) {
+		const listed = [];
+		for (const comment of this.byId.values()) if (comment.sessionId === sessionId) listed.push(comment);
+		return listed.sort((left, right) => left.createdAt - right.createdAt);
+	}
+	/** A comment by id, whatever session it belongs to. */
+	get(id) {
+		return this.byId.get(id);
+	}
+	/**
+	* A counter bumped on every change, so a poller can tell "nothing new" from
+	* "re-read": the list endpoint ships the session's comments anyway, and this is
+	* what says whether anything moved since the last read.
+	*/
+	commentsRevision() {
+		return this.revision;
+	}
+	/**
+	* Record one annotation.
+	*
+	* Writing a comment that is already here is the SAME comment written again — a client
+	* retrying a request whose response was dropped, or a second client sending the id it
+	* was handed — so the questions already asked in it are kept and only the annotation's
+	* own fields move. Overwriting the whole record would erase the identity of a question
+	* that is in flight, and its answer could then never be matched back to this thread;
+	* `createdAt` is kept for the same reason, since it is what a list read orders by.
+	*
+	* @param record - the comment to store.
+	* @returns the stored comment, which is the existing one when the id was already here.
+	*/
+	add(record) {
+		const stored = this.mergeOf(record);
+		this.byId.set(record.id, stored);
+		this.revision += 1;
+		this.save(record.sessionId);
+		return stored;
+	}
+	/**
+	* Record several annotations at once, as ONE write per affected session.
+	*
+	* This is what putting a batch of restored comments back needs and what a loop of `add` calls
+	* cannot give it: each `add` saves its session's file, so an undo that restored ten threads wrote
+	* that file ten times — ten chances for a transient failure to leave the store and the disk
+	* disagreeing about an action the reader already watched happen. The records are stored by the SAME
+	* rule as `add` (a new id verbatim, an existing one merged with its `createdAt` and its questions
+	* kept), which is what lets a restore be an ordinary write rather than a special case: a snapshot
+	* that came back as a new comment, with a fresh id and no questions, would be a look-alike of the
+	* reader's thread.
+	*
+	* A batch that carries nothing changes nothing, so a no-op restore does not rewrite a file.
+	*
+	* @param records - the comments to store, in the caller's order.
+	* @returns the stored record for each input, index-aligned: what landed, which is not always what
+	*   was handed over (a merge keeps the fields the existing comment owns). A count would drop that,
+	*   and a caller needing it would have to `get` each id back and race a later change.
+	*/
+	addMany(records) {
+		const stored = [];
+		const sessions = /* @__PURE__ */ new Set();
+		for (const record of records) {
+			const merged = this.mergeOf(record);
+			this.byId.set(record.id, merged);
+			stored.push(merged);
+			sessions.add(record.sessionId);
+		}
+		if (records.length === 0) return stored;
+		this.revision += 1;
+		for (const sessionId of sessions) this.save(sessionId);
+		return stored;
+	}
+	/**
+	* The record as the store keeps it: a new id VERBATIM, an id already here merged.
+	*
+	* The one place the merge rule lives, so `add` and `addMany` cannot drift: writing a comment that
+	* is already here is the same comment written again — a client retrying a request whose response
+	* was dropped, or a second client sending the id it was handed — so the questions already asked in
+	* it are kept and only the annotation's own fields move. Overwriting the whole record would erase
+	* the identity of a question that is in flight, and its answer could then never be matched back to
+	* this thread; `createdAt` is kept for the same reason, since it is what a list read orders by.
+	* @param record - the comment as the caller wrote it.
+	* @returns the record to store under its id.
+	*/
+	mergeOf(record) {
+		const before = this.byId.get(record.id);
+		return before === void 0 ? record : {
+			...record,
+			createdAt: before.createdAt,
+			...before.asks === void 0 ? {} : { asks: before.asks }
+		};
+	}
+	/**
+	* Drop one comment.
+	* @param sessionId - the session the caller believes the comment belongs to.
+	* @param id - the comment to drop.
+	* @returns whether it was there (and belonged to that session).
+	*/
+	remove(sessionId, id) {
+		return this.removeMany(sessionId, [id]).length === 1;
+	}
+	/**
+	* Drop several comments of one session in ONE write.
+	*
+	* This is what a batch action needs and what a loop of `remove` calls cannot give it: each
+	* `remove` saves the session's file, so ending ten comments wrote that file ten times — ten
+	* chances for a transient failure to leave the store and the disk disagreeing about an action
+	* the reader asked for once. The save happens only when something was actually dropped, so a
+	* batch that matches nothing does not rewrite the file.
+	*
+	* An id of another session, or one that is not here at all, is skipped rather than refused:
+	* a batch is one request and the comments it names are the ones it can act on, and a comment
+	* another client already ended is the state the caller was asking for anyway.
+	*
+	* @param sessionId - the session the caller believes the comments belong to.
+	* @param ids - the comments to drop; a repeated id is one comment.
+	* @returns the ids that were dropped, in the order given.
+	*/
+	removeMany(sessionId, ids) {
+		const removed = [];
+		for (const id of ids) {
+			if (removed.includes(id)) continue;
+			const comment = this.byId.get(id);
+			if (comment === void 0 || comment.sessionId !== sessionId) continue;
+			this.byId.delete(id);
+			removed.push(id);
+		}
+		if (removed.length === 0) return removed;
+		this.revision += 1;
+		this.save(sessionId);
+		return removed;
+	}
+	/**
+	* Every comment one pending entry carries, oldest first.
+	*
+	* The read half of `removeForEntry` and kept beside it, because they are two answers about the same
+	* fact: which comments an entry owns. A caller that is about to drop the entry asks this first, so
+	* the undo pair can carry them back; the two must agree on that set, or a restore would put back
+	* fewer (or more) threads than the drop took.
+	* @param entryId - the entry id (= path).
+	* @returns that entry's comments, in list order.
+	*/
+	forEntry(entryId) {
+		const listed = [];
+		for (const comment of this.byId.values()) if (comment.entryId === entryId) listed.push(comment);
+		return listed.sort((left, right) => left.createdAt - right.createdAt);
+	}
+	/**
+	* Drop every comment of one pending entry. This is what "a comment dies with
+	* its entry" means, and the entry knows nothing about comments, so the caller
+	* runs it beside the entry's own removal.
+	* @param entryId - the entry id (= path) that left the list.
+	* @returns how many comments went with it.
+	*/
+	removeForEntry(entryId) {
+		const sessions = /* @__PURE__ */ new Set();
+		let removed = 0;
+		for (const comment of [...this.byId.values()]) {
+			if (comment.entryId !== entryId) continue;
+			this.byId.delete(comment.id);
+			sessions.add(comment.sessionId);
+			removed += 1;
+		}
+		if (removed > 0) {
+			this.revision += 1;
+			for (const sessionId of sessions) this.save(sessionId);
+		}
+		return removed;
+	}
+	/**
+	* The orphan sweep: drop every comment whose entry is not in `entryIds`.
+	*
+	* The explicit `removeForEntry` is the primary path; this is the backstop that
+	* catches a comment left behind by a crash between the two writes. Run it when
+	* the store loads and on every list read, and the one race it could lose — an
+	* entry re-added after its comments were already swept — cannot happen: entries
+	* only leave through this host, so an entry absent at load time was removed
+	* while the host was running, and the sweep at load runs before anything can
+	* add it back.
+	* @param entryIds - every entry id the pending store currently holds.
+	* @returns how many orphaned comments were dropped.
+	*/
+	retain(entryIds) {
+		const sessions = /* @__PURE__ */ new Set();
+		let removed = 0;
+		for (const comment of [...this.byId.values()]) {
+			if (entryIds.has(comment.entryId)) continue;
+			this.byId.delete(comment.id);
+			sessions.add(comment.sessionId);
+			removed += 1;
+		}
+		if (removed > 0) {
+			this.revision += 1;
+			for (const sessionId of sessions) this.save(sessionId);
+		}
+		return removed;
+	}
+	/**
+	* Record one question asked in a thread. The answer itself is never stored, and the
+	* request id is minted by the caller before it submits, so this runs as part of the
+	* ask rather than waiting for the session to answer. A thread keeps its questions in
+	* order: the first is the annotation's own, and each follow-up appends.
+	*
+	* The reader's own words are stored WITH the question (`text`), because they exist
+	* nowhere else: the transcript holds the prompt, which is those words wrapped in the
+	* marker, the reference and the rules, and a thread that showed the prompt would show
+	* the scaffolding rather than the question.
+	*
+	* @param sessionId - the session the comment belongs to.
+	* @param id - the comment that was asked in.
+	* @param requestId - the identity the submission carries into the transcript.
+	* @param turn - the turn that claimed it, when that is already known.
+	* @param text - the reader's own words, without the prompt's wrapper.
+	* @returns whether the comment existed.
+	*/
+	recordAsk(sessionId, id, requestId, turn, text) {
+		return this.patch((comment) => comment.sessionId === sessionId && comment.id === id, (comment) => ({
+			...comment,
+			asks: [...comment.asks ?? [], {
+				requestId,
+				text,
+				...turn === void 0 ? {} : { turn }
+			}],
+			updatedAt: Date.now()
+		})) > 0;
+	}
+	/**
+	* Record the turn that claimed one question, as the agent's inbox reported it. Two
+	* questions claimed by the same turn were answered together, which is a fact the
+	* panel can state instead of guessing from transcript positions.
+	* @param sessionId - the session the submission belongs to.
+	* @param requestId - the request identity the inbox reported back.
+	* @param turn - the turn that claimed it.
+	* @returns how many threads the patch touched.
+	*/
+	recordTurnForRequest(sessionId, requestId, turn) {
+		return this.patch((comment) => comment.sessionId === sessionId && hasAsk(comment, requestId, (ask) => ask.turn !== turn), (comment) => ({
+			...comment,
+			asks: (comment.asks ?? []).map((ask) => ask.requestId === requestId ? {
+				...ask,
+				turn
+			} : ask),
+			updatedAt: Date.now()
+		}));
+	}
+	/**
+	* Record that the session dropped one question before a turn claimed it: nothing is
+	* coming, and the reader is told rather than left waiting.
+	* @param sessionId - the session the submission belongs to.
+	* @param requestId - the request identity the inbox reported back.
+	* @returns how many threads the patch touched.
+	*/
+	markDroppedForRequest(sessionId, requestId) {
+		return this.patch((comment) => comment.sessionId === sessionId && hasAsk(comment, requestId, (ask) => ask.dropped !== true), (comment) => ({
+			...comment,
+			asks: (comment.asks ?? []).map((ask) => ask.requestId === requestId ? {
+				...ask,
+				dropped: true
+			} : ask),
+			updatedAt: Date.now()
+		}));
+	}
+	/**
+	* Record that a turn is over, so the questions it claimed stop looking pending.
+	*
+	* The turn number is the only handle the stopping event carries — no message, no
+	* request id — so the questions that were claimed by that turn are the ones patched
+	* (see `recordTurnForRequest`, which wrote the number down when the inbox claimed
+	* them). A question whose turn is over and that the transcript shows no answer for
+	* was cut off; the client says so instead of waiting forever. Nothing here decides
+	* that: whether an answer exists is read from the transcript on each list read, so a
+	* turn that stopped AFTER writing its answer keeps showing the answer.
+	*
+	* @param sessionId - the session whose turn ended.
+	* @param turn - the turn that stopped.
+	* @returns how many threads the patch touched.
+	*/
+	markTurnEnded(sessionId, turn) {
+		return this.patch((comment) => comment.sessionId === sessionId && (comment.asks ?? []).some((ask) => ask.turn === turn && ask.ended !== true), (comment) => ({
+			...comment,
+			asks: (comment.asks ?? []).map((ask) => ask.turn === turn ? {
+				...ask,
+				ended: true
+			} : ask),
+			updatedAt: Date.now()
+		}));
+	}
+	/**
+	* Apply one patch to every comment it matches, and schedule the affected sessions'
+	* writes. The one mutation seam, so no caller has to remember to bump the revision
+	* or to save: a patch that matches nothing changes nothing.
+	* @param match - which comments to patch.
+	* @param patch - the change to apply.
+	* @returns how many comments changed.
+	*/
+	patch(match, patch) {
+		const sessions = /* @__PURE__ */ new Set();
+		let changed = 0;
+		for (const comment of [...this.byId.values()]) {
+			if (!match(comment)) continue;
+			this.byId.set(comment.id, patch(comment));
+			sessions.add(comment.sessionId);
+			changed += 1;
+		}
+		if (changed > 0) {
+			this.revision += 1;
+			for (const sessionId of sessions) this.save(sessionId);
+		}
+		return changed;
+	}
+	/**
+	* Wait for every scheduled write to settle.
+	*
+	* The mutators return as soon as a change is in memory — that is what lets an
+	* entry's removal take its comments with it in the same tick — so this is how a
+	* caller that must not lose the write (a dispose path, a test asserting the file)
+	* waits for the disk.
+	* @returns resolution after every session file's write chain has drained.
+	*/
+	async settled() {
+		await Promise.all([...this.tails.values()]);
+	}
+	/**
+	* Write one session's comments, serialized against that file's own writes.
+	*
+	* A rejected write is reported, not swallowed: the mutation already answered
+	* "added" and the panel is drawing the thread from memory, so a silent failure means
+	* the reader keeps writing into a thread that a restart will erase. The report rides
+	* the list read (`persistError`) and the caller's logger, and a later write that works
+	* retracts it the way the pending half retracts its own.
+	*
+	* A session whose file could not be read at load AND could not be moved aside is not
+	* written at all: the only copy of that session's threads is the bytes the load could
+	* not parse, and the store's memory holds just what has been added since. Writing the
+	* memory-only view would TRUNCATE that copy — turning a read failure into a permanent
+	* loss — so the save is refused and reported instead, which is what tells the reader
+	* those comments are memory-only.
+	* @param sessionId - the session whose file to rewrite.
+	*/
+	save(sessionId) {
+		const file = fileOf(this.root, sessionId);
+		const refused = this.unmovable.get(file);
+		if (refused !== void 0) {
+			this.reportPersist(file, `'${file}' ${refused}, so this session's comments are kept in memory rather than written over it`);
+			return;
+		}
+		const comments = this.list(sessionId);
+		const task = async () => {
+			await writeJsonAtomic(file, {
+				version: COMMENT_FILE_VERSION,
+				comments
+			});
+		};
+		const run = (this.tails.get(file) ?? Promise.resolve()).then(task, task);
+		this.tails.set(file, run.then(() => {
+			this.reportPersist(file, void 0);
+		}, (error) => {
+			this.reportPersist(file, `${file}: ${reasonOf(error)}`);
+		}));
+	}
+	/**
+	* Publish the write state of one session's file, once per distinct report. Kept as its own
+	* step so both the success and the failure of the chain above land in one place — the
+	* retraction is what arms a later failure to be reported again.
+	*
+	* Keyed per file, so a healthy session's write cannot retract a broken one's report (see
+	* `persistError`); the callback sees the aggregate, which is what rides the list read.
+	* @param file - the session file the write was for.
+	* @param message - the failure's text, or undefined when the write worked.
+	*/
+	reportPersist(file, message) {
+		const before = this.persistError();
+		this.persistFailures.delete(file);
+		if (message !== void 0) this.persistFailures.set(file, message);
+		const after = this.persistError();
+		if (before === after) return;
+		this.options.onPersistError?.(after);
+	}
+};
+//#endregion
+//#region lib/types/comment-ask.js
+/**
+* Asking the session's agent about one comment, and reading the answer back out of
+* the transcript.
+*
+* The submission goes through the host's own session API (`ctx.sessionController`),
+* which is the one path that already knows how to admit a prompt: it mints the
+* message, persists it, and — the reason this module needs no identity of its own —
+* stores the request id the caller supplies on the exact user message it accepts
+* (`source.rpcId`). That id is the join key between a comment and its message, and it
+* makes a retried submission the same submission rather than a second one.
+*
+* The answer is never stored: `answers()` derives it from the session's own derived
+* message history on every read, so the transcript stays the single source of truth
+* for what the agent said. The agent is asked with `mode: 'queue'`, so a comment is
+* its own turn ("one ordinary message of its own turn") — two comments asked at the
+* same time are two turns, not one turn two blocks have to share.
+*
+* @module dsh-diff-approval/src/comment-ask
+*/
+/** Nothing was found: no message of ours, so no turn and no end. */
+const NO_READ = {
+	answer: void 0,
+	turn: void 0,
+	ended: false
+};
+/** The prompt text a message holds, or '' when it carries none. */
+function textOf(message) {
+	if (!Array.isArray(message.content)) return "";
+	const parts = [];
+	for (const block of message.content) {
+		if (typeof block !== "object" || block === null) continue;
+		const { type, text } = block;
+		if (type === "text" && typeof text === "string" && text !== "") parts.push(text);
+	}
+	return parts.join("\n").trim();
+}
+/** The request id one message was submitted under, when it has one. */
+function requestOf(message) {
+	const rpcId = message.source?.rpcId;
+	return typeof rpcId === "string" && rpcId !== "" ? rpcId : void 0;
+}
+/** The message one `user/message` or `assistant/message` event carries, or undefined. */
+function messageOf(event) {
+	const data = event.data;
+	if (data === void 0) return void 0;
+	return event.type === "assistant/message" ? data.message : {
+		role: data.role,
+		content: data.content,
+		source: data.source
+	};
+}
+/** The turn number one event attributes itself to, or `undefined` when the type has none. */
+function turnOf(event) {
+	const turn = event.data !== void 0 && "turn" in event.data ? event.data.turn : void 0;
+	return typeof turn === "number" ? turn : void 0;
+}
+/**
+* The answer to one submitted comment, read from the session's own event log.
+*
+* Our prompt and the turn that ran because of it are one thing. The submission carries a
+* request id on its `user/message` (`source.rpcId`), and `turn/start` is the bracket the
+* log puts around a turn, so the question's own turn IS the window: the assistant
+* messages of that turn are the answer, and `turn/end` for it is where the question is
+* over. Nothing between the two belongs to anyone else.
+*
+* That is what keeps a later input from stealing the answer. A session log has
+* user-role messages no human wrote — a subagent report, a background-job notice, an
+* injected context — and under the old "walk to the next human message, take the last
+* assistant text" rule any of them let the span run on into the NEXT turn's answer, so a
+* comment that had been answered was silently replaced by whatever the agent later said
+* about something else entirely. A tool-result message (role `user` as well) has the
+* same problem for the opposite reason: it is a boundary trap that would end a segment
+* mid-turn and make a question with a tool call behind it look unanswered. Bound by the
+* turn, both read correctly: the tool result is inside it, and the later input is not.
+*
+* @param events - the session's event log, in sequence order.
+* @param requestId - the request id the comment was submitted under.
+* @returns the claiming turn, its answer text, and whether the turn is over.
+*/
+function answerForRequest(events, requestId) {
+	let askedAt = -1;
+	let open;
+	for (let index = 0; index < events.length; index++) {
+		const event = events[index];
+		if (event === void 0 || event.type === void 0) continue;
+		if (event.type === "turn/start") {
+			open = turnOf(event);
+			continue;
+		}
+		if (event.type === "turn/end") {
+			if (open !== void 0 && turnOf(event) === open) open = void 0;
+			continue;
+		}
+		if (event.type !== "user/message") continue;
+		const message = messageOf(event);
+		if (message === void 0 || requestOf(message) !== requestId) continue;
+		askedAt = index;
+		let turn = turnOf(event) ?? open;
+		for (let back = index; turn === void 0 && back >= 0; back--) {
+			const earlier = events[back];
+			if (earlier?.type === "turn/start") turn = turnOf(earlier);
+		}
+		return readTurn(events, askedAt, turn);
+	}
+	return NO_READ;
+}
+/**
+* The answer the turn named by one question produced.
+*
+* Reads forward from the question: its turn's assistant messages are the answer, and that
+* turn's own `turn/end` is where the question is over. A question the bracketing above
+* could not attribute takes its turn from the FIRST message after it that names one — the
+* log is append-only and a question is followed by its own turn's step, so that is the
+* question's turn; it is what keeps a window whose `turn/start` is outside it readable.
+*
+* @param events - the session's event log, in sequence order.
+* @param askedAt - index of the question's own `user/message`.
+* @param turn - the turn the log attributed the question to, or undefined when it could not.
+* @returns the answer, the turn, and whether the turn is over.
+*/
+function readTurn(events, askedAt, turn) {
+	let claimed = turn;
+	let answer;
+	for (let index = askedAt + 1; index < events.length; index++) {
+		const event = events[index];
+		if (event === void 0) continue;
+		const eventTurn = turnOf(event);
+		if (claimed === void 0 && eventTurn !== void 0) claimed = eventTurn;
+		const mine = claimed === void 0 || eventTurn === void 0 || eventTurn === claimed;
+		if (event.type === "turn/end" && mine) return {
+			answer,
+			turn: claimed,
+			ended: true
+		};
+		if (event.type !== "assistant/message" || !mine) continue;
+		const message = messageOf(event);
+		const text = message === void 0 ? "" : textOf(message);
+		if (text !== "") answer = text;
+	}
+	return {
+		answer,
+		turn: claimed,
+		ended: false
+	};
+}
+/**
+* Read every question one session has asked, keyed by its request id.
+* @param events - the session's event log, in sequence order.
+* @param requestIds - the questions' request ids.
+* @returns the read per request id; a question the log holds nothing for reads as nothing.
+*/
+function answersIn(events, requestIds) {
+	const reads = {};
+	for (const requestId of requestIds) reads[requestId] = answerForRequest(events, requestId);
+	return reads;
+}
+/**
+* Submits comments as turns of their session, and reads their answers back.
+*
+* One instance serves every session: the store is the state, and the per-agent
+* subscription is registered on first use and lives with the agent's own context.
+*/
+var CommentAsker = class {
+	ctx;
+	comments;
+	/**
+	* The agent each session's inbox events are subscribed on, keyed by session id, with
+	* the disposers that release those subscriptions.
+	*
+	* Keyed by AGENT IDENTITY, not merely "this session id was watched once": a
+	* resumed or re-created agent for the same session id is a different object
+	* whose listeners live on its OWN context, so a session-id set would consider
+	* the new agent already watched and never subscribe to it — leaving `turn`
+	* undefined forever, `agent/turn-stopping` never arriving, and the panel stuck
+	* on "replying" with no way out (the defect this map replaces). The disposers are
+	* what keeps a replacement from leaking a second set of handlers per event.
+	*/
+	watched = /* @__PURE__ */ new Map();
+	/**
+	* @param ctx - the plugin's host context (its `sessionController` and `agents` are asked for lazily).
+	* @param comments - the comment store the ask is recorded in.
+	*/
+	constructor(ctx, comments) {
+		this.ctx = ctx;
+		this.comments = comments;
+	}
+	/**
+	* Ask one stored comment as its own turn.
+	*
+	* The request id is recorded BEFORE the submission leaves, so a claim event that
+	* arrives while the submission is still in flight already finds its comment. A
+	* submission that rejects is marked dropped rather than left looking pending.
+	*
+	* @param sessionId - the session the comment belongs to.
+	* @param commentId - the comment to ask.
+	* @param prompt - the prompt text to send verbatim.
+	* @param text - the reader's own words, which the prompt wraps: the thread keeps these.
+	* @param signal - aborts the submission.
+	* @returns what the request did.
+	*/
+	async ask(sessionId, commentId, prompt, text, signal) {
+		const comment = this.comments.get(commentId);
+		if (comment === void 0 || comment.sessionId !== sessionId) return { outcome: "missing" };
+		const controller = this.ctx.get("sessionController");
+		if (typeof controller?.prompt !== "function") {
+			this.ctx.logger.warn("diff-approval: no sessionController.prompt in this host, so a comment cannot be asked");
+			return { outcome: "no-agent" };
+		}
+		if (this.agentOf(sessionId) === void 0) {
+			this.ctx.logger.warn(`diff-approval: no live agent for session ${String(sessionId)}, so a comment cannot be asked`);
+			return { outcome: "no-agent" };
+		}
+		this.watch(sessionId);
+		const requestId = randomUUID();
+		this.comments.recordAsk(sessionId, commentId, requestId, void 0, text);
+		try {
+			await controller.prompt({
+				requestId,
+				sessionId,
+				mode: "queue",
+				content: [{
+					type: "text",
+					text: prompt
+				}]
+			}, signal);
+			return {
+				outcome: "asked",
+				requestId
+			};
+		} catch (error) {
+			const reason = rejectionText(error);
+			this.ctx.logger.warn(`diff-approval: asking a comment failed: ${reason}`);
+			this.comments.markDroppedForRequest(sessionId, requestId);
+			return {
+				outcome: "failed",
+				message: reason
+			};
+		}
+	}
+	/**
+	* Every question of one session and what the transcript says about it, keyed by the
+	* question's request id (which is what `CommentAsk` records and what a client matches
+	* against). Derived from the session's own event log on every call and never stored:
+	* the log is the one source of truth for what the agent said, so a stored copy could
+	* only ever disagree with it.
+	* @param sessionId - the session whose comments to read.
+	* @returns the read per question; empty when the session holds no questions.
+	*/
+	answers(sessionId) {
+		this.watch(sessionId);
+		const requestIds = [];
+		for (const comment of this.comments.list(sessionId)) for (const ask of comment.asks ?? []) requestIds.push(ask.requestId);
+		if (requestIds.length === 0) return {};
+		let events;
+		try {
+			events = this.sessionEvents(sessionId);
+		} catch {
+			events = void 0;
+		}
+		if (events === void 0) return {};
+		return answersIn(events, requestIds);
+	}
+	/**
+	* The turns the session's log shows as over, for the questions it holds.
+	*
+	* `agent/turn-stopping` already reports a turn's end live, and that is what usually
+	* writes `ended` down (see `markTurnEnded`). Reading it out of the log as well is what
+	* makes the flag survive a session this process did not watch end — a resumed session,
+	* a client that connected afterwards, a deployment whose agent events cannot be
+	* subscribed at all — because `turn/end` is durable and the event is not.
+	*
+	* @param sessionId - the session whose turns to check.
+	* @returns the turns the log closed, or empty when the log cannot be read.
+	*/
+	endedTurns(sessionId) {
+		let events;
+		try {
+			events = this.sessionEvents(sessionId);
+		} catch {
+			events = void 0;
+		}
+		if (events === void 0) return [];
+		const turns = [];
+		for (const event of events) {
+			if (event?.type !== "turn/end") continue;
+			const turn = turnOf(event);
+			if (turn !== void 0) turns.push(turn);
+		}
+		return turns;
+	}
+	/**
+	* One session's event log, as the reads above take it.
+	*
+	* `snapshotEvents()` and not `deriveMessages()`: the derived history is a list of
+	* messages with no turn attribution, and the turn is the whole point of the answer read
+	* (see `answerForRequest`). The event log is the session's append-only source of truth
+	* and `snapshotEvents` hands back a frozen, sequence-ordered copy of it, so walking it
+	* is a plain read that cannot disturb the session.
+	*
+	* @param sessionId - the session to read.
+	* @returns its events, or undefined when no live session can be read.
+	*/
+	sessionEvents(sessionId) {
+		return this.ctx.sessions.get(sessionId)?.snapshotEvents?.();
+	}
+	/** The live agent for one session, or `undefined` when this host drives none. */
+	agentOf(sessionId) {
+		try {
+			return this.ctx.get("agents")?.get?.(sessionId);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Subscribe to one agent's inbox, once per LIVE agent, moving to a replacement agent
+	* when the session's agent changes under us.
+	*
+	* The listeners live on the agent's own context, so they go away with the agent
+	* and never outlive it — which is exactly why the dedup has to be per agent and
+	* not per session: a session whose agent was re-created (a resume, a restart, a
+	* rebuilt agent for the same id) has nothing listening on the new one, and every
+	* event this module depends on would silently stop arriving. The remembered
+	* agent is compared by identity, so a different object re-subscribes and a
+	* disposed one's stale entry cannot block it. What the replaced agent held is
+	* released first, so re-arming is not a leak: one set of handlers per live agent,
+	* not one more per identity change.
+	*
+	* Called on every ask AND on every poll read (`answers`), because the agent can be
+	* replaced while a question is still pending — the case where nothing asks again.
+	* @param sessionId - the session whose agent to watch.
+	*/
+	watch(sessionId) {
+		const key = String(sessionId);
+		const agent = this.agentOf(sessionId);
+		const on = agent?.ctx?.on;
+		if (agent === void 0 || typeof on !== "function") return;
+		const watching = this.watched.get(key);
+		if (watching?.agent === agent) return;
+		if (watching !== void 0) {
+			this.watched.delete(key);
+			for (const off of watching.detach) try {
+				off();
+			} catch {}
+		}
+		const detach = [];
+		/** Attach one listener, keeping the disposer when the context offers one. */
+		const listen = (name, handler) => {
+			const handle = on.call(agent.ctx, name, handler);
+			if (typeof handle === "function") detach.push(handle);
+		};
+		try {
+			listen("agent/inbox/claimed", (payload) => {
+				const requestId = requestIdOf(payload);
+				if (requestId === void 0) return;
+				const turn = typeof payload.turn === "number" ? payload.turn : void 0;
+				if (turn === void 0) return;
+				this.comments.recordTurnForRequest(sessionId, requestId, turn);
+			});
+			listen("agent/inbox/discarded", (payload) => {
+				const requestId = requestIdOf(payload);
+				if (requestId !== void 0) this.comments.markDroppedForRequest(sessionId, requestId);
+			});
+			listen("agent/turn-stopping", (payload) => {
+				const turn = payload.turn;
+				if (typeof turn === "number") this.comments.markTurnEnded(sessionId, turn);
+			});
+			this.watched.set(key, {
+				agent,
+				detach
+			});
+		} catch (error) {
+			for (const off of detach) try {
+				off();
+			} catch {}
+			this.ctx.logger.warn(`diff-approval: watching the comment inbox failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+};
+/** The request id one inbox event names, when it names our kind of message. */
+function requestIdOf(payload) {
+	const rpcId = payload.message?.source?.rpcId;
+	return typeof rpcId === "string" && rpcId !== "" ? rpcId : void 0;
+}
+/**
+* The human text of one rejection.
+*
+* A prompt is refused by the host's session API with its own error objects — a
+* `RemoteError` carrying a code and a message, or a plain thrown value. Reading
+* `message` off whatever arrived keeps the panel's failure line meaningful
+* (`session/model-unavailable`, `session/agent-busy`, …) instead of printing
+* "[object Object]" for the shapes that are not `Error` instances.
+*
+* @param error - the thrown value.
+* @returns its message, or its string form when it carries none.
+*/
+function rejectionText(error) {
+	if (typeof error === "object" && error !== null) {
+		const message = error.message;
+		if (typeof message === "string" && message !== "") return message;
+	}
+	return String(error);
+}
+//#endregion
+//#region lib/types/comment-lines.js
+/**
+* Where a comment's quote sits in a file's CURRENT content: the rule that turns the lines a comment
+* was WRITTEN on into the lines it is about now.
+*
+* Pure and free of both Node and the DOM, so the two halves of the plugin import the very same rule:
+* the host resolves each comment against the entry content it hangs off and ships the figures on the
+* list read, and the browser half draws them. The panel's own row-level re-anchor
+* (`src/client/discussion.ts`) is this same rule seen through the diff's rows — with one row per
+* line, a removed line among them, and the quote's context taken from the rows — and it stays the
+* browser's business: where a card is DRAWN is a layout fact. What a reader is TOLD (the list's
+* label, the card's own chip, the jump's target line) comes from here, once, so two panes cannot
+* name two lines for one comment.
+*
+* The two models can disagree in one situation, and it is worth knowing which: the host has the
+* file's own lines, while the client's rows also carry the lines this file DELETED. A quote whose
+* recorded `quoteContext` was captured across a deleted row therefore matches a context window the
+* host cannot reproduce, and the host answers `undefined` where the client would re-anchor. The
+* caller then falls back to `record.anchor` — the line the comment was written on — which is what an
+* outdated thread shows anyway: the number stays honest rather than drifting.
+*
+* What the two may NOT disagree about is how far a match is allowed to be from the stored line: a
+* look-alike elsewhere in the file is refused by both, through the one bound they share
+* (`REANCHOR_MAX_LINES`), so the list's figure, the card's chip and the card's place cannot name two
+* different lines for one comment.
+* @module dsh-diff-approval/comment-lines
+*/
+/**
+* One file's content lines, numbered exactly as the diff numbers them.
+*
+* Both line endings are normalized first (`\r\n` and a lone `\r` become `\n`), and a single trailing
+* newline is a line TERMINATOR rather than an extra empty line — the same convention the browser
+* half's whole-file diff splits on (its `contentLines`), so line 1 here is the line the diff calls
+* line 1 and the two cannot drift by a trailing newline.
+*
+* @param text - the file's content.
+* @returns its lines, without the terminating newline; an empty file has none.
+*/
+function commentFileLines(text) {
+	const body = text.replace(/\r\n?/g, "\n");
+	if (body === "") return [];
+	return (body.endsWith("\n") ? body.slice(0, -1) : body).split("\n");
+}
+/**
+* Whether a match that far from where the comment was written is that code having moved.
+*
+* The rule the two halves share, so neither can widen or narrow the bound on its own (see
+* `REANCHOR_MAX_LINES` for the number and for what it separates). The bound is inclusive: at exactly
+* the limit the code is taken to have moved.
+*
+* @param stored - the line (the host's content) or row (the browser half's model) the comment names.
+* @param found - the line or row the quote was found on.
+* @returns whether that match is close enough to be the same code.
+*/
+function reanchorWithinLimit(stored, found) {
+	return Math.abs(found - stored) <= 30;
+}
+/**
+* Where one comment's quote sits in a file's current content, or `undefined` when it is nowhere.
+*
+* The rule, in the order it is applied — the same order the browser half's `remapDiscussion` applies
+* it in, so the same file and the same record produce the same number in both halves:
+*
+* 1. The lines the comment names have to exist in this file at all. When even the anchor's first
+*    line is past the end, nothing here can be re-anchored: `undefined`.
+* 2. The anchor's own line still reads the quote: the comment has not moved. The stored range is the
+*    answer, `endLine` included — a range whose quote covers a different number of lines (a removed
+*    row was quoted among them) still belongs to the reader's own numbers.
+* 3. Otherwise the quote is followed: every window of as many lines as the quote has is compared to
+*    it, the recorded context has to agree where the record carries one, and the occurrence CLOSEST
+*    to the stored anchor wins — that is where the reader last saw the code. An equal distance keeps
+*    the earlier occurrence, which is the first window an ascending scan meets.
+* 4. The occurrence also has to be NEAR the stored anchor (see `REANCHOR_MAX_LINES`): a window
+*    farther than that from the line the comment was written on is not this code having moved but
+*    another place in the file that reads the same — however exactly its recorded context agrees.
+* 5. Nothing matched: `undefined`. The caller falls back to `record.anchor`, the line the comment was
+*    written on — the same answer the code view gives an outdated thread.
+*
+* @param text - the entry's current content (the file as it reads now).
+* @param comment - the stored comment's anchor and quote.
+* @returns the new-file line range the quote occupies now, or `undefined` when it is gone.
+*/
+function resolveCommentLines(text, comment) {
+	const lines = commentFileLines(text);
+	const quote = comment.quote;
+	const span = quote.split("\n").length - 1;
+	const { startLine, endLine } = comment.anchor;
+	/** The `span + 1` lines from `row` on, joined as the quote is; past the end reads as empty lines. */
+	const windowAt = (row) => {
+		const parts = [];
+		for (let index = row; index <= row + span; index++) parts.push(index < lines.length ? lines[index] : "");
+		return parts.join("\n");
+	};
+	/** That window with one line of context on each side, as far as the file has them. */
+	const contextAt = (row) => {
+		const parts = [];
+		for (let index = Math.max(0, row - 1); index <= Math.min(lines.length - 1, row + span + 1); index++) parts.push(lines[index]);
+		return parts.join("\n");
+	};
+	if (!(startLine >= 1 && startLine <= lines.length)) return void 0;
+	const row = startLine - 1;
+	if (windowAt(row) === quote) return {
+		start: startLine,
+		end: endLine
+	};
+	const fingerprint = comment.quoteContext;
+	let found = -1;
+	for (let index = 0; index + span < lines.length; index++) {
+		if (windowAt(index) !== quote) continue;
+		if (fingerprint !== void 0 && contextAt(index) !== fingerprint) continue;
+		if (!reanchorWithinLimit(startLine, index + 1)) continue;
+		if (found === -1 || Math.abs(index - row) < Math.abs(found - row)) found = index;
+	}
+	if (found === -1) return void 0;
+	return {
+		start: found + 1,
+		end: found + span + 1
+	};
+}
+//#endregion
 //#region lib/types/open.js
 /**
 * OS-level "open file" and "reveal in folder" launches for the host half's
@@ -1330,6 +2587,450 @@ const COMMENT_SKILL = {
 `,
 	source: "runtime"
 };
+/** The contribution to register with the skill registry. */
+const ANNOTATE_SKILL = {
+	name: "dsh-diff-approval-annotate",
+	description: "How to annotate code with the review panel's cards: one card per place, on the lines as the file reads now, never on lines a card already holds — and the card is a conversation the user can answer.",
+	whenToUse: "The user asks you to explain, walk through, or review code that has pending changes in the review panel (查看差异 / 改动审批), or you want to point at particular lines while discussing them — load this before calling `diff_approval_annotate`.",
+	content: `# 用卡片给代码做批注
+
+改动审批面板里的卡片 = 针对**具体几行代码**的对话。你写的批注会成为卡片的第一条内容（你在工具里写的 \`note\`），用户就在代码旁边看到它，并且可以在这张卡片里回你；他的回复会以 \`[评论] (path:lines)\` 的消息回到你。
+
+## 什么时候该用
+
+- 用户想读代码：把**调用链**一步步批注出来（每个关键调用点一张卡，按阅读顺序），比在回复里贴一大段代码或行号清单清楚得多。
+- 你要指出某段代码的问题、理由、或需要注意的地方（Review 场景），让证据就贴在证据所在的行上。
+- 你正在讨论某段代码，想把话直接挂在那些行上，而不是让用户在回复里对着行号找。
+
+不要在用户没让你讲代码时刷卡片，也不要用它代替回复：卡片是**补充**，你的回答还是要写在回复里（可以简短说"已在代码上标了 3 处"并给出要点）。
+
+## 怎么调用 \`diff_approval_annotate\`
+
+- \`path\`：面板里那个文件。你读文件时用的路径也行（按尾部匹配）；匹配到多个会被拒，把完整路径给它。
+  **文件还不在面板的列表里也没关系：会自动加进去**（工作区里能读成文本的文件），所以"用户想读懂某个文件"不必先等改动发生。工作区之外、或读不出文本，才会被拒。
+- \`startLine\` / \`endLine\`：**现在**的行号（1 起，含两端；省略 \`endLine\` 就是一行）。先读文件再写号，别凭记忆。
+- \`note\`：卡片上写的话。要短——卡片是**按行**排版、行高按行算的（上限 1000 字符，超了会被拒）。讲流程时，把这一步的序号写在 note 的**最前面**（\`1. …\`、\`2. …\`）。
+- \`quote\`（可选，建议给）：你读到的那几行原文（换行连接）。文件在你读完之后又变了的话，会当场被拒并把现在的原文给你，避免批注挂在错误的行上。
+
+## 讲流程就在正文开头写序号
+
+如果这几张卡是**一条流程/调用链的步骤**，把序号写在 note 的最前面，用户就能按号读：
+
+- 序号没有专门参数，也不是面板画的——它就是正文的头几个字符，所以卡片里、列表里、复制出去的内容里都带着它，你在回复里也能引用同一个号。
+- 号由你排：按你希望用户阅读的顺序；1、2、3… 连不连续、重不重复都随你（**不需要唯一**，讲同一个点的补充卡可以同号）。
+- 顺序号也写进你的回复（"我在代码上标了 1–5，从 X 开始"），这样面板里的号和回复里的号对得上。
+- 零散的批注（不是一串步骤）**不要**写号。
+
+## 一张卡一个点
+
+- 范围要小：**最多 60 行**，通常 1–5 行就够。要讲整段逻辑就拆成几张卡。
+- 一条调用链 = 一张卡一个调用点，按你应该让用户阅读的顺序依次创建；不要把所有步骤塞进一张卡。
+- note 里只谈这些行（最多带上直接相邻的一两行），不要扩到整个文件或整个任务。
+- 写法沿用批注的规矩：不超过 3 行、行间不空行、**不要 Markdown 表格/列表/标题/围栏代码块**（卡片按行排版，表格会读成一堆竖线并把高度算错），行内只用 \`代码\` 和 **加粗**。要引用别处就写 \`文件:行号\`。
+- 用用户的语言写 note。
+
+## 那几行已经被占用时
+
+如果这些行已经落在**某张卡片里**，调用会被拒，拒绝信息里会写明是哪一张（id、行号、它开头的话）。这不是错误，是"这里已经有话说了"：
+
+- 换一处行号；或者
+- 把这件事写进你的回复里，不要试图硬塞进那张卡：那张卡的对话属于写它的人（可能是用户，也可能是你早先写的）。如果用户想在那张卡上继续聊，他会在卡片里回复你，那时你会收到 \`[评论]\`，按 \`dsh-diff-approval-comment\` 的规矩回答即可。
+
+**不要**在回复里假装已经批注成功——工具返回的是"refused: ..."就说明没有卡片被创建。
+`,
+	source: "runtime"
+};
+/**
+* The most characters one annotation's note may carry.
+*
+* The card lays its text out one row per line and reserves exactly that many rows in the diff, so an
+* essay in a card pushes the code it is about off the screen. Anything longer belongs in the agent's
+* own reply to the user, which is not measured in code rows.
+*/
+const MAX_ANNOTATION_CHARS = 1e3;
+/**
+* Whether two line ranges share a line. Ranges are inclusive on both ends, which is how the panel's own
+* selection rule reads them (`discussionOverlapping`).
+*
+* @param aStart - first line of one range.
+* @param aEnd - last line of one range.
+* @param bStart - first line of the other range.
+* @param bEnd - last line of the other range.
+* @returns whether they overlap.
+*/
+function overlaps(aStart, aEnd, bStart, bEnd) {
+	return aStart <= bEnd && bStart <= aEnd;
+}
+/**
+* The quote, the context fingerprint and the gutter numbers a range of a file's own lines produces.
+*
+* The shape mirrors what the panel records when the reader annotates rows: the quote is the named lines
+* newline-joined, the context is one line each side of them (as far as the file reaches, which is how
+* the client's own `contextAt` clamps at the ends), and the gutter numbers are the new-file numbers of
+* the quoted lines.
+*
+* The old-file side is deliberately absent, and so is the add/del/context marker: the host holds the
+* file's current text, not a diff, so it cannot say which of those lines the change added and which it
+* left alone. Absent is the honest answer — the panel draws such a quote with the numbers it has and
+* no wash, exactly as it does for a thread recorded before those fields existed.
+*
+* @param lines - the file's lines, as `commentFileLines` splits them.
+* @param startLine - first quoted line, 1-based.
+* @param endLine - last quoted line, 1-based and inclusive.
+* @returns the record's quote fields.
+*/
+function annotationQuote(lines, startLine, endLine) {
+	const quoted = lines.slice(startLine - 1, endLine);
+	const before = startLine > 1 ? lines[startLine - 2] : void 0;
+	const after = endLine < lines.length ? lines[endLine] : void 0;
+	const context = [
+		before,
+		...quoted,
+		after
+	].filter((line) => line !== void 0);
+	return {
+		quote: quoted.join("\n"),
+		quoteContext: context.join("\n"),
+		quoteLines: quoted.map((_line, index) => ({ new: startLine + index }))
+	};
+}
+/**
+* Turn one annotation request into the record the panel draws, or say why it cannot be made.
+*
+* The order of the checks is the order a caller can act on them: what it asked for (note, range), then
+* whether the code it means is still there (`quote`), then whether the reader already has a card on
+* those lines. Nothing is written here — the caller hands the record to the comment store — so this is
+* a pure function of the entry, the stored comments and the request, and it can be tested as one.
+*
+* @param request - what to annotate and with what words.
+* @param existing - every comment the store holds for this entry.
+* @returns the record to store, or the refusal to hand back.
+*/
+function annotateLines(request, existing) {
+	const note = request.note.trim();
+	if (note === "") return { outcome: "empty-note" };
+	if (note.length > 1e3) return {
+		outcome: "note-too-long",
+		limit: MAX_ANNOTATION_CHARS,
+		length: note.length
+	};
+	const start = Math.trunc(request.startLine);
+	const end = Math.trunc(request.endLine ?? request.startLine);
+	if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) return {
+		outcome: "range-too-wide",
+		limit: 60,
+		lines: 0
+	};
+	if (end - start + 1 > 60) return {
+		outcome: "range-too-wide",
+		limit: 60,
+		lines: end - start + 1
+	};
+	const lines = commentFileLines(request.entry.newText);
+	if (start < 1 || end > lines.length) return {
+		outcome: "out-of-range",
+		lines: lines.length,
+		startLine: start,
+		endLine: end
+	};
+	const quoted = lines.slice(start - 1, end).join("\n");
+	if (request.quote !== void 0 && request.quote.trim() !== "" && request.quote !== quoted) return {
+		outcome: "quote-mismatch",
+		actual: quoted
+	};
+	for (const comment of existing) {
+		if (comment.entryId !== request.entry.id) continue;
+		const range = resolveCommentLines(request.entry.newText, comment);
+		if (range === void 0) continue;
+		if (!overlaps(start, end, range.start, range.end)) continue;
+		return {
+			outcome: "already-annotated",
+			comment,
+			start: range.start,
+			end: range.end
+		};
+	}
+	const now = request.now ?? Date.now();
+	return {
+		outcome: "annotated",
+		comment: {
+			id: request.id ?? randomUUID(),
+			sessionId: request.sessionId,
+			entryId: request.entry.id,
+			path: request.entry.path,
+			anchor: {
+				startLine: start,
+				endLine: end
+			},
+			text: note,
+			createdAt: now,
+			updatedAt: now,
+			author: "agent",
+			...annotationQuote(lines, start, end)
+		}
+	};
+}
+/**
+* The one line a refusal is summarised with, for the caller's own log: the outcome and what it says.
+*
+* The agent is handed a full sentence by the tool layer (see `annotate-tool.ts`), which is where the
+* wording lives because that is what a model reads. This is for the plugin's logger.
+*
+* @param refusal - the refusal to name.
+* @returns the outcome, plus the numbers that make two of the same kind tellable apart.
+*/
+function refusalSummary(refusal) {
+	switch (refusal.outcome) {
+		case "already-annotated": return `already-annotated(${refusal.comment.id} ${refusal.start}-${refusal.end})`;
+		case "out-of-range": return `out-of-range(${refusal.startLine}-${refusal.endLine} of ${refusal.lines})`;
+		case "quote-mismatch": return "quote-mismatch";
+		case "range-too-wide": return `range-too-wide(${refusal.lines} lines)`;
+		case "note-too-long": return `note-too-long(${refusal.length} chars)`;
+		default: return refusal.outcome;
+	}
+}
+//#endregion
+//#region lib/types/annotate-tool.js
+/**
+* The tool the agent calls to annotate code: one card, on the lines it names.
+*
+* This is the half a model reads. The rule it applies lives in `annotate.ts` and is a pure function of
+* the entry, the stored comments and the request; what is here is the model-facing surface — the name,
+* the argument schema, the sentence each outcome is handed back as — plus the two lookups that only
+* exist at run time (which session is calling, and which of ITS pending files the caller means).
+*
+* Why a tool at all, when the reader can already annotate: the reader annotates what they are looking
+* at, and the agent annotates what it is EXPLAINING. A call chain the reader asked to have walked, a
+* piece of code the agent wants to point at, a review finding with its evidence beside it — all of those
+* are "quote these lines and say something about them", which is exactly the card the panel already
+* draws. The card is the shared object: the agent's note is its first turn, the reader answers it in the
+* card, and that answer comes back to the agent as an ordinary `[评论]` message.
+*
+* The refusal the caller is most likely to meet is the one that makes the feature coherent: those lines
+* already belong to a card. Two cards hanging off the same lines cannot be told apart in the panel, so
+* the annotation is refused and the refusal NAMES the card holding them — the agent can then say its
+* piece in its own reply, or annotate other lines.
+*
+* The definition is built BY HAND rather than with the harness's `defineTool`: the host half of this
+* plugin imports nothing from the harness at runtime (its harness packages are services it asks for by
+* name, and types), the registry asks only for `name`, `description`, a raw argument schema and an
+* `output` with a schema and a `render`, and this way a build whose harness has no `dsh-tools` at all
+* still loads the plugin — the tool is simply never registered.
+*
+* @module dsh-diff-approval/src/annotate-tool
+*/
+/** The name the agent calls this by. Prefixed with the package: tool names share one flat namespace. */
+const ANNOTATE_TOOL_NAME = "diff_approval_annotate";
+/**
+* The routing line the model always sees, which has to carry the two things that decide whether it calls
+* this at all: what appears for the reader, and that the lines must be free.
+*/
+const ANNOTATE_TOOL_DESCRIPTION = "Annotate a few lines of a file in the review panel: the note becomes a card the user sees on those exact lines, and they can reply to it there. Use it to explain code the user is reading (a call chain is one card per step), to point at a piece of code while discussing it, or to record a review finding on the lines it is about. A file the panel is not showing yet is added to it, so this works whether or not anything in that file has changed. The card shows exactly the text you write, so how the note is worded — including any numbering the user needs to read it in order — is yours. The lines must not already be inside an existing card: that case is refused, and the refusal names the card holding them, so say it in your reply instead of annotating those lines again.";
+/**
+* The argument schema, as raw JSON Schema.
+*
+* Raw rather than the harness's author DSL because the definition is hand-built (see the module
+* comment): the registry validates a hand-built definition's arguments against this subset, and the
+* model reads the same descriptions either way.
+*/
+const ANNOTATE_TOOL_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"path",
+		"startLine",
+		"note"
+	],
+	properties: {
+		path: {
+			type: "string",
+			description: "The file to annotate: a path of a file with pending changes, as the review panel shows it (the path you read is fine too — the tail is matched)."
+		},
+		startLine: {
+			type: "integer",
+			description: "First line to annotate, 1-based, counted in the file as it reads NOW."
+		},
+		endLine: {
+			type: "integer",
+			description: "Last line, inclusive. Omit to annotate the single line startLine names."
+		},
+		note: {
+			type: "string",
+			description: "What the card says. Keep it to a few lines: the card is drawn line by line next to the code, and the reader can reply to it there."
+		},
+		quote: {
+			type: "string",
+			description: "Optional guard: the exact text you believe those lines hold (newline-joined). A mismatch is refused with the text that is actually there, which catches a file that moved between your read and this call."
+		}
+	}
+};
+/**
+* The definition to hand to `ctx.tools.register`.
+*
+* The canonical value is the sentence itself: this tool answers with prose because that is all the model
+* needs from it, and a one-field schema keeps the wire contract trivial.
+*
+* @param run - what fulfils one call; it never throws for a refusal (see below), only for a call that
+*        could not be carried out at all.
+* @returns the definition object.
+*/
+function annotateToolDefinition(run) {
+	return {
+		name: ANNOTATE_TOOL_NAME,
+		description: ANNOTATE_TOOL_DESCRIPTION,
+		parameters: ANNOTATE_TOOL_PARAMETERS,
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(args, exec) {
+			const execution = exec;
+			return run(args, {
+				sessionId: execution?.agent?.id,
+				signal: execution?.signal
+			});
+		}
+	};
+}
+/**
+* One path, folded to the form two spellings of the same file share: separators unified, trailing slash
+* dropped, case dropped (the panel and the agent can each write `C:\a\b.ts`, `C:/a/b.ts` or `c:\A\B.TS`).
+*
+* @param path - the path as written.
+* @returns the comparable form.
+*/
+function foldPath(path) {
+	return path.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/$/, "").toLowerCase();
+}
+/**
+* Which pending file the caller means by `path`.
+*
+* A model writing this argument usually hands back the path it just read — absolute, workspace-relative,
+* or with a slash style of its own. Exact match first, then a trailing-segment match; an AMBIGUOUS tail
+* is reported as such rather than guessed, because annotating the wrong file's lines is the one mistake
+* the reader would see as a bug in the panel.
+*
+* @param entries - the session's pending files.
+* @param path - the path the caller wrote.
+* @returns the one entry, or why it could not be picked.
+*/
+function lookupEntry(entries, path) {
+	const asked = foldPath(path);
+	if (asked === "") return { kind: "none" };
+	const exact = entries.filter((file) => foldPath(file.path) === asked);
+	if (exact.length === 1) return {
+		kind: "one",
+		entry: exact[0]
+	};
+	const byTail = entries.filter((file) => {
+		const folded = foldPath(file.path);
+		return folded.endsWith(`/${asked}`) || asked.endsWith(`/${folded}`);
+	});
+	const candidates = exact.length > 1 ? exact : byTail;
+	if (candidates.length === 1) return {
+		kind: "one",
+		entry: candidates[0]
+	};
+	if (candidates.length === 0) return { kind: "none" };
+	return {
+		kind: "many",
+		paths: candidates.map((file) => file.path)
+	};
+}
+/**
+* The sentence a refusal is handed back as.
+*
+* Every one of these is written for a model that has to choose what to do next, so each says what was
+* wrong AND what it can do instead. The lines are named back in the panel's own form (`path:from-to`),
+* which is the reference the reader sees in a card's header.
+*
+* @param refusal - what the rule refused.
+* @param path - the file the request named, for the reference.
+* @returns the sentence the caller reads.
+*/
+function refusalText(refusal, path) {
+	switch (refusal.outcome) {
+		case "already-annotated": {
+			const held = refusal.comment.text.replace(/\s+/g, " ").slice(0, 60);
+			const who = refusal.comment.author === "agent" ? "your own earlier annotation" : "an existing comment";
+			return `refused: ${path}:${refusal.start}-${refusal.end} is already inside ${who} (id ${refusal.comment.id}, "${held}"). Two cards cannot hang off the same lines, so annotate different lines — or say this in your reply to the user, and mention that card if what you are saying is about it.`;
+		}
+		case "out-of-range": return `refused: ${path} has ${refusal.lines} lines, so ${refusal.startLine}-${refusal.endLine} is not in it. Read the file and use the line numbers it has now.`;
+		case "quote-mismatch": return `refused: those lines do not read what "quote" said they do. They read:\n${refusal.actual}\nRead the file again and either drop "quote" or pass the text that is there now.`;
+		case "range-too-wide": return `refused: ${refusal.lines} lines is more than the ${refusal.limit} one annotation may name. A card is a note on a few lines; a walkthrough is several cards, one per step.`;
+		case "note-too-long": return `refused: the note is ${refusal.length} characters, over the ${refusal.limit} a card may carry. Put the long form in your reply to the user and keep the card to its point.`;
+		default: return "refused: the note is empty, so the card would say nothing.";
+	}
+}
+/**
+* The sentence a file that could not be listed is refused with.
+*
+* All three are the workspace's rules rather than the annotation's: the panel can only show what the
+* session's workspace contains and the file service can read, and naming which one failed is what lets
+* the agent pick another file, or stop annotating that one.
+*
+* @param kind - why listing failed.
+* @param path - the path the caller named.
+* @returns the sentence the caller reads.
+*/
+function unlistedText(kind, path) {
+	switch (kind) {
+		case "outside": return `refused: "${path}" is not inside this session's workspace, so the review panel cannot list it. Annotate a file of the workspace the user is working in.`;
+		case "no-workspace": return `refused: this session has no workspace, so there is no file list to add "${path}" to.`;
+		default: return `refused: "${path}" could not be read as a text file, so there is nothing to annotate. Check the path (a workspace-relative path is fine) and try again.`;
+	}
+}
+/**
+* Build the body one tool call runs: resolve the file, apply the rule, store the record.
+*
+* A refusal is NOT an error: "those lines belong to a card" is an answer about the code, not a broken
+* call, and returning it as text keeps the turn going so the agent can act on it in the same step.
+* Throwing is left for what it means to the registry: the call could not be carried out at all.
+*
+* @param deps - the host lookups and the store write.
+* @returns the body to hand to {@link annotateToolDefinition}.
+*/
+function annotateRun(deps) {
+	return async (args, context) => {
+		if (context.sessionId === void 0) return "refused: this call did not come from a session, so there is no panel to annotate in.";
+		await deps.ready?.();
+		const sessionId = context.sessionId;
+		const lookup = lookupEntry(deps.entriesOf(sessionId), args.path);
+		if (lookup.kind === "many") return `refused: "${args.path}" matches more than one pending file: ${lookup.paths.join(", ")}. Pass the full path of the one you mean.`;
+		let entry;
+		let added = false;
+		if (lookup.kind === "one") entry = lookup.entry;
+		else {
+			const outcome = await deps.listFile(sessionId, args.path, context.signal);
+			if (outcome.kind !== "listed") {
+				deps.log?.(`annotate: not-listed(${outcome.kind}) (${args.path})`);
+				return unlistedText(outcome.kind, args.path);
+			}
+			entry = outcome.entry;
+			added = outcome.added;
+		}
+		const result = annotateLines({
+			sessionId,
+			entry,
+			startLine: args.startLine,
+			endLine: args.endLine,
+			note: args.note,
+			quote: args.quote
+		}, deps.commentsOf(sessionId));
+		if (result.outcome !== "annotated") {
+			deps.log?.(`annotate: ${refusalSummary(result)} (${entry.path})`);
+			return refusalText(result, entry.path);
+		}
+		deps.addComment(result.comment);
+		const { startLine, endLine } = result.comment.anchor;
+		const span = startLine === endLine ? `${startLine}` : `${startLine}-${endLine}`;
+		const listed = added ? ", and the file was added to the list" : "";
+		return `annotated ${entry.path}:${span} (card ${result.comment.id}${listed}). The user sees it in the review panel now; they can reply to it there, and their reply reaches you as a [评论] message.`;
+	};
+}
 //#endregion
 //#region lib/types/font-slices.js
 /**
@@ -1392,13 +3093,17 @@ const FONT_ASSET_DIR = "../assets/fonts";
 * directory.
 *
 * Scope of one import (mirrors the panel's preferences):
-* - modified files (git: working tree vs index — "仅未暂存"; svn: vs BASE;
-*   p4: opened edits), imported as `edit` (old = baseline, new = working);
+* - modified files, imported as `edit` (old = baseline, new = working). The GIT baseline is the
+*   last commit, not the index: this list answers "what is not committed yet", so a change the
+*   reader already `git add`ed is as much a review item as one they have not — staging is a step
+*   towards a commit, not a decision this panel records (`git diff HEAD` semantics). svn compares
+*   against BASE and p4 against `#have`, which are their "last commit" already;
 * - deleted files, imported as `edit` with an empty new side (revert restores);
-* - new/untracked files (git `??`, svn `?`, p4 not-yet-opened files), imported
-*   as `create` ONLY when the untracked preference is on. For p4 that means a
-*   full workspace scan (`p4 status`, which can be slow); with the preference
-*   off only already-opened files are read.
+* - new/untracked files, imported as `create` ONLY when the untracked preference is on: git `??`
+*   (never added), svn unversioned, p4 not-yet-opened. For p4 that means a full workspace scan
+*   (`p4 status`, which can be slow); with the preference off only already-opened files are read.
+*   A file that is new but already under version control (git `A`, svn `added`) needs no
+*   preference: it is an uncommitted change like any other.
 * @module dsh-diff-approval/vcs
 */
 /** Cap on one VCS command's runtime; scans (git status, svn status) can be slow
@@ -1412,25 +3117,66 @@ const GIT_BLOB_STDOUT_SLACK = 1024;
 function shq(value) {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-/** POSIX path-inside check, case-insensitive on Windows. */
-function isPathInside(absolutePath, root) {
-	const folded = (value) => process.platform === "win32" ? value.toLowerCase() : value;
-	const path = folded(resolve(absolutePath));
-	const base = folded(resolve(root));
+/** Resolve one path to its real (link-followed) form. A path that is not on disk yet — a file git
+* still reports as untracked, or a scope below a directory that does not exist — has no real path
+* of its own, so the deepest ancestor that does exist is resolved and the rest re-appended:
+* `resolve()` collapses the `..`/`.` segments of that tail. When nothing on the way resolves, the
+* lexical path is what is left and the comparison falls back to the purely lexical one. */
+function realpathOrSelf(absolutePath) {
+	const path = resolve(absolutePath);
+	try {
+		return realpathSync.native(path);
+	} catch {
+		const parent = dirname(path);
+		if (parent === path) return path;
+		const resolvedParent = realpathOrSelf(parent);
+		if (resolvedParent === parent) return path;
+		return resolve(resolvedParent, path.slice(parent.length + 1));
+	}
+}
+/** Resolve the workspace root and the scope once, for {@link inScanScope} to reuse per row. */
+function realRoots(workspaceRoot, scope) {
+	return { real: {
+		workspace: realpathOrSelf(workspaceRoot),
+		scope: scope === void 0 ? void 0 : realpathOrSelf(scope)
+	} };
+}
+/** The prefix test itself, on two already-absolute and already-resolved paths: case-insensitive on
+* Windows, separator-aware so a sibling sharing a name prefix (`/w/repo-x` vs `/w/repo`) is not
+* read as inside. On Windows `/` and `\` name the same separator, so both are folded to `sep`. */
+function isLexicallyInside(absolutePath, root) {
+	const fold = (value) => {
+		const unified = sep === "\\" ? value.replace(/\//g, sep) : value;
+		return process.platform === "win32" ? unified.toLowerCase() : unified;
+	};
+	const path = fold(absolutePath);
+	const base = fold(root);
 	if (path === base) return true;
 	return path.startsWith(base + sep);
 }
+/** Path-inside check on real paths, case-insensitive on Windows. Both sides are put in their real
+* (link-followed) form first: a workspace reached through a symlink, a Windows junction or a mapped
+* path is the same directory as its target, and comparing the two spellings lexically reads one
+* file as two unrelated paths — which silently drops every imported change. The lexical check is
+* still the answer when neither side resolves (nothing exists to follow). */
+function isPathInside(absolutePath, root) {
+	const path = resolve(absolutePath);
+	const base = resolve(root);
+	const realPath = realpathOrSelf(path);
+	const realRoot = realpathOrSelf(base);
+	if (realPath === path && realRoot === base) return isLexicallyInside(path, base);
+	return isLexicallyInside(realPath, realRoot);
+}
 /**
 * Whether one changed path belongs to the scan: inside the workspace, and inside
 * the narrowed `scope` when the caller set one.
 * @param absolutePath - the changed file's absolute path.
-* @param workspaceRoot - the session's workspace root.
-* @param scope - one path to restrict the scan to, or undefined for all of it.
+* @param roots - the workspace root and scope, resolved once per scan by {@link realRoots}.
 * @returns whether the change is in scope.
 */
-function inScanScope(absolutePath, workspaceRoot, scope) {
-	if (!isPathInside(absolutePath, workspaceRoot)) return false;
-	return scope === void 0 || isPathInside(absolutePath, scope);
+function inScanScope(absolutePath, roots) {
+	if (!isPathInside(absolutePath, roots.real.workspace)) return false;
+	return roots.real.scope === void 0 || isPathInside(absolutePath, roots.real.scope);
 }
 /** The VCS marker of one directory, or undefined when it holds none. */
 function markerOf(directory) {
@@ -1460,23 +3206,49 @@ function detectVcsRoot(start) {
 }
 /** Run one command through the shell executor; a non-zero exit throws. */
 async function runShell(shell, command, workdir, signal, stdoutMaxBytes) {
-	const spec = shell.resolve({
+	const result = await runThrough(shell, {
 		command,
 		workdir,
 		timeoutMs: VCS_COMMAND_TIMEOUT_MS,
 		signal,
 		stdoutMaxBytes
 	});
-	const result = await shell.run(spec);
 	if (result.exitCode !== 0) {
 		const detail = (result.stderr.text || result.stdout.text).trim();
 		throw new Error(`command failed (exit ${String(result.exitCode)}): ${detail || command}`);
 	}
 	return result.stdout.text;
 }
+/**
+* One command, through whichever era of the shell seam is loaded.
+*
+* @param shell - the deployment's shell service.
+* @param request - the command, its workdir, deadline and capture budget.
+* @returns the run's exit code and collected streams.
+* @throws when the service offers neither entry point, naming the methods it does offer — the alternative
+*   is the message that brought this code here, `shell.run is not a function`, which says nothing about
+*   what the seam became.
+*/
+async function runThrough(shell, request) {
+	if (typeof shell.execute === "function") {
+		const spec = typeof shell.resolve === "function" ? shell.resolve(request) : request;
+		const handle = await shell.execute(spec);
+		if (handle !== null && typeof handle.result === "function") return await handle.result();
+		throw new Error("the shell executor returned a handle with no result(); the seam changed again");
+	}
+	if (typeof shell.run === "function") return await shell.run(typeof shell.resolve === "function" ? shell.resolve(request) : request);
+	const names = /* @__PURE__ */ new Set();
+	for (let node = shell; node !== null && node !== Object.prototype; node = Object.getPrototypeOf(node)) for (const name of Object.getOwnPropertyNames(node)) names.add(name);
+	const offered = [...names].filter((name) => name !== "constructor" && typeof shell[name] === "function");
+	throw new Error(`the shell service offers neither execute() nor run() (it has: ${offered.join(", ") || "no methods"})`);
+}
 /** Parse `git status --porcelain=v1 -z` output into (XY, repo-relative path)
-* records. Rename/copy records carry a trailing destination field, which is
-* consumed and skipped. */
+* records. In `-z` a rename/copy record is `XY <to>\0<from>\0`: the record's own
+* field holds the path that exists in the worktree, and the ORIGIN follows as its
+* own NUL field, which is consumed and skipped. (`orig -> dest` is the non-`-z`
+* spelling; verified against git: `git mv a.txt b.txt` gives `R  b.txt\0a.txt\0`.)
+* The status command below turns rename detection off, so this branch is a fallback
+* for a caller that enables it. */
 function parseGitPorcelainZ(output) {
 	const records = [];
 	let index = 0;
@@ -1501,44 +3273,62 @@ function parseGitPorcelainZ(output) {
 	}
 	return records;
 }
+/** The status command both the import and the per-file refresh read. Rename detection is off, so
+* a rename reads as its two halves (a delete and an add) rather than a row the review cannot
+* express. */
+const GIT_STATUS_COMMAND = "git -c status.renames=false status --porcelain=v1 -z --untracked-files=all";
+/**
+* Read one file's content at a revision (`<rev>:<path>`), or undefined when that revision has no
+* such path (a new file, or a repo whose HEAD is unborn).
+*
+* The blob is read straight off `git show` with a per-call stdout budget raised to the blob's own
+* size the way `git cat-file -s` reports it, so the executor cannot truncate a large baseline.
+* Read-only, no temp-file write, so it works even where the sandbox denies a write to the repo
+* root.
+* @param root - the repository root (the command's working directory).
+* @param revision - the revision to read, e.g. `HEAD`.
+* @param rel - the repository-relative path.
+* @param shell - the deployment's shell executor.
+* @param signal - the caller's abort signal.
+* @returns the file's content at that revision, or undefined when it has none.
+*/
+async function readGitBlob(root, revision, rel, shell, signal) {
+	try {
+		const reported = Number.parseInt((await runShell(shell, `git cat-file -s ${revision}:${shq(rel)}`, root, signal)).trim(), 10);
+		const size = Number.isFinite(reported) ? reported : 0;
+		return await runShell(shell, `git show ${revision}:${shq(rel)}`, root, signal, size + GIT_BLOB_STDOUT_SLACK);
+	} catch {
+		return;
+	}
+}
 /** Enumerate the workspace's local changes in a git checkout. */
 async function gitChanges(input) {
 	const { root, workspaceRoot, includeUntracked, scope, shell, readText, signal } = input;
-	const stdout = await runShell(shell, "git -c status.renames=false status --porcelain=v1 -z --untracked-files=all", root, signal);
+	const roots = realRoots(workspaceRoot, scope);
+	const stdout = await runShell(shell, GIT_STATUS_COMMAND, root, signal);
 	const changes = [];
 	for (const { xy, rel } of parseGitPorcelainZ(stdout)) {
 		const absolute = resolve(root, rel);
-		if (!inScanScope(absolute, workspaceRoot, scope)) continue;
+		if (!inScanScope(absolute, roots)) continue;
 		if (xy === "??") {
 			if (!includeUntracked) continue;
 			const newText = await readText(absolute) ?? "";
 			changes.push({
 				path: absolute,
 				kind: "create",
-				oldText: "",
-				newText
-			});
-			continue;
-		}
-		const worktree = xy[1] ?? " ";
-		if (worktree !== "M" && worktree !== "D") continue;
-		let oldText = "";
-		try {
-			let size = 0;
-			try {
-				size = Number.parseInt((await runShell(shell, `git cat-file -s :0:${shq(rel)}`, root, signal)).trim(), 10);
-			} catch {
-				size = 0;
-			}
-			if (Number.isFinite(size) && size > 0) oldText = await runShell(shell, `git show :0:${shq(rel)}`, root, signal, size + GIT_BLOB_STDOUT_SLACK);
-		} catch {
-			oldText = "";
+				oldText: "",
+				newText
+			});
+			continue;
 		}
+		const baseline = await readGitBlob(root, "HEAD", rel, shell, signal);
+		const worktree = xy[1] ?? " ";
+		const oldText = baseline ?? "";
 		const newText = worktree === "D" ? "" : await readText(absolute) ?? "";
 		if (oldText === "" && newText === "") continue;
 		changes.push({
 			path: absolute,
-			kind: "edit",
+			kind: baseline === void 0 ? "create" : "edit",
 			oldText,
 			newText
 		});
@@ -1552,6 +3342,7 @@ function xmlUnescape(value) {
 /** Enumerate the workspace's local changes in an svn working copy. */
 async function svnChanges(input) {
 	const { root, workspaceRoot, includeUntracked, scope, shell, readText, signal } = input;
+	const roots = realRoots(workspaceRoot, scope);
 	const stdout = await runShell(shell, "svn status --xml", root, signal);
 	const changes = [];
 	const entryPattern = /<entry[^>]*path="([^"]*)"[^>]*>\s*<wc-status[^>]*item="([^"]*)"/g;
@@ -1560,7 +3351,7 @@ async function svnChanges(input) {
 		const rel = xmlUnescape(match[1]);
 		const item = match[2];
 		const absolute = resolve(root, rel);
-		if (!inScanScope(absolute, workspaceRoot, scope)) continue;
+		if (!inScanScope(absolute, roots)) continue;
 		if (item === "modified" || item === "deleted") {
 			let oldText = "";
 			try {
@@ -1616,7 +3407,9 @@ function p4ChangeOf(line) {
 * the scan — which can be slow — is skipped. */
 async function p4Changes(input) {
 	const { root, workspaceRoot, includeUntracked, scope, shell, readText, signal } = input;
-	const stdout = await runShell(shell, includeUntracked ? "p4 status" : "p4 opened", root, signal);
+	const command = includeUntracked ? "p4 status" : "p4 opened";
+	const roots = realRoots(workspaceRoot, scope);
+	const stdout = await runShell(shell, command, root, signal);
 	const changes = [];
 	for (const line of stdout.split("\n")) {
 		const opened = p4ChangeOf(line);
@@ -1624,7 +3417,7 @@ async function p4Changes(input) {
 		const local = (await runShell(shell, `p4 where ${shq(opened.depot)}`, root, signal)).trim().split(/\s+/).pop();
 		if (local === void 0 || local.length === 0) continue;
 		const absolute = resolve(local);
-		if (!inScanScope(absolute, workspaceRoot, scope)) continue;
+		if (!inScanScope(absolute, roots)) continue;
 		const deleted = opened.action === "delete" || opened.action === "move/delete";
 		const created = opened.action === "add" || opened.action === "move/add";
 		const newText = deleted ? "" : await readText(absolute) ?? "";
@@ -1701,14 +3494,19 @@ const name = "diff-approval";
 * Services required before the review surface activates. `webServer` rides with
 * `connection` (both come from the web bundle), and is named explicitly because
 * the channel's owner context must be able to resolve it — see
-* `ConnectionServiceSurface`.
+* `ConnectionServiceSurface`. `sessionController` and `agents` are what a comment is
+* asked through and what reports the turn that claimed it: both come from the same
+* base composition this plugin already requires for `sessions`, so a host that could
+* list pending changes at all has them.
 */
 const inject = [
 	"fs",
 	"connection",
 	"webServer",
 	"workspaceRegistry",
-	"sessions"
+	"sessions",
+	"sessionController",
+	"agents"
 ];
 /** The connection RPC channel this plugin serves. */
 const DIFF_APPROVAL_CHANNEL = "/diff-approval";
@@ -1760,26 +3558,28 @@ function lazyCommentSkill(ctx, registered) {
 	};
 }
 /**
-* Register the comment-answering skill with the harness's skill registry, when it has
-* one. The registry's own `skill` tool advertises the catalog and loads the body on
-* demand, so this costs nothing until a comment is answered — and unlike a
-* system-prompt section, a global registration here cannot shape unrelated turns.
+* Register one of this plugin's skills with the harness's skill registry, when it has one. The
+* registry's own `skill` tool advertises the catalog and loads a body on demand, so this costs nothing
+* until the situation it is about comes up — and unlike a system-prompt section, a global registration
+* here cannot shape unrelated turns.
 *
-* Feature-detected and contained: a build without the registry, or a registry that
-* refuses the contribution, simply leaves the short rules the comment prompt already
-* carries as the whole policy.
+* Feature-detected and contained: a build without the registry, or a registry that refuses the
+* contribution, leaves whatever the prompts already carry as the whole policy (the comment prompt names
+* its skill inline; the annotating rules lose only their long form, and the tool description still says
+* what the tool is for).
 *
 * @param ctx - the plugin's host context.
+* @param skill - the contribution to register.
 * @returns whether the skill is now in the registry.
 */
-function registerCommentSkill(ctx) {
+function registerRuntimeSkill(ctx, skill) {
 	if (typeof ctx.get("skills")?.register !== "function") return false;
 	let registered = false;
 	ctx.effect(() => {
 		const skills = ctx.get("skills");
 		if (typeof skills?.register !== "function") return () => {};
 		try {
-			const dispose = skills.register(COMMENT_SKILL);
+			const dispose = skills.register(skill);
 			registered = true;
 			return typeof dispose === "function" ? dispose : () => {};
 		} catch {
@@ -1788,6 +3588,36 @@ function registerCommentSkill(ctx) {
 	});
 	return registered;
 }
+/**
+* Register the annotate tool with the harness's tool registry, when it has one.
+*
+* Feature-detected like the skills, and deliberately NOT declared in `inject`: the host half of this
+* plugin imports nothing from the harness at runtime (its harness packages are services it asks for by
+* name, and types), so a composition without a tool registry keeps working with the tool simply absent
+* — where an unsatisfied `inject` would defer the whole plugin, the trap `src/index.ts` documents for
+* `sessionController`.
+*
+* @param ctx - the plugin's host context.
+* @param deps - what fulfils one call (see `annotate-tool.ts`).
+* @returns whether the tool is now in the registry.
+*/
+function registerAnnotateTool(ctx, deps) {
+	if (typeof ctx.get("tools")?.register !== "function") return false;
+	let registered = false;
+	ctx.effect(() => {
+		const tools = ctx.get("tools");
+		if (typeof tools?.register !== "function") return () => {};
+		try {
+			const dispose = tools.register(annotateToolDefinition(annotateRun(deps)));
+			registered = true;
+			return typeof dispose === "function" ? dispose : () => {};
+		} catch (error) {
+			ctx.logger.warn(`diff-approval: the annotate tool was refused by the tool registry: ${errorMessage(error)}`);
+			return () => {};
+		}
+	});
+	return registered;
+}
 /** The dominant line ending of `text`: CRLF when `\r\n` meets or beats lone
 * `\n`, else LF; a text with no line breaks falls back to LF.
 * @param text - the content to inspect.
@@ -1981,9 +3811,83 @@ function apply(ctx, config) {
 	const storageDir = config?.storageDir;
 	if (storageDir !== void 0 && (typeof storageDir !== "string" || storageDir.trim().length === 0)) throw new Error("diff-approval: storageDir must be a non-empty string");
 	const store = new PendingDiffStore();
-	const persistence = new PendingPersistence(resolve(expandHomePath(storageDir ?? defaultStorageDir())));
+	const storageRoot = resolve(expandHomePath(storageDir ?? defaultStorageDir()));
+	const persistence = new PendingPersistence(storageRoot);
+	const comments = new CommentStore(commentsDirFor(storageRoot), {
+		onLoadSkipped: (file, error) => {
+			ctx.logger.warn(`diff-approval: skipping unreadable comment file '${file}' (moved to '.corrupt'): ${errorMessage(error)}`);
+		},
+		onPersistError: (message) => {
+			if (message === void 0) return;
+			ctx.logger.error(`diff-approval: writing comments failed, so the threads will not survive a restart: ${message}`);
+		}
+	});
+	const commentAsker = new CommentAsker(ctx, comments);
+	/**
+	* The lines each comment sits on now, resolved from the entry content it hangs off and held
+	* against the version of that content it was resolved at (see `resolveCommentLines` for the rule
+	* and `PendingDiffStore.contentVersion` for the versions).
+	*
+	* The list read is the hot path — every client of the session asks once a second — so a figure
+	* that costs a search of the entry's whole content is computed when the content can have changed
+	* and reused until it has. Nothing is written to the comment record: a resolved line is DERIVED,
+	* and a persisted one would outlive the content it was true of.
+	*/
+	const commentLines = /* @__PURE__ */ new Map();
+	/**
+	* The new-file lines this session's comments sit on now, keyed by comment id.
+	*
+	* This is the whole point of resolving in the host: the list pane, the code view's own card and
+	* the jump that opens it draw ONE figure, and they draw it without anything having been opened —
+	* a comment used to be corrected by the open file's pane and published back to the list, so the
+	* list read `382` while the card read `378` until the reader opened the file.
+	*
+	* A comment whose quote is gone from the content is ABSENT from the map rather than guessed at:
+	* the caller then falls back to `record.anchor`, the line the comment was written on, which is
+	* the same answer an outdated thread shows.
+	* @param sessionId - the session whose comments to resolve.
+	* @returns the resolved lines per comment id; comments that do not resolve are left out.
+	*/
+	function resolvedCommentLines(sessionId) {
+		const resolved = {};
+		for (const comment of comments.list(sessionId)) {
+			const entry = store.get(comment.entryId);
+			if (entry === void 0) continue;
+			const version = store.contentVersion(comment.entryId);
+			const cached = commentLines.get(comment.id);
+			if (cached !== void 0 && cached.entryId === comment.entryId && cached.version === version && cached.quote === comment.quote && cached.context === comment.quoteContext && cached.startLine === comment.anchor.startLine && cached.endLine === comment.anchor.endLine) {
+				if (cached.range !== void 0) resolved[comment.id] = cached.range;
+				continue;
+			}
+			const range = resolveCommentLines(entry.newText, comment);
+			commentLines.set(comment.id, {
+				entryId: comment.entryId,
+				version,
+				quote: comment.quote,
+				context: comment.quoteContext,
+				startLine: comment.anchor.startLine,
+				endLine: comment.anchor.endLine,
+				range
+			});
+			if (range !== void 0) resolved[comment.id] = range;
+		}
+		return resolved;
+	}
+	/**
+	* Drop the resolved lines of every comment that hangs off one entry. They are what an entry takes
+	* with it when it leaves the list (`dropEntry` removes those comments), so their figures go too.
+	* @param entryId - the entry that left the list.
+	*/
+	function forgetCommentLinesForEntry(entryId) {
+		for (const [id, row] of commentLines) if (row.entryId === entryId) commentLines.delete(id);
+	}
+	/** Drop the resolved lines of the comments the store no longer holds (the orphan sweep's leavings). */
+	function forgetOrphanedCommentLines() {
+		for (const id of commentLines.keys()) if (comments.get(id) === void 0) commentLines.delete(id);
+	}
 	const launchPath = config?.openPath ?? defaultOpenPath;
-	const commentSkill = lazyCommentSkill(ctx, registerCommentSkill(ctx));
+	const commentSkill = lazyCommentSkill(ctx, registerRuntimeSkill(ctx, COMMENT_SKILL));
+	registerRuntimeSkill(ctx, ANNOTATE_SKILL);
 	/** Hydrate the globally-unique store once from the single persistence file. */
 	let loadPromise;
 	const ensureLoaded = () => {
@@ -1995,9 +3899,96 @@ function apply(ctx, config) {
 			} catch (error) {
 				ctx.logger.error(`diff-approval: loading persisted state failed, so the list starts empty: ${errorMessage(error)}`);
 			}
+			try {
+				if (await comments.loadAll() > 0 && comments.skippedFiles().length === 0) comments.retain(new Set(store.all().map((entry) => entry.id)));
+			} catch (error) {
+				ctx.logger.error(`diff-approval: loading comment state failed, so the comments start empty: ${errorMessage(error)}`);
+			}
 		})();
 		return loadPromise;
 	};
+	registerAnnotateTool(ctx, {
+		ready: ensureLoaded,
+		entriesOf: (sessionId) => store.list(sessionId),
+		commentsOf: (sessionId) => comments.list(sessionId),
+		addComment: (record) => {
+			comments.add(record);
+		},
+		listFile: (sessionId, asked, signal) => listFileForAnnotation(sessionId, asked, signal),
+		log: (message) => ctx.logger.info(`diff-approval: ${message}`)
+	});
+	/**
+	* Admit one file into a session's list, so an annotation can hang on it.
+	*
+	* The panel lists what the workspace has pending; an agent that wants to explain a file nobody is
+	* reviewing has nowhere to put the card until the file is listed. This is the same admission the
+	* reader's own "add this path" performs (`add-path`), reached by the agent instead of by hand: both
+	* sides of the entry are the file's own text — the "no pending diff" shape a scanned-clean file
+	* already lands with — so the file opens at its own content and the card sits on the lines it names.
+	*
+	* It is deliberately that ROUTE and not a raw insert: a path already listed is answered from the list
+	* (so annotating twice never re-baselines a review in progress), a path outside the workspace is
+	* refused here rather than confined later, and what lands goes through the same fold + persist + undo
+	* bookkeeping as every other admission.
+	*
+	* @param sessionId - the session whose list gains the file.
+	* @param asked - the path the agent named, workspace-relative or absolute.
+	* @param signal - the caller's lifetime, for the read.
+	* @returns the listed entry (and whether this call is what listed it), or why it could not be listed.
+	*/
+	async function listFileForAnnotation(sessionId, asked, signal) {
+		await ensureLoaded();
+		const workspace = workspaceOf(sessionId);
+		if (workspace === void 0) return { kind: "no-workspace" };
+		const absolute = resolveInsideWorkspace(workspace.path, asked);
+		if (absolute === void 0) return { kind: "outside" };
+		const listed = store.list(sessionId).find((entry) => pathIdentity(entry.path) === pathIdentity(absolute));
+		if (listed !== void 0) return {
+			kind: "listed",
+			entry: listed,
+			added: false
+		};
+		const content = await readTextOrNone(absolute, signal ?? new AbortController().signal);
+		if (content === void 0) return { kind: "missing" };
+		await foldBatch(sessionId, [{
+			id: absolute,
+			sessionId,
+			path: absolute,
+			kind: "edit",
+			oldText: content,
+			newText: content,
+			updatedAt: Date.now(),
+			sessionIds: [sessionId]
+		}], true);
+		const landed = store.list(sessionId).find((entry) => pathIdentity(entry.path) === pathIdentity(absolute));
+		return landed === void 0 ? { kind: "missing" } : {
+			kind: "listed",
+			entry: landed,
+			added: true
+		};
+	}
+	/**
+	* Drop one entry from its session's list, ALONG WITH THE COMMENTS it carries.
+	*
+	* The comments go in the same tick as the entry — rather than being swept on some later read —
+	* because a second client polling in between must never be handed a comment naming a file the same
+	* read no longer lists. Synchronous: the comment store applies changes to memory as it goes and
+	* persists on its own chain.
+	*
+	* This call is the DESTRUCTION the undo pair of every dropping action has to be able to reverse, so
+	* each of those actions snapshots the entry's comments into its `before` side first (see
+	* `droppingComments`). The panel still asks before a press that drops an entry carrying comments
+	* (see the `remove-one` / `remove-*` prompts): undo covers the paths that have a pair, and the ask
+	* covers the reader's intent either way.
+	* @param id - the entry id (= path) leaving the list.
+	* @returns whether the entry was there.
+	*/
+	function dropEntry(id) {
+		const removed = store.remove(id);
+		comments.removeForEntry(id);
+		forgetCommentLinesForEntry(id);
+		return removed;
+	}
 	/** Pre-write bases captured at the intent seams, keyed by the tool call id. */
 	const editorIntents = /* @__PURE__ */ new Map();
 	/**
@@ -2123,8 +4114,8 @@ function apply(ctx, config) {
 			stack.length = 0;
 			stack.push(...kept);
 		};
-		clean(undoStack);
-		clean(redoStack);
+		for (const stack of undoStacks.values()) clean(stack);
+		for (const stack of redoStacks.values()) clean(stack);
 	}
 	/**
 	* Settle each listed entry against its live file. Existence is decided by the
@@ -2141,13 +4132,14 @@ function apply(ctx, config) {
 		for (const entry of store.list(sessionId)) {
 			const live = await liveStateOf(entry.path);
 			if (live.kind === "deleted") {
-				store.remove(entry.path);
-				pushUndo(sessionId, {
+				const checkpoint = droppingComments({
 					id: entry.path,
 					path: entry.path,
 					entry,
 					fileText: entry.newText
-				}, {
+				});
+				dropEntry(entry.path);
+				pushUndo(sessionId, checkpoint, {
 					id: entry.path,
 					path: entry.path,
 					entry: void 0,
@@ -2157,7 +4149,7 @@ function apply(ctx, config) {
 				continue;
 			}
 			if (live.kind === "unavailable") {
-				store.remove(entry.path);
+				dropEntry(entry.path);
 				purgeForEntry(entry.path);
 				persistSession();
 				continue;
@@ -2168,7 +4160,7 @@ function apply(ctx, config) {
 			if (hasContent && content !== entry.newText) {
 				adopted = content;
 				const beforeText = entry.newText;
-				const redoWasPresent = redoStack.length > 0;
+				const redoWasPresent = redoStackOf(sessionId).length > 0;
 				store.update(entry.path, { newText: content });
 				pushUndo(sessionId, {
 					id: entry.path,
@@ -2246,19 +4238,7 @@ function apply(ctx, config) {
 				fileText: void 0
 			});
 		}
-		if (batchBefore.length > 0) pushUndo(sessionId, {
-			id: batchBefore[0].id,
-			path: batchBefore[0].path,
-			entry: void 0,
-			fileText: void 0,
-			batch: batchBefore
-		}, {
-			id: batchAfter[0].id,
-			path: batchAfter[0].path,
-			entry: void 0,
-			fileText: void 0,
-			batch: batchAfter
-		});
+		if (batchBefore.length > 0) pushBatchUndo(sessionId, batchBefore, batchAfter);
 		return folded;
 	}
 	/**
@@ -2380,6 +4360,56 @@ function apply(ctx, config) {
 		return policy === void 0 ? ctx.fs.writeText(target, content, void 0, signal) : ctx.fs.writeText(target, content, void 0, signal, policy);
 	}
 	/**
+	* Delete one file as a Revert, under the same session sandbox policy the write
+	* path carries.
+	*
+	* A Revert of a created file removes it, and a removal is a mutation like any
+	* other: going through a raw `processPath` + `rm` bypassed the confinement
+	* entirely, so a `workspace-write` session could delete a file the very same
+	* policy would refuse to write. The mode is therefore checked here, against the
+	* target's own path, and the backend that does confine is handed the policy as
+	* well: the check is what a build with no confining backend still enforces, and
+	* passing the policy through is what lets a confining one enforce its own,
+	* stricter rules. The plain `rm` remains the last resort for a deployment whose
+	* `ctx.fs` has no delete verb of its own.
+	* @param target - the resolved target to delete.
+	* @param sessionId - the session whose policy governs the delete.
+	* @param signal - aborts before the delete is issued.
+	*/
+	async function removeRevert(target, sessionId, signal) {
+		const policy = sandboxPolicyOf(sessionId);
+		const osPath = processPathOf(target);
+		if (policy !== void 0 && !withinSandboxRoot(osPath, policy)) throw new Error(`file access denied under ${policy.mode} mode: '${osPath}' is outside the sandbox workspace root '${policy.workspaceRoot}'`);
+		const fs = ctx.fs;
+		if (policy !== void 0 && typeof fs.remove === "function") {
+			await fs.remove(target, policy, signal);
+			return;
+		}
+		await rm(osPath, { force: true });
+	}
+	/** The OS path a resolved target names, as the confinement check reads it. */
+	function processPathOf(target) {
+		return ctx.fs.processPath(target);
+	}
+	/**
+	* Whether a path lies inside the policy's workspace root (or IS it). Paths are
+	* compared case-insensitively on Windows for the same reason the backend's own
+	* containment is: `C:\Repo` and `c:\repo` are one directory there.
+	* @param path - the OS path the delete would touch.
+	* @param policy - the session's resolved policy.
+	* @returns true when the mode permits the delete at that path.
+	*/
+	function withinSandboxRoot(path, policy) {
+		if (policy.mode !== "read-only" && policy.mode !== "workspace-write") return true;
+		if (policy.mode === "read-only") return false;
+		if (policy.workspaceRoot === "") return true;
+		const target = process.platform === "win32" ? path.toLowerCase() : path;
+		const root = process.platform === "win32" ? policy.workspaceRoot.toLowerCase() : policy.workspaceRoot;
+		if (target === root) return true;
+		const rel = relative(root, target);
+		return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+	}
+	/**
 	* Revert one entry's file back to its baseline (the shared per-entry logic
 	* behind both the single `revert` endpoint and the bulk `revert-all`). A
 	* created file's revert deletes it (not undoable: the file is gone), an edit
@@ -2392,7 +4422,7 @@ function apply(ctx, config) {
 	async function revertEntryContent(entry, sessionId, signal) {
 		const resolved = await ctx.fs.resolve(entry.path, { signal });
 		if (entry.kind === "create") {
-			await rm(ctx.fs.processPath(resolved), { force: true });
+			await removeRevert(resolved, sessionId, signal);
 			return;
 		}
 		const preWrite = await ctx.fs.readText(resolved, void 0) ?? entry.newText;
@@ -2413,27 +4443,173 @@ function apply(ctx, config) {
 			}
 		};
 	}
-	const undoStack = [];
-	const redoStack = [];
+	const undoStacks = /* @__PURE__ */ new Map();
+	const redoStacks = /* @__PURE__ */ new Map();
+	/** The undo stack of one session, created on first use. */
+	function undoStackOf(sessionId) {
+		let stack = undoStacks.get(sessionId);
+		if (stack === void 0) {
+			stack = [];
+			undoStacks.set(sessionId, stack);
+		}
+		return stack;
+	}
+	/** The redo stack of one session, created on first use. */
+	function redoStackOf(sessionId) {
+		let stack = redoStacks.get(sessionId);
+		if (stack === void 0) {
+			stack = [];
+			redoStacks.set(sessionId, stack);
+		}
+		return stack;
+	}
+	/** Record one undoable action in its own session's history. A fresh action
+	*  invalidates that session's redo history (and only that session's). */
 	function pushUndo(sessionId, before, after) {
-		undoStack.push({
+		undoStackOf(sessionId).push({
 			sessionId,
 			before,
 			after
 		});
-		redoStack.length = 0;
+		redoStackOf(sessionId).length = 0;
+	}
+	/**
+	* Record several entries' worth of ONE decision as a single undo step.
+	*
+	* The reader asked once — a VCS import, or a keep/revert over a pick of files — so one Ctrl+Z has to
+	* take the whole thing back. A loop of single actions would push one step per entry instead, and undo
+	* would then peel that one decision apart file by file.
+	*
+	* @param sessionId - the session whose history this belongs to.
+	* @param before - one state per entry, in the order the decision touched them.
+	* @param after - the same entries as the decision left them; the two arrays are index-aligned, which
+	*   is also what the divergence guard on a restore reads (see `restoreState`).
+	*/
+	function pushBatchUndo(sessionId, before, after) {
+		if (before.length === 0) return;
+		pushUndo(sessionId, {
+			id: before[0].id,
+			path: before[0].path,
+			entry: void 0,
+			fileText: void 0,
+			batch: before
+		}, {
+			id: after[0].id,
+			path: after[0].path,
+			entry: void 0,
+			fileText: void 0,
+			batch: after
+		});
+	}
+	/** Drop the top pair of one stack when it belongs to `sessionId`; otherwise the
+	*  stack is left exactly as it was, so another session's action is untouched.
+	* @param stack - the session's stack (undo or redo).
+	* @param sessionId - the session the request is for.
+	* @returns the pair to move, or undefined when this session has nothing to move.
+	*/
+	function popOwnPair(stack, sessionId) {
+		const pair = stack[stack.length - 1];
+		if (pair === void 0 || pair.sessionId !== sessionId) return void 0;
+		stack.pop();
+		return pair;
+	}
+	/**
+	* One side of a comment pair: the records it holds, and the entry they hang off.
+	*
+	* The pair's `id`/`path` are that ENTRY's id (= its path, the store's global identity), which is the
+	* one field that makes a comment pair behave like a file pair everywhere the stack is walked:
+	* `purgeForEntry` filters by paths, so a comment whose file left the review cannot be restored onto
+	* it. A pick of comments can span several files, in which case the pair names its first record's
+	* entry — each record still carries its own `entryId`, which is where the restore puts it back.
+	* @param entryId - the entry the pair's comments hang off.
+	* @param records - the threads this side holds.
+	* @returns the snapshot for `pushUndo`.
+	*/
+	function commentState(entryId, records) {
+		return {
+			id: entryId,
+			path: entryId,
+			entry: void 0,
+			fileText: void 0,
+			kind: "comments",
+			comments: records
+		};
+	}
+	/**
+	* The `before` side of an action that DROPS its entry, with the comments that drop is about to
+	* delete riding along.
+	*
+	* Undo means one thing to the reader — their last action, taken back — so a pair whose action takes
+	* a file out of the list has to bring back the threads that went with it, exactly as the pair for a
+	* closed card brings the card back. Without this, Ctrl+Z gave the row back empty and the same
+	* gesture meant two different things depending on whether the action was about a file or a comment.
+	*
+	* The snapshot goes on the `before` side ONLY: `after` carries none, which is what makes a redo the
+	* same drop again rather than something that reinstalls a thread.
+	*
+	* Only the paths that really drop take one. A keep asked to leave its entry listed never deletes a
+	* comment, and a snapshot there would re-add what the store still holds — and worse, would make the
+	* undo of that keep resurrect comments the reader wrote after it.
+	*
+	* Must be called BEFORE `dropEntry`: the snapshot is of what that call is about to take away.
+	* @param state - the `before` side as the action's own bookkeeping built it.
+	* @returns that side, carrying the entry's records when it has any (absent rather than empty, so
+	*   "this pair is about comments too" is one check for the restore).
+	*/
+	function droppingComments(state) {
+		const carried = comments.forEntry(state.path);
+		return carried.length === 0 ? state : {
+			...state,
+			comments: carried
+		};
+	}
+	/**
+	* Install one side of a comment pair: the comments that side holds go back into the store, and the
+	* ones only the other side holds are what this restore removes.
+	*
+	* The records go in VERBATIM (`CommentStore.add` stores a record it has never seen exactly as it
+	* arrived), which is the whole point of snapshotting them: a rebuilt record would come back as a new
+	* comment, with a fresh id, a fresh `createdAt` and no questions, and the reader's thread would be
+	* gone behind a look-alike.
+	*
+	* The resolved lines of the entry are forgotten afterwards, because a range resolved against the
+	* content the comment was written on is not a fact about the content it is being restored onto: the
+	* file may have moved on while the thread was closed, so the next read has to place the quote again.
+	*
+	* Nothing here touches `ctx.fs` or the pending store: a comment is not a change to a file, and a
+	* restore that also wrote one would turn "take the comment back" into "take the edit back".
+	* @param sessionId - the session the pair was taken in (a pair's comments are one session's).
+	* @param state - the side to install.
+	* @param expectedFile - the other side; the comments only it lists are the ones to remove.
+	*/
+	function restoreComments(sessionId, state, expectedFile) {
+		const installing = state.comments ?? [];
+		const installed = new Set(installing.map((record) => record.id));
+		const stale = (expectedFile?.comments ?? []).map((record) => record.id).filter((id) => !installed.has(id));
+		if (stale.length > 0) {
+			comments.removeMany(sessionId, stale);
+			for (const id of stale) commentLines.delete(id);
+		}
+		if (installing.length > 0) comments.addMany(installing);
+		forgetCommentLinesForEntry(state.path);
 	}
 	/**
 	* Restore one snapshot (the before/after side of an undo pair). File writes
 	* carry the session sandbox policy; a divergence guard refuses to overwrite
 	* a file an outside writer has since changed. The store change is applied
-	* only after the write succeeds, keeping the restore all-or-nothing.
+	* only after the write succeeds, keeping the restore all-or-nothing — and the
+	* comments a dropping action removed are the LAST thing put back, so a refused
+	* restore cannot leave a thread on a row that did not come back.
 	* @param sessionId - the owning session.
 	* @param state - the snapshot to restore.
 	* @param expectedFile - the other side's file content, checked before a write.
 	* @param signal - aborts before atomic publication takes effect.
 	*/
 	async function restoreState(sessionId, state, expectedFile, signal) {
+		if (state.kind === "comments") {
+			restoreComments(sessionId, state, expectedFile);
+			return;
+		}
 		if (state.fileText !== void 0) {
 			const resolved = await ctx.fs.resolve(state.path, { signal });
 			if (expectedFile?.fileText !== void 0) {
@@ -2442,12 +4618,19 @@ function apply(ctx, config) {
 			await writeRevert(resolved, state.fileText, sessionId, signal);
 		}
 		if (state.batch !== void 0) {
-			for (const item of state.batch) if (item.entry !== void 0) store.restore(item.entry);
-			else store.remove(item.path);
+			const counterpart = expectedFile?.batch;
+			for (const [index, item] of state.batch.entries()) await restoreState(sessionId, {
+				...item,
+				batch: void 0
+			}, counterpart?.[index], signal);
 			return;
 		}
 		if (state.entry !== void 0) store.restore(state.entry);
-		else store.remove(state.path);
+		else dropEntry(state.path);
+		if (state.comments !== void 0 && state.comments.length > 0) {
+			comments.addMany(state.comments);
+			forgetCommentLinesForEntry(state.path);
+		}
 	}
 	/**
 	* Mirror the whole (globally-unique) entry set to disk. A write fault logs a
@@ -2529,18 +4712,101 @@ function apply(ctx, config) {
 				const sessionId = sessionOf(payload);
 				if (sessionId === void 0) return rpcError("sessionId must be a non-empty string");
 				await ensureLoaded();
+				if (comments.retain(new Set(store.all().map((entry) => entry.id))) > 0) forgetOrphanedCommentLines();
 				const { files, redoCleared } = await listWithState(sessionId);
+				const commentAnswers = {};
+				if (comments.list(sessionId).length > 0) {
+					const answers = commentAsker.answers(sessionId);
+					for (const [requestId, read] of Object.entries(answers)) if (read.turn !== void 0) comments.recordTurnForRequest(sessionId, requestId, read.turn);
+					for (const turn of commentAsker.endedTurns(sessionId)) comments.markTurnEnded(sessionId, turn);
+					for (const [requestId, read] of Object.entries(answers)) if (read.answer !== void 0) commentAnswers[requestId] = read.answer;
+				}
 				return {
 					ok: true,
 					value: {
 						files,
+						comments: comments.list(sessionId),
+						commentLines: resolvedCommentLines(sessionId),
+						commentsRevision: comments.commentsRevision(),
+						commentAnswers,
 						workspacePath: workspaceOf(sessionId)?.path,
 						redoCleared: redoCleared || void 0,
 						commentSkill: commentSkill(),
-						persistError: persistFailureReported
+						persistError: persistFailureReported,
+						commentPersistError: comments.persistError()
 					}
 				};
 			}
+			case "comment-add": {
+				const input = commentAddOf(payload);
+				if (input === void 0) return rpcError("sessionId, entryId, anchor, quote and text must be valid");
+				await ensureLoaded();
+				const entry = store.list(input.sessionId).find((candidate) => candidate.id === input.entryId);
+				if (entry === void 0) return {
+					ok: true,
+					value: { outcome: "missing" }
+				};
+				const now = Date.now();
+				const record = {
+					id: input.id ?? randomUUID(),
+					sessionId: input.sessionId,
+					entryId: entry.id,
+					path: entry.path,
+					anchor: input.anchor,
+					quote: input.quote,
+					text: input.text,
+					createdAt: now,
+					updatedAt: now,
+					...input.quoteContext === void 0 ? {} : { quoteContext: input.quoteContext },
+					...input.quoteLines === void 0 ? {} : { quoteLines: input.quoteLines }
+				};
+				comments.add(record);
+				pushUndo(input.sessionId, commentState(entry.path, []), commentState(entry.path, [record]));
+				return {
+					ok: true,
+					value: {
+						outcome: "added",
+						comment: record
+					}
+				};
+			}
+			case "comment-remove": {
+				const target = targetOf(payload);
+				if (target === void 0) return rpcError("sessionId and id must be non-empty strings");
+				await ensureLoaded();
+				const record = comments.get(target.id);
+				const removed = comments.remove(target.sessionId, target.id);
+				const value = { outcome: removed ? "removed" : "missing" };
+				if (removed && record !== void 0) pushUndo(target.sessionId, commentState(record.entryId, [record]), commentState(record.entryId, []));
+				commentLines.delete(target.id);
+				return {
+					ok: true,
+					value
+				};
+			}
+			case "comment-remove-many": {
+				const request = commentRemoveManyOf(payload);
+				if (request === void 0) return rpcError("sessionId and a non-empty ids array of strings must be given");
+				await ensureLoaded();
+				const snapshot = request.ids.map((id) => comments.get(id)).filter((record) => record !== void 0 && record.sessionId === request.sessionId);
+				const removed = comments.removeMany(request.sessionId, request.ids);
+				for (const id of removed) commentLines.delete(id);
+				const first = snapshot[0];
+				if (first !== void 0) pushUndo(request.sessionId, commentState(first.entryId, snapshot), commentState(first.entryId, []));
+				return {
+					ok: true,
+					value: { removed: removed.length }
+				};
+			}
+			case "comment-ask": {
+				const input = commentAskOf(payload);
+				if (input === void 0) return rpcError("sessionId, id, prompt and text must be valid");
+				await ensureLoaded();
+				return {
+					ok: true,
+					value: await commentAsker.ask(input.sessionId, input.id, input.prompt, input.text, signal)
+				};
+			}
 			case "keep": {
 				const target = targetOf(payload);
 				if (target === void 0) return rpcError("sessionId and id must be non-empty strings");
@@ -2580,13 +4846,14 @@ function apply(ctx, config) {
 						}
 					};
 				}
-				store.remove(target.id);
-				pushUndo(target.sessionId, {
+				const beforeDrop = droppingComments({
 					id: entry.path,
 					path: entry.path,
 					entry,
 					fileText: void 0
-				}, {
+				});
+				dropEntry(target.id);
+				pushUndo(target.sessionId, beforeDrop, {
 					id: entry.path,
 					path: entry.path,
 					entry: void 0,
@@ -2644,8 +4911,12 @@ function apply(ctx, config) {
 						}
 					};
 				}
-				store.remove(target.id);
-				if (undo !== void 0) pushUndo(target.sessionId, undo.before, undo.after);
+				const pair = undo === void 0 ? void 0 : {
+					before: droppingComments(undo.before),
+					after: undo.after
+				};
+				dropEntry(target.id);
+				if (pair !== void 0) pushUndo(target.sessionId, pair.before, pair.after);
 				persistSession(true);
 				return {
 					ok: true,
@@ -2660,33 +4931,21 @@ function apply(ctx, config) {
 				const before = [];
 				const after = [];
 				for (const entry of entries) {
-					before.push({
+					before.push(droppingComments({
 						id: entry.id,
 						path: entry.path,
 						entry,
 						fileText: void 0
-					});
+					}));
 					after.push({
 						id: entry.id,
 						path: entry.path,
 						entry: void 0,
 						fileText: void 0
 					});
-					store.remove(entry.id);
+					dropEntry(entry.id);
 				}
-				if (before.length > 0) pushUndo(sessionId, {
-					id: before[0].id,
-					path: before[0].path,
-					entry: void 0,
-					fileText: void 0,
-					batch: before
-				}, {
-					id: after[0].id,
-					path: after[0].path,
-					entry: void 0,
-					fileText: void 0,
-					batch: after
-				});
+				if (before.length > 0) pushBatchUndo(sessionId, before, after);
 				persistSession(true);
 				return {
 					ok: true,
@@ -2708,30 +4967,121 @@ function apply(ctx, config) {
 						return rpcError(`revert-all failed for ${entry.path}`);
 					}
 					if (undo !== void 0) {
-						batchBefore.push(undo.before);
+						batchBefore.push(droppingComments(undo.before));
 						batchAfter.push(undo.after);
 					}
-					store.remove(entry.id);
+					dropEntry(entry.id);
 				}
-				if (batchBefore.length > 0) pushUndo(sessionId, {
-					id: batchBefore[0].id,
-					path: batchBefore[0].path,
-					entry: void 0,
-					fileText: void 0,
-					batch: batchBefore
-				}, {
-					id: batchAfter[0].id,
-					path: batchAfter[0].path,
-					entry: void 0,
-					fileText: void 0,
-					batch: batchAfter
-				});
+				if (batchBefore.length > 0) pushBatchUndo(sessionId, batchBefore, batchAfter);
 				persistSession(true);
 				return {
 					ok: true,
 					value: { affected: entries.length }
 				};
 			}
+			case "keep-many": {
+				const request = manyTargetsOf(payload);
+				if (request === void 0) return rpcError("sessionId and a non-empty ids array of strings must be given");
+				await ensureLoaded();
+				const before = [];
+				const after = [];
+				for (const id of request.ids) {
+					const entry = store.get(id);
+					if (entry === void 0) continue;
+					if (request.keepListed === true) {
+						store.update(id, { oldText: entry.newText });
+						before.push({
+							id: entry.id,
+							path: entry.path,
+							entry,
+							fileText: void 0
+						});
+						after.push({
+							id: entry.id,
+							path: entry.path,
+							entry: {
+								...entry,
+								oldText: entry.newText,
+								updatedAt: Date.now()
+							},
+							fileText: void 0
+						});
+						continue;
+					}
+					before.push(droppingComments({
+						id: entry.id,
+						path: entry.path,
+						entry,
+						fileText: void 0
+					}));
+					after.push({
+						id: entry.id,
+						path: entry.path,
+						entry: void 0,
+						fileText: void 0
+					});
+					dropEntry(id);
+				}
+				pushBatchUndo(request.sessionId, before, after);
+				persistSession(true);
+				return {
+					ok: true,
+					value: { affected: before.length }
+				};
+			}
+			case "revert-many": {
+				const request = manyTargetsOf(payload);
+				if (request === void 0) return rpcError("sessionId and a non-empty ids array of strings must be given");
+				await ensureLoaded();
+				const before = [];
+				const after = [];
+				let affected = 0;
+				for (const id of request.ids) {
+					const entry = store.get(id);
+					if (entry === void 0) continue;
+					affected += 1;
+					let undo;
+					try {
+						undo = await revertEntryContent(entry, request.sessionId, signal);
+					} catch {
+						return rpcError(`revert-many failed for ${entry.path}`);
+					}
+					if (request.keepListed === true) {
+						const content = undo?.after.fileText ?? "";
+						store.update(id, { newText: content });
+						if (undo !== void 0) {
+							before.push({
+								id: entry.path,
+								path: entry.path,
+								entry,
+								fileText: undo.before.fileText
+							});
+							after.push({
+								id: entry.path,
+								path: entry.path,
+								entry: {
+									...entry,
+									newText: content,
+									updatedAt: Date.now()
+								},
+								fileText: content
+							});
+						}
+						continue;
+					}
+					if (undo !== void 0) {
+						before.push(droppingComments(undo.before));
+						after.push(undo.after);
+					}
+					dropEntry(id);
+				}
+				pushBatchUndo(request.sessionId, before, after);
+				persistSession(true);
+				return {
+					ok: true,
+					value: { affected }
+				};
+			}
 			case "block-keep": {
 				const blockTarget = blockTargetOf(payload);
 				if (blockTarget === void 0) return rpcError("sessionId, id, and block must be valid");
@@ -2763,13 +5113,14 @@ function apply(ctx, config) {
 				persistSession();
 				const fullyResolved = contentEqual(updatedOld, entry.newText);
 				if (fullyResolved && blockTarget.removeWhenResolved === true) {
-					store.remove(blockTarget.id);
-					pushUndo(blockTarget.sessionId, {
+					const resolvedDrop = droppingComments({
 						id: entry.id,
 						path: entry.path,
 						entry: afterEntry,
 						fileText: void 0
-					}, {
+					});
+					dropEntry(blockTarget.id);
+					pushUndo(blockTarget.sessionId, resolvedDrop, {
 						id: entry.id,
 						path: entry.path,
 						entry: void 0,
@@ -2806,7 +5157,7 @@ function apply(ctx, config) {
 				let undo;
 				try {
 					const target = await ctx.fs.resolve(entry.path, { signal });
-					if (entry.kind === "create" && content === "") await rm(ctx.fs.processPath(target), { force: true });
+					if (entry.kind === "create" && content === "") await removeRevert(target, blockTarget.sessionId, signal);
 					else {
 						const preWrite = await ctx.fs.readText(target, void 0) ?? entry.newText;
 						await writeRevert(target, content, blockTarget.sessionId, signal);
@@ -2832,13 +5183,14 @@ function apply(ctx, config) {
 				persistSession();
 				const fullyResolved = contentEqual(updatedNew, entry.oldText);
 				if (fullyResolved && blockTarget.removeWhenResolved === true) {
-					store.remove(blockTarget.id);
-					pushUndo(blockTarget.sessionId, {
+					const resolvedDrop = droppingComments({
 						id: entry.id,
 						path: entry.path,
 						entry: afterEntry,
 						fileText: void 0
-					}, {
+					});
+					dropEntry(blockTarget.id);
+					pushUndo(blockTarget.sessionId, resolvedDrop, {
 						id: entry.id,
 						path: entry.path,
 						entry: void 0,
@@ -2857,18 +5209,18 @@ function apply(ctx, config) {
 			case "undo": {
 				const sessionId = sessionOf(payload);
 				if (sessionId === void 0) return rpcError("sessionId must be a non-empty string");
-				const pair = undoStack.pop();
+				const pair = popOwnPair(undoStackOf(sessionId), sessionId);
 				if (pair === void 0) return {
 					ok: true,
 					value: { outcome: "nothing" }
 				};
 				try {
-					await restoreState(sessionId, pair.before, pair.after, signal);
+					await restoreState(pair.sessionId, pair.before, pair.after, signal);
 				} catch (error) {
-					undoStack.push(pair);
+					undoStackOf(sessionId).push(pair);
 					return rpcError(`undo failed: ${errorMessage(error)}`);
 				}
-				redoStack.push(pair);
+				redoStackOf(sessionId).push(pair);
 				persistSession(true);
 				return {
 					ok: true,
@@ -2881,18 +5233,18 @@ function apply(ctx, config) {
 			case "redo": {
 				const sessionId = sessionOf(payload);
 				if (sessionId === void 0) return rpcError("sessionId must be a non-empty string");
-				const pair = redoStack.pop();
+				const pair = popOwnPair(redoStackOf(sessionId), sessionId);
 				if (pair === void 0) return {
 					ok: true,
 					value: { outcome: "nothing" }
 				};
 				try {
-					await restoreState(sessionId, pair.after, pair.before, signal);
+					await restoreState(pair.sessionId, pair.after, pair.before, signal);
 				} catch (error) {
-					redoStack.push(pair);
+					redoStackOf(sessionId).push(pair);
 					return rpcError(`redo failed: ${errorMessage(error)}`);
 				}
-				undoStack.push(pair);
+				undoStackOf(sessionId).push(pair);
 				persistSession(true);
 				return {
 					ok: true,
@@ -3375,6 +5727,136 @@ function targetOf(payload) {
 		id
 	};
 }
+/**
+* Narrow a wire payload to one keep/revert over a PICK of files: one session, the files to act on, and
+* whether the resolved ones stay listed.
+*
+* The ids are all-or-nothing, like the pick itself: a payload with one unusable id is not a pick, so the
+* whole request is refused rather than half-honoured (the ids themselves are still only acted on where
+* they exist, which is the endpoint's business). A repeated id names one file, so it is kept once.
+*
+* @param payload - the wire payload.
+* @returns the request, or undefined when it is not one.
+*/
+function manyTargetsOf(payload) {
+	const sessionId = sessionOf(payload);
+	if (sessionId === void 0) return void 0;
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return void 0;
+	const record = payload;
+	const ids = record.ids;
+	if (!Array.isArray(ids) || ids.length === 0) return void 0;
+	const wanted = [];
+	for (const id of ids) {
+		if (typeof id !== "string" || id.length === 0) return void 0;
+		if (!wanted.includes(id)) wanted.push(id);
+	}
+	return {
+		sessionId,
+		ids: wanted,
+		keepListed: record.keepListed === true ? true : void 0
+	};
+}
+/**
+* Narrow a wire payload to one batch comment removal: one session, and the comments to drop.
+*
+* The ids are all-or-nothing: a payload with one unusable id is not a batch, so the whole request
+* is refused rather than half-honoured (the ids themselves are still only dropped where they exist,
+* which is `CommentStore.removeMany`'s business). A repeated id names one comment, so it is kept once.
+*
+* @param payload - the wire payload.
+* @returns the request, or undefined when it is not one.
+*/
+function commentRemoveManyOf(payload) {
+	const sessionId = sessionOf(payload);
+	if (sessionId === void 0) return void 0;
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return void 0;
+	const ids = payload.ids;
+	if (!Array.isArray(ids) || ids.length === 0) return void 0;
+	const wanted = [];
+	for (const id of ids) {
+		if (typeof id !== "string" || id.length === 0) return void 0;
+		if (!wanted.includes(id)) wanted.push(id);
+	}
+	return {
+		sessionId,
+		ids: wanted
+	};
+}
+/**
+* Narrow a wire payload to one comment-ask request: a target, the prompt to send, and the
+* reader's own words that prompt wraps.
+*
+* Both strings are required. The prompt is what the agent is asked; `text` is what the
+* thread shows as the question, and it cannot be recovered from the prompt (which carries
+* the marker, the reference and the rules around it) — a request without it would store a
+* question nobody can read, so it is refused instead.
+*
+* @param payload - the wire payload.
+* @returns the request, or undefined when it is not one.
+*/
+function commentAskOf(payload) {
+	const target = targetOf(payload);
+	if (target === void 0) return void 0;
+	const record = payload;
+	const prompt = record.prompt;
+	if (typeof prompt !== "string" || prompt.trim().length === 0) return void 0;
+	const text = record.text;
+	if (typeof text !== "string" || text.trim().length === 0) return void 0;
+	return {
+		...target,
+		prompt,
+		text
+	};
+}
+/**
+* Narrow a wire payload to one comment-add request.
+*
+* The display path is deliberately NOT read from the wire: the entry a comment
+* hangs off is the authority on what that file is called, so a client cannot pin a
+* comment to a path the list disagrees with.
+*
+* @param payload - the request body.
+* @returns the narrowed request, or `undefined` when a required field is missing.
+*/
+function commentAddOf(payload) {
+	const sessionId = sessionOf(payload);
+	if (sessionId === void 0) return void 0;
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return void 0;
+	const body = payload;
+	const { entryId, anchor, quote, text } = body;
+	if (typeof entryId !== "string" || entryId.length === 0) return void 0;
+	if (typeof anchor !== "object" || anchor === null || Array.isArray(anchor)) return void 0;
+	const { startLine, endLine } = anchor;
+	if (typeof startLine !== "number" || !Number.isFinite(startLine)) return void 0;
+	if (typeof endLine !== "number" || !Number.isFinite(endLine)) return void 0;
+	if (typeof quote !== "string") return void 0;
+	if (typeof text !== "string" || text.trim().length === 0) return void 0;
+	const id = body.id;
+	const quoteContext = body.quoteContext;
+	const quoteLines = [];
+	if (Array.isArray(body.quoteLines)) for (const line of body.quoteLines) {
+		if (typeof line !== "object" || line === null || Array.isArray(line)) continue;
+		const { old, new: side, kind } = line;
+		quoteLines.push({
+			...typeof old === "number" && Number.isFinite(old) ? { old } : {},
+			...typeof side === "number" && Number.isFinite(side) ? { new: side } : {},
+			...kind === "add" || kind === "del" || kind === "context" ? { kind } : {}
+		});
+	}
+	return {
+		sessionId,
+		id: typeof id === "string" && id.length > 0 ? id : void 0,
+		entryId,
+		anchor: {
+			startLine,
+			endLine
+		},
+		quote,
+		quoteContext: typeof quoteContext === "string" && quoteContext !== "" ? quoteContext : void 0,
+		quoteLines: quoteLines.length > 0 ? quoteLines : void 0,
+		text
+	};
+}
 /** Narrow a wire payload to one preview-image target. */
 function previewImageTargetOf(payload) {
 	const sessionId = sessionOf(payload);
@@ -3534,4 +6016,4 @@ function fontRoute(warn) {
 	};
 }
 //#endregion
-export { COMMENT_SKILL_NAME, DIFF_APPROVAL_CHANNEL, PendingDiffStore, PendingPersistence, apply, defaultOpenPath, defaultStorageDir, fontRoute, inject, name, resetFontSlicesForTests, serveFontSlice };
+export { COMMENT_SKILL_NAME, CommentAsker, CommentStore, DIFF_APPROVAL_CHANNEL, PendingDiffStore, PendingPersistence, answerForRequest, apply, commentsDirFor, defaultOpenPath, defaultStorageDir, fontRoute, inject, name, resetFontSlicesForTests, serveFontSlice };