@sema-agent/server 7.16.0-rc.3 → 7.17.0

package/dist/boot/reapers.js

@@ -17,6 +17,7 @@ import { sweepStaleScratchpads } from "../env-facts.js";
 import { CostQuota } from "../observability/cost-quota.js";
 import { isAdoptionQuiescing, trackMaintenanceLeg } from "../adoption/quiesce.js";
 import { createApprovalReconciler } from "../approval-reconciler.js";
+import { createE2bOrphanSandboxProvider, reclaimOrphanE2bSandboxes, E2B_ORPHAN_GRACE_MS } from "../plugins/e2b-orphan-reclaim.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
@@ -97,6 +98,17 @@ export function startReapers(ctx) {
             logger.info("reaper_swept", { metric, ...labels, count: n });
         }
     };
+    // #242:E2B 孤儿回收腿的三件座——provider(仅 e2b 部署形 + 旋钮 ON 时铸,一次)、时间节流锚
+    // (初始 -GRACE ⇒ 首 tick 即跑,承担 boot 半场)、重入守卫(list+逐杀可能跨多个 tick;provider RPC
+    // 带 SDK 级 requestTimeoutMs,旗不会因一次挂起永挂)。节流锚刻意用墙钟(codex R3 登记不改):判据
+    // 侧的 GRACE 比对是 E2B startedAt(墙钟)vs Date.now(墙钟)同钟系,节流锚换单调钟只护住「回拨多跑
+    // 一轮 list」这种无害面,却让本文件唯一一处异质钟——不值。锚在**发起时**推进(非成功时):失败轮也
+    // 压满 GRACE 间隔=对 provider 的天然退避;错误可见性由 e2bOrphanGuard 的连败阈值 warn 承担。
+    const e2bOrphanProvider = config.remoteExec?.provider === "e2b" && config.remoteExec.orphanReclaim !== false
+        ? createE2bOrphanSandboxProvider({ apiKey: config.remoteExec.apiKey })
+        : undefined;
+    let e2bOrphanLastRunMs = Date.now() - E2B_ORPHAN_GRACE_MS;
+    let e2bOrphanInFlight = false;
     let wfRunReapInFlight = false; // 1.108 review (lens③): serialize the all-scopes retention sweep across ticks
     let attachmentSweepInFlight = false; // 复审 F1:附件孤儿 sweep 的重入守卫(同上)
     let bgAgentReapInFlight = false; // core 1.364: same serialization for the durable bg-agent joint reap (per-scope serial loop)
@@ -105,6 +117,7 @@ export function startReapers(ctx) {
     // per-tick, so each leg's consecutive-failure streak survives across ticks — see createThrottledReaperCatch).
     const probeClockSkewGuard = createThrottledReaperCatch("probe_clock_skew", logger);
     const runsReapStaleGuard = createThrottledReaperCatch("runs_reap_stale", logger);
+    const e2bOrphanGuard = createThrottledReaperCatch("e2b_orphan_reclaim", logger); // #242
     const checkpointsReapExpiredGuard = createThrottledReaperCatch("checkpoints_reap_expired", logger);
     const runsFailSuspendedExpiredCheckpointGuard = createThrottledReaperCatch("runs_fail_suspended_expired_checkpoint", logger);
     const runDenySweepGuard = createThrottledReaperCatch("run_deny_sweep", logger);
@@ -483,6 +496,22 @@ export function startReapers(ctx) {
             })
                 .then(() => scratchpadSweepStaleGuard.onSuccess(), scratchpadSweepStaleGuard.onError));
         }
+        // #242(design/242 v1):E2B 孤儿沙盒回收。tick 内**时间节流**到 GRACE 周期(每 tick 打一次
+        // provider list API 是浪费——孤儿的时间尺度是分钟级);首轮在进程起后第一个 tick 就跑(boot 半场,
+        // 不单开 boot 调用点)。判据/边界全在 e2b-orphan-reclaim.ts;这里只管节流+重入+throttled catch。
+        if (e2bOrphanProvider && runStore && Date.now() - e2bOrphanLastRunMs >= E2B_ORPHAN_GRACE_MS && !e2bOrphanInFlight) {
+            e2bOrphanInFlight = true;
+            e2bOrphanLastRunMs = Date.now();
+            leg(reclaimOrphanE2bSandboxes({ provider: e2bOrphanProvider, runs: runStore, logger })
+                .then((s) => {
+                if (s.reclaimed > 0)
+                    metrics.inc("e2b_orphans_reclaimed_total", {}, s.reclaimed);
+            })
+                .then(() => e2bOrphanGuard.onSuccess(), e2bOrphanGuard.onError)
+                .finally(() => {
+                e2bOrphanInFlight = false;
+            }));
+        }
     }, config.reapIntervalSec * 1000);
     reaper.unref?.();
     return reaper;

package/dist/config-types.d.ts

@@ -359,6 +359,9 @@ export interface ServiceConfigFlat {
         allowInternetAccess?: boolean;
         sandboxEnv?: Record<string, string>;
         mountPath?: string;
+        /** #242:崩溃遗留沙盒回收腿(E2B_ORPHAN_RECLAIM,默认 true;判据与 v1 边界见
+         *  plugins/e2b-orphan-reclaim.ts 头注)。 */
+        orphanReclaim?: boolean;
     } | {
         provider: "k8s";
         image: string;

package/dist/config.js

@@ -765,14 +765,14 @@ function parseModelDomain() {
         // A non-empty value here would override every brain to one URL — breaking failover AND the Anthropic
         // route (it would POST to the vLLM gateway). See design/15.
         baseUrl: "",
-        reasoning: env("MODEL_REASONING", "true") === "true",
+        reasoning: boolEnv("MODEL_REASONING", true), // #245:直读族收编词表(rc.2 登记的 7.17 件)
         // vision precheck: the modality list drives BOTH the `model_no_vision` 422 (main.ts resolveSpec,
         // when body.images hits a text-only model) AND the vision flag on GET /v1/models. The env-lane default model
         // declares vision via MODEL_VISION — DEFAULT "true" keeps the historical image-capable behavior, so set
         // MODEL_VISION=false for a text-only model (e.g. deepseek) to make the precheck actually fire instead of letting
         // images透传 to an opaque downstream-gateway 400. (The centralized config-center lane derives input from its own
         // per-model vision flag — see config-center/facade.ts.)
-        input: env("MODEL_VISION", "true") === "true" ? ["text", "image"] : ["text"],
+        input: boolEnv("MODEL_VISION", true) ? ["text", "image"] : ["text"], // #245
         // Per-1M-token USD pricing (core `modelCostToPricing`: input→inputPer1M, …). Default 0 keeps the
         // historical behavior (spend reads $0) — set MODEL_COST_* on a deploy to make `model_cost_micro_usd`
         // + the Fleet card's costUsd real. Numbers are the gateway's contract price (e.g. the review gateway's
@@ -831,11 +831,8 @@ function parseModelDomain() {
             // AND defeat the precheck (config.models[cheapId] is user-pickable via body.model) — the SAME dead-code-on-a-lane
             // class clay caught on the env main model. MODEL_CHEAP_VISION declares it (strict "true"); UNSET → inherit the
             // main model's input (prior behavior, no change — the documented "same gateway, just a different id" case).
-            input: process.env.MODEL_CHEAP_VISION === undefined
-                ? model.input
-                : process.env.MODEL_CHEAP_VISION === "true"
-                    ? ["text", "image"]
-                    : ["text"],
+            // #245:三态语义不变(缺席/空串 ⇒ 继承主模型),词面收编 parseBoolWord(未知词 boot 拒)。
+            input: ((v) => (v === undefined ? model.input : v ? ["text", "image"] : ["text"]))(parseBoolWord("MODEL_CHEAP_VISION", process.env.MODEL_CHEAP_VISION)),
             // Own pricing: pricing is keyed by model id (budget.buildPricing), so without this the cheap model
             // inherits the MAIN model's `cost` and subagent/summarize spend (council lenses, compaction) is
             // metered at the PRO per-token price → cost metric + per-principal quota over-count. Set
@@ -857,7 +854,7 @@ function parseModelDomain() {
             // wrong when the cheap slot is a different tokenizer family (e.g. CJK-dense deepseek cheap under an
             // anthropic main). MODEL_CHEAP_CHARS_PER_TOKEN overrides; UNSET → inherit main (same knob family).
             ...(optFinitePositiveEnv("MODEL_CHEAP_CHARS_PER_TOKEN") !== undefined ? { charsPerToken: optFinitePositiveEnv("MODEL_CHEAP_CHARS_PER_TOKEN") } : {}),
-            reasoning: process.env.MODEL_CHEAP_REASONING === undefined ? model.reasoning : process.env.MODEL_CHEAP_REASONING === "true",
+            reasoning: parseBoolWord("MODEL_CHEAP_REASONING", process.env.MODEL_CHEAP_REASONING) ?? model.reasoning, // #245:三态同上
         }
         : undefined;
     // [818]① 1M dual-window (core 1.289 `Model.autoCompactTokens`, additive): a 1M-window model gets
@@ -932,7 +929,7 @@ function parseModelDomain() {
                 authToken: firstSetEnv("ANTHROPIC_AUTH_TOKEN"),
                 baseUrl: firstSetEnv("ANTHROPIC_BASE_URL"),
                 version: process.env.ANTHROPIC_VERSION,
-                cacheBreakpoints: (process.env.ANTHROPIC_CACHE_BREAKPOINTS ?? "true") === "true",
+                cacheBreakpoints: boolEnv("ANTHROPIC_CACHE_BREAKPOINTS", true), // #245
                 ...(process.env.ANTHROPIC_MAX_RETRIES ? { maxRetries: numEnv("ANTHROPIC_MAX_RETRIES", "2") } : {}), // A1 同族:NaN 会把 SDK 重试面折没
             }
             : undefined,
@@ -1221,7 +1218,9 @@ function parseApprovalDomain(ctx) {
         // boot 期的休眠行审计(`boot/permission-rules-audit.ts`)——对显式开过的部署说「N 条规则随默认 ON
         // 激活」是假话,那些行本来就是活的。判据与 `boolEnv` 认的字面量集**同源**(只有 "true"/"false"
         // 算表态;空串按未设,拼错的值走 boolEnv 的告警臂并落回默认 ⇒ 也不算表态)。
-        permissionRulesEnabledExplicit: ((raw) => raw === "true" || raw === "false")(process.env["PERMISSION_RULES_ENABLED"]),
+        // #245:显式表态判别随词表放宽——八词任一在场即「显式」(旧形只认 true/false 两词,=1 的显式关/开
+        // 会被当「未表态」滑进派生腿,恰是 operator-knob 病的判别位变体);未知词由本体 boolEnv 先拒启。
+        permissionRulesEnabledExplicit: parseBoolWord("PERMISSION_RULES_ENABLED", process.env["PERMISSION_RULES_ENABLED"]) !== undefined,
         // #151 车2(design/172 §3.3 D3):ToolApprovalCoordinator 窗长三元的安全余量。numEnv fail-loud 形,
         // 照邻居旋钮(approvalTimeoutSec 等)抄——坏形（非数字)在启动期炸,不静默折成 NaN。
         streamAskWindowMarginMs: numEnv("STREAM_ASK_WINDOW_MARGIN_MS", "10000"),
@@ -1664,6 +1663,10 @@ function parseOrchestrationDomain(ctx) {
                 // cwd——改此值前先 drain 挂起中的 e2b 任务,否则 resumed 任务的 exec 落新根而产物在旧根
                 // (根修=core resumeVM 契约带回 WorkspaceHandle.mountPath,已转 core)。
                 ...(process.env.E2B_MOUNT_PATH ? { mountPath: process.env.E2B_MOUNT_PATH } : {}),
+                // #242(design/242 v1):崩溃遗留沙盒回收腿(boot 一次+reaper 周期)。默认 ON——泄漏=真金
+                // 白银,判据已保守化(活行跳过/无行 10min GRACE/拿不准恒不杀);v1 前置=每部署独立 E2B key
+                // (跨部署异库共用一把 key 的形不支持,发车说明成文)。
+                orphanReclaim: boolEnv("E2B_ORPHAN_RECLAIM", true),
             }
             : // Kata pod sandbox on our k3s: image required; auth explicit (K8S_API_URL/K8S_TOKEN) or in-cluster SA.
                 process.env.REMOTE_EXEC === "k8s" && process.env.K8S_SANDBOX_IMAGE
@@ -1974,7 +1977,7 @@ function parseIntegrationsDomain() {
             ? {
                 baseUrl: env("SEMA_REGISTRY_URL"),
                 token: process.env.SEMA_REGISTRY_TOKEN || "",
-                dryRun: process.env.SEMA_REGISTRY_DRY_RUN === "true",
+                dryRun: boolEnv("SEMA_REGISTRY_DRY_RUN", false), // #245
                 worker: process.env.SEMA_REGISTRY_WORKER || undefined,
             }
             : undefined,

package/dist/observability/fail-open.d.ts

@@ -61,6 +61,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "P-DEBT";
         readonly note: "跨副本赎回 parked 审批时,祖先层在 park 时是 **auto-mode 武装**的,但那只分类器是祖先任务上的活闭包(绑着它自己的转写窗+brain),跨进程重建不出来 ⇒ 本仓交一只如实拒答的 decider,core 收到 `unavailable` 后**不产生任何自动裁决**、原样落到祖先冻结审批席那条链(本腿的席位又是无 ALS 的降级形 ⇒ 再 park 给人)。方向:分类器本会 allow 的改成问人(更严),本会 block 的也改成问人(**不是自动放行**,但比自动拒松一档)⇒ 记债不当合法兜底。计数 = 「丢了祖先分类器判决的继承 ask」次数。收口件二选一:core 把分类器判据持久进链条目,或让祖先 decider 有可跨进程重建的形。";
     };
+    readonly "server.e2b.orphan-skip-unknown": {
+        readonly cls: "F";
+        readonly note: "#242 E2B 孤儿回收对一只沙盒**判不了属主/活性**(metadata 缺 taskId 的病态形 / run 行状态词在 LIVE 与 TERMINAL 两表之外 / getRun 抛错)⇒ 恒不杀,本轮跳过。方向纪律:回收是清理型能力,缺席判据=不动作——误杀是杀活任务的手,漏杀只是钱;但每次跳过必须计数,否则「回收在跑却总有几只杀不掉」的病灶(店故障/新状态词未收编/别家部署共用 key)永不显形。";
+    };
     readonly "server.fleet.subscriber-callback-threw": {
         readonly cls: "F";
         readonly note: "fleet bus 某订阅回调抛错 ⇒ 该回调本帧作废,其余订阅方与发布方不受影响。隔离是承重的:扇出同步,修前异常会传回发布方 put/update 投影点,core 持久化 catch{} 且不推进 storeRev ⇒ durable 行冻在 running 而 notify 已 ack(#183 复审 R3 HIGH)。丢的只是一个消费方的一帧渲染,故 F 类;但必须留痕——静默吞掉等于订阅方病灶永不显形。";

package/dist/observability/fail-open.js

@@ -84,6 +84,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "P-DEBT",
         note: "跨副本赎回 parked 审批时,祖先层在 park 时是 **auto-mode 武装**的,但那只分类器是祖先任务上的活闭包(绑着它自己的转写窗+brain),跨进程重建不出来 ⇒ 本仓交一只如实拒答的 decider,core 收到 `unavailable` 后**不产生任何自动裁决**、原样落到祖先冻结审批席那条链(本腿的席位又是无 ALS 的降级形 ⇒ 再 park 给人)。方向:分类器本会 allow 的改成问人(更严),本会 block 的也改成问人(**不是自动放行**,但比自动拒松一档)⇒ 记债不当合法兜底。计数 = 「丢了祖先分类器判决的继承 ask」次数。收口件二选一:core 把分类器判据持久进链条目,或让祖先 decider 有可跨进程重建的形。",
     },
+    "server.e2b.orphan-skip-unknown": {
+        cls: "F",
+        note: "#242 E2B 孤儿回收对一只沙盒**判不了属主/活性**(metadata 缺 taskId 的病态形 / run 行状态词在 LIVE 与 TERMINAL 两表之外 / getRun 抛错)⇒ 恒不杀,本轮跳过。方向纪律:回收是清理型能力,缺席判据=不动作——误杀是杀活任务的手,漏杀只是钱;但每次跳过必须计数,否则「回收在跑却总有几只杀不掉」的病灶(店故障/新状态词未收编/别家部署共用 key)永不显形。",
+    },
     "server.fleet.subscriber-callback-threw": {
         cls: "F",
         note: "fleet bus 某订阅回调抛错 ⇒ 该回调本帧作废,其余订阅方与发布方不受影响。隔离是承重的:扇出同步,修前异常会传回发布方 put/update 投影点,core 持久化 catch{} 且不推进 storeRev ⇒ durable 行冻在 running 而 notify 已 ack(#183 复审 R3 HIGH)。丢的只是一个消费方的一帧渲染,故 F 类;但必须留痕——静默吞掉等于订阅方病灶永不显形。",

package/dist/plugins/e2b-orphan-reclaim.d.ts

@@ -0,0 +1,74 @@
+/**
+ * #242([3738] / design/242 v1)— E2B 孤儿沙盒回收。
+ *
+ * 病:server 进程崩溃(SIGKILL/OOM)后 core Runner 的 `destroy()` 不跑,E2B 沙盒按自己的
+ * timeout 窗继续存活计费;崩溃循环下泄漏累积。create 侧的归属打标早已在
+ * (`remote-env-e2b.ts` factory:metadata 带 sessionId/taskId,本批补 `semaManaged:"1"`);
+ * 本模块是缺的另一半——回收腿。
+ *
+ * 判据(全部保守方向,**拿不准恒不杀**——回收是清理型能力,缺席判据=不动作,方向纪律见
+ * memory `capability-probe-fail-direction`;误杀的代价是杀死一个活任务的手,漏杀的代价只是钱):
+ *   a. `metadata.semaManaged !== "1"`         → 非我方铸造,provider 侧 query 过滤已排除;防御性重验。
+ *   b. `metadata.taskId` 缺席                 → 病态形(factory 恒打标),不杀 + failOpen 留痕。
+ *   c. run 行在场:
+ *        LIVE 词(running/suspended/needs_review)→ 活,跳过;
+ *        TERMINAL 词                           → 孤儿,kill;
+ *        两表皆不中的词                        → 词表纪律(#157):不杀 + failOpen(新词先安全后收编)。
+ *   d. 行不存在:
+ *        startedAt 距今 < GRACE                → create→行落库窗口,跳过(防误杀新沙盒);
+ *        ≥ GRACE                              → 真孤儿,kill(单库 fleet 方向下行跨副本可见)。
+ *   e. `getRun` 抛错                          → 不杀 + failOpen(不知道 ≠ 孤儿)。
+ *
+ * v1 边界(design/242 §设计②,发车说明同步):跨部署**异库**共用一把 E2B key 的形不支持——
+ * 别家沙盒的 taskId 在本库查不到行,超 GRACE 会被误杀;前置=每部署独立 E2B key(本就是推荐姿势)。
+ * metadata 无跨重启稳定的部署标识可用(instanceId 每 boot 变,恰是要回收上一世代)是结构原因。
+ *
+ * kill 逐只 try/catch(一只失败不挡其余);list 整体失败由调用方(reaper throttled catch)兜底。
+ */
+import type { Logger } from "../observability/logger.js";
+/** create→run 行落库窗口的误杀护栏。非行为表态面,常量不设旋钮(理由:它只需要「远大于一次
+ *  create+首写延迟、远小于沙盒 timeout 窗」,10min 对两端都有量级余量;错设它的运维事故面比
+ *  它保护的窗口更大)。 */
+export declare const E2B_ORPHAN_GRACE_MS: number;
+/** factory 打进 metadata 的归属标(create 半场,remote-env-e2b.ts);值恒 "1"。 */
+export declare const SEMA_MANAGED_METADATA_KEY = "semaManaged";
+/** provider 窄面(真实装配=E2B SDK `Sandbox.list()`/`Sandbox.kill()` 包装;测试注入 fake)。 */
+export interface OrphanSandboxProvider {
+    /** 列出**我方铸造**的沙盒(装配侧用 `query.metadata = { semaManaged: "1" }` 服务端过滤)。 */
+    listManaged(): Promise<OrphanSandboxInfo[]>;
+    kill(sandboxId: string): Promise<void>;
+}
+export interface OrphanSandboxInfo {
+    sandboxId: string;
+    metadata: Record<string, string>;
+    /** SDK `SandboxInfo.startedAt`。 */
+    startedAt: Date;
+}
+export interface OrphanReclaimDeps {
+    provider: OrphanSandboxProvider;
+    /** RunStore 三形(TiDB/Pg/File)共同的窄读口。 */
+    runs: {
+        getRun(taskId: string): Promise<{
+            status: string;
+        } | undefined>;
+    };
+    logger?: Logger;
+    now?: () => number;
+    graceMs?: number;
+}
+export interface OrphanReclaimSummary {
+    scanned: number;
+    reclaimed: number;
+    skippedLive: number;
+    skippedGrace: number;
+    skippedUnknown: number;
+    killFailed: number;
+}
+/** 一轮回收(boot 一次 + reaper interval 周期共用)。list 抛错穿透给调用方(reaper catch 族)。 */
+export declare function reclaimOrphanE2bSandboxes(deps: OrphanReclaimDeps): Promise<OrphanReclaimSummary>;
+/** 真实 provider(E2B SDK 包装)。SDK 静态面动态 import——回收腿只在 e2b 部署形挂载,
+ *  非 e2b 形零加载(与 execution-env 的按需装配同姿势)。 */
+export declare function createE2bOrphanSandboxProvider(cfg: {
+    apiKey: string;
+}): OrphanSandboxProvider;
+//# sourceMappingURL=e2b-orphan-reclaim.d.ts.map

package/dist/plugins/e2b-orphan-reclaim.js

@@ -0,0 +1,135 @@
+/**
+ * #242([3738] / design/242 v1)— E2B 孤儿沙盒回收。
+ *
+ * 病:server 进程崩溃(SIGKILL/OOM)后 core Runner 的 `destroy()` 不跑,E2B 沙盒按自己的
+ * timeout 窗继续存活计费;崩溃循环下泄漏累积。create 侧的归属打标早已在
+ * (`remote-env-e2b.ts` factory:metadata 带 sessionId/taskId,本批补 `semaManaged:"1"`);
+ * 本模块是缺的另一半——回收腿。
+ *
+ * 判据(全部保守方向,**拿不准恒不杀**——回收是清理型能力,缺席判据=不动作,方向纪律见
+ * memory `capability-probe-fail-direction`;误杀的代价是杀死一个活任务的手,漏杀的代价只是钱):
+ *   a. `metadata.semaManaged !== "1"`         → 非我方铸造,provider 侧 query 过滤已排除;防御性重验。
+ *   b. `metadata.taskId` 缺席                 → 病态形(factory 恒打标),不杀 + failOpen 留痕。
+ *   c. run 行在场:
+ *        LIVE 词(running/suspended/needs_review)→ 活,跳过;
+ *        TERMINAL 词                           → 孤儿,kill;
+ *        两表皆不中的词                        → 词表纪律(#157):不杀 + failOpen(新词先安全后收编)。
+ *   d. 行不存在:
+ *        startedAt 距今 < GRACE                → create→行落库窗口,跳过(防误杀新沙盒);
+ *        ≥ GRACE                              → 真孤儿,kill(单库 fleet 方向下行跨副本可见)。
+ *   e. `getRun` 抛错                          → 不杀 + failOpen(不知道 ≠ 孤儿)。
+ *
+ * v1 边界(design/242 §设计②,发车说明同步):跨部署**异库**共用一把 E2B key 的形不支持——
+ * 别家沙盒的 taskId 在本库查不到行,超 GRACE 会被误杀;前置=每部署独立 E2B key(本就是推荐姿势)。
+ * metadata 无跨重启稳定的部署标识可用(instanceId 每 boot 变,恰是要回收上一世代)是结构原因。
+ *
+ * kill 逐只 try/catch(一只失败不挡其余);list 整体失败由调用方(reaper throttled catch)兜底。
+ */
+import { recordFailOpen } from "../observability/fail-open.js";
+/** create→run 行落库窗口的误杀护栏。非行为表态面,常量不设旋钮(理由:它只需要「远大于一次
+ *  create+首写延迟、远小于沙盒 timeout 窗」,10min 对两端都有量级余量;错设它的运维事故面比
+ *  它保护的窗口更大)。 */
+export const E2B_ORPHAN_GRACE_MS = 10 * 60 * 1000;
+/** factory 打进 metadata 的归属标(create 半场,remote-env-e2b.ts);值恒 "1"。 */
+export const SEMA_MANAGED_METADATA_KEY = "semaManaged";
+// 构造侧 satisfies 锚类型真源;容器声明 ReadonlySet<string> 让消费侧(窄读口的 status: string)直判。
+const LIVE_STATUSES = new Set(["running", "suspended", "needs_review"]);
+const TERMINAL_STATUSES = new Set(["completed", "blocked", "failed"]);
+const _statusesCovered = true;
+void _statusesCovered;
+/** 一轮回收(boot 一次 + reaper interval 周期共用)。list 抛错穿透给调用方(reaper catch 族)。 */
+export async function reclaimOrphanE2bSandboxes(deps) {
+    const now = deps.now ?? Date.now;
+    const graceMs = deps.graceMs ?? E2B_ORPHAN_GRACE_MS;
+    const summary = { scanned: 0, reclaimed: 0, skippedLive: 0, skippedGrace: 0, skippedUnknown: 0, killFailed: 0 };
+    const sandboxes = await deps.provider.listManaged();
+    for (const sbx of sandboxes) {
+        summary.scanned++;
+        // a. 防御性重验(provider 装配侧已 query 过滤;fake/将来的宽 provider 不许绕过归属判别)。
+        if (sbx.metadata[SEMA_MANAGED_METADATA_KEY] !== "1") {
+            summary.skippedUnknown++;
+            recordFailOpen("server.e2b.orphan-skip-unknown");
+            continue;
+        }
+        const taskId = sbx.metadata.taskId;
+        // b. 病态形:factory 恒打 taskId(ctx.taskId 缺席时连 sessionId 都在而 taskId 不在)——不杀,留痕。
+        if (!taskId) {
+            summary.skippedUnknown++;
+            recordFailOpen("server.e2b.orphan-skip-unknown");
+            continue;
+        }
+        let verdict;
+        try {
+            const run = await deps.runs.getRun(taskId);
+            if (run === undefined) {
+                // d. 无行:GRACE 内=create→落库窗口;超窗=真孤儿。
+                verdict = now() - sbx.startedAt.getTime() < graceMs ? "grace" : "kill";
+            }
+            else if (LIVE_STATUSES.has(run.status)) {
+                verdict = "live";
+            }
+            else if (TERMINAL_STATUSES.has(run.status)) {
+                verdict = "kill";
+            }
+            else {
+                // c. 词表外的新词:不杀 + failOpen(先安全后收编;收编=上面两表加词,遗漏在 census 计数可见)。
+                verdict = "unknown";
+            }
+        }
+        catch {
+            // e. store 读错:不知道 ≠ 孤儿。
+            verdict = "unknown";
+        }
+        if (verdict === "live")
+            summary.skippedLive++;
+        else if (verdict === "grace")
+            summary.skippedGrace++;
+        else if (verdict === "unknown") {
+            summary.skippedUnknown++;
+            recordFailOpen("server.e2b.orphan-skip-unknown");
+        }
+        else {
+            try {
+                await deps.provider.kill(sbx.sandboxId);
+                summary.reclaimed++;
+                deps.logger?.info("e2b_orphan_reclaimed", { sandboxId: sbx.sandboxId, taskId, ageMs: now() - sbx.startedAt.getTime() });
+            }
+            catch (e) {
+                summary.killFailed++;
+                deps.logger?.warn("e2b_orphan_kill_failed", { sandboxId: sbx.sandboxId, taskId, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+    }
+    if (summary.reclaimed > 0 || summary.killFailed > 0) {
+        deps.logger?.info("e2b_orphan_reclaim_round", { ...summary });
+    }
+    return summary;
+}
+/** provider RPC 墙钟上限。🔴 codex 对抗复审 R2(验真后修):无超时的 list/kill 一次 provider 挂起会让
+ *  调用方的重入旗永挂(finally 等的 promise 永不结算)⇒ 回收腿从此静默死掉。SDK 原生收
+ *  `requestTimeoutMs`(SandboxApiOpts),用它而非外包 race——超时语义留在 SDK 的连接层。 */
+const PROVIDER_RPC_TIMEOUT_MS = 30_000;
+/** 真实 provider(E2B SDK 包装)。SDK 静态面动态 import——回收腿只在 e2b 部署形挂载,
+ *  非 e2b 形零加载(与 execution-env 的按需装配同姿势)。 */
+export function createE2bOrphanSandboxProvider(cfg) {
+    return {
+        async listManaged() {
+            const { Sandbox } = await import("e2b");
+            const out = [];
+            // 服务端 metadata 过滤(SandboxListOpts.query.metadata,AND 语义);state 默认含 running+paused
+            // ——paused 也计费存储位且同样是孤儿人群,刻意不收窄。
+            const paginator = Sandbox.list({ apiKey: cfg.apiKey, requestTimeoutMs: PROVIDER_RPC_TIMEOUT_MS, query: { metadata: { [SEMA_MANAGED_METADATA_KEY]: "1" } } });
+            while (paginator.hasNext) {
+                const items = await paginator.nextItems();
+                for (const s of items)
+                    out.push({ sandboxId: s.sandboxId, metadata: s.metadata ?? {}, startedAt: s.startedAt });
+            }
+            return out;
+        },
+        async kill(sandboxId) {
+            const { Sandbox } = await import("e2b");
+            await Sandbox.kill(sandboxId, { apiKey: cfg.apiKey, requestTimeoutMs: PROVIDER_RPC_TIMEOUT_MS });
+        },
+    };
+}
+//# sourceMappingURL=e2b-orphan-reclaim.js.map

package/dist/plugins/remote-env-e2b.js

@@ -1236,7 +1236,8 @@ export class RemoteContainerExecutionEnv {
 export function e2bExecutionEnvFactory(config, deps) {
     return (ctx) => new RemoteContainerExecutionEnv({
         ...config,
-        metadata: { ...config.metadata, sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
+        // #242:semaManaged=归属标(孤儿回收腿 e2b-orphan-reclaim.ts 按它服务端过滤;值恒 "1")。
+        metadata: { ...config.metadata, semaManaged: "1", sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
     }, deps);
 }
 // ─────────────────────────────── module helpers ───────────────────────────────

package/dist/tool-approval.js

@@ -1193,6 +1193,7 @@ export class ToolApprovalCoordinator {
         // 而 `settle` 可能因为人已经答过了而整个是空操作 —— 标志式写法会在那种赛跑里给一个**人类的**终局盖上
         // 「窗到期」的章。只有真正落定这次终局的那一次调用才有资格留下自报词。
         let hostSettled;
+        let denyReasonSettled; // #243:respond deny 的人写理由,shapeOutcome deny 臂消费(声明纪律见 settle 注)
         /**
          * 已落定的本地终局 → `AskOutcome` 的**唯一**成形口。本方法有两个出口(方法尾的正常路,与
          * `earlyAbortDuringEnsure` 的早退路),它们此前各写了一份等价分派 —— 结果就是本批的 `settledBy`
@@ -1201,6 +1202,11 @@ export class ToolApprovalCoordinator {
          *  · allow + 编辑 ⇒ 对象臂带 `updatedInput`;
          *  · deny + 宿主自报 ⇒ 对象臂带 `settledBy`(见 {@link HostSettledBy};allow 侧恒不带 —— core 对
          *    `{allow:true, settledBy:"timeout"}` 是响亮拒,而自报只在 deny 分支产生);
+         *  · deny + 人写理由 ⇒ 对象臂带 `reason`(#243,core 5.29.0 收口:模型经它看到拒因——围栏
+         *    delimitUntrusted 与 REVIEWER_NOTE_MAX_BODY 截断全在 core,server 只透传不预判;空串按 core
+         *    契约的缺席读——truthiness——不铸键;allow 侧恒不带,core 对 allow 行的 reason 恒销毁不渲染,
+         *    审计面由店的 decisionNote 承载)。理由只从 respond 腿流入(finishRespond),窗到期/取消/
+         *    外部清算臂无人写理由,恒缺席。
          *  · 其余 ⇒ 裸 boolean(falsy 纪律)。
          */
         const shapeOutcome = (settled) => {
@@ -1209,13 +1215,21 @@ export class ToolApprovalCoordinator {
             if (settled.allowed) {
                 return settled.updatedInput !== undefined ? { allow: true, updatedInput: settled.updatedInput } : true;
             }
-            return hostSettled !== undefined ? { allow: false, settledBy: hostSettled } : false;
+            if (hostSettled !== undefined || (denyReasonSettled !== undefined && denyReasonSettled !== "")) {
+                return {
+                    allow: false,
+                    ...(hostSettled !== undefined ? { settledBy: hostSettled } : {}),
+                    ...(denyReasonSettled !== undefined && denyReasonSettled !== "" ? { reason: denyReasonSettled } : {}),
+                };
+            }
+            return false;
         };
-        const settle = (allowed, outcome, updatedInput, hostSettledBy) => {
+        const settle = (allowed, outcome, updatedInput, hostSettledBy, denyReason) => {
             if (done)
                 return;
             done = true;
             hostSettled = hostSettledBy;
+            denyReasonSettled = allowed ? undefined : denyReason;
             if (timer)
                 clearTimeout(timer);
             for (const [sig, fn] of abortListeners)
@@ -1877,7 +1891,10 @@ export class ToolApprovalCoordinator {
             this.allowAllSessions.add(sessionAllowKey(entry.owner, entry.sessionId, sessionAllowCategory(entry.toolName)));
         }
         const allowed = parsed.value !== "deny";
-        entry.settle(allowed, allowed ? "allowed" : "denied", parsed.updatedInput);
+        // #243:deny 的 note 同时是给模型的拒因(AskOutcome.reason,core 5.29.0 围栏+上限在 core);allow 的
+        // note 只走店的审计列(core 对 allow 行 reason 恒销毁,不铸注定被丢的键)。第 4 参 hostSettledBy 恒缺席
+        // ——respond 腿是人经 API 决,不是宿主自报臂。
+        entry.settle(allowed, allowed ? "allowed" : "denied", parsed.updatedInput, undefined, allowed ? undefined : parsed.note);
         // updatedInputForwarded=server 已透传(是否被引擎消费取决于 core OnAsk 对象臂是否在——诚实措辞,
         // 不称 applied;cli 版本门+core 单落地后全链生效)。
         // 🔴 codex 交叉复审 round2 R2-4(2026-08-06 真缺陷):这个回显必须以「**这次调用真的把 updatedInput

package/dist/trace/core-keyset-guard.d.ts

@@ -27,7 +27,7 @@ type _GuardBgNotif = AssertAllKeysHandled<Exclude<keyof BackgroundChildEvent, Bg
 type RosterProjected = "name" | "agentId" | "sessionId" | "toolUseId" | "owner" | "scope" | "sessionScoped" | "rootSessionId" | "model" | "modelFallback" | "createdAt";
 type _GuardRoster = AssertAllKeysHandled<Exclude<keyof RosterEntry, RosterProjected>>;
 type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation" | "ruleSuggestions" | "persistedRuleShadowed";
-type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash";
+type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash" | "isDelegatedChild";
 type _GuardAsk = AssertAllKeysHandled<Exclude<keyof AskRequest, AskProjected | AskExcluded>>;
 type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome" | "human_input" | "wiring_manifest";
 type _GuardTaskEvent = AssertAllKeysHandled<Exclude<TaskEvent["type"], TaskEventHandled>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.16.0-rc.3",
+  "version": "7.17.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.28.0",
+    "@sema-agent/core": "^5.29.0",
     "@sema-agent/registry-core": "^0.16.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",