@sema-agent/server 7.132.0 → 7.133.0

package/dist/http/approval-sweeps.js

@@ -1,4 +1,5 @@
 import { redactHead } from "../observability/run-terminal.js";
+const errText = (e) => redactHead(e instanceof Error ? e.message : String(e), 2000);
 import { findParkOrigin } from "../parked-decide.js";
 import { decodeCheckpointScope } from "../security.js";
 import { hostDecisionFacts } from "../host-decision.js";
@@ -8,7 +9,9 @@ import { gatedPrincipal, hasServiceAuth } from "./principal-gate.js";
 import { costQuotaRefusalOf } from "./request-guards.js";
 import { admissionRefusalOf, readinessOf } from "./readiness.js";
 import { readResumeCtx } from "./resume-ctx-read.js";
+import { isResumeBlockedByPolicy } from "./checkpoint-ctx.js";
 import { storedBodyReplayRefusal } from "./stored-body-replay.js";
+import { refusalBody } from "./refusal-body.js";
 const BLOCKED_SCALAR_KEYS = ["errorCode", "blockedBy", "field", "reason", "count", "cap", "index"];
 function blockedScalars(body) {
     const out = {};
@@ -70,7 +73,7 @@ export function createApprovalSweeps(ctx) {
         catch (e) {
             deps.metrics?.inc("deny_sweep_list_failed_total");
             deps.logger?.warn?.("deny_sweep_list_failed", {
-                err: redactHead(e instanceof Error ? e.message : String(e), 2000),
+                err: errText(e),
                 note: "the SLA deny-sweep could not read the expired approvals this tick, so nothing was denied and nothing was skipped; the rows stay suspended and are read again next tick (the terminal backstop still reaps them)",
             });
             return;
@@ -80,21 +83,24 @@ export function createApprovalSweeps(ctx) {
             let token;
             try {
                 token = (await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS })) ?? undefined;
-                if (!parkSources || !token)
-                    return { token, parked: false };
+                if (!token)
+                    return { token, parked: false, rev: undefined };
                 const cp = await cs.get(token);
                 if (!cp)
-                    return { token, parked: false };
+                    return { token, parked: false, rev: undefined };
+                const rev = cp.rev ?? 0;
+                if (!parkSources)
+                    return { token, parked: false, rev };
                 const origin = await findParkOrigin({
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
                     ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
                         ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
                         : {}),
                 }, { token, scope: cp.scope, sessionId: cp.sessionId });
-                return { token, parked: origin !== undefined };
+                return { token, parked: origin !== undefined, rev };
             }
             catch {
-                return { token, parked: false };
+                return { token, parked: false, rev: undefined };
             }
         };
         const storedBodyUnservable = async (sessionId) => {
@@ -105,11 +111,32 @@ export function createApprovalSweeps(ctx) {
                 return undefined;
             return storedBodyReplayRefusal(read.ctx, deps.config);
         };
+        const expirePolicyBlockedCard = async (cardToken, observedRev, sessionId, body) => {
+            let won;
+            try {
+                const cp = await cs.get(cardToken);
+                if (!cp)
+                    return;
+                if (cp.status !== "pending" || (cp.rev ?? 0) !== observedRev) {
+                    deps.logger?.warn?.("deny_sweep_policy_blocked_expire_skipped", { sessionId, skipReason: cp.status !== "pending" ? "not_pending" : "card_changed", ...blockedScalars(body) });
+                    return;
+                }
+                won = await cs.expire(cardToken, cp.scope);
+            }
+            catch (e) {
+                deps.logger?.warn?.("deny_sweep_policy_blocked_expire_failed", { sessionId, err: errText(e) });
+                return;
+            }
+            blockedWarned.delete(cardToken);
+            if (won)
+                deps.metrics?.inc("deny_sweep_policy_blocked_expired_total");
+            deps.logger?.warn?.("deny_sweep_policy_blocked_expired", { sessionId, won, ...blockedScalars(body) });
+        };
         let parkedSkipped = 0;
         const replaySkipped = [];
         const seenCards = new Set();
         for (const { sessionId } of expired) {
-            const { token: cardToken, parked } = await cardOf(sessionId);
+            const { token: cardToken, parked, rev: cardRev } = await cardOf(sessionId);
             if (cardToken !== undefined)
                 seenCards.add(cardToken);
             if (parked) {
@@ -121,12 +148,22 @@ export function createApprovalSweeps(ctx) {
                 replaySkipped.push({ sessionId, kind: unservable.kind });
                 continue;
             }
-            await resumeCheckpoint(sessionId, "deny", "approval SLA expired — auto-denied", { decidedBy: "sla_timeout" }).then((r) => {
-                if (r.status >= 400)
-                    noteResumeBlocked(cardToken, sessionId, r.status, r.body);
-                else if (cardToken !== undefined)
+            let out;
+            try {
+                out = await resumeCheckpoint(sessionId, "deny", "approval SLA expired — auto-denied", { decidedBy: "sla_timeout" });
+            }
+            catch (e) {
+                deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: errText(e) });
+                continue;
+            }
+            if (out.status < 400) {
+                if (cardToken !== undefined)
                     blockedWarned.delete(cardToken);
-            }, (e) => deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: redactHead(e instanceof Error ? e.message : String(e), 2000) }));
+                continue;
+            }
+            noteResumeBlocked(cardToken, sessionId, out.status, out.body);
+            if (isResumeBlockedByPolicy(out) && cardToken !== undefined && cardRev !== undefined)
+                await expirePolicyBlockedCard(cardToken, cardRev, sessionId, out.body);
         }
         for (const token of [...blockedWarned.keys()])
             if (!seenCards.has(token))
@@ -144,10 +181,10 @@ export function createApprovalSweeps(ctx) {
     async function redeemParkedAsk(req) {
         const cs = deps.checkpointStore;
         if (!cs) {
-            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
         if (!hasServiceAuth(deps.config) && !deps.config.allowUnauthedWrites) {
-            return { status: 503, body: { error: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions", errorCode: "auth.service_token_required" } };
+            return { status: 503, body: refusalBody({ errorCode: "auth.service_token_required", message: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions" }) };
         }
         const refusal = admissionRefusalOf(readinessOf(deps), deps.servingLease?.(), "hitl-answer");
         if (refusal !== undefined)
@@ -169,17 +206,17 @@ export function createApprovalSweeps(ctx) {
         catch (e) {
             if (!(await mayDiscloseRowError(cs, req.gateToken, { principal: req.principal, explicitOperator: false }))) {
                 deps.logger?.warn?.("parked_late_decision_unreadable_row_withheld", { askId: req.askId });
-                return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+                return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
             }
-            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
         }
         if (!cp) {
-            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
         const cpPrincipal = decodeCheckpointScope(cp.scope);
         if (cpPrincipal !== undefined && cpPrincipal !== req.principal) {
             deps.logger?.warn?.("parked_late_decision_scope_mismatch", { askId: req.askId });
-            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
         const binding = {
             checkpointToken: req.gateToken,

package/dist/http/caller-trust.d.ts

@@ -0,0 +1,77 @@
+/**
+ * **调用方信任档** —— 一份请求里「不经人答就生效」的规则表按谁的档准入:全仓唯一一张表({@link callerTrust})、唯一一只准入判({@link requestTrustRefusal})。
+ *
+ * ## 律
+ * 契约(settings-schema `SAFETY_MERGE_SPEC.permissions` 的成员阶梯)按**层的信任档**准入每个成员:`allow` 放宽免问面(`loosen`),要 `global`;`deny` / `ask` 只收紧,
+ * 文件层最低档 `local` 就收。wire 上没有层 —— 提交体是合并后的扁平结果,层只在合并端(cli 本地)存在;自报一个层 / 作者位不可验(引擎侧已拒立这种位)。所以本服务
+ * 的「层」= **这次请求验过的凭据**:档只由部署形 + 身份来源 + 登录令牌的 scope 角色推,调用方说什么都不改档。
+ *
+ *  · 单用户 turnkey(`requirePrincipal !== true`,本仓 posture 判别式同一只)⇒ `global`:一台机一位超管;
+ *  · 多租 · 部署的 service 凭据 ⇒ `global`:部署自己的凭据是运维档(契约给「启动方自己的行为」—— `SETTINGS_SOURCE_CONTRACT.flagSettings` —— 的档),持它的前端为自己转发的内容负责;
+ *    出示的 Bearer 就是 service 凭据时,哪怕它同时也被鉴权桥验成登录令牌,也按 service 凭据读(与凭据门派 `source` 同序:`dispatch.ts` 先认 service 凭据);
+ *  · 多租 · 中心登录令牌,scope 角色 ≥ 契约 `domainWriteRole("governance")` ⇒ `global`:能写 scope 治理域(autonomy / commandPolicy / approvalRequire,全组织的免问面)
+ *    的角色,放宽自己这一 run 是它的子集;门槛读契约,不手抄角色词;
+ *  · 多租 · 其余(登录令牌角色低于它 / 不带 / 认不出;直连门 principal 令牌只证身份不证角色;没有验过的凭据)⇒ `project`:契约给非运维档作者的仓控来源的档,
+ *    收紧成员照收、放宽成员不收 —— 没有可验的角色就落到这里(fail-closed)。
+ *
+ * **判的是哪些表**:请求体上不经人答就生效的规则表 —— `settings.permissions` 的每个成员桶(逐 `membersOf("permissions")`),以及请求**按名点用**(`userInvokedSkills`)的
+ * 自带技能的两只清单(引擎 `seedSkillGrants`:人点的名就是表态,不出 `Skill` 卡 ⇒ `allowedTools` 是 `allow` 成员的孪生、`disallowedTools` 是 `deny` 的孪生,键 → 成员一张表
+ * {@link SKILL_LIST_MEMBER})。没点用的自带技能不判:它的清单要经 `Skill` 卡上的人点头才生效 —— 那正是契约给低于门槛的放宽指定的同意出口。
+ * 准入只经契约导出:桶非空且 `!isAtLeast(档, memberAdmission(…).minTrust)` ⇒ 不准入;不按方向开特例(契约的层准入同样先判 floor)。
+ * 不准入 ⇒ 受理口 400,体与条目问题同形(`entry-problems.ts`:`field` + `detail.problems` + `total`),原因词 = 契约 `LAYER_ADMISSION_VERDICTS` 的 `below_trust_floor`,
+ * 另带 `detail.callerTrust`(这次请求的档)。响亮拒而不是静默丢:契约要求低于门槛的放宽不得静默吞,出路是同意(答卡)或运维的 allow 表。
+ *
+ * 读者(都读同一次求值,不各算一份):提交受理口(`admission.ts` `prepareSpec`,三提交面共用)与能力位 `settings.permissions.callerTrust`(`routes/capabilities.ts`)。
+ * 续跑腿不读本档:存储体在自己的受理口按当时的档准入过。
+ */
+import type { IncomingMessage } from "node:http";
+import { type MinTrust, type SafetyMergeMember, type UserRole } from "@sema-agent/settings-schema";
+import type { SkillSpec } from "@sema-agent/core";
+import type { ServiceConfig } from "../config-types.js";
+import { type EntryProblem } from "../entry-problems.js";
+import type { ParsedTaskSettings } from "../task-settings.js";
+/**
+ * 档是**怎么**推出来的(闭集;拒句按它说出路)。加一个词 ⇒ {@link basisClause} 的穷举 switch 编译红。
+ *  · `single_user` —— 单用户 turnkey;
+ *  · `service_credential` —— 多租 · 部署的 service 凭据;
+ *  · `sign_in_role` —— 多租 · 登录令牌带契约阶梯里的角色(够不够档看 `trust`);
+ *  · `sign_in_role_unrecognized` —— 多租 · 登录令牌不带角色,或角色不在契约阶梯里;
+ *  · `identity_without_role` —— 多租 · 直连门 principal 令牌(只证身份);
+ *  · `unverified` —— 多租 · 没有验过的凭据。
+ */
+export type CallerTrustBasis = "single_user" | "service_credential" | "sign_in_role" | "sign_in_role_unrecognized" | "identity_without_role" | "unverified";
+/** 一次求值的读数。`role` 只在 `basis === "sign_in_role"` 时在场(契约阶梯里的词)。 */
+export interface CallerTrust {
+    readonly trust: MinTrust;
+    readonly basis: CallerTrustBasis;
+    readonly role?: UserRole;
+}
+/** 档表(唯一一张)。规则全文见文件头。 */
+export declare function callerTrust(req: IncomingMessage, config: ServiceConfig): CallerTrust;
+/** 请求 `settings.permissions` 的成员桶 —— 按**契约的成员型**取:契约加成员而本仓的请求桶没有它 ⇒ 这里编译红(本仓必须先决定那只桶怎么上 wire)。 */
+type RequestPermissionMembers = Pick<NonNullable<ParsedTaskSettings["permissions"]>, SafetyMergeMember<"permissions">>;
+/** 准入判的输入:解析后的请求桶(`parseTaskSettings` 的读数 = `applyTaskSettings` 投进引擎的那一份)+ 请求自带技能 + 按名点用的技能名(两者受理门已判过形)。 */
+export interface RequestRuleTables {
+    readonly permissions: RequestPermissionMembers | undefined;
+    readonly skills: readonly Pick<SkillSpec, "name" | "allowedTools" | "disallowedTools">[] | undefined;
+    readonly userInvokedSkills: readonly string[] | undefined;
+}
+/** 受理口拒体:句子 + 机读位(原样进 `sendError` 的 facts)。 */
+export interface RequestTrustRefusal {
+    readonly message: string;
+    readonly facts: {
+        readonly field: string;
+        readonly detail: {
+            readonly problems: readonly EntryProblem[];
+            readonly total: number;
+            readonly callerTrust: MinTrust;
+        };
+    };
+}
+/**
+ * 请求里不经人答就生效的规则表的成员级准入(唯一一只判)。全部准入 ⇒ `undefined`;否则句子说扫描序里**第一张**不准入的表(坐标、档、floor、出路),
+ * 机读位把这一遍判下来的**全部**条目一次列全。空表什么也不改,不算。
+ */
+export declare function requestTrustRefusal(tables: RequestRuleTables, reading: CallerTrust): RequestTrustRefusal | undefined;
+export {};
+//# sourceMappingURL=caller-trust.d.ts.map

package/dist/http/caller-trust.js

@@ -0,0 +1,143 @@
+import { domainWriteRole, isAtLeast, isRole, memberAdmission, membersOf, roleAtLeast, USER_ROLES, } from "@sema-agent/settings-schema";
+import { entryProblem, entryProblemsFacts } from "../entry-problems.js";
+import { ssoVerifiedRole } from "../security.js";
+import { systemFor, verifiedIdentitySource } from "./principal-gate.js";
+export function callerTrust(req, config) {
+    if (config.requirePrincipal !== true)
+        return { trust: "global", basis: "single_user" };
+    const source = verifiedIdentitySource(req, config);
+    switch (source) {
+        case "service_token":
+            return { trust: "global", basis: "service_credential" };
+        case "sso": {
+            if (systemFor(req, config) !== undefined)
+                return { trust: "global", basis: "service_credential" };
+            const role = ssoVerifiedRole(req);
+            if (role === undefined || !isRole(role))
+                return { trust: "project", basis: "sign_in_role_unrecognized" };
+            return { trust: roleAtLeast(role, domainWriteRole("governance")) ? "global" : "project", basis: "sign_in_role", role };
+        }
+        case "direct_door_jwt":
+            return { trust: "project", basis: "identity_without_role" };
+        case undefined:
+            return { trust: "project", basis: "unverified" };
+        default: {
+            const unknownSource = source;
+            throw new Error(`callerTrust: identity source ${String(unknownSource)} has no trust row`);
+        }
+    }
+}
+const TRUST_REFUSAL_CODE = "request.field_invalid";
+const BELOW_TRUST_FLOOR = "below_trust_floor";
+const SKILL_LIST_MEMBER = { allowedTools: "allow", disallowedTools: "deny" };
+function effectiveRuleTables(t) {
+    const out = [];
+    if (t.permissions !== undefined) {
+        for (const member of membersOf("permissions")) {
+            const entries = t.permissions[member];
+            if (entries !== undefined)
+                out.push({ member, field: `settings.permissions.${member}`, entries, source: "settings" });
+        }
+    }
+    if (t.skills !== undefined && t.userInvokedSkills !== undefined) {
+        const named = new Set();
+        for (const name of t.userInvokedSkills) {
+            if (named.has(name))
+                continue;
+            named.add(name);
+            const at = t.skills.findIndex((skill) => skill.name === name);
+            const skill = t.skills[at];
+            if (skill === undefined)
+                continue;
+            for (const key of ["allowedTools", "disallowedTools"]) {
+                const entries = skill[key];
+                if (entries !== undefined)
+                    out.push({ member: SKILL_LIST_MEMBER[key], field: `skills[${at}].${key}`, entries, source: "invoked_skill" });
+            }
+        }
+    }
+    return out;
+}
+export function requestTrustRefusal(tables, reading) {
+    const problems = [];
+    let first;
+    for (const table of effectiveRuleTables(tables)) {
+        if (table.entries.length === 0)
+            continue;
+        const admission = memberAdmission("permissions", table.member);
+        if (isAtLeast(reading.trust, admission.minTrust))
+            continue;
+        first ??= { table, minTrust: admission.minTrust, loosens: directionLoosens(admission.direction) };
+        for (const entry of table.entries)
+            problems.push(entryProblem(TRUST_REFUSAL_CODE, table.field, entry, BELOW_TRUST_FLOOR));
+    }
+    if (first === undefined)
+        return undefined;
+    const facts = entryProblemsFacts(problems);
+    return {
+        message: `${first.table.field} needs trust "${first.minTrust}" (${whatItDoes(first.table.source, first.loosens)}) and this request is admitted at "${reading.trust}": ${basisClause(reading)}. Below that trust these rules are not applied — ${outletOf(first.table.source, first.loosens)}.`,
+        facts: { field: facts.field, detail: { ...facts.detail, callerTrust: reading.trust } },
+    };
+}
+function whatItDoes(source, loosens) {
+    const effect = loosens ? "lets matching calls run without a person being asked" : "changes which calls are asked or refused";
+    switch (source) {
+        case "settings":
+            return `it ${effect}`;
+        case "invoked_skill":
+            return `the request invokes this skill by name, so the list applies with no approval card and ${effect}`;
+        default: {
+            const unknownSource = source;
+            throw new Error(`requestTrustRefusal: rule table source ${String(unknownSource)} unknown`);
+        }
+    }
+}
+function outletOf(source, loosens) {
+    if (!loosens)
+        return "remove them, or ask the operator to set them deployment-wide";
+    switch (source) {
+        case "settings":
+            return "remove them and answer the approval questions as they come, or ask the operator to put them in APPROVAL_GRANT";
+        case "invoked_skill":
+            return "drop the skill from userInvokedSkills (the model can still activate it behind its approval card), remove the list, or ask the operator to put the rules in APPROVAL_GRANT";
+        default: {
+            const unknownSource = source;
+            throw new Error(`requestTrustRefusal: rule table source ${String(unknownSource)} unknown`);
+        }
+    }
+}
+function directionLoosens(direction) {
+    switch (direction) {
+        case "loosen":
+            return true;
+        case "tighten":
+            return false;
+        default: {
+            const unknownDirection = direction;
+            throw new Error(`requestTrustRefusal: member direction ${String(unknownDirection)} unknown`);
+        }
+    }
+}
+function basisClause(reading) {
+    const governanceRole = domainWriteRole("governance");
+    const reach = `the deployment's service credential, or a registry sign-in token whose role in its active scope is "${governanceRole}" or higher (the role that may write the scope's governance), is admitted at "global"`;
+    switch (reading.basis) {
+        case "single_user":
+            return `this single-user deployment admits every caller at "global"`;
+        case "service_credential":
+            return `the deployment's service credential is admitted at "global"`;
+        case "sign_in_role":
+            return `the registry sign-in token's role in its active scope is "${reading.role ?? ""}" — ${reach}; a scope admin can raise the role`;
+        case "sign_in_role_unrecognized":
+            return `the registry sign-in token carries no role this deployment recognizes (${USER_ROLES.join(" < ")}) — ${reach}`;
+        case "identity_without_role":
+            return `a direct-door principal token proves who the caller is, not a role — ${reach}`;
+        case "unverified":
+            return `the request carries no credential this deployment verifies — ${reach}`;
+        default: {
+            const unknownBasis = reading.basis;
+            throw new Error(`requestTrustRefusal: trust basis ${String(unknownBasis)} unknown`);
+        }
+    }
+}
+//# sourceMappingURL=caller-trust.js.map

package/dist/http/checkpoint-ctx.d.ts

@@ -101,15 +101,9 @@ export declare function permissionModeReadingStated(ctx: CheckpointCtx): boolean
 /**
  * 第三问的拒答复 —— 码与落点同 allow 记号那一问(`checkpoint.unsupported_version`,409;卡仍 pending 时体上的 `retriable:true` 由 {@link resumeRefusalWithCard} 追加,本铸点不带)。
  * 句子说原因(更早的版本在每次续跑重钳运维的 AUTONOMY、没把它记进任务;本版只在提交时记一次 ⇒ 续跑会按任务提交时的原词跑)与两条出路。
- * 🔴 形是给冻结门看的:`status: <三位数>, body: { error: "<整句双引号字面>", errorCode: "<码>"`,中间只许有空白。
+ * 🔴 形是给冻结门看的:`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
  */
-export declare function permissionModeReadingRefusal(): {
-    status: number;
-    body: {
-        error: string;
-        errorCode: string;
-    };
-};
+export declare function permissionModeReadingRefusal(): ResumeRefusalAnswer;
 /**
  * 本行能否被按当前读法重放:体里 `allow` 在生效而行上的记号不是当前这一个词 ⇒ **不能**(`true` = 拒)。
  * 记号缺席、是旧词(`"statement"`)或认不得(手改 / 将来的写者)⇒ 同样拒:只有当前这个词是「按当前读法写下」的证据。
@@ -122,15 +116,9 @@ export declare function allowListReadingEraOf(ctx: CheckpointCtx): AllowListRead
  * 拒在认领之前,所以没有 `taskId`(行没抢到就不造键)。句子按这一行是哪一代写的分两句(闭集穷举,加一代 ⇒ 编译红):说原因(这条任务停在哪种读法上、
  * 照当前读法续跑会放宽什么)与出路(作为新任务重提,仍停驻的先取消)。
  *
- * 🔴 形是给冻结门看的(`api-error-text-freeze` 的 resume 家族收集器):`status: <三位数>, body: { error: "<整句双引号字面>", errorCode: "<码>"`,中间只许有空白。
+ * 🔴 形是给冻结门看的(`api-error-text-freeze` 的 resume 家族收集器):`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
  */
-export declare function allowListReadingRefusal(era: AllowListReadingEra): {
-    status: number;
-    body: {
-        error: string;
-        errorCode: string;
-    };
-};
+export declare function allowListReadingRefusal(era: AllowListReadingEra): ResumeRefusalAnswer;
 /**
  * 一条停驻行的持久化体在本版上**不能**重放时,是哪一条规则拒的(闭集;加一条 ⇒ {@link storedBodyReplayAnswer} 的 switch 编译红)。
  * 答 `checkpoint.unsupported_version` 的两臂随带这一行的写者版本(续跑上下文的 `writerVersion`,缺席 = 本版之前写下的行)—— 那一码的两版本键由它铸({@link buildCheckpointVersionKeys})。
@@ -172,11 +160,23 @@ export interface ResumeRefusalAnswer {
  * `blockedBy` = 内层的码,句子 = 前缀 + 内层的句子,内层的机读事实原样随体。{@link storedBodyReplayAnswer} 的工具名清单那一臂与
  * `resume-legs.ts` 的折叠口都调它 —— 句子与码只在这里写一次(冻结门 `api-error-text-freeze` 的模板骨架表锚这一处)。
  *
+ * 🔴 **句尾点名出口**:这一拒不消费卡(卡仍 pending、run 行留停驻),被挡在一张 deny 不掉的卡前面的调用方需要知道怎么收场 ——
+ * `POST /v1/runs/:id/cancel` 对停驻的 run 直接结算(CAS 过期该卡再终局 run 行,不跑模型轮)。句子写「若仍停驻」而不是随卡有无换话:有卡 / 无卡(终态 run 的 steer 在铸唤醒卡之前拒)
+ * 两种处境除 `retriable` 外逐字同体(同判同答),与另两类存量体拒(allow 读法 / 模式词读法)句子里的出口是同一个端点、同一种写法。
+ *
  * 本铸点**不带** `retriable`:那是调用点的事实(有没有一张待批卡仍在等),由 {@link resumeRefusalWithCard} 一处追加 —— 续跑入口(卡仍 pending、run 行留 `suspended`)
  * 带 `retriable:true`,终态 run 的 steer 在铸唤醒卡之前拒(没有卡)不带。键集 = `errorCode` · `error` · `blockedBy` · (`field` · `reason` · 其余 `extra`,有才在)
  * · (`retriable`,卡在才在)。
  */
 export declare function resumeBlockedByPolicyAnswer(inner: Refusal): ResumeRefusalAnswer;
+/**
+ * 一次续跑的答复是不是 {@link resumeBlockedByPolicyAnswer} 铸的那一只(409 `resume_blocked_by_policy`)—— SLA 拒扫腿据此区分「同一份字节在本版永远被拒」与别的 ≥400
+ * (后者可能是瞬时的,照旧逐拍重试)。码的写端与读端住在同一个模块,读端不在别处第二次手拼这个字面。
+ */
+export declare function isResumeBlockedByPolicy(answer: {
+    readonly status: number;
+    readonly body: unknown;
+}): boolean;
 /**
  * 🔴 **三类续跑拒体上 `retriable` 的唯一写点**(本服务重放存量体前的拒、准入策略折叠、引擎拒的续跑):卡仍 pending(`cardPending`)⇒ 体尾追加 `retriable: true`;
  * 否则体原样(键缺席)。这三类拒上规则一条:`retriable` 在场 ⇔ 有一张待批卡仍在等、run 行留 `suspended`(**不是**「原样重试会成功」—— 契约附录 A.1 注那一个意思)。

package/dist/http/checkpoint-ctx.js

@@ -32,10 +32,10 @@ export function permissionModeReadingStated(ctx) {
 export function permissionModeReadingRefusal() {
     return {
         status: 409,
-        body: {
-            error: "this task was suspended by an earlier server version that re-applied this deployment's AUTONOMY on every resume instead of recording it in the task; this version records the operator's plan floor once, when a task is submitted, so continuing would run this task under the permission mode it was submitted with rather than the one it ran under. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel); to let it finish with read-only hands instead, set AUTONOMY=read-only until it does.",
+        body: refusalBody({
             errorCode: "checkpoint.unsupported_version",
-        },
+            message: "this task was suspended by an earlier server version that re-applied this deployment's AUTONOMY on every resume instead of recording it in the task; this version records the operator's plan floor once, when a task is submitted, so continuing would run this task under the permission mode it was submitted with rather than the one it ran under. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel); to let it finish with read-only hands instead, set AUTONOMY=read-only until it does.",
+        }),
     };
 }
 export function allowListReadingUnstated(ctx) {
@@ -53,18 +53,18 @@ export function allowListReadingRefusal(era) {
         case "list":
             return {
                 status: 409,
-                body: {
-                    error: "this task was suspended by an earlier server version that did not record how it read settings.permissions.allow (7.114.0 and earlier read it as a whitelist: every tool not on the list was refused); this version hands that list to the engine's allow layer, where each entry is a standing yes for the calls it covers, so continuing would give the task more tools than it was submitted with. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel). To allow only certain tools, use the session rules' toolAllow (PUT /v1/sessions/:id/policy) or the request's excludeTools.",
+                body: refusalBody({
                     errorCode: "checkpoint.unsupported_version",
-                },
+                    message: "this task was suspended by an earlier server version that did not record how it read settings.permissions.allow (7.114.0 and earlier read it as a whitelist: every tool not on the list was refused); this version hands that list to the engine's allow layer, where each entry is a standing yes for the calls it covers, so continuing would give the task more tools than it was submitted with. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel). To allow only certain tools, use the session rules' toolAllow (PUT /v1/sessions/:id/policy) or the request's excludeTools.",
+                }),
             };
         case "statement":
             return {
                 status: 409,
-                body: {
-                    error: "this task was suspended by an earlier server version (7.115.0 to 7.116.x) that read settings.permissions.allow as a statement that the named tools are allowed, which answered only the question nobody else had answered and never cleared an ordinary question such as a file write or a shell command; this version hands that list to the engine's allow layer, where an entry also clears those ordinary questions, so continuing would run calls without asking that the task was submitted to ask about. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel).",
+                body: refusalBody({
                     errorCode: "checkpoint.unsupported_version",
-                },
+                    message: "this task was suspended by an earlier server version (7.115.0 to 7.116.x) that read settings.permissions.allow as a statement that the named tools are allowed, which answered only the question nobody else had answered and never cleared an ordinary question such as a file write or a shell command; this version hands that list to the engine's allow layer, where an entry also clears those ordinary questions, so continuing would run calls without asking that the task was submitted to ask about. Nothing was decided and nothing was resumed, and retrying will be refused the same way: submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel).",
+                }),
             };
         default: {
             const unhandled = era;
@@ -78,9 +78,12 @@ export function buildCheckpointVersionKeys(writerVersion, readerVersion) {
 export function resumeBlockedByPolicyAnswer(inner) {
     return {
         status: 409,
-        body: refusalBody({ errorCode: "resume_blocked_by_policy", message: `resume blocked by an admission policy change: ${inner.message}`, facts: { blockedBy: inner.errorCode, ...inner.facts } }),
+        body: refusalBody({ errorCode: "resume_blocked_by_policy", message: `resume blocked by an admission policy change: ${inner.message} — nothing was resumed; if the task is still suspended on its approval, cancel it (POST /v1/runs/:id/cancel) to end it without another model turn`, facts: { blockedBy: inner.errorCode, ...inner.facts } }),
     };
 }
+export function isResumeBlockedByPolicy(answer) {
+    return answer.status === 409 && typeof answer.body === "object" && answer.body !== null && answer.body.errorCode === "resume_blocked_by_policy";
+}
 export function resumeRefusalWithCard(answer, cardPending) {
     return cardPending ? { status: answer.status, body: { ...answer.body, retriable: true } } : answer;
 }

package/dist/http/claimed-run.d.ts

@@ -1,11 +1,12 @@
 /**
- * 一条提交腿**刚认领**的 run 在起跑之前就收场 —— 撤掉本请求建的东西的**唯一**写法。两个调用点:device 落点拒
- * (`device-placement.ts` `commitPlacement`)与续跑输入写不进(`submit-ctx.ts` `persistSubmitCtx`)。
+ * 一条提交腿**刚认领**的 run 在起跑之前就收场 —— 撤掉本请求建的东西的**唯一**写法。三个调用点:device 落点拒
+ * (`device-placement.ts` `commitPlacement`)、续跑输入写不进(`submit-ctx.ts` `persistSubmitCtx`)与 workflow 决定行没落成
+ * (`durable-run-leg.ts` 的 fresh 投递腿;此刻认领可能已被收割归了别人 —— 两步都按这一跑自己的 taskId,碰不到别人的认领)。
  *
  * 撤两步,**各自独立**(一步失败不拦另一步,残余最小):
  *  · 终结这条 run 行(`setTerminal` 是按 taskId 的 CAS,首写者赢 ⇒ 重复调用是 no-op)—— 随之释放它的 `task_active` 认领;
  *  · 放开它占的提交幂等键(拒绝答复邀请重试;同键重试必须真跑,不是回放这次拒绝 —— `RunStore.releaseIdemKey`)。
- * 撤不掉不致命、但要响:每一步的失败各交给调用方按自己的名字留痕(`onFailure`)。终结没落下 ⇒ 此刻心跳还没起来,`reapStale`
+ * 撤不掉不致命、但要响:每一步的失败各交给调用方按自己的名字留痕(`onFailure`)。终结没落下 ⇒ 起跑前的心跳随调用腿收场停下(或从没起过),`reapStale`
  * 在 `REAP_RUN_STALE_SEC` 之后把这条行翻 failed 并释放会话;幂等键没放开 ⇒ 同键重提回放这条行的回执(两形都是修前每一次的样子)。
  */
 import type { RunStore } from "../plugins/store-backend.js";

package/dist/http/device-placement.d.ts

@@ -53,6 +53,7 @@ import { type DeviceOwner } from "../device-store.js";
 import { type DeviceEnrollment, type DeviceRejection } from "../device-enrollment.js";
 import type { ServiceConfig } from "../config.js";
 import type { RunStore } from "../plugins/store-backend.js";
+import { type RefusalBody } from "./refusal-body.js";
 /**
  * 调用方 device 域的**唯一铸造点**。`undefined` = 判不出域(无 principal,或凭据不带 tenant claim)——
  * 消费点必须响亮拒,禁静默空视图。
@@ -170,8 +171,5 @@ export declare function placementWriteDeadlineMs(runStaleSec: number | undefined
  */
 export declare function commitPlacement(ctx: PlacementCommitCtx, runStore: RunStore, taskId: string, intent: DevicePlacementIntent | undefined): Promise<DeviceRejection | null>;
 /** 拒绝的**唯一** wire 体铸点(四个消费点各自用自己协议的发送姿势,但体的键集只有这一份)。 */
-export declare function devicePlacementErrorBody(rej: DeviceRejection): {
-    error: string;
-    errorCode: string;
-};
+export declare function devicePlacementErrorBody(rej: DeviceRejection): RefusalBody;
 //# sourceMappingURL=device-placement.d.ts.map

package/dist/http/device-placement.js

@@ -3,6 +3,7 @@ import { gatedPrincipal } from "./principal-gate.js";
 import { DEVICE_ERROR_CODES, assertDeviceIdShape, } from "../device-store.js";
 import { buildDeviceRejection } from "../device-enrollment.js";
 import { releaseClaimedRun } from "./claimed-run.js";
+import { refusalBody } from "./refusal-body.js";
 export function deviceOwnerDomainOf(req, config) {
     const subject = gatedPrincipal(req, config);
     if (subject === undefined)
@@ -139,6 +140,6 @@ export async function commitPlacement(ctx, runStore, taskId, intent) {
     return rejection;
 }
 export function devicePlacementErrorBody(rej) {
-    return { error: rej.message, errorCode: rej.code };
+    return refusalBody({ errorCode: rej.code, message: rej.message });
 }
 //# sourceMappingURL=device-placement.js.map

package/dist/http/dispatch.js

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
-import { setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isDestructiveSessionWrite, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../security.js";
+import { setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, setSsoRole, isDestructiveSessionWrite, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../security.js";
 import { publicStoreProbeError } from "../store-live-probe.js";
 import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
 import { ROUTE_METHOD_ORDER } from "./route-ctx.js";
 import { READ_CREDENTIAL_ROUTES, PUBLIC_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, billableKindOf, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute, isProbePath, isSubscriptionRequest } from "./route-table.js";
 import { sendJson, sendError, isSseResponse, endSseWithError } from "./send.js";
-import { admissionRefusalOf, readinessOf, healthReadinessKeys, sendReadyz, sendBillableRefusal, billableRefusalOf } from "./readiness.js";
+import { admissionRefusalOf, readinessOf, healthReadinessKeys, sendReadyz, sendBillableRefusal, billableRefusalOf, billableRefusalFrame } from "./readiness.js";
 import { ENGINE_SIGNAL_KEY, buildEngineSignal, fleetMembershipKeys, healthConfigLedgerKeys, healthDrainingKeys, mintEngineSignal, restartActionable } from "../fleet/engine-signal.js";
 import { buildHealthSelfReport } from "./health-self-report.js";
 import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal, sendUnauthorized, verifiedIdentitySource, hasServiceAuth, devOpenDeployment } from "./principal-gate.js";
@@ -51,10 +51,10 @@ export function createDispatch(ctx) {
         };
         deps.drainState.lastAttachEndedAt = () => lastAttachEndedAt;
         deps.drainState.endSubscriptions = () => {
-            const { errorCode, message } = billableRefusalOf("draining").body;
+            const frame = billableRefusalFrame(billableRefusalOf("draining"));
             for (const r of [...openSubscriptions])
                 if (isSseResponse(r))
-                    endSseWithError(r, { errorCode, message });
+                    endSseWithError(r, frame);
         };
     }
     async function dispatchSegment(rows, req, res, url, search, method, allow, ctx, admit) {
@@ -159,6 +159,10 @@ export function createDispatch(ctx) {
                     const credential = deps.centerCredentialState?.();
                     return credential ? { centerCredential: credential } : {};
                 })(),
+                ...(() => {
+                    const identityNotice = deps.centerIdentityNoticeState?.();
+                    return identityNotice ? { centerIdentityNotice: identityNotice } : {};
+                })(),
                 ...(() => {
                     const modelRefusals = deps.modelRefusalsState?.();
                     return modelRefusals ? { modelRefusals } : {};
@@ -214,6 +218,8 @@ export function createDispatch(ctx) {
                     req.headers[deps.config.principalHeader.toLowerCase()] = v.identity.principal;
                     if (v.identity.scope)
                         setSsoScope(req, v.identity.scope);
+                    if (v.identity.role)
+                        setSsoRole(req, v.identity.role);
                     deps.logger?.info?.("auth_bridge_principal_accepted", { principal: v.identity.principal, ...(v.identity.scope ? { scope: v.identity.scope } : {}) });
                 }
             }