dsh-vscode-mode 0.17.0 → 0.19.0

package/lib/index.js

@@ -3,7 +3,7 @@ import { chmod, copyFile, cp, lstat, mkdir, open, readFile, readdir, realpath, r
 import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
 import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, watch, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
 import { DatabaseSync } from "node:sqlite";
 import { Buffer as Buffer$1 } from "node:buffer";
@@ -295,6 +295,469 @@ function installIsolation(ctx) {
 	syncAll();
 }
 //#endregion
+//#region src/shared/mcp.ts
+/** @public @author ddj 2026年10月20号 @param input Project-only policy. @returns Validated defaults. @throws Invalid explicit policy. */
+function parseMcpPolicy(input) {
+	if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) throw new Error("vscodeMode 必须是对象");
+	const policy = input ?? {};
+	const startup = policy.startup ?? "on-demand";
+	const sharing = policy.sharing ?? "agent";
+	const startupTimeoutMs = policy.startupTimeoutMs ?? 6e4;
+	if (!["on-demand", "background"].includes(startup)) throw new Error("不支持的 MCP startup");
+	if (!["agent", "workspace"].includes(sharing)) throw new Error("不支持的 MCP sharing");
+	if (!Number.isInteger(startupTimeoutMs) || startupTimeoutMs < 1e3 || startupTimeoutMs > 3e5) throw new Error("MCP startupTimeoutMs 必须为 1000–300000 的整数");
+	return {
+		startup,
+		sharing,
+		startupTimeoutMs
+	};
+}
+//#endregion
+//#region src/mcpBridge.ts
+/** Private official-MCP registrations, never a global provider. @author ddj 2026年10月20号 */
+/** Per-agent public surface; original definitions still run inside the normal registry pipeline. */
+var McpBinding = class {
+	agent;
+	pool;
+	entry;
+	valid;
+	called;
+	removals = [];
+	unsubscribe;
+	closed = false;
+	/** @public @author ddj 2026年10月20号 @param agent Public scope. @param pool Connection owner. @param entry Exact generation. @param valid Authorization recheck. */
+	constructor(agent, pool, entry, valid, called) {
+		this.agent = agent;
+		this.pool = pool;
+		this.entry = entry;
+		this.valid = valid;
+		this.called = called;
+	}
+	/** @private @author ddj 2026年10月20号 @param execution Registry caller. @throws Stale generation or foreign caller. */
+	check(execution) {
+		if (this.closed || !this.valid() || !this.entry.live || execution && execution.agent !== this.agent) throw new Error("项目 MCP 作用域或配置已失效");
+	}
+	/** @public @author ddj 2026年10月20号 Reconciles exact definitions after official tool-list updates. */
+	sync() {
+		this.check();
+		const bridge = this.entry.bridge;
+		if (!bridge) return;
+		this.clear();
+		for (const [name, definition] of bridge.tools) {
+			/** @author ddj 2026年10月20号 @param args Registry-validated arguments. @param execution Unmodified caller context. @returns Official canonical output. */
+			const execute = async (args, execution) => {
+				this.check(execution);
+				return this.pool.run(this.entry, async () => {
+					this.check(execution);
+					if (bridge.tools.get(name) !== definition) throw new Error("MCP 工具定义已更新，请重新发现");
+					const startedAt = Date.now();
+					const result = await definition.execute(args, execution);
+					this.called?.(Date.now() - startedAt);
+					return result;
+				}, execution.signal);
+			};
+			this.removals.push(this.agent.ctx.get("tools").register({
+				...definition,
+				execute
+			}));
+		}
+		for (const section of bridge.sections.values()) {
+			/** @author ddj 2026年10月20号 @param context Actual prompt assembly. @returns Only valid-generation instructions. */
+			const text = (context) => {
+				if (!this.valid() || this.closed) return "";
+				if (typeof section.text === "function") return section.text(context);
+				return section.text;
+			};
+			this.removals.push(this.agent.ctx.get("systemPrompt").section({
+				...section,
+				text
+			}));
+		}
+		/** @author ddj 2026年10月20号 Reconciles dynamic official registrations only for a live subscriber. */
+		const update = () => {
+			if (!this.closed && this.valid() && this.entry.live) this.sync();
+		};
+		if (!this.unsubscribe) this.unsubscribe = bridge.subscribe(update);
+	}
+	/** @private @author ddj 2026年10月20号 Removes only this binding's exact scoped registrations. */
+	clear() {
+		for (const remove of this.removals.splice(0).reverse()) remove();
+	}
+	/** @public @author ddj 2026年10月20号 Revokes proxies synchronously before releasing a lease. */
+	dispose() {
+		this.closed = true;
+		this.unsubscribe?.();
+		this.unsubscribe = void 0;
+		this.clear();
+	}
+};
+/** A connection's private surface. Public consumers register scoped proxies, not this scope. */
+var McpBridge = class McpBridge {
+	scope;
+	tools = /* @__PURE__ */ new Map();
+	resources = /* @__PURE__ */ new Map();
+	sections = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	closed = false;
+	closing;
+	/** @private @author ddj 2026年10月20号 @param scope Private lifetime and registration context. */
+	constructor(scope) {
+		this.scope = scope;
+	}
+	/** @public @author ddj 2026年10月20号 @param ctx Host owner. @param make Optional real scope factory for installed-host tests. @returns Isolated registration adapter. */
+	static async create(ctx, make) {
+		const scope = (make ?? (await loadHostModule("@deepseek-ai/dsh-scope")).createScope)(ctx, {});
+		await scope.ctx.fiber?.await?.();
+		const bridge = new McpBridge(scope);
+		bridge.install();
+		return bridge;
+	}
+	/** @private @author ddj 2026年10月20号 Installs only private services; no project registration reaches the root. */
+	install() {
+		const privateCtx = this.scope.ctx.isolate("tools").isolate("mcpResources").isolate("systemPrompt");
+		privateCtx.provide("tools", { register: (definition) => this.register(this.tools, definition.name, definition) });
+		privateCtx.provide("mcpResources", { register: (name, provider) => this.register(this.resources, name, provider) });
+		privateCtx.provide("systemPrompt", {
+			getSectionOrder: () => 3100,
+			section: (section) => this.register(this.sections, section.name, section)
+		});
+		this.scope.ctx = privateCtx;
+	}
+	/** @private @author ddj 2026年10月20号 @param registry Private generation map. @param name Stable registration name. @param entry Exact value. @returns Exact-entry removal, safe after replacement. */
+	register(registry, name, entry) {
+		if (this.closed) throw new Error("MCP bridge is disposed");
+		if (registry.has(name)) throw new Error("Duplicate private MCP registration: " + name);
+		registry.set(name, entry);
+		this.changed();
+		return () => {
+			if (registry.get(name) !== entry) return;
+			registry.delete(name);
+			this.changed();
+		};
+	}
+	/** @public @author ddj 2026年10月20号 @param listener Surface change subscriber. @returns Subscription disposer. */
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/** @private @author ddj 2026年10月20号 Notifies consumers; observer errors cannot corrupt the official sync transaction. */
+	changed() {
+		for (const listener of this.listeners) try {
+			listener();
+		} catch {}
+	}
+	/** @public @author ddj 2026年10月20号 @returns Quiescent private-scope teardown. */
+	dispose() {
+		this.closed = true;
+		return this.closing ??= this.closeScope();
+	}
+	/** @private @author ddj 2026年10月20号 @returns Exact scope closure before forgetting registrations. */
+	async closeScope() {
+		await this.scope.dispose();
+		this.tools.clear();
+		this.resources.clear();
+		this.sections.clear();
+		this.changed();
+		this.listeners.clear();
+	}
+};
+//#endregion
+//#region src/mcpPool.ts
+/** Connection ownership, bounded cold starts and workspace leases. @author ddj 2026年10月20号 */
+/** @private @author ddj 2026年10月20号 @param input Plain effective configuration. @returns Stable secret-bearing identity used only as digest input. */
+function stableConfig(input) {
+	if (Array.isArray(input)) return "[" + input.map(stableConfig).join(",") + "]";
+	if (input && typeof input === "object") {
+		const config = input;
+		return "{" + Object.keys(config).sort().map((key) => JSON.stringify(key) + ":" + stableConfig(config[key])).join(",") + "}";
+	}
+	return JSON.stringify(input) ?? "null";
+}
+/** @public @author ddj 2026年10月20号 @param task Shared work that must remain alive for other waiters. @param signal One waiter's cancellation. @returns Caller-local wait without abandoning owned pool work. */
+function waitMcp(task, signal) {
+	if (!signal) return task;
+	return new Promise((resolve, reject) => {
+		/** @author ddj 2026年10月20号 Rejects only this waiter. */
+		const abort = () => {
+			reject(/* @__PURE__ */ new Error("MCP 等待已取消"));
+		};
+		if (signal.aborted) {
+			abort();
+			return;
+		}
+		signal.addEventListener("abort", abort, { once: true });
+		task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+/** The pool owns private scopes independently from any first subscriber. */
+var McpPool = class {
+	ctx;
+	load;
+	make;
+	entries = /* @__PURE__ */ new Map();
+	owners = /* @__PURE__ */ new WeakMap();
+	ownerSeq = 0;
+	running = 0;
+	queue = [];
+	jobs = /* @__PURE__ */ new Set();
+	stopped = false;
+	/** @public @author ddj 2026年10月20号 @param ctx Host lifecycle owner. @param load Official plugin loader. @param make Private scope factory. */
+	constructor(ctx, load, make = () => McpBridge.create(ctx)) {
+		this.ctx = ctx;
+		this.load = load;
+		this.make = make;
+	}
+	/** @private @author ddj 2026年10月20号 @param spec Effective request. @returns Private digest; never emit configuration or secrets. */
+	keyOf(spec) {
+		let owner = 0;
+		if (spec.policy.sharing === "agent") {
+			if (!this.owners.has(spec.owner)) this.owners.set(spec.owner, ++this.ownerSeq);
+			owner = this.owners.get(spec.owner);
+		}
+		const workspace = process.platform === "win32" ? spec.workspace.replace(/\\/g, "/").toLowerCase() : spec.workspace;
+		return createHash("sha256").update(stableConfig([
+			workspace,
+			owner,
+			spec.config,
+			spec.policy
+		])).digest("hex");
+	}
+	/** @public @author ddj 2026年10月20号 @param spec Authorized connection request. @returns Reference-counted single-flight lease. */
+	acquire(spec) {
+		if (this.stopped) throw new Error("MCP runtime is disposed");
+		const key = this.keyOf(spec);
+		let entry = this.entries.get(key);
+		if (entry?.phase === "error" && entry.retryAt !== void 0 && Date.now() >= entry.retryAt && !entry.close) {
+			this.entries.delete(key);
+			entry = void 0;
+		}
+		if (entry && !entry.live) throw new Error(entry.error ?? "MCP 旧连接仍在释放，暂不能创建替代实例");
+		if (!entry) {
+			entry = {
+				key,
+				spec,
+				refs: 0,
+				phase: "queued",
+				queuedAt: Date.now(),
+				phaseAt: Date.now(),
+				ready: Promise.resolve(),
+				live: true,
+				calls: Promise.resolve()
+			};
+			this.entries.set(key, entry);
+			entry.ready = this.schedule(entry);
+			entry.ready.catch(() => void 0);
+		}
+		if (entry.idle) clearTimeout(entry.idle);
+		entry.idle = void 0;
+		entry.refs += 1;
+		let released = false;
+		return {
+			entry,
+			release: () => {
+				if (released) return;
+				released = true;
+				this.release(entry);
+			}
+		};
+	}
+	/** @private @author ddj 2026年10月20号 @param entry New entry. @returns Queued initialization, bounded to two concurrent starts. */
+	schedule(entry) {
+		return new Promise((resolve, reject) => {
+			/** @author ddj 2026年10月20号 Initializes a still-owned queue item. */
+			const run = async () => {
+				try {
+					await this.start(entry);
+					resolve();
+				} catch (error) {
+					reject(error);
+				}
+			};
+			this.queue.push(run);
+			this.pump();
+		});
+	}
+	/** @private @author ddj 2026年10月20号 Advances FIFO work; each task holds its slot until startup or cleanup quiesces. */
+	pump() {
+		while (this.running < 2 && this.queue.length) {
+			const run = this.queue.shift();
+			this.running += 1;
+			const job = run().finally(() => {
+				this.running -= 1;
+				this.jobs.delete(job);
+				this.pump();
+			});
+			this.jobs.add(job);
+		}
+	}
+	/** @private @author ddj 2026年10月20号 @param entry Connection to initialize. @returns Initialization completion, or failure after owned cleanup. */
+	async start(entry) {
+		if (!entry.live || this.stopped) throw new Error("MCP 启动已取消");
+		entry.phase = "loading";
+		entry.phaseAt = Date.now();
+		entry.startAt = entry.phaseAt;
+		let timer;
+		const work = this.mount(entry);
+		const deadline = new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error("MCP 初始化超时")), entry.spec.policy.startupTimeoutMs);
+			timer.unref?.();
+		});
+		try {
+			await Promise.race([work, deadline]);
+			if (!entry.live) throw new Error("MCP 启动已取消");
+			entry.phase = "ready";
+			entry.finishedAt = Date.now();
+			entry.connectedAt = entry.finishedAt;
+		} catch (error) {
+			entry.error = "MCP 初始化失败或超时，请查看 Host 日志";
+			this.ctx.logger?.warn?.("MCP initialization failed: " + String(error));
+			entry.live = false;
+			entry.phase = "stopping";
+			const closing = this.closeBridge(entry);
+			await Promise.allSettled([closing, work]);
+			entry.phase = "error";
+			entry.finishedAt = Date.now();
+			entry.retryAt = Date.now() + 5e3;
+			throw new Error(entry.error);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+	/** @private @author ddj 2026年10月20号 @param entry Owned generation. @returns Official initial sync; never publishes after invalidation. */
+	async mount(entry) {
+		const official = await this.load();
+		if (!entry.live || this.stopped) return;
+		const bridge = await this.make();
+		if (!entry.live || this.stopped) {
+			await bridge.dispose();
+			return;
+		}
+		entry.bridge = bridge;
+		entry.phase = "starting";
+		entry.phaseAt = Date.now();
+		entry.fiber = bridge.scope.ctx.plugin(official, entry.spec.config);
+		await entry.fiber;
+		if (entry.fiber?.state !== void 0 && entry.fiber.state !== 2) throw new Error("MCP 插件未完成激活");
+	}
+	/** @private @author ddj 2026年10月20号 @param entry Connection to close. @returns Shared closure barrier; rejection retains a fenced entry. */
+	async closeBridge(entry) {
+		if (entry.close) return entry.close;
+		const close = entry.bridge?.dispose() ?? Promise.resolve();
+		entry.close = close;
+		try {
+			await close;
+			entry.bridge = void 0;
+			entry.fiber = void 0;
+			entry.close = void 0;
+		} catch (error) {
+			entry.error = "MCP 释放未确认，禁止重建，请查看 Host 日志";
+			this.ctx.logger?.warn?.("MCP cleanup failed: " + String(error));
+			throw error;
+		}
+	}
+	/** @private @author ddj 2026年10月20号 @param entry One lease's owner. Arms workspace-only warm retention. */
+	release(entry) {
+		entry.refs = Math.max(0, entry.refs - 1);
+		if (entry.refs || !entry.live) return;
+		if (entry.spec.policy.sharing === "agent") {
+			this.retire(entry).catch(() => void 0);
+			return;
+		}
+		entry.idle = setTimeout(() => {
+			this.retire(entry).catch(() => void 0);
+		}, 6e4);
+		entry.idle.unref?.();
+	}
+	/** @public @author ddj 2026年10月20号 @param entry Invalid generation. @returns Quiescent close; callers may await before starting a replacement. */
+	async retire(entry) {
+		entry.live = false;
+		entry.phase = "stopping";
+		if (entry.idle) clearTimeout(entry.idle);
+		await this.closeBridge(entry);
+		await entry.ready.catch(() => void 0);
+		await entry.calls.catch(() => void 0);
+		if (this.entries.get(entry.key) === entry) this.entries.delete(entry.key);
+	}
+	/** @public @author ddj 2026年10月20号 @param entry Authorized connection. @param action Per-call work retaining original execution identity. @param signal Caller cancellation. @returns Serialized shared result; no direct registry bypass is introduced here. */
+	run(entry, action, signal) {
+		/** @author ddj 2026年10月20号 Checks cancellation and generation again at actual dispatch. */
+		const invoke = async () => {
+			await waitMcp(entry.ready, signal);
+			if (signal?.aborted || !entry.live || entry.phase !== "ready") throw new Error("MCP 连接不可用或调用已取消");
+			return action();
+		};
+		const result = entry.calls.then(invoke);
+		entry.calls = result.catch(() => void 0);
+		return result;
+	}
+	/** @public @author ddj 2026年10月20号 @returns Full disposal of entries, queue, timers and owned work. */
+	async dispose() {
+		this.stopped = true;
+		await Promise.all([...this.entries.values()].map((entry) => this.retire(entry)));
+		await Promise.all([...this.jobs]);
+	}
+};
+//#endregion
+//#region src/mcpDiscover.ts
+/** @public @author ddj 2026年10月20号 @param runtime Authorized runtime. @param ctx Host registration context. @returns Global discovery cleanup; normal capability filters remain authoritative. */
+function installDiscover(runtime, ctx) {
+	const tools = ctx.get("tools");
+	/** @author ddj 2026年10月20号 @param args Validated operation. @param execution Registry-owned caller identity. @returns Safe capability catalogue or real connected schemas. */
+	const execute = async (args, execution) => {
+		const agent = execution.agent;
+		if (!agent || !runtime.agents.has(agent)) throw new Error("会话未激活，不能使用项目 MCP 发现入口");
+		if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some((key) => !["action", "serverName"].includes(key))) throw new Error("发现入口仅接受 action 和 serverName");
+		if (!["list", "connect"].includes(args.action)) throw new Error("action 必须为 list 或 connect");
+		if (args.action === "list") return runtime.catalogue(agent);
+		if (typeof args.serverName !== "string") throw new Error("请指定已配置的 serverName");
+		return runtime.connect(agent, args.serverName, execution.signal);
+	};
+	/** @author ddj 2026年10月20号 @param _args Unused. @param result Safe canonical JSON. @returns Native content without bypassing output validation. */
+	const render = (_args, result) => [{
+		type: "text",
+		text: JSON.stringify(result)
+	}];
+	return tools.register({
+		name: "discover_project_mcp",
+		description: "List this workspace’s configured project MCP services without starting them, or connect one to discover its real tools. After connecting, call discovered tools in the NEXT request/program; never guess schemas. Global/preset MCPs are not included.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: {
+					type: "string",
+					enum: ["list", "connect"]
+				},
+				serverName: { type: "string" }
+			},
+			required: ["action"],
+			additionalProperties: false
+		},
+		output: {
+			schema: {},
+			render
+		},
+		execute
+	});
+}
+/** @public @author ddj 2026年10月20号 @param runtime Active owners. @param agent Scoped catalogue owner. @returns Scoped instruction cleanup; does not register a tool override. */
+function discoverPrompt(runtime, agent) {
+	const prompt = agent.ctx.get("systemPrompt");
+	/** @author ddj 2026年10月20号 @returns Current enabled names only; no credential-bearing configuration. */
+	const text = () => {
+		const names = runtime.catalogue(agent).map((server) => server.serverName);
+		if (!names.length) return "";
+		return "Project MCP capabilities (may not be started): " + JSON.stringify(names) + ". Use discover_project_mcp action=list, then action=connect with serverName when needed. Only use returned real tool schemas. Native tools appear on the next model request; PTC must finish the current program and start a new program to refresh its SDK. Do not eval or bypass tool approval.";
+	};
+	return prompt.section({
+		name: "vscode-mode:project-mcp",
+		order: 3090,
+		text,
+		interpolate: false
+	});
+}
+//#endregion
 //#region src/shared/diff.ts
 /** 统一取对应 hunk；callHunk 只用于旧记录缺失 hunks 时兼容。 */
 function preciseHunk(record, idx) {
@@ -2245,22 +2708,13 @@ async function archiveRecords(ctx, session, cwd, bucket, recs, reason, opts) {
 }
 //#endregion
 //#region src/mcpRuntime.ts
-/** Agent-owned project MCP fibers. @author ddj 2026年09月28号 */
+/** Project-owned MCP connections and scoped on-demand capabilities. @author ddj 2026年10月20号 */
 const runtimes = /* @__PURE__ */ new WeakMap();
-/**
-* Load the official plugin from the running host's installation tree.
-* @private @author ddj 2026年09月28号
-* @returns Official MCP plugin namespace; rejects if the host package is absent.
-*/
+/** @private @author ddj 2026年09月28号 @returns Official namespace from the running Host installation. */
 async function loadMcp() {
 	return loadHostModule(MCP_PACKAGE);
 }
-/**
-* Resolve one runtime per host, shared by lifecycle and RPC contexts.
-* @public @author ddj 2026年09月28号
-* @param ctx Host context.
-* @returns Lazy runtime; allocating it does not start connections.
-*/
+/** @public @author ddj 2026年09月28号 @param ctx Host context. @returns Lazy per-host runtime, without opening connections. */
 function runtimeOf(ctx) {
 	const owner = ctx.root ?? ctx;
 	let runtime = runtimes.get(owner);
@@ -2270,178 +2724,273 @@ function runtimeOf(ctx) {
 	}
 	return runtime;
 }
-/** Agent -> server -> fiber ledger. Configuration alone never opens a connection. */
+/** The pool owns transports; each agent owns only revocable public capabilities and leases. */
 var McpRuntime = class {
 	ctx;
 	load;
 	projects = /* @__PURE__ */ new Map();
 	agents = /* @__PURE__ */ new Map();
-	tail = Promise.resolve();
+	pool;
 	stopped = false;
+	offDiscover;
 	retired = /* @__PURE__ */ new WeakSet();
 	module;
-	/**
-	* Create an idle ledger with an injectable official-plugin resolver.
-	* @public @author ddj 2026年09月28号
-	* @param ctx Host services and lifecycle owner.
-	* @param load Official module resolver, replaceable in targeted tests.
-	*/
-	constructor(ctx, load = loadMcp) {
+	pending = /* @__PURE__ */ new Set();
+	barriers = /* @__PURE__ */ new Map();
+	/** @public @author ddj 2026年10月20号 @param ctx Host services. @param load Official module resolver. @param make Optional controlled private-scope factory for tests. */
+	constructor(ctx, load = loadMcp, make) {
 		this.ctx = ctx;
 		this.load = load;
+		this.pool = new McpPool(ctx, () => this.getModule(), make);
 	}
-	/**
-	* Serialize reconfiguration and creation; a failed operation cannot poison the queue.
-	* @private @author ddj 2026年09月28号
-	* @param action Mutation to execute while the runtime remains live.
-	* @returns Completion of this mutation, including official startup readiness.
-	*/
-	enqueue(action) {
-		const run = async () => {
-			if (!this.stopped) await action();
-		};
-		const next = this.tail.then(run);
-		this.tail = next.catch(() => void 0);
-		return next;
+	/** @private @author ddj 2026年10月20号 @param task Owned background operation. Tracks failures without abandoning work. */
+	track(task) {
+		this.pending.add(task);
+		task.catch((error) => this.ctx.logger?.warn?.("Project MCP task failed: " + String(error))).finally(() => this.pending.delete(task));
 	}
-	/**
-	* Find the longest registered workspace containing an agent's cwd.
-	* @public @author ddj 2026年09月28号
-	* @param agent Live agent.
-	* @returns Registered workspace path, or undefined outside managed workspaces.
-	*/
+	/** @private @author ddj 2026年10月20号 @param agent Scope owner. @returns Live record; retired agents cannot be resurrected. */
+	recordOf(agent) {
+		if (this.stopped || this.retired.has(agent)) return void 0;
+		let record = this.agents.get(agent);
+		if (!record) {
+			record = {
+				instances: /* @__PURE__ */ new Map(),
+				resources: /* @__PURE__ */ new Map(),
+				requested: /* @__PURE__ */ new Set(),
+				live: true,
+				tail: Promise.resolve(),
+				startedAt: Date.now()
+			};
+			this.agents.set(agent, record);
+		}
+		return record;
+	}
+	/** @public @author ddj 2026年10月20号 @param agent Newly created scope. Starts only configuration timing. */
+	prepare(agent) {
+		this.recordOf(agent);
+	}
+	/** @public @author ddj 2026年10月20号 @param agent Owner. @param error Configuration failure, never sent raw to clients. */
+	configError(agent, error) {
+		const record = this.recordOf(agent);
+		if (record) record.error = error === void 0 ? void 0 : "项目 MCP 配置读取或校验失败，保留最后有效配置；请查看 Host 日志";
+	}
+	/** @public @author ddj 2026年09月28号 @param agent Agent identity. @returns Longest registered workspace containing its cwd. */
 	workspace(agent) {
 		const paths = (this.ctx.get("workspaceRegistry")?.list?.() ?? []).map((ws) => ws.path);
 		return matchWorkspace(cwdOfSession(this.ctx, agent?.session) ?? void 0, paths);
 	}
-	/**
-	* Read configured server ownership, including disabled definitions.
-	* @public @author ddj 2026年09月28号
-	* @returns Server name to workspace mapping.
-	*/
+	/** @public @author ddj 2026年09月28号 @returns Configured namespaces including disabled definitions. */
 	owners() {
 		const names = /* @__PURE__ */ new Map();
 		for (const record of this.agents.values()) for (const [name, instance] of record.instances) names.set(name, instance.path);
 		for (const [path, defs] of this.projects) for (const name of defs.keys()) names.set(name, path);
 		return names;
 	}
-	/**
-	* Publish ownership changes before any provider can become visible.
-	* @private @author ddj 2026年09月28号
-	* @sideEffects Refreshes agent restrictions and scoped prompt shadows synchronously.
-	*/
+	/** @private @author ddj 2026年10月20号 @param def Effective definition. @returns Config and policy generation identity. */
+	defKey(def) {
+		return JSON.stringify([def.config, parseMcpPolicy(def.policy)]);
+	}
+	/** @private @author ddj 2026年09月28号 Refreshes existing isolation restrictions synchronously. */
 	changed() {
 		this.ctx.emit?.("vscode-mode/mcp-change");
 	}
-	/**
-	* Replace one validated file snapshot and update its active agents.
-	* @public @author ddj 2026年09月28号
-	* @param path Registered workspace path.
-	* @param defs Validated source definitions.
-	* @param refresh Optional server whose unchanged fiber must also be recreated.
-	* @returns Completion after old fibers close and replacement startups settle.
-	*/
-	replace(path, defs, refresh) {
+	/** @private @author ddj 2026年10月20号 @param instance Public lease to revoke. Revokes synchronously before lease release. */
+	revoke(instance) {
+		instance.binding.dispose();
+		instance.lease.release();
+	}
+	/** @public @author ddj 2026年10月20号 @param path Owner workspace. @param defs Validated snapshot. @param refresh Optional explicitly invalidated service. @param wait Await configuration cleanup, never connection readiness. @returns Publication and optionally cleanup completion. */
+	async replace(path, defs, refresh, wait = true) {
+		if (this.stopped) return;
+		const previous = this.projects.get(path);
+		if (!refresh && previous && JSON.stringify([...previous]) === JSON.stringify([...defs])) return;
+		this.projects.set(path, defs);
+		const closing = /* @__PURE__ */ new Set();
+		for (const [agent, record] of this.agents) for (const [name, instance] of record.instances) {
+			const def = defs.get(name);
+			if (instance.path !== path) continue;
+			if (this.workspace(agent) === path && def?.enabled && this.defKey(def) === instance.key && name !== refresh) continue;
+			record.instances.delete(name);
+			this.revoke(instance);
+			closing.add(instance.lease.entry);
+		}
+		for (const entry of this.pool.entries.values()) {
+			if (entry.spec.workspace !== path) continue;
+			const def = defs.get(entry.spec.config.serverName);
+			const config = def && this.options(def.config, path);
+			if (!def?.enabled || JSON.stringify(config) !== JSON.stringify(entry.spec.config) || JSON.stringify(parseMcpPolicy(def.policy)) !== JSON.stringify(entry.spec.policy) || entry.spec.config.serverName === refresh) closing.add(entry);
+		}
+		const prior = this.barriers.get(path) ?? Promise.resolve();
+		const cleanup = Promise.all([...closing].map((entry) => this.pool.retire(entry))).then(() => void 0);
+		const barrier = Promise.all([prior, cleanup]).then(() => void 0);
+		this.barriers.set(path, barrier);
+		this.track(barrier);
+		this.changed();
+		const updates = [...this.agents].map(([agent, record]) => this.enqueue(agent, record));
+		if (wait) await Promise.all([barrier, ...updates]);
+	}
+	/** @private @author ddj 2026年10月20号 @param agent Owner. @param record Lightweight queue. @returns Scoped catalogue/resource update, not transport initialization. */
+	enqueue(agent, record) {
 		const update = async () => {
-			this.projects.set(path, defs);
-			this.changed();
-			for (const [agent, record] of this.agents) await this.syncAgent(agent, record, this.workspace(agent) === path ? refresh : void 0);
-			this.changed();
+			if (!record.live || this.stopped) return;
+			this.syncAgent(agent, record);
 		};
-		return this.enqueue(update);
+		const task = record.tail.then(update);
+		record.tail = task.catch(() => {
+			record.error = "MCP 清理或入口更新失败，请查看 Host 日志";
+		});
+		this.track(task);
+		return task;
 	}
-	/**
-	* Attach an agent once and await its project plugin startups.
-	* @public @author ddj 2026年09月28号
-	* @param agent Created or already-active agent.
-	* @returns Completion suitable for the serial agent/created listener.
-	*/
+	/** @public @author ddj 2026年10月20号 @param agent Live agent. @returns Lightweight capability installation; never waits for MCP startup. */
 	attach(agent) {
-		if (this.stopped || this.retired.has(agent)) return Promise.resolve();
-		let record = this.agents.get(agent);
-		if (!record) {
-			record = {
-				instances: /* @__PURE__ */ new Map(),
-				live: true
-			};
-			this.agents.set(agent, record);
+		const record = this.recordOf(agent);
+		if (!record) return Promise.resolve();
+		this.offDiscover ??= installDiscover(this, this.ctx);
+		if (!record.remove) record.remove = discoverPrompt(this, agent);
+		return this.enqueue(agent, record);
+	}
+	/** @private @author ddj 2026年10月20号 @param agent Owner. @param record Scope record. Updates lazy resources and schedules explicit background services. */
+	syncAgent(agent, record) {
+		const path = this.workspace(agent);
+		const defs = this.projects.get(path ?? "") ?? /* @__PURE__ */ new Map();
+		for (const [name, instance] of record.instances) {
+			const def = defs.get(name);
+			if (instance.path === path && def?.enabled && this.defKey(def) === instance.key) continue;
+			record.instances.delete(name);
+			this.revoke(instance);
 		}
-		const target = record;
-		const attach = async () => {
-			await this.syncAgent(agent, target);
-			this.changed();
+		for (const remove of record.resources.values()) remove();
+		record.resources.clear();
+		for (const [name, def] of defs) {
+			if (!def.enabled) continue;
+			this.lazyResource(agent, record, name);
+			if (!record.instances.has(name) && (parseMcpPolicy(def.policy).startup === "background" || record.requested.has(name))) this.track(this.connect(agent, name));
+		}
+		record.finishedAt ??= Date.now();
+		this.changed();
+	}
+	/** @private @author ddj 2026年10月20号 @param agent Owner. @param record Ledger. @param name Enabled namespace. Installs a resource-only on-demand entry without starting a connection. */
+	lazyResource(agent, record, name) {
+		const resources = agent.ctx.get("mcpResources");
+		/** @author ddj 2026年10月20号 @param request Resource operation. @param execution Actual registry caller. @returns Official provider result after demand connection. */
+		const request = async (request, execution) => {
+			if (execution?.agent !== agent) throw new Error("不能借用其他会话的 MCP 资源");
+			await this.connect(agent, name, execution.signal);
+			const instance = record.instances.get(name);
+			if (!instance || !this.valid(agent, record, name, instance)) throw new Error("项目 MCP 配置已失效");
+			return this.pool.run(instance.lease.entry, async () => {
+				if (!this.valid(agent, record, name, instance)) throw new Error("项目 MCP 配置已失效");
+				const provider = instance.lease.entry.bridge?.resources.get(name);
+				if (!provider) throw new Error("MCP 未提供资源入口");
+				const startedAt = Date.now();
+				const result = await provider.request(request, execution);
+				instance.firstCallMs ??= Date.now() - startedAt;
+				return result;
+			}, execution.signal);
 		};
-		return this.enqueue(attach);
+		record.resources.set(name, resources.register(name, { request }));
 	}
-	/**
-	* Dispose a single connection before releasing its ledger slot.
-	* @private @author ddj 2026年09月28号
-	* @param record Agent ledger.
-	* @param name Server name to stop.
-	* @returns Awaitable Cordis teardown; failures remain visible to the caller.
-	*/
-	async stopOne(record, name) {
-		const instance = record.instances.get(name);
-		if (instance) await this.stopFiber(instance);
-		if (record.instances.get(name) === instance) record.instances.delete(name);
+	/** @private @author ddj 2026年10月20号 @param agent Owner. @param record Ledger. @param name Namespace. @param instance Exact lease. @returns Whether a previously issued proxy can still execute. */
+	valid(agent, record, name, instance) {
+		const path = this.workspace(agent);
+		const def = this.projects.get(path ?? "")?.get(name);
+		return !this.stopped && record.live && record.instances.get(name) === instance && instance.path === path && def?.enabled === true && this.defKey(def) === instance.key;
+	}
+	/** @private @author ddj 2026年10月20号 @param config Official config. @param path Default working directory. @returns Detached effective config; project strategy is never forwarded. */
+	options(config, path) {
+		return config.transport === "stdio" ? {
+			...config,
+			cwd: config.cwd || path
+		} : { ...config };
+	}
+	/** @public @author ddj 2026年10月20号 @param agent Actual execution owner. @returns Safe enabled catalogue without opening connections. */
+	catalogue(agent) {
+		const record = this.agents.get(agent);
+		if (!record?.live || this.stopped) return [];
+		return [...this.projects.get(this.workspace(agent) ?? "") ?? []].filter(([, def]) => def.enabled).map(([serverName]) => {
+			const entry = record.instances.get(serverName)?.lease.entry;
+			return {
+				serverName,
+				phase: entry?.fiber?.state === 3 ? "error" : entry?.phase ?? "idle"
+			};
+		});
 	}
-	/**
-	* Await exact fiber teardown, including a disposer already claimed by its owning scope.
-	* @private @author ddj 2026年09月28号
-	* @param instance Connection ledger entry.
-	* @returns Shared completion of asynchronous Cordis effects.
-	*/
-	stopFiber(instance) {
-		const close = async () => {
-			const fiber = instance.fiber;
-			await fiber?.dispose();
-			while (fiber?.inertia !== void 0) await fiber.inertia;
+	/** @private @author ddj 2026年10月20号 @param agent Owner. @param record Ledger. @param path Workspace. @param name Namespace. @param def Validated definition. @returns Synchronously reserved lease and public binding. */
+	reserve(agent, record, path, name, def) {
+		const lease = this.pool.acquire({
+			workspace: path,
+			owner: agent,
+			config: this.options(def.config, path),
+			policy: parseMcpPolicy(def.policy)
+		});
+		const instance = {
+			key: this.defKey(def),
+			path,
+			lease,
+			startedAt: Date.now(),
+			reused: lease.entry.refs > 1 || lease.entry.phase === "ready"
 		};
-		return instance.stopping ??= close();
+		const valid = () => this.valid(agent, record, name, instance);
+		instance.binding = new McpBinding(agent, this.pool, lease.entry, valid, (elapsed) => {
+			instance.firstCallMs ??= elapsed;
+		});
+		record.instances.set(name, instance);
+		instance.ready = lease.entry.ready.then(() => {
+			if (!valid()) throw new Error("项目 MCP 配置已失效");
+			instance.binding.sync();
+			this.changed();
+		});
+		this.track(instance.ready);
+		return instance;
 	}
-	/**
-	* Cancel and drain every fiber owned by a disposed agent.
-	* @public @author ddj 2026年09月28号
-	* @param agent Disposed agent.
-	* @returns Completion of connection cleanup.
-	*/
+	/** @public @author ddj 2026年10月20号 @param agent Actual active caller. @param name Enabled configured server. @param signal Caller-local cancellation. @returns Real tool schemas after private initial sync; no guessed tools. */
+	async connect(agent, name, signal) {
+		const record = this.agents.get(agent);
+		if (!record?.live || this.stopped) throw new Error("会话未激活，不能连接项目 MCP");
+		await waitMcp(record.tail, signal);
+		const path = this.workspace(agent);
+		await waitMcp(this.barriers.get(path ?? "") ?? Promise.resolve(), signal);
+		if (!record.live || this.workspace(agent) !== path) throw new Error("项目 MCP 作用域已失效");
+		const def = this.projects.get(path ?? "")?.get(name);
+		if (!def?.enabled || !path) throw new Error("当前工作区未启用该项目 MCP");
+		if (entriesOf(this.ctx).some((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? "")) && entry.options?.config?.serverName === name)) throw new Error("serverName 已被全局 MCP 使用");
+		let instance = record.instances.get(name);
+		if (instance?.lease.entry.phase === "error" && (instance.lease.entry.retryAt ?? Infinity) <= Date.now()) {
+			record.instances.delete(name);
+			this.revoke(instance);
+			instance = void 0;
+		}
+		record.requested.add(name);
+		instance ??= this.reserve(agent, record, path, name, def);
+		await waitMcp(instance.ready, signal);
+		if (!this.valid(agent, record, name, instance)) throw new Error("项目 MCP 配置已失效");
+		const visible = agent.ctx.get("tools")?.view?.(agent)?.visible;
+		return {
+			serverName: name,
+			tools: [...instance.lease.entry.bridge.tools.values()].filter((tool) => visible?.has(tool.name)).map((tool) => ({
+				name: tool.name,
+				description: tool.description,
+				parameters: tool.parameters
+			})),
+			resources: instance.lease.entry.bridge.resources.has(name),
+			nextRequest: "Use these tools in the next model request; PTC must start a new program to refresh its SDK."
+		};
+	}
+	/** @public @author ddj 2026年10月20号 @param agent Disposed owner. @returns Scoped teardown; shared transports remain owned by other leases. */
 	async detach(agent) {
 		this.retired.add(agent);
 		const record = this.agents.get(agent);
 		if (!record) return;
 		record.live = false;
-		await Promise.all([...record.instances.keys()].map((name) => this.stopOne(record, name)));
+		record.remove?.();
+		for (const remove of record.resources.values()) remove();
+		for (const instance of record.instances.values()) this.revoke(instance);
+		record.instances.clear();
 		this.agents.delete(agent);
 		this.changed();
 	}
-	/**
-	* Match the agent ledger to the current enabled definitions.
-	* @private @author ddj 2026年09月28号
-	* @param agent Scoped plugin owner.
-	* @param record Agent ledger.
-	* @param refresh Optional server to reconnect.
-	* @returns Completion of removals and scoped mounts.
-	*/
-	async syncAgent(agent, record, refresh) {
-		if (!record.live || this.stopped) return;
-		const path = this.workspace(agent);
-		const defs = this.projects.get(path ?? "") ?? /* @__PURE__ */ new Map();
-		for (const [name, instance] of record.instances) {
-			const def = defs.get(name);
-			if (def?.enabled && instance.path === path && instance.key === JSON.stringify(def.config) && name !== refresh) continue;
-			await this.stopOne(record, name);
-		}
-		for (const [name, def] of defs) {
-			if (!record.live || this.stopped) break;
-			if (!def.enabled || record.instances.has(name)) continue;
-			await this.mount(agent, record, def.config, path);
-		}
-	}
-	/**
-	* Cache successful module loads while allowing explicit refresh after transient failures.
-	* @private @author ddj 2026年10月08号
-	* @returns Official plugin module; load failures propagate to the instance diagnostic.
-	*/
+	/** @private @author ddj 2026年10月08号 @returns Cached official module; failures are retryable. */
 	async getModule() {
 		const loading = this.module ??= this.load();
 		try {
@@ -2451,100 +3000,113 @@ var McpRuntime = class {
 			throw error;
 		}
 	}
-	/**
-	* Mount the official plugin through agent.ctx; ACTIVE is not connection evidence.
-	* @private @author ddj 2026年09月28号
-	* @param agent Scoped context owner.
-	* @param record Agent ledger.
-	* @param config Validated source config.
-	* @param path Default stdio working directory.
-	* @returns Settled startup; errors are retained for the project status view.
-	*/
-	async mount(agent, record, config, path) {
-		const instance = {
-			key: JSON.stringify(config),
-			path
-		};
-		record.instances.set(config.serverName, instance);
-		try {
-			const officialMcp = await this.getModule();
-			if (!record.live || this.stopped) return;
-			if (entriesOf(this.ctx).find((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? "")) && entry.options?.config?.serverName === config.serverName)) throw new Error("serverName 已被全局 MCP 使用：" + config.serverName);
-			const options = config.transport === "stdio" ? {
-				...config,
-				cwd: config.cwd || path
-			} : { ...config };
-			instance.fiber = agent.ctx.plugin(officialMcp, options);
-			await instance.fiber;
-		} catch (error) {
-			instance.error = String(error);
-			await this.stopFiber(instance);
-			instance.fiber = void 0;
-		}
-	}
-	/**
-	* Build project status from exact agent scopes without assuming ACTIVE means connected.
-	* @public @author ddj 2026年09月28号
-	* @param path Workspace to summarize.
-	* @returns Masked server views, including configured-only and disabled definitions.
-	*/
-	views(path) {
-		return [...this.projects.get(path) ?? /* @__PURE__ */ new Map()].map(([name, def]) => this.serverView(path, name, def));
-	}
-	/**
-	* Summarize one definition and its connection instances across matching agents.
-	* @private @author ddj 2026年09月28号
-	* @param path Owning workspace.
-	* @param name Server name.
-	* @param def Persisted definition.
-	* @returns Honest status and union of tools visible to its agents.
-	*/
-	serverView(path, name, def) {
-		const tools = /* @__PURE__ */ new Map();
-		const instances = [];
+	/** @public @author ddj 2026年10月20号 @returns Detached read-only active session statuses, without IO or activation. */
+	sessionSnapshot() {
+		const sessions = [];
 		for (const [agent, record] of this.agents) {
-			if (this.workspace(agent) !== path) continue;
-			const instance = record.instances.get(name);
-			if (!instance) continue;
-			instances.push(instance);
-			for (const tool of toolsOf(this.ctx, name, agent)) tools.set(tool.name, tool);
+			if (!record.live || typeof agent?.session?.id !== "string") continue;
+			const servers = this.sessionServers(agent, record);
+			const active = servers.find((server) => [
+				"stopping",
+				"starting",
+				"loading",
+				"queued"
+			].includes(server.phase));
+			let phase = "ready";
+			if (record.error || servers.some((server) => server.phase === "error")) phase = "error";
+			else if (active) phase = active.phase;
+			else if (!record.finishedAt) phase = "preparing";
+			else if (!servers.length) phase = "none";
+			else if (servers.some((server) => server.phase === "idle")) phase = "idle";
+			const attempts = servers.filter((server) => server.phase !== "idle");
+			const startedAt = attempts.length ? Math.min(...attempts.map((server) => server.startedAt)) : record.startedAt;
+			sessions.push({
+				configMs: Math.max(0, (record.finishedAt ?? Date.now()) - record.startedAt),
+				sessionId: agent.session.id,
+				phase,
+				startedAt,
+				phaseAt: active?.phaseAt ?? startedAt,
+				finishedAt: active ? void 0 : Math.max(record.finishedAt ?? record.startedAt, ...servers.map((server) => server.finishedAt ?? 0)),
+				error: record.error,
+				servers
+			});
 		}
-		const error = instances.find((item) => item.error)?.error;
-		const fibers = instances.filter((item) => item.fiber);
-		const failed = error || fibers.some((item) => item.fiber.state === 3);
-		const status = !def.enabled ? "disabled" : failed ? "error" : fibers.length === 0 ? "configured" : fibers.some((item) => item.fiber.state === 1 || item.fiber.state === 0) ? "connecting" : "unverified";
 		return {
-			id: projectEntryId(path, name),
-			serverName: name,
-			enabled: def.enabled,
-			transport: def.config.transport,
-			config: publicConfig(def.config),
-			status,
-			instanceCount: fibers.length,
-			toolCount: tools.size,
-			tools: [...tools.values()],
-			error: error || (failed ? "MCP 插件未正常运行" : void 0)
+			sessions,
+			sampledAt: Date.now()
 		};
 	}
-	/**
-	* Close every owned connection and prevent queued work from mounting replacements.
-	* @public @author ddj 2026年09月28号
-	* @returns Completion after connection disposal and pending startup work settle.
-	*/
+	/** @private @author ddj 2026年10月20号 @param agent Owner. @param record Ledger. @returns Server phases with caller-local timing, not pooled connection age. */
+	sessionServers(agent, record) {
+		return this.catalogue(agent).map(({ serverName, phase }) => {
+			const instance = record.instances.get(serverName);
+			if (!instance) return {
+				serverName,
+				phase: "idle",
+				startedAt: record.finishedAt ?? record.startedAt,
+				phaseAt: record.finishedAt ?? record.startedAt
+			};
+			const entry = instance.lease.entry;
+			return {
+				serverName,
+				phase,
+				startedAt: instance.startedAt,
+				phaseAt: Math.max(instance.startedAt, entry.phaseAt),
+				finishedAt: entry.finishedAt && Math.max(instance.startedAt, entry.finishedAt),
+				error: entry.error,
+				reused: instance.reused,
+				queuedMs: Math.max(0, (entry.startAt ?? Date.now()) - instance.startedAt),
+				connectMs: entry.connectedAt === void 0 ? void 0 : Math.max(0, entry.connectedAt - Math.max(instance.startedAt, entry.startAt ?? instance.startedAt)),
+				firstCallMs: instance.firstCallMs
+			};
+		});
+	}
+	/** @public @author ddj 2026年09月28号 @param path Workspace. @returns Masked configuration and pool/lease counts; initialization is not health. */
+	views(path) {
+		return [...this.projects.get(path) ?? []].map(([name, def]) => {
+			const entries = [...this.pool.entries.values()].filter((entry) => entry.spec.workspace === path && entry.spec.config.serverName === name);
+			const tools = /* @__PURE__ */ new Map();
+			for (const [agent] of this.agents) if (this.workspace(agent) === path) for (const tool of toolsOf(this.ctx, name, agent)) tools.set(tool.name, tool);
+			const failed = entries.some((entry) => entry.phase === "error" || entry.error);
+			const busy = entries.some((entry) => [
+				"queued",
+				"loading",
+				"starting",
+				"stopping"
+			].includes(entry.phase));
+			let status = "configured";
+			if (!def.enabled) status = "disabled";
+			else if (failed) status = "error";
+			else if (busy) status = "connecting";
+			else if (entries.some((entry) => entry.phase === "ready")) status = "unverified";
+			return {
+				id: projectEntryId(path, name),
+				serverName: name,
+				enabled: def.enabled,
+				transport: def.config.transport,
+				config: publicConfig(def.config),
+				policy: parseMcpPolicy(def.policy),
+				status,
+				instanceCount: entries.filter((entry) => entry.fiber).length,
+				sessionCount: entries.reduce((total, entry) => total + entry.refs, 0),
+				tools: [...tools.values()],
+				toolCount: tools.size,
+				error: failed ? "MCP 初始化或清理异常，请查看 Host 日志" : void 0
+			};
+		});
+	}
+	/** @public @author ddj 2026年10月20号 @returns Complete owned transport and capability cleanup. */
 	async dispose() {
 		this.stopped = true;
+		this.offDiscover?.();
 		await Promise.all([...this.agents.keys()].map((agent) => this.detach(agent)));
-		await this.tail;
+		await this.pool.dispose();
+		await Promise.allSettled([...this.pending]);
 		this.projects.clear();
 		this.module = void 0;
 	}
 };
-/**
-* Remove every old global project entry before any agent-scoped mount is attempted.
-* @public @author ddj 2026年09月28号
-* @param ctx Host loader context.
-* @returns Completion of loader removal and connection teardown.
-*/
+/** @public @author ddj 2026年09月28号 @param ctx Host loader. @returns Removal of legacy global project entries before any scoped entry is installed. */
 async function clearLegacy(ctx) {
 	const loader = ctx.get("loader");
 	for (const entry of entriesOf(ctx)) {
@@ -2552,35 +3114,41 @@ async function clearLegacy(ctx) {
 		await loader.remove(entry.id);
 	}
 }
-/**
-* Install awaited creation hooks, migrate global entries, and attach existing agents.
-* @public @author ddj 2026年09月28号
-* @param ctx Host lifecycle context; installIsolation must already be installed.
-* @returns Readiness for index.apply to await before advertising startup completion.
-*/
+/** @public @author ddj 2026年10月20号 @param ctx Host lifecycle. @returns Config/catalogue readiness, independent from all project MCP handshakes. */
 async function installMcpRuntime(ctx) {
 	const runtime = runtimeOf(ctx);
 	let ready;
+	/** @author ddj 2026年10月20号 Loads validated snapshots before exposing lazy capabilities. */
 	const initialize = async () => {
 		await clearLegacy(ctx);
-		await listProjects(ctx);
-		for (const agent of ctx.get("agents")?.list?.() ?? []) await runtime.attach(agent);
+		const { projects } = await listProjects(ctx, false);
+		for (const agent of ctx.get("agents")?.list?.() ?? []) {
+			runtime.prepare(agent);
+			const project = projects.find((item) => item.workspacePath === runtime.workspace(agent));
+			if (project?.fileError) runtime.configError(agent, project.fileError);
+		}
 	};
+	/** @author ddj 2026年10月20号 @param event Actual created agent. Reads configuration but never waits for connection startup. */
 	const created = async ({ agent }) => {
+		runtime.prepare(agent);
 		await ready;
 		const path = runtime.workspace(agent);
 		if (path) try {
-			await reconcileProject(ctx, path);
+			await reconcileProject(ctx, path, void 0, false);
+			runtime.configError(agent);
 		} catch (error) {
+			runtime.configError(agent, error);
 			ctx.logger?.warn?.("MCP configuration retained: " + String(error));
 		}
 		await runtime.attach(agent);
 	};
+	/** @author ddj 2026年10月20号 @param event Actual disposed agent. Revokes public access synchronously. */
 	const disposed = ({ agent }) => {
 		runtime.detach(agent).catch((error) => ctx.logger?.warn?.("MCP disposal failed: " + String(error)));
 	};
 	const offCreate = ctx.on("agent/created", created);
 	const offDispose = ctx.on("agent/disposed", disposed);
+	/** @author ddj 2026年10月20号 @returns Full lifecycle teardown. */
 	const cleanup = async () => {
 		offCreate?.();
 		offDispose?.();
@@ -2590,6 +3158,7 @@ async function installMcpRuntime(ctx) {
 	ctx.effect(() => cleanup, "vscode-mode:mcp-runtime");
 	ready = initialize();
 	await ready;
+	await Promise.all((ctx.get("agents")?.list?.() ?? []).map((agent) => runtime.attach(agent)));
 }
 //#endregion
 //#region src/mcpProject.ts
@@ -2773,9 +3342,10 @@ async function checkMcpName(ctx, serverName, workspacePath) {
 * @param ctx Host services.
 * @param workspacePath Registered workspace.
 * @param refresh Optional unchanged server to reconnect.
-* @returns Completion after scoped fibers match the file, including disabled flags.
+* @param wait Await connection synchronization for management, or only publication/scheduling for creation.
+* @returns Configuration publication, optionally including scoped fiber synchronization.
 */
-async function reconcileProject(ctx, workspacePath, refresh) {
+async function reconcileProject(ctx, workspacePath, refresh, wait = true) {
 	const data = await readProjectJson(ctx, workspacePath);
 	const defs = /* @__PURE__ */ new Map();
 	for (const [name, def] of Object.entries(serversOf(data))) {
@@ -2784,11 +3354,12 @@ async function reconcileProject(ctx, workspacePath, refresh) {
 		await checkMcpName(ctx, name, workspacePath);
 		defs.set(name, {
 			config,
-			enabled: def.disabled !== true
+			enabled: def.disabled !== true,
+			policy: parseMcpPolicy(def.vscodeMode)
 		});
 	}
 	await clearLegacy(ctx);
-	await runtimeOf(ctx).replace(workspacePath, defs, refresh);
+	await runtimeOf(ctx).replace(workspacePath, defs, refresh, wait);
 }
 /**
 * List one project, retaining the last good runtime view on file errors.
@@ -2798,7 +3369,7 @@ async function reconcileProject(ctx, workspacePath, refresh) {
 * @param title Workspace title.
 * @returns Configuration and honest runtime status with any read error attached.
 */
-async function projectOf(ctx, workspacePath, title) {
+async function projectOf(ctx, workspacePath, title, wait = true) {
 	let fileError;
 	let missingDir;
 	try {
@@ -2806,7 +3377,7 @@ async function projectOf(ctx, workspacePath, title) {
 		if (!fs) throw new Error("缺少 fs 服务");
 		const info = await fs.stat(await fs.resolve(workspacePath));
 		missingDir = !info || info.type !== "directory";
-		if (!missingDir) await reconcileProject(ctx, workspacePath);
+		if (!missingDir) await reconcileProject(ctx, workspacePath, void 0, wait);
 	} catch (error) {
 		missingDir = isMissingFile(error) || void 0;
 		fileError = String(error);
@@ -2833,9 +3404,9 @@ async function projectOf(ctx, workspacePath, title) {
 * @param ctx Host services.
 * @returns Project list; individual malformed files are reported on their project.
 */
-async function listProjects(ctx) {
+async function listProjects(ctx, wait = true) {
 	const projects = [];
-	for (const ws of ctx.get("workspaceRegistry")?.list?.() ?? []) projects.push(await projectOf(ctx, ws.path, ws.title ?? ""));
+	for (const ws of ctx.get("workspaceRegistry")?.list?.() ?? []) projects.push(await projectOf(ctx, ws.path, ws.title ?? "", wait));
 	return { projects };
 }
 /**
@@ -2881,11 +3452,12 @@ function mergeDefinition(previous, config) {
 * @param config Submitted configuration.
 * @returns Updated project view; invalid sources or conflicts reject before writing.
 */
-async function projectSave(ctx, workspacePath, serverName, config) {
-	return mcpEdit(ctx, () => saveProject(ctx, workspacePath, serverName, config));
+async function projectSave(ctx, workspacePath, serverName, config, policy) {
+	if (policy !== void 0) parseMcpPolicy(policy);
+	return mcpEdit(ctx, () => saveProject(ctx, workspacePath, serverName, config, policy));
 }
 /** @private @author ddj 2026年10月08号 @param ctx Host services. @param workspacePath Owner. @param serverName Namespace. @param config Editable fields. @returns Persisted project status. */
-async function saveProject(ctx, workspacePath, serverName, config) {
+async function saveProject(ctx, workspacePath, serverName, config, policy) {
 	const workspace = requireWorkspace$2(ctx, workspacePath);
 	validateConfig({
 		...config,
@@ -2898,6 +3470,7 @@ async function saveProject(ctx, workspacePath, serverName, config) {
 		...config,
 		serverName
 	});
+	if (policy !== void 0) servers[serverName].vscodeMode = { ...parseMcpPolicy(policy) };
 	await writeProjectJson(ctx, workspacePath, {
 		...data,
 		mcpServers: servers
@@ -3180,6 +3753,7 @@ async function saveMcp(ctx, config) {
 }
 /** @private @author ddj 2026年10月08号 @param ctx Host services. @param config Configuration. @returns Saved status; validation failures do not write. */
 async function saveGlobal(ctx, config) {
+	if (config && "vscodeMode" in config) throw new Error("vscodeMode 启动和共享策略仅适用于项目 MCP");
 	validateConfig(config);
 	await checkMcpName(ctx, config.serverName);
 	const loader = ctx.get("loader");
@@ -5977,13 +6551,6 @@ const PERSIST_DEBOUNCE_MS = 1e4;
 const HEAL_DEBOUNCE_MS = 3e3;
 /** cwd → 索引状态（随会话销毁清理）。 */
 const states = /* @__PURE__ */ new Map();
-/** 单调时钟：连续 put 的 ts 严格递增（同毫秒不并列，逐出/裁剪顺序可预期）。 */
-let clock = 0;
-/** 取下一时间戳（不小于真实时间且严格递增）。 */
-function nextTs() {
-	clock = Math.max(Date.now(), clock + 1);
-	return clock;
-}
 /** 条目原始值 → 合法条目（非法返回 null）。 */
 function entryOf(raw) {
 	if (!raw || typeof raw !== "object") return null;
@@ -6054,10 +6621,10 @@ function indexParse(text) {
 					type: e.type
 				});
 			}
-			if (!entries.length) continue;
+			const full = dir.full === true && entries.length === dir.entries.length;
 			dirs[rel] = {
 				ts: typeof dir.ts === "number" ? dir.ts : 0,
-				full: dir.full === true,
+				full,
 				entries
 			};
 		}
@@ -6076,11 +6643,12 @@ function trimPersist(data, maxDirs = 400, maxEntries = PERSIST_DIR_ENTRIES) {
 	const sorted = Object.entries(data.dirs).sort((a, b) => b[1].ts - a[1].ts);
 	for (const [rel, dir] of sorted) {
 		if (Object.keys(dirs).length >= maxDirs) break;
-		const full = dir.entries.length <= maxEntries;
+		const truncated = dir.entries.length > maxEntries;
+		const full = dir.full && !truncated;
 		dirs[rel] = {
 			ts: dir.ts,
 			full,
-			entries: full ? dir.entries : dir.entries.slice(0, maxEntries)
+			entries: truncated ? dir.entries.slice(0, maxEntries) : dir.entries
 		};
 	}
 	return {
@@ -6089,7 +6657,7 @@ function trimPersist(data, maxDirs = 400, maxEntries = PERSIST_DIR_ENTRIES) {
 		dirs
 	};
 }
-/** 取（或建）某 cwd 的索引状态，并惰性加载落盘快照（合并：文件 ts 更新才采纳）。 */
+/** 取（或建）某 cwd 的索引状态并惰性加载快照；加载期间真实列取优先，不被旧快照覆盖。 */
 function ensureState(ctx, cwd) {
 	const existing = states.get(cwd);
 	if (existing) return existing;
@@ -6102,6 +6670,7 @@ function ensureState(ctx, cwd) {
 			dirs: {}
 		},
 		stale: /* @__PURE__ */ new Set(),
+		lru: /* @__PURE__ */ new Map(),
 		dirty: false,
 		persistTimer: null,
 		healTimer: null,
@@ -6129,44 +6698,68 @@ async function loadIndex(state) {
 	try {
 		const parsed = indexParse(await readFile(treeCacheFile(state.cwd), "utf8"));
 		if (!parsed) return;
-		for (const [rel, dir] of Object.entries(parsed.dirs)) {
-			const cur = state.data.dirs[rel];
-			if (!cur || dir.ts > cur.ts) state.data.dirs[rel] = dir;
+		const snapshots = Object.entries(parsed.dirs).sort((a, b) => a[1].ts - b[1].ts);
+		for (const [rel, dir] of snapshots) {
+			if (state.data.dirs[rel]) continue;
+			state.data.dirs[rel] = dir;
+			touchDir(state, rel);
 		}
 		if (parsed.root && !state.data.root) state.data.root = parsed.root;
 	} catch (error) {} finally {
 		state.loading = false;
 	}
 }
-/** 命中：新鲜且未失效 → 条目（并刷新 ts 保活）；否则 null。 */
+/**
+* @private
+* @author ddj 2026年10月22号
+* @description 更新运行时访问顺序，超限时同步清理目录及失效标记。
+* @param state 工作区索引状态
+* @param rel 本次访问的相对目录
+*/
+function touchDir(state, rel) {
+	state.lru.delete(rel);
+	state.lru.set(rel, true);
+	if (state.lru.size <= 2e3) return;
+	const oldest = state.lru.keys().next().value;
+	if (oldest === void 0) return;
+	state.lru.delete(oldest);
+	state.stale.delete(oldest);
+	delete state.data.dirs[oldest];
+}
+/**
+* @public
+* @author ddj 2026年10月22号
+* @description 完整、新鲜且未失效才命中；访问仅更新 LRU，不续期硬 TTL。
+* @param cwd 工作区根
+* @param rel 相对目录
+* @returns 完整条目，或未命中时的 null
+*/
 function hitIndex(cwd, rel) {
 	const state = states.get(cwd);
 	if (!state) return null;
 	const dir = state.data.dirs[rel];
-	if (!dir || state.stale.has(rel)) return null;
-	const now = Date.now();
-	if (now - dir.ts > 6e4) return null;
-	dir.ts = now;
+	if (!dir || !dir.full || state.stale.has(rel)) return null;
+	if (Date.now() - dir.ts >= 6e4) return null;
+	touchDir(state, rel);
 	return dir.entries;
 }
-/** 更新某目录条目：写内存 + 打脏 + 防抖落盘；stale 撤销。 */
+/**
+* @public
+* @author ddj 2026年10月22号
+* @description 保存完整实列结果与确认时间，更新 LRU、撤销 stale 并防抖落盘。
+* @param ctx 工作区上下文
+* @param cwd 工作区根
+* @param rel 相对目录
+* @param entries 完整实列条目
+*/
 function putIndex(ctx, cwd, rel, entries) {
 	const state = ensureState(ctx, cwd);
-	const dirs = state.data.dirs;
-	if (!dirs[rel] && Object.keys(dirs).length >= 2e3) {
-		let oldest = rel;
-		let oldestTs = Infinity;
-		for (const [k, v] of Object.entries(dirs)) if (v.ts < oldestTs) {
-			oldestTs = v.ts;
-			oldest = k;
-		}
-		delete dirs[oldest];
-	}
-	dirs[rel] = {
-		ts: nextTs(),
-		full: entries.length <= PERSIST_DIR_ENTRIES,
+	state.data.dirs[rel] = {
+		ts: Date.now(),
+		full: true,
 		entries
 	};
+	touchDir(state, rel);
 	state.stale.delete(rel);
 	state.dirty = true;
 	schedulePersist(state);
@@ -6231,6 +6824,7 @@ function disposeIndex(cwd) {
 		state.healTimer = null;
 	}
 	if (state.dirty) persistNow(state);
+	state.lru.clear();
 	states.delete(cwd);
 }
 /** 错误 → 用户文案（DirListError 用自身 message，其余带上下文）。 */
@@ -6283,6 +6877,7 @@ async function listDirCached(ctx, cwd, rel, force) {
 			if (error instanceof DirListError && error.code === "not-found") {
 				if (state.data.dirs[rel]) {
 					delete state.data.dirs[rel];
+					state.lru.delete(rel);
 					state.dirty = true;
 					schedulePersist(state);
 				}
@@ -11385,7 +11980,140 @@ function settingsDocPath(configuredPath, requestedPath, platform = process.platf
 	}
 }
 //#endregion
+//#region src/shared/textPages.ts
+/** Bounded, read-only text paging protocol. @author ddj 2026年10月22号 */
+const TEXT_PAGE_BYTES = 262144;
+//#endregion
+//#region src/textPages.ts
+/**
+* Create a Host-owned pager with process-local authenticated cursors.
+* @public @author ddj 2026年10月22号
+* @returns A bounded reader requiring an independently authorized range capability.
+*/
+function createTextPages() {
+	const secret = randomBytes(32);
+	/** @private @author ddj 2026年10月22号 @param payload Authenticated state. @returns Signed cursor. */
+	function signCursor(payload) {
+		const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+		return body + "." + createHmac("sha256", secret).update(body).digest("base64url");
+	}
+	/** @private @author ddj 2026年10月22号 @param token Untrusted cursor. @returns Verified state or null. */
+	function parseCursor(token) {
+		if (typeof token !== "string" || token.length > 8192) return null;
+		const parts = token.split(".");
+		if (parts.length !== 2 || !/^[A-Za-z0-9_-]+$/.test(parts[0])) return null;
+		const signature = Buffer.from(parts[1], "base64url");
+		const expected = createHmac("sha256", secret).update(parts[0]).digest();
+		if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) return null;
+		try {
+			const payload = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+			if (typeof payload.identity !== "string" || typeof payload.version !== "string" || typeof payload.sessionId !== "string" || typeof payload.path !== "string" || typeof payload.pendingCR !== "boolean" || !Number.isSafeInteger(payload.offset) || payload.offset <= 0) return null;
+			return payload;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Read at most 256 KiB, validating freshness before and after IO.
+	* @public @author ddj 2026年10月22号
+	* @param source Authorized range capability; absent means unsupported.
+	* @param args Request identity and optional signed cursor.
+	* @returns Strict UTF-8 text or an explicit fail-closed result; never partial success on mutation.
+	*/
+	async function readTextPage(source, args) {
+		if (!source) return failure("unsupported", "Host does not expose authorized range reads");
+		const cursor = args.cursor === void 0 ? void 0 : parseCursor(args.cursor);
+		if (cursor === null || cursor && (cursor.identity !== source.identity || cursor.sessionId !== (args.sessionId ?? "") || cursor.path !== args.path)) return failure("invalid-cursor", "Cursor does not belong to this file and session");
+		try {
+			const before = await source.stat();
+			if (!before || before.type !== "file" || typeof before.version !== "string" || !Number.isSafeInteger(before.size) || before.size < 0) return failure("unsupported", "Regular file size and opaque version are required");
+			if (cursor && (cursor.version !== before.version || cursor.offset >= before.size)) return failure("stale", "File changed; restart text preview");
+			const offset = cursor?.offset ?? 0;
+			const length = Math.min(TEXT_PAGE_BYTES, before.size - offset);
+			const bytes = await source.readRange(offset, length);
+			const after = await source.stat();
+			if (!after || after.version !== before.version || after.size !== before.size || after.type !== "file") return failure("stale", "File changed during text read");
+			if (!(bytes instanceof Uint8Array) || bytes.byteLength !== length) return failure("read-failed", "Range reader returned an incomplete or oversized page");
+			return decodePage(bytes, before, offset, cursor?.pendingCR ?? false, args, source.identity, signCursor);
+		} catch (error) {
+			return failure("read-failed", String(error));
+		}
+	}
+	return readTextPage;
+}
+/** @private @author ddj 2026年10月22号 @param reason Failure discriminator. @param error User-visible error. @returns Failure result. */
+function failure(reason, error) {
+	return {
+		ok: false,
+		reason,
+		error
+	};
+}
+/**
+* Keep an incomplete final UTF-8 sequence for a bounded re-read on the next page.
+* @private @author ddj 2026年10月22号
+* @param bytes Raw page. @returns Complete prefix length; invalid sequences remain for fatal decoding.
+*/
+function utf8Prefix(bytes) {
+	let start = bytes.length - 1;
+	while (start >= 0 && (bytes[start] & 192) === 128) start--;
+	if (start < 0) return bytes.length;
+	const lead = bytes[start];
+	let width = 1;
+	if (lead >= 194 && lead <= 223) width = 2;
+	else if (lead >= 224 && lead <= 239) width = 3;
+	else if (lead >= 240 && lead <= 244) width = 4;
+	return bytes.length - start < width ? start : bytes.length;
+}
+/**
+* Decode one page preserving original line endings without buffering a long line.
+* @private @author ddj 2026年10月22号
+* @param bytes Raw page. @param info File snapshot. @param offset Current offset.
+* @param pendingCR Previous trailing CR. @param args Request identity. @param identity Authorized target identity.
+* @param signCursor Host cursor signer. @returns Page or strict decoding failure.
+*/
+function decodePage(bytes, info, offset, pendingCR, args, identity, signCursor) {
+	const consumed = offset + bytes.length === info.size ? bytes.length : utf8Prefix(bytes);
+	let text;
+	try {
+		text = new TextDecoder("utf-8", {
+			fatal: true,
+			ignoreBOM: true
+		}).decode(bytes.subarray(0, consumed));
+	} catch {
+		return failure("not-text", "File is not valid UTF-8");
+	}
+	if (text.includes("\0")) return failure("not-text", "Binary text preview is unsupported");
+	if (offset === 0 && text.startsWith("")) text = text.slice(1);
+	if (pendingCR) text = "\r" + text;
+	const nextOffset = offset + consumed;
+	const eof = nextOffset === info.size;
+	const trailingCR = !eof && text.endsWith("\r");
+	if (trailingCR) text = text.slice(0, -1);
+	const nextCursor = eof ? null : signCursor({
+		identity,
+		sessionId: args.sessionId ?? "",
+		path: args.path,
+		version: info.version,
+		offset: nextOffset,
+		pendingCR: trailingCR
+	});
+	return {
+		ok: true,
+		text,
+		version: info.version,
+		offset: nextOffset,
+		size: info.size,
+		eof,
+		nextCursor,
+		encoding: "utf-8",
+		partialLine: !eof && !/[\r\n]$/.test(text)
+	};
+}
+//#endregion
 //#region src/rpc.ts
+/** Process-local cursor signer; reads must stay on the Host filesystem capability. */
+const readTextPage = createTextPages();
 /** cwd → 上次 stale 自动清理时间：全量轮询（EditorView/DiffBadge/Dock 各自 5s）节流，避免每轮都读文件算指纹。 */
 const staleCheckedAt = /* @__PURE__ */ new Map();
 /** stale 自动清理最小间隔。 */
@@ -11475,7 +12203,10 @@ async function readTargetOf(ctx, sc, path) {
 			err: "文件不存在",
 			resolvedPath: fs.processPath(target)
 		};
-		if ((info.size ?? 0) > 33554432) return { err: "文件过大（>32MB），不支持整文件预览" };
+		if ((info.size ?? 0) > 33554432) return {
+			err: "文件过大（>32MB），不支持整文件预览",
+			code: "file-too-large"
+		};
 		return {
 			target,
 			fs,
@@ -11492,13 +12223,11 @@ async function readTargetOf(ctx, sc, path) {
 * @returns { ok:false } 形态载荷
 */
 function targetErrOf(prep) {
-	return prep.resolvedPath !== void 0 ? {
+	return {
 		ok: false,
 		error: prep.err,
-		resolvedPath: prep.resolvedPath
-	} : {
-		ok: false,
-		error: prep.err
+		...prep.resolvedPath !== void 0 ? { resolvedPath: prep.resolvedPath } : {},
+		...prep.code ? { code: prep.code } : {}
 	};
 }
 /**
@@ -12027,6 +12756,44 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				results: await applyDecisions(ctx, sc.session, sc.cwd, bucket, Array.isArray(args.items) ? args.items : [])
 			};
 		},
+		/** @author ddj 2026年10月22号 @param args Read-only request. @returns Bounded official range read, or unsupported on older providers; never bypasses Host IO. */
+		"edrv.textPage": async (args) => {
+			const sc = await requireSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err,
+				reason: "read-failed"
+			};
+			try {
+				const target = await resolveTarget(ctx, sc.session, args.path);
+				const fs = ctx.get("fs");
+				if (typeof fs?.readByteRange !== "function" || typeof fs.stat !== "function") return readTextPage(void 0, args);
+				const targetKey = typeof target === "string" ? target : target.targetKey;
+				if (typeof targetKey !== "string") return readTextPage(void 0, args);
+				/** @author ddj 2026年10月22号 @returns Provider metadata used for before/after freshness checks. */
+				function statPage() {
+					return fs.stat(target);
+				}
+				/** @author ddj 2026年10月22号 @param offset Verified cursor position. @param length Bounded byte count. @returns Bytes through the official provider only. */
+				function readRange(offset, length) {
+					return fs.readByteRange(target, {
+						offset,
+						length
+					});
+				}
+				return readTextPage({
+					identity: JSON.stringify([sc.cwd, targetKey]),
+					stat: statPage,
+					readRange
+				}, args);
+			} catch (error) {
+				return {
+					ok: false,
+					error: "读取失败：" + String(error),
+					reason: "read-failed"
+				};
+			}
+		},
 		"edrv.read": async (args) => {
 			const settingsTarget = settingsTargetOf(ctx, args.path);
 			if (settingsTarget && args.encoding !== "base64") try {
@@ -12091,7 +12858,8 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				}
 				if ((prep.info.size ?? 0) > 8388608) return {
 					ok: false,
-					error: "文件过大（>8MB），不支持整文件预览"
+					error: "文件过大（>8MB），不支持整文件预览",
+					code: "file-too-large"
 				};
 				const content = await prep.fs.readText(prep.target);
 				return {
@@ -12850,6 +13618,10 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			ok: true,
 			...mcpSnapshot(ctx)
 		}),
+		"mcp.sessionSnapshot": async () => ({
+			ok: true,
+			...runtimeOf(ctx).sessionSnapshot()
+		}),
 		"mcp.save": async (args) => {
 			try {
 				return {
@@ -12913,11 +13685,31 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				};
 			}
 		},
+		"mcp.projectConnect": async (args) => {
+			const runtime = runtimeOf(ctx);
+			const agent = [...runtime.agents.keys()].find((owner) => owner.session?.id === args.sessionId);
+			if (!agent || runtime.workspace(agent) !== args.workspacePath) return {
+				ok: false,
+				error: "请先打开此项目的活跃会话；不会激活历史会话"
+			};
+			try {
+				await runtime.connect(agent, args.serverName);
+				return {
+					ok: true,
+					project: mcpSnapshot(ctx).projects.find((item) => item.workspacePath === args.workspacePath)
+				};
+			} catch {
+				return {
+					ok: false,
+					error: "项目 MCP 连接失败，请查看会话状态和 Host 日志"
+				};
+			}
+		},
 		"mcp.projectSave": async (args) => {
 			try {
 				return {
 					ok: true,
-					project: await projectSave(ctx, args.workspacePath, args.serverName, args.config)
+					project: await projectSave(ctx, args.workspacePath, args.serverName, args.config, args.policy)
 				};
 			} catch (error) {
 				return {