@sema-agent/server 7.114.0 → 7.116.0

package/dist/run-local.js

@@ -8,11 +8,12 @@ import { realpathSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { Runner, uuidv7, FileStorageBackend, NodeExecutionEnv, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore, defaultTaskRegistry } from "@sema-agent/core";
+import { readAskClassPair } from "./approval-card.js";
 import { singleUserAutoAcceptBaselineApplies } from "./approval.js";
 import { withUnattendedLeg } from "./unattended-permission-mode.js";
 import { buildUnattendedPolicyRefusal } from "./tool-approval.js";
 import { createBrain } from "./brain.js";
-import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, createApprovalBaselinePolicy, createDeploymentGovernanceInputs, } from "./deployment-governance.js";
+import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, buildApprovalGrantNotice, createApprovalBaselinePolicy, createDeploymentGovernanceInputs, } from "./deployment-governance.js";
 import { applyRuntimeGovernance } from "./runtime-governance.js";
 import { ForkRoutingSessionStore } from "./plugins/fork-routing-session-store.js";
 import { taskWallClockSec } from "./task-workflow.js";
@@ -133,6 +134,52 @@ export function applyLocalGovernance(base, config, workspaceDir, engineDataRoot)
 }
 const NO_TTY_REFUSAL_REASON = "this run-local invocation has no TTY, so there is no one to put this approval to; it is refused fail-closed instead of being asked.";
 const UNDISPLAYABLE_ARGS_REFUSAL_REASON = "the call's arguments cannot be displayed, so there is nothing a person could review; it is refused fail-closed instead of being asked.";
+const NO_TTY_SPOKEN_REMEDIES = ["grant", "approval_lists", "deployment_mandate", "shell_gate"];
+export const NO_TTY_ASK_CLASS_ROW = {
+    content_question: { remedy: "terminal_only", autoBudgetReleases: false },
+    hook: { remedy: "terminal_only", autoBudgetReleases: false },
+    ancestor: { remedy: "terminal_only", autoBudgetReleases: false },
+    unverifiable_delete: { remedy: "terminal_only", autoBudgetReleases: false },
+    transcript_write: { remedy: "terminal_only", autoBudgetReleases: false },
+    org_rule: { remedy: "terminal_only", autoBudgetReleases: false },
+    governance_unavailable: { remedy: "terminal_only", autoBudgetReleases: false },
+    rule_unreadable: { remedy: "terminal_only", autoBudgetReleases: false },
+    ask_rule: { remedy: "approval_lists", autoBudgetReleases: true },
+    denial_limit_fallback: { remedy: "terminal_only", autoBudgetReleases: false },
+    operator_forced: { remedy: "deployment_mandate", autoBudgetReleases: false },
+    shell_floor: { remedy: "shell_gate", autoBudgetReleases: false },
+    write_protection_unresolved: { remedy: "terminal_only", autoBudgetReleases: false },
+    probe: { remedy: "terminal_only", autoBudgetReleases: false },
+    write_protection: { remedy: "terminal_only", autoBudgetReleases: false },
+    tool_marks_mcp: { remedy: "terminal_only", autoBudgetReleases: false },
+    tool_marks_a2a: { remedy: "terminal_only", autoBudgetReleases: false },
+    policy_rra: { remedy: "terminal_only", autoBudgetReleases: false },
+    artifact_shared_read: { remedy: "terminal_only", autoBudgetReleases: false },
+    mode: { remedy: "terminal_only", autoBudgetReleases: false },
+    unstated: { remedy: "grant", autoBudgetReleases: false },
+    ordinary: { remedy: "terminal_only", autoBudgetReleases: false },
+    requires_user_interaction: { remedy: "terminal_only", autoBudgetReleases: false },
+};
+const NO_TTY_REMEDY_SENTENCE = {
+    grant: () => `No rule, policy or hook granted this server tool and it states no permission of its own: the operator states one with APPROVAL_GRANT ` +
+        `(an allow rule for server tools — an exact tool name, mcp__<server>__* or a2a__<peer>__*).`,
+    approval_lists: (budget) => `The gate comes from the approval lists: APPROVAL_REQUIRE / APPROVAL_NEVER_AUTO (APPROVAL_DENY refuses outright without asking); ` +
+        `a separate .env for this CLI keeps a server's lists off it.` +
+        (budget ? ` APPROVAL_AUTO_BUDGET auto-approves that many APPROVAL_REQUIRE calls.` : ""),
+    deployment_mandate: () => `This deployment mandates a person for it — one of: APPROVAL_NEVER_AUTO (always a human), or a runtime.commandPolicy entry in config.d/governance.json ` +
+        `(an \`ask\` entry, or — when that policy has any \`allow\` entry — a command it does not list).`,
+    shell_gate: () => `This deployment raises the shell gate to always-ask — one of: AUTONOMY=ask, MANUAL_MODE_SHELL_GATE=always.`,
+};
+function buildNoTtyRemedySentence(req) {
+    const terminal = "Run it in a terminal to answer interactively.";
+    const pair = readAskClassPair(req);
+    if (pair === undefined)
+        return `The engine did not say what kind of question this is, so no setting can be named here. ${terminal}`;
+    const rows = pair.classes.map((c) => NO_TTY_ASK_CLASS_ROW[c]);
+    const budget = rows.every((r) => r.autoBudgetReleases);
+    const spoken = NO_TTY_SPOKEN_REMEDIES.filter((k) => rows.some((r) => r.remedy === k)).map((k) => NO_TTY_REMEDY_SENTENCE[k](budget));
+    return [...spoken, terminal].join(" ");
+}
 export function createLocalApprover(io) {
     let tail = Promise.resolve();
     const refuseWithoutPerson = (reason) => {
@@ -141,11 +188,7 @@ export function createLocalApprover(io) {
     };
     return async (req, signal) => {
         if (!io.isTty) {
-            io.printErr(`denied "${terminalSafeText(req.toolName)}" (${terminalSafeText(req.message)}) — this run-local invocation has no TTY, so there is nobody to ask. ` +
-                `The gate comes from this deployment's governance knobs: APPROVAL_REQUIRE / APPROVAL_NEVER_AUTO (the approval lists; ` +
-                `APPROVAL_DENY refuses outright without asking), AUTONOMY, MANUAL_MODE_SHELL_GATE, runtime.commandPolicy (config.d/governance.json). ` +
-                `Run it in a terminal to answer interactively, or relax the knob (APPROVAL_AUTO_BUDGET auto-approves that many APPROVAL_REQUIRE calls; ` +
-                `a separate .env for this CLI keeps a server's lists off it).`);
+            io.printErr(`denied "${terminalSafeText(req.toolName)}" (${terminalSafeText(req.message)}) — this run-local invocation has no TTY, so there is nobody to ask. ${buildNoTtyRemedySentence(req)}`);
             return refuseWithoutPerson(NO_TTY_REFUSAL_REASON);
         }
         const argsShown = argsDisplayOf(req.args);
@@ -334,6 +377,9 @@ export async function runLocal(argv, deps = {}) {
     });
     if (ungatedCompensation)
         logger.warn(ungatedCompensation.event, ungatedCompensation.fields);
+    const approvalGrantNotice = buildApprovalGrantNotice(config);
+    if (approvalGrantNotice)
+        logger.info(approvalGrantNotice.event, approvalGrantNotice.fields);
     if (!deps.brain) {
         const missing = missingGatewayRequirements(config);
         if (missing.length > 0) {

package/dist/runs.d.ts

@@ -99,64 +99,6 @@ export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, ta
 export declare function isSessionConflictResult(result: {
     terminal: TerminalCause;
 }): boolean;
-/**
- * E18 resume-at CALLER error → an HTTP 4xx. A bad/stale resume-at target (the resolved entryId is gone or is not a
- * settled message boundary) surfaces as a FAILED TaskResult carrying a `resume_at.*` errorCode (core swallows the
- * prepare-throw into the result, exactly like a session conflict — runtask catch → status:"failed"+errorCode). The
- * sync path otherwise 200s a failed result; map these to 4xx so a caller mistake reads as one. `not_found` (the
- * entry is genuinely absent) → 404; everything else (not_a_message / conflicts_resume / no_session) → 422.
- *
- * [ref] Phase3: `requireExistingSession` on a genuinely-missing/purged session ALSO surfaces as a failed result
- * (core prepare-task maps the store's `not_found` → `resume.session_not_found`); map it to 404 (the session is gone),
- * the same "caller mistake reads as a 4xx, not a silent 200 fresh run" discipline.
- *
- * [ref] rewind exclusive mode (core 1.292 resumeAtMode:"before"): its two edge rejections ride the same `resume_at.*`
- * prefix (before_target_not_user / before_root_unsupported → 422 via the existing branch, errorCode passed through
- * UNCHANGED for the shell). `rewind_snapshot.unresolvable` (rewindFiles + "before": no snapshot at/above the branch
- * point) is core's third rejection with a DIFFERENT prefix — same caller-mistake shape (prepare-throw, nothing
- * billed), map it to 422 explicitly so it doesn't fall through to a 200-with-failed body.
- *
- * [ref] 件A([ref] 件4): core 5.13.0's org-memory admission rides the SAME prepare-throw pipe
- * (GOVERNANCE_CODES). `memory.admission_denied` is TERMINAL — the principal has no grant on that tenant
- * plane → 403 (a retry cannot change the verdict). `memory.admission_required` is TRANSIENT fail-closed —
- * the directory is unreachable / no resolver is wired → 503 (retry later; the sync leg forwards the
- * result's `retryAfterMs` as body `retryAfterSec`, same family shape as usage.window_exhausted). Exact
- * codes only, no memory.* family grab — an unknown sibling stays a 200-with-failed-body until cataloged.
- *
- * [ref] (core 7.0.0 片2/3, [ref] S-3): the session capture opt-out's four prepare-throw refusals ride the
- * same pipe. `memory.capture_optout_denied` is TERMINAL (the principal's `allowMemoryOptOut` verdict is an
- * explicit `false`, or the posture is `capture-required` / `governed`-with-absent-verdict — a retry cannot
- * change it) → 403, the `memory.admission_denied` twin. `memory.capture_optout_unpersisted` is the
- * declaration arm's "control-plane record could not be written" refusal — a store outage, retry may succeed
- * → 503 (transient fail-closed, the `memory.admission_required` twin; no retryAfterMs on this one — core
- * mints none, so the sync leg forwards no hint rather than inventing one). `config.memory_capture_spelling`
- * is a TaskSpec authoring mistake (the only legal spelling is the string "off") → 400, the
- * `config.memory_erasure_request` family shape. `config.memory_capture_unsupported` is the DEPLOYMENT SHAPE
- * refusing the declaration (remote/per-run execution with no durable capture-record carrier: the record
- * would not survive to a resume replica) → 409 — the request is well-formed, the deployment's state
- * conflicts with it, the `config.refresh_unavailable` family shape ("change the deployment, not the request").
- * Status choices are pinned by the `config.`/`memory.` family status sets in error-code-catalog-live.test.ts.
- *
- * S-125 件⑥(core 7.4.0 [ref]):`rewind.child_scope_unsupported` —— 这条腿是一个**委派子代**,它的文件编辑
- * 记在**根 session** 的文件历史里,所以「把文件还原到某个 entry」是根 session 的动作、不是子代的;core 在
- * prepare 期响亮拒(零计费,文件一个字节没动)。映射 **422**:请求形式合法、语义上找错了执行者 —— 与
- * `resume_at.*` 的「调用方指错了锚」同一族同一档,而不是 404(目标在,只是不归你)也不是 409(部署状态没冲突)。
- * ⚠️ **前缀不吞**:本码前缀是 `rewind.`,与下面那条 `resume_at.` **开集前缀臂**不同族 —— 它不会被那一臂顺手
- * 兜走(兜走会把一条「找错执行者」的拒答成「锚解析不了」),也不是 `rewind_snapshot.`(那是「快照找不到」)。
- * 三个前缀各自成族,逐码对表见 `test/resume-anchor.test.ts` 的 S-125 `rewind.` 族格。
- * 🔴 **可达性如实**:本仓的 HTTP 面**今天铸不出**这条腿 —— 子代由 core 内部的 Agent 工具派生,
- * `fileHistoryLineage` 是 core prepare 的 internals(不在 `TaskSpec` 上),server 从不直接 prepare 一条带
- * lineage 的子代腿。本臂是**分诊面的完备性**(core 说 X ⇒ wire 形是 Y),不是一条今天在跑的路;将来的
- * 委派入口接线那天零改动即生效。同族其余码(`rewind_files_retired` / `invalid_spec` / `conflicting_targets` /
- * `restore_failed`)今天**仍落 200-with-failed-body**,那是各自提货批**之前**就存在的缺口(不是回归),已在上述对表格里
- * 逐码显式登记为债务,并由那道门看住不许陈腐。
- *
- * S-724(core 7.31.0 #1048 / #1050):`rewind.capture_disabled` → **422**(关断词与还原同体 = 自相矛盾;本服务的请求面上
- * 走不到它 —— fresh 受理门先 400 `request.field_conflict`(立门理由:core 这一拒落在会话分叉之后、不回滚;S-865 / core 7.35.0
- * #1195 起 core 在分叉之前拒);映射是分诊面完备性)、`rewind.store_unconfigured`
- * → **409**(部署没有历史店;`FILE_HISTORY_CAPTURE=false` 自本版不再摘店 ⇒ 可达面只剩没有后端的部署形,那里
- * `capabilities.rewindFiles` 恒报 false —— 三问在 CHANGELOG 7.104.0)。
- */
 export declare function resumeAtHttpStatus(result: {
     terminal: TerminalCause;
 }): number | undefined;

package/dist/runs.js

@@ -71,6 +71,19 @@ export function isSessionConflictResult(result) {
         return result.terminal.code === "conflict";
     return /stale write|concurrent write|conflict/i.test(result.terminal.message ?? "");
 }
+const PREPARE_REFUSAL_HTTP_STATUS = {
+    "resume.session_not_found": 404,
+    "rewind_snapshot.unresolvable": 422,
+    "rewind.child_scope_unsupported": 422,
+    "rewind.capture_disabled": 422,
+    "rewind.store_unconfigured": 409,
+    "memory.capture_optout_unpersisted": 503,
+    "config.memory_capture_spelling": 400,
+    "config.invalid_checkpoint_store": 400,
+    "config.skill_listing_budget_invalid": 400,
+    "config.user_invoked_skill_unknown": 400,
+    "config.memory_capture_unsupported": 409,
+};
 export function resumeAtHttpStatus(result) {
     const code = failureCodeOf(result.terminal);
     if (code === undefined)
@@ -86,26 +99,8 @@ export function resumeAtHttpStatus(result) {
         if (wire !== undefined)
             return wire.status;
     }
-    if (code === "resume.session_not_found")
-        return 404;
-    if (code === "rewind_snapshot.unresolvable")
-        return 422;
-    if (code === "rewind.child_scope_unsupported")
-        return 422;
-    if (code === "rewind.capture_disabled")
-        return 422;
-    if (code === "rewind.store_unconfigured")
-        return 409;
-    if (code === "memory.capture_optout_unpersisted")
-        return 503;
-    if (code === "config.memory_capture_spelling")
-        return 400;
-    if (code === "config.invalid_checkpoint_store")
-        return 400;
-    if (code === "config.skill_listing_budget_invalid")
-        return 400;
-    if (code === "config.memory_capture_unsupported")
-        return 409;
+    if (Object.hasOwn(PREPARE_REFUSAL_HTTP_STATUS, code))
+        return PREPARE_REFUSAL_HTTP_STATUS[code];
     if (!code.startsWith("resume_at."))
         return undefined;
     return code === "resume_at.not_found" ? 404 : 422;

package/dist/runtime-governance.d.ts

@@ -97,6 +97,19 @@ export declare function validateCommandRules(rules: CommandRule[]): string[];
  * 闭集本身则由契约 zod 派生 ⇒ 契约加一个判词,`RANK` 与桶分配的穷尽 switch 双双**编译红**。
  */
 export declare function compileCommandPolicyLayers(rules: CommandRule[] | undefined): ToolPolicy[];
+/** 运维 allow 规则表的出处名 = 它的 env 名(盖进每条规则;编不出来 / 不合文法时拒启句的主语)。 */
+export declare const APPROVAL_GRANT_SOURCE = "APPROVAL_GRANT";
+/**
+ * 7.115.0 —— 运维的 allow 规则(`APPROVAL_GRANT`)编成治理层的**叶**(空 / 缺席 ⇒ `[]`,本层一片叶都不铸,折叠逐字与修前同)。
+ *
+ * 编译口是**请求腿 `settings.permissions.allow` 的同一只**(`permission-rule-list.ts` `createRuleListPolicy`,`behavior: "allow"`):命中 = core 带
+ * `decisionReason: "rule"` 的放行(折叠把这句表态带到终局,引擎据此不再为没人表态的服务器工具调用出 `unstated` 卡);未命中 = 裸 allow =
+ * 不表态。它是一片**不收紧**的叶 —— 与 commandPolicy / 守卫集同住一个折叠点,只因为三者是同一个「部署说的话」:折叠 deny > ask > allow,
+ * 同折叠里任何一片叶的 deny / ask、`tightenTaskSpec` 之下的审批基线、之上的请求 settings 与会话规则,照旧压过它。
+ *
+ * 启动校验(`config.ts` `approvalGrantRefusal`)试编的也是本函数 —— 拒启判据与运行期编译是同一只,不会出现「启动收下、任务里编不出来」。
+ */
+export declare function compileApprovalGrantLayers(grant: readonly string[] | undefined): ToolPolicy[];
 /**
  * Expand an autonomy mode into TIGHTEN-ONLY `TaskSpec` safety overrides (the primitives — TRAP #2):
  *  - `read-only` / `plan` → `handsReadOnly: true` **+ `writeFace: "roots"`** (read + propose, never mutate; the
@@ -203,13 +216,18 @@ export declare function governanceOriginOf(gate: {
     };
 } | undefined, governance: GovernancePosture | undefined): true | undefined;
 /**
- * Apply the operator's runtime governance (autonomy + commandPolicy + manualModeShellGate) onto a base
+ * Apply the operator's runtime governance (autonomy + commandPolicy + manualModeShellGate + the guard set + the
+ * `APPROVAL_GRANT` allow rules) onto a base
  * `TaskSpec`, TIGHTEN-ONLY, in a SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy`
  * override (combined onto the baseline by `tightenTaskSpec` — TRAP #1), and autonomy expands to
  * `handsReadOnly` / `shellGate` overrides (TRAP #2). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any
  * override would LOOSEN a stricter base safety field — surfacing a misconfiguration loudly instead of silently
  * weakening the gate. Returns `base` untouched when there is nothing to apply.
  *
+ * 7.115.0:`APPROVAL_GRANT` 是这里唯一一片**不收紧**的叶 —— 它只给出 allow 的那句表态(core 7.40.0 起没人表态的服务器工具调用要问,
+ * 运维的规则就是那句答),从不清掉任何 deny / ask:折叠 deny > ask > allow,所以「部署 ⊇ 操作员 ⊇ 客户端只能收窄」的不变量逐字成立。
+ * 编译口与请求腿的 allow 桶同一只({@link compileApprovalGrantLayers})。
+ *
  * [ref]([ref] server 分单②):`MANUAL_MODE_SHELL_GATE` 从 settings 折叠搬到这里**无条件施加**。旧家
  * (task-settings deriveSettingsPolicy 的 default/auto/acceptEdits 三臂)让一个**部署级 tighten-only 旋钮
  * 的生死由客户端表态在场性决定**:body 无 settings/permissionMode(cli print/headless 腿按设计不 stamp)
@@ -242,6 +260,8 @@ export declare function applyRuntimeGovernance(base: TaskSpec, governance: {
     /** 守卫集的**叶**(`deployment-governance.ts` `createDeploymentGovernanceInputs` 预铸;S-958 起是叶的列表,不是一只预折的策略)。
      *  空列表与缺席同义。 */
     sensitivePathLayers?: readonly ToolPolicy[];
+    /** 7.115.0:运维的 allow 规则(`APPROVAL_GRANT` 原串;本函数经 {@link compileApprovalGrantLayers} 编成叶)。空列表与缺席同义。 */
+    approvalGrant?: readonly string[];
     /** [ref]/[ref] `governanceForced` 的标记表(缺省 = **当前 run 腿的 ALS 表**,见
      *  `governance-ask-marks.ts` 顶注「作用域」段)。注入口只为测试与将来的多实例形。 */
     askMarks?: GovernanceAskMarks;

package/dist/runtime-governance.js

@@ -2,6 +2,7 @@ import { combinePolicies, COARSE_SHELL_TOOLS as CORE_COARSE_SHELL_TOOLS, createC
 import { GovernanceConfig } from "@sema-agent/settings-schema";
 import { currentGovernanceAskMarks } from "./governance-ask-marks.js";
 import { createDeploymentAuthoredPolicy, operatorAsk } from "./operator-ask.js";
+import { createRuleListPolicy } from "./permission-rule-list.js";
 import { heldRuleName } from "./tool-rule-names.js";
 const COMMAND_RULE_SHAPE = GovernanceConfig.shape.commandPolicy.unwrap().element.shape;
 const COMMAND_DECISIONS = COMMAND_RULE_SHAPE.decision.options;
@@ -100,6 +101,10 @@ export function compileCommandPolicyLayers(rules) {
     }
     return policies;
 }
+export const APPROVAL_GRANT_SOURCE = "APPROVAL_GRANT";
+export function compileApprovalGrantLayers(grant) {
+    return grant !== undefined && grant.length > 0 ? [createRuleListPolicy(grant, "allow", APPROVAL_GRANT_SOURCE, undefined)] : [];
+}
 export function autonomyOverrides(autonomy) {
     switch (autonomy) {
         case "read-only":
@@ -143,7 +148,7 @@ function createGovernanceShellGateMarkPolicy(marksOf, tools = COARSE_SHELL_TOOLS
 export function applyRuntimeGovernance(base, governance) {
     const marksOf = () => governance.askMarks ?? currentGovernanceAskMarks();
     const overrides = { ...autonomyOverrides(governance.autonomy) };
-    const layers = [...compileCommandPolicyLayers(governance.commandPolicy), ...(governance.sensitivePathLayers ?? [])];
+    const layers = [...compileCommandPolicyLayers(governance.commandPolicy), ...(governance.sensitivePathLayers ?? []), ...compileApprovalGrantLayers(governance.approvalGrant)];
     const governancePolicy = layers.length > 0 ? createGovernanceAskMarkingPolicy(combinePolicies(...layers.map(createDeploymentAuthoredPolicy)), marksOf) : undefined;
     if (governancePolicy !== undefined)
         overrides.toolPolicy = governancePolicy;

package/dist/security.js

@@ -65,7 +65,7 @@ export function createAuthorizer(config, sessionStore) {
                 let owner = await ownerOf(requested);
                 if (owner === undefined) {
                     if (requireExisting) {
-                        throw new HttpError(404, "requireExistingSession: session does not exist (resume.session_not_found)");
+                        throw createCodedHttpError(404, "resume.session_not_found", "requireExistingSession: session does not exist (resume.session_not_found)");
                     }
                     if (register) {
                         await register(requested, principal ?? null);
@@ -89,7 +89,7 @@ export function createAuthorizer(config, sessionStore) {
         }
         else {
             if (requireExisting) {
-                throw new HttpError(422, "requireExistingSession requires a sessionId — there is no existing session to resume (resume.session_not_found)");
+                throw createCodedHttpError(422, "request.field_conflict", "requireExistingSession requires a sessionId — there is no existing session to resume");
             }
             sessionId = uuidv7();
             if (register)

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

@@ -16,15 +16,25 @@
  *        自陈「Malformed shape → 400(never a downstream TypeError)」,这一半没守);
  *      · `loosenReasons` 的每一臂都从 `prior` 出发,**prior 为空时恒回空集** ⇒ tighten-only 门对一条
  *        全新的会话放行任何内容,坏形因此连「收紧门」这一层都碰不到。
- * ⇒ 类修:一只读者,键集由 `keyof SessionPermissionRules` **派生**(下方 `RULE_FIELD_ROLE` 的
- * `satisfies Record<keyof SessionPermissionRules, RuleFieldRole>`:core 加桶 ⇒ 缺键**编译红**;core 删桶 ⇒
+ * ⇒ 类修:一只读者,键集由 `keyof SessionPermissionRules` **派生**(下方 `RULE_FIELDS` 的
+ * `satisfies Record<keyof SessionPermissionRules, true>`:core 加桶 ⇒ 缺键**编译红**;core 删桶 ⇒
  * 多键**编译红**),两条腿同调。
  *
  * ── S-800(7.105.0):同一只读者多判一问 —— 写得进却跑不了的工具名 ─────────────────────────────────
  * 两条写入腿是 server 往会话规则店写的**全部**写口,所以「写口 fail-closed」收成一只**写口读者**
- * ({@link readWritableSessionPermissionRules} = 形读者 + {@link legacyToolNameOf}),两腿同调,将来第三条写入腿
+ * ({@link readWritableSessionPermissionRules} = 形读者 + 名字判官),两腿同调,将来第三条写入腿
  * 调同一只也同得。判词多一种(`legacy-tool-name`),两腿各把它映射成 `400 rules.legacy_tool_name`(映射点仍在各自
  * 站点:码位只放字面量)。形读者本身不变 —— SQL 店的读回也用它,读回不许判名字(理由见写口读者头注)。
+ * S-1047(7.116.0 / core 7.41.0 #1156):名字判官 = core 导出的 `assertSessionRuleNamesCurrent`(两只 bundled 店与本仓 SQL 双生在 `putRules`
+ * 里同点同调它;准备阶段的名审计与本仓配置表读的是同一只 `judgeRuleToolName`)—— 本仓手写的那一只(`legacyToolNameOf`)删除,零双读;
+ * 「哪几桶装工具名」归 core(它的 `HOLDS_TOOL_NAMES`)。
+ *
+ * ── 7.116.0:写口读者再多判一问 —— 够不着挂载工具的协议名 ─────────────────────────────────────
+ * 缺段(`mcp__srv__` / `mcp__`)与对端段铸不出(`mcp__github.com__*`)的协议名 core 的判官判 `current`(它只看退役名与无前缀 `__` 名),
+ * 而配置表一直拒缺段名 —— 一个名字两张表两种答案,对端段那一半则两张表都照收、永不命中。判官与句子是 `namespaced-rule-name.ts` 的那一只
+ * (配置表同调),码 `400 request.field_invalid`(会话规则写口既有的字段值码;不另铸新码,也不往 core 的判词闭集里塞本仓的词)。
+ * 这一问要逐桶判,而 core 不导出 `HOLDS_TOOL_NAMES` 的运行期值 ⇒ 桶表 {@link TOOL_NAME_FIELDS} 的键集从 core 判官交回的 `field` 型派生(两向 tsc 配对),
+ * 随这一问在 core 自己给出判词那天整只退役。SQL 店写口经 {@link assertSessionRuleNamesReachable} 同判。
  *
  * ── 文案也在这里(codex 一轮追加:两条腿各铸一份句子 = 第二份手抄)───────────────────────────────
  * 初版把 wire 文案留在两个路由各自铸,理由是错误文案冻结门(`test/api-error-text-freeze.test.ts`)锚的是
@@ -33,53 +43,25 @@
  * 「常量锚」):句子收进本文件**单一属主**,冻结职责搬到冻结门的**常量锚格** —— 那一格直接断言这两只
  * 渲染器对每一种判词的输出字节,且对判词闭集穷尽(加一种判词 ⇒ 那一格编译红)。文案一个字节未改。
  */
-import type { SessionPermissionRules, SessionPolicyError, SessionRulesRecord } from "@sema-agent/core";
-declare const RULE_FIELD_ROLE: {
-    readonly toolAllow: "tool-name";
-    readonly toolDeny: "tool-name";
-    readonly allowDirs: "path";
-    readonly commandAllow: "command";
-    readonly commandDeny: "command";
-};
+import { SessionPolicyError } from "@sema-agent/core";
+import type { SessionPermissionRules, SessionRuleNameRefusal, SessionRulesRecord } from "@sema-agent/core";
+import { type UnreachableNamespacedRuleName } from "./namespaced-rule-name.js";
 /** core `SessionPermissionRules` 的桶名全集(派生,不是手抄)。 */
 export declare const SESSION_PERMISSION_RULE_FIELDS: readonly (keyof SessionPermissionRules)[];
-/** 装工具名的那几桶(由 {@link RULE_FIELD_ROLE} 派生的型)。 */
-export type ToolNameRuleField = {
-    [K in keyof typeof RULE_FIELD_ROLE]: (typeof RULE_FIELD_ROLE)[K] extends "tool-name" ? K : never;
-}[keyof typeof RULE_FIELD_ROLE];
+/** 工具名桶里一条够不着任何挂载工具的协议名(缺段 / 对端段铸不出);`verdict` = 判官的判词。 */
+export interface SessionRuleUnreachableName {
+    readonly field: SessionRuleNameRefusal["field"];
+    readonly name: string;
+    readonly verdict: UnreachableNamespacedRuleName;
+}
+/** 逐桶逐条过协议规则名判官;第一条够不着的交回,全部够得着 ⇒ `undefined`。 */
+export declare function unreachableSessionRuleNameOf(rules: SessionPermissionRules): SessionRuleUnreachableName | undefined;
 /**
- * S-800(client-core [ref] CC-226;server [ref];core [ref])—— 「写得进、跑不了、撤不掉」的工具名。
- *
- * 两臂,逐字对应 core 7.33.8 准备阶段名审计抛 `config.legacy_tool_name` 的那两臂(判据只用 core **导出**的
- * 两件,零镜像表 —— 表随 core 钉版走):
- *  · `"retired"`:名字在 core 的 `RETIRED_TOOL_NAMES` 里;`guidance` = 那张表给它的一句现役指引(原样);
- *  · `"unprefixed-namespace"`:名字里有 `"__"` 分隔符,而 `protocolOf(name)` 认不出它属于哪个协议。
- *
- * 为什么在**写口**判:会话规则店只准非 operator 收紧,删掉一条 deny 算放宽 ⇒ 写进去的这种名字属主自己删不掉,
- * 而准备阶段见它就整只拒启 ⇒ 这个会话之后的每一跑都起不来。写口是唯一还来得及说「不」的地方。
- *
- * ⚠️ **比准备阶段严一格**(方向安全,与 client-core 0.83.6 的 KL-157 同向):准备阶段对**本 run 名册里挂着**的
- * 同名工具放行(部署自己挂了一只叫 `Task` 的工具就不审计它),写口看不到将来哪一跑的名册 ⇒ 一律拒。
- * 受伤的是「部署自带与退役名同名的工具、又要在会话规则里点它」的形;出路 = 部署级工具策略(不经会话规则店)。
- * ⚠️ **过渡形**:core 已表态(#1156)把这两臂抽成一只导出纯函数并在会话规则店写口即拒 —— 到货后本函数
- * 换成调 core 那只(拒因原样透传),三份判定收成一份。**S-877 提货复核(core 7.35.0)**:#1156 **未随版**(发车帖 [ref] 逐字
- * 「照 #1156 未随本版」);同版新导出的 `rosterToolName` / `ruleNamesOf`(#1194)是**别名归一**(一个名字在名册上落到哪只行的线名 /
- * 一次调用可被规则拼成的名字集),不回答「这个名字会不会让准备阶段拒启」,不能替本函数 ⇒ 本函数照留,等 #1156。
- *
- * 🔴 **为什么不复用 `config.ts` 的 `findUnmatchableToolNames`**(本仓另一只按名字判的单点;读过实现后裁):两只回答的
- * 不是同一个问题。那一只问「部署名单里这条名字会不会**永远匹配不上**活工具」—— 它刻意豁免 `allow`(白名单匹配不上 =
- * fail-closed 且当场可见),并且拒两段 MCP 名 `mcp__srv`(一名两义)与 core 文法编不出的串。本函数问的是「引擎见到这条
- * 会话规则会不会**拒启**」:引擎准备阶段的名审计对 `allow` 桶照样抛(豁免它 = 放过一条砖化路径),对 `mcp__srv` 却
- * **不**抛(会话层自 core 5.55 / 5.56 起把它当整对端覆盖形真命中)。判据只能逐字跟 core 那两臂走,不能借另一只的口径。
- * 两只在「退役名」「无前缀 `__` 名」两臂上同源(都读 core 导出的同两件),#1156 到货的那一批一并换调 core 的导出函数。
+ * SQL 会话规则店写口的同一问(core 判官之后、收紧门之前,与 `assertSessionRuleNamesCurrent` 同点):够不着 ⇒ 抛,一条写语句都不发。
+ * 抛的是普通 `Error`(不是 `SessionPolicyError`:core 那张闭集里没有这个词,也不往里塞)—— 本服务的两条 HTTP 写口在读者那一层先拒,
+ * 走到这里 = 有一个绕过写口读者的写者,HTTP 上落 500(服务端自身的失误,响亮)。
  */
-export type LegacyToolName = {
-    why: "retired";
-    guidance: string;
-} | {
-    why: "unprefixed-namespace";
-};
-export declare function legacyToolNameOf(name: string): LegacyToolName | undefined;
+export declare function assertSessionRuleNamesReachable(rules: SessionPermissionRules): void;
 /** 一条规则体的**形**问题。判词而非文案(见文件头注的「文案属主」一段)。 */
 export type SessionPermissionRulesShapeProblem = 
 /** 整体不是一只普通对象(`null` / 数组 / 标量 / 缺席)。 */
@@ -91,14 +73,17 @@ export type SessionPermissionRulesShapeProblem =
     kind: "field-not-string-array";
     field: keyof SessionPermissionRules;
 };
-/** 一条**要写进店**的规则体的问题 = 形问题 ∪ S-800 的名字问题(判据 {@link legacyToolNameOf})。 */
+/** 一条**要写进店**的规则体的问题 = 形问题 ∪ S-800 的名字问题(判官 = core 的 `assertSessionRuleNamesCurrent`)。 */
 export type SessionPermissionRulesProblem = SessionPermissionRulesShapeProblem
-/** S-800:形对,但工具名桶里有一条写进去就跑不了的名字。 */
+/** S-800 / S-1047:形对,但工具名桶里有一条写进去就跑不了的名字;`refusal` = core 判官交回的 detail(原样上 wire)。 */
  | {
     kind: "legacy-tool-name";
-    field: ToolNameRuleField;
-    name: string;
-    legacy: LegacyToolName;
+    refusal: SessionRuleNameRefusal;
+}
+/** 形对、core 判官也放行,但工具名桶里有一条够不着任何挂载工具的协议名(缺段 / 对端段铸不出)。 */
+ | {
+    kind: "unreachable-tool-name";
+    unreachable: SessionRuleUnreachableName;
 };
 /** 两只读者的读数:有问题给判词,没问题给**已收窄**的规则体(调用方零 cast)。`P` = 这只读者会给的判词集。 */
 export type SessionPermissionRulesRead<P extends SessionPermissionRulesProblem = SessionPermissionRulesProblem> = {
@@ -123,9 +108,9 @@ export declare function readSessionPermissionRules(raw: unknown): SessionPermiss
  * **写口读者**(S-800)= 形读者 + 名字判官:两条写入腿(`PUT /v1/sessions/:id/policy`、sync/import 的 `policy`
  * 面经 {@link readSessionRulesRecords})往会话规则店写之前的**唯一**判据。两问,按序:
  *  ① 形(同 {@link readSessionPermissionRules};一份坏形的体答形的 400);
- *  ② 工具名桶里的每一条过 {@link legacyToolNameOf} —— 写进去之后属主撤不掉、会话之后每一跑都起不来的名字,
- *     写口是唯一来得及拒的地方。
- * 🔴 **只在写口,不在读回**:SQL 店读回同一行时只判形(形读者)。一条早先写进去的退役名行必须**读得出来** ——
+ *  ② 工具名桶里的每一条过 core 的判官({@link legacyToolNameRefusalOf})—— 写进去就让会话之后每一跑都起不来的名字,在写口拒;
+ *  ③ 工具名桶里的每一条过协议规则名判官({@link unreachableSessionRuleNameOf})—— 写进去永远匹配不到任何挂载工具的协议名,在写口拒。
+ * 🔴 **只在写口,不在读回**:SQL 店读回同一行时只判形(形读者)。一条早先写进去的退役名行(或够不着的协议名行)必须**读得出来** ——
  * 那是运营方清掉它的唯一路径(operator 的 PUT 先读写前快照),也是 core 准备阶段报 `config.legacy_tool_name`
  * 而不是一只 500 `corrupt` 的前提。把判官放进形读者会让读回把它判坏(7.105.0 车QQ 双库套件实抓,修在同批)。
  */
@@ -178,10 +163,7 @@ export declare function describeSessionPermissionRulesProblem(p: SessionPermissi
  * 调用点据此发 `rules.legacy_tool_name`,否则发形的码。闭集穷尽两层:记录级判词或桶级判词加一种 ⇒ 编译红,
  * 新判词不会静默落进某一个码。
  */
-export declare function legacyToolNameProblemOf(p: SessionRulesRecordProblem): {
-    field: ToolNameRuleField;
-    name: string;
-} | undefined;
+export declare function legacyToolNameProblemOf(p: SessionRulesRecordProblem): SessionRuleNameRefusal | undefined;
 /** `policy[]` 判词 → 人话(sync/import 腿在它前面拼 `policy: `)。闭集穷尽同上。 */
 export declare function describeSessionRulesRecordProblem(p: SessionRulesRecordProblem): string;
 /**
@@ -211,5 +193,4 @@ export declare function sessionPolicyErrorHttp(code: SessionPolicyError["code"])
     status: number;
     errorCode: string;
 };
-export {};
 //# sourceMappingURL=session-policy-wire.d.ts.map

package/dist/session-policy-wire.js

@@ -1,21 +1,41 @@
-import { PROTOCOL_TABLE, RETIRED_TOOL_NAMES, protocolOf } from "@sema-agent/core";
-const RULE_FIELD_ROLE = {
-    toolAllow: "tool-name",
-    toolDeny: "tool-name",
-    allowDirs: "path",
-    commandAllow: "command",
-    commandDeny: "command",
+import { PROTOCOL_TABLE, SessionPolicyError, assertSessionRuleNamesCurrent, judgeRuleToolName } from "@sema-agent/core";
+import { describeUnreachableNamespacedRuleName, unreachableNamespacedRuleNameOf } from "./namespaced-rule-name.js";
+const RULE_FIELDS = {
+    toolAllow: true,
+    toolDeny: true,
+    allowDirs: true,
+    commandAllow: true,
+    commandDeny: true,
 };
-export const SESSION_PERMISSION_RULE_FIELDS = Object.keys(RULE_FIELD_ROLE);
-const TOOL_NAME_RULE_FIELDS = SESSION_PERMISSION_RULE_FIELDS.filter((f) => RULE_FIELD_ROLE[f] === "tool-name");
-export function legacyToolNameOf(name) {
-    const guidance = RETIRED_TOOL_NAMES.get(name);
-    if (guidance !== undefined)
-        return { why: "retired", guidance };
-    if (name.includes("__") && protocolOf(name) === undefined)
-        return { why: "unprefixed-namespace" };
+export const SESSION_PERMISSION_RULE_FIELDS = Object.keys(RULE_FIELDS);
+function legacyToolNameRefusalOf(rules) {
+    try {
+        assertSessionRuleNamesCurrent(rules);
+        return undefined;
+    }
+    catch (e) {
+        if (e instanceof SessionPolicyError && e.code === "legacy_tool_name" && e.detail !== undefined)
+            return e.detail;
+        throw e;
+    }
+}
+const TOOL_NAME_FIELD_TABLE = { toolAllow: "toolAllow", toolDeny: "toolDeny" };
+const TOOL_NAME_FIELDS = Object.values(TOOL_NAME_FIELD_TABLE);
+export function unreachableSessionRuleNameOf(rules) {
+    for (const field of TOOL_NAME_FIELDS) {
+        for (const name of rules[field] ?? []) {
+            const verdict = unreachableNamespacedRuleNameOf(name);
+            if (verdict !== undefined)
+                return { field, name, verdict };
+        }
+    }
     return undefined;
 }
+export function assertSessionRuleNamesReachable(rules) {
+    const unreachable = unreachableSessionRuleNameOf(rules);
+    if (unreachable !== undefined)
+        throw new Error(describeUnreachableSessionRuleName(unreachable));
+}
 function protocolToolNameShapes() {
     return PROTOCOL_TABLE.map((ns) => `${ns.prefix}<peer>__<tool>`).join(" or ");
 }
@@ -38,13 +58,12 @@ export function readWritableSessionPermissionRules(raw) {
     const read = readSessionPermissionRules(raw);
     if (read.problem !== undefined)
         return read;
-    for (const field of TOOL_NAME_RULE_FIELDS) {
-        for (const name of read.rules[field] ?? []) {
-            const legacy = legacyToolNameOf(name);
-            if (legacy !== undefined)
-                return { problem: { kind: "legacy-tool-name", field, name, legacy } };
-        }
-    }
+    const refusal = legacyToolNameRefusalOf(read.rules);
+    if (refusal !== undefined)
+        return { problem: { kind: "legacy-tool-name", refusal } };
+    const unreachable = unreachableSessionRuleNameOf(read.rules);
+    if (unreachable !== undefined)
+        return { problem: { kind: "unreachable-tool-name", unreachable } };
     return read;
 }
 export function readSessionRulesRecords(raw) {
@@ -71,22 +90,29 @@ 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`;
-        case "legacy-tool-name": return describeLegacyToolName(p.field, p.name, p.legacy);
+        case "legacy-tool-name": return describeLegacyToolName(p.refusal);
+        case "unreachable-tool-name": return describeUnreachableSessionRuleName(p.unreachable);
         default: {
             const unhandled = p;
             throw new Error(`unhandled SessionPermissionRules problem: ${JSON.stringify(unhandled)}`);
         }
     }
 }
-function describeLegacyToolName(field, name, legacy) {
-    switch (legacy.why) {
-        case "retired":
-            return `${field} names "${name}", a retired tool name (${legacy.guidance}); with that rule in place this session could not start another run, so nothing was written — use the current tool name`;
-        case "unprefixed-namespace":
-            return `${field} names "${name}", which contains "__" but no protocol prefix; with that rule in place this session could not start another run, so nothing was written — a protocol tool is named ${protocolToolNameShapes()}`;
+function describeUnreachableSessionRuleName(u) {
+    return `${u.field} names "${u.name}", which can never match a tool (${describeUnreachableNamespacedRuleName(u.verdict)}), so nothing was written`;
+}
+function describeLegacyToolName(r) {
+    switch (r.verdict) {
+        case "retired": {
+            const v = judgeRuleToolName(r.name, new Set());
+            const guidance = v.kind === "retired" ? v.guidance : `renamed "${r.currentName ?? "?"}"`;
+            return `${r.field} names "${r.name}", a retired tool name (${guidance}); with that rule in place this session could not start another run, so nothing was written — use the current tool name${r.currentName !== undefined ? ` ("${r.currentName}")` : ""}`;
+        }
+        case "unprefixed_namespace":
+            return `${r.field} names "${r.name}", which contains "__" but no protocol prefix; with that rule in place this session could not start another run, so nothing was written — a protocol tool is named ${protocolToolNameShapes()}`;
         default: {
-            const unhandled = legacy;
-            throw new Error(`unhandled legacy tool name arm: ${JSON.stringify(unhandled)}`);
+            const unhandled = r.verdict;
+            throw new Error(`unhandled legacy tool name verdict: ${JSON.stringify(unhandled)}`);
         }
     }
 }
@@ -100,9 +126,10 @@ export function legacyToolNameProblemOf(p) {
             switch (p.problem.kind) {
                 case "not-an-object":
                 case "field-not-string-array":
+                case "unreachable-tool-name":
                     return undefined;
                 case "legacy-tool-name":
-                    return { field: p.problem.field, name: p.problem.name };
+                    return p.problem.refusal;
                 default: {
                     const unhandled = p.problem;
                     throw new Error(`unhandled SessionPermissionRules problem: ${JSON.stringify(unhandled)}`);
@@ -131,6 +158,7 @@ export function sessionPolicyErrorHttp(code) {
         case "conflict": return { status: 409, errorCode: "conflict" };
         case "loosen_forbidden": return { status: 403, errorCode: "loosen_forbidden" };
         case "corrupt": return { status: 500, errorCode: "corrupt" };
+        case "legacy_tool_name": return { status: 400, errorCode: "rules.legacy_tool_name" };
         default: {
             const unhandled = code;
             throw new Error(`unhandled SessionPolicyError code: ${JSON.stringify(unhandled)}`);