@sema-agent/server 7.129.0 → 7.130.0

package/dist/hooks/hook-llm.js

@@ -2,6 +2,7 @@ import { adjudicateModelRoute, joinRequestUrl, resolveRouteCredential, routeKeyO
 import { matchCatalogModel, refusedCatalogEntry } from "../model-select.js";
 import { modelUnavailableMessage } from "../model-entry-refusal.js";
 import { resolveOpenaiRouteEndpoint } from "../model-route-endpoint.js";
+import { dispatchBrainLane } from "../model-provider.js";
 import { egressRedirectRefusal } from "../egress-redirect.js";
 import { buildDisplaySafeRefusal, redactSecrets } from "../trace/redact.js";
 export function buildHookFailureText(raw) {
@@ -16,21 +17,17 @@ export function buildHookFailureText(raw) {
 }
 export function createHookLlm(deps) {
     const { config, metrics } = deps;
-    const anthropicRouteBaseUrl = () => config.anthropic ? config.anthropic.baseUrl || "https://api.anthropic.com" : undefined;
+    const anthropicRouteBaseUrl = () => config.anthropic?.baseUrl || "https://api.anthropic.com";
     const shapeFrom = (catalogRef, m, providerModelId) => {
-        const api = m?.api === "anthropic-messages" || m?.provider === "anthropic" ? "anthropic-messages" : "openai-completions";
-        if (api === "anthropic-messages") {
-            const baseUrl = m?.baseUrl || anthropicRouteBaseUrl();
-            if (!baseUrl) {
-                return {
-                    ok: false,
-                    error: `hook model "${catalogRef}" is served over anthropic-messages but no anthropic route is configured — set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN (plus ANTHROPIC_BASE_URL for a non-default endpoint), or give the model its own baseUrl`,
-                };
+        const lane = dispatchBrainLane(m?.provider, config.anthropic !== undefined);
+        switch (lane) {
+            case "anthropic":
+                return { ok: true, catalogRef, providerModelId, baseUrl: m?.baseUrl || anthropicRouteBaseUrl(), api: "anthropic-messages" };
+            case "gateway": {
+                const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m?.baseUrl, config.gatewayBaseUrl);
+                return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api: "openai-completions" } : { ok: false, error: endpoint.refusal };
             }
-            return { ok: true, catalogRef, providerModelId, baseUrl, api };
         }
-        const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m?.baseUrl, config.gatewayBaseUrl);
-        return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api } : { ok: false, error: endpoint.refusal };
     };
     const hookModelFor = (requested) => {
         const shape = (ref) => shapeFrom(ref, config.models[ref], config.models[ref]?.id ?? ref);
@@ -135,7 +132,7 @@ export function createHookLlm(deps) {
             const r = await fetchImpl(url, { method: "POST", headers, body, signal: ac.signal, redirect: "manual" });
             const redirected = egressRedirectRefusal(r, "declare the final endpoint as this route's base URL");
             if (redirected !== undefined)
-                return { ok: false, error: `hook llm ${redirected}` };
+                return { ok: false, error: `hook llm ${redirected}`, code: "redirect_refused" };
             if (!r.ok)
                 return { ok: false, error: `hook llm HTTP ${r.status}` };
             let text;

package/dist/hooks/hook-runner.d.ts

@@ -270,7 +270,7 @@ export type HookLlmCall = (opts: {
 }>;
 /** 失败判别码(B8:判别一律走码,禁按 error 文案分支——v3.1 批2,统检第二波 high)。error 仍是给人看的
  *  自由文本;code 是给控制流的。缺席=未分类失败(不重试、不特判)。 */
-export type HookLlmFailureCode = "no_content" | "hard_timeout";
+export type HookLlmFailureCode = "no_content" | "hard_timeout" | "redirect_refused";
 /**
  * hook 上下文片段 → 喂给模型的单串。**所有** `additionalContext` 聚合点的唯一属主(此前是同一个
  * `contexts.join("\n")` 表达式抄在二十余处,总量帽无处可挂 —— 那正是漂移成因)。

package/dist/http/routes/capabilities.js

@@ -44,6 +44,9 @@ function retentionAdvertisement(config) {
 export function createCapabilitiesLocal() {
     return { mcpProbe: createMcpProbeLocal() };
 }
+function sendScenarioNotFound(res) {
+    sendError(res, 404, "scenario_not_found", "scenario not found");
+}
 export async function handleCapabilities(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
@@ -51,7 +54,7 @@ export async function handleCapabilities(req, res, match, ctx) {
             const name = match.params.name;
             const detail = deps.scenarioDetails?.[name];
             if (!detail) {
-                sendError(res, 404, "scenario_not_found", "scenario not found");
+                sendScenarioNotFound(res);
                 return;
             }
             sendJson(res, 200, detail);
@@ -217,7 +220,22 @@ export async function handleCapabilities(req, res, match, ctx) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
-            await serveMcpProbeFace(res, ctx, principal, mcpForScenario(deps.config.mcpServers, deps.config.defaultScenario) ?? [], "deployment");
+            const scenarioParams = new URLSearchParams(match.search).getAll("scenario");
+            if (scenarioParams.length > 1) {
+                sendError(res, 400, "request.field_invalid", "scenario must be given at most once (omit it to read this deployment's default scenario)");
+                return;
+            }
+            const requestedScenario = scenarioParams[0];
+            let scenarioName;
+            if (requestedScenario === undefined)
+                scenarioName = deps.config.defaultScenario;
+            else if (deps.scenarioGate === undefined) {
+                sendScenarioNotFound(res);
+                return;
+            }
+            else
+                scenarioName = await deps.scenarioGate(principal, requestedScenario);
+            await serveMcpProbeFace(res, ctx, principal, mcpForScenario(deps.config.mcpServers, scenarioName) ?? [], "deployment");
             return;
         }
         case "capability-mcp-probe": {

package/dist/http/routes/runs.js

@@ -599,6 +599,14 @@ export async function handleRuns(req, res, match, ctx) {
             };
             const job = prior.then(async () => {
                 const cs = deps.checkpointStore;
+                const withdrawWakeCard = async (token, scope, arm) => {
+                    try {
+                        await cs.expire(token, scope);
+                    }
+                    catch (e) {
+                        deps.logger?.warn?.("steer_wake_card_withdraw_failed", { taskId, sessionId: run.sessionId, arm, error: redactHead(e instanceof Error ? e.message : String(e), 2000) });
+                    }
+                };
                 const reprobe = await tryPark();
                 if (reprobe === "parked") {
                     mintResult.parked = true;
@@ -645,18 +653,18 @@ export async function handleRuns(req, res, match, ctx) {
                 });
                 const stillRead = await readResumeCtx(cs.getCtx(run.sessionId));
                 if (stillRead.kind === "corrupt") {
-                    await cs.expire(wakeToken, cpScope).catch(() => undefined);
+                    await withdrawWakeCard(wakeToken, cpScope, "resume_context_corrupt");
                     mintResult.corruptCtxWhere = stillRead.where;
                     return;
                 }
                 if (stillRead.kind !== "ok") {
-                    await cs.expire(wakeToken, cpScope).catch(() => undefined);
+                    await withdrawWakeCard(wakeToken, cpScope, "resume_context_absent");
                     mintResult.noResumeCtx = true;
                     return;
                 }
                 const winner = await cs.findPendingTokenBySession(run.sessionId, undefined, { gateKinds: TERMINAL_PARK_GATE_KINDS, pick: "oldest" }).catch(() => null);
                 if (winner !== null && winner !== wakeToken) {
-                    await cs.expire(wakeToken, cpScope).catch(() => undefined);
+                    await withdrawWakeCard(wakeToken, cpScope, "converged_on_winner");
                     await parkOnce(winner, cpScope);
                     return;
                 }
@@ -680,7 +688,7 @@ export async function handleRuns(req, res, match, ctx) {
                 return;
             }
             if (mintResult.corruptCtxWhere !== undefined) {
-                sendError(res, 500, "corrupt", "run already ended and this session's stored resume context cannot be read — no wake card was minted and nothing was queued. Ask whoever operates this deployment to repair or remove the row named in `where` before steering this session again.", { where: mintResult.corruptCtxWhere });
+                sendError(res, 500, "corrupt", "run already ended and this session's stored resume context cannot be read — nothing was queued. Ask whoever operates this deployment to repair or remove the row named in `where` before steering this session again.", { where: mintResult.corruptCtxWhere });
                 return;
             }
             if (mintResult.unservable !== undefined) {

package/dist/http/server.d.ts

@@ -563,6 +563,14 @@ export interface ServiceSeamDeps {
      *  per-principal 查询走 caps client 的 executionRuling 同车(零额外 RTT);absent = 无 center(单用户/
      *  dry-run)⇒ 观测面不接线,零行为差。fail-open:观测失败绝不影响 sync 面本身。 */
     sessionMirrorRuling?: (principal: string | undefined) => Promise<SessionMirrorRuling | undefined>;
+    /** 请求点名的场景名过门 —— `capabilities/scenarios.ts` `createScenarioGate` 铸的**那一只**(与 `resolveSpec` 同一个工厂、同一张场景表、同一份
+     *  `principalCaps`、同一份部署缺省):`GET /v1/capabilities/mcp?scenario=<名>` 的状态面靠它回答「这个场景名在不在册、这位 principal 放不放行」,
+     *  拒体(400 `scenario_unknown` 附在册词表 / 400 `scenario_not_allowed` 附 allowlist)因此与任务提交腿逐字同。
+     *  读面上这只门走**只读腿**(`createScenarioGate(…, "peek")`):问中心裁定时 center 抖动的那一拍,不替这个主体的真提交留下 fail-closed 降级项
+     *  (提交腿自己是 `"enforce"`)。只在请求**点名了**场景时才问(缺席 ⇒ 部署缺省场景,不问门、不多一次中心往返;点名空串也交门答,与提交腿 `scenario: ""` 同码)。
+     *  本接缝缺席 = 嵌入方的 HTTP 面没有场景表可问:状态面点名场景答 404 `scenario_not_found`,与场景详情读面({@link scenarioDetails} 缺席)同一个答复,
+     *  不另造空表门、不静默回缺省集。 */
+    scenarioGate?: import("../capabilities/scenarios.js").ScenarioGate;
     /** Degenerate-output a/b instrument: on errorCode=output.degenerate, inspect the session's turns to
      *  classify where the salvageable answer was (counter + log). Fire-and-forget; no-op otherwise. */
     instrumentDegenerate?: (result: TaskResult) => void;

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

@@ -117,7 +117,11 @@ export declare const FAIL_OPEN_TAGS: {
     };
     readonly "server.session-titler.gateway-unreachable": {
         readonly cls: "F";
-        readonly note: "S-178(cli [6662] ① clay 裁定转达,`session-titler.ts logFailure`):自动会话标题那一次廉价模型调用失败(gateway 不可达 / 凭据缺失 / 超时)。标题是**纯装饰**——列表面回退 objectivePreview,零行为影响,门/裁决/账本一个字节不受它管。此前每个新会话首次同 cause 打一条 `warn`,于是一台没配模型 gateway 的单机部署在日志里被这条噪音刷屏,壳因此去关 `SESSION_AUTO_TITLE`(替上游压噪),而那是把一个部署级旋钮当消音器用。现在:逐次 `debug` + 本计数 + 一次性 warn(recorder 自己的),运维仍看得见「这台机器的 titler 一直在失败」,用户面零噪音。观测面另有 `session_title_total{outcome}` 逐次记账。";
+        readonly note: "S-178(cli [6662] ① clay 裁定转达,`session-titler.ts logFailure`):自动会话标题那一次廉价模型调用失败(gateway 不可达 / 凭据缺失 / 超时 / 非 2xx 应答;端点回 3xx 重定向被拒的那一族另记 `server.session-titler.redirect-refused`,不进本 tag)。标题是**纯装饰**——列表面回退 objectivePreview,零行为影响,门/裁决/账本一个字节不受它管。此前每个新会话首次同 cause 打一条 `warn`,于是一台没配模型 gateway 的单机部署在日志里被这条噪音刷屏,壳因此去关 `SESSION_AUTO_TITLE`(替上游压噪),而那是把一个部署级旋钮当消音器用。现在:逐次 `debug` + 本计数 + 一次性 warn(recorder 自己的),运维仍看得见「这台机器的 titler 一直在失败」,用户面零噪音。观测面另有 `session_title_total{outcome}` 逐次记账。";
+    };
+    readonly "server.session-titler.redirect-refused": {
+        readonly cls: "F";
+        readonly note: "`session-titler.ts logFailure`:自动会话标题那一次廉价模型调用被拒 —— 配置的模型端点回了 3xx 重定向。本服务发往配置端点的直连请求不跟随重定向(跟随会把请求体里的用户内容与凭据头送到 `Location` 指向的另一个 origin),所以这是**端点配置问题,不是网络问题**:出路 = 把该模型的网关 URL(`MODEL_GATEWAY_BASEURL` / 目录条目自己的 baseUrl / `ANTHROPIC_BASE_URL`)改成最终地址,查网络没有用。与 `server.session-titler.gateway-unreachable` 的分界 = 失败码(llm 面交回的 `redirect_refused`),不看文案。标题是**纯装饰**——列表面回退 objectivePreview,零行为影响,门/裁决/账本一个字节不受它管。放行的最坏后果 = 该部署的会话没有自动标题。逐次 `debug` + 本计数 + 一次性 warn(recorder 自己的);`session_title_total{outcome=llm_failed}` 照常逐次记账。";
     };
     readonly "server.prompts.artifact-cache-write-failed": {
         readonly cls: "F";

package/dist/observability/fail-open.js

@@ -98,7 +98,11 @@ export const FAIL_OPEN_TAGS = {
     },
     "server.session-titler.gateway-unreachable": {
         cls: "F",
-        note: "S-178(cli [6662] ① clay 裁定转达,`session-titler.ts logFailure`):自动会话标题那一次廉价模型调用失败(gateway 不可达 / 凭据缺失 / 超时)。标题是**纯装饰**——列表面回退 objectivePreview,零行为影响,门/裁决/账本一个字节不受它管。此前每个新会话首次同 cause 打一条 `warn`,于是一台没配模型 gateway 的单机部署在日志里被这条噪音刷屏,壳因此去关 `SESSION_AUTO_TITLE`(替上游压噪),而那是把一个部署级旋钮当消音器用。现在:逐次 `debug` + 本计数 + 一次性 warn(recorder 自己的),运维仍看得见「这台机器的 titler 一直在失败」,用户面零噪音。观测面另有 `session_title_total{outcome}` 逐次记账。",
+        note: "S-178(cli [6662] ① clay 裁定转达,`session-titler.ts logFailure`):自动会话标题那一次廉价模型调用失败(gateway 不可达 / 凭据缺失 / 超时 / 非 2xx 应答;端点回 3xx 重定向被拒的那一族另记 `server.session-titler.redirect-refused`,不进本 tag)。标题是**纯装饰**——列表面回退 objectivePreview,零行为影响,门/裁决/账本一个字节不受它管。此前每个新会话首次同 cause 打一条 `warn`,于是一台没配模型 gateway 的单机部署在日志里被这条噪音刷屏,壳因此去关 `SESSION_AUTO_TITLE`(替上游压噪),而那是把一个部署级旋钮当消音器用。现在:逐次 `debug` + 本计数 + 一次性 warn(recorder 自己的),运维仍看得见「这台机器的 titler 一直在失败」,用户面零噪音。观测面另有 `session_title_total{outcome}` 逐次记账。",
+    },
+    "server.session-titler.redirect-refused": {
+        cls: "F",
+        note: "`session-titler.ts logFailure`:自动会话标题那一次廉价模型调用被拒 —— 配置的模型端点回了 3xx 重定向。本服务发往配置端点的直连请求不跟随重定向(跟随会把请求体里的用户内容与凭据头送到 `Location` 指向的另一个 origin),所以这是**端点配置问题,不是网络问题**:出路 = 把该模型的网关 URL(`MODEL_GATEWAY_BASEURL` / 目录条目自己的 baseUrl / `ANTHROPIC_BASE_URL`)改成最终地址,查网络没有用。与 `server.session-titler.gateway-unreachable` 的分界 = 失败码(llm 面交回的 `redirect_refused`),不看文案。标题是**纯装饰**——列表面回退 objectivePreview,零行为影响,门/裁决/账本一个字节不受它管。放行的最坏后果 = 该部署的会话没有自动标题。逐次 `debug` + 本计数 + 一次性 warn(recorder 自己的);`session_title_total{outcome=llm_failed}` 照常逐次记账。",
     },
     "server.prompts.artifact-cache-write-failed": {
         cls: "F",

package/dist/plugins/one-time-migrations.d.ts

@@ -170,6 +170,17 @@
  *    **读侧半场**(同一行、同一窗,不另起登记行):由存卡唯一读者入口 `approval-card.ts` `readStoredCardEnvelope`(起服改写够不着的卡 —— 滚动升级窗里
  *    7.128.x 副本新写的、local 车道的文件 ask 账)与停驻行入口 `currentParkArm`(**所有**停驻行 —— SQL 与 local 车道引擎 File 店的同一条路径)读时过同一只改写,
  *    **响亮**(`server.approval-card.retired-card-word-read`);读的是浅拷贝,被读的行一个字节不动。local 车道读数恒零(`NO_SQL_MIGRATIONS`)。
+ *  · **M19 续跑重放腿上的存量 `toolAxes`**(7.130.0)—— 请求体 `mcpServers[].toolAxes` 的判官从本版起是引擎的 `readMcpToolAxes`(整份一坏全拒);
+ *    升级前的请求腿读者把非对象(含 `null`)整键忽略、对象逐成员剔坏留好,server 照挂。续跑重放腿重放的是升级前存下的请求体(`checkpoint_ctx`),
+ *    停驻在那台 server 某只工具审批上的任务,若这台 server 整条不进,批准即撞 `resume.tool_unavailable`、检查点重开、永远批不过去。与 M10 同形:
+ *    不改写存下的字节(体按原样留在 ctx 里),是一只**窗内才生效的行为臂** —— 窗开着时(运行期读本表 M19 行的 `removableAfter`,见 {@link migrationWindowOpen}),
+ *    **只在续跑重放腿**、**只对判官判不过的那一格**按升级前的读法重读一次(`stored-request-tool-axes-m19.ts`),产物再交同一只判官(不过 ⇒ 整条不进的原臂),
+ *    真挂上的这类 server 各一行运维 warn `mcp_tool_axes_read_as_before_upgrade`;窗关之后照今天答(整条不进),删码因此是零行为变化。
+ *    窗 = 发布日 + 30 天 = 停驻行的终局兜底窗缺省(`APPROVAL_TERMINAL_BACKSTOP_MS` 缺省 30 天)—— 与 M7 / M12 同一条论证。没有起服读数(它不写库)。
+ *    窗按**发布日**算、停驻行的期限按**停驻时刻**算 ⇒ 三类部署会有升级前停驻的行活过窗、窗关后回到「整条不进」:发布后才升级的部署(发布日到它升级那天之间
+ *    停驻的行)、把 `APPROVAL_TERMINAL_BACKSTOP_MS` 调长的部署、滚动升级里仍跑 7.129.x 的副本在窗内新写的行。与 M7 / M18 一样如实登记,不为它们加长窗。
+ *    **它是上游字段标准的限时例外**:引擎对 `toolAxes` 的标准是「坏键不丢、坏词不默认」(core `mcp-server-spec.d.ts`),窗内这一臂恰恰剔坏留好 ——
+ *    依据是持久数据律(存量数据不能「变红」,只许一次性迁移、窗关删码),只对升级前已经按这种读法跑过的存量体,且对运维响亮。新提交与部署腿不受它影响。
  *
  * ## 幂等
  * 改写的几条都可重复跑(M4:`detail IS NOT NULL AND … = 'null'`;M5:列在场探针 + `WHERE incarnation = ''`;M6:`WHERE error_code IS NULL`;
@@ -295,7 +306,7 @@ export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
 /**
  * 一条登记行的窗**此刻**开着没有(`today` = UTC 日历日 YYYY-MM-DD):未发布形(`removableAfter: null`)⇒ 开;否则今天不晚于 `removableAfter` ⇒ 开
  * (窗关当天仍开,与到期门「今天严格晚于才红」同一条边界)。
- * 只给**窗内才生效的行为臂**用(M10 的认领):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
+ * 只给**窗内才生效的行为臂**用(M10 的认领、M19 的续跑重读):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
  */
 export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow, "removableAfter">, today: string): boolean;
 /** local 车道上 SQL 独有的几条(M4 / M5 / M8 / M9 / M11 / M17 / M18)的读数(M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */

package/dist/plugins/one-time-migrations.js

@@ -241,6 +241,23 @@ export const ONE_TIME_MIGRATIONS = [
             "引擎续跑不受影响:续跑入口读行摘要、不按今日闭集重判停驻行上的这两座,行字节引擎怎么写的还是怎么在",
         reportKeys: ["retiredCardWordAskRowsRewritten", "retiredCardWordRowsUnreadable"],
     },
+    {
+        id: "M19",
+        introducedIn: "7.130.0",
+        releasedOn: "2026-10-16",
+        removableAfter: "2026-11-15",
+        removal: "删 `src/stored-request-tool-axes-m19.ts` 整只文件(`storedToolAxesRereadM19` / `readToolAxesAsServer7129M19` / `StoredToolAxesRereadM19`);" +
+            "`boot/resolve-spec.ts` 里递给 `resolveRequestMcp` 的那一实参(`opts?.leg === \"fresh\" ? undefined : storedToolAxesRereadM19(…)`)与它的 import;" +
+            "`task-mcp.ts` 里 `resolveRequestMcp` / `classifyRequestMcp` / `classifyHonored` / `validateRequestMcpEntries` / `normalizeServer` 的 `storedToolAxes` 形参、" +
+            "`toolAxesReread` 事实与运维行 `mcp_tool_axes_read_as_before_upgrade`,以及对本模块的型 import;`tool-axis-words.ts` 头注与两只谓词 JSDoc 里点名 M19 的那几处;" +
+            "`test/mcp-tool-axes-m19.test.ts`(窗关那一格 —— 存量坏形整条不进、warn 与通告点名 `field: toolAxes` —— 改钉到 `test/task-mcp.test.ts`);" +
+            "本文件的 `migrationWindowOpen`(若再无别的读者)",
+        afterRemoval: "没有新的臂,接住它的是今天的读法(删码零行为变化:窗关那一刻起重读臂已经不生效):升级前存下的请求体里引擎判官判不过的 `toolAxes`,续跑重放时这一条 server 整条不进," +
+            "运维 warn `mcp_injection_dropped`(`reason: malformed_entry`、`field: toolAxes`)+ 用户面通告 `mcp.injection_dropped`,兄弟照挂;停驻在这台 server 工具审批上的任务" +
+            "批准后撞 `resume.tool_unavailable`(拒绝照常可出)—— 出路是拒绝那张卡,用改好的 `toolAxes` 重新提交。会撞上它的是活过窗的升级前停驻行:发布后才升级的部署、" +
+            "调长了 `APPROVAL_TERMINAL_BACKSTOP_MS` 的部署、滚动升级里旧副本在窗内新写的行(头注 M19 段)",
+        reportKeys: [],
+    },
 ];
 export function migrationWindowOpen(window, today) {
     return window.removableAfter === null || today <= window.removableAfter;

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

@@ -4,6 +4,7 @@ import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
+import { commandBoundsOf, livenessCutMessage } from "../exec-bounds.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -191,7 +192,7 @@ export class RemoteAdbExecutionEnv {
             w?.();
         };
         let lastChunk = Date.now();
-        const idleMs = options?.readTimeoutMs;
+        const liveness = commandBoundsOf({ readTimeoutMs: options?.readTimeoutMs }, undefined).liveness;
         let paused = false;
         let onAbort;
         const teardown = () => {
@@ -262,7 +263,7 @@ export class RemoteAdbExecutionEnv {
                     throw failure;
                 if (finished)
                     break;
-                const waitMs = idleMs ? Math.max(1, idleMs - (Date.now() - lastChunk)) : 30_000;
+                const waitMs = liveness !== undefined ? Math.max(1, liveness.ms - (Date.now() - lastChunk)) : 30_000;
                 let waitTimer;
                 try {
                     await new Promise((r) => {
@@ -274,8 +275,8 @@ export class RemoteAdbExecutionEnv {
                     if (waitTimer !== undefined)
                         clearTimeout(waitTimer);
                 }
-                if (idleMs && !finished && Date.now() - lastChunk >= idleMs) {
-                    throw new RemoteExecutionError("timeout", `execStream idle > ${idleMs}ms (device hang / disconnected)`);
+                if (liveness !== undefined && !finished && Date.now() - lastChunk >= liveness.ms) {
+                    throw new RemoteExecutionError("timeout", livenessCutMessage(liveness));
                 }
             }
             while (queue.length)

package/dist/plugins/remote-env-e2b.d.ts

@@ -71,8 +71,9 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
      *  isRunning/files.*. A provider hang is surfaced as a typed retryable `RemoteExecutionError("timeout")` after
      *  this, instead of pinning the worker for the sandbox lifetime. Default {@link DEFAULT_RPC_TIMEOUT_MS}. */
     rpcTimeoutMs?: number;
-    /** 🔴 (hang class-fix) Idle/liveness bound (ms) for a command (exec/execStream): max time with NO output
-     *  and not yet complete = suspected hang. Also bounds the command-creation RPC. Default {@link DEFAULT_LIVENESS_MS}. */
+    /** 🔴 (hang class-fix) The lane's idle/liveness bound (ms; env `E2B_LIVENESS_MS`): max time with NO output and not yet
+     *  complete = suspected hang — cuts a running command ONLY when its caller stated neither a wall-clock (`timeout`) nor its own
+     *  idle bound (`readTimeoutMs`); the rule: `exec-bounds.ts` (creation included). Positive only (`laneLivenessOf`). Default `LIVENESS_MS_DEFAULT`. */
     livenessMs?: number;
     /** 🔴 Wall-clock for data-transfer/provisioning RPCs (large file io, snapshot suspend/resume,
      *  create/connect) — wider than {@link rpcTimeoutMs} so a legit multi-minute transfer is not killed. Default
@@ -105,6 +106,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     readonly cdPath: "unknown";
     private readonly cfg;
     private readonly sandboxApi;
+    /** This lane's own liveness bound — what {@link commandBoundsOf} falls back to when a command's caller stated no bound. */
+    private readonly laneLiveness;
     private sbx?;
     /** 🔴 BL-31 keep-alive — the E2B sandbox lifetime is hard-capped (≈1h, {@link E2B_SANDBOX_MAX_MS}), but a long
      *  leader/repair run legitimately exceeds it. This interval RE-extends the sandbox (`setTimeout(timeoutMs)` resets
@@ -287,23 +290,42 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      * the adapter NEVER blind-retries). A caller AbortSignal still aborts independently (op surfaces it / "aborted").
      */
     private rpc;
+    /**
+     * A command start that already returned to its caller (its creation deadline fired, or it failed): a handle the provider
+     * hands over LATER is killed — the caller was told the command was cut, so it must not run on. The rule for the in-flight
+     * count this start holds: it is released **once, and only when the command is confirmed not running** (council #4: never
+     * snapshot a running command). Confirmations: the provider answered `kill()` (`true` killed / `false` no such process);
+     * the handle's one `wait()` reports the process exited (a result, or `CommandExitError` for a non-zero exit). Not
+     * confirmations: a refused `kill()` (logged; the exit is still awaited), a `wait()` that ends without an exit (the
+     * connection deadline, a lost stream — the process may still run). With neither the count stays held and `suspendVM`
+     * keeps refusing `command_in_flight` — the same arm as a start that never settles. No start promise (the op never ran)
+     * ⇒ released now. A failed start is released at once too, as in 7.129.0 — and that one is NOT a confirmation: there is
+     * no handle to kill or wait on, and a start whose reply was lost (the SDK's own 60 s handshake) may have spawned the
+     * process. Closing it means classifying the start failure (provider refused ⇒ not started; lost reply ⇒ held) — open,
+     * not done here.
+     */
+    private settleAbandonedStart;
     /**
      * Per-command wall-clock for the E2B SDK (seconds→ms). 🔴 This is a PHYSICAL CAP, NOT the hang
      * detector. The old code returned `this.cfg.timeoutMs` (the sandbox lifetime) when no `timeout` was given AND
      * had no liveness check → a hung command waited the WHOLE lifetime (~30 min, the original hang bug). The fix is
      * NOT to shorten this cap (that would spuriously kill a long-but-progressing `npm ci`) — it's to add a LIVENESS
      * bound ({@link cfg.livenessMs}) in exec/execStream that catches a *zero-progress* command in ~livenessMs,
-     * independent of this cap. So: explicit caller `timeout` wins; else the lifetime is the cap (a command can't
-     * outlive its VM) but hang detection no longer depends on it.
+     * independent of this cap. So: explicit caller `timeout` wins — and is then the command's bound (the liveness bound
+     * stays out, `exec-bounds.ts`); else the lifetime is the cap (a command can't outlive its VM) and the liveness bound
+     * is the hang detector.
      */
     private commandTimeoutMs;
     /**
-     * 🔴 Liveness for the buffered exec WAIT phase. `handle.wait()` is a long-poll with no read timeout —
+     * 🔴 Bounds for the buffered exec WAIT phase. `handle.wait()` is a long-poll with no read timeout —
      * a command that hangs DURING execution (not creation) would otherwise wait the E2B command timeout (= the
-     * lifetime when none is set, the original hang bug). Races wait() against an idle check: if no stdout/stderr for
-     * `livenessMs`, the command is hung → kill + typed retryable "timeout". `lastProgress()` is bumped by the
-     * stdout/stderr callbacks, so a slow-but-PROGRESSING command (long `npm ci`) is never killed. (execStream has
-     * its own chunk-driven idle timer; this is the buffered-exec analogue.)
+     * lifetime when none is set, the original hang bug). With a `liveness` bound (the caller stated no `timeout` —
+     * `exec-bounds.ts`) it races wait() against an idle check: no stdout/stderr for `liveness.ms` ⇒ hung → kill + typed
+     * retryable "timeout" with the shared cut sentence. `lastProgress()` is bumped by the stdout/stderr callbacks, so a
+     * slow-but-PROGRESSING command (long `npm ci`) is never killed. Both cuts reject with an `ExecutionError` carrying
+     * its real code (exec returns it as-is) — a `RemoteExecutionError` here would reach {@link execError}'s text match
+     * and land as `unknown`. The rejection is armed BEFORE the kill: the kill rejects `wait()` too, and the race must
+     * see the bound, not the kill. (execStream has its own chunk-driven idle timer; this is the buffered-exec analogue.)
      */
     private waitWithLiveness;
     /** Lazily provision the VM on first use: a task that never touches the hand pays zero cost.

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

@@ -3,13 +3,13 @@ import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
 import { numEnvOr, runSymlinkChain, shellQuote } from "./remote-shell.js";
+import { commandBoundsOf, firstBoundOf, laneLivenessOf, livenessCutMessage, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
 const PROVIDER = "e2b";
 const DEFAULT_MOUNT_PATH = "/home/user";
 const DEFAULT_TIMEOUT_MS = 5 * 60_000;
 const E2B_SANDBOX_MAX_MS = numEnvOr("E2B_SANDBOX_MAX_MS", 3_600_000, 60_000);
 const DEFAULT_RPC_TIMEOUT_MS = 60_000;
-const DEFAULT_LIVENESS_MS = 120_000;
 const DEFAULT_DATA_TIMEOUT_MS = 5 * 60_000;
 const E2B_BG_MAX_CONCURRENT = numEnvOr("E2B_BG_MAX_CONCURRENT", 8, 1);
 const E2B_BG_DEFAULT_TIMEOUT_SEC = numEnvOr("E2B_BG_DEFAULT_TIMEOUT_SEC", 300, 1);
@@ -22,6 +22,7 @@ export class RemoteContainerExecutionEnv {
     cdPath = "unknown";
     cfg;
     sandboxApi;
+    laneLiveness;
     sbx;
     keepAlive;
     handle;
@@ -36,9 +37,10 @@ export class RemoteContainerExecutionEnv {
             timeoutMs: Math.min(config.timeoutMs ?? DEFAULT_TIMEOUT_MS, E2B_SANDBOX_MAX_MS),
             allowInternetAccess: config.allowInternetAccess ?? true,
             rpcTimeoutMs: config.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
-            livenessMs: config.livenessMs ?? DEFAULT_LIVENESS_MS,
+            livenessMs: config.livenessMs ?? LIVENESS_MS_DEFAULT,
             dataTimeoutMs: config.dataTimeoutMs ?? DEFAULT_DATA_TIMEOUT_MS,
         };
+        this.laneLiveness = laneLivenessOf(this.cfg.livenessMs, "E2B_LIVENESS_MS");
         this.cwd = this.cfg.mountPath;
         this.homeDir = config.homeDir;
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
@@ -255,9 +257,14 @@ export class RemoteContainerExecutionEnv {
             s.total += b.length;
         };
         let lastProgress = Date.now();
+        const startedAt = lastProgress;
+        const bounds = commandBoundsOf({ timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined }, this.laneLiveness);
+        const first = firstBoundOf(bounds);
         let handle;
+        let starting;
+        let startCut = false;
         try {
-            handle = await this.rpc("commands.run", () => sbx.commands.run(command, {
+            handle = await this.rpc("commands.run", () => (starting = sbx.commands.run(command, {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
                 ...(options?.env ? { envs: options.env } : {}),
@@ -265,6 +272,8 @@ export class RemoteContainerExecutionEnv {
                     ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
                     : this.commandTimeoutMs(options?.timeout),
                 onStdout: (d) => {
+                    if (startCut)
+                        return;
                     if (tee)
                         teePush(tee.stdout, d);
                     if (!detached) {
@@ -273,6 +282,8 @@ export class RemoteContainerExecutionEnv {
                     }
                 },
                 onStderr: (d) => {
+                    if (startCut)
+                        return;
                     if (tee)
                         teePush(tee.stderr, d);
                     if (!detached) {
@@ -280,11 +291,13 @@ export class RemoteContainerExecutionEnv {
                         options?.onStderr?.(d);
                     }
                 },
-            }), options?.abortSignal, this.cfg.livenessMs);
+            })), options?.abortSignal, first.ms);
         }
         catch (e) {
-            this.activeCommands--;
-            return { ok: false, error: this.execError(e, options?.abortSignal) };
+            startCut = true;
+            this.settleAbandonedStart(starting);
+            const cut = e instanceof RemoteExecutionError && e.code === "timeout" && !options?.abortSignal?.aborted;
+            return { ok: false, error: cut ? new ExecutionError("timeout", boundCutMessage(first)) : this.execError(e, options?.abortSignal) };
         }
         const onAbort = () => { if (!detached)
             void handle.kill().catch(() => { }); };
@@ -333,7 +346,8 @@ export class RemoteContainerExecutionEnv {
             const fg = this.waitWithLiveness(handle, () => lastProgress, {
                 waitP,
                 disarmed: () => detached,
-                ...(tee ? { wallMs: this.commandTimeoutMs(options?.timeout) } : {}),
+                ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)) } } : {}),
+                liveness: bounds.liveness,
             });
             const winner = await (detachedP ? Promise.race([fg, detachedP]) : fg);
             if (winner === "detached") {
@@ -385,6 +399,9 @@ export class RemoteContainerExecutionEnv {
         };
         let bytes = 0;
         const cap = options?.maxOutputBytes;
+        const bounds = commandBoundsOf({ timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined, readTimeoutMs: options?.readTimeoutMs }, this.laneLiveness);
+        const liveness = bounds.liveness;
+        const first = firstBoundOf(bounds);
         const push = (type, data) => {
             if (finished)
                 return;
@@ -394,18 +411,22 @@ export class RemoteContainerExecutionEnv {
         };
         this.activeCommands++;
         let handle;
+        let starting;
         try {
-            handle = await this.rpc("commands.run", () => sbx.commands.run(command, {
+            handle = await this.rpc("commands.run", () => (starting = sbx.commands.run(command, {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
                 ...(options?.env ? { envs: options.env } : {}),
                 timeoutMs: this.commandTimeoutMs(options?.timeout),
                 onStdout: (d) => push("stdout", d),
                 onStderr: (d) => push("stderr", d),
-            }), options?.signal, this.cfg.livenessMs);
+            })), options?.signal, first.ms);
         }
         catch (e) {
-            this.activeCommands--;
+            finished = true;
+            this.settleAbandonedStart(starting);
+            if (e instanceof RemoteExecutionError && e.code === "timeout" && !options?.signal?.aborted)
+                throw new RemoteExecutionError("timeout", boundCutMessage(first), e);
             throw this.remoteError(e, "connect_failed");
         }
         handle
@@ -424,7 +445,7 @@ export class RemoteContainerExecutionEnv {
                 exitCode = e.exitCode;
             }
             else {
-                failure = this.remoteError(e, "unknown");
+                failure = this.remoteError(e, providerTimedOut(e) ? "timeout" : "unknown");
             }
             finished = true;
             signalReady();
@@ -465,13 +486,14 @@ export class RemoteContainerExecutionEnv {
                 const next = new Promise((resolve) => {
                     wake = resolve;
                 });
-                const idleMs = options?.readTimeoutMs ?? this.cfg.livenessMs;
                 let timer;
-                const idle = new Promise((_, reject) => {
-                    timer = setTimeout(() => reject(new RemoteExecutionError("timeout", `execStream idle > ${idleMs}ms (provider hang / unreachable sandbox)`)), idleMs);
-                });
+                const idle = liveness === undefined
+                    ? undefined
+                    : new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new RemoteExecutionError("timeout", livenessCutMessage(liveness))), liveness.ms);
+                    });
                 try {
-                    await Promise.race([next, idle]);
+                    await (idle === undefined ? next : Promise.race([next, idle]));
                 }
                 catch (e) {
                     finished = true;
@@ -794,36 +816,59 @@ export class RemoteContainerExecutionEnv {
             combined?.dispose();
         }
     }
+    settleAbandonedStart(starting) {
+        let held = true;
+        const release = () => {
+            if (!held)
+                return;
+            held = false;
+            this.activeCommands--;
+        };
+        if (starting === undefined)
+            return release();
+        void starting.then((late) => {
+            late.wait().then(release, (e) => {
+                if (e instanceof CommandExitError)
+                    release();
+            });
+            late.kill().then(release, (e) => {
+                this.cfg.logger?.warn?.("e2b_abandoned_start_kill_failed", { sandboxId: this.sbx?.sandboxId, pid: late.pid, error: e instanceof Error ? e.name : typeof e });
+            });
+        }, release);
+    }
     commandTimeoutMs(timeoutSec) {
         return timeoutSec != null ? timeoutSec * 1000 : this.cfg.timeoutMs;
     }
     async waitWithLiveness(handle, lastProgress, opts) {
         let timer;
         let wallTimer;
+        const liveness = opts?.liveness;
         const idle = new Promise((_, reject) => {
-            const arm = () => {
+            const arm = (bound) => {
                 timer = setTimeout(() => {
                     if (opts?.disarmed?.())
                         return;
                     const idleFor = Date.now() - lastProgress();
-                    if (idleFor >= this.cfg.livenessMs) {
+                    if (idleFor >= bound.ms) {
+                        reject(new ExecutionError("timeout", livenessCutMessage(bound)));
                         void handle.kill().catch(() => { });
                         this.cfg.metrics?.inc("remote_env_exec_idle_timeout_total", { provider: PROVIDER });
-                        reject(new RemoteExecutionError("timeout", `exec idle > ${this.cfg.livenessMs}ms (provider hang / unreachable sandbox)`));
                     }
                     else {
-                        arm();
+                        arm(bound);
                     }
-                }, Math.max(this.cfg.livenessMs - (Date.now() - lastProgress()), 0));
+                }, Math.max(bound.ms - (Date.now() - lastProgress()), 0));
             };
-            arm();
-            if (opts?.wallMs != null) {
+            if (liveness !== undefined)
+                arm(liveness);
+            if (opts?.wall !== undefined) {
+                const wall = opts.wall;
                 wallTimer = setTimeout(() => {
                     if (opts.disarmed?.())
                         return;
+                    reject(new ExecutionError("timeout", boundCutMessage({ ms: wall.totalMs, cut: "wall" })));
                     void handle.kill().catch(() => { });
-                    reject(new RemoteExecutionError("timeout", `exec exceeded ${opts.wallMs}ms`));
-                }, opts.wallMs);
+                }, wall.leftMs);
             }
         });
         try {
@@ -905,7 +950,7 @@ export class RemoteContainerExecutionEnv {
         const name = e?.name;
         if (abortSignal?.aborted || name === "AbortError")
             return new ExecutionError("aborted", msg);
-        if (name === "TimeoutError" || /timeout|timed out/i.test(msg))
+        if (providerTimedOut(e))
             return new ExecutionError("timeout", msg);
         return new ExecutionError("unknown", msg, e instanceof Error ? e : undefined);
     }
@@ -924,6 +969,12 @@ export function e2bExecutionEnvFactory(config, deps) {
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
+function boundCutMessage(first) {
+    return first.cut === "wall" ? `exec exceeded ${first.ms}ms` : livenessCutMessage(first.cut);
+}
+function providerTimedOut(e) {
+    return e?.name === "TimeoutError" || /timeout|timed out/i.test(errMsg(e));
+}
 function anySignal(signals) {
     const ctor = AbortSignal;
     if (typeof ctor.any === "function")