@sema-agent/server 7.140.0 → 7.142.0

package/dist/terminal.js

@@ -1,5 +1,7 @@
 import { terminalProjection } from "@sema-agent/core";
+import { errorCodeOf } from "./observability/err-text.js";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { redactSecrets } from "./trace/redact.js";
 export function failureCodeOf(terminal) {
     return terminal.kind === "failed" ? terminal.code : undefined;
 }
@@ -8,25 +10,116 @@ export const STORE_ERROR_CODE = "internal.store_error";
 export function outwardFailureCode(code) {
     return OUTWARD_CODE_SHAPE.test(code) ? code : STORE_ERROR_CODE;
 }
+export function isCodeToken(code) {
+    return typeof code === "string" && CODE_TOKEN_SHAPE.test(code) && redactSecrets(code, { observe: false }) === code;
+}
+const CODE_TOKEN_SHAPE = /^[A-Za-z0-9_.:-]{1,64}$/;
+export function codeFieldOf(err) {
+    const code = errorCodeOf(err);
+    return isCodeToken(code) ? { code } : {};
+}
+export const PAUSE_SEATS = [
+    { path: ["terminal"], token: "token", gate: "gate" },
+    { path: ["terminal", "nestedPause"], token: "token", gate: "gate" },
+    { path: ["verification", "verifierPause"], token: "checkpointToken", gate: "checkpointGate" },
+];
+export function mapPauseSeats(result, f) {
+    let out = result;
+    for (const seat of PAUSE_SEATS)
+        out = mapSeatAt(out, seat.path, 0, (o) => f(o, seat));
+    return out;
+}
+function mapSeatAt(node, path, depth, f) {
+    if (node === null || typeof node !== "object" || Array.isArray(node))
+        return node;
+    if (depth === path.length)
+        return f(node);
+    const key = path[depth];
+    if (!Object.hasOwn(node, key))
+        return node;
+    const child = node[key];
+    const next = mapSeatAt(child, path, depth + 1, f);
+    return Object.is(next, child) ? node : { ...node, [key]: next };
+}
+function dropCapability(seat, keys) {
+    if (!Object.hasOwn(seat, keys.token))
+        return seat;
+    const { [keys.token]: _drop, ...rest } = seat;
+    return rest;
+}
 export function sealResultForExit(result) {
-    const t = result?.terminal;
-    if (t === null || typeof t !== "object")
+    return seal(result, "exit");
+}
+export function sealStoredResult(result, seat) {
+    return seal(result, seat);
+}
+function seal(result, at) {
+    if (result === null || typeof result !== "object")
         return result;
-    if (t.kind === "paused")
-        return { ...result, terminal: stripPausedToken(t) };
-    if (t.kind !== "failed")
+    return foldOutwardFailureCodes(mapPauseSeats(result, dropCapability), at);
+}
+function foldOutwardFailureCodes(result, at) {
+    const terminal = foldCauseCode(result.terminal, at);
+    const priorAttempts = result.attempts;
+    const attempts = foldAttemptCodes(priorAttempts, at);
+    const terminalKept = Object.is(terminal, result.terminal);
+    const attemptsKept = Object.is(attempts, priorAttempts);
+    if (terminalKept && attemptsKept)
         return result;
-    let terminal = t;
-    if (t.nestedPause !== undefined)
-        terminal = { ...terminal, nestedPause: stripPausedToken(t.nestedPause) };
-    if (t.code !== undefined) {
-        const outward = outwardFailureCode(t.code);
-        if (outward !== t.code) {
-            console.warn(`[terminal] outward_failure_code_folded original=${t.code} outward=${outward}`, { message: t.message });
-            terminal = { ...terminal, code: outward, message: `${t.message ?? "the durable store failed"} [original code: ${t.code}]` };
+    return { ...result, ...(terminalKept ? {} : { terminal }), ...(attemptsKept ? {} : { attempts }) };
+}
+function foldCauseCode(terminal, at) {
+    const t = failedCauseWithCode(terminal);
+    if (t === undefined)
+        return terminal;
+    const outward = outwardFailureCode(t.code);
+    if (outward === t.code)
+        return terminal;
+    reportFold(t.code, outward, t.message, at);
+    const message = typeof t.message === "string" ? t.message : "the durable store failed";
+    return { ...t, code: outward, message: `${message} [original code: ${t.code}]` };
+}
+function foldAttemptCodes(attempts, at) {
+    if (!Array.isArray(attempts))
+        return attempts;
+    let folded;
+    attempts.forEach((attempt, i) => {
+        if (attempt === null || typeof attempt !== "object")
+            return;
+        const code = attempt.errorCode;
+        if (typeof code !== "string")
+            return;
+        const outward = outwardFailureCode(code);
+        if (outward === code)
+            return;
+        reportFold(code, outward, undefined, at);
+        (folded ??= [...attempts])[i] = { ...attempt, errorCode: outward };
+    });
+    return folded ?? attempts;
+}
+const STORED_RESULT_FOLD_TAG = "server.terminal.stored-result-code-folded";
+function reportFold(code, outward, message, at) {
+    const messageBytes = typeof message === "string" ? Buffer.byteLength(message, "utf8") : 0;
+    const fields = `original=${isCodeToken(code) ? code : "<not-a-code>"} outward=${outward} messageBytes=${messageBytes} at=${at}`;
+    switch (at) {
+        case "exit":
+            console.warn(`[terminal] outward_failure_code_folded ${fields}`);
+            return;
+        case "run.result":
+        case "ev.done.result":
+            recordFailOpen(STORED_RESULT_FOLD_TAG, fields);
+            return;
+        default: {
+            const unhandled = at;
+            throw new Error(`unhandled fold sighting: ${String(unhandled)}`);
         }
     }
-    return terminal === t ? result : { ...result, terminal };
+}
+function failedCauseWithCode(t) {
+    if (t === null || typeof t !== "object")
+        return undefined;
+    const { kind, code } = t;
+    return kind === "failed" && typeof code === "string" ? { ...t, kind, code } : undefined;
 }
 export function outwardPlane(terminal) {
     const plane = terminalProjection(terminal);
@@ -35,10 +128,6 @@ export function outwardPlane(terminal) {
     const outward = outwardFailureCode(plane.errorCode);
     return outward === plane.errorCode ? plane : { ...plane, errorCode: outward };
 }
-function stripPausedToken(paused) {
-    const { token: _drop, ...rest } = paused;
-    return rest;
-}
 export function nestedPauseOf(terminal) {
     return terminal.kind === "failed" ? terminal.nestedPause : undefined;
 }

package/dist/tool-approval.d.ts

@@ -34,7 +34,7 @@ export declare function approvalDecidePath(sessionId: string): string;
 /**
  * [ref] 随批小件:`tool_approval.not_pending` 404 的**判别位**([ref] 排障代价实证 —— 三因合并成一句人话,现场分不出「答案没地方兑」与「打错副本了」)。
  * DECIDED/PARKED 已从 404 分流(DECIDED ⇒ 200 回放首决,回执带 `decidedBy`,**不是**成因;PARKED ⇒ 赎回席),残余两类:
- *  · 行 `VOID` / `DENIED`(没有人决过它)—— `cause` = **行上记的那个成因词**(问账 `denied_reason` 列;与决断口 410 `gone.ask` 体的 `cause`、审计 settle 行
+ *  · 行 `VOID` / `DENIED`(没有人决过它)—— `cause` = **行上记的那个成因词**(问账 `ending_cause` 列;与决断口 410 `gone.ask` 体的 `cause`、审计 settle 行
  *    的 `cause` 同一个词,闭集 {@link SettleCause});行上没写归因(存量行)⇒ 缺席,不替没写的行编一个词;
  *  · {@link NOT_PENDING_UNKNOWN_CAUSE} —— 无行 / 行不是调用方的 / 行仍在别处活着:换副本或换端点重试才有意义(这个词只属于 404 面,不是结局成因)。
  * 对齐 [ref] 反枚举语义:cause 只在**已过属主门**的面上出,不扩枚举面(属主门不过 = 与未知 id 同形)。
@@ -1666,7 +1666,8 @@ export declare class ToolApprovalCoordinator {
      *  ② 在 `deadlineMs` 之前等:未决卡结清、在飞腿闭合(闭了的腿照常落 `leg_closed`)、**本次路由到 park 的卡全部结清**
      *     (F1:观察到 core 已处置这次调用 —— 停车行提交或承载它的腿退场 ⇒ 那张卡的审计 settle 行此刻才写,见 {@link settleParksAwaitingCommit})、
      *     店里在飞的 `put` 静默;
-     *  ③ 到期:仍未闭的腿 ⇒ 审计落 `interrupted_by_shutdown` 记号(下一次 boot 收敛照样列出它,decided 臂的 `resumeSafe:false` 提醒不丢);
+     *  ③ 等待结束(全结清或到期)⇒ 审计落**一行**进程级 `interrupted_by_shutdown` 记录([ref]:有序收尾走完是进程的事实,不是腿的 —— 此刻还没结清的卡
+     *     不论在不在协调器的追踪视野里,下一次 boot 都写 `shutdown_before_park`;下一次 boot 收敛照样列出它们,decided 臂的 `resumeSafe:false` 提醒不丢);
      *     仍未提交的 park ⇒ settle 行**不写**(账本上仍是 pending 孤儿 ⇒ 下一次 boot 与崩溃同路收敛,证据不丢),交回调用方
      *     (`uncommittedParks`,运维 warn `approval_park_uncommitted_at_shutdown` 由关停序落 —— 它握 logger)。之后才观察到的照样写 settle 行
      *     (观察到就是结清,迟到也是)。
@@ -1674,7 +1675,7 @@ export declare class ToolApprovalCoordinator {
      * 的 await 里 —— 零活流的后台 / 委派子代也在内)在登记那一刻按同一条路收场(`askBroadcast` 的铸造审计点之后读这一位)。等待条件
      * 因此数「在飞的 ask」({@link asksInFlight},`askBroadcast` 进出计数)而不只是 `pending` —— 尚未登记的卡不在 `pending` 里。
      * `deadlineMs` 是绝对时刻(`Date.now()` 域):关停序对审批面与店 quiesce 读**同一个**到期点(一个宽限窗,不是两个)。
-     * 从不抛错(关停序不许被审计面卡住);再调一次 = 再等一次(记号有去重集,零重写)。
+     * 从不抛错(关停序不许被审计面卡住);再调一次 = 再等一次(关停记录一世一行,零重写)。
      */
     drainForShutdown(deadlineMs: number): Promise<{
         uncommittedParks: Array<{

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

@@ -17,9 +17,10 @@
  * ⑨⑩([ref],2026-08-31)把两个最大的 wire 面也纳入:TaskSpec 按「server 有无写点」记 Wired/Unwired,
  * TaskResult 按「转发/摘除」记 Forwarded/Stripped —— 谁改 resolve-spec.ts / runs.ts 的发射点谁同步本文件。
  */
-import type { TaskNotificationPayload, SemaProvenance, BackgroundChildEvent, RosterEntry, AskRequest, CheckpointSummary, PendingAction, TaskEvent, TraceEvent, MailboxMessage, MailboxAppendMessage, TaskSpec, TaskResult, SideQueryResult, WiringManifest, PermissionModeReceipt, GateOutcome, GateDisposition, Settlement, PausedCause, TerminalCause, WorkflowRun, ReadRootGrantCandidate, McpReconnectResult, McpServerStatus, NodeLspManagerOptions, RunnerDeps, SessionMemoryStatus, PromptManifestIdentity, PromptIdentityLayers, PromptManifestSelectors, PromptManifestSection, PromptChainLink, SupersededOverlay, ToolDisclosureManifest } from "@sema-agent/core";
+import type { TaskNotificationPayload, SemaProvenance, BackgroundChildEvent, RosterEntry, AskRequest, CheckpointSummary, PendingAction, TaskEvent, TraceEvent, MailboxMessage, MailboxAppendMessage, TaskSpec, TaskResult, SideQueryResult, WiringManifest, PermissionModeReceipt, GateOutcome, GateDisposition, Settlement, PausedCause, TerminalCause, CheckpointGate, CheckpointToken, VerificationResult, CascadeRunResult, WorkflowRun, ReadRootGrantCandidate, McpReconnectResult, McpServerStatus, NodeLspManagerOptions, RunnerDeps, SessionMemoryStatus, PromptManifestIdentity, PromptIdentityLayers, PromptManifestSelectors, PromptManifestSection, PromptChainLink, SupersededOverlay, ToolDisclosureManifest } from "@sema-agent/core";
 import type { ToolApprovalFrame } from "../tool-approval.js";
 import type { TableCoreKeys } from "./projection-table.js";
+import type { PauseSeat } from "../terminal.js";
 /** 编译期断言:T 必须收敛到 never(有残余键 = tsc 红)。
  *  🔴 **导出**([ref] U1/U2):本仓「词表闭集,未处置成员=编译红」的钉法只许有**一个**形 ——
  *  `observability/run-terminal.ts` 的三张叶表 + 结果顶层键表用同一只断言,而不是各自再抄一份
@@ -248,6 +249,190 @@ type TerminalArmForwarded = "kind" | "code" | "message" | "nestedPause" | "detai
 type TerminalArmStripped = never;
 type _GuardTerminalArm = AssertAllKeysHandled<Exclude<NonPausedTerminalKeys, TerminalArmForwarded | TerminalArmStripped>>;
 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}`;
+/** 两个型**全同**(不是「互相可赋」:全可选成员的子对象与它的父对象互相可赋,却不是同一个型)。 */
+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`
+ * 会让更深的座看不见;门内 `riskDescriptor` 的子树今天就到第 7 层)。
+ */
+type PathsTo<T, Leaf, Seen extends readonly unknown[] = [], D extends number = 12> = [D] extends [never] ? "<depth-exhausted>" : 0 extends 1 & T ? never : T extends Leaf ? "" : T extends string | 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<"[]", PathsTo<E, Leaf, [...Seen, T], SeatDepth[D]>> : T extends object ? {
+    [K in keyof T & string]-?: JoinPath<K, PathsTo<NonNullable<T[K]>, Leaf, [...Seen, T], SeatDepth[D]>>;
+}[keyof T & string] : never;
+type _SeatWalkDeep = {
+    verification: {
+        deep: {
+            a: {
+                b: {
+                    c: {
+                        d: {
+                            e: {
+                                f: {
+                                    t: CheckpointToken;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+type _SeatWalkCheckDepth8 = AssertAllKeysHandled<Exclude<"verification.deep.a.b.c.d.e.f.t", PathsTo<_SeatWalkDeep, CheckpointToken>>>;
+type _SeatWalkTooDeep = {
+    a: {
+        b: {
+            c: {
+                d: {
+                    e: {
+                        f: {
+                            g: {
+                                h: {
+                                    i: {
+                                        j: {
+                                            k: {
+                                                l: {
+                                                    m: {
+                                                        t: CheckpointToken;
+                                                    };
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+type _SeatWalkCheckExhaustionLoud = AssertAllKeysHandled<Exclude<"a.b.c.d.e.f.g.h.i.j.k.l.m.<depth-exhausted>", PathsTo<_SeatWalkTooDeep, CheckpointToken>>>;
+/** 本仓结算点交给封口的**全部出口结果类型**(普通腿 / 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;
+/** 座表上某一键(凭据 / 门)的全部路径,按行分配。⑩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>>;
@@ -478,7 +663,16 @@ export type CoreKeysetGuards = [
     _GuardLspOptionsReverse,
     _GuardLedgerRunnerDepsReverse,
     _GuardSessionWorkspace,
-    _GuardSessionWorkspaceReverse
+    _GuardSessionWorkspaceReverse,
+    _GuardTokenSeats,
+    _GuardTokenSeatsReverse,
+    _GuardGateSeats,
+    _GuardGateSeatsReverse,
+    _SeatWalkCheckDepth8,
+    _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 码元(含截断记号);
@@ -19,6 +20,9 @@ export type SafeText = string & {
  *    引擎放过的形照抹);界 200 码元,原样出门(JSON 串值,消费方自己渲染)。
  *  · `peer-declaration-sentence`:引擎判官对一份 MCP / A2A 对端声明说的句子(`toolAxes` / `toolFaces` / `sessionMetaKey` / 启动界的原因句,逐字带着声明方写的工具名、键名),
  *    进请求面 400 拒句、续跑重放的丢弃行与重读行、名册的跳过行 —— 读者是调用方与运维,句子已是一行;不设界(拒句要说全判官的话),原样出门。
+ *  · `inbox-diagnostics-text`:`workflow_complete` 补投帧上的诊断教学文本(`diagnostics`)—— 引擎在 workflow 完成通知上铸的「读哪里 / 怎么续跑」文本,入会话收件时洗一次,
+ *    店里(`payload` 列)只放出门安全的字节,drain 逐字带出。洗法与 live `task_notification.diagnostics` 同一个 scope(`free-text`);
+ *    这一行比 `trace-frame-text` 多一条界(4000 码元,与同族条目的文本位同额),原样出门:`payload` 列是 TEXT,无界的文本一旦超过列宽,入箱写整条失败、补投连摘要一起丢(完成已被记作送达),所以先有界。
  *  · `boot-refusal-line`:起服拒启的一行拒句 —— 部署座装配的拒句(`mods-declaration.ts`:声明的席名、包名、读包者 / 引擎准入交回的话);它经进程级 fatal 出口原样多行进 stderr,
  *    所以必须在这里先压成一行(一句拒因里的换行会在运维的终端里伪造出第二条日志行);界 512 码元(含截断记号)。
  */
@@ -62,6 +66,10 @@ declare const EXIT_SEATS: {
     readonly "peer-declaration-sentence": {
         readonly scope: "free-text";
     };
+    readonly "inbox-diagnostics-text": {
+        readonly scope: "free-text";
+        readonly maxChars: 4000;
+    };
     readonly "boot-refusal-line": {
         readonly scope: "free-text";
         readonly maxChars: 512;

package/dist/trace/exit-seat.js

@@ -14,6 +14,7 @@ const EXIT_SEATS = {
     "session-title": { scope: "free-text", maxChars: 80, emit: "title-line" },
     "mcp-remote-text": { scope: "free-text", maxChars: 200 },
     "peer-declaration-sentence": { scope: "free-text" },
+    "inbox-diagnostics-text": { scope: "free-text", maxChars: 4000 },
     "boot-refusal-line": { scope: "free-text", maxChars: 512, emit: "log-line" },
 };
 export function seatMaxChars(seat) {

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) => {