@eddyskywalker/dsh-chatgpt-subscription 0.61.0 → 0.63.0

package/lib/codemode.js

@@ -1,5 +1,5 @@
 import { n as PLUGIN_MESSAGE_SOURCE_KIND } from "./llm-compat-u9mor0uu.js";
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { HarnessError, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { NativeToolExecutor } from "@deepseek-ai/dsh-tool-executor-native";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/host/codemode/discovery.ts
@@ -587,6 +587,10 @@ function summarizeHidden(names) {
 * 工具的数量、namespace 分布、会话 id 或时间，因此同一部署下逐字节恒定：挂载或卸载
 * MCP 服务端不会改写它，前缀缓存不会因为它失效。
 *
+* 结果形状索引（`read` / `glob` / `grep` … 的顶层字段）也**必须是静态的**：它照抄自各工具
+* 声明过的 output schema，不读活 catalog。按 catalog 生成会让「挂一个 MCP 服务端」改写系统
+* 提示词首段，正好毁掉这一层要保住的前缀缓存。
+*
 * @param input - 传输工具名、发现工具名与程序形态。
 * @returns 说明段正文。
 */
@@ -624,9 +628,18 @@ function buildCodemodeSectionText(input) {
 		"",
 		python ? retained ? "- A retained Python REPL: top-level await and a final expression. Its variables and imported modules survive into your later programs in this session." : "- Async Python program: top-level await works; print or evaluate a final expression to produce output." : retained ? "- A retained TypeScript REPL: top-level declarations, await, and a final expression. Its variables and imported modules survive into your later programs in this session." : "- Erasable TypeScript, run as the body of an async function: top-level await and return work.",
 		"- Only what you return or console.log reaches the conversation; every intermediate result stays in the program, so filter and aggregate there instead of returning raw payloads.",
-		"- File, search, and shell tool results are named-field objects, never bare strings (whereas `job_list` returns a bare array): `glob` answers `{ root, paths }`, `grep` answers `{ matches }` with matches shaped `{ path, lineNumber, line }`, `read` answers `{ path, offset, lines, totalLines }` with `lines` items shaped `{ number, text }`, and `win_bash` answers `{ stdout, stderr, exitCode }`. A named-field object carries its list or text inside those fields — `r.lines.map((l) => l.text)` — so never call `.map`, `.filter`, `.split`, `.splitlines` or `in` on the envelope itself.",
+		"- File, search, and shell tool results are named-field objects, never bare strings — read the field, not the envelope (`job_list` and `list_agents` are the only bare arrays):",
+		"  `read` → `{ path, offset, lines: [{ number, text }], totalLines }` · `glob` → `{ root, paths }` · `grep` → `{ matches: [{ path, lineNumber, line }] }` · `edit` → `{ path, before, after }` · `write` → `{ path, operation, before, after }` · `win_bash` → `{ stdout, stderr, exitCode }` · `web_fetch` → `{ url, statusCode, body, truncated }` · `job_output` → `{ text, job }` · `read_image` → `{ path, image }` · `skill` → `{ name, content }`.",
+		python ? "- Read the field: `page[\"lines\"]`, `match[\"text\"]`. Calling `.split()`, `.splitlines()` or `in` on the envelope itself is always wrong." : "- Read the field: `r.lines.map((l) => l.text)`. Calling `.map`, `.filter`, `.split` or `in` on the envelope itself is always wrong.",
+		"- Anything not listed above (MCP tools, hidden plugin tools) answers with its **declared output schema**: call `" + describeTool + "({ name })` and read the top-level keys before picking a field. One discovery call is far cheaper than the `TypeError` that loses the whole program.",
 		"- Discovery returns whole objects too: `" + listTool + "` answers `{ tools: [{ name, description, namespace }] }`, `" + searchTool + "` answers `{ tools: [{ name, namespace, description, parameters, output? }], fallback? }`, and `" + describeTool + "` answers `{ found, name?, namespace?, description?, parameters?, output? }`.",
 		"- Tool argument objects and `return` values must be lossless JSON: **never leave `undefined` in an object property value** — `{ a: x.opt }` fails the call when `x.opt === undefined`. Omit the key, write `x.opt ?? null`, or print it with `console.log`.",
+		"- Parameter keys: `read`, `edit`, `write`, and `read_image` take `file_path` (not `path`); `glob` and `grep` take `path`; `win_bash` takes `workdir` (not `cwd`).",
+		...python ? [] : [
+			"- Paths and regexes: write a Windows path with forward slashes (`C:/Users/...`) or wrap it in `String.raw`; a literal `C:\\Users` inside an ordinary string is read as the escape `\\U` and the program never starts (`Expected unicode escape`). Regex backslashes (`\\d`, `\\.`) have the same trap — double them or use `String.raw`.",
+			"- A program is not a module: `import('./src/x.ts')` and `import('vscode')` cannot resolve — the program runs in a fresh process with no module graph. Read files with `tools.read`; `await import('node:fs')` works only for Node built-ins.",
+			"- `process.env` is empty inside the program: `os.tmpdir()` and credentialed CLIs (`gh`, `git`, `npm`) spawned via `node:child_process` miss `TEMP`, `HOME`, `APPDATA`, and auth tokens. Run shell and CLI commands through `await tools.win_bash({ command })` instead."
+		],
 		"- Prefer batching multi-step read/search chains inside one " + run + " program instead of issuing many sequential single-tool turns.",
 		"- Independent read-only calls may overlap under Promise.all; mutating calls run alone, in submission order.",
 		"- A failed sub-call rejects; try/catch or Promise.allSettled it to keep the calls that succeeded. Completed calls are real side effects and are not rolled back.",
@@ -799,7 +812,10 @@ function createCodemodeExecutor(ctx, rules, hooks) {
 				additionalContexts: [],
 				concluded: false
 			};
-		}
+		},
+		...typeof hooks.reset === "function" ? { async reset(agent) {
+			await hooks.reset(agent);
+		} } : {}
 	};
 }
 /**
@@ -847,169 +863,6 @@ function sectionOrderOf(ctx) {
 	}
 }
 //#endregion
-//#region src/host/codemode/retention.ts
-/**
-* 造一个常驻环境管理器。
-*
-* @param runtimeOf - 读当前运行时的函数（每次调用重读，运行时可能晚于本插件挂载）。
-* @returns 管理句柄。
-*/
-function createRetention(runtimeOf) {
-	const live = /* @__PURE__ */ new Set();
-	const released = /* @__PURE__ */ new WeakSet();
-	const release = async (owner) => {
-		if (released.has(owner)) return;
-		released.add(owner);
-		live.delete(owner);
-		const runtime = runtimeOf();
-		if (runtime?.release === void 0) return;
-		try {
-			await runtime.release(owner);
-		} catch {}
-	};
-	return {
-		owner(agent) {
-			const owner = typeof agent === "object" && agent !== null ? agent : fallbackOwner;
-			released.delete(owner);
-			live.add(owner);
-			return owner;
-		},
-		release,
-		async dispose() {
-			const owners = [...live];
-			await Promise.all(owners.map((owner) => release(owner)));
-		}
-	};
-}
-/** 没有 agent 的调用（例如服务级直调）共用的 owner。 */
-const fallbackOwner = Object.freeze({ kind: "codemode-sessionless" });
-//#endregion
-//#region src/host/codemode/scope.ts
-/**
-* 工具归属判定：一个名字是**全局层**注册的，还是**本预设**注册的。
-*
-* ## 为什么要这么绕
-*
-* 注册表没有公开「某个工具注册在哪个作用域」的 API。`@deepseek-ai/dsh-scope` 把作用域标签
-* 写在一个模块私有的 `Symbol('dsh.scope')` 上，链关系（parent）也在私有 WeakMap 里，
-* 都不导出。能用的只有两件事：
-*
-* 1. 本包自己所在作用域的 key —— 按符号描述从 ctx 上扫出来（{@link findScopeKey}）；
-* 2. 公开的 `ctx.tools.get(name)`（全局视图）与 `ctx.tools.get(name, key)`（该作用域视图）。
-*
-* 于是归属判定变成两次公开查询：
-*
-* - 全局视图能解析 → 全局层（MCP 服务端、profile 级 bundle）；
-* - 只有本预设视图能解析 → 本预设自己注册的；
-* - 两处都解析不到 → 只可能注册在本预设之下（agent 层）。
-*
-* 探测失败（本包被挂在 host 层而不是预设里）时返回 `enabled: false`：规则整体降级为
-* 纯名字匹配，绝不因为读不到归属就误遮蔽。
-*
-* @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/scope
-*/
-/** 内核写作用域标签用的符号描述。 */
-const SCOPE_SYMBOL_DESCRIPTION = "dsh.scope";
-/**
-* 从一个 ctx 上找出「本包所在作用域」的 key。
-*
-* Cordis 的 scoped context 把作用域标签写成自有（或原型上）的一个 symbol 属性，
-* 描述是 `dsh.scope`。这里按描述扫，不猜符号本身——写法与参考实现一致，因为
-* 直接 `import` 内核的 scope 包在 profile 插件里解析不到。
-*
-* @param ctx - 本包的行上下文。
-* @returns 作用域 key；读不到时为 `undefined`。
-*/
-function findScopeKey(ctx) {
-	if (typeof ctx !== "object" || ctx === null) return void 0;
-	return scanForScope(ctx, 0);
-}
-/** 在对象自身及其原型链上找作用域标签（只看 symbol 属性，深度上限 4）。 */
-function scanForScope(source, depth) {
-	if (depth > 4) return void 0;
-	let symbols;
-	try {
-		symbols = Object.getOwnPropertySymbols(source);
-	} catch {
-		return;
-	}
-	for (const symbol of symbols) {
-		if (symbol.description !== SCOPE_SYMBOL_DESCRIPTION) continue;
-		let value;
-		try {
-			value = source[symbol];
-		} catch {
-			continue;
-		}
-		if (typeof value === "object" && value !== null) return value;
-	}
-	const proto = Object.getPrototypeOf(source);
-	if (proto === null || proto === Object.prototype) return void 0;
-	return scanForScope(proto, depth + 1);
-}
-/**
-* 为一个名字清单建立归属视图。
-*
-* @param tools - 工具注册表（结构探测，不看类身份）。
-* @param scopeKey - 本预设的作用域 key；`undefined` 表示探测失败。
-* @param names - 要判定的名字（通常是本步的模型可见清单）。
-* @returns 归属视图；读不到任何归属时返回禁用视图。
-*/
-function resolveCatalogView(tools, scopeKey, names) {
-	const registry = asRegistry(tools);
-	if (scopeKey === void 0 || registry === void 0) return DISABLED_VIEW;
-	const globalNames = /* @__PURE__ */ new Set();
-	const presetNames = /* @__PURE__ */ new Set();
-	for (const name of names) {
-		if (typeof name !== "string" || name.length === 0) continue;
-		if (probes(registry, name, void 0)) globalNames.add(name);
-		if (probes(registry, name, scopeKey)) presetNames.add(name);
-	}
-	return {
-		enabled: true,
-		globalNames,
-		presetNames
-	};
-}
-/**
-* 判定一个名字在**调用时**是否属于本预设之外的层。
-*
-* 拒绝路径（模型直呼被遮蔽的名字）没有当步清单可用，只能按同一个视图单独判一次；
-* 判定规则与 {@link resolveCatalogView} 完全一致，两处因此不可能给出互相矛盾的结论。
-*
-* @param tools - 工具注册表。
-* @param scopeKey - 本预设的作用域 key。
-* @param name - 工具名。
-* @returns 归属视图（只含这一个名字）。
-*/
-function resolveNameView(tools, scopeKey, name) {
-	const registry = asRegistry(tools);
-	if (scopeKey === void 0 || registry === void 0) return DISABLED_VIEW;
-	const globalNames = /* @__PURE__ */ new Set();
-	const presetNames = /* @__PURE__ */ new Set();
-	if (probes(registry, name, void 0)) globalNames.add(name);
-	if (probes(registry, name, scopeKey)) presetNames.add(name);
-	return {
-		enabled: true,
-		globalNames,
-		presetNames
-	};
-}
-/** 一次公开查询：解析得到定义时为 `true`。 */
-function probes(registry, name, scope) {
-	try {
-		return registry.get(name, scope) !== void 0;
-	} catch {
-		return false;
-	}
-}
-/** 结构探测：读得到 `get` 就当注册表用。 */
-function asRegistry(tools) {
-	if (typeof tools !== "object" || tools === null) return void 0;
-	if (typeof tools.get !== "function") return void 0;
-	return tools;
-}
-//#endregion
 //#region src/host/codemode/transport.ts
 /**
 * Code Mode 的程序传输工具 `code_run`。
@@ -1051,8 +904,41 @@ const catalogScope = new AsyncLocalStorage();
 function currentCatalogSnapshot() {
 	return catalogScope.getStore();
 }
+/** 传输工具名（与 {@link DEFAULT_RUN_TOOL_NAME} 一致，导出方便测试引用）。 */
+const TRANSPORT_TOOL_NAME = "code_run";
+/** 进展汇报工具名：融合参数里救回来的简报用它补发。 */
+const PROGRESS_UPDATE_TOOL = "progress_update";
 /** 允许单次提权的目标沙箱模式（对齐 `@deepseek-ai/dsh-sandbox` 的 `ESCALATION_TARGETS`）。 */
 const ESCALATION_TARGETS = Object.freeze(["workspace-write", "danger-full-access"]);
+/**
+* 子调用配额耗尽时的宿主中止原因（对齐 `@deepseek-ai/dsh-tool-executor-ptc` 的 `ToolCallLimitExceededError`）。
+*
+* 超出的那一次调用不会派发；结算阶段识别此错误并保留完整诊断，防止常驻模式下的泛化取消文案吞掉真实原因。
+*/
+var ToolCallLimitExceededError = class extends Error {
+	constructor(limit, callNumber, callsPerMinute, runToolName = TRANSPORT_TOOL_NAME) {
+		super(`${runToolName} exceeded its limit of ${String(limit)} tool calls (${String(callsPerMinute)} per minute of its timeout); call ${String(callNumber)} was not dispatched. The ${runToolName} program may contain an infinite loop. Check loop termination or split the work into smaller ${runToolName} calls.`);
+		this.name = "ToolCallLimitExceededError";
+	}
+};
+/**
+* 程序运行自身失败时抛出的结构化错误（对齐内核 `CodeRunFailedError`，`code: 'CODE_RUN_FAILED'`）。
+*/
+var CodeRunFailedError = class extends HarnessError {
+	constructor(message) {
+		super(message, "CODE_RUN_FAILED");
+		this.name = "CodeRunFailedError";
+	}
+};
+/**
+* 常驻环境重置不支持或失败时抛出的结构化错误（对齐内核 `CodeResetFailedError`，`code: 'CODE_RESET_FAILED'`）。
+*/
+var CodeResetFailedError = class extends HarnessError {
+	constructor(message) {
+		super(message, "CODE_RESET_FAILED");
+		this.name = "CodeResetFailedError";
+	}
+};
 /** 与内核 `run_code` 一致的 `description` 参数说明。 */
 const DESCRIPTION_PARAM_DESCRIPTION = "Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\".";
 function buildFlavor(languageName, execution) {
@@ -1177,24 +1063,25 @@ function createTransportDefinition(host, rules) {
 			}
 		},
 		presentCall(args) {
-			if (typeof args !== "object" || args === null) return void 0;
-			const record = args;
-			const code = record["code"];
-			const description = record["description"];
-			if (typeof code !== "string" || typeof description !== "string" || description.trim().length === 0) return;
-			return {
-				card: "generic",
-				title: description,
-				kind: "execute",
-				rawInput: code
-			};
+			try {
+				const input = readArguments(args);
+				return {
+					card: "generic",
+					title: input.description,
+					kind: "execute",
+					rawInput: input.code
+				};
+			} catch {
+				return;
+			}
 		},
 		async execute(args, exec) {
 			const input = readArguments(args);
 			const runtime = host.runtime();
 			if (runtime === void 0) throw new Error("codemode: no PTC runtime is mounted (ctx.ptcRuntime); the program transport is unavailable");
 			if (input.timeoutMs !== void 0 && runtime.timeout !== void 0 === false && isStrictTimeoutUnsupported(runtime)) throw new Error("timeoutMs is not available for this PTC runtime");
-			const catalog = host.catalog();
+			await host.awaitPredecessors?.(exec.agent, exec.signal);
+			const catalog = host.catalog(exec.agent, exec.toolSet);
 			const runController = new AbortController();
 			const onOuterAbort = () => {
 				runController.abort(exec.signal.reason);
@@ -1202,6 +1089,7 @@ function createTransportDefinition(host, rules) {
 			if (exec.signal.aborted) runController.abort(exec.signal.reason);
 			else exec.signal.addEventListener("abort", onOuterAbort, { once: true });
 			const nestedSignal = markNested(runController.signal) ?? runController.signal;
+			if (input.narration !== void 0) await forwardNarration(host, input.narration, exec, nestedSignal);
 			const owner = host.stateOwner(exec.agent);
 			let maxSubCalls = rules.options.maxSubCalls;
 			let attempts = 0;
@@ -1215,11 +1103,11 @@ function createTransportDefinition(host, rules) {
 					if (runController.signal.aborted) throw new Error(runToolName + " run is over; " + entry.name + " not dispatched");
 					const n = ++attempts;
 					if (n > maxSubCalls) {
-						const limitErr = /* @__PURE__ */ new Error("program sub-call limit exceeded: " + String(maxSubCalls) + " calls");
+						const limitErr = new ToolCallLimitExceededError(maxSubCalls, n, rules.options.maxSubCallsPerMinute, runToolName);
 						runController.abort(limitErr);
 						throw limitErr;
 					}
-					const parsed = losslessArgs(rawArgs);
+					const parsed = normalizeSubCallArgs(definitions.get(entry.name), losslessArgs(rawArgs));
 					const loggedArgs = losslessArgs(parsed);
 					const callId = String(exec.callId) + NESTED_CALL_ID_MARKER + String(n);
 					const dispatchLog = createDispatchLog(exec.agent, {
@@ -1229,8 +1117,8 @@ function createTransportDefinition(host, rules) {
 						name: entry.name,
 						arguments: loggedArgs
 					});
-					const mode = isConcurrencySafe(definitions.get(entry.name), parsed) ? "parallel" : "exclusive";
-					return lane.schedule(mode, {
+					return lane.schedule({
+						classify: () => isConcurrencySafe(definitions.get(entry.name), parsed) ? "parallel" : "exclusive",
 						start() {
 							dispatchLog.start();
 						},
@@ -1245,35 +1133,39 @@ function createTransportDefinition(host, rules) {
 						/**
 						* 提交阶段：按**提交顺序**逐条执行，落在会话里的副作用因此与提交顺序一致。
 						*
-						* 内核把这几步全部放在同一条有序 lane 里（`ptc.ts` 的 commit 游标）：回放内容
-						* 投影、settle 事件、图片与附加上下文、`concludeTurn`、放行互斥屏障。并发的
-						* body 谁先跑完都不影响这一串的顺序——否则界面里的子调用记录会错位，延迟上下文
-						* 也会插到错误的位置。
+						* 对齐内核 `ptc.ts:537-634`：延迟上下文（图片与 `additionalContexts`）与 `concludeTurn`
+						* 按提交顺序同步生效后，**立刻**向程序返回子调用结果，避免慢速日志落盘监听器阻塞程序
+						* 后续执行；`shapeDispatchLog` 与 `tool/ptc-dispatch` 事件通过带背压的有序 `logWork`
+						* 队列异步结算，并在 `lane.drain()` 中完整排空。
 						*/
-						async commit(parked) {
+						commit(parked, enqueueLog) {
 							if (!parked.ok) {
-								dispatchLog.settle({ error: messageOf$1(parked.error) });
+								enqueueLog(async () => {
+									dispatchLog.settle({ error: messageOf$2(parked.error) });
+								});
 								throw parked.error;
 							}
 							const outcome = parked.value;
 							const isError = outcome.error !== void 0;
-							const content = await shapeDispatchContent(host, {
-								agent: exec.agent,
-								name: entry.name,
-								arguments: loggedArgs,
-								isError,
-								content: clipContent(outcome.content)
-							});
-							dispatchLog.settle({
-								...outcome,
-								content
-							});
 							if (!isError && Array.isArray(outcome.content) && hasImageBlock(outcome.content)) {
 								const imageMsg = host.createImageContext?.(outcome.content);
 								if (imageMsg !== void 0) exec.deferContext?.(imageMsg);
 							}
 							if (Array.isArray(outcome.additionalContexts)) for (const contextMsg of outcome.additionalContexts) exec.deferContext?.(contextMsg);
 							if (!isError && outcome.concluded === true) exec.concludeTurn?.();
+							enqueueLog(async () => {
+								const content = await shapeDispatchContent(host, {
+									agent: exec.agent,
+									name: entry.name,
+									arguments: loggedArgs,
+									isError,
+									content: clipContent(outcome.content)
+								});
+								dispatchLog.settle({
+									...outcome,
+									content
+								});
+							});
 							if (runController.signal.aborted) throw new Error(runToolName + " run is over; " + entry.name + " result discarded");
 							if (outcome.error !== void 0) throw new Error(outcome.error);
 							return outcome.value !== void 0 ? outcome.value : outcome.text ?? null;
@@ -1298,7 +1190,7 @@ function createTransportDefinition(host, rules) {
 				* `stateOwner`，避免把单次授权固化到常驻环境中（对齐内核 `ptc.ts`）。
 				*/
 				let approvedEscalatedMode;
-				/** 这次运行在入口那边的登记；结算时释放（重跑会重新登记一次）。 */
+				/** 这次运行在入口那边的登记；结算时释放（重跑原位更新 mode，外层 finally 统一释放）。 */
 				let untrackRun = () => {};
 				const attempt = async () => {
 					const authority = await host.runAuthority?.(exec.agent, nestedSignal);
@@ -1325,11 +1217,11 @@ function createTransportDefinition(host, rules) {
 						};
 						escalated = modeOfPolicy(effectivePolicy) !== modeOfPolicy(standingPolicy);
 					}
-					untrackRun();
 					const runMode = modeOfPolicy(effectivePolicy);
 					untrackRun = host.trackRun?.({
 						agent: exec.agent,
 						controller: runController,
+						signal: nestedSignal,
 						...runMode === void 0 ? {} : { mode: runMode }
 					}) ?? (() => {});
 					const request = {
@@ -1368,10 +1260,17 @@ function createTransportDefinition(host, rules) {
 					untrackRun();
 				}
 				if (result.error !== void 0) {
+					const limitError = runController.signal.reason instanceof ToolCallLimitExceededError ? runController.signal.reason : void 0;
+					if (result.error.kind === "abort" && exec.signal.aborted && limitError === void 0) {
+						const abortError = new HarnessError(runtime.retainsState ? `tool call aborted: ${result.error.message}` : "tool call aborted", "ABORTED");
+						abortError.name = "AbortError";
+						throw abortError;
+					}
 					const logsText = Array.isArray(result.logs) && result.logs.length > 0 ? "\nCaptured output:\n" + result.logs.join("\n") : "";
 					const sandboxText = result.sandbox === void 0 ? "" : "\nFile sandbox: " + result.sandbox.mode + (result.sandbox.enforcement === void 0 ? "" : "; enforcement: " + result.sandbox.enforcement) + (result.sandbox.denied ? "; operation denied" : "") + ".";
 					const hint = result.sandbox?.denied ? escalationGuidance(runtime.sandboxMode) : "";
-					throw new Error("program failed (" + result.error.kind + "): " + result.error.message + logsText + sandboxText + hint);
+					const failureText = limitError === void 0 || limitError.message === result.error.message ? result.error.message : `${limitError.message}\n${result.error.message}`;
+					throw new CodeRunFailedError("program failed (" + result.error.kind + "): " + failureText + logsText + sandboxText + hint);
 				}
 				return {
 					logs: [...result.logs ?? []],
@@ -1504,32 +1403,257 @@ function validateEscalationArgs(sandboxPermissions, justification) {
 		justification
 	};
 }
+/** 程序源码可能出现的键名。模型偶尔把源码写进 `program` / `source` / `script`。 */
+const CODE_KEYS = Object.freeze([
+	"code",
+	"program",
+	"source",
+	"script",
+	"code_run",
+	"codecode",
+	"program_source",
+	"programSource"
+]);
+/** 模型把「先汇报再执行」写成一次调用时，简报落在 `progress_update` 的那两个键上。 */
+const NARRATION_TITLE_KEY = "title";
+/** 见 {@link NARRATION_TITLE_KEY}。 */
+const NARRATION_MESSAGE_KEY = "message";
+/** 回显原始参数时最多带多少字符。 */
+const RAW_EXCERPT_LIMIT = 120;
+/** 一个值是不是普通对象。 */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 尝试解析一段 JSON 文本。 */
+function tryJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+/**
+* 切出一段文本里的顶层平衡 JSON 对象片段。
+*
+* 模型偶尔把两次调用的参数写进同一段文本（`{"title":…,"message":…}{"code":…}`），
+* 整段 `JSON.parse` 必然失败；按花括号配对切出来的每一段却都还能解析，程序因此可救。
+*
+* @param text - 待切分的原始参数文本。
+* @returns 按出现顺序排列的片段（字符串内的花括号不算）。
+*/
+function topLevelJsonObjects(text) {
+	const fragments = [];
+	let depth = 0;
+	let start = -1;
+	let inString = false;
+	let escaped = false;
+	for (let index = 0; index < text.length; index += 1) {
+		const ch = text[index];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") inString = false;
+			continue;
+		}
+		if (ch === "\"") {
+			inString = true;
+			continue;
+		}
+		if (ch === "{") {
+			if (depth === 0) start = index;
+			depth += 1;
+			continue;
+		}
+		if (ch !== "}") continue;
+		if (depth === 0) continue;
+		depth -= 1;
+		if (depth === 0 && start >= 0) {
+			fragments.push(text.slice(start, index + 1));
+			start = -1;
+		}
+	}
+	return fragments;
+}
+/** 从一个参数对象里读出程序源码。 */
+function codeOf(record) {
+	for (const key of CODE_KEYS) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim().length > 0) return value;
+	}
+}
+/** 从一个参数对象里读出进展简报（`title` / `message` 至少有一个）。 */
+function narrationOf(record) {
+	const title = stringOf(record[NARRATION_TITLE_KEY]);
+	const message = stringOf(record[NARRATION_MESSAGE_KEY]);
+	if (title === void 0 && message === void 0) return void 0;
+	return {
+		title: title ?? message.slice(0, 40),
+		message: message ?? title
+	};
+}
+/** 一个非空字符串（**不裁剪**内容，源码要原样送出）。 */
+function stringOf(value) {
+	return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+/** 错误回显里的一段原始文本。 */
+function excerpt(text) {
+	const flat = text.replace(/[\r\n]+/g, "⏎").replace(/\s+/g, " ").trim();
+	return flat.length <= RAW_EXCERPT_LIMIT ? flat : flat.slice(0, RAW_EXCERPT_LIMIT) + "…";
+}
+/** 参数完全不成形时的错误。 */
+function invalidArgumentsError(args, raw, keys) {
+	if (args === null) return /* @__PURE__ */ new Error("codemode: invalid arguments: expected an object with \"code\" and \"description\" (received null)");
+	if (typeof args !== "string") return /* @__PURE__ */ new Error("codemode: invalid arguments: expected an object with \"code\" and \"description\" (received " + typeof args + ")");
+	if (keys !== void 0 && keys.length > 0) return /* @__PURE__ */ new Error("codemode: invalid arguments: expected an object with \"code\" and \"description\" (received keys: " + keys.join(", ") + ")");
+	if (raw.trim().length === 0) return /* @__PURE__ */ new Error("codemode: invalid arguments: expected an object with \"code\" and \"description\" (received an empty string)");
+	return /* @__PURE__ */ new Error("codemode: invalid arguments: expected an object with \"code\" and \"description\" (received a string that is not a JSON object: " + excerpt(raw) + ")");
+}
+/** 参数里没有程序源码、又不是可救形态时的错误。 */
+function missingCodeError(record, raw) {
+	const keys = Object.keys(record);
+	const note = keys.length === 0 ? "" : " (received keys: " + keys.join(", ") + (raw.trim().length > 0 ? "; raw: " + excerpt(raw) : "") + "; pass program source in \"code\")";
+	return /* @__PURE__ */ new Error("codemode: invalid code: expected a non-empty string" + note);
+}
+/** 一段文本像不像程序源码（模型把源码直接发成字符串时判这个）。 */
+function looksLikeProgram(text) {
+	return text.includes("\n") || /\b(await|return|const|let|function|import|console\.)\b/.test(text);
+}
+/** 从源码首行兜底出一句描述。 */
+function descriptionFromCode(code) {
+	const cleaned = (code.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0) ?? "").replace(/^(\/\/|#)\s*/, "").slice(0, 80);
+	return cleaned.length > 0 ? cleaned : "code program";
+}
+/**
+* 把工具收到的原始参数读成一个对象。
+*
+* ## 为什么要容错
+*
+* 模型有四种真实存在的发送形态，照搬内核 PTC 的严格 schema 会把它们全判死：
+*
+* 1. **原生对象**（正常）；
+* 2. **字符串里的 JSON**（执行器把解析失败的文本原样传下来）；
+* 3. **两段 JSON 拼接**——`{"title":…,"message":…}{"code":…}`，模型想在同一次调用里
+*    既汇报又执行，整段解析必失败，但按花括号切开后两段都合法（实测 7/7 可救）；
+* 4. **只有一段纯程序**（模型直接把源码当参数发）。
+*
+* @param args - 工具收到的原始参数。
+* @returns 参数对象、可选的简报与来源形态。
+*/
+function parseArguments(args) {
+	if (isRecord(args)) return {
+		record: args,
+		origin: "object",
+		raw: ""
+	};
+	if (typeof args !== "string") throw invalidArgumentsError(args, "");
+	const raw = args;
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) throw invalidArgumentsError(args, raw);
+	const parsed = tryJson(trimmed);
+	if (isRecord(parsed)) {
+		const narration = narrationOf(parsed);
+		return {
+			record: parsed,
+			origin: "json",
+			raw,
+			...narration === void 0 ? {} : { narration }
+		};
+	}
+	if (Array.isArray(parsed)) {
+		const hit = parsed.find((entry) => isRecord(entry) && codeOf(entry) !== void 0);
+		if (isRecord(hit)) {
+			const narration = narrationOf(hit);
+			return {
+				record: hit,
+				origin: "json",
+				raw,
+				...narration === void 0 ? {} : { narration }
+			};
+		}
+	}
+	const fragments = topLevelJsonObjects(trimmed);
+	let chosen;
+	let narration;
+	for (const fragment of fragments) {
+		const value = tryJson(fragment);
+		if (!isRecord(value)) continue;
+		if (codeOf(value) !== void 0) {
+			chosen = value;
+			narration ??= narrationOf(value);
+			continue;
+		}
+		narration ??= narrationOf(value);
+	}
+	if (chosen !== void 0) return {
+		record: chosen,
+		origin: fragments.length > 1 ? "fused" : "json",
+		raw,
+		...narration === void 0 ? {} : { narration }
+	};
+	if (looksLikeProgram(trimmed)) return {
+		record: { code: raw },
+		origin: "bare",
+		raw
+	};
+	throw invalidArgumentsError(args, raw, keysOf(fragments));
+}
+/** 把若干 JSON 片段里出现过的键并起来（错误回显用）。 */
+function keysOf(fragments) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const fragment of fragments) {
+		const value = tryJson(fragment);
+		if (!isRecord(value)) continue;
+		for (const key of Object.keys(value)) keys.add(key);
+	}
+	return [...keys];
+}
 /** 校验并读出工具参数。 */
 function readArguments(args) {
-	if (typeof args !== "object" || args === null) throw new Error("codemode: expected an arguments object");
-	const record = args;
-	const code = record["code"];
-	const description = record["description"];
-	if (typeof code !== "string" || code.trim().length === 0) {
-		const received = Object.keys(record);
-		throw new Error("codemode: invalid code: expected a non-empty string" + (received.length === 0 ? "" : " (received keys: " + received.join(", ") + "; pass program source in \"code\")"));
-	}
-	if (typeof description !== "string" || description.trim().length === 0) throw new Error("codemode: invalid description: expected a non-empty string");
+	const parsed = parseArguments(args);
+	const record = parsed.record;
+	const code = codeOf(record);
+	if (code === void 0) throw missingCodeError(record, parsed.raw);
+	const description = stringOf(record["description"])?.trim() ?? stringOf(record["desc"])?.trim() ?? stringOf(record["summary"])?.trim() ?? parsed.narration?.title ?? descriptionFromCode(code);
 	const escalation = validateEscalationArgs(record["sandbox_permissions"], record["justification"]);
 	const timeoutMs = record["timeoutMs"];
-	if (timeoutMs === void 0) return {
-		code,
-		description,
-		...escalation
-	};
-	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("codemode: invalid timeoutMs: expected a positive finite number");
+	if (timeoutMs !== void 0) {
+		if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("codemode: invalid timeoutMs: expected a positive finite number");
+	}
 	return {
 		code,
 		description,
-		timeoutMs,
-		...escalation
+		...timeoutMs === void 0 ? {} : { timeoutMs },
+		...escalation,
+		...parsed.narration === void 0 ? {} : { narration: parsed.narration }
 	};
 }
+/**
+* 把救回来的进展简报补发成一次 `progress_update`。
+*
+* 简报只影响界面，因此这里的任何失败都被吞掉：发不出去（没有投影、没有服务端、外层已取消）
+* 绝不能连累这次程序。
+*
+* @param host - 运行环境句柄。
+* @param narration - 从融合参数里救回来的简报。
+* @param exec - 本次执行上下文。
+* @param signal - 已带嵌套标记的取消信号。
+*/
+async function forwardNarration(host, narration, exec, signal) {
+	try {
+		if (!host.catalog().some((entry) => entry.name === PROGRESS_UPDATE_TOOL)) return;
+		await host.callTool({
+			name: PROGRESS_UPDATE_TOOL,
+			args: {
+				title: narration.title,
+				message: narration.message
+			},
+			callId: String(exec.callId) + ":ptc:0",
+			signal,
+			agent: exec.agent,
+			toolSet: exec.toolSet
+		});
+	} catch {}
+}
 /** 子调用参数必须是可无损 JSON 化的值。 */
 function losslessArgs(value) {
 	if (value === void 0) return {};
@@ -1539,29 +1663,95 @@ function losslessArgs(value) {
 		throw new Error("codemode: tool arguments must be lossless JSON");
 	}
 }
-/** 一个工具的调用是否可以与兄弟调用重叠（只有明确 true 才算）。 */
-function isConcurrencySafe(entry, args) {
-	if (entry === void 0 || typeof entry.isConcurrencySafe !== "function") return false;
-	try {
-		return entry.isConcurrencySafe(args) === true;
-	} catch {
-		return false;
+/** 内置按单文件 `file_path` 寻址的工具名。 */
+const FILE_PATH_TOOLS = /* @__PURE__ */ new Set([
+	"read",
+	"edit",
+	"write",
+	"read_image"
+]);
+/** 内置按目录/目标 `path` 寻址的检索工具名。 */
+const SEARCH_PATH_TOOLS = /* @__PURE__ */ new Set(["glob", "grep"]);
+/**
+* 宿主层子调用入参别名容错：把模型在 `code_run` 内高频写错的参数键名映射到工具真实声明的键名。
+*
+* 审计证据（`session-e190c243` seq 171-182 等）：模型在 `Promise.all` 里容易把 `tools.read` 的
+* `file_path` 写成 `glob`/`grep` 的 `path`（或反过来），或者把 snake_case 写成 camelCase，导致整段
+* 程序因单个属性名不匹配而抛 `ToolCallError: invalid arguments: missing required property "file_path"`。
+*
+* 规则：仅当目标规范键尚未提供（`=== undefined`）、别名键存在且类型匹配、且别名键本身不是该工具声明的
+* 独立参数时，才把值搬运到规范键并删掉多余别名键（防止 `additionalProperties: false` 拒收）。
+*
+* @param entry - 工具清单条目（含参数 schema）。
+* @param value - 已脱离引用的 JSON 参数值。
+* @returns 归一化后的参数值。
+*/
+function normalizeSubCallArgs(entry, value) {
+	if (!isRecord(value)) return value;
+	const name = entry?.name ?? "";
+	const schemaProps = isRecord(entry?.parameters) && isRecord(entry.parameters.properties) ? entry.parameters.properties : void 0;
+	const declares = (key) => schemaProps !== void 0 && Object.prototype.hasOwnProperty.call(schemaProps, key);
+	const out = { ...value };
+	const remap = (target, aliases, predicate) => {
+		if (out[target] !== void 0) return;
+		for (const alias of aliases) {
+			if (declares(alias)) continue;
+			const candidate = out[alias];
+			if (predicate(candidate)) {
+				out[target] = candidate;
+				delete out[alias];
+				return;
+			}
+		}
+	};
+	const isString = (v) => typeof v === "string";
+	const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+	const isBoolean = (v) => typeof v === "boolean";
+	if (FILE_PATH_TOOLS.has(name) || declares("file_path") && !declares("path")) remap("file_path", ["path", "filePath"], isString);
+	else if (SEARCH_PATH_TOOLS.has(name) || declares("path") && !declares("file_path")) remap("path", ["file_path", "filePath"], isString);
+	if (name === "edit" || declares("old_string") || declares("new_string")) {
+		remap("old_string", ["oldString"], isString);
+		remap("new_string", ["newString"], isString);
+		remap("replace_all", ["replaceAll"], isBoolean);
+	}
+	if (name === "win_bash" || declares("workdir")) {
+		remap("workdir", [
+			"cwd",
+			"workingDirectory",
+			"working_directory"
+		], isString);
+		remap("timeoutMs", ["timeout_ms"], isNumber);
+		remap("run_in_background", ["runInBackground"], isBoolean);
+	}
+	if (name === "job_output" || name === "job_kill" || declares("job_id")) {
+		remap("job_id", ["jobId"], isString);
+		if (name === "job_output" || declares("timeout_ms")) remap("timeout_ms", ["timeoutMs"], isNumber);
+	}
+	return out;
+}
+/** 一个工具的调用是否可以与兄弟调用重叠（只有明确 true 才算）。 */
+function isConcurrencySafe(entry, args) {
+	if (entry === void 0 || typeof entry.isConcurrencySafe !== "function") return false;
+	try {
+		return entry.isConcurrencySafe(args) === true;
+	} catch {
+		return false;
 	}
 }
 /**
-* 子调用的并发、提交顺序与互斥屏障（对齐内核 `ptc.ts` 的 ordered commit lane）。
+* 子调用的并发、提交顺序与互斥屏障（对齐内核 `ptc.ts` 的 ordered commit lane + `logWork` 背压）。
 *
+* - `classify()` 在队列头部真正出队启动时惰性求值，保证前序调用产生的状态变更可被观察；
 * - `start()`（记 start 事件 + 启动 body）在 lane 里按提交顺序执行：`parallel` body 之间
 *   可以并发重叠，最多 `maxParallel` 个同时在飞；
-* - `commit()`（记 settle 事件 + 转发图片/附加上下文 + `concludeTurn` + 放行互斥屏障）
-*   按**提交顺序**逐条执行：前一条没提交完，后一条的结果不会先落到会话里；
+* - `commit()`（转发图片/附加上下文 + `concludeTurn` + 放行互斥屏障）按**提交顺序**逐条执行，
+*   并在同步完成上下文挂载后**立刻**将结果返回给程序；`shapeDispatchLog` 与 settle 事件作为
+*   有序后台 `logWork` 执行，超出 `maxParallel` 时在提交车道施加背压；
 * - `exclusive` 调用等所有在飞 body 结算后独占运行，并独占到自己 commit 完成才放行后续；
 * - 排队期间若外层运行已中止，直接放弃且不启动任务（未启动调用零 `start` 事件）；
-* - `drain()` 等到 lane 彻底静止（所有 body 结算、所有 commit 完成）才返回。
+* - `drain()` 等到 lane 彻底静止且所有后台 `logWork` 落盘完成才返回。
 *
-* 程序拿到的值在 commit 里结算（与内核同）：body 结束不保证顺序，提交才是顺序。
-*
-* @param maxParallel - 同时在飞的上限。
+* @param maxParallel - 同时在飞的上限（同时作为 `logWork` 背压上限）。
 * @param isAborted - 外层运行是否已中止。
 * @returns 调度入口与排空。
 */
@@ -1570,6 +1760,8 @@ function createCommitLane(maxParallel, isAborted) {
 	const queue = [];
 	const commitQueue = [];
 	const inFlight = /* @__PURE__ */ new Set();
+	const logWork = /* @__PURE__ */ new Set();
+	let logTail = Promise.resolve();
 	let exclusiveActive = false;
 	let driving = false;
 	let driverRun = Promise.resolve();
@@ -1579,6 +1771,13 @@ function createCommitLane(maxParallel, isAborted) {
 		wake = void 0;
 		release?.();
 	};
+	const enqueueLog = (work) => {
+		logTail = logTail.then(work, work).catch(() => void 0);
+		const tracked = logTail.finally(() => {
+			logWork.delete(tracked);
+		});
+		logWork.add(tracked);
+	};
 	/**
 	* 唯一的有序车道：每一轮先提交队首已结算的调用，再在有空位时启动下一个排队调用，
 	* 否则睡到「有 body 结算或有新提交」为止。三条队列全空即静止。
@@ -1606,8 +1805,10 @@ function createCommitLane(maxParallel, isAborted) {
 							head.abandon();
 							continue;
 						}
-						if (!exclusiveActive && (head.mode === "exclusive" ? inFlight.size === 0 : inFlight.size < cap)) {
-							if (head.mode === "exclusive") exclusiveActive = true;
+						const mode = head.classify();
+						if (!exclusiveActive && (mode === "exclusive" ? inFlight.size === 0 : inFlight.size < cap)) {
+							head.mode = mode;
+							if (mode === "exclusive") exclusiveActive = true;
 							queue.shift();
 							commitQueue.push(head);
 							head.start();
@@ -1630,11 +1831,18 @@ function createCommitLane(maxParallel, isAborted) {
 		return driverRun;
 	};
 	return {
-		schedule(mode, task) {
+		schedule(task) {
 			return new Promise((resolve, reject) => {
 				let parked;
 				const entry = {
-					mode,
+					mode: "exclusive",
+					classify() {
+						try {
+							return task.classify ? task.classify() : "exclusive";
+						} catch {
+							return "exclusive";
+						}
+					},
 					settled: false,
 					flight: Promise.resolve(),
 					start() {
@@ -1659,10 +1867,11 @@ function createCommitLane(maxParallel, isAborted) {
 						const result = parked;
 						if (result === void 0) return;
 						try {
-							resolve(await task.commit(result));
+							resolve(await task.commit(result, enqueueLog));
 						} catch (error) {
 							reject(error);
 						}
+						while (logWork.size > cap) await Promise.race(logWork);
 					},
 					abandon() {
 						try {
@@ -1679,6 +1888,7 @@ function createCommitLane(maxParallel, isAborted) {
 		},
 		async drain() {
 			await drive();
+			while (logWork.size > 0) await Promise.allSettled([...logWork]);
 		}
 	};
 }
@@ -1697,7 +1907,7 @@ async function shapeDispatchContent(host, dispatch) {
 	}
 }
 /** 一个抛出值的消息。 */
-function messageOf$1(error) {
+function messageOf$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 const JSON_INDENT = "  ";
@@ -1790,6 +2000,358 @@ function renderProgramValue(value) {
 	return chunks.join("");
 }
 //#endregion
+//#region src/host/codemode/retention.ts
+/**
+* 常驻执行环境的生命周期与会话级调用协调（对齐内核 `ptc.ts` 与 `PtcCalls`）。
+*
+* 部署把 `@deepseek-ai/dsh-ptc-runtime-node` 配成 `executionMode: persistent-in-memory` 时，
+* 同一个 agent 的多次 `code_run` 会共用一个常驻 REPL：顶层变量、函数与 `import` 的模块
+* 跨调用存活。可以不去用，但**不能只注册不释放**——常驻环境没有空闲过期，忘了释放会让子进程
+* 活到进程结束。
+*
+* 所以这里把「传了 owner」与「注册了释放」写进同一个动作：结构性无法表达「传了却没释放」。
+* 清理有三条路，覆盖所有生命周期终点与显式重置：
+*
+* 1. 挂在 **agent.ctx** 上的释放（对齐 `ptc.ts` 的 `stateOwners`）：展开 Cordis 包装链后按原初
+*    runtime provider 去重登记 `agent.ctx.effect`，即使本包早已卸载，agent 销毁也会释放它的环境；
+* 2. 挂在**插件**上的 teardown：卸载或热重载本包时先中止并排空在飞调用，再释放所有遗留环境；
+* 3. 会话级 `PtcCalls` 协调：新调用进入前等待同会话已取消的前序调用与进行中的 `reset` 彻底排空，
+*    避免前一次取消的收尾清理撞上后一次调用的 `assertIdle()`。
+*
+* @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/retention
+*/
+/** Cordis 服务包装链指向原初实现的符号描述。 */
+const CORDIS_ORIGINAL_DESCRIPTION = "cordis.original";
+/**
+* 造一个常驻环境与会话调用协调管理器。
+*
+* @param runtimeOf - 读当前运行时的函数（每次调用重读，运行时可能晚于本插件挂载）。
+* @returns 管理句柄。
+*/
+function createRetention(runtimeOf) {
+	const live = /* @__PURE__ */ new Set();
+	const released = /* @__PURE__ */ new WeakSet();
+	const stateOwners = /* @__PURE__ */ new WeakMap();
+	const calls = /* @__PURE__ */ new Map();
+	const resets = /* @__PURE__ */ new Map();
+	let disposed = false;
+	const release = async (owner, options) => {
+		const strict = options?.strict === true;
+		if (!strict && released.has(owner)) return;
+		released.add(owner);
+		live.delete(owner);
+		const runtime = runtimeOf();
+		if (runtime?.release === void 0) return;
+		try {
+			await runtime.release(owner);
+		} catch (error) {
+			if (strict) {
+				released.delete(owner);
+				live.add(owner);
+				throw error;
+			}
+		}
+	};
+	/** 在 `agent.ctx` 上按原初 runtime provider 去重挂一次释放钩子（对齐 `ptc.ts:669-684`）。 */
+	const bindAgentLifecycle = (owner) => {
+		const runtime = runtimeOf();
+		if (runtime === void 0 || typeof runtime !== "object" || runtime === null) return;
+		const ctx = owner.ctx;
+		if (typeof ctx?.effect !== "function") return;
+		let runtimes = stateOwners.get(owner);
+		if (runtimes === void 0) {
+			runtimes = /* @__PURE__ */ new WeakSet();
+			stateOwners.set(owner, runtimes);
+		}
+		const provider = unwrapOriginalProvider(runtime);
+		if (runtimes.has(provider)) return;
+		try {
+			ctx.effect(() => () => release(owner), "PTC retained environment");
+			runtimes.add(provider);
+		} catch {}
+	};
+	return {
+		owner(agent) {
+			const owner = typeof agent === "object" && agent !== null ? agent : fallbackOwner;
+			released.delete(owner);
+			live.add(owner);
+			if (owner !== fallbackOwner) bindAgentLifecycle(owner);
+			return owner;
+		},
+		release,
+		async awaitPredecessors(agent, signal) {
+			const key = sessionKeyOf(agent);
+			if (key !== void 0) for (;;) {
+				const reset = resets.get(key);
+				if (reset !== void 0) {
+					try {
+						await reset.done;
+					} catch (error) {
+						throw new CodeRunFailedError("Program environment unavailable: " + messageOf$1(error) + ". Ask the host to reset it before running more code.");
+					}
+					continue;
+				}
+				const pending = [...calls.get(key) ?? []].filter((call) => call.signal.aborted);
+				if (pending.length === 0) break;
+				await Promise.all(pending.map((call) => call.done));
+			}
+			if (signal.aborted) throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason ?? "tool call aborted"));
+			if (disposed) throw new Error("PTC tool executor disposed");
+		},
+		trackRun(run) {
+			const key = sessionKeyOf(run.agent);
+			if (key === void 0) return () => void 0;
+			let bucket = calls.get(key);
+			if (bucket === void 0) {
+				bucket = /* @__PURE__ */ new Set();
+				calls.set(key, bucket);
+			}
+			for (const existing of bucket) if (existing.controller === run.controller) {
+				existing.mode = run.mode;
+				return () => {
+					const current = calls.get(key);
+					if (current !== void 0) {
+						current.delete(existing);
+						if (current.size === 0) calls.delete(key);
+					}
+					existing.resolveDone();
+				};
+			}
+			let resolveDone = () => void 0;
+			const done = new Promise((resolve) => {
+				resolveDone = resolve;
+			});
+			const record = {
+				controller: run.controller,
+				signal: run.signal ?? run.controller.signal,
+				...run.mode === void 0 ? {} : { mode: run.mode },
+				done,
+				resolveDone
+			};
+			bucket.add(record);
+			return () => {
+				const current = calls.get(key);
+				if (current !== void 0) {
+					current.delete(record);
+					if (current.size === 0) calls.delete(key);
+				}
+				record.resolveDone();
+			};
+		},
+		cancelOnModeChange(session, event) {
+			if (typeof event !== "object" || event === null) return;
+			const record = event;
+			if (record.type !== "sandbox/mode") return;
+			const mode = (typeof record.data === "object" && record.data !== null ? record.data : void 0)?.mode;
+			if (typeof mode !== "string") return;
+			const key = sessionKeyOf(session);
+			if (key === void 0) return;
+			for (const call of calls.get(key) ?? []) if (call.mode !== void 0 && call.mode !== mode) call.controller.abort(/* @__PURE__ */ new Error("sandbox mode changed"));
+		},
+		reset(agent, notify) {
+			if (disposed) return Promise.reject(/* @__PURE__ */ new Error("PTC tool executor disposed"));
+			const key = sessionKeyOf(agent) ?? fallbackOwner;
+			const previous = resets.get(key);
+			if (previous !== void 0 && !previous.settled) return previous.done;
+			let resolveDone = () => void 0;
+			let rejectDone = () => void 0;
+			const done = new Promise((resolve, reject) => {
+				resolveDone = resolve;
+				rejectDone = reject;
+			});
+			done.catch(() => void 0);
+			const resetRecord = {
+				done,
+				settled: false
+			};
+			resets.set(key, resetRecord);
+			const active = [...calls.get(key) ?? []];
+			for (const call of active) call.controller.abort(/* @__PURE__ */ new Error("PTC environment reset"));
+			const owner = typeof agent === "object" && agent !== null ? agent : fallbackOwner;
+			Promise.allSettled([Promise.resolve().then(() => release(owner, { strict: true })), ...active.map((call) => call.done)]).then((results) => {
+				const failure = results.find((result) => result.status === "rejected");
+				if (failure !== void 0 && failure.status === "rejected") throw failure.reason;
+				notify?.();
+			}).then(() => {
+				resetRecord.settled = true;
+				resets.delete(key);
+				resolveDone();
+			}, (error) => {
+				resetRecord.settled = true;
+				rejectDone(error);
+			});
+			return done;
+		},
+		async dispose() {
+			disposed = true;
+			const activeCalls = [...calls.values()].flatMap((bucket) => [...bucket]);
+			for (const call of activeCalls) call.controller.abort(/* @__PURE__ */ new Error("PTC tool executor disposed"));
+			await Promise.allSettled([...activeCalls.map((call) => call.done), ...[...resets.values()].map((reset) => reset.done)]);
+			const owners = [...live];
+			await Promise.all(owners.map((owner) => release(owner)));
+		}
+	};
+}
+/**
+* 展开 Cordis 服务代理上的 `[symbols.original]` 链，定位原初 provider 对象。
+*/
+function unwrapOriginalProvider(runtime) {
+	let current = runtime;
+	for (let depth = 0; depth < 8; depth += 1) {
+		let next;
+		for (const sym of Object.getOwnPropertySymbols(current)) if (sym.description === CORDIS_ORIGINAL_DESCRIPTION) {
+			next = current[sym];
+			break;
+		}
+		if (typeof next !== "object" || next === null || next === current) break;
+		current = next;
+	}
+	return current;
+}
+/**
+* 一个会话的身份键（优先用 `session.id`，无 id 时退回会话对象本身）。
+*/
+function sessionKeyOf(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const nested = value.session;
+	const session = typeof nested === "object" && nested !== null ? nested : value;
+	const id = session.id;
+	if (typeof id === "string" && id.length > 0) return id;
+	return session;
+}
+/** 一个抛出值的消息。 */
+function messageOf$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** 没有 agent 的调用（例如服务级直调）共用的 owner。 */
+const fallbackOwner = Object.freeze({ kind: "codemode-sessionless" });
+//#endregion
+//#region src/host/codemode/scope.ts
+/**
+* 工具归属判定：一个名字是**全局层**注册的，还是**本预设**注册的。
+*
+* ## 为什么要这么绕
+*
+* 注册表没有公开「某个工具注册在哪个作用域」的 API。`@deepseek-ai/dsh-scope` 把作用域标签
+* 写在一个模块私有的 `Symbol('dsh.scope')` 上，链关系（parent）也在私有 WeakMap 里，
+* 都不导出。能用的只有两件事：
+*
+* 1. 本包自己所在作用域的 key —— 按符号描述从 ctx 上扫出来（{@link findScopeKey}）；
+* 2. 公开的 `ctx.tools.get(name)`（全局视图）与 `ctx.tools.get(name, key)`（该作用域视图）。
+*
+* 于是归属判定变成两次公开查询：
+*
+* - 全局视图能解析 → 全局层（MCP 服务端、profile 级 bundle）；
+* - 只有本预设视图能解析 → 本预设自己注册的；
+* - 两处都解析不到 → 只可能注册在本预设之下（agent 层）。
+*
+* 探测失败（本包被挂在 host 层而不是预设里）时返回 `enabled: false`：规则整体降级为
+* 纯名字匹配，绝不因为读不到归属就误遮蔽。
+*
+* @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/scope
+*/
+/** 内核写作用域标签用的符号描述。 */
+const SCOPE_SYMBOL_DESCRIPTION = "dsh.scope";
+/**
+* 从一个 ctx 上找出「本包所在作用域」的 key。
+*
+* Cordis 的 scoped context 把作用域标签写成自有（或原型上）的一个 symbol 属性，
+* 描述是 `dsh.scope`。这里按描述扫，不猜符号本身——写法与参考实现一致，因为
+* 直接 `import` 内核的 scope 包在 profile 插件里解析不到。
+*
+* @param ctx - 本包的行上下文。
+* @returns 作用域 key；读不到时为 `undefined`。
+*/
+function findScopeKey(ctx) {
+	if (typeof ctx !== "object" || ctx === null) return void 0;
+	return scanForScope(ctx, 0);
+}
+/** 在对象自身及其原型链上找作用域标签（只看 symbol 属性，深度上限 4）。 */
+function scanForScope(source, depth) {
+	if (depth > 4) return void 0;
+	let symbols;
+	try {
+		symbols = Object.getOwnPropertySymbols(source);
+	} catch {
+		return;
+	}
+	for (const symbol of symbols) {
+		if (symbol.description !== SCOPE_SYMBOL_DESCRIPTION) continue;
+		let value;
+		try {
+			value = source[symbol];
+		} catch {
+			continue;
+		}
+		if (typeof value === "object" && value !== null) return value;
+	}
+	const proto = Object.getPrototypeOf(source);
+	if (proto === null || proto === Object.prototype) return void 0;
+	return scanForScope(proto, depth + 1);
+}
+/**
+* 为一个名字清单建立归属视图。
+*
+* @param tools - 工具注册表（结构探测，不看类身份）。
+* @param scopeKey - 本预设的作用域 key；`undefined` 表示探测失败。
+* @param names - 要判定的名字（通常是本步的模型可见清单）。
+* @returns 归属视图；读不到任何归属时返回禁用视图。
+*/
+function resolveCatalogView(tools, scopeKey, names) {
+	const registry = asRegistry(tools);
+	if (scopeKey === void 0 || registry === void 0) return DISABLED_VIEW;
+	const globalNames = /* @__PURE__ */ new Set();
+	const presetNames = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		if (typeof name !== "string" || name.length === 0) continue;
+		if (probes(registry, name, void 0)) globalNames.add(name);
+		if (probes(registry, name, scopeKey)) presetNames.add(name);
+	}
+	return {
+		enabled: true,
+		globalNames,
+		presetNames
+	};
+}
+/**
+* 判定一个名字在**调用时**是否属于本预设之外的层。
+*
+* 拒绝路径（模型直呼被遮蔽的名字）没有当步清单可用，只能按同一个视图单独判一次；
+* 判定规则与 {@link resolveCatalogView} 完全一致，两处因此不可能给出互相矛盾的结论。
+*
+* @param tools - 工具注册表。
+* @param scopeKey - 本预设的作用域 key。
+* @param name - 工具名。
+* @returns 归属视图（只含这一个名字）。
+*/
+function resolveNameView(tools, scopeKey, name) {
+	const registry = asRegistry(tools);
+	if (scopeKey === void 0 || registry === void 0) return DISABLED_VIEW;
+	const globalNames = /* @__PURE__ */ new Set();
+	const presetNames = /* @__PURE__ */ new Set();
+	if (probes(registry, name, void 0)) globalNames.add(name);
+	if (probes(registry, name, scopeKey)) presetNames.add(name);
+	return {
+		enabled: true,
+		globalNames,
+		presetNames
+	};
+}
+/** 一次公开查询：解析得到定义时为 `true`。 */
+function probes(registry, name, scope) {
+	try {
+		return registry.get(name, scope) !== void 0;
+	} catch {
+		return false;
+	}
+}
+/** 结构探测：读得到 `get` 就当注册表用。 */
+function asRegistry(tools) {
+	if (typeof tools !== "object" || tools === null) return void 0;
+	if (typeof tools.get !== "function") return void 0;
+	return tools;
+}
+//#endregion
 //#region src/entry-codemode.ts
 /**
 * Code Mode 预设行 —— 本包自己的「原生工具 + 程序传输」呈现方式。
@@ -1881,52 +2443,8 @@ function apply(ctx, config = {}) {
 	if (typeof context.effect === "function") context.effect(() => () => {
 		retention.dispose();
 	}, "codemode retained environments");
-	/** 在飞运行：会话键 → 该会话里正在跑的程序。 */
-	const activeRuns = /* @__PURE__ */ new Map();
-	/**
-	* 登记一只在飞运行，返回运行结算时的 disposer。
-	*
-	* 传输层每轮运行（含常驻环境换策略后的重跑）都登记一次，入口因此知道「这一轮跑在哪个
-	* 会话、当时的沙箱模式是什么」。会话切模式时，模式不匹配的运行必须停：常驻环境换策略
-	* 会抛错，而已经跑起来的那一轮不能继续用旧权限往下写。
-	*/
-	const trackRun = (run) => {
-		const key = sessionKeyOf(run.agent);
-		if (key === void 0) return () => void 0;
-		const record = {
-			controller: run.controller,
-			...run.mode === void 0 ? {} : { mode: run.mode }
-		};
-		let bucket = activeRuns.get(key);
-		if (bucket === void 0) {
-			bucket = /* @__PURE__ */ new Set();
-			activeRuns.set(key, bucket);
-		}
-		bucket.add(record);
-		return () => {
-			const current = activeRuns.get(key);
-			if (current === void 0) return;
-			current.delete(record);
-			if (current.size === 0) activeRuns.delete(key);
-		};
-	};
-	/**
-	* 会话的 `sandbox/mode` 事件：生效模式已经变了的在飞运行直接取消（内核 `PtcCalls` 同此）。
-	*
-	* 只取消「能确认模式变了」的那些：拿不到模式（运行时不管沙箱）或模式相同的运行一律不动。
-	*/
-	const cancelOnModeChange = (session, event) => {
-		if (typeof event !== "object" || event === null) return;
-		const record = event;
-		if (record.type !== "sandbox/mode") return;
-		const mode = (typeof record.data === "object" && record.data !== null ? record.data : void 0)?.mode;
-		if (typeof mode !== "string") return;
-		const key = sessionKeyOf(session);
-		if (key === void 0) return;
-		for (const run of activeRuns.get(key) ?? []) if (run.mode !== void 0 && run.mode !== mode) run.controller.abort(/* @__PURE__ */ new Error("sandbox mode changed"));
-	};
 	if (typeof context.on === "function") try {
-		const off = context.on("session/event", cancelOnModeChange, { global: true });
+		const off = context.on("session/event", retention.cancelOnModeChange, { global: true });
 		if (typeof context.effect === "function") context.effect(() => () => {
 			if (typeof off === "function") off();
 		}, "codemode sandbox mode cancellation");
@@ -1953,10 +2471,27 @@ function apply(ctx, config = {}) {
 	};
 	const scopeKey = findScopeKey(ctx);
 	if (rules.options.nativeScope && scopeKey === void 0) log("warn", "[codemode] no registry scope tag on this context: masking falls back to name rules only (" + rules.options.hiddenPrefixes.join(", ") + "). Mount this row inside an agent preset to hide every tool the preset does not own.");
-	/** 最近一次 describe 收到的完整定义集（含被遮蔽的）。 */
+	/** 最近一次 describe 收到的完整定义集（含被遮蔽的），作为无 `tools.definitions` 时的回退快照。 */
 	let catalog = [];
 	const debugRing = [];
 	let firstDescribeLogged = false;
+	/**
+	* 解析当前调用方 agent 与步骤准入下的工具清单（对齐内核 `ptc.ts:662`）。
+	*
+	* 优先通过 `ctx.tools.definitions(agent, toolSet)` 实时读取调用方自己的可见集合（含
+	* `agent.ctx` 专属工具与 `tools.restrict` 过滤），避免多会话并发时被另一个会话的
+	* `describe()` 覆盖；测试替身未提供 `definitions` 时回退到最近一次 `catalog`。
+	*/
+	const resolveCatalog = (agent, toolSet) => {
+		if (agent !== void 0 && typeof tools.definitions === "function") try {
+			const defs = tools.definitions(agent, toolSet);
+			if (Array.isArray(defs) && defs.length > 0) {
+				const entries = defs.map(toCatalogEntry).filter((entry) => entry !== void 0);
+				if (entries.length > 0) return entries;
+			}
+		} catch {}
+		return catalog;
+	};
 	const escalateSandbox = async (input) => {
 		const record = typeof input.standingPolicy === "object" && input.standingPolicy !== null ? input.standingPolicy : void 0;
 		const effectiveMode = typeof record?.["mode"] === "string" ? record["mode"] : void 0;
@@ -1989,10 +2524,11 @@ function apply(ctx, config = {}) {
 		}
 	};
 	const host = {
-		catalog: () => catalog,
+		catalog: (agent, toolSet) => resolveCatalog(agent, toolSet),
 		runtime: runtimeOf,
 		stateOwner: (agent) => retention.owner(agent),
 		releaseOwner: (owner) => retention.release(owner),
+		awaitPredecessors: (agent, signal) => retention.awaitPredecessors(agent, signal),
 		runAuthority,
 		escalateSandbox,
 		createImageContext(content) {
@@ -2001,7 +2537,7 @@ function apply(ctx, config = {}) {
 				source: { kind: PLUGIN_MESSAGE_SOURCE_KIND }
 			});
 		},
-		trackRun,
+		trackRun: (run) => retention.trackRun(run),
 		shapeDispatchLog,
 		async callTool(request) {
 			const call = {
@@ -2065,6 +2601,25 @@ function apply(ctx, config = {}) {
 		onCatalog: (definitions) => {
 			catalog = definitions.map(toCatalogEntry).filter((entry) => entry !== void 0);
 		},
+		async reset(agent) {
+			const runtime = runtimeOf();
+			if (runtime === void 0) throw new Error("codemode: no PTC runtime is mounted (ctx.ptcRuntime); the program transport is unavailable");
+			if (!runtime.retainsState) throw new CodeResetFailedError("The PTC runtime does not retain an environment");
+			try {
+				await retention.reset(agent, () => {
+					const inject = typeof agent === "object" && agent !== null ? agent.inject : void 0;
+					if (typeof inject === "function") inject.call(agent, createUserMessage({
+						content: [{
+							type: "text",
+							text: "Program environment reset; retained variables cleared. Completed tool effects remain."
+						}],
+						source: { kind: PLUGIN_MESSAGE_SOURCE_KIND }
+					}));
+				});
+			} catch (error) {
+				throw new CodeResetFailedError("Program environment reset failed: " + messageOf(error) + ". State may not be cleared; retry the host reset before running more code.");
+			}
+		},
 		onDescribe: (decision) => {
 			const hidden = summarizeHidden(decision.masked);
 			debugRing.push({
@@ -2145,24 +2700,6 @@ function errorInfoOf(result) {
 function nonEmptyString(value) {
 	return typeof value === "string" && value.length > 0 ? value : void 0;
 }
-/**
-* 一个会话的身份键。
-*
-* 优先用会话 id（与内核 `session/event` 监听器里的 `session.id` 对齐）；取不到 id 时退回
-* 会话对象本身——调用方 agent 上的 `session` 与事件里的会话是同一个对象，靠身份比对同样
-* 成立。连会话都没有时返回 `undefined`，这类运行不参与取消。
-*
-* @param value - 一个 agent，或一个会话对象。
-* @returns 会话 id / 会话对象，或 `undefined`。
-*/
-function sessionKeyOf(value) {
-	if (typeof value !== "object" || value === null) return void 0;
-	const nested = value.session;
-	const session = typeof nested === "object" && nested !== null ? nested : value;
-	const id = session.id;
-	if (typeof id === "string" && id.length > 0) return id;
-	return session;
-}
 /** 把内容块里的文本拼起来。 */
 function textOf(content) {
 	if (!Array.isArray(content)) return "";