@sema-agent/server 7.89.0 → 7.90.0

package/dist/model-route-url.d.ts

@@ -3,6 +3,14 @@ export declare const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
 /** 同族第二码(S-483 座⑨):这一位根本不是一个层级式绝对 URL。三根键共用一码,与上面那只同纪律
  *  (码按**规则**命名,不按键名 —— 键名已经逐字在拒因文案里点过了)。 */
 export declare const MODEL_ROUTE_URL_INVALID_CODE = "config.model_route_url_invalid";
+/**
+ * 🔴 **第三条臂的机读码(S-514;core 7.24.2 / [ref] 提货)——请求根带 `#fragment`**。
+ *
+ * 为什么与前两条各自一码:运维要按码行动,而三条臂的**出路不同**(补全 URL / 把凭据搬去旋钮 / 删掉 `#`
+ * 之后的一切)。`fetch` **从不把 fragment 发上线**,所以这一形此前是**静默**打根自己的路径、端点后缀整段
+ * 落进被丢弃的那一半 —— 请求发得出去、也可能 200,只是打错了地方而一个字不说。
+ */
+export declare const MODEL_ROUTE_URL_FRAGMENT_CODE = "config.model_route_url_fragment";
 /**
  * 模型路由 base URL 的拒因(`undefined` = 这一位合法)—— **这三根键的唯一判官**。
  *

package/dist/model-route-url.js

@@ -1,6 +1,7 @@
 import { buildDisplaySafeUrl, isHierarchicalUrl } from "./trace/redact.js";
 export const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
 export const MODEL_ROUTE_URL_INVALID_CODE = "config.model_route_url_invalid";
+export const MODEL_ROUTE_URL_FRAGMENT_CODE = "config.model_route_url_fragment";
 export function modelRouteUrlRefusal(envKey, raw, credentialKnob) {
     if (raw === "")
         return undefined;
@@ -12,13 +13,21 @@ export function modelRouteUrlRefusal(envKey, raw, credentialKnob) {
             `Set ${envKey} to a full scheme://host URL (and put the credential in ${credentialKnob}, never in the URL).`);
     }
     const u = new URL(raw);
-    if (u.username === "" && u.password === "")
-        return undefined;
-    return (`env ${envKey} carries credentials in the URL userinfo (${buildDisplaySafeUrl(raw)}) [${GATEWAY_URL_USERINFO_CODE}] — ` +
-        "WHATWG forbids constructing a fetch Request from a URL with credentials, so EVERY model call on this route " +
-        "fails deterministically at request-construction time (it used to look like a slow network flake: the error was " +
-        "retried for ~3 minutes before surfacing). " +
-        `Put the credential in ${credentialKnob} (or the matching header knob) instead of the URL, and keep the URL to ` +
-        "scheme/host/port/path.");
+    if (u.username !== "" || u.password !== "")
+        return (`env ${envKey} carries credentials in the URL userinfo (${buildDisplaySafeUrl(raw)}) [${GATEWAY_URL_USERINFO_CODE}] — ` +
+            "WHATWG forbids constructing a fetch Request from a URL with credentials, so EVERY model call on this route " +
+            "fails deterministically at request-construction time (it used to look like a slow network flake: the error was " +
+            "retried for ~3 minutes before surfacing). " +
+            `Put the credential in ${credentialKnob} (or the matching header knob) instead of the URL, and keep the URL to ` +
+            "scheme/host/port/path.");
+    if (u.hash !== "") {
+        return (`env ${envKey} carries a URL fragment (${buildDisplaySafeUrl(raw)}#…) [${MODEL_ROUTE_URL_FRAGMENT_CODE}] — ` +
+            "a fragment is never sent on the wire, so this route would silently target the root's own path and every " +
+            "endpoint suffix (/chat/completions, /v1/messages) would land inside the discarded part: the request goes out, " +
+            "may even return 200, and points somewhere else without saying so. " +
+            `Drop everything from the "#" on in ${envKey}. A per-deployment QUERY is fully supported and rides every ` +
+            "request (a gateway's `?api-version=…`); a fragment cannot be.");
+    }
+    return undefined;
 }
 //# sourceMappingURL=model-route-url.js.map

package/dist/plugins/memory-embedder.d.ts

@@ -26,12 +26,6 @@ export interface OpenAiCompatEmbedderOptions extends MemoryEmbedderConfig {
  * URL 合法性门,只在运行期炸(而运行期的炸法就是上面那条「写入失败/检索退档」的静默病)。
  */
 export declare function embeddingsUrl(endpoint: string): string;
-/**
- * 诊断面用的**脱敏** URL(codex 复审 F4,已核真):端点里可能带 userinfo(`https://user:pass@h/v1`)
- * 或把凭据放 query(Azure 的 `api-key=`),而错误文本会进日志、进 PatchReport 的 conflict reason。
- * 主机与路径保留(诊断价值全在这里),userinfo 抹掉、query 值一律换成 `***`(键名保留,便于认形)。
- */
-export declare function redactEndpointForLog(raw: string): string;
 /** 造一个 OpenAI 兼容的 `PgEmbedder`(工厂命名律:返回带行为的对象 ⇒ `create*`)。 */
 export declare function createOpenAiCompatEmbedder(opts: OpenAiCompatEmbedderOptions): PgEmbedder;
 /**

package/dist/plugins/memory-embedder.js

@@ -1,13 +1,17 @@
+import { joinRequestUrl } from "@sema-agent/core";
 import { z } from "zod";
+import { buildDisplaySafeRefusal, buildDisplaySafeUrl } from "../trace/redact.js";
 const EmbeddingsResponse = z.object({
     data: z.array(z.object({ embedding: z.array(z.number()) })).min(1),
 });
 export function embeddingsUrl(endpoint) {
-    const u = new URL(endpoint);
-    u.hash = "";
-    const path = u.pathname.replace(/\/+$/, "");
-    u.pathname = decodeUnreservedEscapes(path).endsWith("/embeddings") ? path : `${path}/embeddings`;
-    return u.toString();
+    const path = URL.canParse(endpoint) ? new URL(endpoint).pathname.replace(/\/+$/, "") : "";
+    try {
+        return joinRequestUrl(endpoint, decodeUnreservedEscapes(path).endsWith("/embeddings") ? "" : "/embeddings");
+    }
+    catch (e) {
+        throw new Error(buildDisplaySafeRefusal(e instanceof Error ? e.message : String(e), [endpoint]), { cause: undefined });
+    }
 }
 function decodeUnreservedEscapes(s) {
     return s.replace(/%([0-9A-Fa-f]{2})/g, (whole, hex) => {
@@ -15,16 +19,6 @@ function decodeUnreservedEscapes(s) {
         return /[A-Za-z0-9\-._~]/.test(c) ? c : whole;
     });
 }
-export function redactEndpointForLog(raw) {
-    if (!URL.canParse(raw))
-        return "<invalid-url>";
-    const u = new URL(raw);
-    u.username = "";
-    u.password = "";
-    for (const k of [...u.searchParams.keys()])
-        u.searchParams.set(k, "***");
-    return u.toString();
-}
 function credentialsInQuery(endpoint) {
     if (!URL.canParse(endpoint))
         return [];
@@ -32,7 +26,7 @@ function credentialsInQuery(endpoint) {
 }
 export function createOpenAiCompatEmbedder(opts) {
     const url = embeddingsUrl(opts.endpoint);
-    const shownUrl = redactEndpointForLog(url);
+    const shownUrl = buildDisplaySafeUrl(url);
     const fetchImpl = opts.fetchImpl ?? fetch;
     const { model, dimensions, timeoutMs, apiKey, onFailure } = opts;
     const secrets = [...(apiKey !== undefined ? [apiKey] : []), ...credentialsInQuery(opts.endpoint)];

package/dist/request-key-closure.js

@@ -20,7 +20,8 @@ export function keyClosureClause(names, label) {
 const TASK_BODY_DECLARED_KEYS = [
     "a2aPeers", "acceptPartialRestore", "additionalDirectories", "additionalReadDirectories", "agents",
     "appendSystemPrompt", "attachmentIds", "attachments", "capabilitiesNeeded", "cascade", "clientContext",
-    "compaction", "compactionModel", "council", "cwd", "debate", "deferTools", "deviceId", "enableFork", "excludeTools",
+    "compaction", "compactionModel", "council", "cwd", "debate", "deferTools", "deviceId", "enableFork",
+    "excludeAllTools", "excludeTools",
     "finalVerification", "forwardSubagentEvents", "images", "interactiveTools", "jobId", "limits", "maxCostUsd",
     "maxTokens", "mcpServers", "memory", "memoryCapture", "memoryWrite", "model", "objective", "oneShot", "outputRetries",
     "outputSchema", "permissionMode", "projectId", "promptProfile", "reasoningEffort", "requireExistingSession",

package/dist/runtime-governance.d.ts

@@ -24,12 +24,14 @@
  * name). Real isolation is the `executionEnv` sandbox. Same caveat core documents on `createCoarseCommandNamePolicy`.
  */
 import { type TaskSpec, type ToolPolicy } from "@sema-agent/core";
+import { GovernanceConfig } from "@sema-agent/settings-schema";
 import { type GovernanceAskMarks } from "./governance-ask-marks.js";
-/** A per-command governance rule (registry `runtime.commandPolicy[]`). */
-export type CommandRule = {
-    command: string;
-    decision: "allow" | "ask" | "deny";
-};
+/** 运维 autonomy 四档的**闭集**(同上)。`config.ts` 的 `parseAutonomy` 也从这里读 —— 四档词表全仓一份。 */
+export declare const AUTONOMY_MODES: ["read-only", "ask", "plan", "auto"];
+/** A per-command governance rule (registry `runtime.commandPolicy[]`) —— **型也从契约派生**:
+ *  契约给 `command` 加一条 refine / 给 `decision` 加一个判词,本仓的型当场跟上(或在下面的
+ *  `RANK` / 穷尽 switch 上编译红),而不是靠人记得把手写联合改一遍。 */
+export type CommandRule = NonNullable<GovernanceConfig["commandPolicy"]>[number];
 /** True when `name` names a DELEGATION tool — the subagent tool(CC-187 canonical `"Agent"`,core
  *  `DEFAULT_SUBAGENT_TOOL_NAME`)。5.0.0 [ref]:折叠面退役,RAW 比对 core 单源常量——旧名("Task")
  *  在 core roster 层响亮 miss,不再需要归一;单源常量本身就防了当年 1.202 改名时裸字符串失配的
@@ -50,8 +52,8 @@ export declare function isDelegationToolName(name: string): boolean;
 export declare function stripDelegationTools<T extends {
     name: string;
 }>(tools: readonly T[]): T[];
-/** The operator autonomy mode (registry `runtime.autonomy`). */
-export type Autonomy = "read-only" | "ask" | "plan" | "auto";
+/** The operator autonomy mode (registry `governance.autonomy`) —— 契约派生(见 {@link AUTONOMY_MODES})。 */
+export type Autonomy = NonNullable<GovernanceConfig["autonomy"]>;
 /** 导出给 `test/coarse-shell-tools-mirror.test.ts` 的同源钉用(见那里的顶注)。 */
 export declare const COARSE_SHELL_TOOLS_MIRROR: readonly string[];
 /** Validate `commandPolicy` rules — the shape (array of {command, decision}), the `command` (a bare argv[0] name,
@@ -81,6 +83,13 @@ export declare function validateCommandRules(rules: CommandRule[]): string[];
  * Either way the result only ever ADDS asks/denies — composed onto the baseline via `combinePolicies`
  * (deny-wins) by {@link applyRuntimeGovernance}, so it is tighten-only. (Assumes commands are pre-validated by
  * {@link validateCommandRules}; an un-matchable command here is simply inert, never a parse error.)
+ *
+ * 🔴 **S-496:词表外的 `decision` 折 `deny`,不折 `ask`。** {@link validateCommandRules} 的头注写下的那条
+ * 后果(「域外的 `decision` 穿过本函数的三元链落到 ASK,静默把一条 intended deny 弱化掉」)此前只靠
+ * **调用方记得先校验**挡着 —— 而本函数在 `resolve-spec` 里是逐请求现调的,`config.commandPolicy` 的来路
+ * (center hot apply / 本地 `config.d/governance.json` / LKG / 测试直塞)不止一条。现在闭集在本函数**内部**
+ * 收口:`VALID_DECISIONS` 之外的值一律折最严的 `deny`(fail-closed,[ref] 的运行期 miss 臂,下方自陈),
+ * 闭集本身则由契约 zod 派生 ⇒ 契约加一个判词,`RANK` 与桶分配的穷尽 switch 双双**编译红**。
  */
 export declare function compileCommandPolicy(rules: CommandRule[] | undefined): ToolPolicy | undefined;
 /**

package/dist/runtime-governance.js

@@ -1,7 +1,10 @@
 import { combinePolicies, COARSE_SHELL_TOOLS as CORE_COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, DEFAULT_SUBAGENT_TOOL_NAME, parseLeadingCommandName, tightenTaskSpec, } from "@sema-agent/core";
-import { SAFETY_MERGE_SPEC } from "@sema-agent/settings-schema";
+import { GovernanceConfig, SAFETY_MERGE_SPEC } from "@sema-agent/settings-schema";
 import { currentGovernanceAskMarks } from "./governance-ask-marks.js";
 import { operatorAsk } from "./operator-ask.js";
+const COMMAND_RULE_SHAPE = GovernanceConfig.shape.commandPolicy.unwrap().element.shape;
+const COMMAND_DECISIONS = COMMAND_RULE_SHAPE.decision.options;
+export const AUTONOMY_MODES = GovernanceConfig.shape.autonomy.unwrap().options;
 export function isDelegationToolName(name) {
     return name === DEFAULT_SUBAGENT_TOOL_NAME;
 }
@@ -30,7 +33,9 @@ function createCommandAskListPolicy(askCommands, tools = COARSE_SHELL_TOOLS) {
     };
 }
 const VALID_COMMAND_NAME = /^[A-Za-z0-9._+-]+$/;
-const VALID_DECISIONS = new Set(["allow", "ask", "deny"]);
+function isCommandDecision(raw) {
+    return typeof raw === "string" && COMMAND_DECISIONS.includes(raw);
+}
 export function validateCommandRules(rules) {
     const errors = [];
     if (!Array.isArray(rules))
@@ -45,8 +50,8 @@ export function validateCommandRules(rules) {
             errors.push(`commandPolicy command "${String(command)}" is not a bare argv[0] name — core matches the EXACT command name (no glob/path/operators). ` +
                 `Use e.g. "git" not "git*"; to gate sub-commands or pipes, deny the interpreter ("sh"/"bash") + rely on the sandbox.`);
         }
-        if (typeof decision !== "string" || !VALID_DECISIONS.has(decision)) {
-            errors.push(`commandPolicy command "${String(command)}" has invalid decision "${String(decision)}" — must be one of allow | ask | deny`);
+        if (!isCommandDecision(decision)) {
+            errors.push(`commandPolicy command "${String(command)}" has invalid decision "${String(decision)}" — must be one of ${COMMAND_DECISIONS.join(" | ")}`);
         }
     }
     return errors;
@@ -57,15 +62,30 @@ export function compileCommandPolicy(rules) {
     const RANK = { deny: 3, ask: 2, allow: 1 };
     const strictest = new Map();
     for (const r of rules) {
+        const decision = isCommandDecision(r.decision) ? r.decision : "deny";
         const prev = strictest.get(r.command);
-        if (prev === undefined || RANK[r.decision] > RANK[prev])
-            strictest.set(r.command, r.decision);
+        if (RANK[decision] > (prev === undefined ? 0 : RANK[prev]))
+            strictest.set(r.command, decision);
     }
     const deny = [];
     const allow = [];
     const ask = [];
     for (const [command, decision] of strictest) {
-        (decision === "deny" ? deny : decision === "allow" ? allow : ask).push(command);
+        switch (decision) {
+            case "deny":
+                deny.push(command);
+                break;
+            case "allow":
+                allow.push(command);
+                break;
+            case "ask":
+                ask.push(command);
+                break;
+            default: {
+                const unhandled = decision;
+                throw new Error(`commandPolicy decision "${String(unhandled)}" has no compilation arm`);
+            }
+        }
     }
     const policies = [];
     if (allow.length > 0) {

package/dist/session-policy-wire.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `SessionPermissionRules` 的 **wire 形读者** —— 两条写入腿(`PUT /v1/sessions/:id/policy` 与
+ * `POST /v1/sessions/:id/sync/import` 的 `policy` 面)**唯一**的形判据。
+ *
+ * ── 为什么是一只共享读者(S-496 / [ref],取证 P4 + S-498)───────────────────────────────────────────
+ * 改前两条腿各自为政:
+ *  · PUT 腿在 `http/routes/sessions.ts` 里**手抄**五桶键名(`["toolAllow","toolDeny","allowDirs",
+ *    "commandAllow","commandDeny"] as const`),core 的 `SessionPermissionRules` 加第六桶 ⇒ 那一桶在
+ *    PUT 上被**静默丢**、200 回执却说「已生效」;
+ *  · sync/import 腿(S-498)只判 `Array.isArray(body.policy)` **外层**,逐条记录的 `principal` / `rules`
+ *    一个字节都不校验就裸交 `replayPolicyRecords` → `putRules`。坏形走的是**放宽**方向,亲读 core
+ *    `session-policy-store.js` 两处实现:
+ *      · `normalizeRules` 对每桶做 `[...rules.toolDeny]` ⇒ 一个**字符串** `"rm"` 被展开成 `["r","m"]`,
+ *        本来该拒 `rm` 的 deny 规则变成拒两个不存在的命令名 = 门整条失效;
+ *      · `allowDirs` 走 `.map(...)` ⇒ 字符串上没有 `.map` ⇒ **TypeError → 500**(路由头注 `:300-302`
+ *        自陈「Malformed shape → 400(never a downstream TypeError)」,这一半没守);
+ *      · `loosenReasons` 的每一臂都从 `prior` 出发,**prior 为空时恒回空集** ⇒ tighten-only 门对一条
+ *        全新的会话放行任何内容,坏形因此连「收紧门」这一层都碰不到。
+ * ⇒ 类修:一只读者,键集由 `keyof SessionPermissionRules` **派生**(下方 `RULE_FIELD_PRESENCE` 的
+ * `satisfies Record<keyof SessionPermissionRules, true>`:core 加桶 ⇒ 缺键**编译红**;core 删桶 ⇒
+ * 多键**编译红**),两条腿同调。
+ *
+ * ── 文案也在这里(codex 一轮追加:两条腿各铸一份句子 = 第二份手抄)───────────────────────────────
+ * 初版把 wire 文案留在两个路由各自铸,理由是错误文案冻结门(`test/api-error-text-freeze.test.ts`)锚的是
+ * `src/http/` 桶里的 `sendError` 站点。codex 一轮指出那等于**把同一句话写了两遍**(`sessions.ts` 与
+ * `session-sync.ts` 各一份),这正是本批要消灭的形。改法照本仓既有成案(S-405 / [ref] / [ref] 三处
+ * 「常量锚」):句子收进本文件**单一属主**,冻结职责搬到冻结门的**常量锚格** —— 那一格直接断言这两只
+ * 渲染器对每一种判词的输出字节,且对判词闭集穷尽(加一种判词 ⇒ 那一格编译红)。文案一个字节未改。
+ */
+import type { SessionPermissionRules, SessionRulesRecord } from "@sema-agent/core";
+/** core `SessionPermissionRules` 的桶名全集(派生,不是手抄)。 */
+export declare const SESSION_PERMISSION_RULE_FIELDS: readonly (keyof SessionPermissionRules)[];
+/** 一条规则体的形问题。判词而非文案(见文件头注的「文案属主」一段)。 */
+export type SessionPermissionRulesProblem = 
+/** 整体不是一只普通对象(`null` / 数组 / 标量 / 缺席)。 */
+{
+    kind: "not-an-object";
+}
+/** 某一桶在场但不是 `string[]`(字符串 / 数字 / 混杂数组都在此)。 */
+ | {
+    kind: "field-not-string-array";
+    field: keyof SessionPermissionRules;
+};
+/** {@link readSessionPermissionRules} 的读数:坏形给判词,好形给**已收窄**的规则体(调用方零 cast)。 */
+export type SessionPermissionRulesRead = {
+    problem: SessionPermissionRulesProblem;
+    rules?: undefined;
+} | {
+    problem?: undefined;
+    rules: SessionPermissionRules;
+};
+/**
+ * 读一只 wire 上的 `SessionPermissionRules`:形不对给判词,形对给**只含五桶**的规则体。
+ *
+ * 认识面窄得刻意:**只判形**,不判内容(桶内字符串的 pattern 文法、路径是否可达、tighten-only 是否成立
+ * 都不在这里 —— 前两者归 core 的 rule 文法与 `normalizeRules`,后者归 `putRules` 的收紧门)。
+ * 未知键**照旧忽略**(不是新的拒因):core 的 `normalizeRules` 本来就只搬这五桶,本读者与它同口径。
+ */
+export declare function readSessionPermissionRules(raw: unknown): SessionPermissionRulesRead;
+/** 一条 `SessionRulesRecord` 的形问题(`policy[]` 的元素级;桶级问题原样转载在 `rules` 位)。 */
+export type SessionRulesRecordProblem = 
+/** `policy` 本身不是数组。 */
+{
+    kind: "not-an-array";
+}
+/** 第 `index` 条记录不是一只普通对象。 */
+ | {
+    kind: "record-not-an-object";
+    index: number;
+}
+/** 第 `index` 条的 `principal` 在场但不是字符串(**缺席**才是「会话级默认行」的合法写法 —— 两个店的
+ *  `listBySession` 对无 principal 的行都产 `undefined`,JSON 序列化后即缺席,所以 `null` 不在受理面)。 */
+ | {
+    kind: "principal-not-a-string";
+    index: number;
+}
+/** 第 `index` 条的 `rules` 形不对(转载桶级判词)。 */
+ | {
+    kind: "rules";
+    index: number;
+    problem: SessionPermissionRulesProblem;
+};
+/** {@link readSessionRulesRecords} 的读数。 */
+export type SessionRulesRecordsRead = {
+    problem: SessionRulesRecordProblem;
+    records?: undefined;
+} | {
+    problem?: undefined;
+    records: SessionRulesRecord[];
+};
+/**
+ * 读 sync/import 的 `policy` 面(`SessionRulesRecord[]`)。好形返回**已收窄**的记录数组,坏形给判词。
+ *
+ * `rev`:记录里带的 `rev` 是**导出端的**乐观锁读数,`putRules` 侧一进门就 `stripRev` 掉(`sameRulesContent`
+ * 也比的是去 rev 的字节形),所以它在本读者里只是过境位 —— 非数字即当缺席(不是拒因:一个坏 rev 改变不了
+ * 任何一次写入的结果,拒它只会把合法同步砖死)。
+ */
+export declare function readSessionRulesRecords(raw: unknown): SessionRulesRecordsRead;
+/** 桶级判词 → 人话。闭集穷尽:{@link SessionPermissionRulesProblem} 加一种判词 ⇒ 本 switch 编译红。 */
+export declare function describeSessionPermissionRulesProblem(p: SessionPermissionRulesProblem): string;
+/** `policy[]` 判词 → 人话(sync/import 腿在它前面拼 `policy: `)。闭集穷尽同上。 */
+export declare function describeSessionRulesRecordProblem(p: SessionRulesRecordProblem): string;
+//# sourceMappingURL=session-policy-wire.d.ts.map

package/dist/session-policy-wire.js

@@ -0,0 +1,66 @@
+const RULE_FIELD_PRESENCE = {
+    toolAllow: true,
+    toolDeny: true,
+    allowDirs: true,
+    commandAllow: true,
+    commandDeny: true,
+};
+export const SESSION_PERMISSION_RULE_FIELDS = Object.keys(RULE_FIELD_PRESENCE);
+export function readSessionPermissionRules(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { problem: { kind: "not-an-object" } };
+    const src = raw;
+    const rules = {};
+    for (const field of SESSION_PERMISSION_RULE_FIELDS) {
+        const v = src[field];
+        if (v === undefined)
+            continue;
+        if (!Array.isArray(v) || !v.every((x) => typeof x === "string"))
+            return { problem: { kind: "field-not-string-array", field } };
+        rules[field] = v;
+    }
+    return { rules };
+}
+export function readSessionRulesRecords(raw) {
+    if (!Array.isArray(raw))
+        return { problem: { kind: "not-an-array" } };
+    const records = [];
+    for (let index = 0; index < raw.length; index++) {
+        const e = raw[index];
+        if (e === null || typeof e !== "object" || Array.isArray(e))
+            return { problem: { kind: "record-not-an-object", index } };
+        const { principal, rules, rev } = e;
+        if (principal !== undefined && typeof principal !== "string")
+            return { problem: { kind: "principal-not-a-string", index } };
+        const read = readSessionPermissionRules(rules);
+        if (read.problem !== undefined)
+            return { problem: { kind: "rules", index, problem: read.problem } };
+        const innerRev = rules?.rev;
+        const carried = typeof innerRev === "number" ? innerRev : typeof rev === "number" ? rev : 0;
+        records.push({ principal, rules: { ...read.rules, rev: carried } });
+    }
+    return { records };
+}
+export function describeSessionPermissionRulesProblem(p) {
+    switch (p.kind) {
+        case "not-an-object": return "rules must be a SessionPermissionRules object";
+        case "field-not-string-array": return `${p.field} must be an array of strings`;
+        default: {
+            const unhandled = p;
+            throw new Error(`unhandled SessionPermissionRules problem: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+export function describeSessionRulesRecordProblem(p) {
+    switch (p.kind) {
+        case "not-an-array": return "must be an array of {principal, rules} records";
+        case "record-not-an-object": return `[${p.index}] must be a {principal, rules} record`;
+        case "principal-not-a-string": return `[${p.index}].principal must be a string when present (omit it for the session-wide row)`;
+        case "rules": return `[${p.index}].rules: ${describeSessionPermissionRulesProblem(p.problem)}`;
+        default: {
+            const unhandled = p;
+            throw new Error(`unhandled SessionRulesRecord problem: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+//# sourceMappingURL=session-policy-wire.js.map

package/dist/task-settings.d.ts

@@ -48,7 +48,16 @@ import { type KeyClosureIssue } from "./request-key-closure.js";
  *  deployment approval/governance baseline is composed OUTSIDE this derive and is untouchable from a settings stamp),
  *  and `auto` adds the same ask gate as `default` with core's auto-mode classifier screening the asks upstream
  *  (entitlement-gated in core, [ref]②). */
-export type SettingsPermissionMode = "default" | "acceptEdits" | "plan" | "bypassPermissions" | "auto";
+export declare const SETTINGS_PERMISSION_MODES: readonly ["default", "acceptEdits", "plan", "bypassPermissions", "auto"];
+/** 五模式闭集的型形 —— **从值表派生**(S-496 / [ref]):改前本仓有 **4 份**同一张五词表(本处的手写联合 /
+ *  下面 `coercePermissionModeStrict` 的运行期字面量链 / `http/admission.ts` 顶层 `permissionMode` 的比较链 /
+ *  同文件 `settings.permissions.defaultMode` 的比较链),外加两句错误文案里各抄一遍词。现在值表一份、
+ *  型与文案都从它派生,比较链改调 {@link isSettingsPermissionMode}。 */
+export type SettingsPermissionMode = (typeof SETTINGS_PERMISSION_MODES)[number];
+/** 五词表的 wire 文案形(`"a" | "b" | …`)—— 两条 400 的句子从这里取词,不再各抄一份。 */
+export declare const SETTINGS_PERMISSION_MODE_WORDS: string;
+/** 闭集成员判定(`unknown` 入口用)—— 词表的**唯一**运行期读者:wire 门与 coerce 两族同调。 */
+export declare function isSettingsPermissionMode(raw: unknown): raw is SettingsPermissionMode;
 /**
  * R4: coerce a raw top-level `body.permissionMode` (the LIGHT per-turn wire — the shell sends the
  * CC permission mode RAW, axis-agnostic; the service interprets) to a service-honored mode, or undefined.
@@ -68,7 +77,8 @@ export type SettingsPermissionMode = "default" | "acceptEdits" | "plan" | "bypas
  */
 export declare function coercePermissionMode(raw: unknown): SettingsPermissionMode | undefined;
 /** 五模式闭集的**严格**读法([ref] ④:`/v1/capabilities?permissionMode=` 查询串用它 —— 读面对词表外的值 400,
- *  不走上面那条给 resume 重放留的 `default` 宽臂)。上面的宽读只是本函数外再包一层折叠,词表单点在此。 */
+ *  不走上面那条给 resume 重放留的 `default` 宽臂)。上面的宽读只是本函数外再包一层折叠。
+ *  S-496:词表单点已上移到 {@link SETTINGS_PERMISSION_MODES},本函数只是它的 `undefined` 形读者。 */
 export declare function coercePermissionModeStrict(raw: unknown): SettingsPermissionMode | undefined;
 /**
  * S-433 —— 一份**被批准的计划**之后,这条会话继续用的 permission mode(`plan_review` 决裁体的

package/dist/task-settings.js

@@ -3,6 +3,11 @@ import { findUnmatchableToolNames, formatUnmatchableToolNames } from "./config.j
 import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
 import { parseHooksConfig } from "./hooks/hook-runner.js";
+export const SETTINGS_PERMISSION_MODES = ["default", "acceptEdits", "plan", "bypassPermissions", "auto"];
+export const SETTINGS_PERMISSION_MODE_WORDS = SETTINGS_PERMISSION_MODES.map((m) => `"${m}"`).join(" | ");
+export function isSettingsPermissionMode(raw) {
+    return typeof raw === "string" && SETTINGS_PERMISSION_MODES.includes(raw);
+}
 export function coercePermissionMode(raw) {
     const strict = coercePermissionModeStrict(raw);
     if (strict !== undefined)
@@ -12,9 +17,7 @@ export function coercePermissionMode(raw) {
     return undefined;
 }
 export function coercePermissionModeStrict(raw) {
-    if (raw === "plan" || raw === "acceptEdits" || raw === "default" || raw === "bypassPermissions" || raw === "auto")
-        return raw;
-    return undefined;
+    return isSettingsPermissionMode(raw) ? raw : undefined;
 }
 export const PLAN_APPROVE_PERMISSION_MODES_AFTER = ["default", "acceptEdits"];
 export function isPlanApprovePermissionModeAfter(raw) {
@@ -154,8 +157,7 @@ export function parseTaskSettings(raw) {
         const allow = cleanStringArray(p.allow);
         const deny = cleanStringArray(p.deny);
         const ask = cleanStringArray(p.ask);
-        const mode = p.defaultMode;
-        const defaultMode = mode === "default" || mode === "acceptEdits" || mode === "plan" || mode === "bypassPermissions" || mode === "auto" ? mode : undefined;
+        const defaultMode = coercePermissionModeStrict(p.defaultMode);
         const rawKill = p.disableAutoMode;
         const disableAutoMode = rawKill === "disable" || rawKill === true || rawKill === false ? rawKill : undefined;
         if (allow || deny || ask || defaultMode || disableAutoMode !== undefined) {

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

@@ -130,8 +130,8 @@ type SummaryProjected = "sessionId" | "scope" | "createdAt" | "gateKind" | "seve
 type SummaryExcluded = "token" | "toolInput" | "toolName" | "toolCallId" | "preview" | "principal" | "sourceTaskId" | "contentKind" | "restoreMode" | "checkpointId" | "previewWithheld";
 type _GuardInboxSummary = AssertAllKeysHandled<Exclude<keyof CheckpointSummary, SummaryProjected | SummaryExcluded>>;
 type _GuardInboxSummaryReverse = AssertAllKeysHandled<Exclude<SummaryProjected | SummaryExcluded, keyof CheckpointSummary>>;
-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" | "writeFace" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "taskId" | "signal" | "preemptSignal" | "modelRole" | "enableBlockedReport" | "maxSuspends" | "autoModeRequested" | "skillListingBudgetFraction" | "skillListingMaxDescChars";
-type TaskSpecUnwired = "excludeAllTools" | "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars";
+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" | "writeFace" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "taskId" | "signal" | "preemptSignal" | "modelRole" | "enableBlockedReport" | "maxSuspends" | "autoModeRequested" | "skillListingBudgetFraction" | "skillListingMaxDescChars" | "excludeAllTools";
+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" | "terminal" | "model" | "effectiveReasoning" | "result" | "salvagedOutput" | "remoteEnvFailures" | "apiFailure" | "retryAfterMs" | "degraded" | "structuredOutput" | "rewindNotes" | "haltedOnUserRejection" | "haltedByUser" | "strandedHumanAnswers" | "pendingApproval" | "approvalWaitedMs" | "effectiveReadFace" | "effectiveReadDenyPatterns" | "effectiveWriteFace" | "effectiveMemoryScopes" | "stats" | "editedFiles";

package/dist/trace/project.d.ts

@@ -769,6 +769,13 @@ export declare function compactedEventData(ev: {
     clampReason?: "budget" | "tolerance";
     tokensAfter?: number;
     triggerTokensBefore?: number;
+    /** core 7.24.0 [ref]:引擎**自己**算的结构性净减(pre-messages 的结构和 减去 post-messages 的同一个和,
+     *  铸点处 clamp ≥0),三条压缩车道(turn 边界 / prompt-too-long 恢复 / 任务末 settle)同一只
+     *  `mintCompactedEvent` 出。🔴 **缺席 = post 测量失败,不是 0**:上面那两个旧键(`tokensAfter` /
+     *  `triggerTokensBefore`)自本版起在 core 的类型上写明是**诊断位、不可相减**(触发闸读的是 usage 锚定
+     *  的数、post 恒是结构和 + 固定提示词开销,两者的差混坐标,实测在普通 run 上是负数)。本仓的处置因此
+     *  是**三条都逐字透传、一条都不合成**:谁要画上下文表就读 `freedTokens`,读不到就渲染 unknown。 */
+    freedTokens?: number;
     durationMs?: number;
     phaseDurations?: {
         prepareMs?: number;

package/dist/trace/project.js

@@ -656,6 +656,7 @@ export function compactedEventData(ev) {
         ...(ev.clampReason !== undefined ? { clampReason: ev.clampReason } : {}),
         ...(num(ev.tokensAfter) !== undefined ? { tokensAfter: num(ev.tokensAfter) } : {}),
         ...(num(ev.triggerTokensBefore) !== undefined ? { triggerTokensBefore: num(ev.triggerTokensBefore) } : {}),
+        ...(num(ev.freedTokens) !== undefined ? { freedTokens: num(ev.freedTokens) } : {}),
         ...(num(ev.durationMs) !== undefined ? { durationMs: num(ev.durationMs) } : {}),
         ...(phaseDurations !== undefined ? { phaseDurations } : {}),
     };