@sema-agent/server 7.43.0 → 7.44.0

package/dist/boot/coordinators.js

@@ -9,46 +9,15 @@ import { basename, resolve } from "node:path";
 import { stat as fsStat, readFile as fsReadFile } from "node:fs/promises";
 export function createLiveCoordinators(ctx) {
     const { config, logger, backend, sendUserFileTaskEnvs, ruleConsent, ruleScopeRootFor, getParkedRedeem } = ctx;
-    // E23 (shell-host contract): inbound MCP elicitation coordinator (live-only HITL). Present ONLY when MCP_ELICITATION_ENABLED
-    // — absent ⇒ onElicit is not wired ⇒ core advertises no elicitation capability to any server (fail-closed). Shared
-    // by the runner (the onElicit seam) and the HTTP layer (the respond route + the per-run ALS context wraps).
     const elicitation = config.mcpElicitation.enabled ? new ElicitationCoordinator(config.mcpElicitation.throttle) : undefined;
-    // §4④: AskUserQuestion LIVE-stream HITL coordinator — the sibling of `elicitation`. Present ⇒ wired onto
-    // `RunnerDeps.onQuestion` (core mounts the AskUserQuestion tool + routes live asks here) AND consumed by the HTTP layer
-    // (the `POST /v1/questions/:id/respond` route + the per-run ALS context wraps on the streaming legs). Absent ⇒ core
-    // mounts the tool with the headless default (a run never hangs; the model just can't get a live answer).
-    // #166 裁2 接线:三旋钮(QUESTION_TTL_MS / QUESTION_MAX_*_PER_RUN)从 config 通到协调器;缺席=构造器
-    // 内建 DEFAULT_QUESTION_THROTTLE,默认值恒等钉在 test/question-unavailable.test.ts。
     const question = config.askQuestionEnabled ? new QuestionCoordinator(config.questionThrottle) : undefined;
-    // [816]/[820]②: the live tool-approval HITL coordinator — the sibling of `question` on core's `RunnerDeps.onAsk`
-    // seam (1.290 sync-ask leg). Present ⇒ a policy `ask` on a LIVE streaming leg becomes a `tool_approval` frame the
-    // shell renders as the CC three-choice card, answered via POST /v1/tool-approvals/:id/respond.
-    // [1535] 正名(旧文「background/workflow ⇒ headless auto-deny stands」已过时):宿主 sync 腿现同时装
-    // `spec.onAsk = boundAsk(ctx)`(装配点在 `http/routes/tasks.ts`,design/158 A9 从 server.ts 拆出后
-    // 的全树唯一装配点)——core 继承链把闭包冻给委派子代,**bg/嵌套子代的
-    // ask 浮到宿主 live 流**(带 sourceTaskId);真正无宿主流的腿(durable-submit/headless resume)才留
-    // 「unavailable → durable park;无 park 设施 core fail-closed deny」。durable 部署 G1 语义不变。
-    // [1.294 G1] durable 姿势必须在 runnerDeps 字面量之前可判(onAsk 的「在场性」本身就是 core suspendAsk 的
-    // 分路条件,不能再靠闭包惰性读)——判据与 checkpointStore 的构造条件同源(backend?.checkpoint 存在 ∧
-    // DURABLE_APPROVAL;store 本体已上移至 subRunner 构造前,[1535] 断点② 双 Runner 挂载)。
-    // 🔴 #151 车3 刀 3b:本行**上移**到协调器构造之前 —— 它同时是流内审批协议的「park 设施在场性」判据
-    //    (§8.4),而协调器要在构造那一刻就知道自己带不带 askStore。位置即契约的原约束(必须在 RunnerDeps
-    //    字面量之前)不变,只是又提前了几行。
     const durableEnabled = backend?.checkpoint !== undefined && config.durableApproval === true;
-    // #151 车3 刀 3b(设计稿 §2.3 + §8.4):协议上场判据走**单一谓词**(与 /v1/capabilities 的
-    // `streamApproval` 格、与回决端点的 501 门同一个符号,见 resolveStreamApprovalGate 顶注)。
     const streamApprovalGate = resolveStreamApprovalGate({
         toolApprovalEnabled: config.toolApprovalEnabled === true,
         streamApprovalEnabled: config.streamApproval.enabled,
         backend,
         parkFacility: durableEnabled,
     });
-    // §8.4:协议**开着**却上不了场 = 合法部署形(不是配置错误)⇒ 一行 **info**(不是 warn),把原因说明白。
-    // 反过来「开关本来就没开」不打日志:显式关掉的部署自己知道为什么关,一行噪音没有信息量。
-    // ⚠️ 读数已反转:总开关默认在树上已是 ON(版本坐标见 config.ts 的 `streamApprovalConfig()` 头注),
-    // 所以这一行在**默认部署**上是常态 —— 任何没有 durable
-    // backend / park 设施的默认部署每次启动都会打一行 `stream_approval_disabled`(每次启动一行,不是每
-    // tick)。写这条判据时的前提「默认形绕开本路径」已不成立;要收紧,收紧点在本 if 而不是在开关处。
     if (config.streamApproval.enabled && !streamApprovalGate.active) {
         logger.info("stream_approval_disabled", {
             reason: streamApprovalGate.reason,
@@ -60,65 +29,31 @@ export function createLiveCoordinators(ctx) {
     }
     const toolApproval = config.toolApprovalEnabled
         ? new ToolApprovalCoordinator({
-            // 协议上场 ⇒ 持久层 + 配置窗(§7:`STREAM_ASK_WINDOW_MS` **只在开关内**生效,
-            // `DEFAULT_APPROVAL_TTL_MS` 一个字不动);不上场 ⇒ 两者都不传,窗保持既有 5min(D1 逐字不变)。
-            // ⚠️ 两臂的窗**默认已同长**:窗默认自 7.5.0 起 = 300000 = `DEFAULT_APPROVAL_TTL_MS`(clay 同裁把
-            // 「窗变短」从翻真里摘出去)。原注画的「上场 = 60s / 不上场 = 5min」这个对比在默认配置下不存在
-            // 了,别据它得出「开了协议窗会缩短」的运维结论:上场与否改变的是**持久层与协议帧**,窗只有在
-            // 部署显式设了 `STREAM_ASK_WINDOW_MS` 时才分叉。
             ...(streamApprovalGate.active ? { askStore: streamApprovalGate.askStore, ttlMs: config.streamApproval.windowMs } : {}),
-            // 余量旋钮恒传(既有键,窗长三元公式的第二项;legDeadlineMonotonic 缺席时它不参与计算)。
             windowMarginMs: config.streamAskWindowMarginMs,
-            // X-2 写侧准入门两帽(协议未上场时门本身不参与,见 ToolApprovalCoordinator.admit)。
             admitMaxPerTask: config.streamApproval.admitMaxPerTask,
             admitMaxPerOwner: config.streamApproval.admitMaxPerOwner,
-            // #154 车二:同意车道(缺席 = 规则店没装配 ⇒ 帧上零候选、回决的 persistRule 如实拒)。
             ...(ruleConsent !== undefined ? { ruleConsent } : {}),
-            // #295(F-1):卡批规则 project root 解析器(缺席 ⇒ 落 global,修前行为)。
             ...(ruleScopeRootFor !== undefined ? { ruleScopeRootFor } : {}),
-            // #280 R-13 C:无人值守政策(闭集 park|deny)。**恒传**(不挂任何在场性推断):它是纯部署级的一位,
-            // 语义/三问/射程边界一处成文见 `config-types.ts` 的 `unattendedApprovalPolicy` 域注。
-            // ⚠️ 恒传是**刻意**的,不是顺手(codex R2-F2 点过这一行):`streamApprovalGate.active` 为假时只
-            // 省略 askStore/窗,协调器照常在场,R-13 的 D1 窗到期臂照样按政策走 —— 那正是设计稿点名的主受益
-            // 部署(park 的承载是 core checkpoint,不是 ask 行)。把政策挂到协议开关上会把它整个切掉。
-            // 协调器本身缺席时(`TOOL_APPROVAL_ENABLED` 关)本旋钮无处施加 —— 成文事实,不是推断腿。
             unattendedPolicy: config.unattendedApprovalPolicy,
-            // #329:PARKED 行迟到决议的赎回席(晚绑取值口,见 LiveCoordinatorsCtx.getParkedRedeem)。
             ...(getParkedRedeem !== undefined ? { parkedRedeem: getParkedRedeem } : {}),
         })
         : undefined;
-    // SendUserFile(真 CC 契约,clay 2026-07-14)两种 lane 形态,其余缺席=诚实(工具不进 roster):
-    //  - host lane:本地盘读+服务端上传,【单用户 only】——host 多租户=任意路径读→公网 URL 的 exfil 面,
-    //    clay 拍永久关死,不留口子。路径=绝对或相对 process.cwd(用户目录语义,与 CC 一致)。
-    //  - e2b/k8s lane(v2,Plan B 直传):沙箱内 stat+`curl -T` 打 server 预签的单对象 PUT(字节不中转、
-    //    凭据不进沙箱);沙箱自身文件系统=租户边界,故任意租户可用。
-    //  - ssh lane(后补 2026-07-14):同一直传链,但 peer=跨任务共享的真实主机(非租户边界)→
-    //    【单用户 only】,租户门在 sandboxSendLaneEnabled(多租户下注册表不建,工具诚实缺席)。
-    //    adb/local-docker 仍后补。
-    // 签发面缺 S3_PUBLIC_ENDPOINT 时 issue-time fail-loud(工具在但用即报修法);100MiB/文件帽在各 send 面。
     const sendUserFileEmitter = (() => {
         if (!config.sendUserFile)
             return undefined;
         if (sendUserFileTaskEnvs)
-            return new SendUserFileEmitter(); // e2b/k8s/ssh(单用户):注册表已就位(lane+租户+签发面判定)
-        // unset REMOTE_EXEC(in-process/TOC 本地形态)有意归入 host 语义:exec 与文件都在本机,单用户门
-        // 同样把关(codex 复审提出收紧到显式 "host";判定=不收——unset 单机+配了 S3 是合法 dev/TOC 场景,
-        // 且与 1.187.0 已发行为一致;真正的红线是 requirePrincipal 多租户,这里恒关)。
+            return new SendUserFileEmitter();
         const provider = config.remoteExec?.provider ?? "host";
         if (provider === "host" && config.requirePrincipal !== true)
             return new SendUserFileEmitter();
         return undefined;
     })();
-    // SendUserFile 账本(多租户治理面,[768]②a 后半):key 里的 scope 段是哈希(URL 不泄 principal),
-    // 按租户列/撤销的 scope↔对象映射记在 server 侧账本(四后端孪生,sendfile_link / JSONL)。有 backend 即建
-    // (签发面也配了才有写点);无 backend(env-only worker)= 无账本 = 不记账不 501 治理面(诚实缺席,
-    // capabilities.sendUserFileLedger=false)。
     const sendFileLedger = config.sendUserFile && backend ? backend.sendFileLedger() : undefined;
     const sendUserFileToolSpec = (() => {
         if (!sendUserFileEmitter || !config.sendUserFile)
             return undefined;
         const issuer = createSendUserFileIssuer(config.sendUserFile);
-        // 两条 lane 的 send 都把 ctx.principal(core VERIFIED)传给签发面 → key 带哈希 scope 段 + link 携原文 scope。
         const rawSend = sendUserFileTaskEnvs
             ? createSandboxFileSend({
                 registry: sendUserFileTaskEnvs,
@@ -133,13 +68,10 @@ export function createLiveCoordinators(ctx) {
                 if (st.size > SEND_USER_FILE_MAX_BYTES)
                     throw new Error(`file exceeds the ${Math.floor(SEND_USER_FILE_MAX_BYTES / (1024 * 1024))} MiB per-file cap (${st.size} bytes)`);
                 const bytes = await fsReadFile(resolved);
-                // 读后复验(codex 复审 MED):stat→read 间文件可增长——上传的是读到的字节,帽必须按真实字节数把关。
                 if (bytes.byteLength > SEND_USER_FILE_MAX_BYTES)
                     throw new Error(`file exceeds the ${Math.floor(SEND_USER_FILE_MAX_BYTES / (1024 * 1024))} MiB per-file cap (${bytes.byteLength} bytes)`);
                 return issuer.issue(bytes, basename(resolved), undefined, sendCtx.principal);
             };
-        // 账本写点(两 lane 同语义):上传+verify 成功后、file_link 帧前记账;记账失败=该文件 fail-loud +
-        // best-effort 删已传对象(治理面必须有行;删失败 warn)。无账本(env-only)= 直通,行为与 1.189 一致。
         const send = sendFileLedger
             ? withLedgerRecording(rawSend, {
                 ledger: sendFileLedger,

package/dist/boot/crash-last.js

@@ -1,32 +1,18 @@
-/**
- * #320①([4728] clay 五点令)—— 崩溃遗言面 `crash-last.json`。
- *
- * 契约:**文件在场 ⇔ 上一次退出=崩溃**。铸点唯一=shutdown.ts 的 uncaught 双钩(写完仍 exit(1),
- * 不吞崩溃);受控退(hardShutdown 收尾链)`clearCrashLast` 删文件——两形可判别就靠这一删:不删的话
- * 文件语义退化成「历史上最后一次崩溃」,运维无从判「上次到底怎么退的」。
- *
- * 写路径全同步(`writeFileSync`):崩溃现场没有事件循环可信赖,async 写在 exit 前不保证落盘。
- * err 只取**首行**且过 `redactSecrets`——崩溃消息常含连接串/token(DSN 在 error.message 里是
- * 常见形,#305 同病),遗言是**判别位**不是取证档,stack 不落盘。
- */
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { redactSecrets } from "../trace/redact.js";
-/** 遗言文件的读回 schema(宪法 [2704] §2:边界读一律 safeParse,不裸铸)。写侧五键同形。 */
 const CrashLastSchema = z.object({
     at: z.string(),
     version: z.string(),
     pid: z.number(),
     uptimeMs: z.number(),
-    /** 崩溃瞬间的在飞腿数(inflight getter 可用时);拿不到=键缺席,不编 0。 */
     inflight: z.number().optional(),
     err: z.string(),
 });
 export function crashLastPath(dataRoot) {
     return join(dataRoot, "crash-last.json");
 }
-/** 崩溃现场写遗言(同步;自身绝不抛——遗言写失败不能遮蔽原崩溃)。 */
 export function writeCrashLast(dataRoot, info) {
     try {
         const raw = info.err instanceof Error ? info.err.message : String(info.err);
@@ -42,19 +28,15 @@ export function writeCrashLast(dataRoot, info) {
         writeFileSync(crashLastPath(dataRoot), JSON.stringify(body) + "\n");
     }
     catch {
-        // 遗言面自身故障(只读 FS 等)静默——崩溃路径上没有更好的去处,原错误仍会打到 stderr。
     }
 }
-/** 受控退收尾:删遗言(幂等,缺席零抛)。 */
 export function clearCrashLast(dataRoot) {
     try {
         unlinkSync(crashLastPath(dataRoot));
     }
     catch {
-        // ENOENT(本就没有)与其余失败同置:清不掉只意味着下次 boot 多一行提示,绝不阻塞停机。
     }
 }
-/** boot 提示腿:在场读回、缺席/坏字节/坏形回 `undefined`(绝不抛——遗言坏了不能挡启动)。 */
 export function readCrashLast(dataRoot) {
     try {
         const p = crashLastPath(dataRoot);

package/dist/boot/deferred-sandbox-path-env.js

@@ -1,87 +1,15 @@
-/**
- * #165 —— 沙箱 lane(e2b/k8s/ssh/adb/local-docker)写门的**真 env 裁决**接法。
- *
- * ## 缺口与它的形状
- *
- * core 的 `createFsWriteGatePolicy` / `createSensitivePathPolicy` 把每一个写目标交给
- * `canonicalizeTarget(env, …)` 去问 fs 要真身(`absolutePath` → `exists` → `canonicalPath` →
- * `fileInfo`/`readLink` 逐跳,dist 亲读)。host lane 上那个 env 就是 hand 工具真正写的那块盘。
- * 沙箱 lane 不是:per-task 的沙箱 env 由 core 的 `executionEnvFactory` 在 spec **之后**才铸,
- * 而写门 wiring 必须在 spec 期就交出去。
- *
- * 出路不是把裁决搬去 hook 层(那要在本仓复刻 `canonicalizeTarget` 的逐级 exists / symlink 解析 /
- * 段匹配 / 折叠序——复制 core 的裁决逻辑=同源谎),而是利用一个部署事实:**那个 per-task 沙箱 env
- * 本来就是本仓铸的**。于是本模块给写门一个 ExecutionEnv **代理**:它在**调用时刻**(runToolGate 裁决,
- * 必在 prepare 之后)去 slot 里取该 task 的真 env 并转发 fs 读原语。call-time 转发消除了时序问题,
- * 与「从调用上下文读 env」是同一性质。
- *
- * ## 三条不可动的裁定
- *
- *  1. **`absolutePath` 一面不转发**,沿用词法规则(POSIX 绝对形归一 / NUL 拒 / 非绝对形 err)。
- *     真 env 的 `absolutePath` 会按 **env 自己的 cwd** 解析相对路径,而工具真写处按 engine 跟踪的
- *     cwd 解析——两个基准不同,转发它等于拿错基准铸 canonical key,而**错误的 allow 比没有门更糟**。
- *     相对形 / `~` / 盘符形因此照旧 err ⇒ `canonicalizeTarget` 失败 ⇒ 写门 `ask`(fail-closed)。
- *     「不猜沙箱工作目录」这条公理不随真 env 到场而松。
- *  2. **slot 空 = fail-closed 且响亮**:转发面返回错误 ⇒ core 把 `exists` 报错读成
- *     `unresolvedSymlink` ⇒ `createSensitivePathPolicy` 判 deny、写门判 ask,折叠后 deny 恒赢。
- *     保护型缺席的失败方向必须与能力语义同向。留痕走结构化 `warn`(每实例一次)而**不**走
- *     `observability/fail-open.ts`:那个词表按其模块头是 `F`(体验/缓存回退)与 `P-DEBT`(明知方向
- *     不对的保护型欠账)两类的准入面,本臂方向是**对的**(fail-closed),登记进去会把「已收口的
- *     保护臂」混进「待还的债」计数里。
- *  3. **slot 只认「当前活腿」**:同一 session 同时只有一条活腿(HTTP `conflict.session_active_run` +
- *     core session acquire 双重串行化;委派子代另用一个 sessionId),所以同键改铸即顶替旧登记——
- *     那些旧登记来自 park-only 之类「不 destroy 也不 suspend」的终局,留着只会让 resume 腿失去真身裁决。
- *
- * ## slot 的键 = sessionId
- *
- * 工厂 ctx 只有 `{sessionId, taskId?, isolation?, parentCwd?}`(core `ExecutionEnvFactoryContext`),
- * 而 `/v1/runs` 会在 resolveSpec **之后**铸自己的持久 taskId 覆盖 `spec.taskId`,所以 taskId 在主路径
- * 上对不上——sessionId 是两侧都稳的那一个(per-task 镜像登记簿是同一个先例)。
- * 委派子任务(Agent / workflow 子代)拿的是**另一个** sessionId,所以父的 slot 不会被子代覆盖(「不许
- * 最后写赢」由此成立)。**残余面**:子代的写仍按**父**的 env 裁决——子代的 policy 就是父的那一个实例
- * (core `inheritedGateForChildren` 把它当 parentConstraint 继承),而 policy 收到的只有
- * `{toolName, args, toolCallId}`,读侧根本没有腿身份可键控。方向上它逼近真相而非远离(过渡形是「谁的盘
- * 都不看」),但有一条**新的松面**:父盘上一个名叫守卫段、真身良性的软链,会让子代在自己盘上指向真守卫段
- * 的同名路径拿到父盘的宽松答案。收口需要一条「按当前工具调用的 env 裁决」的引擎缝,属设计件;
- * 该面由 test/task-settings.test.ts 的「真身胜过名字」特征化钉机器可见。
- */
 import { posix } from "node:path";
 import { FileError, StubExecutionEnv, err, ok } from "@sema-agent/core";
-/** 哪些 lane 用本模块的代理裁决写门 —— `REMOTE_EXEC` 未设(进程内 host)与显式 `host` 之外的全部。
- *  与 resolve-spec 的 `hostSemanticsLane` 是同一判别式的两面,取值处**只此一个**(两处各写一份正是漂移的成因)。 */
 export function isSandboxPathAdjudicationLane(provider) {
     return provider !== undefined && provider !== "host";
 }
-/** 词法归一:纯字符串运算,折 `.` / `..` / 重复分隔符,不碰 fs。
- *  `posix.normalize` 把 `..` 在根部截断(`/../x` → `/x`),与「沙箱根之上没有东西」的语义一致。
- *  尾部分隔符统一剥掉(根 `/` 除外),让同一目标只有一个 key ——前缀判域靠的就是 key 的唯一性。
- *  (core 内部有同形的 `normalizeAbsPathLexically`,但未从包根导出;此处是 Node 标准库的等价运算,
- *   不是它的抄本——若日后 core 导出,这里应改为直接复用。) */
 function normalizeAbsolutePathLexically(path) {
     const collapsed = posix.normalize(path.replace(/^\/+/, "/"));
     return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
 }
-/** 同时可登记的 session 数上限。到顶后先清死条目,仍满则**拒收新键、绝不驱逐在场者**:被拒的 session
- *  只是拿不到真 env(⇒ fail-closed),而驱逐一个在场者会让一个正在跑的 task 的写门突然失去真身裁决。 */
 const MAX_BOUND_SESSIONS = 4096;
-/**
- * per-session 的真 env 登记簿 —— 工厂装饰器写,写门代理读。
- *
- * **同键改铸 = 顶替**(不排队、不判歧义)。依据是一条被两道门执法的不变量:一个 session 同时只有一条
- * 活腿(HTTP 层 `conflict.session_active_run` + core 的 session acquire),而委派子代用的是**另一个**
- * sessionId。所以工厂为某 session 铸出新 env 的那一刻,同键上还留着的登记按构造已经是死腿——最典型的
- * 产地是 **park-only 车道**(非 suspendable 的远程 env:durable park 既不 `suspendVM` 也不 `destroy`,
- * core 的 `teardownOwnedEnv` 在 checkpoint token 在场时整条跳过)。留着它只会让 resume 腿整轮拿不到
- * 真 env(写门恒 fail-closed);顶替按**实例身份**收口,被顶掉那一方迟到的注销全部落空,不误伤后继。
- */
 export class SandboxPathEnvSlots {
-    /** **弱持有**:登记簿只在「别人还用着这个 env」期间指向它。跑着的任务由 core 强持有(`prepared.ownedEnv`),
-     *  所以在场腿的裁决永远解得出;而一条 park 后再没人来 resume 的死腿,其 env 一旦无人引用即可被回收,
-     *  条目在下一次清扫时消失。强持有会把它们连同各自的 adapter 连接一起钉死到进程结束,并在 4096 条之后
-     *  让**每一个**新 session 拿不到真 env(守卫集下 = 每一次结构化写都 deny)—— 那是一道会自己关上的门。 */
     bySession = new Map();
-    /** 登记一个刚铸出的 env(同键顶替),返回**幂等**的注销闭包;到达上限而拒收时返回 `undefined`。
-     *  注销按**实例身份**摘除,所以一个迟到的 destroy 不会误伤同键的后继 env。 */
     bind(sessionId, env) {
         if (!this.bySession.has(sessionId) && this.bySession.size >= MAX_BOUND_SESSIONS) {
             this.sweepCollected();
@@ -102,46 +30,21 @@ export class SandboxPathEnvSlots {
         const env = ref?.deref();
         if (env === undefined) {
             if (ref !== undefined)
-                this.bySession.delete(sessionId); // 顺手收掉已回收的条目
+                this.bySession.delete(sessionId);
             return { ok: false, reason: "unbound" };
         }
         return { ok: true, env };
     }
-    /** 登记簿规模(上限行为的可观测面;测试与运维探针用)。含尚未清扫的死条目。 */
     get boundSessions() {
         return this.bySession.size;
     }
-    /** 清掉 env 已被回收的条目。只在触到上限时跑一遍(O(n) 的代价换掉一次拒收)。 */
     sweepCollected() {
         for (const [sid, ref] of this.bySession)
             if (ref.deref() === undefined)
                 this.bySession.delete(sid);
     }
 }
-/** 进程内唯一的登记簿:工厂装饰器(boot/execution-env.ts)与写门 wiring(boot/resolve-spec.ts)分处
- *  装配链两端,而中间的 core 只肯传 `ExecutionEnvFactoryContext`——两端共享同一个实例是它们唯一的会合点。
- *  测试要隔离时自建 {@link SandboxPathEnvSlots} 实例注入即可(两个消费点都收可选参)。 */
 export const sandboxPathEnvSlots = new SandboxPathEnvSlots();
-/**
- * 装饰工厂:每铸出一个 env 就按 `ctx.sessionId` 登记(同键顶替,见 {@link SandboxPathEnvSlots}),
- * 终态时注销。
- *
- * 挂**最外层**(装配链尾):内层装饰器可能**换掉**env 实例(worktree 隔离的 `rootEnvAt`)或改写它的
- * 方法(scratchpad 的 exec/canonicalPath 前置),写门要裁决的是 core 最终拿到手的那一个。
- *
- * 生命周期三面(顺序即语义):
- *  · `destroy` ⇒ 注销。
- *  · `suspendVM` 成功 ⇒ 注销。core 在挂起时**跳过** destroy(runtask 留着 env 做快照),所以这是可挂起
- *    车道唯一的及时腾位点:挂起期该 session 没有活腿,登记留着只是白占登记簿容量。
- *  · `resumeVM` 成功 ⇒ **重新登记**。挂起并不必然终结这一轮:`commitSuspendSaga` 的 checkpoint 写失败
- *    臂会 `resumeVM` + `postResumeInit` 把**同一个实例**复活,然后作废本次挂起让 run 继续跑
- *    (core dist 亲读)。只注销不复登记,一次瞬时 checkpoint 故障就会让这条 run 之后每一次写都失去真身
- *    裁决(方向 fail-closed,但整轮写面被毒死)。复登记幂等:仍在场时是 no-op,所以正常 resume 腿
- *    (新 env 在工厂处已登记、随后被 core `resumeVM` 复原快照)照旧不动;后继腿已接管该 session 时也不抢回。
- *
- * 两个终态面都缺席的 env(五条沙箱 adapter 都不是这一形)照样登记——正确性优先于回收:不登记等于
- * 让那条 lane 的写门恒 fail-closed。回收兜底=登记簿自己的上限。
- */
 export function withSandboxPathEnvSlot(factory, slots, logger) {
     return async (ctx) => {
         const env = await factory(ctx);
@@ -150,7 +53,6 @@ export function withSandboxPathEnvSlot(factory, slots, logger) {
         const sessionId = ctx.sessionId;
         let release = slots.bind(sessionId, env);
         if (release === undefined) {
-            // 上限拒收:该 task 的写门会落 fail-closed 而不是拿别人的盘裁决,但运维得知道为什么。
             logger?.warn?.("sandbox_path_env_slot_at_capacity", { sessionId, boundSessions: slots.boundSessions });
             return env;
         }
@@ -160,9 +62,9 @@ export function withSandboxPathEnvSlot(factory, slots, logger) {
         };
         const revive = () => {
             if (release !== undefined)
-                return; // 仍在场:复活是 no-op,绝不重复登记
+                return;
             if (slots.resolve(sessionId).ok)
-                return; // 后继腿已接管这个 session:一个迟到的复活绝不把它顶掉
+                return;
             release = slots.bind(sessionId, env);
             if (release === undefined)
                 logger?.warn?.("sandbox_path_env_slot_at_capacity", { sessionId, boundSessions: slots.boundSessions });
@@ -197,18 +99,10 @@ export function withSandboxPathEnvSlot(factory, slots, logger) {
         return env;
     };
 }
-/**
- * 写门用的 ExecutionEnv 代理(见文件头)。fs **读**原语转发 slot 里的真 env,`absolutePath` 保留词法形,
- * 其余一切(写面 / shell 面 / listDir …)继承 `StubExecutionEnv` 的 `not_supported`。
- *
- * **继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会随 `StubExecutionEnv`
- * 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
- */
 export class DeferredSandboxPathEnv extends StubExecutionEnv {
     sessionId;
     slots;
     logger;
-    /** 每实例一次的留痕闸:裁决面每个写目标要走 3-4 次转发,逐次 warn 会把日志刷成噪声。 */
     warned = false;
     constructor(opts) {
         super();
@@ -216,7 +110,6 @@ export class DeferredSandboxPathEnv extends StubExecutionEnv {
         this.slots = opts.slots;
         this.logger = opts.logger;
     }
-    /** 取真 env;取不到就地铸 fail-closed 错误(并留痕一次)。 */
     bound(path, face) {
         const found = this.slots.resolve(this.sessionId);
         if (found.ok)
@@ -235,16 +128,10 @@ export class DeferredSandboxPathEnv extends StubExecutionEnv {
             error: new FileError("not_supported", `no sandbox execution environment is bound for this task (${found.reason}) — the write gate cannot inspect the real filesystem`, path),
         };
     }
-    /** 词法一面,**不**转发 —— 理由见文件头裁定 1。 */
     absolutePath(path) {
-        // 含 NUL 的字符串不是合法 POSIX 路径(任何 fs 面都写不进去),但词法归一会照样给它铸出 canonical
-        // key——`\0` 尾巴让守卫段 glob 失配,豁免会话下还能拿 allow。拒收让 canon 在豁免咨询**之前**就失败。
         if (path.includes("\u0000")) {
             return Promise.resolve(err(new FileError("not_supported", "this gate resolves paths lexically and rejects a path containing a NUL byte (not a representable POSIX path)", path)));
         }
-        // POSIX 绝对形是沙箱 lane(全 Linux)上 hand 工具的书面契约形。相对路径 / `~` / `C:\…` 都要一个
-        // 沙箱工作目录才能解析,而那个基准与工具真写处的基准不是同一个,不猜。
-        // (反斜杠 UNC 形根本到不了这里:core 在 canonicalizeTarget 入口就短路了。)
         if (!path.startsWith("/")) {
             return Promise.resolve(err(new FileError("not_supported", "this gate cannot resolve a non-absolute path (the sandbox working directory is not the gate's to guess)", path)));
         }
@@ -262,9 +149,6 @@ export class DeferredSandboxPathEnv extends StubExecutionEnv {
         const b = this.bound(path, "fileInfo");
         return b.ok ? b.env.fileInfo(path, abortSignal) : b;
     }
-    /** `readLink` 在 `ExecutionEnv` 上是**可选**面。本代理恒定义它,于是 core 永远走不到自己的
-     *  「env 没有 readLink」腿——真 env 缺这一面时由此处答错误,落到 core 同一条 `unresolvedSymlink` 出口,
-     *  裁决结果与那条腿完全一致。 */
     async readLink(path, abortSignal) {
         const b = this.bound(path, "readLink");
         if (!b.ok)