@sema-agent/server 3.21.0 → 3.22.0

package/dist/approval-hmac.d.ts

@@ -30,13 +30,19 @@ import type { ApprovalHmacKey } from "./auth-keys.js";
  * 之所以到今天才把规则写死:此前四个字段全是**受限字母表**(uuid / 调用 id / 十六进制 / 枚举),转义怎么
  * 写都一样、规则不写也测不出来;`reason` 是第一个进入签名载荷的自由文本,转义从"无所谓"变成"承重"。
  */
-export declare function approvalHmacMessage(env: {
+/** The canonical 5-field envelope both {@link approvalHmacMessage} (the signer's/verifier's shared byte-rule) and
+ *  {@link verifyApprovalHmac} take — ONE named type so the two signatures cannot silently drift into two
+ *  structurally-similar-but-not-identical inline shapes (drift there would only surface at RUNTIME as a MAC
+ *  mismatch, never at compile time — see the file-header canonical-message note for why each field's presence
+ *  is load-bearing). */
+export interface ApprovalEnvelope {
     sessionId: string;
     boundCallId?: string | null;
     boundInputHash?: string | null;
     decision: string;
     reason?: string | null;
-}): string;
+}
+export declare function approvalHmacMessage(env: ApprovalEnvelope): string;
 /** 签名载荷里 `reason` 的字符上限。**拒**而不是截 —— 截断在这条路径上**结构上不可行**:服务端截过的字节
  *  与签名方签的字节必然不同,MAC 恒不匹配,"截断"只会把一个可诊断的 413 变成一个费解的 401。
  *  取 4096 与本仓既有的人写文本上限同档(`MAX_ELICIT_MESSAGE_CHARS` / `MAX_AGENT_TEXT_CHARS`)。 */
@@ -47,11 +53,5 @@ export declare const MAX_APPROVAL_REASON_CHARS = 4096;
  * signed with a key being rotated out still verifies during the overlap). `timingSafeEqual` avoids a timing
  * oracle. An empty key-set ⇒ false (caller decides whether absence = skip-because-inactive or fail-closed).
  */
-export declare function verifyApprovalHmac(env: {
-    sessionId: string;
-    boundCallId?: string | null;
-    boundInputHash?: string | null;
-    decision: string;
-    reason?: string | null;
-}, mac: string, kid: string | undefined, keys: ApprovalHmacKey[]): boolean;
+export declare function verifyApprovalHmac(env: ApprovalEnvelope, mac: string, kid: string | undefined, keys: ApprovalHmacKey[]): boolean;
 //# sourceMappingURL=approval-hmac.d.ts.map

package/dist/approval-hmac.js

@@ -25,37 +25,6 @@
  * already-resolved token → the resolve CAS fails already_resolved), so no separate replay cache is needed.
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
-/**
- * The canonical message an approval MAC signs — a fixed-order, JSON-escaped tuple so no field value (an id, a
- * hash, a free-text note) can ambiguate the boundary with the next (same discipline as the approvals-stream diff
- * key). 🔴 Bound to CLIENT-VISIBLE values only: `sessionId` (in the /decide URL) + `boundCallId`/`boundInputHash`
- * (surfaced by listPending) + `reason` (the caller's own body). It must NOT include the checkpointToken — that is
- * the unexposed resume credential the client can never see (it resumes by sessionId), so a checkpointToken-bound
- * message would be uncomputable by the signer.
- *
- * ── `reason` 入签(三方裁 (a):cli [1797] / core [1801]§四 / server;clay「干净切」令 [1802])─────────────
- * `reason` 是随决定落账的自由文本(审计面的一部分)。它此前**在信封之外** ⇒ 能改线上字节的一方(反代 /
- * 被劫持的客户端 —— 正是 HMAC 要防的威胁模型)可以在操作员批准同一个动作的那次决定里,把落账理由换成
- * 别的:动作没变,**审计记录变了**。三方裁定纳入签名载荷,不留 `reasonUnsigned` 宽限代际(未上生产)。
- *
- * ── 🔴 字节构造规则(权威定义;跨仓签名器照此实现,docs/ASSISTANT-WIRE-CONTRACT.md §6.2 同源)──────────
- * 被 HMAC 的是下面这个字符串的 **UTF-8 字节**:
- *   1. **恒 5 元素、定序**的紧凑 JSON 数组(元素间**无空格**):
- *      `[sessionId, boundCallId|null, boundInputHash|null, decision, reason|null]`
- *      —— 恒定长度是刻意的:签名器里少一个"有 reason 才追加"的条件分支,就少一类跨实现漂移。
- *   2. 缺席 ⇒ `null`;**`""`(空串)是与 `null` 不同的被签值**(否则"把理由抹成空"不改变 MAC)。
- *   3. 字符串转义 = RFC 8259 最小集:`"`→`\"`、`\`→`\\`、U+0000–U+001F → `\n`/`\t`/`\uXXXX`。
- *   4. **非 ASCII 原样输出 UTF-8,不转 `\uXXXX`**。⚠️ Python 的 `json.dumps` 缺省 `ensure_ascii=True` 会踩
- *      —— 必须 `json.dumps(t, ensure_ascii=False, separators=(",", ":"))`。
- *   5. **`<` `>` `&` 不转义**。⚠️ Go 的 `json.Marshal` 缺省 HTML 转义会踩 —— 必须
- *      `enc := json.NewEncoder(w); enc.SetEscapeHTML(false)`(并去掉它追加的换行)。
- *   6. 孤代理项按 ES2019 well-formed 语义转成 `\udXXX`(JS 原生行为,其它语言按同规则)。
- *   7. MAC = HMAC-SHA256(上述字节),**小写十六进制**上 wire。
- * 逐字节黄金向量(含中文/引号/换行/制表/`<`/`&`/emoji)钉在 `test/approval-hmac.test.ts`,签名器对拍用。
- *
- * 之所以到今天才把规则写死:此前四个字段全是**受限字母表**(uuid / 调用 id / 十六进制 / 枚举),转义怎么
- * 写都一样、规则不写也测不出来;`reason` 是第一个进入签名载荷的自由文本,转义从"无所谓"变成"承重"。
- */
 export function approvalHmacMessage(env) {
     return JSON.stringify([env.sessionId, env.boundCallId ?? null, env.boundInputHash ?? null, env.decision, env.reason ?? null]);
 }

package/dist/approval.js

@@ -8,6 +8,8 @@
  * dropped at the task deadline instead of holding the worker — design/06 F4 self-protection.
  */
 import { createApprovalPolicy, canonicalToolName, uuidv7 } from "@sema-agent/core";
+import { createLogger } from "./observability/logger.js";
+const logger = createLogger();
 /**
  * 运维**是否表达了门意图** —— boot 的单用户 allow-all 基线只在"零门意图"时才允许铺开,
  * 所以这个谓词漏一格 = 那一格的意图被 allow-all 静默吞掉。
@@ -170,7 +172,12 @@ export async function waitForDecision(store, id, scope, signal, pollMs) {
     let consecutiveErrors = 0;
     for (;;) {
         if (signal?.aborted) {
-            await store.decide(id, scope, "expired", "task aborted before decision", null).catch(() => undefined);
+            // C1(failloud):最小对症=失败留痕,不必重试——这是最后一次尝试把行标 expired,任务本身已经在
+            // abort 路径上收尾,重试没有下一个时机。裸吞会让一次真实的店写故障(TiDB blip)在观测面上
+            // 与"成功标了 expired"毫无区别;补 error 留痕,行为(deny)不变。
+            await store.decide(id, scope, "expired", "task aborted before decision", null).catch((e) => {
+                logger.error("approval_expire_write_failed", { id, scope, err: e instanceof Error ? e.message : String(e) });
+            });
             return false;
         }
         let s;

package/dist/boot/config-center.d.ts

@@ -1,9 +1,10 @@
-import { CenterPromptSource, type Model } from "@sema-agent/core";
+import { CenterPromptSource } from "@sema-agent/core";
 import { buildPricing } from "../budget.js";
 import { type PromptsDomainFaces } from "../capabilities/center-prompts.js";
 import { type Scenario, type ScenarioDeps, type ScenarioDetail } from "../capabilities/scenarios.js";
 import type { LoadedSkill } from "../capabilities/skills.js";
 import { type ServiceConfig } from "../config.js";
+import { type ModelKeyRef } from "../key-resolver.js";
 import type { Logger } from "../observability/logger.js";
 import type { Metrics } from "../observability/metrics.js";
 import { type RestartSignal } from "../config-center/facade.js";
@@ -42,7 +43,7 @@ export interface ConfigCenterRuntime {
         pricing: ReturnType<typeof buildPricing>;
     }): void;
     /** 晚绑取值:refresh 热应用会整个换引用(hook LLM / resolveSpec 每次现取)。 */
-    getKeyResolver(): ((model: Model) => Promise<{
+    getKeyResolver(): ((model: ModelKeyRef) => Promise<{
         apiKey: string;
     } | undefined>) | undefined;
     /** 晚绑取值:center 提示词面(热采用,新任务边界生效)。 */

package/dist/boot/resolve-spec.js

@@ -30,7 +30,7 @@ import { applyLongtailDefer } from "../capabilities/tool-defer.js";
 import { acceptShellScratchpadDir, buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, resumeFactsForLane } from "../env-facts.js";
 import { FleetEventBus } from "../fleet/fleet-bus.js";
 import { composeHooks, createTaskHooks } from "../hooks/hook-runner.js";
-import { explicitOperator } from "../http/server.js";
+import { explicitOperatorOk } from "../http/server.js";
 import { matchCatalogModel, modelSupportsImages, resolveTaskModel } from "../model-select.js";
 import { PerTaskImageRegistry, resolveSandboxImageRef } from "../per-task-image.js";
 import { isRemoteScratchpadLane, remoteScratchpadDirFor } from "../plugins/remote-scratchpad.js";
@@ -533,7 +533,7 @@ export function createResolveSpec(ctx) {
             // design/131 (core 1.246): per-task resilience INTENT flags. allowDegrade/allowFailover are
             // caller-facing (a bench/eval run wants true failure shapes); bypassBreaker is operator-only (normalizer
             // drops it for non-operators — it punches through a SHARED breaker). All-absent = byte-compat.
-            resilience: normalizeResilience(body.resilience, explicitOperator(auth?.principal, config.operatorPrincipals)),
+            resilience: normalizeResilience(body.resilience, explicitOperatorOk(auth?.principal, config.operatorPrincipals)),
             // design/132 (core 1.249): one-shot end-game verification nudge ("re-run the final artifact through
             // its real entrypoint before finishing"). OPT-IN by core's own judgment (default ON lost the evidence case:
             // +1 turn on every interactive write task) — the AUTONOMY caller declares it (harness/scheduler lanes).
@@ -962,11 +962,11 @@ export function createResolveSpec(ctx) {
                 profile: taskImageProfile,
                 ...(capsNeeded && capsNeeded.length > 0 ? { capabilitiesNeeded: capsNeeded } : {}),
                 // principal comes from the auth channel (trusted header / verified JWT), NEVER the body — so a caller
-                // cannot widen its own visibility. explicitOperator (NOT isOperator): an empty OPERATOR_PRINCIPALS must
+                // cannot widen its own visibility. explicitOperatorOk (NOT isOperator): an empty OPERATOR_PRINCIPALS must
                 // yield operator=false here — isOperator([],p)=true-for-all would let any caller resolve tenant-scoped
                 // images on an operator-less deployment (adversarial-review HIGH-1; the bake/direct-door boot guards do
                 // NOT cover per-task image selection).
-                viewer: { operator: explicitOperator(auth.principal, config.operatorPrincipals), tenantId: auth.principal ?? null },
+                viewer: { operator: explicitOperatorOk(auth.principal, config.operatorPrincipals), tenantId: auth.principal ?? null },
                 index: imageIndex,
             });
             if (!resolved.ok)

package/dist/boot/session-faces.js

@@ -63,8 +63,9 @@ export function createSessionFaces(ctx) {
         })
         : undefined;
     // S2 fast path([1208]③ 兑现):同副本 append 落点(tidb/pg persist post-commit)经 leaf-bus 直推
-    // notifyLocal——单副本部署零延迟;owner 不随 bus 传(写点无廉价 owner 读),探针围栏仍是租户权威
-    // (session-leaf-bus 契约注)。local lane 无写钩,探针道照旧。
+    // notifyLocal——单副本部署零延迟;owner 随 bus 传(commit-time row owner,session-leaf-bus 头注契约:
+    // "Owner IS carried"),notifyLocal 据此做 generation 围栏(旧 A 世代不会假匹配新租户的叶子)。
+    // local lane 无写钩,探针道照旧。
     setLeafAdvanceListener(sessionWatchRegistry ? (sid, leaf, owner, seq) => sessionWatchRegistry.notifyLocal(sid, leaf, owner, seq) : undefined);
     const purgeSession = ownerAware.deleteSession
         ? async (sessionId, owner) => {

package/dist/boot/workflow-orchestration.js

@@ -33,7 +33,7 @@ export function createWorkflowOrchestration(ctx) {
     // present — a failover-landed session sees the run's history + its pending completion push on ANY replica.
     // Explicit WORKFLOW_RUN_STORE=file/memory still wins (single-box File posture unchanged: local backend has
     // no workflowRun() so auto falls to File there).
-    const sqlWorkflowRunStore = config.workflowRunStoreBackend === "auto" ? backend?.workflowRun?.() : undefined;
+    const sqlWorkflowRunStore = config.workflowRunStoreBackend === "auto" ? backend?.workflowRun?.((msg, meta) => logger.warn(msg, meta)) : undefined; // C5: oversize-slim 留痕接 logger(completionInbox :82 同款)
     const baseWorkflowRunStore = config.selfOrchestrationEnabled
         ? config.workflowRunStoreBackend === "memory"
             ? new InMemoryWorkflowRunStore()

package/dist/budget.d.ts

@@ -83,7 +83,7 @@ export { type PromptManifestRecord, promptManifestRecordOf, configAssembledRecor
  * fires for EVERY call (top-level + async + council sub-tasks) → `model_cost_micro_usd_total` is the authoritative
  * spend, and (when a {@link ModelUsageTracker} is supplied) the per-task `modelUsage` echo's source.
  */
-export declare function createTracer(metrics: Pick<Metrics, "inc" | "observe">, costQuota?: QuotaTracker, modelUsage?: ModelUsageTracker, fleetUsage?: FleetUsageAccumulator, fleetLease?: FleetLeaseManager, quotaWeightFor?: (model: string) => number, promptManifests?: PromptManifestTracker): TracerHook;
+export declare function createTracer(metrics: Pick<Metrics, "inc" | "observe">, costQuota?: QuotaTracker, modelUsage?: ModelUsageTracker, fleetUsage?: Pick<FleetUsageAccumulator, "record">, fleetLease?: Pick<FleetLeaseManager, "recordSpend">, quotaWeightFor?: (model: string) => number, promptManifests?: PromptManifestTracker): TracerHook;
 /**
  * [1469] side-query 记账 seam(codex R3 high:sideQuery 不走 core tracer——brain.stream 直调不发
  * brain.call——createTracer 的四路 sink(costQuota/model_cost 指标/fleetUsage 批报/fleetLease 本地扣减)
@@ -106,7 +106,7 @@ export declare function cacheFamilyOfMirror(model: {
         promptCacheFamily?: string;
     };
 } | undefined): "input-includes-cached" | "input-excludes-cached" | undefined;
-export declare function createSideQueryAccountant(metrics: Pick<Metrics, "inc">, costQuota?: QuotaTracker, fleetUsage?: FleetUsageAccumulator, fleetLease?: FleetLeaseManager, quotaWeightFor?: (model: string) => number): (principal: string | undefined, r: {
+export declare function createSideQueryAccountant(metrics: Pick<Metrics, "inc">, costQuota?: QuotaTracker, fleetUsage?: Pick<FleetUsageAccumulator, "record">, fleetLease?: Pick<FleetLeaseManager, "recordSpend">, quotaWeightFor?: (model: string) => number): (principal: string | undefined, r: {
     model: string;
     family?: "input-includes-cached" | "input-excludes-cached";
     usage?: {

package/dist/budget.js

@@ -320,7 +320,9 @@ export function cacheFamilyOfMirror(model) {
         return "input-includes-cached";
     return model.api === "anthropic-messages" || model.api === "bedrock-converse-stream" ? "input-excludes-cached" : "input-includes-cached";
 }
-export function createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetLease, quotaWeightFor) {
+export function createSideQueryAccountant(metrics, costQuota, 
+// 依赖面收窄到真消费的方法(§X 同 ModelKeyRef 一式):全形对象照传(结构超集),测试桩零铸型。
+fleetUsage, fleetLease, quotaWeightFor) {
     return (principal, r) => {
         const input = typeof r.usage?.input === "number" ? r.usage.input : 0;
         const output = typeof r.usage?.output === "number" ? r.usage.output : 0;
@@ -331,8 +333,11 @@ export function createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetL
         // 大幅少收(lease 可被 cache-heavy side query 绕穿)。family 未知(catalog 查不到)走**保守臂**
         // (含 cache——OpenAI 族此臂多收,方向与 cost 残差一致:宁多勿少,记档同一条)。
         const promptTokens = r.family === "input-includes-cached" ? input : input + cacheRead + cacheWrite;
-        const micro = Math.round((typeof r.usage?.cost?.total === "number" ? r.usage.cost.total : 0) * 1_000_000);
-        if (micro > 0) {
+        // RB-368/#59 同判据(createTracer 上方注释同款纪律):`usage.cost.total` 整键缺席 = 未知(unpriced 部署的
+        // side query 真形),不是「花了 $0」——折 0 就是把「不知道」编造成「免费」。已知(哪怕显式 0)才带键。
+        const costTotal = typeof r.usage?.cost?.total === "number" ? r.usage.cost.total : undefined;
+        const micro = costTotal !== undefined ? Math.round(costTotal * 1_000_000) : undefined;
+        if (micro !== undefined && micro > 0) {
             metrics.inc("model_cost_micro_usd_total", { model: r.model }, micro);
             if (principal)
                 costQuota?.add(principal, micro);
@@ -340,9 +345,9 @@ export function createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetL
         const qwRaw = quotaWeightFor?.(r.model);
         const qw = typeof qwRaw === "number" && Number.isFinite(qwRaw) && qwRaw > 0 ? qwRaw : 1;
         const weightedTokens = Math.round((promptTokens + output) * qw);
-        if (weightedTokens > 0 || micro > 0) {
-            fleetUsage?.record(principal, r.model, "", { inputTokens: promptTokens, outputTokens: output, costMicroUsd: micro, weightedTokens, quotaWeightAtUse: qw }); // taskId ""(无 run 语义;accumulator 对 "" 不计 runsSeen);inputTokens=归一化总输入含 cache(fleet-bus 同口径)
-            fleetLease?.recordSpend(principal, { weightedTokens, costMicroUsd: micro });
+        if (weightedTokens > 0 || (micro !== undefined && micro > 0)) {
+            fleetUsage?.record(principal, r.model, "", { inputTokens: promptTokens, outputTokens: output, ...(micro !== undefined ? { costMicroUsd: micro } : {}), weightedTokens, quotaWeightAtUse: qw }); // taskId ""(无 run 语义;accumulator 对 "" 不计 runsSeen);inputTokens=归一化总输入含 cache(fleet-bus 同口径);RB-368 透传缺席
+            fleetLease?.recordSpend(principal, { weightedTokens, ...(micro !== undefined ? { costMicroUsd: micro } : {}) }); // RB-368 透传缺席
         }
     };
 }

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

@@ -1,4 +1,4 @@
-import type { Model } from "@sema-agent/core";
+import type { ModelKeyRef } from "../key-resolver.js";
 import type { ServiceConfig } from "../config-types.js";
 import type { HookLlmCall } from "./hook-runner.js";
 /**
@@ -32,7 +32,7 @@ export interface HookLlm {
 export declare function createHookLlm(deps: {
     config: ServiceConfig;
     /** 与 brain 同一 hot-refreshed per-model key 面(main.ts 热应用会整个换引用,故取函数不取值)。 */
-    getKeyResolver: () => ((model: Model) => Promise<{
+    getKeyResolver: () => ((model: ModelKeyRef) => Promise<{
         apiKey: string;
     } | undefined>) | undefined;
     metrics: {

package/dist/hooks/hook-llm.js

@@ -74,7 +74,7 @@ export function createHookLlm(deps) {
             let perModelKey;
             if (keyResolver) {
                 try {
-                    perModelKey = (await keyResolver({ name: pick.catalogRef }))?.apiKey;
+                    perModelKey = (await keyResolver({ name: pick.catalogRef }))?.apiKey; // ModelKeyRef: legal mint, no cast (B1)
                 }
                 catch (e) {
                     return { ok: false, error: `per-model key resolution for "${pick.catalogRef}" failed — refusing to fall back to the shared route credential (${String(e)})` };

package/dist/http/principal-gate.d.ts

@@ -14,7 +14,10 @@ export declare function bearerPresentedButUnverified(req: IncomingMessage, confi
 export declare function gatedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
 /** 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 declare function explicitOperatorOk(principal: string | undefined, operatorPrincipals: readonly string[]): boolean;
 /** May `principal` act as an OPERATOR on the F4 approval queue? Empty `operatorPrincipals` = legacy
  *  behavior (the shared service token IS the operator boundary → everyone authenticated is an operator).
@@ -24,6 +27,7 @@ export declare function isOperator(principal: string | undefined, operatorPrinci
  *  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 declare function explicitOperator(principal: string | undefined, operatorPrincipals: readonly string[]): boolean;
+ *  `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.d.ts.map

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/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