@lmzhen/dsh-evolution-core 0.3.64 → 0.3.66

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(() => {});
@@ -393,7 +426,7 @@ function nodeEvolutionIo(lockAttempts = 40) {
 				} catch {}
 				continue;
 			}
-			if (name.includes(".corrupt")) {
+			if (/\.corrupt(\.\d+)?$/.test(name)) {
 				const corruptPath = join(dir, name);
 				try {
 					const st = await stat(corruptPath);
@@ -576,29 +609,47 @@ function parseUsage(raw) {
 async function loadUsage(root, io = nodeEvolutionIo()) {
 	return parseUsage(await io.readText(usageFile(root)));
 }
-/**
-* Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
-* the map parsed from the current on-disk state and may mutate it; the result
-* is persisted inside the same transact so a second process sharing DSH_HOME
-* cannot interleave its RMW and lose a counter update. Callers keep their own
-* single-process serialize chain as the second layer.
-*/
-async function mutateUsage(root, io, task) {
+async function mutateUsage(root, io, task, options = {}) {
 	await transactIo(io, usageFile(root), async (current) => {
 		let shapePreserved = false;
-		if (current !== null) try {
-			const probe = JSON.parse(current);
-			if (probe === null || Array.isArray(probe) || typeof probe !== "object") shapePreserved = true;
-			else {
-				const record = probe;
-				if (Object.values(record).some((value) => value === null || typeof value !== "object" || Array.isArray(value))) shapePreserved = true;
-				if (typeof record.version === "number" && record.version > 1) shapePreserved = true;
+		let recovered = null;
+		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) {
+					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]));
+					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 ${usageFile(root)}.corrupt and the remaining entries continue to be served`);
+				}
 			}
-		} catch {
-			return current;
 		}
 		if (shapePreserved) return current;
-		const map = parseUsage(current);
+		const map = parseUsage(recovered ?? current);
 		await task(map);
 		return JSON.stringify(Object.fromEntries(map.entries()), null, 2);
 	});
@@ -1314,7 +1365,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,
@@ -1976,9 +2027,16 @@ function clampedNumber(value, fallback, opts) {
 * Threat scanning for agent-authored memory and skill content.
 *
 * Ported as a small, dependency-free subset of Hermes Agent's
-* `tools/threat_patterns.py` + hermes-claw `threats.ts`. The policy is the
-* load-bearing part: ANY in-scope hit blocks. Severity and category are
-* metadata for diagnostics only.
+* `tools/threat_patterns.py` + hermes-claw `threats.ts`.
+*
+* Policy (P1-1, v19): a finding either BLOCKS the write or only REPORTS.
+* Blocking is reserved for shapes with no legitimate use in stored knowledge
+* (prompt-injection phrasing, credential exfiltration, the invisible-character
+* smuggling core). Typography and presentation characters that are legitimate
+* in ordinary prose — variation selectors (❤️), zero-width non-joiner, soft
+* hyphen from PDF paste, Arabic letter mark, Mongolian vowel separator — are
+* REPORT findings: they stay visible to operators and tests but never reject a
+* write. Blocking them turned every emoji into a security event.
 */
 const FILLER = String.raw`(?:\w+\s+){0,8}`;
 const PATTERNS = [
@@ -2064,19 +2122,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",
@@ -2142,10 +2200,42 @@ 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(`[\\u00ad\\u034f\\u061c\\u180e\\u200b\\u200c\\u200d\\u2060\\u2061\\u2062\\u2063\\u2064\\u206a-\\u206f\\ufeff\\ufe00-\\ufe0f]|\\u{e0000}-\\u{e007f}`, "u");
+const ZERO_WIDTH_CHARS = new RegExp(`[\\u034f\\u200b\\u2060\\u2061\\u2062\\u2063\\u2064\\u206a-\\u206f\\ufeff\\u{e0000}-\\u{e007f}]`, "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]/;
 const SCOPE_ORDER = {
 	all: 1,
@@ -2172,22 +2262,30 @@ function scanThreats(text, scope = "strict", maxScanChars = 65536, options = NO_
 	const windowSize = clampedNumber(maxScanChars, 65536, { min: 4097 });
 	const findings = [];
 	const excluded = new Set(options.excludeLabels ?? []);
-	if (ZERO_WIDTH_CHARS.test(text) && !excluded.has("unicode_zero_width")) findings.push({
+	if ((ZERO_WIDTH_CHARS.test(text) || ZWJ_OUTSIDE_EMOJI.test(text)) && !excluded.has("unicode_zero_width")) findings.push({
 		label: "unicode_zero_width",
 		category: "unicode_obfuscation",
 		scope: "all"
 	});
+	if (TYPOGRAPHY_CHARS.test(text) && !excluded.has("unicode_typography")) findings.push({
+		label: "unicode_typography",
+		category: "unicode_obfuscation",
+		scope: "all",
+		severity: "report"
+	});
 	if (BIDI_CHARS.test(text) && !excluded.has("unicode_bidi_override")) findings.push({
 		label: "unicode_bidi_override",
 		category: "unicode_obfuscation",
 		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) {
@@ -2205,11 +2303,13 @@ function scanThreats(text, scope = "strict", maxScanChars = 65536, options = NO_
 	}
 	return findings;
 }
-/** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */
+/** Blocking policy (P1-1, v19): a finding blocks unless it is explicitly
+* `report`-only. Pattern findings carry no severity and therefore block as
+* before. */
 function evaluateThreat(text, scope = "strict", maxScanChars = 65536, options = NO_SCAN_OPTIONS) {
 	const findings = scanThreats(text, scope, maxScanChars, options);
 	return {
-		blocked: findings.length > 0,
+		blocked: findings.some((finding) => finding.severity !== "report"),
 		findings
 	};
 }
@@ -2218,27 +2318,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
 /**
@@ -2937,7 +3036,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;
@@ -3138,9 +3237,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([\\s]*[:=][\\s]*)(?:\"([^\"\\r\\n]*)\"|'([^'\\r\\n]*)'|([^\\r\\n]+))", "gi");
+const INLINE_ASSIGNMENT_PATTERN = /* @__PURE__ */ new RegExp("(^|[^\\w-])([\\w-]{0,64}[_\\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\\-][\\w-]{0,64})?)\\b([\\t ]*[:=][\\t ]*)([^\\r\\n]+)", "gi");
+const URL_CREDENTIALS_PATTERN = /([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)([^\s/@]+)@/gi;
 /**
 * Mask credential-shaped text before it crosses a session boundary.
 * @param text - the text about to be sent to a model outside this session.
@@ -3149,7 +3253,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
@@ -3598,6 +3707,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));
 }
@@ -3836,6 +3947,13 @@ function authoringFeedback(frontmatter) {
 		lines
 	};
 }
+/** 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). */
+function isCommittedOnly(error) {
+	return error?.committed === true;
+}
 async function listNames(root, io) {
 	const entries = await io.list(root);
 	const names = [];
@@ -4392,6 +4510,7 @@ var SkillLibrary = class {
 			ok: false,
 			message: "Only the foreground (user or the main agent) may pin or unpin skills."
 		};
+		let durabilityWarning = "";
 		const dir = this.dirOf(normalized);
 		const marker = markerPath(dir, "pinned");
 		const existing = await this.io.exists(marker);
@@ -4409,12 +4528,26 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${normalized}" not found.`
 		};
-		if (pinned) await this.io.writeText(marker, "");
-		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,
-			message: pinned ? `Skill "${normalized}" pinned: protected from deletion, background review, and the lifecycle.` : `Skill "${normalized}" unpinned.`,
+			message: `${pinned ? `Skill "${normalized}" pinned: protected from deletion, background review, and the lifecycle.` : `Skill "${normalized}" unpinned.`}${durabilityWarning === "" ? "" : ` (warning: the write landed but the directory fsync failed — durability unconfirmed: ${durabilityWarning})`}`,
 			path: dir
 		};
 	}
@@ -4456,6 +4589,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,
@@ -4465,20 +4602,31 @@ var SkillLibrary = class {
 		const createPath = join(dir, "SKILL.md");
 		let existsAtCommit = false;
 		let taskRan = false;
-		if (this.transact) await this.transact(this.io, createPath, (current) => {
-			taskRan = true;
-			if (current !== null) {
-				existsAtCommit = true;
-				return current;
-			}
-			return onDisk;
-		});
+		let createDurabilityWarning = "";
+		if (this.transact) try {
+			await this.transact(this.io, createPath, (current) => {
+				taskRan = true;
+				if (current !== null) {
+					existsAtCommit = true;
+					return current;
+				}
+				return onDisk;
+			});
+		} catch (error) {
+			if (!isCommittedOnly(error)) throw error;
+			createDurabilityWarning = error instanceof Error ? error.message : String(error);
+		}
 		else if (await this.io.exists(createPath)) {
 			taskRan = true;
 			existsAtCommit = true;
 		} else {
 			taskRan = true;
-			await this.io.writeText(createPath, onDisk);
+			try {
+				await this.io.writeText(createPath, onDisk);
+			} catch (error) {
+				if (!isCommittedOnly(error)) throw error;
+				createDurabilityWarning = error instanceof Error ? error.message : String(error);
+			}
 		}
 		if (!taskRan) return {
 			ok: false,
@@ -4488,7 +4636,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",
@@ -4497,7 +4655,7 @@ var SkillLibrary = class {
 		});
 		return {
 			ok: true,
-			message: `Skill "${normalized}" created.`,
+			message: `Skill "${normalized}" created.${createDurabilityWarning === "" ? "" : ` (warning: the write landed but the directory fsync failed — durability unconfirmed: ${createDurabilityWarning})`}`,
 			path: dir,
 			...norm.changed ? { normalizedFrontmatterFields: norm.fields } : {}
 		};
@@ -4821,9 +4979,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 {
@@ -4840,27 +4996,33 @@ 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(() => {});
 	}
 	/** A1-4 (v18): a manifest-declared name is copied with `join(root, name)`;
 	* only a single, non-traversing path component is safe. Dotfiles
-	* (`.usage.json`) stay allowed — sidecars are legitimately dot-prefixed. */
+	* (`.usage.json`) stay allowed — sidecars are legitimately dot-prefixed.
+	* P2-4 (v19): a non-string entry (`skills: [123]`) is refused structurally
+	* instead of throwing `name.includes is not a function`. */
 	safeSnapshotEntryName(name) {
+		if (typeof name !== "string") return false;
 		return name !== "" && name !== "." && name !== ".." && !name.includes("/") && !name.includes("\\") && basename(name) === name;
 	}
 	/** A1-7 (v18): a root-level lock whose holder is alive must refuse the
 	* restore; a dead residue is swept so a crashed writer cannot block
 	* recovery. A non-lock body shape is left alone (user file). */
 	async refuseLiveLockOrSweep(lockPath, label) {
-		const body = await this.io.readText(lockPath).catch(() => null);
+		let body;
+		try {
+			body = await this.io.readText(lockPath);
+		} catch (error) {
+			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(() => {});
 	}
@@ -5279,7 +5441,17 @@ var SkillLibrary = class {
 		try {
 			for (const entry of landing) {
 				try {
-					await this.io.writeText(entry.target, entry.content);
+					if (this.transact) {
+						const drift = { seen: false };
+						await this.transact(this.io, entry.target, (current) => {
+							if (current !== entry.previous) {
+								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);
@@ -5494,12 +5666,41 @@ 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}`);
@@ -5581,7 +5782,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,
@@ -5660,13 +5868,19 @@ var SkillLibrary = class {
 	*/
 	async restoreSnapshotIntoRoot(snapshotPath) {
 		const manifest = await this.readSnapshotManifest(snapshotPath);
-		if (manifest === null) {
-			if (await this.io.exists(join(snapshotPath, "manifest.json"))) throw new Error(`snapshot ${snapshotPath} has an unreadable manifest.json; refusing to clear the active tree`);
-		} else {
-			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.skills.length === 0) {
-				if ((await this.io.list(snapshotPath)).some((entry) => entry !== "manifest.json" && entry !== "extras" && entry !== ".archive")) throw new Error(`snapshot ${snapshotPath} declares no skills but contains entries; refusing to clear the active tree`);
-			}
+		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.skills.length === 0) {
+			const snapshotEntries = await this.io.list(snapshotPath);
+			const declared = new Set([
+				"manifest.json",
+				"extras",
+				".archive",
+				...manifest.skills,
+				...manifest.sidecars
+			]);
+			const undeclared = snapshotEntries.filter((entry) => !declared.has(entry));
+			if (undeclared.length > 0) throw new Error(`snapshot ${snapshotPath} declares no skills but contains undeclared entries (${undeclared.join(", ")}); refusing to clear the active tree`);
 		}
 		let rootEntries;
 		try {
@@ -5686,17 +5900,16 @@ var SkillLibrary = class {
 				if (await this.hasWriteLock(dir)) throw new Error(`snapshot restore refused: skill "${entry}" is being written (write lock present); retry once the write completes`);
 			}
 		}
-		const restoresSuppressed = manifest !== null && manifest.sidecars.includes(".curator-suppressed.json");
+		const restoresSuppressed = manifest.sidecars.includes(".curator-suppressed.json");
 		for (const entry of rootEntries) {
 			if (entry === ".archive" || entry === ".backups" || entry === ".mutations.json") continue;
 			if (entry === ".curator-suppressed.json" && restoresSuppressed) continue;
 			if (entry.endsWith(".lock") || entry.endsWith(`.lock.next`)) continue;
 			await this.io.remove(join(this.root, entry));
 		}
-		if (manifest === null) throw new Error(`snapshot ${snapshotPath} has no readable manifest.json; refusing to restore`);
-		else {
-			for (const name of manifest.skills) await this.io.copy(join(snapshotPath, name), join(this.root, name));
-			for (const sidecar of manifest.sidecars) await this.io.copy(join(snapshotPath, sidecar), join(this.root, sidecar));
+		for (const name of manifest.skills) await this.io.copy(join(snapshotPath, name), join(this.root, name));
+		for (const sidecar of manifest.sidecars) await this.io.copy(join(snapshotPath, sidecar), join(this.root, sidecar));
+		{
 			const archiveRoot = join(this.root, ".archive");
 			if (manifest.hasArchive === true) {
 				await this.io.remove(archiveRoot);
@@ -5710,4 +5923,4 @@ var SkillLibrary = class {
 	}
 };
 //#endregion
-export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOCK_BODY_RE, LOCK_SUFFIX, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PATTERN_OVERLAP, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_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/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

@@ -412,7 +412,9 @@ export declare class SkillLibrary {
     private sweepLockIfStranded;
     /** A1-4 (v18): a manifest-declared name is copied with `join(root, name)`;
      * only a single, non-traversing path component is safe. Dotfiles
-     * (`.usage.json`) stay allowed — sidecars are legitimately dot-prefixed. */
+     * (`.usage.json`) stay allowed — sidecars are legitimately dot-prefixed.
+     * P2-4 (v19): a non-string entry (`skills: [123]`) is refused structurally
+     * instead of throwing `name.includes is not a function`. */
     private safeSnapshotEntryName;
     /** A1-7 (v18): a root-level lock whose holder is alive must refuse the
      * restore; a dead residue is swept so a crashed writer cannot block
@@ -472,6 +474,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

package/lib/types/threats.d.ts

@@ -2,15 +2,25 @@
  * Threat scanning for agent-authored memory and skill content.
  *
  * Ported as a small, dependency-free subset of Hermes Agent's
- * `tools/threat_patterns.py` + hermes-claw `threats.ts`. The policy is the
- * load-bearing part: ANY in-scope hit blocks. Severity and category are
- * metadata for diagnostics only.
+ * `tools/threat_patterns.py` + hermes-claw `threats.ts`.
+ *
+ * Policy (P1-1, v19): a finding either BLOCKS the write or only REPORTS.
+ * Blocking is reserved for shapes with no legitimate use in stored knowledge
+ * (prompt-injection phrasing, credential exfiltration, the invisible-character
+ * smuggling core). Typography and presentation characters that are legitimate
+ * in ordinary prose — variation selectors (❤️), zero-width non-joiner, soft
+ * hyphen from PDF paste, Arabic letter mark, Mongolian vowel separator — are
+ * REPORT findings: they stay visible to operators and tests but never reject a
+ * write. Blocking them turned every emoji into a security event.
  */
 export type ThreatScope = 'all' | 'context' | 'strict';
 export interface ThreatFinding {
     label: string;
     category: string;
     scope: ThreatScope;
+    /** P1-1 (v19): `block` (default) refuses the write; `report` is an audit
+     * trail entry only. Absent means `block`. */
+    severity?: 'block' | 'report';
 }
 /**
  * Optional scan controls. Default behavior (`options` omitted) is unchanged:
@@ -39,7 +49,9 @@ export declare const PATTERN_OVERLAP = 4096;
  * characters (skill files may run to 100,000) is no longer a blind zone.
  */
 export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): ThreatFinding[];
-/** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */
+/** Blocking policy (P1-1, v19): a finding blocks unless it is explicitly
+ * `report`-only. Pattern findings carry no severity and therefore block as
+ * before. */
 export declare function evaluateThreat(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): {
     blocked: boolean;
     findings: ThreatFinding[];
@@ -49,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/lib/types/usage.d.ts

@@ -52,7 +52,13 @@ export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<U
  * cannot interleave its RMW and lose a counter update. Callers keep their own
  * single-process serialize chain as the second layer.
  */
-export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>): Promise<void>;
+export interface UsageMutateOptions {
+    /** P2-9 (v19): called when malformed entries had to be quarantined before the
+     * task could run. The guard preserves bytes AND keeps the facility working;
+     * this callback is how that stays observable. */
+    onQuarantine?: ((message: string) => void) | undefined;
+}
+export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>, options?: UsageMutateOptions): Promise<void>;
 /**
  * Curator-owned usage fields (rc.67 K-2): the curator writes ONLY this set —
  * lifecycle state, archive stamp, the six-factor quality pair, and the

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.64",
+  "version": "0.3.66",
   "publishConfig": {
     "access": "public"
   },