@sema-agent/server 7.132.0 → 7.134.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,36 +83,62 @@ 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) => {
-            const read = await readResumeCtx(cs.getCtx(sessionId));
+            const read = await readResumeCtx(cs.getCtx(sessionId), { sessionId, opener: deps.checkpointCtxSealing });
             if (read.kind === "corrupt")
                 return undefined;
+            if (read.kind === "unsealable")
+                return undefined;
             if (read.kind === "absent")
                 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 +150,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 +183,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 +208,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

@@ -39,6 +39,10 @@
  * `resolveSpec` 本身留作真正的拒点(提交腿 400;续跑腿在到它之前已被本判据答掉)。再开第六个问点必须调这两只,不许各判各的 —— 此前铸卡前只判了
  * allow 记号,工具名清单那一问漏在外面,卡铸出来了、`/wake` 恒 409([ref] 合并复审两腿同报)。
  *
+ * ## 凭据位密封(7.134.0;常设规则,不是迁移)
+ * 体里请求面凭据位上的值在 ctx 里只以封签存在 —— 写:{@link buildCheckpointCtx} / {@link sealCheckpointCtx} 一只封口;读:续跑上下文读口里一只开口
+ * {@link openCheckpointCtx};开不开 ⇒ `409 conflict.checkpoint_ctx_unsealable`。规则全文在本文件末段「凭据位密封」的头注。
+ *
  * ## 何时删(一次性迁移,不是长期双读)
  * 本判据、拒臂、记号写点与 `CheckpointCtx.permissionsAllowReading` 一起删,删除条件与窗登记在 `plugins/one-time-migrations.ts` 的
  * 一次性迁移登记表(本条那一行):所有旧读法下停驻的行都已结束或被收割(停驻行的终局 = 落盘起 `TERMINAL_BACKSTOP_MS`,见
@@ -73,14 +77,16 @@ export declare function bodyCarriesAllowList(body: TaskRequestBody): boolean;
  * 调用方是「本进程刚按当前读法读过这份体」的写点:fresh 提交(受理门按当前读法读过 `allow`),或已经过了续跑拒臂的重放腿
  * (`startFreshHostTurn` 把宿主的存量体交给 `POST /v1/runs` 同一条链 —— 它在那之前调过 `resolveResumeSpecOrBlocked`,没记号却带 `allow` 的体到不了这里)。
  * 续跑腿的**写回**不经本函数:**不改词**的写回传读进来的 ctx(记号随行,不重新判 —— 在写回口重新判会把一条没记号的旧行「洗」成新行);
- * **改词**的写回(只有 `plan_review` 的批准 / 编辑)经 {@link withPermissionModeRewritten}。
+ * **改词**的写回(只有 `plan_review` 的批准 / 编辑)经 {@link withPermissionModeRewritten}。两种写回落盘之前都过同一只封口 {@link sealCheckpointCtx}。
+ *
+ * `sealer` / `sessionId`:凭据位密封的两件(本文件末段)—— `sessionId` 是这一行的会话(绑进封签);`sealer` 必传,缺席也要说出来(`undefined`)。
  */
 export declare function buildCheckpointCtx(fields: {
     body: TaskRequestBody;
     memoryScope?: string | undefined;
     unattendedLeg?: true;
     writerVersion: string;
-}): CheckpointCtx;
+}, sealer: CheckpointCtxSealer | undefined, sessionId: string): SealedCheckpointCtx;
 /**
  * 模式词的**第二个写者** —— `plan_review` 的批准 / 编辑把这条 run 的体词从 `plan` 写成批准的档(`resume-legs.ts` `drivePlanReview`,调用点只有那一处;
  * `test/allow-list-reading-park-refusal.test.ts` 枚举调用点,多一处即红)。与 {@link buildCheckpointCtx} **同一条规则**:按当前读法写下的词,盖当前读法记号。
@@ -101,15 +107,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 +122,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 +166,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 注那一个意思)。
@@ -208,4 +214,153 @@ export declare function storedBodyReplayLogFields(refusal: StoredBodyReplayRefus
  * 没有默认值:每个调用点必须说出这件事实。
  */
 export declare function storedBodyReplayAnswer(refusal: StoredBodyReplayRefusal, readerVersion: string, cardPending: boolean): ResumeRefusalAnswer;
+/**
+ * 🔴 **停驻行里请求面凭据的落盘形 —— 一条规则**:提交体里**凭据位**({@link CHECKPOINT_CTX_CREDENTIAL_SLOTS},闭集)上的每一个值,在 `checkpoint_ctx`
+ * (local 店的 `<数据根>/checkpoint-ctx/<会话>.json` / SQL 店的 `checkpoint_ctx.ctx` 列)里只以**封签**({@link SealedCheckpointValue})存在。
+ *  · **写**:一只封口 {@link sealCheckpointCtx}。新的持久化写经 {@link buildCheckpointCtx}(它的唯一产物形就是封好的 {@link StoredCheckpointCtx}),
+ *    续跑腿的写回(`resume-legs.ts` 的 `commitResumeCtx`:读进来的 ctx 在内存里是开封形)经它本身;一次性迁移 M28 对存量行用同一只走法
+ *    ({@link sealStoredCheckpointCtxM28})。凭据位上的**每一个值都封,不分类型**(串、数字、`null`、对象 —— 包括调用方自己送来的封签形对象):
+ *    封签里装的是那个 JSON 值本身,开封逐字还原。字典位上的容器本身不是字典(串 / 数组 / `null` / 封签形对象)⇒ 整只容器当一个值封。
+ *    于是落盘形里凭据位上**只有本封口铸的封签**,没有哪个值能「原样存下、续跑时被开成别的东西」(调用方送一只封签形对象 ⇒ 存的是再封一层,
+ *    开出来还是那只对象 —— 与新提交腿看到的同一个值)。没有封签器而有值要封 ⇒ 抛 {@link CheckpointCtxUnsealableError}(`no_key_store`,调用方在写之前拒)。
+ *  · **读法记号**(与本文件另两只记号同一条「写的人盖章」):封口铸出的每一份落盘形都带 `credentialSeal: CHECKPOINT_CTX_SEAL_ALG` —— 这一行的凭据位
+ *    **全部**由本封口封过。没有记号的行是 7.134.0 之前的写者写下的:那时没有任何写者封值,所以它凭据位上的封签形对象只可能是调用方原样送来的,不是封签。
+ *    记号只在落盘形上(开口交出的开封形里没有它;写回再封时重新盖)。
+ *  · **读**:一只开口 {@link openCheckpointCtx},唯一调用方 = 续跑上下文唯一读口 `resume-ctx-read.ts` 的 `readResumeCtx`(读出的 ctx 在任何消费者
+ *    看到之前已开封)。行带当前记号:凭据位上封签 ⇒ 开(开不开 ⇒ 拒);带 `sealed` 键却不是本闭集的封签形(含将来的 `alg`)⇒ 拒 `unrecognized_seal`;
+ *    其余任何值 ⇒ 拒 `plaintext`。行没有记号 ⇒ 凭据位上**任何**值(含封签形对象)⇒ 拒 `plaintext`(更早版本写下、M28 还没扫到);记号认不得(将来的格式)⇒
+ *    凭据位上任何值 ⇒ 拒 `unrecognized_seal`。凭据位上没有值的行不论记号照常开。
+ *    **拒** = 读口第四态 `unsealable`(`field` = 哪一个凭据位,`reason` ∈ {@link CHECKPOINT_CTX_UNSEALABLE_REASONS}),各续跑入口答
+ *    `409 conflict.checkpoint_ctx_unsealable`(`resume-ctx-read.ts` 的 `resumeCtxUnsealableAnswer`)。**没有**明文回落臂、**没有**静默丢键臂。
+ *  · **装配**:`checkpointStore` 在场而封签器缺席 ⇒ 拒启({@link CHECKPOINT_CTX_SEALING_REQUIRED};`createHttpServer` 与起服第 6 段同一句)。
+ *
+ * **一个域一对钥匙**:停驻行封签用这一域自己的保管店(`<数据根>/sealed-key/checkpoint-ctx-keys/`,生产工厂 `sealed-key.ts` `ensureCheckpointCtxSealing`),
+ * 与模型钥匙(`ModelEntry.sealedApiKey`)的那对钥匙不共用 —— 模型钥匙的密文放进凭据位、停驻行的封签放进 `sealedApiKey`,两边都是「不持有那把钥匙」;
+ * 封签再把**会话 id 绑进密文**(信封 = `[alg, sessionId, value]`):别的会话那一行的封签搬过来开不开 —— 读口不是这台副本任何一把钥匙的解密预言机。
+ *
+ * 本模块的零值依赖纪律照旧:封签器 / 开封器是调用方递进来的接口(实现在 `sealed-key.ts`,它依赖 libsodium,不进本模块的闭包)。
+ */
+export declare const CHECKPOINT_CTX_SEAL_ALG = "checkpoint-ctx-sealedbox-v1";
+/** 停驻行里一只凭据值的**封签**(闭集形:恰这三键、三值皆串、`alg` 只有 {@link CHECKPOINT_CTX_SEAL_ALG} 一个词)。与明文不可混淆:明文是串,封签是对象。 */
+export interface SealedCheckpointValue {
+    readonly alg: typeof CHECKPOINT_CTX_SEAL_ALG;
+    /** 封它的那把公钥的 id(开封按它**精确**选私钥,不逐把试)。 */
+    readonly publicKeyId: string;
+    /** `crypto_box_seal` 密文的标准 base64。 */
+    readonly sealed: string;
+}
+/** 封口(只会封):把凭据位上的一个 JSON 值(任何类型)封进 `sessionId` 那一行。抛 = 封不了(调用方当写失败处置)。 */
+export interface CheckpointCtxSealer {
+    seal(value: unknown, sessionId: string): SealedCheckpointValue;
+}
+/** 开口:`holds` = 这台副本有没有 `publicKeyId` 那把私钥;`open` 抛 = 开不开(密文坏 / 不是 `sessionId` 那一行封的 / 不是停驻行信封);返回封进去的那个 JSON 值。
+ *  🔴 `open` 的返回值是活凭据:只进内存,不进日志、不落盘(再落盘必经 {@link sealCheckpointCtx})。 */
+export interface CheckpointCtxOpener {
+    holds(publicKeyId: string): boolean;
+    open(sealed: SealedCheckpointValue, sessionId: string): unknown;
+}
+/** 封签器 = 封口 + 开口(生产工厂 `sealed-key.ts` `ensureCheckpointCtxSealing`;`ServiceDeps.checkpointCtxSealing` 的型)。 */
+export interface CheckpointCtxSealing extends CheckpointCtxSealer, CheckpointCtxOpener {
+}
+/**
+ * **凭据位闭集**(提交体里值为凭据的位置)。路径段 `*` = 那一格容器的**每一个成员**:数组的每一项、字典的每一个值(一只走法,不分容器种类 —— 字典成员的点名形
+ * `field` 是 `.<键>`,数组是 `[<下标>]`)。`map` = 那一格是串值字典,**每一个值**都是凭据(不分哪一键);`value` = 那一格本身是凭据。
+ * 入表判据(一条):请求面上**为承载凭据而设**的字段 —— 静态请求头(MCP http 传输、A2A 对端〔引擎型注:「e.g. an auth bearer」〕、http hook 条目)、
+ * 交给子进程的 env(MCP stdio 传输、任务 shell 的 `settings.env`)、请求自带的搜索后端钥匙。http hook 的头与另两种静态头同判:契约包的条目形是
+ * `headers: Record<string, string>`、受理面(`parseHooksConfig`)只判条数与字数、`interpolateHookEnvVars` 只换 `$NAME` 引用而字面值原样上 wire ——
+ * 头值可以就是字面的 `Authorization: Bearer …`。hooks 的形 = 事件名 → 匹配组数组 → 组的 `hooks` 数组 → 条目;只有 `type:"http"` 的条目有 `headers`,
+ * 别的条目在那一段缺席、走法照常不往下走。**不入表**:命令行 / URL / 工具实参之类自由文本(不是凭据字段;它们里有没有秘密不是本层能判的)。
+ * 加一位 = 加一行,读写两侧与一次性迁移 M28 共用 {@link mapCredentialSlots} 一只走法,自动覆盖。
+ */
+export declare const CHECKPOINT_CTX_CREDENTIAL_SLOTS: readonly [{
+    readonly path: readonly ["mcpServers", "*", "transport", "headers"];
+    readonly holds: "map";
+}, {
+    readonly path: readonly ["mcpServers", "*", "transport", "env"];
+    readonly holds: "map";
+}, {
+    readonly path: readonly ["a2aPeers", "*", "headers"];
+    readonly holds: "map";
+}, {
+    readonly path: readonly ["settings", "env"];
+    readonly holds: "map";
+}, {
+    readonly path: readonly ["settings", "webSearch", "apiKey"];
+    readonly holds: "value";
+}, {
+    readonly path: readonly ["settings", "hooks", "*", "*", "hooks", "*", "headers"];
+    readonly holds: "map";
+}];
+/** 开不开 / 封不了的成因(闭集):`no_key_store` = 这台副本没有封签器(没有保管店);`key_not_held` = 封它的那把钥匙不在这台副本的保管店里
+ *  (多副本不共享 `<数据根>/sealed-key/`,或保管目录被换过);`unopenable` = 钥匙在、开不开(密文坏 / 不是这一行封的 / 不是停驻行信封);
+ *  `plaintext` = 凭据位上是明文(更早版本的写者);`unrecognized_seal` = 带 `sealed` 键却不是本闭集的封签形(含将来的 `alg`)。 */
+export declare const CHECKPOINT_CTX_UNSEALABLE_REASONS: readonly ["no_key_store", "key_not_held", "unopenable", "plaintext", "unrecognized_seal"];
+export type CheckpointCtxUnsealableReason = (typeof CHECKPOINT_CTX_UNSEALABLE_REASONS)[number];
+/** 封不了 / 开不开的那一格:`field` = 凭据位在提交体里的路径(如 `mcpServers[0].transport.headers.Authorization`、
+ *  `settings.hooks.PreToolUse[0].hooks[0].headers.Authorization`;键名不是秘密,值从不进来)。 */
+export declare class CheckpointCtxUnsealableError extends Error {
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+    constructor(field: string, reason: CheckpointCtxUnsealableReason);
+}
+/**
+ * 停驻行的**落盘形**:凭据位上是封签,不是 {@link TaskRequestBody} 型面说的串 —— 所以体在型面上只是「一只对象」,读它的唯一合法方式是 {@link openCheckpointCtx}
+ * (经续跑上下文读口)。产物只有两只铸点:{@link buildCheckpointCtx} 与 {@link sealCheckpointCtx}。
+ */
+export type StoredCheckpointCtx = Omit<CheckpointCtx, "body"> & {
+    readonly body: {
+        readonly [key: string]: unknown;
+    };
+    readonly credentialSeal?: typeof CHECKPOINT_CTX_SEAL_ALG;
+};
+declare const sealedCheckpointCtxBrand: unique symbol;
+/**
+ * **封口铸出的**落盘形(品牌型):店的写口(`putCtx`)与一次性迁移 M28 的行改写只收它 ⇒ 「写 ctx 只有封口一个写入面」由型面守,
+ * 不再靠逐个数调用点(把开封形 / 裸对象直接交给写口 = 当场 tsc 红)。铸点闭集(都在本模块,都经 {@link mintSealedCheckpointCtx}):
+ * {@link sealCheckpointCtx}(新的持久化写经 {@link buildCheckpointCtx} 到它;续跑腿的写回)与 {@link sealStoredCheckpointCtxM28}。零运行期变化。
+ */
+export type SealedCheckpointCtx = StoredCheckpointCtx & {
+    readonly [sealedCheckpointCtxBrand]: true;
+};
+/** 装配期拒启的那一句(`createHttpServer` 与起服第 6 段同调;一句、一个出口)。 */
+export declare const CHECKPOINT_CTX_SEALING_REQUIRED = "a durable checkpoint store is wired but checkpointCtxSealing is not: suspended tasks keep the request's credentials (MCP / A2A headers and env values, settings.env, settings.webSearch.apiKey, http hook headers) in their resume context, and they are stored sealed or not at all \u2014 give the service a sealed-key store for them (this service builds it under <data root>/sealed-key/checkpoint-ctx-keys/ at boot; a failure there is the earlier checkpoint_ctx_sealing_unavailable warning \u2014 make that directory creatable and chmod-able by the service, or repair or remove a key file there whose public and private halves do not belong together), or, when embedding, pass checkpointCtxSealing: await ensureCheckpointCtxSealing(sealedKeyDir); refusing to start rather than write credentials in plaintext";
+/** 封签形的判官(恰三键、三值皆串、`alg` 是本闭集那一个词)。 */
+export declare function isSealedCheckpointValue(v: unknown): v is SealedCheckpointValue;
+/**
+ * **封口**(写的一侧唯一的一只):内存里的开封形 ctx ⇒ 落盘形。`sealer` 必传(缺席也要说出来:`undefined` = 这台副本没有保管店 ⇒ 体里有凭据就抛
+ * {@link CheckpointCtxUnsealableError} `no_key_store`,调用方在写之前拒;体里没有凭据 ⇒ 没有要封的东西,照常)。`sessionId` = 这一行的会话(绑进封签)。
+ * 调用方:{@link buildCheckpointCtx}(新的持久化写)与续跑腿的写回(`resume-legs.ts` `commitResumeCtx`)。
+ */
+export declare function sealCheckpointCtx(ctx: CheckpointCtx, sealer: CheckpointCtxSealer | undefined, sessionId: string): SealedCheckpointCtx;
+/** {@link openCheckpointCtx} 的结局:开封形 ctx,或第一处开不开的凭据位。 */
+export type OpenedCheckpointCtx = {
+    readonly kind: "ok";
+    readonly ctx: CheckpointCtx;
+} | {
+    readonly kind: "unsealable";
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+};
+/**
+ * **开口**(读的一侧唯一的一只;唯一调用方 = 续跑上下文读口 `readResumeCtx`):落盘形 ⇒ 开封形。`opener` 缺席 = 这台副本没有保管店(体里有封签就
+ * `no_key_store`;没有凭据的行照常开)。判词见本段头注。
+ */
+export declare function openCheckpointCtx(stored: StoredCheckpointCtx, opener: CheckpointCtxOpener | undefined, sessionId: string): OpenedCheckpointCtx;
+/**
+ * 一份落盘 ctx(持久化 JSON,不信型面)的凭据位上**第一只封签**的点名(`field`,形同拒句里的那一位;键名不是秘密,值从不出来)—— 没有 ⇒ `undefined`。
+ * 走法 = 封口 / 开口 / M28 共用的那一只 {@link mapCredentialSlots},判形 = {@link isSealedCheckpointValue};不开封、不看记号(只问「凭据位上有没有封签」)。
+ * 唯一读者:随包排空检查脚本的 `sealed-credentials-rollback` 判据(经编译产物取):7.133.x 读不懂封签、续跑时把这些凭据位当没有 ⇒ 回滚之前先把这样的停驻行决掉或取消。
+ */
+export declare function sealedCredentialFieldOf(stored: unknown): string | undefined;
+/**
+ * 🔴 **一次性迁移 M28 的行改写**(窗与删法见 `plugins/one-time-migrations.ts` 登记表 M28;编排 = `checkpoint-ctx-seal-m28.ts`):一行存量 ctx
+ * (持久化 JSON,不信型面)**没有读法记号**(= 7.134.0 之前的写者写下的)⇒ 凭据位上的**每一个值**(含调用方原样送来的封签形对象)用同一只封口封好、盖记号 ——
+ * 与写侧 {@link sealCheckpointCtx} 同一条规则。带记号的行(本版写下的,或本条已改写过的)、记号认不得的行 ⇒ `undefined`(不写:第二跑零命中;认不得的留给读口拒);
+ * 凭据位上没有值 ⇒ `undefined`(不写);体不是对象 ⇒ `undefined`(读口自己的形判接住)。其余位(另两只记号、写者版本、非凭据字段)原样。
+ */
+export declare function sealStoredCheckpointCtxM28(stored: object, sealer: CheckpointCtxSealer, sessionId: string): {
+    readonly ctx: SealedCheckpointCtx;
+    readonly valuesSealed: number;
+} | undefined;
+export {};
 //# sourceMappingURL=checkpoint-ctx.d.ts.map