@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,7 +1,10 @@
 import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "@sema-agent/core";
 import { type PendingCheckpoint } from "./tidb-checkpoint-store.js";
 export interface LocalCheckpointStoreOptions {
+    /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
     getActiveTaskId?: (sessionId: string) => Promise<string | undefined>;
+    /** E21 owner guard (the LocalSessionStore's `ownerOf`). Absent ⇒ owner guard degrades to null-owner-only
+     *  (a non-null owner with no owner source purges NOTHING — fail-closed, mirrors the SQL EXISTS guard). */
     ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
 }
 export declare class LocalCheckpointStore {
@@ -11,9 +14,18 @@ export declare class LocalCheckpointStore {
     private readonly ctxDir;
     private readonly tmpDir;
     private readonly scopes;
+    /** [868] sessionId → every token ever put for it — the service-side index that stands in for the SQL twins'
+     *  `WHERE checkpoint.session_id = ?` on NON-pending rows (core's File store enumerates pending only via
+     *  listByScope; get(token) is the sole read for resolved/expired rows, so cross-status session queries need
+     *  this registry). Registered BEFORE the inner put (same crash direction as the scopes registry: a stale
+     *  index entry is a harmless empty lookup; an unindexed EXPIRED row would silently disable the
+     *  failSuspendedWithExpiredCheckpoint leg — the bad direction). Persisted so a restart keeps the
+     *  suspend→crash→expire-later lifecycle visible. Entries are never dropped while the inner row exists
+     *  (a `resolved` row can be reopen()ed back to pending — pruning it would be wrong). */
     private readonly sessionTokens;
     private readonly opts;
     constructor(root: string, opts?: LocalCheckpointStoreOptions);
+    /** Persist the session→tokens index (whole-file atomic replace — puts are per-suspend, low frequency). */
     private persistSessionTokens;
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
     get(token: CheckpointToken): Promise<Checkpoint | null>;
@@ -27,21 +39,49 @@ export declare class LocalCheckpointStore {
     reap(scope: string, cutoff: number): Promise<number>;
     listByScope(scope: string): Promise<CheckpointSummary[]>;
     close(): void;
+    /** C4-B:注册表损坏时从**数据本体**懒重建 scope 集(core 1.424 `listScopes?` = 「有 ≥1 条 pending 的
+     *  distinct scope 集」,与 listByScope 可见面对齐 —— 恰好是本注册表要的内容)。一次性:重建后回写
+     *  sidecar,恢复正常路径。seam 缺席(第三方旧 inner)⇒ 保持 C 案的可见降级,不装恢复了。 */
     private scopeRegistryCorrupt;
     private ensureScopesRebuilt;
+    /** All still-pending checkpoints across the registered scopes (summary + full row via get). */
     private pendings;
+    /** Operator approval queue — the same NON-secret card as the SQL twins (never the token). */
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
     findPendingTokenBySession(sessionId: string, scope?: string): Promise<CheckpointToken | null>;
+    /** [868] read-only probe face: does this session have an EXPIRED checkpoint row? The local twin of the SQL
+     *  `EXISTS (SELECT 1 FROM checkpoint ce WHERE ce.session_id = ? AND ce.status = 'expired')` that drives the
+     *  run stores' failSuspendedWithExpiredCheckpoint. Scans the session→token index (get(token) is the only
+     *  cross-status read core's File store offers); an index entry whose inner row vanished is pruned lazily.
+     *  Backed by a persisted registry, so it stays honest — never a guessed "true".
+     *  ⚠️ 存量限制(codex M2,如实):索引随 put 增量建立,无升级迁移——本版本部署前已存在的 checkpoint 不在
+     *  索引里,其 expired 对本探针不可见(core File store 的 listByScope 是 pending-only,无法枚举历史行回填)。
+     *  旧存量锁死的恢复把手 = cancel verb([868]①,不依赖本索引);增量行全覆盖。 */
     hasExpiredBySession(sessionId: string): Promise<boolean>;
+    /** `undefined` = no pending row; else the owner scope (local scopes are always strings — never null). */
     peekPendingScope(sessionId: string): Promise<string | null | undefined>;
+    /**
+     * design/80 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 branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
+     */
     reapExpired(cutoff: number): Promise<number>;
+    /** design/80 D-D SLA deny-sweep input — pending human/irreversible_ask gates past deadline (excl. AskUserQuestion). */
     listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
         sessionId: string;
         scope: string;
     }>>;
     putCtx(sessionId: string, ctx: unknown): Promise<void>;
     getCtx<T = unknown>(sessionId: string): Promise<T | null>;
+    /** GC ctx files whose lifecycle is over — same three guards as the SQL twins (stale ∧ no pending ∧ no active run). */
     reapCtx(cutoff: number): Promise<number>;
+    /**
+     * E21 session purge — functional contract: a deleted session has no resumable future. Expires every pending
+     * gate of the session (all scopes) + unlinks its ctx file. Owner guard mirrors the SQL EXISTS guard: with an
+     * `ownerOf` source the owner must null-safe-match; without one, only an ownerless call (owner=null) purges.
+     * Returns the number of gates expired. (Terminal ledger history stays on disk — local transcripts posture.)
+     */
     deleteBySession(sessionId: string, owner: string | null): Promise<number>;
 }
 //# sourceMappingURL=local-checkpoint-store.d.ts.map

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

@@ -1,11 +1,35 @@
+/**
+ * LOCAL (file-backed) checkpoint store — EnterPlanMode / durable HITL for the TOC local lane.
+ *
+ * Shape: core's `FileCheckpointStore` (crash-safe ledger+snapshot, per-token CAS — the ENGINE contract) is the
+ * inner authority; this wrapper adds the SERVICE half the SQL twins carry (operator queue / session lookups /
+ * resume ctx / reapers) WITHOUT re-implementing any core abstraction ([[core-service-boundary]]: engine contract
+ * stays core's; wire/ops glue is ours).
+ *
+ * Enumeration seam: core's File store exposes only `listByScope(scope)` (pending-only summaries) + `get(token)`.
+ * Cross-scope queries (fleet listPending / reapExpired / session lookups) therefore ride a service-side SCOPES
+ * REGISTRY: `put` records each scope once into `checkpoint-scopes.json` (registered BEFORE the inner put so a
+ * crash can't leave an unenumerable pending row; a scope whose rows are gone is harmless — its listByScope is
+ * simply empty). Projection fields come from `get(token)` (the full Checkpoint), so listPending serves the same
+ * non-secret card as the SQL twins (shared `boundedToolInput` bound, same severity-DESC sort).
+ *
+ * Honest degrades (documented, single-user local lane):
+ *  - `deleteBySession` EXPIRES the session's pending gates + unlinks its ctx file — the ledger/snapshot keeps
+ *    terminal history like the local tool-result/transcript stores do (no physical row delete primitive in
+ *    core's File store; the E21 functional contract — "a deleted session has no resumable future" — holds).
+ *  - `taskId` on the pending card comes from an injected `getActiveTaskId` (the local FileRunStore) — `null`
+ *    when not wired, which every consumer already tolerates.
+ */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { FileCheckpointStore, atomicWriteFile, sanitizePathComponent, } from "@sema-agent/core";
 import { boundedToolInput, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./tidb-checkpoint-store.js";
+/** design/80 D-D read-time twin of the TiDB put-time `terminal_at` column (same formula — anti-drift). */
 function terminalAtOf(cp) {
     return Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS);
 }
+/** Collision-proof ctx filename: readable prefix + content hash of the FULL sessionId (sanitize can collide). */
 function ctxFileOf(sessionId) {
     return `${sanitizePathComponent(sessionId).slice(0, 48)}-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}.json`;
 }
@@ -16,6 +40,14 @@ export class LocalCheckpointStore {
     ctxDir;
     tmpDir;
     scopes = new Set();
+    /** [868] sessionId → every token ever put for it — the service-side index that stands in for the SQL twins'
+     *  `WHERE checkpoint.session_id = ?` on NON-pending rows (core's File store enumerates pending only via
+     *  listByScope; get(token) is the sole read for resolved/expired rows, so cross-status session queries need
+     *  this registry). Registered BEFORE the inner put (same crash direction as the scopes registry: a stale
+     *  index entry is a harmless empty lookup; an unindexed EXPIRED row would silently disable the
+     *  failSuspendedWithExpiredCheckpoint leg — the bad direction). Persisted so a restart keeps the
+     *  suspend→crash→expire-later lifecycle visible. Entries are never dropped while the inner row exists
+     *  (a `resolved` row can be reopen()ed back to pending — pruning it would be wrong). */
     sessionTokens = new Map();
     opts;
     constructor(root, opts = {}) {
@@ -36,11 +68,18 @@ export class LocalCheckpointStore {
                             this.scopes.add(s);
             }
             catch (e) {
+                // C4(clay 裁 2026-07-26,C 先行 + B 根治):此前这里静默吞 ⇒ 存量待决审批整体从枚举面隐身,
+                // 操作员看到的是**空列表而不是错误**,没人会对空列表排障。处置两层:
+                // ①fail-visible(C):warn 大声 + 坏文件改名隔离留证(也防下一次 put 的整写把证据盖掉);
+                // ②重建(B,core 1.424 `listScopes?` seam,[1800]② 索 → [1803] 交付):constructor 是同步的,
+                //   重建挂在读路径懒执行一次(见 ensureScopesRebuilt)—— 从数据本体枚举 pending scope 集,
+                //   枚举面完整恢复,不再依赖「下次 suspend 自愈」只救新件。
                 const quarantine = `${this.scopesPath}.corrupt-${Date.now()}`;
                 try {
                     renameSync(this.scopesPath, quarantine);
                 }
                 catch {
+                    /* 移不动就留原地 —— warn 里已给路径,人工可查 */
                 }
                 this.scopeRegistryCorrupt = true;
                 console.warn(`LocalCheckpointStore: checkpoint-scopes.json is corrupt (${e instanceof Error ? e.message : String(e)}) — ` +
@@ -60,17 +99,23 @@ export class LocalCheckpointStore {
                 }
             }
             catch {
+                /* a corrupt index only narrows hasExpiredBySession (fail-safe: the reaper skips, cancel still works) */
             }
         }
     }
+    /** Persist the session→tokens index (whole-file atomic replace — puts are per-suspend, low frequency). */
     persistSessionTokens() {
         atomicWriteFile(this.tmpDir, this.sessionTokensPath, JSON.stringify(Object.fromEntries([...this.sessionTokens].map(([sid, set]) => [sid, [...set]]))));
     }
+    // ─────────── core CheckpointStore contract — delegated to core's File store (the engine authority) ───────────
     async put(token, cp) {
+        // Register the scope BEFORE the inner commit: a crash between the two leaves a stale scope entry
+        // (harmless empty enumeration), never an unenumerable pending checkpoint (the bad direction).
         if (!this.scopes.has(cp.scope)) {
             this.scopes.add(cp.scope);
             atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
         }
+        // [868] session→token index, same before-the-inner-put crash rationale (see the field doc).
         if (!this.sessionTokens.get(cp.sessionId)?.has(token)) {
             const set = this.sessionTokens.get(cp.sessionId) ?? new Set();
             set.add(token);
@@ -103,13 +148,17 @@ export class LocalCheckpointStore {
     close() {
         this.inner.close();
     }
+    // ─────────── service extensions (the SQL twins' operator/ops half) ───────────
+    /** C4-B:注册表损坏时从**数据本体**懒重建 scope 集(core 1.424 `listScopes?` = 「有 ≥1 条 pending 的
+     *  distinct scope 集」,与 listByScope 可见面对齐 —— 恰好是本注册表要的内容)。一次性:重建后回写
+     *  sidecar,恢复正常路径。seam 缺席(第三方旧 inner)⇒ 保持 C 案的可见降级,不装恢复了。 */
     scopeRegistryCorrupt = false;
     async ensureScopesRebuilt() {
         if (!this.scopeRegistryCorrupt)
             return;
         const listScopes = this.inner.listScopes;
         if (typeof listScopes !== "function")
-            return;
+            return; // 无 seam:维持已 warn 的降级
         const rebuilt = await listScopes.call(this.inner);
         for (const s of rebuilt)
             this.scopes.add(s);
@@ -117,6 +166,7 @@ export class LocalCheckpointStore {
         atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
         console.warn(`LocalCheckpointStore: scope registry REBUILT from the data plane (${rebuilt.length} scope(s) with pending gates) — enumeration restored`);
     }
+    /** All still-pending checkpoints across the registered scopes (summary + full row via get). */
     async pendings(scope) {
         await this.ensureScopesRebuilt();
         const out = [];
@@ -130,6 +180,7 @@ export class LocalCheckpointStore {
         }
         return out;
     }
+    /** Operator approval queue — the same NON-secret card as the SQL twins (never the token). */
     async listPending(scope) {
         const rows = [];
         for (const { cp } of await this.pendings(scope)) {
@@ -150,6 +201,7 @@ export class LocalCheckpointStore {
                 riskDescriptor: gate?.riskDescriptor ?? null,
             });
         }
+        // Same triage order as the SQL twins: severity DESC, then oldest-first within a tier.
         return rows.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
     }
     async findPendingTokenBySession(sessionId, scope) {
@@ -158,6 +210,14 @@ export class LocalCheckpointStore {
                 return token;
         return null;
     }
+    /** [868] read-only probe face: does this session have an EXPIRED checkpoint row? The local twin of the SQL
+     *  `EXISTS (SELECT 1 FROM checkpoint ce WHERE ce.session_id = ? AND ce.status = 'expired')` that drives the
+     *  run stores' failSuspendedWithExpiredCheckpoint. Scans the session→token index (get(token) is the only
+     *  cross-status read core's File store offers); an index entry whose inner row vanished is pruned lazily.
+     *  Backed by a persisted registry, so it stays honest — never a guessed "true".
+     *  ⚠️ 存量限制(codex M2,如实):索引随 put 增量建立,无升级迁移——本版本部署前已存在的 checkpoint 不在
+     *  索引里,其 expired 对本探针不可见(core File store 的 listByScope 是 pending-only,无法枚举历史行回填)。
+     *  旧存量锁死的恢复把手 = cancel verb([868]①,不依赖本索引);增量行全覆盖。 */
     async hasExpiredBySession(sessionId) {
         const tokens = this.sessionTokens.get(sessionId);
         if (!tokens)
@@ -166,7 +226,7 @@ export class LocalCheckpointStore {
         for (const t of [...tokens]) {
             const cp = await this.inner.get(t);
             if (!cp) {
-                tokens.delete(t);
+                tokens.delete(t); // inner row gone (e.g. a wiped data plane) — the index entry is stale
                 pruned = true;
                 continue;
             }
@@ -180,16 +240,24 @@ export class LocalCheckpointStore {
                 this.persistSessionTokens();
             }
             catch {
+                /* best-effort — a stale on-disk entry is re-pruned on the next scan */
             }
         }
         return false;
     }
+    /** `undefined` = no pending row; else the owner scope (local scopes are always strings — never null). */
     async peekPendingScope(sessionId) {
         for (const { cp } of await this.pendings())
             if (cp.sessionId === sessionId)
                 return cp.scope;
         return undefined;
     }
+    /**
+     * design/80 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 branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
+     */
     async reapExpired(cutoff) {
         let n = 0;
         for (const { token, cp } of await this.pendings()) {
@@ -204,6 +272,7 @@ export class LocalCheckpointStore {
         }
         return n;
     }
+    /** design/80 D-D SLA deny-sweep input — pending human/irreversible_ask gates past deadline (excl. AskUserQuestion). */
     async listExpiredApprovalGates(cutoff, limit = 100) {
         const hits = [];
         for (const { cp } of await this.pendings()) {
@@ -221,6 +290,7 @@ export class LocalCheckpointStore {
             .slice(0, limit)
             .map(({ sessionId, scope }) => ({ sessionId, scope }));
     }
+    // ─────────── checkpoint ctx (resume rebuild inputs; sessionId-keyed, one JSON file per session) ───────────
     async putCtx(sessionId, ctx) {
         const rec = { sessionId, updatedAt: Date.now(), ctx };
         atomicWriteFile(this.tmpDir, join(this.ctxDir, ctxFileOf(sessionId)), JSON.stringify(rec));
@@ -231,12 +301,13 @@ export class LocalCheckpointStore {
             return null;
         try {
             const rec = JSON.parse(readFileSync(p, "utf8"));
-            return rec.sessionId === sessionId ? (rec.ctx ?? null) : null;
+            return rec.sessionId === sessionId ? (rec.ctx ?? null) : null; // hash-collision paranoia: verify the embedded id
         }
         catch {
-            return null;
+            return null; // a torn/corrupt ctx reads as absent — the resume 409s "resume context missing" (fail-loud upstream)
         }
     }
+    /** GC ctx files whose lifecycle is over — same three guards as the SQL twins (stale ∧ no pending ∧ no active run). */
     async reapCtx(cutoff) {
         let n = 0;
         for (const f of readdirSync(this.ctxDir)) {
@@ -248,7 +319,7 @@ export class LocalCheckpointStore {
                 rec = JSON.parse(readFileSync(p, "utf8"));
             }
             catch {
-                continue;
+                continue; // unreadable ⇒ leave for inspection (never a blind unlink)
             }
             if (rec.updatedAt >= cutoff)
                 continue;
@@ -261,20 +332,27 @@ export class LocalCheckpointStore {
                 n++;
             }
             catch {
+                /* racing unlink is fine */
             }
         }
         return n;
     }
+    /**
+     * E21 session purge — functional contract: a deleted session has no resumable future. Expires every pending
+     * gate of the session (all scopes) + unlinks its ctx file. Owner guard mirrors the SQL EXISTS guard: with an
+     * `ownerOf` source the owner must null-safe-match; without one, only an ownerless call (owner=null) purges.
+     * Returns the number of gates expired. (Terminal ledger history stays on disk — local transcripts posture.)
+     */
     async deleteBySession(sessionId, owner) {
         if (this.opts.ownerOf) {
             const actual = await this.opts.ownerOf(sessionId);
             if (actual === undefined)
-                return 0;
+                return 0; // no session row ⇒ EXISTS guard fails ⇒ purge nothing
             if ((actual ?? null) !== (owner ?? null))
                 return 0;
         }
         else if (owner !== null) {
-            return 0;
+            return 0; // no owner source to verify a non-null owner against — fail-closed
         }
         let n = 0;
         for (const { token, cp } of await this.pendings()) {
@@ -287,6 +365,7 @@ export class LocalCheckpointStore {
                 unlinkSync(p);
         }
         catch {
+            /* best-effort ctx unlink */
         }
         return n;
     }

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

@@ -3,45 +3,157 @@ import type { SessionSummary } from "./store-contracts.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class LocalSessionStore implements SessionStore {
     private readonly repo;
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one (mirrors TiDBSessionStore). */
     private readonly pending;
+    /** Service-side owner scope per session (core's repo has no owner column). Registered-ownerless ⇒ null; absent ⇒ undefined. */
     private readonly owners;
+    /** 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). */
     private readonly lastActivity;
+    /** 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. */
     private readonly lastTaskRun;
+    /** 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). */
     private readonly stagings;
+    /** Lazy one-shot load of the persisted lastActivity sidecar (memoized; only the first reader pays the read). */
     private loaded?;
+    /** A pending debounced sidecar flush (coalesces a burst of touch() into one write). undefined ⇒ no flush queued. */
     private 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). */
     private writeChain;
+    /** 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). */
     private dirty;
+    /** 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). */
     private writeSeq;
+    /** 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. */
     private lastWarnAt;
+    /** Absolute path to the lastActivity JSON sidecar, or undefined when not persisting (in-memory-only deployment). */
     private readonly 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}). */
     private readonly titleSidecarPath?;
+    /** Per-instance fallback used ONLY when there is no sidecar path (nothing is shared, so nothing to collapse). */
     private readonly ownTitleState;
+    /** @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: SessionRepo, dataDir?: string);
+    /** 该实例应当使用的 title 状态:有 sidecar ⇒ 按路径共享的那份;无 sidecar ⇒ 自己那份(无共享后端)。 */
     private get titleState();
+    /** Lazy one-shot hydrate of the persisted titles (mirrors ensureLoaded's posture: missing file silent, torn warn). */
     private ensureTitlesLoaded;
+    /** 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). */
     private persistTitles;
+    /** 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">;
+    /** 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). */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** 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. */
     private ensureLoaded;
+    /** 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. */
     private scheduleFlush;
+    /** 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. */
     private flush;
+    /** 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. */
     private 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. */
     private warnSidecar;
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
     private load;
+    /** 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. */
     register(sessionId: string, owner: string | null): Promise<void>;
+    /** 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 行,重启无损)。 */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
+    /** [1196] 六轮复审:owner+leafId 原子快照——单线程 JS 内两同步/顺序读之间无 await 打断 owner 判定
+     *  (owner 先取快照,leaf 读后 owner 复核,变了=undefined 视作删除中,调用方按删处理)。 */
     getHead(sessionId: string): Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
+    /** 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: string, owner: string | null): void;
     touch(sessionId: string): Promise<void>;
+    /** E18 — the session's current leaf SessionTreeEntry.id (@see TiDBSessionStore.getLeafId). Reads the repo's storage
+     *  leaf (no acquire-lock; InMemory/File repo reads don't lock). null when the session doesn't exist / has no leaf. */
     getLeafId(sessionId: string): Promise<string | null>;
+    /** Durable history is retained by the repo; just drop the in-flight cache entry (mirrors TiDBSessionStore.release). */
     release(sessionId: string): Promise<void>;
+    /**
+     * 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.
+     */
     listSessions(opts: {
         owner?: string;
         cursor?: {
@@ -51,22 +163,67 @@ export declare class LocalSessionStore implements SessionStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** 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: string, taskId: string): void;
+    /** Synthesize a session's objective preview = the most-recent USER text message (the objective the run last saw).
+     *  Reads the session's entries through the repo; any read error degrades to null (never fails the list). */
     private previewOf;
+    /** E17 — fork a session's WHOLE history to a NEW id owned by `owner` (core SessionRepo.fork). Returns the new id,
+     *  or null if the source does not exist (the route maps that to 404). */
     fork(sourceId: string, owner: string | null): Promise<string | null>;
+    /** 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. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
+    /** 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. */
     listEntryIds(sessionId: string): Promise<string[] | null>;
+    /** 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). */
     exportEntriesStream(sessionId: string, opts?: {
         afterSeq?: number;
         batchSize?: number;
     }): Promise<AsyncIterable<SessionTreeEntry> | null>;
+    /** 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`). */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /** 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). */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /** 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: string, token: string): StagingHandle;
+    /** 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). */
     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;
+    /** 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. */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     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). */
     dispose(): Promise<void>;
 }
 //# sourceMappingURL=local-session-store.d.ts.map