agent-purge 0.2.9 → 0.2.11

package/lib/environment.mjs

@@ -0,0 +1,36 @@
+// 只传递运行时所需的系统变量；测试、抓包与构建 smoke 共用隔离边界。
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+export function ownShimDirectory(env = process.env) {
+	return resolve(env.AGENT_PURGE_SHIM_DIR || join(env.AGENT_PURGE_HOME || join(env.USERPROFILE || env.HOME || homedir(), ".agent-purge"), "bin"));
+}
+
+const INTERNAL = new Set([
+	"AGENT_PURGE_FORCE", "AGENT_PURGE_MODE", "AGENT_PURGE_PERSONA",
+	"AGENT_PURGE_LAUNCH", "AGENT_PURGE_LAUNCH_FILE", "AGENT_PURGE_PS_ARGS",
+]);
+
+export function launchEnvironment(env = process.env) {
+	return Object.fromEntries(Object.entries(env).filter(([key]) => !INTERNAL.has(key.toUpperCase())));
+}
+
+export function isolatedEnv(root, source = process.env) {
+	const env = {};
+	for (const key of ["PATH", "Path", "SystemRoot", "WINDIR", "ComSpec", "COMSPEC", "PATHEXT", "ProgramFiles", "ProgramFiles(x86)"])
+		if (source[key]) env[key] = source[key];
+	env.HOME = env.USERPROFILE = join(root, "home");
+	env.TEMP = env.TMP = join(root, "tmp");
+	for (const key of [
+		"APPDATA", "LOCALAPPDATA", "AGENT_PURGE_HOME", "AGENT_PURGE_SHIM_DIR", "AGENT_PURGE_JOURNAL_DIR",
+		"PI_CODING_AGENT_DIR", "PI_HOME", "OMP_HOME", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "CODEBUDDY_HOME",
+		"GROK_HOME", "HERMES_HOME", "DSH_HOME", "ZCODE_HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "XDG_STATE_HOME",
+	]) env[key] = join(root, key);
+	for (const value of new Set(Object.values(env))) if (value.startsWith(root)) mkdirSync(value, { recursive: true });
+	Object.assign(env, {
+		AGENT_PURGE_ISOLATED: "1", NO_COLOR: "1", DO_NOT_TRACK: "1", CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1", DISABLE_AUTOUPDATER: "1",
+		OPENCODE_DISABLE_AUTOUPDATE: "true", OPENCODE_DISABLE_MODELS_FETCH: "true", OPENCODE_DISABLE_LSP_DOWNLOAD: "true",
+	});
+	return env;
+}

package/lib/evidence.mjs

@@ -0,0 +1,41 @@
+// Pure evidence model shared by the Web UI and Node control plane.
+// An isolated capability test is never proof about an already-running session.
+const array = value => Array.isArray(value) ? value : [];
+const mainRequests = mode => array(mode?.requests).filter(request => request && (request.kind === undefined || request.kind === 'main'));
+export const privilegedHit = request => Number(request?.markerCount) > 0 &&
+  array(request?.roles).some(role => role === 'system' || role === 'developer');
+export const sysHit = result => array(result?.modes).some(mode => mainRequests(mode).some(privilegedHit));
+
+export function captureScopeLabel(scope) {
+  if (scope?.kind === 'isolated-cli') return `隔离 CLI${scope.profile ? `（${scope.profile}）` : ''}`;
+  if (scope?.kind === 'isolated-session') return `隔离同会话${scope.profile ? `（${scope.profile}）` : ''}`;
+  return '历史隔离测试（未记录入口）';
+}
+
+export function verificationEvidence(result) {
+  const view = (state, label, kind = 'warn') => ({ state, label, kind, runtimeConfirmed: false });
+  if (!result) return view('not-tested', '未实测', '');
+  if (['missing', 'unavailable'].includes(result.status)) return view('unavailable', '未找到入口');
+  if (result.status === 'blocked') return view('blocked', '验证受阻');
+  if (result.status === 'error') return view('error', '验证出错');
+  if (result.status === 'no-request') return view('no-request', '未捕获请求');
+  const modes = array(result.modes);
+  if (!modes.length) return view('invalid', '无有效证据');
+  if (modes.some(m => m?.timedOut || (m?.exitCode !== undefined && m.exitCode !== 0) || m?.status === 'error'))
+    return view('error', '验证出错');
+  const hasRequests = modes.some(m => mainRequests(m).length > 0);
+  if (!hasRequests) return view('no-request', '未捕获请求');
+  if (modes.some(m => !mainRequests(m).length || m?.status === 'no-request'))
+    return view('partial', '验证未完成');
+  if (modes.every(m => m?.mode === 'off')) {
+    return modes.every(m => m.status === 'captured' && mainRequests(m).every(r => r.markerCount === 0))
+      ? view('off-verified', '暂停验证通过', 'blue') : view('mismatch', '暂停仍有残留');
+  }
+  const active = modes.filter(m => m?.mode !== 'off');
+  const hits = active.flatMap(mainRequests);
+  if (!hits.some(privilegedHit)) return view('miss', '请求未命中');
+  if (result.status !== 'captured' || modes.some(m => m?.status !== 'captured') ||
+      hits.some(r => !privilegedHit(r) || r.markerCount !== 1))
+    return view('partial', '请求部分命中');
+  return view('verified', '隔离测试命中', 'good');
+}

package/lib/extension.mjs

@@ -0,0 +1,140 @@
+// pi/omp 使用同一生成器；源码与生成运行时共用启用、锁和来源追踪实现。
+import { resolveRuntime, rewriteRuntime } from "./rewrite.mjs";
+import { launchRuntime } from "./launch.mjs";
+import { controlRuntime } from "./control.mjs";
+
+export function extensionSource(root, harness) {
+	return `// agent-purge 托管扩展：每轮读取配置；首次安装/更新后重载扩展。
+import { readFileSync } from "node:fs";
+${controlRuntime}
+const HOME = ${JSON.stringify(root)};
+const STATE = HOME + "/state.json";
+const PERSONAS = HOME + "/personas/";
+const HARNESS = ${JSON.stringify(harness)};
+const AUTO = HARNESS + "Auto";
+${rewriteRuntime}
+${resolveRuntime}
+${launchRuntime}
+function readState() {
+  try {
+    const st = JSON.parse(readFileSync(STATE, "utf8"));
+    return st && typeof st === "object" && !Array.isArray(st) ? st : null;
+  } catch { return null; }
+}
+function loadPersona(id) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(id || "") || id === "active") return { id: null, body: "" };
+  try {
+    const raw = readFileSync(PERSONAS + id + ".md", "utf8").replace(/^---\\r?\\n[\\s\\S]*?\\r?\\n---(?:\\r?\\n|$)/, "");
+    return { id, body: raw.trim() };
+  } catch { return { id, body: "" }; }
+}
+export default function agentPurge(api) {
+  let forced = null, explicitMode = null, commandEpoch = null;
+  let rewrite = createTextRewriter();
+  let messageRecords = new Map(), generated = createProvenance(), bridge = null;
+  function config() {
+    const st = readState();
+    const launch = readLaunch(HOME, st, HARNESS);
+    const epoch = (st?.activationEpoch || "initial") + ":" + (st?.harnessEpochs?.[HARNESS] || "initial");
+    if (commandEpoch && commandEpoch !== epoch) { forced = null; explicitMode = null; commandEpoch = null; }
+    const c = resolveActivation(st, HARNESS, { channel: "slash", session: forced, launch: !!launch,
+      mode: explicitMode || launch?.mode, persona: launch?.persona });
+    // CLI 参数已注入时，这个进程的常驻扩展只负责撤销自己以前写的内容。
+    if (launch?.writer === "cli") c.on = false;
+    const persona = loadPersona(c.persona);
+    return { ...c, st, ...persona, on: c.on && !!persona.body, epoch };
+  }
+  function recordFor(msg, index) {
+    const key = msg.role + ":" + (msg.id ?? msg.timestamp ?? index);
+    if (!messageRecords.has(key)) messageRecords.set(key, createProvenance());
+    while (messageRecords.size > 64) messageRecords.delete(messageRecords.keys().next().value);
+    return messageRecords.get(key);
+  }
+  api.on("session_start", async () => {
+    forced = null; explicitMode = null; commandEpoch = null;
+    rewrite = createTextRewriter(); messageRecords = new Map(); generated = createProvenance(); bridge = null;
+  });
+  api.on("before_agent_start", async event => {
+    const c = config();
+    const input = Array.isArray(event.systemPrompt) ? event.systemPrompt : [event.systemPrompt ?? ""];
+    const restored = rewrite(input, "", "off");
+    const next = rewrite(input, c.on ? c.body : "", c.on ? c.mode : "off");
+    if (c.on) bridge = { before: restored.join("\\n\\n"), after: next.join("\\n\\n") };
+    return { systemPrompt: HARNESS === "omp" ? next : next.join("\\n\\n") };
+  });
+  if (HARNESS === "pi") {
+    try {
+      api.on("context_with_system", async event => {
+        if (!Array.isArray(event.messages)) return;
+        const c = config(), messages = event.messages;
+        // 只有完整匹配本会话生成消息的来源记录才删除，宿主/用户同名标签不参与清洗。
+        for (let i = messages.length - 1; i >= 0; i--) if (generated.restore(messages[i]) === null) messages.splice(i, 1);
+        for (let i = 0; i < messages.length; i++) {
+          const msg = messages[i];
+          if (msg.role !== "system" && msg.role !== "user") continue;
+          const provenance = recordFor(msg, messages.slice(0, i).filter(m => m.role === msg.role).length);
+          let host = provenance.restore(msg.content);
+          if (msg.role === "system" && bridge) {
+            if (host === bridge.after) host = bridge.before;
+            else if (Array.isArray(host)) host = host.map(b => b?.text === bridge.after ? { ...b, text: bridge.before } : b);
+          }
+          let next = host;
+          if (msg.role === "system" && c.on) {
+            next = typeof host === "string" ? rewriteTexts([host], c.body, c.mode).join("\\n\\n") : createContentRewriter()(host, c.body, c.mode);
+          }
+          msg.content = provenance.remember(host, next);
+        }
+        if (c.on && !messages.some(m => m.role === "system")) {
+          const own = { role: "system", content: c.body };
+          generated.remember(null, own); messages.unshift(own);
+        }
+        if (c.on && c.st.piUserLayer) {
+          const index = messages.findLastIndex(m => m.role === "user");
+          if (index >= 0) {
+            const msg = messages[index], provenance = recordFor(msg, messages.slice(0, index).filter(m => m.role === msg.role).length);
+            const host = provenance.restore(msg.content);
+            const prefix = "<agent-purge>\\n" + c.body + "\\n</agent-purge>\\n\\n";
+            const next = typeof host === "string" ? prefix + host : [{ type: "text", text: prefix }, ...(Array.isArray(host) ? host : [])];
+            msg.content = provenance.remember(host, next);
+          }
+        }
+      });
+    } catch { /* 旧宿主只支持 before_agent_start */ }
+  }
+  api.registerCommand("purge", {
+    description: "会话开关、人设与模式（跟随 agent-purge 配置）",
+    getArgumentCompletions: prefix => ["on", "off", "always", "status", "reload", "mode"].filter(v => v.startsWith(prefix)).map(value => ({ value, label: value })),
+    handler: async (args, ctx) => {
+      const [cmd = "", want] = String(args).trim().split(/\\s+/);
+      const tell = (text, level = "info") => ctx.ui.notify(text, level);
+      const c = config();
+      if (cmd === "status" || cmd === "reload") return tell("状态: " + (c.on ? "开启" : "关闭") + "\\n模式: " + c.mode + "\\n人设: " + (c.id || "未设置") + "\\n启用来源: " + (c.source || c.blockedBy || "无") + "\\n配置: " + STATE);
+      if (cmd === "off" || (!cmd && c.on)) { forced = false; commandEpoch = c.epoch; return tell("本会话已关闭；下一轮撤销有来源记录的内容"); }
+      if (cmd === "on" || !cmd) {
+        const activation = resolveActivation(c.st, HARNESS, { channel: "slash", session: true });
+        if (!activation.on) return tell("当前未启用: " + activation.blockedBy, "error");
+        if (!c.body) return tell("没有可用人设", "error");
+        forced = true; commandEpoch = c.epoch;
+        return tell("本会话已开启，下一轮读取当前人设");
+      }
+      if (cmd === "mode") {
+        if (!["strict", "replace", "append"].includes(want)) return tell("用法: /purge mode strict|replace|append", "error");
+        explicitMode = want; commandEpoch = c.epoch;
+        return tell("本会话模式 → " + want + "；暂停和执行器停用仍优先");
+      }
+      if (cmd === "always") {
+        if (!["on", "off"].includes(want)) return tell("用法: /purge always on|off", "error");
+        try {
+          withControlLock(HOME, () => {
+            const st = readState(); if (!st) throw new Error("配置缺失或损坏");
+            atomicControlJSON(STATE, { ...st, [AUTO]: want === "on" });
+          });
+          return tell("裸启动自动应用 → " + want + "；通道选择和暂停保持不变");
+        } catch (e) { return tell(e.message, "error"); }
+      }
+      tell("用法: /purge [on|off|status|reload|mode strict|replace|append|always on|off]", "error");
+    },
+  });
+}
+`;
+}

package/lib/footprints.mjs

@@ -0,0 +1,59 @@
+// 足迹账本保留写入路径、所有者与还原方式；损坏时保留原文件并停止销账。
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { atomicControlJSON, withControlLock } from "./control.mjs";
+
+const keyOf = path => process.platform === "win32" ? resolve(path).toLowerCase() : resolve(path);
+const sameLocation = (a, b) => (a.kind ?? "file") === (b.kind ?? "file") && keyOf(a.path) === keyOf(b.path);
+const sameOwner = (a, b) => sameLocation(a, b) && a.harness === b.harness && a.channel === b.channel;
+const idOf = entry => createHash("sha256").update([entry.kind ?? "file", keyOf(entry.path), entry.harness ?? "", entry.channel ?? ""].join("\0")).digest("hex").slice(0, 24);
+export const ledgerFile = root => join(root, "footprints.json");
+
+export function loadLedger(root) {
+	const file = ledgerFile(root);
+	try {
+		const raw = JSON.parse(readFileSync(file, "utf8"));
+		if (!Array.isArray(raw?.entries) || raw.entries.some(e => !e || typeof e.path !== "string" || !e.path || typeof e.undo?.type !== "string")) throw new Error("账本结构无效");
+		return { version: 1, entries: raw.entries };
+	} catch (error) {
+		if (error.code === "ENOENT") return { version: 1, entries: [] };
+		throw new Error(`足迹账本损坏，原文件已保留：${file}`, { cause: error });
+	}
+}
+export function saveLedger(root, entries) {
+	return withControlLock(root, () => atomicControlJSON(ledgerFile(root), { version: 1, entries }));
+}
+
+/** 同一位置、harness、channel 幂等；共享 PATH 不会互相覆盖所有权。 */
+export function record(root, entry) {
+	if (!entry?.path || !entry?.undo?.type) throw new Error("足迹缺少路径或撤销方式");
+	return withControlLock(root, () => {
+		const ledger = loadLedger(root), at = ledger.entries.findIndex(e => sameOwner(e, entry));
+		const previous = at >= 0 ? ledger.entries[at] : null;
+		const next = { ...previous, ...entry, id: idOf(entry), createdAt: previous?.createdAt ?? entry.createdAt ?? new Date().toISOString() };
+		if (!entry.sha256 && entry.kind !== "path" && existsSync(entry.path)) next.sha256 = createHash("sha256").update(readFileSync(entry.path)).digest("hex");
+		if (at >= 0) ledger.entries[at] = next; else ledger.entries.push(next);
+		saveLedger(root, ledger.entries);
+		return next;
+	});
+}
+
+/** 精确 id 或位置销账；有 owner 条件时只影响该通道。 */
+export function cancel(root, entry) {
+	if (!entry?.path && !entry?.id) return;
+	return withControlLock(root, () => {
+		const ledger = loadLedger(root);
+		const kept = ledger.entries.filter(e => entry.id ? e.id !== entry.id :
+			!sameLocation(e, entry) || (entry.harness !== undefined && e.harness !== entry.harness) || (entry.channel !== undefined && e.channel !== entry.channel));
+		if (kept.length !== ledger.entries.length) saveLedger(root, kept);
+	});
+}
+export function forgetHarness(root, harness, channel = null) {
+	return withControlLock(root, () => {
+		const ledger = loadLedger(root);
+		const kept = ledger.entries.filter(e => e.harness !== harness || (channel !== null && e.channel !== channel));
+		if (kept.length !== ledger.entries.length) saveLedger(root, kept);
+	});
+}
+export const listLedger = root => loadLedger(root).entries;

package/lib/home.mjs

@@ -1,47 +1,47 @@
-// 用户数据目录：state.json 与 personas/ 不跟代码走。
-//
-// 原因：npm 升级是「整个包目录替换」，数据若留在包目录里会连人设一起被清掉。
-// 所以代码认 ROOT（装在哪都行），数据认 HOME：
-//   AGENT_PURGE_HOME 显式指定 > ~/.agent-purge
-//
-// 老布局（数据躺在包目录里）在首次运行时整份拷过来，原件留着当备份，不删。
-import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
-
-export function dataHome() {
-	const env = process.env.AGENT_PURGE_HOME?.trim();
-	if (!env) return join(homedir(), ".agent-purge");
-	return isAbsolute(env) ? env : resolve(env);
-}
-
-/**
- * 确保数据目录存在，并把旧布局搬过来。
- * @returns {{ home: string, migrated: string[] }}
- */
-export function ensureDataHome(pkgRoot = null) {
-	const home = dataHome();
-	mkdirSync(home, { recursive: true });
-	const migrated = [];
-	// 显式指定 AGENT_PURGE_HOME = 用户自己挑的新家，不往里搬旧数据
-	if (!pkgRoot || process.env.AGENT_PURGE_HOME?.trim() || resolve(pkgRoot) === resolve(home)) {
-		return { home, migrated };
-	}
-
-	const state = [join(pkgRoot, "state.json"), join(home, "state.json")];
-	if (existsSync(state[0]) && !existsSync(state[1])) {
-		copyFileSync(state[0], state[1]);
-		migrated.push(`state: ${state[0]} → ${state[1]}`);
-	}
-
-	const from = join(pkgRoot, "personas");
-	const to = join(home, "personas");
-	if (existsSync(from) && !existsSync(to)) {
-		const md = readdirSync(from).filter((f) => f.endsWith(".md"));
-		if (md.length) {
-			cpSync(from, to, { recursive: true });
-			migrated.push(`personas: ${from} → ${to}（${md.length} 个）`);
-		}
-	}
-	return { home, migrated };
-}
+// 用户数据目录：state.json 与 personas/ 不跟代码走。
+//
+// 原因：npm 升级是「整个包目录替换」，数据若留在包目录里会连人设一起被清掉。
+// 所以代码认 ROOT（装在哪都行），数据认 HOME：
+//   AGENT_PURGE_HOME 显式指定 > ~/.agent-purge
+//
+// 老布局（数据躺在包目录里）在首次运行时整份拷过来，原件留着当备份，不删。
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export function dataHome() {
+	const env = process.env.AGENT_PURGE_HOME?.trim();
+	if (!env) return join(homedir(), ".agent-purge");
+	return isAbsolute(env) ? env : resolve(env);
+}
+
+/**
+ * 确保数据目录存在，并把旧布局搬过来。
+ * @returns {{ home: string, migrated: string[] }}
+ */
+export function ensureDataHome(pkgRoot = null) {
+	const home = dataHome();
+	mkdirSync(home, { recursive: true });
+	const migrated = [];
+	// 显式指定 AGENT_PURGE_HOME = 用户自己挑的新家，不往里搬旧数据
+	if (!pkgRoot || process.env.AGENT_PURGE_HOME?.trim() || resolve(pkgRoot) === resolve(home)) {
+		return { home, migrated };
+	}
+
+	const state = [join(pkgRoot, "state.json"), join(home, "state.json")];
+	if (existsSync(state[0]) && !existsSync(state[1])) {
+		copyFileSync(state[0], state[1]);
+		migrated.push(`state: ${state[0]} → ${state[1]}`);
+	}
+
+	const from = join(pkgRoot, "personas");
+	const to = join(home, "personas");
+	if (existsSync(from) && !existsSync(to)) {
+		const md = readdirSync(from).filter((f) => f.endsWith(".md"));
+		if (md.length) {
+			cpSync(from, to, { recursive: true });
+			migrated.push(`personas: ${from} → ${to}（${md.length} 个）`);
+		}
+	}
+	return { home, migrated };
+}

package/lib/launch-conflicts.mjs

@@ -0,0 +1,24 @@
+// 单次 off 不移除其他来源；有静态托管块时报告精确路径，不靠粗粒度禁用宿主功能。
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, parse, resolve } from "node:path";
+import { targets, stripBlock } from "./persist.mjs";
+import { listLedger } from "./footprints.mjs";
+import { projectFilePath } from "./project.mjs";
+
+export function launchConflicts(root, harness, cwd) {
+	const files = new Set();
+	const target = targets[harness];
+	if (target?.kind === "block") files.add(target.file());
+	for (const row of listLedger(root)) if (row.kind === "block" && (row.harness === harness || row.channel === "project")) files.add(row.path);
+	let dir = resolve(cwd);
+	while (true) {
+		const file = projectFilePath(harness, dir); if (file) files.add(file);
+		if (dir === parse(dir).root) break;
+		dir = dirname(dir);
+	}
+	return [...files].filter(file => {
+		if (!existsSync(file)) return false;
+		try { const text = readFileSync(file, "utf8"); return stripBlock(text) !== text; }
+		catch { throw new Error(`静态配置读取失败：${file}`); }
+	});
+}

package/lib/launch.mjs

@@ -0,0 +1,57 @@
+// 每次显式启动独立凭据；token 继承、孤儿插件、别家的进程均不是启用许可。
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { atomicControlJSON, withControlLock } from "./control.mjs";
+import { loadState } from "./state.mjs";
+
+/** 纯核验也生成进插件；bornAt 是宿主运行时实际的进程启动时间。 */
+export function validLaunch(record, state, harness, identity) {
+	if (!record || record.version !== 1 || record.harness !== harness || record.token !== identity.token) return false;
+	if (!identity.token || record.hostPid !== identity.pid || !Number.isSafeInteger(record.hostPid)) return false;
+	if (!Number.isFinite(identity.bornAt) || Math.abs(identity.bornAt - record.startedAt) > 10000) return false;
+	if (!Number.isFinite(record.expiresAt) || record.expiresAt < identity.now || record.startedAt > identity.now + 1000) return false;
+	if (record.epoch !== (state?.activationEpoch ?? "initial")) return false;
+	if (record.harnessEpoch !== (state?.harnessEpochs?.[harness] ?? "initial")) return false;
+	return true;
+}
+
+export function readLaunch(root, state, harness, token = process.env.AGENT_PURGE_LAUNCH) {
+	if (!/^[a-f0-9-]{36}$/i.test(token ?? "")) return null;
+	try {
+		const record = JSON.parse(readFileSync(root + "/runtime/" + token + ".json", "utf8"));
+		if (!validLaunch(record, state, harness, { token, pid: process.pid, bornAt: Date.now() - process.uptime() * 1000, now: Date.now() })) return null;
+		try { process.kill(record.ownerPid, 0); } catch { return null; }
+		return record;
+	} catch { return null; }
+}
+
+/** 发布前回调保持透传；发布、停用均与配置事务使用同一把锁。 */
+export function createLaunch(root, harness, { persona = null, mode, writer = "temporary" } = {}) {
+	const token = randomUUID(), file = join(root, "runtime", token + ".json");
+	const state = loadState(root).state;
+	const initial = { epoch: state.activationEpoch ?? "initial", harnessEpoch: state.harnessEpochs?.[harness] ?? "initial" };
+	let record = null, timer = null, closed = false;
+	return {
+		token, file, env: { AGENT_PURGE_LAUNCH: token },
+		publish(hostPid, startedAt) {
+			if (closed || !Number.isSafeInteger(hostPid)) throw new Error("启动凭据缺少宿主 PID");
+			withControlLock(root, () => {
+				const current = loadState(root).state;
+				if ((current.activationEpoch ?? "initial") !== initial.epoch || (current.harnessEpochs?.[harness] ?? "initial") !== initial.harnessEpoch)
+					throw new Error("启动期间配置已撤销，请重新启动");
+				mkdirSync(join(root, "runtime"), { recursive: true });
+				record = { version: 1, token, harness, ownerPid: process.pid, hostPid, startedAt, persona, mode, writer, ...initial, expiresAt: Date.now() + 60000 };
+				atomicControlJSON(file, record);
+			});
+			timer = setInterval(() => {
+				if (closed || !existsSync(file)) return;
+				try { record.expiresAt = Date.now() + 60000; atomicControlJSON(file, record); } catch { /* 丢失凭据则停止，而非借 FORCE 回退 */ }
+			}, 10000);
+			timer.unref();
+		},
+		close() { if (timer) clearInterval(timer); closed = true; rmSync(file, { force: true }); },
+	};
+}
+
+export const launchRuntime = [validLaunch, readLaunch].map(fn => fn.toString()).join("\n");

package/lib/opencode.mjs

@@ -0,0 +1,62 @@
+// OpenCode 两代 API 共用相同的启用/撤销实现；临时插件只接受父进程发布的凭据。
+import { join } from "node:path";
+import { personaBodyRuntime, resolveRuntime, rewriteRuntime } from "./rewrite.mjs";
+import { launchRuntime } from "./launch.mjs";
+
+export function opencodeSource(root, harness, { temporary = false, active = join(root, "personas", "active.md") } = {}) {
+	const common = `// agent-purge 托管文件；${temporary ? "仅本次显式启动" : "常驻配置"}，每轮检查实时状态。
+import { readFileSync } from "node:fs";
+const HOME = ${JSON.stringify(root)};
+const STATE = HOME + "/state.json";
+const PERSONAS = HOME + "/personas";
+const ACTIVE = ${JSON.stringify(active)};
+const HARNESS = ${JSON.stringify(harness)};
+const TEMPORARY = ${temporary};
+${rewriteRuntime}
+${resolveRuntime}
+${personaBodyRuntime}
+${launchRuntime}
+function cfg() {
+  try {
+    const st = JSON.parse(readFileSync(STATE, "utf8"));
+    const lease = readLaunch(HOME, st, HARNESS);
+    if (TEMPORARY ? !lease || lease.writer !== "temporary" : lease?.writer === "temporary") return null;
+    const c = resolveActivation(st, HARNESS, { channel: "install", launch: TEMPORARY && !!lease,
+      mode: TEMPORARY ? lease?.mode : undefined, persona: TEMPORARY ? lease?.persona : undefined });
+    if (!c.on) return null;
+    const body = resolvePersonaBody(PERSONAS, c.persona, ACTIVE);
+    return body ? { mode: c.mode, body } : null;
+  } catch { return null; }
+}
+const sessions = new Map();
+function rewriter(id) {
+  const key = id ?? "default";
+  if (!sessions.has(key)) sessions.set(key, ${harness === "opencode" ? "createTextRewriter" : "createContentRewriter"}());
+  while (sessions.size > 64) sessions.delete(sessions.keys().next().value);
+  return sessions.get(key);
+}
+`;
+	if (harness === "opencode") return common + `
+export const AgentPurge = async () => ({
+  "experimental.chat.system.transform": async (input, output) => {
+    if (!Array.isArray(output.system)) return;
+    const c = cfg();
+    const next = rewriter(input?.sessionID)(output.system, c?.body || "", c?.mode || "off");
+    if (JSON.stringify(next) !== JSON.stringify(output.system)) output.system.splice(0, output.system.length, ...next);
+  },
+});
+`;
+	return common + `
+export default {
+  id: ${JSON.stringify(temporary ? "agent-purge-v2-session" : "agent-purge")},
+  async setup(ctx) {
+    await ctx.session.hook("context", event => {
+      if (!Array.isArray(event.system)) return;
+      const c = cfg();
+      const next = rewriter(event.sessionID ?? event.session?.id)(event.system, c?.body || "", c?.mode || "off");
+      if (JSON.stringify(next) !== JSON.stringify(event.system)) event.system.splice(0, event.system.length, ...next);
+    });
+  },
+};
+`;
+}

package/lib/paths.mjs

@@ -0,0 +1,25 @@
+// 配置落点只在这里解释。XDG_CONFIG_HOME 是配置根，PI_CODING_AGENT_DIR 是 agent 目录。
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export function userHome() {
+	return process.env.USERPROFILE || process.env.HOME || homedir();
+}
+export function configHome(id) {
+	const home = userHome();
+	const env = process.env;
+	const roots = {
+		pi: env.PI_CODING_AGENT_DIR || env.PI_HOME || join(home, ".pi", "agent"),
+		omp: env.OMP_HOME || join(home, ".omp"),
+		codex: env.CODEX_HOME || join(home, ".codex"),
+		claude: env.CLAUDE_CONFIG_DIR || join(home, ".claude"),
+		codebuddy: env.CODEBUDDY_HOME || join(home, ".codebuddy"),
+		grok: env.GROK_HOME || join(home, ".grok"),
+		dsh: env.DSH_HOME || join(home, ".dsh"),
+		zcode: env.ZCODE_HOME || join(home, ".zcode"),
+		hermes: env.HERMES_HOME || (process.platform === "win32" ? join(home, "AppData", "Local", "hermes") : join(home, ".hermes")),
+		opencode: join(env.XDG_CONFIG_HOME || join(home, ".config"), "opencode"),
+	};
+	const root = roots[id === "opencode2" ? "opencode" : id];
+	return root ? resolve(root) : null;
+}