@sema-agent/server 3.21.0 → 3.23.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/bake-runner/main.d.ts

@@ -1,4 +1,4 @@
-import { type ImageApiClient, type ChildSpawner, type HostOps } from "./runner.js";
+import { type ImageApiClient, type ChildSpawner, type HostOps, type BakeRunnerLogger } from "./runner.js";
 interface RunnerEnv {
     imageApiBase: string;
     token: string;
@@ -14,7 +14,7 @@ interface RunnerEnv {
 declare function loadEnv(): RunnerEnv;
 /** The real image-api HTTP client. Authenticates claim/heartbeat with the runner bearer; ingest additionally
  *  carries the per-bake ingest secret header (so image-api can reject a stale/rogue runner — §P2.4e). */
-declare function makeApiClient(env: RunnerEnv): ImageApiClient;
+declare function makeApiClient(env: RunnerEnv, log: BakeRunnerLogger): ImageApiClient;
 /** The real child spawner: `setsid`-style detached process GROUP so a cancel/deadline kill signals the whole tree
  *  (channel-close / a plain kill of the immediate child does NOT stop a detached build — §P2.11). */
 declare function makeSpawner(): ChildSpawner;

package/dist/bake-runner/main.js

@@ -11,6 +11,7 @@ import { spawn, exec as execCb } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { createLogger } from "../observability/logger.js";
+import { parseNumOrFailNonNegative } from "../config.js";
 import { BakeRunner, } from "./runner.js";
 const exec = promisify(execCb);
 function loadEnv() {
@@ -28,14 +29,22 @@ function loadEnv() {
         recipeDir: process.env.RECIPE_DIR || "/opt/recipes",
         buildShPath: process.env.BUILD_SH_PATH || "e2b-template/dev-sandbox/build.sh",
         dataDir: process.env.BAKE_DATA_DIR || "/data",
-        heartbeatMs: Number(process.env.BAKE_HEARTBEAT_MS || "30000"),
-        idlePollMs: Number(process.env.BAKE_IDLE_POLL_MS || "5000"),
-        minFreeGb: Number(process.env.IMAGE_BAKE_MIN_FREE_GB || "20"),
+        // A2/E5 (gap-sweep 2026-08-01): these were bare `Number(process.env.X || default)` — a unit-suffixed or
+        // typo'd value (`"30s"`) silently became NaN, and NaN survives every downstream `??`/`?? default` guard
+        // (those only catch null/undefined). The fallout is a SILENT-LOOSENING pair: `clock.sleep(NaN)` resolves
+        // ~immediately (`setTimeout(fn, NaN)` behaves like a 0ms timer) turning the lease heartbeat into a tight
+        // POST loop against image-api, and `freeGb < NaN` is always false so the pre-flight disk guard silently
+        // never fires. `parseNumOrFailNonNegative` (config.ts, shared with leader/wire.ts's four resource knobs)
+        // fails loud at bake-runner startup instead — non-numeric OR negative both throw; unset/empty still falls
+        // back to the documented default (zero behavior change on the happy path).
+        heartbeatMs: parseNumOrFailNonNegative("BAKE_HEARTBEAT_MS", process.env.BAKE_HEARTBEAT_MS || "30000"),
+        idlePollMs: parseNumOrFailNonNegative("BAKE_IDLE_POLL_MS", process.env.BAKE_IDLE_POLL_MS || "5000"),
+        minFreeGb: parseNumOrFailNonNegative("IMAGE_BAKE_MIN_FREE_GB", process.env.IMAGE_BAKE_MIN_FREE_GB || "20"),
     };
 }
 /** The real image-api HTTP client. Authenticates claim/heartbeat with the runner bearer; ingest additionally
  *  carries the per-bake ingest secret header (so image-api can reject a stale/rogue runner — §P2.4e). */
-function makeApiClient(env) {
+function makeApiClient(env, log) {
     const auth = { authorization: `Bearer ${env.token}`, "content-type": "application/json" };
     return {
         // Long-poll claim (§P2.12): the bare `POST …/bakes/claim` finds the oldest queued bake AND leases it in one
@@ -46,13 +55,27 @@ function makeApiClient(env) {
                 headers: auth,
                 body: JSON.stringify({ runnerId: env.runnerId }),
             });
-            if (res.status === 204 || res.status === 409)
-                return null; // empty queue, or lost the single-flight CAS
-            if (!res.ok)
+            if (res.status === 204)
+                return null; // empty queue — the routine "nothing to do" case, no log line
+            // C6/C1 (2026-08-01): 401 (bad runner credential) / 409 (lost the single-flight CAS to another runner
+            // replica) / 5xx previously fell into this SAME silent-`null` branch as an empty queue — a misconfigured
+            // BAKE_RUNNER_TOKEN and a healthy idle runner were indistinguishable from the outside (both just idle-poll
+            // forever with zero log lines). `bake_claim_error` (loop()'s catch) only fires on a THROWN error — a non-ok
+            // HTTP response never throws — so this warn is the only trace a non-2xx claim response leaves anywhere.
+            if (!res.ok) {
+                log.warn("bake_claim_rejected", { status: res.status });
                 return null;
+            }
             const c = (await res.json());
-            if (!c.bakeId || !Array.isArray(c.argv) || !c.ingestSecret)
+            if (!c.bakeId || !Array.isArray(c.argv) || !c.ingestSecret) {
+                // A malformed 2xx body is worse than a rejection: image-api's claim call ATOMICALLY leases the bake
+                // server-side before returning it, so a shape we refuse to trust here is a bake already checked OUT
+                // from the queue that we are about to drop on the floor. We still can't safely act on an untrusted
+                // shape (no bakeId ⇒ no way to release/fail it), so this warn is the only surfacing point until
+                // image-api's stale-lease reaper reclaims it (§P2.7) — see runner.ts module doc for the reaper backstop.
+                log.warn("bake_claim_malformed", { status: res.status, bakeId: typeof c.bakeId === "string" ? c.bakeId : undefined });
                 return null;
+            }
             return {
                 bakeId: c.bakeId,
                 argv: c.argv.map(String),
@@ -223,7 +246,7 @@ async function main() {
         minFreeGb: env.minFreeGb,
     }); // NB: the token + per-bake ingest secret are NEVER logged (§P2.4e)
     const runner = new BakeRunner({
-        api: makeApiClient(env),
+        api: makeApiClient(env, log),
         spawner: makeSpawner(),
         host: makeHostOps(env),
         clock: makeClock(),

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/capabilities/center-plugins.js

@@ -180,7 +180,7 @@ export async function applyCenterPlugins(baseline, eff, opts) {
             }
             if (!rootCheck.dir)
                 continue; // 无 skills 目录:合法(commands-only 插件,cli 壳的半场)
-            const loaded = loadSkills(rootCheck.dir);
+            const loaded = loadSkills(rootCheck.dir, { confineTo: liveDir }); // 不可信 lane:逐条目约束在 clone root 内(根守卫只守了 skills 根,根下 symlink 可逃逸) // 不可信 lane:逐条目约束在 clone root 内(根守卫只守了 skills 根,根下 symlink 可逃逸) // 不可信 lane:逐条目约束在 clone root 内(根守卫只守了 skills 根,根下 symlink 可逃逸)
             for (const skill of loaded) {
                 if (taken.has(skill.spec.name)) {
                     // 收紧④:plugin 让位(方向与 center-wins 相反,理由见模块顶注)。

package/dist/capabilities/skills.d.ts

@@ -31,7 +31,18 @@ export interface LoadedSkill {
     /** Scenarios this skill applies to; empty = global (every scenario). */
     scenarios: string[];
 }
-export declare function loadSkills(dir: string): LoadedSkill[];
+/** 加载 lane 的信任级。缺席(受控 lane:烤制进镜像的 skills 目录)= 维持既有语义,symlink 照跟
+ *  ——那个便利是有意的(`foo.md -> 共享文件`)。`confineTo` 在场(**不可信 lane**:第三方 git checkout,
+ *  见 center-plugins 的 plugin 装载)= 每个被读条目 realpath 后必须仍在该根之内,逃逸即抛。
+ *  🔴 为什么信任级必须是**参数**而不是注释里的假设:本函数的头注原写着「skills dir 全受控」,而
+ *  center-plugins 把它原样复用在 attacker-controlled 的 git checkout 上——git 原样保留仓里的 symlink,
+ *  于是 checkout 里某个 skill 条目(`任意 .md -> /宿主/任意文件`)会被读进 spec.files 进入提示词。resolvePluginSkillsRoot
+ *  只 realpath 守了 skills **根**,根下逐条目没守。 */
+export interface LoadSkillsOptions {
+    /** 不可信 lane 的约束根(通常=clone root)。缺席=受控 lane,不做逐条目约束。 */
+    confineTo?: string;
+}
+export declare function loadSkills(dir: string, opts?: LoadSkillsOptions): LoadedSkill[];
 /** Skills applicable to a scenario: those tagged with it, plus untagged (global) ones. */
 export declare function skillsForScenario(loaded: LoadedSkill[], scenario: string): SkillSpec[];
 export declare function parseFrontmatter(raw: string): {

package/dist/capabilities/skills.js

@@ -1,6 +1,20 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-export function loadSkills(dir) {
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, sep } from "node:path";
+/** `p` 的 realpath 必须落在 `rootReal` 之内(含自身),否则抛。`sep` 边界判定防 `/a/root-evil` 撞
+ *  `/a/root` 前缀。目标不存在 ⇒ realpath 抛 ENOENT,同样是拒绝(悬空链接不该被读)。 */
+function assertConfined(p, rootReal) {
+    let real;
+    try {
+        real = realpathSync(p);
+    }
+    catch (e) {
+        throw new Error(`skill entry ${p} is unreadable (dangling symlink or missing): ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (real !== rootReal && !real.startsWith(rootReal + sep)) {
+        throw new Error(`skill entry ${p} escapes the plugin root (resolves outside ${rootReal}) — untrusted checkouts may not link to host files`);
+    }
+}
+export function loadSkills(dir, opts) {
     let entries;
     try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -21,17 +35,22 @@ export function loadSkills(dir) {
     // sort 保证加载顺序稳定(冲突报错的"先到者"也因此确定)。dotfile/dot 目录跳过(.DS_Store/.git 类
     // 环境杂物,不是 skill 内容);isFileLike 兼容 symlink(Dirent.isFile() 对 symlink 恒 false,而旧扁平
     // 实现 readFileSync 是跟链接的——不兼容会让 skills 目录下 `foo.md -> 共享文件` 这种软链无声消失)。
+    const confineRoot = opts?.confineTo !== undefined ? realpathSync(opts.confineTo) : undefined;
     const isFileLike = (entry, p) => entry.isFile() || (entry.isSymbolicLink() && statSync(p).isFile());
     const isDirLike = (entry, p) => entry.isDirectory() || (entry.isSymbolicLink() && statSync(p).isDirectory());
     for (const entry of entries.slice().sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
         if (entry.name.startsWith("."))
             continue;
         if (isFileLike(entry, join(dir, entry.name)) && entry.name.endsWith(".md")) {
+            if (confineRoot !== undefined)
+                assertConfined(join(dir, entry.name), confineRoot);
             const raw = readFileSync(join(dir, entry.name), "utf8");
             push(parseSkill(raw, entry.name.replace(/\.md$/, "")), join(dir, entry.name));
         }
         else if (isDirLike(entry, join(dir, entry.name))) {
             const skillDir = join(dir, entry.name);
+            if (confineRoot !== undefined)
+                assertConfined(skillDir, confineRoot);
             let raw;
             try {
                 raw = readFileSync(join(skillDir, "SKILL.md"), "utf8");
@@ -41,8 +60,10 @@ export function loadSkills(dir) {
                 // 整个 skill 无声丢掉 → fail-loud
                 throw new Error(`skill directory ${skillDir} has no SKILL.md`);
             }
+            if (confineRoot !== undefined)
+                assertConfined(join(skillDir, "SKILL.md"), confineRoot);
             const skill = parseSkill(raw, entry.name);
-            const files = collectAttachments(skillDir, "");
+            const files = collectAttachments(skillDir, "", confineRoot);
             if (files.length > 0)
                 skill.spec.files = files;
             push(skill, join(skillDir, "SKILL.md"));
@@ -53,7 +74,7 @@ export function loadSkills(dir) {
 /** 目录形态附件:递归收 SKILL.md 之外的一切文件,path=相对 skill 目录(posix 斜杠),sort 稳定。
  *  dotfile/dot 目录跳过(交叉评审 M3):skill 目录若从别的 checkout 整拷,.git/config、.env 类隐藏物
  *  会连凭据一起进 spec.files 变成提示词可见附件——附件只收显式内容文件。symlink 跟链接(同扁平兼容)。 */
-function collectAttachments(skillDir, rel) {
+function collectAttachments(skillDir, rel, confineRoot) {
     const files = [];
     const here = rel === "" ? skillDir : join(skillDir, rel);
     for (const entry of readdirSync(here, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
@@ -64,9 +85,13 @@ function collectAttachments(skillDir, rel) {
         const dirLike = entry.isDirectory() || (entry.isSymbolicLink() && statSync(abs).isDirectory());
         const fileLike = entry.isFile() || (entry.isSymbolicLink() && statSync(abs).isFile());
         if (dirLike) {
-            files.push(...collectAttachments(skillDir, relPath));
+            if (confineRoot !== undefined)
+                assertConfined(abs, confineRoot);
+            files.push(...collectAttachments(skillDir, relPath, confineRoot));
         }
         else if (fileLike && relPath !== "SKILL.md") {
+            if (confineRoot !== undefined)
+                assertConfined(abs, confineRoot);
             files.push({ path: relPath, content: readFileSync(abs, "utf8") });
         }
     }

package/dist/config.d.ts

@@ -25,6 +25,18 @@ export declare function numEnv(name: string, fallback: string): number;
  * `undefined`/空串 ⇒ 交给调用方的 fallback 语义处理(本函数只判「给了值但不是数」)。
  */
 export declare function parseNumOrFail(name: string, raw: string | undefined): number;
+/**
+ * `parseNumOrFail` layered with a non-negative floor — the SAME judgment `leader/wire.ts`'s (private,
+ * file-local) `parseNumOrFailNonNegative` already applies to its four resource knobs, exported here so a
+ * second call site (bake-runner's heartbeat/idle-poll/disk-guard knobs, gap-sweep 2026-08-01) can reuse the
+ * one shared primitive instead of re-deriving its own "reject a bad number" scheme. A negative value is
+ * JS-truthy, so a bare `|| default` fallback lets it straight through; for a duration knob that means
+ * `clock.sleep(-N)` fires ~immediately (the same tight-loop failure NaN causes), and for a threshold knob
+ * (`freeGb < minFreeGb`) a negative floor makes the comparison vacuously true/false depending on sign —
+ * either way the guard it configures goes silently slack. `undefined`/unset stays NaN (unchanged) so
+ * existing `|| fallback` chains built on `parseNumOrFail` are untouched by this stricter sibling.
+ */
+export declare function parseNumOrFailNonNegative(name: string, raw: string | undefined): number;
 export declare function drainConfigWarnings(): Array<{
     env: string;
     raw: string;

package/dist/config.js

@@ -94,6 +94,23 @@ export function parseNumOrFail(name, raw) {
         throw new Error(`env ${name}="${raw}" must be a number`);
     return n;
 }
+/**
+ * `parseNumOrFail` layered with a non-negative floor — the SAME judgment `leader/wire.ts`'s (private,
+ * file-local) `parseNumOrFailNonNegative` already applies to its four resource knobs, exported here so a
+ * second call site (bake-runner's heartbeat/idle-poll/disk-guard knobs, gap-sweep 2026-08-01) can reuse the
+ * one shared primitive instead of re-deriving its own "reject a bad number" scheme. A negative value is
+ * JS-truthy, so a bare `|| default` fallback lets it straight through; for a duration knob that means
+ * `clock.sleep(-N)` fires ~immediately (the same tight-loop failure NaN causes), and for a threshold knob
+ * (`freeGb < minFreeGb`) a negative floor makes the comparison vacuously true/false depending on sign —
+ * either way the guard it configures goes silently slack. `undefined`/unset stays NaN (unchanged) so
+ * existing `|| fallback` chains built on `parseNumOrFail` are untouched by this stricter sibling.
+ */
+export function parseNumOrFailNonNegative(name, raw) {
+    const n = parseNumOrFail(name, raw);
+    if (n < 0)
+        throw new Error(`env ${name}=${n} must not be negative`);
+    return n;
+}
 /** Numeric env with a [min,max] bound (BL-17): an out-of-range value FAILS at startup instead of being
  *  silently clamped/applied (e.g. a multi-hour MCP_ELICITATION_TTL_MS would silently never expire). */
 function numEnvBounded(name, fallback, min, max) {

package/dist/fleet/fleet-bus.js

@@ -203,9 +203,12 @@ export function fleetRunPublisher(bus, run) {
                 elapsedDonor.add(cid);
             const elapsed = elapsedDonor.has(cid) ? Date.now() - childStartedAt.get(cid) : undefined;
             if (donorName !== undefined || elapsed !== undefined) {
+                // cli [2297]①:donorName 只进 `name` 位。run-leg tick 手上没有独立的类型名([1364]③/core 1.350:
+                // name=display 标签、agentType=类型名),把 display 值同时写进 agentType 会让 fleet 的 TYPE 列显示
+                // description。缺源的键不铸(与「匿名行不铸假名」同一条原则);BCE 行自己的帧带真 agentType 时自然补上。
                 bus.publishTask({
                     id: bceRowId,
-                    ...(donorName !== undefined ? { name: donorName, agentType: donorName } : {}),
+                    ...(donorName !== undefined ? { name: donorName } : {}),
                     ...(elapsed !== undefined ? { elapsedMs: elapsed } : {}),
                 });
             }

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)})` };
@@ -160,7 +160,7 @@ export function createHookLlm(deps) {
                 text = j.choices?.[0]?.message?.content ?? undefined;
             }
             metrics.inc("hook_llm_calls_total", { type: "prompt" });
-            return typeof text === "string" ? { ok: true, text } : { ok: false, error: "hook llm returned no content" };
+            return typeof text === "string" ? { ok: true, text } : { ok: false, error: "hook llm returned no content", code: "no_content" };
         }
         catch (e) {
             // 网络层失败原样只有 "TypeError: fetch failed"(不是人话):带上端点与 cause(ECONNREFUSED 等),

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

@@ -91,7 +91,11 @@ export type HookLlmCall = (opts: {
 } | {
     ok: false;
     error: string;
+    code?: HookLlmFailureCode;
 }>;
+/** 失败判别码(B8:判别一律走码,禁按 error 文案分支——v3.1 批2,统检第二波 high)。error 仍是给人看的
+ *  自由文本;code 是给控制流的。缺席=未分类失败(不重试、不特判)。 */
+export type HookLlmFailureCode = "no_content" | "hard_timeout";
 /**
  * 阶段三a:`http` 条目——契约语义 = POST hook 输入 JSON 到 `url`;headers 里的 `$NAME` 仅当 NAME 列在
  * `allowedEnvVars` 才从 worker 进程 env 插值(配置本身绝不携带密钥值,契约同边界)。

package/dist/hooks/hook-runner.js

@@ -383,7 +383,7 @@ async function runLlmHook(entry, payload, ctx, extra) {
     // 顺序是承重的 —— 包装句逐字预设会话在上文,放反了那句话本身就是在骗模型。
     const prompt = extra ? `${extra.transcript}\n\n---\n\n${wrapCondition("Stop", substituted)}` : substituted;
     // 载体外再包一层硬顶:契约说载体自己兜超时,但一个部署组装 bug 不该能挂死工具门(纵深)。
-    const hardTop = new Promise((r) => setTimeout(() => r({ ok: false, error: "__hook_llm_hard_timeout__" }), timeoutMs + 5_000).unref?.());
+    const hardTop = new Promise((r) => setTimeout(() => r({ ok: false, error: "hook llm hard-timeout backstop fired (carrier did not settle within timeoutMs+5s — deployment assembly bug)", code: "hard_timeout" }), timeoutMs + 5_000).unref?.());
     const invoke = () => Promise.race([
         call({
             prompt,
@@ -397,17 +397,17 @@ async function runLlmHook(entry, payload, ctx, extra) {
     // 🔴 **"一个字都没吐出来"重试一次**(仅 CC 评估者路)。这个失败形的后果是**判词被丢弃 ⇒ fail-open**
     // (该拦没拦),而它是**瞬态**的(推理档模型偶尔把额度用在 thinking 上)。
     // ⚠️ 只重试**无内容**,不重试"有内容但读不懂" —— 后者重试一次多半还是读不懂,而且那一格按设计就该放行。
-    if (extra && !res.ok && res.error.includes("returned no content")) {
+    if (extra && !res.ok && res.code === "no_content") { // B8:判别走码不走文案(v3.1 批2)
         ctx.logger.warn("hook_llm_no_content_retry", { event: "Stop" });
         res = await invoke();
         // 重试之后**仍然**没有内容 ⇒ 这一轮的守卫确实没能评估。发观测帧(纯 observe,不改变运行)——
         // 方向仍是 fail-open,但用户/壳侧要能知道「这轮没看住」,否则那个放行与「已达成」无法区分。
-        if (!res.ok && res.error.includes("returned no content")) {
+        if (!res.ok && res.code === "no_content") {
             ctx.onHookNotice?.({ kind: "hook_decision_unavailable", event: "Stop", reason: "no_content", detail: "carrier returned no content (after one retry)" });
         }
     }
     if (!res.ok) {
-        return res.error === "__hook_llm_hard_timeout__"
+        return res.code === "hard_timeout"
             ? { code: null, stdout: "", stderr: "", timedOut: true }
             : { code: null, stdout: "", stderr: "", timedOut: false, spawnError: clip(res.error, 500) };
     }

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