@sema-agent/server 7.141.0 → 7.142.0

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

@@ -42,7 +42,7 @@ import type { PgQueryFn } from "./pg-query.js";
 import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
 import type { HostSettledBy } from "../host-decision.js";
-import { type AskRowCause, type SettleCause } from "../approval-deny-reasons.js";
+import { type AskRowEndingCause, type SettleCause, type ParkTriggerCause } from "../approval-deny-reasons.js";
 import { type IndexSpec } from "./ensure-index.js";
 import { type ExecutionLane } from "../execution-lane-caps.js";
 export type AskDecision = "approve" | "deny";
@@ -132,7 +132,16 @@ export interface AskRow {
      */
     updatedInput?: unknown;
     decidedAtMs: number | null;
-    deniedReason: string | null;
+    /**
+     * `ending_cause` 列原值 —— **终态成因**:这一行为什么没被人答就结束了(到 `VOID` / `DENIED` 的转移带着它写:取消 claim、店内撤兄弟 / bind-once 落选 / 批中止、对账器、起服收敛;没带的转移 ⇒ 保持 `null`)。
+     * 只经 {@link askRowEndingCause} 读(词表 + 行不变式在那里);`null` = 没写归因。
+     */
+    endingCause: string | null;
+    /**
+     * `park_trigger` 列原值 —— **转 park 的触发成因**:这一行为什么被转进投递面。**唯一写者** = 赢下 `STREAM_PENDING → PARKING` 的那一次 `claimTerminal(expire, { cause })`,
+     * 此后不再被写(行走到 `PARKED` / `DENIED` / `VOID` 之后它仍在;{@link AskTransitionPatch} 没有这一键)。只经 {@link askRowParkTrigger} 读;`null` = 没写(不带 cause 的转 park)。
+     */
+    parkTrigger: string | null;
     /** PARKED 坐标三件。 */
     gateToken: string | null;
     gateBoundCallId: string | null;
@@ -222,7 +231,9 @@ export interface AskTransitionPatch {
     decisionActor?: unknown | null;
     decisionNote?: string | null;
     decidedAtMs?: number | null;
-    deniedReason?: string | null;
+    /** 终态成因(值域与终局 claim 的 `cause` 同一型 {@link SettleCause};读口按终态成因词表读,且只在 `VOID` / `DENIED` 上作数 —— 别的转移上写了也读成缺席)。
+     *  补丁**没有**触发成因那一键:它只由 `claimTerminal(expire, { cause })` 写一次。 */
+    endingCause?: SettleCause;
     gateToken?: string | null;
     gateBoundCallId?: string | null;
     gateBoundInputHash?: string | null;
@@ -330,9 +341,10 @@ export interface ExpireResult {
  */
 export type AskTerminalClaimIntent = "expire" | "cancel" | "refuse";
 /**
- * 终局 claim 的可选实参:`cause` —— **赢下 `cancel`(VOID)/ `expire`(PARKING)时写进这一行 `denied_reason` 列的成因词**(决断口 410 / 晚答 404 / 跨副本的败方读数读同一列,
- * 所以这一行自己记着「为什么」,读面不靠任何进程内的东西)。`cancel` 写终态成因({@link SettleCause} 里的 `run_cancelled` / `run_exited`),
- * `expire` 写转 park 的触发成因({@link ParkTriggerCause}:`ttl_expired` / `broadcast_lost` / `stream_disconnected` / `undeliverable` / `shutdown_before_park`);缺席 ⇒ 列保持 NULL(读面缺席即缺席)。
+ * 终局 claim 的可选实参:`cause` —— **赢下终局的同一步写进这一行的成因词**,列由意图定({@link claimCauseColumn}):`cancel`(VOID)写 `ending_cause` = 终态成因
+ * ({@link SettleCause} 里的 `run_cancelled` / `run_exited`;决断口 410 / 晚答 404 / 跨副本的败方读数读这一列),`expire`(PARKING)写 `park_trigger` = 转 park 的触发成因
+ * ({@link ParkTriggerCause}:`ttl_expired` / `broadcast_lost` / `stream_disconnected` / `undeliverable` / `shutdown_before_park`;跨副本的悬挂腿与败方读数读这一列)。
+ * 所以这一行自己记着「为什么」,读面不靠任何进程内的东西;缺席 ⇒ 列保持 NULL(读面缺席即缺席)。
  * `refuse` 不读它(落的是一条决议,来源位 `policy`,不是结局成因);`expire` 撤兄弟时店自己写 `batch_sibling_withdrawn`(那是这条事务本身的事实)。
  */
 export interface AskTerminalClaimOpts {
@@ -348,6 +360,11 @@ export declare const POLICY_REFUSAL_DECISION: {
     readonly decision: "deny";
     readonly settledBy: Extract<HostSettledBy, "policy">;
 };
+/**
+ * 带成因的终局 claim 把成因写进哪一列(穷举 switch:意图闭集加一个词 ⇒ 这里编译期先红)。一列一义:`cancel` 赢下的是终态(`ending_cause`),
+ * `expire` 赢下的是转 park(`park_trigger`);`refuse` 落的是一条决议,不带成因(不进本表)。SQL 两孪生读这一只;内存孪生的两臂各自落同一格(`transitionAsk` 的补丁 / `expireAsk`)。
+ */
+export declare function claimCauseColumn(intent: Exclude<AskTerminalClaimIntent, "refuse">): "ending_cause" | "park_trigger";
 /** 终局 claim 意图 → 本次 CAS 的目标态(穷举 switch:意图闭集加一个词 ⇒ 这里编译期先红)。 */
 export declare function claimTargetState(intent: AskTerminalClaimIntent): AskState;
 /**
@@ -374,10 +391,11 @@ export type AskTerminalClaimCurrent = {
     /** [ref]:赢家决议的**结算来源**(语义与两态读法见 {@link AskRow.settledBy})。**必填**(不是可选)——
      *  可选会让投影漏挑这一列时静默编译过,而漏挑的后果恰是本批要修的病:CAS 输家把赢家的策略拒读成人拒。 */
     settledBy: HostSettledBy | null;
-    /** 行上记着的成因,经问账行成因的唯一读口 `causeOfAskRow` 读出(`kind` 说它在这一行上的意思:VOID / DENIED = 终态成因,PARKING / PARKED = 转 park 的触发成因);
-     *  **只在读得出时在场**(没写 / 与 state 不配 ⇒ 缺席;DECIDED 的败方读数逐字不变)。CAS 输家据它按**行上那个成因**结算(而不是把别人撤的卡读成一次拒绝);
-     *  投影的唯一函数是 {@link projectAskTerminalClaimTruth},三 twin 不各自挑列,原始列值不出店层。 */
-    cause?: AskRowCause;
+    /** 行上记着的终态成因(`ending_cause` 列,经唯一读口 `askRowEndingCause` 读出)。**只在读得出时在场**(没写 / 与 state 不配 ⇒ 缺席;DECIDED 的败方读数逐字不变)。
+     *  CAS 输家据它按**行上那个成因**结算(而不是把别人撤的卡读成一次拒绝);投影的唯一函数是 {@link projectAskTerminalClaimTruth},三 twin 不各自挑列,原始列值不出店层。 */
+    endingCause?: AskRowEndingCause;
+    /** 行上记着的转 park 触发成因(`park_trigger` 列,经唯一读口 `askRowParkTrigger` 读出;行走过 PARKING 才可能在场)。在场律同 {@link endingCause}。 */
+    parkTrigger?: ParkTriggerCause;
 };
 /**
  * 单次原子往返的答案(语义律的唯一规范陈述点 = core `checkpoint-store.ts` `claimTerminal` 契约 JSDoc,
@@ -578,6 +596,20 @@ export declare const APPROVAL_ASK_EXECUTION_LANE_COLUMN: {
     readonly mysql: "execution_lane VARCHAR(32) NOT NULL DEFAULT ''";
     readonly pg: "execution_lane VARCHAR(32) COLLATE \"C\" NOT NULL DEFAULT ''";
 };
+/**
+ * 问行两列成因的列定义(两方言;唯一属主 —— 建表 DDL 内联它们,存量库的改名 / 加列只由一次性迁移做,那一步也读这里:窗口见 `plugins/one-time-migrations.ts` 登记表 M34)。
+ * 宽度 64 = 成因闭集里最长的词有余(钉在 `test/approval-reconciler.test.ts`)。语义见 {@link AskRow.endingCause} / {@link AskRow.parkTrigger}。
+ */
+export declare const APPROVAL_ASK_ENDING_CAUSE_COLUMN: {
+    readonly name: "ending_cause";
+    readonly mysql: "ending_cause VARCHAR(64) NULL";
+    readonly pg: "ending_cause VARCHAR(64) COLLATE \"C\"";
+};
+export declare const APPROVAL_ASK_PARK_TRIGGER_COLUMN: {
+    readonly name: "park_trigger";
+    readonly mysql: "park_trigger VARCHAR(64) NULL";
+    readonly pg: "park_trigger VARCHAR(64) COLLATE \"C\"";
+};
 export declare const APPROVAL_BATCH_TABLE = "approval_batch";
 /**
  * TiDB/MySQL-protocol 侧的两条建表语句,**抽成导出数组**(车3 刀 3a):`tidb-pool.ts` 的

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

@@ -1,6 +1,6 @@
 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 { 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";
@@ -61,6 +61,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,14 +90,16 @@ 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 } : {}),
+        ...(endingCause !== undefined ? { endingCause } : {}),
+        ...(parkTrigger !== undefined ? { parkTrigger } : {}),
     };
 }
 export function askRowOnCall(row, call) {
@@ -105,6 +119,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)) {
@@ -163,7 +187,10 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     -- 编辑实参是整只工具入参,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,
@@ -244,7 +271,9 @@ export async function ensurePgApprovalAskSchema(q) {
     -- 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",
@@ -290,7 +319,7 @@ function askCols(dialect) {
         jsonColumnText(dialect, "decision_actor"),
         "decision_note, settled_by",
         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",
@@ -338,7 +367,8 @@ function mapAskRowBody(r, askId) {
         settledBy: strOrNull(r.settled_by),
         ...(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 +403,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,9 +457,9 @@ 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,
@@ -566,7 +596,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 +615,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 +623,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 +669,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 +677,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 +707,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 +715,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();

package/dist/plugins/file-run-store.d.ts

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import { StoreBootRefusalError, type FenceLanded, type FencedRun, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { StoreBootRefusalError, type FenceLanded, type FencedRun, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
@@ -169,6 +169,11 @@ export declare class FileRunStore implements InProcessClaimFence {
      *  `createdAt DESC, taskId DESC`,与本店 {@link FileRunStore.listSessions} 挑 `rn=1` 那一行的比较器逐字同一份)。
      */
     latestRunForSession(sessionId: string): Promise<LatestRunRef | undefined>;
+    /**
+     * [ref] —— 这个会话**最近一条已结腿**与它的记忆观测(规则属主 = `store-contracts.ts` 的 {@link SettledLegMemoryObservation};
+     * {@link SqlRunStore.latestMemoryObservationForSession} 的孪生:同一只已结谓词(`isTerminalRunStatus`)、同一个排序口径 —— 与本店 {@link FileRunStore.latestRunForSession} 的比较器逐字同一份)。
+     */
+    latestMemoryObservationForSession(sessionId: string): Promise<SettledLegMemoryObservation | undefined>;
     /** DISTINCT sessions newest-first by last activity (the CC /resume picker): latest run's preview/status + first/last/count. */
     listSessions(opts: {
         owner?: string;

package/dist/plugins/file-run-store.js

@@ -7,7 +7,7 @@ import { randomBytes } from "node:crypto";
 import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprint, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError, readLegacyHolderDeathCode } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError, readLegacyHolderDeathCode, isTerminalRunStatus, settledLegObservationOf } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
 import { readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 import { createInProcessSpaceCommitTable, fenceSpaceCommitAtTerminal, SPACE_COMMIT_RECORD_SCHEMA } from "../workspace-space-commit.js";
@@ -595,6 +595,16 @@ export class FileRunStore {
         }
         return latest === undefined ? undefined : { taskId: latest.taskId, owner: latest.owner, createdAt: latest.createdAt.toISOString() };
     }
+    async latestMemoryObservationForSession(sessionId) {
+        let latest;
+        for (const r of this.runs.values()) {
+            if (r.sessionId !== sessionId || !isTerminalRunStatus(r.status))
+                continue;
+            if (latest === undefined || r.createdAt.getTime() > latest.createdAt.getTime() || (r.createdAt.getTime() === latest.createdAt.getTime() && r.taskId > latest.taskId))
+                latest = r;
+        }
+        return latest === undefined ? undefined : settledLegObservationOf(latest.taskId, latest.result);
+    }
     async listSessions(opts) {
         const bySession = new Map();
         for (const r of this.runs.values()) {

package/dist/plugins/local-session-store.d.ts

@@ -349,9 +349,9 @@ export declare class LocalSessionStore implements SessionStore {
     writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
     /**
      * 写原语锁住的那一行(调用方持这只会话的写锁并已 {@link loadRowSidecars}):会话元数据那一格(属主 `owner ?? null` —— 与头读、列表行同读;化身经
-     * `incarnationFromCell` 的 `absent` 读法;执行位 `mirror`)+ 列表面上有它(会话仓里有;`forking` 中间态的存档不在 ⇒ 不在列表上)+ 两只边档的格。
-     * 没有那一格或不在列表面上 ⇒ `undefined`(没有行)。委派分区行(placed)不上列表面(repo 的 `list()` 按存档行头排除,义务 2)⇒ 走到这里的行恒非 placed,
-     * `placed: false` 是列表面那一判的投影,不是另一读。
+     * `incarnationFromCell` 的 `absent` 读法;执行位 `mirror`)+ 行集里有它({@link rowHeaderOf};`forking` 中间态的存档不在 ⇒ 不在列表上)+ 两只边档的格。
+     * 没有那一格或不在列表面上 ⇒ `undefined`(没有行)。委派分区行(placed)不上列表面(repo 的 `list()` 按存档行头排除,义务 2;行头读不出的行没有可读的 placement 记录、
+     * 按普通行读 —— 文件头注那一条)⇒ `placed: false` 是列表面那一判的投影,不是另一读。存档读不出的行照样是一行(行格住在边档,写得了;HTTP 改名口的坏档判据排在本原语之前)。
      */
     private lockedRowOf;
     /** 两只边档上这只会话的可写格(已发布的值;缺键 = 缺省)。调用方先 {@link loadRowSidecars}。 */
@@ -361,10 +361,35 @@ export declare class LocalSessionStore implements SessionStore {
     /** 应答行(锁内另读):列表行同一只合成 + 读到它时那一格上的住客。不在列表面上 / 没有那一格 ⇒ `undefined`。 */
     private listRowOf;
     /** ONE session's list row — {@link listSessions}' projection ({@link summaryOf}, the same synthesis) for one id;
-     *  `undefined` = not a row of the list face (not in the session repo). */
+     *  `undefined` = not a row of the list face ({@link rowHeaders}). */
     sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
-    /** 会话仓里这只会话的列表元数据(列表面上的行 = `repo.list()` 里的一项)。 */
-    private listedMeta;
+    /**
+     * 本店的**行集** —— 唯一的会话枚举(列表 {@link listSessions}、一次性迁移 M33 的步 1 读它;按 id 读的 {@link rowHeaderOf} 是同一只判据的一只 id 形):
+     *  · 引擎仓的列表(core `repo.list()`:存档**行头**读得出、非 placed)—— 行头读得出的行;
+     *  · ∪ 会话元数据边档里有格、不在引擎仓列表里的 id,经 {@link headerUnreadableRowOf}:存档头读了抛、且不是 placed 行 ⇒ 行头读不出的行(带那只故障);
+     *    不抛(存档不在:fork 中间态 / 删除中;或读间新建)/ placed 行(行头读得出,repo 的 `listPlaced` 认得它,尾部再坏也不上列表面)⇒ 不是行集里的行。
+     * 边档里没有格、存档头又读不出的会话(7.104.0 之前写下、此后从没被读过)没有一格可读的行事实 —— 属主读不出 ⇒ 不进行集(fail-closed,与归属门同读:
+     * {@link metaOf} 判不了它在不在 ⇒ 整只拒);运维面由 core 列表的披露座与起服 warn 点名它。
+     * 「行头读不读得出」(行集,M33 回填行事实问的就是它)与「叶子读不读得出」(列表行的 `unreadable`,{@link listedRowOf})是两件事、各一只读法。
+     */
+    private rowHeaders;
+    /**
+     * 行集里的这一行({@link rowHeaders} 的按 id 一形:同一只判据,只判这一只 id 的行 —— 别的会话读不出不改它的答)。`undefined` = 不是行集里的行。
+     * ⚠️ 如实:取它的行头仍经引擎仓列表(`repo.list()` 读一遍各会话的头),所以别的会话的头坏了,这一次读照旧为它报一次读坏披露;按 id 直读不在本形里。
+     */
+    private rowHeaderOf;
+    /** 不在引擎仓列表里、边档有格的一只 id:存档头读了抛、且不是 placed 行 ⇒ 行头读不出的那一行;否则 `undefined`(见 {@link rowHeaders})。 */
+    private headerUnreadableRowOf;
+    /**
+     * 委派分区行的 id 集的读者(repo 记 placement ⇒ 它的 `listPlaced`,行头那一读;不记 ⇒ 空集 —— 那种 repo 里没有 placed 行)。惰性、一次读:只在有一只 id 的存档头读抛、
+     * 要分「行头读不出」与「行头读得出的 placed 行尾部坏了」时才读。
+     */
+    private createPlacedIdsReader;
+    /**
+     * 列表面上的一行的内容那一半 = 头读的**叶子**那一读({@link archiveHeadOf},与 {@link headOf} 的叶子同一读):行头读不出 ⇒ 读不出(那只故障);行头读得出 ⇒ 再读叶子,
+     * 抛 ⇒ 读不出(尾部 I/O 故障之类:行头好、头读照样抛);否则读得出。所以行上的 `unreadable` 与头读、读口对同一只会话的答复同读。
+     */
+    private listedRowOf;
     /** [ref] —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**
@@ -481,6 +506,10 @@ export declare class LocalSessionStore implements SessionStore {
      *                          `lastTaskRunId` = that run's `result.runId`). One call per list (not per row); a session with no
      *                          run row ⇒ `0 / "" / null` (TiDB's null→"" mapping); a run-store read failure throws (never `0 / ""`).
      *
+     *   - `unreadable`      — present-iff the row's head leaf cannot be read ({@link listedRowOf}: the archive header, or the tail the head read
+     *                          scans): the row's facts above still come from its session-meta cell; `objectivePreview` is null; the marker's
+     *                          `errorCode` is what the session's own reads answer.
+     *
      * Keyset matches the contract: STRICTLY older than the cursor, ties broken by id DESC; `limit` is honored after
      * the in-memory sort. Cheap (a local single-user store holds few sessions). Errors reading one session's entries
      * degrade that row's preview to null rather than failing the whole list.
@@ -693,7 +722,7 @@ export declare class LocalSessionStore implements SessionStore {
     /**
      * 一次性迁移 M33 的 local 腿(`LocalBackend.runOneTimeMigrations` 调;起服、先于任何请求;窗内每次起服都跑,第二次起零命中):
      *  0. 恢复先行({@link settleArchiveSnapshots},幂等);
-     *  1. **枚举**:id 全集 = 引擎仓的列表(读得出头的存档)∪ 边档全部键;只在边档里的、头读抛的 ⇒ 计 unreadable(步 3 整档读抛的同计)。两边都不在的读不出存档(列表跳过它、边档里没它的格)
+     *  1. **枚举**(行集 `rowHeaders`):id 全集 = 引擎仓的列表(读得出头的存档)∪ 边档全部键;只在边档里的、头读抛且不是 placed 行(行头读得出)的 ⇒ 计 unreadable(步 3 整档读抛的同计)。两边都不在的读不出存档(列表跳过它、边档里没它的格)
      *     对本店与引擎同样不可见,不计;
      *  2. **行回填**:列表里每一只存档 —— 格缺 ⇒ 建一格(化身新铸、属主「从没被记下」,与补铸同义);格缺建档时刻 ⇒ 写存档头的;格缺谱系而存档头有 ⇒ 写它。只写行(边档的一次提交),
      *     然后一道**落盘屏障**(边档文件与目录各 fsync)—— 在这之前不碰任何存档;

package/dist/plugins/local-session-store.js

@@ -4,7 +4,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { isDeepStrictEqual } from "node:util";
 import { dirname, join, resolve } from "node:path";
 import { assertFirstOwnerWritable, forkOwnerOf, importerOwnerOf } from "./session-ownership.js";
-import { StampedSessionArchiveError } from "../session-error-wire.js";
+import { StampedSessionArchiveError, sessionUnreadableOf } from "../session-error-wire.js";
 import { FileSessionRepo, SessionError, StoredSession, admitSessionPlacement, atomicWriteFile, sessionLogMarkOf, settledForkOptions, uuidv7, validateEntriesForImport } from "@sema-agent/core";
 import { createPlacedSessionRow, sourceFacesVia } from "../delegated-session-owner.js";
 import { placementCapabilityOf } from "./session-placement.js";
@@ -677,7 +677,7 @@ export class LocalSessionStore {
     }
     async lockedRowOf(sessionId) {
         const meta = this.metaCellOf(sessionId);
-        if (meta === undefined || (await this.listedMeta(sessionId)) === undefined)
+        if (meta === undefined || (await this.rowHeaderOf(sessionId)) === undefined)
             return undefined;
         return { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), placed: false, mirror: meta.execution?.role === "mirror", cells: this.rowCellsOf(sessionId) };
     }
@@ -713,19 +713,62 @@ export class LocalSessionStore {
     }
     async listRowOf(sessionId) {
         await this.loadRowSidecars();
-        const listed = await this.listedMeta(sessionId);
+        const header = await this.rowHeaderOf(sessionId);
         const meta = this.metaCellOf(sessionId);
-        if (listed === undefined || meta === undefined)
+        if (header === undefined || meta === undefined)
             return undefined;
-        return { row: await this.summaryOf(listed, await this.runRollups()), occupant: { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent") } };
+        return { row: await this.summaryOf(await this.listedRowOf(header), await this.runRollups()), occupant: { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent") } };
     }
     async sessionSummaryOf(sessionId) {
         await this.loadRowSidecars();
-        const meta = await this.listedMeta(sessionId);
-        return meta === undefined ? undefined : this.summaryOf(meta, await this.runRollups());
+        const header = await this.rowHeaderOf(sessionId);
+        return header === undefined ? undefined : this.summaryOf(await this.listedRowOf(header), await this.runRollups());
     }
-    async listedMeta(sessionId) {
-        return (await this.repo.list()).find((m) => m.id === sessionId);
+    async rowHeaders() {
+        await this.meta.ensureLoaded();
+        const listed = await this.repo.list();
+        const listedIds = new Set(listed.map((row) => row.id));
+        const placed = this.createPlacedIdsReader();
+        const rows = listed.map((header) => ({ sessionId: header.id, header }));
+        for (const id of [...this.meta.state.entries.keys()].sort()) {
+            if (listedIds.has(id))
+                continue;
+            const row = await this.headerUnreadableRowOf(id, placed);
+            if (row !== undefined)
+                rows.push(row);
+        }
+        return rows;
+    }
+    async rowHeaderOf(sessionId) {
+        await this.meta.ensureLoaded();
+        const header = (await this.repo.list()).find((m) => m.id === sessionId);
+        if (header !== undefined)
+            return { sessionId, header };
+        return this.meta.state.entries.has(sessionId) ? this.headerUnreadableRowOf(sessionId, this.createPlacedIdsReader()) : undefined;
+    }
+    async headerUnreadableRowOf(sessionId, placed) {
+        try {
+            await this.archiveHeadOf(sessionId);
+            return undefined;
+        }
+        catch (fault) {
+            return (await placed()).has(sessionId) ? undefined : { sessionId, headerFault: fault };
+        }
+    }
+    createPlacedIdsReader() {
+        let ids;
+        return () => (ids ??= (async () => new Set((await this.listPlaced?.("subagent"))?.map((row) => row.sessionId) ?? []))());
+    }
+    async listedRowOf(row) {
+        if ("headerFault" in row)
+            return { sessionId: row.sessionId, unreadable: row.headerFault };
+        try {
+            await this.archiveHeadOf(row.sessionId);
+            return { sessionId: row.sessionId, readable: row.header };
+        }
+        catch (fault) {
+            return { sessionId: row.sessionId, unreadable: fault };
+        }
     }
     async readInstructionSource(sessionId) {
         await this.instructionSources.ensureLoaded();
@@ -953,14 +996,16 @@ export class LocalSessionStore {
     }
     async listSessions(opts) {
         await this.loadRowSidecars();
-        const metas = await this.repo.list();
+        const rows = [];
+        for (const header of await this.rowHeaders())
+            rows.push(await this.listedRowOf(header));
         const rollups = await this.runRollups();
         const all = [];
-        for (const meta of metas) {
-            const owner = this.ownerCellOf(meta.id);
+        for (const row of rows) {
+            const owner = this.ownerCellOf(row.sessionId);
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
                 continue;
-            all.push(await this.summaryOf(meta, rollups));
+            all.push(await this.summaryOf(row, rollups));
         }
         const qlc = opts.q?.toLowerCase();
         const filtered = qlc ? all.filter((r) => r.objectivePreview?.toLowerCase().includes(qlc)) : all;
@@ -983,23 +1028,25 @@ export class LocalSessionStore {
         const cell = this.meta.state.entries.get(sessionId);
         return cell === undefined ? null : (readSessionMetaCell(cell).owner ?? null);
     }
-    async summaryOf(meta, rollups) {
-        const firstActivityAt = rowCreatedAtOf(meta.id, this.metaCellOf(meta.id));
-        const owner = this.ownerCellOf(meta.id);
-        const cells = this.rowCellsOf(meta.id);
-        const rowTag = this.rowTagKeyOf(meta.id, owner, cells);
-        const lastActivityAt = this.lastActivity.get(meta.id) ?? firstActivityAt;
-        const objectivePreview = await this.previewOf(meta);
+    async summaryOf(listed, rollups) {
+        const { sessionId } = listed;
+        const firstActivityAt = rowCreatedAtOf(sessionId, this.metaCellOf(sessionId));
+        const owner = this.ownerCellOf(sessionId);
+        const cells = this.rowCellsOf(sessionId);
+        const rowTag = this.rowTagKeyOf(sessionId, owner, cells);
+        const lastActivityAt = this.lastActivity.get(sessionId) ?? firstActivityAt;
+        const objectivePreview = "readable" in listed ? await this.previewOf(listed.readable) : null;
         return {
-            sessionId: meta.id,
+            sessionId,
             owner,
             lastActivityAt,
             firstActivityAt,
             objectivePreview,
-            ...this.runProjectionOf(meta.id, rollups),
+            ...this.runProjectionOf(sessionId, rollups),
             title: cells.title,
             pinned: cells.pinned,
             ...rowTag,
+            ...("unreadable" in listed ? { unreadable: sessionUnreadableOf(listed.unreadable) } : {}),
         };
     }
     rowTagKeyOf(sessionId, owner, cells) {
@@ -1381,19 +1428,16 @@ export class LocalSessionStore {
         if (!this.repo.readRow || !this.repo.importEntries)
             throw new SessionError("storage", "LocalSessionStore: the one-time migration M33 needs a session repo that reads a whole row and imports a log (readRow / importEntries)");
         await this.meta.ensureLoaded();
-        const listed = await this.repo.list();
-        const listedIds = new Set(listed.map((row) => row.id));
+        const rowHeaders = await this.rowHeaders();
+        const listed = [];
         const unreadable = [];
-        for (const id of [...this.meta.state.entries.keys()].sort()) {
-            if (listedIds.has(id))
+        for (const row of rowHeaders) {
+            if ("header" in row) {
+                listed.push(row.header);
                 continue;
-            try {
-                await this.archiveHeadOf(id);
-            }
-            catch (e) {
-                const errno = errnoOf(e);
-                unreadable.push({ sessionId: id, ...(errno !== undefined ? { errno } : {}) });
             }
+            const errno = errnoOf(row.headerFault);
+            unreadable.push({ sessionId: row.sessionId, ...(errno !== undefined ? { errno } : {}) });
         }
         let rowFactsBackfilled = 0;
         const committed = await this.meta.commit((draft) => {

package/dist/plugins/local-task-attachment-store.d.ts

@@ -1,18 +1,28 @@
-import { type TaskAttachmentStore, type TaskAttachmentRecord } from "./task-attachment-store.js";
+import { type AttachmentStoreBindOutcome, type TaskAttachmentStore, type TaskAttachmentRecord } from "./task-attachment-store.js";
 export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
     private readonly dir;
     private metas;
     private hydration;
+    /** 变更串行段的尾(见 `serialized`):每只变更口排在上一只的落盘与合回之后。本店唯一一只。 */
+    private mutationTail;
     constructor(rootDir: string);
     private hydrate;
+    /**
+     * 本店**唯一**的变更串行段:凡改 `this.metas` 或删盘上行的口(put / bind / delete / deleteBySession / reapUnbound)把**整条操作**
+     * (判 + 落盘 + 合回内存)交进来,于是任何一只变更口都观察不到别的变更口做到一半的中间态 —— bind 落盘期间「副本已判、内存未合」
+     * 的那一段,收割 / 删除既不会判到旧内存、也不会把盘上正在落的行删掉。读口不进来:它们只读内存,不排队。
+     * 一只变更失败不堵后面的(尾巴吞掉失败,错原样上抛给它自己的调用方)。操作体里不得再调 `serialized`(会排在自己后面)。
+     */
+    private serialized;
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;
     }): Promise<void>;
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
     private persistMeta;
-    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
+    /** 删一行(meta + bytes + 内存索引)。只在 `serialized` 的操作体里调用。 */
     private removeRow;
     delete(owner: string, id: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;