pi-proactive 0.2.0-beta.5 → 0.2.0-beta.7

package/tools/enumerate-residue.mjs

@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+/**
+ * 独立残留枚举器（DEBT-1）—— 按**冻结口径**实现。
+ *
+ * 口径依据（唯一真源）：docs/project/cp010-enumeration-contract.md
+ *   §3 残留七字段 + note；pidAlive 三值（true=条目在且进程活 / false=条目在但进程死 / null=条目不在）
+ *   §4 三态（expired / unreachable 计入；inflight 不计入、单列；端点=文件在且无活监听者 ⇒ 计入）
+ *   §5 canonical 发射（顶层键固定；scope 恒 canonical 顺序；scope_dirs = --scope 书写顺序；residues 按 id 排序）
+ *   §6 对拍（丢 checked_at / checked_at_iso / ledger_id；note 逐字比；退出码 0/4/5）
+ *
+ * 纪律：
+ *   - **只读**：本工具只读被枚举目录，**恒不写台账**（`--no-record` 是事实描述，不是开关）。
+ *   - **不打扰**：判定「有活监听者」只依据注册表事实（pid 是否存活），**不连接对端 socket**。
+ *   - 零第三方依赖；发布包内只有 .mjs（无 .ts）。
+ *
+ * 退出码：0=成功 / 2=用法或输入错误 / 4=对拍·空对空·不给结论 / 5=对拍·有差异。
+ *
+ * 与 ai-native 现行实现的**已知口径差异**（逐条证据见 docs/project/cp010-evidence/PROVENANCE.md）：
+ *   ① 本实现按契约 §3 只发七字段 + note；对方还多发 unreachable / identity_via 两个字段；
+ *   ② 本实现按契约 §5 只发八个顶层键；对方还多发 fault_count / collaboration_count / inflight_count；
+ *   ③ 「TTL 内但收件方进程已死」：本实现判 unreachable（契约首行「残留 = 不可能再被消费」），
+ *      对方判 inflight（只看「注册表有条目」）；
+ *   ④ 端点名解析：本实现认全 src/socket.ts 的两种形态（常规名 + G-R5 降级哈希名），
+ *      对方只认降级哈希名 ⇒ 常规名端点上字段不一致。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createHash } from "node:crypto";
+
+/** canonical 目录顺序（契约 §5）。 */
+const CANONICAL_SCOPE = ["mailbox", "run", "agents"];
+/** 信封缺省 TTL（与 src/envelope.ts: DEFAULT_TTL_MS 一致）。 */
+const DEFAULT_TTL_MS = 3_600_000;
+/** 身份不可达时的 ownerProject 兜底。 */
+const UNKNOWN_OWNER = "unknown";
+/** 对拍时丢弃的字段（契约 §6：只丢这三个）。 */
+const DIFF_DROP_FIELDS = ["checked_at", "checked_at_iso", "ledger_id"];
+/** 残留条目的字段集合（契约 §3：七字段 + note）——逐字固定，不多不少。 */
+const RESIDUE_FIELDS = ["kind", "id", "path", "agentId", "pidAlive", "ownerProject", "mtime", "note"];
+
+const EXIT_OK = 0;
+const EXIT_USAGE = 2;
+const EXIT_EMPTY_VS_EMPTY = 4;
+const EXIT_DIFFERENT = 5;
+
+const USAGE = `用法：
+  enumerate-residue.mjs [--agent-dir <dir>] [--scope mailbox,run,agents] [--json] [--no-record]
+  enumerate-residue.mjs ... --diff <产物.json> [--lenient]
+
+  --agent-dir  agent 根目录（默认 PI_CODING_AGENT_DIR 或 ~/.pi/agent）；扫描 <dir>/proactive/{mailbox,run,agents}
+  --scope      要扫描的目录（逗号分隔）；书写顺序原样出现在 scope_dirs；scope 恒为 canonical 顺序
+  --json       stdout 输出 JSON（默认）
+  --no-record  显式声明「不写台账」——本工具恒只读，该参数只为调用兼容
+  --diff       与一份产物做字段级对拍；0=一致 / 4=空对空·不给结论 / 5=有差异
+  --lenient    对拍宽松档（有损：pidAlive null↔false 视为等价；数组按 id 排序后比较）
+`;
+
+// ---------------------------------------------------------------- 只读小工具 ----
+
+function readDirSafe(dir) {
+	try {
+		return fs.readdirSync(dir).sort();
+	} catch {
+		return [];
+	}
+}
+
+function statSafe(p) {
+	try {
+		return fs.statSync(p);
+	} catch {
+		return null;
+	}
+}
+
+function readJsonSafe(p) {
+	try {
+		return JSON.parse(fs.readFileSync(p, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+/** pid 是否存活（EPERM = 进程在但无权发信号 ⇒ 仍算活）。 */
+function pidAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return e?.code === "EPERM";
+	}
+}
+
+// ------------------------------------------------------------------ 命名规则 ----
+// 三条纯函数与 pi-proactive 源码**逐字一致**（发布包内没有 .ts，故此处复制；改规则时必须同步两处）：
+//   src/socket.ts: sanitizeSocketFileName / hashedSocketFileName
+//   src/envelope.ts: agentSegment
+
+/** socket 文件名安全化：`/ \ # 空白` → `-`。 */
+function sanitizeSocketFileName(agentId) {
+	return agentId.replace(/[/\\#\s]/g, "-") || "unknown";
+}
+
+/** 降级端点名：`h-<sha256(agentId) 前 16 位>`。 */
+function hashedSocketFileName(agentId) {
+	return `h-${createHash("sha256").update(agentId, "utf8").digest("hex").slice(0, 16)}`;
+}
+
+/** 邮箱/注册表段名：`/ \ 空白` → `_`（保留 `#`）。 */
+function agentSegment(agentId) {
+	return agentId.replace(/[/\\\s]/g, "_") || "unknown";
+}
+
+// -------------------------------------------------------------------- 注册表 ----
+
+/** 读注册表（只读）：`<agentDir>/proactive/agents/*.json`。 */
+function readRegistry(agentsDir) {
+	const byId = new Map();
+	const bySegment = new Map();
+	for (const name of readDirSafe(agentsDir)) {
+		if (!name.endsWith(".json")) continue;
+		const parsed = readJsonSafe(path.join(agentsDir, name));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+		const agentId =
+			typeof parsed.agentId === "string" && parsed.agentId.length > 0 ? parsed.agentId : name.slice(0, -5);
+		parsed.agentId = agentId;
+		byId.set(agentId, parsed);
+		const seg = agentSegment(agentId);
+		if (!bySegment.has(seg)) bySegment.set(seg, parsed);
+	}
+	return { byId, bySegment };
+}
+
+function lookup(registry, agentId) {
+	return registry.byId.get(agentId) ?? registry.bySegment.get(agentId);
+}
+
+/** ownerProject = 注册表条目 cwd 的目录名；身份不可达 ⇒ "unknown"。 */
+function ownerProject(entry) {
+	const cwd = entry && typeof entry.cwd === "string" ? entry.cwd : "";
+	const base = cwd ? path.basename(cwd.replace(/\/+$/, "")) : "";
+	return base || UNKNOWN_OWNER;
+}
+
+// ------------------------------------------------------------------ 枚举本体 ----
+
+/** 邮箱：未认领的信封。expired / unreachable 计入；inflight 不计入。 */
+function scanMailbox(mailboxDir, registry, now) {
+	const out = [];
+	for (const inbox of readDirSafe(mailboxDir)) {
+		if (inbox === "claims") continue; // 认领锁目录，不是收件箱
+		const inboxDir = path.join(mailboxDir, inbox);
+		const st = statSafe(inboxDir);
+		if (!st || !st.isDirectory()) continue;
+		for (const name of readDirSafe(inboxDir)) {
+			if (!name.endsWith(".json")) continue;
+			const file = path.join(inboxDir, name);
+			const fst = statSafe(file);
+			if (!fst || !fst.isFile()) continue;
+			const env = readJsonSafe(file);
+			const to = env && typeof env.to === "string" && env.to ? env.to : inbox;
+			const entry = lookup(registry, to);
+			const id = env && typeof env.id === "string" && env.id ? env.id : name.slice(0, -5);
+			const createdAt =
+				env && typeof env.createdAt === "number" && Number.isFinite(env.createdAt) ? env.createdAt : fst.mtimeMs;
+			const ttlMs = env && typeof env.ttlMs === "number" && env.ttlMs > 0 ? env.ttlMs : DEFAULT_TTL_MS;
+			const alive = entry ? pidAlive(entry.pid) : null; // null = 条目不在
+			const expired = now - createdAt >= ttlMs; // 恰好等于 TTL 即过期
+			const state = expired ? "expired" : alive === true ? "inflight" : "unreachable";
+			const note = expired
+				? `TTL expired; ttlMs=${ttlMs}`
+				: alive === true
+					? "inflight (TTL 内且收件方可达)"
+					: entry
+						? "identity gone (process dead)"
+						: "identity gone (registry entry absent)";
+			out.push({
+				kind: "envelope",
+				id,
+				path: file,
+				agentId: to,
+				pidAlive: alive,
+				ownerProject: ownerProject(entry),
+				// mtime = 对象自身的时间戳：信封用 createdAt（TTL 的基准），端点没有 createdAt ⇒ 用文件 mtime。
+				mtime: Math.floor(createdAt),
+				note,
+				state,
+			});
+		}
+	}
+	return out;
+}
+
+/** 端点：`<agentDir>/proactive/run/*.sock`。文件在且无活监听者 ⇒ 计入。 */
+function scanRun(runDir, registry) {
+	const out = [];
+	const byFile = new Map();
+	for (const entry of registry.byId.values()) {
+		const agentId = entry.agentId;
+		if (typeof agentId !== "string" || !agentId) continue;
+		// 端点名有两种形态（src/socket.ts: 常规名 / G-R5 长度降级名）——两种都要认。
+		byFile.set(`${sanitizeSocketFileName(agentId)}.sock`, entry);
+		byFile.set(`${hashedSocketFileName(agentId)}.sock`, entry);
+	}
+	for (const name of readDirSafe(runDir)) {
+		if (!name.endsWith(".sock")) continue;
+		const file = path.join(runDir, name);
+		const st = statSafe(file);
+		// 端点在真机上就是 unix domain socket（statSync().isFile() === false！）⇒ 只排除目录，不能用 isFile 过滤。
+		if (!st || st.isDirectory()) continue;
+		const entry = byFile.get(name);
+		const alive = entry ? pidAlive(entry.pid) : null;
+		if (alive === true) continue; // 有活监听者 ⇒ 不计入
+		out.push({
+			kind: "endpoint",
+			id: name,
+			path: file,
+			agentId: entry ? entry.agentId : null,
+			pidAlive: alive,
+			ownerProject: ownerProject(entry),
+			mtime: Math.floor(st.mtimeMs),
+			note: entry ? "entry alive but process dead" : "registry entry gone (swept)",
+			state: "endpoint",
+		});
+	}
+	return out;
+}
+
+/** 残留条目 → 契约 §3 的七字段 + note（逐字固定顺序）。 */
+function toResidue(r) {
+	const out = {};
+	for (const f of RESIDUE_FIELDS) out[f] = r[f];
+	return out;
+}
+
+/** 枚举：产出 canonical 产物（契约 §5）。 */
+function enumerate(opts) {
+	const now = Date.now();
+	const root = path.join(opts.agentDir, "proactive");
+	const dirs = {
+		mailbox: path.join(root, "mailbox"),
+		run: path.join(root, "run"),
+		agents: path.join(root, "agents"),
+	};
+	const selected = CANONICAL_SCOPE.filter((d) => opts.scope.includes(d));
+	const registry = opts.scope.includes("agents")
+		? readRegistry(dirs.agents)
+		: { byId: new Map(), bySegment: new Map() };
+
+	const records = [];
+	if (opts.scope.includes("mailbox")) records.push(...scanMailbox(dirs.mailbox, registry, now));
+	if (opts.scope.includes("run")) records.push(...scanRun(dirs.run, registry));
+	records.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+	const counts = { expired: 0, unreachable: 0, endpoint: 0, inflight: 0 };
+	for (const r of records) counts[r.state] += 1;
+	const residues = records.filter((r) => r.state !== "inflight").map(toResidue);
+
+	return {
+		checked_at: now,
+		checked_at_iso: new Date(now).toISOString(),
+		scope: selected.map((d) => dirs[d]),
+		scope_dirs: [...opts.scope],
+		residue_count: residues.length,
+		zero: residues.length === 0,
+		residues,
+		note:
+			`残留 ${residues.length} 条（expired ${counts.expired} · unreachable ${counts.unreachable} · ` +
+			`endpoint ${counts.endpoint}）；在途 ${counts.inflight} 条（TTL 内且收件方可达，不计入）；只读枚举，未写台账`,
+	};
+}
+
+// ---------------------------------------------------------------------- 对拍 ----
+
+function sameValue(a, b) {
+	return deepEqual(a, b);
+}
+
+/** 深比较（JSON 值）：数组/对象按内容比，不是按引用。 */
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (typeof a === "number" && typeof b === "number") return Number.isNaN(a) && Number.isNaN(b);
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	if (Array.isArray(a)) {
+		if (a.length !== b.length) return false;
+		return a.every((v, i) => deepEqual(v, b[i]));
+	}
+	const ka = Object.keys(a);
+	const kb = Object.keys(b);
+	if (ka.length !== kb.length) return false;
+	return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+}
+
+/** 宽松档的有损等价：pidAlive null↔false 视为等价（契约 §6）。 */
+function lossyEqual(field, a, b) {
+	return field === "pidAlive" && (a === null || b === null) && (a === false || b === false);
+}
+
+function diffValue(field, a, b, lenient) {
+	if (sameValue(a, b)) return null;
+	if (lenient && lossyEqual(field, a, b)) return null;
+	return { field, ours: a === undefined ? null : a, theirs: b === undefined ? null : b };
+}
+
+function compareResidues(oursList, theirList, lenient) {
+	const differences = [];
+	const o = new Map(oursList.map((r) => [r.id, r]));
+	const t = new Map(theirList.map((r) => [r.id, r]));
+	// 严格档：残留条目的**顺序**也算差异（契约 §6 的「数组排序」有损项默认关闭）。
+	if (!lenient) {
+		const oIds = oursList.map((r) => r.id);
+		const tIds = theirList.map((r) => r.id);
+		if (!deepEqual(oIds, tIds)) {
+			differences.push({ field: "residues[].id 序列", ours: oIds, theirs: tIds, reason: "残留条目顺序不同" });
+		}
+	}
+	for (const id of [...o.keys()].sort()) {
+		const a = o.get(id);
+		const b = t.get(id);
+		if (!b) {
+			differences.push({ field: `residues[id=${id}]`, ours: id, theirs: null, reason: "我方多出残留条目" });
+			continue;
+		}
+		for (const f of RESIDUE_FIELDS) {
+			const d = diffValue(f, a[f], b[f], lenient);
+			if (d) differences.push({ field: `residues[id=${id}].${f}`, ours: d.ours, theirs: d.theirs });
+		}
+		for (const f of Object.keys(b)) {
+			if (!RESIDUE_FIELDS.includes(f)) {
+				differences.push({ field: `residues[id=${id}].${f}`, ours: null, theirs: b[f], reason: "对方多出字段" });
+			}
+		}
+		for (const f of Object.keys(a)) {
+			if (!RESIDUE_FIELDS.includes(f)) {
+				differences.push({ field: `residues[id=${id}].${f}`, ours: a[f], theirs: null, reason: "我方多出字段" });
+			}
+		}
+	}
+	for (const id of [...t.keys()].sort()) {
+		if (!o.has(id)) {
+			differences.push({ field: `residues[id=${id}]`, ours: null, theirs: id, reason: "对方多出残留条目" });
+		}
+	}
+	return differences;
+}
+
+/** 字段级对拍（契约 §6）。 */
+function compare(ours, theirs, lenient) {
+	const ourRes = Array.isArray(ours.residues) ? ours.residues : [];
+	const theirRes = Array.isArray(theirs.residues) ? theirs.residues : [];
+	const ourCount = typeof ours.residue_count === "number" ? ours.residue_count : ourRes.length;
+	const theirCount = typeof theirs.residue_count === "number" ? theirs.residue_count : theirRes.length;
+	const summary = {
+		ours: { residue_count: ourCount, zero: ours.zero === true },
+		theirs: { residue_count: theirCount, zero: theirs.zero === true },
+	};
+
+	// 空对空 ⇒ 不给结论（两边都没残留时，「一致」是空洞的）。
+	if (ourCount === 0 && theirCount === 0) {
+		return {
+			verdict: "empty_vs_empty",
+			reason: "空对空·不给结论（两侧都没有残留 ⇒ 一致性无法判别）",
+			lossy: !!lenient,
+			differences: [],
+			...summary,
+		};
+	}
+
+	const differences = [];
+	for (const key of Object.keys(theirs)) {
+		if (DIFF_DROP_FIELDS.includes(key)) continue;
+		if (!(key in ours)) {
+			differences.push({ field: key, ours: null, theirs: theirs[key], reason: "对方多出顶层键" });
+			continue;
+		}
+		if (key === "residues") continue;
+		const d = diffValue(key, ours[key], theirs[key], lenient);
+		if (d) differences.push({ field: key, ours: d.ours, theirs: d.theirs });
+	}
+	for (const key of Object.keys(ours)) {
+		if (DIFF_DROP_FIELDS.includes(key)) continue;
+		if (!(key in theirs)) {
+			differences.push({ field: key, ours: ours[key], theirs: null, reason: "我方多出顶层键" });
+		}
+	}
+	differences.push(...compareResidues(ourRes, theirRes, lenient));
+
+	return {
+		verdict: differences.length === 0 ? "identical" : "different",
+		reason:
+			differences.length === 0
+				? "字段级一致（已丢 checked_at / checked_at_iso / ledger_id）"
+				: `有差异（${differences.length} 处）`,
+		lossy: !!lenient,
+		lossy_note: lenient ? "有损档：pidAlive null↔false 视为等价；数组按 id 排序后比较" : null,
+		differences,
+		...summary,
+	};
+}
+
+// ------------------------------------------------------------------------ CLI ----
+
+function parseArgs(argv) {
+	const opts = {
+		agentDir: null,
+		scope: null,
+		json: false,
+		diff: null,
+		lenient: false,
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--agent-dir") opts.agentDir = argv[++i] ?? null;
+		else if (a === "--scope") opts.scope = argv[++i] ?? null;
+		else if (a === "--json") opts.json = true;
+		else if (a === "--no-record") opts.noRecord = true;
+		else if (a === "--diff") opts.diff = argv[++i] ?? null;
+		else if (a === "--lenient") opts.lenient = true;
+		else if (a === "--record") return { error: "本工具恒只读（不写台账）：--record 未实现，请用 --no-record" };
+		else if (a === "-h" || a === "--help") return { help: true };
+		else return { error: `未知参数：${a}` };
+	}
+	if (opts.agentDir === null) {
+		opts.agentDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+	}
+	if (opts.scope === null) {
+		opts.scope = [...CANONICAL_SCOPE];
+	} else {
+		const names = opts.scope.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+		for (const n of names) {
+			if (!CANONICAL_SCOPE.includes(n)) return { error: `--scope 含未知目录：${n}（只能是 ${CANONICAL_SCOPE.join("/")}）` };
+		}
+		const seen = new Set();
+		opts.scope = names.filter((n) => (seen.has(n) ? false : (seen.add(n), true)));
+		if (opts.scope.length === 0) return { error: "--scope 为空" };
+	}
+	opts.agentDir = path.resolve(opts.agentDir);
+	if (opts.diff !== null) opts.diff = path.resolve(opts.diff);
+	return { opts };
+}
+
+function humanReport(artifact) {
+	const lines = [
+		`残留 ${artifact.residue_count} 条｜检查时刻 ${artifact.checked_at_iso}`,
+		`note: ${artifact.note}`,
+	];
+	for (const r of artifact.residues) {
+		lines.push(`- [${r.kind}] ${r.id}  pidAlive=${String(r.pidAlive)}  owner=${r.ownerProject}  ${r.note}`);
+		lines.push(`  ${r.path}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function main(argv) {
+	const parsed = parseArgs(argv);
+	if (parsed.error) {
+		process.stderr.write(`用法错误：${parsed.error}\n${USAGE}`);
+		return EXIT_USAGE;
+	}
+	if (parsed.help) {
+		process.stdout.write(USAGE);
+		return EXIT_OK;
+	}
+	const opts = parsed.opts;
+	const artifact = enumerate(opts);
+
+	if (opts.diff !== null) {
+		const peer = readJsonSafe(opts.diff);
+		if (!peer || typeof peer !== "object" || Array.isArray(peer)) {
+			process.stderr.write(`用法错误：读不到对拍产物或不是 JSON 对象：${opts.diff}\n`);
+			return EXIT_USAGE;
+		}
+		const report = compare(artifact, peer, opts.lenient);
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (report.verdict === "identical") return EXIT_OK;
+		if (report.verdict === "empty_vs_empty") return EXIT_EMPTY_VS_EMPTY;
+		return EXIT_DIFFERENT;
+	}
+
+	process.stdout.write(opts.json ? `${JSON.stringify(artifact, null, 2)}\n` : humanReport(artifact));
+	return EXIT_OK;
+}
+
+process.exitCode = main(process.argv.slice(2));