@sema-agent/server 7.14.0 → 7.16.0-rc.1

package/dist/run-local.js

@@ -582,6 +582,7 @@ export async function runLocal(argv, deps = {}) {
      */
     const sharedRunnerDeps = createSharedRunnerDeps({
         config,
+        logger, // #240②:onNotice 席(共享基座键,本地形同席——结构化通告落同一 logger)
         // 交接件⑤:commit 尾注署名座进**共享基座** ⇒ 主 runner 与 subRunner 同源。
         // [931]① clay 拍:run-local = Sema 品牌本地形态,commit 尾注接 Sema 署名(core 1.300 缺省已翻转不署)。
         // 修前它只写在下面主 runner 的差异键里 ⇒ **委派出去的子代提交不带署名**,而它提交进的是同一个仓、

package/dist/tool-approval.d.ts

@@ -190,6 +190,7 @@ export declare function parseToolApprovalResponse(body: unknown): {
     value: ToolApprovalDecision;
     updatedInput?: unknown;
     persistRule?: string;
+    note?: string;
 } | {
     ok: false;
     error: string;
@@ -418,7 +419,16 @@ export declare class ToolApprovalCoordinator {
      * `req.args` 是 `unknown` ⇒ 窄读,**禁裸 as-cast**(宪法 [2704]:一个形状漂了的 args 若被 cast,
      * 会把 `undefined` 当命令送进 `prepareCardApproval`,那是放宽面上的静默垃圾)。
      */
+    /** 两份候选是否**逐条逐键**相等(顺序即展示序 ⇒ 顺序敏感)。两侧都缺席 = 相等;一侧缺席 = 不等。
+     *  用在幂等重入的「行 = 真源」对账上(见 `ensureAsk` 那段撤回臂)。 */
+    private static ruleSuggestionsEqual;
     private buildRuleLaneMaterial;
+    /** #241([3731]/[3730] 双属主裁定):把某 wire run 的**流内未决 ask** 立即转 durable park——断连支专用。
+     *  匹配键=`ctxTaskId`(wire run id)。该字段的顶注说它「不是清扫判据」——那是因为清扫要判**连接**的
+     *  生死(同 id 可被两个 ctx 实例复用);本臂语义不同:调用方就是该 wire run 的承载流,断连=这个 id 的
+     *  流没了,值相等即目标集;极端复用形下多转的那条也只是从流内卡变 durable 卡,方向保守。
+     *  返回触发条数(0 = 无流内未决 ask,调用方照旧 abort)。幂等:已结算条目跳过,重复调用无害。 */
+    parkOpenAsksForTask(wireTaskId: string): number;
     /** 测试/可观测性钩子(X-2):某 (taskId) 维当前占用的准入名额数。 */
     admittedCount(taskId: string): number;
     /** #151 车2(D5 store 故障姿势):任何 store 调用 throw ⇒ fail-open 到进程内机械照旧(store 是记账/

package/dist/tool-approval.js

@@ -47,8 +47,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7, MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "./trace/redact.js";
 import { createLogger } from "./observability/logger.js";
-import { deriveAskId, deriveBatchId } from "./approval-ask-machine.js";
-import { ApprovalCardEnvelopeSchema, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, } from "./approval-card.js";
+import { deriveAskId, deriveBatchId, MAX_DECISION_NOTE_CHARS } from "./approval-ask-machine.js";
+import { ApprovalCardEnvelopeSchema, MAX_RULE_SUGGESTIONS, buildApprovalCard, buildApprovalCardEnvelope, buildApprovalRequestFrame, buildRevokeFrame, } from "./approval-card.js";
 import { governanceAskMarksFor, runWithGovernanceAskScope } from "./governance-ask-marks.js";
 /** #151 车2:本模块自有的日志出口——同 config-provider.ts/runtime-caps-resolver.ts 先例(协调器不走
  *  DI logger,构造签名是设计定稿钉死的三键 options bag,加第四个 logger 键属于重议已裁事项）。仅用于
@@ -159,7 +159,27 @@ export function parseToolApprovalResponse(body) {
             }
             persistRule = rule;
         }
-        return { ok: true, value: d, ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}), ...(persistRule !== undefined ? { persistRule } : {}) };
+        // #229(设计稿 233 稿B):回决**理由**。与 durable 腿(`http/routes/runs.ts` 的 `AskDecisionBodySchema.note`)
+        // **同词同源同上限**({@link MAX_DECISION_NOTE_CHARS}),落的也是同一列 `decision_note` —— 不造第三口径。
+        // 🔴 **任何 decision 都可带**(deny 也算),与 durable 腿的无条件记账形对齐:「为什么拒」正是审计面上
+        // 最值钱的那一条,做成 allow-only 等于把它扔掉。⚠️ `allow_session` 是 wire 上的三值之一,落到行上是
+        // `approve`(三值映二值)—— 它的 note 因此记在**那条 approve 行**上,不另开一行、也不丢。
+        // 坏形(非串 / 超上限)是**响亮 400**,不静默截断:一条被悄悄砍半的审计理由比没有理由更坏。
+        const rawNote = body.note;
+        let note;
+        if (rawNote !== undefined) {
+            if (typeof rawNote !== "string" || rawNote.length > MAX_DECISION_NOTE_CHARS) {
+                return { ok: false, error: `note must be a string of at most ${MAX_DECISION_NOTE_CHARS} characters` };
+            }
+            note = rawNote;
+        }
+        return {
+            ok: true,
+            value: d,
+            ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}),
+            ...(persistRule !== undefined ? { persistRule } : {}),
+            ...(note !== undefined ? { note } : {}),
+        };
     }
     return { ok: false, error: 'decision must be one of "allow" | "allow_session" | "deny"' };
 }
@@ -430,6 +450,15 @@ export class ToolApprovalCoordinator {
      * `req.args` 是 `unknown` ⇒ 窄读,**禁裸 as-cast**(宪法 [2704]:一个形状漂了的 args 若被 cast,
      * 会把 `undefined` 当命令送进 `prepareCardApproval`,那是放宽面上的静默垃圾)。
      */
+    /** 两份候选是否**逐条逐键**相等(顺序即展示序 ⇒ 顺序敏感)。两侧都缺席 = 相等;一侧缺席 = 不等。
+     *  用在幂等重入的「行 = 真源」对账上(见 `ensureAsk` 那段撤回臂)。 */
+    static ruleSuggestionsEqual(a, b) {
+        if (a === undefined || b === undefined)
+            return a === b;
+        if (a.length !== b.length)
+            return false;
+        return a.every((x, i) => x.rule === b[i].rule && x.match === b[i].match && x.command === b[i].command);
+    }
     buildRuleLaneMaterial(req, owner, governanceForced) {
         if (this.ruleConsent === undefined)
             return undefined;
@@ -449,9 +478,21 @@ export class ToolApprovalCoordinator {
         // 「单机 + 无 principal」的部署第一次同时满足其余三项。
         if (owner === null)
             return undefined;
-        const suggestions = req.ruleSuggestions;
-        if (!Array.isArray(suggestions) || suggestions.length === 0)
+        const rawSuggestions = req.ruleSuggestions;
+        if (!Array.isArray(rawSuggestions) || rawSuggestions.length === 0)
             return undefined;
+        // 🔴 **基数帽在这里扣,而且只在这里扣**(重扫二轮红先修)。此前同步腿对这一格**零执法**:两族帧与
+        // `card_json` 都是逐字透传,真正按 {@link MAX_RULE_SUGGESTIONS} 截的只有耐久腿
+        // (`boundedRuleSuggestions`)。于是上游给 5 条时:live 帧发 5 条(契约文 §4a-bis 却把「server 执法帽 4」
+        // 写在**活卡帧**这条载体上,消费端按 ≤4 布局)、`card_json` 落 5 条,而一切读面都过
+        // `ApprovalCardSchema`(`ruleSuggestions.max(4)`)⇒ 判假 ⇒ 重放腿跳过 + `persisted-row-unusable` 臂返
+        // `"unavailable"` ⇒ **整只 ask 走 park**。那条「容忍余量」的设计意图在同步腿上完全没兑现,只是把悬崖
+        // 从 2 挪到了 4。
+        // 截在**素材铸点**而不是 `buildApprovalCard`:后者只截卡,会让 live 帧(5 条)与卡(4 条)分家,违背
+        // `approval-card.ts` 顶注自证的「wire 帧与 card_json 用同一份已洗素材,不是两处各算一遍的巧合」。
+        // 单一属主收在这里,于是**两族帧 + `card_json` + 回决口 `rule_not_offered` 的等式左边**拿的是同一份 ——
+        // 没渲出来的候选也就恒兑不动(反过来才是真扩权面)。保序取前 N:core 的 `exact` 形恒在 index 0。
+        const suggestions = rawSuggestions.length > MAX_RULE_SUGGESTIONS ? rawSuggestions.slice(0, MAX_RULE_SUGGESTIONS) : rawSuggestions;
         const args = req.args;
         if (args === null || typeof args !== "object" || Array.isArray(args))
             return undefined;
@@ -466,6 +507,21 @@ export class ToolApprovalCoordinator {
             ...(boundInputHash !== null ? { boundInputHash } : {}),
         };
     }
+    /** #241([3731]/[3730] 双属主裁定):把某 wire run 的**流内未决 ask** 立即转 durable park——断连支专用。
+     *  匹配键=`ctxTaskId`(wire run id)。该字段的顶注说它「不是清扫判据」——那是因为清扫要判**连接**的
+     *  生死(同 id 可被两个 ctx 实例复用);本臂语义不同:调用方就是该 wire run 的承载流,断连=这个 id 的
+     *  流没了,值相等即目标集;极端复用形下多转的那条也只是从流内卡变 durable 卡,方向保守。
+     *  返回触发条数(0 = 无流内未决 ask,调用方照旧 abort)。幂等:已结算条目跳过,重复调用无害。 */
+    parkOpenAsksForTask(wireTaskId) {
+        let n = 0;
+        for (const e of this.pending.values()) {
+            if (e.ctxTaskId === wireTaskId && e.settledOutcome === undefined) {
+                e.forceParkNow();
+                n++;
+            }
+        }
+        return n;
+    }
     /** 测试/可观测性钩子(X-2):某 (taskId) 维当前占用的准入名额数。 */
     admittedCount(taskId) {
         return this.admitByTask.get(taskId) ?? 0;
@@ -1033,6 +1089,28 @@ export class ToolApprovalCoordinator {
                         cardForFrame = rest;
                     }
                 }
+                // 🔴 **候选是「行 = 真源」F2 家族的第三位**(codex 对抗复审 R1-[medium],验真后修)。上面两条把
+                // `governanceForced` / `persistedRuleShadowed` 收进了这条纪律,候选却漏在外面:幂等命中一条既有行时
+                // 呈卡帧读的是**行上的卡**,而旧帧的 `ruleSuggestions` 与 `ruleLaneMaterial`(= 回决口
+                // `rule_not_offered` 那道等式的**左边**)仍来自**这一腿**的 `req`。两腿的候选可以真的不同(重试 /
+                // 并发 / 混版跑 / 规则店在两腿之间变了),于是同一个 `approvalId` 上会出现:呈卡帧展示 A、旧帧展示 B、
+                // 兑付口按 B 判 —— 人点了卡上看见的 A,拿回一句 `rule_not_offered`。
+                //
+                // 处置 = **不一致就整条撤回车道**,与上面那条治理撤回**逐字同形**(本文件既定的安全方向:少渲一格
+                // 是安全的,渲一格按不动的才是 wire 谎言)。不选「采信行的候选」:兑付还要 `command`/`boundInputHash`
+                // 等素材,而行上的卡不带它们,拼起来就是第三份来源;也不选「采信本地」:人看见的是行上那张卡。
+                // ⚠️ 残余如实记:这里撤的是**本次投递**的两族帧与素材,行本身不动 ⇒ 纯重放腿(`buildReplayFrame`)
+                // 仍会从行上投出候选。那条腿本来就没有自己的兑付通道(射程见 `ApprovalCardSchema.ruleSuggestions`
+                // 顶注:只有同副本 live `approvalId` 兑得动),所以不构成「按得动却兑不动」。
+                if (ruleLaneMaterial !== undefined && !ToolApprovalCoordinator.ruleSuggestionsEqual(cardForFrame.ruleSuggestions, ruleLaneMaterial.suggestions)) {
+                    this.noteStoreError(new Error("persisted approval row offers a different ruleSuggestions set than this leg — withdrawing the rule lane for this delivery"), "ensureAsk(rule-suggestions-drift)");
+                    ruleLaneMaterial = undefined;
+                    delete frame.ruleSuggestions;
+                    if (cardForFrame.ruleSuggestions !== undefined) {
+                        const { ruleSuggestions: _drifted, ...rest } = cardForFrame;
+                        cardForFrame = rest;
+                    }
+                }
             }
             catch (err) {
                 this.noteStoreError(err, "ensureAsk");
@@ -1271,6 +1349,18 @@ export class ToolApprovalCoordinator {
                 }
             })();
         };
+        // #241:断连强制转 park(接口注释见 PendingApproval.forceParkNow)。有店 ⇒ 走窗到期同路(expireAsk
+        // CAS+兄弟撤卡,赢=unavailable/输=向持久真源收敛——人已决就尊重人);无店 ⇒ 进程内直接改判 park 路由。
+        const forceParkNow = () => {
+            if (done)
+                return;
+            if (!this.askStore || askId === undefined || batchId === undefined) {
+                windowRouteUnavailable = true;
+                settle(false, "expired");
+                return;
+            }
+            windowExpired();
+        };
         // F2 修:定时器量的是**行上那个绝对 deadline** 的剩余时长(重入拿到既有行时,剩余时长比一整个窗短
         // —— 旧形会给一条早就该到期的行重新挂一个满窗的表)。store 缺席时逐字沿用 `effectiveWindowMs`(D1)。
         timer = setTimeout(windowExpired, this.askStore ? Math.max(0, persistedExpiresAtMs - Date.now()) : effectiveWindowMs);
@@ -1394,6 +1484,7 @@ export class ToolApprovalCoordinator {
         // 自己的 TTL/abortSignal 才作数;上面的 aliveCtxs abort 倒计时仍照常适用于它自己的连接级 abort)。
         const pendingEntry = {
             settle,
+            forceParkNow,
             owner: primary.owner,
             ctxTaskId: primary.taskId,
             originCtx: primary,
@@ -1664,14 +1755,28 @@ export class ToolApprovalCoordinator {
      *  时仍是纯同步函数(D1)。`askStore`/`askId`/`batchId` 由调用方在已窄化的分支里传入(避免非空断言）。 */
     async respondWithCas(askStore, askId, batchId, id, entry, parsed) {
         let decidedWon = false;
+        // 🔴 #229 + codex 对抗复审 round1 [high](验真后修):`noteRecorded` 的判据比 `decidedWon` **更严**,
+        // 所以是**两个**变量而不是一个。`decidedWon` 回答「这条决议是不是终局」(单赢者 CAS 的语义,足够支撑
+        // 200/404 的分派与 `notifyExternalDecision`);`noteLanded` 回答「**这一次请求**的那段文本在不在行上」。
+        // 两者在**提交歧义**臂上会分岔(见下方 catch 里的理由),而回执上那句「你的理由记上了」只能由后者答。
+        let noteLanded = false;
         try {
-            const decided = await this.withStoreDeadline(askStore.decideAsk(askId, batchId, { decision: parsed.value === "deny" ? "deny" : "approve" }), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
+            const decided = await this.withStoreDeadline(
+            // #229:`decisionNote` 是**店缝上既有**的键(`DecideAskInput.decisionNote`,SQL twin 与 memory twin
+            // 都已实装)⇒ 零新 SQL、零新列,live 腿与 durable 腿写同一条 UPDATE 的同一列。
+            askStore.decideAsk(askId, batchId, {
+                decision: parsed.value === "deny" ? "deny" : "approve",
+                ...(parsed.note !== undefined ? { decisionNote: parsed.note } : {}),
+            }), "decideAsk", DURABLE_CALL_TIMEOUT_MS, (late) => {
                 // R3-1 迟到成功:HTTP 响应早已发出(这次调用报的是超时),但**决议真落了盘** —— 同 askId 下
                 // 还在悬挂的本地条目必须按真决议结清,否则它们只能等自己的窗/取消再绕一圈。
                 if (late.ok)
                     this.notifyExternalDecision(askId, parsed.value !== "deny", parsed.updatedInput);
             });
             decidedWon = decided.ok;
+            // 干净赢下 CAS ⇒ note 与决议是**同一条 UPDATE** 写的,赢即落,不必再读一次。
+            if (decided.ok)
+                noteLanded = true;
             if (!decided.ok) {
                 // CAS 输——respond 绝不覆盖赢家(D2)。逐字复用现行 404 形(409/410 分化留给车4)。
                 return { status: 404, body: { error: "no pending tool approval for this id (settled, expired, or not on this replica)", errorCode: "tool_approval.not_pending" } };
@@ -1687,8 +1792,18 @@ export class ToolApprovalCoordinator {
             // 那本就该回放成功)。复核读本身失败/超时 ⇒ 维持「不知道」,守卫照旧 404(不许把未知说成成功)。
             try {
                 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"))
+                if (row?.state === "DECIDED" && row.decision === (parsed.value === "deny" ? "deny" : "approve")) {
                     decidedWon = true;
+                    // 🔴 codex 对抗复审 round1 [high](真 finding,红先复现):**note 的判据不能沿用决议的判据**。
+                    // 上一段那句「别人不可能写出同一条决议再让我们看见」对**决议**成立(单赢者 CAS),对 `note`
+                    // **不成立** —— 两路并发 respond 完全可以带**同决议、不同 note**:一路干净赢下 CAS(写进去的是
+                    // 它的 note),另一路撞上提交歧义,在这次确认读里看见那条 DECIDED 行。只比决议的话,输的那一路
+                    // 会把别人的胜利认成自己的,回一句「你的理由记上了」,而行上是**别人**的理由 —— 恰好是本布尔
+                    // 存在的意义被反过来用。所以这里逐字比**行上的 note**:相等才算落地(文本真的相同就不是谎,
+                    // 哪怕是别人写的);行上没有 note、或与本次提交不同 ⇒ 如实 `false`。
+                    // 决议侧的 `decidedWon` 保持原样(200/404 的分派与 `notifyExternalDecision` 的判据不动)。
+                    noteLanded = parsed.note === undefined || row.decisionNote === parsed.note;
+                }
             }
             catch (confirmErr) {
                 this.noteStoreError(confirmErr, "getAsk(decideAsk-confirm)");
@@ -1726,9 +1841,12 @@ export class ToolApprovalCoordinator {
             // session 记忆照记(grant 谈的是**将来**的 ask,与这次投递是否由我完成无关)。
             // 但 `updatedInput` **没有**随那次结算送达闭包(R2-4)⇒ 显式声明未投递,回显里不许出现
             // `updatedInputForwarded`。
-            return this.finishRespond(id, entry, parsed, { updatedInputDelivered: false });
+            // #229:`noteRecorded` 取的是**店的真实结果**(`noteLanded`,比 `decidedWon` 更严——见其声明处),
+            // 与 `updatedInputForwarded` 的判据刻意分家:那一格问「闭包收到编辑没有」(本支恒否),
+            // 这一格问「行上记下的是不是**这次**的理由」。两件事,不共用一个布尔。
+            return this.finishRespond(id, entry, parsed, { updatedInputDelivered: false, noteRecorded: noteLanded });
         }
-        const result = this.finishRespond(id, entry, parsed);
+        const result = this.finishRespond(id, entry, parsed, { noteRecorded: noteLanded });
         // round5(pendingByAskId 顶注):回决赢下 CAS 时同样要收尾「同 askId 重复本地注册」那一支——与
         // windowExpired/runCancel/emitAllP 三条竞争者的赢家路径同精神(那三处已经这么做)。此处 entry 已经
         // 经 `finishRespond` 自行 settle 并从 pendingByAskId 的 Set 里摘除自己,故这里天然只会清算真正
@@ -1768,6 +1886,21 @@ export class ToolApprovalCoordinator {
         // 命令行);此时还回 `updatedInputForwarded: true` 等于告诉壳「你的编辑生效了」,是最不该撒的那种谎。
         // 调用方在 stale-entry 分支传 `updatedInputDelivered: false`,回显里这个键就整个缺席(壳按未透传处理)。
         const updatedInputDelivered = opts?.updatedInputDelivered ?? true;
+        // #229(设计稿 233 稿B v2 §1):`noteRecorded` = 这次回决的**理由到底有没有落进持久行**。
+        //
+        // 🔴 形照 `rulePersisted`(always-emit 布尔,只在请求真带了 `note` 时在场),值照**店的真实结果**
+        // (调用方传进来的 `decidedWon`,含 CAS 抛错后那次确认读的改判),不是「askStore 在不在」:
+        //  · 本方法被 `respond()` **直接**调到 = store 缺席,或 store 在场但 `ensureAsk` 失败已清掉坐标 ——
+        //    两种都是「压根没打过那条 UPDATE」,缺省 `false` 正是这一支的真相;
+        //  · `respondWithCas` 的 D5 fail-open 支(店抖动、确认读也没读到赢)同样 `false` —— **不知道不许
+        //    说成成功**(与 `updatedInputForwarded` 从不发 `false`、只在真投递时发 `true` 是同一条纪律的两面:
+        //    那一格靠缺席表达否定,这一格是三态里的一态,必须显式说 `false`,否则壳分不出「这台不支持」);
+        //  · 提交歧义臂上**赢了决议但行上是别人的 note**(同决议不同 note 的并发)同样 `false` —— 判据是
+        //    「行上那段文本是不是这次提交的」,不是「这条决议是不是终局」(codex round1 [high],见调用方
+        //    `respondWithCas` 里 `noteLanded` 的推导)。
+        // 能力位 `capabilities.approvalDecisionNote` 与本格**必须同车**:老服务对未知键静默丢 + 200,少了
+        // 能力位,「记上了」与「这台不认识 note」在 wire 上不可判别。
+        const noteRecorded = opts?.noteRecorded ?? false;
         return {
             status: 200,
             body: {
@@ -1776,6 +1909,7 @@ export class ToolApprovalCoordinator {
                 decision: parsed.value,
                 ...(rememberApplied !== undefined ? { rememberApplied } : {}),
                 ...(parsed.updatedInput !== undefined && allowed && updatedInputDelivered ? { updatedInputForwarded: true } : {}),
+                ...(parsed.note !== undefined ? { noteRecorded } : {}),
             },
         };
     }

package/dist/trace/project.js

@@ -886,7 +886,15 @@ function mapTraceEventInner(type, seq, data) {
             return { event: "prompt-assembled", data: { seq, ...data } };
         case "done":
             return { event: "done", data: { seq } };
+        // 🔴 park 的账本事件名有**两个**(扫描P2,status/kind 同名词混淆病族):`suspended` 与
+        // `needs_review` —— 写点是 `trace/ledger-sink.ts` 的 `appendParked(kind)`(kind 逐字取自
+        // `result.status`)、`runs.ts` 的 bg 腿、`http/server.ts` 的两条 resume 腿;`needs_review` 就是
+        // plan_review / dry_run 两种 gate 的 park 落名。只映射前者 ⇒ 一条 plan_review park 在 trace 流上
+        // 落进 `default → null`,**一帧都不发**,消费端只看到流无声中止(既不是 done 也不是 error)。
+        // 契约 2.3 的 park 标记只有 `suspended: true` 这一个位 ⇒ 两个词共用同一张帧(gate 细分在
+        // `GET /v1/runs/:id`,不在这条流上)。
         case "suspended":
+        case "needs_review":
             return { event: "done", data: { seq, suspended: true } };
         case "failed":
             // BL-13: redact at the read boundary too (defense-in-depth) — covers any errorMessage that reached the

package/dist/trace/redact.d.ts

@@ -1,5 +1,18 @@
 export declare function setRedactionObserver(fn: ((patternLabel: string, count: number) => void) | undefined): void;
-export declare function redactSecrets(text: string): string;
+/**
+ * `opts.observe: false` = **照常脱敏,但这一遍不计数**(合并码重扫)。
+ *
+ * 为什么需要它:本函数对自己的输出**值幂等、计数不幂等** —— URL-userinfo 与 JSON 秘密字段两条 pattern
+ * 会命中自己已经替换过的输出并再计一次。于是任何**重扫已脱敏文本**的读路径(耐久待批队列的回读腿,
+ * `/v1/approvals/stream` 每 3s 一拍)都会持续给 `redactions_applied_total` 加数,把那个用来识别
+ * 「过度脱敏 / pattern 从不触发」的指标灌成不可读。
+ *
+ * 🔴 关的是**计数**,不是脱敏:重扫这一遍仍是纵深防御(手改过的行、未来某条写路径漏了脱敏,读面照样
+ * 兜住)—— 少脱一次的代价是把凭证投上跨租户可见的运维队列,那条永远不能省。
+ */
+export declare function redactSecrets(text: string, opts?: {
+    observe?: boolean;
+}): string;
 /**
  * 🔴 环 + 深度预算(2026-07-25 补)。原实现是纯递归、**既不记已访问节点也不限深度**,而它的调用位置是
  * **最不可信的边界**:`toolStart`/`toolEnd` 把工具的 `args`/`output`/`structured` 直接喂进来。后果两条:

package/dist/trace/redact.js

@@ -33,11 +33,23 @@ export function setRedactionObserver(fn) {
     onRedaction = fn;
 }
 const PATTERN_LABELS = SECRET_PATTERNS.map(([, repl]) => repl.replace(/[«»]/g, "").replace(/^redacted:/, ""));
-export function redactSecrets(text) {
+/**
+ * `opts.observe: false` = **照常脱敏,但这一遍不计数**(合并码重扫)。
+ *
+ * 为什么需要它:本函数对自己的输出**值幂等、计数不幂等** —— URL-userinfo 与 JSON 秘密字段两条 pattern
+ * 会命中自己已经替换过的输出并再计一次。于是任何**重扫已脱敏文本**的读路径(耐久待批队列的回读腿,
+ * `/v1/approvals/stream` 每 3s 一拍)都会持续给 `redactions_applied_total` 加数,把那个用来识别
+ * 「过度脱敏 / pattern 从不触发」的指标灌成不可读。
+ *
+ * 🔴 关的是**计数**,不是脱敏:重扫这一遍仍是纵深防御(手改过的行、未来某条写路径漏了脱敏,读面照样
+ * 兜住)—— 少脱一次的代价是把凭证投上跨租户可见的运维队列,那条永远不能省。
+ */
+export function redactSecrets(text, opts) {
+    const observe = opts?.observe ?? true;
     let out = text;
     for (let i = 0; i < SECRET_PATTERNS.length; i++) {
         const [re, repl] = SECRET_PATTERNS[i];
-        if (!onRedaction) {
+        if (!onRedaction || !observe) {
             out = out.replace(re, repl);
             continue;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.14.0",
+  "version": "7.16.0-rc.1",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.27.0",
+    "@sema-agent/core": "^5.28.0",
     "@sema-agent/registry-core": "^0.16.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
@@ -69,7 +69,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "^6.15.0",
+    "@sema-agent/sdk": "^6.17.2",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",