@sema-agent/server 7.131.0 → 7.133.0

package/dist/per-task-image.js

@@ -3,15 +3,15 @@ const REQUESTABLE_CAPS = new Set(["browser", "db", "nestedBuild"]);
 export async function resolveSandboxImageRef(opts) {
     const entry = await opts.index.latestPublished(opts.profile, opts.viewer);
     if (!entry) {
-        return { ok: false, status: 404, message: `no published sandbox image for profile "${opts.profile}" visible to this principal` };
+        return { ok: false, status: 404, errorCode: "not_found.image", message: `no published sandbox image for profile "${opts.profile}" visible to this principal` };
     }
     const caps = entry.capabilities;
     for (const cap of opts.capabilitiesNeeded ?? []) {
         if (!REQUESTABLE_CAPS.has(cap)) {
-            return { ok: false, status: 400, message: `unknown sandbox capability "${cap}" (allowed: ${[...REQUESTABLE_CAPS].join(", ")})` };
+            return { ok: false, status: 400, errorCode: "request.field_invalid", message: `unknown sandbox capability "${cap}" (allowed: ${[...REQUESTABLE_CAPS].join(", ")})` };
         }
         if (caps[cap] !== true) {
-            return { ok: false, status: 404, message: `sandbox image for profile "${opts.profile}" does not provide capability "${cap}"` };
+            return { ok: false, status: 404, errorCode: "not_found.image", message: `sandbox image for profile "${opts.profile}" does not provide capability "${cap}"` };
         }
     }
     return { ok: true, ref: `${entry.repo}@${entry.digest}`, capabilities: entry.capabilities };

package/dist/permission-rule-list.d.ts

@@ -6,7 +6,7 @@
  * `TaskSpec.allowedTools`(`task-settings.ts` 的 `applyTaskSettings`),运维的 `APPROVAL_GRANT` 投 `RunnerDeps.allowedTools`
  * (`boot/runner-deps.ts` 的部署姿态座席族)。本口的 `behavior` 型直接是 core 的 `PermissionRule["behavior"]`(不手抄:core 收窄,这里跟着收窄)。
  *
- * 为什么住在一只叶模块里(不留在 `task-settings.ts`):本模块只 import core 与 `text-bidi.ts`(纯叶),读者引它不成环。
+ * 为什么住在一只叶模块里(不留在 `task-settings.ts`):本模块只 import core 与契约包 settings-schema(纯叶),读者引它不成环。
  */
 import { type PathRuleBases, type PermissionRule, type ToolPolicy } from "@sema-agent/core";
 /** 一张表里规则条数的上限 —— 请求腿 wire 门(`task-settings.ts` 的 deny / ask 两桶判形)读的也是这一个名字:core 的缺省帽是 256,

package/dist/permission-rule-list.js

@@ -1,5 +1,5 @@
 import { createPermissionRulePolicy } from "@sema-agent/core";
-import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
+import { stripControlAndBidi } from "@sema-agent/settings-schema";
 export const MAX_PERMISSION_RULES_PER_LIST = 1_000;
 export function createRuleListPolicy(names, behavior, source, pathBases) {
     try {
@@ -10,7 +10,7 @@ export function createRuleListPolicy(names, behavior, source, pathBases) {
         });
     }
     catch (e) {
-        const coreMsg = (e instanceof Error ? e.message : String(e)).replace(CONTROL_AND_BIDI_STRIP_RE, "");
+        const coreMsg = stripControlAndBidi(e instanceof Error ? e.message : String(e));
         throw new Error(`${source.replace("settings.", "")} has rule(s) core cannot compile — ${coreMsg}`, { cause: e });
     }
 }

package/dist/plain-string-record.d.ts

@@ -0,0 +1,25 @@
+/** 一个没进副本的成员:名字(调用方写的,原样;回显前由调用点清洗)与它为什么不能交(只说种类,不回显值)。 */
+export interface PlainStringRecordMemberFault {
+    readonly name: string;
+    readonly fault: string;
+}
+/**
+ * {@link readPlainStringRecord} 的读数(见模块头注的律):`ok:false` = 记录不交(`fault` 只说种类;坏在某个成员时 `member` 点名它);
+ * `ok:true` = 交出去的纯数据副本 + 被剔掉的 `__proto__` 名成员(按记录里的顺序;恒只有这一种成员会被剔)。
+ * `ok:false` 的 `fault` 是接在「its member "<名>" 」后面的原因句;成员名恰是 `__proto__` 而值也坏时,这一句同时说两件事(名不许、值必须是串)。
+ */
+export type PlainStringRecordRead = {
+    readonly ok: true;
+    readonly record: Record<string, string>;
+    readonly stripped: readonly PlainStringRecordMemberFault[];
+} | {
+    readonly ok: false;
+    readonly fault: string;
+    readonly member?: string;
+};
+/**
+ * 读一份「名 → 串」记录(见模块头注的律)。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算,与引擎收据同读法),值按属性描述读:
+ * 数据属性取值,访问器调一次。先判每个成员的值(`__proto__` 名的成员也判:它的值不是串 ⇒ 整只不交,与 7.131.x 同),再剔 `__proto__` 名。调用方的对象不被交出去、也不被改。
+ */
+export declare function readPlainStringRecord(v: unknown): PlainStringRecordRead;
+//# sourceMappingURL=plain-string-record.d.ts.map

package/dist/plain-string-record.js

@@ -0,0 +1,32 @@
+import { describeValueShape } from "@sema-agent/settings-schema";
+const PROTO_MEMBER_FAULT = 'no member of a declaration may be named "__proto__"';
+export function readPlainStringRecord(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return { ok: false, fault: v === null ? "got null" : Array.isArray(v) ? "got an array" : `got a ${typeof v}` };
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null)
+        return { ok: false, fault: "got an object that is not plain data (a class instance, a Map, process.env, or a record built on a prototype; copy it into a plain object)" };
+    const record = {};
+    const stripped = [];
+    for (const name of Object.getOwnPropertyNames(v)) {
+        const d = Object.getOwnPropertyDescriptor(v, name);
+        let value;
+        let unreadable = false;
+        try {
+            value = d === undefined ? undefined : Object.hasOwn(d, "value") ? d.value : d.get === undefined ? undefined : Reflect.apply(d.get, v, []);
+        }
+        catch {
+            unreadable = true;
+        }
+        if (unreadable || typeof value !== "string") {
+            const valueFault = unreadable ? "could not be read (its getter threw)" : `must be a string — got ${describeValueShape(value)}`;
+            return { ok: false, fault: name === "__proto__" ? `is not allowed (${PROTO_MEMBER_FAULT}) and its value ${valueFault}` : valueFault, member: name };
+        }
+        if (name === "__proto__")
+            stripped.push({ name, fault: PROTO_MEMBER_FAULT });
+        else
+            record[name] = value;
+    }
+    return { ok: true, record, stripped };
+}
+//# sourceMappingURL=plain-string-record.js.map

package/dist/plugins/approval-ask-store-file.d.ts

@@ -22,7 +22,7 @@ export declare const ASK_JOURNAL_COMPACT_GROWTH = 2;
  * 账本的**动词闭集**([ref] 形)。运行期的词表判定与编译期的穷尽 `switch` 读同一份:
  * 往这里加一个词,{@link FileApprovalAskStore.replayOp} 的 switch 立刻编译红(漏一口不可能发布)。
  */
-declare const JOURNAL_OPS: readonly ["ensureAsk", "transitionAsk", "decideAsk", "claimTerminal", "claimTerminalRefuse", "expireAsk", "bindBatch", "abortBatch", "deferReconcile", "resolveProvisional", "deleteByTask"];
+declare const JOURNAL_OPS: readonly ["ensureAsk", "transitionAsk", "decideAsk", "claimTerminal", "claimTerminalRefuse", "expireAsk", "bindBatch", "abortBatch", "deferReconcile", "resolveProvisional", "deleteByTask", "reapSettledAsks", "reapEmptyBatches"];
 type JournalOpWord = (typeof JOURNAL_OPS)[number];
 /** 运行期词表(上面的数组)与类型面动词维({@link JournalCall})的**双向**对表 —— 任一边加词而另一边
  *  没跟上,这个别名解析成 `never`,{@link JOURNAL_OP_TABLE_GATE} 的赋值当场编译红。 */
@@ -96,6 +96,17 @@ type JournalCall = {
 } | {
     op: "deleteByTask";
     taskId: string;
+}
+/** 留存律的问账两半(挂靠集落成数组;Set 不是 JSON)。更老的读者不认这两个动词 ⇒ 拒启并点名出路(与 `claimTerminalRefuse` 同一条降级纪律)。 */
+ | {
+    op: "reapSettledAsks";
+    cutoffMs: number;
+    limit: number;
+    keepAnchors: string[];
+} | {
+    op: "reapEmptyBatches";
+    cutoffMs: number;
+    limit: number;
 };
 export declare class FileApprovalAskStore implements ApprovalAskStore {
     /** 语义内核(转移判定的唯一真源)。本类对它只做两件事:重放、代理。 */
@@ -171,6 +182,10 @@ export declare class FileApprovalAskStore implements ApprovalAskStore {
     deferReconcile(askId: string, expectedState: AskState, expectedRev: number, nowMs: number): Promise<boolean>;
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
+    /** 留存律的问行半场(谓词在内核,见接口注)。空的一次(内核的纯读选择为空)不落账本、不碰内存;否则照常「先落账、再翻内存」。 */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /** 留存律的批行半场(同上)。 */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
     listByState(state: AskState, limit: number): Promise<AskRow[]>;
     listPendingByTask(taskId: string, signal?: AbortSignal): Promise<AskRow[]>;
     listPendingBySession(sessionId: string, owner: string | null, signal?: AbortSignal): Promise<AskRow[]>;

package/dist/plugins/approval-ask-store-file.js

@@ -21,6 +21,8 @@ const JOURNAL_OPS = [
     "deferReconcile",
     "resolveProvisional",
     "deleteByTask",
+    "reapSettledAsks",
+    "reapEmptyBatches",
 ];
 const JOURNAL_OP_WORDS = new Set(JOURNAL_OPS);
 export const JOURNAL_OP_TABLE_GATE = true;
@@ -159,6 +161,11 @@ export class FileApprovalAskStore {
             refuse("call record without a clock reading");
         if (probe.op === "claimTerminal" && !JOURNAL_V1_CLAIM_INTENT_WORDS.has(String(raw.intent)))
             refuse("claimTerminal intent outside this build's journal set (a newer server wrote it)");
+        if (probe.op === "reapSettledAsks") {
+            const anchors = raw.keepAnchors;
+            if (!Array.isArray(anchors) || !anchors.every((a) => typeof a === "string"))
+                refuse("reapSettledAsks record without a string-array keepAnchors");
+        }
         const rec = raw;
         this.pinnedNow = rec.t;
         try {
@@ -197,6 +204,10 @@ export class FileApprovalAskStore {
                 return this.core.resolveProvisional(rec.askId, rec.from, rec.to, rec.patch);
             case "deleteByTask":
                 return this.core.deleteByTask(rec.taskId);
+            case "reapSettledAsks":
+                return this.core.reapSettledAsks(rec.cutoffMs, rec.limit, new Set(rec.keepAnchors));
+            case "reapEmptyBatches":
+                return this.core.reapEmptyBatches(rec.cutoffMs, rec.limit);
             default: {
                 const unreachable = rec;
                 throw new Error(`FileApprovalAskStore: unreachable journal op ${JSON.stringify(unreachable)}`);
@@ -244,6 +255,16 @@ export class FileApprovalAskStore {
     async deleteByTask(taskId) {
         return this.write({ op: "deleteByTask", taskId }, (c) => this.core.deleteByTask(c.taskId));
     }
+    async reapSettledAsks(cutoffMs, limit, keepAnchors) {
+        if (this.core.planReapSettledAsks(cutoffMs, limit, keepAnchors).length === 0)
+            return 0;
+        return this.write({ op: "reapSettledAsks", cutoffMs, limit, keepAnchors: [...keepAnchors].sort() }, (c) => this.core.reapSettledAsks(c.cutoffMs, c.limit, new Set(c.keepAnchors)));
+    }
+    async reapEmptyBatches(cutoffMs, limit) {
+        if (this.core.planReapEmptyBatches(cutoffMs, limit).length === 0)
+            return 0;
+        return this.write({ op: "reapEmptyBatches", cutoffMs, limit }, (c) => this.core.reapEmptyBatches(c.cutoffMs, c.limit));
+    }
     listByState(state, limit) {
         return this.core.listByState(state, limit);
     }

package/dist/plugins/approval-ask-store-memory.d.ts

@@ -6,7 +6,7 @@
  *
  * 🔴 **S-384:本类同时是 `FileApprovalAskStore` 的内核**(local 车道的持久形不再是「第二份手抄」——
  * 它把本类**原样**包起来,每次写前先把**调用本身**落 JSONL、重放时用同一只内核重放同一串调用)。
- * 为此本类多了三件、且**只**多这三件(全是数据面,零转移判定):
+ * 为此本类多了这几件、且**只**多这几件(全是数据面,零转移判定):
  *  · {@link InMemoryApprovalAskStore.constructor} 的可注入钟 `now` —— 五个动词(decideAsk / claimTerminal /
  *    expireAsk / bindBatch / abortBatch)原先直读 `Date.now()`,那是重放路上唯一的不确定源:同一串调用
  *    重放出来的 `updatedAtMs`/`decidedAtMs` 必须与当初**逐字节**相同,否则「重放等价」是假的。
@@ -16,6 +16,8 @@
  *  · {@link InMemoryApprovalAskStore.exportRows} / {@link InMemoryApprovalAskStore.importRows} —— 压实用的
  *    整本快照口(纯搬行,不经任何谓词)。压实要把「一串调用」折成「一串终局行」,没有这一对就只能在
  *    File 形里另写一套「哪些行还算数」的判据 —— 那才是第二份手抄。
+ *  · {@link InMemoryApprovalAskStore.planReapSettledAsks} / {@link InMemoryApprovalAskStore.planReapEmptyBatches} —— 两只留存动词的
+ *    **纯读选择**(删哪些行)。File 形据它判「这一次有没有东西可删」,空的一次不落账本;删除本身仍是接口动词,与选择共用这一只。
  *
  * 行为口径与 `SqlApprovalAskStore` 逐条对齐:
  *  - ensureAsk 幂等 upsert(ask_id 已在 ⇒ 返回既有行,不改写;batch 行若不存在则以 OPEN 补齐）。
@@ -106,6 +108,21 @@ export declare class InMemoryApprovalAskStore implements ApprovalAskStore {
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
     getBatch(batchId: string): Promise<BatchRow | null>;
+    /**
+     * 留存律的问行半场(谓词见接口注,与 SQL twin 的 `DELETE … LIMIT` 同答)。方法体全同步(零 `await`)⇒ File 形把它当一次落账的调用
+     * 重放时逐字复现(cutoff / limit / 挂靠集都是调用实参,不读钟)。
+     */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /** 留存律的批行半场(谓词见接口注,与 SQL twin 同答;同上,全同步)。 */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
+    /**
+     * 两只留存动词会删哪些行(纯读,零写)。File 形据此判「这一次有没有东西可删」—— 空的一次不落账本(否则每次清扫都往账本里写一条什么都
+     * 没做的调用)。与删除共用这一只选择,没有第二份谓词。选哪几只:按 `(updatedAtMs, id)` 升序取前 `limit` 只 —— 确定性只为重放,律本身
+     * 不依赖次序(SQL twin 不排序)。
+     */
+    planReapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): readonly string[];
+    /** {@link reapEmptyBatches} 的选择(同上)。 */
+    planReapEmptyBatches(cutoffMs: number, limit: number): readonly string[];
 }
 export type { AskDecision, AskState, BatchState };
 //# sourceMappingURL=approval-ask-store-memory.d.ts.map

package/dist/plugins/approval-ask-store-memory.js

@@ -1,6 +1,6 @@
-import { canAskTransition } from "../approval-ask-machine.js";
+import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
 import { APPROVAL_ENDING_CAUSES } from "../approval-deny-reasons.js";
-import { askRowOnCall, assertDecideSettledBy, assertIdempotencyKeyShape, assertIntegralEpochMs, ApprovalAskReadAbortedError, claimTargetState, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./approval-ask-store-sql.js";
+import { askRowOnCall, assertDecideSettledBy, assertIdempotencyKeyShape, assertIntegralEpochMs, assertReapBounds, ApprovalAskReadAbortedError, claimTargetState, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./approval-ask-store-sql.js";
 function applyPatch(row, patch) {
     if (patch.decision !== undefined)
         row.decision = patch.decision;
@@ -359,5 +359,37 @@ export class InMemoryApprovalAskStore {
         const b = this.batches.get(batchId);
         return b ? { ...b } : null;
     }
+    async reapSettledAsks(cutoffMs, limit, keepAnchors) {
+        const ids = this.planReapSettledAsks(cutoffMs, limit, keepAnchors);
+        for (const id of ids)
+            this.asks.delete(id);
+        return ids.length;
+    }
+    async reapEmptyBatches(cutoffMs, limit) {
+        const ids = this.planReapEmptyBatches(cutoffMs, limit);
+        for (const id of ids)
+            this.batches.delete(id);
+        return ids.length;
+    }
+    planReapSettledAsks(cutoffMs, limit, keepAnchors) {
+        assertReapBounds(cutoffMs, limit);
+        const anchored = (r) => keepAnchors.has(r.taskId) || keepAnchors.has(r.sessionId) || keepAnchors.has(r.sourceTaskId);
+        return [...this.asks.values()]
+            .filter((r) => ASK_TERMINAL.has(r.state) && !r.provisional && r.updatedAtMs < cutoffMs && !anchored(r))
+            .sort((a, b) => a.updatedAtMs - b.updatedAtMs || (a.askId < b.askId ? -1 : a.askId > b.askId ? 1 : 0))
+            .slice(0, limit)
+            .map((r) => r.askId);
+    }
+    planReapEmptyBatches(cutoffMs, limit) {
+        assertReapBounds(cutoffMs, limit);
+        const occupied = new Set();
+        for (const r of this.asks.values())
+            occupied.add(r.batchId);
+        return [...this.batches.values()]
+            .filter((b) => b.updatedAtMs < cutoffMs && !occupied.has(b.batchId))
+            .sort((a, b) => a.updatedAtMs - b.updatedAtMs || (a.batchId < b.batchId ? -1 : a.batchId > b.batchId ? 1 : 0))
+            .slice(0, limit)
+            .map((b) => b.batchId);
+    }
 }
 //# sourceMappingURL=approval-ask-store-memory.js.map

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -268,6 +268,8 @@ export type DecideResult = {
  *  隐式截断 —— 两方言不同答;这里改成两方言同一句 TypeError(响亮,点名字段与值),铸点侧(`tool-approval.ts`
  *  的 deadline 铸点)负责给整数,本守卫只拦漏网。 */
 export declare function assertIntegralEpochMs(field: string, value: number): void;
+/** 留存动词两只的入参门(三 twin 同判):cutoff 是整数毫秒、limit 是正整数(limit 在 SQL twin 里内联进语句)。 */
+export declare function assertReapBounds(cutoffMs: number, limit: number): void;
 export declare function assertIdempotencyKeyShape(key: string): void;
 /** `settled_by` 列宽 = 这一格的唯一尺(两方言 DDL 与下面的形门读同一个常量,不手抄第二份)。 */
 export declare const MAX_SETTLED_BY_CHARS = 16;
@@ -510,6 +512,21 @@ export interface ApprovalAskStore {
     getByIdempotencyKey(taskId: string, key: string): Promise<AskRow | null>;
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
+    /**
+     * **审批账本留存律的问账半场之一:问行**(律、节律与「还能动的 run」一处成文在 `approval-ask-retention.ts`;维护 tick 是唯一调用方)。
+     * 删至多 `limit` 只**结了**的问行 —— `state ∈ ASK_TERMINAL` ∧ `provisional = false`(provisional 行还能被 {@link resolveProvisional} 改判,没结)
+     * ∧ `updatedAtMs < cutoffMs` ∧ 行挂靠的三格(`taskId` / `sessionId` / `sourceTaskId`)都不在 `keepAnchors`(还能动的东西的挂靠集:
+     * 它还会回读这些行 —— 会话授权的争议判据 {@link listByCall} 把「这次调用在腿内没有行」读成可以代答)。非终态行多老都不删(它们归对账器
+     * 与起服收敛)。只删不改。
+     * 一条语句:要么删了并交回删掉的行数,要么一行没删就抛。三形同答(InMemory = 内核;File 形把这次调用照常落成一条账本动词,
+     * 空的一次不落;SQL 两方言 = 一条 `DELETE … LIMIT`,行谓词,多副本同扫只是一方删到零行)。
+     */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /**
+     * **问账半场之二:批行**。删至多 `limit` 只批里已经**没有任何问行**、且自己的 `updatedAtMs < cutoffMs` 的批 —— 批是问的容器,问走光了它才走。
+     * 一条语句,同上;三形同答。
+     */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
     /** 🔴 车1 追加(不在设计定稿 §4 的接口字面清单里):设计的 `ApprovalAskStore` 接口本身没有批读方法,
      *  但 §6 测试钉(3/6/7 条)要求断言批行的 state/boundAskId 变化——没有读口就无法验证 store 真做对了
      *  它自己承诺的事。加一个纯观测方法(不改变任何写路径行为),SQL 双方言 + InMemory 三形都实现,
@@ -667,6 +684,14 @@ export declare class SqlApprovalAskStore implements ApprovalAskStore {
     deferReconcile(askId: string, expectedState: AskState, expectedRev: number, nowMs: number): Promise<boolean>;
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
+    /**
+     * 留存律的问行半场(谓词见接口注)。一条带 `LIMIT` 的 `DELETE`(PG 无 `DELETE … LIMIT` ⇒ `ctid IN (SELECT … LIMIT)`,与
+     * `permission-rule-store-sql.ts` 的清扫同形);终态闭集从 {@link ASK_TERMINAL} 展开成占位符,不在 SQL 里手抄态名;挂靠集对三格各一句
+     * (MySQL `NOT IN (?, …)` 三次展开、PG 同一只 `text[]` 参数用三次 `<> ALL`),空集不加。`limit` 先过整数门再内联(本仓常量,门只防将来的误用)。
+     */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /** 留存律的批行半场(谓词见接口注):一条带 `LIMIT` 的 `DELETE`,批里有没有问 = 对问表的 `NOT EXISTS`。 */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
     getBatch(batchId: string): Promise<BatchRow | null>;
 }
 /** MySQL-protocol(TiDB)绑定。 */

package/dist/plugins/approval-ask-store-sql.js

@@ -1,5 +1,5 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
-import { canAskTransition } from "../approval-ask-machine.js";
+import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
 import { APPROVAL_ENDING_CAUSES, causeOfAskRow } from "../approval-deny-reasons.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
@@ -9,6 +9,11 @@ export function assertIntegralEpochMs(field, value) {
         throw new TypeError(`approval-ask store: ${field} must be an integer epoch-ms (BIGINT column), got ${String(value)}`);
     }
 }
+export function assertReapBounds(cutoffMs, limit) {
+    assertIntegralEpochMs("cutoffMs", cutoffMs);
+    if (!Number.isSafeInteger(limit) || limit <= 0)
+        throw new Error(`approval-ask-store: reap limit must be a positive integer, got ${String(limit)}`);
+}
 export function assertIdempotencyKeyShape(key) {
     if (key.length === 0 || key.length > 255 || key.trim() !== key) {
         throw new Error(`invalid idempotency key: must be 1-255 chars with no leading/trailing whitespace (got ${JSON.stringify(key.slice(0, 32))}${key.length > 32 ? "…" : ""}, length ${key.length})`);
@@ -722,6 +727,37 @@ export class SqlApprovalAskStore {
         await this.db.query(this.q(`DELETE FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ?`, `DELETE FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1`), [taskId]);
         await this.db.query(this.q(`DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE task_id = ?`, `DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE task_id = $1`), [taskId]);
     }
+    async reapSettledAsks(cutoffMs, limit, keepAnchors) {
+        assertReapBounds(cutoffMs, limit);
+        const terminal = [...ASK_TERMINAL];
+        const keep = [...keepAnchors];
+        const dialect = this.db.dialect;
+        let n = 0;
+        const statePh = terminal.map(() => ph(dialect, ++n)).join(", ");
+        const cutPh = ph(dialect, ++n);
+        const ANCHOR_COLUMNS = ["task_id", "session_id", "source_task_id"];
+        let keepSql = "";
+        let keepParams = [];
+        if (keep.length > 0 && dialect === "tidb") {
+            const list = keep.map(() => "?").join(", ");
+            keepSql = ANCHOR_COLUMNS.map((c) => ` AND ${c} NOT IN (${list})`).join("");
+            keepParams = ANCHOR_COLUMNS.flatMap(() => keep);
+        }
+        else if (keep.length > 0) {
+            const arr = ph(dialect, ++n);
+            keepSql = ANCHOR_COLUMNS.map((c) => ` AND ${c} <> ALL(${arr}::text[])`).join("");
+            keepParams = [keep];
+        }
+        const where = `state IN (${statePh}) AND provisional = 0 AND updated_at_ms < ${cutPh}${keepSql}`;
+        const params = [...terminal, cutoffMs, ...keepParams];
+        const res = await this.db.query(this.q(`DELETE FROM ${APPROVAL_ASK_TABLE} WHERE ${where} LIMIT ${limit}`, `DELETE FROM ${APPROVAL_ASK_TABLE} WHERE ctid IN (SELECT ctid FROM ${APPROVAL_ASK_TABLE} WHERE ${where} LIMIT ${limit})`), params);
+        return res.affected;
+    }
+    async reapEmptyBatches(cutoffMs, limit) {
+        assertReapBounds(cutoffMs, limit);
+        const res = await this.db.query(this.q(`DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE updated_at_ms < ? AND NOT EXISTS (SELECT 1 FROM ${APPROVAL_ASK_TABLE} a WHERE a.batch_id = ${APPROVAL_BATCH_TABLE}.batch_id) LIMIT ${limit}`, `DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE ctid IN (SELECT b.ctid FROM ${APPROVAL_BATCH_TABLE} b WHERE b.updated_at_ms < $1 AND NOT EXISTS (SELECT 1 FROM ${APPROVAL_ASK_TABLE} a WHERE a.batch_id = b.batch_id) LIMIT ${limit})`), [cutoffMs]);
+        return res.affected;
+    }
     async getBatch(batchId) {
         const { rows } = await this.db.query(this.q(`SELECT ${BATCH_COLS} FROM ${APPROVAL_BATCH_TABLE} WHERE batch_id = ?`, `SELECT ${BATCH_COLS} FROM ${APPROVAL_BATCH_TABLE} WHERE batch_id = $1`), [batchId]);
         return rows[0] ? mapBatchRow(rows[0]) : null;

package/dist/plugins/blob-backend.d.ts

@@ -1,19 +1,79 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-/** (a)(clay 拍 a+c,2026-07-27)tidb 方言的默认 per-blob 帽 = **6 MiB,TiDB 自己的默认
- *  `txn-entry-size-limit`**。两堵墙真库实测(k3s8 tidb-test v7.5.1 默认配置,2026-07-27 探针):
- *  7MiB=`entry too large`(entry 墙,默认 6291456)、31MiB=同、32MiB=`max_allowed_packet`(包墙,
- *  64MiB ÷ ~2× 文本协议膨胀)——矮墙是 entry 的 6MiB,不是先前推测的包墙 ~31MiB。帽=诚实拒绝:
- *  超限 blob 在 query 之前 typed 拒(消费面 HTTP 413 / capture warn 拿到可行动信息);**帽拒绝的
- *  在默认配置下本来也落不进去 ⇒ 零回归**。调大过 entry 限/packet 的部署用 SNAPSHOT_BLOB_SQL_MAX_BYTES
- *  放宽(两方言都生效)。**pg 方言默认不设帽**(扩展协议无这两堵墙,不人为降档)。D-1 附件战役同墙
- *  教训:task-attachment-store.ts:19。 */
-export declare const SQL_BLOB_DEFAULT_MAX_BYTES = 6291456;
+import { type SqlEngineFacts, type SqlEngineReading, type SqlWallSource, type SqlWallsReading } from "./sql-driver.js";
+import { type Logger } from "../observability/logger.js";
+/**
+ * 文本协议的 blob 膨胀律 —— mysql2 `query()` 把 Buffer 参数写成 `X'<hex>'`,一字节两个字符,所以承载一个 blob 的语句至少是它的 2 倍。
+ * 包墙折成「能装下多大的 blob」只用这一只常量,推导里不手写 `/ 2`。
+ */
+export declare const SQL_TEXT_PROTOCOL_BLOB_INFLATION = 2;
+/**
+ * 包墙下能装多大的 blob:语句里的载荷量({@link packetWallStatementBytes})再按 {@link SQL_TEXT_PROTOCOL_BLOB_INFLATION} 折半。
+ * blob 以十六进制字面进语句、有 2× —— 膨胀律是 blob 腿自己的,余量不是。
+ */
+export declare function packetWallBlobCap(maxPacketBytes: number): number;
+/**
+ * SQL 快照 blob 的**缺省**帽(运维没设 `SNAPSHOT_BLOB_SQL_MAX_BYTES` 时)的唯一推导 —— 入参是判官 `sqlWallsOf` 给的墙(不读事实、不判缺席、不看方言),**两堵墙取最小**:
+ * 行墙腿(`SqlEngineFacts.maxRowBytes`,TiDB:{@link rowWallPayloadBytes} 的 `blob` = 行墙 − blob 行的余量 1 KiB —— 按这一行的真实形算,不借 JSON 提交体行的 64 KiB)
+ * 与包墙腿(`SqlEngineFacts.maxPacketBytes`,InnoDB 与 TiDB 都有:{@link packetWallBlobCap} = ⌊(包墙 − 1 KiB 语句余量) ÷ 2⌋)。余量只在 `sql-driver.ts` 定义一次
+ * (墙 × 行的形各一只),提交体受理口(`http/request-guards.ts` `refuseSubmitBody`)读同一张表的 `json` 那一只,不各抄。
+ * 墙的 `null` 只表示「这堵墙不存在」;两堵都不存在(PG —— 扩展协议无这两堵墙 —— 或没有 SQL 后端)⇒ `undefined` 不设帽。
+ * 「事实本身缺席」不是这里的入参:店的写前判读的是借出连接自己的事实(恒已建立,见 {@link SqlConnectionReading}),缺席的读法只在提交受理口读池级读口时出现(判官 `sqlWallsOf` 给墙)。
+ * 显式旋钮是运维的策略帽,在本推导之上(见 {@link sqlBlobCapBytes})。
+ *
+ * 两堵墙的真库读数(clay 拍 a+c,2026-07-27;k3s8 tidb-test v7.5.1 默认配置探针):7 MiB / 31 MiB = `entry too large`(行墙,默认 6291456)、
+ * 32 MiB = `max_allowed_packet`(包墙,64 MiB ÷ ~2× 文本协议膨胀)。帽=诚实拒绝:超限 blob 在 query 之前 typed 拒(消费面 HTTP 413 / capture warn
+ * 拿到可行动信息);帽与墙之间只差这一行自己的几百字节(blob 行余量),帽之下的 blob 在缺省配置下落得进。D-1 附件战役同墙教训:`task-attachment-store.ts` 头注。
+ */
+export declare function sqlBlobDefaultCapBytes(walls: SqlWallsReading): number | undefined;
+/**
+ * 一个 SQL 快照 blob 的帽 + 它**从哪来**。`operator` = 运维显式设的 `SNAPSHOT_BLOB_SQL_MAX_BYTES`(策略帽);`reported` / `assumed` = 缺省推导里**定下这个帽的那条腿**的墙数字出处
+ * ({@link SqlWallSource}:库自己报的 / 读失败或事实缺席而退的文档缺省)。机读位同 413 拒体的 `wallSource` 词,旋钮形多一个 `operator`。
+ */
+export interface SqlBlobCapReading {
+    readonly capBytes: number;
+    readonly source: "operator" | SqlWallSource;
+}
+/**
+ * 缺省帽的推导(唯一一处,{@link sqlBlobDefaultCapBytes} 是它的字节投影):两条腿各带自己那堵墙的出处,取最小的那条;两条一样小取行墙腿。两堵墙都不存在 ⇒ `undefined`。
+ */
+export declare function sqlBlobDefaultCapOf(walls: SqlWallsReading): SqlBlobCapReading | undefined;
+/**
+ * 一条**借出连接**的引擎读口:方言(装配事实)+ 它自己那次初始化回读的事实。与 {@link SqlEngineReading} 的差别只有一处 —— `facts` 恒在:连接是借出时才有的,
+ * 借出即已初始化({@link connectJudged} 交给判决的就是借出连接的 `sqlConnectionFacts`),所以「事实缺席」在这条读法上**不可表示**(编译期拒,不是运行期一个没人走的分支)。
+ * 事实缺席(池上还没建立过、或最近一次初始化被拒)只出现在读**池级**读口的地方 —— 提交受理口 —— 那一格的墙由判官 `sqlWallsOf` 给,不经过帽的推导。
+ */
+export interface SqlConnectionReading {
+    readonly dialect: SqlEngineReading["dialect"];
+    readonly facts: SqlEngineFacts;
+}
+/**
+ * 一个 SQL 快照 blob 此刻的帽 —— **显式旋钮 ?? 判官给的墙走缺省推导**的唯一一只函数。唯一读者 = 店的写前判({@link SqlBlobBackend.putBlob}),传的读口({@link SqlConnectionReading})是
+ * **将要执行写入的那条连接**的(方言 + 它自己那次初始化回读的事实,墙经与提交受理口同一只判官 `sqlWallsOf`):包墙是连接的会话值,所以判决只在写入的那条连接上做,
+ * HTTP 面不替店另算一份帽。
+ */
+export declare function sqlBlobCapOf(explicitCapBytes: number | undefined, connection: SqlConnectionReading): SqlBlobCapReading | undefined;
+/** {@link sqlBlobCapOf} 的字节投影(同一个推导,不另读)。 */
+export declare function sqlBlobCapBytes(explicitCapBytes: number | undefined, connection: SqlConnectionReading): number | undefined;
+/**
+ * 这一拒是不是**那条连接的包墙**定的:帽是缺省推导出的(不是运维旋钮)、那条连接有包墙、且包墙腿的折算恰是这个帽(包墙腿是最矮的一腿,或与行墙腿并列)。
+ * 只有这种拒才值得问「这条连接过时了吗」({@link connectJudged}) —— 旋钮的拒、行墙的拒与连接新旧无关。`walls` = 判出这个帽的那一份墙({@link sqlWallsOf})。
+ */
+export declare function capBoundByPacketWall(cap: SqlBlobCapReading, walls: SqlWallsReading): boolean;
+/**
+ * 一次 blob 超帽的拒句 —— **唯一的组句器**(店的 typed {@link BlobTooLargeError} 调它;`PUT /sync/blobs` 的 413 原样转出它的句子):句子按帽的出处({@link SqlBlobCapReading.source})
+ * 分三形,不把假定说成库的上限、也不把运维的旋钮说成库的上限。
+ *  · `operator` —— 帽是运维设的 `SNAPSHOT_BLOB_SQL_MAX_BYTES`;
+ *  · `reported` —— 帽由库报的两堵墙推出(单行上限与包墙÷文本协议膨胀的较小者);
+ *  · `assumed` —— 库的上限没读到(事实还没建立,或这一堵读失败),帽按受支持引擎里最保守的缺省墙推出,稍后重试或由运维设旋钮。
+ */
+export declare function sqlBlobCapRefusalText(byteLen: number, cap: SqlBlobCapReading): string;
 /** typed 判别错:blob 超过 SQL 店的承载帽。判别码供店侧结果映射/HTTP 面/日志使用——绝不能与
- *  transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)。 */
+ *  transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)。句子是 {@link sqlBlobCapRefusalText}(带帽的出处)。 */
 export declare class BlobTooLargeError extends Error {
+    readonly cap: SqlBlobCapReading;
     readonly code: "blob_too_large_for_sql";
-    constructor(byteLen: number, capBytes: number);
+    constructor(byteLen: number, cap: SqlBlobCapReading);
 }
 /**
  * The content-addressed byte store. All four methods are keyed on the sha256 `hash` of the bytes:
@@ -47,16 +107,24 @@ export interface BlobBackend {
 export declare class SqlBlobBackend implements BlobBackend {
     private readonly dialect;
     private readonly pool;
-    /** Effective per-blob cap: explicit ctor value wins; else tidb=SQL_BLOB_DEFAULT_MAX_BYTES, pg=uncapped. */
-    private readonly capBytes;
+    /** Explicit per-blob cap (the operator's `SNAPSHOT_BLOB_SQL_MAX_BYTES`); absent ⇒ the derivation in {@link sqlBlobCapOf} over the walls of the connection each write borrows. */
+    private readonly explicitCapBytes;
     /** Blob-domain table ([ref] blob 域隔离:file-history 域用自己的表,reap/GC 不跨域)。代码内字面量,非用户输入。 */
     private readonly table;
-    constructor(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, maxBytes?: number, table?: string);
+    /** The write path's connection source: every `putBlob` borrows ONE connection from it (through {@link connectJudged}), judges on that connection's walls, writes on it. */
+    private readonly db;
+    /** Where a stale connection's replacement is logged ({@link connectJudged}); the boot assembly passes the service logger. */
+    private readonly log;
+    constructor(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, maxBytes?: number, table?: string, log?: Pick<Logger, "warn">);
     /** The created_at-refreshing content-addressed upsert — VERBATIM the tidb/pg stores' `putBlobRow`. Refreshes
      *  created_at even on a dedup hit so a re-used/just-written blob is "touched=now" and GC-grace-protected.
      *  (a): an over-cap blob is REJECTED (typed {@link BlobTooLargeError}) BEFORE the driver ever sees the bytes —
      *  the alternative is an inscrutable packet-limit error deep in the driver, and on the HTTP face a 502 that
-     *  invites the peer to retry a blob that can never land. */
+     *  invites the peer to retry a blob that can never land.
+     *  🔴 The cap is judged ON THE CONNECTION THAT WRITES (S-1746): `max_allowed_packet` is a session value, fixed per
+     *  connection, so the write borrows one connection through {@link connectJudged}, which reads ITS walls, judges, and — when
+     *  the refusal is that connection's packet wall and the server's global wall is higher — replaces the stale connection and
+     *  judges once more; the INSERT runs on the connection that passed. Never a pool-level reading, never a bare `pool.query`. */
     putBlob(hash: string, bytes: Uint8Array): Promise<void>;
     /** The bytes for `hash` (undefined if absent) — VERBATIM the tidb/pg stores' getBlob SELECT. A pool/query error
      *  PROPAGATES (a transient DB fault is loud, not a silent "missing blob" — parity with the MinIO backend's throw). */

package/dist/plugins/blob-backend.js

@@ -1,14 +1,54 @@
 import { createHash } from "node:crypto";
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
+import { connectJudged, mysqlDriver, packetWallStatementBytes, pgDriver, rowWallPayloadBytes, sqlWallsOf } from "./sql-driver.js";
+import { createLogger } from "../observability/logger.js";
 const BLOB_GC_GRACE_MS = 3_600_000;
-export const SQL_BLOB_DEFAULT_MAX_BYTES = 6_291_456;
+export const SQL_TEXT_PROTOCOL_BLOB_INFLATION = 2;
+export function packetWallBlobCap(maxPacketBytes) {
+    return Math.floor(packetWallStatementBytes(maxPacketBytes) / SQL_TEXT_PROTOCOL_BLOB_INFLATION);
+}
+export function sqlBlobDefaultCapBytes(walls) {
+    return sqlBlobDefaultCapOf(walls)?.capBytes;
+}
+export function sqlBlobDefaultCapOf(walls) {
+    const legs = [];
+    if (walls.maxRowBytes !== null)
+        legs.push({ capBytes: rowWallPayloadBytes(walls.maxRowBytes, "blob"), source: walls.sources.maxRowBytes });
+    if (walls.maxPacketBytes !== null)
+        legs.push({ capBytes: packetWallBlobCap(walls.maxPacketBytes), source: walls.sources.maxPacketBytes });
+    return legs.reduce((best, leg) => (best === undefined || leg.capBytes < best.capBytes ? leg : best), undefined);
+}
+export function sqlBlobCapOf(explicitCapBytes, connection) {
+    return explicitCapBytes !== undefined ? { capBytes: explicitCapBytes, source: "operator" } : sqlBlobDefaultCapOf(sqlWallsOf(connection));
+}
+export function sqlBlobCapBytes(explicitCapBytes, connection) {
+    return sqlBlobCapOf(explicitCapBytes, connection)?.capBytes;
+}
+export function capBoundByPacketWall(cap, walls) {
+    return cap.source !== "operator" && walls.maxPacketBytes !== null && packetWallBlobCap(walls.maxPacketBytes) === cap.capBytes;
+}
+export function sqlBlobCapRefusalText(byteLen, cap) {
+    const objectStorage = "configure MinIO object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) for large snapshot blobs";
+    const head = `blob of ${byteLen} bytes exceeds this deployment's SQL snapshot-blob cap (${cap.capBytes} bytes — `;
+    switch (cap.source) {
+        case "operator":
+            return `${head}set by the operator's SNAPSHOT_BLOB_SQL_MAX_BYTES) — ${objectStorage}, or raise SNAPSHOT_BLOB_SQL_MAX_BYTES if the database allows larger writes`;
+        case "reported":
+            return `${head}the smaller of the database's single-row limit (TiDB txn-entry-size-limit, 6MiB by default) and about half its max_allowed_packet (the text protocol doubles a blob inside the statement)) — ${objectStorage}, or raise SNAPSHOT_BLOB_SQL_MAX_BYTES if your deployment lifted those limits`;
+        case "assumed":
+            return `${head}the database's limits were not read — engine facts not read yet, or a limit could not be read — so the smallest documented default wall applies) — retry shortly, ${objectStorage}, or set SNAPSHOT_BLOB_SQL_MAX_BYTES to the limit your deployment actually has`;
+        default: {
+            const unhandled = cap.source;
+            throw new Error(`blob cap refusal without a sentence: ${String(unhandled)}`);
+        }
+    }
+}
 export class BlobTooLargeError extends Error {
+    cap;
     code = "blob_too_large_for_sql";
-    constructor(byteLen, capBytes) {
-        super(`blob of ${byteLen} bytes exceeds the SQL snapshot-blob cap (${capBytes} bytes): a single-row INSERT this large ` +
-            `hits TiDB's txn-entry-size-limit (default 6MiB) or the mysql-protocol max_allowed_packet (~2x text-protocol ` +
-            `inflation). Configure object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) for large snapshot ` +
-            `blobs, or override the cap with SNAPSHOT_BLOB_SQL_MAX_BYTES if your deployment raised those limits.`);
+    constructor(byteLen, cap) {
+        super(sqlBlobCapRefusalText(byteLen, cap));
+        this.cap = cap;
         this.name = "BlobTooLargeError";
     }
 }
@@ -26,22 +66,35 @@ async function mapBounded(items, limit, fn) {
 export class SqlBlobBackend {
     dialect;
     pool;
-    capBytes;
+    explicitCapBytes;
     table;
-    constructor(dialect, pool, maxBytes, table = "snapshot_blob") {
+    db;
+    log;
+    constructor(dialect, pool, maxBytes, table = "snapshot_blob", log) {
         this.dialect = dialect;
         this.pool = pool;
-        this.capBytes = maxBytes ?? (dialect === "tidb" ? SQL_BLOB_DEFAULT_MAX_BYTES : Number.POSITIVE_INFINITY);
+        this.explicitCapBytes = maxBytes;
         this.table = table;
+        this.db = dialect === "tidb" ? mysqlDriver(pool) : pgDriver(pool);
+        this.log = log ?? createLogger();
     }
     async putBlob(hash, bytes) {
-        if (bytes.byteLength > this.capBytes)
-            throw new BlobTooLargeError(bytes.byteLength, this.capBytes);
-        if (this.dialect === "tidb") {
-            await this.pool.query(`INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
+        const judged = await connectJudged(this.db, (facts) => {
+            const connection = { dialect: this.dialect, facts };
+            const cap = sqlBlobCapOf(this.explicitCapBytes, connection);
+            if (cap === undefined || bytes.byteLength <= cap.capBytes)
+                return undefined;
+            return { cap, packetBound: capBoundByPacketWall(cap, sqlWallsOf(connection)) };
+        }, (refusal) => refusal.packetBound, this.log);
+        if (judged.refusal !== undefined)
+            throw new BlobTooLargeError(bytes.byteLength, judged.refusal.cap);
+        try {
+            await judged.conn.query(this.dialect === "tidb"
+                ? `INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`
+                : `INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,$3,$4) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
         }
-        else {
-            await this.pool.query(`INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,$3,$4) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
+        finally {
+            judged.conn.release();
         }
     }
     async getBlob(hash) {