@sema-agent/server 7.131.0 → 7.132.0

package/dist/observability/tool-trace.d.ts

@@ -1,15 +1,18 @@
-import { type Hooks } from "@sema-agent/core";
+import { type EngineDollar, type ModRegistration } from "@sema-agent/core";
 import type { Logger } from "./logger.js";
 import type { Metrics } from "./metrics.js";
+/** 两张部署注册的名字 —— wire 可见(`wiring_manifest.mods[].name`);名字中性、稳定、不含部署信息。 */
+export declare const PERMISSION_DENIED_METER_REGISTRATION = "server.permission-denied-meter";
+export declare const TOOL_TRACE_REGISTRATION = "server.tool-trace";
 /**
  * ALWAYS-ON gate-deny meter (goal B4, 2026-07-08): `permission_denied_total{deniedBy}` — how often the
  * adjudicate chain DENIES a tool call, by the LAYER whose verdict is the deny. Deliberately SEPARATE from
  * {@link createToolTracer}: the tracer is a default-OFF diagnostic (TOOL_TRACE=true), but deny frequency is an
  * operational/security signal that must reach /metrics on every deployment — a spike in `deniedBy="policy"`
  * means a task keeps asking for something the operator forbids; `deniedBy="org"` is the organization layer
- * refusing, the one class an operator most wants to see on its own. main.ts composes this UNDER the tracer via
- * composeHooks (both are void observers on the permissionDenied slot, which composeHooks double-runs
- * deployment-first).
+ * refusing, the one class an operator most wants to see on its own. It is the deployment seat's first registration
+ * (`createDeploymentMods`, `boot/deployment-mods.ts`): an observer on `classic.PermissionDenied`, run before the tracer's observer on the same
+ * event (the engine runs observers by tier, then deployment before task, then each seat's own order).
  *
  * 🔴 BREAKING(server 7.64.0,core 7.6.0 提货):标签名 `source` → `deniedBy`,词表从七词
  * (`policy/hook/safety/shellGate/planMode/classifier/org`)换成八词
@@ -46,7 +49,7 @@ import type { Metrics } from "./metrics.js";
  *  · **计数总量方向**:新座只在「分类器那一轮没有裁决」时在场(`<block>yes` 的真裁决恒缺席),与旧座的
  *    「分类器停摆」同向;多出来的那一格是 `parse_error`,它也确实是「分类器没正常工作」的一种。
  */
-export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc">): Hooks;
+export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc">): ModRegistration<EngineDollar>;
 /**
  * prove-before-scale stopgap ([ref]): a no-op observer hook that logs every tool call (pre + post)
  * to the worker log — INCLUDING resumed legs that `GET /v1/runs/:id/events` does NOT surface (the
@@ -59,21 +62,13 @@ export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc"
  * the full sequence: a repeated `write_file path=X contentLen=Y` across resumes ⇒ restart-loop;
  * write X → write Y → bash ⇒ iteration.
  *
- * Pure observation: every hook returns `undefined`, so it never rewrites args, never gates, never alters
- * the result (and per core's hooks invariant a hook's `allow` can't bypass the policy gate anyway).
- *
- * 🔴 core 5.20.0 起这条「纯观察」性质必须**声明**出来(`preToolUseObservational`),不能只写在注释里:
- * core 5.19.0 的委派折叠按「PreToolUse 席位在不在」把父的 screening 面折进子代的祖先约束链——它分不出
- * 诊断 tracer 与真裁决者。后果是**这个默认关的诊断旋钮**一开,该部署所有 hook-wired 父的 parked 子代
- * checkpoint 就记 `parentConstraintCount=2`,而跨副本赎回腿(`boot/parked-revive-gate.ts`)恒供 1 ⇒
- * core pre-CAS 响亮拒、行永久 pending(层数 park 时写死,事后关旋钮/重批/回滚都不改)。
- * 声明之后该面不铸链条目,count 回到 1,病路消灭。
- * ⛔ 打这个标的前提是**真的一条裁决都不出**:core 对声明了却返回判词的面是「拒绝采纳 + onError 告警」
- * (classification `observational-hook-verdict-ignored`),即判词被静默丢弃——把标打到会裁决的面上比原
- * 缺陷更坏。本文件三个 pre/post 回调恒返 `undefined`,`permissionDenied` 本就是 void 观察槽。
- * 📎 连带的**可观测**变化(不是回归):core 的「可写工具面无 effect-aware 门」启动告警此前把本 tracer
- * 算作一道门而被抑制;声明之后它不再算,于是「没配任何 policy 层 + 开着 TOOL_TRACE」的部署升级后会
- * 多出那行告警。方向正确——tracer 从来没有门住任何东西,原先的抑制本身就是一次静默 fail-open。
+ * Pure observation: every handler is an observer (`{ observe: true }`, via {@link observeClassic}) — a detached copy of
+ * the event, outside the chain, its answer never adopted — so it never rewrites args, never gates, never alters the result.
+ * Being an observer is also what keeps it out of a delegated child's inherited constraint: the engine mints a screening
+ * entry only from a chain that JUDGES, so turning this diagnostic switch on adds no `parentConstraintCount` to a parked
+ * child of a hook-wired parent (the cross-replica revive leg, `boot/parked-revive-gate.ts`, supplies the caller policy only).
+ * 📎 Not a gate either for the engine's "writable tool face without an effect-aware gate" startup warning: a deployment with
+ * no policy layer and `TOOL_TRACE` on still gets that warning — the tracer never gated anything.
  */
-export declare function createToolTracer(logger: Logger): Hooks;
+export declare function createToolTracer(logger: Logger): ModRegistration<EngineDollar>;
 //# sourceMappingURL=tool-trace.d.ts.map

package/dist/observability/tool-trace.js

@@ -1,60 +1,69 @@
 import { isClassifierDenyCause, isDeniedBy } from "@sema-agent/core";
+import { observeClassic } from "../hooks/classic-stations.js";
 import { redactSecrets } from "../trace/redact.js";
+export const PERMISSION_DENIED_METER_REGISTRATION = "server.permission-denied-meter";
+export const TOOL_TRACE_REGISTRATION = "server.tool-trace";
 function deniedByLabel(gate) {
     const d = gate.disposition;
     return d.kind === "denied" && isDeniedBy(d.deniedBy) ? d.deniedBy : "other";
 }
 export function createPermissionDeniedMeter(metrics) {
     return {
-        permissionDenied(payload) {
-            metrics.inc("permission_denied_total", { deniedBy: deniedByLabel(payload.gate) });
-            const disposition = payload.gate?.disposition;
-            const cause = disposition?.kind === "denied" ? disposition.cause : undefined;
-            if (cause !== undefined) {
-                metrics.inc("auto_mode_classifier_deny_cause_total", { cause: isClassifierDenyCause(cause) ? cause : "other" });
-            }
+        name: PERMISSION_DENIED_METER_REGISTRATION,
+        tier: "prepend",
+        uses: { events: ["classic.PermissionDenied"], calls: [] },
+        register(on) {
+            observeClassic(on, "classic.PermissionDenied", (payload) => {
+                metrics.inc("permission_denied_total", { deniedBy: deniedByLabel(payload.gate) });
+                const disposition = payload.gate?.disposition;
+                const cause = disposition?.kind === "denied" ? disposition.cause : undefined;
+                if (cause !== undefined) {
+                    metrics.inc("auto_mode_classifier_deny_cause_total", { cause: isClassifierDenyCause(cause) ? cause : "other" });
+                }
+            });
         },
     };
 }
 export function createToolTracer(logger) {
     return {
-        preToolUseObservational: true,
-        preToolUse(toolName, input, ctx) {
-            logger.info("tool_trace", { phase: "pre", id: ctx.toolCallId, tool: toolName, arg: summarize(input) });
-            return undefined;
-        },
-        postToolUse(toolName, _input, output, ctx) {
-            logger.info("tool_trace", {
-                phase: "post",
-                id: ctx.toolCallId,
-                tool: toolName,
-                isError: output.isError,
-                out: textOf(output.content),
+        name: TOOL_TRACE_REGISTRATION,
+        tier: "prepend",
+        uses: { events: ["classic.PreToolUse", "classic.PostToolUse", "classic.PostToolUseFailure", "classic.PermissionDenied"], calls: [] },
+        register(on) {
+            observeClassic(on, "classic.PreToolUse", (e) => {
+                logger.info("tool_trace", { phase: "pre", id: e.tool_use_id, tool: e.tool, arg: summarize(e.input) });
             });
-            return undefined;
-        },
-        postToolUseFailure(toolName, _input, failure, ctx) {
-            logger.info("tool_trace", {
-                phase: "post",
-                id: ctx.toolCallId,
-                tool: toolName,
-                isError: true,
-                isInterrupt: failure.isInterrupt,
-                ...(failure.durationMs !== undefined ? { durationMs: failure.durationMs } : {}),
-                out: clip(redactSecrets(failure.error), 200),
+            observeClassic(on, "classic.PostToolUse", (e) => {
+                logger.info("tool_trace", {
+                    phase: "post",
+                    id: e.tool_use_id,
+                    tool: e.tool,
+                    isError: e.output.isError,
+                    out: textOf(e.output.content),
+                });
             });
-            return undefined;
-        },
-        permissionDenied(payload) {
-            logger.info("tool_trace", {
-                phase: "denied",
-                id: payload.toolCallId,
-                tool: payload.toolName,
-                deniedBy: deniedByLabel(payload.gate),
-                ...(payload.gate.origin === undefined ? {} : { origin: payload.gate.origin }),
-                ...(payload.gate.settlement === undefined ? {} : { settlement: payload.gate.settlement.kind }),
-                reason: clip(redactSecrets(payload.reason), 200),
-                arg: summarize(payload.input),
+            observeClassic(on, "classic.PostToolUseFailure", (e) => {
+                logger.info("tool_trace", {
+                    phase: "post",
+                    id: e.tool_use_id,
+                    tool: e.tool,
+                    isError: true,
+                    isInterrupt: e.failure.isInterrupt,
+                    ...(e.failure.durationMs !== undefined ? { durationMs: e.failure.durationMs } : {}),
+                    out: clip(redactSecrets(e.failure.error), 200),
+                });
+            });
+            observeClassic(on, "classic.PermissionDenied", (payload) => {
+                logger.info("tool_trace", {
+                    phase: "denied",
+                    id: payload.toolCallId,
+                    tool: payload.toolName,
+                    deniedBy: deniedByLabel(payload.gate),
+                    ...(payload.gate.origin === undefined ? {} : { origin: payload.gate.origin }),
+                    ...(payload.gate.settlement === undefined ? {} : { settlement: payload.gate.settlement.kind }),
+                    reason: clip(redactSecrets(payload.reason), 200),
+                    arg: summarize(payload.input),
+                });
             });
         },
     };

package/dist/per-task-image.d.ts

@@ -4,13 +4,19 @@ import type { ImageViewer, ImageIndexEntry } from "./plugins/store-contracts.js"
 export interface SandboxImageResolver {
     latestPublished(profile: string, viewer: ImageViewer): Promise<Pick<ImageIndexEntry, "repo" | "digest" | "capabilities"> | null>;
 }
+/**
+ * 解析失败的机读码(闭集):`not_found.image` = 按调用方的约束(档案 · 本主体可见 · 已发布 · 所需能力)找不到镜像 —— 与 `POST /v1/images/select`
+ * 「没有可见的已发布镜像」同一个码(同一个事实);`request.field_invalid` = `capabilitiesNeeded` 里有不认识的能力词。状态随码,一码一状态。
+ */
+export type SandboxImageRefusalCode = "not_found.image" | "request.field_invalid";
 export type SandboxImageResolution = {
     ok: true;
     ref: string;
     capabilities?: import("./plugins/store-contracts.js").ImageCapabilities;
 } | {
     ok: false;
-    status: number;
+    status: 404 | 400;
+    errorCode: SandboxImageRefusalCode;
     message: string;
 };
 /**

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/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/blob-backend.d.ts

@@ -1,19 +1,69 @@
 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 SqlEngineReading, type SqlWallSource, type SqlWallsReading } from "./sql-driver.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;
+/**
+ * **事实本身还没建立**时 MySQL 协议方言的缺省帽(池上还没借出过连接,或最近一次连接初始化被拒:`SqlDriver.facts === null`)= 事实缺席时的墙
+ * (`sql-driver.ts` `SQL_FACTS_ABSENT_WALLS`,判官 `sqlWallsOf`;提交受理口读同一只)走下面同一个推导 —— 不是第二份落点,只是那个推导在这组墙上的值
+ * (今天 = TiDB 缺省行墙走 blob 行的折算 6 MiB − 1 KiB:最矮的包墙缺省 16 MiB 扣语句余量再折半仍近 8 MiB,行腿更矮)。
+ */
+export declare const SQL_BLOB_FACTS_ABSENT_CAP_BYTES: 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` 不设帽。事实本身缺席时
+ * 墙由判官给(MySQL 协议按最保守的墙),走同一个推导 = {@link SQL_BLOB_FACTS_ABSENT_CAP_BYTES}。显式旋钮是运维的策略帽,在本推导之上(见 {@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;
+/**
+ * 一个 SQL 快照 blob 此刻的帽 —— **显式旋钮 ?? 判官给的墙走缺省推导**的唯一一只函数。两个读者同调它、各传本池的**引擎读口**(方言与活事实同出一只驱动,
+ * 与提交受理口读的是同一种读口):店的写前帽({@link SqlBlobBackend},本池的驱动)与 `PUT /sync/blobs` 的前置 413(`boot/stage-10-http-server.ts` 装配的读口,
+ * 按请求调,读 `ServiceDeps.sqlEngine`)。同一池上两个读口读的是同一份池级事实。
+ */
+export declare function sqlBlobCapOf(explicitCapBytes: number | undefined, engine: SqlEngineReading): SqlBlobCapReading | undefined;
+/** {@link sqlBlobCapOf} 的字节投影(同一个推导,不另读)。 */
+export declare function sqlBlobCapBytes(explicitCapBytes: number | undefined, engine: SqlEngineReading): number | undefined;
+/**
+ * 一次 blob 超帽的拒句 —— **唯一的组句器**(`PUT /sync/blobs` 的前置 413 与店的 typed {@link BlobTooLargeError} 同调它):句子按帽的出处({@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,11 +97,16 @@ 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 sqlBlobCapBytes} over this pool's live engine facts. */
+    private readonly explicitCapBytes;
+    /** This pool's engine reading (dialect + live facts, from the pool's own driver) — the one source the cap's walls are read from. */
+    private readonly engine;
     /** Blob-domain table ([ref] blob 域隔离:file-history 域用自己的表,reap/GC 不跨域)。代码内字面量,非用户输入。 */
     private readonly table;
     constructor(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, maxBytes?: number, table?: string);
+    /** The cap in force for this write: the explicit one, else the default derived from the pool's engine facts as they
+     *  stand now (the driver refreshes them on each connection initialization). */
+    private cap;
     /** 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 —

package/dist/plugins/blob-backend.js

@@ -1,14 +1,51 @@
 import { createHash } from "node:crypto";
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
+import { SQL_FACTS_ABSENT_WALLS, mysqlDriver, packetWallStatementBytes, pgDriver, rowWallPayloadBytes, sqlWallsOf } from "./sql-driver.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 const SQL_BLOB_FACTS_ABSENT_CAP_BYTES = sqlBlobDefaultCapBytes(SQL_FACTS_ABSENT_WALLS);
+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, engine) {
+    return explicitCapBytes !== undefined ? { capBytes: explicitCapBytes, source: "operator" } : sqlBlobDefaultCapOf(sqlWallsOf(engine));
+}
+export function sqlBlobCapBytes(explicitCapBytes, engine) {
+    return sqlBlobCapOf(explicitCapBytes, engine)?.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,17 +63,23 @@ async function mapBounded(items, limit, fn) {
 export class SqlBlobBackend {
     dialect;
     pool;
-    capBytes;
+    explicitCapBytes;
+    engine;
     table;
     constructor(dialect, pool, maxBytes, table = "snapshot_blob") {
         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.engine = dialect === "tidb" ? mysqlDriver(pool) : pgDriver(pool);
+    }
+    cap() {
+        return sqlBlobCapOf(this.explicitCapBytes, this.engine);
     }
     async putBlob(hash, bytes) {
-        if (bytes.byteLength > this.capBytes)
-            throw new BlobTooLargeError(bytes.byteLength, this.capBytes);
+        const cap = this.cap();
+        if (cap !== undefined && bytes.byteLength > cap.capBytes)
+            throw new BlobTooLargeError(bytes.byteLength, cap);
         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()]);
         }

package/dist/plugins/checkpoint-store-sql.d.ts

@@ -51,11 +51,12 @@ export interface PendingCheckpoint extends ParkRowFacts {
      *  consumer to treat the key's PRESENCE as "there is a binding" and echo `null` back into /decide. */
     boundCallId?: string;
     boundInputHash?: string;
-    /** 🔴 [ref]③ (additive): the checkpoint's gate kind — the operator queue mixes tool approvals with
+    /** 🔴 [ref]③: the checkpoint's gate kind — the operator queue mixes tool approvals with
      *  plan_review / resource_limit / task_done parks (all of which carry `toolName: null`), so a durable-recovery
-     *  consumer needs this to ROUTE a row to the right wire (`/decide` vs `/plan_review` vs `/resume`). Absent
-     *  only for a legacy SQL row suspended before the `gate_kind` column existed. */
-    gateKind?: CheckpointGate["kind"];
+     *  consumer needs this to ROUTE a row to the right wire (`/decide` vs `/plan_review` vs `/resume`). ALWAYS present
+     *  (S-1681, 7.132.0): every park stamps it, the one-time migration M21 filled any row without it from the row's gate,
+     *  and a SQL row that still carries none is not listed by `listPending` (counted: `server.approvals.queue-row-gate-kind-missing`; no decide route binds it either). */
+    gateKind: CheckpointGate["kind"];
     /** The suspended run's taskId (task_active join) — the key to the run/trace ("view task context"). */
     taskId: string | null;
     /** The pending tool call's args (post-hook), redacted + bounded — for tool_approval the write payload, for a
@@ -278,6 +279,15 @@ export declare function assertCheckpointColumnSchema(query: (sql: string) => Pro
 export declare function boundedRuleOffers(raw: unknown, opts?: {
     countRedactions?: boolean;
 }): RuleOfferProjection[] | undefined;
+/**
+ * S-1681 —— 运维队列行的门型:**两只孪生同一只判官**(SQL 孪生读 `gate_kind` 列 —— put 时从同一只门反范式下来的那一格,每次停驻都盖,一次性迁移 M21 把没有它的
+ * 存量行从门子树补齐;local 孪生读快照上的门 `cp.gate.kind`)。
+ * 读到的值是 NULL / 缺席 / 不是 core 登记的门型 ⇒ `undefined`:这一行**不列**(响亮:计一次 `server.approvals.queue-row-gate-kind-missing`)—— 与每一条决断口同一个读法:
+ * 按门型绑定取行的读口对这种行本来就不命中(`pendingRowQuery` 的 `gate_kind IN (…)`,证不出门型就不当它是这道门),队列不再把一行谁也决不了的行投出去,
+ * 也不按缺键投(消费方按 `gateKind` 路由、缺键即 fail-closed)。不整只拒:一行坏行不许让整个租户的队列(列表 500、SSE 心跳照常而队列永远停在旧帧)消失。
+ * 按构造不可达(写口恒盖、M21 补齐);计数非零 = 写腿或手改出了错,按 `SELECT … WHERE status = 'pending' AND gate_kind IS NULL` 查那一行。
+ */
+export declare function queueRowGateKind(kind: unknown): CheckpointGate["kind"] | undefined;
 /** Redact + size-bound a pending tool call's args for persistence/serving. JSON-roundtrips so the stored shape
  *  matches what the operator queue serves; oversized payloads collapse to a marker rather than bloating the row.
  *  Exported for the LOCAL twin (local-checkpoint-store.ts) so the operator-queue projection can't drift. */

package/dist/plugins/checkpoint-store-sql.js

@@ -1,13 +1,13 @@
 import { parkedApprovalCard, parkedFacetOf } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
 import { APPROVAL_GATE_KINDS_SQL_IN, denySweepOwns } from "../tool-approval.js";
-import { CheckpointError, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
+import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, parkRowFacts, screenUncoveredDetailSeat } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
-import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
+import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const REAP_CLASSIFY_BATCH = 200;
@@ -196,6 +196,12 @@ function readParkGateCell(cell) {
     }
 }
 const readParkGateMemberBody = createObjectColumnReader();
+export function queueRowGateKind(kind) {
+    if (isGateKind(kind))
+        return kind;
+    recordFailOpen("server.approvals.queue-row-gate-kind-missing", `gate_kind=${kind === null || kind === undefined ? "NULL" : redactSecrets(String(kind)).slice(0, 40)}`);
+    return undefined;
+}
 function parkedGateOfRow(r) {
     return { kind: r.gate_kind ?? undefined, approvalCard: readParkGateCell(r[PARK_ROW_GATE.as])?.approvalCard };
 }
@@ -418,7 +424,7 @@ export class SqlCheckpointStore {
             if (this.isDupKey(e)) {
                 throw new CheckpointError("checkpoint.already_exists", `checkpoint token already exists`);
             }
-            throw e;
+            throw rowTooLargeOrSelf(this.db.dialect, e, `the checkpoint row for session ${JSON.stringify(cp.sessionId)}`);
         }
     }
     async get(token) {
@@ -582,31 +588,33 @@ export class SqlCheckpointStore {
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
             : await this.db.query(`${base} ORDER BY c.created_at_ms ASC`);
-        const out = rows.map((r) => {
+        const out = rows.flatMap((r) => {
+            const gateKind = queueRowGateKind(r.gate_kind);
+            if (gateKind === undefined)
+                return [];
             const toolName = r.tool_name ?? null;
             const toolCallId = r.tool_call_id ?? null;
             const boundInputHash = r.bound_input_hash ?? null;
-            const gateKind = r.gate_kind ?? null;
             const ruleOffers = readRuleOffersCell(r.rule_suggestions);
             const approvalCard = parkedApprovalCard(parkedGateOfRow(r));
-            return {
-                sessionId: String(r.session_id),
-                scope: String(r.scope),
-                toolName,
-                toolCallId,
-                ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
-                ...(boundInputHash !== null ? { boundInputHash } : {}),
-                ...(gateKind !== null ? { gateKind } : {}),
-                taskId: r.task_id ?? null,
-                input: refusing("a tool input the operator would be approving unseen", () => decodeToolInputColumn(r.tool_input)) ?? null,
-                createdAt: Number(r.created_at_ms),
-                deadline: r.deadline == null ? null : Number(r.deadline),
-                riskDescriptor: readRiskDescriptorCell(r.risk_descriptor),
-                ...(ruleOffers !== undefined ? { ruleOffers } : {}),
-                ...(Number(r.has_bidi_controls) === 1 ? { hasBidiControls: true } : {}),
-                ...(approvalCard !== undefined ? { approvalCard } : {}),
-                ...readParkRowFactsCell(r[PARK_ROW_PENDING_ACTION.as]),
-            };
+            return [{
+                    sessionId: String(r.session_id),
+                    scope: String(r.scope),
+                    toolName,
+                    toolCallId,
+                    ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
+                    ...(boundInputHash !== null ? { boundInputHash } : {}),
+                    gateKind,
+                    taskId: r.task_id ?? null,
+                    input: refusing("a tool input the operator would be approving unseen", () => decodeToolInputColumn(r.tool_input)) ?? null,
+                    createdAt: Number(r.created_at_ms),
+                    deadline: r.deadline == null ? null : Number(r.deadline),
+                    riskDescriptor: readRiskDescriptorCell(r.risk_descriptor),
+                    ...(ruleOffers !== undefined ? { ruleOffers } : {}),
+                    ...(Number(r.has_bidi_controls) === 1 ? { hasBidiControls: true } : {}),
+                    ...(approvalCard !== undefined ? { approvalCard } : {}),
+                    ...readParkRowFactsCell(r[PARK_ROW_PENDING_ACTION.as]),
+                }];
         });
         return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
     }
@@ -716,9 +724,14 @@ export class SqlCheckpointStore {
     async putCtx(sessionId, ctx) {
         const text = this.json(ctx, "checkpoint ctx");
         assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (write leg)`);
-        await this.db.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES (?,?,?) " +
-            "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at_ms = VALUES(updated_at_ms)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES ($1,$2::jsonb,$3) " +
-            "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at_ms = EXCLUDED.updated_at_ms"), [sessionId, text, Date.now()]);
+        try {
+            await this.db.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES (?,?,?) " +
+                "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at_ms = VALUES(updated_at_ms)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES ($1,$2::jsonb,$3) " +
+                "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at_ms = EXCLUDED.updated_at_ms"), [sessionId, text, Date.now()]);
+        }
+        catch (e) {
+            throw rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)}`);
+        }
     }
     async getCtx(sessionId) {
         const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);