weapp-ide-cli 6.2.0 → 6.3.0

package/dist/{devtoolsProjectOwnership-yDD6h0dO.js → devtoolsProjectOwnership-BMfSAg4n.js}

@@ -1,16 +1,16 @@
-import { a as assertWechatDevtoolsPort, c as withPowerShellUtf8Output, i as assertWechatDevtoolsHost, o as resolveWechatDevtoolsInstallationRoot, r as resolveWechatDevtoolsTarget, s as resolveWechatInspectionTimeout } from "./sessionStore-zdzy2UFM.js";
+import { E as withPowerShellUtf8Output, T as inspectWechatDevtoolsInstallation, g as resolveWechatInspectionTimeout, h as resolveWechatDevtoolsInstallationRoot, m as assertWechatDevtoolsPort, p as assertWechatDevtoolsHost, u as resolveWechatDevtoolsTarget } from "./automatorProject-DjYLqMj6.js";
 import path from "node:path";
 import { TextDecoder, debuglog, isDeepStrictEqual, stripVTControlCharacters } from "node:util";
 import { assertMachineE2ELeaseRecoveryScope, mutateLease, withMachineE2ELease, withMachineE2ELeaseRecoveryOperation } from "@weapp-vite/devtools-runtime";
 import { execa } from "execa";
-import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import process from "node:process";
+import { createHash, randomUUID } from "node:crypto";
 import { Buffer } from "node:buffer";
 import net from "node:net";
 import { setTimeout } from "node:timers/promises";
 import { z } from "zod";
-import { performance } from "node:perf_hooks";
+import { performance as performance$1 } from "node:perf_hooks";
 //#region src/cli/agentStart.ts
 /** 提取独立的完整 JSON 对象，普通日志和嵌套对象不能替代命令响应。 */
 function readResponseObjects(stdout) {
@@ -91,6 +91,9 @@ async function startWechatIdeAgent(options) {
 				String(options.port)
 			];
 			if (options.trustProject === true) argv.push("--trust-project");
+			options.signal?.throwIfAborted();
+			await options.onBeforeDispatch?.();
+			options.signal?.throwIfAborted();
 			const started = parseAgentStartResponse((await execa(target.cliPath, argv, {
 				cancelSignal: options.signal,
 				timeout,
@@ -114,34 +117,151 @@ async function startWechatIdeAgent(options) {
 	});
 }
 //#endregion
-//#region src/devtoolsProjectOwnership/host.ts
-const inspectionOptions$1 = {
+//#region src/devtoolsProjectOwnership/installationExit/darwinKernelPaths.ts
+const inspectionTimeoutMs$1 = 1e4;
+const kernelPathsScript = `
+ObjC.import('Foundation');
+ObjC.bindFunction('malloc', ['void *', ['unsigned long']]);
+ObjC.bindFunction('free', ['void', ['void *']]);
+ObjC.bindFunction('proc_pidpath', ['int', ['int', 'void *', 'uint32_t']]);
+ObjC.bindFunction('strchr', ['char *', ['void *', 'int']]);
+function run(argv) {
+  var pids = JSON.parse(argv[0]);
+  var buffer = $.malloc(4096);
+  if (!buffer) throw new Error('Cannot allocate process path buffer.');
+  try {
+    return JSON.stringify(pids.map(function(pid) {
+      var count = $.proc_pidpath(pid, buffer, 4096);
+      return { pid: pid, executable: count > 0 ? $.strchr(buffer, 47) : null };
+    }));
+  } finally { $.free(buffer); }
+}
+`;
+/** 在 JSON 边界严格核验内核响应，不让进程身份查询依赖 schema 运行时。 */
+function parseKernelPaths(stdout) {
+	const parsed = JSON.parse(stdout);
+	if (!Array.isArray(parsed)) throw new TypeError("Invalid kernel process paths.");
+	return parsed.map((entry) => {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry) || Object.keys(entry).length !== 2 || !("pid" in entry) || typeof entry.pid !== "number" || !Number.isSafeInteger(entry.pid) || entry.pid <= 0 || !("executable" in entry) || entry.executable !== null && typeof entry.executable !== "string") throw new TypeError("Invalid kernel process path entry.");
+		return {
+			pid: entry.pid,
+			executable: entry.executable
+		};
+	});
+}
+/** 系统 JXA/libproc 不可用时明确拒绝核验，不安装工具或以进程标题降级。 */
+async function readDarwinKernelPaths(pids, timeoutMs = inspectionTimeoutMs$1) {
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error("Installation-exit recovery cannot inspect kernel executable paths.");
+	const result = await execa("/usr/bin/osascript", [
+		"-l",
+		"JavaScript",
+		"-e",
+		kernelPathsScript,
+		JSON.stringify(pids)
+	], {
+		timeout: Math.min(inspectionTimeoutMs$1, timeoutMs),
+		reject: false,
+		env: { LC_ALL: "C" }
+	});
+	if (result.exitCode !== 0 || result.timedOut || result.signal || result.stderr?.trim()) throw new Error("Installation-exit recovery cannot inspect kernel executable paths.");
+	let parsed;
+	try {
+		parsed = parseKernelPaths(result.stdout);
+	} catch {
+		throw new Error("Installation-exit recovery received incomplete kernel executable paths.");
+	}
+	const entries = new Map(parsed.map((entry) => [entry.pid, entry.executable]));
+	if (entries.size !== pids.length || parsed.length !== pids.length || pids.some((pid) => !entries.has(pid))) throw new Error("Installation-exit recovery received incomplete kernel process identities.");
+	return entries;
+}
+//#endregion
+//#region src/devtoolsProjectOwnership/darwinProcessIdentity.ts
+const inspectionTimeoutMs = 3e3;
+function invalidIdentity$2() {
+	return /* @__PURE__ */ new Error("Managed DevTools process identity could not be verified; no project was closed.");
+}
+async function readStarted(pids, remaining) {
+	const result = await execa("/bin/ps", [
+		"-p",
+		pids.join(","),
+		"-o",
+		"pid=,lstart="
+	], {
+		timeout: remaining(),
+		reject: false,
+		env: { LC_ALL: "C" }
+	});
+	remaining();
+	if (result.timedOut || result.signal || result.stderr?.trim() || result.exitCode === 0 && !result.stdout.trim() || result.exitCode !== 0 && !(result.exitCode === 1 && !result.stdout.trim())) throw invalidIdentity$2();
+	const started = /* @__PURE__ */ new Map();
+	for (const line of result.stdout.split(/\r?\n/).filter((line) => line.trim())) {
+		const match = /^\s*(\d+)\s+(\w{3}\s+\w{3}\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s*$/.exec(line);
+		const pid = Number(match?.[1]);
+		if (!match || !pids.includes(pid) || started.has(pid)) throw invalidIdentity$2();
+		started.set(pid, match[2].replace(/\s+/g, " "));
+	}
+	return started;
+}
+/** 批量读取内核路径，并以前后启动时间绑定 PID；进程标题变化不改变身份。 */
+async function readDarwinManagedProcessIdentities(pids) {
+	if (pids.some((pid) => !Number.isSafeInteger(pid) || pid <= 0)) throw invalidIdentity$2();
+	const requested = [...new Set(pids)];
+	const identities = new Map(requested.map((pid) => [pid, void 0]));
+	if (!requested.length) return identities;
+	const deadline = performance.now() + inspectionTimeoutMs;
+	const remaining = () => {
+		const timeout = Math.floor(deadline - performance.now());
+		if (timeout <= 0) throw invalidIdentity$2();
+		return timeout;
+	};
+	const before = await readStarted(requested, remaining);
+	if (!before.size) return identities;
+	const paths = await readDarwinKernelPaths([...before.keys()], remaining());
+	const after = await readStarted(requested, remaining);
+	for (const pid of requested) {
+		const started = after.get(pid);
+		if (!started) continue;
+		const executable = paths.get(pid);
+		if (before.get(pid) !== started || !executable?.startsWith("/")) throw invalidIdentity$2();
+		identities.set(pid, {
+			pid,
+			started,
+			executable
+		});
+	}
+	remaining();
+	return identities;
+}
+//#endregion
+//#region src/devtoolsProjectOwnership/processIdentity.ts
+const inspectionOptions$2 = {
 	timeout: 3e3,
 	reject: false,
 	windowsHide: true
 };
-const windowsInspectionOptions = {
-	...inspectionOptions$1,
+const windowsInspectionOptions$1 = {
+	...inspectionOptions$2,
 	timeout: resolveWechatInspectionTimeout("win32")
 };
-function invalidIdentity(result, timeout) {
+function invalidIdentity$1(result, timeout) {
 	const details = result ? ` Inspection: exitCode=${result.exitCode ?? "none"}, signal=${result.signal ?? "none"}, timedOut=${result.timedOut ?? false}, timeoutMs=${timeout}.` : "";
 	return /* @__PURE__ */ new Error(`Managed DevTools process identity could not be verified; no project was closed.${details}`);
 }
 /** PID 必须连同启动时间和可执行文件核验；进程号复用不继承所有权。 */
 async function readManagedProcessIdentity(pid, platform = process.platform) {
-	if (!Number.isSafeInteger(pid) || pid <= 0) throw invalidIdentity();
+	if (!Number.isSafeInteger(pid) || pid <= 0) throw invalidIdentity$1();
+	if (platform === "darwin") return (await readDarwinManagedProcessIdentities([pid])).get(pid);
 	if (platform === "win32") {
 		const result = await execa("powershell.exe", [
 			"-NoProfile",
 			"-NonInteractive",
 			"-Command",
 			withPowerShellUtf8Output(`$ErrorActionPreference='Stop'; Get-CimInstance Win32_Process -Filter "ProcessId=${pid}" | Select-Object ProcessId,ExecutablePath,@{Name='Started';Expression={$_.CreationDate.ToUniversalTime().ToString('o')}} | ConvertTo-Json -Compress`)
-		], windowsInspectionOptions);
-		if (result.exitCode !== 0) throw invalidIdentity(result, windowsInspectionOptions.timeout);
+		], windowsInspectionOptions$1);
+		if (result.exitCode !== 0) throw invalidIdentity$1(result, windowsInspectionOptions$1.timeout);
 		if (!result.stdout.trim()) return;
 		const value = JSON.parse(result.stdout);
-		if (!value || typeof value !== "object" || !("ProcessId" in value) || value.ProcessId !== pid || !("ExecutablePath" in value) || typeof value.ExecutablePath !== "string" || !value.ExecutablePath || !("Started" in value) || typeof value.Started !== "string" || !value.Started) throw invalidIdentity();
+		if (!value || typeof value !== "object" || !("ProcessId" in value) || value.ProcessId !== pid || !("ExecutablePath" in value) || typeof value.ExecutablePath !== "string" || !value.ExecutablePath || !("Started" in value) || typeof value.Started !== "string" || !value.Started) throw invalidIdentity$1();
 		return {
 			pid,
 			executable: value.ExecutablePath,
@@ -151,17 +271,18 @@ async function readManagedProcessIdentity(pid, platform = process.platform) {
 	if (platform === "linux") try {
 		const [executable, stat] = await Promise.all([fs.readlink(`/proc/${pid}/exe`), fs.readFile(`/proc/${pid}/stat`, "utf8")]);
 		const boot = await fs.readFile("/proc/sys/kernel/random/boot_id", "utf8").catch(() => {
-			throw invalidIdentity();
+			throw invalidIdentity$1();
 		});
 		const started = stat.slice(stat.lastIndexOf(")") + 2).split(/\s+/)[19];
-		if (!started || !/^\d+$/.test(started) || !boot.trim()) throw invalidIdentity();
+		if (!started || !/^\d+$/.test(started) || !boot.trim()) throw invalidIdentity$1();
 		return {
 			pid,
 			executable,
 			started: `${boot.trim()}:${started}`
 		};
 	} catch (error) {
-		if (error.code === "ENOENT") return;
+		const code = error.code;
+		if (code === "ENOENT" || code === "ESRCH") return;
 		throw error;
 	}
 	const result = await execa("ps", [
@@ -172,12 +293,12 @@ async function readManagedProcessIdentity(pid, platform = process.platform) {
 		"-o",
 		"comm="
 	], {
-		...inspectionOptions$1,
+		...inspectionOptions$2,
 		env: { LC_ALL: "C" }
 	});
 	if (result.exitCode === 1 && !result.stdout.trim()) return;
 	const match = /^(\w{3}\s+\w{3}\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(\S[^\r\n]*)$/.exec(result.stdout.trim());
-	if (result.exitCode !== 0 || !match) throw invalidIdentity();
+	if (result.exitCode !== 0 || !match) throw invalidIdentity$1();
 	return {
 		pid,
 		started: match[1].replace(/\s+/g, " "),
@@ -187,6 +308,21 @@ async function readManagedProcessIdentity(pid, platform = process.platform) {
 function sameManagedProcess(first, second) {
 	return first.pid === second.pid && first.started === second.started && first.executable === second.executable;
 }
+//#endregion
+//#region src/devtoolsProjectOwnership/host.ts
+const inspectionOptions$1 = {
+	timeout: 3e3,
+	reject: false,
+	windowsHide: true
+};
+const windowsInspectionOptions = {
+	...inspectionOptions$1,
+	timeout: resolveWechatInspectionTimeout("win32")
+};
+function invalidIdentity(result, timeout) {
+	const details = result ? ` Inspection: exitCode=${result.exitCode ?? "none"}, signal=${result.signal ?? "none"}, timedOut=${result.timedOut ?? false}, timeoutMs=${timeout}.` : "";
+	return /* @__PURE__ */ new Error(`Managed DevTools process identity could not be verified; no project was closed.${details}`);
+}
 async function listenerPid(port, platform = process.platform) {
 	const result = platform === "win32" ? await execa("powershell.exe", [
 		"-NoProfile",
@@ -214,7 +350,7 @@ async function inspectManagedProjectHost(target, port, platform = process.platfo
 	return identity;
 }
 async function assertManagedInstallation(target) {
-	const current = await resolveWechatDevtoolsTarget({ cliPath: target.cliPath });
+	const current = await inspectWechatDevtoolsInstallation(target.cliPath);
 	if (current.installationId !== target.installationId || current.appPath !== target.appPath || current.cliPath !== target.cliPath || current.profileDir !== target.profileDir || current.version !== target.version || current.channel !== target.channel) throw new Error("Managed DevTools installation changed; no project was closed.");
 }
 function isManagedPortClosed(port) {
@@ -255,7 +391,8 @@ const installationExitRecoverySchema = z.object({
 		state: z.enum([
 			"starting",
 			"unconfirmed",
-			"failed"
+			"failed",
+			"borrowed"
 		]),
 		error: z.string().optional(),
 		updatedAt: z.string().min(1),
@@ -276,12 +413,6 @@ const installationExitRecoverySchema = z.object({
 	}).strict()
 }).strict();
 //#endregion
-//#region src/devtoolsProjectOwnership/journal/constants.ts
-/** 受管项目日志的环境变量名称；基础设施预检可在构建包之前读取。 */
-const MANAGED_PROJECT_JOURNAL_ENV = "WEAPP_IDE_MANAGED_PROJECT_JOURNAL";
-/** 仅供显式受管任务声明双项目窗口验收；不允许无限扩大并行窗口。 */
-const MANAGED_PROJECT_MAX_WINDOWS_ENV = "WEAPP_IDE_MANAGED_PROJECT_MAX_WINDOWS";
-//#endregion
 //#region src/devtoolsProjectOwnership/journal/scope.ts
 const markerName = ".ownership-scope";
 const scopeSchema = z.object({
@@ -467,7 +598,7 @@ async function readWindowsJournalWriterIdentity() {
 	const timeout = resolveWechatInspectionTimeout("win32");
 	const trace = debug.enabled;
 	const command = windowsSelfIdentityCommand(process.pid);
-	const started = performance.now();
+	const started = performance$1.now();
 	const query = execa("powershell.exe", [
 		"-NoProfile",
 		"-NonInteractive",
@@ -481,14 +612,14 @@ async function readWindowsJournalWriterIdentity() {
 		stripFinalNewline: !trace
 	});
 	if (trace) {
-		const report = (phase) => debug("phase=%s elapsedMs=%s", phase, (performance.now() - started).toFixed(1));
+		const report = (phase) => debug("phase=%s elapsedMs=%s", phase, (performance$1.now() - started).toFixed(1));
 		report("launch");
 		query.nodeChildProcess.once("spawn", () => report("spawn"));
 		query.stderr?.on("data", observeWindowsSelfIdentityPhases(report));
 	}
 	const result = await query;
 	const stderr = trace ? stripWindowsSelfIdentityPhases(result.stderr) : result.stderr;
-	if (trace) debug("phase=settled elapsedMs=%s exitCode=%s signal=%s timedOut=%s", (performance.now() - started).toFixed(1), result.exitCode ?? "none", result.signal ?? "none", result.timedOut ?? false);
+	if (trace) debug("phase=settled elapsedMs=%s exitCode=%s signal=%s timedOut=%s", (performance$1.now() - started).toFixed(1), result.exitCode ?? "none", result.signal ?? "none", result.timedOut ?? false);
 	if (result.exitCode !== 0 || result.failed || result.timedOut || result.signal || stderr.trim()) {
 		const reason = /^WEAPP_JOURNAL_SELF_V1:error:([\w.]+):-?\d+\r?\n?$/.exec(stderr)?.[1] ?? "unconfirmed";
 		throw new Error(`Managed journal writer identity could not be verified; the journal remains unchanged. Inspection: exitCode=${result.exitCode ?? "none"}, signal=${result.signal ?? "none"}, timedOut=${result.timedOut ?? false}, timeoutMs=${timeout}, reason=${reason}.`);
@@ -513,6 +644,26 @@ function readManagedJournalWriterIdentity() {
 	return currentIdentity$1;
 }
 //#endregion
+//#region src/devtoolsProjectOwnership/snapshot/schema.ts
+const managedSnapshotSchema = z.object({
+	protocol: z.literal("wechat-devtools-project-snapshot-v1"),
+	sourceProjectPath: z.string().min(1),
+	token: z.string().uuid(),
+	state: z.enum([
+		"reserved",
+		"ready",
+		"removed"
+	]),
+	directoryIdentity: z.object({
+		dev: z.string().min(1),
+		ino: z.string().min(1)
+	}).strict().optional(),
+	dispatchedAt: z.string().datetime().optional(),
+	cleanupStartedAt: z.string().datetime().optional(),
+	removedAt: z.string().datetime().optional(),
+	cleanupError: z.string().optional()
+}).strict();
+//#endregion
 //#region src/devtoolsProjectOwnership/windowClose/schema.ts
 const text = z.string().min(1);
 const cursorSchema = z.object({
@@ -603,8 +754,10 @@ const recordSchema = z.object({
 	releasedReason: z.enum([
 		"borrowed",
 		"project-closed",
-		"installation-exited"
+		"installation-exited",
+		"not-started"
 	]).optional(),
+	snapshot: managedSnapshotSchema.optional(),
 	installationExitRecovery: installationExitRecoverySchema.optional(),
 	error: z.string().optional()
 }).refine((record) => record.releasedReason === "installation-exited" ? record.state === "released" && record.installationExitRecovery !== void 0 : record.installationExitRecovery === void 0, { message: "Installation exit recovery requires its distinct release reason and forensic evidence." });
@@ -619,7 +772,7 @@ async function readManagedRecord(journalPath, id) {
 	const file = managedRecordPath(journalPath, id);
 	if (!(await fs.lstat(file)).isFile()) throw new Error("Managed DevTools journal record is not a regular file.");
 	const record = recordSchema.parse(JSON.parse(await fs.readFile(file, "utf8")));
-	if (record.id !== id || record.journalPath !== journalPath || !path.isAbsolute(record.projectPath)) throw new Error("Managed DevTools journal identity does not match its task directory.");
+	if (record.id !== id || record.journalPath !== journalPath || !path.isAbsolute(record.projectPath) || record.snapshot && (record.projectPath !== path.join(journalPath, "snapshots", id) || !path.isAbsolute(record.snapshot.sourceProjectPath) || record.snapshot.sourceProjectPath === record.projectPath)) throw new Error("Managed DevTools journal identity does not match its task directory.");
 	return record;
 }
 async function writeManagedRecord(record) {
@@ -738,6 +891,110 @@ async function withManagedJournalLock(directory, run) {
 	});
 }
 //#endregion
+//#region src/devtoolsProjectOwnership/snapshot/index.ts
+const MARKER = ".weapp-ide-snapshot-owner";
+function managedSnapshotPath(journalPath, id) {
+	return path.join(journalPath, "snapshots", id);
+}
+/** 窗口已经释放不代表本任务快照也已回收。 */
+function isManagedWechatProjectFullyReleased(record) {
+	return record.state === "released" && (!record.snapshot || record.snapshot.state === "removed");
+}
+function markerValue(record) {
+	return JSON.stringify({
+		protocol: record.snapshot.protocol,
+		journalPath: record.journalPath,
+		id: record.id,
+		generation: record.generation,
+		ownerToken: record.ownerToken,
+		token: record.snapshot.token,
+		sourceProjectPath: record.snapshot.sourceProjectPath,
+		projectPath: record.projectPath,
+		target: record.target
+	});
+}
+async function directoryStat(directory) {
+	const stat = await fs.lstat(directory, { bigint: true });
+	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Managed DevTools snapshot directory identity changed; refusing filesystem cleanup.");
+	return {
+		dev: String(stat.dev),
+		ino: String(stat.ino)
+	};
+}
+function assertPath(record) {
+	if (!record.snapshot || record.projectPath !== managedSnapshotPath(record.journalPath, record.id) || !path.isAbsolute(record.snapshot.sourceProjectPath) || record.snapshot.sourceProjectPath === record.projectPath) throw new Error("Managed DevTools snapshot is not bound to its exact task journal.");
+}
+async function verifySnapshot(record, allowIncompleteCreation = false) {
+	assertPath(record);
+	const snapshot = record.snapshot;
+	await directoryStat(record.journalPath);
+	await directoryStat(path.dirname(record.projectPath));
+	const actual = await directoryStat(record.projectPath);
+	if (await fs.realpath(record.projectPath) !== path.join(await fs.realpath(record.journalPath), "snapshots", record.id)) throw new Error("Managed DevTools snapshot escaped its canonical task journal.");
+	if (!snapshot.directoryIdentity || actual.dev !== snapshot.directoryIdentity.dev || actual.ino !== snapshot.directoryIdentity.ino) throw new Error("Managed DevTools snapshot directory was replaced; refusing cleanup.");
+	const marker = path.join(record.projectPath, MARKER);
+	try {
+		const stat = await fs.lstat(marker);
+		if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || await fs.readFile(marker, "utf8") !== markerValue(record)) throw new Error("Managed DevTools snapshot creation marker changed; refusing cleanup.");
+	} catch (error) {
+		if (error.code !== "ENOENT" || !snapshot.cleanupStartedAt && !(allowIncompleteCreation && snapshot.state === "reserved" && !snapshot.dispatchedAt)) throw error;
+	}
+}
+/** 调用方持有 journal 根锁；先登记预算，再独占创建本次 generation 的快照。 */
+async function prepareManagedProjectSnapshot(record, populate) {
+	assertPath(record);
+	const snapshot = record.snapshot;
+	if (record.state !== "starting" || snapshot.state !== "reserved" || snapshot.directoryIdentity || snapshot.dispatchedAt) throw new Error("Managed DevTools snapshot preparation requires its unused project reservation.");
+	await directoryStat(record.journalPath);
+	const parent = path.dirname(record.projectPath);
+	await fs.mkdir(parent, { mode: 448 }).catch((error) => {
+		if (error.code !== "EEXIST") throw error;
+	});
+	await directoryStat(parent);
+	await fs.mkdir(record.projectPath, { mode: 448 });
+	snapshot.directoryIdentity = await directoryStat(record.projectPath);
+	await writeManagedRecord(record);
+	await fs.writeFile(path.join(record.projectPath, MARKER), markerValue(record), {
+		encoding: "utf8",
+		mode: 384,
+		flag: "wx"
+	});
+	await populate(record.projectPath);
+	await verifySnapshot(record);
+	snapshot.state = "ready";
+	await writeManagedRecord(record);
+}
+/** 窗口与端口证据由原有 owner 协议提供；这里仅回收匹配 provenance 的快照。 */
+async function finalizeManagedProjectSnapshot(record) {
+	if (!record.snapshot || record.snapshot.state === "removed") return;
+	const snapshot = record.snapshot;
+	try {
+		assertPath(record);
+		if (record.state !== "released" || ![
+			"project-closed",
+			"installation-exited",
+			"not-started"
+		].includes(record.releasedReason ?? "") || record.releasedReason === "not-started" && (snapshot.dispatchedAt || record.openedProjectWindow !== void 0)) throw new Error("Managed DevTools snapshot is still used by an unresolved project; preserving its files.");
+		if (await fs.lstat(record.projectPath).then(() => true).catch((error) => {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		})) {
+			await verifySnapshot(record, true);
+			snapshot.cleanupStartedAt ??= (/* @__PURE__ */ new Date()).toISOString();
+			await writeManagedRecord(record);
+			await fs.rm(record.projectPath, { recursive: true });
+		}
+		snapshot.state = "removed";
+		snapshot.removedAt = (/* @__PURE__ */ new Date()).toISOString();
+		delete snapshot.cleanupError;
+		await writeManagedRecord(record);
+	} catch (error) {
+		snapshot.cleanupError = error instanceof Error ? error.message : String(error);
+		await writeManagedRecord(record);
+		throw error;
+	}
+}
+//#endregion
 //#region src/devtoolsProjectOwnership/windowBudget.ts
 function maximumOwnedWindows(options) {
 	const selected = options.maxOwnedWindows ?? process.env["WEAPP_IDE_MANAGED_PROJECT_MAX_WINDOWS"] ?? 1;
@@ -751,7 +1008,7 @@ function sameTarget(first, second) {
 function checkManagedWindowBudget(records, options) {
 	const maximum = maximumOwnedWindows(options);
 	const projectPath = path.resolve(options.projectPath);
-	if (records.some((record) => record.state !== "released" && record.projectPath === projectPath && sameTarget(record.target, options.target))) throw new Error("Managed DevTools project already has an active session; use its existing endpoint in connect-only mode instead of starting it again.");
+	if (records.some((record) => !isManagedWechatProjectFullyReleased(record) && (record.projectPath === projectPath || record.snapshot?.sourceProjectPath === projectPath) && sameTarget(record.target, options.target))) throw new Error("Managed DevTools project already has an active session; use its existing endpoint in connect-only mode instead of starting it again.");
 	const owned = records.filter((record) => record.state === "owned").length;
 	if (owned >= maximum) throw new Error(`Managed DevTools window budget exhausted (${owned}/${maximum}); close the previous owned project before another start.`);
 }
@@ -1331,28 +1588,28 @@ const options = {
 	reject: false,
 	env: { LC_ALL: "C" }
 };
-const pathSchema = z.array(z.object({
-	pid: z.number().int().positive(),
-	executable: z.string().nullable()
-}).strict());
-const kernelPathsScript = `
-ObjC.import('Foundation');
-ObjC.bindFunction('malloc', ['void *', ['unsigned long']]);
-ObjC.bindFunction('free', ['void', ['void *']]);
-ObjC.bindFunction('proc_pidpath', ['int', ['int', 'void *', 'uint32_t']]);
-ObjC.bindFunction('strchr', ['char *', ['void *', 'int']]);
-function run(argv) {
-  var pids = JSON.parse(argv[0]);
-  var buffer = $.malloc(4096);
-  if (!buffer) throw new Error('Cannot allocate process path buffer.');
-  try {
-    return JSON.stringify(pids.map(function(pid) {
-      var count = $.proc_pidpath(pid, buffer, 4096);
-      return { pid: pid, executable: count > 0 ? $.strchr(buffer, 47) : null };
-    }));
-  } finally { $.free(buffer); }
+const textImageDecoder = new TextDecoder("utf-8", { fatal: true });
+/** 按本机 LC_ALL=C 的 lsof 表示还原字节；有歧义的控制表示不能用于负归属判断。 */
+function decodeTextImagePath(wire) {
+	if (!wire.startsWith("/") || /[^\u0020-\u007E]|\^[A-GKN-Z[\]\\^_]/.test(wire)) throw new Error("Installation-exit recovery received an unverifiable executable image path.");
+	if (!wire.includes("\\")) return wire;
+	const bytes = Buffer.allocUnsafe(wire.length);
+	let length = 0;
+	for (let index = 0; index < wire.length; index++) {
+		let byte = wire.charCodeAt(index);
+		if (wire[index] === "\\") {
+			const escape = wire[++index];
+			if (escape === "\\") byte = 92;
+			else if (escape === "x" && /^[\da-f]{2}$/.test(wire.slice(index + 1, index + 3))) {
+				byte = Number.parseInt(wire.slice(index + 1, index + 3), 16);
+				index += 2;
+				if (byte < 128) throw new Error("Installation-exit recovery received an unverifiable executable image path.");
+			} else throw new Error("Installation-exit recovery received an unverifiable executable image path.");
+		}
+		bytes[length++] = byte;
+	}
+	return textImageDecoder.decode(bytes.subarray(0, length));
 }
-`;
 /** ps 仅用于 PID、启动时间和僵尸状态，不能用可修改的 comm 代替实际可执行文件。 */
 async function readDarwinProcessStates() {
 	const inspection = execa("/bin/ps", ["-axo", "pid=,stat=,lstart="], options);
@@ -1372,28 +1629,9 @@ async function readDarwinProcessStates() {
 	if (new Set(records.map((record) => record.pid)).size !== records.length) throw new Error("Installation-exit recovery found duplicate process identities.");
 	return records.filter((record) => record.pid !== inspectorPid);
 }
-/** 系统 JXA/libproc 不可用时明确拒绝恢复，不安装工具或以进程标题降级。 */
-async function readDarwinKernelPaths(pids) {
-	const result = await execa("/usr/bin/osascript", [
-		"-l",
-		"JavaScript",
-		"-e",
-		kernelPathsScript,
-		JSON.stringify(pids)
-	], options);
-	if (result.exitCode !== 0 || result.stderr?.trim()) throw new Error("Installation-exit recovery cannot inspect kernel executable paths.");
-	let parsed;
-	try {
-		parsed = pathSchema.parse(JSON.parse(result.stdout));
-	} catch {
-		throw new Error("Installation-exit recovery received incomplete kernel executable paths.");
-	}
-	const entries = new Map(parsed.map((entry) => [entry.pid, entry.executable]));
-	if (entries.size !== pids.length || parsed.length !== pids.length || pids.some((pid) => !entries.has(pid))) throw new Error("Installation-exit recovery received incomplete kernel process identities.");
-	return entries;
-}
 /** 已删除可执行文件无法经 proc_pidpath 读取时，核验全部 program-text 映像而非猜测首项。 */
-async function readDarwinTextImages(pid) {
+async function readDarwinTextImages(pid, timeoutMs = options.timeout) {
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error("Installation-exit recovery cannot inspect executable text images without a positive timeout.");
 	const result = await execa("/usr/sbin/lsof", [
 		"-nP",
 		"-a",
@@ -1402,29 +1640,25 @@ async function readDarwinTextImages(pid) {
 		"-d",
 		"txt",
 		"-F0pftn"
-	], options);
-	if (result.exitCode !== 0 || result.stderr?.trim()) throw new Error("Installation-exit recovery cannot inspect all executable text images.");
-	const fields = result.stdout.split("\0").map((field) => field.replace(/^\r?\n/, "")).filter(Boolean);
-	if (fields.shift() !== `p${pid}` || fields.length === 0 || fields.length % 3 !== 0) throw new Error("Installation-exit recovery received incomplete executable text images.");
+	], {
+		...options,
+		timeout: Math.min(options.timeout, timeoutMs)
+	});
+	if (result.exitCode !== 0 || result.timedOut || result.signal || result.stderr?.trim()) throw new Error(`Installation-exit recovery cannot inspect all executable text images for PID ${pid}.`, { cause: {
+		exitCode: result.exitCode,
+		stderr: result.stderr?.trim()
+	} });
+	const fields = result.stdout.split("\0").map((field) => field.replace(/^\r?\n/, ""));
+	if (fields.pop() !== "" || fields.shift() !== `p${pid}` || fields.length === 0 || fields.length % 3 !== 0) throw new Error("Installation-exit recovery received incomplete executable text images.");
 	const paths = [];
 	for (let index = 0; index < fields.length; index += 3) {
 		if (fields[index] !== "ftxt" || fields[index + 1] !== "tREG" || !fields[index + 2]?.startsWith("n")) throw new Error("Installation-exit recovery received unverifiable executable text images.");
-		paths.push(fields[index + 2].slice(1));
+		paths.push(decodeTextImagePath(fields[index + 2].slice(1)));
 	}
 	return paths;
 }
 //#endregion
 //#region src/devtoolsProjectOwnership/installationExit/processes.ts
-/** 已删除映像仍有内核 vnode 路径；从现存祖先解析符号链接，不把缺失文件当成已退出进程。 */
-async function canonicalImagePath(file) {
-	if (!path.isAbsolute(file) || /[\r\n\0]/.test(file)) throw new Error("Installation-exit recovery received an unverifiable executable image path.");
-	try {
-		return await fs.realpath(file);
-	} catch (error) {
-		if (error.code !== "ENOENT" || path.dirname(file) === file) throw new Error("Installation-exit recovery cannot resolve an executable image path.", { cause: error });
-		return path.join(await canonicalImagePath(path.dirname(file)), path.basename(file));
-	}
-}
 /** 仅支持已验证的 macOS 全安装清单；未知平台、权限错误或不完整映像均拒绝推断退出。 */
 async function inspectExitedWechatInstallation(target, platform = process.platform) {
 	if (platform !== "darwin") throw new Error("Installation-exit recovery requires the verified macOS process inventory.");
@@ -1453,11 +1687,24 @@ async function inspectExitedWechatInstallation(target, platform = process.platfo
 				continue;
 			}
 			const executable = kernelPaths.get(entry.pid);
-			const images = executable ? [executable] : await readDarwinTextImages(entry.pid);
+			let images;
+			try {
+				images = executable ? [executable] : await readDarwinTextImages(entry.pid);
+			} catch (error) {
+				const latest = await readDarwinProcessStates().then((states) => states.find((process) => process.pid === entry.pid), (confirmationError) => {
+					throw new AggregateError([error, confirmationError], "Installation-exit recovery cannot independently confirm process exit after failed image inspection.");
+				});
+				if (!latest) {
+					exitedProcessCount++;
+					continue;
+				}
+				if (latest.started !== entry.started) throw new Error("Installation-exit recovery process identity changed during inspection.", { cause: error });
+				throw error;
+			}
 			if (!images.length) throw new Error("Installation-exit recovery received no verifiable executable text images.");
 			for (const image of images) {
-				const resolved = await canonicalImagePath(image);
-				const relative = path.relative(installationRoot, resolved);
+				if (!path.isAbsolute(image) || /[\r\n\0]/.test(image)) throw new Error("Installation-exit recovery received an unverifiable executable image path.");
+				const relative = path.relative(installationRoot, image);
 				if (!relative || !path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`)) throw new Error("The selected WeChat DevTools installation still has a live process; no ownership was recovered.");
 			}
 			if (executable) kernelPathProcessCount++;
@@ -1497,7 +1744,7 @@ async function fingerprint(record) {
 	return createHash("sha256").update(await fs.readFile(file)).digest("hex");
 }
 function canRecoverAfterExit(record) {
-	return record.state === "starting" || record.state === "unconfirmed" || record.state === "failed" && record.openedProjectWindow === true && record.host !== void 0 && record.port !== void 0 && record.error !== void 0;
+	return record.state === "starting" || record.state === "unconfirmed" || record.state === "borrowed" && record.snapshot !== void 0 && record.openedProjectWindow === false || record.state === "failed" && record.openedProjectWindow === true && record.host !== void 0 && record.port !== void 0 && record.error !== void 0;
 }
 async function recoverAfterExit(options) {
 	const { target, recoveryScope } = options;
@@ -1512,9 +1759,12 @@ async function recoverAfterExit(options) {
 		if (new Set(records.map((record) => record.id)).size !== records.length) throw new Error("Installation-exit recovery found duplicate record identities.");
 		if (records.some((record) => !isDeepStrictEqual(record.target, target))) throw new Error("Installation-exit recovery cannot include another installation or profile.");
 		if (records.some((record) => record.state !== "released" && !canRecoverAfterExit(record))) throw new Error("Installation-exit recovery refuses confirmed or unresolved project-close ownership.");
-		const candidates = (await readManagedWechatProjectRecords(journalPath)).filter(canRecoverAfterExit);
+		const scopeRecords = await readManagedWechatProjectRecords(journalPath);
+		const candidates = scopeRecords.filter(canRecoverAfterExit);
+		const pendingSnapshots = scopeRecords.filter((record) => record.state === "released" && !isManagedWechatProjectFullyReleased(record));
 		if (!candidates.length) {
 			await assertMachineE2ELeaseRecoveryScope(recoveryScope);
+			for (const record of pendingSnapshots) await finalizeManagedProjectSnapshot(record);
 			return { recoveredRecordIds: [] };
 		}
 		const before = new Map(await Promise.all(records.map(async (record) => [record.id, await fingerprint(record)])));
@@ -1544,7 +1794,7 @@ async function recoverAfterExit(options) {
 			await assertMachineE2ELeaseRecoveryScope(recoveryScope);
 			if (await fingerprint(record) !== before.get(record.id)) throw new Error("Installation-exit recovery journal bytes changed before recording recovery.");
 			const previousState = record.state;
-			if (previousState !== "starting" && previousState !== "unconfirmed" && previousState !== "failed") throw new Error("Installation-exit recovery cannot replace a confirmed ownership state.");
+			if (previousState !== "starting" && previousState !== "unconfirmed" && previousState !== "failed" && previousState !== "borrowed") throw new Error("Installation-exit recovery cannot replace a confirmed ownership state.");
 			record.installationExitRecovery = {
 				protocol: "wechat-devtools-installation-exit-v1",
 				recoveredAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1566,8 +1816,10 @@ async function recoverAfterExit(options) {
 			record.state = "released";
 			record.releasedReason = "installation-exited";
 			await writeManagedRecord(record);
+			await finalizeManagedProjectSnapshot(record);
 			recoveredRecordIds.push(record.id);
 		}
+		for (const record of pendingSnapshots) await finalizeManagedProjectSnapshot(record);
 		return { recoveredRecordIds };
 	});
 }
@@ -1587,7 +1839,7 @@ async function release(record, reason) {
 	delete record.error;
 	await writeManagedRecord(record);
 }
-async function closeRecord(record) {
+async function closeWindowRecord(record) {
 	if (record.state === "released") return;
 	if (record.state === "borrowed" && record.openedProjectWindow === false) {
 		await release(record, "borrowed");
@@ -1631,6 +1883,17 @@ async function closeRecord(record) {
 		throw error;
 	}
 }
+async function closeRecord(record) {
+	if (isManagedWechatProjectFullyReleased(record)) return;
+	if (record.state !== "released") {
+		if (record.snapshot && !record.snapshot.dispatchedAt && record.openedProjectWindow === void 0) await release(record, "not-started");
+		else {
+			if (record.snapshot && record.openedProjectWindow === false) throw new Error("Managed DevTools snapshot received a borrowed window receipt; preserving files until installation exit is proven.");
+			await closeWindowRecord(record);
+		}
+	}
+	await finalizeManagedProjectSnapshot(record);
+}
 /** 窗口销毁与连接断开分别验证；失败保留登记供后续继续观察。 */
 function closeManagedWechatProject(options) {
 	const journalPath = resolveManagedJournal(options.journalPath);
@@ -1648,6 +1911,7 @@ async function beginManagedWechatProject(options) {
 	const journalPath = resolveManagedJournal(options.journalPath);
 	if (!journalPath) return;
 	const id = randomUUID();
+	const projectPath = options.snapshotProject ? managedSnapshotPath(journalPath, id) : path.resolve(options.projectPath);
 	await withManagedJournalLock(journalPath, async (scopeRoot) => {
 		const previous = await readManagedWechatProjectRecords(scopeRoot);
 		if (previous.some((record) => [
@@ -1655,7 +1919,7 @@ async function beginManagedWechatProject(options) {
 			"unconfirmed",
 			"closing",
 			"failed"
-		].includes(record.state))) throw new Error("Managed DevTools journal contains unresolved ownership or cleanup; refusing another project start.");
+		].includes(record.state) || record.state === "released" && !isManagedWechatProjectFullyReleased(record) || record.state === "borrowed" && record.snapshot?.state !== void 0 && record.snapshot.state !== "removed")) throw new Error("Managed DevTools journal contains unresolved ownership or cleanup; refusing another project start.");
 		checkManagedWindowBudget(previous, options);
 		const now = (/* @__PURE__ */ new Date()).toISOString();
 		await writeManagedRecord({
@@ -1666,7 +1930,13 @@ async function beginManagedWechatProject(options) {
 			ownerToken: managedProcessToken,
 			ownerPid: process.pid,
 			target: { ...options.target },
-			projectPath: path.resolve(options.projectPath),
+			projectPath,
+			...options.snapshotProject ? { snapshot: {
+				protocol: "wechat-devtools-project-snapshot-v1",
+				sourceProjectPath: path.resolve(options.projectPath),
+				token: randomUUID(),
+				state: "reserved"
+			} } : {},
 			state: "starting",
 			port: options.port,
 			createdAt: now,
@@ -1676,10 +1946,36 @@ async function beginManagedWechatProject(options) {
 	return {
 		id,
 		journalPath,
+		projectPath,
+		prepareSnapshot: async (populate) => {
+			await withManagedJournalLock(journalPath, async () => {
+				const record = await readManagedRecord(journalPath, id);
+				try {
+					await prepareManagedProjectSnapshot(record, populate);
+				} catch (error) {
+					if (record.snapshot) {
+						record.snapshot.cleanupError = describe(error);
+						await writeManagedRecord(record);
+					}
+					throw error;
+				}
+			});
+		},
+		markLaunchDispatched: async () => {
+			await withManagedJournalLock(journalPath, async () => {
+				const record = await readManagedRecord(journalPath, id);
+				if (record.snapshot) {
+					if (record.state !== "starting" || record.snapshot.state !== "ready" || record.snapshot.dispatchedAt) throw new Error("Managed DevTools snapshot is not ready for its first start dispatch.");
+					record.snapshot.dispatchedAt = (/* @__PURE__ */ new Date()).toISOString();
+					await writeManagedRecord(record);
+				}
+			});
+		},
 		confirm: async (result) => {
 			await withManagedJournalLock(journalPath, async () => {
 				const record = await readManagedRecord(journalPath, id);
 				if (record.state !== "starting" && record.state !== "unconfirmed") throw new Error("Managed DevTools start receipt was already recorded.");
+				if (record.snapshot && (!record.snapshot.dispatchedAt || record.snapshot.state !== "ready")) throw new Error("Managed DevTools snapshot start receipt has no prepared dispatch intent.");
 				if (typeof result.openedProjectWindow !== "boolean" || !Number.isInteger(result.port) || result.port <= 0 || result.port > 65535 || record.port !== void 0 && record.port !== result.port) throw new Error("Managed DevTools start receipt does not match its requested port.");
 				record.openedProjectWindow = result.openedProjectWindow;
 				record.port = result.port;
@@ -1723,4 +2019,4 @@ async function cleanupManagedWechatProjects(options = {}) {
 	if (errors.length) throw new AggregateError(errors, "Managed DevTools project cleanup remains incomplete; stop the acceptance lane.");
 }
 //#endregion
-export { readManagedRecord as a, withManagedJournalLock as c, MANAGED_PROJECT_MAX_WINDOWS_ENV as d, assertManagedInstallation as f, startWechatIdeAgent as h, recoverManagedWechatProjectsAfterInstallationExit as i, writeManagedRecord as l, sameManagedProcess as m, cleanupManagedWechatProjects as n, readManagedWechatProjectRecords as o, inspectManagedProjectHost as p, closeManagedWechatProject as r, resolveManagedJournal as s, beginManagedWechatProject as t, MANAGED_PROJECT_JOURNAL_ENV as u };
+export { isManagedWechatProjectFullyReleased as a, resolveManagedJournal as c, assertManagedInstallation as d, inspectManagedProjectHost as f, recoverManagedWechatProjectsAfterInstallationExit as i, withManagedJournalLock as l, startWechatIdeAgent as m, cleanupManagedWechatProjects as n, readManagedRecord as o, sameManagedProcess as p, closeManagedWechatProject as r, readManagedWechatProjectRecords as s, beginManagedWechatProject as t, writeManagedRecord as u };