@lmzhen/dsh-evolution-core 0.3.66 → 0.3.68

package/lib/index.js

@@ -18,14 +18,24 @@ import { load } from "js-yaml";
 * node backend's V5-03 short-circuit).
 */
 async function transactIo(io, path, task) {
-	if (io.transact) {
+	const committedOnly = (error) => isCommittedWarning(error);
+	if (io.transact) try {
 		await io.transact(path, task);
 		return;
+	} catch (error) {
+		if (!committedOnly(error)) throw error;
+		console.warn(`evolution-io: ${path} was written but its directory fsync failed — the bytes are visible, durability is unconfirmed: ${error instanceof Error ? error.message : String(error)}`);
+		return;
 	}
 	const current = await io.readText(path);
 	const next = await task(current);
 	if (next === null) await io.remove(path);
-	else if (next !== current) await io.writeText(path, next);
+	else if (next !== current) try {
+		await io.writeText(path, next);
+	} catch (error) {
+		if (!committedOnly(error)) throw error;
+		console.warn(`evolution-io: ${path} was written but its directory fsync failed — the bytes are visible, durability is unconfirmed: ${error instanceof Error ? error.message : String(error)}`);
+	}
 }
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 function evolutionIoAdapter(provider) {
@@ -214,6 +224,72 @@ function parseLockBody(body) {
 	return match === null ? null : Number(match[1]);
 }
 /**
+* V27 G0.2 (EVO-IO-01): the write lock named by this claim is no longer ours
+* at the commit point — a takeover reclaimed it while we were inside the
+* critical section. The lock layer converts this into a retry of the whole
+* read-modify-write; it must never reach a caller as a successful write.
+*/
+var LostWriteLock = class extends Error {
+	constructor() {
+		super("evolution-io: the write lock was reclaimed before the commit");
+		this.name = "LostWriteLock";
+	}
+};
+/** V27 G1.4: every quarantine-copy name this family has ever produced —
+* `<file>.corrupt` (current fixed name), `<file>.corrupt.<epoch>`, and the
+* v10-05 legacy `<file>.corrupt-<epoch>-<rand>` series. A user support file
+* keeps a final extension (`.corrupt-backup.md`) and therefore stays. */
+const CORRUPT_COPY_RE = /\.corrupt(\.\d+|-\d+-[0-9a-z]+)?$/;
+/** V27 G1.1: the three takeover windows, as protocol constants at ONE place
+* (the inline copies that used to live in the acquisition loop, plus the dead
+* branch's bare `1000`, are gone). */
+/** A named holder that is gone, past this age, is reclaimed. Fits inside the
+* `lockAttempts * 50ms` retry budget so a dead holder's lock is reachable
+* within one budget (v19 gate arithmetic: budget >= 2 x threshold). */
+const DEAD_LOCK_TAKEOVER_MS = 1e3;
+/** No body at all: nothing attributes the lock to a holder, so this is the one
+* branch that cannot probe liveness — it must outlast any plausible stall
+* between create and body write (V27 G0.2: 1s was below what a loaded machine
+* actually took, which let a peer delete a live holder's lock). */
+const EMPTY_LOCK_TAKEOVER_MS = 3e4;
+/** A body with no parseable pid (crash mid-write): 1h, far above any legal hold
+* and far below "forever". */
+const LOCK_TEAR_TAKEOVER_MS = 36e5;
+/**
+* V27 G1.3: the error `commitTmp` throws when the rename landed but the parent
+* directory fsync failed — the bytes ARE visible, only their durability is
+* unconfirmed. A consumer that treats it as a plain failure reports "not
+* written" for a write that happened (and a two-phase caller may try to roll
+* back a visible write). Every transaction consumer must therefore treat this
+* shape as SUCCESS-with-warning, never as a rejection.
+*/
+function isCommittedWarning(error) {
+	return error?.committed === true;
+}
+/**
+* V27 G1.1: the lock-takeover decision as ONE pure function, so the protocol is
+* testable and exhaustive instead of being an inline expression inside the
+* acquisition loop:
+*   - `none`    the lock is fresh, or its holder is alive → wait, never steal;
+*   - `dead`    a named holder that is gone, past the dead threshold;
+*   - `empty`   no body at all: nothing attributes it to a holder, so only the
+*               wide `emptyAfterMs` window may reclaim it;
+*   - `corrupt` a body with no parseable pid (a crash mid-write), past the 1h
+*               tear threshold.
+* The age thresholds compare against `nowMs - mtimeMs` with `>` so a lock whose
+* age EQUALS the threshold is not yet reclaimed (the boundary the v19 gate fix
+* pinned).
+*/
+function decideTakeover(probe) {
+	const age = (probe.nowMs ?? Date.now()) - probe.mtimeMs;
+	const holder = Number(probe.body.split(":")[0] ?? "");
+	const namedHolder = Number.isInteger(holder) && holder > 0;
+	if (probe.body === "") return age > (probe.emptyAfterMs ?? 3e4) ? "empty" : "none";
+	if (!namedHolder) return age > (probe.corruptAfterMs ?? 36e5) ? "corrupt" : "none";
+	if (probe.alive(holder)) return "none";
+	return age > (probe.deadAfterMs ?? 1e3) ? "dead" : "none";
+}
+/**
 * Build the Node IO backend. `lockAttempts` scales the write-lock retry budget
 * (attempts × 50ms); the default 40 (~2s, rc.69) covers production contention,
 * while contention TESTS on a loaded runner may raise it (e.g. 240 ≈ 12s) —
@@ -228,14 +304,6 @@ function nodeEvolutionIo(lockAttempts = 40) {
 	/** True when the pid is alive (single source: `isProcessAlive`). */
 	const isAlive = isProcessAlive;
 	/**
-	* V10-07 (P2-1): age threshold for taking over a lock whose body is TORN
-	* (non-empty, but the pid prefix does not parse to a positive integer). 1h:
-	* a legal hold (the ~2s lock/rename retry budgets, a slow task) never
-	* approaches minutes, so 1h fires only in the "torn write + creator long
-	* dead" scenario — far above any legitimate hold, far below "forever".
-	*/
-	const LOCK_TEAR_TAKEOVER_MS = 36e5;
-	/**
 	* V10-06 (P1-1 integration fix): a takeover TICKET must never be reclaimed
 	* while its (live) holder can still be committing — the C-28 rename retry
 	* budget is ~2.35s under AV/indexer pressure, so the former 1s ticket age
@@ -280,31 +348,41 @@ function nodeEvolutionIo(lockAttempts = 40) {
 	* parseable pid) — is taken over after a wide 1h threshold with a
 	* console.warn; before this branch such a lock blocked every future writer
 	* forever.
+	* V27 G0.2 (EVO-IO-01): the CONTRACT for `task` is therefore: commit only
+	* after calling the `assertOwned` callback it receives, immediately before the
+	* rename (or delete) that publishes the result. A takeover may reclaim a lock
+	* whose holder is alive — an empty body cannot be attributed to a pid, and a
+	* peer can read a stale stat — and the holder cannot see it from the handle it
+	* opened (on POSIX its write lands on the UNLINKED inode). With the guard, a
+	* reclaimed claim aborts the RMW (`LostWriteLock`, converted into a retry
+	* here) instead of overwriting the current holder's result; without it, two
+	* writers commit and one update is silently lost.
 	*/
 	const withWriteLock = async (path, task) => {
 		const lock = `${path}${LOCK_SUFFIX}`;
 		let myClaim = "";
 		for (let attempt = 0; attempt < lockAttempts; attempt += 1) {
-			let lockHandle = null;
 			try {
 				myClaim = `${process.pid}:${randomBytes(4).toString("hex")}`;
-				lockHandle = await open(lock, "wx");
-				await lockHandle.writeFile(myClaim);
-				await lockHandle.close();
-				lockHandle = null;
+				await writeFile(lock, myClaim, { flag: "wx" });
 			} catch (error) {
 				const code = error?.code;
-				if (lockHandle) {
-					await lockHandle.close().catch(() => {});
+				if (code === "EEXIST" || code === "EPERM") {} else {
 					await rm(lock, { force: true }).catch(() => {});
 					throw error;
 				}
-				if (code !== "EEXIST" && code !== "EPERM") throw error;
 				try {
 					const st = await stat(lock);
-					const holderContent = await readFile(lock, "utf8").catch(() => "");
+					const holderRead = await readFile(lock, "utf8").then((body) => ({
+						ok: true,
+						body
+					}), () => ({
+						ok: false,
+						body: ""
+					}));
+					if (!holderRead.ok) continue;
+					const holderContent = holderRead.body;
 					const holder = Number(holderContent.split(":")[0] ?? "");
-					const holderAlive = Number.isInteger(holder) && holder > 0 && isAlive(holder);
 					if (holder === process.pid && pendingSelfCleanup.has(lock)) {
 						const token = pendingSelfCleanup.get(lock);
 						if (await readFile(lock, "utf8").catch(() => "") === token) try {
@@ -313,11 +391,13 @@ function nodeEvolutionIo(lockAttempts = 40) {
 						} catch {}
 						continue;
 					}
-					const staleDead = Number.isInteger(holder) && holder > 0 && Date.now() - st.mtimeMs > 1e3 && !holderAlive;
-					const staleEmpty = holderContent === "" && Date.now() - st.mtimeMs > 1e3;
-					const staleCorrupt = holderContent !== "" && !(Number.isInteger(holder) && holder > 0) && Date.now() - st.mtimeMs > LOCK_TEAR_TAKEOVER_MS;
-					if (staleDead || staleEmpty || staleCorrupt) {
-						if (staleCorrupt) console.warn(`evolution-io: took over a corrupt write lock "${lock}" (body ${JSON.stringify(holderContent)} has no parseable pid, lock older than 1h) — a previous writer likely crashed mid-write`);
+					const decision = decideTakeover({
+						body: holderContent,
+						mtimeMs: st.mtimeMs,
+						alive: isAlive
+					});
+					if (decision !== "none") {
+						console.warn(`evolution-io: taking over write lock ${lock} (branch=stale${decision[0]?.toUpperCase()}${decision.slice(1)}, body=${JSON.stringify(holderContent)}, ageMs=${Date.now() - st.mtimeMs}, holderPid=${Number.isInteger(holder) && holder > 0 ? holder : "none"})`);
 						if (await readFile(lock, "utf8").catch(() => "") === holderContent) {
 							const ticket = `${lock}.next`;
 							try {
@@ -357,8 +437,18 @@ function nodeEvolutionIo(lockAttempts = 40) {
 				await new Promise((resolve) => setTimeout(resolve, 50));
 				continue;
 			}
+			const assertOwned = async () => {
+				const body = await readFile(lock, "utf8").catch(() => null);
+				if (body !== myClaim) {
+					console.warn(`evolution-io: write lock ${lock} was reclaimed by another writer before the commit (on disk now: ${JSON.stringify(body)}, ours: ${JSON.stringify(myClaim)}) — aborting this read-modify-write and retrying under a fresh acquisition`);
+					throw new LostWriteLock();
+				}
+			};
 			try {
-				return await task();
+				return await task(assertOwned);
+			} catch (error) {
+				if (error instanceof LostWriteLock) continue;
+				throw error;
 			} finally {
 				if (await readFile(lock, "utf8").catch(() => null) === myClaim) await rm(lock, {
 					force: true,
@@ -426,7 +516,7 @@ function nodeEvolutionIo(lockAttempts = 40) {
 				} catch {}
 				continue;
 			}
-			if (/\.corrupt(\.\d+)?$/.test(name)) {
+			if (CORRUPT_COPY_RE.test(name)) {
 				const corruptPath = join(dir, name);
 				try {
 					const st = await stat(corruptPath);
@@ -446,14 +536,16 @@ function nodeEvolutionIo(lockAttempts = 40) {
 		},
 		async writeText(path, content) {
 			await mkdir(dirname(path), { recursive: true });
-			await withWriteLock(path, async () => {
+			await withWriteLock(path, async (assertOwned) => {
 				await sweepStaleTmps(path);
-				await commitTmp(await writeDurableTmp(path, content), path);
+				const tmp = await writeDurableTmp(path, content);
+				await assertOwned();
+				await commitTmp(tmp, path);
 			});
 		},
 		async transact(path, task) {
 			await mkdir(dirname(path), { recursive: true });
-			await withWriteLock(path, async () => {
+			await withWriteLock(path, async (assertOwned) => {
 				await sweepStaleTmps(path);
 				let current;
 				try {
@@ -464,11 +556,14 @@ function nodeEvolutionIo(lockAttempts = 40) {
 				}
 				const next = await task(current);
 				if (next === null) {
+					await assertOwned();
 					await rm(path, { force: true });
 					return;
 				}
 				if (next === current) return;
-				await commitTmp(await writeDurableTmp(path, next), path);
+				const tmp = await writeDurableTmp(path, next);
+				await assertOwned();
+				await commitTmp(tmp, path);
 			});
 		},
 		async remove(path) {
@@ -796,6 +891,14 @@ function parseSuppressed(raw) {
 	}
 }
 async function saveSuppressedNames(root, names, io = nodeEvolutionIo()) {
+	const current = await io.readText(suppressedFile(root)).catch(() => null);
+	if (current !== null) try {
+		const parsed = JSON.parse(current);
+		if (parsed !== null && typeof parsed.version === "number" && parsed.version > 1) {
+			console.warn(`suppression sidecar ${suppressedFile(root)} declares version ${String(parsed.version)} (newer than 1); not overwritten`);
+			return;
+		}
+	} catch {}
 	await io.writeText(suppressedFile(root), JSON.stringify({
 		version: 1,
 		names: [...names].sort()
@@ -809,10 +912,17 @@ async function saveSuppressedNames(root, names, io = nodeEvolutionIo()) {
 */
 async function updateSuppressedNames(root, io, task) {
 	await transactIo(io, suppressedFile(root), async (current) => {
-		if (current !== null) try {
-			JSON.parse(current);
-		} catch {
-			return current;
+		if (current !== null) {
+			let parsed = null;
+			try {
+				parsed = JSON.parse(current);
+			} catch {
+				return current;
+			}
+			if (parsed !== null && typeof parsed.version === "number" && parsed.version > 1) {
+				console.warn(`suppression sidecar ${suppressedFile(root)} declares version ${String(parsed.version)} (newer than 1); not overwritten`);
+				return current;
+			}
 		}
 		const names = parseSuppressed(current);
 		await task(names);
@@ -920,6 +1030,20 @@ const EVOLUTION_WRITE_TOOLS = ["memory", "skill_manage"];
 * 0.3.16 (T-4): moved here from skill-store.ts so drift-signals (pure, no IO)
 * can reference it without importing the skill-store module. */
 const AUTHORING_DESCRIPTION_BAR = 60;
+/** V27 G2.4: the largest millisecond delay a timer accepts. `AbortSignal.timeout`
+* (and `setTimeout`) coerce anything larger to 1ms after a Node warning, so a
+* timeout configured above this ceiling silently collapses to "immediately
+* aborted". The curator's review timeout and the review timeout each carried
+* their own copy of the literal; the bound is one protocol constant.
+* (v19 P2-10 corrected the value from 2^32-1 to Node's real 2^31-1 ceiling.) */
+const MAX_TIMER_DELAY_MS = 2147483647;
+/** V27 G2.4: the model each review/curation leg defaults to. The policy schema,
+* the policy resolver and the curator's LLM nomination pass each carried their
+* own copy of these strings — a deployment that changed the policy default used
+* to leave the curator passing a different model than the reviews. */
+const DEFAULT_MEMORY_REVIEW_MODEL = "deepseek-v4-flash";
+const DEFAULT_SKILL_REVIEW_MODEL = "deepseek-v4-pro";
+const DEFAULT_CURATOR_MODEL = "deepseek-v4-pro";
 //#endregion
 //#region lib/types/gates.js
 /**
@@ -987,6 +1111,8 @@ function buildCuratorRunReport(input) {
 		archiveCandidates: [...input.archiveCandidates],
 		archived: [...input.archived],
 		failed: [...input.failed],
+		...input.aborted === void 0 ? {} : { aborted: input.aborted },
+		...input.unattributed === void 0 || input.unattributed.length === 0 ? {} : { unattributed: [...input.unattributed] },
 		...input.consolidated === void 0 ? {} : { consolidated: [...input.consolidated] },
 		...input.snapshotPath === void 0 ? {} : { snapshotPath: input.snapshotPath },
 		...input.llmReviewEnabled === void 0 ? {} : { llmReviewEnabled: input.llmReviewEnabled },
@@ -1008,6 +1134,8 @@ function renderCuratorReportMarkdown(report) {
 		`- **LLM nominations**: ${report.llmNominations.length}`,
 		`- **Archived**: ${report.archived.length}`,
 		`- **Failed**: ${report.failed.length}`,
+		...report.aborted === void 0 ? [] : [`- **Aborted**: ${report.aborted}`],
+		...report.unattributed === void 0 || report.unattributed.length === 0 ? [] : [`- **Unattributed errors**: ${report.unattributed.length}`],
 		...report.snapshotPath === void 0 ? [] : [`- **Snapshot**: ${report.snapshotPath}`],
 		...report.llmReviewEnabled === void 0 ? [] : [`- **llmReview**: ${report.llmReviewEnabled}`],
 		...report.nominationsWarnings === void 0 || report.nominationsWarnings.length === 0 ? [] : [`- **Nomination warnings**: ${report.nominationsWarnings.join("; ")}`]
@@ -1022,6 +1150,7 @@ function renderCuratorReportMarkdown(report) {
 		...lines,
 		...section("Archived", report.archived.map((item) => `${item.name} (${item.reason})`)),
 		...section("Failed", report.failed.map((item) => `${item.name}: ${item.reason}`)),
+		...section("Unattributed", report.unattributed ?? []),
 		...section("Stale candidates", report.staleCandidates),
 		...section("LLM nominations", report.llmNominations),
 		""
@@ -1180,15 +1309,6 @@ function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Da
 				});
 				result.markStale.push(name);
 			}
-		} else if (idle < staleAfterDays) {
-			record.state = "active";
-			result.transitions.push({
-				name,
-				from: "stale",
-				to: "active",
-				reason: `recent activity ${Math.round(idle)}d`
-			});
-			result.reactivate.push(name);
 		} else if (idle >= config.archiveAfterDays) {
 			record.state = "archived";
 			record.archived_at = now.toISOString();
@@ -1199,6 +1319,15 @@ function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Da
 				reason: `idle ${Math.round(idle)}d >= ${config.archiveAfterDays}d`
 			});
 			result.archive.push(name);
+		} else if (idle < staleAfterDays) {
+			record.state = "active";
+			result.transitions.push({
+				name,
+				from: "stale",
+				to: "active",
+				reason: `recent activity ${Math.round(idle)}d`
+			});
+			result.reactivate.push(name);
 		}
 	}
 	return result;
@@ -1215,12 +1344,15 @@ function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Da
 *
 * Usage events (C semantics, rc.73+): `type:'usage'` records are the
 * OBSERVATION WINDOW ANCHOR — written once, when the library's first observed
-* read (`view_count` 0 -> 1) happens. Before that anchor the usage sidecar
-* has no read evidence (reads were invisible pre-A2), so churn-based health
-* judgments are NOT trustworthy; the curator suppresses them (its
-* `usageObserved()` gate) until the anchor exists. `counts` on the event is a
-* cumulative library-wide snapshot (skills/views/use/patches) at that moment,
-* and `window.opened` pins the window start for the timeline.
+* read (`view_count` 0 -> 1) happens. The anchor is the durable timeline record
+* of that moment: the churn-suppression gate itself (`usageObserved()`) reads
+* the usage SIDECAR's own first-view evidence, since reads were invisible to it
+* pre-A2 and no sidecar record can reach `view_count > 0` without the same
+* 0 -> 1 transition. `counts` on the event is a cumulative library-wide
+* snapshot (skills/views/use/patches) at that moment, and `window.opened` pins
+* the window start for the timeline. (V27 G3.3: `verify-event-pairing` requires
+* every persisted type to have a production reader or a declared external
+* contract — this one is the latter.)
 *
 * Rotation (rc.71, 007 design): when the active log reaches
 * `EVENT_LOG_ROTATE_AT` the older half is split into an archive
@@ -2233,7 +2365,8 @@ const PATTERNS = [
 		regex: /(?:密钥|凭据|口令|密码|环境变量)[\s\S]{0,30}(?:发送|上传|传输|外传|泄露)[\s\S]{0,30}(?:到|至)\s*(?:https?:\/\/|[\w.-]+\.(?:com|net|org|io|cn|dev|xyz|ru)\b)/
 	}
 ];
-const ZERO_WIDTH_CHARS = new RegExp(`[\\u034f\\u200b\\u2060\\u2061\\u2062\\u2063\\u2064\\u206a-\\u206f\\ufeff\\u{e0000}-\\u{e007f}]`, "u");
+const INVISIBLE_CHAR_CLASS = "\\u034f\\u200b\\u2060\\u2061\\u2062\\u2063\\u2064\\u206a-\\u206f\\ufeff\\u{e0000}-\\u{e007f}";
+const ZERO_WIDTH_CHARS = new RegExp(`[${INVISIBLE_CHAR_CLASS}]`, "u");
 const ZWJ_OUTSIDE_EMOJI = /(?<!\p{Extended_Pictographic})\u200d(?!\p{Extended_Pictographic})/u;
 const TYPOGRAPHY_CHARS = /[\u00ad\u061c\u180e\u200c\ufe00-\ufe0f]/;
 const BIDI_CHARS = /[\u202a-\u202e\u2066-\u2069]/;
@@ -2280,7 +2413,8 @@ function scanThreats(text, scope = "strict", maxScanChars = 65536, options = NO_
 	});
 	const normalized = text.normalize("NFKC");
 	const SPACE_SPLITTERS = /[\u00ad\u061c\u180e\u200c\ufe00-\ufe0f]/gu;
-	const patternTexts = [normalized.replace(SPACE_SPLITTERS, " "), normalized.replace(SPACE_SPLITTERS, "")];
+	const OBFUSCATION_SPLITTERS = new RegExp(`[${INVISIBLE_CHAR_CLASS}\\u200d]`, "gu");
+	const patternTexts = [normalized.replace(SPACE_SPLITTERS, " ").replace(OBFUSCATION_SPLITTERS, " "), normalized.replace(SPACE_SPLITTERS, "").replace(OBFUSCATION_SPLITTERS, "")];
 	const windows = [];
 	for (const patternText of patternTexts) if (patternText.length <= windowSize) windows.push(patternText);
 	else {
@@ -2548,25 +2682,25 @@ var MemoryStore = class {
 			limit: this.limitFor(target)
 		};
 	}
-	async add(target, facts) {
-		return await this.serial(() => this.addChained(target, facts));
-	}
-	async addChained(target, facts) {
-		if (!facts.trim()) return {
-			ok: false,
-			message: "Content cannot be empty.",
-			entries: [],
-			chars: 0,
-			limit: this.limitFor(target)
-		};
-		const path = fileFor(this.root, target);
+	/**
+	* The ONE memory write skeleton (V27 G2.5): oversized read-guard pre-transact,
+	* one transaction over the target path, and the C-01 structured refusal when a
+	* backend never invokes the task. `addChained` and `applyBatchChained` supply
+	* only their own in-transaction core, so the two write paths cannot drift in
+	* their guard order, their missing-file handling or their error text.
+	*
+	* @param target - memory target being written
+	* @param core - the in-transaction read-modify-write for the locked body
+	* @returns the core's result, or the oversized / contract-violation refusal
+	*/
+	async chainedWrite(target, core) {
 		const refusal = await this.oversizedRefusal(target);
 		if (refusal) return refusal;
 		let outcome;
-		await transactIo(this.io, path, async (current) => {
-			const core = await this.addCore(target, facts, current ?? "");
-			outcome = core.result;
-			return core.write ?? current ?? null;
+		await transactIo(this.io, fileFor(this.root, target), async (current) => {
+			const step = await core(current ?? "");
+			outcome = step.result;
+			return step.write ?? current ?? null;
 		});
 		return outcome ?? {
 			ok: false,
@@ -2576,6 +2710,19 @@ var MemoryStore = class {
 			limit: this.limitFor(target)
 		};
 	}
+	async add(target, facts) {
+		return await this.serial(() => this.addChained(target, facts));
+	}
+	async addChained(target, facts) {
+		if (!facts.trim()) return {
+			ok: false,
+			message: "Content cannot be empty.",
+			entries: [],
+			chars: 0,
+			limit: this.limitFor(target)
+		};
+		return await this.chainedWrite(target, async (raw) => await this.addCore(target, facts, raw));
+	}
 	/**
 	* Single-entry add inside the transaction: shared checks (oversized,
 	* drift, threat) and the content computation. `raw` is the locked view
@@ -2593,19 +2740,11 @@ var MemoryStore = class {
 			},
 			write: null
 		};
-		if (this.driftFromRaw(target, raw)) {
-			const backup = await this.backupFile(target);
-			return {
-				result: {
-					ok: false,
-					message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
-					entries: [],
-					chars: 0,
-					limit: this.limitFor(target)
-				},
-				write: null
-			};
-		}
+		const refusal = await this.driftRefusal(target, raw);
+		if (refusal) return {
+			result: refusal,
+			write: null
+		};
 		const threat = this.memoryThreatBlock(content);
 		if (threat) return {
 			result: {
@@ -2661,14 +2800,52 @@ var MemoryStore = class {
 			write: render(next)
 		};
 	}
-	/** Canonical-form drift check derived from the locked view (same formula as `detectDrift`, no second read). */
-	driftFromRaw(target, raw) {
-		if (raw.trim() === "") return false;
+	/**
+	* The single drift predicate. `raw` is in canonical form when it byte-matches
+	* `render(normalizeEntries(raw))`; anything else means it was edited outside
+	* MemoryStore (empty/`§`-only entries, stray blank lines, leading or trailing
+	* delimiters — structural anomalies the writer would quietly normalize away).
+	* Both write paths derive this from their locked view and `detectDrift` from
+	* a fresh read, so a write and a later read can never disagree about the same
+	* bytes.
+	*
+	* An absent, empty, or whitespace-only body is the "never written" state
+	* (rc.42 audit P1-6): it parses to zero entries, and the canonical form
+	* `'\n'` can never byte-match it, so flagging it would permanently refuse
+	* every write path — including the repairs the model would need to make.
+	* Such files are adopted instead of flagged.
+	*
+	* @param target - memory target whose char limit bounds one parsed entry
+	* @param raw - on-disk body, or `null` when the file does not exist
+	* @returns whether these bytes count as externally drifted
+	*/
+	drifted(target, raw) {
+		if (raw === null || raw.trim() === "") return false;
 		const entries = normalizeEntries(raw);
 		const limit = this.limitFor(target);
 		if (limit > 0 && entries.some((entry) => entry.length > limit)) return true;
 		return render(entries) !== raw;
 	}
+	/**
+	* Drift refusal for a body already read under the write lock, or `null` when
+	* the body is canonical. Both write paths return this unchanged, so their
+	* refusals stay byte-identical and each carries the same backup.
+	*
+	* @param target - memory target that owns the drifted file
+	* @param raw - locked file body
+	* @returns the refusal to hand back, or `null` to continue writing
+	*/
+	async driftRefusal(target, raw) {
+		if (!this.drifted(target, raw)) return null;
+		const backup = await this.backupFile(target);
+		return {
+			ok: false,
+			message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
+			entries: [],
+			chars: 0,
+			limit: this.limitFor(target)
+		};
+	}
 	async applyBatch(target, operations) {
 		return await this.serial(() => this.applyBatchChained(target, operations));
 	}
@@ -2680,38 +2857,15 @@ var MemoryStore = class {
 			chars: 0,
 			limit: this.limitFor(target)
 		};
-		const path = fileFor(this.root, target);
-		const refusal = await this.oversizedRefusal(target);
-		if (refusal) return refusal;
-		let outcome;
-		await transactIo(this.io, path, async (current) => {
-			const core = await this.applyBatchCore(target, operations, current ?? "");
-			outcome = core.result;
-			return core.write ?? current ?? null;
-		});
-		return outcome ?? {
-			ok: false,
-			message: "internal error: the memory transaction did not invoke the task; no write was performed",
-			entries: [],
-			chars: 0,
-			limit: this.limitFor(target)
-		};
+		return await this.chainedWrite(target, async (raw) => await this.applyBatchCore(target, operations, raw));
 	}
 	/** Batch RMW inside the transaction. `write: null` = failure/no-op, disk untouched. */
 	async applyBatchCore(target, operations, raw) {
-		if (this.driftFromRaw(target, raw)) {
-			const backup = await this.backupFile(target);
-			return {
-				result: {
-					ok: false,
-					message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
-					entries: [],
-					chars: 0,
-					limit: this.limitFor(target)
-				},
-				write: null
-			};
-		}
+		const refusal = await this.driftRefusal(target, raw);
+		if (refusal) return {
+			result: refusal,
+			write: null
+		};
 		const entries = [...new Set(normalizeEntries(raw))];
 		const working = [...entries];
 		const datePrefix = this.addDatePrefix ? `## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}\n` : "";
@@ -2881,27 +3035,17 @@ var MemoryStore = class {
 		return parts.join("\n\n");
 	}
 	/**
-	* Detect on-disk drift: true when the file is not in the canonical
-	* `render(normalizeEntries(raw))` form. This catches structural anomalies
-	* the writer would quietly normalize away (empty/`§`-only entries, stray
-	* blank lines, leading/trailing delimiters) that indicate the file was
-	* edited outside MemoryStore. Purely single-canonical content reaches the
-	* same serialization and returns false, so a normal write is never flagged.
+	* Detect on-disk drift for a caller that holds no locked view: `true` when the
+	* file is not in canonical form, or when its size trips the read guard. The
+	* write paths apply the same predicate (`drifted`) to the body they read under
+	* the lock, so a write and a follow-up read agree about the same bytes.
 	*
-	* An absent, empty, or whitespace-only file is the "never written" state
-	* (rc.42 audit P1-6): it parses to zero entries, so the canonical form
-	* `'\n'` can never byte-match it and every write path was permanently
-	* refused with "External drift detected" — including the repairs the model
-	* would need to make. Such files are adopted instead of flagged.
+	* @param target - memory target to inspect
+	* @returns whether the file on disk counts as externally drifted
 	*/
 	async detectDrift(target) {
 		if (await this.oversizedFile(target)) return true;
-		const raw = await this.io.readText(fileFor(this.root, target));
-		if (raw === null || raw.trim() === "") return false;
-		const entries = normalizeEntries(raw);
-		const limit = this.limitFor(target);
-		if (limit > 0 && entries.some((entry) => entry.length > limit)) return true;
-		return render(entries) !== raw;
+		return this.drifted(target, await this.io.readText(fileFor(this.root, target)));
 	}
 };
 //#endregion
@@ -3243,7 +3387,7 @@ const SECRET_PATTERNS = [
 	["google api key", /AIza[0-9A-Za-z_-]{30,}/g],
 	["bearer credential", /Bearer[\s]+[a-z0-9._~+/=\-]{16,}/gi]
 ];
-const INLINE_ASSIGNMENT_PATTERN = /* @__PURE__ */ new RegExp("(^|[^\\w-])([\\w-]{0,64}[_\\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\\-][\\w-]{0,64})?)\\b([\\t ]*[:=][\\t ]*)([^\\r\\n]+)", "gi");
+const INLINE_ASSIGNMENT_PATTERN = /* @__PURE__ */ new RegExp("(^|[^\\w-])([\\w-]{0,64}[_\\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\\-][\\w-]{0,64})?)\\b([\"\\']?[\\t ]*[:=][\\t ]*)([^\\r\\n]+)", "gi");
 const URL_CREDENTIALS_PATTERN = /([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)([^\s/@]+)@/gi;
 /**
 * Mask credential-shaped text before it crosses a session boundary.
@@ -3639,28 +3783,28 @@ function skillsRoot(env = process.env) {
 function resolveSkillsRoot(config = {}) {
 	return (config.root ?? "").trim() || skillsRoot();
 }
-/** E-7 (v18): every family row reads ONE root key. `root` is canonical;
-* `skillsRoot` is a deprecated alias honoured only while `root` is empty (so a
-* deployment that sets both keeps the canonical one) and removed after 0.3.65.
-* Callers log their own deprecation warning.
-* @param config - the raw plugin config, carrying `root` and/or `skillsRoot`.
-* @returns the effective root (empty when neither key is set) and whether the
-* deprecated alias supplied it.
+/** E-7 (v18) → V27 G2.4 (M-08): every family row reads ONE root key. `root` is
+* canonical; the `skillsRoot` alias was honoured for one minor version and its
+* window closed at 0.3.65 — it is now two releases past expiry, so this
+* resolver no longer reads it at all. A deployment that still sets the alias
+* must fail LOUDLY at load (see {@link assertSkillsRootAliasRetired}): silently
+* ignoring a config key leaves the deployment pointing at a root nobody reads,
+* which is the worst form of compatibility.
+* @param config - the raw plugin config.
+* @returns the effective root (empty when the key is unset or blank).
 */
 function resolveRootConfig(config = {}) {
-	const root = (config.root ?? "").trim();
-	if (root !== "") return {
-		root,
-		usedDeprecatedAlias: false
-	};
-	const alias = (config.skillsRoot ?? "").trim();
-	return alias === "" ? {
-		root: "",
-		usedDeprecatedAlias: false
-	} : {
-		root: alias,
-		usedDeprecatedAlias: true
-	};
+	return { root: (config.root ?? "").trim() };
+}
+/** V27 G2.4 (M-08): the retirement gate for the expired `skillsRoot` alias.
+* Called at each plugin's load boundary (before the root is resolved), it turns
+* a stale key into an explicit load error naming the replacement — the
+* fail-loud form the plan requires instead of a silent no-op.
+* @param config - the raw plugin config (the alias field stays DECLARED in each
+* schema so the loader can hand it here instead of dropping it).
+*/
+function assertSkillsRootAliasRetired(config = {}) {
+	if ((config.skillsRoot ?? "").trim() !== "") throw new Error("evolution: config \"skillsRoot\" was removed after 0.3.65 — rename the key to \"root\" (the alias is no longer honoured)");
 }
 /**
 * Map a requesting session onto the two origin surfaces (rc.44 plan M2-2.3):
@@ -3714,21 +3858,28 @@ function markerPath(dir, marker) {
 }
 /**
 * Shared frontmatter block detection (P3-3 single owner): opening line `---`
-* and closing line exactly `---` (both trimmed). Used by `parseFrontmatter`,
+* and closing line exactly `---`. Used by `parseFrontmatter`,
 * `frontmatterYamlUnsafeValues` and `normalizeFrontmatter` so the three can
 * never disagree about where the block ends (the loose `indexOf('\n---')`
 * form matched `\n----` and was replaced by this strict line rule).
+*
+* V27 G2.1: both fence lines are matched EXACTLY, tolerating only a trailing
+* `\r` — the same rule the upstream filesystem catalog uses
+* (`skill-filesystem.parseFrontmatter`). The former `.trim()` comparison
+* accepted ` --- `, so an indented fence loaded in the family while the
+* platform ignored the file: family visibility split from platform visibility,
+* which is exactly what a strict-YAML frontmatter is supposed to prevent.
 */
 function frontmatterBlock(content) {
 	if (!content.trimStart().startsWith("---")) return null;
 	const nl = content.includes("\r\n") ? "\r\n" : "\n";
 	const lines = content.split(nl);
-	if ((lines[0] ?? "").trim() !== "---") return null;
+	if ((lines[0] ?? "").replace(/\r$/, "") !== "---") return null;
 	let end = -1;
 	for (let i = 1; i < lines.length; i++) {
 		const line = lines[i];
 		if (line === void 0) continue;
-		if (line.trim() === "---") {
+		if (line.replace(/\r$/, "") === "---") {
 			end = i;
 			break;
 		}
@@ -3741,24 +3892,176 @@ function frontmatterBlock(content) {
 		nl
 	};
 }
-function parseFrontmatter(content) {
+/**
+* Raw-line scan of a frontmatter block: the single owner of "which entries the
+* strict catalog cannot load". `frontmatterYamlUnsafeValues` publishes it and
+* `normalizeFrontmatter` decides each rewrite with the same predicate
+* (`yamlPlainScalarNeedsQuotes`), so the audit verdict and the write path can
+* never disagree. Only single-line `key: value` entries are judged; a line with
+* embedded breaks is skipped.
+*/
+function unsafeFrontmatterEntries(block, nl) {
+	const found = [];
+	for (const line of block.split(nl)) {
+		if (line.includes("\n") || line.includes("\r")) continue;
+		const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+		if (!match) continue;
+		const key = match[1];
+		if (key === void 0) continue;
+		const value = (match[2] ?? "").trim();
+		if (yamlPlainScalarNeedsQuotes(value)) found.push({
+			key,
+			value
+		});
+	}
+	return found;
+}
+/**
+* Frontmatter values as the STRICT platform catalog reads them — js-yaml, the
+* parser `normalizeFrontmatter` also verifies rewrites with — or `null` when
+* the block is not loadable as a YAML mapping.
+*
+* Scalars publish their text (`name`, `description`, `whenToUse` are strings by
+* contract; a number/boolean-shaped value keeps the text the family always
+* published), a flow or block sequence publishes its inline `[a, b]` form
+* (`relatedSkillNames` scans names out of it), and a nested mapping publishes
+* nothing — no consumer in this family reads one, and a lossy string could be
+* picked up by a routing field. A string value is trimmed: YAML's block-scalar
+* chomping appends a newline that the family's single-line routing fields never
+* carried.
+*/
+function strictFrontmatterValues(block) {
+	if (block.trim() === "") return /* @__PURE__ */ new Map();
+	let loaded;
+	try {
+		loaded = load(block);
+	} catch {
+		return null;
+	}
+	if (loaded === null || loaded === void 0) return /* @__PURE__ */ new Map();
+	if (typeof loaded !== "object" || Array.isArray(loaded)) return null;
+	const values = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(loaded)) {
+		if (typeof value === "string") {
+			values.set(key, value.trim());
+			continue;
+		}
+		if (typeof value === "number" || typeof value === "boolean") {
+			values.set(key, String(value));
+			continue;
+		}
+		if (Array.isArray(value)) {
+			values.set(key, `[${value.map((item) => String(item)).join(", ")}]`);
+			continue;
+		}
+	}
+	return values;
+}
+/**
+* Lenient line scan, used only for a block the strict parser rejects: the
+* family keeps routing a legacy file the platform refuses, and
+* `catalogInvalid` reports the split instead of hiding it. Values are trimmed
+* and unquoted exactly as before.
+*/
+function lenientFrontmatterValues(block, nl) {
+	const values = /* @__PURE__ */ new Map();
+	const blockLines = block.split(nl);
+	for (let i = 0; i < blockLines.length; i += 1) {
+		const line = blockLines[i] ?? "";
+		const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+		if (!match) continue;
+		const [, key, value] = match;
+		if (key === void 0 || value === void 0) continue;
+		const header = /^([>|])[+-]?\d*$/.exec(value.trim());
+		if (header !== null) {
+			const fold = header[1] === ">";
+			const parts = [];
+			let scan = i + 1;
+			for (; scan < blockLines.length; scan += 1) {
+				const raw = blockLines[scan] ?? "";
+				if (raw.trim() === "") {
+					parts.push("");
+					continue;
+				}
+				if (!/^\s/.test(raw)) break;
+				parts.push(raw.trim());
+			}
+			while (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
+			let folded = "";
+			for (const part of parts) {
+				if (part === "") {
+					if (folded !== "" && !folded.endsWith("\n")) folded += "\n";
+					continue;
+				}
+				if (folded === "" || folded.endsWith("\n")) folded += part;
+				else folded += ` ${part}`;
+			}
+			values.set(key, (fold ? folded : parts.join("\n")).trim());
+			i = scan - 1;
+			continue;
+		}
+		values.set(key, value.trim().replace(/^["']|["']$/g, ""));
+	}
+	return values;
+}
+/**
+* The single read of a SKILL.md frontmatter block: values, body and every
+* strict-catalog signal, computed once. `null` only when the file has no
+* frontmatter block; the body may be empty. {@link parseFrontmatter} and
+* {@link frontmatterCatalogInvalid} are its two projections.
+*
+* @param content - the SKILL.md text.
+* @returns the block read, or `null` when there is no block.
+*/
+function readFrontmatterBlock(content) {
 	const found = frontmatterBlock(content);
 	if (!found) return null;
 	const body = found.lines.slice(found.end + 1).join(found.nl).trim();
-	if (!body) return null;
+	const strict = strictFrontmatterValues(found.block);
+	const values = strict ?? lenientFrontmatterValues(found.block, found.nl);
 	const frontmatter = {};
-	for (const line of found.block.split(found.nl)) {
-		const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
-		if (match) {
-			const [, key, value] = match;
-			if (key && value !== void 0) frontmatter[key] = value.trim().replace(/^["']|["']$/g, "");
-		}
-	}
+	for (const [key, value] of values) frontmatter[key] = value;
 	return {
 		frontmatter,
-		body
+		body,
+		unsafeValues: unsafeFrontmatterEntries(found.block, found.nl),
+		strictFailed: strict === null
+	};
+}
+/**
+* Parse a SKILL.md: its frontmatter values and body, or `null` when the file
+* has no frontmatter block or no body. Every consumer of frontmatter values
+* goes through here — the write path's validation, `list()`'s published
+* description, `relatedSkillNames` and the audit — so all of them read the same
+* bytes the same way.
+*
+* @param content - the SKILL.md text.
+* @returns the read, or `null` when there is no block or no body.
+*/
+function parseFrontmatter(content) {
+	const read = readFrontmatterBlock(content);
+	if (!read || !read.body) return null;
+	return {
+		frontmatter: read.frontmatter,
+		body: read.body,
+		unsafeValues: read.unsafeValues,
+		catalogInvalid: read.strictFailed || read.unsafeValues.length > 0
 	};
 }
+/**
+* Whether this file's frontmatter is valid as written for the strict platform
+* catalog (see `FrontmatterRead.catalogInvalid`). Body-independent (a body-less
+* file is still judged), and derived from the same read as `parseFrontmatter` —
+* so the audit's verdict and the values the family publishes for one file can
+* never disagree (V27 G2.1).
+*
+* @param content - the SKILL.md text.
+* @returns `true` when the strict parser rejects the block or an unquoted value would read as something else.
+*/
+function frontmatterCatalogInvalid(content) {
+	const read = readFrontmatterBlock(content);
+	return read === null ? false : read.strictFailed || read.unsafeValues.length > 0;
+}
 /** YAML plain-scalar hazards that make an UNQUOTED frontmatter value
 * unloadable to the platform catalog (strict YAML parser): `: ` (mapping
 * separator), ` #` (comment start), a trailing `:` (a mapping marker),
@@ -3777,6 +4080,7 @@ function yamlPlainScalarNeedsQuotes(value) {
 	if (value.length === 0) return false;
 	if (value.length >= 2 && (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'"))) return false;
 	if (/^\[.*\]$/.test(value) || /^\{.*\}$/.test(value)) return false;
+	if (/^[>|][+-]?\d*$/.test(value)) return false;
 	if (value.includes(": ")) return true;
 	if (value.includes(" #")) return true;
 	if (value.endsWith(":")) return true;
@@ -3788,24 +4092,13 @@ function yamlPlainScalarNeedsQuotes(value) {
 * YAML-unsafe for the strict platform catalog. Operates on the ORIGINAL line
 * value (quotes included), so a value already wrapped by
 * `normalizeFrontmatter` is never re-flagged — one source with the write
-* path. Single-line entries only; lines with embedded line breaks skip. */
+* path. V27 G2.1: delegates to the shared scan, which
+* `parseFrontmatter(...).catalogInvalid` also uses, so the audit view and the
+* read view of one file can never disagree. Independent of the body: a
+* body-less file is still reported here. */
 function frontmatterYamlUnsafeValues(content) {
-	const found = [];
 	const block = frontmatterBlock(content);
-	if (!block) return found;
-	for (const line of block.block.split(block.nl)) {
-		if (line.includes("\n") || line.includes("\r")) continue;
-		const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
-		if (!match) continue;
-		const key = match[1];
-		const value = (match[2] ?? "").trim();
-		if (key === void 0) continue;
-		if (yamlPlainScalarNeedsQuotes(value)) found.push({
-			key,
-			value
-		});
-	}
-	return found;
+	return block === null ? [] : unsafeFrontmatterEntries(block.block, block.nl);
 }
 /**
 * Normalize a SKILL.md frontmatter block into catalog-loadable YAML: values
@@ -3916,7 +4209,7 @@ function relatedSkillNames(content, exclude) {
 }
 function validateFrontmatter(content, expectedName, limits = DEFAULT_SKILL_LIMITS) {
 	const parsed = parseFrontmatter(content);
-	if (!parsed) return "SKILL.md must start and end with YAML frontmatter and include a body.";
+	if (!parsed) return "SKILL.md must start with a `---` line, close the frontmatter with another exact `---` line (only a trailing `\\r` is tolerated), and include a body below it.";
 	if (!parsed.frontmatter.name) return "Frontmatter must include a name field.";
 	if (!SKILL_NAME_RE.test(parsed.frontmatter.name)) return `Invalid skill name "${parsed.frontmatter.name}" — use lowercase letters, digits, and hyphens.`;
 	if (parsed.frontmatter.name.length > limits.maxNameLength) return `Skill name exceeds ${limits.maxNameLength} characters.`;
@@ -4804,6 +5097,8 @@ var SkillLibrary = class {
 				},
 				write: null
 			};
+			const anchorCount = oldString === "" ? 0 : md.split(oldString).length - 1;
+			const patchNote = !replaceAll && anchorCount > 1 ? ` Replaced the FIRST of ${anchorCount} occurrences; pass replace_all=true to change every one.` : "";
 			let writeContent = patched;
 			let normalizedFields;
 			if (target === skillMd) {
@@ -4871,7 +5166,7 @@ var SkillLibrary = class {
 			return {
 				result: {
 					ok: true,
-					message: `Skill "${name}" patched (${patchLabel}).`,
+					message: `Skill "${name}" patched (${patchLabel}).${patchNote}`,
 					path: dir,
 					...normalizedFields ? { normalizedFrontmatterFields: normalizedFields } : {}
 				},
@@ -5085,6 +5380,9 @@ var SkillLibrary = class {
 		try {
 			await this.io.writeText(join(dest, ".archive-reason"), `${(/* @__PURE__ */ new Date()).toISOString()}: ${reason}\n`);
 		} catch {}
+		try {
+			await this.io.writeText(join(dest, ".archive-name"), `${name}\n`);
+		} catch {}
 		await this.audit(name, "archive", md, null, reason);
 		this.notifyMutation({
 			action: "archive",
@@ -5211,10 +5509,12 @@ var SkillLibrary = class {
 				};
 				const writes = [];
 				for (const reference of referenceWrites) {
-					const base = (await this.io.readText(reference.target).catch(() => null))?.trimEnd() ?? "";
+					const previous = await this.io.readText(reference.target).catch(() => null);
+					const base = previous?.trimEnd() ?? "";
 					writes.push({
 						target: reference.target,
-						content: base === "" ? reference.content : `${base}\n\n${reference.content}`
+						content: base === "" ? reference.content : `${base}\n\n${reference.content}`,
+						expected: previous
 					});
 				}
 				if (mode === "append") {
@@ -5226,7 +5526,8 @@ var SkillLibrary = class {
 					};
 					writes.push({
 						target: join(targetDir, "SKILL.md"),
-						content: merged
+						content: merged,
+						expected: freshTargetMd
 					});
 				} else {
 					const pointerLines = normalizedSources.map((source) => `\n${POINTER_LINE_PREFIX}${source}.md`).join("");
@@ -5238,7 +5539,8 @@ var SkillLibrary = class {
 					};
 					writes.push({
 						target: join(targetDir, "SKILL.md"),
-						content: extended
+						content: extended,
+						expected: freshTargetMd
 					});
 				}
 				return await this.applyTreeChange({
@@ -5306,6 +5608,11 @@ var SkillLibrary = class {
 			message: `Restructure exceeds 5 moves.`
 		};
 		for (const move of moves) {
+			const raw = move;
+			if (raw === null || typeof raw !== "object") return {
+				ok: false,
+				message: "Every restructure move must be an object with a heading."
+			};
 			if (typeof move.heading !== "string" || !move.heading.trim()) return {
 				ok: false,
 				message: "Every restructure move needs a non-empty heading."
@@ -5359,15 +5666,18 @@ var SkillLibrary = class {
 		const writes = [];
 		for (const entry of byRel.values()) {
 			const target = join(dir, ...entry.rel.split("/"));
-			const base = (await this.io.readText(target).catch(() => null))?.trimEnd() ?? "";
+			const previous = await this.io.readText(target).catch(() => null);
+			const base = previous?.trimEnd() ?? "";
 			writes.push({
 				target,
-				content: base === "" ? entry.texts.join("\n\n") : `${base}\n\n${entry.texts.join("\n\n")}`
+				content: base === "" ? entry.texts.join("\n\n") : `${base}\n\n${entry.texts.join("\n\n")}`,
+				expected: previous
 			});
 		}
 		writes.push({
 			target: join(dir, "SKILL.md"),
-			content: finalMd
+			content: finalMd,
+			expected: md
 		});
 		const result = await this.applyTreeChange({
 			name,
@@ -5433,7 +5743,8 @@ var SkillLibrary = class {
 			landing.push({
 				target: write.target,
 				content: write.content,
-				previous
+				previous,
+				expected: write.expected
 			});
 		}
 		const written = [];
@@ -5442,9 +5753,10 @@ var SkillLibrary = class {
 			for (const entry of landing) {
 				try {
 					if (this.transact) {
+						const baseline = entry.expected === void 0 ? entry.previous : entry.expected;
 						const drift = { seen: false };
 						await this.transact(this.io, entry.target, (current) => {
-							if (current !== entry.previous) {
+							if (current !== baseline) {
 								drift.seen = true;
 								return current;
 							}
@@ -5462,10 +5774,21 @@ var SkillLibrary = class {
 				});
 			}
 		} catch (error) {
-			for (const entry of written.reverse()) await (entry.previous === null ? this.io.remove(entry.target) : this.io.writeText(entry.target, entry.previous)).catch(() => {});
+			const stuck = [];
+			for (const entry of written.reverse()) try {
+				if (entry.previous === null) await this.io.remove(entry.target);
+				else await this.io.writeText(entry.target, entry.previous);
+			} catch {
+				stuck.push(entry.target);
+			}
+			const reason = error instanceof Error ? error.message : String(error);
+			if (stuck.length === 0) return {
+				ok: false,
+				message: `Tree change failed and was rolled back: ${reason}`
+			};
 			return {
 				ok: false,
-				message: `Tree change failed and was rolled back: ${error instanceof Error ? error.message : String(error)}`
+				message: `Tree change failed: ${reason}. The rollback could not restore ${stuck.join(", ")} — recover those targets from the .backups snapshot (or re-apply the change).`
 			};
 		}
 		await this.audit(name, plan.auditAction, md, landing.find((entry) => entry.target.split(/[\\/]/).pop() === "SKILL.md")?.content ?? md, plan.auditSummary);
@@ -5509,14 +5832,33 @@ var SkillLibrary = class {
 		}
 		const candidates = entries.filter((entry) => entry === name || entry.startsWith(`${name}-`)).sort().reverse();
 		let chosen;
-		for (const candidate of candidates) if (parseFrontmatter(await this.io.readText(join(archiveRoot, candidate, "SKILL.md")).catch(() => null) ?? "")?.frontmatter.name === name) {
-			chosen = candidate;
-			break;
+		const unreadable = [];
+		for (const candidate of candidates) {
+			if ((await this.io.readText(join(archiveRoot, candidate, ".archive-name")).catch(() => null))?.trim() === name) {
+				chosen = candidate;
+				break;
+			}
+			const parsed = parseFrontmatter(await this.io.readText(join(archiveRoot, candidate, "SKILL.md")).catch(() => null) ?? "");
+			if (parsed?.frontmatter.name === name) {
+				chosen = candidate;
+				break;
+			}
+			if (parsed === null && candidate === name) {
+				chosen = candidate;
+				break;
+			}
+			if (parsed === null) unreadable.push(candidate);
+		}
+		if (!chosen) {
+			if (unreadable.length === 0) return {
+				ok: false,
+				message: `Skill "${name}" is not in .archive.`
+			};
+			return {
+				ok: false,
+				message: `No archived entry for "${name}" carries a matching frontmatter name, but .archive holds ${unreadable.length} entr(y/ies) named like it: ${unreadable.join(", ")}. Those entries have no readable SKILL.md (or none matching the name), so restoring by name cannot tell them apart — rename the directory to the skill name and restore again, or restore from a snapshot.`
+			};
 		}
-		if (!chosen) return {
-			ok: false,
-			message: `Skill "${name}" is not in .archive.`
-		};
 		const source = join(archiveRoot, chosen);
 		if (this.io.isSymlink) {
 			if (await this.io.isSymlink(source) === true) return {
@@ -5534,7 +5876,7 @@ var SkillLibrary = class {
 			message: `Restore of "${name}" from .archive failed: ${moveFailure}`
 		};
 		await this.deleteStrandedLocks(dest);
-		if (await this.io.exists(join(dest, ".archive-reason"))) await this.io.remove(join(dest, ".archive-reason"));
+		for (const marker of [".archive-reason", ".archive-name"]) if (await this.io.exists(join(dest, marker))) await this.io.remove(join(dest, marker));
 		await this.audit(name, "restore", null, await this.io.readText(join(dest, "SKILL.md")).catch(() => null), `restored from ${source}`);
 		this.notifyMutation({
 			action: "restore",
@@ -5707,7 +6049,13 @@ var SkillLibrary = class {
 		while (await this.io.exists(dest)) dest = join(backupRoot, `skills-${stamp}-${Math.random().toString(36).slice(2, 8)}`);
 		try {
 			const names = await listNames(this.root, this.io);
-			const copyFailure = (await Promise.allSettled(names.map(async (name) => {
+			const skipped = [];
+			const copyable = [];
+			for (const name of names) if (await this.hasWriteLock(this.dirOf(name))) {
+				console.warn(`skill-store: snapshot skipped "${name}" — a byte-writer holds its write lock; the skill is recorded as skipped in the manifest`);
+				skipped.push(name);
+			} else copyable.push(name);
+			const copyFailure = (await Promise.allSettled(copyable.map(async (name) => {
 				await this.io.copy(this.dirOf(name), join(dest, name));
 			}))).find((result) => result.status === "rejected");
 			if (copyFailure) throw copyFailure.reason;
@@ -5732,7 +6080,8 @@ var SkillLibrary = class {
 			await this.io.writeText(join(dest, "manifest.json"), JSON.stringify({
 				reason,
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-				skills: names,
+				skills: copyable,
+				skipped,
 				sidecars,
 				hasArchive,
 				extras: extraNames
@@ -5745,6 +6094,45 @@ var SkillLibrary = class {
 		return dest;
 	}
 	/** Read and normalize a snapshot manifest; null when the file is missing or unparsable. */
+	/**
+	* V26-03 (v25/v26): sanitize the manifest's `skipped` list before it can
+	* reach a user-visible restore message. Entries must pass the same name
+	* gate as snapshot entries (a corrupted or hand-edited manifest cannot
+	* inject arbitrary text into the result), bounded to 50 entries of at most
+	* 64 chars each (the name-rule maximum — real skill names always fit).
+	*/
+	sanitizeSkippedNames(raw) {
+		if (!Array.isArray(raw)) return [];
+		const out = [];
+		for (const entry of raw) {
+			if (typeof entry !== "string") continue;
+			if (!this.safeSnapshotEntryName(entry)) continue;
+			out.push(entry.length > 64 ? entry.slice(0, 64) : entry);
+			if (out.length >= 50) break;
+		}
+		return out;
+	}
+	/**
+	* V27 G0.4 (core-a-01): the per-entry gate `skipped` already has. A corrupted
+	* or hand-edited manifest could carry `extras: [123]`: the array check passed,
+	* `SNAPSHOT_EXTRA_NAME_RE.test(123)` coerced the number to the string "123"
+	* and matched, and the value then threw `TypeError` inside `path.join` — which
+	* `readSnapshotExtras` reached only AFTER a whole-tree restore had committed.
+	* Extras are path components under `extras/`, so they take the entry gate too;
+	* bounded like `skipped` so a hostile manifest cannot grow the read set.
+	*/
+	sanitizeExtraNames(raw) {
+		if (!Array.isArray(raw)) return [];
+		const out = [];
+		for (const entry of raw) {
+			if (typeof entry !== "string") continue;
+			if (!SNAPSHOT_EXTRA_NAME_RE.test(entry)) continue;
+			if (!this.safeSnapshotEntryName(entry)) continue;
+			out.push(entry);
+			if (out.length >= 50) break;
+		}
+		return out;
+	}
 	async readSnapshotManifest(path) {
 		const raw = await this.io.readText(join(path, "manifest.json"));
 		if (raw === null) return null;
@@ -5755,9 +6143,10 @@ var SkillLibrary = class {
 				reason: typeof manifest.reason === "string" ? manifest.reason : "",
 				createdAt: typeof manifest.createdAt === "string" ? manifest.createdAt : "",
 				skills: manifest.skills,
+				skipped: this.sanitizeSkippedNames(manifest.skipped),
 				sidecars: Array.isArray(manifest.sidecars) ? manifest.sidecars : [],
 				...typeof manifest.hasArchive === "boolean" ? { hasArchive: manifest.hasArchive } : {},
-				extras: Array.isArray(manifest.extras) ? manifest.extras : []
+				extras: this.sanitizeExtraNames(manifest.extras)
 			};
 		} catch {
 			return null;
@@ -5831,6 +6220,7 @@ var SkillLibrary = class {
 			message: "No skill snapshot available."
 		};
 		const preRollbackPath = await this.snapshotAll("pre-rollback", extras);
+		const snapshotExtras = await this.readSnapshotExtras(latest.path);
 		try {
 			await this.restoreSnapshotIntoRoot(latest.path);
 		} catch (error) {
@@ -5848,7 +6238,6 @@ var SkillLibrary = class {
 				};
 			}
 		}
-		const snapshotExtras = await this.readSnapshotExtras(latest.path);
 		this.notifyMutation({
 			action: "restore",
 			name: "snapshot"
@@ -5870,6 +6259,7 @@ var SkillLibrary = class {
 		const manifest = await this.readSnapshotManifest(snapshotPath);
 		if (manifest === null) throw new Error(await this.io.exists(join(snapshotPath, "manifest.json")) ? `snapshot ${snapshotPath} has an unreadable manifest.json; refusing to clear the active tree` : `snapshot ${snapshotPath} has no readable manifest.json; refusing to restore`);
 		for (const name of [...manifest.skills, ...manifest.sidecars]) if (!this.safeSnapshotEntryName(name)) throw new Error(`snapshot ${snapshotPath} declares an unsafe entry name ${JSON.stringify(name)}; refusing to restore`);
+		if (manifest.skipped.length > 0) throw new Error(`snapshot ${snapshotPath} is incomplete: ${manifest.skipped.length} skill(s) were skipped when it was taken (a live writer held their write lock: ${manifest.skipped.join(", ")}); restoring it would clear the active tree without bringing them back — let the writer finish and take a fresh snapshot, then restore that one`);
 		if (manifest.skills.length === 0) {
 			const snapshotEntries = await this.io.list(snapshotPath);
 			const declared = new Set([
@@ -5923,4 +6313,4 @@ var SkillLibrary = class {
 	}
 };
 //#endregion
-export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOCK_BODY_RE, LOCK_SUFFIX, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PATTERN_OVERLAP, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, clampedNumber, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterYamlUnsafeValues, getRecord, isProcessAlive, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };
+export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, EMPTY_LOCK_TAKEOVER_MS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_TIMER_DELAY_MS, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PATTERN_OVERLAP, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, clampedNumber, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, decideTakeover, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, frontmatterYamlUnsafeValues, getRecord, isCommittedWarning, isProcessAlive, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };