@sema-agent/server 7.125.0 → 7.126.0

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

@@ -2,14 +2,14 @@ import { redactErrorMessage, redactLedgerEventData, sealRunRowResult } from "../
 import { outwardPlane } from "../terminal.js";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { join } from "node:path";
-import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprint, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError, readLegacyHolderDeathCode } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
-import { migrateRetiredAskOrigin } from "./one-time-migrations.js";
+import { createInProcessSpaceCommitTable, fenceSpaceCommitAtTerminal, SPACE_COMMIT_RECORD_SCHEMA } from "../workspace-space-commit.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isParseableDate = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
 const RUN_ROW_SHAPE = {
@@ -53,6 +53,8 @@ export class FileRunStore {
     runsDir;
     activeDir;
     tmpDir;
+    spaceCommitsDir;
+    spaceCommits;
     runs = new Map();
     active = new Map();
     byIdem = new Map();
@@ -69,6 +71,15 @@ export class FileRunStore {
         this.runsDir = join(root, "runs");
         this.activeDir = join(root, "runs", "active");
         this.tmpDir = join(root, "tmp");
+        this.spaceCommitsDir = join(root, "space-commits");
+        this.spaceCommits = createInProcessSpaceCommitTable({
+            load: (spaceKey) => this.loadSpaceCommit(spaceKey),
+            save: (record) => {
+                mkdirSync(this.spaceCommitsDir, { recursive: true });
+                atomicWriteFile(this.tmpDir, this.spaceCommitPath(record.spaceKey), `${JSON.stringify(record)}\n`);
+            },
+            remove: (spaceKey) => rmSync(this.spaceCommitPath(spaceKey), { force: true }),
+        });
         try {
             ensureDir(this.runsDir);
             ensureDir(this.activeDir);
@@ -97,8 +108,45 @@ export class FileRunStore {
     activePath(sessionId) {
         return join(this.activeDir, sanitizePathComponent(sessionId));
     }
+    spaceCommitPath(spaceKey) {
+        return join(this.spaceCommitsDir, `${sanitizePathComponent(spaceKey)}.json`);
+    }
+    loadSpaceCommit(spaceKey) {
+        let text;
+        try {
+            text = readFileSync(this.spaceCommitPath(spaceKey), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return undefined;
+            throw err;
+        }
+        const r = SPACE_COMMIT_RECORD_SCHEMA.safeParse(JSON.parse(text));
+        if (!r.success || r.data.spaceKey !== spaceKey) {
+            throw new Error(`space-commits/${spaceKey}.json is not a workspace space commit record — refusing to guess whether a commit is in flight`);
+        }
+        return r.data;
+    }
+    readSpaceCommit(spaceKey) {
+        return this.spaceCommits.readSpaceCommit(spaceKey);
+    }
+    claimSpaceCommit(spaceKey, taskId, state, claim) {
+        return this.spaceCommits.claimSpaceCommit(spaceKey, taskId, state, claim);
+    }
+    endSpaceCommit(spaceKey, taskId) {
+        return this.spaceCommits.endSpaceCommit(spaceKey, taskId);
+    }
+    abandonSpaceCommit(spaceKey, taskId) {
+        return this.spaceCommits.abandonSpaceCommit(spaceKey, taskId);
+    }
     toRow(d) {
-        return { ...d, idemKey: typeof d.idemKey === "string" ? d.idemKey : null, createdAt: new Date(d.createdAt), updatedAt: new Date(d.updatedAt) };
+        return {
+            ...d,
+            idemKey: typeof d.idemKey === "string" ? d.idemKey : null,
+            idemBodyFingerprint: typeof d.idemBodyFingerprint === "string" ? d.idemBodyFingerprint : null,
+            createdAt: new Date(d.createdAt),
+            updatedAt: new Date(d.updatedAt),
+        };
     }
     toDisk(r) {
         return { ...r, createdAt: r.createdAt.toISOString(), updatedAt: r.updatedAt.toISOString() };
@@ -283,7 +331,7 @@ export class FileRunStore {
         return log;
     }
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
-        const idemKey = meta.idemKey ?? null;
+        const idemKey = meta.idem?.key ?? null;
         return this.withClaimLock(sessionId, async () => {
             const acquired = await this.acquireClaim(sessionId, taskId);
             if (!acquired.ok) {
@@ -327,6 +375,7 @@ export class FileRunStore {
                 instanceId,
                 objectivePreview: meta.objectivePreview ?? null,
                 idemKey,
+                idemBodyFingerprint: meta.idem?.bodyFingerprint ?? null,
                 createdAt: now,
                 updatedAt: now,
                 cancelRequested: false,
@@ -399,8 +448,12 @@ export class FileRunStore {
             .map((e) => ({ ...e, data: e.data == null ? null : structuredClone(e.data) }));
     }
     async setTerminal(taskId, status, result, error) {
+        await fenceSpaceCommitAtTerminal(taskId, async (spaceCommit) => this.writeTerminal(taskId, status, result, error, spaceCommit));
+    }
+    writeTerminal(taskId, status, result, error, spaceCommit) {
         result = sealRunRowResult(result);
         error = error === null ? null : (redactErrorMessage(error) ?? null);
+        const fenced = spaceCommit !== undefined && this.spaceCommits.claimSync(spaceCommit.spaceKey, taskId, "pending", spaceCommit.claim);
         const r = this.runs.get(taskId);
         if (!r) {
             for (const [sessionId, tid] of this.active)
@@ -408,7 +461,7 @@ export class FileRunStore {
                     this.releaseClaim(sessionId);
                     break;
                 }
-            return;
+            return fenced;
         }
         let pending;
         if (r.status === "running" || r.status === "suspended" || r.status === "needs_review") {
@@ -434,6 +487,7 @@ export class FileRunStore {
             this.releaseClaim(r.sessionId);
         if (pending)
             notifyRunTerminal(pending);
+        return fenced;
     }
     async setSuspended(taskId, result) {
         const sealed = sealRunRowResult(result);
@@ -477,13 +531,21 @@ export class FileRunStore {
     }
     async releaseIdemKey(taskId) {
         const r = this.runs.get(taskId);
-        if (!r || r.idemKey === null)
+        if (!r || (r.idemKey === null && r.idemBodyFingerprint === null))
             return;
         const key = r.idemKey;
-        this.persist({ ...r, idemKey: null });
-        if (this.byIdem.get(key) === taskId)
+        this.persist({ ...r, idemKey: null, idemBodyFingerprint: null });
+        if (key !== null && this.byIdem.get(key) === taskId)
             this.byIdem.delete(key);
     }
+    async bindIdemBodyFingerprint(taskId, idem) {
+        const r = this.runs.get(taskId);
+        if (!r || r.idemKey !== idem.key)
+            return null;
+        if (r.idemBodyFingerprint === null)
+            this.persist({ ...r, idemBodyFingerprint: idem.bodyFingerprint });
+        return this.runs.get(taskId)?.idemBodyFingerprint ?? null;
+    }
     async getRunByIdem(idemKey) {
         const taskId = this.byIdem.get(idemKey);
         const r = taskId !== undefined ? this.runs.get(taskId) : undefined;
@@ -921,32 +983,6 @@ export class FileRunStore {
             }
         }
     }
-    async migrateRetiredAskOriginRows() {
-        const rewrites = new Map();
-        for (const [taskId, list] of this.events) {
-            let touched = 0;
-            const rows = list.map((e) => {
-                const data = migrateRetiredAskOrigin(e.type, e.data);
-                if (data === undefined)
-                    return e;
-                touched++;
-                return { ...e, data };
-            });
-            if (touched > 0)
-                rewrites.set(taskId, { rows, touched });
-        }
-        if (rewrites.size === 0)
-            return 0;
-        this.dispose();
-        let migrated = 0;
-        for (const [taskId, { rows, touched }] of rewrites) {
-            mkdirSync(this.runDir(taskId), { recursive: true });
-            atomicWriteFile(this.tmpDir, this.eventsPath(taskId), rows.map((e) => `${JSON.stringify(e)}\n`).join(""));
-            this.events.set(taskId, rows);
-            migrated += touched;
-        }
-        return migrated;
-    }
     migrateLegacyHolderDeathCodes() {
         let migrated = 0;
         for (const r of this.runs.values()) {

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

@@ -172,13 +172,16 @@ export declare class LocalCheckpointStore {
      *  [ref]:与 `findPendingTokenBySession` 同一个 {@link pickPendingRow}(同 binding ⇒ 同一行)。 */
     peekPendingScope(sessionId: string, binding?: PendingRowBinding): Promise<string | null | undefined>;
     /**
-     * [ref] D-D global expiry sweep — same kind-split as the TiDB twin: the deadline branch abort-expires
-     * every kind EXCEPT a human/irreversible_ask approval gate (those get the graceful resolve-DENY via
-     * listExpiredApprovalGates), with the AskUserQuestion carve-back (denying a question is incoherent → expire);
-     * the terminal_at_ms branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
+     * [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
+     * listExpiredApprovalGates). Among approval kinds the ONE judge is core `facetOf(gate)` (#1468 A-S4): a gate
+     * carrying the `question` card is facet `B` — its deadline voids it (denying a question is incoherent); a gate
+     * with no card (parked before core 7.49.0) is no question (core's reading, never re-derived from the tool name).
+     * The terminal_at_ms branch (derived read-time via the SAME formula the SQL put stamps) abort-expires ANY kind.
      */
     reapExpired(cutoff: number): Promise<number>;
-    /** [ref] D-D SLA deny-sweep input — pending human/irreversible_ask gates past deadline (excl. AskUserQuestion). */
+    /** [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;

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

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { ASK_USER_QUESTION_TOOL_NAME, contentKindOf } from "../approval-content-kind.js";
+import { parkedApprovalCard } from "../approval-content-kind.js";
 import { parkRowFacts } from "../approval-card.js";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { isApprovalGateKind } from "../tool-approval.js";
+import { denySweepOwns } from "../tool-approval.js";
 import { FileCheckpointStore, atomicWriteFile, executionVerdict, sanitizePathComponent, } from "@sema-agent/core";
 import { approvalDecisionOfWinner, approvalPayloadFingerprint, boundedRuleOffers, boundedToolInput, pendingActionToolCallId, pendingRowPrecedes, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
@@ -184,7 +184,7 @@ export class LocalCheckpointStore {
                     return rs !== undefined ? { ruleOffers: rs } : {};
                 })(),
                 ...(pa?.hasBidiControls === true ? { hasBidiControls: true } : {}),
-                ...(contentKindOf(pa?.toolName ?? null) !== undefined ? { contentKind: "content_ask" } : {}),
+                ...((card) => (card !== undefined ? { approvalCard: card } : {}))(parkedApprovalCard(cp.gate)),
                 ...parkRowFacts(cp.pendingAction),
             });
         }
@@ -288,11 +288,7 @@ export class LocalCheckpointStore {
     async reapExpired(cutoff) {
         let n = 0;
         for (const { token, cp } of await this.pendings()) {
-            const gateKind = cp.gate?.kind;
-            const toolName = cp.pendingAction?.toolName ?? "";
-            const deadlineBranch = cp.deadline !== undefined &&
-                cp.deadline <= cutoff &&
-                (gateKind === undefined || !isApprovalGateKind(gateKind) || toolName === ASK_USER_QUESTION_TOOL_NAME);
+            const deadlineBranch = cp.deadline !== undefined && cp.deadline <= cutoff && !denySweepOwns(cp.gate);
             const terminalBranch = terminalAtOf(cp) <= cutoff;
             if ((deadlineBranch || terminalBranch) && (await this.inner.expire(token, cp.scope)))
                 n++;
@@ -302,13 +298,7 @@ export class LocalCheckpointStore {
     async listExpiredApprovalGates(cutoff, limit = 100) {
         const hits = [];
         for (const { cp } of await this.pendings()) {
-            const gateKind = cp.gate?.kind;
-            const toolName = cp.pendingAction?.toolName ?? "";
-            if (gateKind !== undefined &&
-                isApprovalGateKind(gateKind) &&
-                toolName !== ASK_USER_QUESTION_TOOL_NAME &&
-                cp.deadline !== undefined &&
-                cp.deadline <= cutoff)
+            if (denySweepOwns(cp.gate) && cp.deadline !== undefined && cp.deadline <= cutoff)
                 hits.push({ sessionId: cp.sessionId, scope: cp.scope, deadline: cp.deadline });
         }
         return hits

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

@@ -4,7 +4,7 @@ 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 } from "../session-sync-kernel.js";
+import { type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 /**
  * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座与会话视图口
  * `audit.ts#buildSessionAuditLocal` 的读旁路),所以坏记录的披露座只有这一份接线 —— 修前视图口自建一只不带座的 repo,同一份坏档在这里读到有计数 / 探针,
@@ -75,6 +75,14 @@ export declare class LocalSessionStore implements SessionStore {
     private readonly meta;
     /** 认领行(`session_owner_claimed`)的出口 —— 一次性迁移 M10 的认领臂专用(窗口见 `plugins/one-time-migrations.ts` 登记表)。 */
     private readonly log;
+    /**
+     * 按会话的写锁(表见 {@link SESSION_WRITE_LOCKS_BY_ROOT})—— 会话行两位的**每一笔**写(住客判 → 边档草稿 → 落盘 → 发布)与同一 id 上住客的**每一次**换人
+     * (删除:存档 + 三只行边档 + 元数据格;按 id 建会话:打开即建、登记;导入:铸新住客;换装:删后插回;staged 导入的提交)排在同一条链上:判过的住客
+     * 在那一笔发布完之前不会被换掉,删除不会落在「判过、未发布」之间,同 id 的新住客也不会在删除做到一半时生出来、再被它的收尾抹掉。只有这一把;
+     * SQL 孪生是一条带化身条件的 UPDATE、一条事务里的删除,没有这个窗,不需要它。按 id 的 acquire(打开 / 首建)也在这条链上:交出的会话挂的住客与打开
+     * 同一节读到(见 `load`)。新 id 的建会话(不带 id 的 acquire、fork)不与任何人争同一 id,不上锁。
+     */
+    private readonly sessionWriteLocks;
     /** @param repo     the core SessionRepo this store projects into the §0.5 SessionStore shape.
      *  @param runs     the run store whose per-session projection is the ONLY source of a row's `runCount` / `lastStatus` / `lastRunId` /
      *                  `lastTaskRunId` (LocalBackend passes its `FileRunStore`). Required — a run-less local session store does not exist.
@@ -95,6 +103,11 @@ export declare class LocalSessionStore implements SessionStore {
     private writeMeta;
     /** 删一只会话的那一格(落盘;落不了 ⇒ 抛 —— 留下的格会让一只删掉的会话在重启后「还在」)。 */
     private dropMeta;
+    /**
+     * 在 `sessionId` 的写锁里跑 `body`(锁见 {@link sessionWriteLocks}):排在这只会话此前每一节之后,`body` 完成(或抛)才放下一节。
+     * 不可重入 —— 锁里的调用方只调 `…Held` 那一形(它们假定锁已在手),不再回到上锁的公开口。
+     */
+    private withSessionWriteLock;
     /** 盘上有没有这只会话(repo 的唯一探针;`open` 读整只存档,所以只在边档里没有那一格时才走到这里)。 */
     private existsInRepo;
     /**
@@ -103,8 +116,21 @@ export declare class LocalSessionStore implements SessionStore {
      * ⇒ 补铸一格只有化身的(属主没有事实可写,不伪造)并落盘后再答 —— 之后的读都命中那一格,不再回 repo。
      */
     private metaOf;
+    /**
+     * 一只**已证明在盘上**的会话的那一格:有 ⇒ 读它;没有(7.104.0 之前写下、此后没被读过)⇒ 补铸一格只有化身的(属主没有事实可写,不伪造)
+     * 并落盘后再答。证明由调用方给:{@link metaOf} 探过 repo;acquire 的打开腿在这只会话的写锁里刚打开它({@link openForItselfHeld})。
+     * `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>;
+    /**
+     * 三条 acquire 腿(无 id 建 / 按 id 打开 / 按 id 首建)交出会话的唯一一处:住客 = 这只会话那一格({@link cellOfPresent} —— 刚建或刚在写锁里
+     * 打开,就是在盘上的证明,不再回 repo 探一次),经与 {@link sessionFaceOf} 同一只解码(`sessionFaceFromRow`),挂到交出的会话上({@link occupiedBy})。
+     */
+    private handOut;
     /** Cheap pre-LLM probe (local twin). The map write needs no session_meta row, so there is
      *  no "none" (register-lag) dimension here — two states only. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
@@ -115,8 +141,8 @@ export declare class LocalSessionStore implements SessionStore {
     /**
      * 会话行的可写位 —— 用户标题 / 置顶的**唯一**写口(SQL 孪生 `patchSessionMeta` 的 local 对位;写者次序见 `src/session-row.ts`)。
      * 只写列表面上的会话(会话仓里有它),且只写调用方验过的那一位住客(`face.incarnation` 与会话元数据那一格的化身相等 —— SQL 孪生的
-     * `AND incarnation = ?`):住客判在每只边档 `commit` 的写链节里、对着那一刻的元数据格判(判、写、落盘后才发布),读回同一判据
-     * ⇒ 回执是那一位住客的列表行,或 `undefined`(期间被删 / 被谁重新登记 —— 什么都没写)。
+     * `AND incarnation = ?`)。住客判、两只边档的草稿 → 落盘 → 发布、读回,**整段在这只会话的写锁里**({@link withSessionWriteLock}):删除 / 导入 /
+     * 换装同锁,判过的住客在这一笔发布完之前换不掉 —— 所以住客只判一次,读回的就是那一位的行;判不过(期间被删 / 被谁重新登记)⇒ `undefined`,什么都没写。
      * `title` 串 ⇒ 无条件写进那一格(自动标题器的 {@link setTitleIfNull} 见格在就不写 ⇒ 用户那笔恒留下);`title: null` ⇒ 删那一格(清回自动标题);
      * `pinned:true` 写 `true`、`false` 删键。
      * 落不了盘 ⇒ 抛、内存不动(用户的一笔写,不做「内存里先记着」的降级)。⚠️ 两键同一体时是两只文件、两次落盘:第二只落不了时第一只已在盘上
@@ -180,6 +206,12 @@ export declare class LocalSessionStore implements SessionStore {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
     private load;
+    /** 为这只会话打开它自己的存档,锁内一形(调用方持这只会话的写锁,见 {@link load})。S-612:这是「为这只会话打开它自己的存档」的那一次
+     *  (引擎 prepare 的 acquire)⇒ 包在打开作用域里:这次回放跳过了记录 ⇒ 打开成功后铸一帧 `session.records_skipped` 投给这只会话(唯一铸点
+     *  与作用域见 `session-records-skipped-notice.ts`);读不出(`corrupt_session`)照旧原样上抛,不铸。存档只读这一次:住客那一格缺(更早版本
+     *  写下的会话)时,这次打开就是补铸的证明({@link handOut})。GUARD(open 腿):打开一只已存在的会话**不写属主** —— 记下的属主(含「登记为
+     *  无主」)一个字节不动,没被记下的也不在这里替它记成无主:打开不是一个属主事实(7.119.0 前这一腿把「不知道」记成进程内存里的 null,重启即失)。 */
+    private openForItselfHeld;
     /**
      * 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
@@ -207,8 +239,9 @@ export declare class LocalSessionStore implements SessionStore {
     } | 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. */
-    restampOwner(sessionId: string, owner: string | null): Promise<void>;
+     *  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. */
@@ -295,7 +328,7 @@ export declare class LocalSessionStore implements SessionStore {
      *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`).
      *  The owner is recorded in the session-meta cell (persisted), together with the incarnation. */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** importEntries / replaceEntries 的共用写半场:导日志 + 一格写全属主与化身(新建铸的那只,或换装沿用的那只)。 */
+    /** importEntries / replaceEntries 的共用写半场:导日志 + 一格写全属主与化身(新建铸的那只,或换装沿用的那只)。调用方持这只会话的写锁。 */
     private importEntriesAs;
     /** 2c session-sync (§7/§8) — IDEMPOTENT REPLACE. The local twin's replace is DELETE-then-IMPORT: core's
      *  InMemorySessionRepo / FileSessionRepo expose no single replace primitive, but the local backend is single-writer
@@ -304,6 +337,8 @@ export declare class LocalSessionStore implements SessionStore {
      *  gap, unlike the durable cross-instance backends which do it in ONE SQL txn). Both halves are best-effort feature-
      *  gated: a repo lacking either seam throws the same clear error importEntries does (no silent half-write). */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /** {@link replaceEntries} 的锁内一形(调用方持这只会话的写锁)。 */
+    private replaceEntriesHeld;
     /** 2c session-sync P1d-β (PUSH streaming) — begin a STAGED import. The LOCAL backend is single-writer with no
      *  cross-instance / cross-replica concurrency story (the durable twins carry that), so the staging handle simply
      *  ACCUMULATES the streamed batches in memory then, on commit, runs the SAME validate-first → replaceEntries the
@@ -316,10 +351,34 @@ export declare class LocalSessionStore implements SessionStore {
     readStagedEntries(stagingId: string): Promise<SessionTreeEntry[]>;
     /** 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)
+     * → 拒未经同意的 fork / stale / 载荷分叉 → 换装(validate-first → 删 → 导入,化身按换装律沿用)或 identical 且内容相同时只重戳属主 → **在同一次持锁里**
+     * 读出落定的会话面交回。锁放下之前谁也换不掉这一位住客,所以交回的面就是这次提交落下的那一位(SQL 孪生在提交事务里读同一行,同义);
+     * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。
+     */
+    commitStagedImport(sessionId: string, owner: string | null, staged: SessionTreeEntry[], opts?: {
+        resolution?: "overwrite-dst";
+    }): Promise<{
+        relation: SyncRelation["relation"];
+        face: SessionFace;
+    }>;
     /** E21 — purge a session's conversation history (core SessionRepo.delete), owner-guarded (single-user: owner=null
      *  matches). Idempotent: a missing/wrong-owner session is a no-op returning false. The runs-ledger / checkpoint /
-     *  tool-result rows are purged separately by the route's purgeSession coordinator. */
+     *  tool-result rows are purged separately by the route's purgeSession coordinator. 整段在这只会话的写锁里(换人)。 */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
+    /**
+     * {@link deleteSession} 的锁内一形(调用方持这只会话的写锁;换装 {@link replaceEntriesHeld} 也走它)。
+     * 删的是 SQL 孪生 `session_meta` 那一行在本店的全部对位:会话存档、三只行边档(标题 / 置顶 / S-690 的指令来源基线)、属主 + 化身那一格。
+     * 三只边档的那一键**都经各自的写链删**(`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 重登记铸新的 —— 那就是下一位住客)。
+     */
+    private deleteSessionHeld;
     get size(): number;
     /** Graceful shutdown: AWAIT the final sidecar write (bug C) so a restart doesn't lose the last debounced-but-unwritten
      *  touch. Cancels any queued debounce, then awaits a flush (which chains after any in-flight write and merges disk). */