@sema-agent/server 7.93.4 → 7.93.6

package/dist/boot/exit-boundary.js

@@ -0,0 +1,73 @@
+import { defaultTaskRegistry } from "@sema-agent/core";
+import { liveHostForegroundChildCount, reapHostForegroundChildren } from "../plugins/host-platform.js";
+import { liveEphemeralHostWorkspaceCount, reapEphemeralHostWorkspaces } from "../plugins/host-workspace-registry.js";
+export function installProcessExitBoundary({ logger }) {
+    const reapOwnChildProcesses = () => {
+        try {
+            const reaped = defaultTaskRegistry.reapAllSessionBackground();
+            if (reaped > 0)
+                logger.info("shutdown_background_reaped", { reaped });
+        }
+        catch (err) {
+            logger.warn("shutdown_background_reap_failed", { err: String(err) });
+        }
+        try {
+            const fg = reapHostForegroundChildren();
+            if (fg.signalled > 0 || fg.alreadyDead > 0)
+                logger.info("shutdown_foreground_reaped", { signalled: fg.signalled, alreadyDead: fg.alreadyDead });
+            if (fg.failed.length > 0)
+                logger.warn("shutdown_foreground_reap_incomplete", { groups: fg.failed });
+        }
+        catch (err) {
+            logger.warn("shutdown_foreground_reap_failed", { err: String(err) });
+        }
+    };
+    const reapOwnHostWorkspaces = () => {
+        try {
+            const { removed, failed } = reapEphemeralHostWorkspaces();
+            if (removed.length > 0)
+                logger.info("shutdown_host_workspaces_reaped", { removed: removed.length });
+            if (failed.length > 0)
+                logger.warn("shutdown_host_workspace_reap_incomplete", { dirs: failed.map((f) => f.dir) });
+        }
+        catch (err) {
+            logger.warn("shutdown_host_workspace_reap_failed", { err: String(err) });
+        }
+    };
+    const onProcessExit = () => {
+        const onBooks = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
+        try {
+            reapOwnChildProcesses();
+        }
+        catch (err) {
+            console.error("shutdown_exit_boundary_child_reap_threw", err);
+        }
+        try {
+            reapOwnHostWorkspaces();
+        }
+        catch (err) {
+            console.error("shutdown_exit_boundary_workspace_reap_threw", err);
+        }
+        const left = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
+        try {
+            logger.info("shutdown_exit_boundary", { ...onBooks, leftForegroundChildren: left.foregroundChildren, leftHostWorkspaces: left.hostWorkspaces });
+            if (left.foregroundChildren > 0 || left.hostWorkspaces > 0)
+                logger.warn("shutdown_exit_boundary_incomplete", left);
+        }
+        catch (err) {
+            console.error("shutdown_exit_boundary_log_threw", err);
+        }
+    };
+    process.once("exit", onProcessExit);
+    let disposed = false;
+    return {
+        reapChildProcessesEarly: reapOwnChildProcesses,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            process.removeListener("exit", onProcessExit);
+        },
+    };
+}
+//# sourceMappingURL=exit-boundary.js.map

package/dist/boot/shutdown.d.ts

@@ -12,8 +12,8 @@
  *     "第二个信号"的语义读数。
  *  3. `clearInterval(reaper)` 必须是 hardShutdown 的第一件事(在 `server.close()` 之前),否则
  *     收尾期还会有 reaper tick 打向正在关闭的池。
- *  4. **进程级监听一律成对**([ref] 二轮件4):本函数装的六只(三信号 + [ref]① 双钩 + S-557 退出边界钩)
- *     只能经返回的
+ *  4. **进程级监听一律成对**([ref] 二轮件4):本函数装的六只(三信号 + [ref]① 双钩 + S-557 退出边界钩
+ *     —— S-560 起后者由 {@link installProcessExitBoundary} 代装,摘除仍并进同一把手)只能经返回的
  *     {@link ShutdownHandle} 摘 —— 调用方手写「摘三信号」的收尾会把双钩漏在进程上,而陈旧的那只
  *     rejection 钩仍握着 `process.exit(1)`,会对后续无关的 rejection 把进程打掉。
  */

package/dist/boot/shutdown.js

@@ -1,9 +1,8 @@
-import { Runner, defaultTaskRegistry } from "@sema-agent/core";
+import { Runner } from "@sema-agent/core";
 import { writeCrashLast, clearCrashLast, readCrashLast } from "./crash-last.js";
 import { createSighupIdleHandler } from "../sighup-idle.js";
 import { createParentWatch } from "../parent-watch.js";
-import { liveHostForegroundChildCount, reapHostForegroundChildren } from "../plugins/host-platform.js";
-import { liveEphemeralHostWorkspaceCount, reapEphemeralHostWorkspaces } from "../plugins/host-workspace-registry.js";
+import { installProcessExitBoundary } from "./exit-boundary.js";
 import { createEngineLeaseTracker } from "./engine-lease.js";
 import { writeExitLast, readExitLast, clearExitLast } from "./exit-last.js";
 import { isScriptRealmRejection, describeRejectionReason } from "../orchestration/hardened-vm-runner.js";
@@ -32,63 +31,7 @@ export function installShutdownHandlers(ctx) {
         if (dataRoot)
             writeCrashLast(dataRoot, { version, inflight: drainState.inflight?.(), err });
     };
-    const reapOwnChildProcesses = () => {
-        try {
-            const reaped = defaultTaskRegistry.reapAllSessionBackground();
-            if (reaped > 0)
-                logger.info("shutdown_background_reaped", { reaped });
-        }
-        catch (err) {
-            logger.warn("shutdown_background_reap_failed", { err: String(err) });
-        }
-        try {
-            const fg = reapHostForegroundChildren();
-            if (fg.signalled > 0 || fg.alreadyDead > 0)
-                logger.info("shutdown_foreground_reaped", { signalled: fg.signalled, alreadyDead: fg.alreadyDead });
-            if (fg.failed.length > 0)
-                logger.warn("shutdown_foreground_reap_incomplete", { groups: fg.failed });
-        }
-        catch (err) {
-            logger.warn("shutdown_foreground_reap_failed", { err: String(err) });
-        }
-    };
-    const reapOwnHostWorkspaces = () => {
-        try {
-            const { removed, failed } = reapEphemeralHostWorkspaces();
-            if (removed.length > 0)
-                logger.info("shutdown_host_workspaces_reaped", { removed: removed.length });
-            if (failed.length > 0)
-                logger.warn("shutdown_host_workspace_reap_incomplete", { dirs: failed.map((f) => f.dir) });
-        }
-        catch (err) {
-            logger.warn("shutdown_host_workspace_reap_failed", { err: String(err) });
-        }
-    };
-    const onProcessExit = () => {
-        const onBooks = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
-        try {
-            reapOwnChildProcesses();
-        }
-        catch (err) {
-            console.error("shutdown_exit_boundary_child_reap_threw", err);
-        }
-        try {
-            reapOwnHostWorkspaces();
-        }
-        catch (err) {
-            console.error("shutdown_exit_boundary_workspace_reap_threw", err);
-        }
-        const left = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
-        try {
-            logger.info("shutdown_exit_boundary", { ...onBooks, leftForegroundChildren: left.foregroundChildren, leftHostWorkspaces: left.hostWorkspaces });
-            if (left.foregroundChildren > 0 || left.hostWorkspaces > 0)
-                logger.warn("shutdown_exit_boundary_incomplete", left);
-        }
-        catch (err) {
-            console.error("shutdown_exit_boundary_log_threw", err);
-        }
-    };
-    process.once("exit", onProcessExit);
+    const exitBoundary = installProcessExitBoundary({ logger });
     const onUncaughtException = (err) => {
         try {
             writeLastWords(err);
@@ -151,7 +94,7 @@ export function installShutdownHandlers(ctx) {
         subRunner.sessions.dispose();
         void lspManager?.dispose?.();
         void workflowNotifyJournal?.close?.();
-        reapOwnChildProcesses();
+        exitBoundary.reapChildProcessesEarly();
         void fleetClient?.stop();
         server.close(() => {
             void retentionTeardown.then(() => (backend ? backend.close() : Promise.resolve())).finally(() => process.exit(0));
@@ -248,7 +191,7 @@ export function installShutdownHandlers(ctx) {
             if (disposed)
                 return;
             disposed = true;
-            process.removeListener("exit", onProcessExit);
+            exitBoundary.dispose();
             process.removeListener("uncaughtException", onUncaughtException);
             process.removeListener("unhandledRejection", onUnhandledRejection);
             process.removeListener("SIGTERM", drainThenShutdown);

package/dist/hooks/hook-runner.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { hostShell, resolveHostShell } from "../plugins/host-platform.js";
+import { hostShell, resolveHostShell, adoptHostForegroundChild } from "../plugins/host-platform.js";
 import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, } from "@sema-agent/settings-schema/hooks";
 import { boundedNoticeText } from "../fleet/fleet-bus.js";
 import { recordFailOpen } from "../observability/fail-open.js";
@@ -271,6 +271,7 @@ function runCommandHook(entry, payload, ctx) {
             resolve({ code: null, stdout: "", stderr: "", timedOut: false, spawnError: String(e) });
             return;
         }
+        const ticket = adoptHostForegroundChild(child);
         let stdout = "";
         let stderr = "";
         let timedOut = false;
@@ -280,6 +281,7 @@ function runCommandHook(entry, payload, ctx) {
                 return;
             settled = true;
             clearTimeout(timer);
+            ticket?.release();
             resolve({ code, stdout, stderr, timedOut });
         };
         const timer = setTimeout(() => {
@@ -326,6 +328,7 @@ function fireAsyncCommandHook(entry, payload, ctx, event) {
             stdio: ["pipe", "ignore", rewake ? "pipe" : "ignore"],
             detached: true,
         });
+        const ticket = adoptHostForegroundChild(child);
         let killedByTimeout = false;
         const timer = setTimeout(() => {
             killedByTimeout = true;
@@ -355,6 +358,7 @@ function fireAsyncCommandHook(entry, payload, ctx, event) {
         });
         child.on("close", (code) => {
             clearTimeout(timer);
+            ticket?.release();
             noteAsyncOutcome(entry, ctx, event, payload, { code, rewake, killedByTimeout });
             if (!rewake || code !== 2)
                 return;

package/dist/observability/fail-open.d.ts

@@ -121,6 +121,22 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "运维待批队列(`GET /v1/approvals` / `/stream`)的某一行,`checkpoint.risk_descriptor` 这一格**不是合法 JSON 文本**(手改过的行 / 回滚残留 / 列语义漂;与同一 `rows.map` 里的 `rule_suggestions` 是同族坏法,两方言都是 TEXT 列)。放行的最坏后果 = **这一行**的分诊 descriptor 落 null:severity 折 0 排到有 descriptor 的行之后、`shadowedRule` 无可脱敏、读面派生的 `governanceForced` 徽章不亮 —— 三者都是**展示/分诊**,不是执法判据(门早已 park,真按 `shellGateDoctrine` 判的 `active-run-conflict.ts` 读的是 checkpoint blob 的 `get()`,不经本读面),且 `governanceForced` 的成文语义本就是「缺席 = 没有治理来源的**证据**」。不放行的代价是整只 `rows.map` 抛出 ⇒ 一行坏 cell 打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远空),连同其余所有行一起消失。故 F 类;tag 与候选那格**分开计**,并计会让「哪一格在坏」在遥测里读不出来。";
     };
+    readonly "server.sql-json.checkpoint.pending-steer-queue-lossy": {
+        readonly cls: "F";
+        readonly note: "S-550(`plugins/checkpoint-store-sql.ts` 的 `get()`,core 5.14.0 #147 的耐久转向队列):一条挂起 run 的 `checkpoint.pending_steer_queue` 这一格**没能完整读出来**(不是合法 JSON 文本 / 不是数组 / 某一条目的四个必备键不合形)⇒ 读不出的那部分**丢掉**,run 照常 resume。放行的最坏后果 = 一条已经 park 的操作员转向指令**没有**在这次 resume 上注入(人以为说过的话没送到);不放行的代价是这条挂起的 run **永远不可 resume** —— resume 是它唯一的出路,为一格读不出的转向把整条 run 变成砖是错误的失败方向(写侧刻意相反:`setPendingSteer` 往一份读不全的队列上追加会把读不出的条目永久抹掉,那里 fail-loud)。故 F 类。留痕从一条 `logger.info` 升成登记 tag 的理由:日志行在**遥测轴**上是零信号,「这台机器的转向队列一直读不出来」与「这台机器本来就没人 steer」在指标上完全同形。计数非零 = 去按日志里的 token 指纹查那一行。";
+    };
+    readonly "server.sql-json.checkpoint.outcome-unreadable": {
+        readonly cls: "F";
+        readonly note: "S-550(`plugins/checkpoint-store-sql.ts` 的 `findDecidedApprovalsForBinding`,`/decide` 的**幂等回放**腿):一条已决 checkpoint 行的 `outcome` 这一格读不出形(手改 / 撕裂写 / 迁移脚本改过)⇒ 这一行交出 `decision: null`(= 判别不出),调用方按「整次拒绝」处置。放行的最坏后果 = 一次 decide **重试**拿不到上次的判词,退回按新请求处理(而不是回放)—— 回放是锦上添花的腿,让一条读不出的 JSON 把一次重试变成 500 比这更坏;方向上没有任何批准被放宽(判不出就是判不出,调用方拒绝)。故 F 类。**只容忍体的问题**:`not-text`(读腿漏了投影)与连接/超时一律原样上抛 —— 那是码坏或故障,不是数据坏。";
+    };
+    readonly "server.sql-json.checkpoint.execution-outcome-unreadable": {
+        readonly cls: "F";
+        readonly note: "S-550(同上那条回放腿的第二格,`checkpoint.execution_outcome`,S-160 的执行判词):这一格读不出形 ⇒ 本行的 `executionOutcome` 交出 `null` = 「不知道这次批准有没有真的执行过」。放行的最坏后果 = 回放腿少一条「已执行」的证据,消费端据此**保守**处理(缺席在 core 的 `executionVerdict` 里读作 `unknown`,从来不读作「放行过」);不放行的代价与上一格同(一次 decide 重试 500)。⚠️ 同一格在 `get()` / `recordExecutionOutcome` 两条腿上**刻意相反**(抛,不容忍):那两条是结算记录的读写口,静默当缺席会让一份不同的记录覆盖已经在案的那份。tag 与上一格**分开计**:并计会让「哪一格在坏」在遥测里读不出来。";
+    };
+    readonly "server.sql-json.task-run.usage-result-unreadable": {
+        readonly cls: "F";
+        readonly note: "S-550(`plugins/run-store-sql.ts` 的 `usageScan`,`/v1/usage/*` 的扫窗腿):窗内某一行的 `task_run.result` 这一格读不出形 ⇒ 这一行**计 tasks、不计 token/cost**(`stats` 键缺席),其余行照常。放行的最坏后果 = 用量总数偏低一行的量(`projectUsageStats` 的成文降级口径逐字如此,三个后端共用);不放行的代价是**一行坏 cell 打掉整个租户的用量页**(扫窗上限 50k 行)。⚠️ 同一列在 `getRun` / `listRuns` 两条腿上**刻意相反**(抛,不容忍):那两条腿上这一格是提交方要的**答案**,把它折成「跑完了没有结果」是在替一次不知道的读编一个答案;而这里它只是一个加数。故 F 类;**只容忍体的问题**,`not-text`(读腿漏了投影)与连接 / 超时原样上抛。";
+    };
     readonly "server.retention.sweep-report-dropped": {
         readonly cls: "F";
         readonly note: "留存 sweep 的**失败上报**自己抛了(poison error 的 toString / 一条抛异常的 logger transport)⇒ 那一条 warn 与 stuck 指标发不出去。放行的最坏后果是**可观测性**损失而不是数据面损失:删除与审计的正确性完全在店事务里,本臂只影响运维看不看得见「这个域连败了」。不放行的后果反而更坏 —— 一个从上报里逃出去的异常会打断 per-domain 循环、饿死后面每一个域(reapers 的同款保护逐字同理由)。";

package/dist/observability/fail-open.js

@@ -112,6 +112,22 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "运维待批队列(`GET /v1/approvals` / `/stream`)的某一行,`checkpoint.risk_descriptor` 这一格**不是合法 JSON 文本**(手改过的行 / 回滚残留 / 列语义漂;与同一 `rows.map` 里的 `rule_suggestions` 是同族坏法,两方言都是 TEXT 列)。放行的最坏后果 = **这一行**的分诊 descriptor 落 null:severity 折 0 排到有 descriptor 的行之后、`shadowedRule` 无可脱敏、读面派生的 `governanceForced` 徽章不亮 —— 三者都是**展示/分诊**,不是执法判据(门早已 park,真按 `shellGateDoctrine` 判的 `active-run-conflict.ts` 读的是 checkpoint blob 的 `get()`,不经本读面),且 `governanceForced` 的成文语义本就是「缺席 = 没有治理来源的**证据**」。不放行的代价是整只 `rows.map` 抛出 ⇒ 一行坏 cell 打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远空),连同其余所有行一起消失。故 F 类;tag 与候选那格**分开计**,并计会让「哪一格在坏」在遥测里读不出来。",
     },
+    "server.sql-json.checkpoint.pending-steer-queue-lossy": {
+        cls: "F",
+        note: "S-550(`plugins/checkpoint-store-sql.ts` 的 `get()`,core 5.14.0 #147 的耐久转向队列):一条挂起 run 的 `checkpoint.pending_steer_queue` 这一格**没能完整读出来**(不是合法 JSON 文本 / 不是数组 / 某一条目的四个必备键不合形)⇒ 读不出的那部分**丢掉**,run 照常 resume。放行的最坏后果 = 一条已经 park 的操作员转向指令**没有**在这次 resume 上注入(人以为说过的话没送到);不放行的代价是这条挂起的 run **永远不可 resume** —— resume 是它唯一的出路,为一格读不出的转向把整条 run 变成砖是错误的失败方向(写侧刻意相反:`setPendingSteer` 往一份读不全的队列上追加会把读不出的条目永久抹掉,那里 fail-loud)。故 F 类。留痕从一条 `logger.info` 升成登记 tag 的理由:日志行在**遥测轴**上是零信号,「这台机器的转向队列一直读不出来」与「这台机器本来就没人 steer」在指标上完全同形。计数非零 = 去按日志里的 token 指纹查那一行。",
+    },
+    "server.sql-json.checkpoint.outcome-unreadable": {
+        cls: "F",
+        note: "S-550(`plugins/checkpoint-store-sql.ts` 的 `findDecidedApprovalsForBinding`,`/decide` 的**幂等回放**腿):一条已决 checkpoint 行的 `outcome` 这一格读不出形(手改 / 撕裂写 / 迁移脚本改过)⇒ 这一行交出 `decision: null`(= 判别不出),调用方按「整次拒绝」处置。放行的最坏后果 = 一次 decide **重试**拿不到上次的判词,退回按新请求处理(而不是回放)—— 回放是锦上添花的腿,让一条读不出的 JSON 把一次重试变成 500 比这更坏;方向上没有任何批准被放宽(判不出就是判不出,调用方拒绝)。故 F 类。**只容忍体的问题**:`not-text`(读腿漏了投影)与连接/超时一律原样上抛 —— 那是码坏或故障,不是数据坏。",
+    },
+    "server.sql-json.checkpoint.execution-outcome-unreadable": {
+        cls: "F",
+        note: "S-550(同上那条回放腿的第二格,`checkpoint.execution_outcome`,S-160 的执行判词):这一格读不出形 ⇒ 本行的 `executionOutcome` 交出 `null` = 「不知道这次批准有没有真的执行过」。放行的最坏后果 = 回放腿少一条「已执行」的证据,消费端据此**保守**处理(缺席在 core 的 `executionVerdict` 里读作 `unknown`,从来不读作「放行过」);不放行的代价与上一格同(一次 decide 重试 500)。⚠️ 同一格在 `get()` / `recordExecutionOutcome` 两条腿上**刻意相反**(抛,不容忍):那两条是结算记录的读写口,静默当缺席会让一份不同的记录覆盖已经在案的那份。tag 与上一格**分开计**:并计会让「哪一格在坏」在遥测里读不出来。",
+    },
+    "server.sql-json.task-run.usage-result-unreadable": {
+        cls: "F",
+        note: "S-550(`plugins/run-store-sql.ts` 的 `usageScan`,`/v1/usage/*` 的扫窗腿):窗内某一行的 `task_run.result` 这一格读不出形 ⇒ 这一行**计 tasks、不计 token/cost**(`stats` 键缺席),其余行照常。放行的最坏后果 = 用量总数偏低一行的量(`projectUsageStats` 的成文降级口径逐字如此,三个后端共用);不放行的代价是**一行坏 cell 打掉整个租户的用量页**(扫窗上限 50k 行)。⚠️ 同一列在 `getRun` / `listRuns` 两条腿上**刻意相反**(抛,不容忍):那两条腿上这一格是提交方要的**答案**,把它折成「跑完了没有结果」是在替一次不知道的读编一个答案;而这里它只是一个加数。故 F 类;**只容忍体的问题**,`not-text`(读腿漏了投影)与连接 / 超时原样上抛。",
+    },
     "server.retention.sweep-report-dropped": {
         cls: "F",
         note: "留存 sweep 的**失败上报**自己抛了(poison error 的 toString / 一条抛异常的 logger transport)⇒ 那一条 warn 与 stuck 指标发不出去。放行的最坏后果是**可观测性**损失而不是数据面损失:删除与审计的正确性完全在店事务里,本臂只影响运维看不看得见「这个域连败了」。不放行的后果反而更坏 —— 一个从上报里逃出去的异常会打断 per-domain 循环、饿死后面每一个域(reapers 的同款保护逐字同理由)。",

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

@@ -515,7 +515,7 @@ export declare function ensurePgApprovalAskSchema(q: PgQueryFn): Promise<void>;
  *
  * 病:本仓不发 `ALTER TABLE`(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升上来
  * 的部署,`CREATE TABLE IF NOT EXISTS` 对存量 `approval_ask` 是空操作 —— 本车新加的
- * `rule_command` / `rule_scope_root` 两列不在,而 `ensureAsk` 的 INSERT 与 `ASK_COLS` 的每一条读
+ * `rule_command` / `rule_scope_root` 两列不在,而 `ensureAsk` 的 INSERT 与 `askCols` 的每一条读
  * **无条件**引用它们。后果不是「少一个新功能」,是**整条流内审批协议**在那台机器上是坏的:
  *  · 每一只 ask 的 `ensureAsk` 撞 unknown column ⇒ 被 `noteStoreError` 吞掉 ⇒ 整只 ask 退回 park 路由
  *    (卡不落库、`GET /v1/approvals` 的重放面恒空、迟到决议腿恒 404);

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

@@ -1,6 +1,7 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { canAskTransition } from "../approval-ask-machine.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readAnyJsonValueColumn, readJsonObjectColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
 export function assertIntegralEpochMs(field, value) {
     if (!Number.isSafeInteger(value)) {
@@ -211,7 +212,7 @@ export async function ensurePgApprovalAskSchema(q) {
 }
 export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
     try {
-        await query(`SELECT rule_command, rule_scope_root, updated_input FROM ${APPROVAL_ASK_TABLE} WHERE 1=0`);
+        await query(`SELECT rule_command, rule_scope_root, ${jsonColumnText(dialect, "updated_input")} FROM ${APPROVAL_ASK_TABLE} WHERE 1=0`);
     }
     catch (err) {
         if (!isMissingColumnError(err, dialect))
@@ -231,14 +232,21 @@ export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
             `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-const ASK_COLS = "ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, " +
-    "provisional, rev, decision, decision_actor, decision_note, settled_by, updated_input, decided_at_ms, denied_reason, gate_token, " +
-    "gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, " +
-    "created_at_ms, updated_at_ms";
-const BATCH_COLS = "batch_id, task_id, state, bound_ask_id, rev, created_at_ms, updated_at_ms";
-function parseJsonColumn(v) {
-    return JSON.parse(String(v));
+function askCols(dialect) {
+    return [
+        "ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state",
+        "provisional, rev, decision",
+        jsonColumnText(dialect, "decision_actor"),
+        "decision_note, settled_by",
+        jsonColumnText(dialect, "updated_input"),
+        "decided_at_ms, denied_reason, gate_token",
+        "gate_bound_call_id, gate_bound_input_hash, idempotency_key",
+        jsonColumnText(dialect, "card_json"),
+        "rule_command, rule_scope_root, schema_version, expires_at_ms",
+        "created_at_ms, updated_at_ms",
+    ].join(", ");
 }
+const BATCH_COLS = "batch_id, task_id, state, bound_ask_id, rev, created_at_ms, updated_at_ms";
 function toBool(v) {
     return Boolean(Number(v));
 }
@@ -249,6 +257,15 @@ function strOrNull(v) {
     return v === null || v === undefined ? null : String(v);
 }
 function mapAskRow(r) {
+    const askId = String(r.ask_id);
+    try {
+        return mapAskRowBody(r, askId);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`approval-ask-store: ${m} — refusing rather than serve an ask row nobody can read`));
+    }
+}
+function mapAskRowBody(r, askId) {
     return {
         askId: String(r.ask_id),
         taskId: String(r.task_id),
@@ -264,17 +281,17 @@ function mapAskRow(r) {
         provisional: toBool(r.provisional),
         rev: Number(r.rev),
         decision: strOrNull(r.decision) ?? null,
-        decisionActor: r.decision_actor == null ? null : parseJsonColumn(r.decision_actor),
+        decisionActor: r.decision_actor == null ? null : decodeJsonColumn(r.decision_actor, readJsonObjectColumn, `${APPROVAL_ASK_TABLE}.decision_actor for ask ${askId}`),
         decisionNote: strOrNull(r.decision_note),
         settledBy: strOrNull(r.settled_by),
-        ...(r.updated_input == null ? {} : { updatedInput: parseJsonColumn(r.updated_input) }),
+        ...(r.updated_input == null ? {} : { updatedInput: decodeJsonColumn(r.updated_input, readAnyJsonValueColumn, `${APPROVAL_ASK_TABLE}.updated_input for ask ${askId}`) }),
         decidedAtMs: numOrNull(r.decided_at_ms),
         deniedReason: strOrNull(r.denied_reason),
         gateToken: strOrNull(r.gate_token),
         gateBoundCallId: strOrNull(r.gate_bound_call_id),
         gateBoundInputHash: strOrNull(r.gate_bound_input_hash),
         idempotencyKey: strOrNull(r.idempotency_key),
-        cardJson: parseJsonColumn(r.card_json),
+        cardJson: decodeJsonColumn(r.card_json, readJsonObjectColumn, `${APPROVAL_ASK_TABLE}.card_json for ask ${askId}`),
         ruleCommand: strOrNull(r.rule_command),
         ruleScopeRoot: strOrNull(r.rule_scope_root),
         schemaVersion: Number(r.schema_version),
@@ -337,7 +354,7 @@ export class SqlApprovalAskStore {
         return isDupKeyError(this.db.dialect, e);
     }
     async getAskOn(conn, askId) {
-        const { rows } = await conn.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [askId]);
+        const { rows } = await conn.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [askId]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async getBatchOn(conn, batchId) {
@@ -485,7 +502,7 @@ export class SqlApprovalAskStore {
             }
             const askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 2)} WHERE ${pendingClaimWhere(dialect, 3)}`, [to, now, askId, batchId]);
             if (askRes.affected !== 1) {
-                const sel = await conn.query(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ${ph(dialect, 1)} AND batch_id = ${ph(dialect, 2)} FOR UPDATE`, [askId, batchId]);
+                const sel = await conn.query(`SELECT ${askCols(dialect)} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ${ph(dialect, 1)} AND batch_id = ${ph(dialect, 2)} FOR UPDATE`, [askId, batchId]);
                 await conn.rollback();
                 return { claimed: false, current: projectAskTerminalClaimTruth(sel.rows[0] ? mapAskRow(sel.rows[0]) : null) };
             }
@@ -614,32 +631,32 @@ export class SqlApprovalAskStore {
         }
     }
     async listByState(state, limit) {
-        const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE state = ? ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE state = $1 ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT $2`), [state, limit]);
+        const { rows } = await this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE state = ? ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE state = $1 ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT $2`), [state, limit]);
         return rows.map(mapAskRow);
     }
     async listPendingByTask(taskId, signal) {
         if (signal?.aborted === true)
             throw abortedReadError("listPendingByTask");
-        const { rows } = await withReadSignal(this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`), [taskId]), signal, "listPendingByTask");
+        const { rows } = await withReadSignal(this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`), [taskId]), signal, "listPendingByTask");
         return rows.map(mapAskRow);
     }
     async listPendingBySession(sessionId, owner, signal) {
         if (signal?.aborted === true)
             throw abortedReadError("listPendingBySession");
         const { rows } = await withReadSignal(this.db.query(owner === null
-            ? this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`)
-            : this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner = ? ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner = $2 ORDER BY created_at_ms ASC`), owner === null ? [sessionId] : [sessionId, owner]), signal, "listPendingBySession");
+            ? this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`)
+            : this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner = ? ORDER BY created_at_ms ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner = $2 ORDER BY created_at_ms ASC`), owner === null ? [sessionId] : [sessionId, owner]), signal, "listPendingBySession");
         return rows.map(mapAskRow);
     }
     async getAsk(askId) {
-        const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [
+        const { rows } = await this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [
             askId,
         ]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async getByIdempotencyKey(taskId, key) {
         assertIdempotencyKeyShape(key);
-        const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND idempotency_key = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND idempotency_key = $2`), [taskId, key]);
+        const { rows } = await this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND idempotency_key = ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND idempotency_key = $2`), [taskId, key]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async deferReconcile(askId, expectedState, expectedRev, nowMs) {

package/dist/plugins/background-agent-store-sql.js

@@ -2,8 +2,30 @@ import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, } from "@sem
 import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
-const SUMMARY_COLS = "handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json";
+function summaryCols(dialect) {
+    return ("handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, " +
+        `spawned_at_ms, updated_at_ms, settled_at_ms, ${jsonColumnText(dialect, "usage_json")}`);
+}
+const readAgentRecordBody = createObjectColumnReader();
+const readUsageBody = createObjectColumnReader();
+function readRecordColumn(v, handle) {
+    try {
+        return decodeJsonColumn(v, readAgentRecordBody, `${BACKGROUND_AGENT_TABLE}.record_json for handle ${handle}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`BackgroundAgentStore: ${m} — refusing rather than serve a hollow agent record`));
+    }
+}
+function readUsageColumn(v, handle) {
+    try {
+        return decodeNullableJsonColumn(v, readUsageBody, `${BACKGROUND_AGENT_TABLE}.usage_json for handle ${handle}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`BackgroundAgentStore: ${m} — refusing rather than report a usage figure nobody can read`));
+    }
+}
 const PROJ_COLS = "scope, owner, session_scoped, session_id, parent_session_id, root_session_id, session_anchor, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json, rev, parked_checkpoint_token, park_claim_id, admitted_org_scopes, admitted_org_write_scope, record_json";
 const PROJ_N = PROJ_COLS.split(", ").length;
 function assertScope(record) {
@@ -52,9 +74,7 @@ function rowToSummary(r) {
         spawnedAt: Number(r.spawned_at_ms),
         updatedAt: Number(r.updated_at_ms),
         ...(r.settled_at_ms !== null && r.settled_at_ms !== undefined ? { settledAt: Number(r.settled_at_ms) } : {}),
-        ...(r.usage_json !== null && r.usage_json !== undefined
-            ? { usage: JSON.parse(String(r.usage_json)) }
-            : {}),
+        ...((u) => (u === undefined ? {} : { usage: u }))(readUsageColumn(r.usage_json, String(r.handle))),
     };
 }
 function flippedForm(live, now) {
@@ -192,8 +212,8 @@ export class TiDBBackgroundAgentStore {
         }
     }
     async get(handle, scope) {
-        const [rows] = (await this.pool.query(`SELECT record_json FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]));
-        return rows.length > 0 ? JSON.parse(String(rows[0].record_json)) : null;
+        const [rows] = (await this.pool.query(`SELECT ${jsonColumnText("tidb", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]));
+        return rows.length > 0 ? readRecordColumn(rows[0].record_json, handle) : null;
     }
     async update(handle, scope, record, expect) {
         const stored = storedForm(record, handle, scope, expect.rev + 1);
@@ -211,12 +231,12 @@ export class TiDBBackgroundAgentStore {
         return res.affectedRows === 1;
     }
     async listBySession(scope, sessionId, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${SUMMARY_COLS} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
+        const [rows] = (await this.pool.query(`SELECT ${summaryCols("tidb")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
        ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]));
         return rows.map(rowToSummary);
     }
     async listByScope(scope, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${SUMMARY_COLS} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
+        const [rows] = (await this.pool.query(`SELECT ${summaryCols("tidb")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
        ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]));
         return rows.map(rowToSummary);
     }
@@ -229,9 +249,9 @@ export class TiDBBackgroundAgentStore {
             return 0;
         const flipped = new Set();
         if (opts.staleRunningMaxAgeMs !== undefined) {
-            const [stale] = (await this.pool.query(`SELECT handle, record_json FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
+            const [stale] = (await this.pool.query(`SELECT handle, ${jsonColumnText("tidb", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
             for (const row of stale) {
-                const live = JSON.parse(String(row.record_json));
+                const live = readRecordColumn(row.record_json, String(row.handle));
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     flipped.add(String(row.handle));
             }
@@ -272,8 +292,8 @@ export class PgBackgroundAgentStore {
         }
     }
     async get(handle, scope) {
-        const { rows } = await this.q(`SELECT record_json FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
-        return rows.length > 0 ? JSON.parse(String(rows[0].record_json)) : null;
+        const { rows } = await this.q(`SELECT ${jsonColumnText("pg", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
+        return rows.length > 0 ? readRecordColumn(rows[0].record_json, handle) : null;
     }
     async update(handle, scope, record, expect) {
         const stored = storedForm(record, handle, scope, expect.rev + 1);
@@ -293,12 +313,12 @@ export class PgBackgroundAgentStore {
         return rows.length === 1;
     }
     async listBySession(scope, sessionId, opts) {
-        const { rows } = await this.q(`SELECT ${SUMMARY_COLS} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND (session_anchor = $2 OR root_session_id = $3)${opts?.status !== undefined ? " AND status = $4" : ""}
+        const { rows } = await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND (session_anchor = $2 OR root_session_id = $3)${opts?.status !== undefined ? " AND status = $4" : ""}
        ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]);
         return rows.map(rowToSummary);
     }
     async listByScope(scope, opts) {
-        const { rows } = await this.q(`SELECT ${SUMMARY_COLS} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1${opts?.status !== undefined ? " AND status = $2" : ""}
+        const { rows } = await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1${opts?.status !== undefined ? " AND status = $2" : ""}
        ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]);
         return rows.map(rowToSummary);
     }
@@ -311,9 +331,9 @@ export class PgBackgroundAgentStore {
             return 0;
         const affected = new Set();
         if (opts.staleRunningMaxAgeMs !== undefined) {
-            const { rows: stale } = await this.q(`SELECT handle, record_json FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status = 'running' AND updated_at_ms < $2`, [scope, now - opts.staleRunningMaxAgeMs]);
+            const { rows: stale } = await this.q(`SELECT handle, ${jsonColumnText("pg", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status = 'running' AND updated_at_ms < $2`, [scope, now - opts.staleRunningMaxAgeMs]);
             for (const row of stale) {
-                const live = JSON.parse(String(row.record_json));
+                const live = readRecordColumn(row.record_json, String(row.handle));
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     affected.add(String(row.handle));
             }

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

@@ -381,8 +381,12 @@ export declare function approvalDecisionOfWinner(winner: ResolvedOutcome | undef
  *  - `{ readable: true, toolCallId: "…" }`  —— 读出来了,拿去比。
  *
  * 逐层 `typeof` 收窄,不做裸 `as` 断言:blob 是持久层读回来的 `unknown`,是信任边界(宪法 [ref])。
+ *
+ * 🔴 S-550:入参是**已经解过码的体**,不是一格列文本 —— 本函数不再自己 `JSON.parse`(SQL 车道的解码
+ * 唯一属主是 `sql-json-column.ts`,见 {@link pendingActionOfColumn};local 孪生本来就递一只对象进来)。
+ * 于是「串就再解一次」这条读法在这里按构造消失,两条车道递进来的东西同形。
  */
-export declare function pendingActionToolCallId(blob: unknown): {
+export declare function pendingActionToolCallId(body: unknown): {
     readable: true;
     toolCallId: string | null;
     boundInputHash: string | null;