agent-purge 0.2.9 → 0.2.11

package/lib/personas.mjs

@@ -1,9 +1,11 @@
 // persona 管理：一个 markdown 文件 = 元数据(frontmatter) + 系统提示词正文。
 // 正文是唯一喂给 harness 的东西；元数据只用来做选择。
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import { loadState, saveState } from "./state.mjs";
+import { listResources, readResource } from "./root.mjs";
+
+const TEMPLATES = "lib/templates/personas/";
 
 const WILD = "*";
 // active.md 是派生物，不是状态：install 指向它、opencode 插件运行时读它 → 真热切。
@@ -19,9 +21,12 @@ export function createStore(root) {
 	// 首次运行（或 npm 安装后的空目录）：从 lib/templates/personas 拷一份中性的起步 persona。
 	{
 		const has = existsSync(dir) && readdirSync(dir).some((f) => f.endsWith(".md") && f !== "active.md");
-		const tpl = join(dirname(fileURLToPath(import.meta.url)), "templates", "personas");
-		if (!has && existsSync(tpl)) {
-			for (const f of readdirSync(tpl)) writeFileSync(join(dir, f), readFileSync(join(tpl, f), "utf8"));
+		if (!has) {
+			try {
+				for (const f of listResources(TEMPLATES)) writeFileSync(join(dir, f), readResource(TEMPLATES + f));
+			} catch {
+				// 模板目录不在（裁剪过/自定义安装）就跳过，不挡人用
+			}
 		}
 	}
 
@@ -54,15 +59,20 @@ export function createStore(root) {
 
 	function remove(id) {
 		if (!isValidId(id)) return false;
+		const wasActive = activeId() === id;
 		rmSync(join(dir, `${id}.md`), { force: true });
 		rmSync(join(build, `${id}.md`), { force: true });
 		// 删的就是 active 时必须改道：否则下次无参启动直接 “没有 persona”。
 		// 落点不抓 list()[0]（那是顺序序，等于静默换人），优先落到 neutral。
-		if (activeId() === id) {
+		if (wasActive) {
 			const all = list();
 			const next = all.find((p) => p.id === "neutral") ?? all[0] ?? null;
 			if (next) setActive(next.id);
-			else writeFileSync(join(dir, ACTIVE_BODY), "You are a helpful coding assistant.\n");
+			else {
+				const { state } = loadState(root);
+				saveState(root, { ...state, persona: null });
+				writeFileSync(join(dir, ACTIVE_BODY), "");
+			}
 		}
 		return true;
 	}

package/lib/private-server.mjs

@@ -0,0 +1,54 @@
+// OpenCode v2 的 prompt 在独立 server 进程执行：父进程直接持有该 PID，不把许可交给 CLI/后代。
+import { randomBytes } from "node:crypto";
+import { prepareCommand, spawnPrepared } from "./spawn.mjs";
+
+export function privateClientArgs(args, url) {
+	if (args.some(value => value === "--server" || value.startsWith("--server="))) throw new Error("本次启动使用独立服务，请移除 --server");
+	return ["--server", url, ...args.filter(value => value !== "--standalone")];
+}
+export async function startPrivateServer(command, { env, cwd, lease, timeout = 20000 }) {
+	const password = randomBytes(32).toString("base64url");
+	// 客户端和服务端使用同一次随机认证；不读取用户已有的服务器密码。
+	env.OPENCODE_PASSWORD = password;
+	delete env.OPENCODE_SERVER_PASSWORD;
+	const descriptor = prepareCommand(command, ["serve", "--stdio", "--hostname", "127.0.0.1", "--port", "0"], { env, cwd, stdio: ["pipe", "pipe", "pipe"] });
+	if (!descriptor.hostDirect) throw new Error("独立服务需要可核验的原生入口");
+	const startedAt = Date.now(), child = spawnPrepared(descriptor);
+	child.on("error", () => {});
+	child.stdin.on("error", () => {});
+	let closed = false, errors = "";
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		child.stdin.end();
+		if (child.exitCode === null) child.kill();
+	};
+	const exited = new Promise(resolve => child.once("close", code => resolve(code)));
+	child.stderr.on("data", chunk => { errors = (errors + chunk.toString()).slice(-2000); });
+	try {
+		if (child.pid) lease?.publish(child.pid, startedAt);
+		const url = await new Promise((resolve, reject) => {
+			let pending = "", settled = false;
+			const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); if (error) reject(error); else resolve(value); };
+			const timer = setTimeout(() => finish(new Error("独立服务启动超时")), timeout);
+			child.once("error", error => finish(error));
+			child.once("exit", code => finish(new Error(`独立服务提前退出 (${code})${errors ? ": " + errors.replaceAll(password, "[redacted]") : ""}`)));
+			child.stdout.on("data", chunk => {
+				if (settled) return;
+				pending += chunk.toString();
+				if (pending.length > 32768) { finish(new Error("独立服务 readiness 超出限制")); return; }
+				let end;
+				while ((end = pending.indexOf("\n")) !== -1) {
+					const line = pending.slice(0, end).trim(); pending = pending.slice(end + 1);
+					if (!line) continue;
+					try {
+						const data = JSON.parse(line), ready = new URL(data.url);
+						if (ready.protocol !== "http:" || !["127.0.0.1", "localhost", "[::1]"].includes(ready.hostname) || !ready.port || ready.username || ready.password || ready.pathname !== "/" || ready.search || ready.hash) throw new Error("readiness URL 不是本机独立服务");
+						finish(null, ready.origin); return;
+					} catch (error) { finish(new Error(`独立服务 readiness 无效：${error.message}`)); return; }
+				}
+			});
+		});
+		return { pid: child.pid, url, exited, close, clientArgs: args => privateClientArgs(args, url) };
+	} catch (error) { lease?.close(); close(); await exited; throw error; }
+}

package/lib/project.mjs

@@ -0,0 +1,134 @@
+// 项目级人设：写进当前项目根的 AGENTS.md / CLAUDE.md 托管块。
+//
+// 为什么要有这条通道：全局配置一改就是全机器生效，改坏了也只能回滚配置；项目块只影响
+// 当前目录，删块即还原，比全局配置更局部也更好解释。撤销走 persist.revertFile（stash 字节还原）。
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { cancel, listLedger, record } from "./footprints.mjs";
+import { readStash, revertFile, stripBlock, upsertBlock, writeStash } from "./persist.mjs";
+import { loadState, patchState } from "./state.mjs";
+import { dataHome } from "./home.mjs";
+
+/** 各家的项目规则文件。没列的家（codebuddy/dsh/antigravity）没有这个落点，不摆开关。 */
+const PROJECT_FILES = {
+	pi: "AGENTS.md",
+	omp: "AGENTS.md",
+	grok: "AGENTS.md",
+	zcode: "AGENTS.md",
+	codex: "AGENTS.md",
+	opencode: "AGENTS.md",
+	opencode2: "AGENTS.md",
+	claude: "CLAUDE.md",
+};
+
+export const projectTargets = PROJECT_FILES;
+export const projectFilePath = (id, dir = process.cwd()) => (PROJECT_FILES[id] ? resolve(dir, PROJECT_FILES[id]) : null);
+const pathKey = path => process.platform === "win32" ? path.toLowerCase() : path;
+
+/** 暂停会撤销磁盘块，因此目录选择单独保存在 state；旧安装只从账本恢复，不猜 cwd。 */
+export function projectDirectories(root, id) {
+	const { state } = loadState(root);
+	const saved = Array.isArray(state.projectDirs?.[id]) ? state.projectDirs[id] : [];
+	const recorded = listLedger(root)
+		.filter(e => e.harness === id && e.channel === "project" && typeof e.path === "string" && isAbsolute(e.path))
+		.map(e => dirname(e.path));
+	const dirs = new Map();
+	for (const path of [...saved, ...recorded]) {
+		if (typeof path !== "string" || !isAbsolute(path)) continue;
+		const dir = resolve(path);
+		dirs.set(pathKey(dir), dir);
+	}
+	return [...dirs.values()];
+}
+
+function saveDirectories(root, id, dirs) {
+	const { state } = loadState(root);
+	const projectDirs = { ...state.projectDirs };
+	if (dirs.length) projectDirs[id] = dirs;
+	else delete projectDirs[id];
+	patchState(root, { projectDirs });
+}
+
+function rememberDirectory(root, id, dir) {
+	const dirs = projectDirectories(root, id);
+	if (!dirs.some(path => pathKey(path) === pathKey(dir))) dirs.push(dir);
+	saveDirectories(root, id, dirs);
+}
+
+/** 项目块优先于全局块（harness 把项目规则放前面），所以两块同时开会两份都进。 */
+export const PROJECT_NOTE = "原生 harness 会共同读取同名规则文件；单文件只登记一个管理归属，同时开全局会有两份";
+
+function ownersOf(root, file) {
+	return Object.keys(PROJECT_FILES).filter(id => projectDirectories(root, id).some(dir => pathKey(projectFilePath(id, dir)) === pathKey(file)));
+}
+
+export function projectInstall(id, { root, active, dir = process.cwd(), paused = false }) {
+	const file = projectFilePath(id, dir);
+	if (!file) return { error: `${id} 没有项目级规则文件（可用: ${Object.keys(PROJECT_FILES).join(", ")}）` };
+	const owners = ownersOf(root, file).filter(owner => owner !== id);
+	if (owners.length) return { error: `项目文件归属冲突：${file} 已登记给 ${owners.join(", ")}，请先撤销原选择`, file, owners };
+	if (paused) {
+		rememberDirectory(root, id, dirname(file));
+		return { file, action: "selected-while-paused" };
+	}
+	const body = String(active ?? "").trim();
+	if (!body) return { error: "没有可用人设" };
+	mkdirSync(dirname(file), { recursive: true });
+	const old = existsSync(file) ? readFileSync(file, "utf8") : null;
+	if (/^(?:\s*)# (?:>>>|<<<) agent-purge/m.test(body)) return { error: `${id}: persona 正文包含 agent-purge 托管标记，拒绝写入` };
+	const next = upsertBlock(old ?? "", body);
+	// 多次同步沿用最初的还原基线；块外被用户编辑时，只移除旧托管块再保存。
+	const previous = readStash(file, root);
+	let before = previous && previous.after === old ? previous.before : old;
+	if (before !== null) before = stripBlock(before);
+	writeStash(file, { file, before, after: next }, root);
+	writeFileSync(file, next);
+	record(root, { kind: "block", harness: id, channel: "project", path: file, undo: { type: "block-revert" } });
+	rememberDirectory(root, id, dirname(file));
+	return { file, action: old === null ? "created" : stripBlock(old) !== old ? "replaced-block" : "appended-block", note: PROJECT_NOTE };
+}
+
+export function projectUninstall(id, { dir = process.cwd(), root = dataHome(), keepSelection = false } = {}) {
+	const file = projectFilePath(id, dir);
+	if (!file) return { error: `${id} 没有项目级规则文件` };
+	const owners = ownersOf(root, file);
+	if (owners.length && !owners.includes(id)) return { file, action: "not-owner", owners };
+	if (owners.length > 1) return { error: `旧项目归属冲突：${file} (${owners.join(", ")})，请先核对账本`, file };
+	// 在撤销账本前保存旧安装的目录，暂停后仍可恢复到同一位置。
+	if (root && keepSelection) rememberDirectory(root, id, dirname(file));
+	const r = revertFile(file, { root });
+	if (root && !r.error) {
+		cancel(root, { kind: "block", path: file });
+		if (!keepSelection) saveDirectories(root, id, projectDirectories(root, id).filter(path => pathKey(path) !== pathKey(dirname(file))));
+	}
+	return r;
+}
+
+/**
+ * 现场状态。同一个 AGENTS.md 可能被好几家共用，所以「开着」必须靠账本归属到具体 harness：
+ * 块在文件里、账本又有这条记录才算开着（账本丢了就说不知道，不自作主张）。
+ */
+export function projectStatus(dir = process.cwd(), root) {
+	const entries = root ? listLedger(root).filter((e) => e.channel === "project") : null;
+	return Object.entries(PROJECT_FILES).map(([id, name]) => {
+		const file = resolve(dir, name);
+		const text = existsSync(file) ? readFileSync(file, "utf8") : null;
+		const hasBlock = text !== null && stripBlock(text) !== text;
+		const mine = entries ? entries.some((e) => e.harness === id && typeof e.path === "string" && pathKey(e.path) === pathKey(file)) : hasBlock;
+		const selected = root ? projectDirectories(root, id).some(path => pathKey(path) === pathKey(dirname(file))) : hasBlock;
+		return { id, file, hasBlock, on: hasBlock && mine, selected };
+	});
+}
+
+/**
+ * git 仓库里没被跟踪的规则文件，改完容易意外进提交。只提示，不替用户改 .gitignore。
+ * 返回 null = 不需要提示（不是 git 仓库 / 文件已被跟踪 / 没有 git）。
+ */
+export function gitHint(id, dir = process.cwd()) {
+	const name = PROJECT_FILES[id];
+	if (!name || !existsSync(join(dir, ".git"))) return null;
+	const run = spawnSync("git", ["-C", dir, "ls-files", "--error-unmatch", "--", name], { encoding: "utf8" });
+	if (run.error || run.status === 0) return null;
+	return `${name} 还没被 git 跟踪：不想提交这份人设就 git update-index --skip-worktree ${name} 或写进 .gitignore（不自动改）`;
+}

package/lib/restore.mjs

@@ -1,114 +1,131 @@
-// 崩溃安全的文件交换。
-//
-// 为什么需要它：bench / launch 会临时改写 harness 自己的配置（hermes 的 config.yaml、
-// opencode 插件、codex 的 config.toml）。如果进程被 Ctrl-C、OOM 或超时杀掉，
-// 只在内存里保存"原内容"是回不去的 —— 实测中 hermes 的 config.yaml 就被留在了半改状态，
-// 下一次启动直接 duplicate key 报错。
-//
-// 做法：每次改写前把原文落到 journal 目录（os.tmpdir()/agent-purge-restore），
-// 进程正常退出 / 收到信号 / 下次启动时统一回滚。undo() 幂等。
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-const JOURNAL_DIR = path.join(os.tmpdir(), "agent-purge-restore");
-const ENTRY = "restore.json";
-
-let installed = false;
-const live = new Set();
-
-function ensureDir() {
-	try {
-		fs.mkdirSync(JOURNAL_DIR, { recursive: true });
-	} catch {}
-}
-
-function entryPath(file) {
-	// 同一文件在 journal 里只应有一条；用稳定 hash 命名，避免路径分隔符
-	const h = Buffer.from(file.toLowerCase()).toString("base64url").slice(0, 40);
-	return path.join(JOURNAL_DIR, h + ".json");
-}
-
-/**
- * 原子写 + 记录 journal。返回幂等的 undo()。
- * @param {string} file 绝对路径
- * @param {string} content 新内容
- */
-export function swapFile(file, content) {
-	ensureDir();
-	const exists = fs.existsSync(file);
-	const backup = exists ? fs.readFileSync(file, "utf8") : null;
-	const record = { file, exists, backup, at: new Date().toISOString() };
-	fs.writeFileSync(entryPath(file), JSON.stringify(record), "utf8");
-
-	const tmp = file + ".purge-tmp";
-	fs.writeFileSync(tmp, content, "utf8");
-	fs.renameSync(tmp, file);
-
-	let done = false;
-	const undo = () => {
-		if (done) return;
-		done = true;
-		live.delete(undo);
-		try {
-			if (record.exists) fs.writeFileSync(file, record.backup, "utf8");
-			else if (fs.existsSync(file)) fs.unlinkSync(file);
-		} catch {}
-		try {
-			fs.rmSync(entryPath(file), { force: true });
-		} catch {}
-	};
-	live.add(undo);
-	return undo;
-}
-
-/** 回滚所有 journal 里残留的条目（上次进程没来得及 undo）。返回恢复的文件数。 */
-export function recover() {
-	ensureDir();
-	let n = 0;
-	for (const name of fs.readdirSync(JOURNAL_DIR)) {
-		if (!name.endsWith(".json")) continue;
-		const p = path.join(JOURNAL_DIR, name);
-		try {
-			const r = JSON.parse(fs.readFileSync(p, "utf8"));
-			if (r.exists) fs.writeFileSync(r.file, r.backup, "utf8");
-			else if (fs.existsSync(r.file)) fs.unlinkSync(r.file);
-			fs.rmSync(p, { force: true });
-			n++;
-		} catch {}
-	}
-	return n;
-}
-
-/** 安装信号钩子：SIGINT/SIGTERM/SIGHUP/uncaughtException/exit 都回滚。幂等。 */
-export function installCrashHandlers() {
-	if (installed) return;
-	installed = true;
-	const flush = (code) => {
-		for (const u of [...live]) {
-			try {
-				u();
-			} catch {}
-		}
-		recover();
-		process.exit(code);
-	};
-	for (const sig of ["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK"]) {
-		try {
-			process.on(sig, () => flush(sig === "SIGINT" ? 130 : 143));
-		} catch {}
-	}
-	process.on("uncaughtException", (e) => {
-		console.error("[restore] 未捕获异常，回滚配置：", e?.message ?? e);
-		flush(1);
-	});
-	process.on("exit", () => {
-		for (const u of [...live]) {
-			try {
-				u();
-			} catch {}
-		}
-	});
-}
-
-export const journalDir = JOURNAL_DIR;
+// 临时文件交换：独占 journal + 所有者存活检查 + 写后指纹。
+// 冲突或恢复失败保留 journal，不覆盖用户在测试期间的修改。
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+
+const JOURNAL_DIR = process.env.AGENT_PURGE_JOURNAL_DIR || path.join(os.tmpdir(), "agent-purge-restore");
+let installed = false;
+const live = new Set();
+const hash = (bytes) => bytes === null ? null : createHash("sha256").update(bytes).digest("hex");
+const read = (file) => { try { return fs.readFileSync(file); } catch (e) { if (e.code === "ENOENT") return null; throw e; } };
+function canonical(file) {
+	const full = path.resolve(file);
+	// 同一目录的符号链接也应指向同一把锁；不跟随不存在的目标。
+	try { return fs.realpathSync(full); } catch (e) {
+		if (e.code !== "ENOENT") throw e;
+		return path.join(fs.realpathSync(path.dirname(full)), path.basename(full));
+	}
+}
+function entryPath(file) {
+	const key = process.platform === "win32" ? file.toLowerCase() : file;
+	return path.join(JOURNAL_DIR, createHash("sha256").update(key).digest("hex") + ".json");
+}
+function alive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return true;
+	try { process.kill(pid, 0); return true; } catch (e) { return e.code !== "ESRCH"; }
+}
+function atomicWrite(file, bytes, mode) {
+	const tmp = file + ".purge-" + randomUUID() + ".tmp";
+	try {
+		fs.writeFileSync(tmp, bytes, { flag: "wx", mode: mode ?? 0o600 });
+		fs.renameSync(tmp, file);
+	} finally { fs.rmSync(tmp, { force: true }); }
+}
+function restore(record, journal) {
+	let currentRecord;
+	try {
+		const source = fs.readFileSync(journal, "utf8");
+		currentRecord = JSON.parse(source);
+	} catch (error) {
+		throw new Error(`无法读取恢复凭据，文件未改动：${journal}`, { cause: error });
+	}
+	if (currentRecord.operation !== record.operation) throw new Error(`恢复所有权已改变：${record.file}`);
+	const current = hash(read(record.file));
+	if (current !== record.beforeHash && current !== record.afterHash) {
+		throw new Error(`文件在交换后被修改，保留 journal 等待处理：${record.file}`);
+	}
+	if (current !== record.beforeHash) {
+		if (record.backup === null) fs.rmSync(record.file, { force: true });
+		else atomicWrite(record.file, Buffer.from(record.backup, "base64"), record.mode);
+	}
+	fs.rmSync(journal);
+}
+
+/** 独占交换；返回可重试、幂等的 undo。恢复失败会抛错且保留原始备份。 */
+export function swapFile(file, content) {
+	file = canonical(file);
+	fs.mkdirSync(JOURNAL_DIR, { recursive: true });
+	const journal = entryPath(file);
+	let fd;
+	try { fd = fs.openSync(journal, "wx", 0o600); }
+	catch (e) {
+		if (e.code === "EEXIST") throw new Error(`文件存在未结束的交换，请先处理 journal：${file}`);
+		throw e;
+	}
+	let record;
+	try {
+		const backup = read(file);
+		const next = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+		record = { version: 2, file, pid: process.pid, operation: randomUUID(), at: new Date().toISOString(),
+			backup: backup === null ? null : backup.toString("base64"), beforeHash: hash(backup), afterHash: hash(next),
+			mode: backup === null ? undefined : fs.statSync(file).mode & 0o777 };
+		fs.writeFileSync(fd, JSON.stringify(record));
+		fs.fsyncSync(fd);
+		fs.closeSync(fd); fd = undefined;
+		atomicWrite(file, next, record.mode);
+	} catch (e) {
+		if (fd !== undefined) fs.closeSync(fd);
+		if (record) { try { restore(record, journal); } catch {} }
+		else fs.rmSync(journal, { force: true });
+		throw e;
+	}
+	let done = false;
+	const undo = () => {
+		if (done) return;
+		restore(record, journal);
+		done = true;
+		live.delete(undo);
+	};
+	live.add(undo);
+	return undo;
+}
+
+/** 只恢复已死亡的 v2 所有者；旧格式无法证明所有权，保留并报告。 */
+export function recover({ onWarning = (message) => console.error(`[restore] ${message}`) } = {}) {
+	fs.mkdirSync(JOURNAL_DIR, { recursive: true });
+	let n = 0;
+	for (const name of fs.readdirSync(JOURNAL_DIR)) {
+		if (!name.endsWith(".json")) continue;
+		const journal = path.join(JOURNAL_DIR, name);
+		try {
+			const record = JSON.parse(fs.readFileSync(journal, "utf8"));
+			if (record.version !== 2 || !record.operation || !path.isAbsolute(record.file || "")) {
+				onWarning(`旧版或不完整 journal，未自动覆盖文件：${journal}`); continue;
+			}
+			if (alive(record.pid)) continue;
+			restore(record, journal); n++;
+		} catch (e) { onWarning(`${journal}: ${e.message}`); }
+	}
+	return n;
+}
+
+export function installCrashHandlers() {
+	if (installed) return;
+	installed = true;
+	const flush = () => {
+		for (const undo of [...live]) {
+			try { undo(); } catch (e) { console.error(`[restore] ${e.message}`); }
+		}
+	};
+	for (const sig of ["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK"]) {
+		try { process.on(sig, () => { flush(); process.exit(sig === "SIGINT" ? 130 : 143); }); } catch {}
+	}
+	process.on("uncaughtException", (e) => {
+		console.error("[restore] 未捕获异常：", e?.stack ?? e);
+		flush(); process.exit(1);
+	});
+	process.on("exit", flush);
+}
+export const journalDir = JOURNAL_DIR;

package/lib/rewrite.mjs

@@ -0,0 +1,124 @@
+// 模式语义与生成插件共享实现；运行时只还原有来源记录的完整变换。
+import { activationRuntime } from "./activation.mjs";
+export function stripIdentity(text) {
+	const self = /^\s*(?:You are|You're|你是|您是|我(?:是|现在扮演|就是))/i;
+	const named = /(Claude|ChatGPT|GPT-?[45]|Gemini|Codex|Copilot|DeepSeek|Qwen|Kimi|GLM|Cursor|Windsurf|OpenCode|ZCode|CodeBuddy|Hermes|Grok|Antigravity|AI (?:assistant|model)|coding (?:assistant|agent)|语言模型|助手)/i;
+	return String(text ?? "").split(/\r?\n/).filter(line => !(self.test(line) && named.test(line))).join("\n").trim();
+}
+
+export function cleanManaged(text, bodies = []) {
+	let out = String(text ?? "").replace(/^# >>> agent-purge[^\S\r\n]*\r?\n[\s\S]*?^# <<< agent-purge[^\S\r\n]*(?:\r?\n|$)/gm, "");
+	for (const body of bodies) {
+		if (!body) continue;
+		// 只删除独立完整正文；共享前40字符的另一份人设/用户规则不匹配。
+		const literal = String(body).trim().replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		out = out.replace(new RegExp("(^|\\n)" + literal + "(?=\\n|$)", "g"), "$1");
+	}
+	return out.trim();
+}
+
+export function rewriteTexts(hostTexts, persona, mode) {
+	if (mode === "off" || !persona) return hostTexts;
+	const host = (Array.isArray(hostTexts) ? hostTexts : []).map(t => String(t ?? "")).filter(t => t.trim());
+	if (mode === "strict") return [persona];
+	if (mode === "append") return [...host, persona];
+	return [persona, ...host.map(stripIdentity).filter(Boolean)];
+}
+
+export function rewriteSections(sections, persona, mode, name = "agent-purge") {
+	const list = Array.isArray(sections) ? sections : [];
+	if (mode === "off" || !persona) return list;
+	if (mode === "strict") return [{ name, text: persona, interpolate: false }];
+	if (mode === "append") return [...list, { name, text: persona, interpolate: false }];
+	const kept = list.map(s => typeof s?.text === "string" ? { ...s, text: stripIdentity(s.text) } : s)
+		.filter(s => typeof s?.text !== "string" || s.text.trim());
+	return [{ name, text: persona, interpolate: false }, ...kept];
+}
+
+/** 有界完整变换记录：无凭据或歧义时原样保留，不按标签/人设文本猜测删除。 */
+export function createProvenance(limit = 64) {
+	const values = new Map();
+	const objects = new WeakMap();
+	const key = value => JSON.stringify(value);
+	function remember(before, after, aliases = []) {
+		const beforeKey = key(before), afterKey = key(after);
+		if (beforeKey === afterKey) return after;
+		const entry = { before: structuredClone(before), beforeKey, afterKey };
+		if (after && typeof after === "object") objects.set(after, entry);
+		for (const candidate of [after, ...aliases]) {
+			const id = key(candidate), previous = values.get(id);
+			values.set(id, previous && previous.beforeKey !== beforeKey ? { ambiguous: true } : previous?.ambiguous ? previous : entry);
+		}
+		while (values.size > limit) values.delete(values.keys().next().value);
+		return after;
+	}
+	function restore(value) {
+		const id = key(value);
+		const direct = value && typeof value === "object" ? objects.get(value) : null;
+		const entry = direct?.afterKey === id ? direct : values.get(id);
+		return entry && !entry.ambiguous ? structuredClone(entry.before) : value;
+	}
+	return { remember, restore };
+}
+
+export function createTextRewriter() {
+	const provenance = createProvenance();
+	return (texts, persona, mode) => {
+		const host = provenance.restore(texts);
+		if (mode === "off" || !persona) return host;
+		const next = rewriteTexts(host, persona, mode);
+		return provenance.remember(host, next, [[next.join("\n\n")]]);
+	};
+}
+
+export function createSectionRewriter() {
+	const provenance = createProvenance();
+	return (sections, persona, mode, name = "agent-purge") => {
+		const host = provenance.restore(sections);
+		if (mode === "off" || !persona) return host;
+		return provenance.remember(host, rewriteSections(host, persona, mode, name));
+	};
+}
+
+/** Anthropic-style content blocks: retain non-text blocks and cache metadata. */
+export function createContentRewriter() {
+	const provenance = createProvenance();
+	return (blocks, persona, mode) => {
+		const host = provenance.restore(blocks);
+		if (mode === "off" || !persona || !Array.isArray(host)) return host;
+		let next;
+		if (mode === "strict") {
+			const text = host.find(b => b?.type === "text");
+			const own = { ...text, type: "text", text: persona };
+			next = [own, ...host.filter(b => b?.type !== "text")];
+		} else {
+			const kept = mode === "replace" ? host.map(b => typeof b?.text === "string" ? { ...b, text: stripIdentity(b.text) } : b) : host;
+			const own = { type: "text", text: persona };
+			next = mode === "append" ? [...kept, own] : [own, ...kept];
+		}
+		return provenance.remember(host, next);
+	};
+}
+
+export const rewriteRuntime = [stripIdentity, cleanManaged, rewriteTexts, rewriteSections, createProvenance, createTextRewriter, createSectionRewriter, createContentRewriter]
+	.map(fn => fn.toString()).join("\n") + `
+const apStrip = stripIdentity;
+const apRewrite = createTextRewriter();
+const apRewriteSections = createSectionRewriter();
+const apRewriteContent = createContentRewriter();
+`;
+
+export const resolveRuntime = activationRuntime;
+
+/** 覆盖指定的人设直接读 personas/<id>.md（剥掉 frontmatter）；读不到再回退嵌入的 active.md。 */
+export const personaBodyRuntime = `
+function resolvePersonaBody(personas, id, fallback) {
+  if (id && id !== "active" && /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(id)) {
+    try {
+      const raw = readFileSync(personas + "/" + id + ".md", "utf8").replace(/^---\\r?\\n[\\s\\S]*?\\r?\\n---(?:\\r?\\n|$)/, "");
+      if (raw.trim()) return raw.trim();
+    } catch { return ""; }
+  }
+  return readFileSync(fallback, "utf8").trim();
+}
+`;

package/lib/root.mjs

@@ -0,0 +1,37 @@
+// 随包资源访问：源码态读磁盘，bun --compile 产物读内嵌表。
+//
+// 为什么不是「算一个 ROOT 再 join」：实测（bun 1.3.14, Windows）
+//   - `[dir]/[name].[ext]` 命名下根目录文件变成 `B:/~BUN/root/./matrix.json`，readFileSync 直接 ENOENT；
+//   - 拼接出来的 `B:/~BUN/root/matrix.json` 同样打不开；
+//   - bunfs 目录不支持 readdir。
+// 只有「原样用 import 拿到的路径」能读，所以编译态的每条路径都由 build 入口生成的表给出，
+// 键 = 仓库相对路径（posix 分隔）。源码态保持原来的 join(包根, 相对路径) 行为。
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const FILES = globalThis.__AGENT_PURGE_FILES ?? null;
+
+export const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** 编译态：资源在 bunfs 里只读，任何「往包目录写」的逻辑都要绕开 */
+export const isCompiled = () => FILES !== null;
+
+/** 读一个随包资源（仓库相对路径，posix 分隔）：matrix.json / web/ui.html / lib/templates/... */
+export function readResource(rel) {
+	const hit = FILES?.[rel];
+	if (hit) return readFileSync(hit);
+	if (FILES) throw new Error(`exe 里没内嵌 ${rel}（scripts/build-exe.mjs 的 assets() 漏了它）`);
+	return readFileSync(join(ROOT, rel));
+}
+
+/** 列一个资源目录下的文件名（不含子目录）：编译态筛内嵌表，源码态真读目录 */
+export function listResources(prefix) {
+	const dir = prefix.endsWith("/") ? prefix : `${prefix}/`;
+	if (FILES) {
+		return Object.keys(FILES)
+			.filter((k) => k.startsWith(dir) && !k.slice(dir.length).includes("/"))
+			.map((k) => k.slice(dir.length));
+	}
+	return readdirSync(join(ROOT, dir));
+}