@sema-agent/server 1.323.0 → 2.0.0

package/dist/fleet/subagent-tail-bus.d.ts

@@ -1,14 +1,25 @@
+/** wire 帧(SSE data 载荷)。`lagged`(慢消费丢帧标记)与 `task_settled`(中途终态信号,复审 #3:
+ *  三条 run 腿的 onTaskNotification 观察者顺手 publish——订阅期间子代 settle 不再只剩 heartbeat 永挂,
+ *  路由收到即写帧收流)是本总线自己的帧(非 core 事件)。`task_settled` 自 core 1.373 起携可选
+ *  `seq`(settle 铸的 stop-cycle 世代号,TaskNotificationPayload.seq 透传)——流上实时拿到「第 N 世代
+ *  终结」,与 meta 帧的 seq(durable 终态跨实例 serve 时在场)成套。 */
 export type SubagentTailFrame = Record<string, unknown> & {
     type: string;
 };
+/** core forward 事件 → wire 投影(sync 主流五分支同源;不认识的帧类型=null 不发——tail 面只承诺
+ *  content 五类,新 core 帧类型先经这里显式收编再出 wire)。 */
 export declare function projectTailFrame(e: Record<string, unknown> & {
     type?: string;
 }): SubagentTailFrame | null;
 export declare class SubagentTailBus {
     private readonly subs;
+    /** 两条 run 腿的 fwdInternals 调用点:帧已投影(projectTailFrame),null 不进来。 */
     publish(bgAgentId: string, frame: SubagentTailFrame): void;
+    /** 有无订阅者(publish 侧的免投影快门:没人听就不投影)。 */
     hasSubscribers(bgAgentId: string): boolean;
     subscribe(bgAgentId: string): AsyncIterableIterator<SubagentTailFrame>;
 }
+/** 进程单例(defaultTaskRegistry 同款姿势):bus 语义本就是进程内 replica-local,两条 run 腿与路由
+ *  直接 import,不穿长参数列表;测试自 new 独立实例。 */
 export declare const defaultSubagentTailBus: SubagentTailBus;
 //# sourceMappingURL=subagent-tail-bus.d.ts.map

package/dist/fleet/subagent-tail-bus.js

@@ -1,6 +1,30 @@
+/**
+ * SubagentTailBus(design/151 S2 server 半场,[1520]{core} 提货单)——per-agent **live tail** 的进程内
+ * 分发总线。core 1.370 起后台子代 lane 向宿主 `onForwardEvent` 转发的每一帧带 `bgAgentId`(a* 句柄,
+ * TaskEventIdentity 顶层平铺;sync/steer 子代无 tag,wa* 走自己的 observer lane)——两条 run 腿
+ * (sync=http/server.ts、bg=runs.ts)的 fwdInternals 按 tag 存在性把帧 publish 进来,
+ * `GET /v1/runs/:id/subagents/:handle/stream` 按句柄订阅。
+ *
+ * 语义边界(与 [1497] A2 的「replay+tail」故事各占一半):
+ *  - **嵌套归并**(core 复审发现 #5):core recordingForward 在每层 bg 边界覆写 bgAgentId——host wire 上
+ *    整棵委托子树的帧一律带**最外层** a* 句柄;对嵌套 a* 行开 tail 流=只有 heartbeat(它的帧归并进外层
+ *    句柄的流,按 parentToolCallId 区分)。core JSDoc 补句已 ask。
+ *  - **live-only**:从订阅时刻起,replica-local(帧只在宿主 run 所在副本产生)——历史/终报走 durable
+ *    replay 面(`GET .../subagents/:handle/output` + AgentTranscript),meta 帧如实声明。
+ *  - **有界背压**:每订阅者有界队列(TAIL_QUEUE_CAP),慢消费者丢**最旧**帧并在下一次 drain 前插入一枚
+ *    `{type:"lagged", dropped}` 诚实标记帧——绝不无界缓冲(死对端=内存增长),绝不静默丢。
+ *  - **投影在 publish 侧一次**(projectTailFrame):与 sync 主流的 forward 投影同 builder 同纪律
+ *    (§E1:tool 帧走 whitelist+redact builder,text verbatim=owner 自己的模型输出同信任类,
+ *    reasoning 过 redactSecrets)——每帧投影一次,N 个订阅者共享同一投影对象(只读约定)。
+ *
+ * 订阅形 = subscribeWorkflow 同姿势:push 迭代器,消费端显式驱动,断连调 `it.return()` 清订阅
+ * (parked next() 不观察 closed 旗——不清理=死订阅者队列永驻)。
+ */
 import { redactSecrets } from "../trace/redact.js";
 import { taskProgressEventData, toolStartEventData, toolEndEventData } from "../trace/project.js";
 const TAIL_QUEUE_CAP = 512;
+/** core forward 事件 → wire 投影(sync 主流五分支同源;不认识的帧类型=null 不发——tail 面只承诺
+ *  content 五类,新 core 帧类型先经这里显式收编再出 wire)。 */
 export function projectTailFrame(e) {
     const t = e.type;
     if (t === "task_progress") {
@@ -8,11 +32,11 @@ export function projectTailFrame(e) {
     }
     if (t === "tool_start") {
         const tsv = e;
-        return { type: "tool_start", ...toolStartEventData(tsv) };
+        return { type: "tool_start", ...toolStartEventData(tsv) }; // label 现由 builder 自带(1.258),外拼冗余已清
     }
     if (t === "tool_end") {
         const te = e;
-        return { type: "tool_end", ...toolEndEventData(te) };
+        return { type: "tool_end", ...toolEndEventData(te) }; // label 现由 builder 自带,外拼冗余已清(同 tool_start 1.258 先例)
     }
     if (t === "text_delta") {
         const td = e;
@@ -26,6 +50,7 @@ export function projectTailFrame(e) {
 }
 export class SubagentTailBus {
     subs = new Map();
+    /** 两条 run 腿的 fwdInternals 调用点:帧已投影(projectTailFrame),null 不进来。 */
     publish(bgAgentId, frame) {
         const set = this.subs.get(bgAgentId);
         if (!set)
@@ -41,6 +66,7 @@ export class SubagentTailBus {
             sub.wake?.();
         }
     }
+    /** 有无订阅者(publish 侧的免投影快门:没人听就不投影)。 */
     hasSubscribers(bgAgentId) {
         return (this.subs.get(bgAgentId)?.size ?? 0) > 0;
     }
@@ -53,6 +79,9 @@ export class SubagentTailBus {
         }
         set.add(sub);
         const cleanup = () => {
+            // 复审 #2(实证):路由对同一迭代器 return() 两次(close 钩+finally,设计如此)——非幂等 cleanup 在
+            // 两次调用之间若有新请求 subscribe 同句柄(map 重建新集),第二次会把**新订阅者的集**从 map 删掉
+            // (静默只剩 heartbeat)。幂等门+集同一性校验双保险。
             if (sub.closed)
                 return;
             sub.closed = true;
@@ -91,5 +120,7 @@ export class SubagentTailBus {
         return it;
     }
 }
+/** 进程单例(defaultTaskRegistry 同款姿势):bus 语义本就是进程内 replica-local,两条 run 腿与路由
+ *  直接 import,不穿长参数列表;测试自 new 独立实例。 */
 export const defaultSubagentTailBus = new SubagentTailBus();
 //# sourceMappingURL=subagent-tail-bus.js.map

package/dist/fleet-client.d.ts

@@ -1,5 +1,26 @@
+/**
+ * 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 { UsageReport } 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 declare const FLEET_USAGE_KEY_CAP = 1024;
+/**
+ * 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 declare class FleetUsageAccumulator {
     private cells;
     private runsSeen;
@@ -10,7 +31,10 @@ export declare class FleetUsageAccumulator {
         weightedTokens?: number;
         quotaWeightAtUse?: number;
     }): void;
+    /** Drain the window into UsageReport entries and RESET. Empty window → []. */
     drain(): UsageReport["entries"];
+    /** 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: UsageReport["entries"]): void;
     get size(): number;
 }
@@ -21,8 +45,10 @@ export interface FleetClientOpts {
         worker: string;
     };
     instanceId: string;
+    /** Reachable base URL of THIS instance — the operator's explicit declaration (`FLEET_ADVERTISE_ADDRESS`). */
     advertiseAddress: string;
     version: string;
+    /** Live drain flag (drainState) — read at every announce. */
     isDraining: () => boolean;
     usage?: FleetUsageAccumulator;
     heartbeatMs?: number;
@@ -31,13 +57,25 @@ export interface FleetClientOpts {
         info: (m: string, d?: Record<string, unknown>) => void;
         warn: (m: string, d?: Record<string, unknown>) => void;
     };
+    /** Injectable for tests. */
     fetchImpl?: typeof fetch;
 }
 export interface FleetClient {
+    /** Immediate out-of-cycle announce — call when `draining` flips (self-remove from routing FIRST). */
     announceNow: () => Promise<void>;
+    /** Stop timers + best-effort DELETE deregistration (bounded; never throws). */
     stop: () => Promise<void>;
 }
+/**
+ * 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 declare function startFleetClient(opts: FleetClientOpts): FleetClient;
+/**
+ * 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 declare function startFleetClientFromEnv(cfg: {
     configCenter?: {
         baseUrl: string;

package/dist/fleet-client.js

@@ -1,10 +1,31 @@
+/**
+ * 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;
+/**
+ * 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();
-    runsSeen = new Set();
+    cells = new Map(); // key = principal <NUL> model
+    runsSeen = new Set(); // taskId per window → runs count (first brain.call of a run in this window)
     record(principal, model, taskId, d) {
-        const p = principal ?? "__anonymous__";
+        const p = principal ?? "__anonymous__"; // single-user turnkey: no principal — still meter, under a stable bucket
         let key = `${p}\u0000${model}`;
         if (!this.cells.has(key) && this.cells.size >= FLEET_USAGE_KEY_CAP)
             key = `__other__\u0000__other__`;
@@ -18,7 +39,7 @@ export class FleetUsageAccumulator {
             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;
         }
@@ -26,6 +47,7 @@ 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) {
@@ -36,6 +58,8 @@ 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}`;
@@ -62,6 +86,10 @@ export class FleetUsageAccumulator {
         return this.cells.size;
     }
 }
+/**
+ * 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;
@@ -69,7 +97,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;
+    let failStreak = 0; // warn once per failure streak, not per tick (a down center must not spam logs)
     const announceNow = async () => {
         const body = {
             instanceId: opts.instanceId,
@@ -101,9 +129,9 @@ export function startFleetClient(opts) {
         const windowEndMs = Date.now();
         const entries = opts.usage.drain();
         const start = windowStartMs;
-        windowStartMs = windowEndMs;
+        windowStartMs = windowEndMs; // half-open [start, end) — the next window starts exactly where this one ended
         if (entries.length === 0)
-            return;
+            return; // nothing accrued — skip the POST entirely
         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] }) });
@@ -111,11 +139,12 @@ export function startFleetClient(opts) {
                 throw new Error(`usage ${res.status}`);
         }
         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();
+    void announceNow(); // boot announce (registration = first heartbeat)
     const hb = setInterval(() => void announceNow(), heartbeatMs);
     hb.unref?.();
     const uw = opts.usage ? setInterval(() => void flushUsage(), usageWindowMs) : undefined;
@@ -127,15 +156,21 @@ export function startFleetClient(opts) {
         clearInterval(hb);
         if (uw)
             clearInterval(uw);
-        await flushUsage();
+        await flushUsage(); // final partial window — best-effort
         try {
             await f(`${base}/api/fleet/instances`, { method: "DELETE", headers, body: JSON.stringify({ instanceId: opts.instanceId, worker: opts.center.worker }) });
         }
         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;

package/dist/fleet-lease.d.ts

@@ -1,8 +1,40 @@
+/**
+ * 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 } from "@sema-agent/registry-core/fleet";
+/** 负缓存 TTL:非 lease-enforced 的 principal 多久后再问一次 center(entitlement 升级为 lease 的收敛上界)。 */
 export declare const NOT_LEASE_TTL_MS: number;
+/** center 判 budget exhausted 后,多久内的重复提交直接拒绝而不再打 center(防 per-request 打爆)。 */
 export declare const EXHAUSTED_RETRY_MS: number;
+/** principal 状态表上界(镜像 FLEET_USAGE_KEY_CAP 的姿势):超界丢最旧 —— 被丢的 principal 下次 admit
+ *  重新协商,一次多余 RTT,无正确性影响。 */
 export declare const LEASE_PRINCIPAL_CAP = 4096;
+/** 复审 O1:lease 协商 RTT 的硬上限——leaseDenied 在提交热路径同步 await 它,一个 accept-but-hang 的
+ *  center 必须迅速塌成 fail-open 而不是拖垮提交。取 2.5s(远小于任何续租余量,略紧于 registry 的 8s)。 */
 export declare const LEASE_FETCH_TIMEOUT_MS = 2500;
+/** E4 定稿的 409 结构化字段(center verbatim → 我方 429 body verbatim 透传;人话归壳/web)。 */
 export type QuotaDenyDetail = {
     windowType?: "fiveHour" | "weekly" | "budget";
     remaining?: number;
@@ -55,16 +87,30 @@ export declare class FleetLeaseManager {
     private readonly now;
     private failStreak;
     constructor(opts: FleetLeaseOpts);
+    /**
+     * 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.
+     */
     admit(principal: string): Promise<LeaseAdmission>;
+    /** 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 类型层定死)。 */
     recordSpend(principal: string | undefined, d: {
         weightedTokens?: number;
         costMicroUsd?: number;
     }): void;
+    /** Test/observability hook: the current state kind for a principal (never exposes the token). */
     peek(principal: string): PrincipalState["kind"] | undefined;
     private set;
     private issueOrRenew;
     private issueOrRenewInner;
 }
+/**
+ * Env/config gate(与 startFleetClientFromEnv 同 D3 分层姿势,但 lease 不需要 FLEET_ADVERTISE_ADDRESS ——
+ * 它是出站消费面,不是入站可达性声明):sema-registry lane 配齐(baseUrl+token+worker)即启;任一缺失 →
+ * undefined,非 fleet 部署零行为变化。
+ */
 export declare function createFleetLeaseFromEnv(cfg: {
     configCenter?: {
         baseUrl: string;

package/dist/fleet-lease.js

@@ -1,17 +1,48 @@
+/**
+ * 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();
+    inflight = new Map(); // single-flight issue/renew per principal
     f;
     base;
     headers;
     now;
-    failStreak = 0;
+    failStreak = 0; // warn once per outage streak (mirrors fleet-client)
     constructor(opts) {
         this.opts = opts;
         this.f = opts.fetchImpl ?? fetch;
@@ -19,6 +50,10 @@ 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);
@@ -28,12 +63,18 @@ 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 类型层定死)。 */
     recordSpend(principal, d) {
         if (!principal)
             return;
@@ -43,15 +84,16 @@ 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;
+            const oldest = this.state.keys().next().value; // insertion order ≈ LRU-enough for a cap backstop
             this.state.delete(oldest);
         }
-        this.state.delete(principal);
+        this.state.delete(principal); // re-insert at tail
         this.state.set(principal, st);
     }
     issueOrRenew(principal) {
@@ -64,6 +106,11 @@ 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,
@@ -72,7 +119,7 @@ export class FleetLeaseManager {
             });
             if (res.status === 200) {
                 const body = (await res.json());
-                const lease = QuotaLease.parse(body.lease);
+                const lease = QuotaLease.parse(body.lease); // zod — a malformed center response fails into the catch (fail-open)
                 this.set(principal, { kind: "lease", lease });
                 if (this.failStreak > 0)
                     this.opts.logger?.info?.("fleet_lease_recovered", { after: this.failStreak });
@@ -82,8 +129,16 @@ 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 } : {}),
@@ -96,9 +151,16 @@ 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) });
@@ -107,6 +169,7 @@ 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) });
@@ -115,6 +178,11 @@ 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/hooks/branch-transcript.d.ts

@@ -1,4 +1,5 @@
 import type { SessionTreeEntry } from "@sema-agent/core";
+/** 渲染结果。**判别式**:证据不足时调用方拿不到 `text`,想用也用不了(见顶注)。 */
 export type BranchTranscript = {
     sufficient: true;
     text: string;
@@ -8,7 +9,14 @@ export type BranchTranscript = {
     sufficient: false;
     reason: "no-entries" | "nothing-renderable" | "empty-after-render";
 };
+/** 单次评估送进模型的 transcript 字符上限。超出保留**尾部**(最近的对话对"条件是否已达成"更相关)。 */
 export declare const BRANCH_TRANSCRIPT_MAX_CHARS = 60000;
+/**
+ * 渲染成 transcript。
+ *
+ * ⚠️ **compaction 的 summary 也算证据**:一次压缩之后,早期内容**只**活在那段摘要里 ——
+ * 把它滤掉等于亲手制造「证据不足」(而那正好会被判成"拦")。
+ */
 export declare function renderBranchTranscript(entries: readonly SessionTreeEntry[] | undefined, opts?: {
     maxChars?: number;
 }): BranchTranscript;

package/dist/hooks/branch-transcript.js

@@ -1,5 +1,30 @@
+/**
+ * 把 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";
+/** 单次评估送进模型的 transcript 字符上限。超出保留**尾部**(最近的对话对"条件是否已达成"更相关)。 */
 export const BRANCH_TRANSCRIPT_MAX_CHARS = 60_000;
+/** 从一条 message entry 里抽人类可读文本(只取 text 片段;工具结果等非文本片段不进 transcript)。 */
 function messageText(entry) {
     const m = entry.message;
     if (!m || typeof m.role !== "string")
@@ -18,6 +43,12 @@ function messageText(entry) {
     const text = parts.join("\n").trim();
     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" };
@@ -38,9 +69,11 @@ 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;
     }