@sema-agent/server 3.20.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/fleet/fleet-bus.d.ts

@@ -291,6 +291,8 @@ export declare class FleetEventBus {
     releaseBackgroundChildLane(scope: string | undefined, childUuid: string): void;
     /** run-leg 车道:该子代是否已有 BCE 真行(有 ⇒ 让位,不铸复合 id 行)。 */
     backgroundChildLaneRow(scope: string | undefined, childUuid: string): string | undefined;
+    /** [2268] 让位迁移料的读面:迁移「只补缺席位」需要看得见存活行现有什么(BCE 是权威车道,不覆盖)。 */
+    taskRow(id: string): Readonly<FleetTaskRow> | undefined;
     /** Upsert a workflow row (MERGE by `id`) + fan out. */
     publishWorkflow(delta: Partial<FleetWorkflowRow> & {
         id: string;

package/dist/fleet/fleet-bus.js

@@ -86,6 +86,10 @@ export class FleetEventBus {
     backgroundChildLaneRow(scope, childUuid) {
         return this.bceClaims.get(FleetEventBus.bceKey(scope, childUuid));
     }
+    /** [2268] 让位迁移料的读面:迁移「只补缺席位」需要看得见存活行现有什么(BCE 是权威车道,不覆盖)。 */
+    taskRow(id) {
+        return this.tasks.get(id);
+    }
     // └────────────────────────────────────────────────────────────────────────────────────────────────┘
     /** Upsert a workflow row (MERGE by `id`) + fan out. */
     publishWorkflow(delta) {
@@ -172,20 +176,43 @@ export function fleetRunPublisher(bus, run) {
      * registry ⇒ 永远没有 BCE 真行,让位就等于让这些 agent 从面板消失。那一形保留复合行,并在帧上带
      * `sourceLane:"run-leg"` 明示这是过渡形——消费端不必再自己发明集合级去重判据。
      */
-    const yieldToBackgroundChildLane = (childTaskId, cid) => {
-        if (bus.backgroundChildLaneRow(run.scope, childTaskId) === undefined)
+    const yieldToBackgroundChildLane = (childTaskId, cid, tickName) => {
+        const bceRowId = bus.backgroundChildLaneRow(run.scope, childTaskId);
+        if (bceRowId === undefined)
             return false;
         if (children.has(cid)) {
             // 我们早于 claim 铸过一行 —— 清场(BCE 侧的后缀扫是同一意图的反应式兜底,两者幂等叠加无害)
             bus.removeTask(cid);
             children.delete(cid);
-            childStartedAt.delete(cid);
+            // ⚠️ childStartedAt 故意不删 —— 它是下面 elapsed 供给的计时基准([2268])
             for (const [k, v] of childByToolCall)
                 if (v === cid)
                     childByToolCall.delete(k);
         }
+        // 🔴 [2268] 迁移料([2269] 认领「迁移」臂):此前让位=删「有名的 run-leg 行」留「无名的 BCE 行」
+        // ((unnamed)/0s/详情空白三症状同源)。tick 手上的显示料补给存活行,**只补缺席位** —— BCE 是权威
+        // 车道,它已有的 name/真 elapsed 一律不碰。elapsed 供给是持续的(本闸每拍都过),不是一次性冻结;
+        // elapsedDonor 记住「这行的 elapsed 是我们供的」,避免把 BCE 自己的真 elapsed 误当缺席重置。
+        // transcriptId 不在 run-leg tick 手上,迁不了(诚实范围;那半归 BCE 行自身后续 tick)。
+        const row = bus.taskRow(bceRowId);
+        if (row) {
+            const donorName = row.name === undefined && tickName !== undefined ? redactSecrets(tickName) : undefined;
+            if (!childStartedAt.has(cid))
+                childStartedAt.set(cid, Date.now());
+            if (elapsedDonor.has(cid) || row.elapsedMs === undefined || row.elapsedMs === 0)
+                elapsedDonor.add(cid);
+            const elapsed = elapsedDonor.has(cid) ? Date.now() - childStartedAt.get(cid) : undefined;
+            if (donorName !== undefined || elapsed !== undefined) {
+                bus.publishTask({
+                    id: bceRowId,
+                    ...(donorName !== undefined ? { name: donorName, agentType: donorName } : {}),
+                    ...(elapsed !== undefined ? { elapsedMs: elapsed } : {}),
+                });
+            }
+        }
         return true;
     };
+    const elapsedDonor = new Set(); // [2268] 我们在为哪些 cid 供 elapsed(见上)
     const sumTokens = (usage) => {
         const u = usage;
         if (!u)
@@ -219,8 +246,8 @@ export function fleetRunPublisher(bus, run) {
             else if (ev.type === "task_progress" && ev.taskId) {
                 // core 1.147 subagent usage tick (per-turn, cumulative) → a CHILD fleet row nested under the run.
                 const cid = childId(ev.taskId);
-                if (yieldToBackgroundChildLane(ev.taskId, cid))
-                    return; // [2070]① BCE 真行在场 ⇒ 让位不铸
+                if (yieldToBackgroundChildLane(ev.taskId, cid, ev.name))
+                    return; // [2070]① BCE 真行在场 ⇒ 让位不铸([2268] 随迁显示料)
                 children.add(cid);
                 // BC-2 (core 1.151): use the subagent's sanitized display `name` (taskName/agent-type) for the child row.
                 // [2070]③:name 缺席时**不铸**(此前回落 taskId=子代 uuid,人眼乱码)——行 IDENTITY 一直是 `cid`
@@ -273,8 +300,8 @@ export function fleetRunPublisher(bus, run) {
             if (ev.type !== "task_progress" || !ev.taskId)
                 return;
             const cid = childId(ev.taskId);
-            if (yieldToBackgroundChildLane(ev.taskId, cid))
-                return; // [2070]① BCE 真行在场 ⇒ 让位不铸
+            if (yieldToBackgroundChildLane(ev.taskId, cid, ev.name))
+                return; // [2070]① BCE 真行在场 ⇒ 让位不铸([2268] 随迁显示料)
             children.add(cid);
             const parentId = ev.parentTaskId && ev.parentTaskId !== run.rootTaskId ? childId(ev.parentTaskId) : run.runId;
             // [WF2-A] redact the forwarded subagent name for parity with the top-level run name (see onEvent above).

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/active-run-conflict.d.ts

@@ -0,0 +1,68 @@
+/**
+ * [2252]/[2255]①/[2257] 追加件:409 `conflict.session_active_run` 的**真出路材料**装配(单源)。
+ *
+ * 事故形:park(suspended/needs_review)占着 session claim,客户端每条新提交吃 409,而旧文案只教
+ * cancel(毁灭当前 run)。对 parked 会话,「继续」的唯一合法动作是去**对的** resume 入口决议——但四条
+ * resume 入口各认各的 gate.kind,客户端不知道等的是哪种门,只能试错。本模块把答案放进 409 响应体:
+ *   activeTaskStatus(区分「插话/取消」与「决议/取消」两族出路)
+ *   pendingGate { kind, decidePath }(parked 且真有 pending checkpoint 时)
+ *
+ * 🔴 token 永不上 wire(approvals-assistant 纪律:resume 寻址=sessionId,checkpoint token 是秘密能力)。
+ * 🔴 失败方向:材料是 best-effort 增强——store 面任何失败都不得挡 409 本体,退化为旧形状,绝不 throw。
+ * 🔴 gateKind→入口映射是**这张表在仓里的唯一函数形**;它的知识此前散在 server.ts 三处 guard 文案里
+ *    (`gate_not_tool_approval`/`gate_not_resumable`/`wake.gate_pending` 的指路句)。三处文案与本表若漂移,
+ *    test/session-active-conflict-materials.test.ts 的分门用例会红。认不出的 kind ⇒ null(诚实缺席,不铸假门)。
+ */
+/** 与 runs.ts/tasks.ts 三个 409 位共享的旧文案(byte-frozen:api-error-text-freeze 门认这句)。 */
+export declare const ACTIVE_RUN_CONFLICT_BASE_TEXT = "session already has an active run \u2014 POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)";
+export interface ActiveRunConflictBody {
+    error: string;
+    errorCode: "conflict.session_active_run";
+    activeTaskId: string | null;
+    activeTaskStatus?: string;
+    pendingGate?: {
+        kind: string;
+        decidePath: string;
+    };
+}
+/** gate.kind → 它的那一个 resume 入口(sessionId/taskId 寻址,无秘密)。 */
+export declare function resumeEntryForGate(kind: string, ids: {
+    sessionId: string;
+    taskId: string;
+}): string | null;
+/** token 泛型:真身是 branded CheckpointToken(秘密能力,只在本函数内部流转,绝不进响应体)。 */
+/**
+ * SSE 车道的 done 帧 result(拒绝形)。与 409 body **同一铸体处** —— 此前 tasks.ts 在 res.write 里
+ * 手搓内联对象挑键,形状没有名字、没有类型、只活在那一行字符串里(conditional-spread 死键的老坑形)。
+ * 这里铸,SDK 的 done 帧 result 类型与本形同车对齐(sdk-api-guarantee-duty),live-contract 套件对已发包真跑。
+ */
+export interface ActiveRunConflictDoneResult {
+    status: "failed";
+    errorMessage: string;
+    activeTaskId: string | null;
+    activeTaskStatus?: string;
+    pendingGate?: {
+        kind: string;
+        decidePath: string;
+    };
+}
+export declare function toDoneFrameResult(body: ActiveRunConflictBody): ActiveRunConflictDoneResult;
+interface ConflictProbeDeps<TToken> {
+    runStore?: {
+        getRun?: (id: string) => Promise<{
+            status?: string;
+        } | null | undefined>;
+    } | undefined;
+    checkpointStore?: {
+        peekPendingScope?: (sessionId: string) => Promise<string | null | undefined>;
+        findPendingTokenBySession?: (sessionId: string, scope?: string) => Promise<TToken | null | undefined>;
+        get?: (token: TToken) => Promise<{
+            gate?: {
+                kind?: string;
+            };
+        } | null | undefined>;
+    } | undefined;
+}
+export declare function buildActiveRunConflict<TToken>(deps: ConflictProbeDeps<TToken>, sessionId: string, activeTaskId: string | null | undefined): Promise<ActiveRunConflictBody>;
+export {};
+//# sourceMappingURL=active-run-conflict.d.ts.map

package/dist/http/active-run-conflict.js

@@ -0,0 +1,89 @@
+/**
+ * [2252]/[2255]①/[2257] 追加件:409 `conflict.session_active_run` 的**真出路材料**装配(单源)。
+ *
+ * 事故形:park(suspended/needs_review)占着 session claim,客户端每条新提交吃 409,而旧文案只教
+ * cancel(毁灭当前 run)。对 parked 会话,「继续」的唯一合法动作是去**对的** resume 入口决议——但四条
+ * resume 入口各认各的 gate.kind,客户端不知道等的是哪种门,只能试错。本模块把答案放进 409 响应体:
+ *   activeTaskStatus(区分「插话/取消」与「决议/取消」两族出路)
+ *   pendingGate { kind, decidePath }(parked 且真有 pending checkpoint 时)
+ *
+ * 🔴 token 永不上 wire(approvals-assistant 纪律:resume 寻址=sessionId,checkpoint token 是秘密能力)。
+ * 🔴 失败方向:材料是 best-effort 增强——store 面任何失败都不得挡 409 本体,退化为旧形状,绝不 throw。
+ * 🔴 gateKind→入口映射是**这张表在仓里的唯一函数形**;它的知识此前散在 server.ts 三处 guard 文案里
+ *    (`gate_not_tool_approval`/`gate_not_resumable`/`wake.gate_pending` 的指路句)。三处文案与本表若漂移,
+ *    test/session-active-conflict-materials.test.ts 的分门用例会红。认不出的 kind ⇒ null(诚实缺席,不铸假门)。
+ */
+/** 与 runs.ts/tasks.ts 三个 409 位共享的旧文案(byte-frozen:api-error-text-freeze 门认这句)。 */
+export const ACTIVE_RUN_CONFLICT_BASE_TEXT = "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)";
+/** gate.kind → 它的那一个 resume 入口(sessionId/taskId 寻址,无秘密)。 */
+export function resumeEntryForGate(kind, ids) {
+    switch (kind) {
+        case "tool_approval":
+        case "human":
+        case "irreversible_ask":
+        case "policy_ask":
+            return `/v1/approvals/${ids.sessionId}/decide`;
+        case "plan_review":
+            return `/v1/assistant/tasks/${ids.taskId}/plan_review`;
+        case "resource_limit":
+            return `/v1/assistant/tasks/${ids.taskId}/resume`;
+        case "task_done":
+            return `/v1/sessions/${ids.sessionId}/wake`;
+        default:
+            return null; // 未知门型:宁缺毋假 —— 客户端仍有 activeTaskStatus + cancel 这条保底真路
+    }
+}
+export function toDoneFrameResult(body) {
+    return {
+        status: "failed",
+        errorMessage: body.error,
+        activeTaskId: body.activeTaskId,
+        ...(body.activeTaskStatus !== undefined ? { activeTaskStatus: body.activeTaskStatus } : {}),
+        ...(body.pendingGate !== undefined ? { pendingGate: body.pendingGate } : {}),
+    };
+}
+export async function buildActiveRunConflict(deps, sessionId, activeTaskId) {
+    const base = {
+        error: ACTIVE_RUN_CONFLICT_BASE_TEXT,
+        errorCode: "conflict.session_active_run",
+        activeTaskId: activeTaskId ?? null,
+    };
+    if (!activeTaskId)
+        return base;
+    try {
+        const row = await deps.runStore?.getRun?.(activeTaskId);
+        const status = row?.status;
+        if (status !== "running" && status !== "suspended" && status !== "needs_review")
+            return base;
+        if (status === "running") {
+            return {
+                ...base,
+                error: "session already has an active run — POST /v1/runs/{activeTaskId}/steer injects a message into the running turn (queued, applied at the next turn boundary), or POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)",
+                activeTaskStatus: status,
+            };
+        }
+        // parked:找 pending checkpoint 的门型,指到它的那一个 resume 入口
+        const cs = deps.checkpointStore;
+        let pendingGate;
+        if (cs?.findPendingTokenBySession) {
+            const scope = (await cs.peekPendingScope?.(sessionId)) ?? undefined;
+            const token = scope === null ? null : await cs.findPendingTokenBySession(sessionId, scope);
+            const kind = token ? (await cs.get?.(token))?.gate?.kind : undefined;
+            const decidePath = kind ? resumeEntryForGate(kind, { sessionId, taskId: activeTaskId }) : null;
+            if (kind && decidePath)
+                pendingGate = { kind, decidePath };
+        }
+        return {
+            ...base,
+            error: pendingGate
+                ? `session already has an active run — it is parked waiting for a decision (${status}); resolve it via POST ${pendingGate.decidePath}, or POST /v1/runs/{activeTaskId}/cancel abandons it`
+                : `session already has an active run — it is parked (${status}); POST /v1/runs/{activeTaskId}/cancel abandons it (its pending decision could not be located on this instance)`,
+            activeTaskStatus: status,
+            ...(pendingGate ? { pendingGate } : {}),
+        };
+    }
+    catch {
+        return base; // 材料装配的任何失败都退化为旧形状 —— 增强绝不成为新故障点
+    }
+}
+//# sourceMappingURL=active-run-conflict.js.map

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