@sema-agent/server 7.2.0 → 7.4.0

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

@@ -0,0 +1,279 @@
+/**
+ * #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();
+            if (this.bySession.size >= MAX_BOUND_SESSIONS)
+                return undefined;
+        }
+        const ref = new WeakRef(env);
+        this.bySession.set(sessionId, ref);
+        return () => {
+            if (this.bySession.get(sessionId) === ref)
+                this.bySession.delete(sessionId);
+        };
+    }
+    resolve(sessionId) {
+        if (!sessionId)
+            return { ok: false, reason: "no_session_id" };
+        const ref = this.bySession.get(sessionId);
+        const env = ref?.deref();
+        if (env === undefined) {
+            if (ref !== undefined)
+                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);
+        if (!ctx.sessionId)
+            return env;
+        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;
+        }
+        const drop = () => {
+            release?.();
+            release = undefined;
+        };
+        const revive = () => {
+            if (release !== undefined)
+                return; // 仍在场:复活是 no-op,绝不重复登记
+            if (slots.resolve(sessionId).ok)
+                return; // 后继腿已接管这个 session:一个迟到的复活绝不把它顶掉
+            release = slots.bind(sessionId, env);
+            if (release === undefined)
+                logger?.warn?.("sandbox_path_env_slot_at_capacity", { sessionId, boundSessions: slots.boundSessions });
+        };
+        const destroyable = env;
+        if (typeof destroyable.destroy === "function") {
+            const origDestroy = destroyable.destroy.bind(env);
+            destroyable.destroy = async () => {
+                drop();
+                return origDestroy();
+            };
+        }
+        const lifecycle = env;
+        if (typeof lifecycle.suspendVM === "function") {
+            const origSuspend = lifecycle.suspendVM.bind(env);
+            lifecycle.suspendVM = async (...args) => {
+                const r = await origSuspend(...args);
+                if (r.ok)
+                    drop();
+                return r;
+            };
+        }
+        if (typeof lifecycle.resumeVM === "function") {
+            const origResume = lifecycle.resumeVM.bind(env);
+            lifecycle.resumeVM = async (...args) => {
+                const r = await origResume(...args);
+                if (r.ok)
+                    revive();
+                return r;
+            };
+        }
+        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();
+        this.sessionId = opts.sessionId;
+        this.slots = opts.slots;
+        this.logger = opts.logger;
+    }
+    /** 取真 env;取不到就地铸 fail-closed 错误(并留痕一次)。 */
+    bound(path, face) {
+        const found = this.slots.resolve(this.sessionId);
+        if (found.ok)
+            return found;
+        if (!this.warned) {
+            this.warned = true;
+            this.logger?.warn?.("sandbox_path_env_slot_unresolved", {
+                reason: found.reason,
+                face,
+                sessionId: this.sessionId ?? null,
+                note: "the sandbox fs-write gate has no task environment to adjudicate against — every write target fails closed (ask, and deny under the sensitive-path set) until one is bound",
+            });
+        }
+        return {
+            ok: false,
+            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)));
+        }
+        return Promise.resolve(ok(normalizeAbsolutePathLexically(path)));
+    }
+    async exists(path, abortSignal) {
+        const b = this.bound(path, "exists");
+        return b.ok ? b.env.exists(path, abortSignal) : b;
+    }
+    async canonicalPath(path, abortSignal) {
+        const b = this.bound(path, "canonicalPath");
+        return b.ok ? b.env.canonicalPath(path, abortSignal) : b;
+    }
+    async fileInfo(path, abortSignal) {
+        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)
+            return b;
+        const readLink = b.env.readLink?.bind(b.env);
+        if (readLink === undefined) {
+            return err(new FileError("not_supported", "the bound sandbox environment cannot read symlinks, so this target's real destination is unknown", path));
+        }
+        return readLink(path, abortSignal);
+    }
+}
+//# sourceMappingURL=deferred-sandbox-path-env.js.map

package/dist/boot/execution-env.js

@@ -10,7 +10,9 @@
  *      → `withRemoteScratchpad`(远程车道首 exec 才 mkdir)
  *      → `withWorktreeIsolation`(host 车道 per-agent worktree,定 cwd)
  *      → `TaskEnvRegistry.wrapFactory`(SendUserFile 直传登记 taskId→env)
- *      → 附件物化(**最外层**:内层先定 cwd,附件才落在最终 cwd —— 原文逐字注释即此)。
+ *      → 附件物化(内层先定 cwd,附件才落在最终 cwd —— 原文逐字注释即此)
+ *      → `withSandboxPathEnvSlot`(#165,**最外层**:沙箱写门要裁决的是 core 最终拿到手的那个实例,
+ *         而内层会换实例/改写方法,所以登记必须排在全部换手之后)。
  * 另:`lspManager` 声明在 host 工厂**之后**,host 工厂闭包对它是同作用域前向引用(闭包每任务才跑,
  * 那时已初始化)——本段整体搬运保住了这个前向引用,拆开两个模块就会破。
  */
@@ -34,6 +36,7 @@ import { materializeAttachmentsInto } from "../plugins/task-attachment-store.js"
 import { reapOrphanWorktrees, withWorktreeIsolation } from "../plugins/worktree-isolation.js";
 import { customPkgSourceFromEnv, derivePkgSourceEnv } from "../sandbox-pkg-source.js";
 import { effectiveHostWorkspace } from "../task-cwd.js";
+import { isSandboxPathAdjudicationLane, sandboxPathEnvSlots, withSandboxPathEnvSlot } from "./deferred-sandbox-path-env.js";
 /**
  * #97 R11: the perSessionCwd/perSessionShellEnv setters below share one idiom (delete-then-set so a
  * re-set moves the tail to MRU, then oldest-first eviction on overflow). Local to this file — NOT the
@@ -337,6 +340,13 @@ export function createExecutionEnv(ctx) {
             return env;
         };
     }
+    // #165 沙箱写门的真 env slot(**最外层**,见文件头的装饰顺序):写门在 spec 期只能拿到一个代理,
+    // 裁决时刻由它去 slot 里取本 task 的真 env 转发 fs 读原语。所以登记的必须是 core 最终拿到手的那一个
+    // ——内层装饰器会换实例(worktree 的 rootEnvAt)或改写方法(scratchpad 的 exec/canonicalPath 前置)。
+    // 沙箱 lane 限定:host-semantics lane 的写门直接拿本机 NodeExecutionEnv,不经代理,包了也无人读。
+    if (executionEnvFactory && isSandboxPathAdjudicationLane(config.remoteExec?.provider)) {
+        executionEnvFactory = withSandboxPathEnvSlot(executionEnvFactory, sandboxPathEnvSlots, logger);
+    }
     if (executionEnvFactory) {
         // k8s (Kata) is isolated; it becomes WORKSPACE-suspendable when an S3 snapshot store is configured
         // (tar→S3→fresh pod restore — files durable, in-VM memory not); e2b is fully suspendable.

package/dist/boot/lexical-path-env.d.ts

@@ -0,0 +1,10 @@
+import { FileError, StubExecutionEnv, type Result } from "@sema-agent/core";
+/**
+ * 无文件系统的路径裁决 env(见文件头)。只覆写 `absolutePath` 一面,其余全部继承 `StubExecutionEnv`
+ * 的 `not_supported` ——**继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会
+ * 随 `StubExecutionEnv` 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
+ */
+export declare class LexicalPathExecutionEnv extends StubExecutionEnv {
+    absolutePath(path: string): Promise<Result<string, FileError>>;
+}
+//# sourceMappingURL=lexical-path-env.d.ts.map

package/dist/boot/lexical-path-env.js

@@ -0,0 +1,88 @@
+/**
+ * #156 —— 非 host lane(e2b/k8s/ssh/adb/local-docker)写门的**纯路径规则**过渡形所用的裁决 env。
+ *
+ * ## 它解决的缺口
+ *
+ * core 的 `createFsWriteGatePolicy` / `createSensitivePathPolicy` 都把写目标交给
+ * `canonicalizeTarget(env, …)` 去「问 fs 要真身」。host lane 上那个 env 就是 hand 工具真正写的那块盘,
+ * 答案可信。沙箱 lane 不是:per-task 的沙箱 env 由 core 的 `executionEnvFactory` 在 spec **之后**才铸,
+ * spec 期手边只有 worker 本机的 fs——拿它去裁沙箱里的路径会答错(exists/symlink 全是别人机器上的事实),
+ * 而**错误的 allow 比没有门更糟**。所以 [816]/[820] 当年在沙箱 lane 诚实不挂门(wiring=undefined ⇒
+ * 三个模式臂全回落 base 规则,写门整条缺席)。#153 的 ③ 号注把这笔记成了余款,#156 是它的过渡还款。
+ *
+ * ## 这个 env 是什么
+ *
+ * 一个**没有文件系统**的 env:除 `absolutePath` 外的每一个 fs 面(exists / canonicalPath / fileInfo /
+ * read* / write* / listDir / createDir / …)与 shell 面都继承 core 的 `StubExecutionEnv`,
+ * 恒返回 `not_supported` 错误(`readLink` 是可选面,Stub 干脆没有——core 把缺席当「symlink 不可解」,
+ * 且该分支在本 env 恒不可达:exists 先错就进了 canonicalizeNewPath)——这不是伪装,这就是本 env 的诚实回答:**spec 期我们确实不知道沙箱里
+ * 那块盘上有什么**。`absolutePath` 是唯一被赋予真实语义的一面,而它本来就是纯路径运算(不碰盘):
+ * POSIX 绝对路径做词法归一后原样奉还,其余一律「不知道」。
+ *
+ * ## 由此得到的裁决语义(core dist 亲读推出,`tools/fs/safety.js` canonicalizeTarget)
+ *
+ *  · 绝对路径(`/…`):`absolutePath` ok ⇒ core 进 exists 探测 ⇒ 我们返回错误 ⇒ core 按「该路径尚不存在」
+ *    走 `canonicalizeNewPath`,那里逐级 exists 也全错 ⇒ 原样返回我们给的词法绝对路径。于是 canonical key
+ *    = **词法归一后的路径**,`canonicalPath` / `fileInfo` / `readLink` 三面在这条路上根本不可达。
+ *  · 相对路径 / `~/…` / Windows 盘符形:`absolutePath` 返回错误 ⇒ `canon.ok=false` ⇒ 写门直接
+ *    `ask`(fail-closed)。沙箱的 cwd 在 spec 期不可知,这正是我们要的偏置——**不猜沙箱工作目录**。
+ *  · 反斜杠 UNC 形(`\\host\share\…`)是唯一**不经过**本 env 的形:core 的 `canonicalizeTarget` 在入口
+ *    就把它短路成 `ok:true, key=原样`(复审 2026-08-05 dist 亲读+实测)。结果不变——写门无放行域可越,
+ *    落 defaultWrite 的 `ask`;sensitive 段匹配按 `[\\/]` 双分隔符切段,`\\host\share\.env` 照样 deny。
+ *  · sensitivePatterns 的 deny 腿照常施加:它按 canonical key 的**路径段**做 glob 匹配,词法 key 足够,
+ *    且在 `combinePolicies` 折叠里 deny 恒胜(session 豁免 / accept 域越不过)。
+ *  · `isExempt`(会话「本会话不再询问」探针)是 name-keyed 的,不做 fs 裁决,任何 lane 都安全,照接。
+ *
+ * ## 已知残余面(过渡形的边界,不是疏漏)
+ *
+ *  · **symlink 形**:词法裁决看不见符号链接。沙箱里一个名字普通的软链可以指向守卫段(`.ssh` 等),
+ *    我们只会给 `ask` 而不是 `deny`;host lane 上 core 会 canonicalize 出真身并 deny。相应地,core 的
+ *    `unresolvedSymlink ⇒ deny` 那条腿在本 env 下永不触发。注意豁免会话下的口径(codex 复审 E):
+ *    name-keyed 豁免不看路径,这类词法无害的软链目标在豁免会话里是 **allow** 而非 ask——这是本残余面
+ *    在「操作员已授 don't-ask-again」情形下的完整代价,host lane 同情形仍会 deny。
+ *  · **exempt/accept 域**:沙箱 lane 既无可信 cwd 也无 scratchpad 对应物,故本过渡形**一个自动放行域都
+ *    不铸**(见 resolve-spec 的 wiring)。代价是 acceptEdits 在沙箱 lane 退化成与 default 同形(全 ask);
+ *    这是 fail-safe 方向,与 host lane「accept 域解析不出 ⇒ 该域不生效」的哨兵先例同口径。
+ *  · **`cwd` 字段**:继承 `StubExecutionEnv` 的 `"/"` 占位。本 env 只活在 policy 折叠里,core 的两个
+ *    policy 都不读 `env.cwd`(相对路径基准走 `rootPath` 形参,而我们不给)——它不代表沙箱的工作目录。
+ *
+ * ## 终局 seam
+ *
+ * 正解是让写门在**工具执行时刻**拿到真沙箱 env:core [2751] 已排期给 `HookToolContext` 加一个只读的
+ * env 能力窄面(174/#22 窗)。那一面到货后,本过渡形整体退役换正解——届时沙箱 lane 与 host lane 走同
+ * 一条真 fs 裁决,上面三条残余面一并消失。
+ */
+import { posix } from "node:path";
+import { FileError, StubExecutionEnv, err, ok } from "@sema-agent/core";
+/** 词法归一:纯字符串运算,折 `.` / `..` / 重复分隔符,不碰 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;
+}
+/**
+ * 无文件系统的路径裁决 env(见文件头)。只覆写 `absolutePath` 一面,其余全部继承 `StubExecutionEnv`
+ * 的 `not_supported` ——**继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会
+ * 随 `StubExecutionEnv` 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
+ */
+export class LexicalPathExecutionEnv extends StubExecutionEnv {
+    absolutePath(path) {
+        // POSIX 绝对形是沙箱 lane(全 Linux)上 hand 工具的书面契约形。其余一切——相对路径、`~`、
+        // `C:\…`——在 spec 期都无法诚实解析成一个沙箱内的绝对路径,返回错误让 core 落 ask。
+        // (反斜杠 UNC 形根本到不了这里:core 在 canonicalizeTarget 入口短路,见文件头「由此得到的裁决语义」。)
+        // codex 复审 A(2026-08-05):含 NUL 的字符串不是合法 POSIX 路径(任何 fs 面都写不进去),但词法归一
+        // 会照样给它铸出 canonical key——`\0` 尾巴让守卫段 glob 失配,豁免会话下还能拿 allow。拒收让 canon
+        // 在豁免咨询**之前**就失败 ⇒ 恒 ask。
+        if (path.includes("\u0000")) {
+            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and rejects a path containing a NUL byte (not a representable POSIX path)", path)));
+        }
+        if (!path.startsWith("/")) {
+            return Promise.resolve(err(new FileError("not_supported", "this environment adjudicates paths lexically and cannot resolve a non-absolute path (the sandbox working directory is unknown at spec time)", path)));
+        }
+        return Promise.resolve(ok(normalizeAbsolutePathLexically(path)));
+    }
+}
+//# sourceMappingURL=lexical-path-env.js.map

package/dist/boot/reapers.d.ts

@@ -21,6 +21,36 @@ import type { Metrics } from "../observability/metrics.js";
 import type { WorkflowNotifyGate, WorkflowNotifyJournalStore } from "../orchestration/workflow-notify-journal.js";
 import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
 import type { CheckpointStoreFull, CostQuotaStore, ImageBake, RateLimiterStore, ServiceWorkflowJournalStore, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
+import type { ToolApprovalCoordinator } from "../tool-approval.js";
+/** #157 / [2762]§五(sema-comms `audits/failopen-governance-176.md` §7 "Z 类 1 条"):default consecutive-failure
+ *  count before a reaper leg's swallowed error gets a `warn` line. The ~15 `.catch(() => undefined)` sites
+ *  below are correct in DIRECTION (a hiccuping periodic sweep must never crash the whole tick loop — one bad
+ *  leg cannot be allowed to starve its ~15 siblings), but were zero-observability: an operator watching only
+ *  `warn`/`error` would never learn a leg had been silently broken for days. `5` (not `1`) is deliberate —
+ *  a transient blip (one DB reconnect, one timeout) is exactly what fail-open exists to absorb without noise;
+ *  only a STREAK crosses into "diagnosable, not transient". Exported so a future per-leg override is a
+ *  constructor-arg change, not a magic-number hunt. */
+export declare const REAPER_FAILURE_WARN_THRESHOLD = 5;
+/** The pair of hooks {@link createThrottledReaperCatch} returns — `onSuccess` resets the streak (call on the
+ *  chain's fulfilled path), `onError` is the `.catch()`-equivalent rejection handler (throttled, never rethrows). */
+export interface ThrottledReaperCatch {
+    onSuccess: () => void;
+    onError: (err: unknown) => void;
+}
+/**
+ * Builds a NAMED, stateful throttle for one reaper leg: attach as `.then(() => guard.onSuccess(), guard.onError)`
+ * in place of a bare `.catch(() => undefined)` (the two-arg `.then` form still catches a rejection from any
+ * earlier link in the chain — same coverage as the `.catch()` it replaces — while also observing the FULFILLED
+ * path, which a plain `.catch()` cannot). Behavior this closure owns, unchanged reaper scheduling/cleanup:
+ *  - a successful run resets the consecutive-failure streak to 0 (one hiccup mid-outage doesn't inflate the count);
+ *  - a failure increments the streak; only once the streak reaches `threshold` (default
+ *    {@link REAPER_FAILURE_WARN_THRESHOLD}) does ONE `warn` line fire (reaper name + streak length + the most
+ *    recent error's message) — then the streak resets to 0 so a STILL-broken leg reports again after another
+ *    full `threshold` run, rather than going silent forever after its first report.
+ * One instance must be created ONCE per named leg (outside the tick's `setInterval` callback) so the streak
+ * survives across ticks — a fresh instance per tick would never accumulate past 1.
+ */
+export declare function createThrottledReaperCatch(name: string, logger: Logger, threshold?: number): ThrottledReaperCatch;
 export interface ReapersCtx {
     config: ServiceConfig;
     logger: Logger;
@@ -44,6 +74,10 @@ export interface ReapersCtx {
     rosterStore: RunnerDeps["rosterStore"];
     backgroundAgentStore: RunnerDeps["backgroundAgentStore"];
     mailboxStore: RunnerDeps["mailboxStore"];
+    /** #151 车6:流内审批撤卡帧的 live 投递口(收敛器/孤儿代打腿产出的帧经它反查 broker 的活连接)。
+     *  `TOOL_APPROVAL_ENABLED=false` 的部署恒 undefined ⇒ 收敛器照常收敛,只是不发通知帧(壳侧靠
+     *  重连 preamble 对账,见 approval-card.ts 的 `ApprovalRevokeFrame` 顶注)。 */
+    toolApproval: ToolApprovalCoordinator | undefined;
     /** 晚绑(server 造出来才有)——见文件头「位置即契约」①。 */
     getRunDenySweep: () => ((now: number) => Promise<void>) | undefined;
 }