agent-purge 0.2.10 → 0.2.12

package/lib/spawn.mjs

@@ -1,126 +1,182 @@
-// Windows 安全的进程启动。
-// 为什么需要它：npm 全局 shim 不是 .exe，而 CreateProcess 只认 .exe ——
-// spawn("codex", { shell: false }) 在 Windows 上必 ENOENT
-// （实测：codex / pi / opencode / codebuddy 全中；claude / grok / omp / hermes 有真 .exe 才没事）。
-// 也不用 shell: true：那会把 persona 文本交给 cmd.exe 解析，%VAR% 展开、^ 被吃，全是注入面。
-// 做法：先把名字解析成磁盘全路径，再按扩展名分流，优先级：
-//   .exe      → 直接启动（真二进制；Unix 一切照旧）
-//   .ps1      → powershell -File（npm>=7 与 pi 安装器都生成；$args 数组传参，实测
-//               引号/空格/%VAR%/^/&| 全部字节级保真）
-//   .cmd/.bat → ComSpec /d /s /c 兜底（老 npm 或手写 shim；仍有 cmd 展开风险，故排最后）
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { delimiter, dirname, extname, join, resolve } from "node:path";
-
-const WIN = process.platform === "win32";
-
-/** 我们自己的裸命令目录：扫 PATH 时必须跳过它，否则 spawn 会绕回 wrapper 套娃 */
-const OWN_SHIM_DIR = join(process.env.USERPROFILE || process.env.HOME || homedir(), ".agent-purge", "bin");
-
-/** 在 PATH 上按扩展名优先级找可执行文件；找不到返回 null。 */
-export function which(names, path, exts = WIN ? [".exe", ".cmd", ".bat", ".ps1"] : [""]) {
-	const own = resolve(OWN_SHIM_DIR).toLowerCase();
-	for (const name of names) {
-		for (const dir of path.split(delimiter)) {
-			if (!dir) continue;
-			if (resolve(dir).toLowerCase() === own) continue;
-			for (const ext of exts) {
-				const p = join(dir, name + ext);
-				if (existsSync(p)) return p;
-			}
-		}
-	}
-	return null;
-}
-
-// 启动解析优先级：真二进制 > .ps1（保真）> .cmd/.bat（兜底）
-const SPAWN_EXTS = [".exe", ".ps1", ".cmd", ".bat"];
-
-/** 把命令名解析成磁盘全路径；找不到返回 null。 */
-export function resolveBin(name) {
-	if (!name) return null;
-	if (name.includes("/") || name.includes("\\")) return existsSync(name) ? name : null;
-	// shim 接管：wrapper 会把自己的真身写进 AGENT_PURGE_REAL_BIN，优先用它，
-	// 否则 PATH 里排第一的是我们自己的 wrapper，会无限套娃。
-	const real = process.env.AGENT_PURGE_REAL_BIN;
-	if (real && existsSync(real)) {
-		const base = real.trim().replace(/^.*[\\/]/, "").replace(/\.(exe|cmd|bat|ps1)$/i, "").toLowerCase();
-		if (base === String(name).toLowerCase()) return real.trim();
-	}
-	return which([name], process.env.PATH || "", WIN ? SPAWN_EXTS : [""]);
-}
-
-/** cmd.exe 侧的单参加引号：含空格或引号时整体包起来，内嵌引号转成 \"（msvcrt argv 认识它） */
-const winQuote = (a) => {
-	const s = String(a);
-	return /[\s"]/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s;
-};
-
-/**
- * cmd.exe 的命令行上限是 8191 字符（真·硬限）。npm 全局 shim 都是 .cmd，
- * 一旦参数里夹了整段人设（9K+），裸命令就会报“The command line is too long.”，
- * 而 agent-purge <h> 没这条限制 —— 同一个 harness 两种入口行为不一致。
- * 解：找出 .cmd 里真正启动的 node 脚本，直接 node 启，绕开 cmd.exe。
- * 只认 npm 的 `"%dp0%...node_modules..."` 形态，认不出就老实走 ComSpec。
- */
-const CMD_LINE_LIMIT = 7000;
-function cmdShimNodeTarget(file) {
-	try {
-		const txt = readFileSync(file, "utf8");
-		const m = txt.match(/"%dp0%\\?([^"]*node_modules[^"]*)"/i);
-		if (!m) return null;
-		const p = join(dirname(file), m[1].replace(/\\/g, "\\"));
-		return existsSync(p) ? p : null;
-	} catch {
-		return null;
-	}
-}
-
-function dispatch(name, args, opts) {
-	// 非 Windows 也要解析成真实路径：否则 shim 目录里的同名壳转回 agent-purge 时，
-	// spawn("pi") 又会命中最前面的壳，无限套娃。
-	if (!WIN) return { cmd: resolveBin(name) ?? name, args, opts: { ...opts, shell: false } };
-	const full = resolveBin(name) ?? name;
-	const ext = extname(full).toLowerCase();
-	if (ext === ".ps1") {
-		return {
-			cmd: "powershell.exe",
-			args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", full, ...args],
-			opts: { ...opts, shell: false },
-		};
-	}
-	if (ext === ".cmd" || ext === ".bat") {
-		const comspec = process.env.ComSpec || process.env.COMSPEC || "cmd.exe";
-		// /s：首尾成对的引号由 cmd 自己剥掉一层，剩下的就是干净的命令行
-		const line = [`"${full}"`, ...args.map(winQuote)].join(" ");
-		// 参数太长就不要过 cmd.exe（8191 上限）：直接 node 启 .cmd 里那个脚本
-		if (line.length > CMD_LINE_LIMIT) {
-			const js = cmdShimNodeTarget(full);
-			if (js) return { cmd: process.execPath, args: [js, ...args], opts: { ...opts, shell: false } };
-		}
-		return {
-			cmd: comspec,
-			args: ["/d", "/s", "/c", `"${line}"`],
-			opts: { ...opts, shell: false, windowsVerbatimArguments: true },
-		};
-	}
-	return { cmd: full, args, opts: { ...opts, shell: false } };
-}
-
-/** 跨平台启动。返回 ChildProcess；调用方照常用 on("error")/on("close")。 */
-export function spawnBin(name, args = [], opts = {}) {
-	const d = dispatch(name, args, opts);
-	return spawn(d.cmd, d.args, d.opts);
-}
-
-/** 抓一次 stdout（版本探测之类用）。失败/超时返回 null，不抛。 */
-export function captureBin(name, args = [], opts = {}) {
-	const d = dispatch(name, args, { timeout: 4000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], ...opts });
-	try {
-		const r = spawnSync(d.cmd, d.args, d.opts);
-		return r.error ? null : (r.stdout ?? null);
-	} catch {
-		return null;
-	}
-}
+// shell:false 为默认；标准 npm shim 直接解析为 Node 入口，其他脚本分开处理。
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { delimiter, dirname, extname, join, resolve } from "node:path";
+import { resolveActivation } from "./state.mjs";
+import { ownShimDirectory } from "./environment.mjs";
+import { knownWrapper } from "./wrappers.mjs";
+
+const WIN = process.platform === "win32";
+const OWN_SHIM_DIR = ownShimDirectory();
+const norm = (p) => WIN ? resolve(p).toLowerCase() : resolve(p);
+export function which(names, path, exts = WIN ? [".exe", ".cmd", ".bat", ".ps1"] : [""]) {
+ for (const name of names) for (const raw of path.split(delimiter)) {
+  const dir = raw.replace(/^"|"$/g, "");
+  if (!dir || norm(dir) === norm(OWN_SHIM_DIR)) continue;
+  for (const ext of exts) { const p = join(dir, name + ext); if (existsSync(p)) return p; }
+ }
+ return null;
+}
+const SPAWN_EXTS = [".exe", ".ps1", ".cmd", ".bat"];
+export function resolveBin(name, env = process.env) {
+ if (!name) return null;
+ if (name.includes("/") || name.includes("\\")) return existsSync(name) ? name : null;
+ const real = env.AGENT_PURGE_REAL_BIN;
+ if (real && existsSync(real)) {
+  const base = real.replace(/^.*[\\/]/, "").replace(/\.(exe|cmd|bat|ps1)$/i, "");
+  if ((WIN ? base.toLowerCase() : base) === (WIN ? name.toLowerCase() : name)) return real;
+ }
+ return which([name], env.PATH || env.Path || "", WIN ? SPAWN_EXTS : [""]);
+}
+/** 显式参数 > 分家配置 > 全局；继承的注入环境不是新一次启用。 */
+export function launchConfig(state, id, { persona = null, mode = null } = {}) {
+ const activation = resolveActivation(state, id, { launch: true, persona: persona || undefined, mode: mode || undefined });
+ return { persona: activation.persona, mode: activation.mode };
+}
+// 仅接受完整的标准模板；不能从任意脚本中捞出一条 node_modules 路径跳过其他逻辑。
+const compact = (s) => s.split(/\r?\n/).filter((l) => !/^\s*#/.test(l)).map((l) => l.trim()).filter(Boolean).join("\n");
+function npmTarget(file) {
+ let text;
+ try { text = readFileSync(file, "utf8"); } catch { return null; }
+ const ext = extname(file).toLowerCase();
+ let target;
+ if (ext === ".ps1") {
+  const hits = [...text.matchAll(/"\$basedir\/([^"\r\n]+)" \$args/g)];
+  if (hits.length !== 4 || !hits.every((m) => m[1] === hits[0][1])) return null;
+  target = hits[0][1];
+  const template = `$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent
+$exe=""
+if ($PSVersionTable.PSVersion -lt "6.0" -or $IsWindows) {
+$exe=".exe"
+}
+$ret=0
+if (Test-Path "$basedir/node$exe") {
+if ($MyInvocation.ExpectingInput) {
+$input | & "$basedir/node$exe"  "$basedir/${target}" $args
+} else {
+& "$basedir/node$exe"  "$basedir/${target}" $args
+}
+$ret=$LASTEXITCODE
+} else {
+if ($MyInvocation.ExpectingInput) {
+$input | & "node$exe"  "$basedir/${target}" $args
+} else {
+& "node$exe"  "$basedir/${target}" $args
+}
+$ret=$LASTEXITCODE
+}
+exit $ret`;
+  if (compact(text) !== compact(template)) return null;
+ } else if (ext === ".cmd") {
+  const legacy = /"%dp0%\\([^"\r\n]+)" %\*/i.exec(text);
+  const modern = /SET "NPM_CLI_JS=%~dp0\\([^"\r\n]+)"[\s\S]*?"%NODE_EXE%" "%NPM_CLI_JS%" %\*/i.exec(text);
+  const m = legacy ?? modern; if (!m) return null;
+  target = m[1];
+  if (modern) {
+   // Node 20+ 的 npm.cmd 先解析 npm-prefix.js，再执行 npm-cli.js；只接受这一固定入口。
+   if (!/^node_modules[\\/]npm[\\/]bin[\\/]npm-cli\.js$/.test(target)) return null;
+  } else {
+   const template = `@ECHO off
+GOTO start
+:find_dp0
+SET dp0=%~dp0
+EXIT /b
+:start
+SETLOCAL
+CALL :find_dp0
+IF EXIST "%dp0%\\node.exe" (
+SET "_prog=%dp0%\\node.exe"
+) ELSE (
+SET "_prog=node"
+SET PATHEXT=%PATHEXT:;.JS;=;%
+)
+endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\\${target}" %*`;
+   if (compact(text) !== compact(template)) return null;
+  }
+ } else return null;
+ if (!/^node_modules[\\/]/.test(target) || /[$%`]/.test(target)) return null;
+ const script = join(dirname(file), target);
+ return existsSync(script) ? script : null;
+}
+// 已核对的启动器模板：整份匹配，不从未知 batch 中猜入口。
+function nativeShim(file) {
+ let source;
+ try { source = readFileSync(file, "utf8"); } catch { return null; }
+ const text = compact(source), dir = dirname(file);
+ if (extname(file).toLowerCase() === ".ps1") {
+  const m = /"\$basedir\/(node_modules\/[^"\r\n]+\.exe)"\s+\$args/.exec(source);
+  if (!m) return null;
+  const template = `$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent
+$exe=""
+if ($PSVersionTable.PSVersion -lt "6.0" -or $IsWindows) {
+$exe=".exe"
+}
+if ($MyInvocation.ExpectingInput) {
+$input | & "$basedir/${m[1]}"   $args
+} else {
+& "$basedir/${m[1]}"   $args
+}
+exit $LASTEXITCODE`;
+  const cmd = join(dir, m[1]);
+  return text === compact(template) && existsSync(cmd) ? { cmd, args: [] } : null;
+ }
+ if (extname(file).toLowerCase() !== ".cmd") return null;
+ if (text === '@ECHO off\nnode "%~dp0pi-launcher.js" %*') {
+  const entry = join(dir, "pi-launcher.js");
+  return existsSync(entry) ? { cmd: "node", args: [entry], hostDirect: false } : null;
+ }
+ const dsh = `@echo off
+setlocal DisableDelayedExpansion
+set "ELECTRON_RUN_AS_NODE=1"
+"%~dp0..\\..\\..\\..\\DeepSeek Harness.exe" --expose-internals "%~dp0..\\..\\..\\app.asar\\dsh\\node_modules\\@deepseek-ai\\dsh-desktop-host\\lib\\cli.js" %*
+exit /b %errorlevel%`;
+ if (text === compact(dsh)) {
+  const cmd = resolve(dir, "../../../..", "DeepSeek Harness.exe");
+  // app.asar 内部路径由 Electron 读取，普通 existsSync 无法探测。
+  const entry = resolve(dir, "../../..", "app.asar/dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/cli.js");
+  return existsSync(cmd) ? { cmd, args: ["--expose-internals", entry], env: { ELECTRON_RUN_AS_NODE: "1" } } : null;
+ }
+ return null;
+}
+function dispatch(name, args, opts) {
+ const env = opts.env ?? process.env;
+ if (!args.every((a) => typeof a === "string" && !a.includes("\0"))) throw new Error("参数必须是不含 NUL 的字符串");
+ const full = resolveBin(name, env) ?? name;
+ if (!WIN) return { hostDirect: true, cmd: full, args, opts: { ...opts, shell: false } };
+ const ext = extname(full).toLowerCase();
+ const wrapper = [".cmd", ".ps1"].includes(ext) ? knownWrapper(full, env, e => which(["node"], e.PATH || e.Path || "", [".exe"])) ?? nativeShim(full) : null;
+ if (wrapper) return { hostDirect: wrapper.hostDirect !== false, cmd: wrapper.cmd, args: [...wrapper.args, ...args], opts: { ...opts, env: { ...env, ...wrapper.env }, shell: false, windowsVerbatimArguments: false } };
+ const script = [".cmd", ".ps1"].includes(ext) ? npmTarget(full) : null;
+ if (script) {
+  const localNode = join(dirname(full), "node.exe");
+  const node = existsSync(localNode) ? localNode : which(["node"], env.PATH || env.Path || "", [".exe"]);
+  if (!node) throw new Error(`npm shim 找不到其 Node 运行时：${full}`);
+  return { hostDirect: true, cmd: node, args: [script, ...args], opts: { ...opts, shell: false, windowsVerbatimArguments: false } };
+ }
+ if (ext === ".ps1") {
+  // 不把用户参数插入 PowerShell 源码/命令行；JSON 通过子进程专用环境传输。
+  const payload = JSON.stringify({ file: resolve(full), args });
+  if (payload.length > 30000) throw new Error("普通 PowerShell 脚本参数超过 30000 字符，请使用原生入口");
+  const code = `$ErrorActionPreference='Stop'; $p=ConvertFrom-Json $env:AGENT_PURGE_PS_ARGS; Remove-Item Env:AGENT_PURGE_PS_ARGS; $a=@($p.args | ForEach-Object {[string]$_}); & $p.file @a; if ($null -ne $LASTEXITCODE) {exit $LASTEXITCODE}`;
+  return { cmd: "powershell.exe", args: ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", Buffer.from(code,"utf16le").toString("base64")], opts: { ...opts, env: { ...env, AGENT_PURGE_PS_ARGS: payload }, shell: false } };
+ }
+ if (ext === ".cmd" || ext === ".bat") {
+  // 未知 batch 可能再次展开 %*；只接收无需多层转义的参数，拒绝静默损坏。
+  if (args.some((a) => !/^[a-zA-Z0-9_./:\\=+,-]+$/.test(a)) || /[%!^&|<>\r\n"]/.test(full)) throw new Error(`非标准 batch 不能可靠传递这些参数：${full}；请指向原生 exe 或 Node 入口`);
+  const line = `"${full}" ${args.join(" ")}`;
+  if (line.length > 7000) throw new Error(`batch 参数过长：${full}`);
+  return { cmd: env.ComSpec || env.COMSPEC || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], opts: { ...opts, shell: false, windowsVerbatimArguments: true } };
+ }
+ return { hostDirect: ext === ".exe", cmd: full, args, opts: { ...opts, shell: false } };
+}
+export function prepareCommand(name, args = [], opts = {}) { return dispatch(name, args, opts); }
+export function spawnPrepared(descriptor) { return spawn(descriptor.cmd, descriptor.args, descriptor.opts); }
+export function spawnBin(name, args = [], opts = {}) {
+ const d = dispatch(name, args, opts); return spawn(d.cmd, d.args, d.opts);
+}
+export function captureBin(name, args = [], opts = {}) {
+ try {
+  const d = dispatch(name, args, { timeout: 4000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], ...opts });
+  const r = spawnSync(d.cmd, d.args, d.opts); return r.error || r.status !== 0 ? null : (r.stdout ?? null);
+ } catch { return null; }
+}

package/lib/state.mjs

@@ -1,60 +1,36 @@
-// 唯一状态文件。
-//
-// 之前是两套：`.defaults.json`（harness+mode）与 `personas/.active`（人设指针），
-// 两个文件、两套语义、Web 与 CLI 各写一边 —— 这就是"用起来混乱"的根源：
-// 用户改了一处以为全生效，其实另一处还压着旧值。
-//
-// 现在只有 state.json：
-//   persona  谁      —— 当前 persona id（人设的唯一指针）
-//   default  注入谁   —— 裸敲 agent-purge 时启动的 harness + 注入模式
-//   armed    怎么生效 —— 每家已经武装了哪几条通道：shim / slash / install
-//
-// personas/active.md 退化为「派生物」：由 launch/arm 时按 persona 生成，
-// 供落盘型 harness 与 opencode 插件读取，不再承载状态。
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+// 唯一配置文件；已配置的模式与运行时实际启用状态分开解析。
+import { existsSync, readFileSync, renameSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-
-const FILE = "state.json";
-const LEGACY_DEFAULTS = ".defaults.json";
-const LEGACY_ACTIVE = join("personas", ".active");
+import { withControlLock, atomicControlJSON } from "./control.mjs";
+import { resolveConfigured } from "./activation.mjs";
+export { resolveActivation } from "./activation.mjs";
 
 export const MODES = ["strict", "replace", "append", "off"];
-/** 三种生效通道，互不冲突，可以叠加 */
-export const ARMS = ["shim", "slash", "install"];
-
+export const ARMS = ["shim", "slash", "install", "project"];
 export const ARM_LABEL = {
-	shim: "裸命令接管（敲 codex 就是接管的）",
-	slash: "会话内 /purge（热切换）",
-	install: "配置文件常驻（连别人启动的也生效）",
+	shim: "裸命令接管（敲 codex 就是接管的）", slash: "会话内 /purge（热切换）",
+	install: "配置文件常驻（连别人启动的也生效）", project: "所选项目的规则文件",
 };
-
-export function statePath(root) {
-	return join(root, FILE);
-}
-
+export const statePath = root => join(root, "state.json");
+const object = value => value && typeof value === "object" && !Array.isArray(value);
 function emptyState() {
-	return { v: 1, persona: null, default: null, armed: {}, piAuto: false, piUserLayer: false, ompAuto: false, dshProfiles: null };
+	return { v: 1, persona: null, default: null, armed: {}, overrides: {}, projectDirs: {}, piAuto: false, piUserLayer: false, ompAuto: false, dshProfiles: null };
 }
 
-/**
- * 读状态，顺带把旧布局迁移过来（旧文件改名 `*.migrated` 留档，之后只认 state.json）。
- * 返回 `{ state, migrated[] }`；migrated 是给调用方打印的一行行说明。
- */
+/** 损坏配置保持原字节，报告后停止操作；运行时独立读取失败时只透传。 */
 export function loadState(root) {
-	const file = statePath(root);
+	const file = statePath(root), migrated = [];
 	let state = emptyState();
-	const migrated = [];
-
 	if (existsSync(file)) {
 		try {
 			const raw = JSON.parse(readFileSync(file, "utf8"));
-			state = { ...state, ...raw, armed: raw?.armed && typeof raw.armed === "object" ? raw.armed : {} };
-		} catch {
-			migrated.push("state.json 损坏 → 按空状态重来");
-		}
+			if (!object(raw)) throw new Error("配置必须是对象");
+			state = { ...state, ...raw, armed: object(raw.armed) ? raw.armed : {},
+				overrides: object(raw.overrides) ? raw.overrides : {}, projectDirs: object(raw.projectDirs) ? raw.projectDirs : {} };
+		} catch (error) { throw new Error(`state.json 损坏，原文件已保留：${file}`, { cause: error }); }
 	}
-
-	const legacy = join(root, LEGACY_DEFAULTS);
+	const legacy = join(root, ".defaults.json");
 	if (!state.default && existsSync(legacy)) {
 		try {
 			const d = JSON.parse(readFileSync(legacy, "utf8"));
@@ -62,112 +38,84 @@ export function loadState(root) {
 				state.default = { harness: d.harness, mode: MODES.includes(d.mode) ? d.mode : "replace" };
 				migrated.push(`.defaults.json → default=${state.default.harness} · ${state.default.mode}`);
 			}
-			renameSync(legacy, legacy + ".migrated");
-		} catch {
-			/* 坏文件不动它，留给人工看 */
-		}
+		} catch { /* 旧配置保持原样 */ }
 	}
-
-	if (!state.persona) {
-		const old = join(root, LEGACY_ACTIVE);
-		if (existsSync(old)) {
-			const id = readFileSync(old, "utf8").trim();
-			if (id) {
-				state.persona = id;
-				migrated.push(`personas/.active → persona=${id}`);
-			}
-			renameSync(old, old + ".migrated");
-		}
+	const oldActive = join(root, "personas", ".active");
+	if (!state.persona && existsSync(oldActive)) {
+		const id = readFileSync(oldActive, "utf8").trim();
+		if (id) { state.persona = id; migrated.push(`personas/.active → persona=${id}`); }
 	}
-
-	// 迁完立即落盘：否则下次调用看不到旧文件，迁移结果直接丢掉
-	if (migrated.length) saveState(root, state);
-
+	if (migrated.length) withControlLock(root, () => {
+		saveState(root, state);
+		if (existsSync(legacy)) renameSync(legacy, legacy + ".migrated");
+		if (existsSync(oldActive)) renameSync(oldActive, oldActive + ".migrated");
+	});
 	return { state, migrated };
 }
 
 export function saveState(root, state) {
-	// 先写临时文件再改名：Web 与 CLI 同时写时，读的一方不会看到半截 JSON
-	const file = statePath(root);
-	const tmp = `${file}.tmp-${process.pid}`;
-	try {
-		writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n");
-		renameSync(tmp, file);
-	} catch (e) {
-		// rename 失败时别把半截临时文件留在 ~/.agent-purge
-		try {
-			unlinkSync(tmp);
-		} catch {}
-		throw e;
-	}
-	return state;
+	return withControlLock(root, () => {
+		let before = {};
+		try { before = JSON.parse(readFileSync(statePath(root), "utf8")); } catch (error) { if (error.code !== "ENOENT") throw error; }
+		const next = { ...state };
+		// 随机撤销代次不会因 off→on 复活旧启动；生成器每轮核对这个值。
+		if (next.default?.mode === "off" && before.default?.mode !== "off") next.activationEpoch = randomUUID();
+		const ids = new Set([...Object.keys(before.overrides ?? {}), ...Object.keys(next.overrides ?? {}), ...(next.disabledHarnesses ?? [])]);
+		for (const id of ids) {
+			if ((next.overrides?.[id]?.mode === "off" && before.overrides?.[id]?.mode !== "off") ||
+				((next.disabledHarnesses ?? []).includes(id) && !(before.disabledHarnesses ?? []).includes(id)))
+				next.harnessEpochs = { ...next.harnessEpochs, [id]: randomUUID() };
+		}
+		atomicControlJSON(statePath(root), next);
+		return next;
+	});
 }
-
-/** 浅合并；armed 需要整块替换时传完整对象 */
-export function patchState(root, patch) {
-	const { state } = loadState(root);
-	return saveState(root, { ...state, ...patch });
+export function updateState(root, update) {
+	return withControlLock(root, () => saveState(root, update(loadState(root).state)));
 }
-
+export function patchState(root, patch) { return updateState(root, state => ({ ...state, ...patch })); }
 export function setDefault(root, { harness, mode }) {
-	if (!harness) throw new Error("harness 不能为空");
-	const { state } = loadState(root);
-	const next = { ...state, default: { harness, mode: MODES.includes(mode) ? mode : "replace" } };
-	return saveState(root, next).default;
-}
-
-export function setPersona(root, id) {
-	const { state } = loadState(root);
-	return saveState(root, { ...state, persona: id }).persona;
-}
-
-/** 裸敲 pi 是否也自动注入（装好的扩展直接读这个位） */
-export function setPiAuto(root, on) {
-	const { state } = loadState(root);
-	return saveState(root, { ...state, piAuto: on === true }).piAuto;
-}
-
-/** 裸敲 omp 是否也自动注入（omp 扩展读这个位） */
-export function setOmpAuto(root, on) {
-	const { state } = loadState(root);
-	return saveState(root, { ...state, ompAuto: on === true }).ompAuto;
+	if (!harness) throw new Error("harness 为空");
+	if (!MODES.includes(mode)) throw new Error(`未知模式: ${mode}`);
+	return updateState(root, state => ({ ...state, default: { harness, mode } })).default;
 }
-
-/** pi 的人设走哪一层：false = system（默认），true = 额外塞进用户消息（给忽略 system 的模型用） */
-export function setPiUserLayer(root, on) {
-	const { state } = loadState(root);
-	return saveState(root, { ...state, piUserLayer: on === true }).piUserLayer;
-}
-
-/** armed 变成 {codex: ["shim","install"]}；空数组即删键 */
+export function setPersona(root, id) { return patchState(root, { persona: id }).persona; }
+export function setPiAuto(root, on) { return patchState(root, { piAuto: on === true }).piAuto; }
+export function setOmpAuto(root, on) { return patchState(root, { ompAuto: on === true }).ompAuto; }
+export function setPiUserLayer(root, on) { return patchState(root, { piUserLayer: on === true }).piUserLayer; }
+export function armedOf(state, id) { return Array.isArray(state?.armed?.[id]) ? state.armed[id] : []; }
 export function setArmed(root, id, arm, on) {
-	const { state } = loadState(root);
-	const cur = new Set(state.armed?.[id] ?? []);
-	if (on) cur.add(arm);
-	else cur.delete(arm);
-	const list = ARMS.filter((a) => cur.has(a));
-	const armed = { ...state.armed };
-	if (list.length) armed[id] = list;
-	else delete armed[id];
-	saveState(root, { ...state, armed });
-	return list;
-}
-
-export function armedOf(state, id) {
-	return state.armed?.[id] ?? [];
+	if (!ARMS.includes(arm)) throw new Error(`未知通道: ${arm}`);
+	const state = updateState(root, before => {
+		const cur = new Set(armedOf(before, id)); on ? cur.add(arm) : cur.delete(arm);
+		const list = ARMS.filter(a => cur.has(a)), armed = { ...before.armed };
+		if (list.length) armed[id] = list; else delete armed[id];
+		return { ...before, armed };
+	});
+	return armedOf(state, id);
 }
-
-/** dsh 三个 profile 哪些生效：null = 没设置过（全部），[] = 全关 */
-export function dshProfilesOf(state) {
-	return Array.isArray(state?.dshProfiles) ? state.dshProfiles : null;
+export function overridesOf(state) { return object(state?.overrides) ? state.overrides : {}; }
+export function resolveFor(state, id) { return resolveConfigured(state, id); }
+export function setOverride(root, id, patch = {}) {
+	const next = updateState(root, state => {
+		const cur = { ...(overridesOf(state)[id] ?? {}) };
+		for (const [key, value] of Object.entries(patch)) {
+			if (!["persona", "mode"].includes(key)) throw new Error(`未知分家字段: ${key}`);
+			if (value === null || value === undefined || value === "") delete cur[key];
+			else if (key === "mode" && !MODES.includes(value)) throw new Error(`未知模式: ${value}`);
+			else cur[key] = value;
+		}
+		const overrides = { ...overridesOf(state) };
+		if (Object.keys(cur).length) overrides[id] = cur; else delete overrides[id];
+		return { ...state, overrides };
+	});
+	return next.overrides[id] ?? null;
 }
-
-/** 开/关单个 dsh profile；all 由调用方传入（列表归属 lib/dsh.mjs，别在状态层再写一份） */
+export function dshProfilesOf(state) { return Array.isArray(state?.dshProfiles) ? state.dshProfiles : null; }
 export function setDshProfile(root, profile, on, all) {
-	const { state } = loadState(root);
-	const cur = new Set(dshProfilesOf(state) ?? all);
-	if (on) cur.add(profile);
-	else cur.delete(profile);
-	const list = all.filter((p) => cur.has(p));
-	return saveState(root, { ...state, dshProfiles: list }).dshProfiles;
+	if (!all.includes(profile)) throw new Error(`未知 dsh profile: ${profile}`);
+	return updateState(root, state => {
+		const cur = new Set(dshProfilesOf(state) ?? all); on ? cur.add(profile) : cur.delete(profile);
+		return { ...state, dshProfiles: all.filter(p => cur.has(p)) };
+	}).dshProfiles;
 }