@sema-agent/server 7.147.0 → 7.149.0

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

@@ -4,8 +4,10 @@ import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, readNonNullJsonValueColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { buildObjectivePreview } from "../user-authored-text.js";
+import { RUN_IDENTITY_COLUMNS, readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 export const LEADER_RUN_TABLE = "leader_run";
 const LEADER_RUN_STATUSES = new Set(["running", "completed", "failed", "needs_human"]);
+const LEADER_RUN_ERROR_CODES = new Set(["cancelled"]);
 export const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
 export const TIDB_LEADER_RUN_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${LEADER_RUN_TABLE} (
@@ -22,6 +24,12 @@ export const TIDB_LEADER_RUN_STATEMENTS = [
      -- result:LeaderResult 的 JSON 原样(店不解释内部结构)。仅终局时写。
      result         JSON         NULL,
      error          TEXT         NULL,
+     -- error_code:终局的机读码(闭集 LeaderRunErrorCode;今天只有取消口停下的 run 写 cancelled,其余 NULL)。
+     error_code     VARCHAR(64)  NULL,
+     -- cancel_requested:耐久取消旗(与 task_run / image_bake 同形)。取消口只翻 running 行;驱动这条 run 的副本按存活心跳拍读它并中止。
+     cancel_requested SMALLINT   NOT NULL DEFAULT 0,
+     -- 受理时验过的身份元组三列(列定义的唯一属主 = identity-source.ts 的 RUN_IDENTITY_COLUMNS,与 task_run 内插同一段)。
+     ${RUN_IDENTITY_COLUMNS.mysql},
      started_at_ms  BIGINT       NOT NULL,
      finished_at_ms BIGINT       NULL,
      PRIMARY KEY (leader_run_id),
@@ -39,6 +47,9 @@ export const PG_LEADER_RUN_SCHEMA = [
      status         VARCHAR(16) COLLATE "C"  NOT NULL,
      result         JSONB        NULL,
      error          TEXT COLLATE "C"         NULL,
+     error_code     VARCHAR(64) COLLATE "C"  NULL,
+     cancel_requested SMALLINT   NOT NULL DEFAULT 0,
+     ${RUN_IDENTITY_COLUMNS.pg},
      started_at_ms  BIGINT       NOT NULL,
      finished_at_ms BIGINT       NULL,
      PRIMARY KEY (leader_run_id),
@@ -47,6 +58,7 @@ export const PG_LEADER_RUN_SCHEMA = [
 ];
 export const LEADER_RUN_INDEXES = [
     { table: `${LEADER_RUN_TABLE}`, name: "idx_leader_run_owner", columns: ["owner"] },
+    { table: `${LEADER_RUN_TABLE}`, name: "uq_leader_run_idem", columns: ["idem_key"], unique: true },
     { table: `${LEADER_RUN_TABLE}`, name: "idx_leader_run_started", columns: ["started_at_ms"] },
 ];
 export async function ensurePgLeaderRunSchema(q) {
@@ -57,7 +69,7 @@ export async function ensurePgLeaderRunSchema(q) {
 export const STALE_SWEEP_REASON = "leader run went stale: no replica settled it within LEADER_RUN_STALE_MS (the replica driving it most likely died). " +
     "The run was NOT taken over — re-submit with a NEW Idempotency-Key to run it again.";
 function selectCols(dialect) {
-    return `leader_run_id, owner, objective_preview, status, ${jsonColumnText(dialect, "result")}, error, started_at_ms, finished_at_ms`;
+    return `leader_run_id, owner, objective_preview, status, ${jsonColumnText(dialect, "result")}, error, error_code, cancel_requested, identity_source, identity_scope, identity_principal_inc, started_at_ms, finished_at_ms`;
 }
 function readResultColumn(text, id) {
     try {
@@ -67,6 +79,15 @@ function readResultColumn(text, id) {
         throw foldJsonColumn(e, (m) => `leader_run: ${m} — refusing rather than serve this run as if it had finished empty-handed`);
     }
 }
+function errorCodeOf(raw, id) {
+    if (raw == null)
+        return undefined;
+    const s = String(raw);
+    if (!LEADER_RUN_ERROR_CODES.has(s)) {
+        throw new Error(`leader_run ${id}: unknown error_code ${JSON.stringify(s)} (closed word table: ${[...LEADER_RUN_ERROR_CODES].join("|")}) — a newer replica wrote a word this build cannot interpret`);
+    }
+    return s;
+}
 function statusOf(raw, id) {
     const s = String(raw);
     if (!LEADER_RUN_STATUSES.has(s)) {
@@ -78,6 +99,7 @@ function mapRow(r) {
     const id = String(r.leader_run_id);
     const result = readResultColumn(r.result, id);
     const error = r.error == null ? undefined : String(r.error);
+    const errorCode = errorCodeOf(r.error_code, id);
     const finished = r.finished_at_ms == null ? undefined : Number(r.finished_at_ms);
     return {
         id,
@@ -86,6 +108,9 @@ function mapRow(r) {
         objectivePreview: r.objective_preview == null ? null : String(r.objective_preview),
         ...(result === undefined ? {} : { result }),
         ...(error === undefined ? {} : { error }),
+        ...(errorCode === undefined ? {} : { errorCode }),
+        cancelRequested: Number(r.cancel_requested) === 1,
+        identity: readRunIdentityCells(r.identity_source, r.identity_scope, r.identity_principal_inc),
         startedAtMs: Number(r.started_at_ms),
         ...(finished === undefined ? {} : { finishedAtMs: finished }),
     };
@@ -102,9 +127,10 @@ export class SqlLeaderRunStore {
         const id = uuidv7();
         const now = Date.now();
         const preview = buildObjectivePreview(input.objective, LEADER_OBJECTIVE_PREVIEW_CHARS);
-        const params = [id, input.idemKey, input.owner, preview, "running", now];
+        const cells = runIdentityCells(input.identity);
+        const params = [id, input.idemKey, input.owner, preview, "running", now, cells.identitySource, cells.identityScope, cells.identityPrincipalInc];
         try {
-            await this.db.query(this.q(`INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms) VALUES (?,?,?,?,?,?)`, `INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms) VALUES ($1,$2,$3,$4,$5,$6)`), params);
+            await this.db.query(this.q(`INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms, identity_source, identity_scope, identity_principal_inc) VALUES (?,?,?,?,?,?,?,?,?)`, `INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms, identity_source, identity_scope, identity_principal_inc) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`), params);
         }
         catch (err) {
             if (isDupKeyError(this.db.dialect, err) && input.idemKey) {
@@ -129,6 +155,10 @@ export class SqlLeaderRunStore {
         const row = res.rows[0];
         return row ? mapRow(row) : undefined;
     }
+    async requestCancel(id) {
+        const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET cancel_requested = 1 WHERE leader_run_id = ? AND status = 'running'`, `UPDATE ${LEADER_RUN_TABLE} SET cancel_requested = 1 WHERE leader_run_id = $1 AND status = 'running'`), [id]);
+        return res.affected > 0;
+    }
     async reapStaleRunning(staleMs, now) {
         const cutoff = now - staleMs;
         const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = 'failed', error = ?, finished_at_ms = ? WHERE status = 'running' AND started_at_ms < ?`, `UPDATE ${LEADER_RUN_TABLE} SET status = 'failed', error = $1, finished_at_ms = $2 WHERE status = 'running' AND started_at_ms < $3`), [STALE_SWEEP_REASON, now, cutoff]);
@@ -139,7 +169,7 @@ export class SqlLeaderRunStore {
     }
     async finishRun(id, patch) {
         const json = dialectJsonEncoder(this.db.dialect);
-        const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = ?, result = CAST(? AS JSON), error = ?, finished_at_ms = ? WHERE leader_run_id = ? AND status = 'running'`, `UPDATE ${LEADER_RUN_TABLE} SET status = $1, result = $2::jsonb, error = $3, finished_at_ms = $4 WHERE leader_run_id = $5 AND status = 'running'`), [patch.status, patch.result == null ? null : json(patch.result), patch.error ?? null, Date.now(), id]);
+        const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = ?, result = CAST(? AS JSON), error = ?, error_code = ?, finished_at_ms = ? WHERE leader_run_id = ? AND status = 'running'`, `UPDATE ${LEADER_RUN_TABLE} SET status = $1, result = $2::jsonb, error = $3, error_code = $4, finished_at_ms = $5 WHERE leader_run_id = $6 AND status = 'running'`), [patch.status, patch.result == null ? null : json(patch.result), patch.error ?? null, patch.errorCode ?? null, Date.now(), id]);
         return res.affected > 0;
     }
 }

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

@@ -1,15 +1,21 @@
 import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ExecutionOutcomeRecordWord, type GateOutcome, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
-import { type CheckpointAskCandidate, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-face.js";
-import { type FencedRun, type InProcessClaimFence } from "./store-contracts.js";
+import { type CheckpointAskCandidate, type CtxClaimPut, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type ExpiredApprovalGate, type ExpiredGatePosition, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-face.js";
+import { type CtxWriteClaim } from "./store-contracts.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
+/**
+ * 一只会话的续跑输入档**严格**删(提交出口撤回一只刚铸会话时的 local 一形;SQL 孪生是撤回事务里的 `DELETE FROM checkpoint_ctx WHERE session_id = ?`):
+ * 档不在 ⇒ 照常;删不掉 ⇒ **抛**(撤回的删序还没落标记 ⇒ 会话完整可见,不吞成「删了」);删掉之后 fsync ctx 目录(win32 不 fsync 目录)。
+ * 只按路径动档,不建店实例(本部署没开续跑输入时目录里本就没有这只档)。路径与 {@link LocalCheckpointStore} 的写口同一只(`localCheckpointStoreDirsFor` + {@link ctxFileOf})。
+ */
+export declare function dropLocalCheckpointCtxStrict(root: string, sessionId: string): void;
 export interface LocalCheckpointStoreOptions {
-    /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
+    /** 本店对引擎的耐久声明(装配方给 —— local 后端递 `localStoreDeclarationOf` 那一份,与会话店同读:两半一起)。缺席 ⇒ 内核的读数 `"durable"`(见字段注)。 */
+    durability?: StoreDurability;
+    /** 会话认领联结(the local FileRunStore's `getActiveTaskId`)—— 停驻行 `taskId` 的第二格读数([ref],写者 `parkedLegTaskId`)。Absent ⇒ 只剩行上的记录。 */
     getActiveTaskId?: (sessionId: string) => Promise<string | undefined>;
     /** E21 owner guard (the LocalSessionStore's owner read, `headOf(id)?.owner`: `undefined` = no session row). Absent ⇒ owner guard degrades
      *  to null-owner-only (a non-null owner with no owner source purges NOTHING — fail-closed, mirrors the SQL EXISTS guard). */
     readSessionOwner?: (sessionId: string) => Promise<string | null | undefined>;
-    /** ctx 改写的认领栅栏({@link LocalCheckpointStore.rewriteCtxWhileClaimed}):同一数据根上的文件 run 店(进程内栅栏形)。缺席 ⇒ 那一口响亮抛(装配缺陷)。 */
-    claims?: InProcessClaimFence;
 }
 /** checkpoint 店在数据根下自己铸的目录(构造器与一次性迁移 M39 的名册同读这一只)。 */
 export declare function localCheckpointStoreDirsFor(root: string): {
@@ -27,6 +33,8 @@ export declare class LocalCheckpointStore {
      *
      * 它与「session store 的 local 形声明 durable 就拒启」不矛盾:那条判据管的是**声明 vs 介质**,而这里
      * 的介质就是盘。真正的 process-local 形(`InMemoryCheckpointStore`)由 core 自己声明 `"process-local"`。
+     * 装配方给了声明就用它(local 后端递 `localStoreDeclarationOf` 那一份 —— 运维声明易失 / 调用方自己那块易失盘 ⇒ 与会话店一起降为 `"process-local"`:
+     * 进程重启照旧活过,容器替换不保留;只降一半会让引擎的 durable-park 自检读出缺口)。
      */
     readonly durability: StoreDurability;
     /**
@@ -68,8 +76,30 @@ export declare class LocalCheckpointStore {
      *  suspend→crash→expire-later lifecycle visible. Entries are never dropped while the inner row exists
      *  (a `resolved` row can be reopen()ed back to pending — pruning it would be wrong). */
     private readonly sessionTokens;
+    /**
+     * **归属索引**:每张卡归在哪只会话上(SQL 孪生的 `checkpoint.host_session_id` 列在本店的同一个事实;读法 `hostSessionOf`,`put` 求值一次)。
+     * `hostTokens` = 归属会话 → 卡,`hostOfToken` = 反查(内存,由前者建)。持久化在 `checkpoint-host-sessions.json`,与 scope 注册表 / 会话索引同一条落盘先后
+     * (先登记、后内核 put:崩在两步之间 ⇒ 一条指向不存在的行的归属,读者按 `get` 为空跳过;反过来 ⇒ 一张谁的 run 都找不到的卡)。
+     * 存量卡由一次性迁移 M49 自卡的会话回填({@link backfillHostSessionsM49})。按 run 找卡的读口(取消 / 收割探针 / 续跑输入回收 / 运维队列行的 run)只读它。
+     */
+    private readonly hostTokens;
+    private readonly hostOfToken;
+    private readonly hostSessionsPath;
     private readonly opts;
     constructor(root: string, opts?: LocalCheckpointStoreOptions);
+    /**
+     * 三份旁索引(scope 注册表 / 会话索引 / 归属索引)在 `put` 里的**唯一**登记形:内存先记、整档落盘;落盘抛 ⇒ 内存那一笔撤回再抛。
+     * 撤回是这条规则的要害:三份索引都按「内存里已有 ⇒ 不再落盘」判,一笔留在内存里的失败登记会让同一张卡的重试 `put` 跳过落盘、内核行照提交
+     * —— 文件里永远没有它(重启之后:scope 枚举不到这张卡;会话索引漏它;归属被 M49 自卡的会话回填,cascade 级上的卡丢了它的 run)。
+     * `record` 交回「这一次记下了新东西」,`undo` 只撤这一次记下的那一笔。
+     */
+    private registerDurably;
+    /** 归属索引的内存两面一起记(不落盘;落盘见 {@link persistHostSessions})。交回这一次新记下的卡数。 */
+    private indexHost;
+    /** {@link indexHost} 的一张卡的逆(只给 {@link registerDurably} 的撤回用)。 */
+    private unindexHost;
+    /** Persist the card→host-session index (whole-file atomic replace — same cadence as the session→tokens index). */
+    private persistHostSessions;
     /** Persist the session→tokens index (whole-file atomic replace — puts are per-suspend, low frequency). */
     private persistSessionTokens;
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
@@ -116,22 +146,22 @@ export declare class LocalCheckpointStore {
      * session 两条 pending 时答哪条取决于 sidecar 里 scope 的插入序 —— 与 SQL 无序 `LIMIT 1` 同病。
      */
     findPendingTokenBySession(sessionId: string, scope?: string, binding?: PendingRowBinding): Promise<CheckpointToken | null>;
+    /** 会话那一轴的候选集(`PendingRowBinding.axis`):卡自己的对话 ⇒ 内核的按会话读口;卡归属的 run 会话 ⇒ 归属索引({@link runPendings})。 */
+    private axisPendings;
     /** [ref]:候选集 → 读口该答的那一条(过滤 sessionId + 门型,再取「最新优先」)。 */
     private pickPendingRow;
-    /** [ref] read-only probe face: does this session have an EXPIRED checkpoint row? The local twin of the SQL
-     *  `EXISTS (SELECT 1 FROM checkpoint ce WHERE ce.session_id = ? AND ce.status = 'expired')` that drives the
-     *  run stores' failSuspendedWithExpiredCheckpoint. Scans the session→token index (get(token) is the only
-     *  cross-status read core's File store offers); an index entry whose inner row vanished is pruned lazily.
-     *  Backed by a persisted registry, so it stays honest — never a guessed "true".
-     *  ⚠️ 存量限制(codex M2,如实):索引随 put 增量建立,无升级迁移——本版本部署前已存在的 checkpoint 不在
-     *  索引里,其 expired 对本探针不可见(core File store 的 listByScope 是 pending-only,无法枚举历史行回填)。
-     *  旧存量锁死的恢复把手 = cancel verb([ref]①,不依赖本索引);增量行全覆盖。 */
-    hasExpiredBySession(sessionId: string): Promise<boolean>;
+    /** [ref] read-only probe face: does this RUN session have an EXPIRED checkpoint filed under it? The local twin of the SQL
+     *  `EXISTS (SELECT 1 FROM checkpoint ce WHERE ce.host_session_id = tr.session_id AND ce.status = 'expired')` that drives the
+     *  run stores' failSuspendedWithExpiredCheckpoint. Scans the card→host-session index (get(token) is the only
+     *  cross-status read core's File store offers). Backed by a persisted registry, so it stays honest — never a guessed "true".
+     *  ⚠️ 存量限制(如实):M49 从会话索引与此刻的待决行回填归属 —— [ref] 会话索引建立之前就已不是 pending 的老卡两边都不在,
+     *  其 expired 对本探针不可见;旧存量锁死的恢复把手 = cancel verb([ref]①)。 */
+    hasExpiredForRun(runSessionId: string): Promise<boolean>;
     /**
      * [ref] 件1 —— SQL 孪生 `findDecidedApprovalsForBinding` 的本地形(判据、词表、失败方向逐条同源;
      * 那处顶注是唯一真源,这里只记两处**本地形自己的**差别)。
      *
-     *  · 枚举面走 [ref] 的 `sessionTokens` 索引 —— 与 `hasExpiredBySession` 同一条路(core 的 File store
+     *  · 枚举面走 [ref] 的 `sessionTokens` 索引(按卡的对话;core 的 File store
      *    只能 pending-only 枚举,跨态读只有 `get(token)`),所以它那条**存量限制**在这里逐字同样成立:
      *    索引建立之前 park 的老行对本口不可见 ⇒ 回放判别不出 ⇒ 调用方逐字回落 404(保守方向)。
      *  · **没有排序**:本口交出全部命中行,由调用方按「判词一致才回放」判(理由见 SQL 孪生顶注的
@@ -155,7 +185,7 @@ export declare class LocalCheckpointStore {
      * 补齐,而不是给下游那两处各加一条「这台机器绑不了」的特判。
      *
      * 形差(逐条,如实):
-     *  · **枚举面**走 [ref] 的 `sessionTokens` 索引(与 `hasExpiredBySession` / `findDecidedApprovalsForBinding`
+     *  · **枚举面**走 [ref] 的 `sessionTokens` 索引(与 `findDecidedApprovalsForBinding`
      *    同一条路),所以它那条**存量限制**在这里逐字同样成立:索引建立之前 put 的老行对本口不可见 ⇒ 判据 1
      *    不命中 ⇒ 行落判据 ②③④⑤(保守方向,与读口缺席时的既有降级同向)。
      *  · **没有列,所以没有列/blob 一致性门**:SQL 孪生的两道矛盾门(`tool_call_id` 与 `bound_input_hash`
@@ -181,6 +211,15 @@ export declare class LocalCheckpointStore {
     /** `undefined` = no pending row; else the owner scope (local scopes are always strings — never null).
      *  [ref]:与 `findPendingTokenBySession` 同一个 {@link pickPendingRow}(同 binding ⇒ 同一行)。 */
     peekPendingScope(sessionId: string, binding?: PendingRowBinding): Promise<string | null | undefined>;
+    /** 归在这只 run 会话上的待决卡(归属索引 → 逐张 `get`;只认 pending,scope 给了就再判一次)。 */
+    private runPendings;
+    /** SQL 孪生 `hostSessionOfCard` 的本地形:`undefined` = 没有这一行;`null` = 行在、归属索引里没有它(M49 还没回填到的存量卡)。 */
+    hostSessionOfCard(token: CheckpointToken): Promise<string | null | undefined>;
+    /**
+     * M49 的本地腿:存量卡的归属自卡的会话回填(SQL 孪生 `UPDATE … SET host_session_id = session_id WHERE host_session_id IS NULL` 的同义)。来源两份:会话索引
+     * (自 [ref] 起每一张 put 过的卡,键 = 卡的会话)与此刻的全部待决行(更早的待决卡)。已有归属的卡不动;交回新记下的卡数(第二跑零)。
+     */
+    backfillHostSessionsM49(): Promise<number>;
     /**
      * [ref] D-D global expiry sweep — same split as the SQL twin: the deadline branch abort-expires every row
      * EXCEPT an approval-kind row whose gate core reads as facet `A` (those get the graceful resolve-DENY via
@@ -191,11 +230,9 @@ export declare class LocalCheckpointStore {
      */
     reapExpired(cutoff: number): Promise<number>;
     /** [ref] D-D SLA deny-sweep input — pending approval-kind gates past deadline that core reads as facet `A`
-     *  (`facetOf`: a `question`-card gate is `B` and is voided by reapExpired instead; same predicate as the SQL twin). */
-    listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
-        sessionId: string;
-        scope: string;
-    }>>;
+     *  (`facetOf`: a `question`-card gate is `B` and is voided by reapExpired instead; same predicate as the SQL twin).
+     *  Same order and paging as the SQL twin: deadline, then token; `after` returns only the rows strictly after that position ([ref]). */
+    listExpiredApprovalGates(cutoff: number, limit?: number, after?: ExpiredGatePosition): Promise<ExpiredApprovalGate[]>;
     /**
      * 🔴 **写腿的形闸与 SQL 孪生逐字同一条**(codex 对抗复审 r1 [medium],验真后按类修):TS 的 `object` 说不出
      * 「序列化之后是一只 JSON 对象」—— 数组 / `Date` / `toJSON()` 返回标量或 `null` 的对象全都通得过类型面,
@@ -207,7 +244,7 @@ export declare class LocalCheckpointStore {
      * 一个 `toJSON(k){ return k === "ctx" ? null : {…} }` 的对象验的是 `{…}`、写的是 `{"ctx":null}`
      * (实测两串逐字不同)。有状态的序列化器同理。⇒ 整条记录**只序列化一次**,闸判那一串,写也写那一串。
      */
-    putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
+    putCtx(sessionId: string, ctx: SealedCheckpointCtx, claim?: CtxWriteClaim): Promise<CtxClaimPut>;
     /**
      * 🔴 **坏体 ⇒ 拒,绝不读成缺席**([ref],与 SQL 孪生同一条判据)。修前这里是
      * `catch { return null }` + `(rec.ctx as T) ?? null`,于是一个撕裂 / 手改 / 权限读不动的 ctx 文件与
@@ -224,7 +261,9 @@ export declare class LocalCheckpointStore {
      * 本孪生的栅栏是进程内形(`store-contracts.ts` `InProcessClaimFence`):判认领、刷新活性、问腿判据与本口的落盘是**同一个同步段**(原子写本就同步),
      * 中间没有让出,所以认领在写落定之前挪不动。只改既有档(档不在 ⇒ `context_absent`,不建档);形闸同 {@link LocalCheckpointStore.putCtx},在栅栏之前判。
      */
-    rewriteCtxWhileClaimed(sessionId: string, taskId: string, ctx: SealedCheckpointCtx, legHolds: (run: FencedRun) => boolean): Promise<CtxClaimRewrite>;
+    rewriteCtxWhileClaimed(sessionId: string, ctx: SealedCheckpointCtx, claim: CtxWriteClaim): Promise<CtxClaimRewrite>;
+    /** 两只 ctx 栅栏写(`putCtx` 交认领的那一形 / `rewriteCtxWhileClaimed`)共用的栅栏例程(SQL 孪生同名例程的进程内形):交来的栅栏是 SQL 事务形 ⇒ 响亮抛(装配缺陷);形闸在栅栏之前;判认领、问腿判据、落盘同一个同步段。 */
+    private writeCtxWhileClaimed;
     /**
      * 🔴 **一次性迁移的 ctx 行改写店腿**(local 孪生;`checkpoint-store-face.ts` `CheckpointCtxRowsRewriter`,判词与 SQL 孪生 `rewriteCtxRows` 逐条同):
      * 逐档读(信封经读腿**同一只**判形 —— 读不出 ⇒ 计数、跳过、**不删**),`rewrite` 交回新体 ⇒ 信封原样(`sessionId` / `updatedAt` 不动:收割按 `updatedAt` 判)