@weapp-vite/devtools-runtime 0.4.24 → 0.5.0

package/dist/index.d.ts

@@ -1,22 +1,128 @@
-import { AutomatorElement, AutomatorMiniProgram, AutomatorPage, DevtoolsConnectionInput, DevtoolsContext, DevtoolsElementSnapshot, DevtoolsPageSnapshot, DevtoolsRuntimeHooks, DevtoolsRuntimeSessionOptions, DevtoolsToolResult, MiniProgramElementLike, readDevtoolsElementSnapshot, resolveDevtoolsProjectPath, resolveDevtoolsWorkspacePath, toDevtoolsSerializableValue } from "./mcp.js";
+import { AutomatorElement, AutomatorMiniProgram, AutomatorPage, DevtoolsConnectionInput, DevtoolsContext, DevtoolsElementSnapshot, DevtoolsInstallationContext, DevtoolsPageSnapshot, DevtoolsRuntimeHooks, DevtoolsRuntimeSessionOptions, DevtoolsToolResult, MiniProgramElementLike, readDevtoolsElementSnapshot, resolveDevtoolsProjectPath, resolveDevtoolsWorkspacePath, toDevtoolsSerializableValue } from "./mcp.js";
+//#region src/lease.d.ts
+export interface RuntimeLease {
+  root: string;
+  token: string;
+  released: boolean;
+  release: () => Promise<void>;
+}
+/** 同一真实工程跨进程互斥；未知持有者不自动回收。 */
+export declare function acquireRuntimeLease(projectRoot: string): Promise<RuntimeLease>;
+export declare function runWithRuntimeLease<T>(lease: RuntimeLease, run: () => Promise<T>): Promise<T>;
+export declare function withRuntimeLease<T>(projectRoot: string, run: () => Promise<T>): Promise<T>;
+//#endregion
+//#region src/lease/directory.d.ts
+interface LeaseOwner {
+  pid: number;
+  token: string;
+}
+/** 注册、释放和过期回收共享短临界区；归属未知的临界区不自动删除。 */
+export declare function mutateLease<T>(directory: string, run: () => Promise<T>, options?: {
+  timeoutMs?: number;
+}): Promise<T>;
+//#endregion
+//#region src/lease/machineRecoveryState.d.ts
+interface MachineE2ELeaseRecoveryScope {
+  readonly id: string;
+  readonly owner: Readonly<LeaseOwner>;
+  readonly ancestors: readonly string[];
+  readonly sealed: boolean;
+  readonly completed: boolean;
+  readonly cleanupKey?: string;
+}
+interface MachineE2ELeaseSnapshot {
+  readonly owner: Readonly<LeaseOwner>;
+  readonly scopes: readonly MachineE2ELeaseRecoveryScope[];
+  readonly borrowers: readonly {
+    readonly pid: number;
+    readonly token: string;
+    readonly scopes: readonly string[];
+  }[];
+}
+//#endregion
+//#region src/lease/machineScopeRecovery.d.ts
+interface MachineE2ERecoverableDescendantScope extends MachineE2ELeaseRecoveryScope {
+  readonly cleanupKey: string;
+}
+//#endregion
+//#region src/lease/machineScope.d.ts
+interface MachineE2EChildScopeOptions {
+  /** 创建时绑定的清理标识；资源含义及准确归属由调用方核验，创建后不能更改。 */
+  cleanupKey?: string;
+}
+interface MachineE2EChildScope {
+  environment: Record<string, string>;
+  /** 先封存借用入口，再确认该子树已无活跃借用者；失败时仍保持封存。 */
+  seal: () => Promise<void>;
+  /** 当前命令已停止且日志清理成功后完成本 scope，不覆盖后代的未完成状态。 */
+  complete: () => Promise<void>;
+  /** 仅接管已停止且有清理绑定的后代；回调成功后逐个完成，不代替本 scope 的清理。 */
+  recoverStoppedDescendants: (run: (scope: MachineE2ERecoverableDescendantScope) => Promise<void>) => Promise<void>;
+}
+//#endregion
+//#region src/lease/machine.d.ts
+export interface MachineE2ELeaseOptions {
+  /** 仅供隔离测试或嵌入方显式选择；不从工作目录或用户配置环境变量推导。 */
+  stateDirectory?: string;
+  env?: NodeJS.ProcessEnv;
+}
+export interface MachineE2ELease {
+  borrowed: boolean;
+  released: boolean;
+  environment: NodeJS.ProcessEnv;
+  createChildScope: (options?: MachineE2EChildScopeOptions) => Promise<MachineE2EChildScope>;
+  release: () => Promise<void>;
+}
+/** 同机同用户的所有 E2E 共用一个租约，子进程凭磁盘核验过的能力票据借用。 */
+export declare function acquireMachineE2ELease(options?: MachineE2ELeaseOptions): Promise<MachineE2ELease>;
+/** 入口持有租约到清理完成；执行与释放同时失败时保留两者，嵌套入口仅释放自己的登记。 */
+export declare function withMachineE2ELease<T>(run: (lease: MachineE2ELease) => Promise<T>, options?: MachineE2ELeaseOptions): Promise<T>;
+//#endregion
+//#region src/lease/machineRecovery.d.ts
+export interface MachineE2ELeaseRecoveryOptions extends MachineE2ELeaseOptions {
+  expected: MachineE2ELeaseSnapshot;
+  /** 必须绑定已核验的资源日志并完成清理；仅此回调成功才允许完成对应 scope。 */
+  recoverScope: (scope: MachineE2ELeaseRecoveryScope) => Promise<void>;
+}
+export interface MachineE2ELeaseRecoveryResult {
+  auditFile: string;
+  recoveredScopes: string[];
+}
+/** 读取供显式恢复核对的精确登记快照，不修改租约或推导资源清理权限。 */
+export declare function readMachineE2ELeaseSnapshot(options?: MachineE2ELeaseOptions): Promise<MachineE2ELeaseSnapshot>;
+/** 核验当前显式恢复回调的原始 scope 与完整接管快照，不授予普通租约额外清理权限。 */
+export declare function assertMachineE2ELeaseRecoveryScope(scope: MachineE2ELeaseRecoveryScope): Promise<void>;
+/** 同步登记完整领域操作；回调漏等候时保留租约，直到在途操作停止后再报告失败。 */
+export declare function withMachineE2ELeaseRecoveryOperation<T>(scope: MachineE2ELeaseRecoveryScope, run: () => Promise<T>): Promise<T>;
+/**
+ * 接管已退出且全部封存的精确租约，按后代优先顺序调用受信清理回调。
+ * 回调通过当前根凭证嵌套普通租约，但不能遗留新登记或改变 scope。
+ * 失败保留新持有者与未完成 scope，待恢复进程退出后凭新快照重试。
+ * 接管中断保留原快照审计；进程崩溃留下的变更锁或混合归属不自动修复。
+ */
+export declare function recoverMachineE2ELease(options: MachineE2ELeaseRecoveryOptions): Promise<MachineE2ELeaseRecoveryResult>;
+//#endregion
 //#region src/index.d.ts
 export interface MiniProgramEventMap {
   console: (payload: unknown) => void;
   exception: (payload: unknown) => void;
 }
-export declare function resolveSharedMiniProgramSessionKey(options: Pick<DevtoolsRuntimeSessionOptions, 'port' | 'projectPath' | 'sessionId'>): string;
+export type SharedMiniProgramSessionOptions = Pick<DevtoolsRuntimeSessionOptions, 'port' | 'projectPath' | 'sessionId' | 'cliPath' | 'installationId' | 'runtimeProvider'>;
+export declare function resolveSharedMiniProgramSessionKey(options: SharedMiniProgramSessionOptions): string;
 /**
  * @description 获取指定项目的共享 automator 会话；若不存在则自动创建。
  */
 export declare function acquireSharedMiniProgram(hooks: DevtoolsRuntimeHooks, options: DevtoolsRuntimeSessionOptions): Promise<AutomatorMiniProgram>;
+/** 使用创建连接时的精确键释放订阅。 */
+export declare function releaseSharedMiniProgramByKey(sessionKey: string): void;
 /**
  * @description 释放指定项目的共享会话引用；会话对象会继续缓存，直到显式关闭或重置。
  */
-export declare function releaseSharedMiniProgram(projectPath: string, sessionIdOrPort?: string | number): void;
+export declare function releaseSharedMiniProgram(projectPath: string, sessionIdOrPort?: string | number, installation?: Omit<SharedMiniProgramSessionOptions, 'projectPath'>): void;
 /**
  * @description 关闭并移除指定项目的共享 automator 会话。
  */
-export declare function closeSharedMiniProgram(projectPath: string, sessionIdOrPort?: string | number): Promise<void>;
+export declare function closeSharedMiniProgram(projectPath: string, sessionIdOrPort?: string | number, installation?: Omit<SharedMiniProgramSessionOptions, 'projectPath'>): Promise<void>;
 /**
  * @description 获取当前共享会话数量，供测试断言使用。
  */
@@ -25,5 +131,11 @@ export declare function getSharedMiniProgramSessionCount(): number;
  * @description 统一管理 automator 会话生命周期。
  */
 export declare function withMiniProgram<T>(hooks: DevtoolsRuntimeHooks, options: DevtoolsRuntimeSessionOptions, runner: (miniProgram: AutomatorMiniProgram) => Promise<T>): Promise<T>;
+/** 检查缓存，供调用方记录其实际创建的连接。 */
+export declare function hasSharedMiniProgram(options: SharedMiniProgramSessionOptions): boolean;
+/** 只清理仍由调用方创建、且已无活动引用的连接。 */
+export declare function closeOwnedSharedMiniProgram(options: SharedMiniProgramSessionOptions, owned: unknown): Promise<void>;
+/** 单独保留管理器订阅，避免与正在执行的操作共享引用计数。 */
+export declare function retainSharedMiniProgram(sessionKey: string): void;
 //#endregion
-export { type AutomatorElement, type AutomatorMiniProgram, type AutomatorPage, type DevtoolsConnectionInput, type DevtoolsContext, type DevtoolsElementSnapshot, type DevtoolsPageSnapshot, type DevtoolsRuntimeHooks, type DevtoolsRuntimeSessionOptions, type DevtoolsToolResult, type MiniProgramElementLike, readDevtoolsElementSnapshot, resolveDevtoolsProjectPath, resolveDevtoolsWorkspacePath, toDevtoolsSerializableValue };
+export { type AutomatorElement, type AutomatorMiniProgram, type AutomatorPage, type DevtoolsConnectionInput, type DevtoolsContext, type DevtoolsElementSnapshot, type DevtoolsInstallationContext, type DevtoolsPageSnapshot, type DevtoolsRuntimeHooks, type DevtoolsRuntimeSessionOptions, type DevtoolsToolResult, type MachineE2EChildScope, type MachineE2EChildScopeOptions, type MachineE2ELeaseRecoveryScope, type MachineE2ELeaseSnapshot, type MachineE2ERecoverableDescendantScope, type MiniProgramElementLike, readDevtoolsElementSnapshot, resolveDevtoolsProjectPath, resolveDevtoolsWorkspacePath, toDevtoolsSerializableValue };

package/dist/index.js

@@ -1,4 +1,820 @@
 import { readDevtoolsElementSnapshot, resolveDevtoolsProjectPath, resolveDevtoolsWorkspacePath, toDevtoolsSerializableValue } from "./mcp.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, lstat, mkdir, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { setTimeout } from "node:timers/promises";
+import { isDeepStrictEqual } from "node:util";
+//#region src/lease/machineScopeState.ts
+/** 未完成的本租约命令不能因持有进程退出而被新验收直接接管。 */
+async function assertNoIncompleteMachineScopes(directory) {
+	const scopes = path.join(directory, "scopes");
+	const files = await readdir(scopes).catch((error) => {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	});
+	for (const file of files) {
+		const record = JSON.parse(await readFile(path.join(scopes, file), "utf8"));
+		if (!record || typeof record !== "object" || !("sealed" in record) || record.sealed !== true || !("completed" in record) || record.completed !== true) throw new Error("Runtime busy: an E2E command scope has unfinished cleanup; preserve the machine lease and its journals.");
+	}
+}
+//#endregion
+//#region src/lease/directory.ts
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code !== "ESRCH";
+	}
+}
+async function readLeaseOwner(file) {
+	const value = await readFile(file, "utf8").then(JSON.parse).catch(() => void 0);
+	if (!value || typeof value !== "object" || !("pid" in value) || !("token" in value) || !Number.isInteger(value.pid) || Number(value.pid) <= 0 || typeof value.token !== "string" || !value.token) return;
+	return {
+		pid: Number(value.pid),
+		token: value.token
+	};
+}
+/** 注册、释放和过期回收共享短临界区；归属未知的临界区不自动删除。 */
+async function mutateLease(directory, run, options = {}) {
+	const guard = `${directory}.recovery`;
+	const timeoutMs = options.timeoutMs ?? 200;
+	if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("Lease mutation timeout must be a finite non-negative number.");
+	const deadline = Date.now() + timeoutMs;
+	while (true) try {
+		await mkdir(guard, { mode: 448 });
+		break;
+	} catch (error) {
+		const code = error.code;
+		const retryPermissionError = process.platform === "win32" && code === "EPERM";
+		if (code !== "EEXIST" && !retryPermissionError) throw error;
+		if (Date.now() >= deadline) {
+			if (retryPermissionError) throw error;
+			throw new Error("Runtime busy: lease ownership update or recovery is in progress.");
+		}
+		await setTimeout(Math.min(10, Math.max(0, deadline - Date.now())));
+	}
+	try {
+		return await run();
+	} finally {
+		await rm(guard, { recursive: true });
+	}
+}
+/** 活跃借用方和不完整登记均阻止回收，避免父进程退出后孤儿任务继续运行。 */
+async function assertNoLeaseBorrowers(directory) {
+	const members = path.join(directory, "borrowers");
+	const files = await readdir(members).catch((error) => {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	});
+	for (const file of files) {
+		const borrower = await readLeaseOwner(path.join(members, file));
+		if (!borrower || isProcessAlive(borrower.pid)) throw new Error("Runtime busy: an E2E child operation still owns this machine lease.");
+	}
+}
+/** 目录创建负责原子占用；只有有效且已退出的持有者允许被回收。 */
+async function acquireDirectoryLease(directory, busyMessage) {
+	await mkdir(path.dirname(directory), {
+		recursive: true,
+		mode: 448
+	});
+	const owner = {
+		pid: process.pid,
+		token: randomUUID()
+	};
+	const create = async () => {
+		await mkdir(directory, { mode: 448 });
+		try {
+			await writeFile(path.join(directory, "owner.json"), JSON.stringify(owner), { mode: 384 });
+		} catch (error) {
+			await rm(directory, { recursive: true });
+			throw error;
+		}
+	};
+	try {
+		await create();
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		await mutateLease(directory, async () => {
+			const previous = await readLeaseOwner(path.join(directory, "owner.json"));
+			if (!previous || isProcessAlive(previous.pid)) throw new Error(busyMessage);
+			await assertNoLeaseBorrowers(directory);
+			await assertNoIncompleteMachineScopes(directory);
+			await rm(directory, { recursive: true });
+			try {
+				await create();
+			} catch (error) {
+				if (error.code === "EEXIST") throw new Error(busyMessage);
+				throw error;
+			}
+		});
+	}
+	let releasing;
+	const lease = {
+		directory,
+		owner,
+		released: false,
+		release: () => {
+			if (lease.released) return Promise.resolve();
+			releasing ??= mutateLease(directory, async () => {
+				const current = await readLeaseOwner(path.join(directory, "owner.json"));
+				if (current?.token !== owner.token || current.pid !== owner.pid) throw new Error("Runtime lease ownership changed; refusing cleanup.");
+				await assertNoLeaseBorrowers(directory);
+				await assertNoIncompleteMachineScopes(directory);
+				await rm(directory, { recursive: true });
+				lease.released = true;
+			}).finally(() => {
+				releasing = void 0;
+			});
+			return releasing;
+		}
+	};
+	return lease;
+}
+//#endregion
+//#region src/lease.ts
+const currentLease = new AsyncLocalStorage();
+/** 同一真实工程跨进程互斥；未知持有者不自动回收。 */
+async function acquireRuntimeLease(projectRoot) {
+	const root = await realpath(projectRoot);
+	const directory = path.join(process.env.WEAPP_AGENT_STATE_DIR ?? path.join(homedir(), ".local", "state", "weapp-agent"), "runtime-locks");
+	const owned = await acquireDirectoryLease(path.join(directory, createHash("sha256").update(root).digest("hex")), "Runtime busy: another operation owns this project. Query or cancel its acceptance task first.");
+	return {
+		root,
+		token: owned.owner.token,
+		get released() {
+			return owned.released;
+		},
+		release: owned.release
+	};
+}
+function runWithRuntimeLease(lease, run) {
+	if (lease.released) throw new Error("Runtime lease already released");
+	return currentLease.run(lease, run);
+}
+async function withRuntimeLease(projectRoot, run) {
+	const root = await realpath(projectRoot);
+	const active = currentLease.getStore();
+	if (active?.root === root && !active.released) return run();
+	const lease = await acquireRuntimeLease(root);
+	try {
+		return await runWithRuntimeLease(lease, run);
+	} finally {
+		await lease.release();
+	}
+}
+//#endregion
+//#region src/lease/machineRecoveryState.ts
+async function assertRecoveryNode(file, kind) {
+	const stat = await lstat(file);
+	if (stat.isSymbolicLink() || (kind === "directory" ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1)) throw new Error("Machine lease recovery refuses redirected or non-regular filesystem entries.");
+}
+function assertKeys(value, keys, optionalKeys = []) {
+	if (!value || typeof value !== "object" || Array.isArray(value) || !isDeepStrictEqual(Object.keys(value).filter((key) => !optionalKeys.includes(key)).sort(), keys.toSorted())) throw new Error("Machine lease recovery found unknown or missing record fields.");
+}
+async function readRecord(file, keys, optionalKeys = []) {
+	await assertRecoveryNode(file, "file");
+	const value = JSON.parse(await readFile(file, "utf8"));
+	assertKeys(value, keys, optionalKeys);
+	return value;
+}
+async function entries(directory) {
+	return assertRecoveryNode(directory, "directory").then(() => readdir(directory)).catch((error) => {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	});
+}
+/** 仅在机器租约短临界区内读取，拒绝无法还原归属链的登记。 */
+async function readMachineSnapshot(directory) {
+	await assertRecoveryNode(directory, "directory").catch((error) => {
+		if (error.code !== "ENOENT") throw error;
+		throw new Error("Machine lease recovery requires an existing, verifiable owner.");
+	});
+	const rootEntries = await readdir(directory);
+	if (!rootEntries.includes("owner.json") || rootEntries.some((entry) => ![
+		"owner.json",
+		"scopes",
+		"borrowers"
+	].includes(entry))) throw new Error("Machine lease recovery found an unknown or missing lease root entry.");
+	const rawOwner = await readRecord(path.join(directory, "owner.json"), ["pid", "token"]);
+	const { pid, token } = parseMachineCredential(JSON.stringify(rawOwner));
+	const owner = {
+		pid,
+		token
+	};
+	const scopes = [];
+	for (const file of (await entries(path.join(directory, "scopes"))).sort()) {
+		const id = file.endsWith(".json") ? file.slice(0, -5) : "";
+		assertKeys((await readRecord(path.join(directory, "scopes", file), [
+			"owner",
+			"ancestors",
+			"sealed",
+			"completed"
+		], ["cleanupKey"])).owner, ["pid", "token"]);
+		scopes.push({
+			id,
+			...await readScope(directory, id)
+		});
+	}
+	const byId = new Map(scopes.map((scope) => [scope.id, scope]));
+	for (const scope of scopes) if (!isDeepStrictEqual(scope.owner, owner) || scope.ancestors.includes(scope.id) || scope.ancestors.some((id, index) => !isDeepStrictEqual(byId.get(id)?.ancestors, scope.ancestors.slice(0, index))) || !scope.completed && scope.ancestors.some((id) => byId.get(id)?.completed) || scope.completed && !scope.sealed) throw new Error("Machine lease recovery found an unverifiable scope ownership chain.");
+	const borrowers = [];
+	for (const file of (await entries(path.join(directory, "borrowers"))).sort()) {
+		const raw = await readRecord(path.join(directory, "borrowers", file), [
+			"pid",
+			"token",
+			"scopes"
+		]);
+		const borrower = parseMachineCredential(JSON.stringify(raw));
+		if (file !== `${borrower.token}.json` || borrower.scopes.some((id, index) => !isDeepStrictEqual(byId.get(id)?.ancestors, borrower.scopes.slice(0, index)))) throw new Error("Machine lease recovery found an unverifiable borrower ownership chain.");
+		borrowers.push(borrower);
+	}
+	return {
+		owner,
+		scopes,
+		borrowers
+	};
+}
+function assertSnapshotStopped(snapshot, requireOwnerStopped) {
+	if (requireOwnerStopped && isProcessAlive(snapshot.owner.pid) || snapshot.borrowers.some((borrower) => isProcessAlive(borrower.pid))) throw new Error("Runtime busy: machine lease recovery requires the owner and registered borrowers to have stopped.");
+	if (snapshot.scopes.some((scope) => !scope.sealed)) throw new Error("Machine lease recovery requires every command scope to be explicitly sealed.");
+}
+async function assertMachineSnapshot(directory, expected) {
+	const actual = await readMachineSnapshot(directory);
+	if (!isDeepStrictEqual(actual, expected)) throw new Error("Machine lease recovery snapshot changed; refusing cleanup of unexpected ownership, scopes, or borrowers.");
+	assertSnapshotStopped(actual, false);
+}
+function recoveryScopeCopy(scope) {
+	return Object.freeze({
+		...scope,
+		owner: Object.freeze({ ...scope.owner }),
+		ancestors: Object.freeze([...scope.ancestors])
+	});
+}
+//#endregion
+//#region src/lease/machineScopeRecovery.ts
+const activeRecoveries = /* @__PURE__ */ new Map();
+/** 活借用登记阻止跨进程接管；进程内保留的父子能力还需防止重叠回调。 */
+function claimSubtree(directory, credential) {
+	let active = activeRecoveries.get(directory);
+	if (!active) {
+		active = /* @__PURE__ */ new Set();
+		activeRecoveries.set(directory, active);
+	}
+	if ([...active].some((other) => other.scopes.includes(credential.token) || credential.scopes.includes(other.token))) throw new Error("Runtime busy: overlapping machine descendant recovery is already in progress.");
+	active.add(credential);
+	return () => {
+		active.delete(credential);
+		if (!active.size) activeRecoveries.delete(directory);
+	};
+}
+function subtree(snapshot, token) {
+	return {
+		owner: snapshot.owner,
+		scopes: snapshot.scopes.filter((scope) => scope.id === token || scope.ancestors.includes(token)),
+		borrowers: snapshot.borrowers.filter((borrower) => borrower.scopes.includes(token))
+	};
+}
+function assertStopped(snapshot) {
+	if (snapshot.borrowers.some((borrower) => isProcessAlive(borrower.pid))) throw new Error("Runtime busy: an E2E command child is still running; preserve its journal before descendant recovery.");
+}
+async function writeScope(directory, scope) {
+	const { id, ...record } = scope;
+	await writeFile(path.join(directory, "scopes", `${id}.json`), JSON.stringify(record), { mode: 384 });
+}
+/** 父能力只接管本子树；未登记清理标识、未知借用者或未确认停止均不能推导清理权。 */
+async function recoverSubtree(directory, credential, run) {
+	const token = credential.scopes.at(-1);
+	if (!token) throw new Error("Descendant recovery requires an explicit parent command scope.");
+	let expected = await mutateLease(directory, async () => {
+		await assertMachineCredential(directory, credential, true);
+		let selected = subtree(await readMachineSnapshot(directory), token);
+		const parent = selected.scopes.find((scope) => scope.id === token);
+		if (!parent.sealed) {
+			await writeScope(directory, {
+				...parent,
+				sealed: true
+			});
+			selected = subtree(await readMachineSnapshot(directory), token);
+		}
+		assertStopped(selected);
+		const pending = selected.scopes.filter((scope) => scope.id !== token && !scope.completed);
+		if (pending.some((scope) => !scope.cleanupKey)) throw new Error("Machine descendant recovery requires an explicit cleanupKey for every unfinished descendant.");
+		for (const scope of pending) if (!scope.sealed) await writeScope(directory, {
+			...scope,
+			sealed: true
+		});
+		return subtree(await readMachineSnapshot(directory), token);
+	});
+	const assertUnchanged = async () => {
+		await assertMachineCredential(directory, credential, true);
+		const actual = subtree(await readMachineSnapshot(directory), token);
+		if (!isDeepStrictEqual(actual, expected)) throw new Error("Machine descendant recovery snapshot changed; preserve unexpected scopes, bindings, or borrowers.");
+		assertStopped(actual);
+	};
+	const pending = expected.scopes.filter((scope) => scope.id !== token && !scope.completed).sort((left, right) => right.ancestors.length - left.ancestors.length);
+	for (const scope of pending) {
+		await mutateLease(directory, assertUnchanged);
+		await run(recoveryScopeCopy(scope));
+		await mutateLease(directory, async () => {
+			await assertUnchanged();
+			await writeScope(directory, {
+				...scope,
+				completed: true
+			});
+			expected = {
+				...expected,
+				scopes: expected.scopes.map((item) => item.id === scope.id ? {
+					...item,
+					completed: true
+				} : item)
+			};
+		});
+	}
+	await mutateLease(directory, assertUnchanged);
+}
+/** 已确认停止的子树串行接管，失败释放当前进程的回调占用但保留磁盘证据。 */
+async function recoverStoppedDescendantScopes(directory, credential, run) {
+	const releaseClaim = claimSubtree(directory, credential);
+	try {
+		await recoverSubtree(directory, credential, run);
+	} finally {
+		releaseClaim();
+	}
+}
+//#endregion
+//#region src/lease/machineScope.ts
+const INHERITED_LEASE_ENV = "WEAPP_VITE_E2E_MACHINE_LEASE";
+const UUID = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+function invalid() {
+	return /* @__PURE__ */ new Error("Runtime busy: inherited E2E lease is invalid or its command scope is sealed; refusing unverified child ownership.");
+}
+function scopesOf(value) {
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !UUID.test(item)) || new Set(value).size !== value.length) throw invalid();
+	return value;
+}
+function ownerOf(value) {
+	if (!value || typeof value !== "object" || !("pid" in value) || !("token" in value) || !Number.isInteger(value.pid) || Number(value.pid) <= 0 || typeof value.token !== "string" || !value.token) throw invalid();
+	return {
+		pid: Number(value.pid),
+		token: value.token
+	};
+}
+function parseMachineCredential(value) {
+	const parsed = JSON.parse(value);
+	const owner = ownerOf(parsed);
+	const scopes = parsed && typeof parsed === "object" && "scopes" in parsed ? scopesOf(parsed.scopes) : [];
+	return {
+		...owner,
+		scopes
+	};
+}
+function sameOwner(left, right) {
+	return left.pid === right.pid && left.token === right.token;
+}
+function sameScopes(left, right) {
+	return left.length === right.length && left.every((token, index) => token === right[index]);
+}
+function scopeFile(directory, token) {
+	if (!UUID.test(token)) throw invalid();
+	return path.join(directory, "scopes", `${token}.json`);
+}
+async function readScope(directory, token) {
+	const value = JSON.parse(await readFile(scopeFile(directory, token), "utf8"));
+	if (!value || typeof value !== "object" || !("owner" in value) || !("ancestors" in value) || !("sealed" in value) || typeof value.sealed !== "boolean" || !("completed" in value) || typeof value.completed !== "boolean") throw invalid();
+	if ("cleanupKey" in value && (typeof value.cleanupKey !== "string" || !value.cleanupKey.trim())) throw invalid();
+	return {
+		owner: ownerOf(value.owner),
+		ancestors: scopesOf(value.ancestors),
+		sealed: value.sealed,
+		completed: value.completed,
+		..."cleanupKey" in value ? { cleanupKey: value.cleanupKey } : {}
+	};
+}
+/** 调用方持有同一机器租约变更锁；派生 token 丢失祖先链时不能降级成根凭证。 */
+async function assertMachineCredential(directory, credential, allowSealed = false) {
+	const owner = await readLeaseOwner(path.join(directory, "owner.json"));
+	if (!owner || owner.pid !== credential.pid || !isProcessAlive(owner.pid) || credential.token !== (credential.scopes.at(-1) ?? owner.token)) throw invalid();
+	for (const [index, token] of credential.scopes.entries()) {
+		const record = await readScope(directory, token).catch(() => {
+			throw invalid();
+		});
+		if (!sameOwner(record.owner, owner) || !sameScopes(record.ancestors, credential.scopes.slice(0, index)) || !allowSealed && record.sealed) throw invalid();
+	}
+	return owner;
+}
+async function assertScopeStopped(directory, token) {
+	const borrowers = path.join(directory, "borrowers");
+	const files = await readdir(borrowers).catch((error) => {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	});
+	for (const file of files) {
+		const value = JSON.parse(await readFile(path.join(borrowers, file), "utf8"));
+		const owner = ownerOf(value);
+		if (!value || typeof value !== "object" || !("scopes" in value)) throw new Error("Runtime busy: an E2E borrower has no verifiable command scope; preserve its journal.");
+		if (scopesOf(value.scopes).includes(token) && isProcessAlive(owner.pid)) throw new Error("Runtime busy: an E2E command child is still running; preserve its journal before cleanup.");
+	}
+}
+async function assertDescendantScopesCompleted(directory, token) {
+	for (const file of await readdir(path.join(directory, "scopes"))) {
+		const record = await readScope(directory, file.endsWith(".json") ? file.slice(0, -5) : "");
+		if (record.ancestors.includes(token) && !record.completed) throw new Error("Runtime busy: an E2E descendant scope has unfinished cleanup; preserve its journal before parent cleanup.");
+	}
+}
+/** 使用现有租约目录与变更锁封存命令子树，阻止存活或迟到子任务与父清理竞争。 */
+async function createMachineChildScope(directory, credential, isHeld, options = {}) {
+	const cleanupKey = options.cleanupKey;
+	if (cleanupKey !== void 0 && (typeof cleanupKey !== "string" || !cleanupKey.trim())) throw new Error("Machine command scope cleanupKey must be a non-empty string.");
+	const token = randomUUID();
+	const scoped = {
+		pid: credential.pid,
+		token,
+		scopes: [...credential.scopes, token]
+	};
+	await mutateLease(directory, async () => {
+		if (!isHeld()) throw invalid();
+		const owner = await assertMachineCredential(directory, credential);
+		await mkdir(path.join(directory, "scopes"), {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(scopeFile(directory, token), JSON.stringify({
+			owner,
+			ancestors: credential.scopes,
+			sealed: false,
+			completed: false,
+			...cleanupKey === void 0 ? {} : { cleanupKey }
+		}), {
+			mode: 384,
+			flag: "wx"
+		});
+	});
+	let recovering;
+	return {
+		environment: { [INHERITED_LEASE_ENV]: JSON.stringify(scoped) },
+		recoverStoppedDescendants: (run) => {
+			recovering ??= recoverStoppedDescendantScopes(directory, scoped, run).finally(() => {
+				recovering = void 0;
+			});
+			return recovering;
+		},
+		seal: () => mutateLease(directory, async () => {
+			await assertMachineCredential(directory, scoped, true);
+			const record = await readScope(directory, token);
+			if (!record.sealed) await writeFile(scopeFile(directory, token), JSON.stringify({
+				...record,
+				sealed: true
+			}), { mode: 384 });
+			await assertScopeStopped(directory, token);
+			await assertDescendantScopesCompleted(directory, token);
+		}),
+		complete: () => mutateLease(directory, async () => {
+			await assertMachineCredential(directory, scoped, true);
+			if (!(await readScope(directory, token)).sealed) throw new Error("Runtime busy: E2E command scope must be sealed before completing its cleanup.");
+			await assertScopeStopped(directory, token);
+			await assertDescendantScopesCompleted(directory, token);
+			const record = await readScope(directory, token);
+			await writeFile(scopeFile(directory, token), JSON.stringify({
+				...record,
+				completed: true
+			}), { mode: 384 });
+		})
+	};
+}
+//#endregion
+//#region src/lease/machineContext.ts
+const currentMachineLease = new AsyncLocalStorage();
+const publishedCredentials = /* @__PURE__ */ new WeakMap();
+function machineStateDirectory(options) {
+	return path.resolve(options.stateDirectory ?? path.join(homedir(), ".local", "state", "weapp-agent"));
+}
+/** 同一凭证仅由最后退出的作用域恢复，避免并发嵌套过早移除父进程环境。 */
+function publishCredential(environment, value) {
+	let published = publishedCredentials.get(environment);
+	if (!published) {
+		if (environment["WEAPP_VITE_E2E_MACHINE_LEASE"] === value) return () => {};
+		published = {
+			value,
+			previous: environment[INHERITED_LEASE_ENV],
+			users: 0
+		};
+		publishedCredentials.set(environment, published);
+		environment[INHERITED_LEASE_ENV] = value;
+	}
+	if (published.value !== value) throw new Error("Runtime busy: another machine lease scope owns this process environment.");
+	published.users++;
+	return () => {
+		if (--published.users > 0) return;
+		publishedCredentials.delete(environment);
+		if (environment["WEAPP_VITE_E2E_MACHINE_LEASE"] !== published.value) return;
+		if (published.previous === void 0) delete environment[INHERITED_LEASE_ENV];
+		else environment[INHERITED_LEASE_ENV] = published.previous;
+	};
+}
+function inheritedMachineEnvironment(options) {
+	const environment = options.env ?? process.env;
+	const active = currentMachineLease.getStore();
+	if (active?.directory === machineStateDirectory(options) && !active.lease.released) return {
+		...environment,
+		...active.lease.environment
+	};
+	if (publishedCredentials.has(environment)) {
+		const inherited = { ...environment };
+		delete inherited[INHERITED_LEASE_ENV];
+		return inherited;
+	}
+	return environment;
+}
+/** 只发布当前持有者上下文；调用方决定何时释放，失败恢复不能隐式完成租约。 */
+async function withMachineLeaseContext(lease, run, options) {
+	const restore = publishCredential(options.env ?? process.env, lease.environment[INHERITED_LEASE_ENV]);
+	try {
+		return await currentMachineLease.run({
+			directory: machineStateDirectory(options),
+			lease
+		}, run);
+	} finally {
+		restore();
+	}
+}
+//#endregion
+//#region src/lease/machine.ts
+/** 同机同用户的所有 E2E 共用一个租约，子进程凭磁盘核验过的能力票据借用。 */
+async function acquireMachineE2ELease(options = {}) {
+	const state = machineStateDirectory(options);
+	const directory = path.join(state, "machine-e2e");
+	const inherited = (options.env ?? process.env)[INHERITED_LEASE_ENV];
+	if (!inherited) {
+		const owned = await acquireDirectoryLease(directory, "Runtime busy: another E2E operation owns this machine. Wait for its owner to finish before retrying.");
+		return {
+			borrowed: false,
+			get released() {
+				return owned.released;
+			},
+			environment: { [INHERITED_LEASE_ENV]: JSON.stringify(owned.owner) },
+			createChildScope: (options) => createMachineChildScope(directory, {
+				...owned.owner,
+				scopes: []
+			}, () => !owned.released, options),
+			release: owned.release
+		};
+	}
+	let credential;
+	try {
+		credential = parseMachineCredential(inherited);
+	} catch {
+		throw new Error("Runtime busy: inherited E2E lease is invalid; refusing to bypass the machine lock.");
+	}
+	const member = {
+		pid: process.pid,
+		token: randomUUID(),
+		scopes: credential.scopes
+	};
+	const memberFile = path.join(directory, "borrowers", `${member.token}.json`);
+	await mkdir(state, {
+		recursive: true,
+		mode: 448
+	});
+	await mutateLease(directory, async () => {
+		await assertMachineCredential(directory, credential);
+		await mkdir(path.dirname(memberFile), {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(memberFile, JSON.stringify(member), { mode: 384 });
+	});
+	let releasing;
+	const lease = {
+		borrowed: true,
+		released: false,
+		environment: { [INHERITED_LEASE_ENV]: inherited },
+		createChildScope: (options) => createMachineChildScope(directory, credential, () => !lease.released, options),
+		release: () => {
+			if (lease.released) return Promise.resolve();
+			releasing ??= mutateLease(directory, async () => {
+				const registered = await readLeaseOwner(memberFile);
+				if (registered?.token !== member.token || registered.pid !== member.pid) throw new Error("Runtime lease borrower ownership changed; refusing cleanup.");
+				await rm(memberFile);
+				lease.released = true;
+			}).finally(() => {
+				releasing = void 0;
+			});
+			return releasing;
+		}
+	};
+	return lease;
+}
+/** 入口持有租约到清理完成；执行与释放同时失败时保留两者，嵌套入口仅释放自己的登记。 */
+async function withMachineE2ELease(run, options = {}) {
+	const lease = await acquireMachineE2ELease({
+		...options,
+		env: inheritedMachineEnvironment(options)
+	});
+	let entered = false;
+	let failure;
+	const release = async () => {
+		try {
+			await lease.release();
+		} catch (releaseError) {
+			if (failure) throw new AggregateError([failure.error, releaseError], "E2E operation failed and machine lease cleanup did not complete.", { cause: failure.error });
+			throw releaseError;
+		}
+	};
+	try {
+		return await withMachineLeaseContext(lease, async () => {
+			entered = true;
+			try {
+				return await run(lease);
+			} catch (error) {
+				failure = { error };
+				throw error;
+			} finally {
+				await release();
+			}
+		}, options);
+	} catch (error) {
+		failure = { error };
+		throw error;
+	} finally {
+		if (!entered) await release();
+	}
+}
+//#endregion
+//#region src/lease/machineRecovery.ts
+const currentRecovery = new AsyncLocalStorage();
+/** 读取供显式恢复核对的精确登记快照，不修改租约或推导资源清理权限。 */
+async function readMachineE2ELeaseSnapshot(options = {}) {
+	const directory = path.join(machineStateDirectory(options), "machine-e2e");
+	return mutateLease(directory, () => readMachineSnapshot(directory));
+}
+function activeRecovery(scope) {
+	const context = currentRecovery.getStore();
+	if (!context?.active || context.scope !== scope || context.snapshot.scopes.find((item) => item.id === scope.id)?.cleanupKey !== scope.cleanupKey) throw new Error("Machine lease recovery requires the active explicit recovery callback and its original scope.");
+	return context;
+}
+/** 核验当前显式恢复回调的原始 scope 与完整接管快照，不授予普通租约额外清理权限。 */
+async function assertMachineE2ELeaseRecoveryScope(scope) {
+	const context = activeRecovery(scope);
+	await mutateLease(context.directory, async () => {
+		activeRecovery(scope);
+		await assertMachineSnapshot(context.directory, context.snapshot);
+		activeRecovery(scope);
+	});
+	activeRecovery(scope);
+}
+/** 同步登记完整领域操作；回调漏等候时保留租约，直到在途操作停止后再报告失败。 */
+function withMachineE2ELeaseRecoveryOperation(scope, run) {
+	let context;
+	try {
+		context = activeRecovery(scope);
+	} catch (error) {
+		return Promise.reject(error);
+	}
+	const operation = (async () => {
+		await assertMachineE2ELeaseRecoveryScope(scope);
+		const result = await run();
+		await assertMachineE2ELeaseRecoveryScope(scope);
+		return result;
+	})();
+	context.operations.add(operation);
+	operation.then(() => context.operations.delete(operation), () => context.operations.delete(operation));
+	return operation;
+}
+/**
+* 接管已退出且全部封存的精确租约，按后代优先顺序调用受信清理回调。
+* 回调通过当前根凭证嵌套普通租约，但不能遗留新登记或改变 scope。
+* 失败保留新持有者与未完成 scope，待恢复进程退出后凭新快照重试。
+* 接管中断保留原快照审计；进程崩溃留下的变更锁或混合归属不自动修复。
+*/
+async function recoverMachineE2ELease(options) {
+	const state = machineStateDirectory(options);
+	const directory = path.join(state, "machine-e2e");
+	const expected = structuredClone(options.expected);
+	const owner = {
+		pid: process.pid,
+		token: randomUUID()
+	};
+	const auditFile = path.join(state, "machine-e2e-recoveries", `${owner.token}.jsonl`);
+	const adopted = {
+		...expected,
+		owner,
+		scopes: expected.scopes.map((scope) => ({
+			...scope,
+			owner
+		}))
+	};
+	const record = (event) => appendFile(auditFile, `${JSON.stringify({
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		...event
+	})}\n`, { mode: 384 });
+	await mutateLease(directory, async () => {
+		await assertMachineSnapshot(directory, expected);
+		assertSnapshotStopped(expected, true);
+		await mkdir(path.dirname(auditFile), {
+			recursive: true,
+			mode: 448
+		});
+		await assertRecoveryNode(path.dirname(auditFile), "directory");
+		await writeFile(auditFile, `${JSON.stringify({
+			event: "adopting",
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			expected,
+			owner
+		})}\n`, {
+			mode: 384,
+			flag: "wx"
+		});
+		for (const scope of adopted.scopes) {
+			const { id, ...value } = scope;
+			await writeFile(path.join(directory, "scopes", `${id}.json`), JSON.stringify(value), { mode: 384 });
+		}
+		await writeFile(path.join(directory, "owner.json"), JSON.stringify(owner), { mode: 384 });
+		await record({ event: "adopted" });
+	});
+	let snapshot = adopted;
+	const recoveredScopes = [];
+	const lease = {
+		borrowed: false,
+		released: false,
+		environment: { [INHERITED_LEASE_ENV]: JSON.stringify(owner) },
+		createChildScope: async () => {
+			throw new Error("Recovery callbacks must not create command scopes.");
+		},
+		release: () => mutateLease(directory, async () => {
+			await assertMachineSnapshot(directory, snapshot);
+			if (snapshot.scopes.some((scope) => !scope.completed)) throw new Error("Machine lease recovery cannot release incomplete scopes.");
+			await record({
+				event: "releasing",
+				recoveredScopes
+			});
+			await rm(directory, { recursive: true });
+			lease.released = true;
+		})
+	};
+	try {
+		await withMachineLeaseContext(lease, async () => {
+			const pending = adopted.scopes.filter((scope) => !scope.completed).sort((a, b) => b.ancestors.length - a.ancestors.length);
+			for (const scope of pending) {
+				await mutateLease(directory, () => assertMachineSnapshot(directory, snapshot));
+				const context = {
+					directory,
+					snapshot,
+					scope: recoveryScopeCopy(scope),
+					active: true,
+					operations: /* @__PURE__ */ new Set()
+				};
+				let failure;
+				try {
+					await currentRecovery.run(context, () => options.recoverScope(context.scope));
+				} catch (error) {
+					failure = { error };
+				} finally {
+					context.active = false;
+				}
+				const unfinished = [...context.operations];
+				if (unfinished.length) await Promise.allSettled(unfinished);
+				if (failure) throw failure.error;
+				if (unfinished.length) throw new Error("Machine lease recovery callback ended with unfinished recovery operations; preserving its incomplete scope.");
+				await mutateLease(directory, async () => {
+					await assertMachineSnapshot(directory, snapshot);
+					const { id, ...value } = scope;
+					await writeFile(path.join(directory, "scopes", `${id}.json`), JSON.stringify({
+						...value,
+						completed: true
+					}), { mode: 384 });
+					snapshot = {
+						...snapshot,
+						scopes: snapshot.scopes.map((item) => item.id === id ? {
+							...item,
+							completed: true
+						} : item)
+					};
+					recoveredScopes.push(id);
+					await record({
+						event: "scope-completed",
+						scopeId: id
+					});
+				});
+			}
+			await lease.release();
+		}, options);
+		return {
+			auditFile,
+			recoveredScopes
+		};
+	} catch (error) {
+		await record({
+			event: "failed",
+			error: error instanceof Error ? error.message : String(error)
+		}).catch(() => {});
+		throw error;
+	}
+}
+//#endregion
 //#region src/index.ts
 const sharedMiniProgramSessions = /* @__PURE__ */ new Map();
 function normalizeError(hooks, error) {
@@ -6,13 +822,27 @@ function normalizeError(hooks, error) {
 	return normalized instanceof Error ? normalized : new Error(String(normalized));
 }
 function resolveSharedMiniProgramSessionKey(options) {
-	const sessionSuffix = options.sessionId || (options.port ? `port:${options.port}` : "default");
-	return `${options.projectPath}#${sessionSuffix}`;
+	const installation = options.installationId || options.cliPath || options.runtimeProvider || "unresolved";
+	return JSON.stringify([
+		installation,
+		options.projectPath,
+		options.sessionId || null,
+		options.port || null
+	]);
+}
+function resolveExistingSessionKey(options) {
+	const matching = [...sharedMiniProgramSessions].filter(([, entry]) => {
+		const current = entry.options;
+		const sessionMatches = options.sessionId ? current.sessionId === options.sessionId && (!options.port || current.port === options.port) : !current.sessionId && current.port === options.port;
+		return (!options.installationId || current.installationId === options.installationId) && (!options.cliPath || current.cliPath === options.cliPath) && (!options.runtimeProvider || current.runtimeProvider === options.runtimeProvider) && current.projectPath === options.projectPath && sessionMatches;
+	});
+	return matching.length === 1 ? matching[0][0] : void 0;
 }
 /**
 * @description 获取指定项目的共享 automator 会话；若不存在则自动创建。
 */
 async function acquireSharedMiniProgram(hooks, options) {
+	options = await hooks.resolveSessionOptions?.(options) ?? options;
 	const sessionKey = resolveSharedMiniProgramSessionKey(options);
 	const existing = sharedMiniProgramSessions.get(sessionKey);
 	if (existing) {
@@ -22,39 +852,52 @@ async function acquireSharedMiniProgram(hooks, options) {
 	const session = hooks.connectMiniProgram(options);
 	const entry = {
 		refs: 1,
+		options,
 		session
 	};
 	sharedMiniProgramSessions.set(sessionKey, entry);
 	try {
 		return await session;
 	} catch (error) {
-		sharedMiniProgramSessions.delete(sessionKey);
+		if (sharedMiniProgramSessions.get(sessionKey) === entry) sharedMiniProgramSessions.delete(sessionKey);
 		throw normalizeError(hooks, error);
 	}
 }
+/** 使用创建连接时的精确键释放订阅。 */
+function releaseSharedMiniProgramByKey(sessionKey) {
+	const entry = sharedMiniProgramSessions.get(sessionKey);
+	if (entry) {
+		entry.refs = Math.max(0, entry.refs - 1);
+		if (entry.refs === 0 && entry.closeWhenUnused) {
+			sharedMiniProgramSessions.delete(sessionKey);
+			entry.session.then((program) => program.disconnect()).catch(() => void 0);
+		}
+	}
+}
 /**
 * @description 释放指定项目的共享会话引用；会话对象会继续缓存，直到显式关闭或重置。
 */
-function releaseSharedMiniProgram(projectPath, sessionIdOrPort) {
-	const entry = sharedMiniProgramSessions.get(resolveSharedMiniProgramSessionKey({
+function releaseSharedMiniProgram(projectPath, sessionIdOrPort, installation = {}) {
+	const key = resolveExistingSessionKey({
+		...installation,
 		projectPath,
 		...typeof sessionIdOrPort === "number" ? { port: sessionIdOrPort } : {},
 		...typeof sessionIdOrPort === "string" ? { sessionId: sessionIdOrPort } : {}
-	}));
-	if (!entry) return;
-	entry.refs = Math.max(0, entry.refs - 1);
+	});
+	if (key) releaseSharedMiniProgramByKey(key);
 }
 /**
 * @description 关闭并移除指定项目的共享 automator 会话。
 */
-async function closeSharedMiniProgram(projectPath, sessionIdOrPort) {
-	const sessionKey = resolveSharedMiniProgramSessionKey({
+async function closeSharedMiniProgram(projectPath, sessionIdOrPort, installation = {}) {
+	const sessionKey = resolveExistingSessionKey({
+		...installation,
 		projectPath,
 		...typeof sessionIdOrPort === "number" ? { port: sessionIdOrPort } : {},
 		...typeof sessionIdOrPort === "string" ? { sessionId: sessionIdOrPort } : {}
 	});
-	const entry = sharedMiniProgramSessions.get(sessionKey);
-	if (!entry) return;
+	const entry = sessionKey ? sharedMiniProgramSessions.get(sessionKey) : void 0;
+	if (!entry || !sessionKey) return;
 	sharedMiniProgramSessions.delete(sessionKey);
 	(await entry.session.catch(() => null))?.disconnect();
 }
@@ -69,15 +912,16 @@ function getSharedMiniProgramSessionCount() {
 */
 async function withMiniProgram(hooks, options, runner) {
 	if (options.miniProgram) return await runner(options.miniProgram);
+	options = await hooks.resolveSessionOptions?.(options) ?? options;
 	if (options.sharedSession) {
 		const miniProgram = await acquireSharedMiniProgram(hooks, options);
 		try {
 			return await runner(miniProgram);
 		} catch (error) {
-			await closeSharedMiniProgram(options.projectPath, options.sessionId || options.port);
+			await closeSharedMiniProgram(options.projectPath, options.sessionId || options.port, options);
 			throw normalizeError(hooks, error);
 		} finally {
-			releaseSharedMiniProgram(options.projectPath, options.sessionId || options.port);
+			releaseSharedMiniProgram(options.projectPath, options.sessionId || options.port, options);
 		}
 	}
 	let miniProgram = null;
@@ -90,5 +934,28 @@ async function withMiniProgram(hooks, options, runner) {
 		if (miniProgram) miniProgram.disconnect();
 	}
 }
+/** 检查缓存，供调用方记录其实际创建的连接。 */
+function hasSharedMiniProgram(options) {
+	return sharedMiniProgramSessions.has(resolveSharedMiniProgramSessionKey(options));
+}
+/** 只清理仍由调用方创建、且已无活动引用的连接。 */
+async function closeOwnedSharedMiniProgram(options, owned) {
+	const key = resolveSharedMiniProgramSessionKey(options);
+	const entry = sharedMiniProgramSessions.get(key);
+	if (!entry) return;
+	const program = await entry.session.catch(() => null);
+	if (program !== owned || sharedMiniProgramSessions.get(key) !== entry) return;
+	if (entry.refs !== 0) {
+		entry.closeWhenUnused = true;
+		return;
+	}
+	sharedMiniProgramSessions.delete(key);
+	program?.disconnect();
+}
+/** 单独保留管理器订阅，避免与正在执行的操作共享引用计数。 */
+function retainSharedMiniProgram(sessionKey) {
+	const entry = sharedMiniProgramSessions.get(sessionKey);
+	if (entry) entry.refs += 1;
+}
 //#endregion
-export { acquireSharedMiniProgram, closeSharedMiniProgram, getSharedMiniProgramSessionCount, readDevtoolsElementSnapshot, releaseSharedMiniProgram, resolveDevtoolsProjectPath, resolveDevtoolsWorkspacePath, resolveSharedMiniProgramSessionKey, toDevtoolsSerializableValue, withMiniProgram };
+export { acquireMachineE2ELease, acquireRuntimeLease, acquireSharedMiniProgram, assertMachineE2ELeaseRecoveryScope, closeOwnedSharedMiniProgram, closeSharedMiniProgram, getSharedMiniProgramSessionCount, hasSharedMiniProgram, mutateLease, readDevtoolsElementSnapshot, readMachineE2ELeaseSnapshot, recoverMachineE2ELease, releaseSharedMiniProgram, releaseSharedMiniProgramByKey, resolveDevtoolsProjectPath, resolveDevtoolsWorkspacePath, resolveSharedMiniProgramSessionKey, retainSharedMiniProgram, runWithRuntimeLease, toDevtoolsSerializableValue, withMachineE2ELease, withMachineE2ELeaseRecoveryOperation, withMiniProgram, withRuntimeLease };

package/dist/mcp.d.ts

@@ -8,7 +8,12 @@ export type AutomatorPage = InstanceType<typeof Page>;
 export type AutomatorElement = InstanceType<typeof Element> & {
   input?: (value: string) => Promise<void>;
 };
-export interface DevtoolsRuntimeSessionOptions {
+export interface DevtoolsInstallationContext {
+  cliPath?: string;
+  installationId?: string;
+  runtimeProvider?: 'devtools' | 'headless';
+}
+export interface DevtoolsRuntimeSessionOptions extends DevtoolsInstallationContext {
   miniProgram?: AutomatorMiniProgram;
   openedOnly?: boolean;
   preferOpenedSession?: boolean;
@@ -20,10 +25,14 @@ export interface DevtoolsRuntimeSessionOptions {
   timeout?: number;
 }
 export interface DevtoolsRuntimeHooks {
+  /** 在缓存查找前固定安装上下文，供连接、复用和清理共用。 */
+  resolveSessionOptions?: (options: DevtoolsRuntimeSessionOptions) => Promise<DevtoolsRuntimeSessionOptions>;
+  /** 项目编译后沿用已固定的安装上下文刷新 IDE。 */
+  prepareProject?: (projectPath: string, signal: AbortSignal, options?: DevtoolsInstallationContext) => Promise<unknown>;
   connectMiniProgram: (options: DevtoolsRuntimeSessionOptions) => Promise<AutomatorMiniProgram>;
   normalizeConnectionError?: (error: unknown) => unknown;
 }
-export interface DevtoolsConnectionInput {
+export interface DevtoolsConnectionInput extends DevtoolsInstallationContext {
   projectPath: string;
   timeout?: number;
   openedOnly?: boolean;

package/dist/mcp.js

@@ -1,5 +1,5 @@
-import { Buffer } from "node:buffer";
 import path from "node:path";
+import { Buffer } from "node:buffer";
 //#region src/mcp.ts
 function resolveDevtoolsProjectPath(workspaceRoot, projectPath) {
 	return path.isAbsolute(projectPath) ? path.normalize(projectPath) : path.resolve(workspaceRoot, projectPath);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weapp-vite/devtools-runtime",
   "type": "module",
-  "version": "0.4.24",
+  "version": "0.5.0",
   "description": "Shared WeChat DevTools runtime automation helpers for weapp-vite packages",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -49,13 +49,15 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@weapp-vite/miniprogram-automator": "1.2.23"
+    "@weapp-vite/miniprogram-automator": "1.3.0"
   },
   "scripts": {
     "dev": "tsdown -w --sourcemap",
     "build": "tsdown",
     "test": "vitest run",
     "test:dev": "vitest",
+    "test:types": "pnpm build && pnpm run test:types:check",
+    "test:types:check": "tsd --files \"test-d/**/*.test-d.ts\"",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"