@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,43 +1,11 @@
-/**
- * LOCAL session store — the DB-less twin of {@link TiDBSessionStore} (clay 2026-06-25 seamless local↔cloud). Wraps a
- * core `SessionRepo` (in-memory `InMemorySessionRepo` for v1; `FileSessionRepo` for the file-backed follow-on — both
- * expose create/open/list/delete/fork) and projects it into the service's `SessionStore` + `OwnerAwareSessionStore`
- * shape, so a locally-run HTTP service serves the SAME session contract a cloud worker does: acquire (the run path) +
- * the §0.5 ownership ops (ownerOf/register/fork/deleteSession).
- *
- * Single-user by construction: a local file/in-memory deployment has no multi-tenant owner column (core's
- * SessionMetadata is `{id, createdAt}`), so REQUIRE_PRINCIPAL must be OFF (main.ts enforces this) and owner is tracked
- * here only as the service-side scope (null/"local").
- *
- * P0.5 variant-2 (clay 2026-06-26): `listSessions` IS implemented — it enumerates the repo's persisted sessions
- * (`repo.list()`) and synthesizes a {@link SessionSummary} per id from the SESSION abstraction (no run ledger), so
- * GET /v1/sessions (server.ts: `sessionStorage.listSessions ?? runStore.listSessions`) takes the FIRST branch and the
- * resume picker is restart-visible when the repo is the file-backed `FileSessionRepo`. Run-ledger-only fields
- * (`runCount`/`lastStatus`) are honestly DEGRADED (the session abstraction has no runs); preview is synthesized from
- * the last user-text entry. The in-memory `InMemorySessionRepo` works too (process-local; lost on restart) — the
- * persistence comes from the repo, not this wrapper.
- */
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-// 🔴 生产级兼容性 bug 撞获(2026-07-25,sema-desktop PoC 全新 npm install 复现):`Session` 在这个文件里
-// 只当类型用(见下方 `as Session` 断言),此前却写成值导入——本地锁定 core@1.401.0 时 `Session` 恰好还是
-// runtime 导出,掩盖了这个问题;但 core 1.403+(黑板 [1628]/[1634])把 `Session` 降级成纯类型、改用
-// `StoredSession` 作 runtime class。任何新装 `@sema-agent/server` 在这行 import 会直接
-// `SyntaxError: does not provide an export named 'Session'` 崩溃启动。改成 `import type` 消除。
-// ✅ 尾声(design/158 F-5 核账,2026-07-28):上文历史版本提到的「三处 runtime `new Session(...)`
-// 待迁移 + 依赖收紧 >=1.401.0 <1.403.0」**均已完成**——全仓 `new Session(` 现为零命中(三处都已迁
-// `StoredSession`),依赖范围现为 `^1.444.0`。此注释保留前半段是因为「值导入 vs 类型导入被本地锁定
-// 版本掩盖」这个缺陷机制仍值得后人读;宣称"待办"的部分已按实况改写(注释宣称≠代码实做是本仓
-// 已立案的病族,过期待办比没有更有害)。
 import { SessionError, validateEntriesForImport } from "@sema-agent/core";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
-/** Extract the plain text of a USER message entry (the objective preview source) — `null` for any other entry
- *  type or a non-user message, so {@link LocalSessionStore.previewOf} walks past tool/assistant turns to the last
- *  thing the human asked. content may be a bare string or a TextContent[] (join the text parts). */
 function userText(entry) {
     if (entry.type !== "message")
         return null;
@@ -57,93 +25,35 @@ function userText(entry) {
     }
     return null;
 }
-/** 🔴 [1684] MODULE-level, keyed by the RESOLVED sidecar path: the authority is the file, so every store instance
- *  pointing at that file must share one view + one lock. Keyed by `resolve()`d path so `./x` and `x` collapse too. */
 const TITLE_STATE_BY_PATH = new Map();
 export class LocalSessionStore {
     repo;
-    /** #270 车1:托管留存声明 —— **诚实的 none**。本店的行没有任何按期删除的腿(留存 lane 的三方法只实现在
-     *  SQL 聚合店上),所以 locked policy + 本店 ⇒ core 的 `assertRetentionCapability` 拒启,这是契约的
-     *  **正确行为**不是缺口(要留存治理先上 DB 后端;设计稿 §1「不做清单」逐字)。缺席也会被读成 none,
-     *  显式写出来是文档义务:沉默表达不出「我核对过我的介质就是删不了」。 */
     retention = UNMANAGED_RETENTION;
-    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one (mirrors TiDBSessionStore). */
     pending = new Map();
-    /** Service-side owner scope per session (core's repo has no owner column). Registered-ownerless ⇒ null; absent ⇒ undefined. */
     owners = new Map();
-    /** Last-activity marker (touch) for ordering — the keyset sort key for {@link listSessions}. PERSISTED to a JSON
-     *  sidecar under {@link dataDir} (when given) so the /resume picker's newest-first order SURVIVES a service restart:
-     *  without persistence the map starts EMPTY on boot and every session degrades to `createdAt` ordering (the picker
-     *  shows the wrong "most recent" — TOC-review #10). In-memory only (no sidecar) when `dataDir` is absent (the
-     *  process-local `InMemorySessionRepo` case, where the sessions themselves are lost on restart anyway). */
     lastActivity = new Map();
-    /** K-5c (core 1.155 SessionStore.noteTaskRun seam): the latest task run per session, recorded by core's Runner at
-     *  runTask START (so a running/suspended run surfaces too) → projected as `lastRunId` on listSessions. The cloud
-     *  TiDB/PG twins derive it from `task_run`; the local backend has no runs ledger, so this is an in-memory map.
-     *  ⚠️ IN-MEMORY BEST-EFFORT (honest degrade, NOT sidecar-persisted — review Q6): it covers the PRIMARY /resume use
-     *  case (re-attach to a RUNNING run — recorded at the run's start, the process can't have restarted while that run
-     *  is still live), and is LOST on a process restart. That's acceptable: a session whose last run predates a restart
-     *  has only TERMINAL runs (no live tail to re-attach), so `lastRunId` falls back to null and the shell uses its
-     *  no-anchor path — same posture as the other local degrades here (runCount:0, lastStatus:""). Persisting it would
-     *  need a sidecar-format change (the #10 clobber area); deferred until a real local-file-backed need. */
     lastTaskRun = new Map();
-    /** 2c P1d-β — live staged-import handles keyed by stagingId, so a local staging's in-memory buffer is readable via
-     *  readStagedEntries (the durable twins re-read the staged session_event rows; local has no such rows). */
     stagings = new Map();
-    /** Lazy one-shot load of the persisted lastActivity sidecar (memoized; only the first reader pays the read). */
     loaded;
-    /** A pending debounced sidecar flush (coalesces a burst of touch() into one write). undefined ⇒ no flush queued. */
     flushTimer;
-    /** Serializes sidecar writes (bug B): the in-flight write promise. A flush() while one is running CHAINS after it
-     *  (re-checking the dirty flag) so an older snapshot can never rename after a newer one (lost-update). */
     writeChain = Promise.resolve();
-    /** Set by touch/delete when the map mutated; cleared by a write that captured the change. A write that ran while this
-     *  is set re-runs (a touch that landed during an active write isn't dropped). Drives the chain's re-run guard (bug B). */
     dirty = false;
-    /** Monotonic per-write counter — feeds a UNIQUE tmp filename per write so overlapping writes can't share one tmp path
-     *  and tear each other's bytes (bug B). */
     writeSeq = 0;
-    /** Last time a sidecar-write error was warned (bug D): throttle the best-effort warn so a persistently-failing disk
-     *  doesn't spam the log on every debounced flush. 0 ⇒ never warned. */
     lastWarnAt = 0;
-    /** Absolute path to the lastActivity JSON sidecar, or undefined when not persisting (in-memory-only deployment). */
     sidecarPath;
-    /** Auto-title map + its own LIGHT sidecar (`session-titles.json`). Separate file from the
-     *  lastActivity sidecar ON PURPOSE (that format is a #10 clobber area); titles are write-once + ultra-low-rate
-     *  (one per session, ever), so a plain read-modify-write with tmp+rename per write is enough — no debounce.
-     *
-     *  🔴 CROSS-INSTANCE (fixed 2026-07-25, blackboard [1684] — core's "per-instance state" defect class):
-     *  these three used to be INSTANCE fields, which is exactly the shape core described — «the backend is shared
-     *  more widely than the object, but the state and the lock hang off the object». Two `LocalSessionStore`s over
-     *  the SAME dataDir each held their own `titles` map and their own write chain, so a real concurrency probe
-     *  (`test/file-stores-cross-instance-concurrency.test.ts`) showed **BOTH winning** the write-once IS-NULL gate
-     *  (`wins=2`): each checked its own map, both saw absent, both returned `true`, and the second whole-map
-     *  snapshot silently clobbered the first title. That is core's A-class (CAS double-win) and B-class
-     *  (lost update) stacked. Fix per core's prescription: state + lock live at MODULE level, keyed by the resolved
-     *  sidecar path, so any number of instances over one dataDir collapse to a single authority.
-     *  Sharing key = the resolved path; NO sidecar (in-memory deployment) ⇒ no shared backend exists ⇒ that case
-     *  keeps genuinely per-instance state (see {@link titleState}). */
     titleSidecarPath;
-    /** Per-instance fallback used ONLY when there is no sidecar path (nothing is shared, so nothing to collapse). */
     ownTitleState = { titles: new Map(), writeChain: Promise.resolve() };
-    /** @param repo     the core SessionRepo this store projects into the §0.5 SessionStore shape.
-     *  @param dataDir  the SAME data dir the file-backed repo persists under (LocalBackend passes `fileBackend.root`).
-     *                  When given, lastActivity is persisted to `<dataDir>/session-last-activity.json` so it survives a
-     *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives). */
     constructor(repo, dataDir) {
         this.repo = repo;
         this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
-        // [1684] resolve() 规范化后当共享键:`./x` 与 `x` 指同一文件,必须塌缩到同一权威。
         this.titleSidecarPath = dataDir ? resolve(join(dataDir, "session-titles.json")) : undefined;
         if (this.titleSidecarPath && !TITLE_STATE_BY_PATH.has(this.titleSidecarPath)) {
             TITLE_STATE_BY_PATH.set(this.titleSidecarPath, { titles: new Map(), writeChain: Promise.resolve() });
         }
     }
-    /** 该实例应当使用的 title 状态:有 sidecar ⇒ 按路径共享的那份;无 sidecar ⇒ 自己那份(无共享后端)。 */
     get titleState() {
         return this.titleSidecarPath ? TITLE_STATE_BY_PATH.get(this.titleSidecarPath) : this.ownTitleState;
     }
-    /** Lazy one-shot hydrate of the persisted titles (mirrors ensureLoaded's posture: missing file silent, torn warn). */
     async ensureTitlesLoaded() {
         if (!this.titleSidecarPath)
             return;
@@ -155,7 +65,7 @@ export class LocalSessionStore {
                     const parsed = JSON.parse(await readFile(path, "utf8"));
                     for (const [id, t] of Object.entries(parsed)) {
                         if (typeof t === "string" && !st.titles.has(id))
-                            st.titles.set(id, t); // live writes win over disk
+                            st.titles.set(id, t);
                     }
                 }
                 catch (e) {
@@ -166,8 +76,6 @@ export class LocalSessionStore {
         }
         return st.loaded;
     }
-    /** Chained snapshot write of the titles sidecar (the chain guarantees the LAST rename carries the
-     *  NEWEST map state: each link re-snapshots the SHARED map at write time, so an overtaken writer is harmless). */
     persistTitles() {
         if (!this.titleSidecarPath)
             return Promise.resolve();
@@ -185,15 +93,10 @@ export class LocalSessionStore {
         });
         return st.writeChain;
     }
-    /** 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. */
     async probeTitle(sessionId) {
         await this.ensureTitlesLoaded();
         return this.titleState.titles.has(sessionId) ? "titled" : "untitled";
     }
-    /** Write-once auto-title (the local twin of the SQL setTitleIfNull). Persists the whole
-     *  (small) map via a SERIALIZED tmp+rename snapshot; a write failure keeps the in-memory title (degrades to
-     *  re-title after restart). */
     async setTitleIfNull(sessionId, title) {
         await this.ensureTitlesLoaded();
         const st = this.titleState;
@@ -203,9 +106,6 @@ export class LocalSessionStore {
         await this.persistTitles();
         return true;
     }
-    /** Best-effort, one-shot hydrate of the persisted lastActivity map (no-op when not persisting / no sidecar yet). A
-     *  read/parse error degrades to an empty map (createdAt ordering) rather than failing the list — the picker still
-     *  works, just without restart-persisted recency. Memoized so concurrent listSessions share one read. */
     async ensureLoaded() {
         if (!this.sidecarPath)
             return;
@@ -216,14 +116,11 @@ export class LocalSessionStore {
                     const raw = await readFile(path, "utf8");
                     const parsed = JSON.parse(raw);
                     for (const [id, ts] of Object.entries(parsed)) {
-                        // Don't clobber an in-process touch() that landed before the lazy load ran (live writes win over disk).
                         if (typeof ts === "string" && !this.lastActivity.has(id))
                             this.lastActivity.set(id, ts);
                     }
                 }
                 catch (e) {
-                    // missing sidecar (first boot) is EXPECTED — silent; a torn file / permission error degrades to an empty map
-                    // (createdAt ordering) but is WARNED (throttled, bug D) so disk-full/permission isn't hidden. Never throws.
                     if (e?.code !== "ENOENT")
                         this.warnSidecar("read", e);
                 }
@@ -231,59 +128,42 @@ export class LocalSessionStore {
         }
         return this.loaded;
     }
-    /** Queue a debounced, best-effort atomic write of the lastActivity map to the sidecar (coalesces touch bursts). The
-     *  write is fire-and-forget: a persistence failure must NEVER break the run path (touch is on the hot acquire path),
-     *  so errors are swallowed — the worst case is a restart falling back to createdAt ordering for un-flushed touches. */
     scheduleFlush() {
-        this.dirty = true; // a mutation landed — even mid-write, so the active write re-runs (bug B: don't drop it)
+        this.dirty = true;
         if (!this.sidecarPath || this.flushTimer)
             return;
         this.flushTimer = setTimeout(() => {
             this.flushTimer = undefined;
             void this.flush();
         }, 250);
-        this.flushTimer.unref?.(); // don't keep the process alive solely for a pending flush
-    }
-    /** Atomic best-effort write of the lastActivity map. SERIALIZED via {@link writeChain} (bug B): overlapping flushes
-     *  chain instead of racing, so an older snapshot can never rename after a newer one (lost-update), and a unique tmp
-     *  name per write means two writes can't tear each other's bytes. Returns the chain so callers (dispose) can await the
-     *  final write (bug C). Each link HYDRATES the disk sidecar first (bug A) and writes the UNION of disk + in-process —
-     *  the `has(id)` live-wins guard in ensureLoaded() keeps in-process touches authoritative — so a fresh-boot flush
-     *  before any list never CLOBBERS the prior boot's recency for not-yet-touched sessions. */
+        this.flushTimer.unref?.();
+    }
     flush() {
         if (!this.sidecarPath)
             return Promise.resolve();
         const next = this.writeChain.then(() => this.doFlush());
-        this.writeChain = next.catch(() => { }); // a failed write must not poison the chain (next flush still runs)
+        this.writeChain = next.catch(() => { });
         return next;
     }
-    /** One serialized sidecar write: hydrate-then-merge (bug A), snapshot, atomic tmp+rename with a UNIQUE tmp name (bug
-     *  B). Clears {@link dirty} for the change it captured; re-runs once if a touch landed mid-write so it's not dropped. */
     async doFlush() {
         const path = this.sidecarPath;
         if (!path)
             return;
-        // bug A: merge the on-disk sidecar BEFORE snapshotting so we never overwrite another boot's recency with an empty
-        // (or partial) in-process map. ensureLoaded()'s `!has(id)` guard keeps live in-process touches authoritative.
         await this.ensureLoaded();
-        this.dirty = false; // capture: a touch AFTER this point flips it back on → we re-run below
+        this.dirty = false;
         const snapshot = Object.fromEntries(this.lastActivity);
         try {
             await mkdir(join(path, ".."), { recursive: true });
-            // bug B: unique tmp per write (pid + monotonic counter) — overlapping/successive writes can't share one tmp path.
             const tmp = `${path}.${process.pid}.${++this.writeSeq}.tmp`;
             await writeFile(tmp, JSON.stringify(snapshot), "utf8");
-            await rename(tmp, path); // atomic swap (POSIX rename) — readers see the whole file or the prior one
+            await rename(tmp, path);
         }
         catch (e) {
-            this.warnSidecar("write", e); // bug D: surface disk-full/permission (throttled) instead of silent swallow
-            // best-effort: a persistence failure degrades restart-recency, never breaks the run path.
+            this.warnSidecar("write", e);
         }
         if (this.dirty)
-            await this.doFlush(); // a touch landed during the write — re-run so it isn't lost (bug B)
+            await this.doFlush();
     }
-    /** Throttled best-effort warn for a sidecar I/O failure (bug D): never throws, at most once per ~minute so a
-     *  persistently-failing disk doesn't spam the log on every debounced flush. */
     warnSidecar(op, e) {
         const now = Date.now();
         if (now - this.lastWarnAt < 60_000)
@@ -298,9 +178,6 @@ export class LocalSessionStore {
             this.owners.set(id, null);
             return { session: session, sessionId: id };
         }
-        // design/114 Phase3 (F1): a `requireExisting` acquire NEVER creates and can REJECT (not_found) — it MUST bypass
-        // the shared create-dedup `pending`, else a concurrent create-capable waiter awaiting that same promise would
-        // inherit the not_found rejection instead of creating-on-miss. (Twin of TiDBSessionStore.acquire.)
         if (opts?.requireExisting)
             return this.load(sessionId, true);
         const inflight = this.pending.get(sessionId);
@@ -311,8 +188,6 @@ export class LocalSessionStore {
         return p;
     }
     async load(sessionId, requireExisting = false) {
-        // open() throws SessionError("not_found") for an unknown id — create it ownerless then (a caller-chosen brand-new
-        // id the service didn't pre-register; only the caller who chose it can reach it, and it holds no prior data).
         try {
             const session = await this.repo.open({ id: sessionId, createdAt: "" });
             if (!this.owners.has(sessionId))
@@ -322,28 +197,17 @@ export class LocalSessionStore {
         catch (e) {
             if (!isNotFound(e))
                 throw e;
-            // design/114 Phase3: `requireExisting` ⇒ FAIL LOUD on a genuinely missing session, never the silent
-            // create-on-miss. Re-throw the store's own `not_found` SessionError; core maps it to `resume.session_not_found`.
             if (requireExisting)
                 throw e;
             const session = await this.repo.create({ id: sessionId });
-            // GUARD: mirror the open branch — NEVER clobber an owner a prior register() recorded
-            // (the TiDB twin's load() re-registers ownerless via an idempotent no-op upsert). Without the guard, a
-            // register(id, principal)-then-acquire(id) [the §0.5 auth flow] would reset owner→null on first acquire →
-            // ownership gate goes silent → cross-principal attach. (register() now also creates the repo session, so this
-            // catch only fires for a genuinely-unregistered id — but guard it defensively regardless.)
             if (!this.owners.has(sessionId))
                 this.owners.set(sessionId, null);
             return { session: session, sessionId };
         }
     }
-    /** Idempotently record a session's owner — never overwrites an existing owner (mirrors TiDBSessionStore.register).
-     *  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. */
     async register(sessionId, owner) {
         if (this.owners.has(sessionId))
-            return; // idempotent — never touch an already-known session's owner
+            return;
         this.owners.set(sessionId, owner);
         try {
             await this.repo.open({ id: sessionId, createdAt: "" });
@@ -355,13 +219,6 @@ export class LocalSessionStore {
                 throw e;
         }
     }
-    /** Owner of a session: `null` if registered ownerless, `undefined` if no such session (mirrors TiDBSessionStore.ownerOf).
-     *
-     *  S3 修(clay 裁 2026-07-26:**local=单用户,多租户走云** ⇒ 跨重启不承诺 owner 隔离):`owners` 是纯内存
-     *  Map,重启后失忆——曾把「失忆」答成 `undefined`(=「无此会话」),让 DELETE /v1/sessions 的 route 门短路成
-     *  already-gone、checkpoint 的 EXISTS 镜像门 return 0 ⇒ **E21 对盘上老会话整体 no-op 且无人知道**。
-     *  现在 Map miss 时探 repo:盘上在 ⇒ 按 load() 两处懒回填早已写下的同一判据回填 `null`(registered
-     *  ownerless);repo 真没有才 `undefined`。SQL 孪生无此形(owner 在 session_meta 行,重启无损)。 */
     async ownerOf(sessionId) {
         if (this.owners.has(sessionId))
             return this.owners.get(sessionId) ?? null;
@@ -376,30 +233,23 @@ export class LocalSessionStore {
             throw e;
         }
     }
-    /** [1196] 六轮复审:owner+leafId 原子快照——单线程 JS 内两同步/顺序读之间无 await 打断 owner 判定
-     *  (owner 先取快照,leaf 读后 owner 复核,变了=undefined 视作删除中,调用方按删处理)。 */
     async getHead(sessionId) {
-        // S3 同根:Map miss ≠ 无此会话 —— 经 ownerOf 的 repo 探在腿判定(盘上在 ⇒ 回填 ownerless 后继续)。
         if (!this.owners.has(sessionId) && (await this.ownerOf(sessionId)) === undefined)
             return undefined;
         const owner = this.owners.get(sessionId) ?? null;
         const leafId = await this.getLeafId(sessionId);
         if (!this.owners.has(sessionId) || (this.owners.get(sessionId) ?? null) !== owner)
-            return undefined; // 读间被删/换主
+            return undefined;
         return { owner, leafId };
     }
-    /** 2c P1d-β — re-stamp the service-side owner scope 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). */
     restampOwner(sessionId, owner) {
         if (this.owners.has(sessionId))
             this.owners.set(sessionId, owner);
     }
     async touch(sessionId) {
         this.lastActivity.set(sessionId, new Date().toISOString());
-        this.scheduleFlush(); // persist the recency marker so the /resume picker's order survives a restart (TOC #10)
+        this.scheduleFlush();
     }
-    /** 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. */
     async getLeafId(sessionId) {
         try {
             const session = await this.repo.open({ id: sessionId, createdAt: "" });
@@ -411,40 +261,18 @@ export class LocalSessionStore {
             throw e;
         }
     }
-    /** Durable history is retained by the repo; just drop the in-flight cache entry (mirrors TiDBSessionStore.release). */
     async release(sessionId) {
         this.pending.delete(sessionId);
     }
-    /**
-     * P0.5 variant-2 (E16, clay 2026-06-26) — enumerate the caller's sessions (CC /resume picker) from the SESSION
-     * abstraction (`repo.list()`), keyset-paginated newest-first by last activity. Session IDENTITY comes from the
-     * repo (one entry per persisted session); a {@link SessionSummary} is SYNTHESIZED per id so the wire shape is
-     * byte-identical to {@link TiDBSessionStore.listSessions} (the run picker doesn't drift):
-     *   - `owner`           — the service-side owner map (process-local; null when unknown/ownerless). Owner FILTERING
-     *                          is best-effort here (the in-memory map IS the source of truth; a single-user local
-     *                          deployment runs REQUIRE_PRINCIPAL=off so the principal path passes owner=null and every
-     *                          null-owner session lists). The route already owner-gates at the HTTP layer.
-     *   - `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` — DEGRADED (0 / ""): the session abstraction has no runs ledger; the TiDB twin
-     *                          LEFT-JOINs `task_run` for these, which the local backend (MemoryRunStore, separate
-     *                          ledger) intentionally does NOT correlate here (variant-2 is session-abstraction-only).
-     *
-     * Keyset matches the contract: STRICTLY older than the cursor, ties broken by id DESC; `limit` is honored after
-     * the in-memory sort. Cheap (a local single-user store holds few sessions). Errors reading one session's entries
-     * degrade that row's preview to null rather than failing the whole list.
-     */
     async listSessions(opts) {
-        await this.ensureLoaded(); // hydrate persisted lastActivity BEFORE reading it — else a restart loses recency order (TOC #10)
+        await this.ensureLoaded();
         await this.ensureTitlesLoaded();
         const metas = await this.repo.list();
-        // Build a summary per persisted session, owner from the process-local map (degrade to null when unknown).
         const all = [];
         for (const meta of metas) {
             const owner = this.owners.has(meta.id) ? (this.owners.get(meta.id) ?? null) : null;
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
-                continue; // owner-scope (best-effort, process-local map) + [4198] 窄臂第三条件
+                continue;
             const firstActivityAt = meta.createdAt || new Date(0).toISOString();
             const lastActivityAt = this.lastActivity.get(meta.id) ?? firstActivityAt;
             all.push({
@@ -452,43 +280,31 @@ export class LocalSessionStore {
                 owner,
                 lastActivityAt,
                 firstActivityAt,
-                runCount: 0, // session abstraction has no runs ledger (honest degrade; TiDB twin LEFT-JOINs task_run)
+                runCount: 0,
                 objectivePreview: await this.previewOf(meta),
-                lastStatus: "", // no run status without the runs ledger (honest degrade — matches TiDB's null→"" mapping)
-                lastRunId: this.lastTaskRun.get(meta.id) ?? null, // K-5c: latest run id from the noteTaskRun seam (null if none)
-                title: this.titleState.titles.get(meta.id) ?? null, // auto-title
+                lastStatus: "",
+                lastRunId: this.lastTaskRun.get(meta.id) ?? null,
+                title: this.titleState.titles.get(meta.id) ?? null,
             });
         }
-        // `?q=` — the local twin matches the synthesized objectivePreview (the last user text; the
-        // SQL twins match ANY run's preview via the runs ledger — each backend searches what it durably has).
-        // Filter BEFORE the sort/keyset slice so pagination stays correct.
         const qlc = opts.q?.toLowerCase();
         const filtered = qlc ? all.filter((r) => r.objectivePreview?.toLowerCase().includes(qlc)) : all;
-        // newest-first by (lastActivityAt, sessionId) — same ORDER BY the SQL twin emits.
         filtered.sort((a, b) => a.lastActivityAt !== b.lastActivityAt
             ? (a.lastActivityAt < b.lastActivityAt ? 1 : -1)
             : (a.sessionId < b.sessionId ? 1 : -1));
-        // keyset: keep rows STRICTLY older than the cursor (ties by id DESC), then honor limit (mirrors the SQL WHERE).
         const c = opts.cursor;
         const after = c
             ? filtered.filter((r) => r.lastActivityAt < c.lastActivityAt || (r.lastActivityAt === c.lastActivityAt && r.sessionId < c.sessionId))
             : filtered;
         return after.slice(0, opts.limit);
     }
-    /** K-5c (core 1.155 SessionStore seam): core's Runner calls this at runTask START with the run's taskId, so the
-     *  latest run surfaces as `lastRunId` on listSessions even while it is still running/suspended (the local backend
-     *  has no runs ledger to derive it from, unlike the TiDB/PG twins). In-memory, last-write-wins per session. */
     noteTaskRun(sessionId, taskId) {
         this.lastTaskRun.set(sessionId, taskId);
     }
-    /** 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). */
     async previewOf(meta) {
         try {
             const session = await this.repo.open({ id: meta.id, createdAt: meta.createdAt });
             const entries = await session.getEntries();
-            // Walk newest-first; the most recent USER message is the objective (mirrors task_run.objective_preview). A
-            // session with no user turn yet (e.g. registered-but-never-run) → null preview (honest empty, like the picker).
             for (let i = entries.length - 1; i >= 0; i--) {
                 const text = userText(entries[i]);
                 if (text)
@@ -497,12 +313,9 @@ export class LocalSessionStore {
             return null;
         }
         catch {
-            // best-effort: a missing/torn/unreadable session lists without a preview rather than failing the whole picker.
             return null;
         }
     }
-    /** 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). */
     async fork(sourceId, owner) {
         try {
             const session = await this.repo.fork({ id: sourceId, createdAt: "" }, {});
@@ -516,104 +329,60 @@ export class LocalSessionStore {
             throw e;
         }
     }
-    /** 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. */
     async exportEntries(sessionId) {
         if (!this.repo.exportEntries)
-            return null; // a repo without the optional seam can't export (older core)
+            return null;
         try {
             return await this.repo.exportEntries(sessionId);
         }
         catch (e) {
             if (isNotFound(e))
-                return null; // unknown source ⇒ null (mirrors fork's 404 semantics)
+                return null;
             throw e;
         }
     }
-    /** 2c session-sync P1d-α (PULL streaming) — the IDS-ONLY projection of the full durable log (@see
-     *  TiDBSessionStore.listEntryIds). The local repo holds the whole log in memory/file so there is no floor to bypass;
-     *  ids are the `exportEntries` ids in order. null if the source is unknown / the repo lacks the export seam. */
     async listEntryIds(sessionId) {
         const entries = await this.exportEntries(sessionId);
         return entries === null ? null : entries.map((e) => e.id);
     }
-    /** 2c session-sync P1d-α (PULL streaming) — STREAM the full durable log as an async generator (@see
-     *  TiDBSessionStore.exportEntriesStream). The LOCAL twin has no cross-instance buffering hazard (an in-memory map /
-     *  single-process file repo), so it reads the whole log via the repo's `exportEntries` then yields it lazily, SLICED
-     *  after `opts.afterSeq` (the LOCAL backend's native seq = the 0-based dense ARRAY INDEX of the entry in the
-     *  oldest-first log; afterSeq=k → entries at index > k = `slice(k+1)`). afterSeq is a BACKEND-NATIVE seq cursor (a
-     *  resume is always same-backend), so the local 0-based-index base needn't match the durable backends' `seq` column
-     *  base. Resolves to null (NOT an empty iterable) for an unknown session — mirrors {@link exportEntries}.
-     *  `opts.batchSize` is accepted for API parity but has no effect locally (the whole log is already in hand). */
     async exportEntriesStream(sessionId, opts) {
         const entries = await this.exportEntries(sessionId);
         if (entries === null)
-            return null; // unknown session — NOT an empty iterable
-        const afterSeq = opts?.afterSeq ?? -1; // 0-based dense → > -1 = from index 0
-        const slice = entries.slice(afterSeq + 1); // afterSeq=k yields entries k+1..end (seq = array index for the local repo)
+            return null;
+        const afterSeq = opts?.afterSeq ?? -1;
+        const slice = entries.slice(afterSeq + 1);
         async function* gen() {
             for (const e of slice)
                 yield e;
         }
         return gen();
     }
-    /** 2c session-sync — IMPORT a verbatim entry log into `sessionId` via core `SessionRepo.importEntries`
-     *  (which runs the `validateEntriesForImport` fail-closed gate before writing). `owner` is the authenticated
-     *  importing principal (re-stamped into the service-side owner map; core's local repo has no owner column, §9).
-     *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`). */
     async importEntries(sessionId, owner, entries) {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
-        await this.repo.importEntries(sessionId, owner ?? undefined, entries); // core gate runs inside; throws invalid_session on violation
-        this.owners.set(sessionId, owner); // re-stamp the service-side owner scope to the importing principal
-    }
-    /** 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
-     *  with NO compaction floor / cross-instance race (a process-local in-memory map / a single-process file repo), so
-     *  deleteSession-then-importEntries is effectively atomic for the local case (no concurrent reader can observe the
-     *  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). */
+        await this.repo.importEntries(sessionId, owner ?? undefined, entries);
+        this.owners.set(sessionId, owner);
+    }
     async replaceEntries(sessionId, owner, entries) {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
         if (!this.repo.delete)
             throw new SessionError("storage", "session replace is not supported by this local backend (no delete seam)");
-        // VALIDATE-FIRST (before the delete): the durable twins run validateEntriesForImport INSIDE a txn that ROLLs BACK on
-        // a bad import, so a failed import can't destroy the existing session. The local twin is delete-then-import (no
-        // single-writer txn), so an invalid bundle — the COMMON failure — must be rejected BEFORE deleteSession purges the
-        // prior session; otherwise a bad import would purge-then-fail and the existing session would be gone. (A post-delete
-        // fs I/O failure on importEntries remains a residual single-writer risk the durable twins don't have — noted.)
         validateEntriesForImport(entries);
-        // We purge first so the subsequent import can't hit a duplicate-id collision over an existing session. delete on an
-        // absent session is a no-op (deleteSession swallows not_found below), so replace over a fresh session is just an
-        // import. importEntries re-runs the (now-known-valid) core gate before writing.
-        await this.deleteSession(sessionId, owner); // owner-guarded purge (defense-in-depth, single-user: owner=null matches)
-        await this.importEntries(sessionId, owner, entries); // core gate runs inside + re-stamps the owner scope
-    }
-    /** 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
-     *  whole-bundle local import uses (effectively atomic locally — no concurrent reader can observe the gap). Keep it
-     *  simple per §1: the durable twins are where the SHADOW-id swap + bounded-memory + concurrency matter. */
+        await this.deleteSession(sessionId, owner);
+        await this.importEntries(sessionId, owner, entries);
+    }
     beginImportStaging(realSessionId, token) {
         const h = new LocalStagingHandle(this, realSessionId, stagingIdFor(realSessionId, token));
         this.stagings.set(h.stagingId, h);
         return h;
     }
-    /** 2c P1d-β (staged-row inspection) — the in-memory staged entries for a local staging id. No longer the import gate
-     *  (the per-line StreamingImportValidator validates during the Phase-B stream); a tests/diagnostics seam. [] for an
-     *  unknown/finished staging id (mirrors the durable twins' empty-set return). */
     async readStagedEntries(stagingId) {
         return this.stagings.get(stagingId)?.snapshotEntries() ?? [];
     }
-    /** Drop a finished/aborted local staging handle from the registry (called by the handle on commit/abort). */
     forgetStaging(stagingId) {
         this.stagings.delete(stagingId);
     }
-    /** 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. */
     async deleteSession(sessionId, owner) {
         const known = this.owners.has(sessionId);
         if (!known || !ownerEq(this.owners.get(sessionId) ?? null, owner))
@@ -627,50 +396,30 @@ export class LocalSessionStore {
         }
         this.owners.delete(sessionId);
         this.lastActivity.delete(sessionId);
-        this.lastTaskRun.delete(sessionId); // K-5c (review): drop the run anchor too — else the map grows on delete churn
-        // and a re-acquire(sameId) would surface the PRIOR incarnation's lastRunId (stale anchor).
-        // Drop the auto-title too (E21 parity with the SQL twins' session_meta row delete) and
-        // persist the removal through the SAME serialized chain (an in-flight grant snapshot must not rename
-        // AFTER this removal and resurrect it — the chain re-snapshots the map, so the delete always wins).
-        // 🔴 hydrate FIRST (workflow audit 2026-07-13): after a restart the map starts empty — an un-hydrated
-        // delete() returns false and the sidecar keeps the title (an E21 right-to-delete residue that would
-        // RESURRECT onto a same-id re-import). ensureTitlesLoaded is memoized — first caller pays, rest no-op.
+        this.lastTaskRun.delete(sessionId);
         await this.ensureTitlesLoaded();
         if (this.titleState.titles.delete(sessionId))
             await this.persistTitles();
-        this.scheduleFlush(); // persist the removal so a deleted session doesn't linger in the sidecar across a restart
+        this.scheduleFlush();
         return true;
     }
     get size() {
         return this.pending.size;
     }
-    /** 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). */
     async dispose() {
         this.pending.clear();
         if (this.flushTimer) {
             clearTimeout(this.flushTimer);
             this.flushTimer = undefined;
         }
-        // Always do a final flush when persisting (a pending debounce OR an in-flight write may hold the last touch); when
-        // not persisting it's a cheap no-op. AWAIT it (and the chain) so close() can't release the data-dir lock first.
         if (this.sidecarPath)
             await this.flush();
     }
 }
-/**
- * 2c session-sync P1d-β — the LOCAL {@link StagingHandle}. Unlike the durable twins (which stage into a shadow
- * session_event partition + atomically rename it), the local backend is single-writer with no cross-instance race, so
- * this handle ACCUMULATES the streamed batches in memory (idempotent on entry id — a re-streamed batch is deduped) and,
- * on commit, runs the SAME validate-first → replaceEntries the whole-bundle local import uses (the existing
- * delete-then-import that is effectively atomic for the single-process local case). It still re-classifies AT COMMIT
- * (against the dst's current ids) so an unconsented fork/stale is refused, matching the durable twins' contract.
- */
 class LocalStagingHandle {
     store;
     realSessionId;
     stagingId;
-    /** Accumulated staged entries, deduped by entry id (resume re-streams from the start → dedup keeps it idempotent). */
     staged = [];
     seen = new Set();
     constructor(store, realSessionId, stagingId) {
@@ -681,47 +430,36 @@ class LocalStagingHandle {
     async appendBatch(entries) {
         for (const e of entries) {
             if (this.seen.has(e.id))
-                continue; // idempotent (resume re-stream) — dedup by entry id
+                continue;
             this.seen.add(e.id);
             this.staged.push(e);
         }
     }
-    /** The staged entries, oldest-first (readStagedEntries reads these). A snapshot copy (callers don't mutate). */
     snapshotEntries() {
         return [...this.staged];
     }
-    /** Commit = in-commit re-classify (dst current ids vs staged) → refuse an unconsented fork/stale → validate + the
-     *  idempotent replaceEntries (validate-first-then-delete-then-import, effectively atomic locally). */
     async commit(owner, opts) {
         const dstEntries = await this.store.exportEntries(this.realSessionId);
         const rel = classifySyncRelationshipByIds(this.staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
         if ((rel.relation === "fork" || rel.relation === "stale") && opts?.resolution !== "overwrite-dst") {
             throw new SyncConflictError(this.realSessionId, rel);
         }
-        // 🔴 [2557] A5/F2(2026-08-05):fast_forward 的**载荷**盲区 —— dst ⊆ src 按 id,但共享 id 的
-        // 内容可能已分叉(目的端纠正过某条、源端拿旧版+追加)。整段换装会静默销毁目的端的纠正,
-        // §7 在载荷层同样要求 409(除非显式 overwrite-dst)。判据与铸形见 session-sync-content.ts。
         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(this.staged.filter((e) => dstSet.has(e.id)), dstEntries);
             if (diverged)
                 throw new SyncConflictError(this.realSessionId, contentForkRelation(diverged, rel.newEntryIds));
         }
-        // 🔴 2026-07-26:`identical` 不再等于"内容相同"。id 是 uuidv7、不是内容寻址 ⇒ 同 id 异载荷完全可能,
-        // 而 commit 这里**手上同时有两份日志**,所以内容比较不需要调用方配合(见 `session-sync-content.ts` 顶注:
-        // 我在黑板 [1701] 说过"server 单方面修不了",那句只对 Phase A 成立,对这一半是错的)。
-        // 判据不符 ⇒ **照常改写**(不抛错、不 409 —— core 定的口径是"不符只意味着多干一趟活")。
         const contentEqual = rel.relation === "identical" && identicalIdsAlsoIdenticalContent(this.staged, dstEntries);
         if (rel.relation !== "identical" || !contentEqual) {
-            await this.store.replaceEntries(this.realSessionId, owner, this.staged); // validate-first + delete-then-import (atomic locally)
+            await this.store.replaceEntries(this.realSessionId, owner, this.staged);
         }
         else {
-            this.store.restampOwner(this.realSessionId, owner); // 内容也相同 ⇒ 只重戳 owner(此时跳过写入是对的)
+            this.store.restampOwner(this.realSessionId, owner);
         }
         this.store.forgetStaging(this.stagingId);
         return { relation: rel.relation };
     }
-    /** Abort = drop the in-memory staged buffer (no durable rows were ever written locally) + forget the handle. */
     async abort() {
         this.staged.length = 0;
         this.seen.clear();