dsh-diff-approval 0.30.1 → 0.32.0

package/lib/index.js

@@ -896,7 +896,7 @@ function touchedBy(entry) {
 function sameEntry(left, right) {
 	const lIds = touchedBy(left);
 	const rIds = touchedBy(right);
-	return left.path === right.path && left.kind === right.kind && left.oldText === right.oldText && left.newText === right.newText && left.updatedAt === right.updatedAt && left.sessionId === right.sessionId && lIds.length === rIds.length && lIds.every((id, index) => id === rIds[index]);
+	return left.path === right.path && left.earlierVersion === right.earlierVersion && left.oldText === right.oldText && left.newText === right.newText && left.updatedAt === right.updatedAt && left.sessionId === right.sessionId && lIds.length === rIds.length && lIds.every((id, index) => id === rIds[index]);
 }
 /**
 * The pending-diff store: one entry per file path across all sessions. Keep /
@@ -951,21 +951,24 @@ var PendingDiffStore = class {
 		return true;
 	}
 	/**
-	* Combine a stored entry and a new capture. `oldText` comes from the earlier
-	* capture (the file's original basis), `newText` from the later (latest
-	* content), and the session set is the union — so the entry always spans the
-	* whole pending change regardless of which session contributed which part.
+	* Combine a stored entry and a new capture. `oldText` comes from the earlier capture (the file's
+	* original basis) — except where that capture was the file's creation and this one edits it, when
+	* the creation's own content becomes the basis — and `newText` from the later (latest content).
+	* The session set is the union, so the entry always spans the whole pending change regardless of
+	* which session contributed which part.
 	*/
 	mergeEntry(a, b) {
 		const earlier = a.updatedAt <= b.updatedAt ? a : b;
 		const later = earlier === a ? b : a;
 		const sessionIds = [.../* @__PURE__ */ new Set([...touchedBy(a), b.sessionId])];
+		const onlyCreations = earlier.earlierVersion === "none" && later.earlierVersion === "none";
 		return {
 			...later,
 			id: later.path,
-			oldText: earlier.oldText,
-			kind: earlier.kind === "create" || later.kind === "create" ? "create" : "edit",
-			sessionIds
+			oldText: onlyCreations ? "" : earlier.earlierVersion === "none" ? earlier.newText : earlier.oldText,
+			earlierVersion: onlyCreations ? "none" : "file",
+			sessionIds,
+			unseen: earlier.unseen === true || later.unseen === true
 		};
 	}
 	/**
@@ -1006,6 +1009,15 @@ var PendingDiffStore = class {
 	/**
 	* Advance one entry's tracked content after a block-level keep/revert. The
 	* entry keeps its path; only the given side's text and capture time move.
+	*
+	* A keep that advances `oldText` also ends the entry's life as a creation. `earlierVersion` is the fact
+	* "this file did not exist before", and once part of the file has been accepted there IS an earlier
+	* version to restore — what the reader kept. The whole-file action must therefore become 回退, not 删除:
+	* deleting would throw away the part they just accepted. (Leaving the field alone kept a partly-kept new
+	* file offering to delete itself, which is what sent the reader here.)
+	*
+	* Every caller of this is a reader action — a block keep or revert, a refresh from version control — so it
+	* also takes the unseen dot down: the reader has just handled this file.
 	* @param path - the file path.
 	* @param patch - the side to advance (`oldText` for keep, `newText` for revert).
 	* @returns whether the entry changed.
@@ -1013,9 +1025,12 @@ var PendingDiffStore = class {
 	update(path, patch) {
 		const entry = this.entries.get(pathKeyOf(path));
 		if (entry === void 0) return false;
+		const kept = patch.oldText !== void 0;
 		const next = {
 			...entry,
 			...patch,
+			...kept ? { earlierVersion: "file" } : {},
+			unseen: false,
 			updatedAt: Date.now()
 		};
 		this.entries.set(pathKeyOf(path), next);
@@ -1023,6 +1038,50 @@ var PendingDiffStore = class {
 		return true;
 	}
 	/**
+	* Mark paths the reader has now seen — the file was opened, or its row was acted on. The dot is about
+	* attention rather than content, so this and the entry leaving the list are the only ways it goes out, and
+	* nothing brings it back except a new capture.
+	* @param paths - one path, or several.
+	* @returns whether anything changed.
+	*/
+	markSeen(paths) {
+		const list = typeof paths === "string" ? [paths] : paths;
+		let changed = false;
+		for (const path of list) {
+			const key = pathKeyOf(path);
+			const entry = this.entries.get(key);
+			if (entry === void 0 || entry.unseen !== true) continue;
+			this.entries.set(key, {
+				...entry,
+				unseen: false
+			});
+			changed = true;
+		}
+		return changed;
+	}
+	/**
+	* Raise the dot for paths whose content moved WITHOUT the reader asking — a writer outside the panel, a
+	* second process. The capture sites set the field on the entry they fold; this is for the changes the
+	* plugin notices by itself while refreshing, which do not come through a capture.
+	* @param paths - one path, or several.
+	* @returns whether anything changed.
+	*/
+	markUnseen(paths) {
+		const list = typeof paths === "string" ? [paths] : paths;
+		let changed = false;
+		for (const path of list) {
+			const key = pathKeyOf(path);
+			const entry = this.entries.get(key);
+			if (entry === void 0 || entry.unseen === true) continue;
+			this.entries.set(key, {
+				...entry,
+				unseen: true
+			});
+			changed = true;
+		}
+		return changed;
+	}
+	/**
 	* Restore one entry exactly as given (an undo/redo replays a snapshot). The
 	* entry is inserted or replaced by path.
 	* @param entry - the entry state to restore.
@@ -1032,7 +1091,10 @@ var PendingDiffStore = class {
 		const key = pathKeyOf(entry.path);
 		const existing = this.entries.get(key);
 		if (existing !== void 0 && sameEntry(existing, entry)) return false;
-		this.entries.set(key, { ...entry });
+		this.entries.set(key, {
+			...entry,
+			unseen: existing?.unseen === true
+		});
 		if (existing === void 0 || existing.newText !== entry.newText) this.bumpContent(entry.path);
 		return true;
 	}
@@ -1173,13 +1235,43 @@ function defaultStorageDir() {
 const FILE_VERSION = 3;
 /** Legacy per-workspace-file version, accepted only for migration. */
 const LEGACY_FILE_VERSION = 2;
+/** The pre-rename spelling of the entry's `earlierVersion`, or undefined for anything else. */
+function legacyEarlierVersion(kind) {
+	if (kind === "edit") return "file";
+	if (kind === "create") return "none";
+}
+/**
+* The lineage one persisted row carries, or `undefined` when it carries none worth keeping.
+*
+* Every part is read independently and dropped when it is not the shape this record writes: a row from
+* an older build has no `lineage` key at all (that is the `undefined` value here, not an error), and a
+* hand-edited or truncated one may carry anything. A row whose parts are all missing is stored WITHOUT
+* a lineage rather than as an empty object, so "not known" has exactly one spelling on disk.
+* @param value - the row's `lineage` field, as parsed JSON.
+* @returns the lineage to keep, or `undefined`.
+*/
+function lineageOfRow(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const record = value;
+	const parent = record.parentSessionId;
+	const depth = record.delegationDepth;
+	const lineage = {
+		parentSessionId: typeof parent === "string" && parent.length > 0 ? parent : void 0,
+		origin: typeof record.origin === "string" && record.origin.length > 0 ? record.origin : void 0,
+		delegationDepth: typeof depth === "number" && Number.isFinite(depth) ? depth : void 0,
+		cwd: typeof record.cwd === "string" && record.cwd.length > 0 ? record.cwd : void 0
+	};
+	return lineage.parentSessionId !== void 0 || lineage.origin !== void 0 || lineage.delegationDepth !== void 0 || lineage.cwd !== void 0 ? lineage : void 0;
+}
 /** Narrow one JSON value to a pending entry; malformed rows are skipped. */
 function pendingEntryOf(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
-	const { id, path, kind, oldText, newText, updatedAt, sessionId, sessionIds } = value;
+	const record = value;
+	const { id, path, oldText, newText, updatedAt, sessionId, sessionIds } = record;
+	const earlierVersion = record.earlierVersion ?? legacyEarlierVersion(record.kind);
 	if (typeof id !== "string" || id.length === 0) return void 0;
 	if (typeof path !== "string" || path.length === 0) return void 0;
-	if (kind !== "edit" && kind !== "create") return void 0;
+	if (earlierVersion !== "file" && earlierVersion !== "none") return void 0;
 	if (typeof oldText !== "string" || typeof newText !== "string") return void 0;
 	if (typeof updatedAt !== "number") return void 0;
 	if (typeof sessionId !== "string" || sessionId.length === 0) return void 0;
@@ -1187,12 +1279,14 @@ function pendingEntryOf(value) {
 	return {
 		id: path,
 		path,
-		kind,
+		earlierVersion,
 		oldText,
 		newText,
 		updatedAt,
+		unseen: record.unseen === true ? true : void 0,
 		sessionId,
-		sessionIds: ids.length > 0 ? ids : [sessionId]
+		sessionIds: ids.length > 0 ? ids : [sessionId],
+		lineage: lineageOfRow(record.lineage)
 	};
 }
 /** Validate a parsed global file. */
@@ -1371,6 +1465,19 @@ function commentsDirFor(storageRoot) {
 function fileOf(root, sessionId) {
 	return join(root, `${encodeURIComponent(String(sessionId))}.json`);
 }
+/**
+* One answer map as a comment record keeps it: keys that name a question, values that are the text
+* read for it. Narrowed here like every other stored field, so a file that has drifted (or been
+* hand-edited) cannot put a non-string where an answer's text is expected.
+* @param value - the stored value.
+* @returns the map, or undefined when there is nothing usable in it.
+*/
+function answersOf(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const map = {};
+	for (const [requestId, text] of Object.entries(value)) if (typeof text === "string") map[requestId] = text;
+	return Object.keys(map).length === 0 ? void 0 : map;
+}
 /** 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;
@@ -1389,6 +1496,10 @@ function commentOf(value) {
 	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;
+	const category = typeof row.category === "string" ? row.category.trim() : "";
+	const asks = asksOf(row.asks);
+	const answerSeen = answersOf(row.answerSeen);
+	const answerNow = answersOf(row.answerNow);
 	return {
 		id,
 		sessionId,
@@ -1402,10 +1513,14 @@ function commentOf(value) {
 		text,
 		createdAt,
 		updatedAt,
+		...row.unseen === true ? { unseen: true } : {},
 		...author === void 0 ? {} : { author },
+		...category === "" ? {} : { category },
 		...typeof context === "string" && context !== "" ? { quoteContext: context } : {},
 		...quoteLines.length > 0 ? { quoteLines } : {},
-		...asksOf(row.asks).length > 0 ? { asks: asksOf(row.asks) } : {}
+		...asks.length > 0 ? { asks } : {},
+		...answerSeen === void 0 ? {} : { answerSeen },
+		...answerNow === void 0 ? {} : { answerNow }
 	};
 }
 /** Narrow a stored thread's questions; malformed rows are skipped. */
@@ -1419,8 +1534,10 @@ function asksOf(value) {
 		if (typeof requestId !== "string" || requestId.length === 0) continue;
 		const turn = record.turn;
 		const text = record.text;
+		const sessionId = record.sessionId;
 		asks.push({
 			requestId,
+			...typeof sessionId === "string" && sessionId !== "" ? { sessionId } : {},
 			...typeof text === "string" && text !== "" ? { text } : {},
 			...typeof turn === "number" ? { turn } : {},
 			...record.dropped === true ? { dropped: true } : {},
@@ -1433,6 +1550,98 @@ function asksOf(value) {
 function hasAsk(comment, requestId, wanted) {
 	return (comment.asks ?? []).some((ask) => ask.requestId === requestId && wanted(ask));
 }
+/**
+* The transcript one question's answer will be written in.
+*
+* `ask.sessionId` when the question recorded one — every question asked since a lineage could read more
+* than one seat's threads does — otherwise the comment's own session, which is where a question asked
+* before that field existed necessarily went: the only session that could ask it was the one that wrote
+* the thread. ONE definition, shared by the answer fold, the turn-end match and the asker's grouping,
+* so the three cannot disagree about which transcript a question belongs to.
+* @param ask - the question.
+* @param comment - the thread it was asked in.
+* @returns the session whose transcript holds its answer.
+*/
+function askTranscript(ask, comment) {
+	return ask.sessionId ?? comment.sessionId;
+}
+/** Whether two answer maps say the same thing, key for key and text for text. */
+function sameAnswers(left, right) {
+	const one = Object.entries(left ?? {});
+	const two = right ?? {};
+	if (one.length !== Object.keys(two).length) return false;
+	return one.every(([requestId, text]) => two[requestId] === text);
+}
+/**
+* What ONE transcript currently says about the questions it owns, and which questions those are.
+*
+* Only the questions asked in that transcript are taken: a read is one session's, and a thread that
+* stored every other transcript's answers would be a copy of the conversation rather than its own
+* state. A question the read found no answer for is left out rather than stored empty, so a turn that
+* has not written yet cannot look like an answer that changed.
+* @param comment - the thread, for the questions it asked.
+* @param sessionId - the transcript being read.
+* @param answers - that transcript's answer text per question id.
+* @returns the thread's own question ids there, and the answers it holds for them.
+*/
+function answersInTranscript(comment, sessionId, answers) {
+	const own = [];
+	const now = {};
+	for (const ask of comment.asks ?? []) {
+		if (askTranscript(ask, comment) !== sessionId) continue;
+		own.push(ask.requestId);
+		const text = answers[ask.requestId]?.answer;
+		if (text !== void 0) now[ask.requestId] = text;
+	}
+	return {
+		own,
+		now
+	};
+}
+/**
+* One thread as a read of ONE transcript leaves it: its questions' current answers, and the dot up if
+* those say something the reader has not been told about.
+*
+* "New" is a DIFFERENCE, not a presence: the transcript answers a question once and hands back the
+* same text on every read afterwards, so "is there an answer" would leave the dot up forever, and
+* "did it change since the last read" would lose the answer entirely on the restart that forgot the
+* previous read. The comparison is against `answerSeen` — the baseline the reader's own visit writes
+* down — and it is STICKY: an answer that arrived while the dot was already up does not need to raise
+* it again. A question the transcript shows no answer for is absent here, so a log this process cannot
+* read, or a turn that has not written yet, leaves the thread exactly as it was.
+*
+* A thread may hold questions asked in MORE THAN ONE transcript (one card, two seats, each asking from
+* its own conversation). This fold owns only its own transcript's entries: it updates those, clears the
+* ones that transcript no longer shows an answer for, and leaves every other group exactly as that
+* group's own fold left it. Replacing the map wholesale would erase a second transcript's answers on
+* the next poll — the reader would watch an answer appear and then vanish.
+* @param comment - the thread as it stands.
+* @param sessionId - the transcript being read.
+* @param answers - that transcript's answer text per question id.
+* @returns what the record should hold after this read.
+*/
+function answerStateOf(comment, sessionId, answers) {
+	const { own, now } = answersInTranscript(comment, sessionId, answers);
+	const answerNow = { ...comment.answerNow ?? {} };
+	for (const requestId of own) {
+		const text = now[requestId];
+		if (text === void 0) delete answerNow[requestId];
+		else answerNow[requestId] = text;
+	}
+	const seen = comment.answerSeen ?? {};
+	const lit = comment.unseen === true || Object.entries(answerNow).some(([requestId, text]) => seen[requestId] !== text);
+	const next = {
+		...comment,
+		answerNow,
+		unseen: lit
+	};
+	if (!lit) delete next.unseen;
+	return next;
+}
+/** Whether a patch would leave a comment exactly as it stands (the check that keeps a read from saving). */
+function sameRecord(before, after) {
+	return before.unseen === after.unseen && sameAnswers(before.answerNow, after.answerNow);
+}
 /** Read one file's JSON; `undefined` when absent (the normal empty state). */
 async function readJson(file) {
 	let raw;
@@ -1593,8 +1802,24 @@ var CommentStore = class {
 		}
 		this.options.onLoadSkipped?.(file, error);
 	}
-	/** One session's comments, oldest first (the order threads are read in). */
-	list(sessionId) {
+	/**
+	* The comments one SCOPE may read, oldest first (the order threads are read in).
+	*
+	* The scope is the caller's lineage rule (`CommentScope`), so a seat reads every thread of the seats
+	* it shares a lineage root with — not only the ones it wrote. The files do not move for that: each
+	* comment still lives in its author's file (see `save`), and the fan-out happens here, in memory,
+	* over the one map `loadAll` filled from every file. That is what keeps a teammate's already-written
+	* threads visible, with no migration.
+	* @param scope - which comment authors this caller may read.
+	* @returns the comments those authors wrote, oldest first.
+	*/
+	list(scope) {
+		const listed = [];
+		for (const comment of this.byId.values()) if (scope(comment.sessionId)) listed.push(comment);
+		return listed.sort((left, right) => left.createdAt - right.createdAt);
+	}
+	/** One author's own comments, oldest first: the WRITE-SET of that author's file (see `save`). */
+	authoredBy(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);
@@ -1612,6 +1837,63 @@ var CommentStore = class {
 		return this.revision;
 	}
 	/**
+	* Fold what ONE transcript now says into the threads that asked there, so a thread whose answer has
+	* arrived (or been rewritten) wears the dot.
+	*
+	* The answers are DERIVED on every list read and never trusted from the file (see
+	* `CommentRecord.answerNow`): the read is the only moment the host knows what the agent has said, and
+	* the comparison it makes is against a baseline that survives a restart — a restart must not light a
+	* dot the reader already cleared, and a read that changed nothing must not light one at all. That is
+	* what `answerSeen` is, and why this writes a baseline only when the text actually moved.
+	*
+	* A question the transcript shows no answer for goes back to ABSENT rather than looking like an
+	* empty answer: a log this process cannot read (or a turn that has not written yet) then leaves the
+	* dot exactly as it was, instead of raising it on every poll.
+	*
+	* The patch's own key is the TRANSCRIPT, not the comment's author: a thread written in one seat can
+	* hold a question asked from another (see `askTranscript`), and this read is that other seat's log.
+	* Only the questions whose answer lives in `sessionId` are folded; a thread that also holds questions
+	* asked elsewhere keeps those exactly as that transcript's own fold left them.
+	*
+	* @param sessionId - the transcript being folded, which owns the questions it is handed.
+	* @param answers - the answer text per question id, as that transcript read it.
+	* @returns whether any thread changed.
+	*/
+	syncAnswers(sessionId, answers) {
+		const lit = (comment) => {
+			if (!(comment.asks ?? []).some((ask) => askTranscript(ask, comment) === sessionId)) return void 0;
+			const next = answerStateOf(comment, sessionId, answers);
+			return sameRecord(comment, next) ? void 0 : next;
+		};
+		return this.patch((comment) => lit(comment) !== void 0, (comment) => lit(comment) ?? comment) > 0;
+	}
+	/**
+	* Mark one comment as looked at: the dot goes out, and the answers it currently shows become the
+	* baseline a later rewrite is measured against — otherwise the next read would find the same answer
+	* "new" again and put the dot straight back up.
+	*
+	* Deliberately its own seam rather than something a read does: only a reader action (the card coming
+	* into view) may clear attention, and a read that cleared it would make the dot impossible to see.
+	*
+	* @param id - the comment the reader has in front of them.
+	* @returns whether the comment existed.
+	*/
+	markSeen(id) {
+		const before = this.byId.get(id);
+		if (before === void 0) return false;
+		const seen = before.answerNow ?? {};
+		const next = {
+			...before,
+			answerSeen: { ...seen }
+		};
+		delete next.unseen;
+		if (before.unseen !== true && sameAnswers(before.answerSeen, next.answerSeen)) return false;
+		this.byId.set(id, next);
+		this.revision += 1;
+		this.save(before.sessionId);
+		return true;
+	}
+	/**
 	* Record one annotation.
 	*
 	* Writing a comment that is already here is the SAME comment written again — a client
@@ -1678,50 +1960,62 @@ var CommentStore = class {
 	*/
 	mergeOf(record) {
 		const before = this.byId.get(record.id);
-		return before === void 0 ? record : {
+		if (before === void 0) return record;
+		const merged = {
 			...record,
 			createdAt: before.createdAt,
-			...before.asks === void 0 ? {} : { asks: before.asks }
+			...before.asks === void 0 ? {} : { asks: before.asks },
+			...record.answerSeen === void 0 && before.answerSeen !== void 0 ? { answerSeen: before.answerSeen } : {}
 		};
+		delete merged.unseen;
+		if (before.unseen === true) merged.unseen = true;
+		return merged;
 	}
 	/**
-	* Drop one comment.
-	* @param sessionId - the session the caller believes the comment belongs to.
+	* Drop one comment the caller's scope covers.
+	* @param scope - which comment authors the caller may act on.
 	* @param id - the comment to drop.
-	* @returns whether it was there (and belonged to that session).
+	* @returns whether it was there (and was in scope).
 	*/
-	remove(sessionId, id) {
-		return this.removeMany(sessionId, [id]).length === 1;
+	remove(scope, id) {
+		return this.removeMany(scope, [id]).length === 1;
 	}
 	/**
-	* Drop several comments of one session in ONE write.
+	* Drop several comments in one write PER FILE that holds them.
 	*
 	* 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.
+	* `remove` saves the 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 a file.
+	*
+	* Each record is removed from the file that HOLDS it, which is its author's (`save`), not the
+	* caller's: once a lineage reads every seat's threads, a batch can name comments written by several
+	* seats, and routing them all to the caller's file would leave the real files holding records the
+	* store no longer has — the next load would resurrect every one of them.
 	*
-	* An id of another session, or one that is not here at all, is skipped rather than refused:
+	* An id outside the scope, 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 scope - which comment authors the caller may act on.
 	* @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) {
+	removeMany(scope, ids) {
 		const removed = [];
+		const sessions = /* @__PURE__ */ new Set();
 		for (const id of ids) {
 			if (removed.includes(id)) continue;
 			const comment = this.byId.get(id);
-			if (comment === void 0 || comment.sessionId !== sessionId) continue;
+			if (comment === void 0 || !scope(comment.sessionId)) continue;
 			this.byId.delete(id);
 			removed.push(id);
+			sessions.add(comment.sessionId);
 		}
 		if (removed.length === 0) return removed;
 		this.revision += 1;
-		this.save(sessionId);
+		for (const sessionId of sessions) this.save(sessionId);
 		return removed;
 	}
 	/**
@@ -1762,31 +2056,38 @@ var CommentStore = class {
 		return removed;
 	}
 	/**
-	* The orphan sweep: drop every comment whose entry is not in `entryIds`.
+	* The orphan sweep: prune every comment whose entry is not in `entryIds`, in MEMORY ONLY.
+	*
+	* The explicit `removeForEntry` is the primary path and the ONLY one that erases; this is the view
+	* filter that guarantees no read is ever handed a comment naming a file the list does not carry. Run it
+	* when the store loads and on every list read.
+	*
+	* WHY IT DOES NOT SAVE (2026-10-06, a data loss measured on the live host). The sweep used to write the
+	* pruned state to the files, on the assumption that an entry absent here had been removed while the host
+	* was running. That is only one of two ways an entry can be missing; the other is that its ADD never
+	* reached `pending.json` — a pending entry is folded in memory and persisted on a later flush — and then
+	* the sweep deleted the comments hanging on it AND saved the deletion. Three real annotations were gone
+	* from the disk after a restart, not merely hidden: the reader's cards were written first and their
+	* entries never landed. An entry that exists but is not on disk yet is not an orphan.
+	*
+	* A write would not even help the case it was added for. A second client must never be handed a comment
+	* naming a file the same read no longer lists — that is a VIEW requirement, and the prune satisfies it.
+	* Erasure belongs to the paths where a removal was actually ASKED FOR: `removeForEntry` (what the panel's
+	* own drop calls, and it removes the comments in the same tick), and `remove`/`removeMany` for one
+	* thread. A genuine orphan therefore stays on the disk, hidden, until the next boot that sees the entry
+	* again — a row nobody reads is a smaller price than a reader's annotation nobody can recover.
 	*
-	* 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.
+	* @returns how many comments the view 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);
-		}
+		if (removed > 0) this.revision += 1;
 		return removed;
 	}
 	/**
@@ -1800,7 +2101,14 @@ var CommentStore = class {
 	* 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.
+	* The ASKING session is recorded on the question, not taken from the comment: a thread another
+	* seat wrote can be asked from this one, and the prompt then goes into the seat the human is
+	* using, so that session's transcript is where the answer will appear (see `askTranscript`).
+	*
+	* Matched by comment ID alone: the request id is minted here and is globally unique, and the
+	* caller has already checked that the thread is in its scope.
+	*
+	* @param sessionId - the transcript the question was submitted into.
 	* @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.
@@ -1808,10 +2116,11 @@ var CommentStore = class {
 	* @returns whether the comment existed.
 	*/
 	recordAsk(sessionId, id, requestId, turn, text) {
-		return this.patch((comment) => comment.sessionId === sessionId && comment.id === id, (comment) => ({
+		return this.patch((comment) => comment.id === id, (comment) => ({
 			...comment,
 			asks: [...comment.asks ?? [], {
 				requestId,
+				sessionId,
 				text,
 				...turn === void 0 ? {} : { turn }
 			}],
@@ -1822,13 +2131,16 @@ var CommentStore = class {
 	* 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.
+	*
+	* Matched by REQUEST ID alone: it is minted per submission and globally unique, so it names the
+	* question on its own — and a thread another seat wrote can hold a question asked from this seat,
+	* which the old `comment.sessionId === sessionId` guard would refuse to write down.
 	* @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) => ({
+	recordTurnForRequest(requestId, turn) {
+		return this.patch((comment) => hasAsk(comment, requestId, (ask) => ask.turn !== turn), (comment) => ({
 			...comment,
 			asks: (comment.asks ?? []).map((ask) => ask.requestId === requestId ? {
 				...ask,
@@ -1838,14 +2150,15 @@ var CommentStore = class {
 		}));
 	}
 	/**
-	* Record that the session dropped one question before a turn claimed it: nothing is
+	* Record that a 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.
+	*
+	* Matched by REQUEST ID alone, for the same reason as `recordTurnForRequest`.
 	* @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) => ({
+	markDroppedForRequest(requestId) {
+		return this.patch((comment) => hasAsk(comment, requestId, (ask) => ask.dropped !== true), (comment) => ({
 			...comment,
 			asks: (comment.asks ?? []).map((ask) => ask.requestId === requestId ? {
 				...ask,
@@ -1865,14 +2178,19 @@ var CommentStore = class {
 	* 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.
+	* Matched by TURN **within one transcript** (`askTranscript`), never by the thread's author: turn
+	* numbers are only unique inside a session, so two sessions can both have a turn 7, and a thread that
+	* holds questions from both would otherwise have one session's ending mark the other's questions
+	* over — the reader would be told a question was cut off while its answer was still coming.
+	* @param sessionId - the transcript 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) => ({
+		const endedHere = (ask, comment) => askTranscript(ask, comment) === sessionId && ask.turn === turn;
+		return this.patch((comment) => (comment.asks ?? []).some((ask) => endedHere(ask, comment) && ask.ended !== true), (comment) => ({
 			...comment,
-			asks: (comment.asks ?? []).map((ask) => ask.turn === turn ? {
+			asks: (comment.asks ?? []).map((ask) => endedHere(ask, comment) ? {
 				...ask,
 				ended: true
 			} : ask),
@@ -1929,7 +2247,12 @@ var CommentStore = class {
 	* 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.
+	*
+	* The write-set is the AUTHOR's own comments (`authoredBy`), never the wider read scope
+	* (`list`): a read spans the lineage, but a file must hold exactly the comments whose
+	* author it is named for — writing the scope's comments into one seat's file would
+	* duplicate every other seat's threads on disk and, on the next load, in memory.
+	* @param sessionId - the author whose file to rewrite.
 	*/
 	save(sessionId) {
 		const file = fileOf(this.root, sessionId);
@@ -1938,7 +2261,7 @@ var CommentStore = class {
 			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 comments = this.authoredBy(sessionId);
 		const task = async () => {
 			await writeJsonAtomic(file, {
 				version: COMMENT_FILE_VERSION,
@@ -2166,16 +2489,19 @@ var CommentAsker = class {
 	* 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 sessionId - the session the question is asked FROM: the prompt goes into it, so its
+	*   transcript is where the answer will appear.
 	* @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.
+	* @param inScope - which comment authors the caller's lineage covers, so a thread another seat
+	*   wrote can be asked from this one.
 	* @returns what the request did.
 	*/
-	async ask(sessionId, commentId, prompt, text, signal) {
+	async ask(sessionId, commentId, prompt, text, signal, inScope) {
 		const comment = this.comments.get(commentId);
-		if (comment === void 0 || comment.sessionId !== sessionId) return { outcome: "missing" };
+		if (comment === void 0 || !inScope(comment.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");
@@ -2205,7 +2531,7 @@ var CommentAsker = class {
 		} catch (error) {
 			const reason = rejectionText(error);
 			this.ctx.logger.warn(`diff-approval: asking a comment failed: ${reason}`);
-			this.comments.markDroppedForRequest(sessionId, requestId);
+			this.comments.markDroppedForRequest(requestId);
 			return {
 				outcome: "failed",
 				message: reason
@@ -2213,25 +2539,44 @@ var CommentAsker = class {
 		}
 	}
 	/**
-	* Every question of one session and what the transcript says about it, keyed by the
+	* One scope's questions, grouped by THE TRANSCRIPT each was submitted into.
+	*
+	* A lineage's threads may hold questions asked from several seats, and an answer lives in the
+	* transcript of the session that was asked — so the read is per transcript, not per thread. Grouping
+	* here (rather than reading each thread separately) is what keeps a poll to ONE log walk per
+	* transcript, however many threads asked there.
+	*
+	* The legacy case is why `askTranscript` exists: a question asked before the asking session was
+	* recorded has only the comment's own session to go on, which is where it went.
+	* @param visible - the comments this read may see (already scoped by the caller).
+	* @returns the request ids per transcript; empty when nothing was ever asked.
+	*/
+	answerGroups(visible) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const comment of visible) for (const ask of comment.asks ?? []) {
+			const transcript = askTranscript(ask, comment);
+			const ids = groups.get(transcript);
+			if (ids === void 0) groups.set(transcript, [ask.requestId]);
+			else ids.push(ask.requestId);
+		}
+		return groups;
+	}
+	/**
+	* Every question submitted into ONE transcript and what it says about them, 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.
+	* against). Derived from that session's 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 transcript to read.
+	* @param requestIds - the questions that were submitted into it.
+	* @param cache - this request's already-read logs, so the answer fold and the turn-end read
+	*   below share ONE walk of a log that can hold >100k events.
 	* @returns the read per question; empty when the session holds no questions.
 	*/
-	answers(sessionId) {
+	answersFor(sessionId, requestIds, cache) {
 		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;
-		}
+		const events = this.sessionEvents(sessionId, cache);
 		if (events === void 0) return {};
 		return answersIn(events, requestIds);
 	}
@@ -2244,16 +2589,12 @@ var CommentAsker = class {
 	* 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.
+	* @param sessionId - the transcript whose turns to check.
+	* @param cache - this request's already-read logs (see `answersFor`).
 	* @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;
-		}
+	endedTurns(sessionId, cache) {
+		const events = this.sessionEvents(sessionId, cache);
 		if (events === void 0) return [];
 		const turns = [];
 		for (const event of events) {
@@ -2272,11 +2613,24 @@ var CommentAsker = class {
 	* and `snapshotEvents` hands back a frozen, sequence-ordered copy of it, so walking it
 	* is a plain read that cannot disturb the session.
 	*
+	* The cache is per REQUEST, not per session: one list read asks this twice for every transcript
+	* (the answer fold and the turn-end read), and the copy is the expensive part of a long session's
+	* log. `has` rather than a truthy check, so "cannot be read" is cached as such instead of being
+	* asked again.
 	* @param sessionId - the session to read.
+	* @param cache - this request's already-read logs, when the caller is doing several reads.
 	* @returns its events, or undefined when no live session can be read.
 	*/
-	sessionEvents(sessionId) {
-		return this.ctx.sessions.get(sessionId)?.snapshotEvents?.();
+	sessionEvents(sessionId, cache) {
+		if (cache !== void 0 && cache.has(sessionId)) return cache.get(sessionId);
+		let events;
+		try {
+			events = this.ctx.sessions.get(sessionId)?.snapshotEvents?.();
+		} catch {
+			events = void 0;
+		}
+		cache?.set(sessionId, events);
+		return events;
 	}
 	/** The live agent for one session, or `undefined` when this host drives none. */
 	agentOf(sessionId) {
@@ -2300,7 +2654,7 @@ var CommentAsker = class {
 	* 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
+	* Called on every ask AND on every poll read (`answersFor`), 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.
 	*/
@@ -2329,11 +2683,11 @@ var CommentAsker = class {
 				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);
+				this.comments.recordTurnForRequest(requestId, turn);
 			});
 			listen("agent/inbox/discarded", (payload) => {
 				const requestId = requestIdOf(payload);
-				if (requestId !== void 0) this.comments.markDroppedForRequest(sessionId, requestId);
+				if (requestId !== void 0) this.comments.markDroppedForRequest(requestId);
 			});
 			listen("agent/turn-stopping", (payload) => {
 				const turn = payload.turn;
@@ -2611,6 +2965,9 @@ const ANNOTATE_SKILL = {
 - \`startLine\` / \`endLine\`：**现在**的行号（1 起，含两端；省略 \`endLine\` 就是一行）。先读文件再写号，别凭记忆。
 - \`note\`：卡片上写的话。要短——卡片是**按行**排版、行高按行算的（上限 1000 字符，超了会被拒）。讲流程时，把这一步的序号写在 note 的**最前面**（\`1. …\`、\`2. …\`）。
 - \`quote\`（可选，建议给）：你读到的那几行原文（换行连接）。文件在你读完之后又变了的话，会当场被拒并把现在的原文给你，避免批注挂在错误的行上。
+- \`category\`（可选）：**给"一类批注"起一个 id**。同一类（同一轮、同一主题、同一次讲解）每次调用都传**同一个** id，换成另一类就换一个 id。面板会按这个 id 给评论列表里的那条评论画一个**彩色圆点**，所以**同一类的批注是同一个颜色**，两类之间可以靠颜色区分。**不传 \`category\` 就完全不画圆点**——它是可选的，圆点只为"有类别"的批注而画。
+  - 颜色只有 12 种，id 是散列到颜色上的，所以**两个不同的 id 可能撞成同一个颜色**，那时这两类看起来一样：这不是"分了几类一目了然"，只是"同一类颜色一致"。想让人分得清，就**有意识地复用同一个 id**，不要给同一类换新 id。
+  - id 本身不解析：随便给（uuid 也行）。颜色由它算出来；你写的 id 只出现在圆点的 **\`title\` / \`aria-label\`** 里（鼠标悬停、或读屏软件），**不是屏幕上的文字**。会去掉两端空白；最多 64 个字符，超了**截断**（不会因此拒掉整条批注）。
 
 ## 讲流程就在正文开头写序号
 
@@ -2649,6 +3006,22 @@ const ANNOTATE_SKILL = {
 */
 const MAX_ANNOTATION_CHARS = 1e3;
 /**
+* The category id as it is stored: trimmed, and cut to {@link MAX_ANNOTATION_CATEGORY_CHARS}.
+*
+* TRUNCATED rather than refused: the id is only ever hashed into a colour and echoed in the mark's label,
+* so an over-long one still groups its annotations consistently — every call of that class is cut in the
+* same place — while refusing would fail an entire annotation over a cosmetic detail. Absent, empty and
+* whitespace-only all mean the same thing: no class, so no dot (see `CommentRecord.category`).
+*
+* @param value - the id the caller passed, if any.
+* @returns the id to store, or `undefined` when there is none.
+*/
+function normalizeCategory(value) {
+	const trimmed = value?.trim() ?? "";
+	if (trimmed === "") return void 0;
+	return trimmed.slice(0, 64);
+}
+/**
 * 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`).
 *
@@ -2751,6 +3124,7 @@ function annotateLines(request, existing) {
 		};
 	}
 	const now = request.now ?? Date.now();
+	const category = normalizeCategory(request.category);
 	return {
 		outcome: "annotated",
 		comment: {
@@ -2766,6 +3140,7 @@ function annotateLines(request, existing) {
 			createdAt: now,
 			updatedAt: now,
 			author: "agent",
+			...category === void 0 ? {} : { category },
 			...annotationQuote(lines, start, end)
 		}
 	};
@@ -2825,7 +3200,7 @@ 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.";
+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. Give every annotation of one kind the same `category` id, and a different id for another kind (one pass, one topic, one round of review): the panel paints a coloured round dot beside each of those comments from it, which is how one class of annotation is told from another. Omit `category` and no dot is drawn at all. 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.
 *
@@ -2861,6 +3236,10 @@ const ANNOTATE_TOOL_PARAMETERS = {
 		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."
+		},
+		category: {
+			type: "string",
+			description: "Optional class for this annotation. Pass the SAME short id for every annotation that belongs to one kind (one pass, one topic, one review round) and a DIFFERENT one for the next: the panel paints a coloured round dot beside these comments from it, so two classes can be told apart. OMIT this argument and no dot is drawn at all — it is optional, and the mark exists only for a class. Opaque: a uuid is fine, it is hashed for the colour and shown to the user in the mark's own label (hover, or a screen reader) as you wrote it. Trimmed, and an id longer than 64 characters is cut to 64 rather than refused."
 		}
 	}
 };
@@ -3018,7 +3397,8 @@ function annotateRun(deps) {
 			startLine: args.startLine,
 			endLine: args.endLine,
 			note: args.note,
-			quote: args.quote
+			quote: args.quote,
+			category: args.category
 		}, deps.commentsOf(sessionId));
 		if (result.outcome !== "annotated") {
 			deps.log?.(`annotate: ${refusalSummary(result)} (${entry.path})`);
@@ -3277,9 +3657,27 @@ function parseGitPorcelainZ(output) {
 * 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";
+/** The message a failed command carries; `runShell` puts the command's own stderr into it. */
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* git's wording for a path a revision does not carry, and ONLY that.
+*
+* Measured against git 2.x: `path 'x' does not exist in 'HEAD'`, and `Not a valid object name
+* HEAD:x` when HEAD is unborn (a repository with no commits yet — there every file is genuinely
+* new). A failure that is none of these — a corrupt object, a refused spawn, a timeout — is not
+* absence, and must never be read as one.
+*/
+const ABSENT_AT_REVISION = /does not exist in|exists on disk, but not in|not a valid object name|invalid object name|unknown revision|bad revision/i;
 /**
-* 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).
+* Read one file's content at a revision (`<rev>:<path>`), and say so when that revision has no such
+* path.
+*
+* The two answers must stay distinguishable. Absence is what makes a file a creation, and a
+* creation's revert DELETES the file — so reading a FAILED read as absence offers to delete a file
+* that is committed and fine. Only git's own words decide (see {@link ABSENT_AT_REVISION}); anything
+* else is thrown with the path named, because a reader can act on that and cannot act on a guess.
 *
 * 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.
@@ -3290,15 +3688,20 @@ const GIT_STATUS_COMMAND = "git -c status.renames=false status --porcelain=v1 -z
 * @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.
+* @returns the file's content at that revision, or `{ found: false }` when it has none.
+* @throws when the read failed for any reason other than absence.
 */
 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;
+		return {
+			found: true,
+			text: await runShell(shell, `git show ${revision}:${shq(rel)}`, root, signal, size + GIT_BLOB_STDOUT_SLACK)
+		};
+	} catch (error) {
+		if (ABSENT_AT_REVISION.test(errorMessage$1(error))) return { found: false };
+		throw new Error(`could not read ${rel} at ${revision}: ${errorMessage$1(error)}`);
 	}
 }
 /** Enumerate the workspace's local changes in a git checkout. */
@@ -3315,7 +3718,7 @@ async function gitChanges(input) {
 			const newText = await readText(absolute) ?? "";
 			changes.push({
 				path: absolute,
-				kind: "create",
+				earlierVersion: "none",
 				oldText: "",
 				newText
 			});
@@ -3323,12 +3726,12 @@ async function gitChanges(input) {
 		}
 		const baseline = await readGitBlob(root, "HEAD", rel, shell, signal);
 		const worktree = xy[1] ?? " ";
-		const oldText = baseline ?? "";
+		const oldText = baseline.found ? baseline.text : "";
 		const newText = worktree === "D" ? "" : await readText(absolute) ?? "";
 		if (oldText === "" && newText === "") continue;
 		changes.push({
 			path: absolute,
-			kind: baseline === void 0 ? "create" : "edit",
+			earlierVersion: baseline.found ? "file" : "none",
 			oldText,
 			newText
 		});
@@ -3353,17 +3756,17 @@ async function svnChanges(input) {
 		const absolute = resolve(root, rel);
 		if (!inScanScope(absolute, roots)) continue;
 		if (item === "modified" || item === "deleted") {
-			let oldText = "";
+			let oldText;
 			try {
 				oldText = await runShell(shell, `svn cat -r BASE ${shq(rel)}`, root, signal);
-			} catch {
-				oldText = "";
+			} catch (error) {
+				throw new Error(`could not read ${rel} at BASE: ${errorMessage$1(error)}`);
 			}
 			const newText = item === "deleted" ? "" : await readText(absolute) ?? "";
 			if (oldText === "" && newText === "") continue;
 			changes.push({
 				path: absolute,
-				kind: "edit",
+				earlierVersion: "file",
 				oldText,
 				newText
 			});
@@ -3371,7 +3774,7 @@ async function svnChanges(input) {
 			const newText = await readText(absolute) ?? "";
 			changes.push({
 				path: absolute,
-				kind: "create",
+				earlierVersion: "none",
 				oldText: "",
 				newText
 			});
@@ -3379,7 +3782,7 @@ async function svnChanges(input) {
 			const newText = await readText(absolute) ?? "";
 			changes.push({
 				path: absolute,
-				kind: "create",
+				earlierVersion: "none",
 				oldText: "",
 				newText
 			});
@@ -3424,13 +3827,13 @@ async function p4Changes(input) {
 		let oldText = "";
 		if (!created) try {
 			oldText = await runShell(shell, `p4 print -q ${shq(opened.depot)}#have`, root, signal);
-		} catch {
-			oldText = "";
+		} catch (error) {
+			throw new Error(`could not read ${opened.depot}#have: ${errorMessage$1(error)}`);
 		}
 		if (oldText === "" && newText === "") continue;
 		changes.push({
 			path: absolute,
-			kind: created ? "create" : "edit",
+			earlierVersion: created ? "none" : "file",
 			oldText,
 			newText
 		});
@@ -3451,6 +3854,229 @@ async function listVcsChanges(input) {
 		case "p4": return p4Changes(input);
 	}
 }
+/**
+* Read one file's BASELINE content — the version every branch above reads to build a change's
+* `oldText`: git's last commit (`HEAD`, when the scan could not see the change), svn's `BASE`, p4's
+* `#have`. The commands are the same ones those branches run, so a caller that needs one file's
+* pre-change content outside a scan (the per-file refresh's "was this committed?" check) does not
+* invent a second way to ask the same question — or a second set of failure modes to reason about.
+*
+* The two answers stay distinguishable, exactly as they do in a scan: a baseline that carries no
+* version of the path is {@link VcsBaseline} `none` (git is the only branch that can report it,
+* through {@link readGitBlob}'s own absence pattern), while a read that FAILED — a refused command,
+* a timeout, a missing client — throws, because "could not read" is not "there is nothing there".
+*
+* @param kind - the VCS to read.
+* @param root - the repository/checkout/client root, as {@link detectVcsRoot} found it.
+* @param absolutePath - the file's absolute path (inside the root's tree).
+* @param shell - the deployment's shell executor.
+* @param signal - the caller's abort signal.
+* @returns the baseline content, or `none` when the baseline has no version of the path.
+* @throws when the baseline read failed for any other reason.
+*/
+async function readVcsBaseline(kind, root, absolutePath, shell, signal) {
+	switch (kind) {
+		case "git": {
+			const blob = await readGitBlob(root, "HEAD", relative(root, resolve(absolutePath)).split(sep).join("/"), shell, signal);
+			return blob.found ? {
+				state: "file",
+				text: blob.text
+			} : { state: "none" };
+		}
+		case "svn": try {
+			return {
+				state: "file",
+				text: await runShell(shell, `svn cat -r BASE ${shq(absolutePath)}`, root, signal)
+			};
+		} catch (error) {
+			throw new Error(`could not read ${absolutePath} at BASE: ${errorMessage$1(error)}`);
+		}
+		case "p4": try {
+			return {
+				state: "file",
+				text: await runShell(shell, `p4 print -q ${shq(absolutePath)}#have`, root, signal)
+			};
+		} catch (error) {
+			throw new Error(`could not read ${absolutePath}#have: ${errorMessage$1(error)}`);
+		}
+	}
+}
+/**
+* Parse `major.minor.patch`, and NOTHING else.
+*
+* Deliberately strict, because the alternative is a bogus "newer": a pre-release
+* (`0.31.0-rc.1`), a range (`^0.31.0`), a dist-tag (`latest`) or a stray suffix all
+* answer `undefined`, and an unparsable side of a comparison is never allowed to look
+* newer. A leading `v` is tolerated because tags carry one.
+*
+* @param text - the candidate, from a registry document or a `package.json`.
+* @returns the three numbers, or `undefined` when the text is not exactly that shape.
+*/
+function parseVersion(text) {
+	if (typeof text !== "string") return void 0;
+	const match = /^v?(\d+)\.(\d+)\.(\d+)$/u.exec(text.trim());
+	if (match === null) return void 0;
+	const parts = [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+	if (parts.some((part) => !Number.isSafeInteger(part))) return void 0;
+	return parts;
+}
+/**
+* Is `latest` strictly newer than `current`?
+*
+* Strictly: equal versions are NOT newer, and neither side parsing means NOT newer —
+* the rule the code above exists to make safe. Comparison is component-wise on the
+* three numbers, so `0.9.0` precedes `0.10.0` (string comparison would get that wrong).
+*
+* @param latest - the published version.
+* @param current - the installed version.
+* @returns whether a notice is warranted.
+*/
+function isNewerVersion(latest, current) {
+	const next = parseVersion(latest);
+	const here = parseVersion(current);
+	if (next === void 0 || here === void 0) return false;
+	return compareVersions(next, here) > 0;
+}
+/**
+* Compare two already-parsed versions.
+*
+* Component-wise, because a string comparison gets `0.9.0` vs `0.10.0` wrong — the reason both
+* callers go through here rather than comparing something textual.
+*
+* @param left - one version.
+* @param right - the other.
+* @returns negative, zero or positive, as a comparator should.
+*/
+function compareVersions(left, right) {
+	for (let index = 0; index < 3; index += 1) if (left[index] !== right[index]) return left[index] - right[index];
+	return 0;
+}
+/**
+* The version installed in this package, read from the `package.json` beside the built
+* `lib/` — the only authority on what the reader is running, and the value the registry
+* answer is compared against.
+*
+* Resolved relative to this module, so it holds for the bundled `lib/index.js`
+* (`../package.json` is the package root) and for the source under test (`../package.json`
+* is the repository root) alike.
+*
+* @param manifestUrl - the manifest to read; the package's own `package.json` unless a caller
+*   says otherwise. It is a parameter because a test runner can serve modules over a non-file
+*   URL, where the default cannot be resolved — the production path is the default, and the
+*   end-to-end case is what proves the default itself.
+* @returns the version, or `undefined` when the file is missing or has none.
+*/
+async function installedVersion(manifestUrl = new URL("../package.json", import.meta.url)) {
+	try {
+		const text = await readFile(manifestUrl, "utf8");
+		const document = JSON.parse(text);
+		return typeof document.version === "string" && document.version.length > 0 ? document.version : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Ask the registry for the published version.
+*
+* @param probe - where to ask and how; every field defaults (see {@link UpdateProbe}).
+* @returns the version, or `undefined` on any failure — including an answer that is not
+*   a version, which must never become a notice.
+*/
+async function fetchLatestVersion(probe = {}) {
+	const body = await fetchText(probe.registryUrl ?? "https://registry.npmjs.org/dsh-diff-approval/latest", probe);
+	if (body === void 0) return void 0;
+	try {
+		const document = JSON.parse(body);
+		return parseVersion(document.version) === void 0 ? void 0 : String(document.version);
+	} catch {
+		return;
+	}
+}
+/**
+* Build the answer behind the `update-check` endpoint: one function a host calls per request.
+*
+* WHAT IS CACHED, AND FOR HOW LONG — the whole point of this factory:
+*
+* - The REMOTE answer (the registry's latest version) is cached, because that is the network cost. It is held
+*   for {@link UPDATE_CACHE_TTL_MS} and then fetched again, so a release published while the host is running
+*   still reaches the reader without a restart. A FAILED fetch is not cached at all: remembering a failure
+*   would hide the notice for the whole TTL after one offline moment, and there is no network cost to save.
+* - The INSTALLED version is read from the manifest on EVERY call. It is a file read, not a request, and it is
+*   the side that changes when the reader upgrades — so a verdict computed before that upgrade must never be
+*   replayed. Caching it was a real defect: a host that answered while an older version was installed kept
+*   announcing "a newer release" to every page until it was restarted.
+*
+* `newer` is therefore decided afresh on every call, from today's manifest against the cached registry answer.
+* NEVER THROWS: every failure — no manifest, an unreachable registry, a nonsense answer — ends as "nothing to
+* say" (`newer: false`), so a network problem can never become an error in the reader's status bar.
+*
+* @param options - where to read and how; every field defaults (see {@link UpdateCheckOptions}).
+* @returns the check itself; call it as often as you like.
+*/
+function createUpdateCheck(options = {}) {
+	const ttl = options.ttlMs ?? 6e5;
+	const now = options.now ?? (() => Date.now());
+	const probe = {
+		...options.registryUrl === void 0 ? {} : { registryUrl: options.registryUrl },
+		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+		...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
+	};
+	const manifestUrl = options.manifestUrl ?? new URL("../package.json", import.meta.url);
+	/** The cached REMOTE answer, with the moment it was fetched. */
+	let remote;
+	return async () => {
+		const current = await installedVersion(manifestUrl);
+		if (current === void 0) return {
+			current: "",
+			newer: false
+		};
+		const at = now();
+		if (remote === void 0 || at - remote.at >= ttl) {
+			const fetched = await fetchLatestVersion(probe);
+			if (fetched !== void 0) remote = {
+				version: fetched,
+				at
+			};
+		}
+		const latest = remote?.version;
+		if (latest === void 0 || !isNewerVersion(latest, current)) return {
+			current,
+			...latest === void 0 ? {} : { latest },
+			newer: false
+		};
+		return {
+			current,
+			latest,
+			newer: true
+		};
+	};
+}
+/** One `GET`, with the module's timeout, mapping every failure to `undefined`. */
+async function fetchText(url, probe) {
+	const implementation = probe.fetchImpl ?? globalThis.fetch;
+	if (implementation === void 0) return void 0;
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort();
+	}, probe.timeoutMs ?? 3e3);
+	timer.unref?.();
+	try {
+		const response = await implementation(url, {
+			signal: controller.signal,
+			headers: { accept: "application/json, text/plain, */*" }
+		});
+		if (!response.ok) return void 0;
+		return await response.text();
+	} catch {
+		return;
+	} finally {
+		clearTimeout(timer);
+	}
+}
 //#endregion
 //#region lib/types/index.js
 /**
@@ -3648,6 +4274,29 @@ function normalizeEol(text) {
 function contentEqual(a, b) {
 	return contentLinesOf(normalizeEol(a)).join("\n") === contentLinesOf(normalizeEol(b)).join("\n");
 }
+/**
+* Whether one entry's change is COMMITTED: its content on disk equals its content at the VCS
+* baseline.
+*
+* Read off the same helpers a scan uses — {@link readVcsBaseline} runs the very commands
+* `listVcsChanges` runs to build a change's `oldText` (git `HEAD`, svn `BASE`, p4 `#have`) — and
+* compared with {@link contentEqual}, the tolerance the whole-file diff already uses. A baseline
+* that carries no version of the path (a file the scan cannot see because it was never
+* committed-and-modified) is NOT "committed": it answers false, exactly like a baseline whose
+* content differs. Anything that failed to read throws, for the caller to read as "not proven".
+*
+* @param root - the detected VCS root.
+* @param kind - the VCS to read the baseline from.
+* @param path - the entry's absolute file path.
+* @param shell - the deployment's shell executor.
+* @param signal - the caller's abort signal.
+* @returns whether the on-disk content is the baseline's.
+*/
+async function committedChange(root, kind, path, shell, signal) {
+	const baseline = await readVcsBaseline(kind, root, path, shell, signal);
+	if (baseline.state !== "file") return false;
+	return contentEqual(await readFile(path, "utf8"), baseline.text);
+}
 /** Re-encode `text`'s line endings to `eol` (its content is unchanged). */
 function reencodeEol(text, eol) {
 	const normalized = normalizeEol(text);
@@ -3667,7 +4316,7 @@ function editOutcomeOf(value) {
 	if (typeof before !== "string" || typeof after !== "string") return void 0;
 	return {
 		path,
-		kind: "edit",
+		earlierVersion: "file",
 		oldText: before,
 		newText: after
 	};
@@ -3675,10 +4324,11 @@ function editOutcomeOf(value) {
 /**
 * Narrow a successful `write` result value to an operation outcome. The write
 * tool's output schema declares `{ path, operation, before, after }`;
-* `operation: 'create'` becomes a `create` entry (revert removes the file),
-* `operation: 'update'` becomes an `edit` entry. An update whose `before` is
-* null carried no contextual basis, so it is skipped rather than tracked as
-* an un-revertable overwrite.
+* `operation: 'create'` becomes an entry with `earlierVersion: 'none'` (there is
+* no earlier version, so the whole-file action removes the file),
+* `operation: 'update'` one with `earlierVersion: 'file'`. An update whose
+* `before` is null carried no contextual basis, so it is skipped rather than
+* tracked as an un-revertable overwrite.
 * @param value - the successful result's JSON value.
 * @returns the outcome, or `undefined` when the value is not a trackable write.
 */
@@ -3690,14 +4340,14 @@ function writeOutcomeOf(value) {
 	if (typeof after !== "string") return void 0;
 	if (operation === "create") return {
 		path,
-		kind: "create",
+		earlierVersion: "none",
 		oldText: "",
 		newText: after
 	};
 	if (typeof before !== "string") return void 0;
 	return {
 		path,
-		kind: "edit",
+		earlierVersion: "file",
 		oldText: before,
 		newText: after
 	};
@@ -3802,6 +4452,31 @@ function rpcError(message) {
 		}
 	};
 }
+/** The process's one update check: see {@link checkForUpdate}. */
+let updateCheck;
+/**
+* Whether a newer release of this package is published — the answer behind the channel's
+* `update-check` endpoint.
+*
+* ONE CHECK PER PROCESS, and what it caches is the REMOTE half only (`createUpdateCheck` in `version.ts`):
+* the registry's latest version, held for a short TTL, while the INSTALLED version is read from the manifest
+* on every call. So an upgrade, a reinstall or a downgrade under a running host is reflected immediately,
+* and a release published while the host runs appears within the TTL rather than at the next restart.
+*
+* NEVER THROWS and never rejects: the endpoint must not be able to turn a network
+* problem into an error in the reader's status bar. A failure to read the version at
+* all (a stripped install with no `package.json`) answers `newer: false`.
+*
+* The registry URL can be overridden by environment — `DSH_DIFF_APPROVAL_UPDATE_REGISTRY_URL` — because
+* the end-to-end case must not depend on the public internet. It is read HERE, on the first call, which is
+* after a test has set it and before the host answers anything. It is the ONLY such override.
+*
+* @returns what the panel needs to decide about its notice.
+*/
+function checkForUpdate() {
+	updateCheck ??= createUpdateCheck({ ...process.env.DSH_DIFF_APPROVAL_UPDATE_REGISTRY_URL === void 0 ? {} : { registryUrl: process.env.DSH_DIFF_APPROVAL_UPDATE_REGISTRY_URL } });
+	return updateCheck();
+}
 /**
 * Mount the pending-edit review surface.
 * @param ctx - Cordis context carrying the filesystem, connection, and workspace registry services.
@@ -3845,12 +4520,14 @@ function apply(ctx, config) {
 	* 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.
+	* @param listed - the comments this read is handing over: the caller took ONE scoped list and reuses it
+	*   here, because resolving lines is derived from a record's own fields (`quote`, `anchor`, `entryId`),
+	*   none of which a fold touches — so the pre-fold and post-fold lists resolve identically.
 	* @returns the resolved lines per comment id; comments that do not resolve are left out.
 	*/
-	function resolvedCommentLines(sessionId) {
+	function resolvedCommentLines(listed) {
 		const resolved = {};
-		for (const comment of comments.list(sessionId)) {
+		for (const comment of listed) {
 			const entry = store.get(comment.entryId);
 			if (entry === void 0) continue;
 			const version = store.contentVersion(comment.entryId);
@@ -3909,10 +4586,16 @@ function apply(ctx, config) {
 	};
 	registerAnnotateTool(ctx, {
 		ready: ensureLoaded,
-		entriesOf: (sessionId) => store.list(sessionId),
-		commentsOf: (sessionId) => comments.list(sessionId),
+		entriesOf: (sessionId) => {
+			const view = lineageView();
+			return store.all().filter((entry) => view.sees(sessionId, entry));
+		},
+		commentsOf: (sessionId) => comments.list(commentScopeOf(sessionId, lineageView())),
 		addComment: (record) => {
-			comments.add(record);
+			comments.add(record.author === "agent" ? {
+				...record,
+				unseen: true
+			} : record);
 		},
 		listFile: (sessionId, asked, signal) => listFileForAnnotation(sessionId, asked, signal),
 		log: (message) => ctx.logger.info(`diff-approval: ${message}`)
@@ -3954,11 +4637,12 @@ function apply(ctx, config) {
 			id: absolute,
 			sessionId,
 			path: absolute,
-			kind: "edit",
+			earlierVersion: "file",
 			oldText: content,
 			newText: content,
 			updatedAt: Date.now(),
-			sessionIds: [sessionId]
+			sessionIds: [sessionId],
+			unseen: true
 		}], true);
 		const landed = store.list(sessionId).find((entry) => pathIdentity(entry.path) === pathIdentity(absolute));
 		return landed === void 0 ? { kind: "missing" } : {
@@ -3987,28 +4671,30 @@ function apply(ctx, config) {
 		const removed = store.remove(id);
 		comments.removeForEntry(id);
 		forgetCommentLinesForEntry(id);
+		liveObservations.delete(id);
 		return removed;
 	}
 	/** Pre-write bases captured at the intent seams, keyed by the tool call id. */
 	const editorIntents = /* @__PURE__ */ new Map();
 	/**
-	* Snapshot one str_replace_editor mutation's basis at its intent seam. A
-	* `create` has an empty basis; an edit reads the pre-write content. Any
-	* failure tracks nothing — the settle-side pairing then sees no basis.
+	* Snapshot one str_replace_editor mutation's basis at its intent seam. A file
+	* creation has no earlier version, so its basis is empty; an edit reads the
+	* pre-write content. Any failure tracks nothing — the settle-side pairing then
+	* sees no basis.
 	* @param target - the resolved target about to be written.
 	* @param actor - the tool execution running the mutation.
-	* @param kind - whether the mutation creates or edits the file.
+	* @param earlierVersion - whether the mutation creates the file (`'none'`: no earlier version) or edits it (`'file'`).
 	*/
-	async function stashEditorIntent(target, actor, kind) {
+	async function stashEditorIntent(target, actor, earlierVersion) {
 		const shaped = actorOf(actor);
 		if (shaped === void 0 || shaped.name !== "str_replace_editor") return;
 		if (typeof shaped.callId !== "string") return;
 		const sessionId = sessionOfAgent(shaped.agent);
 		if (sessionId === void 0) return;
-		if (kind === "create") {
+		if (earlierVersion === "none") {
 			editorIntents.set(shaped.callId, {
 				target,
-				kind,
+				earlierVersion,
 				before: "",
 				sessionId
 			});
@@ -4018,7 +4704,7 @@ function apply(ctx, config) {
 			const before = await ctx.fs.readText(target, void 0) ?? "";
 			editorIntents.set(shaped.callId, {
 				target,
-				kind,
+				earlierVersion,
 				before,
 				sessionId
 			});
@@ -4037,29 +4723,43 @@ function apply(ctx, config) {
 		if (basis === void 0 || basis.sessionId === void 0 || result.isError) return;
 		const argumentsValue = exec.arguments;
 		const command = typeof argumentsValue === "object" && argumentsValue !== null ? argumentsValue.command : void 0;
-		if (!(basis.kind === "create" ? command === "create" : command === "str_replace" || command === "insert")) return;
+		if (!(basis.earlierVersion === "none" ? command === "create" : command === "str_replace" || command === "insert")) return;
 		let after;
 		try {
 			after = await ctx.fs.readText(basis.target, void 0) ?? "";
 		} catch {
 			return;
 		}
-		if (basis.kind === "edit" && after === basis.before) return;
+		if (basis.earlierVersion === "file" && after === basis.before) return;
 		const sessionId = basis.sessionId;
 		const path = basis.target.displayPath;
 		const entry = {
 			id: path,
 			sessionId,
 			path,
-			kind: basis.kind,
+			earlierVersion: basis.earlierVersion,
 			oldText: basis.before,
 			newText: after,
 			updatedAt: Date.now(),
-			sessionIds: [sessionId]
+			sessionIds: [sessionId],
+			lineage: lineageOf(sessionId, exec.agent),
+			unseen: true
 		};
 		await ensureLoaded();
 		if (store.fold(entry)) persistSession();
 	}
+	/**
+	* What was last READ from one tracked path, and the freshness token that read was taken at.
+	*
+	* `ctx.fs.stat` returns no `mtimeMs` (see `FsStat`): its freshness signal is `version`, an opaque token
+	* the backend documents as "the freshness token a write/edit guards against" and derives from the file's
+	* identity and times — the local backend builds it as `dev:ino:size:mtimeNs:ctimeNs`, so it moves when
+	* the size or either timestamp does, which is exactly the `mtimeMs`+`size` signal wanted here. `size` is
+	* carried beside it as a second, plain-text field.
+	*
+	* In memory only, one entry per tracked path: a restart has read nothing, so it observes afresh.
+	*/
+	const liveObservations = /* @__PURE__ */ new Map();
 	/** The stable `FsError.code`, when the thrown value carries one. */
 	function fsErrorCodeOf(error) {
 		if (typeof error !== "object" || error === null) return void 0;
@@ -4067,13 +4767,16 @@ function apply(ctx, config) {
 		return typeof code === "string" ? code : void 0;
 	}
 	/**
-	* Read one path's live state. The only existence test is `stat`: it returns
-	* `undefined` for an absent target (gone), so a deleted file never falls into
-	* the unreadable bucket. A file that exists but cannot be read is `unavailable`.
+	* Ask the backend where one tracked path is and what it is, reading NOTHING.
+	*
+	* This is the whole liveness test, shared by the full read (`liveStateOf`) and the light count
+	* (`list-count`): `resolve` + `stat`, with `undefined` from `stat` meaning the target is absent, and a
+	* thrown `FS_NOT_FOUND` meaning the same one step earlier. `version`/`size` come back as `undefined` when
+	* the backend does not report them, which is what tells `liveStateOf` it has no freshness evidence.
 	* @param path - backend display path to probe through `ctx.fs`.
-	* @returns the live state.
+	* @returns what the backend says, and the target a caller may then read.
 	*/
-	async function liveStateOf(path) {
+	async function probePath(path) {
 		let target;
 		try {
 			target = await ctx.fs.resolve(path, {});
@@ -4087,12 +4790,55 @@ function apply(ctx, config) {
 			return fsErrorCodeOf(error) === "FS_NOT_FOUND" ? { kind: "deleted" } : { kind: "unavailable" };
 		}
 		if (info === void 0) return { kind: "deleted" };
+		return {
+			kind: "present",
+			target,
+			version: typeof info.version === "string" && info.version.length > 0 ? info.version : void 0,
+			size: typeof info.size === "number" ? info.size : void 0
+		};
+	}
+	/**
+	* Read one path's live state. The only existence test is `stat`: it returns
+	* `undefined` for an absent target (gone), so a deleted file never falls into
+	* the unreadable bucket. A file that exists but cannot be read is `unavailable`.
+	*
+	* The CONTENT is not re-read when the backend's own freshness evidence says the file has not moved since
+	* the last observation: an identical `version` AND an identical numeric `size`, both reported. The stat
+	* still runs — it is the cheap half, and it is what notices a file that has gone — so a deleted file is
+	* still `deleted`, a moved one is read again, and `diverged`/`missing` are computed from real content
+	* either way. The skip needs BOTH fields: a stat that reports no size is a weaker observation than the
+	* contract allows, so it falls back to reading rather than trusting a token alone.
+	* @param path - backend display path to probe through `ctx.fs`.
+	* @returns the live state.
+	*/
+	async function liveStateOf(path) {
+		const probe = await probePath(path);
+		if (probe.kind !== "present") {
+			liveObservations.delete(path);
+			return probe;
+		}
+		const { target, version, size } = probe;
+		const trustable = version !== void 0 && size !== void 0;
+		if (trustable) {
+			const observed = liveObservations.get(path);
+			if (observed !== void 0 && observed.version === version && observed.size === size) return {
+				kind: "present",
+				content: observed.content
+			};
+		}
 		try {
+			const content = await ctx.fs.readText(target, void 0);
+			if (trustable) liveObservations.set(path, {
+				version,
+				size,
+				content
+			});
 			return {
 				kind: "present",
-				content: await ctx.fs.readText(target, void 0)
+				content
 			};
 		} catch (error) {
+			liveObservations.delete(path);
 			return fsErrorCodeOf(error) === "FS_NOT_FOUND" ? { kind: "deleted" } : { kind: "unavailable" };
 		}
 	}
@@ -4124,12 +4870,17 @@ function apply(ctx, config) {
 	* list and has its undo/redo records dropped, and externally changed content
 	* is adopted as the new baseline with its own checkpoint.
 	* @param sessionId - the session being listed (its session-scoped view).
+	* @param view - the request's lineage view: the caller builds it once and hands it here, because the
+	*   list read needs the same view for the comment scope, the answer fold and the undo keys, and a
+	*   second `lineageView()` would walk the store again for nothing.
+	* @param entries - that request's ONE `store.all()` snapshot (see `lineageView`).
 	* @returns the listed entries plus whether an external change cleared redo.
 	*/
-	async function listWithState(sessionId) {
+	async function listWithState(sessionId, view, entries) {
 		const listed = [];
 		let redoCleared = false;
-		for (const entry of store.list(sessionId)) {
+		for (const entry of entries) {
+			if (!view.sees(sessionId, entry)) continue;
 			const live = await liveStateOf(entry.path);
 			if (live.kind === "deleted") {
 				const checkpoint = droppingComments({
@@ -4144,7 +4895,7 @@ function apply(ctx, config) {
 					path: entry.path,
 					entry: void 0,
 					fileText: void 0
-				});
+				}, view);
 				persistSession();
 				continue;
 			}
@@ -4162,6 +4913,7 @@ function apply(ctx, config) {
 				const beforeText = entry.newText;
 				const redoWasPresent = redoStackOf(sessionId).length > 0;
 				store.update(entry.path, { newText: content });
+				store.markUnseen(entry.path);
 				pushUndo(sessionId, {
 					id: entry.path,
 					path: entry.path,
@@ -4176,7 +4928,7 @@ function apply(ctx, config) {
 						updatedAt: Date.now()
 					},
 					fileText: content
-				});
+				}, view);
 				persistSession();
 				if (redoWasPresent) redoCleared = true;
 			}
@@ -4184,10 +4936,16 @@ function apply(ctx, config) {
 				missing: false,
 				diverged: hasContent ? content !== adopted : true
 			};
+			const viaLineage = ownersOf(entry).includes(sessionId) ? void 0 : true;
+			const hasChildContribution = ownersOf(entry).some((owner) => owner !== sessionId && view.sameRoot(owner, sessionId));
+			const lineageDirection = view.directionOf(sessionId, entry);
 			listed.push({
 				...entry,
 				newText: adopted,
-				...state
+				...state,
+				viaLineage,
+				hasChildContribution,
+				lineageDirection
 			});
 		}
 		return {
@@ -4217,7 +4975,7 @@ function apply(ctx, config) {
 			changedPaths.push(entry.path);
 		}
 		if (folded === 0) return 0;
-		persistSession(true);
+		await persistSession(true);
 		const after = new Map(store.list(sessionId).map((entry) => [entry.path, entry]));
 		const batchBefore = [];
 		const batchAfter = [];
@@ -4326,6 +5084,47 @@ function apply(ctx, config) {
 		for (const workspace of ctx.workspaceRegistry.list()) if (workspace.sessionIds.includes(sessionId)) return workspace;
 	}
 	/**
+	* The identity one session's workspace is compared by, or `undefined` when this
+	* deployment does not account the session.
+	*
+	* The merged view needs it because the pending list is NOT scoped by workspace: the store is one map
+	* keyed by absolute path (`pending.ts`) persisted to one `pending.json` under the storage root
+	* (`persist.ts`), and that root comes from the plugin's `storageDir` alone — the `workspaces/`
+	* component of the default path is the LEGACY per-workspace layout whose files are folded in and
+	* deleted on load. Nothing else in the list path consults the workspace, so a row recorded by a
+	* session in another one would otherwise be listed under this session's view.
+	*
+	* `resolve` folds separators and `.`/`..`; Windows additionally compares case-insensitively, the same
+	* way `withinSandboxRoot` and the backend's own containment do (`C:\Repo` and `c:\repo` are one
+	* directory there). An ABSENT workspace, or one the registry records with no path, answers
+	* `undefined` — "not known", never a guess: the caller keeps the pre-workspace behaviour for it
+	* rather than refusing a row it cannot show to be elsewhere.
+	* @param sessionId - the session whose workspace is wanted.
+	* @returns the comparison key, or `undefined` when it is not known.
+	*/
+	function workspaceKeyOf(sessionId) {
+		const path = workspaceOf(sessionId)?.path;
+		if (typeof path !== "string" || path.length === 0) return void 0;
+		const resolved = resolve(path);
+		return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	}
+	/**
+	* Whether two workspaces, already reduced to comparison keys by {@link workspaceKeyOf}, are the same
+	* one as far as this deployment can say.
+	*
+	* TRUE when either side is unknown, which is the whole point: an unknown workspace must not turn into
+	* a refusal. The pending list is not scoped by workspace (see `workspaceKeyOf`), so a session the
+	* registry does not account — a memory-only session, a row from a host that named no workspace, a
+	* deployment whose registry the plugin cannot read — would otherwise lose rows it has always shown.
+	* The check is for the case this code can actually see: two KNOWN roots that differ.
+	* @param left - one session's key, or `undefined` when unknown.
+	* @param right - the other's.
+	* @returns whether they can be shown to share a workspace.
+	*/
+	function sameWorkspaceKey(left, right) {
+		return left === void 0 || right === void 0 || left === right;
+	}
+	/**
 	* Resolve the file-sandbox policy for one session's Revert write, or
 	* undefined when no confining backend is mounted. A live session carries
 	* its workspace root through `ctx.sessions`; a persisted entry from a
@@ -4346,6 +5145,326 @@ function apply(ctx, config) {
 		};
 	}
 	/**
+	* The session header entry lineage is read from.
+	*
+	* Two routes, in the order a capture can answer them. The live one is the tool execution's own agent:
+	* `Agent` is AUGMENTED at run time with `session` (dsh-agent's `runtime-types`), and the DSH's own
+	* bundled plugins read exactly that on a `tools/*` execution — `dsh-tool-present` uses
+	* `exec.agent.session.header.cwd` and `dsh-experimental-agent-team` reads
+	* `agent.session.header.parentSession` for precisely the lineage question this records. `Agent` is typed
+	* `{ id }` in the types this package compiles against (the augmentation is not among them), so the field
+	* is read structurally — the same way `sessionOfAgent` reads `id` off the same object.
+	*
+	* The fallback is this plugin's own session registry, which `sandboxPolicyOf` already consults
+	* (`ctx.sessions.get(id)`); it is what answers when the agent carries no `session`, and it is also the
+	* only route at a capture site that has no execution in hand (the editor-intent seam, version control,
+	* a hand-added path). It is read through `ctx.get`, the way this file reads every optional service
+	* (`sandboxPolicy`, `shell`): the capture must never fail because the lineage could not be asked for,
+	* and a context that was never handed a session service throws on the plain property instead.
+	* @param sessionId - the session whose header is wanted.
+	* @param agent - the live agent of a tool execution, when the caller has one.
+	* @returns the header, or `undefined` when neither route has one.
+	*/
+	function headerOf(sessionId, agent) {
+		if (typeof agent === "object" && agent !== null) {
+			const session = agent.session;
+			if (typeof session === "object" && session !== null) {
+				const header = session.header;
+				if (typeof header === "object" && header !== null) return header;
+			}
+		}
+		return sessionRegistry()?.get(sessionId)?.header;
+	}
+	/**
+	* The lineage one entry records for its session, read off that session's own header.
+	*
+	* Every part is taken on its own and only when it is there, and NO lineage is recorded when the header
+	* held none of it. Absence is the honest value: an ordinary root session has no parent by design, and a
+	* host older than these header fields reports none of them — while a merged view has to be able to tell
+	* "this session is a root" from "this host could not say", and guessing a root would file a session
+	* under the wrong one.
+	* @param sessionId - the session the entry belongs to.
+	* @param agent - the live agent, when the capture has one (see `headerOf`).
+	* @returns the lineage to store, or `undefined` when the header named none of it.
+	*/
+	function lineageOf(sessionId, agent) {
+		const header = headerOf(sessionId, agent);
+		if (header === void 0) return void 0;
+		const parent = header.parentSession;
+		const depth = header.delegationDepth;
+		const lineage = {
+			parentSessionId: typeof parent === "string" && parent.length > 0 ? SessionId(parent) : void 0,
+			origin: typeof header.origin === "string" && header.origin.length > 0 ? header.origin : void 0,
+			delegationDepth: typeof depth === "number" && Number.isFinite(depth) ? depth : void 0,
+			cwd: typeof header.cwd === "string" && header.cwd.length > 0 ? header.cwd : void 0
+		};
+		return lineage.parentSessionId !== void 0 || lineage.origin !== void 0 || lineage.delegationDepth !== void 0 || lineage.cwd !== void 0 ? lineage : void 0;
+	}
+	/** The session registry, read the way this file reads every optional service (see `headerOf`). */
+	function sessionRegistry() {
+		return ctx.get("sessions");
+	}
+	/** The most lineage hops one walk will take: a bound, not a depth anyone should reach. */
+	const MAX_LINEAGE_DEPTH = 16;
+	/** Every session that touched an entry (its own fallback, the way the store reads an old row).
+	*
+	*  PROVENANCE, and the merge's basis: it is who WROTE the row, which is what the row's mark and its
+	*  `viaLineage` flag are made of. It is deliberately NOT the write policy any more — an action's write
+	*  runs under the REQUESTING session (see `DiffApprovalUndoPair.policySession` and the
+	*  `revertEntryContent` call sites), so nothing here decides who may write.
+	*/
+	function ownersOf(entry) {
+		return Array.isArray(entry.sessionIds) && entry.sessionIds.length > 0 ? entry.sessionIds : [entry.sessionId];
+	}
+	/**
+	* What one session is known by when a lineage is walked: the lineage STEP 1 recorded for it, and
+	* otherwise the live header.
+	*
+	* Recorded first is deliberate: it is what the row itself says, it survives a session that is no longer
+	* live, and it is the same answer the entry carries — so the walk and the row cannot disagree. The
+	* registry is the fallback for a session that recorded nothing (a row written before this step, or a
+	* session whose entries have all been settled away).
+	*
+	* `subagent` is the only field the walk trusts for a LINK: `parentSession` alone is not one. The header
+	* documents it as "the session this one was forked from (seed lineage)", so a host fork or a seeded
+	* continuation carries it while being an INDEPENDENT ROOT — the Team package reads exactly that
+	* distinction (`dsh-experimental-agent-team/lib/types/roster.js:76-81`: "Ordinary host forks are
+	* independent roots"). `origin: 'subagent'` is the header's own marker for a session "created as a
+	* subagent child", and the one function that builds a child's meta sets it together with `parentSession`
+	* and `delegationDepth` (`dsh-subagent/lib/types/child-agent.js:111-125`).
+	* @param sessionId - the session being asked about.
+	* @param recorded - the lineages step 1 recorded, read once per request.
+	* @returns whether the session is a subagent child, and the parent it names when it is.
+	*/
+	function knownLineageOf(sessionId, recorded) {
+		const entry = recorded.get(sessionId);
+		if (entry !== void 0) return {
+			parent: entry.parentSessionId,
+			subagent: entry.origin === "subagent"
+		};
+		const header = sessionRegistry()?.get(sessionId)?.header;
+		const parent = header?.parentSession;
+		return {
+			parent: typeof parent === "string" && parent.length > 0 ? SessionId(parent) : void 0,
+			subagent: header?.origin === "subagent"
+		};
+	}
+	/**
+	* The lineage view one request is answered from — which sessions' entries the requester may SEE, and
+	* therefore act on.
+	*
+	* The rule is ROOT-EQUAL **AND SAME-WORKSPACE**: an entry is visible when any session that touched it
+	* walks to the same lineage root as the requester AND can be shown to sit in the requester's workspace.
+	* Walking is `knownLineageOf` links only, so a teammate's rows appear in the lead's list (both walk to
+	* the lead) and the lead's appear in the teammate's — while a host fork, which names a parent but is not
+	* a subagent child, stays an independent root and shares nothing.
+	*
+	* The workspace half is not redundant with the lineage half, because NOTHING ELSE IN THE LIST PATH
+	* SCOPES BY WORKSPACE: the store is one map keyed by absolute path persisted to one `pending.json` under
+	* the storage root (`pending.ts`, `persist.ts` — the `workspaces/` component of the default path is the
+	* legacy per-workspace layout, folded in and deleted on load). So without this a row recorded by a
+	* session in ANOTHER workspace would be listed here whenever the two share a lineage root — which is a
+	* real shape: this view merges every subagent child (see the KNOWN LIMIT below), and the harness's
+	* out-of-process shape lets a child run under a configured `cwd` of its own, its cwd being documented as
+	* the child's "workspace identity" (`dsh-subagent/lib/types/out-of-process.js`:
+	* `resolveChildCwd`/`assertUsableCwd`). An in-process child copies its parent's cwd verbatim
+	* (`…/child-agent.js:childSessionMeta`), so the two agree there; this rule is what makes the plugin's
+	* answer independent of which of those two shapes it is handed.
+	*
+	* A session the registry does not account is NOT refused: `sameWorkspace` answers true when either
+	* side's workspace is unknown, so an unaccounted or memory-only session keeps exactly the view it had
+	* before this term existed. UNKNOWN DEGRADES TO SELF on the lineage half and TO THE OLD ANSWER here —
+	* never to a guess, and never to a refusal the reader cannot see the reason for.
+	*
+	* UNKNOWN DEGRADES TO SELF, never to a guess: with no recorded lineage and no header facts every
+	* session is its own root, so only the requester matches — byte-for-byte today's behaviour. A cycle
+	* (which no shell should produce) stops at the first repeat, and the walk is bounded by
+	* {@link MAX_LINEAGE_DEPTH}.
+	*
+	* TWO THINGS A MERGED VIEW DOES NOT MERGE, so the next reader does not expect them:
+	* comments stay per-session (`comments` is read with the requester's id, so a merged list shows the
+	* requester's threads only), and undo stacks stay per-lineage — every ACTION records its pair under the
+	* canonical session of the seat that PRESSED it, so the seats of one lineage share one history and a
+	* different lineage cannot reach into it (`undoStackOf`/`popOwnPair` are keyed by that root). The
+	* session-scoped thing a merged press does NOT take from the ROW is the write policy: an action's file
+	* write runs under the REQUESTING session's own workspace and sandbox (see
+	* `DiffApprovalUndoPair.policySession`), never the owner's.
+	*
+	* THE MARK (`hasChildContribution`) IS A DIFFERENT QUESTION and keeps asking only the lineage half: it
+	* claims an owner other than the requester WROTE part of the row, which a child in another workspace
+	* really did. Adding the workspace term there would make that copy lie, so it deliberately does not ask
+	* it (see `sameRoot` below).
+	*
+	* KNOWN LIMIT: a teammate child cannot be told from ANY OTHER subagent child by its header. Both are
+	* built by the one `childSessionMeta` above, and the Team spawner adds nothing to the child — it passes
+	* only `childId`/`provider`/`label` into `ctx.subagents.startContinuable`
+	* (`dsh-experimental-agent-team/lib/types/roster.js:253-262`) and records membership in the LEAD's own
+	* journal (`:249`), which this plugin cannot read. So this view merges every subagent child, not only
+	* teammates; narrowing it to the roster would need a service the plugin does not inject.
+	* @param entries - the store's entries, when the caller already took ONE snapshot for the whole request
+	*   (`store.all()` rebuilds and re-sorts the array, so a read takes it once and hands it down). Defaults
+	*   to a fresh snapshot for the callers that only need the walk.
+	* @returns the view: `sees` answers the visibility question for one entry, `sameRoot` answers whether two
+	* sessions share a lineage root (the question the row's mark asks about its other owners), `directionOf`
+	* says WHICH WAY that other owner stands for the sentence the mark wears, and `rootOf` is the CANONICAL
+	* session — the lineage root, or the session itself when its lineage is unknown — that every
+	* session-scoped store is keyed by (see `canonicalOf`).
+	*/
+	function lineageView(entries = store.all()) {
+		const recorded = /* @__PURE__ */ new Map();
+		for (const entry of entries) if (entry.lineage !== void 0 && !recorded.has(entry.sessionId)) recorded.set(entry.sessionId, entry.lineage);
+		const facts = /* @__PURE__ */ new Map();
+		/**
+		* One session's UPWARD CHAIN: itself, then each recorded subagent parent above it, in order.
+		*
+		* This is the one walk the whole view is made of. `rootOf` is its last element, and the mark's
+		* DIRECTION is a membership question over two of these chains — so the merge, the root and the
+		* direction can never be computed from different links. The links are `knownLineageOf`'s, which reads
+		* the lineage the entry RECORDED before it asks the live header (see that function), and only an
+		* `origin: 'subagent'` link is followed: a host fork names a parent while being an independent root.
+		*
+		* Memoized per view like `roots` was, because the list read asks this per entry per owner on a path
+		* every client repeats once a second. The walk stops at a repeat (`walked`) and at
+		* {@link MAX_LINEAGE_DEPTH}, so a malformed cycle cannot hang it — the same two guards the root walk
+		* has always had.
+		*/
+		const chains = /* @__PURE__ */ new Map();
+		/**
+		* Each session's workspace key, resolved once per view.
+		*
+		* Memoized for the same reason `chains` is: this runs inside `sees`, which the list read calls once per
+		* entry per owner (`listWithState`), on a path every client repeats once a second — and the registry
+		* lookup walks the deployment's workspace list. `has` rather than a truthy check so "known to be
+		* unknown" is cached as such instead of being asked again for an unaccounted session.
+		*/
+		const workspaceKeys = /* @__PURE__ */ new Map();
+		const workspaceKey = (sessionId) => {
+			if (workspaceKeys.has(sessionId)) return workspaceKeys.get(sessionId);
+			const key = workspaceKeyOf(sessionId);
+			workspaceKeys.set(sessionId, key);
+			return key;
+		};
+		const chainOf = (sessionId) => {
+			const known = chains.get(sessionId);
+			if (known !== void 0) return known;
+			const chain = [sessionId];
+			const walked = /* @__PURE__ */ new Set([sessionId]);
+			let current = sessionId;
+			for (let depth = 0; depth < MAX_LINEAGE_DEPTH; depth += 1) {
+				let fact = facts.get(current);
+				if (fact === void 0) {
+					fact = knownLineageOf(current, recorded);
+					facts.set(current, fact);
+				}
+				if (!fact.subagent || fact.parent === void 0 || walked.has(fact.parent)) break;
+				walked.add(fact.parent);
+				chain.push(fact.parent);
+				current = fact.parent;
+			}
+			chains.set(sessionId, chain);
+			return chain;
+		};
+		/** The top of one session's chain: the lineage root both `sees` and `sameRoot` compare. */
+		const rootOf = (sessionId) => {
+			const chain = chainOf(sessionId);
+			return chain[chain.length - 1];
+		};
+		return {
+			sees: (sessionId, entry) => {
+				const root = rootOf(sessionId);
+				const mine = workspaceKey(sessionId);
+				return ownersOf(entry).some((owner) => {
+					if (rootOf(owner) !== root) return false;
+					if (owner === sessionId) return true;
+					return sameWorkspaceKey(workspaceKey(owner), mine);
+				});
+			},
+			sameRoot: (a, b) => rootOf(a) === rootOf(b),
+			rootOf,
+			/**
+			* Which way the row's other contributors stand, for the marker's sentence.
+			*
+			* Read off the SAME recorded links `rootOf` walks, never guessed and never inferred from a name: an
+			* owner is the requester's CHILD when the requester sits on that owner's upward chain, its PARENT
+			* when that owner sits on the requester's chain, and a SIBLING when the two merely share a root.
+			* `parent` therefore means ANCESTOR, however many hops up — which is exactly what the Chinese 上级
+			* says and what the English copy is written to mean.
+			*
+			* Owners of DIFFERENT directions answer `mixed`: the row carries two different relationships and
+			* picking one would state a fact about the row that is only true of part of it. The set is
+			* unresolvable in the honest direction too — "another session" is true of every member — which is
+			* why `mixed` is a real answer and not a failure. `undefined` when no other same-root owner
+			* contributed, i.e. when there is no mark to word.
+			*
+			* The criterion is `hasChildContribution`'s exactly (non-requester, same root) — the workspace term
+			* belongs to visibility, not to this claim (see `sameRoot`).
+			* @param sessionId - the session listing the row.
+			* @param entry - the row being listed.
+			* @returns the direction, or `undefined` when nothing but the lister touched the row.
+			*/
+			directionOf: (sessionId, entry) => {
+				const root = rootOf(sessionId);
+				const mine = chainOf(sessionId);
+				const seen = /* @__PURE__ */ new Set();
+				for (const owner of ownersOf(entry)) {
+					if (owner === sessionId) continue;
+					if (rootOf(owner) !== root) continue;
+					if (chainOf(owner).includes(sessionId)) seen.add("child");
+					else if (mine.includes(owner)) seen.add("parent");
+					else seen.add("sibling");
+				}
+				if (seen.size === 0) return void 0;
+				return seen.size === 1 ? [...seen][0] : "mixed";
+			}
+		};
+	}
+	/**
+	* THE CANONICALIZATION SEAM: the one session-scoped state of a request belongs to.
+	*
+	* The lineage ROOT, because the seats of one lineage read one list — so the undo history they share and
+	* the comment threads they read must be keyed by the lineage, not by whichever seat is looking. A
+	* session whose lineage is unknown (no recorded link, no header facts) is its own root, which is
+	* byte-for-byte the behaviour before any of this existed.
+	*
+	* Every session-scoped seam goes through this function, and the endpoints that already hold a view pass
+	* it so the walk is done once per request (`view` is optional only so a push deep inside a helper cannot
+	* forget to canonicalize; it never means "do not canonicalize").
+	* @param sessionId - the session the request came from.
+	* @param view - the request's lineage view, when the caller already built one.
+	* @returns the canonical session: the lineage root, or `sessionId` itself when it has none.
+	*/
+	function canonicalOf(sessionId, view) {
+		return (view ?? lineageView()).rootOf(sessionId);
+	}
+	/**
+	* The comment scope of one request: which comment AUTHORS this lineage may read and act on.
+	*
+	* `sameRoot` is the view's own question, so the scope and the merge cannot disagree about who is kin —
+	* and it is the same predicate for reading, removing, marking seen and asking, so no verb can widen or
+	* narrow the lineage on its own.
+	* @param sessionId - the session the request came from.
+	* @param view - the request's lineage view.
+	* @returns the predicate the comment store's `CommentScope` takes.
+	*/
+	function commentScopeOf(sessionId, view) {
+		return (author) => view.sameRoot(author, sessionId);
+	}
+	/**
+	* The entry one id names, when the requesting session may act on it; `undefined` otherwise.
+	*
+	* Every action path resolves its entry through this, so an id outside the requester's lineage is
+	* answered exactly like an id that names nothing — `missing` — and no action can reach a row the
+	* requester cannot see.
+	* @param view - the request's lineage view.
+	* @param sessionId - the requesting session.
+	* @param id - the entry id (its path).
+	* @returns the entry, or `undefined` when it is absent or outside the view.
+	*/
+	function actionableEntryOf(view, sessionId, id) {
+		const entry = store.get(id);
+		return entry !== void 0 && view.sees(sessionId, entry) ? entry : void 0;
+	}
+	/**
 	* Write a Revert through `ctx.fs`, carrying the session's sandbox policy
 	* only when a confining backend is mounted (so the plain 4-arg call shape is
 	* preserved for the unsandboxed composition).
@@ -4379,7 +5498,7 @@ function apply(ctx, config) {
 	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}'`);
+		if (policy !== void 0 && !withinSandboxRoot(osPath, policy)) throw new Error(sandboxDenial(osPath, policy));
 		const fs = ctx.fs;
 		if (policy !== void 0 && typeof fs.remove === "function") {
 			await fs.remove(target, policy, signal);
@@ -4410,10 +5529,157 @@ function apply(ctx, config) {
 		return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
 	}
 	/**
+	* The sentence a confining policy uses when it refuses one path, wherever it is produced.
+	*
+	* ONE producer, so the check a delete performs, the preflight a restore runs and the message a reader is
+	* handed can never describe the refusal differently.
+	* @param path - the OS path the policy refused.
+	* @param policy - the session's resolved policy.
+	* @returns the refusal sentence.
+	*/
+	function sandboxDenial(path, policy) {
+		return `file access denied under ${policy.mode} mode: '${path}' is outside the sandbox workspace root '${policy.workspaceRoot}'`;
+	}
+	/**
+	* Whether a thrown write error is the session's own AUTHORITY refusing it, rather than the file being
+	* gone, changed, or unreadable.
+	*
+	* Exactly two shapes qualify, and nothing else does: a confining backend raises `FS_SANDBOX_DENIED` (the
+	* `FsErrorCode` the fs package owns for "the policy layer said no"), and this file's own containment
+	* check in `removeRevert` raises a plain Error saying the path is outside the sandbox workspace root.
+	* Everything else keeps its own answer: `FS_NOT_FOUND` is a missing file, the divergence guard's "changed
+	* outside the review" is a diverged one, `FS_PERMISSION_DENIED` is the FILE SYSTEM refusing (a fact about
+	* the file, not about this session's grant) and the rest are IO or aborted faults. The predicate is
+	* deliberately this narrow: widening it is how a reader loses the difference between "I may not write
+	* there" and "that file is gone".
+	* @param error - the value a write path threw.
+	* @returns whether the sandbox/policy refused the write.
+	*/
+	function isPolicyRefusal(error) {
+		if (fsErrorCodeOf(error) === "FS_SANDBOX_DENIED") return true;
+		return /outside the sandbox workspace root/i.test(errorMessage(error));
+	}
+	/**
+	* The answer for a write the session's authority refused: a sentence that NAMES THE PATH and says, in
+	* words, that this session may not write there, carrying the sandbox's own reason with it.
+	*
+	* Why TEXT and not a code: the RPC error vocabulary this channel answers in is closed and owned by the
+	* vendor (`RpcErrorDetailsMap` in `@deepseek-ai/dsh-host-apiproxy` — `internal` is its catch-all, and a
+	* new code needs a row in that table), so this package cannot mint a `permission` code of its own. The
+	* reader still gets the sentence: the port folds a failed call into `Error(code: message)` and the
+	* panel's failed-row notice prints that message verbatim, so the refusal arrives as words on the path the
+	* panel already has for a failed action. A LOCALIZED route would need a client-side classifier over the
+	* message plus new locale keys — a copy change across the host/client seam — for no difference the reader
+	* can see, since every other message on this channel is host English too.
+	* @param path - the file the refused write was about (the entry's own path).
+	* @param error - what the write threw.
+	* @returns the error branch to answer with.
+	*/
+	function policyRefusal(path, error) {
+		return rpcError(refusalText(path, error));
+	}
+	/** The refusal sentence itself, shared by every path that answers with one. */
+	function refusalText(path, error) {
+		return `'${path}' is outside this session's write authority: the workspace this session may write does not cover it. The sandbox refused the write: ${errorMessage(error)}`;
+	}
+	/**
+	* Every file write a restore will make, in the order it will make them.
+	*
+	* Mirrors `restoreState`'s own walk, index-aligned with the counterpart side, so the preflight below and
+	* the writer can never disagree about WHICH files a restore touches. A state with no `fileText` writes
+	* nothing: it puts an entry back in the list (or takes it out) and never opens a file.
+	* @param state - the side being installed.
+	* @param expectedFile - the other side, whose per-index `fileText` is the divergence snapshot.
+	* @returns the writes, in order.
+	*/
+	function restoreWritesOf(state, expectedFile) {
+		const writes = [];
+		if (state.batch !== void 0) {
+			const counterpart = expectedFile?.batch;
+			for (const [index, item] of state.batch.entries()) writes.push(...restoreWritesOf({
+				...item,
+				batch: void 0
+			}, counterpart?.[index]));
+			return writes;
+		}
+		if (state.fileText !== void 0) writes.push({
+			path: state.path,
+			expected: expectedFile?.fileText
+		});
+		return writes;
+	}
+	/**
+	* Check EVERY write a restore will make before it makes the first one, and refuse the whole restore if any
+	* of them would be refused.
+	*
+	* WHAT IS GUARANTEED, and what is not (this is the honest half of the design):
+	*
+	* - AUTHORITY is guaranteed all-or-nothing. Each target is checked with the SAME predicate the write path
+	*   enforces (`withinSandboxRoot`, the one `removeRevert` refuses with and the policy `writeRevert` hands
+	*   the backend), under `pair.policySession` — the seat the action ran under. A refusal anywhere means no
+	*   file is written at all, so an undo can never take back half of a decision. This is a check made before
+	*   the first byte, so it is a guarantee rather than a hope.
+	* - DIVERGENCE is also preflighted, because it is cheap and detectable up front: a target whose
+	*   counterpart snapshot no longer matches the file refuses the whole restore rather than stopping
+	*   half-way through it.
+	* - A RUNTIME failure is NOT preflightable and is not promised away: a file that vanishes between this
+	*   check and the write, or an IO fault on the third of five files, can still leave the earlier writes
+	*   applied. When that happens the caller reports exactly how far the restore got (`RestoreProgress`)
+	*   instead of claiming nothing happened. Do not read this function as an atomicity promise; it is a
+	*   permission and staleness promise, and the mid-way case is reported as the partial state it is.
+	* @param writes - the plan, from `restoreWritesOf`.
+	* @param policySession - the session whose policy the write runs under (the pair's recorded seat).
+	* @param signal - aborts the checks too.
+	* @returns the first refusal (its path and the reason to report), or undefined when the plan may run.
+	*/
+	async function preflightRestore(writes, policySession, signal) {
+		const policy = sandboxPolicyOf(policySession);
+		for (const write of writes) {
+			let resolved;
+			try {
+				resolved = await ctx.fs.resolve(write.path, { signal });
+			} catch (error) {
+				return {
+					path: write.path,
+					error
+				};
+			}
+			if (policy !== void 0 && !withinSandboxRoot(processPathOf(resolved), policy)) return {
+				path: write.path,
+				error: new Error(sandboxDenial(processPathOf(resolved), policy))
+			};
+			if (write.expected !== void 0) {
+				if (await ctx.fs.readText(resolved, void 0) !== write.expected) return {
+					path: write.path,
+					error: /* @__PURE__ */ new Error("the file changed outside the review after the action; undo is unavailable")
+				};
+			}
+		}
+	}
+	/**
+	* The answer for a restore that did not finish: the refusal sentence when the sandbox was the reason, the
+	* ordinary `undo failed:`/`redo failed:` text otherwise — and in EVERY case, when the restore had already
+	* written something, how far it got. "Never that nothing happened": a partial restore is reported as the
+	* partial state it is.
+	* @param action - which direction was running.
+	* @param path - the file the failure is about.
+	* @param error - what the restore threw.
+	* @param progress - the writes it completed, and how many it had to make.
+	* @returns the error branch to answer with.
+	*/
+	function restoreFailure(action, path, error, progress) {
+		if (isPolicyRefusal(error)) {
+			const far = progress.written === 0 ? "" : ` The ${action} had already written ${progress.written} of ${progress.total} files before that.`;
+			return rpcError(refusalText(path, error) + far);
+		}
+		return rpcError(`${action} failed${progress.written === 0 ? "" : ` after writing ${progress.written} of ${progress.total} files`}: ${errorMessage(error)}`);
+	}
+	/**
 	* 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
-	* writes the baseline back and yields the before/after undo snapshot.
+	* behind both the single `revert` endpoint and the bulk `revert-all`). An
+	* entry with no earlier version (`earlierVersion: 'none'`) has its file
+	* deleted (not undoable: the file is gone); one that has an earlier version
+	* (`'file'`) writes it back and yields the before/after undo snapshot.
 	* @param entry - the entry to revert.
 	* @param sessionId - the entry's session (for the per-session write policy).
 	* @param signal - aborts before atomic publication takes effect.
@@ -4421,7 +5687,7 @@ function apply(ctx, config) {
 	*/
 	async function revertEntryContent(entry, sessionId, signal) {
 		const resolved = await ctx.fs.resolve(entry.path, { signal });
-		if (entry.kind === "create") {
+		if (entry.earlierVersion === "none") {
 			await removeRevert(resolved, sessionId, signal);
 			return;
 		}
@@ -4445,33 +5711,91 @@ function apply(ctx, config) {
 	}
 	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);
+	/** The undo stack of one lineage root, created on first use. Its key is a CANONICAL session. */
+	function undoStackOf(root) {
+		let stack = undoStacks.get(root);
 		if (stack === void 0) {
 			stack = [];
-			undoStacks.set(sessionId, stack);
+			undoStacks.set(root, stack);
 		}
 		return stack;
 	}
-	/** The redo stack of one session, created on first use. */
-	function redoStackOf(sessionId) {
-		let stack = redoStacks.get(sessionId);
+	/** The redo stack of one lineage root, created on first use. Its key is a CANONICAL session. */
+	function redoStackOf(root) {
+		let stack = redoStacks.get(root);
 		if (stack === void 0) {
 			stack = [];
-			redoStacks.set(sessionId, stack);
+			redoStacks.set(root, 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) {
-		undoStackOf(sessionId).push({
-			sessionId,
+	/**
+	* One entry as an undo target sees it, for the "did this really change?" comparison.
+	*
+	* `updatedAt` is deliberately NOT in the key: every action stamps it with `Date.now()`, so including it
+	* would make every recorded target look changed — the exact false positive the comparison exists to stop.
+	*/
+	function entryKeyOf(entry) {
+		if (entry === void 0) return "(no entry)";
+		return JSON.stringify(entry, (key, value) => key === "updatedAt" ? void 0 : value);
+	}
+	/** One side's comment records as a comparable key (a pair that carries threads changes when they do). */
+	function commentsKeyOf(comments) {
+		return (comments ?? []).map((comment) => `${comment.id}@${comment.anchor.startLine}-${comment.anchor.endLine}:${comment.text}`).join("|");
+	}
+	/**
+	* Whether one target of a forward action really changed anything.
+	*
+	* THE RULE the reader asked for: a pair records only what changed. `before` is what the action found and
+	* `after` is what it left — which is also what the file and the entry hold NOW, since the action has just
+	* finished — so comparing the two sides is comparing the target against the world. Three things can
+	* differ and each counts on its own: the file bytes (`fileText`, with `undefined` meaning "no write"), the
+	* entry (its content-bearing fields; see `entryKeyOf`), and a comment pair's records. A target where none
+	* of them differs is not a change and is not recorded, so Ctrl+Z cannot walk a file the action never
+	* moved.
+	*
+	* A BATCH state is not compared here: its members are filtered one by one in `pushBatchUndo`, which is
+	* where the index alignment lives.
+	* @param before - the state the action found.
+	* @param after - the state it left.
+	* @returns whether recording this target would give the reader something to take back.
+	*/
+	function stateChanged(before, after) {
+		if (before.batch !== void 0 || after.batch !== void 0) return true;
+		if (before.kind === "comments" || after.kind === "comments") return commentsKeyOf(before.comments) !== commentsKeyOf(after.comments);
+		if (before.fileText !== after.fileText) return true;
+		return entryKeyOf(before.entry) !== entryKeyOf(after.entry);
+	}
+	/**
+	* Record one undoable action in its lineage's history. A fresh action invalidates that lineage's redo
+	* history (and only that lineage's).
+	*
+	* THE RULE: the pair is filed under the CANONICAL session, so every seat of one lineage shares one
+	* history and any of them can take the action back; the session that pressed is remembered on the pair
+	* (`pressedBy` for attribution, and `policySession` for the write the RESTORE runs) — and the write
+	* policy is recorded rather than re-derived, because the seat that POPS a pair need not be the seat that
+	* made it. Canonicalizing HERE rather than at the call site is what makes the rule unforgettable: every
+	* push in this file goes through this function.
+	*
+	* `policySession` is the presser because the forward action's own write is the requester's (see the
+	* `revertEntryContent` call sites) — so every push here records the seat whose authority the action ran
+	* under, and the restore replays exactly that.
+	* @param sessionId - the session that pressed the action.
+	* @param before - the state the action found, and what a restore puts back.
+	* @param after - the state the action left, and what a redo re-applies.
+	* @param view - the request's lineage view, when the caller already built one.
+	*/
+	function pushUndo(sessionId, before, after, view) {
+		if (!stateChanged(before, after)) return;
+		const root = canonicalOf(sessionId, view);
+		undoStackOf(root).push({
+			root,
+			pressedBy: sessionId,
+			policySession: sessionId,
 			before,
 			after
 		});
-		redoStackOf(sessionId).length = 0;
+		redoStackOf(root).length = 0;
 	}
 	/**
 	* Record several entries' worth of ONE decision as a single undo step.
@@ -4480,36 +5804,45 @@ function apply(ctx, config) {
 	* 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 sessionId - the session that pressed.
 	* @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`).
+	* @param view - the request's lineage view, when the caller already built one.
 	*/
-	function pushBatchUndo(sessionId, before, after) {
-		if (before.length === 0) return;
+	function pushBatchUndo(sessionId, before, after, view) {
+		const changedBefore = [];
+		const changedAfter = [];
+		for (const [index, item] of before.entries()) {
+			const counterpart = after[index];
+			if (counterpart === void 0 || !stateChanged(item, counterpart)) continue;
+			changedBefore.push(item);
+			changedAfter.push(counterpart);
+		}
+		if (changedBefore.length === 0) return;
 		pushUndo(sessionId, {
-			id: before[0].id,
-			path: before[0].path,
+			id: changedBefore[0].id,
+			path: changedBefore[0].path,
 			entry: void 0,
 			fileText: void 0,
-			batch: before
+			batch: changedBefore
 		}, {
-			id: after[0].id,
-			path: after[0].path,
+			id: changedAfter[0].id,
+			path: changedAfter[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.
+			batch: changedAfter
+		}, view);
+	}
+	/** Drop the top pair of one lineage root's stack, when it belongs to that root; otherwise the
+	*  stack is left exactly as it was, so another lineage's action is untouched.
+	* @param stack - the root's stack (undo or redo).
+	* @param root - the canonical session the request is for.
+	* @returns the pair to move, or undefined when this lineage has nothing to move.
 	*/
-	function popOwnPair(stack, sessionId) {
+	function popOwnPair(stack, root) {
 		const pair = stack[stack.length - 1];
-		if (pair === void 0 || pair.sessionId !== sessionId) return void 0;
+		if (pair === void 0 || pair.root !== root) return void 0;
 		stack.pop();
 		return pair;
 	}
@@ -4578,16 +5911,18 @@ function apply(ctx, config) {
 	*
 	* 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.
+	* @param scope - which comment authors this restore may remove: the undo's lineage. The stale side is
+	*   the comments the OTHER side held, and they belong to whichever seats wrote them, so the removal has
+	*   to be allowed to reach every file the pair's records live in (see `CommentStore.removeMany`).
 	*/
-	function restoreComments(sessionId, state, expectedFile) {
+	function restoreComments(state, expectedFile, scope) {
 		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);
+			comments.removeMany(scope, stale);
 			for (const id of stale) commentLines.delete(id);
 		}
 		if (installing.length > 0) comments.addMany(installing);
@@ -4600,14 +5935,18 @@ function apply(ctx, config) {
 	* 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 sessionId - the session the policy is resolved from (the pair's presser — see `undoStackOf`).
 	* @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.
+	* @param scope - which comment authors this restore may remove (the undo request's lineage).
+	* @param progress - counts the file writes as they land, so a mid-way failure can report exactly how far
+	*   it got instead of claiming nothing happened (see `restoreFailure`). Omitted where the caller has no
+	*   use for it; a restore that gets no `progress` is unchanged.
 	*/
-	async function restoreState(sessionId, state, expectedFile, signal) {
+	async function restoreState(sessionId, state, expectedFile, signal, scope, progress) {
 		if (state.kind === "comments") {
-			restoreComments(sessionId, state, expectedFile);
+			restoreComments(state, expectedFile, scope);
 			return;
 		}
 		if (state.fileText !== void 0) {
@@ -4615,14 +5954,16 @@ function apply(ctx, config) {
 			if (expectedFile?.fileText !== void 0) {
 				if (await ctx.fs.readText(resolved, void 0) !== expectedFile.fileText) throw new Error("the file changed outside the review after the action; undo is unavailable");
 			}
+			if (progress !== void 0) progress.path = state.path;
 			await writeRevert(resolved, state.fileText, sessionId, signal);
+			if (progress !== void 0) progress.written += 1;
 		}
 		if (state.batch !== void 0) {
 			const counterpart = expectedFile?.batch;
 			for (const [index, item] of state.batch.entries()) await restoreState(sessionId, {
 				...item,
 				batch: void 0
-			}, counterpart?.[index], signal);
+			}, counterpart?.[index], signal, scope, progress);
 			return;
 		}
 		if (state.entry !== void 0) store.restore(state.entry);
@@ -4666,6 +6007,21 @@ function apply(ctx, config) {
 	}
 	/** Mark the store dirty and schedule one throttled, coalesced write. Pass
 	* `force` to write immediately (user actions need durable, immediate results). */
+	/**
+	* Mark the list dirty and start its write. The throttle is for the panel's own churn; `force` writes
+	* NOW and, since 2026-10-06, RETURNS the write's promise.
+	*
+	* That return value is a durability guarantee, not a convenience: a caller that is about to write
+	* something NAMING an entry — the annotate tool's comment — has to know the entry is readable at the
+	* next boot first. Folded in memory and written on a later flush, an entry can be lost to a host that
+	* stops in between, and the load-time sweep then hides (and used to delete) the comments that named
+	* it. Awaiting here is what makes "the comment exists" imply "its entry was on disk first".
+	*
+	* @param force - write immediately rather than on the throttle's schedule.
+	* @returns a promise that settles when the write this call started has finished (never rejects: a
+	* failure is logged and reported through `persistFailureReported`, because a store that cannot write
+	* must keep answering reads).
+	*/
 	function persistSession(force = false) {
 		persistDirty = true;
 		if (force) {
@@ -4673,20 +6029,18 @@ function apply(ctx, config) {
 				clearTimeout(persistTimer);
 				persistScheduled = false;
 			}
-			flushPersist();
-			return;
+			return flushPersist();
 		}
-		if (persistScheduled) return;
+		if (persistScheduled) return Promise.resolve();
 		const delay = PERSIST_THROTTLE_MS - (Date.now() - lastPersistAt);
-		if (delay <= 0) flushPersist();
-		else {
-			persistScheduled = true;
-			persistTimer = setTimeout(() => {
-				persistScheduled = false;
-				flushPersist();
-			}, delay);
-			persistTimer.unref?.();
-		}
+		if (delay <= 0) return flushPersist();
+		persistScheduled = true;
+		persistTimer = setTimeout(() => {
+			persistScheduled = false;
+			flushPersist();
+		}, delay);
+		persistTimer.unref?.();
+		return Promise.resolve();
 	}
 	ctx.on("tools/result", (exec, result) => {
 		if (exec.name === "str_replace_editor") {
@@ -4702,31 +6056,47 @@ function apply(ctx, config) {
 			sessionId,
 			...outcome,
 			updatedAt: Date.now(),
-			sessionIds: [sessionId]
+			sessionIds: [sessionId],
+			lineage: lineageOf(sessionId, exec.agent),
+			unseen: true
 		};
 		if (store.fold(entry)) persistSession();
 	});
 	const handle = async (endpoint, payload, signal) => {
 		switch (endpoint) {
+			case "update-check": return {
+				ok: true,
+				value: await checkForUpdate()
+			};
 			case "list": {
 				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 entries = store.all();
+				const view = lineageView(entries);
+				if (comments.retain(new Set(entries.map((entry) => entry.id))) > 0) forgetOrphanedCommentLines();
+				const { files, redoCleared } = await listWithState(sessionId, view, entries);
+				const scope = commentScopeOf(sessionId, view);
+				const visibleComments = comments.list(scope);
+				let folded = false;
 				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;
+				if (visibleComments.length > 0) {
+					const transcripts = /* @__PURE__ */ new Map();
+					for (const [transcript, requestIds] of commentAsker.answerGroups(visibleComments)) {
+						const answers = commentAsker.answersFor(transcript, requestIds, transcripts);
+						for (const [requestId, read] of Object.entries(answers)) if (read.turn !== void 0 && comments.recordTurnForRequest(requestId, read.turn) > 0) folded = true;
+						for (const turn of commentAsker.endedTurns(transcript, transcripts)) if (comments.markTurnEnded(transcript, turn) > 0) folded = true;
+						if (comments.syncAnswers(transcript, answers)) folded = true;
+						for (const [requestId, read] of Object.entries(answers)) if (read.answer !== void 0) commentAnswers[requestId] = read.answer;
+					}
 				}
+				const listedComments = folded ? comments.list(scope) : visibleComments;
 				return {
 					ok: true,
 					value: {
 						files,
-						comments: comments.list(sessionId),
-						commentLines: resolvedCommentLines(sessionId),
+						comments: listedComments,
+						commentLines: resolvedCommentLines(listedComments),
 						commentsRevision: comments.commentsRevision(),
 						commentAnswers,
 						workspacePath: workspaceOf(sessionId)?.path,
@@ -4737,11 +6107,44 @@ function apply(ctx, config) {
 					}
 				};
 			}
+			case "list-count": {
+				const sessionId = sessionOf(payload);
+				if (sessionId === void 0) return rpcError("sessionId must be a non-empty string");
+				await ensureLoaded();
+				const entries = store.all();
+				const view = lineageView(entries);
+				let count = 0;
+				for (const entry of entries) {
+					if (!view.sees(sessionId, entry)) continue;
+					if ((await probePath(entry.path)).kind !== "present") continue;
+					count += 1;
+				}
+				return {
+					ok: true,
+					value: { count }
+				};
+			}
+			case "comment-seen": {
+				const seen = targetOf(payload);
+				if (seen === void 0) return rpcError("sessionId and id must be non-empty strings");
+				await ensureLoaded();
+				const record = comments.get(seen.id);
+				if (record === void 0 || !commentScopeOf(seen.sessionId, lineageView())(record.sessionId)) return {
+					ok: true,
+					value: { outcome: "missing" }
+				};
+				comments.markSeen(seen.id);
+				return {
+					ok: true,
+					value: { outcome: "seen" }
+				};
+			}
 			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);
+				const view = lineageView();
+				const entry = actionableEntryOf(view, input.sessionId, input.entryId);
 				if (entry === void 0) return {
 					ok: true,
 					value: { outcome: "missing" }
@@ -4761,7 +6164,7 @@ function apply(ctx, config) {
 					...input.quoteLines === void 0 ? {} : { quoteLines: input.quoteLines }
 				};
 				comments.add(record);
-				pushUndo(input.sessionId, commentState(entry.path, []), commentState(entry.path, [record]));
+				pushUndo(input.sessionId, commentState(entry.path, []), commentState(entry.path, [record]), view);
 				return {
 					ok: true,
 					value: {
@@ -4774,10 +6177,11 @@ function apply(ctx, config) {
 				const target = targetOf(payload);
 				if (target === void 0) return rpcError("sessionId and id must be non-empty strings");
 				await ensureLoaded();
+				const view = lineageView();
 				const record = comments.get(target.id);
-				const removed = comments.remove(target.sessionId, target.id);
+				const removed = comments.remove(commentScopeOf(target.sessionId, view), target.id);
 				const value = { outcome: removed ? "removed" : "missing" };
-				if (removed && record !== void 0) pushUndo(target.sessionId, commentState(record.entryId, [record]), commentState(record.entryId, []));
+				if (removed && record !== void 0) pushUndo(target.sessionId, commentState(record.entryId, [record]), commentState(record.entryId, []), view);
 				commentLines.delete(target.id);
 				return {
 					ok: true,
@@ -4788,11 +6192,13 @@ function apply(ctx, config) {
 				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);
+				const view = lineageView();
+				const scope = commentScopeOf(request.sessionId, view);
+				const snapshot = request.ids.map((id) => comments.get(id)).filter((record) => record !== void 0 && scope(record.sessionId));
+				const removed = comments.removeMany(scope, 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, []));
+				if (first !== void 0) pushUndo(request.sessionId, commentState(first.entryId, snapshot), commentState(first.entryId, []), view);
 				return {
 					ok: true,
 					value: { removed: removed.length }
@@ -4802,18 +6208,20 @@ function apply(ctx, config) {
 				const input = commentAskOf(payload);
 				if (input === void 0) return rpcError("sessionId, id, prompt and text must be valid");
 				await ensureLoaded();
+				const view = lineageView();
 				return {
 					ok: true,
-					value: await commentAsker.ask(input.sessionId, input.id, input.prompt, input.text, signal)
+					value: await commentAsker.ask(input.sessionId, input.id, input.prompt, input.text, signal, commentScopeOf(input.sessionId, view))
 				};
 			}
 			case "keep": {
 				const target = targetOf(payload);
 				if (target === void 0) return rpcError("sessionId and id must be non-empty strings");
-				let entry = store.get(target.id);
+				const lineage = lineageView();
+				let entry = actionableEntryOf(lineage, target.sessionId, target.id);
 				if (entry === void 0) {
 					await ensureLoaded();
-					entry = store.get(target.id);
+					entry = actionableEntryOf(lineage, target.sessionId, target.id);
 					if (entry === void 0) return {
 						ok: true,
 						value: { outcome: "missing" }
@@ -4868,10 +6276,11 @@ function apply(ctx, config) {
 			case "revert": {
 				const target = targetOf(payload);
 				if (target === void 0) return rpcError("sessionId and id must be non-empty strings");
-				let entry = store.get(target.id);
+				const lineage = lineageView();
+				let entry = actionableEntryOf(lineage, target.sessionId, target.id);
 				if (entry === void 0) {
 					await ensureLoaded();
-					entry = store.get(target.id);
+					entry = actionableEntryOf(lineage, target.sessionId, target.id);
 					if (entry === void 0) return {
 						ok: true,
 						value: { outcome: "missing" }
@@ -4881,6 +6290,7 @@ function apply(ctx, config) {
 				try {
 					undo = await revertEntryContent(entry, target.sessionId, signal);
 				} catch (error) {
+					if (isPolicyRefusal(error)) return policyRefusal(entry.path, error);
 					return rpcError(`revert failed: ${errorMessage(error)}`);
 				}
 				if (payload.keepListed === true) {
@@ -4927,7 +6337,8 @@ function apply(ctx, config) {
 				const sessionId = sessionOf(payload);
 				if (sessionId === void 0) return rpcError("sessionId must be a non-empty string");
 				await ensureLoaded();
-				const entries = store.list(sessionId);
+				const lineage = lineageView();
+				const entries = store.all().filter((entry) => lineage.sees(sessionId, entry));
 				const before = [];
 				const after = [];
 				for (const entry of entries) {
@@ -4956,16 +6367,22 @@ function apply(ctx, config) {
 				const sessionId = sessionOf(payload);
 				if (sessionId === void 0) return rpcError("sessionId must be a non-empty string");
 				await ensureLoaded();
-				const entries = store.list(sessionId);
+				const lineage = lineageView();
+				const entries = store.all().filter((entry) => lineage.sees(sessionId, entry));
 				const batchBefore = [];
 				const batchAfter = [];
+				/** How many files this press had already put back when it stopped: said, never hidden (see 3c). */
+				let reverted = 0;
 				for (const entry of entries) {
 					let undo;
 					try {
 						undo = await revertEntryContent(entry, sessionId, signal);
-					} catch {
-						return rpcError(`revert-all failed for ${entry.path}`);
+					} catch (error) {
+						const far = reverted === 0 ? "" : ` (this press had already reverted ${reverted} of ${entries.length} files)`;
+						if (isPolicyRefusal(error)) return rpcError(refusalText(entry.path, error) + far);
+						return rpcError(`revert-all failed for ${entry.path}${far}`);
 					}
+					reverted += 1;
 					if (undo !== void 0) {
 						batchBefore.push(droppingComments(undo.before));
 						batchAfter.push(undo.after);
@@ -4983,10 +6400,11 @@ function apply(ctx, config) {
 				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 lineage = lineageView();
 				const before = [];
 				const after = [];
 				for (const id of request.ids) {
-					const entry = store.get(id);
+					const entry = actionableEntryOf(lineage, request.sessionId, id);
 					if (entry === void 0) continue;
 					if (request.keepListed === true) {
 						store.update(id, { oldText: entry.newText });
@@ -5033,18 +6451,21 @@ function apply(ctx, config) {
 				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 lineage = lineageView();
 				const before = [];
 				const after = [];
 				let affected = 0;
 				for (const id of request.ids) {
-					const entry = store.get(id);
+					const entry = actionableEntryOf(lineage, request.sessionId, 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}`);
+					} catch (error) {
+						const far = affected - 1 === 0 ? "" : ` (this pick had already reverted ${affected - 1} of ${request.ids.length} files)`;
+						if (isPolicyRefusal(error)) return rpcError(refusalText(entry.path, error) + far);
+						return rpcError(`revert-many failed for ${entry.path}${far}`);
 					}
 					if (request.keepListed === true) {
 						const content = undo?.after.fileText ?? "";
@@ -5086,7 +6507,7 @@ function apply(ctx, config) {
 				const blockTarget = blockTargetOf(payload);
 				if (blockTarget === void 0) return rpcError("sessionId, id, and block must be valid");
 				await ensureLoaded();
-				const entry = store.get(blockTarget.id);
+				const entry = actionableEntryOf(lineageView(), blockTarget.sessionId, blockTarget.id);
 				if (entry === void 0) return {
 					ok: true,
 					value: { outcome: "missing" }
@@ -5140,7 +6561,7 @@ function apply(ctx, config) {
 				const blockTarget = blockTargetOf(payload);
 				if (blockTarget === void 0) return rpcError("sessionId, id, and block must be valid");
 				await ensureLoaded();
-				const entry = store.get(blockTarget.id);
+				const entry = actionableEntryOf(lineageView(), blockTarget.sessionId, blockTarget.id);
 				if (entry === void 0) return {
 					ok: true,
 					value: { outcome: "missing" }
@@ -5157,7 +6578,7 @@ function apply(ctx, config) {
 				let undo;
 				try {
 					const target = await ctx.fs.resolve(entry.path, { signal });
-					if (entry.kind === "create" && content === "") await removeRevert(target, blockTarget.sessionId, signal);
+					if (entry.earlierVersion === "none" && 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);
@@ -5177,6 +6598,7 @@ function apply(ctx, config) {
 						};
 					}
 				} catch (error) {
+					if (isPolicyRefusal(error)) return policyRefusal(entry.path, error);
 					return rpcError(`block revert failed: ${errorMessage(error)}`);
 				}
 				if (undo !== void 0) pushUndo(blockTarget.sessionId, undo.before, undo.after);
@@ -5209,18 +6631,35 @@ 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 = popOwnPair(undoStackOf(sessionId), sessionId);
+				const view = lineageView();
+				const root = canonicalOf(sessionId, view);
+				const pair = popOwnPair(undoStackOf(root), root);
 				if (pair === void 0) return {
 					ok: true,
 					value: { outcome: "nothing" }
 				};
+				const writes = restoreWritesOf(pair.before, pair.after);
+				const refused = await preflightRestore(writes, pair.policySession, signal);
+				if (refused !== void 0) {
+					undoStackOf(root).push(pair);
+					return restoreFailure("undo", refused.path, refused.error, {
+						written: 0,
+						total: writes.length,
+						path: refused.path
+					});
+				}
+				const progress = {
+					written: 0,
+					total: writes.length,
+					path: pair.before.path
+				};
 				try {
-					await restoreState(pair.sessionId, pair.before, pair.after, signal);
+					await restoreState(pair.policySession, pair.before, pair.after, signal, commentScopeOf(pair.pressedBy, view), progress);
 				} catch (error) {
-					undoStackOf(sessionId).push(pair);
-					return rpcError(`undo failed: ${errorMessage(error)}`);
+					undoStackOf(root).push(pair);
+					return restoreFailure("undo", progress.path, error, progress);
 				}
-				redoStackOf(sessionId).push(pair);
+				redoStackOf(root).push(pair);
 				persistSession(true);
 				return {
 					ok: true,
@@ -5233,18 +6672,35 @@ 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 = popOwnPair(redoStackOf(sessionId), sessionId);
+				const view = lineageView();
+				const root = canonicalOf(sessionId, view);
+				const pair = popOwnPair(redoStackOf(root), root);
 				if (pair === void 0) return {
 					ok: true,
 					value: { outcome: "nothing" }
 				};
+				const writes = restoreWritesOf(pair.after, pair.before);
+				const refused = await preflightRestore(writes, pair.policySession, signal);
+				if (refused !== void 0) {
+					redoStackOf(root).push(pair);
+					return restoreFailure("redo", refused.path, refused.error, {
+						written: 0,
+						total: writes.length,
+						path: refused.path
+					});
+				}
+				const progress = {
+					written: 0,
+					total: writes.length,
+					path: pair.after.path
+				};
 				try {
-					await restoreState(pair.sessionId, pair.after, pair.before, signal);
+					await restoreState(pair.policySession, pair.after, pair.before, signal, commentScopeOf(pair.pressedBy, view), progress);
 				} catch (error) {
-					redoStackOf(sessionId).push(pair);
-					return rpcError(`redo failed: ${errorMessage(error)}`);
+					redoStackOf(root).push(pair);
+					return restoreFailure("redo", progress.path, error, progress);
 				}
-				undoStackOf(sessionId).push(pair);
+				undoStackOf(root).push(pair);
 				persistSession(true);
 				return {
 					ok: true,
@@ -5292,11 +6748,12 @@ function apply(ctx, config) {
 							id: change.path,
 							sessionId,
 							path: change.path,
-							kind: change.kind,
+							earlierVersion: change.earlierVersion,
 							oldText: change.oldText,
 							newText: change.newText,
 							updatedAt: Date.now(),
-							sessionIds: [sessionId]
+							sessionIds: [sessionId],
+							lineage: lineageOf(sessionId)
 						}))),
 						detected: true
 					}
@@ -5306,7 +6763,7 @@ function apply(ctx, config) {
 				const target = targetOf(payload);
 				if (target === void 0) return rpcError("sessionId and id must be non-empty strings");
 				await ensureLoaded();
-				const entry = store.get(target.id);
+				const entry = actionableEntryOf(lineageView(), target.sessionId, target.id);
 				if (entry === void 0) return {
 					ok: true,
 					value: { outcome: "missing" }
@@ -5336,22 +6793,32 @@ function apply(ctx, config) {
 					return rpcError(`refresh failed: ${errorMessage(error)}`);
 				}
 				const change = changes.find((candidate) => pathIdentity(candidate.path) === pathIdentity(entry.path));
-				if (change === void 0) return {
-					ok: true,
-					value: { outcome: "no-change" }
-				};
-				if (change.kind === entry.kind && change.oldText === entry.oldText && change.newText === entry.newText) return {
+				if (change === void 0) {
+					let committed = false;
+					try {
+						committed = await committedChange(root.root, root.kind, entry.path, shell, signal);
+					} catch {}
+					return {
+						ok: true,
+						value: committed ? {
+							outcome: "committed",
+							resolved: true
+						} : { outcome: "no-change" }
+					};
+				}
+				if (change.earlierVersion === entry.earlierVersion && change.oldText === entry.oldText && change.newText === entry.newText) return {
 					ok: true,
 					value: { outcome: "unchanged" }
 				};
 				const refreshed = {
 					...entry,
-					kind: change.kind,
+					earlierVersion: change.earlierVersion,
 					oldText: change.oldText,
 					newText: change.newText,
 					updatedAt: Date.now()
 				};
 				store.restore(refreshed);
+				store.markSeen(entry.path);
 				pushUndo(target.sessionId, {
 					id: entry.path,
 					path: entry.path,
@@ -5492,11 +6959,12 @@ function apply(ctx, config) {
 						id: absolute,
 						sessionId: target.sessionId,
 						path: absolute,
-						kind: "edit",
+						earlierVersion: "file",
 						oldText: content,
 						newText: content,
 						updatedAt: now,
-						sessionIds: [target.sessionId]
+						sessionIds: [target.sessionId],
+						lineage: lineageOf(target.sessionId)
 					}], false, false);
 				}
 				const root = detectVcsRoot(workspace.path);
@@ -5537,11 +7005,12 @@ function apply(ctx, config) {
 					id: change.path,
 					sessionId: target.sessionId,
 					path: change.path,
-					kind: change.kind,
+					earlierVersion: change.earlierVersion,
 					oldText: change.oldText,
 					newText: change.newText,
 					updatedAt: now,
-					sessionIds: [target.sessionId]
+					sessionIds: [target.sessionId],
+					lineage: lineageOf(target.sessionId)
 				}));
 				let truncated = false;
 				if (target.includeUnchanged) {
@@ -5562,25 +7031,42 @@ function apply(ctx, config) {
 							id: file.path,
 							sessionId: target.sessionId,
 							path: file.path,
-							kind: "edit",
+							earlierVersion: "file",
 							oldText: file.content,
 							newText: file.content,
 							updatedAt: now,
-							sessionIds: [target.sessionId]
+							sessionIds: [target.sessionId],
+							lineage: lineageOf(target.sessionId)
 						});
 					}
 				}
 				return await admitNamed(candidates, isDirectory, truncated);
 			}
+			case "seen": {
+				const seen = payload ?? {};
+				if (typeof seen.id !== "string" || seen.id.length === 0) return rpcError("id must be a non-empty string");
+				await ensureLoaded();
+				if (store.markSeen(seen.id)) persistSession();
+				return {
+					ok: true,
+					value: { outcome: "seen" }
+				};
+			}
 			case "open": {
 				const target = openTargetOf(payload);
 				if (target === void 0) return rpcError("sessionId, id, and action must be valid");
 				await ensureLoaded();
-				const entry = store.get(target.id);
+				const lineage = lineageView();
+				let entry = actionableEntryOf(lineage, target.sessionId, target.id);
+				if (entry === void 0) {
+					await ensureLoaded();
+					entry = actionableEntryOf(lineage, target.sessionId, target.id);
+				}
 				if (entry === void 0) return {
 					ok: true,
 					value: { outcome: "missing" }
 				};
+				if (store.markSeen(entry.path)) persistSession();
 				try {
 					const resolved = await ctx.fs.resolve(entry.path, { signal });
 					await launchPath(ctx.fs.processPath(resolved), target.action);
@@ -5632,11 +7118,11 @@ function apply(ctx, config) {
 		return server.register(route);
 	}, "diff-approval: code font slices");
 	ctx.effect(() => ctx.on("fs/edit-intent", async (target, actor, next) => {
-		await stashEditorIntent(target, actor, "edit");
+		await stashEditorIntent(target, actor, "file");
 		return next();
 	}, { prepend: true }), "diff-approval: str_replace_editor edit basis");
 	ctx.effect(() => ctx.on("fs/write-intent", async (target, actor, next) => {
-		await stashEditorIntent(target, actor, "create");
+		await stashEditorIntent(target, actor, "none");
 		return next();
 	}, { prepend: true }), "diff-approval: str_replace_editor create basis");
 }