@sema-agent/server 7.43.0 → 7.44.0

package/dist/model-select.js

@@ -1,43 +1,11 @@
 import { parseModelMention } from "@sema-agent/core";
-/**
- * Resolve the model ref for a task spec from the request (CLI `/model` picker + `run --model`).
- *
- * Priority (a deliberate selection beats incidental free text):
- *   1) an explicit, allow-listed `body.model` (the picker / `--model <ref>` flag),
- *   2) an inline `@name` mention in the objective (core's `parseModelMention`),
- *   3) the `default` role.
- *
- * Security: BOTH the explicit field and the @mention are gated by the SAME catalog (`config.models` keys), so
- * untrusted body/text can pick WHICH configured model but can never inject a baseUrl/apiKey (parseModelMention
- * only ever returns an allow-listed catalog name).
- *
- * [865]②(生产实锤:面板上选了 A 模型,实际跑的是目录里的另一个):
- *  - explicit ref 走 name+id 双键索引({@link matchCatalogModel})——壳 boot 回读的 mainLoopModel 是 **id 形**,
- *    目录键是 **name 形**,单键索引把 id 形请求当「未知」静默落 default = session 中途静默换模型(最恶性的
- *    上下文污染路径)。
- *  - 真未知不再无声:FRESH submit 在 HTTP 门 400 fail-loud(带 available 列表,http/server.ts);本函数保持
- *    不 throw(RESUME 重放持久化 body 不过 400 门——模型可能事后被移出目录,砖死 resume 比降级更糟),但把
- *    未知 ref 透出给调用方(`unknownExplicit`),resolveSpec 记 warn——降级永远可见,绝不静默。
- *
- * Returns the chosen model ref AND the objective with any `@mention` stripped (parseModelMention's cleanedText).
- *
- * 🔴 Was a real defect: resolveSpec previously read ONLY the inline @mention, so `body.model` (the picker + the
- * `--model` flag) was SILENTLY DROPPED — the picker UX was a no-op server-side. This restores it.
- */
 export function resolveTaskModel(bodyModel, objective, catalog, allowlist) {
     const mention = parseModelMention(objective, Object.keys(catalog));
     const explicit = typeof bodyModel === "string" ? matchCatalogModel(bodyModel, catalog) : undefined;
-    // 未匹配的「在场」ref 一律透出(codex L1:历史 checkpoint 里的空串/非字符串 model 在 RESUME 重放也不许
-    // 静默降级——非字符串给类型表示,不 stringify 值本体防日志泄内容)。
     const present = bodyModel !== undefined && bodyModel !== null;
     const unknown = present && explicit === undefined;
     const repr = typeof bodyModel !== "string" ? `<non-string:${typeof bodyModel}>` : bodyModel === "" ? "<empty-string>" : bodyModel;
     const model = explicit ?? mention.model ?? "default";
-    // #233 / A-002.8:名单只裁**用户逐 turn 选择通道**——显式 ref(body.model / settings.model)与 objective
-    // 内联 `@name`。两者都缺席时落 `default`(operator 配置通道),本门**不碰**:名单管"用户可点什么",
-    // 不管"operator 配什么"(registry-core 也只校验名单 ⊆ catalog,从不要求 default ∈ 名单)。
-    // 不 throw:resume 重放持久化 body 不过 HTTP 门,砖死 resume 比降级糟(本文件 [865]② 同判据)——
-    // 判别式拒因交给调用点按 leg 分流(fresh 400 / resume warn 续跑)。
     const picked = explicit !== undefined ? { ref: explicit, source: "explicit", requested: repr } : mention.model !== undefined ? { ref: mention.model, source: "mention", requested: mention.model } : undefined;
     const notAllowed = picked !== undefined && !isModelAllowlisted(picked.ref, catalog, allowlist)
         ? { requested: picked.requested, resolved: terminalCatalogName(picked.ref, catalog) ?? picked.ref, source: picked.source }
@@ -49,28 +17,6 @@ export function resolveTaskModel(bodyModel, objective, catalog, allowlist) {
         ...(notAllowed ? { notAllowed } : {}),
     };
 }
-/**
- * #233 / A-002.8 —— **归一条款**:membership 判定前把 ref 归一到**终端 catalog 条目**再比。
- *
- * 为什么不能拿字符串直接跟名单比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)
- * 的值与 `config.models[<name>]` 是**同一个对象引用**——裸串比较会让 `@pro` 绕过一张按 name 写的名单
- * (同一只模型,两个键)。所以两边(ref 与每个名单条目)都先经 {@link matchCatalogModel} 解到目录条目,
- * 再按 **引用相等** 判同。id 形的 ref 不需要特别处理:`matchCatalogModel` 本身就是 name+id 双键索引,
- * 它会把 id 解成目录键,引用相等接着就对上了。
- *
- * 🔴 **刻意没有「id 相等」退路**(codex 复审 R1 [high],已采纳):目录**允许两条不同 name 的条目共享
- * 同一个上游 `Model.id`,却各自带不同的 `baseUrl` / `apiKeyEnv` / `cost` / provider** —— 那正是多网关、
- * 多账号部署形。按 id 判同会把 `safe` 与 `premium` 合并,于是一张只含 `safe` 的名单会放行 `premium`,
- * 而真正执行的是 `premium` 那份坐标与计费。判据只认**目录条目本身**:两条条目就是两只模型,哪怕上游
- * id 撞车。(引用相等因此不是"优化",是唯一正确的判据;它天然覆盖 tier 词/别名/id 三形。)
- *
- * 缺席/空名单 ⇒ 恒 `true`(ship-dark:缺省 = 旧行为,全放行)。
- * 目录里根本没有的 ref ⇒ 恒 `true`:那是「未知模型」那道门的辖区(fresh 400 / resume 降级留声),
- * 本门只答「在目录里,但准不准点」——两道门同码同拒会让消费端分不清"没这模型"和"不让你点"。
- *
- * ⚠️ 射程:本门是**提交时**门。core 运行时路由(degrade 降级链 / cascade 梯 / roles 解析)按 operator
- * 配置自己走,**不经本门**——那不是一次用户选择,如实声明,不假装是运行时执法。
- */
 export function isModelAllowlisted(ref, catalog, allowlist) {
     if (allowlist === undefined || allowlist.length === 0)
         return true;
@@ -80,25 +26,16 @@ export function isModelAllowlisted(ref, catalog, allowlist) {
     for (const name of allowlist) {
         const allowed = catalogEntryOf(name, catalog);
         if (allowed === undefined)
-            continue; // 悬空/不可解名单条目(apply 期已 warn):它准不了任何东西
+            continue;
         if (allowed === entry)
-            return true; // 引用相等 —— 增广目录里 tier 词/别名/id 最终都落到这同一只条目
+            return true;
     }
     return false;
 }
-/** ref(name / 档位词 / 别名 / id)→ 它在目录里的**条目对象**;未知 ⇒ undefined。 */
 function catalogEntryOf(ref, catalog) {
     const name = matchCatalogModel(ref, catalog);
     return name === undefined ? undefined : catalog[name];
 }
-/**
- * #233 —— ref → **终端 catalog name**(拒因/日志的可读形)。
- *
- * 为什么不是 `matchCatalogModel` 的返回值:增广目录里 `pro`/`opus`/`default` 都是**真实存在的键**,
- * 于是 `matchCatalogModel("pro")` 回的就是 `"pro"` —— 那是用户点的那个别名,不是他真会跑的模型。
- * 取条目自己的 `Model.name`(applyEffective 建目录时 `models[m.name].name === m.name`,env lane 同)
- * 才是终端名;拿不到时如实退回匹配键(诚实缺席,不猜)。
- */
 export function terminalCatalogName(ref, catalog) {
     const key = matchCatalogModel(ref, catalog);
     if (key === undefined)
@@ -106,13 +43,6 @@ export function terminalCatalogName(ref, catalog) {
     const name = catalog[key]?.name;
     return typeof name === "string" && name.length > 0 ? name : key;
 }
-/**
- * [865]② name+id 双键目录索引:返回 ref 命中的目录 **name 键**(spec.model 的规范形),未知 → undefined。
- *  - name 命中用 Object.hasOwn(🔴 不用真值索引:Object.prototype 继承键 "constructor"/"__proto__" 等在裸
- *    索引下是真值,会绕过 allow-list——沿袭原实现的纪律)。
- *  - id 命中扫目录值(`Model.id`),跳过 "default" 别名键(它与其指向的真身共享 id,解析到别名会让 /model
- *    面板与实际路由再度撕裂);同 id 多 name 时取目录序第一个(与 /v1/models 列表序一致,确定性)。
- */
 export function matchCatalogModel(ref, catalog) {
     if (Object.hasOwn(catalog, ref))
         return ref;
@@ -124,16 +54,9 @@ export function matchCatalogModel(ref, catalog) {
     }
     return undefined;
 }
-/**
- * vision precheck: a catalog model can read images iff its `input` modality list
- * includes `"image"` (the SAME test as the vision capability on GET /v1/models — `server.ts`). FALSE-SAFE on
- * missing/unknown modality info: returns `true` (do NOT block) — only an EXPLICIT text-only `input` triggers the
- * precheck, so a model that never declared its modalities is never wrongly 422'd. Lets a request with images 422
- * up-front instead of hitting the downstream gateway as an opaque deserialize 400 on a text-only model.
- */
 export function modelSupportsImages(model) {
     if (!model || !Array.isArray(model.input))
-        return true; // no modality info → fail-open (don't block)
+        return true;
     return model.input.includes("image");
 }
 //# sourceMappingURL=model-select.js.map

package/dist/observability/cost-quota.js

@@ -1,25 +1,13 @@
 export class CostQuota {
     now;
     windows = new Map();
-    /** 🔴 不再 `readonly`:限额/窗长是比较参数,换代只动它们,窗内已累计的花费一个不动(design/322 §5)。 */
     limitMicroUsd;
     windowMs;
-    /** @param limitMicroUsd ceiling per window (integer micro-USD; `<=0` = OFF sentinel). @param windowMs rolling window. */
     constructor(limitMicroUsd, windowMs, now = () => Date.now()) {
         this.now = now;
         this.limitMicroUsd = limitMicroUsd;
         this.windowMs = windowMs;
     }
-    /**
-     * 值换代。两件事**语义不同**,别混:
-     *  · **限额**换代 = 纯比较参数 ⇒ 窗内已累计的花费一个不动(design/322 §5 定案:调小当场更严)。
-     *  · **窗长**换代 = 换**记账周期** ⇒ 当代累计重开。
-     *
-     * 🔴 后者是 codex R1-F4(真 finding,红先):SQL 腿的窗长是**桶键的一部分**(`floor(now/windowMs)`),
-     * 换窗长后当代桶天然重算 ⇒ 已累计不跟着搬家;内存腿修前却保留原窗口累计。于是**同一条发布**在
-     * 内存部署上继续拒绝超额 principal、在 PG/TiDB 部署上重新放行一整个额度 —— 后端相关的成本 fail-open。
-     * 统一取 SQL 腿那一侧(唯一能在两条腿上都实现的语义:SQL 侧无法把旧桶累计搬进新桶)。
-     */
     setLimits(next) {
         this.limitMicroUsd = next.limitMicroUsd;
         if (next.windowMs !== this.windowMs) {
@@ -27,9 +15,7 @@ export class CostQuota {
             this.windows.clear();
         }
     }
-    /** Is this principal under quota right now? (Reads only — does not consume.) */
     check(key) {
-        // 关断哨兵:零窗表访问,如实报 `limitMicroUsd: 0`(消费方据此知道「本部署此刻没有 ceiling」)。
         if (this.limitMicroUsd <= 0)
             return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0 };
         const t = this.now();
@@ -40,10 +26,9 @@ export class CostQuota {
         const retryAfterSec = !allowed && live ? Math.ceil((w.start + this.windowMs - t) / 1000) : 0;
         return { allowed, usedMicroUsd: used, limitMicroUsd: this.limitMicroUsd, retryAfterSec };
     }
-    /** Add spend for a principal, starting a fresh window if the prior one expired. */
     add(key, micro) {
         if (this.limitMicroUsd <= 0)
-            return; // 关断哨兵:不为一个不存在的门攒内存(0→N 打开时是全新的窗口)
+            return;
         if (micro <= 0)
             return;
         const t = this.now();
@@ -53,7 +38,6 @@ export class CostQuota {
         else
             w.micro += micro;
     }
-    /** Drop expired windows (called from the background reaper) to bound memory. */
     reap() {
         const t = this.now();
         let dropped = 0;

package/dist/observability/cost-taxonomy.js

@@ -1,25 +1,4 @@
-/**
- * design/80 b (item 3) — the INFRA cost axes the SERVICE owns, composed with core's LLM-family `costBreakdown`
- * for the supervisor cost surface.
- *
- * (design/158 N24: moved here from the single-file `src/finance/` directory — lens4 §4.4 flagged the "cost"
- * concept as split across `finance/cost-taxonomy.ts` + `observability/cost-quota.ts` + `budget.ts`. Chose
- * "dissolve finance/, fold into observability/" over "collect all three into finance/": this module + the
- * quota tracker are both cost REPORT/GUARD layers that feed metrics/decisions (observability's existing
- * job), and budget.ts stays put — it has ~19 import sites and was already the N18 move target this same
- * batch; stacking a second wide-fanout move on it in one session was the higher-risk option for no added
- * clarity.)
- *
- * The engine prices ONLY LLM tokens (core's `Stats.costBreakdown` = llmRoot / nestedSubagent / memoryConsolidation
- * / compaction). It has NO $ for tool calls, sandbox wall-clock, or network egress — those are INFRA/service costs
- * the service owns the data + rates for. This module is the thin report layer: it turns a
- * per-run infra USAGE + the deployment's RATES into an infra breakdown, then composes it with the core LLM
- * breakdown into one supervisor-facing total. Pure + rate-driven (rates default 0 ⇒ infra reads $0, exactly like
- * MODEL_COST_* — opt-in pricing). The per-run usage extraction (sandbox wall-clock from the run's remote-env
- * spans, tool-call count from the trace) is the data-source wiring fed in by the caller; this layer is the math.
- */
 const nonNeg = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
-/** Price a run's infra usage. Every term clamps negatives to 0 (a bad usage/rate never produces a negative cost). */
 export function infraCost(usage, rates) {
     const toolCallMicroUsd = nonNeg(usage.toolCalls) * nonNeg(rates.toolCallMicroUsd);
     const sandboxWalltimeMicroUsd = (nonNeg(usage.sandboxWalltimeMs) / 1000) * nonNeg(rates.sandboxSecMicroUsd);
@@ -31,25 +10,12 @@ export function infraCost(usage, rates) {
         totalMicroUsd: toolCallMicroUsd + sandboxWalltimeMicroUsd + egressMicroUsd,
     };
 }
-/**
- * Compose the supervisor cost surface from core's LLM breakdown + total and the service's infra breakdown.
- * `llmTotalMicroUsd` is core's authoritative priced-LLM total (`stats.costMicroUsd`) — the grand total is that +
- * infra, NOT a re-sum of the LLM sub-categories (so a breakdown category bug can't move the grand total).
- */
 export function composeSupervisorCost(llm, llmTotalMicroUsd, infra) {
     return { llm, infra, totalMicroUsd: nonNeg(llmTotalMicroUsd) + infra.totalMicroUsd };
 }
-/** True iff ANY infra axis is priced — the gate for surfacing the composed supervisor cost (when all rates are 0
- *  the infra contribution is always $0, so the client just reads core's `stats.costBreakdown` directly). */
 export function hasInfraPricing(r) {
     return r.toolCallMicroUsd > 0 || r.sandboxSecMicroUsd > 0 || r.egressGbMicroUsd > 0;
 }
-/**
- * Extract a run's infra USAGE from its event log + wall-clock span. `toolCalls` = the `tool_start` events (one per
- * tool invocation). `sandboxWalltimeMs` ≈ the run's wall-clock duration (the remote-env is connected for ~the
- * run's active life; the precise per-span sum lives in logs, not the event trace — the run duration is the
- * faithful per-run proxy). `egressBytes` = 0 (not yet metered per run).
- */
 export function infraUsageFromEvents(events, runDurationMs) {
     return {
         toolCalls: events.reduce((n, e) => (e.type === "tool_start" ? n + 1 : n), 0),

package/dist/observability/fail-open.js

@@ -1,36 +1,4 @@
-/**
- * #157 fail-open 治理专项 —— 兜底路径的**响亮化**工具(server 半场;跨仓方案见 sema-comms
- * `audits/failopen-governance-176.md` §2,三仓语义对齐、实现各自)。
- *
- * ## 它解决的问题
- * 「走了兜底」与「一切正常」在外部**同形**——成功回执一样、日志一样、指标一样。于是一个静默降级
- * 能带病运行数周,只能靠"该发生的事没发生"这种间接症状发现。本模块给每条合法兜底臂一个**登记过的
- * tag**,走到即留痕三件套:
- *
- *  1. **计数(逐次)** —— `fail_open_total{tag,cls}`;
- *  2. **探针文件(逐次)** —— `SEMA_FAILOPEN_PROBE=<path>` 在场时逐次追加 `fail-open <tag> <detail>`。
- *     逐次是承重的:同进程多腿时"第二腿起无行"会让「无行=没走兜底」的黑盒断言变成假绿;
- *  3. **一次性 warn(每进程每 tag 一次)** —— 防刷屏。**只有这一件是一次性的**,计数与探针都逐次。
- *
- * ## 它**不**解决的问题(封装不是合法化通道)
- * 词表的 `cls` 只有 `F` 与 `P-DEBT` 两种,**结构性**地把 P/Z 类挡在外面:
- *  - **P 保护型**(权限门/判定词表/凭证/车道选择):正解是 fail-closed,不是"留痕后继续放行"。
- *    确实一时改不动的,才允许以 `P-DEBT` 登记——让债在遥测里显形,而不是让它消失。
- *  - **Z 计量型**(重试/预算/超时/清理范围):正解是归零 + 自己的节流告警
- *    (先例:`boot/reapers.ts` 的 `createThrottledReaperCatch`),不走本封装。
- *
- * ## 词表是闭集
- * {@link FailOpenTag} 由 {@link FAIL_OPEN_TAGS} 的键推导,未登记的 tag 是**编译期错误**——
- * "新 tag 须登记"因此是机器执法的,不靠自觉。新增 tag 同时要在 `docs/FAIL-OPEN-CENSUS.md` 补行。
- *
- * ## 进程级而非注入级
- * 三件套里有两件(一次性 warn、进程计数)天然是**进程**范围的,且真正的兜底臂往往在没有 logger/
- * metrics 句柄的深处(`question.ts` / `elicitation.ts` 全文零观测通道)。所以对外主口是自由函数
- * {@link recordFailOpen},装配层用 {@link installFailOpenRecorder} 把 logger/metrics 接上即可;
- * 装配之前的调用不会丢——探针与 stderr 契约行不依赖注入,计数也照常累加并在装配时继承过去。
- */
 import { appendFileSync } from "node:fs";
-/** 闭集 tag 词表。形=`<repo>.<domain>.<site>`(跨仓同形,便于三仓遥测并表)。 */
 export const FAIL_OPEN_TAGS = {
     "server.run-store.file-hydrate-unreadable": {
         cls: "P-DEBT",
@@ -149,26 +117,12 @@ export const FAIL_OPEN_TAGS = {
         note: "A-057.59:一只 **baseUrl 指向别家主机**(非本部署 `gatewayBaseUrl`)的目录模型**没有** per-model key ⇒ `createPerModelAuthSeat` 回 `undefined`(side-query 面 = core 5.46.0 的 `SideQuerySpec.getApiKeyAndHeaders` 座位;WebFetch 摘要面 = 同一只座位包在 `createPerModelKeyBrain` 里,那面 core 至今无座位)⇒ core 的 `options?.apiKey ?? config.apiKey` 回落**主网关 key**,而同一行下面的 `model.baseUrl || config.baseUrl` 仍把请求路由到那台外部主机 —— 这一次调用真把共享网关凭据发给了运维在 config-center 里指定的另一家。方向明知不对(hook 面对逐字同形的场景是 TRUE fail-closed:「refusing to send the prompt off-gateway」),之所以记债而不是当场收严:该缺席语义与**主推理链**(`dist/engine/harness/agent-harness.js` 的 `auth?.apiKey !== undefined` 臂)逐字同语义,只收严 wrapper 这两面会造成「同一只模型跑任务能用、问一句 401」,且「同账号多网关主机/多区域」是既有且正当的部署形、无旋钮可退。计数覆盖两面(side-query / WebFetch 摘要),`detail` = 模型名。⚠️ 判据需要参照系:调用方没给 `gatewayBaseUrl` ⇒ **不计**(宁可漏计不可错计),故计数是**下限**。终局收口 = 跨面收严件 #309(三面同批 + 旋钮 + 表态制),届时本 tag 同批销。",
     },
 };
-/**
- * 断流丢帧该记哪个 tag —— **按帧型分类**,纯函数(与写流的那条闭包解耦,才单测得动)。
- *
- * 一刀切记同一个 tag 是错的:承载 HITL 帧的那条闭包同时驮着完成面包屑与其它运行流帧,于是**一次**
- * 断连会让保护型计数涨两次(open 一次、complete 又一次),真正的 open 失败率被面包屑的假阳性盖住。
- * 只有 open 帧是"人在环这道门被跳过"的证据,其余都是体验损失。
- *
- * ⚠️ **两条 question 臂在生产上已不可达**(#173 之后,2026-08-07):本函数唯一的生产调用点是
- * `routes/tasks.ts` 的 `emitAsk` 断流臂,而 question 与 question_complete 两型帧都先过同文件
- * `emitQuestion` 的断流守卫(两道守卫同步相邻、其间无 await)并在断流时 throw,永不抵达这里;另一条
- * question 路(`runs.ts` 的 durable append)根本不经 emitAsk。在产的只剩 elicitation 族与 default。
- * 两臂**保留不删**:它们是本映射的语义定义(单测直打的纯函数),elicit 侧若哪天照 question 收紧、或
- * 新增第四条 emit 腿忘了守卫,留着的臂是正确落点而不是死码。读遥测时按上面这段判在产分布。
- */
 export function failOpenTagForDroppedFrame(frameType) {
     switch (frameType) {
-        case "question": // 见头注:#173 后生产不可达(emitQuestion 先 throw),保留为映射定义
+        case "question":
         case "elicitation":
             return "server.hitl.frame-undelivered-stream-closed";
-        case "question_complete": // 同上,生产不可达
+        case "question_complete":
             return "server.question.complete-breadcrumb-dropped";
         case "elicitation_complete":
             return "server.elicitation.complete-breadcrumb-dropped";
@@ -176,9 +130,7 @@ export function failOpenTagForDroppedFrame(frameType) {
             return "server.stream.frame-dropped-stream-closed";
     }
 }
-/** 探针文件的 env 名(跨仓同名同形:`audits/failopen-governance-176.md` §2-r2,壳/引擎同认)。 */
 export const FAIL_OPEN_PROBE_ENV = "SEMA_FAILOPEN_PROBE";
-/** 计数器名。`cls` 进标签:一眼分得出"合法兜底"与"保护型欠账"两种曲线,后者应当只降不升。 */
 const FAIL_OPEN_COUNTER = "fail_open_total";
 export function createFailOpenRecorder(deps = {}) {
     const counts = new Map(deps.seedCounts ?? []);
@@ -189,52 +141,40 @@ export function createFailOpenRecorder(deps = {}) {
     const writeStderr = deps.writeStderr ?? ((line) => void process.stderr.write(line));
     const appendProbe = deps.appendProbe ?? ((path, line) => appendFileSync(path, line));
     deps.metrics?.counter(FAIL_OPEN_COUNTER, "fallback (fail-open) arms traversed, by registered tag — see docs/FAIL-OPEN-CENSUS.md");
-    // 补账:装配前(无 metrics/无 logger)命中的那几次不能凭空消失——否则 `fail_open_total` 永久
-    // 少算,少的还正是 boot 期兜底。metrics 到场即把欠账一次性灌进去并清零(所以再 install 一次不会重放),
-    // 结构化 warn 同理按 tag 补一条。stderr 契约行**不补**:它在装配前就已经喊过了,一 tag 一次是它的全部价值。
-    // 🔴 记账**后于**投递(codex R2 复审 MEDIUM):先清 backlog / 先 `logged.add` 再投递,等于把一次
-    // 投递失败记成"已送达"——欠账从此无法重放,而它保的正是最需要补的那批 boot 期兜底。
     if (deps.metrics !== undefined && backlog.size > 0) {
         for (const [tag, n] of [...backlog]) {
             try {
                 deps.metrics.inc(FAIL_OPEN_COUNTER, { tag, cls: FAIL_OPEN_TAGS[tag].cls }, n);
-                backlog.delete(tag); // 只有真进了汇才销账
+                backlog.delete(tag);
             }
             catch {
-                /* 留在 backlog 里,下一次装配再补 */
             }
         }
     }
-    // 补痕的起算集=**观测到的 tag 全集**(`counts`),不是"stderr 喊成功过的那批"(`warned`)——
-    // 后者在"装配前命中 + stderr 正断裂"这条组合路上恒空,那次兜底的结构化痕迹就永久没了(codex R3)。
     if (deps.logger !== undefined) {
         for (const tag of counts.keys()) {
             if (logged.has(tag))
                 continue;
             try {
                 deps.logger.warn("fail_open", { tag, cls: FAIL_OPEN_TAGS[tag].cls, note: FAIL_OPEN_TAGS[tag].note, backfilled: true });
-                logged.add(tag); // 同上:warn 真发出去才算已报
+                logged.add(tag);
             }
             catch {
-                /* 不记 logged,下一次装配/下一次命中再补 */
             }
         }
     }
     return {
         record: (tag, detail) => {
-            // 三件套逐件独立 try:一件的失败(坏路径的探针文件、抛错的 logger 传输)绝不能让**另外两件**
-            // 也丢,更不能让调用方的兜底臂变成抛错——那等于把"降级"换成"故障",正是本模块要消灭的方向。
             const entry = FAIL_OPEN_TAGS[tag];
             counts.set(tag, (counts.get(tag) ?? 0) + 1);
             if (deps.metrics === undefined) {
-                backlog.set(tag, (backlog.get(tag) ?? 0) + 1); // 记欠账,等 install 补
+                backlog.set(tag, (backlog.get(tag) ?? 0) + 1);
             }
             else {
                 try {
                     deps.metrics.inc(FAIL_OPEN_COUNTER, { tag, cls: entry.cls });
                 }
                 catch {
-                    // 汇在场但这一次没进去 ⇒ 同样记欠账(而不是蒸发),等下一次装配补。
                     backlog.set(tag, (backlog.get(tag) ?? 0) + 1);
                 }
             }
@@ -243,30 +183,23 @@ export function createFailOpenRecorder(deps = {}) {
                     appendProbe(probePath, `fail-open ${tag}${detail !== undefined && detail !== "" ? ` ${detail}` : ""}\n`);
                 }
                 catch {
-                    /* 探针路径不可写(只读盘/权限)⇒ 静默放弃,不牵连本次兜底 */
                 }
             }
-            // 只有**真发出去**才记进 logged —— 没有 logger 时记了,会让日后 install 的补账把这条当成
-            // "已经报过"而跳过,那正是本轮复审要修的漏账形。
             if (deps.logger !== undefined && !logged.has(tag)) {
                 try {
                     deps.logger.warn("fail_open", { tag, cls: entry.cls, note: entry.note, ...(detail !== undefined ? { detail } : {}) });
-                    logged.add(tag); // 记账后于投递:没发出去就不算已报,下一次命中重试
+                    logged.add(tag);
                 }
                 catch {
-                    /* 观测不得成为故障 */
                 }
             }
             if (warned.has(tag))
                 return;
             try {
-                // 跨仓约定的黑盒锚,逐字 `[sema] fail-open: <tag>`。**不依赖** logger 是否装配上——
-                // 评测线的断言打的就是这一行,它在 boot 之前的兜底上也必须成立。
                 writeStderr(`[sema] fail-open: ${tag}\n`);
-                warned.add(tag); // 同上。stderr 永久断裂时代价=每次命中试写一次(有界),不是丢掉这条契约行
+                warned.add(tag);
             }
             catch {
-                /* 断裂的 stderr(EPIPE 族)⇒ 丢这行,不丢进程 */
             }
         },
         counts: () => counts,
@@ -275,16 +208,7 @@ export function createFailOpenRecorder(deps = {}) {
         loggedTags: () => logged,
     };
 }
-/** 进程单例。装配前也可用(探针+stderr 契约行照常,计数照常;只是没有结构化 warn/metric)。 */
 let current = createFailOpenRecorder();
-/**
- * 装配层接线:把 logger/metrics 接到进程单例上。搬四份状态过去,各有各的理由:
- *  - `seedCounts` —— 逻辑总数续算,不从 0 重来;
- *  - `seedWarned` —— boot 期已喊过的 stderr 契约行不再喊(「每进程每 tag 一次」是它的全部价值);
- *  - `seedBacklog` —— 装配**前**命中的次数还没进任何 metrics 汇,交给新实例补账(补完清零,
- *    所以第二次 install 不会重放);
- *  - `seedLogged` —— 已真发出去的结构化 warn 不重发;没发过的由新 logger 补一条。
- */
 export function installFailOpenRecorder(deps) {
     current = createFailOpenRecorder({
         ...deps,
@@ -295,15 +219,12 @@ export function installFailOpenRecorder(deps) {
     });
     return current;
 }
-/** 兜底臂的调用口。`tag` 必须已登记(闭集类型),`detail` 是可选的一行现场(路径/原因,不放密钥)。 */
 export function recordFailOpen(tag, detail) {
     current.record(tag, detail);
 }
-/** 本进程各 tag 累计次数——`/metrics` 之外的进程内读数(测试与自检面用)。 */
 export function failOpenCounts() {
     return current.counts();
 }
-/** test-only:换一个全新单例(计数与 warn 集合清零),让每个用例都从"第一次"看起。 */
 export function resetFailOpenRecorderForTest(deps = {}) {
     current = createFailOpenRecorder(deps);
     return current;

package/dist/observability/logger.js

@@ -1,9 +1,4 @@
 const ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
-// EPIPE hardening (live catch): a host that feeds this engine's stdout through a
-// PIPE and exits first leaves the fd broken — the NEXT log write raises EPIPE. Without a listener
-// that async 'error' event on process.stdout is fatal, which killed drainThenShutdown ON ITS FIRST
-// LOG LINE (the SIGHUP reap never ran). Logs are droppable; the process is not — swallow both the
-// sync throw (try/catch below) and the async 'error' event (no-op listener, attached once).
 let stdioErrorsSwallowed = false;
 function swallowStdioErrors() {
     if (stdioErrorsSwallowed)
@@ -28,7 +23,6 @@ export function createLogger(minLevel = "info") {
             (level === "error" || level === "warn" ? process.stderr : process.stdout).write(line + "\n");
         }
         catch {
-            // Broken/destroyed stream (EPIPE family): drop the line, never the process.
         }
     };
     return {