@sema-agent/server 7.43.0 → 7.44.0

package/dist/fleet-client.js

@@ -1,47 +1,11 @@
-/**
- * Fleet worker-side wiring(announce/heartbeat + usage 批报;契约 = registry-core 0.1.48+
- * `/fleet`,center 端点 = sema-registry `/api/fleet/*`)。设计要点:
- *  - **可选分层(D3)**:仅当 center 已配置(sema-registry lane 的 baseUrl+token+worker)∧ `FLEET_ADVERTISE_ADDRESS`
- *    显式声明时才启动 —— 不配 center 的部署零行为变化。address 不自猜(k8s pod IP / docker alias / 127.0.0.1:port
- *    只有部署环境自己知道,故用显式 env)。
- *  - **announce=注册=心跳同形状幂等 upsert**:boot 后 POST 一次 + 每 heartbeatMs 续;`ready = bootDone ∧ !draining`。
- *  - **draining 翻转即刻再 announce**(第一时间自摘流,比任何观测都快);退出前 DELETE(显式注销,幂等)。
- *  - **usage 批报**:tracer 的 `brain.call` 已带 ALS principal —— FleetUsageAccumulator 按 principal×model
- *    累计,每窗口(默认 60s,半开 [windowStartMs, windowEndMs))POST /api/fleet/usage。幂等键
- *    (worker,instanceId,windowStartMs) 重发安全;**发送失败 → merge 回累计器**,并入下一窗(失败窗从未入账,
- *    向前合并不会双计 —— 只延迟,不丢量)。
- *  - 全部 fire-and-forget + swallow-guarded:fleet 面是运维旁路,绝不影响任务面;网络错误只 warn 一次/连败类。
- */
 import { InstanceAnnouncement, UsageReport, DEFAULT_HEARTBEAT_MS } from "@sema-agent/registry-core/fleet";
-/** Bound on distinct principal×model keys per window — a runaway/multi-tenant burst collapses into
- *  `__other__` instead of growing unbounded (same posture as budget.ts cardinalityGuard). */
 export const FLEET_USAGE_KEY_CAP = 1024;
-/** C1(2026-08-03):announce/usage/deregister 三站点的 fetch 上界(fleet-lease `LEASE_FETCH_TIMEOUT_MS`
- *  同款判据的普适形)。比 lease 的 2500 略宽——这三条不在提交热路径,5s 足以吃掉慢网 RTT,又远小于
- *  undici 默认 ~300s headersTimeout(此前半开 center 把 stop()/心跳各钉住到那个量级)。 */
 export const FLEET_CLIENT_FETCH_TIMEOUT_MS = 5000;
-/**
- * Per-window principal×model usage accumulator, fed from the tracer's `brain.call` hook (which carries the
- * ALS principal — reaches council/team sub-task spend too, same attribution point costQuota uses). Sync,
- * never throws (TracerHook contract).
- */
 export class FleetUsageAccumulator {
-    cells = new Map(); // key = principal <NUL> model
-    runsSeen = new Set(); // taskId per window → runs count (first brain.call of a run in this window)
-    /**
-     * 🔴 RB-368(core 2.3.0;registry-core 0.11.0 收口,[2103]):`d.costMicroUsd` **可缺席 = 未知**
-     * (unpriced 部署,budget.ts 如实不带键)。wire 自 0.11.0 起有缺席位(UsageEntry.costMicroUsd
-     * optional)⇒ 本处**整键透传缺席**,不再折 0 低估。cell 级累加语义与 budget.ts ModelUsageTracker
-     * 同款=**传染**(同为单 producer 累加器:已知+未知=未知);center 聚合面的「下界 + costUnknown
-     * 标记」语义在 registry-core aggregateUsage(跨 worker 审计总账层,两层判据见 [2103])。
-     * 配额轴(weightedTokens)不受影响,仍逐笔精确。
-     *
-     * core 3.0.0([2296] 装车单 S4c)语义注:`d.inputTokens` 在唯一调用点(budget.ts 的
-     * `fleetUsage.record(...)`,S1 已迁)传的是 `e.totalInputTokens`(归一化总输入含 cache),不是
-     * `e.promptTokens`(3.0.0 起恒 cache-MISS)——上游已切换口径,本函数只是照收不重算,值域/签名零改动。
-     */
+    cells = new Map();
+    runsSeen = new Set();
     record(principal, model, taskId, d) {
-        const p = principal ?? "__anonymous__"; // single-user turnkey: no principal — still meter, under a stable bucket
+        const p = principal ?? "__anonymous__";
         let key = `${p}\u0000${model}`;
         if (!this.cells.has(key) && this.cells.size >= FLEET_USAGE_KEY_CAP)
             key = `__other__\u0000__other__`;
@@ -52,11 +16,10 @@ export class FleetUsageAccumulator {
         if (cur) {
             cur.inputTokens += d.inputTokens;
             cur.outputTokens += d.outputTokens;
-            // 缺席=未知 ⇒ 传染(见上方旁注);两边都已知才相加
             cur.costMicroUsd = cur.costMicroUsd === undefined || d.costMicroUsd === undefined ? undefined : cur.costMicroUsd + d.costMicroUsd;
             cur.weightedTokens += d.weightedTokens ?? 0;
             if (d.quotaWeightAtUse !== undefined)
-                cur.quotaWeightAtUse = d.quotaWeightAtUse; // 审计尾迹=最新倍率(窗口内基本恒定)
+                cur.quotaWeightAtUse = d.quotaWeightAtUse;
             if (firstOfRun)
                 cur.runs += 1;
         }
@@ -64,7 +27,6 @@ export class FleetUsageAccumulator {
             this.cells.set(key, { inputTokens: d.inputTokens, outputTokens: d.outputTokens, costMicroUsd: d.costMicroUsd, weightedTokens: d.weightedTokens ?? 0, quotaWeightAtUse: d.quotaWeightAtUse ?? 1, runs: firstOfRun ? 1 : 0 });
         }
     }
-    /** Drain the window into UsageReport entries and RESET. Empty window → []. */
     drain() {
         const out = [];
         for (const [key, c] of this.cells) {
@@ -75,8 +37,6 @@ export class FleetUsageAccumulator {
         this.runsSeen.clear();
         return out;
     }
-    /** Merge a FAILED batch back (delivery error → carry the amounts into the next window; never double-counts
-     *  because the failed window was never recorded center-side). */
     mergeBack(entries) {
         for (const e of entries) {
             let key = `${e.principal}\u0000${e.model}`;
@@ -88,7 +48,7 @@ export class FleetUsageAccumulator {
             if (cur) {
                 cur.inputTokens += e.inputTokens;
                 cur.outputTokens += e.outputTokens;
-                cur.costMicroUsd = cur.costMicroUsd === undefined || e.costMicroUsd === undefined ? undefined : cur.costMicroUsd + e.costMicroUsd; // 回携未知同款传染
+                cur.costMicroUsd = cur.costMicroUsd === undefined || e.costMicroUsd === undefined ? undefined : cur.costMicroUsd + e.costMicroUsd;
                 cur.weightedTokens += w;
                 if (qw !== undefined)
                     cur.quotaWeightAtUse = qw;
@@ -103,9 +63,6 @@ export class FleetUsageAccumulator {
         return this.cells.size;
     }
 }
-/** #123 F1 披露半场(§M):center 的拒绝响应体是操作员唯一的自诊线索(E2E #121:web 端明说了
- *  「address must be a parseable http(s) base URL」而 server 日志只有 `announce 400`)——摘要进错误
- *  信息(cap 200 字符);读体失败不改变结果面(照旧只有状态码)。 */
 async function rejectionSnippet(res) {
     try {
         const text = (await res.text()).slice(0, 200).trim();
@@ -115,10 +72,6 @@ async function rejectionSnippet(res) {
         return "";
     }
 }
-/**
- * Start the worker-side fleet loops. Caller has already gated on "center configured ∧ advertise address set"
- * (startFleetClientFromEnv below) — this function assumes a complete opts.
- */
 export function startFleetClient(opts) {
     const f = opts.fetchImpl ?? fetch;
     const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
@@ -126,7 +79,7 @@ export function startFleetClient(opts) {
     const base = opts.center.baseUrl.replace(/\/+$/, "");
     const headers = { authorization: `Bearer ${opts.center.token}`, "content-type": "application/json" };
     let stopped = false;
-    let failStreak = 0; // warn once per failure streak, not per tick (a down center must not spam logs)
+    let failStreak = 0;
     const announceNow = async () => {
         const body = {
             instanceId: opts.instanceId,
@@ -138,9 +91,6 @@ export function startFleetClient(opts) {
             heartbeatMs,
         };
         try {
-            // 鲁棒性批1 C1(2026-08-03):三条对 center 的 fetch 全部界上 abort(fleet-lease O1 同款判据的
-            // 普适形)——半开 center 下此前各挂 undici 默认 ~300s headersTimeout,stop() 的滚动更新被单个
-            // 半开连接钉住;心跳侧每 tick 叠一个在飞请求。
             const res = await f(`${base}/api/fleet/instances`, { method: "POST", headers, body: JSON.stringify(body), signal: AbortSignal.timeout(FLEET_CLIENT_FETCH_TIMEOUT_MS) });
             if (!res.ok)
                 throw new Error(`announce ${res.status}${await rejectionSnippet(res)}`);
@@ -161,9 +111,9 @@ export function startFleetClient(opts) {
         const windowEndMs = Date.now();
         const entries = opts.usage.drain();
         const start = windowStartMs;
-        windowStartMs = windowEndMs; // half-open [start, end) — the next window starts exactly where this one ended
+        windowStartMs = windowEndMs;
         if (entries.length === 0)
-            return; // nothing accrued — skip the POST entirely
+            return;
         const report = { worker: opts.center.worker, instanceId: opts.instanceId, windowStartMs: start, windowEndMs, entries };
         try {
             const res = await f(`${base}/api/fleet/usage`, { method: "POST", headers, body: JSON.stringify({ reports: [report] }), signal: AbortSignal.timeout(FLEET_CLIENT_FETCH_TIMEOUT_MS) });
@@ -171,12 +121,11 @@ export function startFleetClient(opts) {
                 throw new Error(`usage ${res.status}${await rejectionSnippet(res)}`);
         }
         catch (err) {
-            // Delivery failed → the window was never recorded center-side; carry the amounts forward (no loss, no double).
             opts.usage.mergeBack(entries);
             opts.logger?.warn("fleet_usage_report_failed", { error: err instanceof Error ? err.message : String(err), entries: entries.length });
         }
     };
-    void announceNow(); // boot announce (registration = first heartbeat)
+    void announceNow();
     const hb = setInterval(() => void announceNow(), heartbeatMs);
     hb.unref?.();
     const uw = opts.usage ? setInterval(() => void flushUsage(), usageWindowMs) : undefined;
@@ -188,29 +137,20 @@ export function startFleetClient(opts) {
         clearInterval(hb);
         if (uw)
             clearInterval(uw);
-        await flushUsage(); // final partial window — best-effort
+        await flushUsage();
         try {
             await f(`${base}/api/fleet/instances`, { method: "DELETE", headers, body: JSON.stringify({ instanceId: opts.instanceId, worker: opts.center.worker }), signal: AbortSignal.timeout(FLEET_CLIENT_FETCH_TIMEOUT_MS) });
         }
         catch {
-            /* deregistration is best-effort — staleness (2× heartbeatMs) reaps us anyway */
         }
     };
     return { announceNow, stop };
 }
-/**
- * Env/config gate (D3 可选分层): start ONLY when the sema-registry lane is configured (baseUrl+token+worker)
- * AND the operator explicitly declared this instance's reachable address. Anything missing → undefined (zero
- * behavior change for non-fleet deployments); worker missing is warned when the rest is present (half-configured).
- */
 export function startFleetClientFromEnv(cfg, opts) {
     const cc = cfg.configCenter;
     const address = opts.advertiseAddress ?? process.env.FLEET_ADVERTISE_ADDRESS;
     if (!cc?.baseUrl || !cc.token || !address)
         return undefined;
-    // #123 F1(E2E #121 立案):旋钮**设了但坏形** ≠ 没设——center 端要求可解析的 http(s) base URL,
-    // 坏形(如缺 scheme 的 host:port)此前静默通过,启动后 fleet 腿每拍 announce 400、worker 永不注册。
-    // env fail-loud 族判据([2443] A1 同族):这里前置响亮拒,部署在起点就失败可见,而不是带病运行。
     let parsed;
     try {
         parsed = new URL(address);

package/dist/fleet-lease.js

@@ -1,48 +1,17 @@
-/**
- * Fleet worker-side QUOTA-LEASE consumption(调度框架 D4=AP 模式的 worker 半场;
- * 契约 = registry-core `/fleet` QuotaLease + center `POST /api/fleet/leases`,center 侧已实装并经
- * chaos 测试验证)。
- *
- * ## 模型(roaming/CDN)
- * center 把某 principal 全局预算的一片(默认 $5 slice / 1h TTL)预授权给 ONE worker;worker 本地扣减
- * (`recordSpend`,零 per-call 往返),`shouldRenewLease`(任一维度 80% 或寿命 80%)提前后台续租;center 用
- * usage 批报事后单调对账(`/api/fleet/usage` 入库顺手 reconcile —— worker 不需要单独上报 consumed)。
- *
- * ## 协商式发现(谁走 lease?)
- * worker 不在本地解析 EntitlementBudget —— 首次 admit 向 center POST,center 用 resolveEntitlement 判:
- *   - 200 {lease}                     → 该 principal 是 lease-enforced,进入本地扣减周期;
- *   - 409 "principal is not lease-enforced" → 负缓存 {@link NOT_LEASE_TTL_MS},走既有本地 CostQuota 路径;
- *   - 409 `code:"quota_exhausted"`    → 提交拒绝(429,镜像 quotaExceeded 姿势),短缓存防打爆 center;
- *   - 网络/5xx                        → **fail-open 放行**(AP 哲学:center 短暂不可达绝不停集群;对账兜底,
- *                                       过花敞口 ≤ slice 尺寸 —— 正是 D4 承诺的 trade)。
- * 单飞(single-flight):同 principal 并发首触/续租只发一个 RTT。
- *
- * ## 边界(documented,非疏漏)
- * - lease 状态 **in-memory**:worker 重启丢本地 consumed → center 续租时用 reports+monotone guard 补账,
- *   敞口同样 ≤ slice(AP 设计内)。
- * - 409 判别靠 center 返回的结构化 code(两端常量);center 侧变更时此处同步。
- * - 全部 swallow-guarded:lease 面绝不 fault 任务提交路径。
- */
 import { QuotaLease, leaseExhausted, shouldRenewLease } from "@sema-agent/registry-core/fleet";
-/** 负缓存 TTL:非 lease-enforced 的 principal 多久后再问一次 center(entitlement 升级为 lease 的收敛上界)。 */
 export const NOT_LEASE_TTL_MS = 10 * 60 * 1000;
-/** center 判 budget exhausted 后,多久内的重复提交直接拒绝而不再打 center(防 per-request 打爆)。 */
 export const EXHAUSTED_RETRY_MS = 30 * 1000;
-/** principal 状态表上界(镜像 FLEET_USAGE_KEY_CAP 的姿势):超界丢最旧 —— 被丢的 principal 下次 admit
- *  重新协商,一次多余 RTT,无正确性影响。 */
 export const LEASE_PRINCIPAL_CAP = 4096;
-/** 复审 O1:lease 协商 RTT 的硬上限——leaseDenied 在提交热路径同步 await 它,一个 accept-but-hang 的
- *  center 必须迅速塌成 fail-open 而不是拖垮提交。取 2.5s(远小于任何续租余量,略紧于 registry 的 8s)。 */
 export const LEASE_FETCH_TIMEOUT_MS = 2500;
 export class FleetLeaseManager {
     opts;
     state = new Map();
-    inflight = new Map(); // single-flight issue/renew per principal
+    inflight = new Map();
     f;
     base;
     headers;
     now;
-    failStreak = 0; // warn once per outage streak (mirrors fleet-client)
+    failStreak = 0;
     constructor(opts) {
         this.opts = opts;
         this.f = opts.fetchImpl ?? fetch;
@@ -50,10 +19,6 @@ export class FleetLeaseManager {
         this.headers = { authorization: `Bearer ${opts.center.token}`, "content-type": "application/json" };
         this.now = opts.now ?? Date.now;
     }
-    /**
-     * Admission check for one billed submission. Fast path is synchronous-shaped (live lease / fresh negative
-     * cache → no await beyond the microtask); only first-touch / expiry / exhaustion pays a center RTT.
-     */
     async admit(principal) {
         const now = this.now();
         const st = this.state.get(principal);
@@ -63,24 +28,12 @@ export class FleetLeaseManager {
             return { ok: false, reason: "budget_exhausted", retryAfterSec: Math.ceil((st.until - now) / 1000), ...(st.detail ? { detail: st.detail } : {}) };
         }
         if (st?.kind === "lease" && !leaseExhausted(st.lease, now)) {
-            // Renew EARLY in the background so the refresh RTT overlaps remaining headroom (never blocks a call).
             if (shouldRenewLease(st.lease, now))
                 void this.issueOrRenew(principal).catch(() => undefined);
             return { ok: true };
         }
-        // No usable state → negotiate with center (single-flight; blocks THIS submission only).
         return this.issueOrRenew(principal);
     }
-    /** Local deduction — wired at the SAME tracer `brain.call` point as the usage accumulator (ALS principal),
-     *  sync + never throws (TracerHook contract). No-op unless the principal currently holds a lease.
-     *  registry-core 0.6.1 双轴:weightedTokens(加权 tokens 配额轴,weight-at-burn 已在调用方固化)
-     *  + costMicroUsd($ 轴,轴名沿用 0.5 既定)。任一轴耗尽=leaseExhausted 拒(deny-wins,registry 类型层定死)。
-     *
-     *  🔴 RB-368(core 2.3.0)已核 undefined 安全:两轴都是 `?? 0`,unpriced 部署下 budget.ts 不带
-     *  costMicroUsd 键调进来 ⇒ $ 轴不扣、不产 NaN。**这是有意的 fail-open**:租约是**执行面**,把"未知"
-     *  当"扣满"会让没配价目表的部署一上来就被 leaseExhausted 拒掉所有请求(deny-wins),那是把可观测性
-     *  缺口升级成可用性事故。补偿=配额轴(weightedTokens)不依赖价目表、逐笔精确,治理在 unpriced 部署下
-     *  仍然咬得住;$ 轴对这类部署等于未启用,这一点在部署位 `capabilities.pricingConfigured` 上可读回。 */
     recordSpend(principal, d) {
         if (!principal)
             return;
@@ -90,16 +43,15 @@ export class FleetLeaseManager {
         st.lease.consumed.weightedTokens += d.weightedTokens ?? 0;
         st.lease.consumed.costMicroUsd += d.costMicroUsd ?? 0;
     }
-    /** Test/observability hook: the current state kind for a principal (never exposes the token). */
     peek(principal) {
         return this.state.get(principal)?.kind;
     }
     set(principal, st) {
         if (!this.state.has(principal) && this.state.size >= LEASE_PRINCIPAL_CAP) {
-            const oldest = this.state.keys().next().value; // insertion order ≈ LRU-enough for a cap backstop
+            const oldest = this.state.keys().next().value;
             this.state.delete(oldest);
         }
-        this.state.delete(principal); // re-insert at tail
+        this.state.delete(principal);
         this.state.set(principal, st);
     }
     issueOrRenew(principal) {
@@ -112,11 +64,6 @@ export class FleetLeaseManager {
     }
     async issueOrRenewInner(principal) {
         try {
-            // 🔴 复审 O1(Opus,3 镜头独立命中):BOUND the negotiation RTT. leaseDenied awaits this on the SUBMISSION
-            // hot path (11 sites), so a center that ACCEPTS the TCP connection but never responds (brownout/half-open LB —
-            // exactly the outage AP is meant to ride out) would otherwise hang up to undici's ~300s default headersTimeout
-            // before the fail-open catch fires, stalling every first-touch/expired principal's submissions. A short abort
-            // lands in the catch below → prompt fail-open. Matches the codebase's outbound-to-center timeout convention.
             const res = await this.f(`${this.base}/api/fleet/leases`, {
                 method: "POST",
                 headers: this.headers,
@@ -125,7 +72,7 @@ export class FleetLeaseManager {
             });
             if (res.status === 200) {
                 const body = (await res.json());
-                const lease = QuotaLease.parse(body.lease); // zod — a malformed center response fails into the catch (fail-open)
+                const lease = QuotaLease.parse(body.lease);
                 this.set(principal, { kind: "lease", lease });
                 if (this.failStreak > 0)
                     this.opts.logger?.info?.("fleet_lease_recovered", { after: this.failStreak });
@@ -135,16 +82,8 @@ export class FleetLeaseManager {
             }
             if (res.status === 409) {
                 const body = (await res.json().catch(() => ({})));
-                // 🔴 复审 O3(Opus):discriminate on a POSITIVE exhaustion match; ANY OTHER 409 (incl. a reworded
-                // not-lease-enforced, or an unforeseen refusal) defaults to the PASS-THROUGH direction — a center wording
-                // drift must not flip legitimate traffic into repeated 429 denial. Failing OPEN on an ambiguous 409 keeps
-                // the AP posture (the local CostQuota path still governs); denying is reserved for an explicit exhaustion.
-                // typed 唯一语义:`code==="quota_exhausted"`(E4 定稿 typed code)。旧常量
-                // `error:"budget exhausted"` 的过渡 fallback 已删——center 侧旧常量已撤,该 fallback 成死分支,已删净。
                 if (body.code === "quota_exhausted") {
                     const until = this.now() + EXHAUSTED_RETRY_MS;
-                    // E4 结构化字段(windowType/remaining/resetAt/isEstimate/pool)verbatim 缓存进 exhausted 态——
-                    // EXHAUSTED_RETRY_MS 窗内的重复提交拒绝也带同一 detail(不再打 center),429 body 透传归 HTTP 层。
                     const detail = {
                         ...(body.windowType !== undefined ? { windowType: body.windowType } : {}),
                         ...(body.remaining !== undefined ? { remaining: body.remaining } : {}),
@@ -157,16 +96,9 @@ export class FleetLeaseManager {
                     this.opts.metrics?.inc("fleet_lease_exhausted_total");
                     return { ok: false, reason: "budget_exhausted", retryAfterSec: Math.ceil(EXHAUSTED_RETRY_MS / 1000), ...(hasDetail ? { detail } : {}) };
                 }
-                // not-lease-enforced (the common case) OR any other 409 → local CostQuota path governs this principal.
                 this.set(principal, { kind: "not-lease", until: this.now() + NOT_LEASE_TTL_MS });
                 return { ok: true };
             }
-            // 🔴 复审 O2(Opus):an auth/config error (401/403/400) is operator MISCONFIG (expired service token, wrong
-            // worker id, URL drift) — NOT an availability event. Failing open silently would disable budget enforcement
-            // indefinitely (a stealth bypass) with only a once-per-streak warn. Fail open STILL (never lock a tenant out
-            // on a token blip) but make it LOUD + observable: a dedicated metric + a warn EVERY occurrence (not deduped),
-            // and DON'T cache — so a persistent misconfig re-warns on every admit and can't hide. No negotiated state is
-            // recorded, so recovery is immediate once the config is fixed.
             if (res.status === 401 || res.status === 403 || res.status === 400) {
                 this.opts.logger?.warn?.("fleet_lease_auth_error_fail_open", { status: res.status, principal, note: "center rejected the lease request — check the service token / worker id / center URL (budget NOT enforced until fixed)" });
                 this.opts.metrics?.inc("fleet_lease_auth_error_total", { status: String(res.status) });
@@ -175,7 +107,6 @@ export class FleetLeaseManager {
             throw new Error(`lease ${res.status}`);
         }
         catch (err) {
-            // center unreachable / 5xx / timeout / malformed → FAIL-OPEN (AP posture): admit, keep whatever state we had.
             this.failStreak += 1;
             if (this.failStreak === 1)
                 this.opts.logger?.warn?.("fleet_lease_unavailable_fail_open", { error: err instanceof Error ? err.message : String(err) });
@@ -184,11 +115,6 @@ export class FleetLeaseManager {
         }
     }
 }
-/**
- * Env/config gate(与 startFleetClientFromEnv 同 D3 分层姿势,但 lease 不需要 FLEET_ADVERTISE_ADDRESS ——
- * 它是出站消费面,不是入站可达性声明):sema-registry lane 配齐(baseUrl+token+worker)即启;任一缺失 →
- * undefined,非 fleet 部署零行为变化。
- */
 export function createFleetLeaseFromEnv(cfg, opts) {
     const cc = cfg.configCenter;
     if (!cc?.baseUrl || !cc.token || !cc.worker)

package/dist/git-api-kind.js

@@ -1,6 +1,3 @@
-/** Git-host API dialect word table (P1-2). Leaf module — the single owner shared by the config layer
- *  (env parse/validation) and `capabilities/repo-tools` (the two client implementations); config must not
- *  value-import the capabilities layer (module-cycle gate §G), so the table lives below both. */
 export const GIT_API_KINDS = ["gitea", "github"];
 export function isGitApiKind(v) {
     return typeof v === "string" && GIT_API_KINDS.includes(v);

package/dist/governance-ask-marks.js

@@ -1,76 +1,6 @@
-/**
- * [2942]/[2943] `governanceForced` 的**判定缝** —— operator 治理层产的 ask 在 server 进程内的标记通道。
- *
- * 🔴 为什么需要一条 out-of-band 通道(侦察结论,亲验装树 core dist;5.16.x 首次落笔,5.23.0 复核仍成立):
- * `PermissionResult.decisionReason`(闭集,词表以 core 的 `DecisionReason` 为准 —— 本文**刻意不复述**那
- * 张表:复述出来的词表会随 core 加员静默过期,而这段话的论点与表里有几个词无关)**到不了帧铸点**。
- * core 在 `dist/core/runner/prepare-task.js` 的 ask 铸造点(`resolveAsk({...})`,三处继承臂 + 主臂)只把
- * `toolName / toolCallId / args / preview / message / askSourceIdentity() / riskAxesOf() / requiresRealApproval`
- * 装进 `AskRequest`;`decisionReason` 连同整个 `PermissionResult` 一起留在 core 内部。`AskRequest` 的类型面
- * (`dist/core/tool-policy.d.ts:78`)也确认没有这个键。所以「映射 decisionReason ⇒ governanceForced」这条
- * 缝在**当前 core 上不存在**——它不是没接线,是没有这个字段可读。
- * ([3372] 提货批复核)core 5.23.0 给这个闭集加了 `org_rule` / `org_unavailable` 两个**治理来源**的词
- * (design/182 org 层)。这看着像是本表终于有了上游判据,其实**不是**:①`AskRequest` 的类型面在 5.23.0
- * 上逐字未变,那两个词仍然到不了帧铸点(缝还是不存在);②即便够得着,它们说的是**组织**发布的快照,
- * 与本键的语义(**本部署运维治理层**产的 ask)不是一回事,直接映射会把两种来源混成一个标记。本仓无
- * org 层装配口(`ToolGateInput.orgRules` 无声明点),该臂当前不可达。
- *
- * 另一侧同样不可用:`riskAxes.irreversible` 在 shellGate 上场时对**每一次** shell 调用都为真(core
- * `prepare-task.js:1620-1631` 无条件 `irreversibilityTier.set("Bash"/"Monitor", …)`),与「这只 ask 是谁
- * 提的」无关;`requiresRealApproval` 的生产者是 core 自己的两条安全策略(unverifiable-delete /
- * transcript-integrity),与治理层无关。两者都不是判据。
- *
- * ⇒ 采用的方案 = **server 标记自家产物**:治理层策略(`runtime-governance.ts` 的
- * `applyRuntimeGovernance`)在合成时被包一层观察器,自己产 `ask` 时把该次调用的 `toolCallId` 记进本表;
- * 帧铸点(`tool-approval.ts` 的 `askBroadcast`)按 `toolCallId` 回查。
- * **禁把信号藏进 message 文本**——那是 in-band hack,消费端只能靠正则猜。
- *
- * ## 三条硬语义
- *
- * 1. **只做正向断言**。命中 = 有直接证据(治理策略本人产的 ask,或治理层把 shellGate 抬到 `"always"` 后
- *    的 shell 调用——该档下每一次 shell 调用都被治理层门住,推断是紧的)。**未命中 ≠ 「不是治理」**,
- *    只是「没有证据」⇒ wire 上键**缺席**,绝不编一个 `false`。宁可漏标,不可错标:一个错标会把运维支去
- *    翻一份根本没门住这只 ask 的治理配置。
- * 2. **peek,不 consume**。同一 `toolCallId` 可能被广播两次(重试 / failover / 闭包再入,见
- *    `tool-approval.ts` 里 `pendingByAskId` 的顶注),消费式读会让第二帧莫名丢键。
- * 3. **有界**。写入点是每一次工具调用,读取点只在 ask 上——未被读到的标记(调用被放行 / 被别的策略 deny)
- *    必须能自己老化掉。按插入序淘汰最旧的(`Set` 的迭代序 = 插入序)。
- *
- * ## 作用域:按**审批 broker key** 分格,不是进程级一锅烩
- *
- * 🔴 codex 交叉复审 round3 [medium](验真):`toolCallId` **不是**全局唯一的 —— 它多数情况下是**提供方**
- * 逐字给的 id(core 的 brain 层不另铸),本仓自己的代码就是这么假设的:core 把 tool-result 引用命名成
- * `tr_<sessionId>~<toolCallId>~<contentSeg>`(core 5.26.0 #119 起的四段单射形;见 `plugins/tool-result-store-sql.ts`
- * 的 `deleteBySession` 顶注),
- * `deriveAskId` 也把 `sourceTaskId`/`runId`/`legKey` 一并入哈希。一张不分格的表会**跨任务/跨租户串味**:
- * 低熵 id(本地/自建模型服务常见的 `call_1` 之类)下,A 任务的治理标会被 B 任务的普通 ask 读走(假出处),
- * 或被 B 的一次治理放行反手清掉(丢真出处)。
- *
- * 分格用的 **scope = 审批协调器的 broker key**(`["session", owner, sessionId]` / `["adhoc", owner, taskId]`)。
- * 选它的理由是**两侧都够得到、且是同一个值**:
- *  · 写侧(治理策略的观察器跑在 core 的 `policy.check` 里,入参只有 `ToolCallRequest`)⇒ 经
- *    AsyncLocalStorage 拿 —— 作用域由 `runWithContext` 与审批 ctx **同拍**进出。
- *  · 读侧(`askBroadcast`)⇒ 由 `origin`/`primary` **显式算出**同一把 key。
- *
- * 🔴 读侧**显式算**而不是也读 ALS(codex 交叉复审 round5 [medium],红先复现后改的形):委派/长命 bg 子代
- * 的 ask 可能在**另一条腿**的上下文里发出(宿主腿退场、壳重连出新腿,子代的卡落到新腿的流上)。读侧若取
- * 环境里的那张表,拿到的是**新腿**的空表,信号静默丢失 —— 那条路径已由
- * `test/governance-forced-signal.test.ts` 的「长命 bg 子代形」用例钉住(改形前它是红的)。scope 由**出处**
- * 决定、与卡投递到哪条连接无关,与本仓 `AskOriginIdentity` 顶注「投递面与出处面是两件事」同源。
- *
- * 残余(成文):同一 (owner, sessionId) 下的**并发多 run** 共用一格 —— 那正是 broker 自己的分组粒度
- * (卡本来就跨该会话投递),同租户同会话内的 id 碰撞才会互串,比进程级一锅烩窄得多。要再窄需要一个
- * 写侧也够得到的 run 级身份,core 的 `ToolCallRequest` 今天给不出。
- */
 import { AsyncLocalStorage } from "node:async_hooks";
-/** 默认表容量(全进程合计,复合键计数)。一次 turn 的工具调用数远小于此;满表淘汰的是最旧的标记
- *  (那些早已不可能再被读到)。 */
 const DEFAULT_MAX_MARKS = 1024;
-/** 复合键。JSON 元组编码(同 `streamKey`/`sessionAllowKey` 先例):任何一段里含分隔符都不可能与下一段
- *  的边界产生歧义 —— 一个精心构造的 sessionId 因此无法伪造出另一格。 */
 const compositeKey = (scope, toolCallId) => JSON.stringify([scope, toolCallId]);
-/** 一张独立的标记表(不进程共享)。生产路径用的是下面 `governanceAskMarksFor` 给出的**分格视图**;
- *  本工厂给测试(与将来的多实例形)一个不依赖任何环境的干净表。 */
 export function createGovernanceAskMarks(opts) {
     return createScopedView(new Set(), "", Math.max(1, Math.floor(opts?.max ?? DEFAULT_MAX_MARKS)));
 }
@@ -78,12 +8,11 @@ function createScopedView(marks, scope, max) {
     return {
         setMarked(toolCallId, marked) {
             if (typeof toolCallId !== "string" || toolCallId === "")
-                return; // 无身份 ⇒ 无从回查,不占格
+                return;
             const key = compositeKey(scope, toolCallId);
-            // 重标记要**刷新新鲜度**:先删后加把它挪到插入序尾部,免得一只长命的 ask 被自己后来的调用挤掉。
             marks.delete(key);
             if (!marked)
-                return; // 覆写成「不是治理门」= 清格(setMarked 顶注:复查路径的陈旧标)
+                return;
             marks.add(key);
             while (marks.size > max) {
                 const oldest = marks.values().next();
@@ -109,20 +38,15 @@ function createScopedView(marks, scope, max) {
         },
     };
 }
-/** 进程级底表(分格由复合键承担,见顶注「作用域」段)。 */
 const processMarks = new Set();
-/** 写侧的 scope 载体 —— 由 `ToolApprovalCoordinator.runWithContext` 与审批 ctx 同拍进出。 */
 const scopeAls = new AsyncLocalStorage();
-/** 进入一条 run 腿的标记作用域(唯一调用点 = `ToolApprovalCoordinator.runWithContext`)。 */
 export function runWithGovernanceAskScope(scope, fn) {
     return scopeAls.run(scope, fn);
 }
-/** **写侧**入口:当前异步作用域那一格的视图;作用域外 = `undefined`(写 no-op,见顶注)。 */
 export function currentGovernanceAskMarks() {
     const scope = scopeAls.getStore();
     return scope === undefined ? undefined : createScopedView(processMarks, scope, DEFAULT_MAX_MARKS);
 }
-/** **读侧**入口:按**显式** scope 取视图(读侧不读 ALS —— 理由见顶注 round5 那段)。 */
 export function governanceAskMarksFor(scope) {
     return createScopedView(processMarks, scope, DEFAULT_MAX_MARKS);
 }

package/dist/hooks/branch-transcript.js

@@ -1,47 +1,5 @@
-/**
- * 把 core 的 `StopHookContext.getBranch()` 交出来的 **entries** 渲染成评估者能读的 transcript。
- *
- * ── 为什么渲染这件事本身带一条安全判据 ──────────────────────────────────────────────────────────
- * CC 的条件评估提示词里有这一句(我从语料逐字核过,见 `cc-stop-prompt.ts`):
- *   > If the transcript does not contain clear evidence that the condition is satisfied, return
- *   > `{"ok": false, "reason": "insufficient evidence in transcript"}`.
- * 而 Stop 钩子的 `ok:false` = **拦住停止**。
- * ⇒ **证据面为空时,一个完全守规矩的模型会给出一个格式良好的「拦」** —— 那不是解析失败(解析会成功、
- *   判词有效),所以任何解析层的防线都救不了。**唯一的防线是不进这条路。**
- *
- * 🔴 判据必须挂在**真正决定结果的那个量**上,也就是**最终送进模型的那段文本**,
- * **不是**挂在 `getBranch` 这个访问器的存在性上(core 黑板 [1758] 指出我原设计挂错了位置):
- *  · `getBranch` 在、返回 `[]` —— 结构上可能(还没产出条目的分支);
- *  · 更常见的一格:**渲染之后为空** —— entries 有,但我这边的过滤条件一条都没命中,
- *    或预算把它截没了。**那是纯自伤,而且每一层看起来都正常。**
- * ⇒ 所以本模块的返回类型是**判别式**的(`sufficient: true | false`),而不是"返回一个字符串,
- *   调用方自己记得判空" —— 后者迟早会有人忘。
- *
- * ── 截断的第二个坑(同源) ──────────────────────────────────────────────────────────────────────
- * **静默截断会自己制造「证据不足」**:证据在被截掉的那一段里,模型如实回 `ok:false` ⇒ 拦。
- * ⇒ 截断时必须在文本里**明说截了**,让模型知道自己看到的是一个后缀,而不是全部。
- */
 import { redactSecrets } from "../trace/redact.js";
-/**
- * ── [2092] 渲染臂的判据:**证据面与模型所见同进同出** ─────────────────────────────────────────────
- * core 的 `SessionTreeEntry` 是 12 型联合,曾经这里只渲 message/compaction 两支 ⇒ 10 型静默丢弃。
- * 其中 `custom_message` 正是非标准入口用户内容(steering)的落点:core `convertToLlm` 把它按
- * `role:"user"` 送模型,而证据面渲没了 ⇒ 评估者如实判「证据不足」⇒ 拦停死循环直到 CAP(cli 带
- * 最小复现的真缺陷)。所以分类规则不是「渲会话内容」,而是:**模型看得见的必须在,看不见的必须不在**。
- *
- * 两张表 = 对 core 型全集的**显式全分类**;test/branch-transcript.test.ts 里的闭合钉从 core d.ts
- * 逐字取联合成员核对「型全集 = 渲染臂 ∪ 跳过表」—— core 加第 13 型 ⇒ 红,逼一次显式分类,
- * 默认可见(下面循环的 default 臂做通用文本抽取)而不是默认失踪。
- */
 export const RENDERED_ENTRY_TYPES = ["message", "compaction", "custom_message"];
-/**
- * 跳过的理由逐型给(「纯控制型」不是一句话,是逐个核过模型看不见):
- * thinking_level_change / model_change / label / session_info / leaf / prompt_epoch /
- * announced_listing / workspace_state / git_announcement / reminder_mark —— 控制面元数据,core 折
- * messages 时不产出内容;
- * custom —— data-only(session.js 折 messages 只认 message/custom_message 两型),模型看不见它的
- * data;把它渲出来反而是把模型没见过的东西冒充成证据,与 [2092] 是同一判据的反方向。
- */
 export const SKIPPED_ENTRY_TYPES = [
     "thinking_level_change",
     "model_change",
@@ -51,24 +9,11 @@ export const SKIPPED_ENTRY_TYPES = [
     "prompt_epoch",
     "announced_listing",
     "workspace_state",
-    // core 5.36.0(env-tail 迁移):git-status 帧的**已通告态**快照条目(`{kind,hash,entryId?,pending?}`)。
-    // 与上面两位同族、同理由 —— 它是控制面的「模型上次被展示的是哪一份 git 视图」记号,**不是**模型看见的
-    // 内容:真正被看见的那份帧正文骑在它 `entryId` 指的那条 `message` 上(已由渲染臂收下)。把这条快照渲进
-    // 证据面 = 把一串 sha256 摘要当成对话冒充给评估者,正是 [2092] 判据的反方向。
     "git_announcement",
-    // core 5.46.0(design/319 A 件):会话的**提醒出处标记**条目(`{type:"reminder_mark", mark}`)。同族
-    // 控制面元数据 —— 它是「本会话的引擎提醒/系统提示声明用的是哪一枚 mark」的记号,模型看见的是**别处**
-    // 那些带 mark 的提醒正文本身(已由渲染臂按 message 收下),这条条目本身从不进 `convertToLlm`。
-    // 把一枚不透明 token 渲进证据面 = 拿模型没见过的东西冒充证据([2092] 判据的反方向)。
     "reminder_mark",
     "custom",
 ];
-/** 单次评估送进模型的 transcript 字符上限。超出保留**尾部**(最近的对话对"条件是否已达成"更相关)。 */
 export const BRANCH_TRANSCRIPT_MAX_CHARS = 60_000;
-/** content(string | 片段数组)→ 可读文本。只取 text 片段;image/工具结果等非文本片段不进 transcript。
- *  已登记的残余窄形(F5,2026-07-30 复审):core `toNormalizedTextBlock` 会把混进 content 的非法块
- *  文本化成 `[normalized] {json}` 送模型,证据面这里丢弃 —— 模型可见/证据缺席方向的缺口,但触发
- *  前提是非标准块混进 custom content(上游产生面不可达);若上游真出现该形,闭合钉/评估者误拦会先暴露。 */
 function contentText(c) {
     const parts = [];
     if (typeof c === "string")
@@ -82,11 +27,6 @@ function contentText(c) {
     }
     return parts.join("\n").trim();
 }
-/**
- * `role:"bashExecution"` 消息(`!` 命令)→ 模型所见文本。镜像 core `bashExecutionToText`
- * (dist/engine/harness/messages.js —— core 根不导出,本地镜像,锚在闭合钉+本注上):
- * convertToLlm 把它按 `role:"user"` 送模型,除非 `excludeFromContext`(那时模型看不见 ⇒ 证据面也不该有)。
- */
 function bashExecutionText(m) {
     if (m["excludeFromContext"])
         return undefined;
@@ -99,25 +39,17 @@ function bashExecutionText(m) {
         text += `\n\nCommand exited with code ${String(m["exitCode"])}`;
     return text;
 }
-/** 从一条 message entry 里抽人类可读文本。 */
 function messageText(entry) {
     const m = entry.message;
     if (!m || typeof m.role !== "string")
         return undefined;
     if (m.role === "bashExecution") {
         const text = bashExecutionText(m)?.trim();
-        // convertToLlm 对 bashExecution 的送模型 role 是 "user" —— 证据面同款,别让评估者猜生僻 role。
         return text ? { role: "user", text } : undefined;
     }
     const text = contentText(m.content);
     return text ? { role: m.role, text } : undefined;
 }
-/**
- * 渲染成 transcript。
- *
- * ⚠️ **compaction 的 summary 也算证据**:一次压缩之后,早期内容**只**活在那段摘要里 ——
- * 把它滤掉等于亲手制造「证据不足」(而那正好会被判成"拦")。
- */
 export function renderBranchTranscript(entries, opts) {
     if (!entries || entries.length === 0)
         return { sufficient: false, reason: "no-entries" };
@@ -136,8 +68,6 @@ export function renderBranchTranscript(entries, opts) {
             continue;
         }
         if (e.type === "custom_message") {
-            // [2092] 真缺陷的落点:steering 等非标准入口的用户内容。core convertToLlm 把它按 role:"user"
-            // 送模型(display 只管 UI,不改模型可见性)—— 证据面同进同出,渲成 user 行。
             const text = contentText(e.content);
             if (text)
                 lines.push(`user: ${text}`);
@@ -145,8 +75,6 @@ export function renderBranchTranscript(entries, opts) {
         }
         if (SKIPPED_ENTRY_TYPES.includes(e.type))
             continue;
-        // default 臂:比我们的分类表更新的型(core 加了第 13 型、部署窗里还没重新分类)——
-        // **默认可见而不是默认失踪**:通用文本抽取,能抽出来就带型标渲出;闭合钉会在 CI 红,逼显式分类。
         const generic = contentText(e.content ?? e.text);
         if (generic)
             lines.push(`[${e.type}] ${generic}`);
@@ -154,11 +82,9 @@ export function renderBranchTranscript(entries, opts) {
     if (lines.length === 0)
         return { sufficient: false, reason: "nothing-renderable" };
     const max = opts?.maxChars ?? BRANCH_TRANSCRIPT_MAX_CHARS;
-    // UNTRUSTED:transcript 是会话内容,与 fleet 行 / workflow 名同一条脱敏纪律。
     let text = redactSecrets(lines.join("\n\n"));
     let truncated = false;
     if (text.length > max) {
-        // 保留**尾部**;并**明说截了** —— 静默截断会让模型把"证据在被截掉那段里"如实报成"证据不足" ⇒ 拦。
         text = `[earlier turns omitted — this transcript is truncated to the most recent portion]\n\n${text.slice(text.length - max)}`;
         truncated = true;
     }