weapp-ide-cli 6.2.0 → 6.4.0

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

@@ -1,17 +1,17 @@
-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-DPU-pEF0.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";
-//#region src/cli/agentStart.ts
+import { performance as performance$1 } from "node:perf_hooks";
+// src/cli/agentStart.ts
 /** 提取独立的完整 JSON 对象，普通日志和嵌套对象不能替代命令响应。 */
 function readResponseObjects(stdout) {
 	const objects = [];
@@ -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,
@@ -113,35 +116,179 @@ async function startWechatIdeAgent(options) {
 		}
 	});
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/host.ts
-const inspectionOptions$1 = {
+// 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;
+}
+// src/devtoolsProjectOwnership/darwinProcessIdentity.ts
+const inspectionTimeoutMs = 3e3;
+function invalidIdentity$2(stage, reason, details = {}, cause) {
+	return new Error(`Managed DevTools process identity could not be verified; no project was closed. ${JSON.stringify({
+		stage,
+		reason,
+		...details
+	})}`, { cause });
+}
+async function readStarted(pids, remaining, stage) {
+	const result = await execa("/bin/ps", [
+		"-p",
+		pids.join(","),
+		"-o",
+		"pid=,stat=,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(stage, "birth-query-failed", { requestedCount: pids.length });
+	const started = /* @__PURE__ */ new Map();
+	for (const line of result.stdout.split(/\r?\n/).filter((line) => line.trim())) {
+		const match = /^\s*(\d+)\s+(\S+)\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(stage, "invalid-birth-inventory", { requestedCount: pids.length });
+		started.set(pid, {
+			started: match[3].replace(/\s+/g, " "),
+			zombie: match[2].startsWith("Z")
+		});
+	}
+	return started;
+}
+/** 批量读取内核路径，并以前后启动时间绑定 PID；进程标题变化不改变身份。 */
+async function readDarwinManagedProcessIdentities(pids) {
+	if (pids.some((pid) => !Number.isSafeInteger(pid) || pid <= 0)) throw invalidIdentity$2("request", "invalid-pid");
+	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;
+	let stage = "before";
+	const remaining = () => {
+		const timeout = Math.floor(deadline - performance.now());
+		if (timeout <= 0) throw invalidIdentity$2(stage, "deadline-exceeded", { requestedCount: requested.length });
+		return timeout;
+	};
+	const before = await readStarted(requested, remaining, "before");
+	if (!before.size) return identities;
+	stage = "kernel";
+	const paths = await readDarwinKernelPaths([...before.keys()], remaining()).catch((cause) => {
+		throw invalidIdentity$2("kernel", "kernel-query-failed", { requestedCount: before.size }, cause);
+	});
+	stage = "after";
+	const after = await readStarted(requested, remaining, "after");
+	for (const pid of requested) {
+		const current = after.get(pid);
+		if (!current) continue;
+		const executable = paths.get(pid);
+		const previous = before.get(pid);
+		if (previous?.started !== current.started) throw invalidIdentity$2("after", "birth-changed", {
+			pid,
+			beforePresent: before.has(pid),
+			afterPresent: true
+		});
+		if (previous.zombie && current.zombie) continue;
+		if (previous.zombie !== current.zombie) throw invalidIdentity$2("after", "terminal-state-changed", {
+			pid,
+			beforeZombie: previous.zombie,
+			afterZombie: current.zombie
+		});
+		if (!executable?.startsWith("/")) throw invalidIdentity$2("after", "kernel-path-unavailable", {
+			pid,
+			beforePresent: true,
+			afterPresent: true,
+			kernelPath: executable ? "non-absolute" : "empty"
+		});
+		identities.set(pid, {
+			pid,
+			started: current.started,
+			executable
+		});
+	}
+	stage = "complete";
+	remaining();
+	return identities;
+}
+// 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 +298,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 +320,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 +335,20 @@ async function readManagedProcessIdentity(pid, platform = process.platform) {
 function sameManagedProcess(first, second) {
 	return first.pid === second.pid && first.started === second.started && first.executable === second.executable;
 }
+// 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 +376,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) {
@@ -241,8 +403,7 @@ async function waitForManagedPortClosed(port, timeoutMs = 1e4) {
 	} while (Date.now() < deadline);
 	throw new Error("Managed DevTools project close returned but its automator port remained open.");
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/installationExit/schema.ts
+// src/devtoolsProjectOwnership/installationExit/schema.ts
 const installationExitRecoverySchema = z.object({
 	protocol: z.literal("wechat-devtools-installation-exit-v1"),
 	recoveredAt: z.string().datetime(),
@@ -255,7 +416,8 @@ const installationExitRecoverySchema = z.object({
 		state: z.enum([
 			"starting",
 			"unconfirmed",
-			"failed"
+			"failed",
+			"borrowed"
 		]),
 		error: z.string().optional(),
 		updatedAt: z.string().min(1),
@@ -275,14 +437,7 @@ const installationExitRecoverySchema = z.object({
 		selectedProcessCount: z.literal(0)
 	}).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
+// src/devtoolsProjectOwnership/journal/scope.ts
 const markerName = ".ownership-scope";
 const scopeSchema = z.object({
 	schemaVersion: z.literal(1),
@@ -335,8 +490,7 @@ async function resolveManagedJournalScope(directory) {
 	if (path.resolve(rootPath, relative) !== currentPath) throw new Error("Managed DevTools journal path changed from its registered task children.");
 	return scope;
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/journal/windowsSelfIdentity/wire.ts
+// src/devtoolsProjectOwnership/journal/windowsSelfIdentity/wire.ts
 const SELF_IDENTITY_WIRE = "WEAPP_JOURNAL_SELF_V1";
 const epochTicks = 621355968000000000n;
 const maximumTicks = 3155378975999999999n;
@@ -370,8 +524,7 @@ function parseWindowsSelfIdentity(stdout, expectedPid) {
 		started
 	};
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/journal/windowsSelfIdentity/command.ts
+// src/devtoolsProjectOwnership/journal/windowsSelfIdentity/command.ts
 /** 当前 writer 的 PID 由 Node 进程提供；脚本只读查询，不执行任何进程或 IDE 清理。 */
 function windowsSelfIdentityCommand(pid) {
 	if (!Number.isSafeInteger(pid) || pid <= 0) throw new TypeError("A positive writer PID is required.");
@@ -411,8 +564,7 @@ finally {
 exit $writerExitCode
 `;
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/journal/windowsSelfIdentity/trace.ts
+// src/devtoolsProjectOwnership/journal/windowsSelfIdentity/trace.ts
 const marker = `${SELF_IDENTITY_WIRE}:phase:`;
 const statements = /* @__PURE__ */ new Map([
 	["$writerFirst=[System.Diagnostics.Process]", "lookup-before"],
@@ -459,15 +611,14 @@ function observeWindowsSelfIdentityPhases(report) {
 function stripWindowsSelfIdentityPhases(stderr) {
 	return stderr.replace(phaseLines, "");
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/journal/windowsSelfIdentity/index.ts
+// src/devtoolsProjectOwnership/journal/windowsSelfIdentity/index.ts
 const debug = debuglog("weapp-ide-journal-writer");
 /** 仅核验当前 Node 写入进程；不能用于任意宿主、旧锁存活判断或进程清理。 */
 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,22 +632,21 @@ 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}.`);
 	}
 	return parseWindowsSelfIdentity(result.stdout, process.pid);
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/journal/writerIdentity.ts
+// src/devtoolsProjectOwnership/journal/writerIdentity.ts
 let currentIdentity$1;
 /** 共享在途与成功身份；失败仍拒绝当前调用，仅允许下一次显式操作重新核验。 */
 function readManagedJournalWriterIdentity() {
@@ -512,8 +662,26 @@ function readManagedJournalWriterIdentity() {
 	}
 	return currentIdentity$1;
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/windowClose/schema.ts
+// 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();
+// src/devtoolsProjectOwnership/windowClose/schema.ts
 const text = z.string().min(1);
 const cursorSchema = z.object({
 	name: z.string().regex(/^[^/\\]+\.log$/),
@@ -554,8 +722,7 @@ const managedWindowCloseSchema = z.object({
 		cursors: z.array(cursorSchema).min(1)
 	}).optional()
 });
-//#endregion
-//#region src/devtoolsProjectOwnership/journal.ts
+// src/devtoolsProjectOwnership/journal.ts
 const managedProcessToken = randomUUID();
 const idSchema = z.string().uuid();
 const hostSchema = z.object({
@@ -603,8 +770,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 +788,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) {
@@ -637,16 +806,15 @@ async function writeManagedRecord(record) {
 		await fs.rm(temporary, { force: true });
 	}
 }
-/** 仅递归当前任务明确传递的 children；不扫描用户缓存，不跟随符号链接。 */
-async function readManagedWechatProjectRecords(journalPath) {
-	const directory = resolveManagedJournal(journalPath);
-	if (!directory) return [];
+async function readManagedJournalDirectory(directory, parentScope) {
+	if (parentScope && !(await fs.lstat(directory)).isDirectory()) throw new Error("Managed DevTools journal scope must use regular directories.");
 	const entries = await fs.readdir(directory, { withFileTypes: true }).catch((error) => {
-		if (error.code === "ENOENT") return;
+		if (error.code === "ENOENT" && !parentScope) return;
 		throw error;
 	});
 	if (!entries) return [];
 	const scope = await resolveManagedJournalScope(directory);
+	if (parentScope && (parentScope.scopeId !== void 0 || scope.scopeId !== void 0) && (parentScope.scopeId !== scope.scopeId || parentScope.rootPath !== scope.rootPath)) throw new Error("Managed DevTools journal scope changed inside its registered children; refusing another task tree.");
 	const records = [];
 	for (const entry of entries) if (entry.name.endsWith(".json")) records.push(await readManagedRecord(directory, entry.name.slice(0, -5)));
 	else if (entry.name === "children") {
@@ -655,13 +823,17 @@ async function readManagedWechatProjectRecords(journalPath) {
 		for (const child of children) {
 			if (!child.isDirectory()) throw new Error("Managed DevTools child journal is not a regular directory.");
 			const childPath = path.join(directory, "children", child.name);
-			const childScope = await resolveManagedJournalScope(childPath);
-			if ((scope.scopeId !== void 0 || childScope.scopeId !== void 0) && (scope.scopeId !== childScope.scopeId || scope.rootPath !== childScope.rootPath)) throw new Error("Managed DevTools journal scope changed inside its registered children; refusing another task tree.");
-			records.push(...await readManagedWechatProjectRecords(childPath));
+			records.push(...await readManagedJournalDirectory(childPath, scope));
 		}
 	}
 	return records;
 }
+/** 仅递归当前任务明确传递的 children；不扫描用户缓存，不跟随符号链接。 */
+async function readManagedWechatProjectRecords(journalPath) {
+	const directory = resolveManagedJournal(journalPath);
+	if (!directory) return [];
+	return await readManagedJournalDirectory(directory);
+}
 const lockOwnerSchema = z.object({
 	token: idSchema,
 	identity: hostSchema
@@ -737,8 +909,110 @@ async function withManagedJournalLock(directory, run) {
 		return await run(scope.rootPath);
 	});
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/windowBudget.ts
+// 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;
+	}
+}
+// src/devtoolsProjectOwnership/windowBudget.ts
 function maximumOwnedWindows(options) {
 	const selected = options.maxOwnedWindows ?? process.env["WEAPP_IDE_MANAGED_PROJECT_MAX_WINDOWS"] ?? 1;
 	if (selected !== 1 && selected !== 2 && selected !== "1" && selected !== "2") throw new Error("Managed DevTools maximum owned windows must be 1 or 2.");
@@ -751,12 +1025,11 @@ 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.`);
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/windowClose/logCursor.ts
+// src/devtoolsProjectOwnership/windowClose/logCursor.ts
 const readLimit = 2097152;
 const scanLimit = 33554432;
 const scanChunkSize = 65536;
@@ -960,8 +1233,7 @@ async function consumeFreshLogLines(directory, cursors, consume) {
 		await Promise.all(streams.map(({ file }) => file.close()));
 	}
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/windowClose/activeLog.ts
+// src/devtoolsProjectOwnership/windowClose/activeLog.ts
 const inspectionOptions = {
 	timeout: 3e3,
 	reject: false,
@@ -1120,8 +1392,7 @@ async function captureActiveMainLogCursors(record, directory, platform = process
 		host: main
 	};
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/windowClose/protocol.ts
+// src/devtoolsProjectOwnership/windowClose/protocol.ts
 function decodeString(value) {
 	const quote = value[0];
 	if (!quote || ![
@@ -1262,8 +1533,7 @@ function consumeWindowCloseTrace(evidence, projectPath, input) {
 		}
 	}
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/windowClose.ts
+// src/devtoolsProjectOwnership/windowClose.ts
 /** 只捕获本次显式安装的日志，必须先于关闭命令持久化。 */
 async function captureManagedWindowClose(record) {
 	if (!record.target.version) throw new Error("Managed DevTools window-close evidence requires the selected product version.");
@@ -1324,41 +1594,44 @@ async function waitForManagedWindowClosed(record, persist, options = {}) {
 	} while (true);
 	throw new Error("Managed DevTools project close has no complete native-window destruction evidence; stop the acceptance lane.");
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/installationExit/darwin.ts
+// src/devtoolsProjectOwnership/installationExit/darwin.ts
 const options = {
 	timeout: 1e4,
 	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);
+async function readDarwinProcessStates(timeoutMs = options.timeout) {
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error("Installation-exit recovery cannot inspect the process inventory without a positive timeout.");
+	const inspection = execa("/bin/ps", ["-axo", "pid=,stat=,lstart="], {
+		...options,
+		timeout: Math.min(options.timeout, timeoutMs)
+	});
 	const inspectorPid = inspection.pid;
 	const result = await inspection;
-	if (result.exitCode !== 0 || result.stderr?.trim() || !result.stdout.trim()) throw new Error("Installation-exit recovery could not read the complete process inventory.");
+	if (result.exitCode !== 0 || result.timedOut || result.signal || result.stderr?.trim() || !result.stdout.trim()) throw new Error("Installation-exit recovery could not read the complete process inventory.");
 	const records = result.stdout.trim().split(/\r?\n/).map((line) => {
 		const match = /^\s*(\d+)\s+(\S+)\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]);
@@ -1372,28 +1645,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,45 +1656,54 @@ 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));
-	}
-}
+// src/devtoolsProjectOwnership/installationExit/processes.ts
 /** 仅支持已验证的 macOS 全安装清单；未知平台、权限错误或不完整映像均拒绝推断退出。 */
-async function inspectExitedWechatInstallation(target, platform = process.platform) {
+async function inspectExitedWechatInstallation(target, platform = process.platform, options = {}) {
 	if (platform !== "darwin") throw new Error("Installation-exit recovery requires the verified macOS process inventory.");
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error("Installation-exit recovery requires a positive process inventory timeout.");
+	const deadline = performance.now() + Math.min(timeoutMs, 3e4);
+	const remaining = () => {
+		const timeout = Math.floor(deadline - performance.now());
+		if (timeout <= 0) throw new Error("Installation-exit recovery process inventory deadline expired; continuing new process activity or incomplete inspection prevents proving exit.");
+		return timeout;
+	};
+	const readStates = async () => {
+		const states = await readDarwinProcessStates(remaining());
+		remaining();
+		return states;
+	};
 	const selectedRoot = resolveWechatDevtoolsInstallationRoot(target, platform);
 	if (!selectedRoot || !path.isAbsolute(selectedRoot) || !selectedRoot.endsWith(".app") || !target.appPath.includes("/Contents/")) throw new Error("Installation-exit recovery cannot resolve the selected application bundle.");
 	const installationRoot = await fs.realpath(selectedRoot);
-	let pending = await readDarwinProcessStates();
+	let pending = await readStates();
 	const verified = /* @__PURE__ */ new Map();
 	let kernelPathProcessCount = 0;
 	let textImageProcessCount = 0;
 	let exitedProcessCount = 0;
 	let zombieProcessCount = 0;
-	for (let round = 0; round < 3; round++) {
-		const kernelPaths = await readDarwinKernelPaths(pending.map((entry) => entry.pid));
-		const after = new Map((await readDarwinProcessStates()).map((entry) => [entry.pid, entry]));
+	while (true) {
+		const kernelPaths = await readDarwinKernelPaths(pending.map((entry) => entry.pid), remaining());
+		const after = new Map((await readStates()).map((entry) => [entry.pid, entry]));
 		for (const entry of pending) {
+			remaining();
 			const current = after.get(entry.pid);
 			if (!current) {
 				exitedProcessCount++;
@@ -1453,11 +1716,25 @@ 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, remaining());
+			} catch (error) {
+				const latest = await readStates().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;
+			}
+			remaining();
 			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++;
@@ -1467,7 +1744,7 @@ async function inspectExitedWechatInstallation(target, platform = process.platfo
 				zombie: false
 			});
 		}
-		const final = await readDarwinProcessStates();
+		const final = await readStates();
 		for (const entry of final) {
 			const previous = verified.get(entry.pid);
 			if (previous && (previous.started !== entry.started || previous.zombie && !entry.zombie)) throw new Error("Installation-exit recovery process identity changed during inspection.");
@@ -1475,7 +1752,7 @@ async function inspectExitedWechatInstallation(target, platform = process.platfo
 		pending = final.filter((entry) => !verified.has(entry.pid));
 		if (!pending.length) break;
 	}
-	if (pending.length) throw new Error("Installation-exit recovery found continuing new process activity; retry after it becomes idle.");
+	remaining();
 	return {
 		platform,
 		installationRoot,
@@ -1488,8 +1765,7 @@ async function inspectExitedWechatInstallation(target, platform = process.platfo
 		selectedProcessCount: 0
 	};
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/installationExit/index.ts
+// src/devtoolsProjectOwnership/installationExit/index.ts
 async function fingerprint(record) {
 	const file = managedRecordPath(record.journalPath, record.id);
 	const stat = await fs.lstat(file);
@@ -1497,7 +1773,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 +1788,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 +1823,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 +1845,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 };
 	});
 }
@@ -1575,8 +1856,7 @@ async function recoverAfterExit(options) {
 function recoverManagedWechatProjectsAfterInstallationExit(options) {
 	return withMachineE2ELeaseRecoveryOperation(options.recoveryScope, () => recoverAfterExit(options));
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/index.ts
+// src/devtoolsProjectOwnership/index.ts
 const pendingClosures = /* @__PURE__ */ new Map();
 function describe(error) {
 	return error instanceof Error ? error.message : String(error);
@@ -1587,7 +1867,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 +1911,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 +1939,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 +1947,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 +1958,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 +1974,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;
@@ -1722,5 +2046,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 };