@sema-agent/server 7.131.0 → 7.132.0

package/dist/http/admission.d.ts

@@ -6,6 +6,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { TaskRequestBody } from "./wire-types.js";
 import { HttpError } from "../security.js";
+import { type LimitFacts } from "../limit-refusal.js";
 import type { PreparedTaskSubmission, RouteHelpers } from "./route-ctx.js";
 import type { FlatServiceDeps } from "./server.js";
 /** = core `SKILL_CONTENT_MAX_CHARS`(1MB 加载门,core 1.293 起 invoke 全文零截断、超 1MB 整拒;常量在
@@ -22,7 +23,7 @@ export declare const MAX_SYSTEM_PROMPT_CHARS = 16384;
  *  validation cost. 32KB comfortably holds a rich nested schema while bounding the abuse surface. */
 export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
 /**
- * Validate `body.skills` —— **形**校验 + 一条引擎孪生门。返回错误串(→ 400)或 null。
+ * Validate `body.skills` —— 逐条:**形**校验 + 一条引擎孪生门,再判两只清单的条数帽(与全部工具名清单同一只判)。返回拒({@link UserSkillsRefusal}:句子 + 撞帽时的机读位 → 400)或 null。
  *
  * 🔴 **[ref](7.77.0,硬 BREAKING;零别名零双读)**:此前这里有三条本仓自造的拒绝臂,全部退役 ——
  *  · `at most 10 skills per request`(条数帽);
@@ -51,7 +52,12 @@ export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
  *
  * 🔴 **server 侧禁裁列表 / 禁截描述**:渲染归引擎(单一属主)。本函数只判「这一条技能的形能不能用」。
  */
-export declare function validateUserSkills(skills: unknown): string | null;
+export declare function validateUserSkills(skills: unknown): UserSkillsRefusal | null;
+/** `body.skills` 的拒:句子 + 撞帽时的机读位(`field` / `reason` / `count` / `cap`;形错只有句子)。与子代定义那道门(`spec-fields.ts` 的 `TaskAgentsRefusal`)同形。 */
+export interface UserSkillsRefusal {
+    readonly message: string;
+    readonly facts?: LimitFacts;
+}
 /**
  * core 7.41.0 #1303 —— 顶层技能带 `manifest` 的拒因句(单铸点)。出路只点本服务上**真存在**的旋钮:技能的两只清单
  * (`allowedTools` / `disallowedTools`)、圈工具 = deny 规则(请求 `settings.permissions.deny` / 运维 `APPROVAL_DENY`)或子代定义的

package/dist/http/admission.js

@@ -8,15 +8,20 @@ import { autonomyModeFloor } from "../runtime-governance.js";
 import { taskBodyKeyIssue } from "../request-key-closure.js";
 import { FILE_HISTORY_DISABLED_NO_RESTORE, fileHistoryRestoreConflict, inheritEnvFieldIssue, singleMemberOffFieldIssue } from "../request-value-closure.js";
 import * as facts from "../capability-facts.js";
-import { buildToolMatcherRefusal, parseHooksConfig, toolMatcherIssue } from "../hooks/hook-runner.js";
+import { buildHooksRefusal, parseHooksConfig, hooksMatcherIssue } from "../hooks/hook-runner.js";
 import { judgeRequestWebSearch } from "../plugins/web-search.js";
-import { normalizeApproachNotice, skillToolListOk, skillToolListRefusal, unknownTaskAgentModelRef, validateTaskAgents } from "../spec-fields.js";
+import { normalizeApproachNotice, skillToolListOk, unknownTaskAgentModelRef, validateTaskAgents } from "../spec-fields.js";
+import { skillToolListsOverCap } from "../rule-entry-list.js";
+import { limitRefusal } from "../limit-refusal.js";
+import { quotedCallerText } from "../caller-text-echo.js";
 import { MAX_ADDITIONAL_DIRS } from "../task-cwd.js";
 import { verifyRoundsFromBody } from "./verify-rounds.js";
 import { skillCarriesRetiredManifest } from "./retired-skill-manifest.js";
 import { resolveDevicePlacementIntent } from "./device-placement.js";
 import { createRunAcceptance } from "../run-acceptance.js";
 import { sendError, sendHttpError } from "./send.js";
+import { refuseSubmitBody } from "./request-guards.js";
+import { sqlWallsOf } from "../plugins/sql-driver.js";
 import { ABSOLUTE_HOST_PATH_MAX, isAbsoluteHostPath, WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
 const APPROVAL_REACH_WORDS = APPROVAL_REACH.map((word) => JSON.stringify(word)).join(" / ");
 export const MAX_SKILL_CONTENT_CHARS = 1_048_576;
@@ -26,27 +31,34 @@ export function validateUserSkills(skills) {
     if (skills === undefined)
         return null;
     if (!Array.isArray(skills))
-        return "skills must be an array of { name, description, content }";
-    for (const s of skills) {
-        if (s === null || typeof s !== "object")
-            return "each skill must be an object { name, description, content }";
-        if (typeof s["name"] !== "string" || s["name"].length === 0)
-            return "skill.name must be a non-empty string";
-        if (typeof s["description"] !== "string")
-            return "skill.description must be a string";
-        if (typeof s["content"] !== "string" || s["content"].length === 0 || s["content"].length > MAX_SKILL_CONTENT_CHARS)
-            return `skill.content must be a non-empty string of at most ${MAX_SKILL_CONTENT_CHARS} characters (the engine rejects skills over this size outright at load time)`;
-        if (s["baseDir"] !== undefined && !isAbsoluteHostPath(s["baseDir"]))
-            return `skill.baseDir must be an absolute path string of at most ${ABSOLUTE_HOST_PATH_MAX} characters with no ".." segment and no NUL byte (it is not resolved or read here — the engine only substitutes it into the skill's own text)`;
-        if (skillCarriesRetiredManifest(s))
-            return SKILL_MANIFEST_RETIRED;
-        for (const key of ["allowedTools", "disallowedTools"]) {
-            if (s[key] !== undefined && !skillToolListOk(s[key]))
-                return `skill.${key} must be an array of strings (permission-rule spellings: a tool name, mcp__<server> / mcp__<server>__*, Bash(<prefix>:*), Read(//<dir>/**))`;
-        }
-        const listRefusal = skillToolListRefusal(s);
-        if (listRefusal !== undefined)
-            return listRefusal;
+        return { message: "skills must be an array of { name, description, content }" };
+    for (let k = 0; k < skills.length; k++) {
+        const shape = userSkillShapeIssue(skills[k]);
+        if (shape !== null)
+            return { message: shape };
+        const over = skillToolListsOverCap(skills[k], `skills[${k}]`, "top");
+        if (over !== undefined)
+            return { message: over.message, ...(over.extra !== undefined ? { facts: over.extra } : {}) };
+    }
+    return null;
+}
+function userSkillShapeIssue(item) {
+    if (item === null || typeof item !== "object")
+        return "each skill must be an object { name, description, content }";
+    const s = item;
+    if (typeof s["name"] !== "string" || s["name"].length === 0)
+        return "skill.name must be a non-empty string";
+    if (typeof s["description"] !== "string")
+        return "skill.description must be a string";
+    if (typeof s["content"] !== "string" || s["content"].length === 0 || s["content"].length > MAX_SKILL_CONTENT_CHARS)
+        return `skill.content must be a non-empty string of at most ${MAX_SKILL_CONTENT_CHARS} characters (the engine rejects skills over this size outright at load time)`;
+    if (s["baseDir"] !== undefined && !isAbsoluteHostPath(s["baseDir"]))
+        return `skill.baseDir must be an absolute path string of at most ${ABSOLUTE_HOST_PATH_MAX} characters with no ".." segment and no NUL byte (it is not resolved or read here — the engine only substitutes it into the skill's own text)`;
+    if (skillCarriesRetiredManifest(s))
+        return SKILL_MANIFEST_RETIRED;
+    for (const key of ["allowedTools", "disallowedTools"]) {
+        if (s[key] !== undefined && !skillToolListOk(s[key]))
+            return `skill.${key} must be an array of strings (permission-rule spellings: a tool name, mcp__<server> / mcp__<server>__*, Bash(<prefix>:*), Read(//<dir>/**))`;
     }
     return null;
 }
@@ -64,11 +76,64 @@ function refuseUnavailableModel(res, config, field, ref) {
     sendError(res, 400, "request.model_unavailable", message);
     return true;
 }
+const kindOf = (v) => (v === null ? "null" : Array.isArray(v) ? "an array" : typeof v === "object" ? "an object" : `a ${typeof v}`);
+function hostPathListRefusal(field, raw) {
+    if (!Array.isArray(raw))
+        return { message: `${field} must be an array of absolute host paths` };
+    if (raw.length > MAX_ADDITIONAL_DIRS)
+        return limitRefusal(field, "entries", raw.length, MAX_ADDITIONAL_DIRS);
+    const index = raw.findIndex((d) => !isAbsoluteHostPath(d));
+    if (index < 0)
+        return undefined;
+    const bad = raw[index];
+    return { message: `${field}[${index}] must be a non-empty absolute host path (no '..' segments) — got ${typeof bad === "string" ? quotedCallerText(bad) : kindOf(bad)}`, facts: { field, reason: "bad_entry", index } };
+}
 const modelIdOf = (model) => (typeof model === "string" ? model : model?.id);
 export function createAdmission(ctx) {
     const { deps, readJson, runnerFor } = ctx;
     async function prepareSpec(req, res, bodyIn, onTypedFailure, legFacts) {
         const body = bodyIn ?? (await readJson(req));
+        {
+            const refusal = refuseSubmitBody(sqlWallsOf(deps.sqlEngine), body);
+            if (refusal !== null) {
+                const facts = { wallSource: refusal.wallSource };
+                switch (refusal.wallSource) {
+                    case "reported":
+                        switch (refusal.by) {
+                            case "row":
+                                sendError(res, 413, "request.payload_too_large", `task body is ${refusal.bytes} bytes, over this deployment's ${refusal.limitBytes}-byte limit: the database stores each submitted task in one row and holds at most ${refusal.wallBytes} bytes per row — shrink the inline images / userAttachments, or ask the operator to raise the database's single-row limit (TiDB performance.txn-entry-size-limit)`, facts);
+                                break;
+                            case "packet":
+                                sendError(res, 413, "request.payload_too_large", `task body is ${refusal.bytes} bytes as sent to the database (JSON text with SQL string escaping), over this deployment's ${refusal.limitBytes}-byte limit: the database takes each submitted task in one statement and accepts at most ${refusal.wallBytes} bytes per statement — shrink the inline images / userAttachments, or ask the operator to raise the database's max_allowed_packet`, facts);
+                                break;
+                            default: {
+                                const unhandled = refusal.by;
+                                throw new Error(`submit body refusal without an HTTP answer: ${String(unhandled)}`);
+                            }
+                        }
+                        break;
+                    case "assumed":
+                        switch (refusal.by) {
+                            case "row":
+                                sendError(res, 413, "request.payload_too_large", `task body is ${refusal.bytes} bytes, over this deployment's ${refusal.limitBytes}-byte limit: the database's single-row limit was not read (engine facts not read yet, or the limit could not be read); refusing conservatively at ${refusal.wallBytes} bytes per row (the smallest documented single-row limit among the supported engines) — retry shortly; if it persists, ask the operator to let the service's database account read the engine's row-size limit`, facts);
+                                break;
+                            case "packet":
+                                sendError(res, 413, "request.payload_too_large", `task body is ${refusal.bytes} bytes as sent to the database (JSON text with SQL string escaping), over this deployment's ${refusal.limitBytes}-byte limit: the database's statement limit was not read (engine facts not read yet, or max_allowed_packet could not be read); refusing conservatively at ${refusal.wallBytes} bytes per statement (smallest documented max_allowed_packet default) — retry shortly; if it persists, ask the operator to check that the service's database account can read max_allowed_packet`, facts);
+                                break;
+                            default: {
+                                const unhandled = refusal.by;
+                                throw new Error(`submit body refusal without an HTTP answer: ${String(unhandled)}`);
+                            }
+                        }
+                        break;
+                    default: {
+                        const unhandled = refusal.wallSource;
+                        throw new Error(`submit body refusal without an HTTP answer: ${String(unhandled)}`);
+                    }
+                }
+                return null;
+            }
+        }
         if (!body || typeof body.objective !== "string") {
             sendError(res, 400, "request.field_invalid", "missing 'objective' string");
             return null;
@@ -113,35 +178,13 @@ export function createAdmission(ctx) {
             sendError(res, 400, "request.field_invalid", "cwd must be a non-empty absolute host path");
             return null;
         }
-        const addDirsRaw = body.additionalDirectories;
-        if (addDirsRaw !== undefined) {
-            if (!Array.isArray(addDirsRaw)) {
-                sendError(res, 400, "request.field_invalid", "additionalDirectories must be an array of absolute host paths");
-                return null;
-            }
-            if (addDirsRaw.length > MAX_ADDITIONAL_DIRS) {
-                sendError(res, 400, "request.field_invalid", `additionalDirectories must have at most ${MAX_ADDITIONAL_DIRS} entries`);
-                return null;
-            }
-            const bad = addDirsRaw.find((d) => !isAbsoluteHostPath(d));
-            if (bad !== undefined) {
-                sendError(res, 400, "request.field_invalid", "each additionalDirectories entry must be a non-empty absolute host path (no '..' segments)");
-                return null;
-            }
-        }
-        const addReadDirsRaw = body.additionalReadDirectories;
-        if (addReadDirsRaw !== undefined) {
-            if (!Array.isArray(addReadDirsRaw)) {
-                sendError(res, 400, "request.field_invalid", "additionalReadDirectories must be an array of absolute host paths");
-                return null;
-            }
-            if (addReadDirsRaw.length > MAX_ADDITIONAL_DIRS) {
-                sendError(res, 400, "request.field_invalid", `additionalReadDirectories must have at most ${MAX_ADDITIONAL_DIRS} entries`);
-                return null;
-            }
-            const badRead = addReadDirsRaw.find((d) => !isAbsoluteHostPath(d));
-            if (badRead !== undefined) {
-                sendError(res, 400, "request.field_invalid", "each additionalReadDirectories entry must be a non-empty absolute host path (no '..' segments)");
+        for (const field of ["additionalDirectories", "additionalReadDirectories"]) {
+            const raw = body[field];
+            if (raw === undefined)
+                continue;
+            const refusal = hostPathListRefusal(field, raw);
+            if (refusal !== undefined) {
+                sendError(res, 400, "request.field_invalid", refusal.message, refusal.facts);
                 return null;
             }
         }
@@ -215,12 +258,13 @@ export function createAdmission(ctx) {
             if (st.hooks !== undefined && st.hooks !== null) {
                 const hooksParsed = parseHooksConfig(st.hooks);
                 if (!hooksParsed.config) {
-                    sendError(res, 400, "request.field_invalid", hooksParsed.error ?? "settings.hooks: invalid shape");
+                    const refusal = buildHooksRefusal(hooksParsed.issue);
+                    sendError(res, 400, "request.field_invalid", refusal.message, { field: refusal.field, detail: refusal.detail });
                     return null;
                 }
-                const toolMatcher = toolMatcherIssue(hooksParsed.config, taskHooksHonored(deps.config) ? "regex" : "literal");
+                const toolMatcher = hooksMatcherIssue(hooksParsed.config, taskHooksHonored(deps.config) ? "regex" : "literal");
                 if (toolMatcher !== undefined) {
-                    const refusal = buildToolMatcherRefusal(toolMatcher);
+                    const refusal = buildHooksRefusal(toolMatcher);
                     sendError(res, 400, "request.field_invalid", refusal.message, { field: refusal.field, detail: refusal.detail });
                     return null;
                 }
@@ -235,7 +279,7 @@ export function createAdmission(ctx) {
         }
         const skillsErr = validateUserSkills(body.skills);
         if (skillsErr) {
-            sendError(res, 400, "request.field_invalid", skillsErr);
+            sendError(res, 400, "request.field_invalid", skillsErr.message, skillsErr.facts);
             return null;
         }
         if (Array.isArray(body.images)) {
@@ -461,7 +505,7 @@ export function createAdmission(ctx) {
         if (body.agents !== undefined) {
             const agentsErr = validateTaskAgents(body.agents);
             if (agentsErr) {
-                sendError(res, 400, "request.field_invalid", agentsErr);
+                sendError(res, 400, "request.field_invalid", agentsErr.message, agentsErr.facts);
                 return null;
             }
             const agentsBare = deps.config.models ?? {};

package/dist/http/approval-sweeps.js

@@ -4,8 +4,7 @@ import { decodeCheckpointScope } from "../security.js";
 import { hostDecisionFacts } from "../host-decision.js";
 import { APPROVAL_GATE_KINDS } from "../tool-approval.js";
 import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
-import { hasServiceAuth } from "./dispatch.js";
-import { gatedPrincipal } from "./principal-gate.js";
+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";
@@ -22,8 +21,27 @@ function blockedScalars(body) {
     }
     return out;
 }
+const BLOCKED_WARNED_MAX = 1024;
 export function createApprovalSweeps(ctx) {
     const { deps, resumeCheckpoint, mayDiscloseRowError } = ctx;
+    const blockedWarned = new Map();
+    const noteResumeBlocked = (cardToken, sessionId, status, body) => {
+        deps.metrics?.inc("deny_sweep_resume_blocked_total");
+        const fields = { status, ...blockedScalars(body) };
+        if (cardToken !== undefined) {
+            const fingerprint = JSON.stringify(fields);
+            if (blockedWarned.get(cardToken) === fingerprint)
+                return;
+            blockedWarned.delete(cardToken);
+            if (blockedWarned.size >= BLOCKED_WARNED_MAX) {
+                const oldest = blockedWarned.keys().next();
+                if (oldest.done !== true)
+                    blockedWarned.delete(oldest.value);
+            }
+            blockedWarned.set(cardToken, fingerprint);
+        }
+        deps.logger?.warn?.("deny_sweep_resume_blocked", { sessionId, ...fields });
+    };
     const denySweepClockGuard = createWallClockJumpGuard({
         slaMs: deps.config.approvalTimeoutSec > 0 ? deps.config.approvalTimeoutSec * 1000 : undefined,
         onJump: ({ jumpMs, graceMs }) => deps.logger?.warn?.("deny_sweep_wall_clock_jump", {
@@ -45,26 +63,38 @@ export function createApprovalSweeps(ctx) {
             return;
         if (!denySweepClockGuard.admit(now))
             return;
-        const expired = await cs.listExpiredApprovalGates(now).catch(() => []);
-        const isParkedOwned = async (sessionId) => {
-            if (deps.backgroundAgentStore === undefined && deps.workflowAgentSessionIndex === undefined)
-                return false;
+        let expired;
+        try {
+            expired = await cs.listExpiredApprovalGates(now);
+        }
+        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),
+                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;
+        }
+        const parkSources = deps.backgroundAgentStore !== undefined || deps.workflowAgentSessionIndex !== undefined;
+        const cardOf = async (sessionId) => {
+            let token;
             try {
-                const token = await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS });
-                if (!token)
-                    return false;
+                token = (await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS })) ?? undefined;
+                if (!parkSources || !token)
+                    return { token, parked: false };
                 const cp = await cs.get(token);
                 if (!cp)
-                    return false;
-                return (await findParkOrigin({
+                    return { token, parked: false };
+                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 })) !== undefined;
+                }, { token, scope: cp.scope, sessionId: cp.sessionId });
+                return { token, parked: origin !== undefined };
             }
             catch {
-                return false;
+                return { token, parked: false };
             }
         };
         const storedBodyUnservable = async (sessionId) => {
@@ -77,8 +107,12 @@ export function createApprovalSweeps(ctx) {
         };
         let parkedSkipped = 0;
         const replaySkipped = [];
+        const seenCards = new Set();
         for (const { sessionId } of expired) {
-            if (await isParkedOwned(sessionId)) {
+            const { token: cardToken, parked } = await cardOf(sessionId);
+            if (cardToken !== undefined)
+                seenCards.add(cardToken);
+            if (parked) {
                 parkedSkipped += 1;
                 continue;
             }
@@ -87,9 +121,16 @@ 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)
-                deps.logger?.warn?.("deny_sweep_resume_blocked", { sessionId, status: r.status, ...blockedScalars(r.body) }); }, (e) => deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: redactHead(e instanceof Error ? e.message : String(e), 2000) }));
+            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)
+                    blockedWarned.delete(cardToken);
+            }, (e) => deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: redactHead(e instanceof Error ? e.message : String(e), 2000) }));
         }
+        for (const token of [...blockedWarned.keys()])
+            if (!seenCards.has(token))
+                blockedWarned.delete(token);
         if (parkedSkipped > 0)
             deps.logger?.info?.("deny_sweep_parked_skipped", { count: parkedSkipped });
         if (replaySkipped.length > 0) {

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

@@ -48,6 +48,7 @@ import type { PermissionMode } from "@sema-agent/core";
 import type { CheckpointCtx } from "./route-ctx.js";
 import type { TaskRequestBody } from "./wire-types.js";
 import type { InertToolListEntry } from "../rule-entry-list.js";
+import { type Refusal } from "./refusal-body.js";
 /** 读法记号的闭集(一词 = 当前读法):这一行体里的 `settings.permissions.allow` 是按「交给引擎的 allow 层」写下、也该按它读的
  *  (与能力位 `settings.permissions.allowLayer` 同一个说法)。 */
 export declare const PERMISSIONS_ALLOW_READINGS: readonly ["allow_layer"];
@@ -98,7 +99,7 @@ export declare function withPermissionModeRewritten(ctx: CheckpointCtx, body: Ta
  *  记号缺席或认不得 ⇒ 不是「按当前读法写下」的证据,与 allow 记号同一条纪律。 */
 export declare function permissionModeReadingStated(ctx: CheckpointCtx): boolean;
 /**
- * 第三问的拒答复 —— 码与落点同 allow 记号那一问(`checkpoint.unsupported_version`,409,`retriable:true` = 那张卡仍 pending,**不是**「原样重试会成功」)。
+ * 第三问的拒答复 —— 码与落点同 allow 记号那一问(`checkpoint.unsupported_version`,409;卡仍 pending 时体上的 `retriable:true` 由 {@link resumeRefusalWithCard} 追加,本铸点不带)。
  * 句子说原因(更早的版本在每次续跑重钳运维的 AUTONOMY、没把它记进任务;本版只在提交时记一次 ⇒ 续跑会按任务提交时的原词跑)与两条出路。
  * 🔴 形是给冻结门看的:`status: <三位数>, body: { error: "<整句双引号字面>", errorCode: "<码>"`,中间只许有空白。
  */
@@ -107,7 +108,6 @@ export declare function permissionModeReadingRefusal(): {
     body: {
         error: string;
         errorCode: string;
-        retriable: true;
     };
 };
 /**
@@ -118,7 +118,7 @@ export declare function allowListReadingUnstated(ctx: CheckpointCtx): boolean;
 /** 被拒的行是哪一代写的(只在 {@link allowListReadingUnstated} 为真时有意义):记号是 `"statement"` ⇒ 表态时代;其余(缺席 / 认不得)⇒ 名单时代。 */
 export declare function allowListReadingEraOf(ctx: CheckpointCtx): AllowListReadingEra;
 /**
- * 拒的答复 —— 码与落点照「退役 mode-seed 行」的先例(`checkpoint.unsupported_version`,409,`retriable:true` = 那张卡仍 pending;**不是**「原样重试会成功」)。
+ * 拒的答复 —— 码与落点照「退役 mode-seed 行」的先例(`checkpoint.unsupported_version`,409;卡仍 pending 时的 `retriable:true` 由 {@link resumeRefusalWithCard} 追加,本铸点不带)。
  * 拒在认领之前,所以没有 `taskId`(行没抢到就不造键)。句子按这一行是哪一代写的分两句(闭集穷举,加一代 ⇒ 编译红):说原因(这条任务停在哪种读法上、
  * 照当前读法续跑会放宽什么)与出路(作为新任务重提,仍停驻的先取消)。
  *
@@ -129,7 +129,6 @@ export declare function allowListReadingRefusal(era: AllowListReadingEra): {
     body: {
         error: string;
         errorCode: string;
-        retriable: true;
     };
 };
 /**
@@ -168,11 +167,24 @@ export interface ResumeRefusalAnswer {
     } & Record<string, unknown>;
 }
 /**
- * 「续跑被一条准入策略挡住」的**唯一**铸点:`resolveSpec` 在重放存量体时抛出的 `HttpError`(400 族)折成 409 `resume_blocked_by_policy`,
- * `blockedBy` = 那条 400 的码(属主 `http/send.ts` `httpErrorCode`),`extra` 原样随体。{@link storedBodyReplayAnswer} 的工具名清单那一臂与
+ * 「续跑被一条准入策略挡住」的**唯一**铸点:`resolveSpec` 在重放存量体时抛出的 `HttpError`(400 族)折成 409 `resume_blocked_by_policy`。
+ * 入参是内层那只拒的 {@link Refusal}(`HttpError` 经 `http/send.ts` 的 `httpErrorRefusal` 读 —— 拆 `HttpError` 的唯一一处,码的属主 `httpErrorCode`):
+ * `blockedBy` = 内层的码,句子 = 前缀 + 内层的句子,内层的机读事实原样随体。{@link storedBodyReplayAnswer} 的工具名清单那一臂与
  * `resume-legs.ts` 的折叠口都调它 —— 句子与码只在这里写一次(冻结门 `api-error-text-freeze` 的模板骨架表锚这一处)。
+ *
+ * 本铸点**不带** `retriable`:那是调用点的事实(有没有一张待批卡仍在等),由 {@link resumeRefusalWithCard} 一处追加 —— 续跑入口(卡仍 pending、run 行留 `suspended`)
+ * 带 `retriable:true`,终态 run 的 steer 在铸唤醒卡之前拒(没有卡)不带。键集 = `errorCode` · `error` · `blockedBy` · (`field` · `reason` · 其余 `extra`,有才在)
+ * · (`retriable`,卡在才在)。
+ */
+export declare function resumeBlockedByPolicyAnswer(inner: Refusal): ResumeRefusalAnswer;
+/**
+ * 🔴 **三类续跑拒体上 `retriable` 的唯一写点**(本服务重放存量体前的拒、准入策略折叠、引擎拒的续跑):卡仍 pending(`cardPending`)⇒ 体尾追加 `retriable: true`;
+ * 否则体原样(键缺席)。这三类拒上规则一条:`retriable` 在场 ⇔ 有一张待批卡仍在等、run 行留 `suspended`(**不是**「原样重试会成功」—— 契约附录 A.1 注那一个意思)。
+ * 门型对不上的早拒(`gate_not_resumable` 一族)不经这里、不带它。三个调用点各交自己的事实:
+ * {@link storedBodyReplayAnswer}(调用方的 `cardPending`)、`resume-legs.ts` 的准入策略折叠口(续跑入口,恒有卡)与 `checkpointRefusalAnswer`(引擎拒的处置读口答 `retriable`)。
+ * 排在体尾:拒绝带来的附带键不得抹掉它。纯函数。
  */
-export declare function resumeBlockedByPolicyAnswer(message: string, blockedBy: string, extra?: Record<string, unknown> | undefined): ResumeRefusalAnswer;
+export declare function resumeRefusalWithCard(answer: ResumeRefusalAnswer, cardPending: boolean): ResumeRefusalAnswer;
 /**
  * `stored-body-replay.ts` `storedBodyReplayRefusal` 的**日志字段**(三处问点同一形,各自只再加坐标键 `sessionId` / `taskId`):`kind` 判别,allow 臂带 `era`、技能臂带 `layer`,`note` 一句出路。
  * 事件名三个(问点各一:`resume_refused_stored_body` / `steer_wake_park_refused_stored_body` / `deny_sweep_stored_body_skipped`),字段形只有这一只。
@@ -189,6 +201,11 @@ export declare function storedBodyReplayLogFields(refusal: StoredBodyReplayRefus
  * `stored-body-replay.ts` `storedBodyReplayRefusal` 的答复:每条规则一只既有铸点(allow 记号 ⇒ {@link allowListReadingRefusal};模式词记号 ⇒ {@link permissionModeReadingRefusal};
  * 这两只答 `checkpoint.unsupported_version`,体按那一码的键律补两版本键,`readerVersion` = 调用方传的本进程服务版本;工具名清单 ⇒ {@link resumeBlockedByPolicyAnswer},与提交腿的 400
  * (该层的拒码:`request.field_invalid` / `config.agent.unknown_tool` / `config.tool_face_control`)同码同句 —— 体上只有这一个问题时;存量体同时还踩中 `resolveSpec` 更早的拒〔三桶超帽 / 托管姿态〕时,提交侧答更早那条、续跑侧答本句,两边都是拒,指路不同)。
+ *
+ * 🔴 `cardPending` —— **调用方交出的事实**:这一次拒的时候,有没有一张待批卡仍在等。`retriable:true` 说的恰是「卡仍 pending」,所以它只在卡在时在场(经
+ * {@link resumeRefusalWithCard} 一处写):续跑入口(`/decide` · `/resume` · `/wake` · plan_review · workflow 决定的新一跑,五个问点里除下面这一个之外全部)传 `true`;
+ * 终态 run 的 `POST /v1/runs/:id/steer` 在**铸唤醒卡之前**就拒,没有卡也没铸卡 ⇒ 传 `false`,体上不带 `retriable`(三条臂同一条律;其余键两种处境逐字相同 —— 同判同答)。
+ * 没有默认值:每个调用点必须说出这件事实。
  */
-export declare function storedBodyReplayAnswer(refusal: StoredBodyReplayRefusal, readerVersion: string): ResumeRefusalAnswer;
+export declare function storedBodyReplayAnswer(refusal: StoredBodyReplayRefusal, readerVersion: string, cardPending: boolean): ResumeRefusalAnswer;
 //# sourceMappingURL=checkpoint-ctx.d.ts.map

package/dist/http/checkpoint-ctx.js

@@ -1,3 +1,4 @@
+import { refusalBody } from "./refusal-body.js";
 export const PERMISSIONS_ALLOW_READINGS = ["allow_layer"];
 export const PERMISSION_MODE_READINGS = ["entry_word"];
 export const ALLOW_LIST_READING_ERAS = ["list", "statement"];
@@ -34,7 +35,6 @@ export function permissionModeReadingRefusal() {
         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.",
             errorCode: "checkpoint.unsupported_version",
-            retriable: true,
         },
     };
 }
@@ -56,7 +56,6 @@ export function allowListReadingRefusal(era) {
                 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.",
                     errorCode: "checkpoint.unsupported_version",
-                    retriable: true,
                 },
             };
         case "statement":
@@ -65,7 +64,6 @@ export function allowListReadingRefusal(era) {
                 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).",
                     errorCode: "checkpoint.unsupported_version",
-                    retriable: true,
                 },
             };
         default: {
@@ -77,12 +75,15 @@ export function allowListReadingRefusal(era) {
 export function buildCheckpointVersionKeys(writerVersion, readerVersion) {
     return writerVersion !== undefined ? { writerVersion, readerVersion } : {};
 }
-export function resumeBlockedByPolicyAnswer(message, blockedBy, extra) {
+export function resumeBlockedByPolicyAnswer(inner) {
     return {
         status: 409,
-        body: { error: `resume blocked by an admission policy change: ${message}`, errorCode: "resume_blocked_by_policy", blockedBy, ...(extra ?? {}) },
+        body: refusalBody({ errorCode: "resume_blocked_by_policy", message: `resume blocked by an admission policy change: ${inner.message}`, facts: { blockedBy: inner.errorCode, ...inner.facts } }),
     };
 }
+export function resumeRefusalWithCard(answer, cardPending) {
+    return cardPending ? { status: answer.status, body: { ...answer.body, retriable: true } } : answer;
+}
 export function storedBodyReplayLogFields(refusal) {
     switch (refusal.kind) {
         case "allow_list_reading":
@@ -97,14 +98,17 @@ export function storedBodyReplayLogFields(refusal) {
         }
     }
 }
-export function storedBodyReplayAnswer(refusal, readerVersion) {
+export function storedBodyReplayAnswer(refusal, readerVersion, cardPending) {
+    return resumeRefusalWithCard(storedBodyReplayArmAnswer(refusal, readerVersion), cardPending);
+}
+function storedBodyReplayArmAnswer(refusal, readerVersion) {
     switch (refusal.kind) {
         case "allow_list_reading": {
             const answer = allowListReadingRefusal(refusal.era);
             return { status: answer.status, body: { ...answer.body, ...buildCheckpointVersionKeys(refusal.writerVersion, readerVersion) } };
         }
         case "inert_tool_list":
-            return resumeBlockedByPolicyAnswer(refusal.entry.message, refusal.entry.code, refusal.entry.extra !== undefined ? { ...refusal.entry.extra } : undefined);
+            return resumeBlockedByPolicyAnswer(refusal.entry.extra === undefined ? { errorCode: refusal.entry.code, message: refusal.entry.message } : { errorCode: refusal.entry.code, message: refusal.entry.message, facts: refusal.entry.extra });
         case "permission_mode_reading": {
             const answer = permissionModeReadingRefusal();
             return { status: answer.status, body: { ...answer.body, ...buildCheckpointVersionKeys(refusal.writerVersion, readerVersion) } };

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

@@ -0,0 +1,13 @@
+/**
+ * 一条提交腿**刚认领**的 run 在起跑之前就收场 —— 撤掉本请求建的东西的**唯一**写法。两个调用点:device 落点拒
+ * (`device-placement.ts` `commitPlacement`)与续跑输入写不进(`submit-ctx.ts` `persistSubmitCtx`)。
+ *
+ * 撤两步,**各自独立**(一步失败不拦另一步,残余最小):
+ *  · 终结这条 run 行(`setTerminal` 是按 taskId 的 CAS,首写者赢 ⇒ 重复调用是 no-op)—— 随之释放它的 `task_active` 认领;
+ *  · 放开它占的提交幂等键(拒绝答复邀请重试;同键重试必须真跑,不是回放这次拒绝 —— `RunStore.releaseIdemKey`)。
+ * 撤不掉不致命、但要响:每一步的失败各交给调用方按自己的名字留痕(`onFailure`)。终结没落下 ⇒ 此刻心跳还没起来,`reapStale`
+ * 在 `REAP_RUN_STALE_SEC` 之后把这条行翻 failed 并释放会话;幂等键没放开 ⇒ 同键重提回放这条行的回执(两形都是修前每一次的样子)。
+ */
+import type { RunStore } from "../plugins/store-backend.js";
+export declare function releaseClaimedRun(runStore: Pick<RunStore, "setTerminal" | "releaseIdemKey">, taskId: string, why: string, onFailure: (err: unknown, step: "terminal" | "idem_key") => void): Promise<void>;
+//# sourceMappingURL=claimed-run.d.ts.map

package/dist/http/claimed-run.js

@@ -0,0 +1,15 @@
+export async function releaseClaimedRun(runStore, taskId, why, onFailure) {
+    try {
+        await runStore.setTerminal(taskId, "failed", null, why);
+    }
+    catch (err) {
+        onFailure(err, "terminal");
+    }
+    try {
+        await runStore.releaseIdemKey(taskId);
+    }
+    catch (err) {
+        onFailure(err, "idem_key");
+    }
+}
+//# sourceMappingURL=claimed-run.js.map

package/dist/http/device-placement.js

@@ -2,6 +2,7 @@ import { createCodedHttpError, ssoVerifiedScope } from "../security.js";
 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";
 export function deviceOwnerDomainOf(req, config) {
     const subject = gatedPrincipal(req, config);
     if (subject === undefined)
@@ -89,16 +90,10 @@ export async function commitPlacement(ctx, runStore, taskId, intent) {
     if (intent === undefined)
         return null;
     const enrollment = ctx.deviceEnrollment;
-    const releaseRun = async (why) => {
-        try {
-            await runStore.setTerminal(taskId, "failed", null, why);
-            await runStore.releaseIdemKey(taskId);
-        }
-        catch (err) {
-            ctx.logger?.warn("device_placement_run_release_failed", { taskId, err: err instanceof Error ? err.message : String(err) });
-            ctx.metrics?.inc("device_placement_run_release_failed_total");
-        }
-    };
+    const releaseRun = (why) => releaseClaimedRun(runStore, taskId, why, (err, step) => {
+        ctx.logger?.warn("device_placement_run_release_failed", { taskId, step, err: err instanceof Error ? err.message : String(err) });
+        ctx.metrics?.inc("device_placement_run_release_failed_total");
+    });
     if (!enrollment) {
         await releaseRun("device placement could not be committed: the device lane's admission chain is not wired");
         throw new Error("commitPlacement: a device placement intent was minted without a DeviceEnrollment — assembly bug (both are read from the same ServiceDeps)");

package/dist/http/dispatch.d.ts

@@ -18,10 +18,6 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { ServiceConfig } from "../config-types.js";
 import type { RouteCtxBase, RunRegistry } from "./route-ctx.js";
 import type { FlatServiceDeps } from "./server.js";
-/** 「这台部署配了任何一把 service 凭证吗」—— fail-closed 写门族的真值源。**单一属主**:`handle()` 的
- *  凭证门、[ref] 的 parked 赎回席、以及 [ref] 的 consolidation 阀门启动期告警读同一句(手抄迟早
- *  只改一处,而这条判据决定的是「无凭证部署上写口开不开」)。导出仅为最后一个消费点(main.ts)。 */
-export declare function hasServiceAuth(config: ServiceConfig): boolean;
 /**
  * 🔴 S-672(test T-72 [ref];主会话裁 ①,分诊 [ref])—— 全局服务凭据门**之前**那几族只读路
  * (`route-table.ts` 里 `position: "read-credential"` 的行)的**唯一**鉴权谓词:「服务凭据 ∨ 已验 principal」。