agent-purge 0.2.9 → 0.2.11

package/lib/capture.mjs

@@ -0,0 +1,324 @@
+// 证据链：跑真二进制 → 本机假 provider → 看它到底把什么发给了模型。
+// 这里不信任 harness 的自述、也不信 matrix.json 的常量表，只认抓到的请求体。
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { spawnBin, resolveBin } from "./spawn.mjs";
+import { isolatedEnv } from "./environment.mjs";
+import { isCompiled } from "./root.mjs";
+export { isolatedEnv } from "./environment.mjs";
+import { inspectRequest, requestKind, startCaptureProvider } from "../bench/capture-provider.mjs";
+import { writeVerification } from "../bench/capture-report.mjs";
+
+const CLI = resolve(dirname(fileURLToPath(import.meta.url)), "..", "bin", "agent-purge.mjs");
+
+// 隔离 HOME 是临时脚手架：证据落在 out/，临时树不能越攒越多。
+const ISOLATED_ROOTS = [];
+export function trackRoot(root) {
+	ISOLATED_ROOTS.push(root);
+	return root;
+}
+
+export function cleanupRoots() {
+	if (process.env.AP_KEEP_ROOTS || process.argv.includes("--keep-roots")) return;
+	for (const root of ISOLATED_ROOTS.splice(0)) {
+		// 不用 rm -rf：Windows 没有；node 自己的重试删除两边都可靠
+		try {
+			rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+		} catch {
+			/* 临时目录删不掉不影响证据 */
+		}
+	}
+}
+
+export function agentCommand(args) { return { cmd: process.execPath, args: isCompiled() ? args : [CLI, ...args] }; }
+
+export function captureOutcome(result, requests, mode) {
+	const detail = String(result.error || result.stderr || result.stdout || '').trim().slice(-1800);
+	if (result.timedOut) return { status: "error", reason: `执行器超时${detail ? `：${detail}` : ""}` };
+	if (result.error || result.code !== 0) return { status: "error", reason: `执行器未正常结束（退出码 ${result.code ?? "未知"}）${detail ? `：${detail}` : ""}` };
+	if (!requests.length) return { status: "no-request", reason: "执行器已退出，但没有捕获到主请求；不能据此判断人设是否生效。" };
+	const passed = requests.every(request => mode === "off" ? request.markerCount === 0 : request.markerCount === 1);
+	return { status: passed ? "captured" : "mismatch", reason: passed ? null : "已捕获主请求，但人设次数与测试模式不符。" };
+}
+
+async function prepareCapture(harness, bin, env, cwd, out, timeout) {
+	if (harness !== "dsh") return;
+	// Single-mode verification used to fail in a fresh HOME: only the first
+	// `off` run in the four-mode benchmark happened to initialize this profile.
+	const result = await runProcess(bin, ["--profile", "headless", "--dump-config"], { env, cwd, timeout });
+	if (out) put(join(out, harness, "prepare.process.json"), result);
+	if (result.error || result.timedOut || result.code !== 0)
+		throw new Error("无法初始化隔离 DSH headless profile：" + (result.error || result.stderr || `exit ${result.code}`));
+}
+
+export function runProcess(cmd, args, { env, cwd, timeout = 35000, input } = {}) {
+	return new Promise((done) => {
+		let child;
+		try {
+			child = spawnBin(cmd, args, { env, cwd, stdio: ["pipe", "pipe", "pipe"] });
+		} catch (e) {
+			done({ code: null, error: e.message, stdout: "", stderr: "" });
+			return;
+		}
+		let stdout = "",
+			stderr = "",
+			timedOut = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			if (process.platform === "win32") spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+			else child.kill("SIGKILL");
+		}, timeout);
+		child.stdout.on("data", (b) => (stdout = (stdout + b).slice(-100000)));
+		child.stderr.on("data", (b) => (stderr = (stderr + b).slice(-100000)));
+		child.on("error", (e) => {
+			clearTimeout(timer);
+			done({ code: null, error: e.message, stdout, stderr });
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			done({ code, timedOut, stdout, stderr });
+		});
+		child.stdin.end(input);
+	});
+}
+
+export function put(file, content) {
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, typeof content === "string" ? content : JSON.stringify(content, null, 2));
+}
+
+export function seed(env, harness, mode, body) {
+	const root = env.AGENT_PURGE_HOME;
+	put(join(root, "personas", "capture-a.md"), body);
+	put(join(root, "personas", "active.md"), body);
+	put(join(root, "state.json"), { v: 1, persona: "capture-a", default: { harness, mode }, armed: {}, piAuto: false, ompAuto: false });
+}
+
+export function configure(h, env, url, cwd) {
+	// 常规代理变量也被同一个 loopback 服务器接住，避免子进程偷偷走真网络。
+	Object.assign(env, {
+		HTTP_PROXY: url,
+		HTTPS_PROXY: url,
+		ALL_PROXY: url,
+		NO_PROXY: "127.0.0.1,localhost",
+		ANTHROPIC_BASE_URL: url,
+		ANTHROPIC_API_KEY: "capture-fixture-key",
+		OPENAI_BASE_URL: url + "/v1",
+		OPENAI_API_KEY: "capture-fixture-key",
+	});
+	const model = {
+		id: "capture",
+		name: "Capture fixture",
+		reasoning: false,
+		input: ["text"],
+		contextWindow: 128000,
+		maxTokens: 2048,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	};
+	const providers = { capture: { baseUrl: url + "/v1", api: "openai-completions", apiKey: "capture-fixture-key", models: [model] } };
+	if (h === "pi") {
+		put(join(env.PI_CODING_AGENT_DIR, "models.json"), { providers });
+		put(join(env.PI_CODING_AGENT_DIR, "settings.json"), { packages: [], mcp: { servers: {} } });
+		return ["--provider", "capture", "--model", "capture", "--no-mcp", "--no-skills", "--no-context-files", "--no-prompt-templates", "--no-session"];
+	}
+	if (h === "omp") {
+		env.PI_CODING_AGENT_DIR = join(env.OMP_HOME, "agent");
+		put(join(env.PI_CODING_AGENT_DIR, "models.yml"), JSON.stringify({ providers }));
+		return ["--provider", "capture", "--model", "capture", "--no-extensions", "--no-skills", "--no-rules", "--no-context-files", "--no-lsp", "--no-title", "--no-session"];
+	}
+	if (h === "claude") return ["--model", "claude-sonnet-4-5", "--max-turns", "1", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--no-session-persistence", "--setting-sources", ""];
+	if (h === "codex") {
+		put(
+			join(env.CODEX_HOME, "config.toml"),
+			`model = "gpt-5.4"\nmodel_provider = "capture"\n[model_providers.capture]\nname = "Capture"\nbase_url = "${url}/v1"\nwire_api = "responses"\nrequires_openai_auth = false\n`,
+		);
+		return ["--skip-git-repo-check", "--ephemeral"];
+	}
+	if (h === "opencode") {
+		put(join(cwd, "opencode.json"), {
+			model: "capture/capture",
+			small_model: "capture/capture",
+			provider: { capture: { npm: "@ai-sdk/openai-compatible", options: { baseURL: url + "/v1", apiKey: "capture-fixture-key" }, models: { capture: { name: "Capture", limit: { context: 128000, output: 2048 } } } } },
+		});
+		return ["--model", "capture/capture"];
+	}
+	if (h === "dsh") {
+		Object.assign(env, { DEEPSEEK_BASE_URL: url, DEEPSEEK_API_KEY: "capture-fixture-key", DSH_TELEMETRY_MODE: "DISABLED", DSH_TELEMETRY_OTLP_URL: url + "/telemetry" });
+		return [];
+	}
+	if (h === "codebuddy") {
+		Object.assign(env, {
+			CODEBUDDY_BASE_URL: url,
+			CODEBUDDY_API_KEY: "capture-fixture-key",
+			CODEBUDDY_MODEL: "capture",
+			CODEBUDDY_SMALL_FAST_MODEL: "capture",
+			CODEBUDDY_BIG_SLOW_MODEL: "capture",
+		});
+		return ["--model", "capture", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--no-session-persistence", "--setting-sources", ""];
+	}
+	if (h === "grok") {
+		Object.assign(env, { XAI_API_KEY: "capture-fixture-key", GROK_XAI_API_BASE_URL: url + "/v1", GROK_MODELS_BASE_URL: url + "/v1", GROK_DISABLE_AUTOUPDATER: "1" });
+		put(
+			join(env.GROK_HOME, "config.toml"),
+			`[model.capture]\nmodel = "capture"\nbase_url = "${url}/v1"\nenv_key = "XAI_API_KEY"\napi_backend = "chat_completions"\n[models]\ndefault = "capture"\n`,
+		);
+		return ["--model", "capture", "--max-turns", "1", "--disable-web-search", "--no-subagents"];
+	}
+	if (h === "opencode2") {
+		put(join(cwd, "opencode.json"), {
+			model: "capture/capture",
+			providers: { capture: { package: "aisdk:@ai-sdk/openai-compatible", settings: { baseURL: url + "/v1", apiKey: "capture-fixture-key" }, models: { capture: { name: "Capture" } } } },
+		});
+		return ["--standalone", "--model", "capture/capture"];
+	}
+	return null;
+}
+
+
+/** 一次抓包：装好种子人设 → 跑一条真请求 → 分析请求体里的 marker 落在哪一层。 */
+export async function captureMode(h, { out, mode = "replace", timeout = 45000 } = {}) {
+	const bin = resolveBin(h);
+	if (!bin) return { harness: h, mode, status: "missing", reason: "Executable not found" };
+	const root = trackRoot(mkdtempSync(join(tmpdir(), `ap-capture-${h}-`)));
+	const env = isolatedEnv(root);
+	const cwd = join(root, "work");
+	mkdirSync(cwd);
+	env.AGENT_PURGE_REAL_BIN = bin;
+	const version = await runProcess(bin, ["--version"], { env, cwd, timeout: 12000 });
+	const base = { harness: h, mode, executable: bin, version: version.stdout.trim(),
+		scope: { kind: "isolated-cli", profile: h === "dsh" ? "headless" : null, syntheticPersona: true, currentSession: false } };
+	if (h === "hermes") return { ...base, status: "blocked", reason: (version.stderr || version.stdout).trim() || "No isolated provider adapter" };
+
+	const provider = await startCaptureProvider(join(out ?? root, h, "requests"));
+	let flags;
+	try {
+		flags = configure(h, env, provider.url, cwd);
+		if (flags) await prepareCapture(h, bin, env, cwd, out, timeout);
+	} catch (e) {
+		await provider.close();
+		return { ...base, status: "error", reason: e.message };
+	}
+	if (!flags) {
+		await provider.close();
+		return { ...base, status: "blocked", reason: "Provider/isolation adapter not yet verified for this executable" };
+	}
+	try {
+		const marker = `AP_CAPTURE_${h}_${mode}_${randomUUID()}`;
+		const body = `Capture-only neutral persona. Marker: ${marker}. Reply briefly.`;
+		seed(env, h, mode, body);
+		const start = provider.captures.length;
+		const command = agentCommand([h, "--ask", "Reply CAPTURE_OK.", "--", ...flags]);
+		const result = await runProcess(command.cmd, command.args, { env, cwd, timeout });
+		const processFile = join(out ?? root, h, mode + ".process.json");
+		put(processFile, result);
+		const analyses = provider.captures.slice(start).map((r) => ({ id: r.id, protocol: r.protocol, kind: requestKind(r.body), ...inspectRequest(r.body, marker) }));
+		// 未知/辅助请求仍是证据，但不能替代主回合。
+		const checks = analyses.filter((a) => a.kind === "main");
+		const hit = checks.find((a) => a.markerCount > 0);
+		return {
+			...base,
+			...captureOutcome(result, checks, mode),
+			processFile,
+			exitCode: result.code,
+			timedOut: result.timedOut,
+			marker,
+			// 注入层：inspectRequest 的 text/markerCount 只算特权角色（system/developer），
+			// 用户消息里的命中由 userMarkerCount 单独给，两个合起来才是「注到哪层」。
+			injected: { sys: Boolean(hit), user: checks.some(request => request.userMarkerCount > 0) },
+			chars: hit?.chars ?? 0,
+			head: (hit?.text ?? "").slice(0, 200),
+			requests: analyses.map(({ text: _text, ...a }) => a),
+		};
+	} finally {
+		await provider.close();
+	}
+}
+
+/** verify：只抓「当前模式」一次，写 web 读的那份 verification/latest.json。
+ * 不写原始提示词文本（那是本地抓包目录的事）：摘要只有角色、字数、marker 命中数。 */
+export async function verifyHarnesses(harnesses, { root, timeout, mode = "replace" } = {}) {
+	const at = new Date().toISOString();
+	const out = join(root, "verification", at.replace(/[:.]/g, "-"));
+	const report = {
+		schema: 1,
+		at,
+		kind: "loopback-real-binary",
+		out,
+		limitations: ["只证明请求体里有人设：不代表模型行为质量", "loopback 假 provider 不是 OS 级网络沙箱"],
+		harnesses: [],
+	};
+	for (const h of harnesses) {
+		let r;
+		try {
+			r = await captureMode(h, { out, mode, timeout });
+		} catch (e) {
+			r = { harness: h, status: "error", reason: e.message };
+		}
+		report.harnesses.push({
+			harness: h,
+			executable: r.executable ?? null,
+			version: r.version ?? "",
+			scope: r.scope ?? null,
+			processFile: r.processFile ?? null,
+			status: r.status,
+			reason: r.reason ?? null,
+			modes: r.requests
+				? [{ mode: r.mode, status: r.status, exitCode: r.exitCode, timedOut: r.timedOut, marker: r.marker, injected: r.injected, chars: r.chars, requests: r.requests }]
+				: [],
+			hotSwitch: { status: "not-tested" },
+		});
+	}
+	writeVerification(join(root, "verification", "latest.json"), report);
+	return report;
+}
+
+export async function captureHarness(h, out) {
+	const bin = resolveBin(h);
+	if (!bin) return { harness: h, status: "unavailable", reason: "Executable not found" };
+	const root = trackRoot(mkdtempSync(join(tmpdir(), `ap-capture-${h}-`)));
+	const env = isolatedEnv(root);
+	const cwd = join(root, "work");
+	mkdirSync(cwd);
+	env.AGENT_PURGE_REAL_BIN = bin;
+	const version = await runProcess(bin, ["--version"], { env, cwd, timeout: 12000 });
+	put(join(out, h, "version.json"), version);
+	const report = { harness: h, executable: bin, version: version.stdout.trim(), isolation: root,
+		scope: { kind: "isolated-cli", profile: h === "dsh" ? "headless" : null, syntheticPersona: true, currentSession: false },
+		modes: [], hotSwitch: { status: "not-tested", reason: "Startup capture does not prove same-session switching" } };
+	if (h === "hermes") {
+		report.status = "blocked";
+		report.reason = (version.stderr || version.stdout).trim() || "No isolated provider adapter";
+		return report;
+	}
+	const provider = await startCaptureProvider(join(out, h, "requests"));
+	const flags = configure(h, env, provider.url, cwd);
+	if (!flags) {
+		await provider.close();
+		return { ...report, status: "blocked", reason: "Provider/isolation adapter not yet verified for this executable" };
+	}
+	try {
+		await prepareCapture(h, bin, env, cwd, out, 35000);
+		for (const mode of ["off", "strict", "replace", "append"]) {
+			const marker = `AP_CAPTURE_${h}_${mode}_${randomUUID()}`;
+			const body = `Capture-only neutral persona. Marker: ${marker}. Reply briefly.`;
+			seed(env, h, mode, body);
+			const start = provider.captures.length;
+			const command = agentCommand([h, "--ask", "Reply CAPTURE_OK.", "--", ...flags]);
+			const result = await runProcess(command.cmd, command.args, { env, cwd });
+			put(join(out, h, mode + ".process.json"), result);
+			const requests = provider.captures.slice(start);
+			const analyses = requests.map((r) => ({ id: r.id, protocol: r.protocol, kind: requestKind(r.body), ...inspectRequest(r.body, marker) }));
+			const checks = analyses.filter((a) => a.kind === "main");
+			report.modes.push({ mode, ...captureOutcome(result, checks, mode), exitCode: result.code, timedOut: result.timedOut, marker, requests: analyses.map(({ text: _text, ...a }) => a) });
+			console.log(`${h} ${mode}: ${report.modes.at(-1).status} (${checks.length} request, exit ${result.code})`);
+		}
+		report.status = report.modes.every((r) => r.status === "captured") ? "captured" : "partial";
+		return report;
+	} finally {
+		await provider.close();
+	}
+}

package/lib/clean.mjs

@@ -0,0 +1,124 @@
+// 撤销先发布全局暂停，再按登记逐项还原；失败保留原位置的账本与 stash 供重试。
+import { existsSync, readdirSync, realpathSync, renameSync, rmdirSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, resolve, sep } from "node:path";
+import { changeChannel } from "./apply.mjs";
+import { withControlLock } from "./control.mjs";
+import { cancel, listLedger } from "./footprints.mjs";
+import { removeOwnedFile, revertFile, uninstall as uninstallPersist } from "./persist.mjs";
+import { removeUserPath, shimDir } from "./shim.mjs";
+import { loadState, patchState } from "./state.mjs";
+
+export function clean(root, { all = false, dryRun = false } = {}) {
+	// 必须在创建锁/写暂停状态之前拒绝危险的数据根；不能等撤销一半才发现。
+	const blocked = all && refuseReason(resolve(root));
+	if (blocked) return { ok: false, steps: [{ what: "data-home", ok: false, detail: blocked }], leftovers: [blocked] };
+	if (dryRun) return runClean(root, { all, dryRun });
+	return withControlLock(root, () => runClean(root, { all, dryRun }));
+}
+function runClean(root, { all, dryRun }) {
+	const steps = [], home = resolve(root);
+	const add = (what, work) => {
+		try {
+			const detail = work();
+			if (detail?.error || detail?.ok === false || detail?.status === "failed") throw new Error(detail.error ?? JSON.stringify(detail));
+			steps.push({ what, ok: true, detail });
+			return true;
+		} catch (error) { steps.push({ what, ok: false, detail: error.message }); return false; }
+	};
+	let state;
+	if (!add("pause", () => {
+		state = loadState(root).state;
+		if (dryRun) return "（dry-run：会先暂停并撤销会话启动凭据）";
+		patchState(root, { default: { harness: state.default?.harness ?? null, mode: "off" },
+			resumeMode: state.default?.mode && state.default.mode !== "off" ? state.default.mode : state.resumeMode ?? "replace" });
+		return "已暂停；旧启动凭据不再恢复";
+	})) return { ok: false, steps, leftovers: ["配置未成功暂停，未开始撤销"] };
+
+	for (const [harness, channels] of Object.entries(state.armed ?? {})) {
+		for (const channel of Array.isArray(channels) ? channels : []) {
+			add(`${harness}/${channel}`, () => dryRun ? "（dry-run：会撤销）" : changeChannel(root, { harness, channel, enabled: false }));
+		}
+	}
+	let entries = [];
+	add("read-ledger", () => { entries = listLedger(root); return `${entries.length} 条恢复记录`; });
+	const customDone = new Set();
+	for (const entry of [...entries].reverse()) {
+		if (dryRun) { steps.push({ what: `ledger:${entry.undo.type}`, ok: true, detail: `（dry-run：会撤销 ${entry.path}）` }); continue; }
+		if (entry.undo.type === "custom" && customDone.has(entry.harness)) continue;
+		add(`ledger:${entry.undo.type}`, () => {
+			let detail;
+			if (entry.undo.type === "custom") {
+				customDone.add(entry.harness);
+				detail = uninstallPersist(entry.harness, { root });
+			} else detail = reverse(entry, root);
+			if (detail?.error || detail?.ok === false) throw new Error(detail.error ?? JSON.stringify(detail));
+			cancel(root, { id: entry.id, kind: entry.kind, path: entry.path, harness: entry.harness, channel: entry.channel });
+			return detail;
+		});
+	}
+	// 目录内允许共存用户文件；只收空目录，不递归删除未知文件。
+	if (existsSync(shimDir())) add("shim-dir", () => {
+		if (dryRun) return "（dry-run：仅收空目录，保留外来文件）";
+		if (readdirSync(shimDir()).length) return "保留目录中未登记的文件";
+		rmdirSync(shimDir());
+		return "removed-empty-directory";
+	});
+	if (!dryRun && steps.every(s => s.ok)) add("reset-selection", () => patchState(root, { armed: {}, pausedInstalls: [], projectDirs: {} }));
+	let pending = leftovers(root);
+	if (all) add("data-home", () => {
+		const blocked = refuseReason(home);
+		if (blocked) throw new Error(blocked);
+		if (dryRun) return `（dry-run：确认全部还原后删除 ${home}）`;
+		if (pending.length || steps.some(s => !s.ok)) throw new Error(`保留原数据目录供重试：${home}；${pending.join("；")}`);
+		if (!existsSync(home)) return "already-gone";
+		const trash = `${home}.trash-${Date.now()}`;
+		renameSync(home, trash);
+		try { rmSync(trash, { recursive: true, force: true }); }
+		catch (error) {
+			try { if (!existsSync(home)) renameSync(trash, home); } catch {}
+			throw new Error(`删除失败，恢复资料保留于 ${existsSync(home) ? home : trash}：${error.message}`);
+		}
+		return home;
+	});
+	pending = leftovers(root);
+	return { ok: steps.every(s => s.ok) && (dryRun || !pending.length), steps, leftovers: pending };
+}
+function refuseReason(home) {
+	const canonical = file => {
+		let full = resolve(file);
+		try { full = realpathSync(full); } catch (error) { if (error.code !== "ENOENT") throw error; }
+		return process.platform === "win32" ? full.toLowerCase() : full;
+	};
+	const h = canonical(home), cwd = canonical(process.cwd());
+	const contains = file => file === h || file.startsWith(h.endsWith(sep) ? h : h + sep);
+	if (contains(cwd)) return `当前工作目录位于数据目录中，请手工处理：${home}`;
+	const protectedDirs = [process.env.USERPROFILE || process.env.HOME || homedir(), homedir(), tmpdir()];
+	if (protectedDirs.some(file => contains(canonical(file))) || !basename(h) || /^[A-Za-z]:[\\/]?$/.test(h) || h === sep)
+		return `数据目录指向用户主目录、临时根或其上级，请手工处理：${home}`;
+	return null;
+}
+function reverse(entry, root) {
+	if (entry.undo.type === "file-delete") {
+		const result = removeOwnedFile(entry.path, { root, expectedSha: entry.sha256 });
+		if (result.action === "skipped-foreign") throw new Error(`保留外来文件与恢复记录：${entry.path}`);
+		return result;
+	}
+	if (entry.undo.type === "block-revert") return revertFile(entry.path, { root });
+	if (entry.undo.type === "path-env") return removeUserPath(entry.path);
+	throw new Error(`未知撤销方式，保留账本：${entry.undo.type}`);
+}
+function leftovers(root) {
+	if (!existsSync(root)) return [];
+	const out = [];
+	try {
+		const pending = listLedger(root);
+		if (pending.length) out.push(`${pending.length} 条账本记录未撤销（${pending.map(e => e.path).join(", ")}）`);
+	} catch (error) { out.push(error.message); }
+	try {
+		const state = loadState(root).state;
+		const armed = Object.entries(state.armed ?? {}).filter(([, channels]) => channels?.length);
+		if (armed.length) out.push(`state 仍记着 armed：${armed.map(([h, cs]) => `${h}=${cs.join("+")}`).join(", ")}`);
+	} catch (error) { out.push(error.message); }
+	return out;
+}

package/lib/control.mjs

@@ -0,0 +1,60 @@
+// 短时同步本地事务；同进程内部调用复用持有的锁，不重复获取。
+import * as controlFs from "node:fs";
+import { resolve as resolveControlRoot } from "node:path";
+import { randomUUID as controlUUID } from "node:crypto";
+const controlHeld = new Set();
+
+export function withControlLock(root, work) {
+	const key = resolveControlRoot(root);
+	if (controlHeld.has(key)) return work();
+	controlFs.mkdirSync(key, { recursive: true });
+	const file = key + "/.apply.lock";
+	let fd;
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try { fd = controlFs.openSync(file, "wx", 0o600); break; }
+		catch (error) {
+			if (error.code !== "EEXIST") throw error;
+			let owner, bytes;
+			try { bytes = controlFs.readFileSync(file, "utf8"); owner = JSON.parse(bytes); } catch {}
+			let dead = false;
+			if (Number.isSafeInteger(owner?.pid) && owner.pid > 0) {
+				try { process.kill(owner.pid, 0); } catch (e) { dead = e.code === "ESRCH"; }
+			}
+			if (attempt === 0 && dead && bytes === controlFs.readFileSync(file, "utf8")) { controlFs.unlinkSync(file); continue; }
+			throw new Error(`另一个配置操作尚未结束（PID ${owner?.pid ?? "unknown"}）：${file}`);
+		}
+	}
+	if (fd === undefined) throw new Error(`配置锁获取失败：${file}`);
+	const token = controlUUID();
+	try {
+		controlFs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token, at: new Date().toISOString() }));
+		controlFs.fsyncSync(fd);
+		// Windows 的打开句柄会阻止数据目录改名；锁的所有权由 wx 文件与 token 保持。
+		controlFs.closeSync(fd);
+		fd = undefined;
+		controlHeld.add(key);
+		const result = work();
+		if (result && typeof result.then === "function") throw new Error("配置事务必须是同步的本地文件操作");
+		return result;
+	} finally {
+		controlHeld.delete(key);
+		if (fd !== undefined) controlFs.closeSync(fd);
+		try { if (JSON.parse(controlFs.readFileSync(file, "utf8")).token === token) controlFs.unlinkSync(file); } catch {}
+	}
+}
+
+export function atomicControlJSON(file, value) {
+	const tmp = file + ".tmp-" + controlUUID();
+	try {
+		controlFs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+		controlFs.renameSync(tmp, file);
+	} finally { controlFs.rmSync(tmp, { force: true }); }
+}
+
+export const controlRuntime = `import * as controlFs from "node:fs";
+import { resolve as resolveControlRoot } from "node:path";
+import { randomUUID as controlUUID } from "node:crypto";
+const controlHeld = new Set();
+${withControlLock.toString()}
+${atomicControlJSON.toString()}
+`;

package/lib/detect.mjs

@@ -1,70 +1,74 @@
-// 自动探测：这台机器上装了哪些 harness、装在哪、配置目录是哪个。
-// 只读文件系统与 PATH，不执行 harness（版本号要 --versions 才去 spawn）。
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { captureBin, which } from "./spawn.mjs";
-
-const home = process.env.USERPROFILE || process.env.HOME;
-const local = process.env.LOCALAPPDATA || join(home, "AppData", "Local");
-const win = process.platform === "win32";
-
-// 每家的"长什么样"：可执行文件、配置根（含环境变量覆盖）、版本命令
-export const specs = {
-	codex: { bins: ["codex"], homes: [["CODEX_HOME", ".codex"]], version: ["--version"], marker: "config.toml" },
-	codebuddy: { bins: ["codebuddy"], homes: [["CODEBUDDY_HOME", ".codebuddy"]], version: ["--version"], marker: "history.jsonl" },
-	claude: { bins: ["claude"], homes: [["CLAUDE_CONFIG_DIR", ".claude"]], version: ["--version"], marker: "settings.json" },
-	opencode: { bins: ["opencode"], homes: [["XDG_CONFIG_HOME", ".config/opencode"]], version: ["--version"], marker: "opencode.json" },
-	opencode2: { bins: ["opencode2"], homes: [["XDG_CONFIG_HOME", ".config/opencode"]], version: ["--version"], marker: "opencode.json" },
-	dsh: { bins: ["dsh"], homes: [["DSH_HOME", ".dsh"]], version: ["--version"], marker: "profiles" },
-	grok: { bins: ["grok"], homes: [["GROK_HOME", ".grok"]], version: ["--version"], marker: "config.toml" },
-	omp: { bins: ["omp"], homes: [["OMP_HOME", ".omp"]], version: ["--version"], marker: "agent/config.yml" },
-	hermes: { bins: ["hermes"], homes: [["HERMES_HOME", "AppData/Local/hermes"]], version: ["--version"], marker: "hermes-agent" },
-	pi: { bins: ["pi"], homes: [["PI_HOME", ".pi/agent"]], version: ["--version"], marker: "extensions" },
-	zcode: {
-		bins: ["zcode"],
-		homes: [["ZCODE_HOME", ".zcode"]],
-		version: ["--version"],
-		marker: "v2/provider_config.json",
-		extra: ["Programs/zcode", "..\\zcode"],
-	},
-	antigravity: { bins: ["antigravity"], homes: [["", "Programs/antigravity"]], version: null, marker: "resources/bin/language_server.exe" },
-	qoder: { bins: ["qoder"], homes: [["", "Qoder CN"]], version: null, marker: "resources/app.asar" },
-	workbuddy: { bins: ["workbuddy"], homes: [["", "WorkBuddy"]], version: null, marker: "resources/app.asar" },
-};
-
-export function detect({ versions = false } = {}) {
-	const path = process.env.PATH || "";
-	const out = {};
-	for (const [id, spec] of Object.entries(specs)) {
-		const bin = which(spec.bins, path);
-		const roots = spec.homes.map(([env, rel]) => {
-			const raw = env && process.env[env] ? process.env[env] : rel;
-			return raw.startsWith(".") || raw.startsWith("AppData") ? join(home, raw) : raw.includes(":") || raw.startsWith("\\") ? raw : join(local, raw);
-		});
-		const found = roots.map((r) => ({ path: r, exists: existsSync(join(r, spec.marker)) })).filter((r) => r.exists);
-		out[id] = {
-			id,
-			bin,
-			version: versions && bin && spec.version ? probe(bin, spec.version) : null,
-			home: found[0]?.path ?? roots[0],
-			homeExists: found.length > 0,
-			found: Boolean(bin || found.length),
-		};
-	}
-	return out;
-}
-
-export function probe(bin, args) {
-	// 走 spawn 桥接：.cmd/.ps1 shim 才能启动（execFileSync 直接打 .cmd 在 Windows 上必失败）
-	const out = captureBin(bin, args);
-	return out ? out.trim().split("\n")[0].slice(0, 60) : null;
-}
-
-// 已安装的常驻配置（由 persist 层告知，这里只做展示用的存在性判断）
-export function readJsonSafe(file) {
-	try {
-		return JSON.parse(readFileSync(file, "utf8"));
-	} catch {
-		return null;
-	}
-}
+// 自动探测：这台机器上装了哪些 harness、装在哪、配置目录是哪个。
+// 只读文件系统与 PATH，不执行 harness（版本号要 --versions 才去 spawn）。
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { captureBin, which } from "./spawn.mjs";
+import { configHome } from "./paths.mjs";
+
+const home = process.env.USERPROFILE || process.env.HOME;
+const local = process.env.LOCALAPPDATA || join(home, "AppData", "Local");
+const win = process.platform === "win32";
+
+// 每家的"长什么样"：可执行文件、配置根（含环境变量覆盖）、版本命令
+export const specs = {
+	codex: { bins: ["codex"], homes: [["CODEX_HOME", ".codex"]], version: ["--version"], marker: "config.toml" },
+	codebuddy: { bins: ["codebuddy"], homes: [["CODEBUDDY_HOME", ".codebuddy"]], version: ["--version"], marker: "history.jsonl" },
+	claude: { bins: ["claude"], homes: [["CLAUDE_CONFIG_DIR", ".claude"]], version: ["--version"], marker: "settings.json" },
+	opencode: { bins: ["opencode"], homes: [["XDG_CONFIG_HOME", ".config/opencode"]], version: ["--version"], marker: "opencode.json" },
+	opencode2: { bins: ["opencode2"], homes: [["XDG_CONFIG_HOME", ".config/opencode"]], version: ["--version"], marker: "opencode.json" },
+	dsh: { bins: ["dsh"], homes: [["DSH_HOME", ".dsh"]], version: ["--version"], marker: "profiles" },
+	grok: { bins: ["grok"], homes: [["GROK_HOME", ".grok"]], version: ["--version"], marker: "config.toml" },
+	omp: { bins: ["omp"], homes: [["OMP_HOME", ".omp"]], version: ["--version"], marker: "agent/config.yml" },
+	hermes: { bins: ["hermes"], homes: [["HERMES_HOME", "AppData/Local/hermes"]], version: ["--version"], marker: "hermes-agent" },
+	pi: { bins: ["pi"], homes: [["PI_HOME", ".pi/agent"]], version: ["--version"], marker: "extensions" },
+	zcode: {
+		bins: ["zcode"],
+		homes: [["ZCODE_HOME", ".zcode"]],
+		version: ["--version"],
+		marker: "v2/provider_config.json",
+		extra: ["Programs/zcode", "..\\zcode"],
+	},
+	antigravity: { bins: ["antigravity"], homes: [["", "Programs/antigravity"]], version: null, marker: "resources/bin/language_server.exe" },
+};
+
+export function detect({ versions = false } = {}) {
+	const path = process.env.PATH || "";
+	const out = {};
+	for (const [id, spec] of Object.entries(specs)) {
+		const bin = which(spec.bins, path);
+		const roots = configHome(id) ? [configHome(id)] : spec.homes.map(([env, rel]) => {
+			const raw = env && process.env[env] ? process.env[env] : rel;
+			// 显式环境变量可能是任意平台的绝对路径：不能靠 ":" 判断（POSIX 路径没有冒号）
+			return raw.startsWith(".") || raw.startsWith("AppData")
+				? join(home, raw)
+				: isAbsolute(raw)
+					? raw
+					: join(local, raw);
+		});
+		const found = roots.map((r) => ({ path: r, exists: existsSync(join(r, spec.marker)) })).filter((r) => r.exists);
+		out[id] = {
+			id,
+			bin,
+			version: versions && bin && spec.version ? probe(bin, spec.version) : null,
+			home: found[0]?.path ?? roots[0],
+			homeExists: found.length > 0,
+			found: Boolean(bin || found.length),
+		};
+	}
+	return out;
+}
+
+export function probe(bin, args) {
+	// 走 spawn 桥接：.cmd/.ps1 shim 才能启动（execFileSync 直接打 .cmd 在 Windows 上必失败）
+	const out = captureBin(bin, args);
+	return out ? out.trim().split("\n")[0].slice(0, 60) : null;
+}
+
+// 已安装的常驻配置（由 persist 层告知，这里只做展示用的存在性判断）
+export function readJsonSafe(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}