@sema-agent/server 7.93.5 → 7.93.6

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/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;

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/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]:这条腿上不许有安静的兜底)。
  *