@lmzhen/dsh-evolution-core 0.3.67 → 0.3.69

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,
@@ -421,12 +511,12 @@ function nodeEvolutionIo(lockAttempts = 40) {
 					const holder = Number(body.split(":")[0] ?? "");
 					const st = await stat(ticketPath);
 					const dead = !Number.isInteger(holder) || holder <= 0 || !isAlive(holder);
-					const old = Date.now() - st.mtimeMs > 1e3;
+					const old = Date.now() - st.mtimeMs > TICKET_STALE_MS;
 					if (dead || old) await rm(ticketPath, { force: true });
 				} 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) {
@@ -578,6 +673,7 @@ function normalizeUsageRecord(record) {
 	const num = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
 	const bool = (value, fallback) => typeof value === "boolean" ? value : fallback;
 	return {
+		...raw,
 		created_by: typeof raw.created_by === "string" ? raw.created_by : null,
 		use_count: num(raw.use_count, base.use_count),
 		view_count: num(raw.view_count, base.view_count),
@@ -935,6 +1031,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
 /**
@@ -1002,6 +1112,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 },
@@ -1023,6 +1135,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("; ")}`]
@@ -1037,6 +1151,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),
 		""
@@ -1195,15 +1310,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();
@@ -1214,6 +1320,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;
@@ -1230,12 +1345,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
@@ -1411,9 +1529,28 @@ async function rotateIfDue(io, path, events, rotateAt) {
 	if (tail.length === 0) return events;
 	const anchor = tail[0]?.seq ?? 0;
 	const archivePath = join(dirname(path), `${EVENT_ARCHIVE_PREFIX}${anchor - 1}.json`);
+	let archived = head;
+	const existing = await io.readText(archivePath).catch(() => null);
+	if (existing !== null) try {
+		const parsed = JSON.parse(existing);
+		const usablePrior = (Array.isArray(parsed.events) ? parsed.events : []).filter(isEventRecord);
+		const bySeq = new Map(usablePrior.map((event) => [event.seq, event]));
+		for (const event of head) bySeq.set(event.seq, event);
+		archived = [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+	} catch {
+		const shiftPath = `${archivePath}.${Date.now()}.collide`;
+		await io.writeText(shiftPath, JSON.stringify({
+			version: 1,
+			events: head
+		}, null, 2));
+		console.warn(`evolution-events: rotation hit an unparsable archive collision — the rotated head band was preserved at ${shiftPath} but is OUTSIDE the logical timeline; inspect and merge it manually`);
+		await retainEventArchives(io, path);
+		await pruneCollideArchives(io, path);
+		return tail;
+	}
 	await io.writeText(archivePath, JSON.stringify({
 		version: 1,
-		events: head
+		events: archived
 	}, null, 2));
 	await retainEventArchives(io, path);
 	return tail;
@@ -1431,6 +1568,34 @@ async function retainEventArchives(io, path) {
 	const excess = names.slice(0, Math.max(0, names.length - 10));
 	for (const name of excess) await io.remove(join(dir, name)).catch(() => {});
 }
+/** v31 EVENTS-02: prune shift-aside collision files (`events-*.json.<ts>.collide`)
+* after the same 7-day window the `.corrupt` sweep uses. They are write-once
+* recovery artifacts no reader accepts; without a sweep they accumulated
+* without bound across rollback episodes. No mtime probe → keep (fail-safe). */
+const COLLIDE_AGE_MS = 10080 * 60 * 1e3;
+async function pruneCollideArchives(io, path) {
+	const dir = dirname(path);
+	let names;
+	try {
+		names = await io.list(dir);
+	} catch {
+		return;
+	}
+	const now = Date.now();
+	for (const name of names) {
+		if (!name.endsWith(".collide") || !name.startsWith("events-")) continue;
+		const full = join(dir, name);
+		const stamp = name.match(/\.(\d{13})\.collide$/);
+		if (stamp && now - Number(stamp[1]) < COLLIDE_AGE_MS) continue;
+		if (!stamp) try {
+			const mtime = await io.mtime?.(full);
+			if (typeof mtime === "number" && now - mtime < COLLIDE_AGE_MS) continue;
+		} catch {
+			continue;
+		}
+		await io.remove(full).catch(() => {});
+	}
+}
 /** Read the event log; a missing/whitespace-only file reads as empty,
 * corrupt content is flagged (and refused on append). A well-formed future-
 * version body is v1-incompatible and reads as empty, NOT malformed (F-338:
@@ -1537,16 +1702,21 @@ function allowRowCollisions(env = process.env) {
 * platform's index cap), and DSH-only additions are marked as such.
 *
 * Every prompt is pinned in a versioned bundle. Review workers verify the
-* bundle digest before spending a model call, so a partially-patched
-* deployment fails closed instead of silently running a truncated prompt.
+* bundle digest before spending a model call — v31 PROMPT-01, stated
+* precisely: THAT check proves internal coherence (id/version/digest agree)
+* for a bundle assembled OUT of process and handed to `verifyPromptBundle`
+* explicitly. It CANNOT detect in-process tampering (the digest is recomputed
+* from the same module state it verifies) — catching a stale or partially
+* patched default bundle is CI's version pin (tests/prompts.spec.ts), not
+* this runtime gate.
 */
 /**
 * Prompt bundle identity. Bump both id and version whenever a prompt's text
 * changes semantically: the bundle digest is the fail-closed signal for
 * review workers, so a stale id across deployments must be distinguishable.
 */
-const PROMPT_BUNDLE_VERSION = 16;
-const PROMPT_BUNDLE_ID = `dsh-evolution@16`;
+const PROMPT_BUNDLE_VERSION = 17;
+const PROMPT_BUNDLE_ID = `dsh-evolution@17`;
 const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
 Review the conversation above and consider saving to memory if appropriate.
 
@@ -1567,7 +1737,7 @@ Signals to look for (any one of these warrants action):
   • Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.
   • A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.
 
-Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+Read-before-write: update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session. On the plan channel ops on unread skills are rejected; direct writes have no such guard, so treat the rule as binding. CREATE of a brand-new umbrella is the only exception.
 
 Preference order — prefer the earliest action that fits, but do pick one when a signal above fired:
   1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded or you read. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.
@@ -1617,7 +1787,7 @@ Signals that warrant a skill update (any one is enough):
   • Non-trivial technique, fix, workaround, or debugging path emerged.
   • A skill that was loaded or consulted turned out wrong, missing, or outdated — patch it now.
 
-Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+Read-before-write: update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session. On the plan channel ops on unread skills are rejected; direct writes have no such guard, so treat the rule as binding. CREATE of a brand-new umbrella is the only exception.
 
 Preference order for skills — pick the earliest that fits:
   1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded or read in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.
@@ -1833,12 +2003,12 @@ function sha256(text) {
 function createPromptBundle(prompts) {
 	const canonical = JSON.stringify({
 		id: PROMPT_BUNDLE_ID,
-		version: 16,
+		version: 17,
 		prompts: Object.fromEntries(Object.entries(prompts).sort())
 	});
 	return Object.freeze({
 		id: PROMPT_BUNDLE_ID,
-		version: 16,
+		version: 17,
 		prompts: Object.freeze({ ...prompts }),
 		sha256: sha256(canonical)
 	});
@@ -1856,10 +2026,10 @@ const PROMPT_BUNDLE = createPromptBundle({
 	skillsGuidance: SKILLS_GUIDANCE
 });
 function verifyPromptBundle(bundle = PROMPT_BUNDLE) {
-	if (bundle.id !== PROMPT_BUNDLE_ID || bundle.version !== 16) return false;
+	if (bundle.id !== PROMPT_BUNDLE_ID || bundle.version !== 17) return false;
 	const canonical = JSON.stringify({
 		id: PROMPT_BUNDLE_ID,
-		version: 16,
+		version: 17,
 		prompts: Object.fromEntries(Object.entries(bundle.prompts).sort())
 	});
 	return bundle.sha256 === sha256(canonical);
@@ -2248,7 +2418,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]/;
@@ -2295,7 +2466,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 {
@@ -2563,6 +2735,53 @@ var MemoryStore = class {
 			limit: this.limitFor(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
+	* @param shrinkOnly - v29 MEM-02: every queued operation REMOVES an entry
+	*   (the recovery path for a limit lowered under existing content). The
+	*   oversized read-guard is skipped for these batches: a canonical file
+	*   written under a ≥10× higher limit trips the `limit × 10` byte bound, and
+	*   the guard's "fix the file manually" refusal would pre-empt exactly the
+	*   shrink recovery MEM-01 advertises. The load is bounded by what the store
+	*   itself wrote under the old limit.
+	* @returns the core's result, or the oversized / contract-violation refusal
+	*/
+	async chainedWrite(target, core, shrinkOnly = false) {
+		const SHRINK_LOAD_CEILING = 64 * 1024 * 1024;
+		if (!shrinkOnly) {
+			const refusal = await this.oversizedRefusal(target);
+			if (refusal) return refusal;
+		} else {
+			const size = await this.io.size?.(fileFor(this.root, target));
+			if (typeof size === "number" && size > SHRINK_LOAD_CEILING) return {
+				ok: false,
+				message: `Memory file is ${size} bytes - too large to load even for a remove-only batch. Fix the file manually, then retry.`,
+				entries: [],
+				chars: 0,
+				limit: this.limitFor(target)
+			};
+		}
+		let outcome;
+		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,
+			message: "internal error: the memory transaction did not invoke the task; no write was performed",
+			entries: [],
+			chars: 0,
+			limit: this.limitFor(target)
+		};
+	}
 	async add(target, facts) {
 		return await this.serial(() => this.addChained(target, facts));
 	}
@@ -2574,22 +2793,7 @@ 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.addCore(target, facts, 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.addCore(target, facts, raw));
 	}
 	/**
 	* Single-entry add inside the transaction: shared checks (oversized,
@@ -2608,19 +2812,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: {
@@ -2676,57 +2872,114 @@ 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 evaluation. `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.
+	*
+	* Returns one of:
+	* - `'external'` — non-canonical body, i.e. real external modification. This
+	*   includes the Hermes-parity signal #2 (an entry larger than the whole-file
+	*   limit): that shape is only meaningful as external evidence on a
+	*   NON-canonical body, because free-form external appends never render
+	*   canonically.
+	* - `'over-limit'` — v28 MEM-01: a CANONICAL body whose entries exceed the
+	*   CURRENT configured limit. Those bytes were written by this store under a
+	*   previous (higher) limit, so they are not external drift; treating them as
+	*   such misattributed a config change to an "external editor" and bricked
+	*   every write path (the advertised recovery — remove/consolidate — is
+	*   exactly what the drift gate refused). Callers route this state to a
+	*   config-naming refusal and let shrink-only batches through.
+	* - `null` — no drift: writable as-is.
+	*
+	* @param target - memory target whose char limit bounds one parsed entry
+	* @param raw - on-disk body, or `null` when the file does not exist
+	*/
+	driftKind(target, raw) {
+		if (raw === null || raw.trim() === "") return null;
 		const entries = normalizeEntries(raw);
+		if (render(entries) !== raw) return "external";
 		const limit = this.limitFor(target);
-		if (limit > 0 && entries.some((entry) => entry.length > limit)) return true;
-		return render(entries) !== raw;
+		if (limit > 0 && entries.some((entry) => entry.length > limit)) return "over-limit";
+		return null;
 	}
-	async applyBatch(target, operations) {
-		return await this.serial(() => this.applyBatchChained(target, operations));
+	/** External-drift predicate: canonical-form violations only (see
+	* {@link driftKind}). `detectDrift` and the write paths share it, so a write
+	* and a later read never disagree about the same bytes. */
+	drifted(target, raw) {
+		return this.driftKind(target, raw) === "external";
 	}
-	async applyBatchChained(target, operations) {
-		if (operations.length === 0) return {
+	/**
+	* Drift refusal for a body already read under the write lock, or `null` when
+	* writing may proceed. Both write paths return this unchanged, so their
+	* refusals stay byte-identical and each carries the same backup.
+	*
+	* The `'over-limit'` state never refuses shrink-only batches (`shrinkOnly`):
+	* removing entries is the advertised recovery for a limit lowered under
+	* existing content, and the batch's own final limit check still gates the
+	* result.
+	*
+	* @param target - memory target that owns the drifted file
+	* @param raw - locked file body
+	* @param shrinkOnly - every queued operation removes an entry (no growth)
+	* @returns the refusal to hand back, or `null` to continue writing
+	*/
+	async driftRefusal(target, raw, shrinkOnly = false) {
+		const kind = this.driftKind(target, raw);
+		if (kind === null) return null;
+		if (kind === "over-limit") {
+			if (shrinkOnly) return null;
+			const limit = this.limitFor(target);
+			const entries = normalizeEntries(raw);
+			const over = entries.filter((entry) => entry.length > limit).length;
+			return {
+				ok: false,
+				message: `${over} memory ${over === 1 ? "entry exceeds" : "entries exceed"} the configured ${target}CharLimit (${limit}); they were written under a higher limit. Raise the limit or remove entries — remove operations stay available.`,
+				entries,
+				chars: entries.join(ENTRY_DELIMITER).length,
+				limit
+			};
+		}
+		const backup = await this.backupFile(target);
+		return {
 			ok: false,
-			message: "operations list is empty.",
+			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)
 		};
-		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 ?? {
+	}
+	async applyBatch(target, operations) {
+		return await this.serial(() => this.applyBatchChained(target, operations));
+	}
+	async applyBatchChained(target, operations) {
+		if (operations.length === 0) return {
 			ok: false,
-			message: "internal error: the memory transaction did not invoke the task; no write was performed",
+			message: "operations list is empty.",
 			entries: [],
 			chars: 0,
 			limit: this.limitFor(target)
 		};
+		const shrinkOnly = operations.every((op) => op.action === "remove");
+		return await this.chainedWrite(target, async (raw) => await this.applyBatchCore(target, operations, raw, shrinkOnly), shrinkOnly);
 	}
 	/** 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
-			};
-		}
+	async applyBatchCore(target, operations, raw, shrinkOnly = false) {
+		const refusal = await this.driftRefusal(target, raw, shrinkOnly);
+		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` : "";
@@ -2896,27 +3149,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
@@ -3258,8 +3501,10 @@ 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;
+const PEM_PRIVATE_KEY_PATTERN = new RegExp(`-----BEGIN\\s+(?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED|PGP)\\s+)?PRIVATE\\s+KEY(?:\\s+BLOCK)?-----[\\s\\S]*?-----END\\s+(?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED|PGP)\\s+)?PRIVATE\\s+KEY(?:\\s+BLOCK)?-----`, "g");
+const BLOCK_KEY_ONLY_LINE = /(?:^|\s)([\w-]{0,64}[_\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\-][\w-]{0,64})?)\s*:\s*$/i;
 /**
 * Mask credential-shaped text before it crosses a session boundary.
 * @param text - the text about to be sent to a model outside this session.
@@ -3267,9 +3512,21 @@ const URL_CREDENTIALS_PATTERN = /([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)([^\s/@]+)@/g
 */
 function redactSecrets(text) {
 	let out = text;
+	out = out.replace(PEM_PRIVATE_KEY_PATTERN, "<redacted-private-key>");
 	for (const [, pattern] of SECRET_PATTERNS) out = out.replace(pattern, "<redacted>");
 	out = out.replace(URL_CREDENTIALS_PATTERN, (_match, lead) => `${lead ?? ""}<redacted>@`);
 	out = out.replace(INLINE_ASSIGNMENT_PATTERN, (_match, lead, prefix, key, separator) => `${lead ?? ""}${prefix ?? ""}${key ?? ""}${separator ?? ""}<redacted>`);
+	const lines = out.split("\n");
+	for (let i = 0; i < lines.length - 1; i++) {
+		const line = lines[i];
+		if (line === void 0 || !BLOCK_KEY_ONLY_LINE.test(line)) continue;
+		const next = lines[i + 1] ?? "";
+		const [, indent, value, tail] = /^([ \t]+)(\S.*?)([ \t]*)$/.exec(next) ?? [];
+		if (indent === void 0 || value === void 0) continue;
+		if (value.includes("<redacted>")) continue;
+		lines[i + 1] = `${indent}<redacted>${tail ?? ""}`;
+	}
+	out = lines.join("\n");
 	out = out.split("\n").map((line) => {
 		if (!/<redacted>/.test(line) && !/\baws\b|\bAKIA\b|\bsecret\b/i.test(line)) return line;
 		return line.replace(/(?<![A-Za-z0-9/+=])[A-Za-z0-9/+=]{40}(?![A-Za-z0-9/+=])/g, "<redacted>");
@@ -3654,28 +3911,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):
@@ -3729,21 +3986,28 @@ function markerPath(dir, marker) {
 }
 /**
 * Shared frontmatter block detection (P3-3 single owner): opening line `---`
-* and closing line exactly `---` (both trimmed). Used by `parseFrontmatter`,
-* `frontmatterYamlUnsafeValues` and `normalizeFrontmatter` so the three can
+* and closing line exactly `---`. Used by `parseFrontmatter`,
+* `frontmatterCatalogInvalid` 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;
 		}
@@ -3756,24 +4020,177 @@ 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". `frontmatterCatalogInvalid` 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);
+	if (read !== null) return read.strictFailed || read.unsafeValues.length > 0;
+	return frontmatterBlock(content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n")) !== null;
+}
 /** 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),
@@ -3792,36 +4209,18 @@ 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;
-	if (/^(?:null|true|false|~|[-+]?\d+(?:\.\d+)?)$/i.test(value)) return true;
+	if (/^(?:null|true|false|~)$/i.test(value)) return true;
+	if (/^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/.test(value)) return true;
+	if (/^0x[0-9a-f]+$/i.test(value)) return true;
+	if (/^0o[0-7]+$/.test(value)) return true;
+	if (/^\.(?:inf|nan)$/i.test(value)) return true;
 	if (/^[-?:,[\]{}#&*!|>'\"%@`\s]/.test(value)) return true;
 	return false;
 }
-/** Raw-line scan of the frontmatter block: entries whose UNQUOTED value is
-* 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. */
-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;
-}
 /**
 * Normalize a SKILL.md frontmatter block into catalog-loadable YAML: values
 * that YAML forbids unquoted get quotes — double quotes normally, single
@@ -3931,7 +4330,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.`;
@@ -3965,9 +4364,18 @@ function authoringFeedback(frontmatter) {
 /** A1-15 (v18) / P2-2 (v19): the io layer marks an error `committed: true` when
 * the rename landed and only the directory fsync failed. Every single-file
 * writer must treat that as "written, durability unconfirmed" — never as a
-* plain failure (which a caller would retry, or a two-phase caller roll back). */
+* plain failure (which a caller would retry, or a two-phase caller roll back).
+* v28 G2.1 (EVO-IO-05): this is a delegation to the seam's own
+* `isCommittedWarning` — the marker predicate has exactly one definition. */
 function isCommittedOnly(error) {
-	return error?.committed === true;
+	return isCommittedWarning(error);
+}
+/** v28 G2.5 (CORE-SK-03): every pre-clear refusal in restoreSnapshotIntoRoot
+* says "refus…" (manifest / traversal / live-writer gates) or "is incomplete"
+* (completeness gate). Anything else thrown from that method means the
+* destructive clear already happened and a rollback is load-bearing. */
+function isPreClearRefusal(message) {
+	return message.includes("refus") || message.includes("is incomplete");
 }
 async function listNames(root, io) {
 	const entries = await io.list(root);
@@ -4238,11 +4646,14 @@ var SkillLibrary = class {
 		let outcome;
 		const run = async (current) => {
 			const o = await task(current ?? null);
-			outcome = o;
+			outcome = {
+				...o,
+				ghostDir: current === null && o.write === null
+			};
 			return o.write ?? current ?? null;
 		};
 		let durabilityWarning = "";
-		const committedOnly = (error) => error?.committed === true;
+		const committedOnly = isCommittedOnly;
 		if (this.transact) try {
 			await this.transact(this.io, path, run);
 		} catch (error) {
@@ -4264,6 +4675,7 @@ var SkillLibrary = class {
 			ok: false,
 			message: "internal error: the write transaction did not invoke the task; no write was performed"
 		};
+		if (o.ghostDir === true) await this.cleanupGhostDir(path);
 		if (o.write !== null && o.audit) await this.audit(o.audit.skillName, o.audit.action, o.audit.before, o.audit.after, o.audit.summary);
 		if (o.write !== null && o.event) this.notifyMutation(o.event);
 		return durabilityWarning === "" || !o.result.ok ? o.result : {
@@ -4271,6 +4683,24 @@ var SkillLibrary = class {
 			message: `${o.result.message} (warning: the write landed but the directory fsync failed — durability unconfirmed: ${durabilityWarning})`
 		};
 	}
+	/**
+	* v28 G1.1 (EVO-IO-02): shared compensating cleanup for a locked write that
+	* found no SKILL.md — remove the possibly-resurrected directory ONLY when it
+	* holds nothing but this path's own write-lock file. The BR-5 rule from
+	* setPinnedCore/createCore applies unchanged: a concurrent mover can land a
+	* full directory between the list probe and the remove, so anything beyond
+	* the lock file (support files, a fresh restore) must never be recursed
+	* away. Best-effort: a failed cleanup leaves the "not found" result
+	* unchanged (the operator-facing ghost-dir refusal is fail-loud already).
+	*/
+	async cleanupGhostDir(skillFilePath) {
+		const dir = dirname(skillFilePath);
+		const lockName = `${basename(skillFilePath)}${LOCK_SUFFIX}`;
+		try {
+			if ((await this.io.list(dir)).some((entry) => entry !== lockName)) return;
+			await this.io.remove(dir);
+		} catch {}
+	}
 	/** Notify the mutation observer after a successful write; observers must never fail the mutation. */
 	notifyMutation(event) {
 		try {
@@ -4288,11 +4718,39 @@ var SkillLibrary = class {
 	contentThreatBlock(content) {
 		return scanContentThreats(content, void 0, this.threatScanOptions());
 	}
+	/**
+	* v30 REV-03: read a support file's bytes for staleness anchoring (the
+	* write/remove replay guard). Same validation as writeSupportFile; a
+	* missing file (or a directory squatting on the path) reads as `null`, any
+	* other failure RETHROWS — the callers are the staging/replay anchors, and
+	* a swallowed error would silently downgrade the anchor to
+	* last-writer-wins.
+	*/
+	async readSupportFile(name, filePath) {
+		const bad = this.badName(name, { allowReserved: true });
+		if (bad) throw new Error(bad);
+		const validation = validateSupportPath(filePath);
+		if (validation) throw new Error(validation);
+		const target = join(this.dirOf(name), ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
+		try {
+			return await this.io.readText(target);
+		} catch (error) {
+			const code = error?.code;
+			if (code === "ENOENT" || code === "EISDIR") return null;
+			throw error;
+		}
+	}
 	async list() {
 		const summaries = [];
 		for (const name of await listNames(this.root, this.io)) {
 			const dir = this.dirOf(name);
-			const md = await this.io.readText(join(dir, "SKILL.md"));
+			let md;
+			try {
+				md = await this.io.readText(join(dir, "SKILL.md"));
+			} catch (error) {
+				if (error?.code === "EISDIR") continue;
+				throw error;
+			}
 			if (md === null) continue;
 			const parsed = parseFrontmatter(md);
 			let entries = null;
@@ -4552,7 +5010,7 @@ var SkillLibrary = class {
 			}
 			if (!await this.io.exists(join(dir, "SKILL.md"))) {
 				await this.io.remove(marker).catch(() => {});
-				if ((await this.io.list(dir).catch(() => [])).length === 0) await this.io.remove(dir).catch(() => {});
+				await this.cleanupGhostDir(join(dir, "SKILL.md"));
 				return {
 					ok: false,
 					message: `Skill "${normalized}" was archived concurrently while pinning; the partial marker was removed — retry after the mover settles.`
@@ -4652,15 +5110,22 @@ var SkillLibrary = class {
 			message: `Skill "${normalized}" already exists.`
 		};
 		if (origin !== "foreground") {
-			await this.io.writeText(markerPath(dir, "hermes-managed"), "");
+			let markerDurabilityWarning = "";
+			try {
+				await this.io.writeText(markerPath(dir, "hermes-managed"), "");
+			} catch (error) {
+				if (!isCommittedOnly(error)) throw error;
+				markerDurabilityWarning = error instanceof Error ? error.message : String(error);
+			}
 			if (!await this.io.exists(createPath)) {
 				await this.io.remove(markerPath(dir, "hermes-managed")).catch(() => {});
-				if ((await this.io.list(dir).catch(() => [])).length === 0) await this.io.remove(dir).catch(() => {});
+				await this.cleanupGhostDir(createPath);
 				return {
 					ok: false,
 					message: `Skill "${normalized}" was archived concurrently while being created; the partial marker was removed — retry once the mover settles.`
 				};
 			}
+			if (markerDurabilityWarning !== "") createDurabilityWarning = createDurabilityWarning === "" ? markerDurabilityWarning : `${createDurabilityWarning}; marker: ${markerDurabilityWarning}`;
 		}
 		await this.audit(normalized, "create", null, onDisk, "created");
 		this.notifyMutation({
@@ -4819,6 +5284,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) {
@@ -4886,7 +5353,7 @@ var SkillLibrary = class {
 			return {
 				result: {
 					ok: true,
-					message: `Skill "${name}" patched (${patchLabel}).`,
+					message: `Skill "${name}" patched (${patchLabel}).${patchNote}`,
 					path: dir,
 					...normalizedFields ? { normalizedFrontmatterFields: normalizedFields } : {}
 				},
@@ -5100,6 +5567,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",
@@ -5482,7 +5952,7 @@ var SkillLibrary = class {
 						if (drift.seen) throw new Error(`concurrent modification detected: ${entry.target} changed after the plan was computed (a concurrent writer won the race); no further writes were performed`);
 					} else await this.io.writeText(entry.target, entry.content);
 				} catch (error) {
-					if (error?.committed !== true) throw error;
+					if (!isCommittedOnly(error)) throw error;
 					durabilityWarning = error instanceof Error ? error.message : String(error);
 				}
 				written.push({
@@ -5491,10 +5961,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);
@@ -5538,14 +6019,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 {
@@ -5563,7 +6063,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",
@@ -5758,7 +6258,9 @@ var SkillLibrary = class {
 				await this.io.copy(archiveRoot, join(dest, ".archive"));
 				hasArchive = true;
 			}
-			const validExtras = extras.filter((extra) => SNAPSHOT_EXTRA_NAME_RE.test(extra.name));
+			const rejectedExtras = extras.filter((extra) => typeof extra?.name !== "string" || !SNAPSHOT_EXTRA_NAME_RE.test(extra.name)).map((extra) => JSON.stringify(extra?.name ?? extra));
+			if (rejectedExtras.length > 0) throw new Error(`snapshotAll: refusing invalid snapshot extras (name must match ${SNAPSHOT_EXTRA_NAME_RE.source}): ${rejectedExtras.join(", ")}`);
+			const validExtras = extras;
 			const extraNames = validExtras.map((extra) => extra.name);
 			const extraFailure = (await Promise.allSettled(validExtras.map(async (extra) => {
 				await this.io.writeText(join(dest, "extras", extra.name), extra.content);
@@ -5799,6 +6301,27 @@ var SkillLibrary = class {
 		}
 		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;
@@ -5812,7 +6335,7 @@ var SkillLibrary = class {
 				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;
@@ -5885,10 +6408,18 @@ var SkillLibrary = class {
 			ok: false,
 			message: "No skill snapshot available."
 		};
-		const preRollbackPath = await this.snapshotAll("pre-rollback", extras);
-		let skipped = [];
+		let preRollbackPath;
+		try {
+			preRollbackPath = await this.snapshotAll("pre-rollback", extras);
+		} catch (error) {
+			return {
+				ok: false,
+				message: `Snapshot restore was refused before anything was cleared: taking the pre-rollback snapshot failed (${error instanceof Error ? error.message : String(error)}) — the active tree is UNCHANGED. Resolve the snapshot write failure and retry.`
+			};
+		}
+		const snapshotExtras = await this.readSnapshotExtras(latest.path);
 		try {
-			skipped = await this.restoreSnapshotIntoRoot(latest.path);
+			await this.restoreSnapshotIntoRoot(latest.path);
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			try {
@@ -5898,21 +6429,24 @@ var SkillLibrary = class {
 					message: `Snapshot restore failed (${reason}); the active tree was rolled back to the pre-rollback snapshot.`
 				};
 			} catch (rollbackError) {
+				const rb = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+				if (isPreClearRefusal(reason) && isPreClearRefusal(rb)) return {
+					ok: false,
+					message: `Snapshot restore was refused before anything was cleared; the active tree is UNCHANGED.\n- target: ${reason}\n- pre-rollback: ${rb}\nResolve the cause (a live skill write, or an incomplete snapshot) and retry — no manual rescue is needed.`
+				};
 				return {
 					ok: false,
-					message: `Snapshot restore failed (${reason}) AND pre-rollback restore failed (${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}). Rescue manually from: ${preRollbackPath} (pre-rollback), ${latest.path} (target).`
+					message: `Snapshot restore failed (${reason}) AND pre-rollback restore failed (${rb}). Rescue manually from: ${preRollbackPath} (pre-rollback), ${latest.path} (target).`
 				};
 			}
 		}
-		const snapshotExtras = await this.readSnapshotExtras(latest.path);
 		this.notifyMutation({
 			action: "restore",
 			name: "snapshot"
 		});
-		const skippedNote = skipped.length === 0 ? "" : ` NOTE: ${skipped.length} skill(s) were skipped when this snapshot was taken (a live writer held their lock) and are NOT restored: ${skipped.join(", ")} — recover them from .backups if a copy exists.`;
 		return {
 			ok: true,
-			message: `Restored skill tree from ${latest.path}.${skippedNote}`,
+			message: `Restored skill tree from ${latest.path}`,
 			path: latest.path,
 			...snapshotExtras.length === 0 ? {} : { extras: snapshotExtras }
 		};
@@ -5927,6 +6461,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([
@@ -5977,8 +6512,7 @@ var SkillLibrary = class {
 			if (entry.startsWith(".")) continue;
 			await this.deleteStrandedLocks(join(this.root, entry));
 		}
-		return manifest.skipped;
 	}
 };
 //#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, 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 };