@sema-agent/server 7.141.0 → 7.143.0

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

@@ -1,6 +1,7 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
-import { APPROVAL_ENDING_CAUSES, causeOfAskRow } from "../approval-deny-reasons.js";
+import { DECIDED_VIA } from "@sema-agent/core";
+import { APPROVAL_ENDING_CAUSES, askRowEndingCause, askRowParkTrigger } from "../approval-deny-reasons.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
 import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
@@ -25,7 +26,8 @@ export const MAX_SETTLED_BY_CHARS = 16;
 export function settledByFitsColumn(v) {
     return v.length > 0 && v.length <= MAX_SETTLED_BY_CHARS;
 }
-export function assertDecideSettledBy(decision) {
+export function assertDecideSource(decision) {
+    assertDecidedViaBesidePolicy(decision);
     const v = decision.settledBy;
     if (v === undefined)
         return;
@@ -33,6 +35,15 @@ export function assertDecideSettledBy(decision) {
         throw new Error(`invalid settledBy: the settlement source is one word from the engine's closed set and lands in a VARCHAR(${MAX_SETTLED_BY_CHARS}) column — must be 1-${MAX_SETTLED_BY_CHARS} chars (got ${JSON.stringify(v.slice(0, 32))}${v.length > 32 ? "…" : ""}, length ${v.length})`);
     }
 }
+export const MAX_DECIDED_VIA_CHARS = 32;
+function assertDecidedViaBesidePolicy(decision) {
+    const via = decision.decidedVia;
+    if (via === undefined)
+        return;
+    if (!DECIDED_VIA.some((w) => w === via) || via.length > MAX_DECIDED_VIA_CHARS || decision.settledBy !== "policy") {
+        throw new Error(`invalid decidedVia: the machine seat is one of ${DECIDED_VIA.map((w) => `"${w}"`).join(" / ")} and is stated only beside settledBy "policy" (got ${JSON.stringify(String(via).slice(0, 32))} beside ${JSON.stringify(decision.settledBy ?? null)})`);
+    }
+}
 export class ApprovalAskReadAbortedError extends Error {
     constructor(where) {
         super(`approval-ask read ${where} aborted by caller`);
@@ -61,6 +72,18 @@ async function withReadSignal(op, signal, where) {
     }
 }
 export const POLICY_REFUSAL_DECISION = { decision: "deny", settledBy: "policy" };
+export function claimCauseColumn(intent) {
+    switch (intent) {
+        case "cancel":
+            return "ending_cause";
+        case "expire":
+            return "park_trigger";
+        default: {
+            const unreachable = intent;
+            throw new Error(`approval-ask-store: no cause column for terminal claim intent ${String(unreachable)}`);
+        }
+    }
+}
 export function claimTargetState(intent) {
     switch (intent) {
         case "expire":
@@ -78,18 +101,21 @@ export function claimTargetState(intent) {
 export function projectAskTerminalClaimTruth(row) {
     if (row === null || row.state === "STREAM_PENDING")
         return { state: "absent" };
-    const cause = causeOfAskRow(row);
+    const endingCause = askRowEndingCause(row);
+    const parkTrigger = askRowParkTrigger(row);
     return {
         state: row.state,
         rev: row.rev,
         decision: row.decision,
         ...(row.updatedInput !== undefined ? { updatedInput: row.updatedInput } : {}),
         settledBy: row.settledBy,
-        ...(cause !== undefined ? { cause } : {}),
+        decidedVia: row.decidedVia,
+        ...(endingCause !== undefined ? { endingCause } : {}),
+        ...(parkTrigger !== undefined ? { parkTrigger } : {}),
     };
 }
 export function askRowOnCall(row, call) {
-    return row.taskId === call.taskId && row.legKey === call.legKey && row.toolCallId === call.toolCallId && row.sourceTaskId === call.sourceTaskId;
+    return row.taskId === call.taskId && row.legKey === call.legKey && row.toolCallId === call.toolCallId && row.sourceSessionId === call.sourceSessionId;
 }
 export function askOwnerAdmits(owner, principal) {
     return owner === null || owner === principal;
@@ -105,6 +131,16 @@ export const APPROVAL_ASK_EXECUTION_LANE_COLUMN = {
     mysql: "execution_lane VARCHAR(32) NOT NULL DEFAULT ''",
     pg: `execution_lane VARCHAR(32) COLLATE "C" NOT NULL DEFAULT ''`,
 };
+export const APPROVAL_ASK_ENDING_CAUSE_COLUMN = {
+    name: "ending_cause",
+    mysql: "ending_cause VARCHAR(64) NULL",
+    pg: `ending_cause VARCHAR(64) COLLATE "C"`,
+};
+export const APPROVAL_ASK_PARK_TRIGGER_COLUMN = {
+    name: "park_trigger",
+    mysql: "park_trigger VARCHAR(64) NULL",
+    pg: `park_trigger VARCHAR(64) COLLATE "C"`,
+};
 function executionLaneColumnOf(raw, askId) {
     const lane = typeof raw === "string" ? raw : "";
     if (!isExecutionLane(lane)) {
@@ -155,15 +191,21 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     -- settled_by(S-558 / #1016 持久半场):这条决议的结算来源词(NULL = 人答的)。语义、两态读法与
     -- 「为什么是自己一列而不是塞进 decision_actor」的全文见 AskRow.settledBy 顶注。
     -- VARCHAR(16):词表属主是 core(AskOutcome.settledBy,今天最长 7 字符 "timeout"),宽度与同表
-    -- decision 同尺同理由 —— 闭集词列,不是自由文本。截断面由入店形门堵死(assertDecideSettledBy),
+    -- decision 同尺同理由 —— 闭集词列,不是自由文本。截断面由入店形门堵死(assertDecideSource),
     -- 不靠「列够宽就不会截」这种运气(MySQL 非严格模式静默截、PG 直接报错 = 两方言不同答)。
     settled_by VARCHAR(16) NULL,
+    -- decided_via(core 7.61.0 #3169):settled_by = 'policy' 旁的机器座位词(NULL = 没陈述 = 部署自己的策略;旧行同读)。
+    -- 与 settled_by 同一条 UPDATE 落列、同一条理由住在行上(语义全文见 AskRow.decidedVia)。闭集词列,宽度 = MAX_DECIDED_VIA_CHARS。
+    decided_via VARCHAR(${MAX_DECIDED_VIA_CHARS}) NULL,
     -- updated_input(S-26 / #304,A-054.15 收口):人批准时带的 ctrl+g 编辑实参,JSON 文本,与决议同一条
     -- UPDATE 原子落列;NULL = 没带编辑(与 JSON "null" = 编辑成 null 分家)。LONGTEXT 照 card_json 先例:
     -- 编辑实参是整只工具入参,VARCHAR/TEXT 会造静默截断面。语义三态与读法见 AskRow.updatedInput 顶注。
     updated_input LONGTEXT NULL,
     decided_at_ms BIGINT NULL,
-    denied_reason VARCHAR(64) NULL,
+    -- 成因两列,一列一义(语义见 AskRow.endingCause / AskRow.parkTrigger):ending_cause = 终态成因(到 VOID / DENIED 的转移写);
+    -- park_trigger = 转 park 的触发成因(只由 expire claim 写一次,终态不覆盖)。
+    ${APPROVAL_ASK_ENDING_CAUSE_COLUMN.mysql},
+    ${APPROVAL_ASK_PARK_TRIGGER_COLUMN.mysql},
     gate_token VARCHAR(120) NULL,
     gate_bound_call_id VARCHAR(255) NULL,
     gate_bound_input_hash VARCHAR(255) NULL,
@@ -241,10 +283,14 @@ export async function ensurePgApprovalAskSchema(q) {
     decision_note TEXT COLLATE "C",
     -- settled_by(S-558)—— MySQL 孪生逐字同形(宽度/语义/形门的理由写在那侧的行内注)。
     settled_by VARCHAR(16) COLLATE "C",
+    -- decided_via(#3169)—— MySQL 孪生逐字同形。
+    decided_via VARCHAR(${MAX_DECIDED_VIA_CHARS}) COLLATE "C",
     -- updated_input(S-26 / #304)—— MySQL 孪生逐字同形(语义/类型理由见那侧行内注;PG TEXT 无长度上限)。
     updated_input TEXT COLLATE "C",
     decided_at_ms BIGINT,
-    denied_reason VARCHAR(64) COLLATE "C",
+    -- 成因两列 —— MySQL 孪生逐字同形(语义见那侧行内注)。
+    ${APPROVAL_ASK_ENDING_CAUSE_COLUMN.pg},
+    ${APPROVAL_ASK_PARK_TRIGGER_COLUMN.pg},
     gate_token VARCHAR(120) COLLATE "C",
     gate_bound_call_id VARCHAR(255) COLLATE "C",
     gate_bound_input_hash VARCHAR(255) COLLATE "C",
@@ -288,9 +334,9 @@ function askCols(dialect) {
         "ask_id, task_id, source_task_id, session_id, owner, execution_lane, 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",
+        "decision_note, settled_by, decided_via",
         jsonColumnText(dialect, "updated_input"),
-        "decided_at_ms, denied_reason, gate_token",
+        "decided_at_ms, ending_cause, park_trigger, 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",
@@ -320,7 +366,7 @@ function mapAskRowBody(r, askId) {
     return {
         askId: String(r.ask_id),
         taskId: String(r.task_id),
-        sourceTaskId: String(r.source_task_id),
+        sourceSessionId: String(r.source_task_id),
         sessionId: String(r.session_id),
         owner: strOrNull(r.owner),
         executionLane: executionLaneColumnOf(r.execution_lane, askId),
@@ -336,9 +382,11 @@ function mapAskRowBody(r, askId) {
         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),
+        decidedVia: strOrNull(r.decided_via),
         ...(r.updated_input == null ? {} : { updatedInput: decodeJsonColumn(r.updated_input, readTriStateJsonValueColumn, `${APPROVAL_ASK_TABLE}.updated_input for ask ${askId}`) }),
         decidedAtMs: numOrNull(r.decided_at_ms),
-        deniedReason: strOrNull(r.denied_reason),
+        endingCause: strOrNull(r.ending_cause),
+        parkTrigger: strOrNull(r.park_trigger),
         gateToken: strOrNull(r.gate_token),
         gateBoundCallId: strOrNull(r.gate_bound_call_id),
         gateBoundInputHash: strOrNull(r.gate_bound_input_hash),
@@ -373,8 +421,8 @@ function patchColumns(patch, json) {
         out.push(["decision_note", patch.decisionNote]);
     if (patch.decidedAtMs !== undefined)
         out.push(["decided_at_ms", patch.decidedAtMs]);
-    if (patch.deniedReason !== undefined)
-        out.push(["denied_reason", patch.deniedReason]);
+    if (patch.endingCause !== undefined)
+        out.push(["ending_cause", patch.endingCause]);
     if (patch.gateToken !== undefined)
         out.push(["gate_token", patch.gateToken]);
     if (patch.gateBoundCallId !== undefined)
@@ -427,12 +475,12 @@ export class SqlApprovalAskStore {
         try {
             await conn.begin();
             await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES (?, ?, 'OPEN', 0, ?, ?)`, `INSERT INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES ($1, $2, 'OPEN', 0, $3, $4) ON CONFLICT (batch_id) DO NOTHING`), [row.batchId, row.taskId, now, now]);
-            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, 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) ` +
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, 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) ` +
-                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $12, $13, $14, $15, $16, $17, $18) ON CONFLICT (ask_id) DO NOTHING"), [
+            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, ending_cause, park_trigger, 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) ` +
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, ending_cause, park_trigger, 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) ` +
+                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $12, $13, $14, $15, $16, $17, $18) ON CONFLICT (ask_id) DO NOTHING"), [
                 row.askId,
                 row.taskId,
-                row.sourceTaskId,
+                row.sourceSessionId,
                 row.sessionId,
                 row.owner ?? null,
                 row.executionLane,
@@ -486,10 +534,10 @@ export class SqlApprovalAskStore {
     async decideAsk(askId, batchId, owner, decision) {
         if (decision.idempotencyKey != null)
             assertIdempotencyKeyShape(decision.idempotencyKey);
-        assertDecideSettledBy(decision);
+        assertDecideSource(decision);
         const now = Date.now();
         const dialect = this.db.dialect;
-        const ownerWhere = decideOwnerWhere(dialect, owner, 11);
+        const ownerWhere = decideOwnerWhere(dialect, owner, 12);
         const conn = await this.db.connect();
         try {
             await conn.begin();
@@ -500,11 +548,12 @@ export class SqlApprovalAskStore {
             }
             let askRes;
             try {
-                askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=${ph(dialect, 1)}, decision_actor=${ph(dialect, 2)}, decision_note=${ph(dialect, 3)}, settled_by=${ph(dialect, 4)}, updated_input=${ph(dialect, 5)}, decided_at_ms=${ph(dialect, 6)}, idempotency_key=${ph(dialect, 7)}, rev=rev+1, updated_at_ms=${ph(dialect, 8)} WHERE ${pendingClaimWhere(dialect, 9)} AND ${ownerWhere.sql}`, [
+                askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=${ph(dialect, 1)}, decision_actor=${ph(dialect, 2)}, decision_note=${ph(dialect, 3)}, settled_by=${ph(dialect, 4)}, decided_via=${ph(dialect, 5)}, updated_input=${ph(dialect, 6)}, decided_at_ms=${ph(dialect, 7)}, idempotency_key=${ph(dialect, 8)}, rev=rev+1, updated_at_ms=${ph(dialect, 9)} WHERE ${pendingClaimWhere(dialect, 10)} AND ${ownerWhere.sql}`, [
                     decision.decision,
                     decision.decisionActor == null ? null : this.json(decision.decisionActor),
                     decision.decisionNote ?? null,
                     decision.settledBy ?? null,
+                    decision.decidedVia ?? null,
                     decision.updatedInput === undefined ? null : this.json(decision.updatedInput),
                     now,
                     decision.idempotencyKey ?? null,
@@ -549,7 +598,7 @@ export class SqlApprovalAskStore {
             throw new Error(`approval-ask-store.claimTerminal: illegal terminal claim STREAM_PENDING -> ${to} (askId=${askId})`);
         }
         if (intent === "refuse")
-            assertDecideSettledBy(POLICY_REFUSAL_DECISION);
+            assertDecideSource(POLICY_REFUSAL_DECISION);
         const now = Date.now();
         const dialect = this.db.dialect;
         const conn = await this.db.connect();
@@ -566,7 +615,7 @@ export class SqlApprovalAskStore {
                 ? await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, decision = ${ph(dialect, 2)}, settled_by = ${ph(dialect, 3)}, decided_at_ms = ${ph(dialect, 4)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 5)} WHERE ${pendingClaimWhere(dialect, 6)}`, [to, POLICY_REFUSAL_DECISION.decision, POLICY_REFUSAL_DECISION.settledBy, now, now, askId, batchId])
                 : (intent === "cancel" || intent === "expire") && opts?.cause !== undefined
                     ?
-                        await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, denied_reason = ${ph(dialect, 2)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 3)} WHERE ${pendingClaimWhere(dialect, 4)}`, [to, opts.cause, now, askId, batchId])
+                        await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, ${claimCauseColumn(intent)} = ${ph(dialect, 2)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 3)} WHERE ${pendingClaimWhere(dialect, 4)}`, [to, opts.cause, now, askId, batchId])
                     : 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,
@@ -585,7 +634,7 @@ export class SqlApprovalAskStore {
             await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=? WHERE batch_id=? AND state='OPEN'`, `UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='OPEN'`), [now, batchId]);
             let voidedSiblings;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -593,7 +642,7 @@ export class SqlApprovalAskStore {
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
                     const inList = voidedSiblings.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [
                         APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN,
                         now,
                         ...voidedSiblings,
@@ -639,7 +688,7 @@ export class SqlApprovalAskStore {
             }
             let voidedSiblings;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='PARKING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='PARKING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -647,7 +696,7 @@ export class SqlApprovalAskStore {
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
                     const inList = voidedSiblings.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='PARKING'`, [APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE, now, ...voidedSiblings]);
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='PARKING'`, [APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE, now, ...voidedSiblings]);
                 }
             }
             await conn.commit();
@@ -677,7 +726,7 @@ export class SqlApprovalAskStore {
             }
             let voided;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$3, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' RETURNING ask_id`, [now, batchId, APPROVAL_ENDING_CAUSES.BATCH_ABORTED]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=$3, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' RETURNING ask_id`, [now, batchId, APPROVAL_ENDING_CAUSES.BATCH_ABORTED]);
                 voided = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -685,7 +734,7 @@ export class SqlApprovalAskStore {
                 voided = sel.rows.map((r) => String(r.ask_id));
                 if (voided.length > 0) {
                     const inList = voided.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [APPROVAL_ENDING_CAUSES.BATCH_ABORTED, now, ...voided]);
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [APPROVAL_ENDING_CAUSES.BATCH_ABORTED, now, ...voided]);
                 }
             }
             await conn.commit();
@@ -722,7 +771,7 @@ export class SqlApprovalAskStore {
         return rows.map(mapAskRow);
     }
     async listByCall(call) {
-        const { rows } = await this.db.query(this.q(`SELECT ${askCols("mysql")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND leg_key = ? AND tool_call_id = ? AND source_task_id = ? ORDER BY created_at_ms ASC, ask_id ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND leg_key = $2 AND tool_call_id = $3 AND source_task_id = $4 ORDER BY created_at_ms ASC, ask_id ASC`), [call.taskId, call.legKey, call.toolCallId, call.sourceTaskId]);
+        const { rows } = await this.db.query(this.q(`SELECT ${askCols("mysql")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND leg_key = ? AND tool_call_id = ? AND source_task_id = ? ORDER BY created_at_ms ASC, ask_id ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND leg_key = $2 AND tool_call_id = $3 AND source_task_id = $4 ORDER BY created_at_ms ASC, ask_id ASC`), [call.taskId, call.legKey, call.toolCallId, call.sourceSessionId]);
         return rows.map(mapAskRow).filter((r) => askRowOnCall(r, call));
     }
     async listParkingBySession(sessionId) {

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

@@ -343,7 +343,7 @@ export interface CheckpointAskCandidate {
     status: string;
     createdAtMs: number;
     /**
-     * 🔴 和解三元组的第一维([ref] 件1,黑板 [ref]③①)—— checkpoint 自己带的 `sourceTaskId`(core 在
+     * 🔴 和解三元组的第一维([ref] 件1,黑板 [ref]③①)—— checkpoint 自己带的 `sourceSessionId`(core 在
      * suspendAsk 铸行时恒填该腿的 `sessionId`)。**没有对应的列**,只能从 blob 窄读;读不出/缺席 = null。
      *
      * 为什么必须进候选集:读口按 `(scope, session_id, tool_call_id)` 查,而委派子代那条腿的 ask 落行时
@@ -351,7 +351,7 @@ export interface CheckpointAskCandidate {
      * (toolCallId, hash) 两维,一条根腿的 park 会被一只子代的 ask 认领(摘要相同的两次同 args 调用完全
      * 正常)。三元组全同才算同一件事。
      */
-    sourceTaskId: string | null;
+    sourceSessionId: string | null;
     /** 该 park 绑定的 tool call(= `pendingAction.toolCallId`)。`unparseable` 行为 null。 */
     boundCallId: string | null;
     /** 服务端铸的入参摘要——判据 1 的第二道硬等式(与 `approval_ask.bound_input_hash` 相等才算命中)。 */
@@ -444,7 +444,7 @@ export declare function pendingActionToolCallId(body: unknown): {
     toolCallId: string | null;
     boundInputHash: string | null;
     kind: string | null;
-    sourceTaskId: string | null;
+    sourceSessionId: string | null;
 } | {
     readable: false;
 };
@@ -781,7 +781,7 @@ export declare class SqlCheckpointStore implements CheckpointStore, KindlessBatc
      * 🔴 **没有「列命中即零解析」的快路径**(原注写过,已作废,别照它优化):函数体对**每一行**无条件解
      * blob,原因有二 ——(a) 前向兼容门与 blob 可读性门必须门在**所有**命中路径之前(codex F3 + 确认轮:
      * 列长得对不代表 blob 读得出,放行一条读不出的行去 `bindBatch` 会把 ask 钉成 PARKED + 一张本进程读不出
-     * 的 resume 坐标,而 PARKED 不可回滚);(b) `[ref]` 之后 blob 顶层的 `sourceTaskId` 是和解三元组的第一
+     * 的 resume 坐标,而 PARKED 不可回滚);(b) `[ref]` 之后 blob 顶层的 `sourceSessionId` 是和解三元组的第一
      * 维,列命中行结构上也必须解 blob 才拿得到它。
      */
     findCheckpointCandidatesForAsk(scope: string, sessionId: string, toolCallId: string, sinceMs: number): Promise<CheckpointAskCandidate[]>;

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

@@ -239,12 +239,14 @@ export function approvalDecisionOfWinner(winner, boundCallId) {
 export function pendingActionToolCallId(body) {
     if (typeof body !== "object" || body === null)
         return { readable: false };
-    const rawSource = "sourceTaskId" in body ? body.sourceTaskId : null;
+    if ("sourceTaskId" in body)
+        return { readable: false };
+    const rawSource = "sourceSessionId" in body ? body.sourceSessionId : null;
     if (rawSource !== null && rawSource !== undefined && typeof rawSource !== "string")
         return { readable: false };
-    const sourceTaskId = typeof rawSource === "string" ? rawSource : null;
+    const sourceSessionId = typeof rawSource === "string" ? rawSource : null;
     if (!("pendingAction" in body))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceTaskId };
+        return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceSessionId };
     const pa = body.pendingAction;
     if (typeof pa !== "object" || pa === null)
         return { readable: false };
@@ -252,7 +254,7 @@ export function pendingActionToolCallId(body) {
     if (kind !== null && typeof kind !== "string")
         return { readable: false };
     if (!("toolCallId" in pa))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind, sourceTaskId };
+        return { readable: true, toolCallId: null, boundInputHash: null, kind, sourceSessionId };
     const id = pa.toolCallId;
     if (typeof id !== "string")
         return { readable: false };
@@ -261,7 +263,7 @@ export function pendingActionToolCallId(body) {
     const bih = "boundInputHash" in pa ? pa.boundInputHash : null;
     if (bih !== null && typeof bih !== "string")
         return { readable: false };
-    return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceTaskId };
+    return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceSessionId };
 }
 function pendingActionOfColumn(cell, where) {
     let body;
@@ -650,7 +652,7 @@ export class SqlCheckpointStore {
                 status: String(r.status),
                 createdAtMs: Number(r.created_at_ms),
                 boundInputHash: r.bound_input_hash == null ? null : String(r.bound_input_hash),
-                sourceTaskId: null,
+                sourceSessionId: null,
             };
             if (Number(r.version) > MAX_SUPPORTED_CHECKPOINT_VERSION) {
                 out.push({ ...base, boundCallId: null, unparseable: true });
@@ -673,7 +675,7 @@ export class SqlCheckpointStore {
             const effectiveHash = base.boundInputHash ?? derived.boundInputHash;
             const effective = col ?? derived.toolCallId;
             if (effective === toolCallId)
-                out.push({ ...base, boundInputHash: effectiveHash, sourceTaskId: derived.sourceTaskId, boundCallId: effective });
+                out.push({ ...base, boundInputHash: effectiveHash, sourceSessionId: derived.sourceSessionId, boundCallId: effective });
         }
         return out;
     }

package/dist/plugins/file-history-store-sql.d.ts

@@ -2,7 +2,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport, type FileHistoryExportResult } from "@sema-agent/core";
 import { type BlobBackend } from "./blob-backend.js";
-import type { SyncBlobPutResult } from "./store-backend.js";
+import type { ServiceBlobExchange } from "./store-backend.js";
 import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 /** The file-history blob domain's SQL table (BlobBackend `table`/MinIO index binding + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -24,12 +24,10 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** RAW native pool — handed to blob-backend.ts (outside the SqlDriver seam, dialect-switches on
      *  its own string). Not used for this class's own statements (those go through `db`). */
     protected readonly pool: MySqlPool | PgPool;
-    /** 2c sync blob-face MARKER (codex R2-high): the route/caps predicates gate on THIS, never on a
-     *  `typeof putBlob` duck-probe — core's local FileFileHistoryStore carries a PRIVATE synchronous
-     *  `putBlob(hash, bytes): void` helper whose name collides with the service face; a name probe
-     *  passes there, mutates core-owned blob storage out of contract, then dereferences `.ok` on
-     *  undefined. Presence of this literal = the full typed putBlob/getBlob/hasBlobs face exists. */
-    readonly syncBlobFaces: true;
+    /** The blob exchange (core's `FileHistoryStore.blobExchange` group, see {@link ServiceBlobExchange}): how another machine's bytes
+     *  come in ahead of an `importHistory`, go out to a puller, and are asked about. Its presence IS the capability — read through
+     *  `blobExchangeOf` (`session-sync.ts`), which defers to core's judge; there is no second word for it on this class. */
+    readonly blobExchange: ServiceBlobExchange;
     protected readonly blobs: BlobBackend;
     /** §10 S-6 in-process lease state (design v1 D2: NOT persisted). Keys = `${scope}\x00${entryId}`. */
     private readonly spentAttempts;
@@ -58,15 +56,25 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /**
      * Per-scope WRITE-SERIALIZATION lock (codex R1-critical): `SELECT … FOR UPDATE` over an EMPTY result
      * locks nothing on PG, so neither the empty-target law (import/adopt) nor a multi-statement graph
-     * write can be serialized by the data rows alone. Every graph-mutating tx therefore first ensures +
+     * write can be serialized by the data rows alone. Every graph transaction therefore first ensures +
      * row-locks the scope's sentinel row — one lock, both dialects, and disjoint-key writers can no
-     * longer interleave into a merged/torn graph. The ensure+lock loops because deleteBySession removes
-     * the sentinel: a waiter woken by that delete sees zero rows and must re-ensure.
+     * longer interleave into a merged/torn graph.
      *
      * Shape A ([ref]): the MySQL ensure verb is `ON DUPLICATE KEY UPDATE scope = scope`, NOT `INSERT IGNORE`.
      * On InnoDB a duplicate-key IGNORE takes an **S** lock on the existing sentinel and the `FOR UPDATE` right
      * below has to upgrade it to X — two concurrent scope writers each holding an S deadlock ([ref]). ON
      * DUPLICATE takes X on the duplicate key, the same mode the locking read wants, so they serialize instead.
+     *
+     * **This is the transaction's first statement** (every caller: `begin()` and then this — nothing of the
+     * transaction exists before it), and a lost arbitration here restarts the transaction from the top
+     * (rollback + begin + the same ensure-and-lock), through the repo's one bound ({@link retryOnDeadlock}). Two shapes:
+     *  · the engine picked this transaction as a deadlock victim. InnoDB only (REPEATABLE READ): when the sentinel
+     *    physically disappears while ≥ 2 transactions are queued on it — its minter rolled back, or a whole-scope
+     *    removal ({@link deleteBySession}) committed and purge took the delete-marked row — the queued locks are
+     *    inherited as GAP locks on the next record, and each queued ensure's insert-intention waits on the others'
+     *    gap locks. The engine kills all but one; the survivor's mint goes through and the others restart into it;
+     *  · the sentinel was gone at the locking read ({@link ScopeSentinelVanishedError}; PG, see there).
+     * The lock order itself stays single: sentinels first (sorted), then the scope's rows.
      */
     private lockScope;
     /** Returns the UPDATE's affected count — 0 = the record is gone (annulled) or was already observed;
@@ -147,14 +155,12 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** Async byte-GC: blobs referenced by NO version row (any scope), past the created_at grace window.
      *  Domain-isolated by construction (this store's blob table only — [ref] D1). Reaper-driven. */
     sweepOrphanBlobs(): Promise<number>;
-    /** Upload ONE content-addressed blob ahead of an importHistory (§5 streamed negotiation). Store-level
-     *  integrity re-check (the route pre-verifies too — the internal caller might not). Never-throw.
-     *  The SQL blob judge's refusal ({@link BlobTooLargeError}, judged on the connection that would have written the blob)
-     *  keeps its own code — the route answers it 413 (the sentence names that connection's walls), every other write failure 502 ("retry"). */
-    putBlob(hash: string, bytes: Uint8Array): Promise<SyncBlobPutResult>;
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    /** The subset of `hashes` already present — one SQL INDEX probe (the import presence pre-check). */
-    hasBlobs(hashes: string[]): Promise<Set<string>>;
+    /** Store ONE content-addressed blob ahead of an importHistory (§5 streamed negotiation). The content address is judged HERE and
+     *  nowhere else (core's `put` law: bytes whose sha256 is not `hash` are refused `adopt_failed` / `terminal`, nothing stored).
+     *  Never-throw. The SQL blob judge's refusal ({@link BlobTooLargeError}, judged on the connection that would have written the blob)
+     *  is a terminal refusal that carries `blobCap` — the route answers it 413 with the judge's sentence; every other write failure is
+     *  `snapshot_failed` with the store's judgment of the fault (the route answers 502, "retry"). */
+    private putExchangedBlob;
     adoptScope(fromScope: string, toScope: string): Promise<FileHistoryResult>;
     private scopeEmpty;
     /** `forUpdate` — see {@link loadTracked}. Every in-transaction caller passes `true`: the four reads are

package/dist/plugins/file-history-store-sql.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, annulProofFailure, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
 import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isMissingColumnError } from "./sql-errors.js";
+import { isMissingColumnError, retryOnDeadlock } from "./sql-errors.js";
 import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
@@ -12,6 +12,8 @@ const sha256hex = (s) => createHash("sha256").update(s).digest("hex");
 const truthy = (v) => v === true || v === 1 || v === "1";
 class StagedRefGoneError extends Error {
 }
+class ScopeSentinelVanishedError extends Error {
+}
 function reapedEntryRefusal(entryId) {
     return {
         ok: false,
@@ -24,7 +26,11 @@ function reapedEntryRefusal(entryId) {
 export class SqlFileHistoryStore {
     db;
     pool;
-    syncBlobFaces = true;
+    blobExchange = {
+        put: (hash, bytes) => this.putExchangedBlob(hash, bytes),
+        get: (hash) => this.blobs.getBlob(hash),
+        has: (hashes) => this.blobs.hasBlobs([...hashes]),
+    };
     blobs;
     spentAttempts = new Set();
     activeAttempts = new Set();
@@ -48,16 +54,21 @@ export class SqlFileHistoryStore {
     async beforeObserve(_scope, _keyHash) { }
     async beforePublish(_scope) { }
     async lockScope(conn, ...scopes) {
-        for (const scope of [...new Set(scopes)].sort()) {
-            let locked = false;
-            for (let i = 0; i < 3 && !locked; i++) {
+        const ordered = [...new Set(scopes)].sort();
+        let restart = false;
+        await retryOnDeadlock(this.db.dialect, async () => {
+            if (restart) {
+                await conn.rollback().catch(() => undefined);
+                await conn.begin();
+            }
+            restart = true;
+            for (const scope of ordered) {
                 await conn.query(this.q("INSERT INTO file_history_scope (scope, created_at_ms) VALUES (?,?) ON DUPLICATE KEY UPDATE scope = scope", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
                 const r = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
-                locked = Boolean(r.rows[0]);
+                if (!r.rows[0])
+                    throw new ScopeSentinelVanishedError(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
             }
-            if (!locked)
-                throw new Error(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
-        }
+        }, (err) => err instanceof ScopeSentinelVanishedError);
     }
     async markObserved(scope, keyHash) {
         const r = await this.db.query(this.q("UPDATE file_history_tracked SET observed_later = 1 WHERE scope = ? AND key_hash = ? AND observed_later = 0", "UPDATE file_history_tracked SET observed_later = TRUE WHERE scope = $1 AND key_hash = $2 AND observed_later = FALSE"), [scope, keyHash]);
@@ -585,9 +596,9 @@ export class SqlFileHistoryStore {
             return 0;
         return this.blobs.deleteBlobs(orphans);
     }
-    async putBlob(hash, bytes) {
+    async putExchangedBlob(hash, bytes) {
         if (sha256hex(bytes) !== hash) {
-            return { ok: false, error: { code: "unsupported_format", message: `putBlob ${hash} fails content-address integrity — nothing stored` } };
+            return { ok: false, error: { code: "adopt_failed", message: `blob ${hash}: the bytes do not hash to this address — nothing stored`, permanence: "terminal" } };
         }
         try {
             await this.blobs.putBlob(hash, bytes);
@@ -595,17 +606,11 @@ export class SqlFileHistoryStore {
         }
         catch (err) {
             if (err instanceof BlobTooLargeError)
-                return { ok: false, error: { code: err.code, message: err.message, wallSource: err.cap.source } };
+                return { ok: false, error: { code: "adopt_failed", message: err.message, permanence: "terminal", blobCap: { wallSource: err.cap.source } } };
             const f = foldCaughtFailure(err);
-            return { ok: false, error: { code: "snapshot_failed", message: `putBlob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
+            return { ok: false, error: { code: "snapshot_failed", message: `blob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
         }
     }
-    async getBlob(hash) {
-        return this.blobs.getBlob(hash);
-    }
-    async hasBlobs(hashes) {
-        return this.blobs.hasBlobs(hashes);
-    }
     async adoptScope(fromScope, toScope) {
         try {
             if (fromScope === toScope)