@sema-agent/server 7.52.0 → 7.53.0

package/dist/tool-approval.js

@@ -3,6 +3,7 @@ import { uuidv7, MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 import { precheckCardRuleText } from "./rules-consent.js";
 import { redactDeep, redactSecrets } from "./trace/redact.js";
 import { hasBidiControls } from "./text-bidi.js";
+import { approvalPayloadFingerprint } from "./plugins/approval-payload-fingerprint.js";
 import { createLogger } from "./observability/logger.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { deriveAskId, deriveBatchId, MAX_DECISION_NOTE_CHARS } from "./approval-ask-machine.js";
@@ -194,14 +195,21 @@ function effectiveAskWindowMs(ttlMs, windowMarginMs, legDeadlineMonotonic, nowMo
     return Math.min(ttlMs, Math.max(0, legRemainingMs - windowMarginMs));
 }
 function replayTerminalAskRow(row) {
-    if (row.state === "DECIDED")
-        return row.decision === "approve";
+    if (row.state === "DECIDED") {
+        if (row.decision !== "approve")
+            return false;
+        return row.updatedInput !== undefined ? { allow: true, updatedInput: row.updatedInput } : true;
+    }
     if (row.state === "PARKING" || row.state === "PARKED")
         return "unavailable";
     return false;
 }
-function recordRowDerivedApproveReplay(where) {
-    recordFailOpen("server.hitl.row-derived-approve-drops-updated-input", where);
+function settleArgsOf(outcome) {
+    if (outcome === "unavailable")
+        return "unavailable";
+    if (typeof outcome === "boolean")
+        return { allowed: outcome };
+    return { allowed: outcome.allow, ...(outcome.updatedInput !== undefined ? { updatedInput: outcome.updatedInput } : {}) };
 }
 export class ToolApprovalCoordinator {
     als = new AsyncLocalStorage();
@@ -445,8 +453,8 @@ export class ToolApprovalCoordinator {
             }
             if (this.editedDecisionInFlight(askId))
                 return undefined;
-            const replayed = replayTerminalAskRow(row);
-            return typeof replayed === "boolean" ? replayed : undefined;
+            const replayed = settleArgsOf(replayTerminalAskRow(row));
+            return replayed === "unavailable" ? undefined : replayed;
         }
         catch (err) {
             this.noteStoreError(err, "getAsk(expire-error-recovery)");
@@ -745,8 +753,6 @@ export class ToolApprovalCoordinator {
                 if (existingOrCreated.row.state !== "STREAM_PENDING") {
                     releaseAdmission();
                     const replayed = this.guardRowDerivedApprove(askId, replayTerminalAskRow(existingOrCreated.row), "ensure-ask-idempotent-replay");
-                    if (replayed === true)
-                        recordRowDerivedApproveReplay("ensure-ask-idempotent-replay");
                     return replayed === "unavailable" ? this.unattendedOutcome() : replayed;
                 }
                 const persistedEnvelope = ApprovalCardEnvelopeSchema.safeParse(existingOrCreated.row.cardJson);
@@ -909,14 +915,13 @@ export class ToolApprovalCoordinator {
                         await new Promise((r) => setTimeout(r, DURABLE_CONVERGE_BACKOFF_MS[attempt]).unref?.());
                         continue;
                     }
-                    const outcome = this.guardRowDerivedApprove(pinnedAskId, replayTerminalAskRow(row), `converge:${where}`);
+                    const outcome = settleArgsOf(this.guardRowDerivedApprove(pinnedAskId, replayTerminalAskRow(row), `converge:${where}`));
                     if (outcome === "unavailable") {
                         windowRouteUnavailable = true;
                         settle(false, "expired");
                     }
-                    else if (outcome === true) {
-                        recordRowDerivedApproveReplay(`converge:${where}`);
-                        settle(true, "allowed");
+                    else if (outcome.allowed) {
+                        settle(true, "allowed", outcome.updatedInput);
                     }
                     else {
                         settle(false, "denied");
@@ -973,9 +978,7 @@ export class ToolApprovalCoordinator {
                     this.noteStoreError(err, "expireAsk");
                     const decided = await this.readDecidedForRecovery(askId);
                     if (decided !== undefined && !done) {
-                        if (decided)
-                            recordRowDerivedApproveReplay("expire-error-recovery");
-                        settle(decided, decided ? "allowed" : "denied");
+                        settle(decided.allowed, decided.allowed ? "allowed" : "denied", decided.updatedInput);
                         return;
                     }
                     settleParkRouteIfUnsettled(hostSelfReport);
@@ -1288,9 +1291,7 @@ export class ToolApprovalCoordinator {
             });
             return this.notPending();
         }
-        const settled = this.notifyExternalDecision(row.askId, row.decision === "approve");
-        if (row.decision === "approve" && settled.settled > 0)
-            recordRowDerivedApproveReplay("respond-late-replay");
+        this.notifyExternalDecision(row.askId, row.decision === "approve", row.updatedInput);
         return {
             status: 200,
             body: {
@@ -1559,11 +1560,13 @@ export class ToolApprovalCoordinator {
     }
     async respondWithCas(askStore, askId, batchId, id, entry, parsed, ruleEligibility) {
         let decidedWon = false;
+        let confirmedRowPayload;
         let noteLanded = false;
         try {
             const decided = await this.withStoreDeadline(askStore.decideAsk(askId, batchId, {
                 decision: parsed.value === "deny" ? "deny" : "approve",
                 ...(parsed.note !== undefined ? { decisionNote: parsed.note } : {}),
+                ...(parsed.value !== "deny" && parsed.updatedInput !== undefined ? { updatedInput: parsed.updatedInput } : {}),
             }), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
                 if (late.ok)
                     this.notifyExternalDecision(askId, parsed.value !== "deny", parsed.updatedInput);
@@ -1582,6 +1585,7 @@ export class ToolApprovalCoordinator {
                 const row = await this.withStoreDeadline(askStore.getAsk(askId), "getAsk(decideAsk-confirm)", DURABLE_CONVERGE_READ_TIMEOUT_MS);
                 if (row?.state === "DECIDED" && row.decision === (parsed.value === "deny" ? "deny" : "approve")) {
                     decidedWon = true;
+                    confirmedRowPayload = { updatedInput: row.updatedInput };
                     noteLanded = parsed.note === undefined || row.decisionNote === parsed.note;
                 }
             }
@@ -1592,15 +1596,20 @@ export class ToolApprovalCoordinator {
         const wantAllowed = parsed.value !== "deny";
         if (this.pending.get(id) !== entry) {
             if (decidedWon)
-                this.notifyExternalDecision(askId, wantAllowed, parsed.updatedInput);
+                this.notifyExternalDecision(askId, wantAllowed, confirmedRowPayload !== undefined ? confirmedRowPayload.updatedInput : parsed.updatedInput);
             const converged = decidedWon && entry.settledOutcome === (wantAllowed ? "allowed" : "denied");
             if (!converged) {
                 return this.notPending();
             }
             return this.finishRespond(id, entry, parsed, { updatedInputDelivered: false, noteRecorded: noteLanded });
         }
-        const result = this.finishRespond(id, entry, parsed, { noteRecorded: noteLanded });
-        this.notifyExternalDecision(askId, wantAllowed, parsed.updatedInput);
+        const payloadIsMine = confirmedRowPayload === undefined ||
+            approvalPayloadFingerprint({ updatedInput: confirmedRowPayload.updatedInput }) === approvalPayloadFingerprint({ updatedInput: parsed.updatedInput });
+        const result = this.finishRespond(id, entry, parsed, {
+            noteRecorded: noteLanded,
+            ...(confirmedRowPayload !== undefined ? { settlePayload: confirmedRowPayload, updatedInputDelivered: payloadIsMine } : {}),
+        });
+        this.notifyExternalDecision(askId, wantAllowed, confirmedRowPayload !== undefined ? confirmedRowPayload.updatedInput : parsed.updatedInput);
         return result;
     }
     finishRespond(id, entry, parsed, opts) {
@@ -1617,7 +1626,7 @@ export class ToolApprovalCoordinator {
             this.allowAllSessions.add(sessionAllowKey(entry.owner, entry.sessionId, sessionAllowCategory(entry.toolName)));
         }
         const allowed = parsed.value !== "deny";
-        entry.settle(allowed, allowed ? "allowed" : "denied", parsed.updatedInput, undefined, allowed ? undefined : parsed.note);
+        entry.settle(allowed, allowed ? "allowed" : "denied", opts?.settlePayload !== undefined ? opts.settlePayload.updatedInput : parsed.updatedInput, undefined, allowed ? undefined : parsed.note);
         const updatedInputDelivered = opts?.updatedInputDelivered ?? true;
         const noteRecorded = opts?.noteRecorded ?? false;
         return {
@@ -1687,18 +1696,14 @@ export class ToolApprovalCoordinator {
                 continue;
             if (this.editedDecisionInFlight(askId))
                 continue;
-            const outcome = replayTerminalAskRow(row);
+            const outcome = settleArgsOf(replayTerminalAskRow(row));
             if (outcome === "unavailable") {
                 const before = this.pendingByAskId.get(askId)?.size ?? 0;
                 this.settleSameAskIdParkRoute(askId);
                 settled += before;
                 continue;
             }
-            if (typeof outcome !== "boolean")
-                continue;
-            const delivered = this.notifyExternalDecision(askId, outcome).settled;
-            if (outcome && delivered > 0)
-                recordRowDerivedApproveReplay("poll-suspended");
+            const delivered = this.notifyExternalDecision(askId, outcome.allowed, outcome.updatedInput).settled;
             settled += delivered;
         }
         const backlog = Math.max(0, candidates.length - polled);

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

@@ -1,9 +1,9 @@
 /**
- * L1 键集机器门([1549] 方法论倡议 server 认领件;clay 令 2026-07-23「不能永远编码有限→复审补漏」)。
+ * L1 键集机器门([ref] 方法论倡议 server 认领件;clay 令 2026-07-23「不能永远编码有限→复审补漏」)。
  *
  * 病族:**投影白名单剥键**——core 给源类型加 additive 新键,server 的列投影/白名单静默丢,直到穿透
- * 审查才被人肉抓。已四案:RosterEntry.model([1532])、task_progress.status / TaskNotificationPayload
- * 四键 / BackgroundChildEvent.usage+transcriptId([1543] 族B)、SDK 0.0.72 fleet meta 剥键。
+ * 审查才被人肉抓。已四案:RosterEntry.model([ref])、task_progress.status / TaskNotificationPayload
+ * 四键 / BackgroundChildEvent.usage+transcriptId([ref] 族B)、SDK 0.0.72 fleet meta 剥键。
  *
  * 机制:对每个「core 源类型 → server 投影」面声明**已处置键集** = PROJECTED(真透传)∪ EXCLUDED
  * (显式记账不透传,理由必写)。`Exclude<keyof 源, 已处置>` 约束为 never——**升 core 后源类型出新键
@@ -14,15 +14,17 @@
  *
  * 维护:core 新键到来时,transparently 透传的加进对应 PROJECTED 并去实现投影;有意不上 wire 的加进
  * EXCLUDED 并写一行理由。谁改投影(project.ts / fleet-bus.ts / roster-store-sql.ts)谁同步本文件。
+ * ⑨⑩([ref],2026-08-31)把两个最大的 wire 面也纳入:TaskSpec 按「server 有无写点」记 Wired/Unwired,
+ * TaskResult 按「转发/摘除」记 Forwarded/Stripped —— 谁改 resolve-spec.ts / runs.ts 的发射点谁同步本文件。
  */
-import type { TaskNotificationPayload, BackgroundChildEvent, RosterEntry, AskRequest, CheckpointSummary, TaskEvent, TraceEvent, MailboxMessage, MailboxStore } from "@sema-agent/core";
+import type { TaskNotificationPayload, BackgroundChildEvent, RosterEntry, AskRequest, CheckpointSummary, TaskEvent, TraceEvent, MailboxMessage, MailboxStore, TaskSpec, TaskResult } from "@sema-agent/core";
 /** 编译期断言:T 必须收敛到 never(有残余键 = tsc 红)。 */
 type AssertAllKeysHandled<T extends never> = T;
-type NotificationProjected = "task_id" | "task_type" | "toolUseId" | "status" | "summary" | "result" | "output_file" | "usage" | "sessionId" | "seq" | "lines" | "stoppedBy" | "source" | "exitCode" | "partial" | "diagnostics" | "recentSteps" | "editedFiles" | "resumable" | "completionId" | "error" | "errorCode";
+type NotificationProjected = "task_id" | "task_type" | "toolUseId" | "status" | "summary" | "result" | "output_file" | "usage" | "sessionId" | "seq" | "lines" | "stoppedBy" | "source" | "exitCode" | "partial" | "diagnostics" | "recentSteps" | "editedFiles" | "resumable" | "completionId" | "error" | "errorCode" | "apiFailure";
 type NotificationExcluded = "peer";
 type _GuardNotification = AssertAllKeysHandled<Exclude<keyof TaskNotificationPayload, NotificationProjected | NotificationExcluded>>;
 type BgNotifProjected = "taskId" | "sessionId" | "seq" | "status" | "summary" | "stoppedBy" | "resumable" | "recentSteps" | "editedFiles" | "usage" | "transcriptId" | "rootSessionId" | "parentTaskId" | "parentToolCallId" | "completionId";
-type BgNotifExcluded = "kind" | "sessionScoped" | "owner" | "scope" | "description" | "agentType" | "name" | "currentAction" | "currentTool" | "parentSessionId" | "startedAt" | "workflowRunId" | "progressTaskId" | "progressParentTaskId";
+type BgNotifExcluded = "kind" | "sessionScoped" | "owner" | "scope" | "description" | "agentType" | "name" | "currentAction" | "currentTool" | "parentSessionId" | "startedAt" | "workflowRunId" | "progressTaskId" | "progressParentTaskId" | "model";
 type _GuardBgNotif = AssertAllKeysHandled<Exclude<keyof BackgroundChildEvent, BgNotifProjected | BgNotifExcluded>>;
 type RosterProjected = "name" | "agentId" | "sessionId" | "toolUseId" | "owner" | "scope" | "sessionScoped" | "rootSessionId" | "model" | "modelFallback" | "createdAt";
 type _GuardRoster = AssertAllKeysHandled<Exclude<keyof RosterEntry, RosterProjected>>;
@@ -47,6 +49,14 @@ type _GuardPermissionTraceNonEmpty = AssertAllKeysHandled<AssertNonEmpty<Permiss
 type SummaryProjected = "sessionId" | "scope" | "createdAt" | "gateKind" | "severity" | "spentMicroUsd" | "deadline" | "hasBidiControls";
 type SummaryExcluded = "token" | "toolInput" | "toolName" | "toolCallId" | "preview" | "principal" | "sourceTaskId" | "contentKind" | "restoreMode" | "checkpointId" | "previewWithheld";
 type _GuardInboxSummary = AssertAllKeysHandled<Exclude<keyof CheckpointSummary, SummaryProjected | SummaryExcluded>>;
+type TaskSpecWired = "objective" | "principal" | "images" | "sessionId" | "requireExistingSession" | "oneShot" | "clientContext" | "resumeAt" | "resumeAtMode" | "model" | "compactionModel" | "thinking" | "systemPrompt" | "appendSystemPrompt" | "promptProvider" | "memory" | "suggestNextPrompts" | "restoreFiles" | "acceptPartialRestore" | "rewindFilesTo" | "tools" | "excludeTools" | "deferTools" | "toolMaterializeStrategy" | "promptProfile" | "toolPolicy" | "onAsk" | "onQuestion" | "hooks" | "durableApproval" | "resourceSuspend" | "resilience" | "finalVerification" | "checkpointStore" | "handsReadOnly" | "memoryPersistenceCapable" | "additionalDirectories" | "additionalReadDirectories" | "enablePlanMode" | "interactiveTools" | "enableFork" | "shellGate" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "taskId" | "signal" | "preemptSignal" | "modelRole" | "enableBlockedReport" | "maxSuspends";
+type TaskSpecUnwired = "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars";
+type _GuardTaskSpec = AssertAllKeysHandled<Exclude<keyof TaskSpec, TaskSpecWired | TaskSpecUnwired>>;
+type _GuardTaskSpecReverse = AssertAllKeysHandled<Exclude<TaskSpecWired | TaskSpecUnwired, keyof TaskSpec>>;
+type TaskResultForwarded = "taskId" | "runId" | "sessionId" | "status" | "model" | "effectiveReasoning" | "result" | "salvagedOutput" | "blockedReason" | "checkpointId" | "checkpointGate" | "workspaceRestoreMode" | "remoteEnvFailures" | "errorMessage" | "errorCode" | "apiFailure" | "retryAfterMs" | "degraded" | "structuredOutput" | "rewindNotes" | "haltedOnUserRejection" | "haltedByUser" | "strandedHumanAnswers" | "pendingApproval" | "approvalWaitedMs" | "effectiveReadFace" | "effectiveReadDenyPatterns" | "effectiveMemoryScopes" | "stats";
+type TaskResultStripped = "checkpointToken";
+type _GuardTaskResult = AssertAllKeysHandled<Exclude<keyof TaskResult, TaskResultForwarded | TaskResultStripped>>;
+type _GuardTaskResultReverse = AssertAllKeysHandled<Exclude<TaskResultForwarded | TaskResultStripped, keyof TaskResult>>;
 export type CoreKeysetGuards = [
     _GuardNotification,
     _GuardBgNotif,
@@ -58,7 +68,11 @@ export type CoreKeysetGuards = [
     _GuardPermissionTrace,
     _GuardPermissionTraceReverse,
     _GuardPermissionTraceNonEmpty,
-    _GuardInboxSummary
+    _GuardInboxSummary,
+    _GuardTaskSpec,
+    _GuardTaskSpecReverse,
+    _GuardTaskResult,
+    _GuardTaskResultReverse
 ];
 export {};
 //# sourceMappingURL=core-keyset-guard.d.ts.map

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

@@ -4,15 +4,15 @@
  * 码数的**受门**真源=契约文档附录 D.3 的小节标题,⑥b 双向门盯着)。
  *
  * 起步的那六码同族:都是「这条 session 的记忆姿态」的披露,resume 之后仍然相关 ⇒ 也进 durable 账本
- * (cli 断连补看走既有 events 重放腿,[4634](ii))。
+ * (cli 断连补看走既有 events 重放腿,[ref](ii))。
  *
- * ⚠️ **自 #366(core 5.61.0)起本表不再是单一族**:`task.turn_interrupted` 与 `task.user_*_undrained`
+ * ⚠️ **自 [ref](core 5.61.0)起本表不再是单一族**:`task.turn_interrupted` 与 `task.user_*_undrained`
  * 两族是前三条**非记忆面**的成员(前者=一次插话真的切断了在飞的 turn;后两者=用户的输入被彻底丢弃)。
  * 判据没有变(受众 × 投递可行性 × 去重单位三条合取,见顶注),变的只是「碰巧六条都是记忆码」这个
  * 事实——别再把「是不是记忆姿态码」当成入册的隐性第四条判据。这条隐性判据正是 `task.user_*_undrained`
  * 两码在明拒表里陈腐多时的帮凶之一(见它们的键注)。
  *
- * 🔴 **表长了就得同步三处**(#366 实测,少一处即门红):`test/engine-notice-wire.test.ts` 的闭集 pin、
+ * 🔴 **表长了就得同步三处**([ref] 实测,少一处即门红):`test/engine-notice-wire.test.ts` 的闭集 pin、
  * 同文件 G1 e2e 的全码扇出夹具、以及契约文档附录 D.3 那张表(含**小节标题里的码数** —— 那道门本批
  * 刚立,立完就在下一次加码时自己咬住了)。
  */
@@ -24,7 +24,7 @@ export declare function isEngineNoticeWireCode(code: string): code is EngineNoti
  * 归属键抽取 —— `detail.sessionId` 提升为顶层(设计稿 ②:归属键一等化)。
  *
  * 非串 / 空串一律按**缺席**处理(不铸 `"undefined"` 这种看起来合法的假值——`compactionOutcomeEventData`
- * 的同款缺键守卫纪律)。core [4631] 的顶层 `EngineNotice.sessionId` 到货后,这里先读顶层再回落 detail
+ * 的同款缺键守卫纪律)。core [ref] 的顶层 `EngineNotice.sessionId` 到货后,这里先读顶层再回落 detail
  * (两处同值,additive 零 BREAKING),届时本函数是唯一改动点。
  */
 export declare function engineNoticeSessionId(notice: {
@@ -37,7 +37,7 @@ export interface EngineNoticeWireRow {
     code: string;
     /**
      * core 铸的人话行。🔴 **仅 fallback 展示,不是匹配键**:core 明写 `memory.session_polluted` 的 message
-     * 随 `memoryProvenance` 模式变文(design/336 mode-aware),按 message 匹配必碎(5.41 合流码形退役同教训)。
+     * 随 `memoryProvenance` 模式变文([ref] mode-aware),按 message 匹配必碎(5.41 合流码形退役同教训)。
      */
     message: string;
     /** 机器可读事实,逐键消毒后直透(见 {@link sanitizeNoticeDetail} 的消毒/尺寸契约)。 */
@@ -82,7 +82,7 @@ export type EngineNoticeWireSink = (row: EngineNoticeWireRow) => void;
  *
  * 🔴 跨 session 隔离靠的是 **Map 键的精确串相等**,不是任何「最近活跃」回落 —— 缺席就是缺席(G5)。
  *
- * 🔴 **同 session 的跨代隔离靠 legId「最新代独占」**(#310 codex 交叉复审 R1-[high],验真后修)。
+ * 🔴 **同 session 的跨代隔离靠 legId「最新代独占」**([ref] codex 交叉复审 R1-[high],验真后修)。
  * 病(真窗,本仓每一处 in-flight 登记都为它写过 identity-guard):run 行在**流体内**就已 setTerminal /
  * setSuspended,而本腿的注销在 `finally` —— 中间那一窗里,同一条 session 上的**下一条腿**(快速续跑 /
  * 紧接着的新提交)已经注册好了自己的口。若按「会话内全量扇出」投,新腿的一条通告会**同时**落进:

package/dist/trace/injection-tier.d.ts

@@ -1,5 +1,5 @@
 /**
- * design/373 注入档位(core 5.61.0)的**闭集单点**(#366)。
+ * [ref] 注入档位(core 5.61.0)的**闭集单点**([ref])。
  *
  * ## 为什么本仓要自己留一份词表
  * 理想写法是复用 core 的谓词 `isSystemInjectionPriority` / 数据表 `SYSTEM_INJECTION_PRIORITIES`。
@@ -15,7 +15,7 @@
  * ## 为什么单独一个叶子模块
  * 消费点有两个且分属两条依赖链:`trace/project.ts`(wire 投影)与
  * `orchestration/workflow-completion-inbox.ts`(durable park 载荷)。手抄两份就是值拷贝漂移源
- * (本仓 [1532] 起的老病族);把它挂在任一方又会在两条链之间拉一条没必要的边。零依赖叶子最干净。
+ * (本仓 [ref] 起的老病族);把它挂在任一方又会在两条链之间拉一条没必要的边。零依赖叶子最干净。
  *
  * 🔴 上游哪天补了根导出:删掉本文件,两处改成一行谓词调用。
  */

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

@@ -1,5 +1,5 @@
 /**
- * runs 账本(`task_run_event`)的**事件型闭集**——A-032 P1-③ / codex 交叉复审 F2。
+ * runs 账本(`task_run_event`)的**事件型闭集**——[ref] P1-③ / codex 交叉复审 F2。
  *
  * ## 为什么需要这个联合
  * 账本行的 `type` 是消费端分流的键:`GET /v1/runs/:id/events` 裸回放照发,而 `trace/project.ts` 的
@@ -36,12 +36,12 @@ export type LedgerEventType = "reasoning" | "text" | "tool_start" | "tool_end" |
  | "suspended" | "needs_review" | "done" | "failed" | "suggestions" | "model_usage" | "prompt_assembled" | "config_assembled" | "file_link"
 /** 人在环三族的 open/close 帧对(投递面 = 本腿的 durable events tail)。 */
  | "elicitation" | "elicitation_complete" | "question" | "question_complete" | "tool_approval" | "tool_approval_complete"
-/** design/172 §4.3 新协议的呈卡帧(与上面两只 tool_approval 帧同一条投递面)。 */
+/** [ref] §4.3 新协议的呈卡帧(与上面两只 tool_approval 帧同一条投递面)。 */
  | "approval_request"
 /** 异步 workflow 完成的入箱 drain(`emitPendingWorkflowCompletions` 两个字面型之一)。 */
  | "workflow_complete"
 /**
- * #310 `engine_notice` —— core `EngineNotice` 白名单三码按 `detail.sessionId` 路由到该会话的事件投影。
+ * [ref] `engine_notice` —— core `EngineNotice` 白名单三码按 `detail.sessionId` 路由到该会话的事件投影。
  *
  * 🔴 **是"腿自己的带外行",不是流事件投影**:它不经 `TaskStream`(`RunnerDeps.onNotice` 是 deps 级
  * 同步 sink),所以两条 durable 腿的 `switch (ev.type)` 里**没有也不该有** `case "engine_notice"` ——

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

@@ -5,7 +5,7 @@ import type { LedgerEventType } from "./ledger-events.js";
  * LedgerSink — the SINGLE "stream event → durable runs-ledger" projection, shared by the background leg
  * (runs.ts `runInBackground`) and the sync `/v1/tasks/stream` detach lane (server.ts, `x-detach-on-disconnect`).
  *
- * [900]①/[906]③: the sync leg historically persisted only createRun+setTerminal — its events ledger stayed
+ * [ref]①/[ref]③: the sync leg historically persisted only createRun+setTerminal — its events ledger stayed
  * EMPTY, so after a detach the shell could only poll the terminal row. Feeding the same sink on the detach
  * lane makes `GET /v1/runs/:id/events` replay the full stream in the EXACT bg-leg vocabulary (the ledger
  * consumer binds to these type/data shapes — a second copy of this switch would drift into a false ledger,
@@ -35,7 +35,7 @@ export interface LedgerSink {
         type: string;
     }): Promise<void>;
     /**
-     * #255(core 5.34.0 的 `RunInternals.onStatusEvent` 第五席):**「只回结果」腿**的 `status` 行写口。
+     * [ref](core 5.34.0 的 `RunInternals.onStatusEvent` 第五席):**「只回结果」腿**的 `status` 行写口。
      *
      * 与 {@link onEvent} 的 `case "status"` 共用**同一个**白名单 builder(`brainStatusEventData`),差别只有
      * 一处:本门**同步入链** —— 在回调进入的那一刻就占住序号槽,而不是先 `await flush()` 再入链。
@@ -58,7 +58,7 @@ export interface LedgerSink {
     onForwardEvent(e: {
         type?: string;
     }): void;
-    /** Park event (durable F4 suspend / design/80 D-B review pause): ONLY the non-secret `checkpointGate` is
+    /** Park event (durable F4 suspend / [ref] D-B review pause): ONLY the non-secret `checkpointGate` is
      *  persisted — never the capability `checkpointToken` (search [18] Q1b). */
     appendParked(kind: "suspended" | "needs_review", result: unknown): Promise<void>;
     /** Terminal `done` event. `result` must already be checkpoint-token-stripped (and, on the bg leg,
@@ -71,13 +71,13 @@ export interface LedgerSink {
     }): Promise<void>;
 }
 /**
- * **单写串行链**的可复用形(#310 codex 交叉复审 R1-[high],验真后修)—— `seq` 的**分配发生在链步内**,
+ * **单写串行链**的可复用形([ref] codex 交叉复审 R1-[high],验真后修)—— `seq` 的**分配发生在链步内**,
  * 于是「分配序 == 发起序 == 提交序」。
  *
  * 病(实测形,`LedgerSink` 内部早有这条纪律的内联版、其顶注 [1.211 codex H2] 逐字记着它):裸写口
  * (`(type, data) => rs.appendEvent(taskId, ++seq, type, data)`)在**同步分配 seq、立刻发起 insert**。
  * 主循环 await 自己的写,所以主循环内部有序;但只要有**一个 fire-and-forget 写者**(子代 forward 帧、
- * #310 的通告口),它的 N 号 insert 可能在池化 SQL 后端上晚于后发的 N+1 号提交。events tail 的读法是
+ * [ref] 的通告口),它的 N 号 insert 可能在池化 SQL 后端上晚于后发的 N+1 号提交。events tail 的读法是
  * `getEvents(id, afterSeq)` —— 读到 N+1 就把游标推过 N,**那一行此后永远不会被投递**(重连也不会,
  * 游标只前进)。行在库里,消费端结构性看不见。
  *
@@ -93,11 +93,11 @@ export declare function createLedgerSink(opts: {
     /** TRACE_THINKING gate: reasoning deltas are buffered (later redacted+persisted) only when true (core [R57] —
      *  persisting CoT is a deployment decision). Both legs pass the SAME config source (`config.traceThinking`). */
     persistThinking: boolean;
-    /** task_notification dedup ledger (core [784]④a seq-folded keys). The bg leg passes its per-leg instance
+    /** task_notification dedup ledger (core [ref]④a seq-folded keys). The bg leg passes its per-leg instance
      *  (shared with its observer/drain arms so no arm double-appends a key another arm delivered); a leg with no
      *  other durable arms (sync detach lane) omits it and gets a private instance. */
     notifiedKeys?: NotifiedKeys;
-    /** #245 S1:turn 活性打点(`recordTurnActivity(taskId)`)。打点位有两处且都必须:①`onEvent` 入口
+    /** [ref] S1:turn 活性打点(`recordTurnActivity(taskId)`)。打点位有两处且都必须:①`onEvent` 入口
      *  ——**text_delta/reasoning_delta 只进内存缓冲、到 flush 边界才 append**(codex S1-F1,2026-08-13:
      *  只打 append 会让长时间流式输出被误读成「无进展」,方向与本键的设计目的正好相反);②`append`
      *  入口——兜住不经 onEvent 的直写路径(appendParked/appendDone/onForwardEvent)。分诊提示性回调: