@sema-agent/server 7.93.4 → 7.93.6

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

@@ -4,7 +4,7 @@ import { APPROVAL_GATE_KINDS_SQL_IN } 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 { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, screenUncoveredDetailSeat } from "../approval-card.js";
-import { parseJsonStrict as parseJson } from "./sql-row-helpers.js";
+import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readAnyJsonValueColumn, 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";
@@ -113,22 +113,61 @@ export function boundedRuleOffers(raw, opts = {}) {
     }
     return out.length > 0 ? out : undefined;
 }
+const readCheckpointBlobBody = createObjectColumnReader();
+const readResumeOutcomeBody = createObjectColumnReader();
+const readGateOutcomeBody = createObjectColumnReader();
+const readRiskDescriptorBody = createObjectColumnReader();
+function readJsonArrayBody(body) {
+    return Array.isArray(body) ? { value: body } : { problem: "expected a JSON array" };
+}
+function decodeCheckpointColumn(cell, where) {
+    return decodeJsonColumn(cell, readCheckpointBlobBody, `checkpoint.checkpoint ${where}`);
+}
+function decodeOutcomeColumn(cell, where) {
+    return decodeNullableJsonColumn(cell, readResumeOutcomeBody, `checkpoint.outcome ${where}`);
+}
+function decodeExecutionOutcomeColumn(cell, where) {
+    return decodeNullableJsonColumn(cell, readGateOutcomeBody, `checkpoint.execution_outcome ${where}`);
+}
+function decodeToolInputColumn(cell) {
+    return decodeNullableJsonColumn(cell, readNonNullJsonValueColumn, "checkpoint.tool_input (operator queue row)");
+}
+function decodeCtxColumn(cell, where) {
+    const body = decodeJsonColumn(cell, readAnyJsonValueColumn, `checkpoint_ctx.ctx ${where}`);
+    return body;
+}
+function refusing(what, read) {
+    try {
+        return read();
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`SqlCheckpointStore: ${m} — refusing rather than serve ${what}`));
+    }
+}
 function readRuleOffersCell(cell) {
+    if (cell === null)
+        return undefined;
     let parsed;
     try {
-        parsed = parseJson(cell);
+        parsed = decodeJsonColumn(cell, readJsonArrayBody, "checkpoint.rule_suggestions (operator queue row)");
     }
-    catch {
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
         recordFailOpen("server.approvals.rule-suggestions-cell-unreadable");
         return undefined;
     }
     return boundedRuleOffers(parsed, { countRedactions: false });
 }
 function readRiskDescriptorCell(cell) {
+    if (cell === null)
+        return null;
     try {
-        return parseJson(cell);
+        return decodeJsonColumn(cell, readRiskDescriptorBody, "checkpoint.risk_descriptor (operator queue row)");
     }
-    catch {
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
         recordFailOpen("server.approvals.risk-descriptor-cell-unreadable");
         return null;
     }
@@ -166,23 +205,16 @@ export function approvalDecisionOfWinner(winner, boundCallId) {
         }
     }
 }
-export function pendingActionToolCallId(blob) {
-    let parsed;
-    try {
-        parsed = typeof blob === "string" ? JSON.parse(blob) : blob;
-    }
-    catch {
-        return { readable: false };
-    }
-    if (typeof parsed !== "object" || parsed === null)
+export function pendingActionToolCallId(body) {
+    if (typeof body !== "object" || body === null)
         return { readable: false };
-    const rawSource = "sourceTaskId" in parsed ? parsed.sourceTaskId : null;
+    const rawSource = "sourceTaskId" in body ? body.sourceTaskId : null;
     if (rawSource !== null && rawSource !== undefined && typeof rawSource !== "string")
         return { readable: false };
     const sourceTaskId = typeof rawSource === "string" ? rawSource : null;
-    if (!("pendingAction" in parsed))
+    if (!("pendingAction" in body))
         return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceTaskId };
-    const pa = parsed.pendingAction;
+    const pa = body.pendingAction;
     if (typeof pa !== "object" || pa === null)
         return { readable: false };
     const kind = "kind" in pa ? pa.kind : null;
@@ -200,6 +232,18 @@ export function pendingActionToolCallId(blob) {
         return { readable: false };
     return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceTaskId };
 }
+function pendingActionOfColumn(cell, where) {
+    let body;
+    try {
+        body = decodeJsonColumn(cell, readJsonObjectColumn, `checkpoint.checkpoint ${where}`);
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        return { readable: false };
+    }
+    return pendingActionToolCallId(body);
+}
 function readActorAssertion(v) {
     if (typeof v !== "object" || v === null)
         return undefined;
@@ -236,33 +280,24 @@ function readQueueEntry(v) {
 }
 export function readPendingSteerQueueColumn(queueRaw) {
     let lossy = false;
-    const parse = (raw) => {
-        if (raw === null || raw === undefined)
-            return undefined;
-        if (typeof raw !== "string")
-            return raw;
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            lossy = true;
-            return undefined;
-        }
-    };
-    const queueParsed = parse(queueRaw);
+    let items;
+    try {
+        items = decodeNullableJsonColumn(queueRaw, readJsonArrayBody, "checkpoint.pending_steer_queue");
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        lossy = true;
+    }
     let queue;
-    if (queueParsed !== undefined) {
-        if (!Array.isArray(queueParsed))
-            lossy = true;
-        else {
-            queue = [];
-            for (const item of queueParsed) {
-                const entry = readQueueEntry(item);
-                if (entry === undefined)
-                    lossy = true;
-                else
-                    queue.push(entry);
-            }
+    if (items !== undefined) {
+        queue = [];
+        for (const item of items) {
+            const entry = readQueueEntry(item);
+            if (entry === undefined)
+                lossy = true;
+            else
+                queue.push(entry);
         }
     }
     return { state: { ...(queue !== undefined ? { pendingSteerQueue: queue } : {}) }, lossy };
@@ -359,7 +394,9 @@ export class SqlCheckpointStore {
         }
     }
     async get(token) {
-        const { rows } = await this.db.query(this.q("SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer_queue, execution_outcome, execution_at_ms FROM checkpoint WHERE token = ?", "SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer_queue, execution_outcome, execution_at_ms FROM checkpoint WHERE token = $1"), [token]);
+        const { rows } = await this.db.query(this.q(`SELECT version, status, ${jsonColumnText("tidb", "checkpoint")}, ${jsonColumnText("tidb", "outcome")}, reopen_reason, rev, ` +
+            `${jsonColumnText("tidb", "pending_steer_queue")}, ${jsonColumnText("tidb", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = ?`, `SELECT version, status, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnText("pg", "outcome")}, reopen_reason, rev, ` +
+            `${jsonColumnText("pg", "pending_steer_queue")}, ${jsonColumnText("pg", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = $1`), [token]);
         const r = rows[0];
         if (!r)
             return null;
@@ -367,21 +404,22 @@ export class SqlCheckpointStore {
         if (version > MAX_SUPPORTED_CHECKPOINT_VERSION) {
             throw new Error(`checkpoint format version ${version} is newer than this build supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION}) — upgrade the service to resume it`);
         }
-        const cp = parseJson(r.checkpoint);
+        const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `for token ${tokenFingerprint(token)}`));
         cp.status = r.status;
-        const outcomeRaw = parseJson(r.outcome);
+        const outcomeRaw = refusing("a decision record nobody can read", () => decodeOutcomeColumn(r.outcome, `for token ${tokenFingerprint(token)}`));
         if (outcomeRaw)
             cp.resolvedOutcome = winnerFromOutcome(outcomeRaw);
         cp.reopenReason = r.reopen_reason ?? undefined;
         cp.rev = r.rev == null ? 0 : Number(r.rev);
-        const executionOutcome = parseJson(r.execution_outcome);
-        if (executionOutcome !== null) {
+        const executionOutcome = refusing("an execution record nobody can read", () => decodeExecutionOutcomeColumn(r.execution_outcome, `for token ${tokenFingerprint(token)}`));
+        if (executionOutcome !== undefined) {
             cp.executionOutcome = executionOutcome;
             if (r.execution_at_ms != null)
                 cp.executionAtMs = Number(r.execution_at_ms);
         }
         const steer = readPendingSteerQueueColumn(r.pending_steer_queue);
         if (steer.lossy) {
+            recordFailOpen("server.sql-json.checkpoint.pending-steer-queue-lossy");
             this.logger?.info?.("checkpoint_pending_steer_unreadable", { tokenFp: tokenFingerprint(token) });
         }
         if (cp.state) {
@@ -412,14 +450,14 @@ export class SqlCheckpointStore {
     }
     async recordExecutionOutcome(token, scope, gate) {
         for (let attempt = 0; attempt < EXECUTION_RECORD_CAS_ATTEMPTS; attempt++) {
-            const { rows } = await this.db.query(this.q("SELECT scope, status, execution_outcome FROM checkpoint WHERE token = ?", "SELECT scope, status, execution_outcome FROM checkpoint WHERE token = $1"), [token]);
+            const { rows } = await this.db.query(this.q(`SELECT scope, status, ${jsonColumnText("tidb", "execution_outcome")} FROM checkpoint WHERE token = ?`, `SELECT scope, status, ${jsonColumnText("pg", "execution_outcome")} FROM checkpoint WHERE token = $1`), [token]);
             const row = rows[0];
             const facts = row === undefined
                 ? undefined
                 : {
                     scope: String(row.scope),
                     status: row.status,
-                    ...((v) => (v === null ? {} : { executionOutcome: v }))(parseJson(row.execution_outcome)),
+                    ...((v) => (v === undefined ? {} : { executionOutcome: v }))(refusing("an execution record nobody can read", () => decodeExecutionOutcomeColumn(row.execution_outcome, `for token ${tokenFingerprint(token)}`))),
                 };
             const disposition = executionRecordDisposition(facts, scope, gate);
             if (disposition === "conflict")
@@ -436,7 +474,7 @@ export class SqlCheckpointStore {
     async setPendingSteer(token, scope, steer) {
         const clean = validatePendingSteer(steer);
         for (let attempt = 0; attempt < STEER_CAS_ATTEMPTS; attempt++) {
-            const { rows } = await this.db.query(this.q("SELECT status, pending_steer_queue, pending_steer_rev FROM checkpoint WHERE token = ? AND scope = ?", "SELECT status, pending_steer_queue, pending_steer_rev FROM checkpoint WHERE token = $1 AND scope = $2"), [token, scope]);
+            const { rows } = await this.db.query(this.q(`SELECT status, ${jsonColumnText("tidb", "pending_steer_queue")}, pending_steer_rev FROM checkpoint WHERE token = ? AND scope = ?`, `SELECT status, ${jsonColumnText("pg", "pending_steer_queue")}, pending_steer_rev FROM checkpoint WHERE token = $1 AND scope = $2`), [token, scope]);
             const row = rows[0];
             if (!row || row.status !== "pending")
                 return false;
@@ -480,7 +518,9 @@ export class SqlCheckpointStore {
         return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
     }
     async listPending(scope) {
-        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.rule_suggestions, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id " +
+        const d = this.db.dialect;
+        const base = `SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
+            `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id ` +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         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])
@@ -500,7 +540,7 @@ export class SqlCheckpointStore {
                 ...(boundInputHash !== null ? { boundInputHash } : {}),
                 ...(gateKind !== null ? { gateKind } : {}),
                 taskId: r.task_id ?? null,
-                input: r.tool_input ?? 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),
@@ -512,12 +552,10 @@ export class SqlCheckpointStore {
         return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
     }
     async listByScope(scope) {
-        const { rows } = await this.db.query(this.q("SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at_ms ASC LIMIT 500", "SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at_ms ASC LIMIT 500"), [scope]);
+        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at_ms ASC LIMIT 500`, `SELECT ${jsonColumnText("pg", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at_ms ASC LIMIT 500`), [scope]);
         const out = [];
         for (const r of rows) {
-            const cp = parseJson(r.checkpoint);
-            if (!cp)
-                continue;
+            const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `in the ${scope} scheduler view`));
             cp.status = r.status;
             out.push(summarizeCheckpoint(cp));
         }
@@ -529,8 +567,8 @@ export class SqlCheckpointStore {
         return rows[0] ? String(rows[0].token) : null;
     }
     async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
-        const { rows } = await this.db.query(this.q("SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
-            "WHERE scope=? AND session_id=? AND created_at_ms>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at_ms ASC", "SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
+        const { rows } = await this.db.query(this.q(`SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, ${jsonColumnText("tidb", "checkpoint")} FROM checkpoint ` +
+            "WHERE scope=? AND session_id=? AND created_at_ms>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at_ms ASC", `SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, ${jsonColumnText("pg", "checkpoint")} FROM checkpoint ` +
             "WHERE scope=$1 AND session_id=$2 AND created_at_ms>=$3 AND (tool_call_id=$4 OR tool_call_id IS NULL) ORDER BY created_at_ms ASC"), [scope, sessionId, sinceMs, toolCallId]);
         const out = [];
         for (const r of rows) {
@@ -545,7 +583,7 @@ export class SqlCheckpointStore {
                 out.push({ ...base, boundCallId: null, unparseable: true });
                 continue;
             }
-            const derived = pendingActionToolCallId(r.checkpoint);
+            const derived = pendingActionOfColumn(r.checkpoint, `for token ${tokenFingerprint(String(r.token))}`);
             if (!derived.readable) {
                 out.push({ ...base, boundCallId: null, unparseable: true });
                 continue;
@@ -567,24 +605,31 @@ export class SqlCheckpointStore {
         return out;
     }
     async findDecidedApprovalsForBinding(sessionId, boundCallId) {
-        const { rows } = await this.db.query(this.q("SELECT scope, bound_input_hash, outcome, execution_outcome FROM checkpoint " +
-            `WHERE session_id=? AND tool_call_id=? AND status='resolved' AND decided_at_ms IS NOT NULL ORDER BY decided_at_ms DESC LIMIT ${DECIDED_REPLAY_SCAN_CAP}`, "SELECT scope, bound_input_hash, outcome, execution_outcome FROM checkpoint " +
+        const { rows } = await this.db.query(this.q(`SELECT scope, bound_input_hash, ${jsonColumnText("tidb", "outcome")}, ${jsonColumnText("tidb", "execution_outcome")} FROM checkpoint ` +
+            `WHERE session_id=? AND tool_call_id=? AND status='resolved' AND decided_at_ms IS NOT NULL ORDER BY decided_at_ms DESC LIMIT ${DECIDED_REPLAY_SCAN_CAP}`, `SELECT scope, bound_input_hash, ${jsonColumnText("pg", "outcome")}, ${jsonColumnText("pg", "execution_outcome")} FROM checkpoint ` +
             `WHERE session_id=$1 AND tool_call_id=$2 AND status='resolved' AND decided_at_ms IS NOT NULL ORDER BY decided_at_ms DESC LIMIT ${DECIDED_REPLAY_SCAN_CAP}`), [sessionId, boundCallId]);
         return rows.map((r) => {
             let winner;
             try {
-                const outcome = parseJson(r.outcome);
+                const outcome = decodeOutcomeColumn(r.outcome, `for the decided row of session ${sessionId}`);
                 winner = outcome ? winnerFromOutcome(outcome) : undefined;
             }
             catch (e) {
+                if (!isJsonColumnBodyProblem(e))
+                    throw e;
+                recordFailOpen("server.sql-json.checkpoint.outcome-unreadable");
                 this.logger?.info?.("checkpoint_decided_outcome_unreadable", { sessionId, error: e instanceof Error ? e.message : String(e) });
             }
             let executed = null;
             try {
-                const verdict = executionVerdict({ ...((v) => (v === null ? {} : { executionOutcome: v }))(parseJson(r.execution_outcome)) });
+                const cell = decodeExecutionOutcomeColumn(r.execution_outcome, `for the decided row of session ${sessionId}`);
+                const verdict = executionVerdict({ ...((v) => (v === undefined ? {} : { executionOutcome: v }))(cell) });
                 executed = verdict.kind === "executed" ? verdict.gate : null;
             }
             catch (e) {
+                if (!isJsonColumnBodyProblem(e))
+                    throw e;
+                recordFailOpen("server.sql-json.checkpoint.execution-outcome-unreadable");
                 this.logger?.info?.("checkpoint_execution_outcome_unreadable", { sessionId, error: e instanceof Error ? e.message : String(e) });
             }
             return {
@@ -615,8 +660,8 @@ export class SqlCheckpointStore {
             "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at_ms = EXCLUDED.updated_at_ms"), [sessionId, this.json(ctx, "checkpoint ctx"), Date.now()]);
     }
     async getCtx(sessionId) {
-        const { rows } = await this.db.query(this.q("SELECT ctx FROM checkpoint_ctx WHERE session_id=?", "SELECT ctx FROM checkpoint_ctx WHERE session_id=$1"), [sessionId]);
-        return rows[0] ? parseJson(rows[0].ctx) : null;
+        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]);
+        return rows[0] ? refusing("a resume context nobody can read", () => decodeCtxColumn(rows[0].ctx, `for session ${JSON.stringify(sessionId)}`)) : null;
     }
     async reapCtx(cutoff) {
         const res = await this.db.query(this.q("DELETE FROM checkpoint_ctx WHERE updated_at_ms < ? " +

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

@@ -186,6 +186,16 @@ export declare class SqlDeviceStore implements DeviceStore {
     appendAudit(input: AppendAuditInput): Promise<void>;
     /** 审计写的**唯一**语句(池级与事务内共用;`SqlExec` 是两者的公共面)。 */
     private insertAuditOn;
+    /**
+     * 审计列表。
+     *
+     * 🔴 **一行读不出形 ⇒ 整页拒,刻意不做逐行隔离**(S-550 修复验证轮,主会话裁定后入档):方向由设计
+     * §2「失败方向 = 拒(fail-closed),全店同向」定。逐行隔离(坏行跳过 / 占位)在**审计**面上尤其危险 ——
+     * 它把「这一页少了一条」变得和「本来就没有那一条」同形,而审计面的全部意义就是「发生过的事都在」。
+     * 一页 5xx 是响亮的运维事件,一条静默消失不是。
+     *
+     * ⇒ 存量库里旧写腿留下的坏字节由**一次性迁移**清掉(`one-time-migrations.ts` M4),不靠读侧容忍。
+     */
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
 }
 /** 方言绑定薄壳(A12 形:ctor 收池,行为全在基类)。 */

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

@@ -2,6 +2,7 @@ import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isCheckViolationError } from "./sql-errors.js";
 import { DEVICE_AUDIT_EVENTS, assertAcquireShape, assertDeviceIdShape, assertDeviceOwnerShape, assertEnrollTokenHashShape, assertIssueTokenShape, assertNewDeviceShape, assertRebindShape, assertRevokeShape, assertRootSessionIdShape, assertWholeSeconds, parseDeviceAuditEvent, parseDevicePlatformOs, parseDeviceStatus, } from "../device-store.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn } from "./sql-json-column.js";
 export const DEVICES_TABLE = "device";
 export const DEVICE_ENROLL_TOKENS_TABLE = "device_enroll_token";
 export const DEVICE_SESSIONS_TABLE = "device_session";
@@ -237,7 +238,7 @@ function sessionCols(dialect) {
     return ["root_session_id", "device_id", "owner_tenant", "owner_subject", ms(dialect, "bound_at", "bound_at_ms"), "rev"].join(", ");
 }
 function auditCols(dialect) {
-    return ["id", ms(dialect, "at", "at_ms"), "event", "device_id", "owner_tenant", "owner_subject", "detail"].join(", ");
+    return ["id", ms(dialect, "at", "at_ms"), "event", "device_id", "owner_tenant", "owner_subject", jsonColumnText(dialect, "detail")].join(", ");
 }
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
@@ -295,9 +296,6 @@ function mapSessionRow(r) {
         rev: Number(r.rev),
     };
 }
-function parseJsonColumn(v) {
-    return JSON.parse(v);
-}
 function mapAuditRow(r) {
     const tenant = strOrNull(r.owner_tenant);
     const subject = strOrNull(r.owner_subject);
@@ -308,9 +306,17 @@ function mapAuditRow(r) {
         event: parseDeviceAuditEvent(bufToStr(r.event)),
         deviceId: strOrNull(r.device_id),
         owner: tenant !== null && subject !== null ? { tenant, subject } : null,
-        detail: rawDetail === null || rawDetail === undefined ? null : typeof rawDetail === "string" ? parseJsonColumn(rawDetail) : rawDetail,
+        detail: rawDetail === null || rawDetail === undefined ? null : readAuditDetail(rawDetail, String(r.id)),
     };
 }
+function readAuditDetail(raw, id) {
+    try {
+        return decodeJsonColumn(raw, readJsonObjectColumn, `${DEVICE_AUDIT_TABLE}.detail for audit row ${id}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`device-store: ${m} — refusing rather than serve an audit row whose detail nobody can read`));
+    }
+}
 function ph(dialect, n) {
     return dialect === "tidb" ? "?" : `$${n}`;
 }
@@ -637,7 +643,7 @@ export class SqlDeviceStore {
             assertDeviceIdShape(input.deviceId);
         if (input.owner)
             assertDeviceOwnerShape(input.owner);
-        await exec.query(this.q(`INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (NOW(3), ?, ?, ?, ?, ?)`, `INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (now(), $1, $2, $3, $4, $5::jsonb)`), [input.event, input.deviceId ?? null, input.owner?.tenant ?? null, input.owner?.subject ?? null, input.detail === undefined ? null : this.json(input.detail)]);
+        await exec.query(this.q(`INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (NOW(3), ?, ?, ?, ?, ?)`, `INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (now(), $1, $2, $3, $4, $5::jsonb)`), [input.event, input.deviceId ?? null, input.owner?.tenant ?? null, input.owner?.subject ?? null, input.detail == null ? null : this.json(input.detail)]);
     }
     async listAudit(filter) {
         const dialect = this.db.dialect;

package/dist/plugins/host-platform.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Host-lane PLATFORM seam (DESIGN-windows-native.md, FINAL r3) — the ONE place the host exec adapter's
+ * POSIX/win32 differences live, so `remote-env-host.ts` stays a single code path with platform-gated leaves.
+ *
+ * 🔴 Iron invariant (design §4.1): the POSIX path is BYTE-IDENTICAL to the pre-Windows code — every helper is
+ * `win32 ? new : exactly-what-the-inline-code-did` (same syscall, same throw behavior). Never "improve" POSIX
+ * here; the existing full test suite is the regression net.
+ *
+ * win32 semantics (design D1-D4):
+ *  - shell   = Git Bash via core 1.224 `getShellConfig` (WSL-launcher-filtered — the `System32\bash.exe`
+ *              trap). Fail-LOUD when absent; never silently degrade to cmd (D1).
+ *  - kill    = core 1.224 `signalProcessTree` (taskkill /T, /F for hard). Soft is a no-op for console trees
+ *              (taskkill errors "can only be terminated forcefully") — the SIGTERM→grace→SIGKILL ladder is
+ *              effectively delay→hard-kill on win32; accepted, CC-identical (D2).
+ *  - spawn   = `detached:false` + `windowsHide:true` (no console window; no POSIX process group — the kill
+ *              side uses the tree, not the group) (D3).
+ *  - env     = case-insensitive key collapse before spawn (win32 env keys are case-insensitive; a `Path`+`PATH`
+ *              pair from case-sensitive Object.assign reaches CreateProcess as ONE undefined-which
+ *              entry). Canonical casing = the first-seen key (process.env's native casing wins since the
+ *              inherit base is spread first).
+ *
+ * ⚠️ The win32 branches are UNVERIFIED on a real machine until S5 (Windows CI runner) — design D5 discipline:
+ * structural tests only on mac/Linux; behavior-level bite happens on the first Windows-runner green.
+ */
+import type { ChildProcess } from "node:child_process";
 import { killProcessTree } from "@sema-agent/core";
 export declare const IS_WIN32: boolean;
 export interface HostShell {
@@ -48,15 +73,52 @@ export declare function killTreeSoft(pid: number): void;
 /** Graceful tree kill where the CALLER has no escalation timer of its own (currently unused by the host lane —
  *  exported for parity with core's surface; the bg driver keeps its own HOST_BG_KILL_GRACE_MS ladder). */
 export { killProcessTree };
-/** 登记回执 = 注销的唯一凭据(纯数据;身份即凭据,见簿注)。 */
+/**
+ * 登记回执 = 注销的**唯一**凭据(身份即凭据,见簿注)+ 一只幂等的注销把手。
+ *
+ * S-566 归一轮:注销**只有这一张脸**(`release()`)。此前另有一只 `untrackHostForegroundChild(ticket)`
+ * 自由函数,于是「把这只回执从簿上删掉」有两种写法 —— 零别名纪律下这属于歧义面,已**整个删除**
+ * (硬 breaking 三句:没有别名、没有过渡方法,调用方的 tsc 红就是通知)。
+ */
 export interface ForegroundChildTicket {
     /** 组领袖 pid = pgid(POSIX `detached:true` 的直接后果)。 */
     readonly pid: number;
+    /**
+     * 提前注销 —— 给各腿**特有**的兜底时点用(settle / `close` / 领养移交 / 生成器 `finally`)。
+     * 幂等(同一只回执 release 多少次都一样),且按**身份**删 ⇒ 迟到的那一次**绝不**碰内核复用同号之后
+     * 的新登记。主时点(`exit` / `error`)由 {@link adoptHostForegroundChild} 自己挂,调用点不必重复写。
+     */
+    release(): void;
 }
-/** 登记一只自起的前台子进程,返回注销用的回执。 */
+/**
+ * 登记一只自起的前台子进程(**低层原语**:只有 pid 在手时用它 —— 产品码一律走
+ * {@link adoptHostForegroundChild},见那条形状钉)。
+ */
 export declare function trackHostForegroundChild(pid: number): ForegroundChildTicket;
-/** 注销(`exit` / settle / 领养移交)。按回执身份删 ⇒ 幂等,且**绝不**碰同号的其它登记。 */
-export declare function untrackHostForegroundChild(ticket: ForegroundChildTicket): void;
+/**
+ * 🔴 **本簿在 `src/` 的唯一登记口**(S-566 归一轮)—— 一只自起的 detached 前台子进程「进簿 + 两只主注销」
+ * 的**全部**语义收在这里。
+ *
+ * ── 为什么是一只函数而不是五处同一句 ────────────────────────────────────────────────────────────
+ * 归一前,这一句在仓里**手抄五份**(`remote-env-host.ts` 三条 fg 腿 + `hook-runner.ts` 两条):
+ * 「`pid != null` 才登记」「`exit` 主注销」「`error` 之后 `exit` 可能不来,所以也要注销」——
+ * 每多一条 detached 腿就要再抄一遍,而**第六处只要漏抄一臂就是一个静默的孤儿洞**(S-566 的病正是
+ * hook 那两条腿整份没抄)。一条规则答完所有腿,规则集因此变小而不是变大。
+ *
+ * ── 语义(三条,逐条有理由)────────────────────────────────────────────────────────────────────
+ *  · **无 pid ⇒ `undefined`,不登记**:spawn 起手失败那一族根本没有组领袖,簿上放一个 `undefined` 的坐标
+ *    等于给收割腿一条假线索;调用点因此拿到的是一个「可能不在」的把手,漏判会被类型挡住。
+ *  · **`exit` = 主注销时点**(不是 `close` / settle):`close` 是**管道**驱动的,一个继承了 stdout 的孙进程
+ *    能把它按住任意久;而一条已退的 pid 留在簿里 = 给收割腿一个**过期坐标** —— 内核复用那个号之后
+ *    `kill(-pid)` 打的是**别人**的组。
+ *  · **`error` 也注销**:Node 契约里 `error` 之后 `exit` **可能不来**(异步起手失败),那一形没有第二次机会。
+ *    本函数只挂注销,**不**吞 `error` —— 五条腿各自的 `error` 处置(记账 / settle / 铸故障帧)原样在位,
+ *    本监听是第 N 只监听器,不改变「`error` 有没有人接」这件事(亲核:五处在归一前就都已有 `error` 监听)。
+ *
+ * 各腿**特有**的兜底(settle / `close` / 领养移交 / 生成器 `finally`)留在调用点,写成一行
+ * `ticket?.release()` —— 它们是**那条腿自己的**生命周期事实,不是本簿的语义。
+ */
+export declare function adoptHostForegroundChild(child: ChildProcess): ForegroundChildTicket | undefined;
 /** 一次前台收割的读数。三格分开是**刻意**的:`alreadyDead` 是想要的结果(不是失败),`failed` 是**真的**
  *  没收上来 —— 两者混成一个数就等于把后者静默掉([ref]:这条腿上不许有安静的兜底)。
  *
@@ -75,8 +137,10 @@ export interface ForegroundReapReading {
  * 收割簿上全部前台子进程组。返回**发出**信号的读数,不是确认死亡数 —— 确认要等,而本函数的调用点之一
  * 是 uncaught 出口。
  *
- * **同步形、一次到位、不等宽限**(S-557 起自述与实现同一句):承重的调用点是收尾链的
- * `process.once("exit")` 钩 —— `exit` 之后**没有续段**,`await` 一个宽限梯就是把收割赌在一个永远等不到的
+ * **同步形、一次到位、不等宽限**(S-557 起自述与实现同一句):承重的调用点是退出边界装配器
+ * (`boot/exit-boundary.ts`)那只 `process.once("exit")` 钩 —— S-560 起它由**两条车道共用**(HTTP 服务的
+ * 收尾链 + `run-local` 一次性 CLI;后者另装 SIGINT/SIGTERM 处理器,因为前台 CLI 的 Ctrl-C 若走默认终止,
+ * `exit` 钩不触发)。`exit` 之后**没有续段**,`await` 一个宽限梯就是把收割赌在一个永远等不到的
  * 时刻上(`hardShutdown` 终点那次早按只是优化,见 `boot/shutdown.ts` 的两处注)。上界 = 簿上条数 ×
  * 一次 `kill(-pid)` syscall(簿条数被 host lane 的在飞 turn 数界住),没有定时器、没有 promise。
  *

package/dist/plugins/host-platform.js

@@ -56,12 +56,23 @@ export function killTreeSoft(pid) {
 export { killProcessTree };
 const liveHostForegroundGroups = new Set();
 export function trackHostForegroundChild(pid) {
-    const ticket = { pid };
+    const ticket = {
+        pid,
+        release() {
+            liveHostForegroundGroups.delete(ticket);
+        },
+    };
     liveHostForegroundGroups.add(ticket);
     return ticket;
 }
-export function untrackHostForegroundChild(ticket) {
-    liveHostForegroundGroups.delete(ticket);
+export function adoptHostForegroundChild(child) {
+    const pid = child.pid;
+    if (pid == null)
+        return undefined;
+    const ticket = trackHostForegroundChild(pid);
+    child.once("exit", () => ticket.release());
+    child.once("error", () => ticket.release());
+    return ticket;
 }
 export function reapHostForegroundChildren() {
     let signalled = 0;

package/dist/plugins/leader-run-store-sql.js

@@ -2,7 +2,7 @@ import { uuidv7 } from "@sema-agent/core";
 import { createHash } from "node:crypto";
 import { isDupKeyError } from "./sql-errors.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
-import { parseJsonOr } from "./sql-row-helpers.js";
+import { decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, readNonNullJsonValueColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
 export const LEADER_RUN_TABLE = "leader_run";
 const LEADER_RUN_STATUSES = new Set(["running", "completed", "failed", "needs_human"]);
@@ -59,7 +59,17 @@ export async function ensurePgLeaderRunSchema(q) {
 }
 export const STALE_SWEEP_REASON = "leader run went stale: no replica settled it within LEADER_RUN_STALE_MS (the replica driving it most likely died). " +
     "The run was NOT taken over — re-submit with a NEW Idempotency-Key to run it again.";
-const SELECT_COLS = "leader_run_id, owner, objective_preview, status, result, error, started_at_ms, finished_at_ms";
+function selectCols(dialect) {
+    return `leader_run_id, owner, objective_preview, status, ${jsonColumnText(dialect, "result")}, error, started_at_ms, finished_at_ms`;
+}
+function readResultColumn(text, id) {
+    try {
+        return decodeNullableJsonColumn(text, readNonNullJsonValueColumn, `${LEADER_RUN_TABLE}.result for leader run ${id}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`leader_run: ${m} — refusing rather than serve this run as if it had finished empty-handed`));
+    }
+}
 function statusOf(raw, id) {
     const s = String(raw);
     if (!LEADER_RUN_STATUSES.has(s)) {
@@ -69,7 +79,7 @@ function statusOf(raw, id) {
 }
 function mapRow(r) {
     const id = String(r.leader_run_id);
-    const result = r.result == null ? undefined : parseJsonOr(r.result, undefined);
+    const result = readResultColumn(r.result, id);
     const error = r.error == null ? undefined : String(r.error);
     const finished = r.finished_at_ms == null ? undefined : Number(r.finished_at_ms);
     return {
@@ -113,12 +123,12 @@ export class SqlLeaderRunStore {
         return { created: true, run };
     }
     async getRun(id) {
-        const res = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = ?`, `SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = $1`), [id]);
+        const res = await this.db.query(this.q(`SELECT ${selectCols("tidb")} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = ?`, `SELECT ${selectCols("pg")} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = $1`), [id]);
         const row = res.rows[0];
         return row ? mapRow(row) : undefined;
     }
     async getByIdem(idemKey) {
-        const res = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE idem_key = ?`, `SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE idem_key = $1`), [idemKey]);
+        const res = await this.db.query(this.q(`SELECT ${selectCols("tidb")} FROM ${LEADER_RUN_TABLE} WHERE idem_key = ?`, `SELECT ${selectCols("pg")} FROM ${LEADER_RUN_TABLE} WHERE idem_key = $1`), [idemKey]);
         const row = res.rows[0];
         return row ? mapRow(row) : undefined;
     }
@@ -132,7 +142,7 @@ export class SqlLeaderRunStore {
     }
     async finishRun(id, patch) {
         const json = dialectJsonEncoder(this.db.dialect);
-        const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = ?, result = CAST(? AS JSON), error = ?, finished_at_ms = ? WHERE leader_run_id = ? AND status = 'running'`, `UPDATE ${LEADER_RUN_TABLE} SET status = $1, result = $2::jsonb, error = $3, finished_at_ms = $4 WHERE leader_run_id = $5 AND status = 'running'`), [patch.status, patch.result === undefined ? null : json(patch.result), patch.error ?? null, Date.now(), id]);
+        const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = ?, result = CAST(? AS JSON), error = ?, finished_at_ms = ? WHERE leader_run_id = ? AND status = 'running'`, `UPDATE ${LEADER_RUN_TABLE} SET status = $1, result = $2::jsonb, error = $3, finished_at_ms = $4 WHERE leader_run_id = $5 AND status = 'running'`), [patch.status, patch.result == null ? null : json(patch.result), patch.error ?? null, Date.now(), id]);
         return res.affected > 0;
     }
 }

package/dist/plugins/one-time-migrations.d.ts

@@ -13,6 +13,9 @@ export interface OneTimeMigrationReport {
     readonly retiredSteerSeatStaleRows: number;
     /** M3:改名的行数(账本 `tool_end` 行 + 已决 checkpoint 的执行判词列,两者相加)。 */
     readonly askOriginRowsMigrated: number;
+    /** M4:`device_audit.detail` 里 JSON 文本 `null` 被改成列 NULL 的行数(表不在 ⇒ 恒 0)。
+     *  非零 = 这次迁移真改写了存量字节,必须让运维看见(与 M1 的 `retiredSnapshotRows` 同一条纪律)。 */
+    readonly auditDetailJsonNullRows: number;
 }
 /** 三条迁移都不适用的载体(local 车道没有 SQL 表)。 */
 export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "askOriginRowsMigrated">;