@sema-agent/server 7.133.0 → 7.135.0

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

@@ -1,10 +1,10 @@
-import { FileSessionRepo, type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
+import { FileSessionRepo, type AcquiredSession, type SessionHead, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionRunRollupSource, SessionSummary } from "./store-contracts.js";
 import type { SessionRowPatch } from "../session-row.js";
 import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
-import { type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
+import { type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 /**
  * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座与会话视图口
  * 窗口 `local-session-window.ts#LocalSessionWindow.wake` 的读旁路),所以坏记录的披露座只有这一份接线 —— 修前视图口自建一只不带座的 repo,同一份坏档在这里读到有计数 / 探针,
@@ -13,6 +13,8 @@ import { type StagingHandle, type SyncRelation } from "../session-sync-kernel.js
  * 的作用域里才记,作用域外 —— 列表 / 导出 / 视图口 —— 是空操作,那些读只进运维面)。
  */
 export declare function createLocalSessionRepo(root: string): FileSessionRepo;
+/** 本店包的 repo:core `SessionRepo` 且答头读(`headOf` —— 叶子出自它;core 7.55.0 起 `FileSessionRepo` / `InMemorySessionRepo` 都答)。 */
+export type HeadReadingSessionRepo = SessionRepo & Required<Pick<SessionRepo, "headOf">>;
 export declare class LocalSessionStore implements SessionStore {
     private readonly repo;
     private readonly runs;
@@ -58,14 +60,14 @@ export declare class LocalSessionStore implements SessionStore {
     /** Pin map (`session-pinned.json`, {@link readPinnedSidecar}) — the local twin of `session_meta.pinned`. Its own file for
      *  the same reason titles have theirs (one small map per concern, no format coupling); absent key = not pinned. */
     private readonly pinned;
-    /** S-690 — instruction-source baselines (`session-instruction-sources.json`): the chain member the session's previous
+    /** [ref] — instruction-source baselines (`session-instruction-sources.json`): the chain member the session's previous
      *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
      *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
     private readonly instructionSources;
     /**
      * 会话元数据(`session-incarnations.json`,一格的形与两种读法见 {@link SessionMetaCell}):**属主与化身的唯一真源**,SQL 孪生
      * `session_meta` 行上 `owner` / `incarnation` 两列在本店的对位。两样都**必须落盘**:
-     *  · 化身(S-790 / S-506,[ref] §2)的口径是「一位住客一生稳定」,记忆引擎按它绑定会话级记录(opt-out / 污染标记)——
+     *  · 化身([ref] / [ref],[ref] §2)的口径是「一位住客一生稳定」,记忆引擎按它绑定会话级记录(opt-out / 污染标记)——
      *    重启后换一只值 = 同一位住客的 opt-out 不再绑它 = 静默恢复采集;
      *  · 属主(7.119.0)是会话策略规则的存储键:规则按「会话 × 属主」存、按 run 的 principal 读 —— 重启后属主丢了,规则照样在跑,
      *    属主自己却读不到也删不掉(`409 conflict.session_ownerless`)。7.118.x 及更早属主只活在一只进程内存 Map 里,就是这个病。
@@ -91,7 +93,7 @@ export declare class LocalSessionStore implements SessionStore {
      *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives).
      *  @param opts.log the `session_owner_claimed` line's sink (LocalBackend passes a logger at the deployment's LOG_LEVEL;
      *                  absent ⇒ an info-level JSON-line logger — a claim is never silent). */
-    constructor(repo: SessionRepo, runs: SessionRunRollupSource, dataDir?: string, opts?: {
+    constructor(repo: HeadReadingSessionRepo, runs: SessionRunRollupSource, dataDir?: string, opts?: {
         log?: Pick<Logger, "info">;
     });
     /**
@@ -111,7 +113,7 @@ export declare class LocalSessionStore implements SessionStore {
     /** 盘上有没有这只会话(repo 的唯一探针;`open` 读整只存档,所以只在边档里没有那一格时才走到这里)。 */
     private existsInRepo;
     /**
-     * 一只会话的元数据 —— 属主与化身的**唯一读口**(`ownerOf` / `sessionFaceOf` / `getHead` / 删除与换装的属主门都经它)。`undefined` = 无此会话。
+     * 一只会话的元数据 —— 属主与化身的**唯一读口**(按 id 读 {@link headOf} / 删除与换装的属主门都经它)。`undefined` = 无此会话。
      * 边档里有那一格 ⇒ 读它(一次同步读,两样同出一格,不会拼出混世代组合);没有那一格而盘上有会话(7.104.0 之前的会话从没被铸过化身)
      * ⇒ 补铸一格只有化身的(属主没有事实可写,不伪造)并落盘后再答 —— 之后的读都命中那一格,不再回 repo。
      */
@@ -122,13 +124,21 @@ export declare class LocalSessionStore implements SessionStore {
      * `undefined` = 补铸落盘之前那一格已被并发删除抹掉(只有锁外的 {@link metaOf} 走得到)。
      */
     private cellOfPresent;
-    /** S-790:属主 + 化身一次读(SQL 孪生同义;`undefined` = 无此会话)—— 两样出自 {@link metaOf} 读到的同一格。 */
-    sessionFaceOf(sessionId: string): Promise<SessionFace | undefined>;
-    /** core `SessionStore.incarnationOf`(按 id 读住客,给没取会话的那一侧):{@link sessionFaceOf} 的化身那一半 —— 同一格、同一次读。 */
-    incarnationOf(sessionId: string): Promise<string | undefined>;
+    /**
+     * core `SessionStore.headOf` —— 本店按 id 读一行的**唯一**读口(SQL 孪生同义;此前的 `ownerOf` / `sessionFaceOf` / `incarnationOf` / `getHead` / `getLeafId`
+     * 五只读并进来,规则见 `session-incarnation.ts` 头注)。属主与住客出自 {@link metaOf} 读到的同一格(local 后端属主 + 化身的唯一真源 —— 本店的**行**),
+     * 叶子出自会话存档(本店的**内容**;core `SessionRepo.headOf`:File repo 读日志首记录与尾、不重放 —— 存档首行的属主 / 令牌本店不读)。
+     * 存档读不出(会话头坏了、I/O 故障)⇒ 头照答行上的属主与住客,叶子那一格带着那只故障(`UnreadableLeaf`,读叶子的人收到它):只判归属的读者
+     * 不因坏存档改判,坏存档只让读内容的那一位看见(SQL 孪生的头不碰 `session_event`,同一条律;规则在 `session-incarnation.ts` 头注)。
+     * 行本身读不出(边档里还没有这一格、要从存档推出这只会话在不在,而存档读不出 —— {@link metaOf} 的探针)⇒ 整只拒。
+     * 两样住在两只文件里 ⇒ 先读那一格、读叶子、再同步复读那一格:格没了(读间被删)或换了主 / 换了住客 ⇒ `undefined`(调用方按删处理),
+     * 所以一只头从不把这一代的属主配上另一代的叶子([ref] 六轮复审同一条)。`undefined` = 无此会话。
+     * 化身那一格经 `headFromRow` 的 `absent` 读法(边档对象形恒有令牌;读不出的边档整只严格拒在 `metaOf` 之前)。
+     */
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
     /**
      * 三条 acquire 腿(无 id 建 / 按 id 打开 / 按 id 首建)交出会话的唯一一处:住客 = 这只会话那一格({@link cellOfPresent} —— 刚建或刚在写锁里
-     * 打开,就是在盘上的证明,不再回 repo 探一次),经与 {@link sessionFaceOf} 同一只解码(`sessionFaceFromRow`),挂到交出的会话上({@link occupiedBy})。
+     * 打开,就是在盘上的证明,不再回 repo 探一次),经活住客的唯一投影(`sessionFaceFromRow`)解码,挂到交出的会话上({@link occupiedBy})。
      */
     private handOut;
     /** Cheap pre-LLM probe (local twin). The map write needs no session_meta row, so there is
@@ -156,10 +166,10 @@ export declare class LocalSessionStore implements SessionStore {
     sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
     /** 会话仓里这只会话的列表元数据(列表面上的行 = `repo.list()` 里的一项)。 */
     private listedMeta;
-    /** S-690 —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
+    /** [ref] —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**
-     * S-690 —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 内存不动、抛**,与 SQL 孪生
+     * [ref] —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 内存不动、抛**,与 SQL 孪生
      * 「要么提交要么抛」同形 —— 修前写失败只 warn、内存照样前进,同来源的后续 run 在相等比较上短路、再也不重写,重启后
      * 比的是一份过期的盘,codex che-NM r1 [medium])。CAS 判定(在草稿上)、落盘、发布**整段在写链的一节里**(`commit`):下一节
      * 开始之前共享的那张表只含落过盘的值,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
@@ -199,14 +209,14 @@ export declare class LocalSessionStore implements SessionStore {
      * ENOENT(首次启动没有这份档)在调用点就被排除,压根到不了这里。
      */
     private refuseSidecar;
-    /** `which` 点名是哪一只边档(S-690 起有三只 —— 此前这句恒写 lastActivity,title 边档的失败也被报成「recency 降级」)。
+    /** `which` 点名是哪一只边档([ref] 起有三只 —— 此前这句恒写 lastActivity,title 边档的失败也被报成「recency 降级」)。
      *  节流仍是本实例一只。 */
     private warnSidecar;
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
     private load;
-    /** 为这只会话打开它自己的存档,锁内一形(调用方持这只会话的写锁,见 {@link load})。S-612:这是「为这只会话打开它自己的存档」的那一次
+    /** 为这只会话打开它自己的存档,锁内一形(调用方持这只会话的写锁,见 {@link load})。[ref]:这是「为这只会话打开它自己的存档」的那一次
      *  (引擎 prepare 的 acquire)⇒ 包在打开作用域里:这次回放跳过了记录 ⇒ 打开成功后铸一帧 `session.records_skipped` 投给这只会话(唯一铸点
      *  与作用域见 `session-records-skipped-notice.ts`);读不出(`corrupt_session`)照旧原样上抛,不铸。存档只读这一次:住客那一格缺(更早版本
      *  写下的会话)时,这次打开就是补铸的证明({@link handOut})。GUARD(open 腿):打开一只已存在的会话**不写属主** —— 记下的属主(含「登记为
@@ -216,7 +226,7 @@ export declare class LocalSessionStore implements SessionStore {
      * Idempotently record a session's owner — never overwrites a RECORDED owner (incl. a recorded `null`, "registered ownerless";
      * mirrors TiDBSessionStore.register's first-write rule). TiDB parity: register INSERTs a session_meta row so the session EXISTS
      * (forkable) even before its first acquire/run — so we also ensure an EMPTY repo session exists (open if present → never
-     * overwrite history; create if not), else `ownerOf` would say a registered-but-never-acquired session exists while `fork` 404s it.
+     * overwrite history; create if not), else `headOf` would say a registered-but-never-acquired session exists while `fork` 404s it.
      *
      * 首写判据在写链里判(两只并发登记:先落盘的那一只赢,后一只不改、也不建会话)。一只**盘上已有、属主从没被记下**的会话
      * (边档那一格只有化身 —— 7.118.x 及更早写下的,或更早到连化身都没有)是一次性迁移 M10 的对象(窗口见 `plugins/one-time-migrations.ts`
@@ -225,27 +235,12 @@ export declare class LocalSessionStore implements SessionStore {
      * `REQUIRE_PRINCIPAL=true`,授权口也只在那时才把 principal 递过来认领(`security.ts` `createAuthorizer`)。
      */
     register(sessionId: string, owner: string | null): Promise<void>;
-    /** Owner of a session: `null` if ownerless (registered ownerless, or an owner that was never recorded — a session written by
-     *  an earlier version), `undefined` if no such session (mirrors TiDBSessionStore.ownerOf). Reads {@link metaOf}: the persisted
-     *  cell, so the answer survives a restart exactly like the SQL twins' `session_meta.owner` column does. (Before 7.119.0 the
-     *  owner lived in a process-local Map and this method answered `null` for every session after a restart — the S3 fallback
-     *  "on disk ⇒ ownerless" kept the E21 delete working, but froze every owner-keyed session-policy rule.) */
-    ownerOf(sessionId: string): Promise<string | null | undefined>;
-    /** [ref] 六轮复审:owner+leafId 原子快照 —— 先读那一格,读 leaf,再同步复读那一格:格没了(读间被删)或换了主 / 换了住客 ⇒
-     *  undefined(调用方按删处理)。 */
-    getHead(sessionId: string): Promise<{
-        owner: string | null;
-        leafId: string | null;
-    } | undefined>;
     /** 2c P1d-β — re-stamp the session's owner WITHOUT rewriting entries (the staged-commit `identical` path: the log is
      *  already present & equal, so only the owner needs re-stamping to the importing principal, §9). Persisted like every
      *  owner write; the incarnation is untouched (same occupant). No cell (no such session) ⇒ no-op. Only caller:
      *  {@link commitStagedImport}, inside the session's write lock. */
     private restampOwner;
     touch(sessionId: string): Promise<void>;
-    /** E18 — the session's current leaf SessionTreeEntry.id (@see TiDBSessionStore.getLeafId). Reads the repo's storage
-     *  leaf (no acquire-lock; InMemory/File repo reads don't lock). null when the session doesn't exist / has no leaf. */
-    getLeafId(sessionId: string): Promise<string | null>;
     /** Durable history is retained by the repo; just drop the in-flight cache entry (mirrors TiDBSessionStore.release). */
     release(sessionId: string): Promise<void>;
     /**
@@ -259,7 +254,7 @@ export declare class LocalSessionStore implements SessionStore {
      *   - `firstActivityAt` — the session's `createdAt` (repo metadata).
      *   - `lastActivityAt`  — the touch marker (falls back to `createdAt`); the keyset sort key.
      *   - `objectivePreview`— the last USER-text entry, synthesized from the session tree (no run ledger).
-     *   - `runCount`/`lastStatus`/`lastRunId`/`lastTaskRunId` — S-1371:read from the run store handed in (`runs`; the TiDB
+     *   - `runCount`/`lastStatus`/`lastRunId`/`lastTaskRunId` — [ref]:read from the run store handed in (`runs`; the TiDB
      *                          twin LEFT-JOINs `task_run` for the same values, the run store's own `listSessions` is that
      *                          join's same-semantics projection — latest run by `created_at DESC, task_id DESC`, count of all,
      *                          `lastTaskRunId` = that run's `result.runId`). One call per list (not per row); a session with no
@@ -282,16 +277,16 @@ export declare class LocalSessionStore implements SessionStore {
     }): Promise<SessionSummary[]>;
     /** 列表行要读的边档一次装齐(lastActivity / 标题 / 置顶 / 会话元数据);各自记忆化,只有第一次真读盘。 */
     private loadRowSidecars;
-    /** 列表行上的属主:那一格的属主(没有格 / 属主从没被记下 ⇒ null —— 与 `ownerOf` 同答;列表不补铸缺的格,`ownerOf` / `sessionFaceOf` 在第一次读时补)。 */
+    /** 列表行上的属主:那一格的属主(没有格 / 属主从没被记下 ⇒ null —— 与 `headOf(id)?.owner` 同答;列表不补铸缺的格,`headOf` 在第一次读时补)。 */
     private ownerCellOf;
     /** 一只会话的列表行 —— {@link listSessions} 与 {@link sessionSummaryOf} 的**同一只**合成(字段来源逐位见 listSessions 的头注)。调用方先 {@link loadRowSidecars}。 */
     private summaryOf;
-    /** S-1371:run 店里每个会话的 run 投影(按 sessionId 索引)。
+    /** [ref]:run 店里每个会话的 run 投影(按 sessionId 索引)。
      *  **一次读**:run 店的 `listSessions` 本来就按会话聚合全账(无会话过滤口),这里取全量再按会话仓的 id 查表 —— 比逐会话 N 次读便宜,
      *  也不在会话店里另存一份 run 账。读失败 ⇒ 抛(不吞成 `0 / ""`:那会把「读不到」说成「没跑过」)。 */
     private runRollups;
     /**
-     * 一行里 run 身份与计数的**唯一出处**(S-1371,会话行四位一源):四位全读 {@link runRollups} 的投影(与 SQL 双生的 `task_run` rn=1 JOIN 同口径);
+     * 一行里 run 身份与计数的**唯一出处**([ref],会话行四位一源):四位全读 {@link runRollups} 的投影(与 SQL 双生的 `task_run` rn=1 JOIN 同口径);
      * 该会话没有 run 行 ⇒ `0` / `""` / `null`、`lastTaskRunId` 缺席(TiDB 的 `COALESCE(…,0)` / null→"" 映射)。在途的最新一条:`lastRunId` 在场(run 行建出来就有)、
      * `lastTaskRunId` 缺席(`result` 在终局与 park 时才写)。
      */
@@ -299,9 +294,14 @@ export declare class LocalSessionStore implements SessionStore {
     /** Synthesize a session's objective preview = the most-recent USER text message (the objective the run last saw).
      *  Reads the session's entries through the repo; any read error degrades to null (never fails the list). */
     private previewOf;
-    /** E17 — fork a session's WHOLE history to a NEW id owned by `owner` (core SessionRepo.fork). Returns the new id,
-     *  or null if the source does not exist (the route maps that to 404). */
-    fork(sourceId: string, owner: string | null): Promise<string | null>;
+    /** E17 — fork a session's WHOLE history to a NEW id (core SessionRepo.fork). Returns the new id, or null if the source does not exist.
+     *  属主按 core `SessionStore.fork` 契约(core 7.54.0 `sessionStoreContract` 的 [ownership] 格,唯一读法 {@link forkOwnerOf}):显式串 ⇒ 该串;
+     *  无参 / 显式 `null` ⇒ **源会话记下的属主**(一份有主历史的拷贝永不降成匿名 —— 匿名的拷贝谁都能认领);源会话没记属主 ⇒ 拷贝也不记(读作无主)。
+     *  修前把参数原样写进新格:`fork(owned, null)` 铸出一份匿名的有主历史。
+     *  拷**已提交**的叶(契约):在飞的 assistant 轮不进孩子 —— 分叉点只有引擎那一只判官(core 7.55.0 起包根导出的 `settledForkOptions`),本店把唤醒出来的源会话交给它、
+     *  把它的答案原样交给引擎自己的 `repo.fork`(与 core 内存店 `TtlSessionStore.fork` 同一条调用链);两只 SQL 孪生同读它(`session-fork.ts`)。钉:
+     *  core 店契约盒的 `[fork]` 格(`test/session-store-contract-kit.test.ts`)。 */
+    fork(sourceId: string, owner?: string | null): Promise<string | null>;
     /** 2c session-sync — EXPORT a session's full durable entry log (core `SessionRepo.exportEntries`; the
      *  in-memory/file repo holds the whole log so there is no floor to bypass). null if the source is unknown / the
      *  underlying repo lacks the optional seam. The owner is NOT exported — import re-stamps it. */
@@ -352,14 +352,13 @@ export declare class LocalSessionStore implements SessionStore {
     /** Drop a finished/aborted local staging handle from the registry (called by the handle on commit/abort). */
     forgetStaging(stagingId: string): void;
     /**
-     * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):提交时重新分类(目的端此刻的日志 vs staged)
+     * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):属主 CAS(此刻的属主格 = 这次导入的门判过的那一格,
+     * 否则抛 {@link StagedCommitOwnerChangedError},一个字节不写;在判目的端日志之前判,SQL 孪生同序)→ 提交时重新分类(目的端此刻的日志 vs staged)
      * → 拒未经同意的 fork / stale / 载荷分叉 → 换装(validate-first → 删 → 导入,化身按换装律沿用)或 identical 且内容相同时只重戳属主 → **在同一次持锁里**
      * 读出落定的会话面交回。锁放下之前谁也换不掉这一位住客,所以交回的面就是这次提交落下的那一位(SQL 孪生在提交事务里读同一行,同义);
-     * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。
+     * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。改属主的每一条写腿(登记 / 删除 / 导入 / 换装)都在同一把锁里,所以锁内这一读到锁放下都成立。
      */
-    commitStagedImport(sessionId: string, owner: string | null, staged: SessionTreeEntry[], opts?: {
-        resolution?: "overwrite-dst";
-    }): Promise<{
+    commitStagedImport(sessionId: string, owner: string | null, staged: SessionTreeEntry[], opts: StagedCommitOptions): Promise<{
         relation: SyncRelation["relation"];
         face: SessionFace;
     }>;
@@ -369,14 +368,14 @@ export declare class LocalSessionStore implements SessionStore {
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     /**
      * {@link deleteSession} 的锁内一形(调用方持这只会话的写锁;换装 {@link replaceEntriesHeld} 也走它)。
-     * 删的是 SQL 孪生 `session_meta` 那一行在本店的全部对位:会话存档、三只行边档(标题 / 置顶 / S-690 的指令来源基线)、属主 + 化身那一格。
+     * 删的是 SQL 孪生 `session_meta` 那一行在本店的全部对位:会话存档、三只行边档(标题 / 置顶 / [ref] 的指令来源基线)、属主 + 化身那一格。
      * 三只边档的那一键**都经各自的写链删**(`commit`:草稿上删、落盘、再发布 —— 与写它们的那一笔同一条链、同一把会话锁),落不了盘 ⇒ 抛:
      * 留在盘上的值会挂到同 id 的下一位住客身上(E21 的删除权残留)。元数据格**最后**删:三只边档任一只落不了而抛时,那一格还在 ⇒ 会话对属主门仍
      * 「在」,重发删除照样走得进来、收敛;反过来先删格,重发就成了 no-op,残留永远留下。
      * 🔴 hydrate FIRST (workflow audit 2026-07-13): after a restart the maps start empty — an un-hydrated delete would find nothing and
      * the sidecar would keep the value (an E21 right-to-delete residue that would RESURRECT onto a same-id re-import). ensureLoaded is
      * memoized — first caller pays, rest no-op.
-     * S-790:化身随那一格消失(同 id 重登记铸新的 —— 那就是下一位住客)。
+     * [ref]:化身随那一格消失(同 id 重登记铸新的 —— 那就是下一位住客)。
      */
     private deleteSessionHeld;
     get size(): number;

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

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { FileSessionRepo, SessionError, StoredSession, validateEntriesForImport } from "@sema-agent/core";
+import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
+import { FileSessionRepo, SessionError, StoredSession, settledForkOptions, validateEntriesForImport } from "@sema-agent/core";
 import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
@@ -8,12 +9,12 @@ import { createZodColumnReader, decodeJsonColumn, readStringRecordColumn, SqlJso
 import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
 import { createLogger } from "../observability/logger.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
-import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { UnreadableLeaf, carriedIncarnation, headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
 import { noteReplayInSessionOpenScope, openSessionForItself } from "../session-records-skipped-notice.js";
 import { createCorruptReadFailOpenSeat } from "../observability/corrupt-read-seat.js";
 import { buildObjectivePreview, isAttachmentFrame } from "../user-authored-text.js";
-import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, ownerCellIs, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
 const SESSION_OBJECTIVE_PREVIEW_CHARS = 200;
@@ -256,12 +257,16 @@ export class LocalSessionStore {
         const cell = this.meta.state.entries.get(sessionId);
         return cell === undefined ? undefined : readSessionMetaCell(cell);
     }
-    async sessionFaceOf(sessionId) {
-        const meta = await this.metaOf(sessionId);
-        return meta === undefined ? undefined : sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation);
-    }
-    async incarnationOf(sessionId) {
-        return (await this.sessionFaceOf(sessionId))?.incarnation;
+    async headOf(sessionId) {
+        const before = await this.metaOf(sessionId);
+        if (before === undefined)
+            return undefined;
+        const leaf = await this.repo.headOf(sessionId).then((archive) => archive?.leafId ?? null, (fault) => new UnreadableLeaf(fault));
+        const cell = this.meta.state.entries.get(sessionId);
+        const after = cell === undefined ? undefined : readSessionMetaCell(cell);
+        if (after === undefined || after.incarnation !== before.incarnation || (after.owner ?? null) !== (before.owner ?? null))
+            return undefined;
+        return headFromRow(sessionId, before.owner ?? null, before.incarnation, leaf);
     }
     async handOut(sessionId, session) {
         const meta = await this.cellOfPresent(sessionId);
@@ -459,6 +464,7 @@ export class LocalSessionStore {
             await this.meta.ensureLoaded();
             if (ownerRecorded(this.meta.state.entries.get(sessionId)))
                 return;
+            assertFirstOwnerWritable(sessionId, owner);
             const existed = await this.existsInRepo(sessionId);
             const claim = existed && owner !== null && ownerClaimWindowOpen();
             const wrote = await this.writeMeta(sessionId, (before) => {
@@ -474,21 +480,6 @@ export class LocalSessionStore {
                 this.log.info("session_owner_claimed", { sessionId });
         });
     }
-    async ownerOf(sessionId) {
-        const meta = await this.metaOf(sessionId);
-        return meta === undefined ? undefined : (meta.owner ?? null);
-    }
-    async getHead(sessionId) {
-        const before = await this.metaOf(sessionId);
-        if (before === undefined)
-            return undefined;
-        const leafId = await this.getLeafId(sessionId);
-        const cell = this.meta.state.entries.get(sessionId);
-        const after = cell === undefined ? undefined : readSessionMetaCell(cell);
-        if (after === undefined || after.incarnation !== before.incarnation || (after.owner ?? null) !== (before.owner ?? null))
-            return undefined;
-        return { owner: before.owner ?? null, leafId };
-    }
     async restampOwner(sessionId, owner) {
         await this.writeMeta(sessionId, (before) => (before === undefined ? undefined : { incarnation: readSessionMetaCell(before).incarnation, owner }));
     }
@@ -496,17 +487,6 @@ export class LocalSessionStore {
         this.lastActivity.set(sessionId, new Date().toISOString());
         this.scheduleFlush();
     }
-    async getLeafId(sessionId) {
-        try {
-            const session = await this.repo.open({ id: sessionId, createdAt: "" });
-            return (await session.getStorage().getLeafId()) ?? null;
-        }
-        catch (e) {
-            if (isNotFound(e))
-                return null;
-            throw e;
-        }
-    }
     async release(sessionId) {
         this.pending.delete(sessionId);
     }
@@ -580,17 +560,23 @@ export class LocalSessionStore {
     }
     async fork(sourceId, owner) {
         await this.meta.ensureLoaded();
-        try {
-            const session = await this.repo.fork({ id: sourceId, createdAt: "" }, {});
-            const id = (await session.getMetadata()).id;
-            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner }));
-            return id;
-        }
-        catch (e) {
-            if (isNotFound(e))
-                return null;
-            throw e;
-        }
+        return this.withSessionWriteLock(sourceId, async () => {
+            const source = this.meta.state.entries.get(sourceId);
+            const forkOwner = forkOwnerOf(owner, source === undefined ? undefined : readSessionMetaCell(source).owner);
+            try {
+                const sourceMeta = { id: sourceId, createdAt: "" };
+                const forkOptions = await settledForkOptions(await this.repo.open(sourceMeta));
+                const session = await this.repo.fork(sourceMeta, forkOptions);
+                const id = (await session.getMetadata()).id;
+                await this.writeMeta(id, () => (forkOwner === undefined ? mintSessionIncarnation() : { incarnation: mintSessionIncarnation(), owner: forkOwner }));
+                return id;
+            }
+            catch (e) {
+                if (isNotFound(e))
+                    return null;
+                throw e;
+            }
+        });
     }
     async exportEntries(sessionId) {
         if (!this.repo.exportEntries)
@@ -657,12 +643,15 @@ export class LocalSessionStore {
     }
     async commitStagedImport(sessionId, owner, staged, opts) {
         return this.withSessionWriteLock(sessionId, async () => {
+            const current = await this.metaOf(sessionId);
+            if (!ownerCellIs(opts.expectedOwner, current === undefined ? undefined : (current.owner ?? null)))
+                throw new StagedCommitOwnerChangedError(sessionId);
             const dstEntries = await this.exportEntries(sessionId);
             const rel = classifySyncRelationshipByIds(staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
-            if ((rel.relation === "fork" || rel.relation === "stale") && opts?.resolution !== "overwrite-dst") {
+            if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 throw new SyncConflictError(sessionId, rel);
             }
-            if (rel.relation === "fast_forward" && opts?.resolution !== "overwrite-dst" && dstEntries !== null && dstEntries.length > 0) {
+            if (rel.relation === "fast_forward" && opts.resolution !== "overwrite-dst" && dstEntries !== null && dstEntries.length > 0) {
                 const dstSet = new Set(dstEntries.map((e) => e.id));
                 const diverged = fastForwardSharedContentDiverged(staged.filter((e) => dstSet.has(e.id)), dstEntries);
                 if (diverged)
@@ -675,9 +664,10 @@ export class LocalSessionStore {
             else {
                 await this.restampOwner(sessionId, owner);
             }
-            const face = await this.sessionFaceOf(sessionId);
-            if (face === undefined)
+            const meta = await this.metaOf(sessionId);
+            if (meta === undefined)
                 throw new SessionError("storage", `LocalSessionStore: staged commit for session ${sessionId} left no session face — nothing was settled`);
+            const face = sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation);
             return { relation: rel.relation, face };
         });
     }
@@ -685,8 +675,8 @@ export class LocalSessionStore {
         return this.withSessionWriteLock(sessionId, () => this.deleteSessionHeld(sessionId, owner));
     }
     async deleteSessionHeld(sessionId, owner) {
-        const current = await this.ownerOf(sessionId);
-        if (current === undefined || !ownerEq(current, owner))
+        const current = await this.metaOf(sessionId);
+        if (current === undefined || !ownerEq(current.owner ?? null, owner))
             return false;
         try {
             await this.repo.delete({ id: sessionId, createdAt: "" });

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

@@ -16,12 +16,18 @@
  *    branch below the floor — so the record the engine reads is the one the run's walk reaches.
  * Read-only: the log is read once (`exportEntries`, pure), no append log is opened, and the window refuses writes.
  *
- * ## Cost: one linear walk
- * The branch is the `parentId` chain from the leaf — the chain core's `getPathToRoot` follows, with the same stop rule (an entry
- * without a parent ends it; a parent the log does not hold is `invalid_session`). It is walked here once, in linear time: core
- * 7.52.0 builds its path with `unshift` (quadratic in the branch length — seconds on a long session, on the event loop), and the
- * view must cost a window read, not a whole-branch walk. Every later read of the window goes through core's own walk, bounded by
- * the floor.
+ * ## Cost: one linear walk, the engine's
+ * The branch is core's own `getPathToRoot` over the whole log (the walk every engine read of a local session makes, with its stop
+ * rules: an entry without a parent ends it, a parent the log does not hold is `invalid_session`, an unknown leaf is `not_found`).
+ * Since core 7.54.0 ([ref]) that walk is linear; before, it built the path with `unshift` (quadratic — seconds on a long session, on
+ * the event loop) and this module walked the `parentId` chain itself. The second walker is retired: the view reads the branch the
+ * engine reads, by the engine's reading. Every later read of the window goes through the same walk, bounded by the floor.
+ * A parent CYCLE (a corrupted log; the engine never writes one) is refused by that same walk: since core 7.54.1 it carries one
+ * `ParentChainGuard`, and the entry it stands on twice ends it with `invalid_session` naming that entry — `wake` refuses a looped log
+ * the way it refuses one whose parent is missing. Core 7.54.0's walk had no guard (a looped log spun it forever on the event loop,
+ * and the view's wake with it). The retired walker's own cycle refusal went with it: the engine's guard is the one refusal now, shared
+ * by `getPathToRoot` and the run's resume ancestor scan (the two walks core 7.54.1 guards; this module has no walker of its own left).
+ * Pinned in `test/session-log-parent-cycle.test.ts`.
  */
 import { BaseSessionStorage } from "@sema-agent/core";
 export declare class LocalSessionWindow extends BaseSessionStorage {

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

@@ -30,25 +30,9 @@ export class LocalSessionWindow extends BaseSessionStorage {
         const metadata = (await repo.list()).find((m) => m.id === sessionId) ?? { id: sessionId, createdAt: new Date().toISOString() };
         const whole = new InMemorySessionStorage({ entries: log });
         const leafId = await whole.getLeafId();
-        const branch = await branchOf(whole, leafId, log.length);
+        const branch = await whole.getPathToRoot(leafId);
         const { tail, floorEntryId } = boundedTail(branch);
         return new LocalSessionWindow(metadata, tail, leafId, floorEntryId, branch.slice(0, branch.length - tail.length));
     }
 }
-async function branchOf(whole, leafId, logLength) {
-    const fromLeaf = [];
-    let current = leafId === null ? undefined : await whole.getEntry(leafId);
-    while (current) {
-        fromLeaf.push(current);
-        if (!current.parentId)
-            break;
-        if (fromLeaf.length > logLength)
-            throw new SessionError("invalid_session", `Entry ${current.id} is on a parent cycle`);
-        const parent = await whole.getEntry(current.parentId);
-        if (!parent)
-            throw new SessionError("invalid_session", `Entry ${current.parentId} not found`);
-        current = parent;
-    }
-    return fromLeaf.reverse();
-}
 //# sourceMappingURL=local-session-window.js.map

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

@@ -44,14 +44,14 @@ export declare function mailboxKeyDeleteSql(dialect: "tidb" | "pg", table: Mailb
 /** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏行的 fail-closed 抛必须**响亮**——core 唯一的
  *  claimLease 调用方(peer-session-drain)吞掉该错,店不记这一笔就成了「静默永久卡箱」。抛之前记
  *  `mailbox_message_column_corrupt`(scope/handle/seq/column/code),运维按 seq 修行。
- *  🔴 S-550 车③a **改名并归一**:旧事件名 `mailbox_peer_meta_corrupt` 在 `hop_chain` 也变成 fail-closed 的
+ *  🔴 [ref] 车③a **改名并归一**:旧事件名 `mailbox_peer_meta_corrupt` 在 `hop_chain` 也变成 fail-closed 的
  *  那一刻就说不出真话了(同一条读腿两列同判)。一个事件 + 一个 `column` 字段,而不是两个事件名 —— 运维
  *  面按 column 分桶,店里只有一条留痕规则。 */
 export interface MailboxStoreLogger {
     warn(event: string, fields: Record<string, unknown>): void;
 }
 export declare function ensureTiDBMailboxSchema(pool: MySqlPool): Promise<void>;
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgMailboxSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgMailboxSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const MAILBOX_INDEXES: readonly IndexSpec[];
 export declare function ensurePgMailboxSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
 export declare class TiDBMailboxStore implements MailboxStore, MailboxRecipientLifecycle {

package/dist/plugins/memory-engine-pg.d.ts

@@ -17,7 +17,7 @@ export interface PgMemoryEngineSchemaOptions {
         pgvector?: boolean;
     };
 }
-/** S-287:记忆引擎 PG 面的索引**声明**(MySQL 孪生是 `memory-engine-tidb.ts` 的内联 `KEY`/`UNIQUE KEY`,
+/** [ref]:记忆引擎 PG 面的索引**声明**(MySQL 孪生是 `memory-engine-tidb.ts` 的内联 `KEY`/`UNIQUE KEY`,
  *  由 `tidb-pool.ts` 的中央 `ensureSchema` 用同一份声明补存量库)。 */
 export declare const MEMORY_ENGINE_INDEXES: readonly IndexSpec[];
 /** Idempotent DDL for the entry plane. Call once at startup (or run through your migration tool). */

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

@@ -73,10 +73,10 @@ export declare class MemoryRunStore implements InProcessClaimFence {
      *  offered) → the terminal row → the active-run slot release. Returns whether the pending row is now this run's. */
     private writeTerminal;
     /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard).
-     *  S-173:同时落 `result` —— 封口脱敏后的投影(`sealRunRowResult`,凭据不落;`null` = 没观察到 park 结果),SQL 孪生同注。 */
+     *  [ref]:同时落 `result` —— 封口脱敏后的投影(`sealRunRowResult`,凭据不落;`null` = 没观察到 park 结果),SQL 孪生同注。 */
     setSuspended(taskId: string, result: PersistedTaskResult | null): Promise<void>;
     /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review.
-     *  S-173:同 {@link setSuspended} 落封口脱敏后的 `result`。 */
+     *  [ref]:同 {@link setSuspended} 落封口脱敏后的 `result`。 */
     setNeedsReview(taskId: string, result: PersistedTaskResult | null): Promise<void>;
     /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags.
      *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
@@ -88,7 +88,7 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
     listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
-     * S-297 —— 这个会话**最近一条腿**的窄指针({@link SqlRunStore.latestRunForSession} 的孪生:同一个排序口径
+     * [ref] —— 这个会话**最近一条腿**的窄指针({@link SqlRunStore.latestRunForSession} 的孪生:同一个排序口径
      *  `createdAt DESC, taskId DESC`,与本店 {@link MemoryRunStore.listSessions} 挑 `rn=1` 那一行的比较器逐字同一份)。
      */
     latestRunForSession(sessionId: string): Promise<LatestRunRef | undefined>;
@@ -135,7 +135,7 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     /** Fail stale `running` rows (crashed-run backstop) + release task_active for any now-terminal row. */
     reapStale(olderThanMs: number): Promise<number>;
     /** [ref] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired'), the
-     *  in-memory twin of the SQL UPDATE (`error`/`error_code` set directly — no result blob to derive from; S-173: the park-time `result` is cleared, same as the SQL `result = NULL`). */
+     *  in-memory twin of the SQL UPDATE (`error`/`error_code` set directly — no result blob to derive from; [ref]: the park-time `result` is cleared, same as the SQL `result = NULL`). */
     private failExpiredPark;
     /** Release the claim for TERMINAL rows only — suspended/needs_review keep it (the `DELETE ta … WHERE tr.status
      *  NOT IN ('running','suspended','needs_review')` twin, shared by reapStale + the [ref] suspended reapers). */

package/dist/plugins/memory-sync-store-pg.d.ts

@@ -46,14 +46,14 @@ export interface MemorySyncStore {
     /** Transient failure: attempts+1 (SQL-atomic), record the error, schedule the next attempt. */
     fail(id: string, error: string, nextAttemptAtMs: number): Promise<void>;
 }
-/** S-287:push queue 的索引**声明**(MySQL 孪生 = `memory-sync-store-tidb.ts` 的内联 `KEY`)。 */
+/** [ref]:push queue 的索引**声明**(MySQL 孪生 = `memory-sync-store-tidb.ts` 的内联 `KEY`)。 */
 export declare const MEMORY_SYNC_INDEXES: readonly IndexSpec[];
 /** Idempotent DDL for the sync plane (PG dialect). Call once at startup. */
 export declare function ensurePgMemorySyncSchema(query: PgQueryFn): Promise<void>;
 /**
  * 本店三只 JSON 承载列的**折码点**(唯一)—— 本店没有枚举式 corrupt 码,既有的「读不出来」口径就是
  * 响亮抛(`claimLeaseMs` 守卫 / dup id 一律 fail-loud)⇒ 折成响亮裸 `Error`,点名 `<表>.<列>` + 行标识
- * (S-550 车①② 裁定,沿用;不新铸码)。两个孪生共用本函数(MySQL 腿 import 它 —— 一条折码规则一个写者)。
+ * ([ref] 车①② 裁定,沿用;不新铸码)。两个孪生共用本函数(MySQL 腿 import 它 —— 一条折码规则一个写者)。
  */
 export declare function refusingMemorySyncRow<T>(read: () => T): T;
 /** Options for {@link PgMemorySyncStore}. */
@@ -115,7 +115,7 @@ export interface MemoryHistoryStore {
     /** Ops read face (§1.3 保留策略: v1 无界 + 运维计数 — quota/pruning waits for a demand signal). */
     countByScope(scope: string): Promise<number>;
 }
-/** S-287:history 表的索引**声明**(MySQL 孪生 = `memory-sync-store-tidb.ts` 的内联 `KEY`)。 */
+/** [ref]:history 表的索引**声明**(MySQL 孪生 = `memory-sync-store-tidb.ts` 的内联 `KEY`)。 */
 export declare const MEMORY_HISTORY_INDEXES: readonly IndexSpec[];
 /** Idempotent DDL for the history table (PG dialect). Separate from the sync-plane ensure so S5.1
  *  can wire the write point independently of the S4 sync wiring. */