@lmzhen/dsh-evolution-core 0.3.65 → 0.3.67

package/lib/index.js

@@ -79,6 +79,18 @@ const RENAME_RETRY_MAX_ATTEMPTS = 6;
 * rethrows with a pointer at the usual causes instead of a bare errno.
 * `fn` is the rename primitive, injectable for deterministic tests.
 *
+* v22 (LOCK-5) documented platform limit: POSIX rename-over-existing is
+* atomic for concurrent READERS, but Windows MoveFileExW(REPLACE_EXISTING)
+* can make the target briefly invisible (ENOENT) while the replacement is in
+* flight. The retry budget above covers the WRITE side only — a LOCKLESS
+* reader (`readText`/`readJson` on a path it does not hold the lock for) can
+* observe that window and see "missing" for a file that was just committed.
+* Verified harmless today: every lockless-read consumer treats the transient
+* miss as self-healing state (no consumer persists a read of null into a
+* write), and distinguishing that ENOENT from a genuinely absent file in
+* `readText` would tax every ordinary missing-file probe. Revisit only if a
+* consumer appears that must never transiently miss.
+*
 * @param tmp - the source path to rename.
 * @param target - the destination path.
 * @param fn - the rename primitive (defaults to `node:fs/promises.rename`).
@@ -189,8 +201,18 @@ function isProcessAlive(pid) {
 const LOCK_SUFFIX = ".lock";
 /** Writer-lock body shape: a decimal pid, a colon, then the claim token. A
 * torn body (no parsable pid) still matches the `\\d+:` prefix rule only when
-* the pid part is intact, which is what the takeover probe needs. */
-const LOCK_BODY_RE = /^\d+:[0-9a-f]*$/;
+* the pid part is intact, which is what the takeover probe needs. The capture
+* group feeds `parseLockBody` (v20 A-1: skill-store's sweepers consume this
+* helper instead of re-inlining a third regex copy — F-17 single-source). */
+const LOCK_BODY_RE = /^(\d+):[0-9a-f]*$/;
+/** Parse a writer-lock body into its holder pid. `null` when the body does
+* not have the `pid:token` shape at all (e.g. a user support file named
+* `*.lock`) — callers leave such files alone. A shape-matching body always
+* yields a number (possibly `0`, which `isProcessAlive` treats as dead). */
+function parseLockBody(body) {
+	const match = LOCK_BODY_RE.exec(body.trim());
+	return match === null ? null : Number(match[1]);
+}
 /**
 * Build the Node IO backend. `lockAttempts` scales the write-lock retry budget
 * (attempts × 50ms); the default 40 (~2s, rc.69) covers production contention,
@@ -309,7 +331,18 @@ function nodeEvolutionIo(lockAttempts = 40) {
 							} catch {
 								continue;
 							}
-							const verify = await readFile(lock, "utf8").catch(() => "");
+							const verifyRead = await readFile(lock, "utf8").then((body) => ({
+								ok: true,
+								body
+							}), () => ({
+								ok: false,
+								body: ""
+							}));
+							if (!verifyRead.ok) {
+								await rm(ticket, { force: true }).catch(() => {});
+								continue;
+							}
+							const verify = verifyRead.body;
 							if (verify === holderContent) {
 								const verifyHolder = Number(verify.split(":")[0] ?? "");
 								if (!(Number.isInteger(verifyHolder) && verifyHolder > 0 && isAlive(verifyHolder))) await rm(lock, { force: true }).catch(() => {});
@@ -580,23 +613,40 @@ async function mutateUsage(root, io, task, options = {}) {
 	await transactIo(io, usageFile(root), async (current) => {
 		let shapePreserved = false;
 		let recovered = null;
-		if (current !== null) try {
-			const probe = JSON.parse(current);
-			if (probe === null || Array.isArray(probe) || typeof probe !== "object") shapePreserved = true;
-			else {
-				const record = probe;
+		const quarantineCopy = async () => {
+			const corruptPath = `${usageFile(root)}.corrupt`;
+			return io.writeText(corruptPath, current).then(() => true, () => false);
+		};
+		if (current !== null) {
+			let parsed = null;
+			try {
+				const probe = JSON.parse(current);
+				if (probe !== null && typeof probe === "object" && !Array.isArray(probe)) parsed = probe;
+			} catch {
+				parsed = null;
+			}
+			if (parsed === null) {
+				if (!await quarantineCopy()) {
+					options.onQuarantine?.(`usage sidecar ${usageFile(root)} is unreadable; the .corrupt copy could not be written — refusing this write so the original bytes stay recoverable (telemetry is frozen until the file is recovered manually)`);
+					return current;
+				}
+				options.onQuarantine?.(`usage sidecar ${usageFile(root)} is unreadable (unparsable JSON or wrong top-level shape); the original bytes were copied to ${usageFile(root)}.corrupt and the sidecar restarts empty`);
+			} else {
+				const record = parsed;
 				const isMalformed = (value) => value === null || typeof value !== "object" || Array.isArray(value);
-				if (typeof record.version === "number" && record.version > 1) shapePreserved = true;
-				else if (Object.values(record).some(isMalformed)) {
+				if (typeof record.version === "number" && record.version > 1) {
+					options.onQuarantine?.(`usage sidecar ${usageFile(root)} carries schema version ${String(record.version)} (> this runtime) — writes stay frozen and the bytes preserved until the runtime is upgraded`);
+					shapePreserved = true;
+				} else if (Object.values(record).some(isMalformed)) {
 					const bad = Object.keys(record).filter((key) => isMalformed(record[key]));
-					const corruptPath = `${usageFile(root)}.corrupt`;
-					await io.writeText(corruptPath, current).catch(() => {});
+					if (!await quarantineCopy()) {
+						options.onQuarantine?.(`usage sidecar ${usageFile(root)} carried ${bad.length} malformed entr${bad.length === 1 ? "y" : "ies"} (${bad.slice(0, 5).join(", ")}); the .corrupt copy could not be written — refusing this write so the original bytes stay recoverable`);
+						return current;
+					}
 					recovered = JSON.stringify(Object.fromEntries(Object.entries(record).filter(([, value]) => !isMalformed(value))));
-					options.onQuarantine?.(`usage sidecar ${usageFile(root)} carried ${bad.length} malformed entr${bad.length === 1 ? "y" : "ies"} (${bad.slice(0, 5).join(", ")}); the original bytes were copied to ${corruptPath} and the remaining entries continue to be served`);
+					options.onQuarantine?.(`usage sidecar ${usageFile(root)} carried ${bad.length} malformed entr${bad.length === 1 ? "y" : "ies"} (${bad.slice(0, 5).join(", ")}); the original bytes were copied to ${usageFile(root)}.corrupt and the remaining entries continue to be served`);
 				}
 			}
-		} catch {
-			return current;
 		}
 		if (shapePreserved) return current;
 		const map = parseUsage(recovered ?? current);
@@ -746,6 +796,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()
@@ -759,10 +817,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);
@@ -1315,7 +1380,7 @@ async function appendEvolutionEvent(io, path, event, rotateAt = EVENT_LOG_ROTATE
 		}
 		const events = await rotateIfDue(io, path, v1EventRecords(parsedBody), rotateAt);
 		let maxSeq = events.reduce((max, entry) => Math.max(max, entry.seq), 0);
-		if (maxSeq === 0) for (const name of await listEventArchives(io, path)) maxSeq = Math.max(maxSeq, Number.parseInt(name.slice(7, name.length - 5), 10));
+		for (const name of await listEventArchives(io, path)) maxSeq = Math.max(maxSeq, Number.parseInt(name.slice(7, name.length - 5), 10));
 		const record = {
 			...event,
 			seq: maxSeq + 1,
@@ -2072,19 +2137,19 @@ const PATTERNS = [
 		label: "send_to_url",
 		category: "exfiltration",
 		scope: "strict",
-		regex: /(?:send|post|upload|transmit)\s+[^\n]{0,512}\s+(?:to|at)\s+https?:\/\//i
+		regex: /(?:send|post|upload|transmit)\s+[\s\S]{0,512}?\s+(?:to|at)\s+https?:\/\//i
 	},
 	{
 		label: "exfil_curl",
 		category: "exfiltration",
 		scope: "all",
-		regex: /\bcurl\s+[^\n]{0,512}\$\{?\w*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)/i
+		regex: /\bcurl\s+[\s\S]{0,512}?\$\{?\w*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)/i
 	},
 	{
 		label: "exfil_wget",
 		category: "exfiltration",
 		scope: "all",
-		regex: /\bwget\s+[^\n]{0,512}\$\{?\w*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)/i
+		regex: /\bwget\s+[\s\S]{0,512}?\$\{?\w*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)/i
 	},
 	{
 		label: "read_secrets",
@@ -2150,7 +2215,37 @@ const PATTERNS = [
 		label: "private_key_block",
 		category: "hardcoded_secrets",
 		scope: "all",
-		regex: /-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----/
+		regex: /-----BEGIN\s+(?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED|PGP)\s+)?PRIVATE\s+KEY(?:\s+BLOCK)?-----/
+	},
+	{
+		label: "prompt_injection_ignore_zh",
+		category: "prompt_injection",
+		scope: "all",
+		regex: /(?:忽略|无视|抛开)[\s\S]{0,8}(?:之前|以上|上面|先前|以前)?[\s\S]{0,8}(?:所有|全部|任何)?[\s\S]{0,4}(?:指令|规则|设定|约束)/
+	},
+	{
+		label: "deception_hide_zh",
+		category: "deception",
+		scope: "all",
+		regex: /(?:不要|别|勿)(?:告诉|告知|透露)(?:给)?[\s\S]{0,6}(?:用户|任何人|主人|开发者)/
+	},
+	{
+		label: "system_prompt_leak_zh",
+		category: "deception",
+		scope: "context",
+		regex: /(?:泄露|输出|打印|透露|导出)[\s\S]{0,10}系统提示|系统提示[\s\S]{0,10}(?:泄露|透露|发送|导出)/
+	},
+	{
+		label: "context_exfil_zh",
+		category: "exfiltration",
+		scope: "strict",
+		regex: /(?:对话记录|聊天记录|全部上下文|完整上下文)[\s\S]{0,30}(?:发送|上传|传输|外传|泄露)[\s\S]{0,30}(?:到|至|给)/
+	},
+	{
+		label: "secret_exfil_zh",
+		category: "exfiltration",
+		scope: "strict",
+		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");
@@ -2199,11 +2294,13 @@ function scanThreats(text, scope = "strict", maxScanChars = 65536, options = NO_
 		scope: "all"
 	});
 	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 windows = [];
-	if (normalized.length <= windowSize) windows.push(normalized);
+	for (const patternText of patternTexts) if (patternText.length <= windowSize) windows.push(patternText);
 	else {
 		const step = Math.max(Math.floor(windowSize / 2), 1);
-		for (let start = 0; start < normalized.length; start += step) windows.push(normalized.slice(start, start + windowSize));
+		for (let start = 0; start < patternText.length; start += step) windows.push(patternText.slice(start, start + windowSize));
 	}
 	const seen = /* @__PURE__ */ new Set();
 	for (const window of windows) for (const pattern of PATTERNS) {
@@ -2236,27 +2333,26 @@ function scanMemoryThreats(text, maxScanChars = 65536, options = NO_SCAN_OPTIONS
 	const { blocked, findings } = evaluateThreat(text, "strict", maxScanChars, options);
 	if (!blocked) return null;
 	const pattern = findings.find((f) => f.category !== "unicode_obfuscation");
-	const exemptionHint = " A deployment that needs a specific label can exempt it via threatExemptLabels (see the README env/dial reference).";
-	if (pattern) return `Blocked by security scan (${pattern.label}). Rephrase without instruction-like language.${exemptionHint}`;
-	return `Blocked by security scan: invisible or potentially malicious Unicode detected.${exemptionHint}`;
+	if (pattern) return `Blocked by security scan (${pattern.label}). Rephrase without instruction-like language.${THREAT_EXEMPTION_HINT}`;
+	return `Blocked by security scan: invisible or potentially malicious Unicode detected.${THREAT_EXEMPTION_HINT}`;
 }
 /** User-facing block message for skill content writes. */
 function scanContentThreats(text, maxScanChars = 65536, options = NO_SCAN_OPTIONS) {
 	const { blocked, findings } = evaluateThreat(text, "strict", maxScanChars, options);
 	if (!blocked) return null;
-	return `Blocked by security scan (${findings[0]?.label ?? "unknown"}). This content appears to contain potentially malicious instructions. Installations with a known-innocent label can exempt it via threatExemptLabels (README dial reference).`;
+	return `Blocked by security scan (${findings[0]?.label ?? "unknown"}). This content appears to contain potentially malicious instructions.${THREAT_EXEMPTION_HINT}`;
 }
 /**
-* V10-03 (P2-18): suffix the SkillLibrary/MemoryStore write gates append to a
-* block message — the hit label is already embedded by scanContentThreats /
-* scanMemoryThreats, this names the deployable self-heal path so the model
-* (or operator) can allowlist a known-benign label. P2-4 (v14): the
-* evolution-threat guard channel now carries `threatExemptLabels` too, so its
-* block message (which embeds the same exemption sentence) is accurate there
-* as well; this suffix stays store-side because the guard returns the scan
-* message verbatim.
+* WD2 (0.3.56): the shared tail of every user-facing threat block — names the
+* deployable self-heal path so the model (or operator) can allowlist a
+* known-benign label. v20 (B-2) single source: the scan builders embed this
+* constant verbatim; do NOT re-word it per call site (the three former copies
+* — memory inline, content inline, and the dead `THREAT_EXEMPT_HINT` export,
+* whose docblock still claimed a store-side append that memory-store/skill-store
+* had already removed — had drifted apart). The evolution-threat guard channel
+* returns the scan message verbatim, so the hint rides along there too.
 */
-const THREAT_EXEMPT_HINT = " If this is a legitimate false positive, the deployment can allow its label via the threatExemptLabels store option.";
+const THREAT_EXEMPTION_HINT = " A deployment that needs a specific label can exempt it via threatExemptLabels (see the README env/dial reference).";
 //#endregion
 //#region lib/types/memory-store.js
 /**
@@ -2955,7 +3051,7 @@ function injectCatalogDescriptionCap(composition) {
 			const next = lines[j] ?? "";
 			if (next.trim() === "") break;
 			if (!/^\s/.test(next)) break;
-			if (/^\s+config:(\s|$)/.test(next)) hasConfig = true;
+			if (/^ {2}config:(\s|$)/.test(next)) hasConfig = true;
 			end = j;
 		}
 		if (hasConfig) continue;
@@ -3156,9 +3252,14 @@ const SECRET_PATTERNS = [
 	["gitlab token", /glpat-[A-Za-z0-9_-]{16,}/g],
 	["slack token", /xox[baprs]-[A-Za-z0-9-]{10,}/g],
 	["jwt", /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g],
+	["npm token", /npm_[A-Za-z0-9]{20,}/g],
+	["stripe key", /[sr]k_(?:live|test)_[A-Za-z0-9]{16,}/g],
+	["github fine-grained token", /github_pat_[A-Za-z0-9_]{20,}/g],
+	["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 URL_CREDENTIALS_PATTERN = /([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)([^\s/@]+)@/gi;
 /**
 * Mask credential-shaped text before it crosses a session boundary.
 * @param text - the text about to be sent to a model outside this session.
@@ -3167,7 +3268,12 @@ const INLINE_ASSIGNMENT_PATTERN = /* @__PURE__ */ new RegExp("(^|[^\\w-])([\\w-]
 function redactSecrets(text) {
 	let out = text;
 	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>`);
+	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>");
+	}).join("\n");
 	return out;
 }
 //#endregion
@@ -3616,6 +3722,8 @@ const MARKER_LOCK_NAMES = [
 	`.pinned${LOCK_SUFFIX}`,
 	`.hermes-managed${LOCK_SUFFIX}`
 ];
+/** v23 (ML-1): `.archive` retention window (see pruneExpiredArchives). */
+const ARCHIVE_RETENTION_DAYS = 365;
 function markerPath(dir, marker) {
 	return join(dir, markerEntryName(marker));
 }
@@ -4435,13 +4543,22 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${normalized}" not found.`
 		};
-		if (pinned) try {
-			await this.io.writeText(marker, "");
-		} catch (error) {
-			if (!isCommittedOnly(error)) throw error;
-			durabilityWarning = error instanceof Error ? error.message : String(error);
-		}
-		else await this.io.remove(marker);
+		if (pinned) {
+			try {
+				await this.io.writeText(marker, "");
+			} catch (error) {
+				if (!isCommittedOnly(error)) throw error;
+				durabilityWarning = error instanceof Error ? error.message : String(error);
+			}
+			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(() => {});
+				return {
+					ok: false,
+					message: `Skill "${normalized}" was archived concurrently while pinning; the partial marker was removed — retry after the mover settles.`
+				};
+			}
+		} else await this.io.remove(marker);
 		await this.audit(normalized, pinned ? "pin" : "unpin", null, null, pinned ? "pinned" : "unpinned");
 		return {
 			ok: true,
@@ -4487,6 +4604,10 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${normalized}" already exists.`
 		};
+		for (const entry of await this.io.list(this.root).catch(() => [])) if (typeof entry === "string" && entry !== normalized && entry.toLowerCase() === normalized.toLowerCase()) return {
+			ok: false,
+			message: `Skill "${normalized}" collides with the existing case-variant directory "${entry}" (skill names are lowercase-only); rename one of them.`
+		};
 		const protection = await this.writeProtection(normalized, origin);
 		if (protection) return {
 			ok: false,
@@ -4530,7 +4651,17 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${normalized}" already exists.`
 		};
-		if (origin !== "foreground") await this.io.writeText(markerPath(dir, "hermes-managed"), "");
+		if (origin !== "foreground") {
+			await this.io.writeText(markerPath(dir, "hermes-managed"), "");
+			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(() => {});
+				return {
+					ok: false,
+					message: `Skill "${normalized}" was archived concurrently while being created; the partial marker was removed — retry once the mover settles.`
+				};
+			}
+		}
 		await this.audit(normalized, "create", null, onDisk, "created");
 		this.notifyMutation({
 			action: "create",
@@ -4863,9 +4994,7 @@ var SkillLibrary = class {
 	* stolen by the sweep. A dead-pid residue would otherwise permanently
 	* refuse archive/restore. */
 	async deleteStrandedLocks(dir) {
-		await this.sweepLockIfStranded(join(dir, "SKILL.md.lock"));
-		await this.sweepLockIfStranded(join(dir, ".pinned.lock"));
-		await this.sweepLockIfStranded(join(dir, ".hermes-managed.lock"));
+		for (const markerLock of MARKER_LOCK_NAMES) await this.sweepLockIfStranded(join(dir, markerLock));
 		for (const supportDir of SUPPORT_DIRS) {
 			let entries = [];
 			try {
@@ -4882,9 +5011,8 @@ var SkillLibrary = class {
 	async sweepLockIfStranded(lockPath) {
 		const body = await this.io.readText(lockPath).catch(() => null);
 		if (body === null) return;
-		const match = /^(\d+):[0-9a-f]*$/.exec(body.trim());
-		if (match === null) return;
-		const pid = Number(match[1]);
+		const pid = parseLockBody(body);
+		if (pid === null) return;
 		if (Number.isInteger(pid) && pid > 0 && isProcessAlive(pid)) return;
 		await this.io.remove(lockPath).catch(() => {});
 	}
@@ -4908,9 +5036,8 @@ var SkillLibrary = class {
 			throw new Error(`snapshot restore refused: cannot verify ${label} (${error instanceof Error ? error.message : String(error)}); a live writer may hold it`);
 		}
 		if (body === null) return;
-		const match = /^(\d+):[0-9a-f]*$/.exec(body.trim());
-		if (match === null) return;
-		const pid = Number(match[1]);
+		const pid = parseLockBody(body);
+		if (pid === null) return;
 		if (Number.isInteger(pid) && pid > 0 && isProcessAlive(pid)) throw new Error(`snapshot restore refused: ${label} is being written (write lock present); retry once the write completes`);
 		await this.io.remove(lockPath).catch(() => {});
 	}
@@ -5099,10 +5226,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") {
@@ -5114,7 +5243,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("");
@@ -5126,7 +5256,8 @@ var SkillLibrary = class {
 					};
 					writes.push({
 						target: join(targetDir, "SKILL.md"),
-						content: extended
+						content: extended,
+						expected: freshTargetMd
 					});
 				}
 				return await this.applyTreeChange({
@@ -5194,6 +5325,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."
@@ -5247,15 +5383,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,
@@ -5321,7 +5460,8 @@ var SkillLibrary = class {
 			landing.push({
 				target: write.target,
 				content: write.content,
-				previous
+				previous,
+				expected: write.expected
 			});
 		}
 		const written = [];
@@ -5329,7 +5469,18 @@ var SkillLibrary = class {
 		try {
 			for (const entry of landing) {
 				try {
-					await this.io.writeText(entry.target, entry.content);
+					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 !== baseline) {
+								drift.seen = true;
+								return current;
+							}
+							return entry.content;
+						});
+						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;
 					durabilityWarning = error instanceof Error ? error.message : String(error);
@@ -5544,19 +5695,54 @@ var SkillLibrary = class {
 		};
 	}
 	/**
+	* v23 (ML-1): `.archive` retention. Archived skills are recoverable history,
+	* but nothing bounded their growth — the curator auto-archives idle skills,
+	* consolidation and manual deletes take the same path, and every snapshot
+	* copies the whole `.archive` (keep-5 retention amplifies it ×6). Entries
+	* older than this many days are pruned at snapshot time. Generous by
+	* design: a year-old auto-archive is effectively dead recoverability.
+	* Backends without the mtime probe skip pruning (no false deletes on
+	* unknown age).
+	*/
+	async pruneExpiredArchives() {
+		const archiveRoot = join(this.root, ".archive");
+		if (!this.io.mtime) return;
+		let entries = [];
+		try {
+			entries = await this.io.list(archiveRoot);
+		} catch {
+			return;
+		}
+		const cutoff = Date.now() - ARCHIVE_RETENTION_DAYS * 864e5;
+		for (const entry of entries) {
+			const entryPath = join(archiveRoot, entry);
+			const mtime = await this.io.mtime(entryPath).catch(() => null);
+			if (mtime === null || mtime > cutoff) continue;
+			await this.io.remove(entryPath).catch(() => {});
+			console.warn(`skill-store: pruned archived skill "${entry}" (older than ${ARCHIVE_RETENTION_DAYS} days; recoverable from snapshots until they rotate)`);
+		}
+	}
+	/**
 	* Snapshot the recoverable skills state: active tree, usage/suppression
 	* sidecars, `.archive/` and caller-supplied extras. `extras` are opaque
 	* side files the Snapshot owner cares about (curator state); they are
 	* listed in the manifest and only those names are ever read back.
 	*/
 	async snapshotAll(reason = "pre-mutation", extras = []) {
+		await this.pruneExpiredArchives();
 		const backupRoot = join(this.root, ".backups");
 		const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 		let dest = join(backupRoot, `skills-${stamp}`);
 		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;
@@ -5581,7 +5767,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
@@ -5594,6 +5781,24 @@ 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;
+	}
 	async readSnapshotManifest(path) {
 		const raw = await this.io.readText(join(path, "manifest.json"));
 		if (raw === null) return null;
@@ -5604,6 +5809,7 @@ 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 : []
@@ -5631,7 +5837,14 @@ var SkillLibrary = class {
 		for (const name of entries.sort().reverse()) {
 			if (!name.startsWith("skills-")) continue;
 			const manifest = await this.readSnapshotManifest(join(backupRoot, name));
-			if (manifest === null) continue;
+			if (manifest === null) {
+				out.push({
+					path: join(backupRoot, name),
+					createdAt: "",
+					reason: "unreadable or missing manifest (orphan snapshot)"
+				});
+				continue;
+			}
 			out.push({
 				path: join(backupRoot, name),
 				createdAt: manifest.createdAt,
@@ -5673,8 +5886,9 @@ var SkillLibrary = class {
 			message: "No skill snapshot available."
 		};
 		const preRollbackPath = await this.snapshotAll("pre-rollback", extras);
+		let skipped = [];
 		try {
-			await this.restoreSnapshotIntoRoot(latest.path);
+			skipped = await this.restoreSnapshotIntoRoot(latest.path);
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			try {
@@ -5695,9 +5909,10 @@ var SkillLibrary = class {
 			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}`,
+			message: `Restored skill tree from ${latest.path}.${skippedNote}`,
 			path: latest.path,
 			...snapshotExtras.length === 0 ? {} : { extras: snapshotExtras }
 		};
@@ -5762,7 +5977,8 @@ 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_EXEMPT_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, 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, 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 };

package/lib/types/events.d.ts

@@ -21,6 +21,15 @@ export interface EvolutionReviewScheduledEvent {
     toolCalls: number;
     userChars: number;
     assistantChars: number;
+    /** V24-15 (v24): which delivery channel actually sent the review. The
+     * emission point was previously covered on only two of the four delivery
+     * paths (subagent success + completion inject), so a consumer on the
+     * default inject-mode deployment would have silently missed every cadence
+     * review. Every delivery path now emits with its channel:
+     * `'subagent'` (spawned review run), `'inject'` (prompt injected into the
+     * parent — direct, fallback, or deferred-drain), `'completion'`
+     * (completion-trigger prompt, direct or deferred-drain). */
+    channel?: 'subagent' | 'inject' | 'completion' | undefined;
 }
 export interface EvolutionPlanAppliedEvent {
     /** Owning session (payload v2): process events carry no session envelope. */

package/lib/types/io.d.ts

@@ -45,11 +45,17 @@ export interface EvolutionIoLike {
      * milliseconds since epoch, or `null` when unknown (unsupported backend,
      * missing path, stat failure). Intended as a cheap invalidation stamp for a
      * cached directory listing; a backend without it keeps event-driven
-     * invalidation only. V9-07 (0.3.51): as of this release NO in-tree consumer
-     * calls it — skill-catalog invalidation is event-driven
-     * (`evolution/skill-mutated` / `evolution/skills-refresh`). The probe stays
-     * as a backend contract extension point; document it here before wiring a
-     * consumer.
+     * invalidation only. v20 correction: the former "NO in-tree consumer" note
+     * (V9-07, 0.3.51) went stale — there are now FOUR in-tree consumers, and a
+     * custom backend that omits `mtime` degrades them silently (every call
+     * site is optional-call + null-fallback, so omission stays legal):
+     *   - evolution-skill-catalog: root-mtime stamp on the summaries cache —
+     *     the second, out-of-band invalidation signal next to the
+     *     `evolution/skill-mutated` / `evolution/skills-refresh` events;
+     *   - evolution-curator: run-report recency ordering (2 call sites);
+     *   - evolution-commands: `.bak` freshness probe in the preset installer.
+     * With `mtime` absent, catalog invalidation degrades to purely
+     * event-driven. Register new consumers here (the seam contract).
      */
     mtime?(this: void, path: string): Promise<number | null>;
 }
@@ -84,6 +90,18 @@ export declare const pendingSelfCleanup: Map<string, string>;
  * rethrows with a pointer at the usual causes instead of a bare errno.
  * `fn` is the rename primitive, injectable for deterministic tests.
  *
+ * v22 (LOCK-5) documented platform limit: POSIX rename-over-existing is
+ * atomic for concurrent READERS, but Windows MoveFileExW(REPLACE_EXISTING)
+ * can make the target briefly invisible (ENOENT) while the replacement is in
+ * flight. The retry budget above covers the WRITE side only — a LOCKLESS
+ * reader (`readText`/`readJson` on a path it does not hold the lock for) can
+ * observe that window and see "missing" for a file that was just committed.
+ * Verified harmless today: every lockless-read consumer treats the transient
+ * miss as self-healing state (no consumer persists a read of null into a
+ * write), and distinguishing that ENOENT from a genuinely absent file in
+ * `readText` would tax every ordinary missing-file probe. Revisit only if a
+ * consumer appears that must never transiently miss.
+ *
  * @param tmp - the source path to rename.
  * @param target - the destination path.
  * @param fn - the rename primitive (defaults to `node:fs/promises.rename`).
@@ -119,8 +137,15 @@ export declare function isProcessAlive(pid: number): boolean;
 export declare const LOCK_SUFFIX = ".lock";
 /** Writer-lock body shape: a decimal pid, a colon, then the claim token. A
  * torn body (no parsable pid) still matches the `\\d+:` prefix rule only when
- * the pid part is intact, which is what the takeover probe needs. */
+ * the pid part is intact, which is what the takeover probe needs. The capture
+ * group feeds `parseLockBody` (v20 A-1: skill-store's sweepers consume this
+ * helper instead of re-inlining a third regex copy — F-17 single-source). */
 export declare const LOCK_BODY_RE: RegExp;
+/** Parse a writer-lock body into its holder pid. `null` when the body does
+ * not have the `pid:token` shape at all (e.g. a user support file named
+ * `*.lock`) — callers leave such files alone. A shape-matching body always
+ * yields a number (possibly `0`, which `isProcessAlive` treats as dead). */
+export declare function parseLockBody(body: string): number | null;
 /**
  * Build the Node IO backend. `lockAttempts` scales the write-lock retry budget
  * (attempts × 50ms); the default 40 (~2s, rc.69) covers production contention,

package/lib/types/skill-store.d.ts

@@ -77,6 +77,13 @@ export interface SnapshotManifest {
     createdAt: string;
     /** Active skill names at snapshot time. */
     skills: string[];
+    /** V25-05 (v25): skills that were SKIPPED by the write-lock probe at
+     * snapshot time (a live byte-writer held them) — they are NOT in the
+     * snapshot directory and are NOT restored by a whole-tree restore, which
+     * clears the live tree and copies back only `skills`. Consumers must
+     * surface this list; restore reports it in its result message. Absent
+     * (empty) on pre-0.3.67 manifests. */
+    skipped: string[];
     /** Co-copied sidecar file names (usage/suppression). */
     sidecars: string[];
     /** Whether `.archive/` was co-copied; absent on legacy manifests (do not touch archive on restore). */
@@ -474,6 +481,17 @@ export declare class SkillLibrary {
     private writeSupportFileCore;
     removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     private removeSupportFileCore;
+    /**
+     * v23 (ML-1): `.archive` retention. Archived skills are recoverable history,
+     * but nothing bounded their growth — the curator auto-archives idle skills,
+     * consolidation and manual deletes take the same path, and every snapshot
+     * copies the whole `.archive` (keep-5 retention amplifies it ×6). Entries
+     * older than this many days are pruned at snapshot time. Generous by
+     * design: a year-old auto-archive is effectively dead recoverability.
+     * Backends without the mtime probe skip pruning (no false deletes on
+     * unknown age).
+     */
+    private pruneExpiredArchives;
     /**
      * Snapshot the recoverable skills state: active tree, usage/suppression
      * sidecars, `.archive/` and caller-supplied extras. `extras` are opaque
@@ -482,6 +500,14 @@ export declare class SkillLibrary {
      */
     snapshotAll(reason?: string, extras?: SnapshotExtra[]): Promise<string>;
     /** 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).
+     */
+    private sanitizeSkippedNames;
     readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
     /** Keep only the newest N snapshots (Hermes keep=5 parity); older ones are removed outright. */
     private retainSnapshots;

package/lib/types/threats.d.ts

@@ -61,14 +61,14 @@ export declare function scanMemoryThreats(text: string, maxScanChars?: number, o
 /** User-facing block message for skill content writes. */
 export declare function scanContentThreats(text: string, maxScanChars?: number, options?: ScanOptions): string | null;
 /**
- * V10-03 (P2-18): suffix the SkillLibrary/MemoryStore write gates append to a
- * block message — the hit label is already embedded by scanContentThreats /
- * scanMemoryThreats, this names the deployable self-heal path so the model
- * (or operator) can allowlist a known-benign label. P2-4 (v14): the
- * evolution-threat guard channel now carries `threatExemptLabels` too, so its
- * block message (which embeds the same exemption sentence) is accurate there
- * as well; this suffix stays store-side because the guard returns the scan
- * message verbatim.
+ * WD2 (0.3.56): the shared tail of every user-facing threat block — names the
+ * deployable self-heal path so the model (or operator) can allowlist a
+ * known-benign label. v20 (B-2) single source: the scan builders embed this
+ * constant verbatim; do NOT re-word it per call site (the three former copies
+ * — memory inline, content inline, and the dead `THREAT_EXEMPT_HINT` export,
+ * whose docblock still claimed a store-side append that memory-store/skill-store
+ * had already removed — had drifted apart). The evolution-threat guard channel
+ * returns the scan message verbatim, so the hint rides along there too.
  */
-export declare const THREAT_EXEMPT_HINT = " If this is a legitimate false positive, the deployment can allow its label via the threatExemptLabels store option.";
+export declare const THREAT_EXEMPTION_HINT = " A deployment that needs a specific label can exempt it via threatExemptLabels (see the README env/dial reference).";
 //# sourceMappingURL=threats.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.3.65",
+  "version": "0.3.67",
   "publishConfig": {
     "access": "public"
   },