@sema-agent/server 3.20.0 → 3.22.0

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

@@ -10,6 +10,7 @@ import { scopedIdempotencyKey } from "../idempotency.js";
 import { streamSseLog } from "../sse-log.js";
 import { normalizeRunEventType } from "../../trace/project.js";
 import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
+import { buildActiveRunConflict } from "../active-run-conflict.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 // server.ts 侧的 routeLabel / isBillableSubmitPath 仍要用下面这些正则,故本模块导出(方向恒为 server.ts → routes/*)。
 export const RUN_ID_RE = /^\/v1\/runs\/([^/]+)(\/events)?$/;
@@ -161,7 +162,8 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 if (clientTaskId && created.activeTaskId === clientTaskId) {
                     return { status: 202, body: { taskId: clientTaskId, sessionId, status: "running" } };
                 }
-                return { status: 409, body: { error: "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)", errorCode: "conflict.session_active_run", activeTaskId: created.activeTaskId } };
+                // [2255]① 真出路材料:activeTaskStatus + parked 时 pendingGate{kind,decidePath}(best-effort,失败退旧形)
+                return { status: 409, body: await buildActiveRunConflict({ runStore, checkpointStore: deps.checkpointStore }, sessionId, created.activeTaskId) };
             }
             // Durable F4: persist the resume rebuild inputs (sessionId-keyed) so an operator can resume from any
             // replica even after this worker is gone — core's checkpoint blob can't carry service scenario context.

package/dist/http/routes/tasks.js

@@ -10,6 +10,7 @@ import { turnEndEventData, contextUsageEventData, toolStartEventData, toolEndEve
 import { cascadeConfig, runMeta } from "../run-meta.js";
 import { scopedIdempotencyKey } from "../idempotency.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
+import { buildActiveRunConflict, toDoneFrameResult } from "../active-run-conflict.js";
 import { headerStr, gatedPrincipal } from "../principal-gate.js";
 export async function handleTasks(req, res, url, ctx) {
     const miss = { fell: false };
@@ -216,10 +217,11 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                     if (created.ok)
                         deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective, typeof prepared.spec.model === "string" ? prepared.spec.model : prepared.spec.model?.id); // fire-and-forget; in-titler dedupe;model 跟 turn([1992]②)
                     if (!created.ok) {
-                        const conflict = { error: "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)", errorCode: "conflict.session_active_run", activeTaskId: created.activeTaskId };
+                        const conflict = await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore }, prepared.spec.sessionId, created.activeTaskId); // [2255]① 真出路材料
                         // Headers are already SSE — encode the rejection as the stream's terminal event; the 409 in
                         // the returned resp is for a deduplicated concurrent caller (and is never idem-cached).
-                        res.write(`data: ${JSON.stringify({ type: "done", result: { status: "failed", errorMessage: conflict.error, activeTaskId: conflict.activeTaskId } })}\n\n`);
+                        // done 帧 additive 携带同一份材料 —— 形状铸在 toDoneFrameResult(有名字有类型),不在这行内联挑键。
+                        res.write(`data: ${JSON.stringify({ type: "done", result: toDoneFrameResult(conflict) })}\n\n`);
                         return { status: 409, body: conflict };
                     }
                     durableTaskId = tid;
@@ -971,7 +973,7 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                     const tid = uuidv7();
                     const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", runMeta(prepared, source));
                     if (!created.ok)
-                        return { status: 409, body: { error: "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)", errorCode: "conflict.session_active_run", activeTaskId: created.activeTaskId } };
+                        return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore }, prepared.spec.sessionId, created.activeTaskId) }; // [2255]① 真出路材料
                     deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective, typeof prepared.spec.model === "string" ? prepared.spec.model : prepared.spec.model?.id); // fire-and-forget;model 跟 turn([1992]②)
                     durableTaskId = tid;
                 }

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;

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/main.js

@@ -24,7 +24,7 @@ import { createRegistryJwtVerifier } from "./auth-bridge.js";
 import { createMetrics } from "./observability/metrics.js";
 import { setRedactionObserver, redactSecrets } from "./trace/redact.js";
 import { RateLimiter } from "./observability/rate-limit.js";
-import { createHttpServer, explicitOperator } from "./http/server.js";
+import { createHttpServer, explicitOperatorOk } from "./http/server.js";
 import { exportMemoryScope } from "./memory-export.js";
 import { performMemorySync } from "./memory-sync.js";
 import { startOtlpExporter } from "./observability/otel-exporter.js";
@@ -421,7 +421,7 @@ async function main() {
         ? selectEnvironmentTool({
             catalog: imageIndex,
             selection: sessionEnvSelection,
-            viewerFor: (principal) => ({ operator: explicitOperator(principal, config.operatorPrincipals), tenantId: principal ?? null }),
+            viewerFor: (principal) => ({ operator: explicitOperatorOk(principal, config.operatorPrincipals), tenantId: principal ?? null }),
         })
         : undefined;
     // Sandbox-image-pool BAKE control plane (IMAGE-API-DESIGN.md §P2): enables /v1/images/bakes* when a pool exists

package/dist/parked-decide.js

@@ -135,7 +135,10 @@ export async function decideParkedAgent(deps, req) {
         boundInputHash: req.binding?.boundInputHash ?? persistedHash,
         decision: req.decision === "approve" ? "allow" : "deny",
         ...(req.decision === "approve" && req.binding?.updatedInput !== undefined ? { updatedInput: req.binding.updatedInput } : {}),
-        ...(req.reason ? { reason: req.reason } : {}),
+        // B10:存在性判定,不是真值判定 —— reason 可以是空串("运维显式选择不写理由"),这与"没传 reason"
+        // 是两件不同的事(姊妹 approval-hmac.ts `env.reason ?? null` 同判据:`??` 只在 null/undefined 时落
+        // null,空串照样入签名载荷)。真值判定会把显式 "" 与缺席折成同一个结果,审计/签名面丢了这个区分。
+        ...(req.reason !== undefined ? { reason: req.reason } : {}),
     };
     const ctx = {
         toolCallId: `drv-${ticket.claimId}`,

package/dist/plugins/file-run-store.js

@@ -293,8 +293,17 @@ export class FileRunStore {
      *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
     async setTerminal(taskId, status, result, error) {
         const r = this.runs.get(taskId);
-        if (!r)
+        if (!r) {
+            // [2255]③ claim 孤儿修:行不在(跨进程窗 —— claim 落盘、行未落/已失;R9 只兜同进程写失败)时,
+            // 终局动词仍必须能放锁:cancel 是文案承诺的用户自救路,它对孤儿失效=会话钉死到 reaper/boot。
+            // 反查 active 索引找持有该 taskId 的 session(O(claims),claims 数=活跃会话数,小)。
+            for (const [sessionId, tid] of this.active)
+                if (tid === taskId) {
+                    this.releaseClaim(sessionId);
+                    break;
+                }
             return;
+        }
         if (r.status === "running" || r.status === "suspended" || r.status === "needs_review") {
             r.status = status;
             r.result = result;
@@ -354,9 +363,9 @@ export class FileRunStore {
         const cursorAt = opts.cursor ? Date.parse(opts.cursor.createdAt) : undefined;
         const rows = [...this.runs.values()]
             .filter((r) => (opts.status ? r.status === opts.status : true))
-            .filter((r) => (opts.jobId ? r.jobId === opts.jobId : true))
-            .filter((r) => (opts.source ? r.source === opts.source : true))
-            .filter((r) => (opts.owner ? r.owner === opts.owner : true)) // exact (SQL `owner = ?`): a set owner excludes null-owner rows
+            .filter((r) => (opts.jobId !== undefined ? r.jobId === opts.jobId : true)) // "" is a valid exact jobId, not "no filter" (B10)
+            .filter((r) => (opts.source !== undefined ? r.source === opts.source : true)) // "" is a valid exact source, not "no filter" (B10)
+            .filter((r) => (opts.owner !== undefined ? r.owner === opts.owner : true)) // exact (SQL `owner = ?`): "" is a valid exact owner, not "no filter" (B10)
             .filter((r) => {
             if (cursorAt === undefined)
                 return true;
@@ -370,8 +379,8 @@ export class FileRunStore {
     async listSessions(opts) {
         const bySession = new Map();
         for (const r of this.runs.values()) {
-            if (opts.owner && r.owner !== opts.owner)
-                continue; // exact owner filter (SQL `owner = ?`)
+            if (opts.owner !== undefined && r.owner !== opts.owner)
+                continue; // exact owner filter (SQL `owner = ?`); "" is a valid exact owner (B10)
             const arr = bySession.get(r.sessionId) ?? [];
             arr.push(r);
             bySession.set(r.sessionId, arr);
@@ -535,8 +544,10 @@ export class FileRunStore {
      */
     async reapSuspended(olderThanMs) {
         const probe = this.checkpointProbe;
-        if (!probe)
+        if (!probe) {
+            this.sweepClaims();
             return 0;
+        } // [2255]③:时间腿无 probe=诚实 NO-OP,但 claim 不变式维护不跟 probe 走
         const cutoff = Date.now() - olderThanMs;
         let reaped = 0;
         for (const r of this.runs.values()) {
@@ -566,8 +577,10 @@ export class FileRunStore {
      */
     async failSuspendedWithExpiredCheckpoint() {
         const probe = this.checkpointProbe;
-        if (!probe)
+        if (!probe) {
+            this.sweepClaims();
             return 0;
+        } // [2255]③ 同上
         let reaped = 0;
         for (const r of this.runs.values()) {
             if (r.status !== "suspended" && r.status !== "needs_review")

package/dist/plugins/host-platform.d.ts

@@ -1,27 +1,3 @@
-/**
- * Host-lane PLATFORM seam (DESIGN-windows-native.md, FINAL r3) — the ONE place the host exec adapter's
- * POSIX/win32 differences live, so `remote-env-host.ts` stays a single code path with platform-gated leaves.
- *
- * 🔴 Iron invariant (design §4.1): the POSIX path is BYTE-IDENTICAL to the pre-Windows code — every helper is
- * `win32 ? new : exactly-what-the-inline-code-did` (same syscall, same throw behavior). Never "improve" POSIX
- * here; the existing full test suite is the regression net.
- *
- * win32 semantics (design D1-D4):
- *  - shell   = Git Bash via core 1.224 `getShellConfig` (WSL-launcher-filtered — the `System32\bash.exe`
- *              trap). Fail-LOUD when absent; never silently degrade to cmd (D1).
- *  - kill    = core 1.224 `signalProcessTree` (taskkill /T, /F for hard). Soft is a no-op for console trees
- *              (taskkill errors "can only be terminated forcefully") — the SIGTERM→grace→SIGKILL ladder is
- *              effectively delay→hard-kill on win32; accepted, CC-identical (D2).
- *  - spawn   = `detached:false` + `windowsHide:true` (no console window; no POSIX process group — the kill
- *              side uses the tree, not the group) (D3).
- *  - env     = case-insensitive key collapse before spawn (win32 env keys are case-insensitive; a `Path`+`PATH`
- *              pair from case-sensitive Object.assign reaches CreateProcess as ONE undefined-which
- *              entry). Canonical casing = the first-seen key (process.env's native casing wins since the
- *              inherit base is spread first).
- *
- * ⚠️ The win32 branches are UNVERIFIED on a real machine until S5 (Windows CI runner) — design D5 discipline:
- * structural tests only on mac/Linux; behavior-level bite happens on the first Windows-runner green.
- */
 import { killProcessTree } from "@sema-agent/core";
 export declare const IS_WIN32: boolean;
 export interface HostShell {
@@ -82,6 +58,17 @@ export { killProcessTree };
  * POSIX: returns the input UNTOUCHED (case-sensitive env is real there — `Path` and `PATH` are distinct).
  */
 export declare function collapseWin32EnvKeys(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Conventional exit-code mapping for a process killed by a signal (128 + signal number). Single pattern-home
+ * construction point for every exec adapter that must turn a `close` event's external-kill case
+ * (`code===null`, `signal` set) into an exit code instead of silently reporting a fake success 0 — the host
+ * lane, ssh, adb, and local-docker all consume THIS function; none of them may hand-write their own signal
+ * table. Uses Node's authoritative platform table (`os.constants.signals`) rather than a hand-written list —
+ * a hand-written table has previously missed `SIGABRT`/`SIGPIPE` (`kill -ABRT` reported 137, impersonating
+ * `SIGKILL`). Callers keep a `?? 9` fallback for a name the platform table doesn't define, matching core's
+ * `SIGNUM[signal] ?? 9`.
+ */
+export declare function signalNumber(signal: NodeJS.Signals): number | undefined;
 /** The platform-free collapse algorithm (exported so the mac/Linux suite can pin the win32 behavior — design
  *  D5: structural verification everywhere, behavioral bite on the Windows runner). */
 export declare function collapseEnvKeysCaseInsensitive(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;