@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,10 +1,42 @@
+/**
+ * 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 { identicalIdsAlsoIdenticalContent } from "../session-sync-content.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;
@@ -24,34 +56,88 @@ 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;
+    /** 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;
@@ -63,7 +149,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);
+                            st.titles.set(id, t); // live writes win over disk
                     }
                 }
                 catch (e) {
@@ -74,6 +160,8 @@ 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();
@@ -91,10 +179,15 @@ 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;
@@ -104,6 +197,9 @@ 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;
@@ -114,11 +210,14 @@ 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);
                 }
@@ -126,42 +225,59 @@ 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;
+        this.dirty = true; // a mutation landed — even mid-write, so the active write re-runs (bug B: don't drop it)
         if (!this.sidecarPath || this.flushTimer)
             return;
         this.flushTimer = setTimeout(() => {
             this.flushTimer = undefined;
             void this.flush();
         }, 250);
-        this.flushTimer.unref?.();
-    }
+        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. */
     flush() {
         if (!this.sidecarPath)
             return Promise.resolve();
         const next = this.writeChain.then(() => this.doFlush());
-        this.writeChain = next.catch(() => { });
+        this.writeChain = next.catch(() => { }); // a failed write must not poison the chain (next flush still runs)
         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;
+        this.dirty = false; // capture: a touch AFTER this point flips it back on → we re-run below
         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);
+            await rename(tmp, path); // atomic swap (POSIX rename) — readers see the whole file or the prior one
         }
         catch (e) {
-            this.warnSidecar("write", 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.
         }
         if (this.dirty)
-            await this.doFlush();
+            await this.doFlush(); // a touch landed during the write — re-run so it isn't lost (bug B)
     }
+    /** 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)
@@ -176,6 +292,9 @@ 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);
@@ -186,6 +305,8 @@ 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))
@@ -195,17 +316,28 @@ 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;
+            return; // idempotent — never touch an already-known session's owner
         this.owners.set(sessionId, owner);
         try {
             await this.repo.open({ id: sessionId, createdAt: "" });
@@ -217,6 +349,13 @@ 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;
@@ -231,23 +370,30 @@ 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();
+        this.scheduleFlush(); // persist the recency marker so the /resume picker's order survives a restart (TOC #10)
     }
+    /** 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: "" });
@@ -259,18 +405,40 @@ 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();
+        await this.ensureLoaded(); // hydrate persisted lastActivity BEFORE reading it — else a restart loses recency order (TOC #10)
         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)
-                continue;
+                continue; // owner-scope (best-effort, process-local map)
             const firstActivityAt = meta.createdAt || new Date(0).toISOString();
             const lastActivityAt = this.lastActivity.get(meta.id) ?? firstActivityAt;
             all.push({
@@ -278,31 +446,43 @@ export class LocalSessionStore {
                 owner,
                 lastActivityAt,
                 firstActivityAt,
-                runCount: 0,
+                runCount: 0, // session abstraction has no runs ledger (honest degrade; TiDB twin LEFT-JOINs task_run)
                 objectivePreview: await this.previewOf(meta),
-                lastStatus: "",
-                lastRunId: this.lastTaskRun.get(meta.id) ?? null,
-                title: this.titleState.titles.get(meta.id) ?? null,
+                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
             });
         }
+        // `?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)
@@ -311,9 +491,12 @@ 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: "" }, {});
@@ -327,60 +510,104 @@ 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;
+            return null; // a repo without the optional seam can't export (older core)
         try {
             return await this.repo.exportEntries(sessionId);
         }
         catch (e) {
             if (isNotFound(e))
-                return null;
+                return null; // unknown source ⇒ null (mirrors fork's 404 semantics)
             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;
-        const afterSeq = opts?.afterSeq ?? -1;
-        const slice = entries.slice(afterSeq + 1);
+            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)
         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);
-        this.owners.set(sessionId, owner);
-    }
+        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). */
     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);
-        await this.deleteSession(sessionId, owner);
-        await this.importEntries(sessionId, owner, 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. */
     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))
@@ -394,30 +621,50 @@ export class LocalSessionStore {
         }
         this.owners.delete(sessionId);
         this.lastActivity.delete(sessionId);
-        this.lastTaskRun.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.
         await this.ensureTitlesLoaded();
         if (this.titleState.titles.delete(sessionId))
             await this.persistTitles();
-        this.scheduleFlush();
+        this.scheduleFlush(); // persist the removal so a deleted session doesn't linger in the sidecar across a restart
         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) {
@@ -428,30 +675,38 @@ class LocalStagingHandle {
     async appendBatch(entries) {
         for (const e of entries) {
             if (this.seen.has(e.id))
-                continue;
+                continue; // idempotent (resume re-stream) — dedup by entry id
             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);
         }
+        // 🔴 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);
+            await this.store.replaceEntries(this.realSessionId, owner, this.staged); // validate-first + delete-then-import (atomic locally)
         }
         else {
-            this.store.restampOwner(this.realSessionId, owner);
+            this.store.restampOwner(this.realSessionId, owner); // 内容也相同 ⇒ 只重戳 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();