@sema-agent/server 3.21.0 → 3.23.0

package/dist/http/principal-gate.js

@@ -61,7 +61,10 @@ export function gatedPrincipal(req, config) {
 }
 /** The EXPLICIT operator gate (IMAGE-API-DESIGN.md §P2.4a MUST-FIX) — NOT the bare `isOperator` (whose empty-list
  *  "true-for-all" is a world-writable RCE door the instant OPERATOR_PRINCIPALS is empty). Requires a non-empty
- *  operator set AND a present principal IN it. The same form the preempt/resume endpoints already use. */
+ *  operator set AND a present principal IN it. The same form the preempt/resume endpoints already use.
+ *  🔴 SINGLE mint point (E1): a byte-identical twin `explicitOperator` used to live below (image-visibility lane)
+ *  and two more hand-inlined copies sat in approvals-assistant — a future hardening of this judgment would have
+ *  missed them. All call sites now consume THIS function; do not re-introduce a sibling. */
 export function explicitOperatorOk(principal, operatorPrincipals) {
     return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
 }
@@ -77,8 +80,7 @@ export function isOperator(principal, operatorPrincipals) {
  *  yields `false` (no one is an operator). Use this where empty-operators-means-all would be a SECURITY hole rather
  *  than a back-compat convenience: image VISIBILITY scoping (a tenant-scoped image must not leak to every caller
  *  just because OPERATOR_PRINCIPALS is unset). Adversarial-review HIGH: `isOperator([], p)=true` made
- *  `latestPublished(..., {operator:true})` bypass tenant visibility for any caller on an operator-less deployment. */
-export function explicitOperator(principal, operatorPrincipals) {
-    return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
-}
+ *  `latestPublished(..., {operator:true})` bypass tenant visibility for any caller on an operator-less deployment.
+ *  (The byte-identical `explicitOperator` twin that used to live here was folded into `explicitOperatorOk` above —
+ *  one judgment, one mint point.) */
 //# sourceMappingURL=principal-gate.js.map

package/dist/http/route-ctx.d.ts

@@ -75,6 +75,38 @@ export interface RouteRequestState {
     /** 凭证派生的调用方系统身份(`source`)。handle() 的鉴权门是**唯一**赋值点,域模块只读。 */
     source: string | null;
 }
+/** B4①(命名化):`prepareSpec` 的返回形(tasks.ts/runs.ts 两域共同消费的属性面)——原为 6 成员内联匿名对象。
+ *  命名后好处不只是过 B4 门:两个消费域现在都能对同一个符号做 `import type` 标注,而不是各自重推断结构。 */
+export interface PreparedTaskSubmission {
+    spec: TaskSpec;
+    auth?: RequestAuth;
+    verify?: {
+        maxRounds: number;
+        costCeilingMicroUsd?: number;
+    };
+    cascade?: boolean;
+    jobId?: string;
+    body: TaskRequestBody;
+}
+/** B4①(命名化):`driveResumeIntoRunLog` 的入参形(resume 家族共用)——原为 9 成员内联匿名对象。 */
+export interface DriveResumeArgs {
+    token: CheckpointToken;
+    sessionId: string;
+    principal: string | undefined;
+    fleetScope: string;
+    taskConfig: Omit<TaskSpec, "objective" | "sessionId">;
+    resumeObjective: string;
+    outcome: ResumeOutcome;
+    verifyRounds: {
+        maxRounds: number;
+        costCeilingMicroUsd?: number;
+    } | undefined;
+    /** codex M2: side-effects that must land AFTER the markResuming CAS is WON (decide accepted, sibling races
+     *  lost — never fires on the 409/404 paths) and BEFORE the model leg drives (so the resumed leg's own next
+     *  ask sees them — the decide leg's exemption grant). Contract: must not throw (callers swallow internally);
+     *  awaited so the ordering guarantee is real, and a store write here is ms-scale vs the model leg. */
+    onResumeCommitted?: () => Promise<void>;
+}
 /** 提交/续跑「腿」= 跨域共享的**有状态**长流程(不像 {@link RouteHelpers} 那样只依赖 deps/config:它们要写
  *  run log、发 fleet 帧、走 markResuming CAS、驱动模型)。A9 上批的停点就在这里——tasks/runs 两域共用
  *  `prepareSpec`,approvals/assistant/notify-wake 三域共用 resume 家族,把它们跟着任一域搬都会造出
@@ -82,17 +114,7 @@ export interface RouteRequestState {
  *  装进这一格,域模块经 `ctx.legs.*` 调用。类型化 ⇒ 腿的形漂了是编译红,不是运行时静默 404。 */
 export interface RouteLegs {
     /** POST /v1/tasks · /v1/tasks/stream · /v1/runs 的共同前段:读体 → 校验 → resolveSpec。null = 已应答(400/…)。 */
-    prepareSpec(req: IncomingMessage, res: ServerResponse): Promise<{
-        spec: TaskSpec;
-        auth?: RequestAuth;
-        verify?: {
-            maxRounds: number;
-            costCeilingMicroUsd?: number;
-        };
-        cascade?: boolean;
-        jobId?: string;
-        body: TaskRequestBody;
-    } | null>;
+    prepareSpec(req: IncomingMessage, res: ServerResponse): Promise<PreparedTaskSubmission | null>;
     /** 同步腿的终局记账(计费/配额/指标),tasks 域用。 */
     finalizeTaskResult(result: TaskResult, principal: string | undefined, objective: string, sessionId: string | undefined): void;
     /** approvals 决策腿:session → pending checkpoint → markResuming CAS → 驱动续跑。 */
@@ -101,20 +123,7 @@ export interface RouteLegs {
         body: object;
     }>;
     /** 全 resume 家族的共同下半场(lease admission + 写 run log + fleet 发布)。 */
-    driveResumeIntoRunLog(args: {
-        token: CheckpointToken;
-        sessionId: string;
-        principal: string | undefined;
-        fleetScope: string;
-        taskConfig: Omit<TaskSpec, "objective" | "sessionId">;
-        resumeObjective: string;
-        outcome: ResumeOutcome;
-        verifyRounds: {
-            maxRounds: number;
-            costCeilingMicroUsd?: number;
-        } | undefined;
-        onResumeCommitted?: () => Promise<void>;
-    }): Promise<{
+    driveResumeIntoRunLog(args: DriveResumeArgs): Promise<{
         status: number;
         body: object;
     }>;

package/dist/http/routes/approvals-assistant.js

@@ -92,7 +92,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const operators = deps.config.operatorPrincipals;
-                const isExplicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
+                const isExplicitOperator = explicitOperatorOk(principal, operators); // E1: single mint point (principal-gate)
                 if (!isExplicitOperator) {
                     // 🔴 fail-CLOSED owner gate (both reviewers, 2026-07-13): mirror the sibling owner-gated routes
                     // (session policy/delete) — ownerOf REQUIRED (absent ⇒ 501, never open), a store error PROPAGATES
@@ -292,7 +292,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             // + the cancel/decide precedent). NOT the bare isOperator (its empty-list "true-for-all" would let any
             // caller preempt anyone — same trap the /decide owner-gate avoids).
             const operators = deps.config.operatorPrincipals;
-            const explicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
+            const explicitOperator = explicitOperatorOk(principal, operators); // E1: single mint point (principal-gate)
             if (!explicitOperator && run.owner !== null && run.owner !== principal) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
@@ -349,7 +349,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
             const operators = deps.config.operatorPrincipals;
-            const explicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
+            const explicitOperator = explicitOperatorOk(principal, operators); // E1: single mint point (principal-gate)
             if (!explicitOperator && run.owner !== null && run.owner !== principal) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
@@ -436,7 +436,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 deciderPrincipal = proof.principal;
             }
             const operators = deps.config.operatorPrincipals;
-            const explicitOperator = operators.length > 0 && deciderPrincipal !== undefined && operators.includes(deciderPrincipal);
+            const explicitOperator = explicitOperatorOk(deciderPrincipal, operators); // E1: single mint point (principal-gate)
             if (!explicitOperator && run.owner !== null && run.owner !== deciderPrincipal) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
@@ -579,7 +579,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             // credential sessionId+boundInputHash (from a log/screenshot/ticket). A non-owner-non-operator gets 404
             // (no existence oracle — parity with runOwnerOk + the cancel P0 precedent), never 403.
             const operators = deps.config.operatorPrincipals;
-            const explicitOperator = operators.length > 0 && deciderPrincipal !== undefined && operators.includes(deciderPrincipal);
+            const explicitOperator = explicitOperatorOk(deciderPrincipal, operators); // E1: single mint point (principal-gate)
             if (!explicitOperator) {
                 const cpScope = await cs.peekPendingScope(sessionId);
                 // "_" = the anonymous-submit scope SENTINEL (main.ts writes auth?.principal ?? "_" at suspend) — treat it

package/dist/http/routes/images.js

@@ -5,7 +5,7 @@ import { manifestToIndexEntry } from "../../images/manifest.js";
 import { validateBake, buildBakeArgv } from "../../images/bake-validate.js";
 import { streamSseLog } from "../sse-log.js";
 import { sendJson, sendError } from "../send.js";
-import { headerStr, safeEqual, gatedPrincipal, explicitOperatorOk, explicitOperator } from "../principal-gate.js";
+import { headerStr, safeEqual, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 import { scopedIdempotencyKey } from "../idempotency.js";
 export function createImagesLocal(deps) {
     // Per-principal bake-submission rate guard (IMAGE-API-DESIGN.md §P2.4c — fills the register DoS gap the images
@@ -86,7 +86,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         // Identity resolved EXACTLY as P1 (direct-door JWT-without-cnf.bnd, else principalFrom).
         const principal = gatedPrincipal(req, deps.config); // direct-door safe — identity-only proof; single source of truth (see gatedPrincipal)
         const operators = deps.config.operatorPrincipals;
-        const explicitOperator = explicitOperatorOk(principal, operators);
+        const isExplicitOperator = explicitOperatorOk(principal, operators);
         const cfg = deps.config.imageBakes;
         // 🔴 H1: the bake-runner identity is DERIVED from its bearer CREDENTIAL (the token-derived `source`,
         // resolved above from SERVICE_AUTH_TOKENS), NOT a self-asserted x-agent-principal/JWT the runner never
@@ -96,7 +96,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         const isRunner = source !== undefined && source !== null && source === cfg.runnerPrincipal;
         // POST /v1/images/bakes — operator-only submit. EXPLICIT operator gate (NOT the bare isOperator; §P2.4a).
         if (req.method === "POST" && url === "/v1/images/bakes") {
-            if (!explicitOperator) {
+            if (!isExplicitOperator) {
                 sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
@@ -198,7 +198,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         // GET /v1/images/bakes/:bakeId/events — resumable SSE (the live "baking…" view), run-trace-SSE-shaped (§P2.2).
         const evMatch = req.method === "GET" ? BAKE_EVENTS_RE.exec(url) : null;
         if (evMatch) {
-            if (!explicitOperator) {
+            if (!isExplicitOperator) {
                 sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
@@ -214,7 +214,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         // POST /v1/images/bakes/:bakeId/cancel — cooperative cancel (durable flag; the runner kills the pgid, §P2.11).
         const cancelMatch = req.method === "POST" ? BAKE_CANCEL_RE.exec(url) : null;
         if (cancelMatch) {
-            if (!explicitOperator) {
+            if (!isExplicitOperator) {
                 sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
@@ -337,7 +337,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         // the `/events|/cancel|/claim|/ingest` sub-actions (two-segment) win first.
         const idMatch = req.method === "GET" ? BAKE_ID_RE.exec(url) : null;
         if (idMatch) {
-            if (!explicitOperator) {
+            if (!isExplicitOperator) {
                 sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
@@ -362,10 +362,10 @@ async function handleImagesBody(req, res, url, ctx, miss) {
     if (deps.imageIndex && url.startsWith("/v1/images")) {
         const idx = deps.imageIndex;
         const principal = gatedPrincipal(req, deps.config); // direct-door safe — identity-only proof; single source of truth (see gatedPrincipal)
-        // explicitOperator (NOT isOperator): for image VISIBILITY, an empty OPERATOR_PRINCIPALS must NOT make every
+        // explicitOperatorOk (NOT isOperator): for image VISIBILITY, an empty OPERATOR_PRINCIPALS must NOT make every
         // caller an operator (that would leak tenant-scoped images). Adversarial-review HIGH — same fix as the P0.5
         // per-task resolve in main.ts. (Approval operator gates below keep isOperator's legacy empty=all boundary.)
-        const operator = explicitOperator(principal, deps.config.operatorPrincipals);
+        const operator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         const viewer = { operator, tenantId: principal ?? null };
         const q = new URL(req.url ?? "", "http://x").searchParams;
         // GET /v1/images — the paginated catalog. ?profile=&status=&capability=&latest=true&limit=&cursor=

package/dist/http/routes/runs.js

@@ -1134,7 +1134,12 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         const parkArbiterUnreachable = details?.error === "park_arbiter_unreachable";
         const parkResumeWon = details?.error === "park_resume_won";
         const stillParked = details?.error === "parked_pending_approval" || details?.status === "parked";
-        if (stopVerb && details?.error !== undefined && (details.status === "running" || stillParked || parkResumeWon || parkArbiterUnreachable)) {
+        // v3.1 批2(统检第二波 high):判别方向翻转——旧形是 (status,error) 的**失败白名单**(status==="running"
+        // || 三个具名码),core 新增失败码且行状态不在 {running,parked} 时整个分支被跳过落 200,与上面注释自陈
+        // 的不变量(kill 没落地绝不读成功)正相悖(B5 联合非穷尽的 default-放行形;not_local/park 族/arbiter
+        // 三次历史新增全靠人追认)。新形:stop 动词的 error **在场即失败**(not_found 已在上方早退),具名臂
+        // 保留各自 errorCode,未知码落 stop.not_landed 兜底 409——新失败码默认可见,不默认成功。
+        if (stopVerb && details?.error !== undefined) {
             // 1.250:durable 回落臂(core stopTask agentStore 分支)对他实例 running 行应答 error="not_local"
             // (没有 kill 被尝试)——与「kill 尝试了没落地」(stop.not_landed)是不同的失败形,各给各的
             // errorCode(同 409 家族,additive)。

package/dist/http/server.d.ts

@@ -31,8 +31,8 @@ import { cascadeConfig } from "./run-meta.js";
 export { cascadeConfig };
 import { coarseStatusForState, errorCodeForExit } from "./routes/images.js";
 export { coarseStatusForState, errorCodeForExit };
-import { explicitOperatorOk, isOperator, explicitOperator } from "./principal-gate.js";
-export { explicitOperatorOk, isOperator, explicitOperator };
+import { explicitOperatorOk, isOperator } from "./principal-gate.js";
+export { explicitOperatorOk, isOperator };
 /** Per-request authorization context resolved before building the spec (identity, owned session). */
 export interface RequestAuth {
     principal?: string;

package/dist/http/server.js

@@ -48,8 +48,8 @@ export { coarseStatusForState, errorCodeForExit };
 // design/158 A9:装配器缝——发送器/身份门下沉到 http/ 叶子模块,routes/* 与 server.ts 共用同一实现
 // (routes/* 绝不可值 import server.ts:那条边会闭合运行时环,见 test/module-cycle-gate.test.ts)。
 import { sendJson, sendError, httpErrorCode, msg } from "./send.js";
-import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, isOperator, explicitOperator } from "./principal-gate.js";
-export { explicitOperatorOk, isOperator, explicitOperator };
+import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, isOperator } from "./principal-gate.js";
+export { explicitOperatorOk, isOperator };
 /** 分组入参 → 平铺视图(createHttpServer 的第一件事)。一组都没给 ⇒ 原样返回(存量调用零开销、零形变)。 */
 export function flattenServiceDeps(deps) {
     const { stores, coordinators, seams, observability, governance, deployment, knobs, ...flat } = deps;
@@ -1671,16 +1671,20 @@ export function createHttpServer(rawDeps) {
                             if (!rs || !taskId)
                                 return;
                             const t = e.type;
+                            // C2/C5(v3.1 批2):写失败留痕——同函数 onTaskNotification 的 park-enqueue 早按 2026-07-11
+                            // 对抗评审补了 warn(false park 指纹),这三处同构 fire-and-forget 此前裸吞:子代 tool 生命周期
+                            // 事件从 durable log 永久消失且零信号。结构上仍不能 await(同步回调),留痕不改调用形。
+                            const warnAppend = (kind) => (err) => deps.logger?.warn?.("forward_event_append_failed", { type: kind, taskId, err: err instanceof Error ? err.message : String(err) });
                             if (t === "task_progress") {
-                                void append("task_progress", taskProgressEventData(e)).catch(() => undefined);
+                                void append("task_progress", taskProgressEventData(e)).catch(warnAppend(t));
                             }
                             else if (t === "tool_start") {
                                 // C1 (core 1.219): a delegated child's forwarded tool lifecycle — durable via the SAME shared
                                 // whitelist+redact builders as the top stream (parity with the bg leg; deltas not persisted per-chunk).
-                                void append("tool_start", toolStartEventData(e)).catch(() => undefined);
+                                void append("tool_start", toolStartEventData(e)).catch(warnAppend(t));
                             }
                             else if (t === "tool_end") {
-                                void append("tool_end", toolEndEventData(e)).catch(() => undefined);
+                                void append("tool_end", toolEndEventData(e)).catch(warnAppend(t));
                             }
                         },
                         // background-completion observer — flip the child's fleet row +
@@ -2559,7 +2563,7 @@ function cors(res, req, origins, principalHeader) {
     // 后五项都是**真被 handler 读**的自定义头:`idempotency-key`(tasks/runs/images)、
     // `x-detach-on-disconnect`(tasks 断连不中止)、direct-door 决策证明三件套(approvals /decide 的
     // crypto 绑定腿 —— 缺了它,direct-door worker 上的 web 审批面在浏览器里根本用不了)。
-    res.setHeader("access-control-allow-headers", `content-type, authorization, last-event-id, ${principalHeader}, idempotency-key, x-detach-on-disconnect, x-approval-principal-token, x-approval-mac, x-approval-mac-kid`);
+    res.setHeader("access-control-allow-headers", `content-type, authorization, last-event-id, ${principalHeader}, idempotency-key, x-detach-on-disconnect, x-approval-principal-token, x-approval-mac, x-approval-mac-kid, if-none-match`);
     // 🔴 expose-headers 此前**整个缺席** ⇒ fetch 类客户端读不到 `X-Task-Id`(routes/tasks.ts 经 sseHeaders
     // 下发的 durable rewind handle)。tasks.ts 的 G15 meta 帧注释把这归因为「EventSource 与部分代理读不到
     // 响应头」—— 对 EventSource 成立,但对 fetch 客户端真因是这里缺 expose,meta 帧只是绕过。

package/dist/key-resolver.d.ts

@@ -23,7 +23,13 @@ import { type SealedKeyPoison } from "./sealed-key.js";
  * construction in applyEffective (a sealed model never lands in modelApiKeyEnv); the ordering here is
  * belt-and-suspenders. 🔴 Plaintext values are live secrets: memory-only, never log them.
  */
-export declare function createKeyResolver(modelApiKeyEnv: Record<string, string>, env?: NodeJS.ProcessEnv, modelApiKeys?: Record<string, string | SealedKeyPoison>): ((model: Model) => Promise<{
+/** The ONE field the per-model key plane keys on. The resolver's parameter is deliberately this minimal
+ *  named ref (not the full core `Model`): full models are structural supersets and pass unchanged, while
+ *  callers that never materialize a full Model (hook-llm resolves keys for roster entries by catalog name)
+ *  can mint `{ name }` legally instead of forcing it through an `as never` escape hatch (B1). Contravariance
+ *  keeps the resolver assignable wherever `(model: Model) => …` is expected. */
+export type ModelKeyRef = Pick<Model, "name">;
+export declare function createKeyResolver(modelApiKeyEnv: Record<string, string>, env?: NodeJS.ProcessEnv, modelApiKeys?: Record<string, string | SealedKeyPoison>): ((model: ModelKeyRef) => Promise<{
     apiKey: string;
 } | undefined>) | undefined;
 /**

package/dist/key-resolver.js

@@ -1,27 +1,4 @@
 import { isSealedKeyPoison, SealedKeyPoisonedError } from "./sealed-key.js";
-/**
- * Build a per-model API-key resolver for `TaskSpec.getApiKeyAndHeaders` from the catalog's
- * name → env-var-NAME map (sema-registry `apiKeyEnv`). core threads this per brain call — and per cascade
- * rung — so each model/rung authenticates with its OWN upstream account/key.
- *
- * Additive by construction: a model absent from the map — or whose env var is unset — returns
- * `undefined`, so core falls back to the brain's construction-time gateway key (today's behavior, no
- * regression). When no per-model keys are configured at all this returns `undefined`, leaving the spec
- * field unset so core's default path is byte-for-byte unchanged.
- *
- * Only the api KEY is per-model; the base URL stays brain-owned (design/15) — core's seam carries
- * `{ apiKey, headers? }`, not a baseUrl. Same-account-rotation could round-robin inside this function.
- *
- * `modelApiKeys` (sealed-box custody) carries per-model entries unsealed from `ModelEntry.sealedApiKey` —
- * resolved FIRST (sealed outranks the env-NAME reference, the registry-core mutual-exclusion ruling). Each
- * entry is either the PLAINTEXT key (successful unseal) or a `SealedKeyPoison` marker (unseal FAILED at
- * apply time): a poisoned model THROWS `SealedKeyPoisonedError` on every resolve — task-level fail-loud —
- * because returning `undefined` here means "use the gateway key", and a broken sealed key must NEVER
- * silently burn the shared gateway account (the core invariant of the poison-pill fix; a poisoned model
- * skips its env reference too, same mutual-exclusion as a healthy sealed key). The maps are disjoint by
- * construction in applyEffective (a sealed model never lands in modelApiKeyEnv); the ordering here is
- * belt-and-suspenders. 🔴 Plaintext values are live secrets: memory-only, never log them.
- */
 export function createKeyResolver(modelApiKeyEnv, env = process.env, modelApiKeys = {}) {
     if (Object.keys(modelApiKeyEnv).length === 0 && Object.keys(modelApiKeys).length === 0)
         return undefined;

package/dist/leader/wire.d.ts

@@ -115,7 +115,6 @@ export declare function stageWorkerEnv(env: WireEnv, opts: {
     uploadScriptPath: string;
     uploadScript: string;
 }): Promise<void>;
-/** Build the `runLeader(body)` the HTTP endpoint invokes. Constructs real per-task deps + runs the leader. */
 /**
  * Per-leader-run resource bounds derived from env (2026-06-14). Exported for unit tests. The worker sandbox
  * lifetime (BUG2), the worker's diff-upload presigned-URL TTL (BUG1), and the worker spec's triple bound
@@ -140,6 +139,25 @@ export declare function leaderResourceConfig(env?: NodeJS.ProcessEnv): {
         maxSuspends: number;
     };
 };
+/** Repair/conflict/replan-loop knobs derived from env + optional `LeaderWireConfig` fallbacks (`repairRounds`/
+ *  `conflictRounds` land in cfg when the caller wires them programmatically instead of via env). Split out of
+ *  `createLeaderRunner`'s closure so it's a plain, unit-testable data constructor. */
+export interface LeaderLoopConfig {
+    repairRounds: number;
+    repairBudgetUsd: number;
+    conflictRounds: number;
+    repairLoopOn: boolean;
+    measureGatesOn: boolean;
+    repairLoopAttempts: number;
+    oracleFlakyK: number;
+    /** replan-lite (design/68 §6) fan-out spend cap from LEADER_BUDGET_USD. Absent = replan-lite's own default
+     *  (unset env stays absent — existing contract untouched; see leaderLoopConfig doc below). */
+    replanBudgetUsd?: number;
+}
+export declare function leaderLoopConfig(cfg: {
+    repairRounds?: number;
+    conflictRounds?: number;
+}, env?: NodeJS.ProcessEnv): LeaderLoopConfig;
 export declare function createLeaderRunner(cfg: LeaderWireConfig): (body: LeaderRequestBody) => Promise<LeaderResult>;
 export {};
 //# sourceMappingURL=wire.d.ts.map

package/dist/leader/wire.js

@@ -98,6 +98,18 @@ export async function stageWorkerEnv(env, opts) {
         throw new Error(`upload-script staging failed: ${wr.error.message}`);
 }
 /** Build the `runLeader(body)` the HTTP endpoint invokes. Constructs real per-task deps + runs the leader. */
+// 🔴 review-batch(重构池②,2026-08-01):`parseNumOrFail` alone still lets a NEGATIVE value through — a negative
+// number is JS-truthy, so every `parseNumOrFail(...) || default` chain in this file passed it straight through
+// instead of falling back (LEADER_WORKER_MAX_TURNS=-5 ⇒ workerMaxTurns=-5, unchanged by any later `|| default`).
+// This is the one extra domain bound (A2: illegal input INCLUDING negatives must fail loud) layered on the same
+// shared parse primitive — not a second parser. `undefined` (unset) stays NaN (`NaN < 0` is false) so the
+// existing `|| default` fallback chains are untouched; only "non-numeric" and "negative" newly throw.
+function parseNumOrFailNonNegative(name, raw) {
+    const n = parseNumOrFail(name, raw);
+    if (n < 0)
+        throw new Error(`env ${name}=${n} must not be negative`);
+    return n;
+}
 /**
  * Per-leader-run resource bounds derived from env (2026-06-14). Exported for unit tests. The worker sandbox
  * lifetime (BUG2), the worker's diff-upload presigned-URL TTL (BUG1), and the worker spec's triple bound
@@ -111,13 +123,13 @@ export async function stageWorkerEnv(env, opts) {
 // ⇒ diff 上传预签名 URL 的暴露窗口一起放大。改走与 numEnv 同源的 parseNumOrFail:非法值当场报错。
 // 刻意**零行为变更**:`|| default` 保留,所以未设与显式 0 的既有语义一个没动。
 export function leaderResourceConfig(env = process.env) {
-    const leaderTimeoutMs = Math.max(600_000, Math.floor(parseNumOrFail("LEADER_TIMEOUT_MS", env.LEADER_TIMEOUT_MS) || 0) || 86_400_000); // default 24h (was 10min)
-    const workerMaxTurns = Math.floor(parseNumOrFail("LEADER_WORKER_MAX_TURNS", env.LEADER_WORKER_MAX_TURNS) || 0) || 10_000;
-    const workerBudgetUsd = (parseNumOrFail("LEADER_WORKER_BUDGET_USD", env.LEADER_WORKER_BUDGET_USD) || 0) || 100;
+    const leaderTimeoutMs = Math.max(600_000, Math.floor(parseNumOrFailNonNegative("LEADER_TIMEOUT_MS", env.LEADER_TIMEOUT_MS) || 0) || 86_400_000); // default 24h (was 10min)
+    const workerMaxTurns = Math.floor(parseNumOrFailNonNegative("LEADER_WORKER_MAX_TURNS", env.LEADER_WORKER_MAX_TURNS) || 0) || 10_000;
+    const workerBudgetUsd = (parseNumOrFailNonNegative("LEADER_WORKER_BUDGET_USD", env.LEADER_WORKER_BUDGET_USD) || 0) || 100;
     const resourceSuspendOn = String(env.LEADER_RESOURCE_SUSPEND ?? "").toLowerCase() === "true";
     // Per-slice window: a fraction of the total so a worker suspends+resumes several times across its budget
     // (default = total/4, min $1). Smaller window ⇒ more, shorter slices ⇒ progress saved more often.
-    const sliceMaxCostUsd = (parseNumOrFail("LEADER_WORKER_SLICE_BUDGET_USD", env.LEADER_WORKER_SLICE_BUDGET_USD) || 0) || Math.max(1, workerBudgetUsd / 4);
+    const sliceMaxCostUsd = (parseNumOrFailNonNegative("LEADER_WORKER_SLICE_BUDGET_USD", env.LEADER_WORKER_SLICE_BUDGET_USD) || 0) || Math.max(1, workerBudgetUsd / 4);
     return {
         leaderTimeoutMs,
         workerMaxTurns,
@@ -135,24 +147,41 @@ export function leaderResourceConfig(env = process.env) {
             : {}),
     };
 }
-export function createLeaderRunner(cfg) {
-    const W = cfg.workspace ?? "/home/user";
-    const repo = `${W}/repo`;
-    const ident = cfg.git ?? { name: "leader", email: "leader@local" };
-    const { leaderTimeoutMs, workerLimits, presignTtlSec, resourceSuspend: resourceCfg } = leaderResourceConfig();
-    const repairRounds = Math.max(0, Math.floor(Number(process.env.LEADER_REPAIR_ROUNDS ?? cfg.repairRounds ?? 0)) || 0);
-    const repairBudgetUsd = Number(process.env.LEADER_REPAIR_BUDGET_USD ?? "4") || 4;
-    const conflictRounds = Math.max(0, Math.floor(Number(process.env.LEADER_CONFLICT_ROUNDS ?? cfg.conflictRounds ?? 0)) || 0);
+// 🔴 review-batch(重构池②,2026-08-01): every knob below used to be a bare `Number(process.env.X ?? default)`
+// with ZERO fail-loud guard — worst case was `LEADER_BUDGET_USD="20usd"` silently becoming `budgetUsd: NaN`,
+// which makes the replan-lite budget gate's `spent > budgetUsd` comparison permanently `false` (the whole
+// gate goes dark, not "loose" — `NaN` compares false in every direction). Converged onto the same
+// `parseNumOrFailNonNegative` primitive leaderResourceConfig uses: non-numeric and negative now throw at
+// startup; `undefined`/explicit-`0` fallback semantics are byte-identical to before.
+export function leaderLoopConfig(cfg, env = process.env) {
+    const repairRounds = Math.max(0, Math.floor(env.LEADER_REPAIR_ROUNDS !== undefined
+        ? parseNumOrFailNonNegative("LEADER_REPAIR_ROUNDS", env.LEADER_REPAIR_ROUNDS)
+        : (cfg.repairRounds ?? 0)) || 0);
+    const repairBudgetUsd = parseNumOrFailNonNegative("LEADER_REPAIR_BUDGET_USD", env.LEADER_REPAIR_BUDGET_USD ?? "4") || 4;
+    const conflictRounds = Math.max(0, Math.floor(env.LEADER_CONFLICT_ROUNDS !== undefined
+        ? parseNumOrFailNonNegative("LEADER_CONFLICT_ROUNDS", env.LEADER_CONFLICT_ROUNDS)
+        : (cfg.conflictRounds ?? 0)) || 0);
     // ── LEADER-REPAIRLOOP-INTEGRATION §10 env knobs (FRESH hunk, §10.8 — mirrors LEADER_REPAIR_ROUNDS above) ──
     // Every flag default-OFF so the whole feature is inert until flipped on a canary (the default path is
     // byte-identical to today). `LEADER_REPAIR_LOOP` is the MASTER (gates the single-agent `runRepairLoop` dep);
     // `LEADER_MEASURE_GATES` gates the merge push-hold-on-signal + measure-drives-repair (§10.3/§10.4);
     // `LEADER_REPAIR_LOOP_ATTEMPTS` is the in-loop attempt ceiling (validated 2-3, default 2 — design/78 §5);
     // `LEADER_ORACLE_FLAKY_K` is the flaky-settle re-isolation count (default 2 — §10.1 / repair-oracle.ts).
-    const repairLoopOn = String(process.env.LEADER_REPAIR_LOOP ?? "").toLowerCase() === "true";
-    const measureGatesOn = String(process.env.LEADER_MEASURE_GATES ?? "").toLowerCase() === "true";
-    const repairLoopAttempts = Math.min(3, Math.max(2, Math.floor(Number(process.env.LEADER_REPAIR_LOOP_ATTEMPTS ?? "2")) || 2));
-    const oracleFlakyK = Math.max(1, Math.floor(Number(process.env.LEADER_ORACLE_FLAKY_K ?? "2")) || 2);
+    const repairLoopOn = String(env.LEADER_REPAIR_LOOP ?? "").toLowerCase() === "true";
+    const measureGatesOn = String(env.LEADER_MEASURE_GATES ?? "").toLowerCase() === "true";
+    const repairLoopAttempts = Math.min(3, Math.max(2, Math.floor(parseNumOrFailNonNegative("LEADER_REPAIR_LOOP_ATTEMPTS", env.LEADER_REPAIR_LOOP_ATTEMPTS ?? "2")) || 2));
+    const oracleFlakyK = Math.max(1, Math.floor(parseNumOrFailNonNegative("LEADER_ORACLE_FLAKY_K", env.LEADER_ORACLE_FLAKY_K ?? "2")) || 2);
+    return {
+        repairRounds, repairBudgetUsd, conflictRounds, repairLoopOn, measureGatesOn, repairLoopAttempts, oracleFlakyK,
+        ...(env.LEADER_BUDGET_USD ? { replanBudgetUsd: parseNumOrFailNonNegative("LEADER_BUDGET_USD", env.LEADER_BUDGET_USD) } : {}),
+    };
+}
+export function createLeaderRunner(cfg) {
+    const W = cfg.workspace ?? "/home/user";
+    const repo = `${W}/repo`;
+    const ident = cfg.git ?? { name: "leader", email: "leader@local" };
+    const { leaderTimeoutMs, workerLimits, presignTtlSec, resourceSuspend: resourceCfg } = leaderResourceConfig();
+    const { repairRounds, repairBudgetUsd, conflictRounds, repairLoopOn, measureGatesOn, repairLoopAttempts, oracleFlakyK, replanBudgetUsd, } = leaderLoopConfig({ repairRounds: cfg.repairRounds, conflictRounds: cfg.conflictRounds });
     // worker resource bounds (limits/maxCostUsd) + presign ttl are derived in leaderResourceConfig(), above.
     // Bounded integration-repair (search 2026-06-14): when the merged tree compiles-clean-but-fails, run a strong
     // agent WITH HANDS in the live merged sandbox to fix the cross-worker integration, then mergeBranches re-runs
@@ -590,8 +619,9 @@ export function createLeaderRunner(cfg) {
             // found live: task02b run5, porting workers + collapse-solo all 'run aborted' at the 600s default while
             // mid-gradle; the per-worker presign ttl below tracks the same knob).
             timeoutMs: leaderTimeoutMs, maxConcurrency: 4, // Semaphore cap; the planner emits ≤6 sub-tasks
-            // replan-lite (design/68 §6) always on in the wired leader; LEADER_BUDGET_USD bounds the fan-out spend.
-            replan: { ...(process.env.LEADER_BUDGET_USD ? { budgetUsd: Number(process.env.LEADER_BUDGET_USD) } : {}) },
+            // replan-lite (design/68 §6) always on in the wired leader; LEADER_BUDGET_USD bounds the fan-out spend
+            // (parsed + fail-loud-guarded in leaderLoopConfig(), above — see LEADER_BUDGET_USD review-batch note).
+            replan: { ...(replanBudgetUsd !== undefined ? { budgetUsd: replanBudgetUsd } : {}) },
             // LEADER-REPAIRLOOP-INTEGRATION §10.3 — the merge push-hold-on-signal (OFF unless LEADER_MEASURE_GATES). It
             // needs NO extra sandbox: `strongOracleSeeded` keys on whether a hidden held-out oracle was injected into the
             // integration sandbox (`injectOracles` runs `body.oracleFiles`), and the §10.3 hold combines it with the

package/dist/lsp/e2b-bridge.js

@@ -26,7 +26,16 @@ const TOKEN = process.env.LSP_TOKEN || '';
 const MAX = 50 * 1024 * 1024;
 const HEARTBEAT_MS = Number(process.env.LSP_HEARTBEAT_MS || 30000);
 const wss = new WebSocketServer({ host: '0.0.0.0', port: PORT });
+// A zero-listener 'error' on ANY EventEmitter throws and crashes the process (Node default). Without this, a
+// bind failure (e.g. EADDRINUSE — a second bridge start racing the same port) took down the WHOLE bridge
+// process, killing every language's LSP session in the sandbox, not just the one that failed to start (HRD-LSP-4).
+// Exit loud + explicit instead of an uncaught-exception dump so the failure is at least attributable.
+wss.on('error', (err) => { console.error('lsp-bridge wss error', err && err.message); process.exit(1); });
 wss.on('connection', (ws, req) => {
+  // Same zero-listener 'error' hazard as wss above, but per-connection: registered FIRST, before anything else
+  // touches this socket. Close (don't crash) — the heartbeat reaper's own ws.terminate() below is a routine
+  // source of a socket 'error' on an already-half-open connection (HRD-LSP-4).
+  ws.on('error', () => { try { ws.terminate(); } catch {} });
   const q = ((req && req.url) || '').split('?')[1] || '';
   if (TOKEN && new URLSearchParams(q).get('token') !== TOKEN) { ws.close(); return; } // auth (council #4)
   ws.isAlive = true;
@@ -37,7 +46,11 @@ wss.on('connection', (ws, req) => {
   const decode = makeFrameDecoder(MAX);
   child.stdout.on('data', (d) => { for (const f of decode(d)) ws.send(f); });
   ws.on('message', (data) => { const p = Buffer.from(data.toString(), 'utf8'); child.stdin.write('Content-Length: ' + p.length + '\r\n\r\n'); child.stdin.write(p); });
-  ws.on('close', () => child.kill());
+  // pid guard: the child 'error' handler above routes spawn FAILURES (missing binary — pid never assigned)
+  // through ws.close() → this 'close' handler. Killing a child whose pid was never assigned can signal the
+  // CALLER's process group instead of the (nonexistent) child (HRD-LSP-4; same hazard class as bake-runner's
+  // spawner, src/bake-runner/main.ts).
+  ws.on('close', () => { if (child.pid !== undefined) child.kill(); });
   child.on('exit', () => { try { ws.close(); } catch {} });
 });
 // Reap half-open connections: the E2B proxy kills a WS at ~60-75s and the kill can be SILENT on THIS side too —

package/dist/lsp/e2b-manager.d.ts

@@ -8,9 +8,11 @@ export interface E2bLspOptions {
         attempts: number;
         delayMs: number;
     };
-    /** Bridge auth token override. The manager pins ONE token per env+language: on a RE-open (transport heal
-     *  after the E2B proxy idle-killed the WS) the original bridge process is still listening with the FIRST
-     *  token — a fresh random token would be rejected and the reconnect would always fail. */
+    /** Bridge auth token override. The manager pins ONE token per env+PORT — the bridge RESOURCE, not the
+     *  language (`portForLanguage` maps several languages, e.g. typescript/javascript, onto the SAME port/process
+     *  — see `createE2bLspManager`). On a RE-open (transport heal after the E2B proxy idle-killed the WS) the
+     *  original bridge process is still listening with the FIRST token — a fresh random token would be rejected
+     *  and the reconnect would always fail. */
     token?: string;
     /** WS scheme for the bridge URL. E2B's `getHost` returns a public TLS proxy host → `wss` (default);
      *  the k8s adapter returns a cluster-internal `podIP:port` → plain `ws` (no TLS on the pod network;
@@ -19,7 +21,9 @@ export interface E2bLspOptions {
     /** Observability hook (open/heal/degrade events) — prod wires the service logger. */
     log?: (event: string, fields: Record<string, unknown>) => void;
 }
-/** Start (+ install on a non-baked template) the language server + bridge inside THIS env's sandbox, then connect. */
+/** Start (+ install on a non-baked template) the language server + bridge inside THIS env's sandbox, then connect.
+ *  Every call starts (or re-starts) the bridge unconditionally — the one production caller is
+ *  `createE2bLspManager`, which de-dupes per env+port before ever reaching here (see its doc). */
 export declare function openE2bLspTransport(language: string, env: LspCapableEnv, opts?: E2bLspOptions): Promise<LspTransport | undefined>;
 /** The single shared `LspServerManager` for the deployment (`RunnerDeps.lspManager`). */
 export declare function createE2bLspManager(opts?: E2bLspOptions): E2bLspManager;