@sema-agent/server 7.118.0 → 7.119.0

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

@@ -1,8 +1,17 @@
-import { type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
+import { FileSessionRepo, type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionSummary } from "./store-contracts.js";
+import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
+/**
+ * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座与会话视图口
+ * `audit.ts#buildSessionAuditLocal` 的读旁路),所以坏记录的披露座只有这一份接线 —— 修前视图口自建一只不带座的 repo,同一份坏档在这里读到有计数 / 探针,
+ * 在视图口读到一个字都没有。座 = F 类 `server.session-repo.corrupt-record-skipped`(会话存档里读不出的记录丢的是可用性:历史少一截 / 列表少一行,不开任何门;
+ * 计数单位 = 一条被跳过的记录,逐命中探针行,warn 每进程一次),外加会话打开作用域的计数腿(`noteReplayInSessionOpenScope`:只在 `openSessionForItself`
+ * 的作用域里才记,作用域外 —— 列表 / 导出 / 视图口 —— 是空操作,那些读只进运维面)。
+ */
+export declare function createLocalSessionRepo(root: string): FileSessionRepo;
 export declare class LocalSessionStore implements SessionStore {
     private readonly repo;
     /** [ref] 车1:托管留存声明 —— **诚实的 none**。本店的行没有任何按期删除的腿(留存 lane 的三方法只实现在
@@ -12,8 +21,6 @@ export declare class LocalSessionStore implements SessionStore {
     readonly retention: import("@sema-agent/core").RetentionDeclaration;
     /** 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
@@ -54,35 +61,52 @@ export declare class LocalSessionStore implements SessionStore {
     private readonly sidecarPath?;
     /** Auto-title map (`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). Cross-instance sharing: see
-     *  {@link SidecarStringMap}. */
+     *  {@link SidecarMap}. */
     private readonly titles;
     /** S-690 — instruction-source baselines (`session-instruction-sources.json`): the chain member the session's previous
      *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
      *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
     private readonly instructionSources;
-    /** S-790 / S-506([ref] §2):会话化身(`session-incarnations.json`,`{ [sessionId]: token }`)。SQL 孪生的
-     *  `session_meta.incarnation` 列在本店的对位。🔴 **必须落盘**(不能像 `owners` 那样只活在内存):化身的口径是「一位住客一生
-     *  稳定」,而记忆引擎按它绑定会话级记录(opt-out / 污染标记)—— 重启后换一只值 = 同一位住客的 opt-out 不再绑它 = 静默恢复采集。
-     *  设计稿原说「存进属主边车」,但本店**没有**落盘的属主边车(`owners` 是纯内存 Map,S3 裁定),所以落在同一族的第四只边档
-     *  (同一只 `SidecarStringMap`:同写链、失败回滚)。铸点只在新建会话;盘上旧会话没有这一格 ⇒ 第一次读补铸并落盘。 */
-    private readonly incarnations;
+    /**
+     * 会话元数据(`session-incarnations.json`,一格的形与两种读法见 {@link SessionMetaCell}):**属主与化身的唯一真源**,SQL 孪生
+     * `session_meta` 行上 `owner` / `incarnation` 两列在本店的对位。两样都**必须落盘**:
+     *  · 化身(S-790 / S-506,[ref] §2)的口径是「一位住客一生稳定」,记忆引擎按它绑定会话级记录(opt-out / 污染标记)——
+     *    重启后换一只值 = 同一位住客的 opt-out 不再绑它 = 静默恢复采集;
+     *  · 属主(7.119.0)是会话策略规则的存储键:规则按「会话 × 属主」存、按 run 的 principal 读 —— 重启后属主丢了,规则照样在跑,
+     *    属主自己却读不到也删不掉(`409 conflict.session_ownerless`)。7.118.x 及更早属主只活在一只进程内存 Map 里,就是这个病。
+     * 没有第二份:进程里的读视图就是这只边档按路径共享的那张表({@link SidecarMap},同写链;只发布已落盘的值 —— 写失败什么都不发布)。铸点只在新建会话;
+     * 盘上有会话而边档里没有它那一格 ⇒ 第一次读补铸一格只有化身的(属主没有事实可写)并落盘。严格读(读不出 ⇒ 整只拒,见 `SidecarMap.strict`)。
+     */
+    private readonly meta;
+    /** 认领行(`session_owner_claimed`)的出口 —— 一次性迁移 M10 的认领臂专用(窗口见 `plugins/one-time-migrations.ts` 登记表)。 */
+    private readonly log;
     /** @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);
+     *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives).
+     *  @param opts.log the `session_owner_claimed` line's sink (LocalBackend passes a logger at the deployment's LOG_LEVEL;
+     *                  absent ⇒ an info-level JSON-line logger — a claim is never silent). */
+    constructor(repo: SessionRepo, dataDir?: string, opts?: {
+        log?: Pick<Logger, "info">;
+    });
+    /**
+     * 把 `sessionId` 那一格写成 `next(before)` 的结果并**落盘**(写链里在草稿上判、写、落盘后才发布给读者 —— 与 instruction-source 同一只 `commit`;
+     * 判据建立在每一节之前的盘上状态上,所以防 clobber 的「已记下就不动」写在 `next` 里,不写在链外)。`next` 返回 `undefined` = 不改。
+     * 落不了盘 ⇒ 抛(属主与化身都是正确性事实,不做「内存里先记着」的降级:一只没落盘的化身重启后会被换掉 —— 那是另一位住客;
+     * 一个没落盘的属主重启后就丢了 —— 那正是 7.119.0 修的病)。返回这一次是否真改了那一格。
+     */
+    private writeMeta;
+    /** 删一只会话的那一格(落盘;落不了 ⇒ 抛 —— 留下的格会让一只删掉的会话在重启后「还在」)。 */
+    private dropMeta;
+    /** 盘上有没有这只会话(repo 的唯一探针;`open` 读整只存档,所以只在边档里没有那一格时才走到这里)。 */
+    private existsInRepo;
     /**
-     * S-790:把 `sessionId` 的化身写成 `next(before)` 的结果并**落盘**(写链里判、写、失败回滚 —— 与 instruction-source 同一只
-     * `commit`)。`next` 返回 `undefined` = 不改。落不了盘 ⇒ 抛(化身是正确性事实,不做「内存里先记着」的降级:一只没落盘的化身
-     * 重启后会被换掉,那就是另一位住客)。
+     * 一只会话的元数据 —— 属主与化身的**唯一读口**(`ownerOf` / `sessionFaceOf` / `getHead` / 删除与换装的属主门都经它)。`undefined` = 无此会话。
+     * 边档里有那一格 ⇒ 读它(一次同步读,两样同出一格,不会拼出混世代组合);没有那一格而盘上有会话(7.104.0 之前的会话从没被铸过化身)
+     * ⇒ 补铸一格只有化身的(属主没有事实可写,不伪造)并落盘后再答 —— 之后的读都命中那一格,不再回 repo。
      */
-    private writeIncarnation;
-    /** S-790:新建会话 ⇒ 铸一只新的(覆盖同 id 上任何残留 —— 新建行就是新住客)。 */
-    private mintIncarnation;
-    /** S-790:已存在的会话缺一只化身(盘上 7.104.0 之前的会话)⇒ 补铸;已有的一个字节不动。 */
-    private ensureIncarnation;
-    /** S-790:属主 + 化身一次读(SQL 孪生同义;`undefined` = 无此会话)。盘上有会话而边档里没有它的化身 ⇒ 补铸并落盘后再答;
-     *  读的过程中会话被删 / 换了主 ⇒ `undefined`(与 {@link getHead} 同一条「读间被删」判据)。 */
+    private metaOf;
+    /** S-790:属主 + 化身一次读(SQL 孪生同义;`undefined` = 无此会话)—— 两样出自 {@link metaOf} 读到的同一格。 */
     sessionFaceOf(sessionId: string): Promise<SessionFace | undefined>;
     /** 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. */
@@ -94,10 +118,10 @@ export declare class LocalSessionStore implements SessionStore {
     /** S-690 —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**
-     * S-690 —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 回滚内存再抛**,与 SQL 孪生
+     * S-690 —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 内存不动、抛**,与 SQL 孪生
      * 「要么提交要么抛」同形 —— 修前写失败只 warn、内存照样前进,同来源的后续 run 在相等比较上短路、再也不重写,重启后
-     * 比的是一份过期的盘,codex che-NM r1 [medium])。CAS 判定、落盘、失败回滚**整段在写链的一节里**(`commit`):下一节
-     * 开始之前内存已回到盘上那份,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
+     * 比的是一份过期的盘,codex che-NM r1 [medium])。CAS 判定(在草稿上)、落盘、发布**整段在写链的一节里**(`commit`):下一节
+     * 开始之前共享的那张表只含落过盘的值,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
      */
     recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
     /** Best-effort, one-shot hydrate of the persisted lastActivity map (no-op when not persisting / no sidecar yet). A
@@ -141,28 +165,35 @@ export declare class LocalSessionStore implements SessionStore {
         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).
+    /**
+     * Idempotently record a session's owner — never overwrites a RECORDED owner (incl. a recorded `null`, "registered ownerless";
+     * mirrors TiDBSessionStore.register's first-write rule). TiDB parity: register INSERTs a session_meta row so the session EXISTS
+     * (forkable) even before its first acquire/run — so we also ensure an EMPTY repo session exists (open if present → never
+     * overwrite history; create if not), else `ownerOf` would say a registered-but-never-acquired session exists while `fork` 404s it.
      *
-     *  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 行,重启无损)。 */
+     * 首写判据在写链里判(两只并发登记:先落盘的那一只赢,后一只不改、也不建会话)。一只**盘上已有、属主从没被记下**的会话
+     * (边档那一格只有化身 —— 7.118.x 及更早写下的,或更早到连化身都没有)是一次性迁移 M10 的对象(窗口见 `plugins/one-time-migrations.ts`
+     * 登记表):窗开着、且这次登记带着 principal(`owner !== null`)⇒ **认领**(记下属主,化身一个字节不动 —— 同一位住客),一行 info
+     * `session_owner_claimed`;否则只补化身(缺就补),属主仍是「没被记下」,读作无主。认领的安全前提是单用户 —— local 后端起服门拒
+     * `REQUIRE_PRINCIPAL=true`,授权口也只在那时才把 principal 递过来认领(`security.ts` `createAuthorizer`)。
+     */
+    register(sessionId: string, owner: string | null): Promise<void>;
+    /** Owner of a session: `null` if ownerless (registered ownerless, or an owner that was never recorded — a session written by
+     *  an earlier version), `undefined` if no such session (mirrors TiDBSessionStore.ownerOf). Reads {@link metaOf}: the persisted
+     *  cell, so the answer survives a restart exactly like the SQL twins' `session_meta.owner` column does. (Before 7.119.0 the
+     *  owner lived in a process-local Map and this method answered `null` for every session after a restart — the S3 fallback
+     *  "on disk ⇒ ownerless" kept the E21 delete working, but froze every owner-keyed session-policy rule.) */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
-    /** [ref] 六轮复审:owner+leafId 原子快照——单线程 JS 内两同步/顺序读之间无 await 打断 owner 判定
-     *  (owner 先取快照,leaf 读后 owner 复核,变了=undefined 视作删除中,调用方按删处理)。 */
+    /** [ref] 六轮复审:owner+leafId 原子快照 —— 先读那一格,读 leaf,再同步复读那一格:格没了(读间被删)或换了主 / 换了住客 ⇒
+     *  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;
+    /** 2c P1d-β — re-stamp the session's owner WITHOUT rewriting entries (the staged-commit `identical` path: the log is
+     *  already present & equal, so only the owner needs re-stamping to the importing principal, §9). Persisted like every
+     *  owner write; the incarnation is untouched (same occupant). No cell (no such session) ⇒ no-op. */
+    restampOwner(sessionId: string, owner: string | null): Promise<void>;
     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. */
@@ -174,10 +205,9 @@ export declare class LocalSessionStore implements SessionStore {
      * 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.
+     *   - `owner`           — the session's persisted session-meta cell (null when ownerless / never recorded). A
+     *                          single-user local deployment runs REQUIRE_PRINCIPAL=off; 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).
@@ -240,9 +270,10 @@ export declare class LocalSessionStore implements SessionStore {
     /** 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`). */
+     *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`).
+     *  The owner is recorded in the session-meta cell (persisted), together with the incarnation. */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** importEntries / replaceEntries 的共用写半场:导日志 + 盖属主 + 落化身(新建铸的那只,或换装沿用的那只)。 */
+    /** importEntries / replaceEntries 的共用写半场:导日志 + 一格写全属主与化身(新建铸的那只,或换装沿用的那只)。 */
     private importEntriesAs;
     /** 2c session-sync (§7/§8) — IDEMPOTENT REPLACE. The local twin's replace is DELETE-then-IMPORT: core's
      *  InMemorySessionRepo / FileSessionRepo expose no single replace primitive, but the local backend is single-writer