@sema-agent/server 7.141.0 → 7.142.0

package/dist/tool-approval.js

@@ -15,7 +15,7 @@ import { ownerOfCheckpointScope } from "./security.js";
 import { deriveAskId, deriveAskScopedBatchId, deriveBatchId, MAX_DECISION_NOTE_CHARS, noteLandedOnRow, noteRecordedReceipt } from "./approval-ask-machine.js";
 import { currentParkArm, MAX_RULE_OFFERS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildReplayFrame, buildRevokeFrame, readDenialLimitFallback, readProbeCause, readProbeReason, readReadRootCandidate, readStoredCardEnvelope, readRuleEvidence, readAllowRuleShadowed, readRuleOffersAbsence, readRuleOffersAbsenceSeat, readParkRowTrueSeat, readAskClassPair, readClosedWordSeat, buildApprovalCompleteFrame, readRuleOfferList, } from "./approval-card.js";
 import { askOwnerAdmits, askRowCarriesOwner, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./plugins/approval-ask-store-sql.js";
-import { APPROVAL_ENDING_CAUSES, SETTLE_OUTCOME, causeOfAskRow } from "./approval-deny-reasons.js";
+import { APPROVAL_ENDING_CAUSES, SETTLE_OUTCOME, askRowEndingCause, askRowParkTrigger } from "./approval-deny-reasons.js";
 import { settleByPolicy } from "./approval-policy-settlement.js";
 import { governanceAskMarksFor, runWithGovernanceAskScope } from "./governance-ask-marks.js";
 import { governanceOriginOf } from "./runtime-governance.js";
@@ -898,7 +898,7 @@ export class ToolApprovalCoordinator {
             await new Promise((r) => setTimeout(r, SHUTDOWN_DRAIN_POLL_MS));
         }
         await this.parkCommits?.quiesce(deadlineMs);
-        this.askAudit?.noteLegsInterruptedByShutdown();
+        this.askAudit?.noteInterruptedByShutdown();
         return { uncommittedParks: [...this.parksAwaitingCommit].map((p) => ({ approvalId: p.approvalId, taskId: p.taskId })) };
     }
     noteParkCommitted(calls) {
@@ -1057,12 +1057,11 @@ export class ToolApprovalCoordinator {
     classifyClaimLoss(askId, current, _where) {
         if (current.state === "absent")
             return { kind: "absent" };
-        const rowCause = current.cause;
-        if (rowCause?.kind === "ending")
-            return { kind: "ended", cause: rowCause.cause };
+        if (current.endingCause !== undefined)
+            return { kind: "ended", cause: current.endingCause };
         const replayedOutcome = replayTerminalAskRow(current);
         if (replayedOutcome === "unavailable") {
-            return rowCause?.kind === "park_trigger" ? { kind: "parked", cause: rowCause.cause } : { kind: "parked" };
+            return current.parkTrigger !== undefined ? { kind: "parked", cause: current.parkTrigger } : { kind: "parked" };
         }
         const replayed = settleArgsOfDecided(replayedOutcome);
         if (!replayed.allowed)
@@ -2300,8 +2299,8 @@ export class ToolApprovalCoordinator {
             }
             case "DENIED":
             case "VOID": {
-                const rowCause = causeOfAskRow(row);
-                body = { state: "void", ...projection, ...(rowCause?.kind === "ending" ? { cause: rowCause.cause } : {}) };
+                const endingCause = askRowEndingCause(row);
+                body = { state: "void", ...projection, ...(endingCause !== undefined ? { cause: endingCause } : {}) };
                 break;
             }
             case "STREAM_PENDING":
@@ -2413,8 +2412,7 @@ export class ToolApprovalCoordinator {
             }
             case "DENIED":
             case "VOID": {
-                const rowCause = causeOfAskRow(row);
-                return this.notPending(rowCause?.kind === "ending" ? rowCause.cause : undefined);
+                return this.notPending(askRowEndingCause(row));
             }
             case "STREAM_PENDING":
                 return this.notPending(NOT_PENDING_UNKNOWN_CAUSE);
@@ -3028,17 +3026,17 @@ export class ToolApprovalCoordinator {
             }
             if (this.editedDecisionInFlight(askId))
                 continue;
-            const rowCause = causeOfAskRow(row);
-            if (rowCause?.kind === "ending") {
+            const endingCause = askRowEndingCause(row);
+            if (endingCause !== undefined) {
                 const before = this.waitingRegistrationCount(askId);
-                this.settleVoidedSiblings([askId], rowCause.cause);
+                this.settleVoidedSiblings([askId], endingCause);
                 settled += before;
                 continue;
             }
             const outcome = replayTerminalAskRow(row);
             if (outcome === "unavailable") {
                 const before = this.waitingRegistrationCount(askId);
-                const parkCause = (rowCause?.kind === "park_trigger" ? rowCause.cause : undefined) ?? (Date.now() >= row.expiresAtMs ? APPROVAL_ENDING_CAUSES.TTL_EXPIRED : APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK);
+                const parkCause = askRowParkTrigger(row) ?? (Date.now() >= row.expiresAtMs ? APPROVAL_ENDING_CAUSES.TTL_EXPIRED : APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK);
                 this.settleSameAskIdParkRoute(askId, parkCause);
                 settled += before;
                 continue;

package/dist/trace/core-keyset-guard.d.ts

@@ -251,8 +251,11 @@ type _GuardTerminalArm = AssertAllKeysHandled<Exclude<NonPausedTerminalKeys, Ter
 type _GuardTerminalArmReverse = AssertAllKeysHandled<Exclude<TerminalArmForwarded | TerminalArmStripped, NonPausedTerminalKeys>>;
 type SeatDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
 type JoinPath<K extends string, P extends string> = [P] extends [never] ? never : P extends "" ? K : `${K}.${P}`;
-/** `T` 与祖先链上某一层**互相可赋**(同一个形)⇒ 这是递归类型的回环(如 JSON 值类型),再走只是同一棵子树换个前缀,停。只比祖先、不比兄弟。 */
-type SeenOnPath<T, Seen extends readonly unknown[]> = Seen extends readonly [infer H, ...infer R extends readonly unknown[]] ? [T] extends [H] ? [H] extends [T] ? true : SeenOnPath<T, R> : SeenOnPath<T, R> : false;
+/** 两个型**全同**(不是「互相可赋」:全可选成员的子对象与它的父对象互相可赋,却不是同一个型)。 */
+type SameType<A, B> = (<G>() => G extends A ? 1 : 2) extends <G>() => G extends B ? 1 : 2 ? true : false;
+/** `T` 与祖先链上某一层**全同** ⇒ 这是递归类型的回环(如 JSON 值类型),再走只是同一棵子树换个前缀,停。只比祖先、不比兄弟。
+ *  有限型的子代不可能与祖先全同(祖先含着它),所以全同只在递归上成立;「互相可赋」会把同形的有限子代(`{text?, cause?: {text?}}` 的 `cause`)误判成回环、整枝丢掉。 */
+type SeenOnPath<T, Seen extends readonly unknown[]> = Seen extends readonly [infer H, ...infer R extends readonly unknown[]] ? SameType<T, H> extends true ? true : SeenOnPath<T, R> : false;
 /**
  * `T` 里类型为 `Leaf` 的全部路径(点分;数组元素记 `[]`;`any` 不展开)。回环按祖先链判停;深度封顶 12 且**封顶响亮**:
  * 走到底还没走完的分支产出以 `<depth-exhausted>` 收尾的路径 —— 它不在座表里 ⇒ 下面的正向对账 TS2344(封顶静默返回 `never`
@@ -311,14 +314,125 @@ type _SeatWalkTooDeep = {
     };
 };
 type _SeatWalkCheckExhaustionLoud = AssertAllKeysHandled<Exclude<"a.b.c.d.e.f.g.h.i.j.k.l.m.<depth-exhausted>", PathsTo<_SeatWalkTooDeep, CheckpointToken>>>;
-type ExitResult = TaskResult | VerificationResult | CascadeRunResult;
+/** 本仓结算点交给封口的**全部出口结果类型**(普通腿 / verify 腿 / cascade 腿)—— ⑩f(停驻座)与 ⑩g(结果文本叶,`observability/run-terminal.ts`)同读这一组。 */
+export type ExitResult = TaskResult | VerificationResult | CascadeRunResult;
 type SeatPathText<P extends readonly string[]> = P extends readonly [infer H extends string, ...infer R extends readonly string[]] ? (R extends readonly [] ? H : `${H}.${SeatPathText<R>}`) : never;
-/** 座表上某一键(凭据 / 门)的全部路径,按行分配。 */
-type SeatKeyPaths<S, K extends "token" | "gate"> = S extends PauseSeat ? `${SeatPathText<S["path"]>}.${S[K]}` : never;
+/** 座表上某一键(凭据 / 门)的全部路径,按行分配。⑩g 的结果文本叶从派生键集里减掉这几条(它们归封口 + 门脱敏,不归文本表)。 */
+export type SeatKeyPaths<S, K extends "token" | "gate"> = S extends PauseSeat ? `${SeatPathText<S["path"]>}.${S[K]}` : never;
 type _GuardTokenSeats = AssertAllKeysHandled<Exclude<PathsTo<ExitResult, CheckpointToken>, SeatKeyPaths<PauseSeat, "token">>>;
 type _GuardTokenSeatsReverse = AssertAllKeysHandled<Exclude<SeatKeyPaths<PauseSeat, "token">, PathsTo<ExitResult, CheckpointToken>>>;
 type _GuardGateSeats = AssertAllKeysHandled<Exclude<PathsTo<ExitResult, CheckpointGate>, SeatKeyPaths<PauseSeat, "gate">>>;
 type _GuardGateSeatsReverse = AssertAllKeysHandled<Exclude<SeatKeyPaths<PauseSeat, "gate">, PathsTo<ExitResult, CheckpointGate>>>;
+/** 一个串型装得下任意文字 ⇔ 以它为键的记录不要求任何具名键(`string` / 模板串 / 品牌串给出索引签名或空形;闭集字面量给出必需键)。 */
+type FreeTextString<S extends string> = {} extends Record<S, 0> ? "" : never;
+type TextLeafSegment<K extends string | number> = K extends number ? (number extends K ? "*" : `${K}`) : string extends K ? "*" : K;
+export type TextLeafPaths<T, Seen extends readonly unknown[] = [], D extends number = 12> = [D] extends [never] ? "<depth-exhausted>" : 0 extends 1 & T ? "" : unknown extends T ? "" : T extends string ? FreeTextString<T> : T extends number | boolean | bigint | symbol | null | undefined ? never : T extends (...args: never[]) => unknown ? never : SeenOnPath<T, Seen> extends true ? never : T extends readonly (infer E)[] ? JoinPath<"[]", TextLeafPaths<E, [...Seen, T], SeatDepth[D]>> : T extends object ? {
+    [K in keyof T & (string | number)]-?: JoinPath<TextLeafSegment<K>, TextLeafPaths<T[K], [...Seen, T], SeatDepth[D]>>;
+}[keyof T & (string | number)] : never;
+/** 落在某个前缀**之下或就是它**的路径折成那个前缀(子树归前缀的属主);不在任何前缀下的原样。前缀之间不许互相嵌套(嵌套 ⇒ 一条路径折成两个,表上两行同判一片叶)。 */
+export type CollapseUnder<P extends string, Prefix extends string> = P extends unknown ? ([OwnerPrefixOf<P, Prefix>] extends [never] ? P : OwnerPrefixOf<P, Prefix>) : never;
+type OwnerPrefixOf<P extends string, Prefix extends string> = Prefix extends unknown ? (P extends Prefix | `${Prefix}.${string}` ? Prefix : never) : never;
+/** 判别联合各臂键的**并集**(`keyof` 一个联合给的是交集)。 */
+type AllKeysOfUnion<T> = T extends unknown ? keyof T : never;
+/** 联合里各臂在键 `K` 上的成员型之并(没有这一键的臂不贡献)。 */
+type MemberOfUnion<T, K extends PropertyKey> = T extends unknown ? (K extends keyof T ? T[K] : never) : never;
+/**
+ * 处置词 `W` 盖得住型 `V` ⇔ `V` 之下的每一片自由文本叶(相对 `V` 的路径)都在 `Covers[W]` 里。词表即盖法表:叶词盖 `""`(成员自己那片叶)、
+ * `text[]` 类词盖 `"[]"`、按自家派生表下降的词与整树词盖 `string`(下降目标的表同样是 {@link OwnerTable},逐层同一条)。
+ */
+export type CoveringWords<V, Covers extends Record<string, string>> = {
+    [W in keyof Covers & string]: [Exclude<TextLeafPaths<V>, Covers[W]>] extends [never] ? W : never;
+}[keyof Covers & string];
+/**
+ * 属主表的型:`T`(可为判别联合,取各臂键之并)的每个成员一行、少一行 / 多一行都红,且每行只许 {@link CoveringWords} —— 一个 `"verbatim"`
+ * 落在藏着自由文本叶的对象成员上(core 往 `stats.nested` 这种数字袋里加一个字符串成员)⇒ 该行不再可赋 ⇒ tsc 红,不是静默逐字。
+ */
+export type OwnerTable<T, Covers extends Record<string, string>> = {
+    readonly [K in AllKeysOfUnion<T>]: CoveringWords<MemberOfUnion<T, K>, Covers>;
+};
+type _TextWalkProbe = {
+    s: string;
+    w: "a" | "b";
+    tpl: `${string}.x`;
+    br: string & {
+        readonly brand: 1;
+    };
+    n: number;
+    f: boolean;
+    o: unknown;
+    a: any;
+    arr: {
+        t: string;
+    }[];
+    idx: Record<string, string>;
+    byNum: Record<number, string>;
+    tuple0: {
+        0: string;
+    };
+    own: {
+        x: string;
+        y: {
+            z: string;
+        };
+    };
+    nil?: null;
+    ev: {
+        text?: string;
+        cause?: {
+            text?: string;
+        };
+    };
+};
+type _TextWalkExpected = "s" | "tpl" | "br" | "o" | "a" | "arr.[].t" | "idx.*" | "byNum.*" | "tuple0.0" | "own" | "ev.text" | "ev.cause.text";
+type _TextWalkGot = CollapseUnder<TextLeafPaths<_TextWalkProbe>, "own">;
+type _TextLeafWalkCheckShapes = AssertAllKeysHandled<Exclude<_TextWalkExpected, _TextWalkGot> | Exclude<_TextWalkGot, _TextWalkExpected>>;
+type _TextWalkTooDeep = {
+    a: {
+        b: {
+            c: {
+                d: {
+                    e: {
+                        f: {
+                            g: {
+                                h: {
+                                    i: {
+                                        j: {
+                                            k: {
+                                                l: {
+                                                    m: {
+                                                        t: string;
+                                                    };
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+type _TextLeafWalkCheckExhaustionLoud = AssertAllKeysHandled<Exclude<"a.b.c.d.e.f.g.h.i.j.k.l.m.<depth-exhausted>", TextLeafPaths<_TextWalkTooDeep>>>;
+type _CoverProbeWords = {
+    verbatim: "";
+    "text[]": "[]";
+    tree: string;
+};
+type _CoverWordsCheck = AssertAllKeysHandled<Exclude<CoveringWords<{
+    tokens: number;
+    label: string;
+}, _CoverProbeWords>, "tree"> | Exclude<"tree", CoveringWords<{
+    tokens: number;
+    label: string;
+}, _CoverProbeWords>> | Exclude<"verbatim" | "tree", CoveringWords<{
+    tokens: number;
+    carrier?: "header" | "query";
+}, _CoverProbeWords>> | Exclude<"text[]" | "tree", CoveringWords<readonly string[] | undefined, _CoverProbeWords>> | Extract<"verbatim" | "text[]", CoveringWords<{
+    note: string;
+}[], _CoverProbeWords>>>;
 type SessionMemoryStatusProjected = "captureOptedOut" | "committedCount" | "foldedCount" | "optOutSource" | "lastCaptureAt";
 type SessionMemoryStatusExcluded = "writeHome";
 type _GuardSessionMemoryStatus = AssertAllKeysHandled<Exclude<keyof SessionMemoryStatus, SessionMemoryStatusProjected | SessionMemoryStatusExcluded>>;
@@ -555,7 +669,10 @@ export type CoreKeysetGuards = [
     _GuardGateSeats,
     _GuardGateSeatsReverse,
     _SeatWalkCheckDepth8,
-    _SeatWalkCheckExhaustionLoud
+    _SeatWalkCheckExhaustionLoud,
+    _TextLeafWalkCheckShapes,
+    _TextLeafWalkCheckExhaustionLoud,
+    _CoverWordsCheck
 ];
 export {};
 //# sourceMappingURL=core-keyset-guard.d.ts.map

package/dist/trace/engine-notice-wire.d.ts

@@ -31,7 +31,7 @@ export declare function engineNoticeSessionId(notice: {
     sessionId?: unknown;
     detail?: Record<string, unknown>;
 }): string | undefined;
-/** wire 上的 `engine_notice` 载荷(**五键固定**,设计稿 ②)。`type` 由发帧处补(SSE)/ 由账本行的 type 列承载。 */
+/** wire 上的 `engine_notice` 载荷(**六键固定**,设计稿 ②;`eventId` 随投递身份一并到货)。`type` 由发帧处补(SSE)/ 由账本行的 type 列承载。 */
 export interface EngineNoticeWireRow {
     /** 稳定机器码 —— 消费契约:cli 按 `code`+`detail` 渲染(见 {@link ENGINE_NOTICE_WIRE_CODES} 各码的 detail 形)。 */
     code: string;
@@ -46,6 +46,12 @@ export interface EngineNoticeWireRow {
     sessionId: string;
     /** **服务端观察时刻**(ms epoch)——`EngineNotice` 自身不带时间戳,这是本仓收到它的那一拍,不是 core 铸它的那一拍。 */
     ts: number;
+    /**
+     * 这一次投递的身份(uuidv7,非空):分流器**扇出时铸一枚**({@link EngineNoticeRouter} 的 `fanOut`,与 `ts` 同处),同腿的 live 帧与 durable 账本行是**同一只行对象**,
+     * 所以两个载体同值。live 帧因此带 `id:` 行(契约 §0.6:载荷有 `eventId` 才发行),重连后从 durable 尾(`GET /v1/runs/:id/events`,从头重放)读到的同一条通告靠这一枚认出是同一件事。
+     * 同一内容的两次投递是两件事、两枚身份。不是 core 的字段(`EngineNotice` 没有),也不可从内容推:同码同毫秒的两条内容哈希会撞。
+     */
+    eventId: string;
 }
 /**
  * 上 wire 的**注册方写的自由文本**的唯一出口纪律:`redactSecrets` + 截到 {@link NOTICE_TEXT_MAX}。
@@ -106,7 +112,7 @@ export declare function engineNoticeEventData(notice: {
     code: string;
     message: string;
     detail?: Record<string, unknown>;
-}, sessionId: string, nowMs: number): EngineNoticeWireRow;
+}, sessionId: string, nowMs: number, eventId: string): EngineNoticeWireRow;
 /**
  * 一条 run 腿注册进来的投递口。抛错由 {@link EngineNoticeRouter.route} 隔离(见那里的 fail-open 登记)。
  * 返回值只对 {@link EngineNoticeRouter.routeConfirmed} 有意义([ref] codex r1-F2 / r2-F1):durable 口交回它那一次账本写的 thenable,

package/dist/trace/engine-notice-wire.js

@@ -1,3 +1,4 @@
+import { uuidv7 } from "@sema-agent/core";
 import { redactSecrets } from "./redact.js";
 import { redactListEntry } from "../list-entry-display.js";
 import { recordFailOpen } from "../observability/fail-open.js";
@@ -128,13 +129,14 @@ export function redactNoticeRuleText(code, detail) {
     });
     return { ...detail, [at.array]: redacted };
 }
-export function engineNoticeEventData(notice, sessionId, nowMs) {
+export function engineNoticeEventData(notice, sessionId, nowMs, eventId) {
     return {
         code: notice.code,
         message: redactNoticeMessage(notice.message).slice(0, NOTICE_TEXT_MAX),
         detail: sanitizeNoticeDetail(redactNoticeRuleText(notice.code, notice.detail)),
         sessionId,
         ts: nowMs,
+        eventId,
     };
 }
 const isThenableResult = (v) => typeof v === "object" && v !== null && typeof v.then === "function";
@@ -189,7 +191,7 @@ export class EngineNoticeRouter {
         const leg = list && list.length > 0 ? list[list.length - 1] : undefined;
         if (!leg || leg.sinks.length === 0)
             return [];
-        const row = engineNoticeEventData(notice, sessionId, nowMs);
+        const row = engineNoticeEventData(notice, sessionId, nowMs, uuidv7());
         const outcomes = [];
         for (const { slot, sink } of leg.sinks) {
             try {

package/dist/trace/exit-seat.d.ts

@@ -9,7 +9,8 @@ export type SafeText = string & {
  *  · `trace-frame-text`:trace 帧的自由文本位(子代名 / 动作行 / 通告正文与结果 / 诊断 / 注入摘录 / 压缩说明 / 人类输入的署名与附件标签 …),不设界;
  *  · `trace-frame-line`:trace 帧里一行宽的展示位(`workspace_changed.cwd` / `brain_status.detail`),界 300 码元;
  *  · `operator-log-text`:运维日志字段里的一句话 —— 读口坏行的缺陷句(core 的筛按位置点名并回显落盘标量)、`tool_trace` 行里工具的输出 / 失败句 / 拒因、
- *    hook 吐出的预览(非 JSON 的输出 / 应答体)与判词、Stop 评估者回话的头、观察面回调与唤醒投递抛出的句子、matcher 超预算的那两串、标题器的两只失败句;界 200 码元(含截断记号);
+ *    hook 吐出的预览(非 JSON 的输出 / 应答体)与判词、Stop 评估者回话的头、观察面回调与唤醒投递抛出的句子、matcher 超预算的那两串、标题器的两只失败句、
+ *    起服面(`src/boot/**`)各条运维行里抛出物的句子与起服自检读数里的客户端异常原文(门 `test/boot-log-thrown-text-seat.test.ts`);界 200 码元(含截断记号);
  *  · `operator-log-arg`:运维日志字段里模型写的工具入参(`tool_trace` 的 `arg.*`:路径 / 命令 / 模式 / 非对象入参的串形);界 120 码元(含截断记号);
  *  · `operator-log-error`:运维日志字段里 hook 一侧的报错 —— hook 命令的 stderr、prompt 条目的载体失败句、起子进程 / 读会话分支抛出的句子;界 300 码元(含截断记号);
  *  · `operator-log-message`:运维日志字段里写给人看的一段话 —— hook 输出的 `systemMessage`、Stop 评估者判「做不到」的理由;界 500 码元(含截断记号);

package/dist/trace/ledger-sink.d.ts

@@ -1,5 +1,5 @@
 import { type TerminalCause } from "@sema-agent/core";
-import { brainStatusEventData, type LegWiringSections } from "./project.js";
+import { brainStatusEventData, type ModelUsageSeat, type LegWiringSections } from "./project.js";
 import { NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
 import { type LedgerEventType, type ParkLedgerEventType } from "./ledger-events.js";
 /**
@@ -59,7 +59,8 @@ export interface LedgerSink {
     onForwardEvent(e: {
         type?: string;
     }): void;
-    /** Park event (durable F4 suspend / [ref] D-B review pause): ONLY the `checkpointGate` is persisted —
+    /** Park event (durable F4 suspend / [ref] D-B review pause), written AFTER any pending `model_usage` delta of the leg (the status frame
+     *  is the last frame a leg writes — `appendParkRow` owns that order): ONLY the `checkpointGate` is persisted —
      *  never the capability `checkpointToken` (search [18] Q1b).
      *  🔴 **The gate is redacted, not "non-secret"** ([ref], 2026-09-10 — the arm [ref] R3 left open): it carries no
      *  capability token, but its `reason` and the `riskDescriptor` leaf family are model-/human-controlled display
@@ -73,8 +74,8 @@ export interface LedgerSink {
     /** Terminal `done` event. `result` must already be checkpoint-token-stripped (and, on the bg leg,
      *  model-usage-attached) by the caller. */
     appendDone(result: unknown): Promise<void>;
-    /** Convenience for the sync detach lane (no model-usage interleave there): flush, then project the result
-     *  to its park/terminal event exactly like the bg leg's done case. `result` must already be stripped. */
+    /** Convenience for the sync detach lane: flush, then project the result to its park/terminal event exactly like the
+     *  bg leg's done case (a park goes through {@link appendParked}, which settles pending model usage first). `result` must already be stripped. */
     onDone(result: {
         terminal: TerminalCause;
     }): Promise<void>;
@@ -154,5 +155,8 @@ export declare function createLedgerSink(opts: {
     /** 这条腿的 `wiring_manifest` **本仓自铸段**(`LegWiringSections`:[ref] `instructions` 读腿的 `InstructionSelectionLeg.segment`、run 级 `skills` 读 spec 字段
      *  `runSkillsOf`)。**必填**:账本行与 live 帧是同一条腿的两个载体,段必须来自同一只腿;在投帧那一刻读(core 推帧之前已 await 过 loader)。 */
     legSections: () => LegWiringSections;
+    /** 这条腿的计量席(E8 累加器 + 归因键)。在场 ⇒ {@link LedgerSink.appendParked} 在停驻行之前先把未结清的用量差落成 `model_usage` 行(状态帧最后,见 `appendParkRow`);
+     *  缺席 ⇒ 这条腿没接累加器,停驻行之前无账可结(夹具、不经 `appendParked` 停驻的腿)。 */
+    usage?: ModelUsageSeat;
 }): LedgerSink;
 //# sourceMappingURL=ledger-sink.d.ts.map

package/dist/trace/ledger-sink.js

@@ -1,7 +1,7 @@
 import {} from "@sema-agent/core";
 import { outwardPlane } from "../terminal.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { modelTextEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, compactionStartedEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, turnEndEventData, contextUsageEventData, parkEventData } from "./project.js";
+import { modelTextEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, compactionStartedEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, turnEndEventData, contextUsageEventData, appendParkRow } from "./project.js";
 import { NotifiedKeys, taskNotificationStreamKeyOf } from "../orchestration/workflow-completion-inbox.js";
 import { isParkLedgerEventType } from "./ledger-events.js";
 import { isModelSegmentBoundary, reasoningDeltaBytes, reasoningSegmentEventId } from "./model-segment.js";
@@ -179,7 +179,7 @@ export function createLedgerSink(opts) {
         return append("status", statusData);
     };
     const appendParked = (kind, result) => {
-        return append(kind, parkEventData(result));
+        return appendParkRow(append, opts.usage, kind, result);
     };
     const appendDone = (result) => append("done", { result });
     const onDone = async (result) => {

package/dist/trace/project.d.ts

@@ -30,7 +30,7 @@ import type { RunCompanionRecord } from "../observability/prompt-manifest.js";
 import { type SafeText } from "./exit-seat.js";
 import { type SemaProvenanceInput } from "./sema-provenance.js";
 import { type ExtensionRequesterFace, type ToolInputRewriteFace } from "./extension-call-face.js";
-import type { LedgerEventType } from "./ledger-events.js";
+import type { LedgerEventType, ParkLedgerEventType } from "./ledger-events.js";
 import type { InstructionsSegment } from "../instruction-selection.js";
 import type { RunSkillEntry } from "../capabilities/skills.js";
 /** 账本写口的统一签名 —— `type` 是**闭集**(`ledger-events.ts`):新型必须先登记,否则调用点编译红
@@ -419,6 +419,23 @@ export interface ParkEventData {
  * 门身份读法与三处 durable 读面同一只(`durableRowIdentity`,face `run-events-park`):没有暂停因由的行不问身份(没有门可认);有因由而读不出 ⇒ 键缺席 + 计一次。
  */
 export declare function parkEventData(result: unknown, reopened?: string | null): ParkEventData;
+/** 一腿的计量席:E8 累加器 + 这条腿在累加器里的归因键。`modelUsage` 缺席 ⇒ 这条腿没接累加器,没有用量可结。 */
+export interface ModelUsageSeat {
+    readonly modelUsage: ModelUsageTracker | undefined;
+    readonly taskId: string;
+}
+/**
+ * park 账本行的**唯一写口** —— {@link parkEventData} 是行的唯一构造器,本函数是它的唯一落账处:后台腿与同步 detach 腿(`LedgerSink.appendParked`)、
+ * 续跑腿的再停两臂、重开臂与续跑 verify 臂(`resume-legs.ts`)都经这一只。
+ *
+ * **状态帧最后**:一腿账本的状态帧(终局 `done` / `failed`、停驻 `suspended` / `needs_review`)是这一腿主线写下的最后一帧(晚到的子代转发帧、完成后的 suggestions 是旁路写,不在此列),计量帧先于它写出 ——
+ * 终局由 {@link attachModelUsage} 先结清最后一拍再落 `done`,停驻由本函数先 drain 再落停驻行。顺序属于写口、不属于调用点:
+ * 只回结果的 verify 腿没有逐 turn 落账的流(无 `turn_end` 帧),挂起前的用量只有停驻这一拍才落账;若各调用点各自记得「先结清」,
+ * 这条腿的账本尾帧就会是 `model_usage`,与不带 `verify` 的停驻(用量在 `turn_end` 就结清了)两形不同序(`GET /v1/runs/:id/events` 的尾帧)。
+ * 用量行落不下 ⇒ 停驻行**照落**,然后把用量行的失败抛给调用方(失败语义与此前逐字同:账本里有停驻帧、调用方按「停驻没落定」收场 —— bg 腿以 `failed` 收、手里的卡作废;
+ * 尽力而为的调用点(detach 腿的兜底停驻、续跑腿的重开臂)照旧吞掉它,停驻帧不因为一笔用量行的失败而缺席)。顺序变了,谁来写、写不下谁抛没有变。
+ */
+export declare function appendParkRow(append: AppendFn, usage: ModelUsageSeat | undefined, word: ParkLedgerEventType, result: unknown, reopened?: string | null): Promise<void>;
 /**
  * The `task_started` payload(core 7.50.0):一只委派子代**起跑**的那一帧 —— 每周期一只(首派 / 复活;耐久续跑腿不铸),
  * 序在子代的 `wiring_manifest` 之后、它的首个 `task_progress` 与首次模型请求之前。

package/dist/trace/project.js

@@ -317,6 +317,22 @@ export function parkEventData(result, reopened) {
         ...(reopened !== undefined ? { reopened } : {}),
     };
 }
+export async function appendParkRow(append, usage, word, result, reopened) {
+    let drainFailed = false;
+    let drainFailure;
+    if (usage !== undefined) {
+        try {
+            await appendModelUsageDelta(append, usage.modelUsage, usage.taskId);
+        }
+        catch (e) {
+            drainFailed = true;
+            drainFailure = e;
+        }
+    }
+    await append(word, parkEventData(result, reopened));
+    if (drainFailed)
+        throw drainFailure;
+}
 export function taskStartedEventData(ev) {
     return {
         taskId: ev.taskId,