@sema-agent/server 7.134.0 → 7.136.0

package/dist/plugins/store-backend.d.ts

@@ -50,7 +50,7 @@ export type { ApprovalNonceStore } from "./approval-nonce-store.js";
  *  车3 刀 3a 起 `StoreBackend.approvalAsk()` 已在(见接口体的那条注)。 */
 export type { ApprovalAskStore, AskRow, NewAskRow, AskTransitionPatch, DecideAskInput, DecideResult, ExpireResult, BindGateInput, BatchRow, AskDecision } from "./approval-ask-store-sql.js";
 /** E6 SessionPolicyStore — core's interface, incl. its optional `deleteBySession` / `listBySession` seams (E21 purge / 2c
- *  export; core's File and InMemory stores carry both since core 7.25.0 — S-546 A7 retired the service's own in-memory
+ *  export; core's File and InMemory stores carry both since core 7.25.0 — [ref] A7 retired the service's own in-memory
  *  twin that existed only because they once did not). tidb/pg = the SQL twin; local = core's FileSessionPolicyStore
  *  (works local — rules need no cloud-only infra). The rev-line contract kit runs the SQL twin against core's InMemory
  *  as oracle (`test/helpers/session-policy-rev-line-contract.ts`). */
@@ -94,12 +94,13 @@ export type ServiceFileHistoryStore = FileHistoryStore & {
 /** SVC-2 (core CORE-7) WorkflowJournalStore — core's interface PLUS the service `deleteByRun` (GC extra). tidb/pg =
  *  durable SQL twins (cross-replica resume journal); local = the service {@link FileWorkflowJournalStore}
  *  (single-box but RESTART-durable crash-safe JSONL, replacing core's InMemory). The shared equivalence suite keeps
- *  all three byte-matched (scope guard / idempotent-per-ordinal / oversize **refusal** —— S-194 / core 7.12.0
+ *  all three byte-matched (scope guard / idempotent-per-ordinal / oversize **refusal** —— [ref] / core 7.12.0
  *  [ref] 起两臂一律抛 `workflow.journal_oversize`,判长口径归 core `assertJournalEntryFits` 单一属主). */
 export type ServiceWorkflowJournalStore = WorkflowJournalStore & {
-    /** codex R1-H2(journal 读面界):分页+单行字节门的投影读——SQL 端 LIMIT/OFFSET 定行数、LENGTH 门
-     *  定单行(超 maxResultBytes 的行 resultJson=null 只回 resultBytes,读面标 truncated)。HTTP 读面
-     *  优先走此面;缺席(旧实现/in-memory)回落全量 load(元素少的店可受)。 */
+    /** journal 读面的分页投影读:**判整份、取一页**——与 `load` 同一个判的范围(这条 journal 里任一行被 core 的判官判坏,本读就抛
+     *  `WorkflowJournalIncompatibleError`,点名按序数升序的第一条坏行;页不是判的单位),只是内存按块有界:返回 `[offset, offset+limit)` 位置上的行,
+     *  字节超 `maxResultBytes` 的行 `resultJson=null` 只回 `resultBytes`(读面标 truncated,全文不进页)。HTTP 读面优先走此面;
+     *  缺席(file / in-memory 店)回落 `load` 后在进程内切页——`load` 本身就整份判,两条路同答。 */
     loadPage?(runId: string, scope: string, opts: {
         offset: number;
         limit: number;
@@ -140,11 +141,11 @@ export type BreakerStateStore = TiDBBreakerState | PgBreakerState;
 export type CostQuotaStore = TiDBCostQuota | PgCostQuota;
 export type RateLimiterStore = TiDBRateLimiter | PgRateLimiter;
 /**
- * S-215 —— capture opt-out **记录载体的按平面取用座**。形与 core 的
+ * [ref] —— capture opt-out **记录载体的按平面取用座**。形与 core 的
  * `RunnerDeps.memoryCaptureRecordStore`(`(plane: { controlDir }) => SessionCaptureRecordStore`)同构,
  * 多一个**不指名平面**的缺省臂:`src()` = 「本部署记忆引擎自己那一只平面」。
  *
- * 🔴 为什么是工厂而不是一只实例(S-215 codex r1 [high] 验真后改形):core 的记忆平面**不止一个**
+ * 🔴 为什么是工厂而不是一只实例([ref] codex r1 [high] 验真后改形):core 的记忆平面**不止一个**
  * (`prepare-memory.js` 的 personal 平面自带 `derivePersonalControlDir(engineRoot)`,与 project 平面的
  * controlDir 不是同一只)。返回单只实例 ⇒ server 把所有平面折到一只目录上,于是升级前落在 personal
  * 控制面的旧 opt-out 记录在升级后读作**缺席**=采集恢复(隐私面的静默 fail-open)。按平面取用后,
@@ -173,7 +174,7 @@ export interface StoreBackend {
     /** Per-session per-toolName approval exemption ("本会话不再询问") — an approval MEMORY the F4
      *  ask-gate consults after deny/neverAuto. REQUIRED on all backends (works local, like resumeAnchor). */
     approvalExemption(): ApprovalExemptionStore;
-    /** S-280 直连门审批证明的一次性消费记录(`plan_review` 的 nonce)。REQUIRED on all backends —— 与
+    /** [ref] 直连门审批证明的一次性消费记录(`plan_review` 的 nonce)。REQUIRED on all backends —— 与
      *  `approvalExemption` 同姿势:tidb/pg = SQL 双方言(单类双语句),local = File 追加日志 + 压实。
      *  **不能**退化成进程内易失形:一次重启若把记录抹掉,JWT TTL 窗内的重放就复活了,而那正是本店要关的洞。 */
     approvalNonce(): ApprovalNonceStore;
@@ -185,7 +186,7 @@ export interface StoreBackend {
     /** [ref]([ref] §3.0-§3.2)流内审批协议持久层:每个流内工具调用一行的 ask 状态机 + 批行。
      *  REQUIRED **且持久** on all backends — tidb/pg = SQL 双方言 twin;local = {@link FileApprovalAskStore}。
      *
-     *  🔴 **「持久」是本口的契约,不是某条腿的巧合**(S-384):`resolveStreamApprovalGate` 自此**不再**
+     *  🔴 **「持久」是本口的契约,不是某条腿的巧合**([ref]):`resolveStreamApprovalGate` 自此**不再**
      *  单独判一次 ask 账的持久性 —— 那条合取项(旧 `volatile_ask_ledger`)存在的唯一理由是 local 车道
      *  当年交的是 `InMemoryApprovalAskStore`(两个进程内 Map ⇒ 重启同时丢重放基准、丢已接受的决议;
      *  「一次真实的人类批准凭空消失」与「对账便利丢失」不是一个量级)。File 形落地后三条腿全是持久店,
@@ -220,12 +221,12 @@ export interface StoreBackend {
     /** SendUserFile scope↔object ledger (multi-tenant list/revoke handle; the hashed key segment hides the
      *  mapping from URLs). REQUIRED on all backends (works local — one JSONL, like approvalExemption). */
     sendFileLedger(): SendFileLedger;
-    /** S-928 用户输入受理账本的存储孪生(「200 applied」受理的影子;语义属主 `src/user-input-ledger.ts`)。REQUIRED on all backends ——
+    /** [ref] 用户输入受理账本的存储孪生(「200 applied」受理的影子;语义属主 `src/user-input-ledger.ts`)。REQUIRED on all backends ——
      *  local = File(数据根下 `user-input-ledger/ledger.jsonl`,singleton:追加 fd 与内存折叠都在实例里),SQL = 表 `user_input_acceptance`。 */
     userInputLedger(): UserInputLedgerStore;
     /** E6 durable SessionPolicyStore (operator-tightened per-session tool rules). REQUIRED on all backends — works local
      *  (local = core's FileSessionPolicyStore), like resumeAnchor. Backs core's RunnerDeps.sessionPolicyStore.
-     *  `logger`:SQL 孪生抹除封键那一臂(S-891)的点名口(缺席 ⇒ 店退回 `console.warn`);local(core 的 File 店)不收。 */
+     *  `logger`:SQL 孪生抹除封键那一臂([ref])的点名口(缺席 ⇒ 店退回 `console.warn`);local(core 的 File 店)不收。 */
     sessionPolicy(logger?: SessionPolicyStoreLogger): ServiceSessionPolicyStore;
     /** [ref] per-edited-file rewind FileHistoryStore (trackEdit/annulTrack/snapshot/restore over the tracked set;
      *  also the 2c history-transfer store). REQUIRED on all backends (local = core's file-backed
@@ -243,14 +244,14 @@ export interface StoreBackend {
      *  「没有行 ⇒ 代码缺省 allow」—— 那是**放宽面**上的静默降级(permissionRule 那条禁令的同一理由)。
      *  File 形候真实的 local+governed 部署需求出现再落(候需求档)。 */
     memoryOptOutGrant(): MemoryOptOutGrantStore | undefined;
-    /** [ref]②([ref] §2.1b,core 7.0.2 [ref] 件2)/ S-215:会话 capture opt-out **记录**的载体 ——
+    /** [ref]②([ref] §2.1b,core 7.0.2 [ref] 件2)/ [ref]:会话 capture opt-out **记录**的载体 ——
      *  core `RunnerDeps.memoryCaptureRecordStore` / `MemoryEngineOptions.captureRecordStore` 的持久层。
      *  与 §3.1 的**授权表**不是一个轴:那张管「谁**可以** opt-out」(operator 写的 verdict),这张管
      *  「谁**已经** opt-out」(用户写的一次性单向记录)。
      *
      *  返回的是**按平面取用的源**({@link SessionCaptureRecordSource}),不是一只实例 —— core 的记忆平面
      *  不止一只,折平会挪动旧记录的地址(理由全文见该类型的头注)。
-     *  载体按车道分形,但**三条车道都供**(S-215 起):SQL 两支 = 双方言 twin(`session_capture_optout`,
+     *  载体按车道分形,但**三条车道都供**([ref] 起):SQL 两支 = 双方言 twin(`session_capture_optout`,
      *  Promise 形三腿,池即依托 ⇒ 无条件供,`plane` 刻意忽略);`local` = core 的控制面文件三腿
      *  `fileSessionCaptureRecordStore(controlDir)` 按平面现造,依托是**记忆引擎的控制面目录** ⇒ 记忆面暗的
      *  部署上该平面不存在,于是这一支**随引擎接线门缺席**(唯一的 `undefined` 成因,逐字理由见 LocalBackend 的实装注)。
@@ -259,7 +260,7 @@ export interface StoreBackend {
      *  确实就是文件三腿)、在**接线层面**是假的:core 的 `captureCarrierUnsupported`
      *  (core 7.13.0 `prepare-task.js`)判的是「这个席位在不在」而不是「文件形能不能用」,叠上
      *  `isRemoteExecutionEnv` 的接口形鸭子判(`remote-env.js`)把本仓 host lane 一并算作 remote,
-     *  于是单机默认部署上 `memoryCapture:"off"` 两条 ingress 结构性不可达(B-085)。
+     *  于是单机默认部署上 `memoryCapture:"off"` 两条 ingress 结构性不可达([ref])。
      *  刻意仍不给 local 一个**内存** twin:内存形会在重启时把一条隐私记录静默丢掉(比文件三腿严格更差)。 */
     sessionCaptureRecords(): SessionCaptureRecordSource | undefined;
     /** Retired-epoch byte hygiene: GC grace-passed orphan `snapshot_blob` rows/objects — the whole-tree snapshot
@@ -301,7 +302,7 @@ export interface StoreBackend {
     /** 1.108 review fix (lens③ HIGH): the notify-JOURNAL twin — third leg of the same axis (a SQL run store +
      *  inbox with a replica-LOCAL File journal stranded a dead replica's un-acked notify forever). */
     notifyJournal?(): import("../orchestration/workflow-notify-journal.js").WorkflowNotifyJournalStore;
-    /** S-185 车CM:workflow 出身 park 的**有界 join** 索引(子会话 id → 它所属的 workflow run)。
+    /** [ref] 车CM:workflow 出身 park 的**有界 join** 索引(子会话 id → 它所属的 workflow run)。
      *  与 `workflowRun`/`completionInbox`/`notifyJournal` 同一条轴 —— SQL 后端 = 跨副本双生;`local` 车道
      *  缺席**是一个真答案**:那里的索引家在 run 店同一间屋子里(`LocalWorkflowAgentSessionIndex`,文件账本
      *  或纯内存),不需要经过 backend。契约与单写者纪律的属主 = orchestration/workflow-agent-session-index.ts。 */
@@ -396,7 +397,7 @@ export interface StoreBackend {
      *  clock to expose replica clock skew (the write-behind counters bucket on LOCAL floor(now/windowMs); skew
      *  splits a fleet window into disjoint buckets = soft-limit leak). OPTIONAL: local backend omits (no fleet). */
     dbNowMs?(): Promise<number>;
-    /** S-1014(core 7.41.0 #1308):**local 后端专有**的 usage-window 账本店 = core `FileStorageBackend` 自己那一只(`usageWindowStore`)——
+    /** [ref](core 7.41.0 [ref]):**local 后端专有**的 usage-window 账本店 = core `FileStorageBackend` 自己那一只(`usageWindowStore`)——
      *  它的坏读披露座是 backend 构造时那**一只** `onCorruptRead`(core:「`FileStorageBackend` forwards its one sink」),所以坏账本拒(`usage_window.store_corrupt`,
      *  拒绝句不带盘上位置)的同时,路径进本 backend 的 `file_store_corrupt_read` 披露座(逐命中 warn)。修前 `boot/stores.ts` 在同一数据根上自己
      *  `new FileUsageWindowStore(root)` 第二只实例、不接座 ⇒ 坏值只拒不披露,运维找不到是哪只文件。SQL 后端省略(它们有自己的 usage-window 双方言店)。 */

package/dist/plugins/store-backend.js

@@ -1,5 +1,5 @@
 import { homedir } from "node:os";
-import { createCorruptReadFailOpenSeat, createDurableAbsenceSeat } from "../observability/corrupt-read-seat.js";
+import { createCorruptReadSeat, createDurableAbsenceSeat } from "../observability/corrupt-read-seat.js";
 import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
 import { AdoptionError, FileStorageBackend } from "@sema-agent/core";
@@ -272,7 +272,7 @@ class LocalBackend {
         this.sendFileLedgerStore = new FileSendFileLedger(this.fileBackend.root);
         this.userInputLedgerStore = new FileUserInputLedgerStore(this.fileBackend.root);
         this.workflowJournalStore = new FileWorkflowJournalStore(this.fileBackend.root, undefined, {
-            onCorruptRead: createCorruptReadFailOpenSeat("server.workflow-journal.corrupt-record-skipped"),
+            onCorruptRead: createCorruptReadSeat(corruptReadWarn, "workflow_journal_refused", "workflow journal = a line the engine cannot read refuses the whole load; the run cannot be listed or resumed until the file is repaired from a kept copy"),
         });
         this.outcomeSinkInst = new FileOutcomeSink(this.fileBackend.root);
         const ownControlDir = fileMemoryControlDirFor(config);
@@ -324,7 +324,7 @@ class LocalBackend {
     checkpointStoreOf() {
         return (this.checkpointStoreInst ??= new LocalCheckpointStore(this.fileBackend.root, {
             getActiveTaskId: (sessionId) => this.runStore.getActiveTaskId(sessionId),
-            ownerOf: (sessionId) => this.sessionStore.ownerOf(sessionId),
+            readSessionOwner: async (sessionId) => (await this.sessionStore.headOf(sessionId))?.owner,
         }));
     }
     checkpoint() {

package/dist/plugins/store-contracts.d.ts

@@ -9,7 +9,7 @@
  * Rules for this file:
  *  - ZERO dialect dependencies (no mysql2, no pg) — types + pure functions only. The only imports
  *    allowed are core contract types and the neutral sql-row-helpers leaf.
- *    (S-550 车③a:`mapBakeRow`/`mapImageRow`/`BAKE_SELECT_COLS` 搬回了它们**唯一**的消费者
+ *    ([ref] 车③a:`mapBakeRow`/`mapImageRow`/`BAKE_SELECT_COLS` 搬回了它们**唯一**的消费者
  *    `image-bake-store-sql.ts` / `image-index-sql.ts` —— 「两个 SQL 孪生共用」那条理由在孪生合成
  *    单文件双方言之后就不存在了,而一条 SELECT 的**列清单**必须和它的**投影铸点**、**解码点**长在
  *    同一个文件里:否则 JSON 承载列的投影门(它按「这个文件查了哪张表」定列集)对那份清单是瞎的。)
@@ -20,7 +20,7 @@
  */
 import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core";
 /**
- * **File 店族的 boot 期拒启基类**(S-384;把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
+ * **File 店族的 boot 期拒启基类**([ref];把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
  *
  * 🔴 **为什么必须是一个可判别的类型,而且必须是一个共同基类**:`openStoreBackendWithFallback` 对
  * **默认推导**的 local(`DB_BACKEND` 未设 —— 也就是绝大多数单机部署)有一条既有降级臂:mkdir / 只读盘
@@ -31,7 +31,7 @@ import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core"
  * 「DB 不可达,已退回内存」把运维支去查连通性。
  *
  * 此前这条纪律是**逐个 `if instanceof` 手工登记**的(`AdoptionError` / `RunStoreStrictHydrateError`),
- * 于是「下一只会拒启的 File 店」默认是**漏的** —— S-384 的 ask 账本拒启就这么漏了一次(替补对抗复审
+ * 于是「下一只会拒启的 File 店」默认是**漏的** —— [ref] 的 ask 账本拒启就这么漏了一次(替补对抗复审
  * F1 [high] 实测:`DB_BACKEND` 未设时坏账本 ⇒ `{backend: undefined, degraded: true}`,不是拒启)。
  * 收法:**一个基类,一条重抛**。新 File 店的拒启只要 `extends StoreBootRefusalError` 就自动落在正确的
  * 一侧;忘了继承是**可见**的(它是一个必须显式选择的父类),而忘了往 if 链里加一行是不可见的。
@@ -97,7 +97,7 @@ export interface RunCancelContext {
     elapsedMs?: number;
 }
 /**
- * 🔴 S-947(cli [ref] 第 3 件 / L-212)—— **server 为什么中止了这条 run**:取消终局的机读成因,闭集。
+ * 🔴 [ref](cli [ref] 第 3 件 / [ref])—— **server 为什么中止了这条 run**:取消终局的机读成因,闭集。
  *
  * 病:非 detach 流断连、`POST /v1/runs/:id/cancel`、断连时有 ask 但 park 宽限用尽 —— 三件事在终局上**逐字同形**
  * (`failed` + `terminal.code:"cancelled"`),壳只能按 `errorMessage` 文案猜。
@@ -109,7 +109,7 @@ export interface RunCancelContext {
  *  · `cancel_verb`              —— `POST /v1/runs/:id/cancel`:同副本快路、跨副本耐久取消旗的轮询(四条腿的心跳 / 登记追平),
  *                                  以及 park 中的 run 被它直接终局化(那一形不经 abort,成因照样是这条动词)。
  * **刻意不在表里**(普查过、没有真站点):抢占(`preempt` 是优雅让出,终局是 `paused`,不是取消)、有序关停
- * (S-929 只把未决卡转 park,从不中止活 run;进程退出后的行由收割器落「持有者死亡」判决,那不是本仓铸的取消终局)、
+ * ([ref] 只把未决卡转 park,从不中止活 run;进程退出后的行由收割器落「持有者死亡」判决,那不是本仓铸的取消终局)、
  * `interrupt`(引擎的 turn 动词,终局 `completed` + `haltedByUser`)、detach 断连(不中止)。
  *
  * 词表属主 = 本文件(与它所在的 {@link PersistedTaskResult} 同住);**单写者** = `run-cancel-context.ts` 的 `createRunAbort`
@@ -123,7 +123,7 @@ export type AbortCause = (typeof ABORT_CAUSES)[number];
  * 本型是这一族键的**唯一登记处**(`trace/core-keyset-guard.ts` 的辖域线指向这里;那边另有一道编译期钉:
  * core 的 `TaskResult` 哪天长出同名键 ⇒ 当场红 —— 同一个键两个铸者是本型存在要防的那件事)。
  *  · `cancelContext`([ref])—— 取消现场快照(分诊材料:多久没动静、起跑多久);
- *  · `abortCause`(S-947)—— 这次取消是谁 / 什么发起的({@link AbortCause})。
+ *  · `abortCause`([ref])—— 这次取消是谁 / 什么发起的({@link AbortCause})。
  * 两键**同一只铸点**(`mintCancelledResult`)、**同一条在场闸**(「只补空座」:终局就是被那次中止打断的那一条,
  * 才挂;与中止赛跑跑完的终局、引擎自带码的失败一律原样立住、两键都不挂)。差别只在缺席纪律:快照一键都证不出 ⇒ 整只缺席;
  * 成因在铸点那一刻恒已知 ⇒ 取消终局上恒在场。
@@ -141,14 +141,14 @@ export interface PersistedResultSideKeys {
  */
 export type PersistedTaskResult = TaskResult & PersistedResultSideKeys;
 /**
- * 🔴 run 店「持有它的实例丢了」那一判的**行上落款**(S-928 codex r1-F1 提为常量):三只 run 店的 `reapStale` 把心跳过期的 running 行翻成
+ * 🔴 run 店「持有它的实例丢了」那一判的**行上落款**([ref] codex r1-F1 提为常量):三只 run 店的 `reapStale` 把心跳过期的 running 行翻成
  * `failed` 并写下这一句。它是 run 店死亡判决留在行上的证据之一(另一只 = {@link RUN_ORPHANED_ERROR})—— 用户输入受理账本的收敛判词
- * (S-969 L8 起两车道同一只)据 {@link isHolderDeathVerdict} 在 reap **之后**仍能判出「写者死了」—— 7.116.0 起判据是同行的机读码 `run.stalled`({@link RUN_HOLDER_DEATH_CODES}),本句只给人读;三个写者同写句子与码。读时折叠成同一句话的 wire 展示站点
+ * ([ref] L8 起两车道同一只)据 {@link isHolderDeathVerdict} 在 reap **之后**仍能判出「写者死了」—— 7.116.0 起判据是同行的机读码 `run.stalled`({@link RUN_HOLDER_DEATH_CODES}),本句只给人读;三个写者同写句子与码。读时折叠成同一句话的 wire 展示站点
  * (`routes/runs.ts` 的 stale 折叠、`routes/trace-usage.ts` 的 WORKER_DOWN 帧)刻意留字面量:它们由文案冻结门逐字钉着,且不参与任何判据。
  */
 export declare const RUN_STALLED_ERROR = "run stalled (instance lost?)";
 /**
- * 🔴 File 车道「持有它的进程随重启没了」那一判的行上落款(S-969 L8 提为常量):boot 孤儿回收(`FileRunStore.reclaimOrphanedAtBoot`,
+ * 🔴 File 车道「持有它的进程随重启没了」那一判的行上落款([ref] L8 提为常量):boot 孤儿回收(`FileRunStore.reclaimOrphanedAtBoot`,
  * 数据根 LOCK 作证前世进程已死 ⇒ 仍 running 的行无条件判孤儿)与运行期 claim 接管的 running 臂(`judgeClaim`,外来 + owner 已死 + 无可续)
  * 都写这一句;接管臂在括号里附上前任持有者的进程指纹(取证用,形 = {@link buildRunOrphanedError})。与 {@link RUN_STALLED_ERROR} 同一种身份:
  * run 店写在行上的**死亡判决**,读者 = {@link isHolderDeathVerdict}(按同行的机读码 `run.orphaned` 判,本句只给人读)。
@@ -220,7 +220,7 @@ export interface RunRecord {
      *  MY replica" (consult the in-process inflight/steerable map authoritatively) from "held elsewhere" (fall
      *  back to the durable cross-replica flag). null for pre-column rows. */
     instanceId: string | null;
-    /** 🔴 S-230 P-45 —— 这条 run 上**挂没挂着取消请求**(耐久 `cancel_requested` 列的投影,跨副本)。
+    /** 🔴 [ref] P-45 —— 这条 run 上**挂没挂着取消请求**(耐久 `cancel_requested` 列的投影,跨副本)。
      *
      *  语义就是那一列的字节:`POST /v1/runs/:id/cancel` 的 running 臂 CAS 成功即置位,持有副本的心跳拍
      *  poll 到它就 abort;`markResuming`(续跑认领)把它清零 —— 一次撞上 suspend 的取消不许在恢复之后
@@ -325,7 +325,7 @@ export interface InProcessClaimFence {
  *    治理判决:门拒绝那条腿在 core 里走 `paused`/`failed`,永远不铸这个词;
  *  · `parked` —— 停在门上还能再动(`suspended` 审批/资源门、`needs_review` 评审门)。
  *
- * 🔴 为什么是**一张表**而不是三张 switch(S-213③,2026-09-11):`blocked` 这个词此前在本仓有**两个
+ * 🔴 为什么是**一张表**而不是三张 switch([ref]③,2026-09-11):`blocked` 这个词此前在本仓有**两个
  * 独立写者**且答案互斥 —— `observability/run-terminal.ts` 判它是「治理判决,不是失败 ⇒ 不打行」,
  * `fleet/fleet-bus.ts` 判它是「非成功终局(agent 放弃)⇒ failed 桶、行离场」。两处各自穷举、各自正确
  * 地编译,而一条 `report_blocked` 的 run 在面板上离场、在引擎日志里一个字都没有。三张手抄的 switch
@@ -355,20 +355,20 @@ export type UnsuccessfulRunStatus = {
     [K in RunRecord["status"]]: (typeof RUN_STATUS_CLASS)[K] extends "unsuccessful" ? K : never;
 }[RunRecord["status"]];
 /** 表判为「park」(停在门上)的词 —— **从表派生**,不是手抄的第二份清单。今天 = `"suspended" | "needs_review"`。
- *  消费点(S-173:同步提交 200 体的 poll 回执 `status`,`http/sync-submit-body.ts`)拿它当型;表翻面 ⇒ 那里当场红。 */
+ *  消费点([ref]:同步提交 200 体的 poll 回执 `status`,`http/sync-submit-body.ts`)拿它当型;表翻面 ⇒ 那里当场红。 */
 export type ParkedRunStatus = {
     [K in RunRecord["status"]]: (typeof RUN_STATUS_CLASS)[K] extends "parked" ? K : never;
 }[RunRecord["status"]];
 /**
  * 一个状态词的类;**表里没有的词 ⇒ `undefined`**。
  *
- * 🔴 形参是 `string` 而不是 `RunRecord["status"]`(S-221):本函数的**全部工作**就是「这个词在不在表里」,
+ * 🔴 形参是 `string` 而不是 `RunRecord["status"]`([ref]):本函数的**全部工作**就是「这个词在不在表里」,
  * 把入参收成闭集等于在签名上宣称「传进来的一定是表内词」,而下一行的 `undefined` 臂正是为了不是的那些 ——
  * 签名与实现自相矛盾时,消费点只能靠 `as RunRecord["status"]` 硬转把窄读口(`{ status: string }`,
  * 三形 store 共同面)喂进来,而那正是本文件头注点名的 `rowToRun` 裸 cast 的同一条病。闭集词照样能传
  * (联合 ⊂ string),编译期的执法点在上面那张表的双向钉,不在这里。
  *
- * 导出面(S-221):`plugins/e2b-orphan-reclaim.ts` 的三臂判决(还能再动 / 终局 / 读不懂)需要的正是
+ * 导出面([ref]):`plugins/e2b-orphan-reclaim.ts` 的三臂判决(还能再动 / 终局 / 读不懂)需要的正是
  * 「类 + unknown」这一对,而不是三条 boolean 谓词各问一遍 —— 它此前因此自带了第二份词表。
  *
  * 🔴 查的是 **null 原型**的那只表,不是 `RUN_STATUS_CLASS` 本身(codex 对抗复审 r1 [high],亲验后修):
@@ -395,7 +395,7 @@ export declare function runStatusClassOf(status: string): RunStatusClass | undef
  */
 export declare function isTerminalRunStatus(status: RunRecord["status"]): boolean;
 /**
- * 「这一行的终局是**非成功**的吗」(S-213③ 的共享判据)——`failed` 与 `blocked` 两词。
+ * 「这一行的终局是**非成功**的吗」([ref]③ 的共享判据)——`failed` 与 `blocked` 两词。
  *
  * 🔴 它回答的问题与 {@link isTerminalRunStatus} **不同**:后者只问「还会不会再动」,本判据问「这次任务
  * 到底成没成」。凡是「这条 run 该不该在失败面上出声/离场」的判断都读这一条,不许再手抄
@@ -434,7 +434,7 @@ export declare function isParkedRunStatus(status: RunRecord["status"]): boolean;
  *    它不是「我知道它闲着」,所以不许铸出 `idle` 这个断言;
  *  · 读不懂的词(滚动升级里新副本写入的新状态词经裸 cast 读到本进程)同判 —— 与
  *    {@link isTerminalRunStatus} 族的保守方向一致。
- *  · **缺席怎么渲染是 core 的辖域,本仓一个字都不复述**(S-514-JU:此处原写着「core 对缺席渲染成 `idle`」
+ *  · **缺席怎么渲染是 core 的辖域,本仓一个字都不复述**([ref]-JU:此处原写着「core 对缺席渲染成 `idle`」
  *    并抄了当时 `list-agents-tool.js` 的旧三元 —— core 7.24.0 [ref] 把那一臂改成了一张 own-key 表 +
  *    `unknown` 兜底,于是那句复述当天就成了假话,而它在本仓被抄了六处)。本表只负责**铸不铸键**;
  *    渲染词由**跑真 core 的黑盒**钉住(`test/peer-lane-e2e.test.ts` 的 G1 格),core 哪天再改那张表,
@@ -453,7 +453,7 @@ export declare const SESSION_TEMPO_BY_RUN_CLASS: {
  *  返回词缺席 ⇒ 调用方**不铸键**(不是铸 `idle`),理由逐字见上表头注。 */
 export declare function sessionTempoOfRunStatus(lastStatus: string): PeerSessionTempo | undefined;
 /**
- * 「**证得出**这条 run 活在别的副本上」——「他副本」那一句话的**唯一判据**(S-381 收编;S-430 迁居)。
+ * 「**证得出**这条 run 活在别的副本上」——「他副本」那一句话的**唯一判据**([ref] 收编;[ref] 迁居)。
  *
  * 成案:这个合取式此前在四处**逐字手抄**(`http/routes/runs.ts` 的 steer 臂与 interrupt 臂、同文件
  * `sendHandleMiss`、`http/routes/run-memory-capture.ts`),`POST /v1/sessions/:id/mcp/reconnect` 是第五处、`fleet/fleet-reconciler.ts` 是第六处 ——
@@ -466,7 +466,7 @@ export declare function sessionTempoOfRunStatus(lastStatus: string): PeerSession
  * `sendHandleMiss` 只对 `running` 行说这句话,而 steer 族在 park/终态两臂之后才走到这里 —— 各调用点
  * 的前置臂不同族,合进来会让某一处悄悄改判。
  *
- * 🔴 **为什么住在这里而不是 `http/route-ctx.ts`**(S-430):`src/fleet/fleet-reconciler.ts` 是第六个手抄点,
+ * 🔴 **为什么住在这里而不是 `http/route-ctx.ts`**([ref]):`src/fleet/fleet-reconciler.ts` 是第六个手抄点,
  * 而 `src/fleet/` 今天对 `src/http/` **零依赖**(边向恒是 http → fleet)。把消费方拉去 http 取一只纯谓词
  * 会凭空造一条反向装载边;而本文件正是 {@link RunRecord} 与它的兄弟谓词({@link isTerminalRunStatus} /
  * {@link isParkedRunStatus})的所在 —— 「关于 run 行的判词」本来就该在行的属主这里,http 与 fleet 都已经
@@ -492,7 +492,7 @@ export interface SessionSummary {
      *  hop (`GET /v1/runs/:lastRunId/events`) when resuming a picked session, instead of a second lookup. */
     lastRunId: string | null;
     /** [ref]([ref]/[ref]):latest run 的 engine runId(`TaskResult.runId`,latest.result JSON 提取的
-     *  零迁移路线 —— result 在终局与 park 时写、认领续跑即清空(S-173)⇒ 在跑 run 键诚实缺席);OMIT-when-absent,恒不铸 null。轴辨析与
+     *  零迁移路线 —— result 在终局与 park 时写、认领续跑即清空([ref])⇒ 在跑 run 键诚实缺席);OMIT-when-absent,恒不铸 null。轴辨析与
      *  wire 半场见 `security.ts SessionListItem.lastTaskRunId`(同名同义)。 */
     lastTaskRunId?: string;
     /** The session's title: the user's (`patchSessionMeta`, unconditional; `null` clears it back to automatic) or the auto-titler's
@@ -504,7 +504,7 @@ export interface SessionSummary {
     pinned: boolean;
 }
 /**
- * S-1371 —— 会话**枚举面**读 run 账里「每会话的 run 投影」的窄读面:`runCount` / `lastStatus` / `lastRunId` / `lastTaskRunId` 四位,
+ * [ref] —— 会话**枚举面**读 run 账里「每会话的 run 投影」的窄读面:`runCount` / `lastStatus` / `lastRunId` / `lastTaskRunId` 四位,
  * 同一次读、同一条「最新一条」的口径。
  *
  * 为什么是 run 店自己的 `listSessions`、不另造一只读口:这四位在 SQL 双生里就是 `task_run` 的 `rn=1` JOIN(计数、最新一条的状态与 task_id、
@@ -521,7 +521,7 @@ export interface SessionRunRollupSource {
     }): Promise<ReadonlyArray<Pick<SessionSummary, "sessionId" | "runCount" | "lastStatus" | "lastRunId" | "lastTaskRunId">>>;
 }
 /**
- * S-297 —— 「这个会话**最近一条腿**是哪一条 run」的窄读面(`latestRunForSession` 的回值)。
+ * [ref] —— 「这个会话**最近一条腿**是哪一条 run」的窄读面(`latestRunForSession` 的回值)。
  *
  * 刻意**不是** {@link RunRecord}:那一形携 `result` 整只 blob,而本读面的三个消费点(run 身份 / 属主门 /
  * 排序口径的自证)一个都用不到它 —— 与 `listSessions` 只提标量 `lastTaskRunId` 而不拉 `result` 是同一条

package/dist/plugins/store-fault.d.ts

@@ -0,0 +1,4 @@
+export type StoreFaultClass = "corrupt" | "connection" | "unclassified";
+/** 判官本体。纯函数、不抛;只看被抛出的这一只对象(不沿 `cause` 链找)。 */
+export declare function storeFaultClassOf(err: unknown): StoreFaultClass;
+//# sourceMappingURL=store-fault.d.ts.map

package/dist/plugins/store-fault.js

@@ -0,0 +1,8 @@
+import { isConnectionFaultError } from "./sql-errors.js";
+import { StoreCorruptError } from "./sql-json-column.js";
+export function storeFaultClassOf(err) {
+    if (err instanceof StoreCorruptError)
+        return "corrupt";
+    return isConnectionFaultError(err) ? "connection" : "unclassified";
+}
+//# sourceMappingURL=store-fault.js.map

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

@@ -31,7 +31,7 @@ import { type IndexSpec } from "./ensure-index.js";
 /**
  * 一条附件 meta 的**形属主**(整仓唯一那份键集)。
  *
- * 🔴 为什么是一只 schema 而不只是一个 interface(S-550 车③b):SQL 车道把这些字段拆成**标量列**,
+ * 🔴 为什么是一只 schema 而不只是一个 interface([ref] 车③b):SQL 车道把这些字段拆成**标量列**,
  * 形由 DDL 管;local 车道把整条记录**序列化成一个 JSON 档**(`attachments/<id>.json`),于是它需要一个
  * 运行期的形判据 —— 而那个判据必须与这里的键集是**同一份**(第二份键集分叉的那天 = 「写得进、读不出」)。
  * 所以类型从 schema 推导({@link TaskAttachmentRecord}),两者按构造不可能漂。
@@ -126,7 +126,7 @@ export declare function materializeAttachmentsInto(env: {
     }>;
 }, store: TaskAttachmentStore, sessionId: string): Promise<number>;
 export declare function ensureTiDBTaskAttachmentSchema(pool: Pool): Promise<void>;
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgTaskAttachmentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgTaskAttachmentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const TASK_ATTACHMENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgTaskAttachmentSchema(q: PgQueryFn): Promise<void>;
 /** bytes → 4 MiB 块序列(共享切块器,两方言 + 完整性校验共用)。 */

package/dist/plugins/task-list-store-sql.d.ts

@@ -27,7 +27,7 @@ export declare const TASK_LIST_ITEM_TABLE = "task_list_item";
  */
 export declare function taskListKeyFor(sessionId: string): string;
 /**
- * `task_list_item.item_json` 的**形读者**(S-550)。
+ * `task_list_item.item_json` 的**形读者**([ref])。
  *
  * 🔴 判据刻意只到「一只 JSON 对象 + 一把串 id」为止,**不复刻 core 的 `TaskListItem` 键表**:那张表的
  * 属主在 core(`tools/task-list.d.ts`),而 core 今天没有导出验证器 —— 在这里手写一份等价 schema 就是

package/dist/plugins/tidb-pool.d.ts

@@ -63,13 +63,13 @@ export declare const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
  *  lock row — which both exhausts TiDB's "pessimistic lock retry limit" (surfacing as a thrown error) AND starves the
  *  app's OWN `SELECT … FOR UPDATE` paths (image-bake admission/lease) of pessimistic-lock budget. So we acquire
  *  NON-BLOCKING (GET_LOCK(name, 0) returns 0 immediately if held) and POLL with jittered backoff: one holder, the
- *  rest sleeping (not blocked in-DB). Polls until acquired (7.83.0: never degrades to unserialized — the S-287
+ *  rest sleeping (not blocked in-DB). Polls until acquired (7.83.0: never degrades to unserialized — the [ref]
  *  `ADD INDEX` leg is not race-safe); a connection whose probe keeps throwing surfaces as a boot failure. */
 export declare function acquireEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;
 /** Release {@link ENSURE_SCHEMA_LOCK} on `conn` (best-effort — the lock also auto-frees when the connection closes). */
 export declare function releaseEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;
 /**
- * S-287:`SCHEMA_STATEMENTS` 建的那批表**在存量库上可能缺的索引**(声明与 PG 侧逐条共用同一份 —— 见
+ * [ref]:`SCHEMA_STATEMENTS` 建的那批表**在存量库上可能缺的索引**(声明与 PG 侧逐条共用同一份 —— 见
  * `plugins/ensure-index.ts` 头注与 `plugins/schema-indexes.ts`)。
  *
  * 组合口径与 `SCHEMA_STATEMENTS` **一一对应**:凡是它建的表,索引声明就进这个数组;它不建的表

package/dist/plugins/tidb-pool.js

@@ -86,7 +86,7 @@ export const SCHEMA_STATEMENTS = [
      placed_at                   DATETIME(3)  NULL,
      -- S-790 / S-506(design/330 §2):会话化身 —— 同一个会话 id 上**这一位住客**的不透明令牌。铸点只在新建行(register /
      -- 无 id 创建 / fork / 导入新行),删除随行消失,同 id 重登记铸新的;'' = 没铸过,读口响亮拒。列定义的唯一属主 =
-     -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库由一次性迁移 M5 用同一串补列 + 回填)。
+     -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由本建表语句生成)。
      -- 不上 wire、不进模型上下文、日志只打前 8 位。
      ${SESSION_META_INCARNATION_COLUMN.tidb},
      PRIMARY KEY (session_id),
@@ -286,6 +286,13 @@ export const SCHEMA_STATEMENTS = [
      -- NULL (a PRE-MIGRATION row, or a gate carrying no kind) ⇒ the LEGACY UNIFORM expire() path: the deny split
      -- is NEW-ROWS-ONLY. See tidb-checkpoint-store.ts reapExpired / listExpiredApprovalGates.
      gate_kind    VARCHAR(32)  NULL,
+     -- approval_card(core 7.55.0 #1468 P1 阶段二):门上的卡词**照存**(core checkpointIndexFacts(cp).approvalCard:TOOL_APPROVAL_CARDS 的词,或本引擎不认的串 ——
+     -- 留着,更晚的引擎读得对);非审批门 / 无卡 / 非串 = NULL。写口与一次性迁移 M29 的存量回填同一只派生(plugins/checkpoint-index-columns.ts)。
+     -- 读者:到期 facet 的生成谓词(由 core CARD_FACET_OVERRIDES + PAUSE_REGISTRY 生成;**不存 facet 本身** —— 存一份会在 core 改表那天陈旧)、运维队列行的卡。
+     -- 本仓不发 ALTER:存量库缺这一列 ⇒ 起服列册对账拒启并给 ADD COLUMN 句(持久数据:表里是在飞的停驻,不删表重建)。
+     -- 列型 TEXT 而不是定长 VARCHAR:引擎照存集外词,长度不由本仓定(191 字的集外词照存)。TEXT 自己的容量是 65,535 **字节**(plugins/checkpoint-index-columns.ts 的
+     -- APPROVAL_CARD_COLUMN_MAX_BYTES):引擎铸的卡词是闭集短词,超出只会是手改 / 外来写者的存量行 —— M29 回填对这样的行计数 + 点名跳过,不写、不挡起服。
+     approval_card TEXT         NULL,
      -- bound_input_hash (design/80 D-1): the server-minted opaque boundInputHash, stamped at put() from
      -- pendingAction.boundInputHash, surfaced via listPending so the operator/portal can ECHO it on /decide (the
      -- D-1 TOCTOU binding guard is UNREACHABLE by the portal without it — it can then only do the unbound legacy
@@ -605,8 +612,8 @@ export const SCHEMA_STATEMENTS = [
      -- tidb-workflow-run-store.ts projects kind only when non-null and workflow-completion-inbox.ts routes
      -- kind === "task_notification" vs everything-else. Do NOT "tidy" this into NOT NULL DEFAULT.
      kind           VARCHAR(24)  NULL,
-     -- payload: bounded + redacted JSON extras (task_type / result / …) for the task_notification family.
-     -- NULL for legacy / plain workflow_complete rows.
+     -- payload: bounded + redacted JSON extras of the entry's kind. task_notification: task_type / result / …;
+     -- workflow_complete: at most {"completionId": …} (the engine's own correlation id, verbatim; NULL when the engine minted none).
      payload        TEXT         NULL,
      PRIMARY KEY (session_id, run_id),
      UNIQUE KEY uq_wfinbox_seq (seq),

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

@@ -8,9 +8,9 @@
  * on acquire (core's F1).
  *
  * Persistence only. **Tenant authorization (who may wake which session) lives in the service layer**
- * (`src/security.ts`), which uses `ownerOf` / `register` below. The store does not infer identity.
+ * (`src/security.ts`), which uses `headOf` (the one by-id read of a row) / `register` below. The store does not infer identity.
  */
-import { type AcquiredSession, type PlacedSessionRow, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
+import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type SessionFace } from "../session-incarnation.js";
@@ -45,21 +45,21 @@ export declare class TiDBSessionStore implements SessionStore {
     register(sessionId: string, owner: string | null): Promise<void>;
     /**
      * acquire 的建行(唯一一处):普通会话 ⇒ 无主(按 id 首建的既有读法);placed 会话 ⇒ 属主按委派继承律在**这一笔**里写入
-     * (S-1770:根会话的属主,根行不在取父,都不在 ⇒ 孤行哨兵 + warn;属主 = 判断时见证到的,读来源 → 判 → INSERT —— 读法与顺序只住在
+     * ([ref]:根会话的属主,根行不在取父,都不在 ⇒ 孤行哨兵 + warn;属主 = 判断时见证到的,读来源 → 判 → INSERT —— 读法与顺序只住在
      * `delegated-session-owner.ts` 的 `createPlacedSessionRow`,本店只交既有读写口,PG 孪生同调)。
      */
     private createOnAcquire;
     /**
-     * S-1770 委派继承律的**认领口**:这只会话的那一位住客(判断时读到的化身)仍是无主的 placed 行 ⇒ 写 `owner`,返回是否写成
+     * [ref] 委派继承律的**认领口**:这只会话的那一位住客(判断时读到的化身)仍是无主的 placed 行 ⇒ 写 `owner`,返回是否写成
      * (句 = `CLAIM_OWNERLESS_PLACED_SQL`,只 CAS 子行自己,与停驻挂点 / M23 同一只;规则在 `delegated-session-owner.ts`)。普通会话行不在射程(placed 判别位)。
      */
     claimOwnerless(sessionId: string, incarnation: string, owner: string): Promise<boolean>;
-    /** 若干来源行的会话面(属主 + 化身)一次读回(委派继承律的来源读;本店没有的 id 不在表里;化身经与 {@link sessionFaceOf} 同一只解码,空 ⇒ 响亮拒)。 */
+    /** 若干来源行的会话面(属主 + 化身)一次读回(委派继承律的来源读;本店没有的 id 不在表里;活住客的投影 `sessionFaceFromRow`,空化身 ⇒ 响亮拒)。 */
     private sourceFaces;
     /** The one session_meta INSERT. Existing owner is never overwritten.
      *  [ref]:`placement` 在场时与行同一条 INSERT 落六列;ON DUPLICATE 臂是 no-op ⇒ 已存在的行的元组
      *  **永不被重写**(first-write 不可变,义务 5 的写侧半场)。
-     *  S-790:化身与属主同一条 first-write 律 —— 新行铸一只(`mintSessionIncarnation`),已存在的行 no-op 臂一个字节不动。 */
+     *  [ref]:化身与属主同一条 first-write 律 —— 新行铸一只(`mintSessionIncarnation`),已存在的行 no-op 臂一个字节不动。 */
     private insertMeta;
     /**
      * [ref] 义务 6 的廉价探针 —— 一行 PK SELECT:`undefined` = 普通会话或无此行。
@@ -78,25 +78,15 @@ export declare class TiDBSessionStore implements SessionStore {
         olderThanMs?: number;
         scope?: string;
     }): Promise<PlacedSessionRow[]>;
-    /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
-    ownerOf(sessionId: string): Promise<string | null | undefined>;
-    /** S-790:属主 + 化身**一次读**(单行单 SELECT —— 两次独立读在删除 / 重登记的缝里能拼出混世代组合)。`undefined` = 无此会话;
-     *  行在而化身为空 ⇒ `SessionIncarnationMissingError`(响亮拒,判据唯一属主 `sessionFaceFromRow`)。 */
-    sessionFaceOf(sessionId: string): Promise<SessionFace | undefined>;
-    /** core `SessionStore.incarnationOf`(按 id 读住客,给没取会话的那一侧):{@link sessionFaceOf} 的化身那一半 —— 同一次读、同一只解码。 */
-    incarnationOf(sessionId: string): Promise<string | undefined>;
+    /**
+     * core `SessionStore.headOf` —— 这一行的属主、住客、叶子,**一条 PK SELECT、一行**(两次独立读在删除 / 重登记的缝里能拼出混世代组合;
+     * 单行单读天然一致)。`undefined` = 无此会话。本店按 id 问这一行的**唯一**读口:授权口的属主、parked 两读的住客、SSE 探针的叶子、
+     * resume-at 的叶子都是它的投影(此前的 `ownerOf` / `sessionFaceOf` / `incarnationOf` / `getLeafId` / `getHead` 五只读全部并进来;规则见
+     * `session-incarnation.ts` 头注)。化身那一格经 `headFromRow` 的 `absent` 读法(空 ⇒ 住客未知);要一位活住客的读者经 `sessionFaceOfHead` 响亮拒空。
+     * 只读、不取会话、不上锁、绕过暖缓存 —— 跑到一半读也安全(写的安全是追加时的 CAS)。
+     */
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
     touch(sessionId: string): Promise<void>;
-    /** E18 — the session's current leaf `SessionTreeEntry.id` (`session_meta.leaf_id`, set transactionally on every
-     *  persist). A single SELECT, NO acquire/lock/CAS — safe to call mid-run (write-safety is the append-time CAS, not
-     *  an acquire lease) and cache-bypassing (the resume-at turn-capture reads it without touching the warm session).
-     *  Returns the leaf id, or null when the session has none / no such session. */
-    getLeafId(sessionId: string): Promise<string | null>;
-    /** [ref] 六轮复审:owner+leafId **单行原子快照**(SSE watch 探针的租户围栏读)——两独立 SELECT 在
-     *  delete/reclaim 缝里可拼出「旧 owner+新 leaf」混世代组合;单 SELECT 单行=天然一致。undefined=无此会话。 */
-    getHead(sessionId: string): Promise<{
-        owner: string | null;
-        leafId: string | null;
-    } | undefined>;
     /**
      * Durable history is retained; just drop any in-flight cache entry.
      *
@@ -164,12 +154,12 @@ export declare class TiDBSessionStore implements SessionStore {
      *  writer order: `src/session-row.ts`). Returns whether this call set it. */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
     /**
-     * S-690 —— 换源通告的基线读(一行 PK SELECT;列的三态读法见 `tidb-pool.ts` 的列注)。行不在 ⇒ 读作「没记过」
+     * [ref] —— 换源通告的基线读(一行 PK SELECT;列的三态读法见 `tidb-pool.ts` 的列注)。行不在 ⇒ 读作「没记过」
      * (loader 跑在 acquire 之后,行恒在;不在 = 被带外删了,没有下一 run 可比)。
      */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**
-     * S-690 —— CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。
+     * [ref] —— CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。
      * **不**碰 `updated_at`(那是会话活动时刻,留存腿按它判龄;记基线不是一次会话活动)。
      * 两条基线查询都带每查询超时(`BASELINE_IO_DEADLINE_MS`,mysql2 的 `{sql, timeout}` 形):被行锁卡住的写由查询自己
      * 在期限内拒。⚠️ mysql2 的超时是客户端侧的 —— 拒之后那条连接仍被挂着的命令占到服务端结束(S-9 同形,如实披露)。

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

@@ -5,13 +5,14 @@ import { jsonColumnText } from "./sql-json-column.js";
 import { escapeLike } from "./sql-escape.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
-import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { carriedIncarnation, headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
 import { createLogger } from "../observability/logger.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
+import { forkCopyOf, forkPointOf } from "./session-fork.js";
 export class TiDBSessionStore {
     pool;
     retention = MANAGED_RETENTION;
@@ -58,7 +59,7 @@ export class TiDBSessionStore {
     }
     async register(sessionId, owner) {
         if (typeof owner !== "string" && owner !== null) {
-            if ((await this.ownerOf(sessionId)) !== undefined)
+            if ((await this.headOf(sessionId)) !== undefined)
                 return;
             assertFirstOwnerWritable(sessionId, owner);
         }
@@ -70,7 +71,7 @@ export class TiDBSessionStore {
         await createPlacedSessionRow(sessionId, placement, {
             readFaces: (ids) => this.sourceFaces(ids),
             insert: (owner) => this.insertMeta(sessionId, owner, placement),
-            readOwner: () => this.ownerOf(sessionId),
+            readOwner: async () => (await this.headOf(sessionId))?.owner,
         }, this.log);
     }
     async claimOwnerless(sessionId, incarnation, owner) {
@@ -107,20 +108,12 @@ export class TiDBSessionStore {
         const [rows] = await this.pool.query(sql, params);
         return rows.map((r) => placedRowFromRow(String(r.session_id), r, r.updated_at instanceof Date ? r.updated_at.getTime() : undefined));
     }
-    async ownerOf(sessionId) {
-        const [rows] = await this.pool.query("SELECT owner FROM session_meta WHERE session_id = ?", [sessionId]);
+    async headOf(sessionId) {
+        const [rows] = await this.pool.query("SELECT owner, incarnation, leaf_id FROM session_meta WHERE session_id = ?", [sessionId]);
         if (rows.length === 0)
             return undefined;
-        return rows[0].owner ?? null;
-    }
-    async sessionFaceOf(sessionId) {
-        const [rows] = await this.pool.query("SELECT owner, incarnation FROM session_meta WHERE session_id = ?", [sessionId]);
-        if (rows.length === 0)
-            return undefined;
-        return sessionFaceFromRow(sessionId, rows[0].owner ?? null, rows[0].incarnation);
-    }
-    async incarnationOf(sessionId) {
-        return (await this.sessionFaceOf(sessionId))?.incarnation;
+        const r = rows[0];
+        return headFromRow(sessionId, r.owner ?? null, r.incarnation, r.leaf_id ?? null);
     }
     async touch(sessionId) {
         await this.pool.query("UPDATE session_meta SET updated_at = ? WHERE session_id = ?", [
@@ -128,16 +121,6 @@ export class TiDBSessionStore {
             sessionId,
         ]);
     }
-    async getLeafId(sessionId) {
-        const [rows] = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = ?", [sessionId]);
-        return rows[0] ? (rows[0].leaf_id ?? null) : null;
-    }
-    async getHead(sessionId) {
-        const [rows] = await this.pool.query("SELECT owner, leaf_id FROM session_meta WHERE session_id = ?", [sessionId]);
-        if (rows.length === 0)
-            return undefined;
-        return { owner: rows[0].owner ?? null, leafId: rows[0].leaf_id ?? null };
-    }
     async release(sessionId) {
         this.pending.delete(sessionId);
         const placed = await this.placementOf(sessionId);
@@ -270,7 +253,12 @@ export class TiDBSessionStore {
             return null;
         const leafId = metaRows[0].leaf_id ?? null;
         const forkOwner = forkOwnerOf(owner, metaRows[0].owner ?? null) ?? null;
-        const [eventRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("tidb", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
+        const storage = await TiDBSessionStorage.wake(this.pool, sourceId);
+        if (storage === null)
+            return null;
+        const point = await forkPointOf(storage);
+        const [allRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("tidb", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
+        const { rows: eventRows, leafId: forkLeafId } = forkCopyOf(allRows, leafId, point);
         const newId = uuidv7();
         const now = new Date();
         const conn = await this.pool.getConnection();
@@ -281,7 +269,7 @@ export class TiDBSessionStore {
                 const payload = String(r.payload);
                 await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
             }
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?)", [newId, forkOwner, now, now, leafId, eventRows.length, mintSessionIncarnation()]);
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?)", [newId, forkOwner, now, now, forkLeafId, eventRows.length, mintSessionIncarnation()]);
             await conn.commit();
             return newId;
         }