@sema-agent/server 7.141.0 → 7.143.0

package/dist/task-settings.d.ts

@@ -15,7 +15,9 @@
  *  - `deny` / `ask` are folded via `tightenTaskSpec` (deny-wins `combinePolicies`); it THROWS on any override that would
  *    LOOSEN a stricter base safety field. Through those two buckets the client can only ADD denies / asks on top of the
  *    deployment + operator baseline.
- *  - `allow` (server 7.117.0, core 7.42.0) is NOT a policy: the list rides WHOLE and verbatim into `TaskSpec.allowedTools`,
+ *  - `allow` (server 7.117.0, core 7.42.0) is NOT a policy: the list rides WHOLE, one member per entry in the entry's position, into `TaskSpec.allowedTools`
+ *    (a string verbatim; a settings layer's `{ rule, layer }` entry as its rule text, or — when its `/` reads at the configuration root — as
+ *    `{ rule, pathBases: { root } }`, the same anchor its deny / ask twin's set declares: {@link allowMemberOf}),
  *    the request member of the engine's ONE allow layer (beside a deployment's `RunnerDeps.allowedTools`, a person's stored
  *    rows, an active skill's `allowed-tools` and a PreToolUse hook's `allow`), read under one predicate. It IS an accepted
  *    loosening for this run: an entry clears the `unstated` / `ordinary` questions the engine raises for the calls it covers
@@ -52,6 +54,7 @@ import { type EntryProblem } from "./entry-problems.js";
 import { type RuleListEntry } from "./permission-rule-list.js";
 import { type KeyClosureIssue } from "./request-key-closure.js";
 import { type RunnableHooksConfig } from "./hooks/hook-runner.js";
+import { type HttpHookAllowlistLayer } from "@sema-agent/settings-schema";
 import type { StoredHooksRereadM20 } from "./stored-request-hooks-m20.js";
 import type { EntryPermissionMode } from "./runtime-governance.js";
 import { type TightenOnlySeatValues } from "./tighten-only-seats.js";
@@ -197,7 +200,8 @@ export declare function skillListingMaxDescOk(v: unknown): v is number;
  *  deferred (submit 路径另有 400 fail-loud),valid `hooks` 进 applied shape(hook-runner 阶段一)。 */
 export interface ParsedTaskSettings {
     permissions?: {
-        allow?: string[];
+        /** 与 `deny` 同一条目形(带层条目的层只选 `/` 的锚);投 `TaskSpec.allowedTools` 的唯一写点 {@link applyTaskSettings}。 */
+        allow?: RuleListEntry[];
         /** 纯串 = 请求自己写的规则;`{ rule, layer }` = 端从某个设置层读来的规则(`permission-rule-list.ts` 的 {@link RuleListEntry};层只选 `/` 的锚)。 */
         deny?: RuleListEntry[];
         /** 同 `deny` 的条目形;编译与 `deny` 同一口({@link deriveSettingsPolicy})。 */
@@ -242,6 +246,9 @@ export interface ParsedTaskSettings {
      *  wire 位置由座位表说(三座在 `settings` 顶层,`neverAuto` 在 `settings.permissions`),解析后与位置无关。空数组 ≡ 缺席(不铸键)。
      *  去处:三座经 {@link applyTaskSettings} 落 core 任务层席;`neverAuto` 经 {@link deriveSettingsPolicy} 落请求叶策略。 */
     tightenOnly?: TightenOnlySeatValues;
+    /** http hook 两张名单(`settings.allowedHttpHookUrls` / `settings.httpHookAllowedEnvVars`)作为**一个设置层**:源名 {@link REQUEST_SETTINGS_SOURCE} + 两键里在场的那几把,值原样(本服务不读内容)。
+     *  两键都缺席 ⇒ 不铸键。唯一读者 = `hooks/hook-runner.ts` 的 http 腿(经 hooks 注册上下文的 `httpHookAllowlistLayers`)。 */
+    httpHookAllowlist?: HttpHookAllowlistLayer;
 }
 /** The result of parsing an untrusted `body.settings`: the applied subset + the names of present-but-deferred
  *  fields (so the caller can log/advertise them — no silent drop). `null` settings ⇒ `{ settings: undefined }`. */
@@ -293,8 +300,8 @@ export interface SettingsPermissionBucketIssue {
 /**
  * 三桶的**唯一**判据(纯函数)。`perms` 不是对象 ⇒ 不判(那一形归「settings.permissions must be an object」那道门);桶缺席 / `null`
  * ⇒ 不判(与 `permissions: null` 的「容器缺席」同一约定)。逐桶按 {@link SETTINGS_PERMISSION_BUCKETS} 的序、按该桶的条目规则:不是数组 ⇒ `bad_entry`
- * (无 `index`);`rule_policy` 桶超帽 ⇒ `over_cap`(先判,拒体有界)、首个不合条目律的项(不是非空串、也不是合形的带层条目)⇒ `bad_entry` + 它的下标;`allow_layer` 桶首个非串项 ⇒
- * `bad_entry` + 它的下标(整表判据 = `ruleEntryListShapeOk`),超帽同样 `over_cap`(帽的理由不同,见段头)。全合法 ⇒ `null`。
+ * (无 `index`);`rule_policy` 桶超帽 ⇒ `over_cap`(先判,拒体有界)、首个不合条目律的项(不是非空串、也不是合形的带层条目)⇒ `bad_entry` + 它的下标;`allow_layer` 桶首个既不是串、
+ * 也不是合形带层条目的项 ⇒ `bad_entry` + 它的下标,超帽同样 `over_cap`(帽的理由不同,见段头)。全合法 ⇒ `null`。
  */
 export declare function settingsPermissionBucketIssue(perms: unknown): SettingsPermissionBucketIssue | null;
 /** 本 service 真正**消费**的 `settings` 顶层键 —— 闭集。每一个都有消费点:
@@ -313,8 +320,12 @@ export declare function settingsPermissionBucketIssue(perms: unknown): SettingsP
  *  🔴 两个 `skillListing*`([ref],7.77.0)= **CC settings 同名键**,值域抄 CC 的 schema 声明
  *  (`skillListingBudgetFraction` 是 `gt(0).lte(1)`、`skillListingMaxDescChars` 是 `int().positive()`);
  *  消费点 = 本文件的 parse + `boot/resolve-spec.ts` 的 `TaskSpec` 透传。语义(预算怎么花、描述怎么裁、
- *  溢出怎么退成 name-only)整个归引擎,本仓一个字节都不渲染,也**不复刻默认值**——缺席即整键不写。 */
-export declare const TASK_SETTINGS_KEYS: readonly ["approvalFrameFamilies", "complianceAdditionalDenies", "env", "hooks", "model", "outputStyle", "permissions", "readDenyPatterns", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch", "writeProtectedExtra"];
+ *  溢出怎么退成 name-only)整个归引擎,本仓一个字节都不渲染,也**不复刻默认值**——缺席即整键不写。
+ *
+ *  🔴 `allowedHttpHookUrls` / `httpHookAllowedEnvVars` = **CC settings 同名键**(契约包的 http hook 两张名单,键表属主 = 契约包 `HTTP_HOOK_ALLOWLIST_KEYS`):
+ *  消费点 = {@link parseTaskSettings} 把它们原样收成一层({@link requestHttpHookAllowlistLayer})→ `boot/resolve-spec.ts` 交给 hooks 注册 → `hooks/hook-runner.ts` 的 http 腿
+ *  在拨出之前问契约包判官。受理面只判键名(本门),不判值:名单的读法只有判官那一只(坏形由判官答 `malformed`、拦)。 */
+export declare const TASK_SETTINGS_KEYS: readonly ["allowedHttpHookUrls", "approvalFrameFamilies", "complianceAdditionalDenies", "env", "hooks", "httpHookAllowedEnvVars", "model", "outputStyle", "permissions", "readDenyPatterns", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch", "writeProtectedExtra"];
 /** 本 service 消费的 `settings.permissions` 子键 —— 闭集(值形校验另有既有门,本门只判键名)。 */
 export declare const TASK_SETTINGS_PERMISSION_KEYS: readonly ["allow", "ask", "defaultMode", "deny", "disableAutoMode", "neverAuto"];
 /** CC/SDK 合约里合法、本 service **不接线**的顶层键。词表外的 CC 键落 `unknown` —— 两列都是 400,标签只影响
@@ -451,7 +462,7 @@ export interface FsWriteGateWiring {
     taskHome?: string;
     /**
      * **执行环境的配置根**(唯一属主 `execution-config-root.ts` 的 `executionConfigRootOf`):user 设置层里 `/` 形路径规则的根 —— 带 `layer: "userSettings"`
-     * 且要 `root` 的条目编进只声明 `{ root: configRoot }` 的那一集(`permission-rule-list.ts` 的 `ruleRootOf`)。缺席(沙箱车道既没转 `SEMA_CONFIG_DIR`、home 也读不出)
+     * 且要 `root` 的条目编进只声明 `{ root: configRoot }` 的那一集、allow 桶里的投成带同一声明的那一员(`permission-rule-list.ts` 的 `ruleRootOf`)。缺席(沙箱车道既没转 `SEMA_CONFIG_DIR`、home 也读不出)
      * ⇒ 这样的条目由 {@link rejectUnmatchableSettingsNames} 响亮拒(422 `home_unresolvable`),不猜目录。拒点与存体预判读同一只函数。
      */
     configRoot?: string;
@@ -478,7 +489,7 @@ export type RulePolicyBucket = (typeof RULE_POLICY_BUCKETS)[number];
 /**
  * deny / ask 两桶的**完整规则判**,唯一一只(拒点 {@link rejectUnmatchableSettingsNames} 与存体预判 `http/stored-body-replay.ts` 同调):
  *  ② 按 {@link RULE_POLICY_BUCKETS} 的序逐桶、桶内按 `RULE_ROOTS` 的序逐集(`permission-rule-list.ts` 的 `ruleSetsOf`:判的就是要编的那一集)问 `judgeUnmatchableToolNames`(名字层 + core 规则文法);
- *  ③ 再判「这条规则要的基本部署给不出」那一拒:`~/` 形缺 home;配置根那一集缺配置根(两者都落在执行环境的 home 上,同词 `home_unresolvable`)。答 `{ bucket, message, problems }`:`bucket` 与 `message` 是**第一处**坏处的
+ *  ③ 再判「这条规则要的基本部署给不出」那一拒:`~/` 形缺 home(deny / ask);配置根那一集缺配置根(三桶,{@link LAYER_ROOT_BUCKETS};两者都落在执行环境的 home 上,同词 `home_unresolvable`)。答 `{ bucket, message, problems }`:`bucket` 与 `message` 是**第一处**坏处的
  *  (句子冻结,先撞上的那一条),`problems` 是**两段、两只桶判下来的全部**坏条目(机读位的原料,形的属主 `entry-problems.ts`;`entry` = 规则原文,带层条目也一样)。
  * 入参:桶、{@link RulePolicyBases}。**home 同源**:拒点的 home 是 `resolve-spec.ts` 的 `laneHomeBase()` 经 `executionLaneHomeDir(config)` 算出的,预判传同一个函数对同一份部署配置算出的;配置根同理(`executionConfigRootOf`)。
  * **任务根那一集声明给文法的基**只有拒点有(根 + home 的并集,执行车道才知道根):core 的规则文法对**没声明**的基不下判词(见 `config.ts` `uncompilableRuleGuidance`),所以预判什么也不声明、两腿逐字同句;
@@ -494,8 +505,8 @@ export interface RulePolicyBases {
     /** 执行环境的配置根(配置根那一集的根;拒点与预判都给);读不出 ⇒ 缺席。 */
     readonly configRoot?: string;
 }
-export declare function rulePolicyBucketsRefusal(permissions: Readonly<Partial<Record<RulePolicyBucket, readonly RuleListEntry[]>>>, bases: RulePolicyBases): {
-    readonly bucket: RulePolicyBucket;
+export declare function rulePolicyBucketsRefusal(permissions: Readonly<Partial<Record<SettingsPermissionBucket, readonly RuleListEntry[]>>>, bases: RulePolicyBases): {
+    readonly bucket: SettingsPermissionBucket;
     readonly message: string;
     readonly problems: readonly EntryProblem[];
 } | undefined;

package/dist/task-settings.js

@@ -2,13 +2,13 @@ import { combinePolicies, parseRuleText, resolveReasoningProfile, rankOf, isThin
 import { judgeUnmatchableToolNames } from "./config.js";
 import { NAME_TABLE_BEHAVIOR } from "./namespaced-rule-name.js";
 import { entryProblem } from "./entry-problems.js";
-import { MAX_PERMISSION_RULES_PER_LIST, RULE_ROOTS, createRuleListPolicy, ruleListEntryOk, ruleSetsOf, ruleSourceOf, ruleTextOf } from "./permission-rule-list.js";
-import { allowLayerEntryCountIssue, describeAllowLayerOverCap, ruleEntryListShapeOk } from "./rule-entry-list.js";
+import { MAX_PERMISSION_RULES_PER_LIST, RULE_ROOTS, allowListEntryOk, createRuleListPolicy, ruleListEntryOk, ruleRootOf, ruleSetsOf, ruleSourceOf, ruleTextOf } from "./permission-rule-list.js";
+import { allowLayerEntryCountIssue, describeAllowLayerOverCap } from "./rule-entry-list.js";
 import { limitRefusal } from "./limit-refusal.js";
 import { tightenGoverned } from "./governance-overrides.js";
 import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
 import { hooksCoordinate, parseHooksConfig } from "./hooks/hook-runner.js";
-import { SETTINGS_SOURCES } from "@sema-agent/settings-schema";
+import { HTTP_HOOK_ALLOWLIST_KEYS, SETTINGS_SOURCES } from "@sema-agent/settings-schema";
 import { heldRuleName } from "./tool-rule-names.js";
 import { policyAskStandingAnswerFacts, standingAnswerDurablyRecordable } from "./tool-approval.js";
 import { createRequestNeverAutoPolicy } from "./approval.js";
@@ -113,8 +113,8 @@ function bucketIssueMessage(f, rule) {
                         : `${f.field}[${f.index}] is neither a non-empty rule string nor a { "rule", "layer" } entry (exactly those two keys; rule = a non-empty rule string; layer = one of ${SETTINGS_SOURCES.join(", ")}) — every entry must be one. Refused rather than dropped, because a dropped entry reads as "in effect" to the caller`;
                 case "allow_layer":
                     return f.index === undefined
-                        ? `${f.field} must be an array of permission-rule strings — refused rather than ignored, because an ignored list reads as "in effect" to the caller`
-                        : `${f.field}[${f.index}] is not a string — every entry must be a permission-rule string (a settings layer's { "rule", "layer" } entry is read in deny / ask only). Refused rather than dropped, because a dropped entry reads as "in effect" to the caller`;
+                        ? `${f.field} must be an array of rule entries (a rule string, or { "rule": <rule>, "layer": <settings source> }) — refused rather than ignored, because an ignored list reads as "in effect" to the caller`
+                        : `${f.field}[${f.index}] is neither a rule string nor a { "rule", "layer" } entry (exactly those two keys; rule = a non-empty rule string; layer = one of ${SETTINGS_SOURCES.join(", ")}) — every entry must be one. Refused rather than dropped, because a dropped entry reads as "in effect" to the caller`;
             }
     }
 }
@@ -146,8 +146,11 @@ export function settingsPermissionBucketIssue(perms) {
                     const over = allowLayerEntryCountIssue(field, v);
                     if (over !== undefined)
                         fields = { field, reason: "over_cap", count: over.facts.count, cap: over.facts.cap };
-                    else if (!ruleEntryListShapeOk(v))
-                        fields = { field, reason: "bad_entry", index: v.findIndex((x) => typeof x !== "string") };
+                    else {
+                        const index = v.findIndex((x) => !allowListEntryOk(x));
+                        if (index >= 0)
+                            fields = { field, reason: "bad_entry", index };
+                    }
                     break;
                 }
             }
@@ -160,7 +163,7 @@ export function settingsPermissionBucketIssue(perms) {
 function acceptedRuleList(v) {
     return Array.isArray(v) && v.length > 0 ? v.slice() : undefined;
 }
-export const TASK_SETTINGS_KEYS = ["approvalFrameFamilies", "complianceAdditionalDenies", "env", "hooks", "model", "outputStyle", "permissions", "readDenyPatterns", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch", "writeProtectedExtra"];
+export const TASK_SETTINGS_KEYS = ["allowedHttpHookUrls", "approvalFrameFamilies", "complianceAdditionalDenies", "env", "hooks", "httpHookAllowedEnvVars", "model", "outputStyle", "permissions", "readDenyPatterns", "skillListingBudgetFraction", "skillListingMaxDescChars", "ultracode", "webSearch", "writeProtectedExtra"];
 export const TASK_SETTINGS_PERMISSION_KEYS = ["allow", "ask", "defaultMode", "deny", "disableAutoMode", "neverAuto"];
 export const TASK_SETTINGS_UNSUPPORTED_KEYS = ["apiKeyHelper", "crossSessionInbound", "dialogExpiry", "sandbox", "statusLine"];
 export const TASK_SETTINGS_UNSUPPORTED_PERMISSION_KEYS = ["additionalDirectories", "disableBypassPermissionsMode"];
@@ -228,6 +231,16 @@ export function hooksKeyIssue(raw, config) {
 export function taskHooksHonored(config) {
     return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
+const REQUEST_SETTINGS_SOURCE = "flagSettings";
+function requestHttpHookAllowlistLayer(s) {
+    const present = HTTP_HOOK_ALLOWLIST_KEYS.filter((key) => Object.hasOwn(s, key));
+    if (present.length === 0)
+        return undefined;
+    const layer = { source: REQUEST_SETTINGS_SOURCE };
+    for (const key of present)
+        layer[key] = s[key];
+    return layer;
+}
 function tightenOnlySeatDeferredName(name) {
     return tightenOnlySeatField(name).replace(/^settings\./, "");
 }
@@ -303,6 +316,9 @@ export function parseTaskSettings(raw, seats = {}) {
         deferred.push(tightenOnlySeatDeferredName(name));
     if (Object.keys(tightenSeats.values).length > 0)
         out.tightenOnly = tightenSeats.values;
+    const httpHookAllowlist = requestHttpHookAllowlistLayer(s);
+    if (httpHookAllowlist !== undefined)
+        out.httpHookAllowlist = httpHookAllowlist;
     return { settings: Object.keys(out).length > 0 ? out : undefined, deferred, ...(hooksReread !== undefined ? { hooksReread } : {}) };
 }
 export function acceptAppendSystemPrompt(v, warn) {
@@ -359,6 +375,7 @@ export class SettingsRuleRefusalError extends Error {
 }
 export const SETTINGS_RULE_REFUSAL_CODE = "request.unprocessable";
 export const RULE_POLICY_BUCKETS = ["ask", "deny"];
+const LAYER_ROOT_BUCKETS = [...RULE_POLICY_BUCKETS, "allow"];
 export function rulePolicyBucketsRefusal(permissions, bases) {
     let first;
     const problems = [];
@@ -410,7 +427,7 @@ export function rulePolicyBucketsRefusal(permissions, bases) {
         }
     }
     if (bases.configRoot === undefined) {
-        for (const bucket of RULE_POLICY_BUCKETS) {
+        for (const bucket of LAYER_ROOT_BUCKETS) {
             const field = `permissions.${bucket}`;
             for (const name of ruleSetsOf(permissions[bucket] ?? [], bucket).configuration.map(ruleTextOf)) {
                 first ??= {
@@ -430,9 +447,25 @@ function ruleSetBases(root, taskBases, configRoot) {
         case "task":
             return taskBases;
         case "configuration":
-            if (configRoot === undefined)
-                throw new Error("a user-settings path rule reached the compiler without a configuration root — the admission judgement refuses it first (home_unresolvable); refusing rather than anchoring it at the task root");
-            return { root: configRoot };
+            return configurationSetBases(configRoot);
+        default: {
+            const unhandled = root;
+            return unhandled;
+        }
+    }
+}
+function configurationSetBases(configRoot) {
+    if (configRoot === undefined)
+        throw new Error("a user-settings path rule reached the compiler without a configuration root — the admission judgement refuses it first (home_unresolvable); refusing rather than anchoring it at the task root");
+    return { root: configRoot };
+}
+function allowMemberOf(entry, configRoot) {
+    const root = ruleRootOf(entry, "allow");
+    switch (root) {
+        case "task":
+            return ruleTextOf(entry);
+        case "configuration":
+            return { rule: ruleTextOf(entry), pathBases: configurationSetBases(configRoot) };
         default: {
             const unhandled = root;
             return unhandled;
@@ -490,7 +523,7 @@ export function applyTaskSettings(base, settings, bases) {
         next = tightenGoverned(next, { ...(toolPolicy !== undefined ? { toolPolicy } : {}), ...seatSpec });
     const allow = settings.permissions?.allow;
     if (allow !== undefined)
-        next = { ...next, allowedTools: allow };
+        next = { ...next, allowedTools: allow.map((entry) => allowMemberOf(entry, bases?.configRoot)) };
     if (settings.outputStyle) {
         const appended = next.appendSystemPrompt ? `${next.appendSystemPrompt}\n\n${settings.outputStyle}` : settings.outputStyle;
         next = { ...next, appendSystemPrompt: appended };

package/dist/terminal.d.ts

@@ -1,5 +1,6 @@
 /**
- * 终局因由(`TaskResult.terminal`)的 server 侧**读**面 —— 一个叶子模块,只依赖 `@sema-agent/core`。
+ * 终局因由(`TaskResult.terminal`)的 server 侧**读**面 —— 一个叶子模块:依赖 `@sema-agent/core`、进程级记录器(`observability/fail-open.ts`)
+ * 与秘密脱敏器(`trace/redact.ts`,只作码判官 {@link isCodeToken} 的一条合取);本仓的结果汇点 / 出口座反过来依赖本模块,本模块不依赖它们。
  *
  * core 7.6.0([ref] S6 D-8,BREAKING)把 `TaskResult` 上并列的八个平面键
  * (`status` / `errorCode` / `errorMessage` / `blockedReason` / `checkpointToken` / `checkpointId` /
@@ -57,18 +58,30 @@ export declare const STORE_ERROR_CODE = "internal.store_error";
  *
  * ⚠️ **辖域如实**:本臂触发条件是「码出了本仓的词法」,所以任何依赖铸出的域外码都落这里,不只 SQL 驱动。
  * 今天可观察的产出方**只有**耐久店那一层(引擎自己的传输/brain 错误在 core 侧已被分类成小写码),故码名
- * 取 `internal.store_error`;原码逐字进 message 尾注(随结果过汇点脱敏)、是码 token 时进运维 warn 行({@link isCodeToken}),归因从不丢失。
+ * 取 `internal.store_error`;原码逐字进 message 尾注(随结果过汇点脱敏)、是码时进运维线索({@link isCodeToken}),归因从不丢失。
  */
 export declare function outwardFailureCode(code: string): string;
 /**
- * 一个错误的 `code` 只在它**是**码(短 token)时才说出口 —— 码形座里装着文字的,不是码(驱动码 `ER_*` / SQLSTATE / `ECONNRESET`
- * 全在这一形里;带空白、`=`、换行或超过 64 字符的就是一句话)。读者两只,同一条判据:折码的运维 warn 行(本文件 {@link sealResultForExit})
- * 与执行车道占位读的故障词(`boot/execution-env.ts`)。
+ * 一个错误的 `code` 只在它**是**码时才说出口 —— 一只判官,两条合取:
+ *  ① **形**:短 token。驱动码 `ER_*` / SQLSTATE / `ECONNRESET` 全在这一形里;带空白、`=`、换行或超过 64 字符的就是一句话,不是码;
+ *  ② **不是凭据形**:秘密脱敏器({@link redactSecrets})原样放过它。`sk-…` / `AKIA…` / `ghp_…` 这类秘密过得了 ①,而 wire 上同一只脱敏器
+ *     会把它从 message 尾注里遮掉 —— 日志行若照印,就是 wire 遮、日志露;所以「长得像码的秘密」在这里判「不是码」,日志与 wire 同读。
+ *     先判 ①:脱敏器只读 ≤ 64 个 token 字符(扫描代价有界);只问不出门(`observe: false`,与影子重扫同口 —— 不计「已脱」读数)。
+ * 读者两只,同一条判据:折码的运维线索(本文件 {@link sealResultForExit} / {@link sealStoredResult})与执行车道占位读的故障词(`boot/execution-env.ts`)。
  */
 export declare function isCodeToken(code: unknown): code is string;
+/**
+ * 一个错误**说得出口**的机器码,以日志字段 / 指标标签的形交回:`err.code` 是串且 {@link isCodeToken} 判它是码 ⇒ `{ code }`(逐字);其余(没有 / 不是串 / 空串 / 非 `Error` 抛出物 / 读取时抛 / 不是码)⇒ `{}`
+ * —— 键缺席,不补 `null` / `none` 之类的占位。「读口 + 判官 + 字段形」的**唯一**组合:引擎交来的错上的 `code` 是别人写的串,凡把它写进运维日志行或指标标签的汇点
+ * (`onError` 汇点的七条行与 `runner_config_advisory_total` 的标签、记忆引擎事故席)都经这一只,不各写一份读法、也不各设一份形判。读口 {@link errorCodeOf} 不抛。
+ * 显式标注返回类型:推断型 `{ code?: undefined } | { code: string }` 进不了指标标签 `Record<string, string>`。
+ */
+export declare function codeFieldOf(err: unknown): {
+    readonly code?: string;
+};
 /**
  * 存量结果被**再观看**的读座(闭集):`GET /v1/runs/:id → result`(终态行与停驻行同一座)与账本 `done` 行的回放(三条耐久读腿共用)。
- * 封口在读座上折码时,运维行按 (读座, 原码) 只报一次 —— 见 {@link sealResultForExit}。
+ * 读入口 {@link sealStoredResult} 必须点名其一(类型级必填);`exit` 不在这里 —— 它只由写入口 {@link sealResultForExit} 给。
  */
 export type StoredResultReadSeat = "run.result" | "ev.done.result";
 /**
@@ -111,7 +124,7 @@ export declare function mapPauseSeats<T>(result: T, f: (seat: SeatObject, keys:
 /**
  * **一条结果离开引擎、进入本仓(可重放账本 / run 行 / wire)的唯一封口** —— 两件事,一个出口:
  *  ①摘掉**耐久恢复能力凭据**(`CheckpointToken`)—— 座表 {@link PAUSE_SEATS} 上的每一座;②把**域外的失败码**折成本仓的
- *  `internal.store_error`({@link outwardFailureCode},[ref])。
+ *  `internal.store_error`({@link outwardFailureCode},[ref])—— 码座两只:因由的 `terminal.code` 与 cascade 每一级的 `attempts[].errorCode`(同一类码,见 {@link foldOutwardFailureCodes})。
  *
  * 🔴 为什么两件事合在一只函数里而不是并列两只(7.92.2 改名 `stripResumeToken` → `sealResultForExit`):
  * 它们是**同一个出口上的同一件事** —— 「这条结果可以见人了吗」。并列两只 = 六个结算点各自要记得调两次,
@@ -129,23 +142,30 @@ export declare function mapPauseSeats<T>(result: T, f: (seat: SeatObject, keys:
  * `/v1/approvals` 决策端点,凭 `checkpointId` 对账,从来不是拿 token 直连引擎。
  *
  * **出口全集都经这一口**:三家 run 店的行写口与账本店的 `done` 行写口在店入口调它(`observability/run-terminal.ts`),
- * 同步 200 体 / 流 done 帧 / 续跑决定腿在铸体处调它,`GET /v1/runs/:id{,/events}` 等读面在回放前再调一次 ——
- * 升级前落盘、还带着凭据的存量行在读面上同样摘掉。两件事都**幂等**,重复过口是同形。
- *
- * ── 折码的运维线索:一行定形句,两个观看点同一句 ──
- * `[terminal] outward_failure_code_folded original=<码 | <not-a-code>> outward=<对外词> messageBytes=<n> at=<exit | 读座>`。
- * 字段只有闭集词、数字与码 token({@link isCodeToken}):失败句只报字节数,**永不**报原文 —— 失败句是自由文本(驱动句里可以有连接串 / 口令),
- * 结果里的那份由结果汇点脱敏,日志行没有汇点,所以日志行压根不带它;码形座里装着文字的同理只报 `<not-a-code>`。`at` 说这是哪一次观看:
- *  · 省略 `readSeat` = 结果**第一次**离开引擎(店的写口 / 出口铸体)⇒ 每折一次报一次 —— 每次都是一件新的失败;
- *  · 给出读座({@link StoredResultReadSeat})= 存量行的**再观看** ⇒ 同一读座同一原码(按它在行上的样子)只报一次,表有界(先进先出)——
- *    读面每次轮询 / 每个观看者 / 每次重连都重放同一批行,逐读逐报会把一次旧失败放大成读次那么多行,而它们说的是同一件事。
- *    折**本身**照旧逐读做(wire 上永远是对外词),去重的只是日志行。
+ * 同步 200 体 / 流 done 帧 / 续跑决定腿在铸体处调它;`GET /v1/runs/:id{,/events}` 等读面在回放前过同一套封口的**读入口**
+ * {@link sealStoredResult} —— 升级前落盘、还带着凭据的存量行在读面上同样摘掉。两件事都**幂等**,重复过口是同形。
+ *
+ * ── 折码的运维线索:一句定形字段,两只入口各说一只词 ──
+ * 字段 `original=<码 | <not-a-code>> outward=<对外词> messageBytes=<n> at=<观看点>`,只有闭集词、数字与码({@link isCodeToken}):
+ * 失败句只报字节数,**永不**报原文 —— 失败句是自由文本(驱动句里可以有连接串 / 口令),结果里的那份由结果汇点脱敏,运维线索没有汇点,
+ * 所以压根不带它;码形座里装着文字的、长得像码的秘密同理只报 `<not-a-code>`。`at` 说这是哪一次观看,**一个入口一只词**(类型给定,不靠记得传):
+ *  · 本函数 = 结果**第一次**离开引擎(店的写口 / 出口铸体)⇒ `at=exit`,每折一次一行 `[terminal] outward_failure_code_folded <字段>` —— 每次都是一件新的失败;
+ *  · {@link sealStoredResult} = 存量行的**再观看**(读座必填)⇒ 走 fail-open 纪律(登记 tag `server.terminal.stored-result-code-folded`):
+ *    逐读计数 + 逐读探针行 + 每进程一次 warn,detail 即上面那句字段。读面每次轮询 / 每个观看者 / 每次重连都重放同一批行 ——
+ *    计数让「旧失败被读了多少次」看得见,一次 warn 让日志不随读次放大;去重归记录器一只,不另造表。
  *
  * 对任何输入安全(非普通对象 / 无可摘的座 / 码在词法内 ⇒ **同一引用**原样返回,不重塑)。
  */
 export declare function sealResultForExit<T extends {
     readonly terminal?: unknown;
-}>(result: T, readSeat?: StoredResultReadSeat): T;
+}>(result: T): T;
+/**
+ * **存量结果被再观看时的封口** —— 与 {@link sealResultForExit} 同一套封口(摘凭据 + 折码,同判同形),只差运维线索的观看点:
+ * 读座({@link StoredResultReadSeat})**必填**,于是新开一条读腿忘了点名读座是 tsc 红,不是悄悄落成 `at=exit`、按读次放大。
+ */
+export declare function sealStoredResult<T extends {
+    readonly terminal?: unknown;
+}>(result: T, seat: StoredResultReadSeat): T;
 /**
  * **投影出口的唯一属主**([ref])—— core 的 `terminalProjection` + 对外码归一,一次。
  *

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;
 }
@@ -9,9 +11,13 @@ 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);
+    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" },
@@ -41,36 +47,73 @@ function dropCapability(seat, keys) {
     const { [keys.token]: _drop, ...rest } = seat;
     return rest;
 }
-export function sealResultForExit(result, readSeat) {
+export function sealResultForExit(result) {
+    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;
-    return foldOutwardFailureCode(mapPauseSeats(result, dropCapability), readSeat);
+    return foldOutwardFailureCodes(mapPauseSeats(result, dropCapability), at);
 }
-function foldOutwardFailureCode(result, readSeat) {
-    const t = failedCauseWithCode(result.terminal);
-    if (t === undefined)
+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;
+    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 result;
-    reportFold(t.code, outward, t.message, readSeat);
+        return terminal;
+    reportFold(t.code, outward, t.message, at);
     const message = typeof t.message === "string" ? t.message : "the durable store failed";
-    return { ...result, terminal: { ...t, code: outward, message: `${message} [original code: ${t.code}]` } };
-}
-const READ_FOLD_LATCH_CAP = 1024;
-const readFoldLatch = new Set();
-function reportFold(code, outward, message, readSeat) {
-    const original = isCodeToken(code) ? code : "<not-a-code>";
-    if (readSeat !== undefined) {
-        const key = `${readSeat} ${original}`;
-        if (readFoldLatch.has(key))
+    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;
-        if (readFoldLatch.size >= READ_FOLD_LATCH_CAP)
-            readFoldLatch.delete(readFoldLatch.values().next().value);
-        readFoldLatch.add(key);
-    }
+        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;
-    console.warn(`[terminal] outward_failure_code_folded original=${original} outward=${outward} messageBytes=${messageBytes} at=${readSeat ?? "exit"}`);
+    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)}`);
+        }
+    }
 }
 function failedCauseWithCode(t) {
     if (t === null || typeof t !== "object")