@sema-agent/server 7.150.0 → 7.151.0

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

@@ -1,21 +1,23 @@
 import { FileSessionRepo, type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionRepo, type SessionMetadata, type SessionTreeEntry, type StoreDurability } from "@sema-agent/core";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { z } from "zod";
-import { StoreBootRefusalError, type SessionRootRows, type SessionRunClaimSource, type SessionRunRollupSource, type SessionSummary } from "./store-contracts.js";
-import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
+import { StoreBootRefusalError, type SessionRootRows, type SessionRunClaimSource, type SessionRunRollupSource, type SessionListQuery, type SessionSummary } from "./store-contracts.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome, type LandedOutcome } from "../session-row.js";
 import { type SqlJsonColumnProblem } from "./sql-json-column.js";
 import { type LocalArchiveKeptStamped, type LocalArchiveUnreadable } from "./one-time-migrations.js";
 import { type ReleaseTriple } from "./release-version.js";
 import { type Logger } from "../observability/logger.js";
 import type { SessionOccupant } from "../session-erase.js";
 import { type RegisterReceipt, type SessionBirth, type SessionFace, type WithdrawOutcome } from "../session-incarnation.js";
+import { type LocalSessionLiveReferenceReaders } from "./local-session-live-reference.js";
+import { type IdleSession, type IdleSessionCursor, type SessionKind, type SessionKindReading } from "../session-kind.js";
 import type { SessionDeletionFace } from "../session-deletion.js";
 import { type ExecutionLane } from "../execution-lane-caps.js";
 import { type ExecutionPlacementSeat, type LocalPlacementBackfillSeat } from "../execution-placement.js";
 import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "./session-fork.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import type { SessionWorkspace } from "../session-workspace.js";
-import { type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
+import { type EntriesStreamOptions, type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 /**
  * 本店执行格的形(会话元数据那一格的 `execution` 位;规则在 `src/execution-placement.ts`):`writer(L)` | `mirror`;缺 = absent。
  * local 车道没有 device 表 ⇒ 不设任何设备位(writer 只带车道)。`forking` 不是存下的值,是「fork 创建的格({@link isForkCreatedCell})而存档不在」的读法。
@@ -59,6 +61,11 @@ interface SessionMetaCellObject {
      * 撤回对它一律答「留」(`upgrade_pending`)。不需要一次性升级:撤回的候选只可能是本版登记新铸的格(化身比对,`session-birth.ts`),缺这一位的格永远不是候选。
      */
     readonly clientWrites?: number;
+    /**
+     * 会话种类(律 `src/session-kind.ts`;SQL 孪生 `session_ext.session_kind`):只由登记新行那一笔写下(带种类的提交建的会话),此后无写口;缺 = 顶层对话。
+     * 半建形(登记写下了格、建存档那一步失败)之后同 id 的缺档新建臂随属主一起带过它(两位都是登记那一笔写下的出生事实)。
+     */
+    readonly sessionKind?: SessionKind;
 }
 /**
  * 会话元数据边档(`session-incarnations.json`)的一格 —— SQL 孪生 `session_meta` 行在本店的对位(同一行 ⇒ 同一格、同一次落盘):属主 / 化身 / 执行放置 / `fork_key` /
@@ -93,6 +100,9 @@ export declare const SESSION_META_CELL_OBJECT: z.ZodObject<{
     dropping: z.ZodOptional<z.ZodLiteral<true>>;
     deleting: z.ZodOptional<z.ZodString>;
     clientWrites: z.ZodOptional<z.ZodNumber>;
+    sessionKind: z.ZodOptional<z.ZodEnum<{
+        sidechain: "sidechain";
+    }>>;
 }, z.core.$strict>;
 /**
  * 数据根对账里一只文件的读数(拒句的逐文件一段;{@link LocalDataRootSchemaMismatchError.findings}):严格边档清册里的一只边档,或引擎版本高水位 marker
@@ -328,6 +338,14 @@ export interface SessionRunWithdrawSource {
 export interface LocalSessionWithdrawDeclaration {
     readonly withdrawCheckpointCtx?: (sessionId: string) => void;
 }
+/**
+ * 本店的老化装配(装配方给;会话种类的律在 `src/session-kind.ts`):活引用判除认领之外的三只读口(检查点 / 后台子代 / workflow 晚绑座,`local-session-live-reference.ts`;
+ * 认领那一腿读本店自己的 run 店)。**显式声明才有老化**:缺这一格 ⇒ 本店不交老化候选面 ⇒ 这台部署记不了种类(能力位 `sessionKinds` 为空、带键提交 400)——
+ * 不按「没说 = 没有引用」放行一条删用户数据的腿;每一腿逐只声明(`"none"` = 这台部署确实没有那只店)。
+ */
+export interface LocalSessionAgeOutDeclaration {
+    readonly liveReferences?: Omit<LocalSessionLiveReferenceReaders, "claim">;
+}
 export declare class LocalSessionStore implements SessionStore, SessionRootRows {
     private readonly repo;
     private readonly runs;
@@ -436,6 +454,13 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
     private archiveSnapshotsSettled;
     /** 撤回时本会话续跑输入的严格删法({@link LocalSessionWithdrawDeclaration};缺 = 没有可删的)。 */
     private readonly withdrawCheckpointCtx;
+    /** 活引用判({@link LocalSessionAgeOutDeclaration};缺 = 本店不老化 —— 老化围栏对带条件的删除一律答「不删」)。 */
+    private readonly liveReferenceOf;
+    /** 老化候选面(`OwnerAwareSessionStore.listIdleOfKind`;只在声明了老化装配时交 —— {@link LocalSessionAgeOutDeclaration})。 */
+    readonly listIdleOfKind?: (kind: SessionKind, idleBefore: Date, page: {
+        readonly after?: IdleSessionCursor;
+        readonly limit: number;
+    }) => Promise<IdleSession[]>;
     /** @param repo     the core SessionRepo this store projects into the §0.5 SessionStore shape.
      *  @param runs     the run store whose per-session projection is the ONLY source of a row's `runCount` / `lastStatus` / `lastRunId` /
      *                  `lastTaskRunId` (LocalBackend passes its `FileRunStore`). Required — a run-less local session store does not exist.
@@ -447,7 +472,7 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      *  @param opts.durability / opts.placements the deployment's declaration ({@link LocalSessionStoreDeclaration}; see the two fields). */
     constructor(repo: HeadReadingSessionRepo & Partial<PlacementRecordingRepo>, runs: SessionRunRollupSource & SessionRunClaimSource, dataDir?: string, opts?: {
         log?: Pick<Logger, "info" | "warn">;
-    } & LocalSessionStoreDeclaration & LocalSessionWithdrawDeclaration);
+    } & LocalSessionStoreDeclaration & LocalSessionWithdrawDeclaration & LocalSessionAgeOutDeclaration);
     /**
      * 🔴 一次性迁移 **M40 的 local 会话腿**(窗口见 `plugins/one-time-migrations.ts` 登记表 M40 行;唯一调用点 `LocalBackend.ensureSchema()` 的**第一步**,
      * 先于任何读会话元数据的店步骤 —— 严格读的执行位只认本版车道词;数据根准入的那一读在内存里先套同一只内核 {@link renameRetiredExecutionLaneWordsInCellsM40},零写):会话元数据边档里 `execution` 位记成退役词的
@@ -616,11 +641,13 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      * 别的读者一律读作不在(读者律);门对别的属主答「不在」的同一句,所以不可探测。SQL 孪生同交这一口(座的原始头读)。
      */
     deletionHeadOf(sessionId: string): Promise<SessionHead | undefined>;
+    /** 按 id 的种类读(`session-kind.ts` 的 `SessionKindFace`):行事实那一格(属主与化身的唯一读口 {@link metaOf} 的同一次观察)上的住客与种类。不在 ⇒ `undefined`。 */
+    sessionKindOf(sessionId: string): Promise<SessionKindReading | undefined>;
     /**
      * 引擎仓存档的头(core `SessionRepo.headOf`:日志首记录与尾,不重放)—— 本店按 id 读存档头的**唯一**一处。存档头在本店只有三种读法:叶子(读内容的人要的那一格)、
      * 行代号(暂存提交落点 / 一次性迁移 M33 的 `expect.row`、迁移判「有没有、读不读得出」)与带戳判({@link assertArchiveAnonymous};读的是存档的**形** —— 头上有没有属主戳 —— 不是属主事实);
      * 属主 / 化身 / 建档时刻 / 谱系作为行事实从不从这里读(规则一,行事实只住边档);例外只有窗内无格存档长第一格的那一读({@link firstCellIncarnationHeld},M47 在树时;
-     * M47 的起服扫经列表面的行集读同一只令牌)。
+     * M47 的起服扫经列表面的行集读同一只令牌);会话老化的候选面也经它问「存档在不在」(行集没交它的时刻时,{@link idleOfKind})。
      */
     private archiveHeadOf;
     /**
@@ -641,7 +668,7 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      *  failure keeps the in-memory title (degrades to re-title after restart). Runs under this session's write lock — the
      *  user's conditional write ({@link writeSessionRowCells}) judges its row tag and writes under the same lock, so the two
      *  writers of the title cell never interleave between a judgement and its write (the SQL twins get this from the row lock). */
-    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    setTitleIfNull(sessionId: string, title: string, landed: SessionFace): Promise<boolean>;
     /**
      * 会话行格写原语 —— 用户标题 / 置顶的**唯一**写口(SQL 孪生 `writeSessionRowCells` 的 local 对位;规则与判序:`src/session-row.ts` 头注「写原语」)。
      * **整段在这只会话的写锁里**({@link withSessionWriteLock}):读出锁住的那一行(会话元数据那一格的属主 + 化身 + 执行位、列表面上有它、两只边档的格)→
@@ -811,7 +838,7 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      * 出生回执面(`session-birth.ts`):与 {@link register} 同一笔写。**只有新建会话那一臂**(存档不在 ∧ 这一笔真写下了新格)交回候选 —— 化身是这一笔里铸的那一只,
      * 不复读;已记下属主(并发登记里后到的那一只)/ 只补化身 ⇒ 不交候选。新格同一笔写下客户端写计数 `0`(版本位,见 {@link SessionMetaCellObject.clientWrites})。
      */
-    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: SessionKind): Promise<RegisterReceipt>;
     touch(sessionId: string): Promise<void>;
     /**
      * 普通会话:durable 史留在 repo,只丢 in-flight 那一格(义务 3,与 SQL 孪生同)。
@@ -847,34 +874,17 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      * 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).
      */
-    listSessions(opts: {
-        owner?: string;
-        /** [ref] 窄互认第二臂的第三条件(SQL 孪生里是 `owner IS NULL` 谓词;此处是同义的 `owner === null` 放行)。 */
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
+    listSessions(opts: SessionListQuery): Promise<SessionSummary[]>;
     /** {@link listSessions} 带每行的住客(属主 + 化身那一格,与行同一刻读)—— `OwnerAwareSessionStore.listSessionRows`;化身不进行本身。 */
-    listSessionRows(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<Array<SessionRowAnswer<SessionSummary>>>;
+    listSessionRows(opts: SessionListQuery): Promise<Array<SessionRowAnswer<SessionSummary>>>;
     /** 列表行要读的边档一次装齐(lastActivity / 标题 / 置顶 / 会话元数据);各自记忆化,只有第一次真读盘。 */
     private loadRowSidecars;
     /** 列表行上的属主:那一格的属主(没有格 / 属主从没被记下 ⇒ null —— 与 `headOf(id)?.owner` 同答;列表不补铸缺的格,`headOf` 在第一次读时补)。 */
     private ownerCellOf;
     /** 一只会话的列表行 —— {@link listSessions} 与 {@link sessionSummaryOf} 的**同一只**合成(字段来源逐位见 listSessions 的头注)。调用方先 {@link loadRowSidecars}。 */
     private summaryOf;
+    /** 列表行的 `sessionKind` 键:那一格的种类(没有那一格 / 顶层 ⇒ 键缺席)。 */
+    private listedKindOf;
     /** 列表行的 `forkedFrom` 键:那一格的谱系经三店唯一的读法 `forkLineageOfRow`(没有那一格 / 不是 fork ⇒ 键缺席;住客令牌不上列表行)。 */
     private listedLineageOf;
     /** 列表行的 `rowTag` 键(规则 `session-row.ts`):化身出自会话元数据那一格(与写原语锁住的那一行同读),属主与两格由调用方交 —— 就是这一行交出去的那两位(同一刻读);没有那一格 ⇒ 键缺席。 */
@@ -939,10 +949,7 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      *  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>;
+    exportEntriesStream(sessionId: string, opts: EntriesStreamOptions): Promise<AsyncIterable<SessionTreeEntry> | null>;
     /**
      * 2c session-sync — IMPORT a verbatim entry log into a **new** session `sessionId`(`owner` = 鉴权过的导入者)。按接口句(`importEntries` 只建新会话;改写既有会话走
      * {@link replaceEntries} / 暂存提交),SQL 孪生同判(占行不成 ⇒ 拒):id 上已有行(或格缺而存档在)⇒ `conflict`,一个字节不写;新行的属主 = 导入者、铸一只化身、
@@ -1044,7 +1051,7 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
     assertArchiveAnonymous(sessionId: string): Promise<void>;
     /**
      * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):属主 CAS(此刻的属主格 = 这次导入的门判过的那一格,
-     * 否则抛 {@link StagedCommitOwnerChangedError},一个字节不写;在判目的端日志之前判,SQL 孪生同序)→ 分区判 → 提交时重新分类(目的端此刻的日志 vs staged)→
+     * 否则抛 {@link StagedCommitOccupantChangedError},一个字节不写;在判目的端日志之前判,SQL 孪生同序)→ 分区判 → 提交时重新分类(目的端此刻的日志 vs staged)→
      * 这一提交要换日志(不是「id 与内容都相同」那一支)⇒ 带戳存档判({@link assertArchiveAnonymous};只有 local 店有带戳存档,SQL 孪生没有这一步)→
      * 拒未经同意的 fork / stale / 载荷分叉(带戳判在它们之前:带戳存档上日志换不了,同步冲突与载荷分叉的出路 —— 带同意重来 —— 无从谈起)→ 准入({@link admitImportHeld}:读认领 → 本处写者 / fork 中间态 → 拒;fork 中间态的拒也在这一处,不再在提交入口另判一遍)→ 换装(导入写序 ①②③,落点 `judged` = 上面这一判;化身与 fork 键按换装律沿用)或 identical 且内容相同时日志不动、
      * 行照样落(② 那一格:重戳属主 + mirror)→ 两支同记新近(推送即活动)→ **在同一次持锁里**
@@ -1073,6 +1080,21 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
     private deletingTokenOf;
     /** 删除面(会话三态的围栏 / 复核 / 收尾输入;律在 `src/session-deletion.ts`)。 */
     readonly sessionDeletion: SessionDeletionFace;
+    /**
+     * 老化候选面的体({@link listIdleOfKind};律 `src/session-kind.ts`):会话元数据格里种类为 `kind` 的行(活格与在删格 —— 在删的照交,交给围栏接管;标记格不交:
+     * 店内删序正在收它)× 时钟锚({@link ageAnchorOf}:新近标记 / 存档的最后写时刻 / 建档时刻里最晚的那一个)早于视界 × 当下无活引用。最老先出、keyset 续页(序的唯一判 `idleSessionAfter`)。
+     * 先按格判(同步、零 I/O:新近标记与建档时刻都早于视界是必要条件);过了的格有一只才读一遍 repo 行集取存档时刻(`lastActiveAt`);行集里没有它的格(半建 / 存档读不出被行集跳过)
+     * 再经存档头读口探一次:存档在而时刻读不到 ⇒ 不交(说不准就护住)。
+     */
+    private idleOfKind;
+    /**
+     * 老化的时钟锚(epoch ms;候选面与围栏同读):新近标记(本进程的 touch / 边档)· 存档的最后写时刻(`archived`:repo 行的 `lastActiveAt` = 日志 mtime,持久 —— 边档读不出、
+     * 最后几次 touch 没落盘时它仍在)· 行上的建档时刻,**取最晚的那一个**。新近标记的持久是尽力的(边档撕裂 ⇒ 空表、去抖窗内崩 ⇒ 丢最后几笔),删用户数据的判不单读它。
+     * 一个读得出的时刻都没有 ⇒ `+∞`(永不闲置)。调用方先 {@link loadRowSidecars}。
+     */
+    private ageAnchorOf;
+    /** 新近标记此刻是否仍早于视界(没有标记 = 本进程没见过它的活动 ⇒ 仍早于)。同步读 —— 围栏在令牌落盘那一节里读它,与 touch 不交错。 */
+    private unTouchedSince;
     /** 一只在删格上的属主(遗留行围栏时没有记下属主 ⇒ 读作无主,与删除门的读法同)。 */
     private deletionOwnerOf;
     /**
@@ -1083,6 +1105,13 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      * 写令牌 `required`(文件 + 目录 fsync):落不了 ⇒ 抛,什么都没删(围栏没立)。遗留行铸一格(化身新铸、只带令牌;回执的化身 `undefined` —— 它的住客从没被记下,没有空间)。
      */
     private fenceDeletionHeld;
+    /**
+     * 老化条件的锁内判(`session-deletion.ts` 的 `SessionAgeOutExpectation`;调用方持这只会话的写锁):活格 ∧ 住客仍是候选那一位 ∧ 种类仍是它 ∧ 时钟锚仍早于视界 ∧ 当下无活引用
+     * (本店的活引用判;没有老化装配 ⇒ 一律不成立)。遗留行(没有格)没有种类 ⇒ 不成立。
+     * 时钟锚在这里读新近标记与建档时刻({@link ageAnchorOf},存档时刻不重读 —— 候选面读过它;本进程独占数据根,之后存档的每一次写都随一次 touch:run 收场、导入、同步推送);
+     * 新近标记在令牌落盘那一节里还要再读一次({@link fenceDeletionHeld})。
+     */
+    private ageOutHoldsHeld;
     /**
      * 客户端写计数 +1(锁内一形,调用方持这只会话的写锁):活格 ⇒ `clientWrites` = 原值(缺 ⇒ 0)+ 1,**落盘必须成功**(`required`;落不了 ⇒ 抛,调用方的写不发生);
      * 没有活格(行不在 / 遗留行)⇒ 不计(没有可撤的候选)。
@@ -1095,6 +1124,15 @@ export declare class LocalSessionStore implements SessionStore, SessionRootRows
      * `write` 不得回到本店上锁的公开口(锁不可重入);`count` 只在这一节里有效(节外调用 ⇒ 抛)。
      */
     withClientWrite<T>(sessionId: string, write: (count: () => Promise<void>) => Promise<T>): Promise<T>;
+    /**
+     * **落定段**的 local 实现(SQL 孪生 `plugins/session-row-sql.ts` 的 `withLandedRow`;律在 `plugins/landed-attendants.ts` 头注):这只会话的写锁一节 —— 节首收尾待删(既有)→
+     * 读出锁住的那一行(与行格写原语同一读 {@link lockedRowOf})→ 同一只判官 `judgeLandedRow`(行在 ∧ 非在删 ∧ 属主与化身整对同)→ 是 ⇒ `body(count)` 在同一节里跑完 ⇒
+     * `{ landed: true, value }`;不是 ⇒ `{ landed: false }`,`body` 一个字节都不跑。与 {@link withClientWrite} 是**同一把锁、同一只计数口**(两只入口一只实现:
+     * 后者不判住客);与删净段 `deleteSession` 同锁 ⇒ 删除与落定写互不穿插。`body` 不得回到本店上锁的公开口(锁不可重入),只调各附随店的动词(锁序 会话 → 店)。
+     */
+    withLanded<T>(sessionId: string, landed: SessionFace, body: (count: () => Promise<void>) => Promise<T>): Promise<LandedOutcome<T>>;
+    /** 持锁的一节里交出那只客户端写计数口(节外调用 ⇒ 抛)。 */
+    private countedSectionHeld;
     /**
      * 条件撤回面(`session-birth.ts` 头注的判序;SQL 孪生的一只事务 = 本店这只会话的写锁一节):
      * 节首收掉了这只 id 的待删 / 行不在 ⇒ `absent`;遗留行、化身或属主不是候选 ⇒ `incarnation`;没有计数版本位 ⇒ `upgrade_pending`;存档里有可撤集合之外的条目 ⇒ `content`;

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

@@ -15,7 +15,7 @@ import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
 import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
 import { entryTypeWithdrawable } from "./session-birth.js";
-import { judgeSessionRowWrite, sessionRowTagKey, settleSessionRowWrite, } from "../session-row.js";
+import { judgeLandedRow, judgeSessionRowWrite, sessionRowTagKey, settleSessionRowWrite, } from "../session-row.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
 import { createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem, isJsonObject, readJsonObjectColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
 import { RENAMED_EXECUTION_LANE_M40, RETIRED_EXECUTION_LANE_WORD_M40 } from "./execution-lane-rename-m40.js";
@@ -26,13 +26,15 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { createLogger, writeLogText } from "../observability/logger.js";
 import { UNMANAGED_RETENTION } from "./retention-declaration.js";
 import { UnreadableLeaf, carriedRowCells, forkLineageOfRow, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { createLocalSessionLiveReference } from "./local-session-live-reference.js";
+import { SESSION_KINDS, idleSessionAfter, sessionKindListed } from "../session-kind.js";
 import { isExecutionLane } from "../execution-lane-caps.js";
-import { SessionForkInProgressError, WRITABLE, assertPlaceableLane, judgeSessionWrite, settledMirrorOutcome, settledPlaceOutcome, SessionDeletingError, } from "../execution-placement.js";
+import { SessionForkInProgressError, WRITABLE, assertPlaceableLane, judgeSessionWrite, sameOccupant, settledMirrorOutcome, settledPlaceOutcome, SessionDeletingError, } from "../execution-placement.js";
 import { classifyForkTarget, forkByFreshId } from "./session-fork.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
 import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
 import { createCorruptReadFailOpenSeat } from "../observability/corrupt-read-seat.js";
-import { classifySyncRelationshipByIds, ownerCellIs, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOccupantChangedError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
 function archiveFaultWord(code) {
@@ -76,8 +78,8 @@ const readPinnedSidecar = createZodColumnReader(z.record(z.string(), z.literal(t
 const MIRROR_CELL = { role: "mirror" };
 function readSessionMetaCell(cell) {
     return typeof cell === "string"
-        ? { incarnation: cell, owner: undefined, execution: undefined, forkKey: undefined, createdAt: undefined, forkedFrom: undefined, forkedFromIncarnation: undefined, dropping: false, deleting: undefined, clientWrites: undefined }
-        : { incarnation: cell.incarnation, owner: cell.owner, execution: cell.execution, forkKey: cell.forkKey, createdAt: cell.createdAt, forkedFrom: cell.forkedFrom, forkedFromIncarnation: cell.forkedFromIncarnation, dropping: cell.dropping === true, deleting: cell.deleting, clientWrites: cell.clientWrites };
+        ? { incarnation: cell, owner: undefined, execution: undefined, forkKey: undefined, createdAt: undefined, forkedFrom: undefined, forkedFromIncarnation: undefined, dropping: false, deleting: undefined, clientWrites: undefined, sessionKind: undefined }
+        : { incarnation: cell.incarnation, owner: cell.owner, execution: cell.execution, forkKey: cell.forkKey, createdAt: cell.createdAt, forkedFrom: cell.forkedFrom, forkedFromIncarnation: cell.forkedFromIncarnation, dropping: cell.dropping === true, deleting: cell.deleting, clientWrites: cell.clientWrites, sessionKind: cell.sessionKind };
 }
 function shellSentinelCellIdsM48(cells) {
     const ids = [];
@@ -168,6 +170,7 @@ export const SESSION_META_CELL_OBJECT = z
     dropping: z.literal(true).optional(),
     deleting: z.string().min(1).optional(),
     clientWrites: z.number().int().nonnegative().optional(),
+    sessionKind: z.enum(SESSION_KINDS).optional(),
 })
     .strict();
 const SESSION_META_SIDECAR = z.record(z.string(), z.union([z.string(), SESSION_META_CELL_OBJECT]));
@@ -719,11 +722,19 @@ export class LocalSessionStore {
     dataRoot;
     archiveSnapshotsSettled = 0;
     withdrawCheckpointCtx;
+    liveReferenceOf;
+    listIdleOfKind;
     constructor(repo, runs, dataDir, opts) {
         this.repo = repo;
         this.runs = runs;
         this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
         this.withdrawCheckpointCtx = opts?.withdrawCheckpointCtx;
+        const liveReferences = opts?.liveReferences;
+        if (liveReferences !== undefined) {
+            const live = createLocalSessionLiveReference({ ...liveReferences, claim: (id) => runs.getActiveTaskId(id) });
+            this.liveReferenceOf = live;
+            this.listIdleOfKind = (kind, idleBefore, page) => this.idleOfKind(kind, idleBefore, page, live);
+        }
         this.log = opts?.log ?? createLogger();
         const repoPlacementOf = repo.placementOf;
         const repoListPlaced = repo.listPlaced;
@@ -1078,6 +1089,10 @@ export class LocalSessionStore {
             return headFromRow(sessionId, cell.meta.owner ?? null, cell.meta.incarnation, null);
         return this.headOf(sessionId);
     }
+    async sessionKindOf(sessionId) {
+        const meta = await this.metaOf(sessionId);
+        return meta === undefined ? undefined : { incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), kind: meta.sessionKind };
+    }
     archiveHeadOf(sessionId) {
         return this.repo.headOf(sessionId);
     }
@@ -1095,10 +1110,8 @@ export class LocalSessionStore {
         await this.titles.ensureLoaded();
         return this.titles.state.entries.has(sessionId) ? "titled" : "untitled";
     }
-    async setTitleIfNull(sessionId, title) {
-        return this.withSessionWriteLock(sessionId, async () => {
-            if (!(await this.rowPresentHeld(sessionId)))
-                return false;
+    async setTitleIfNull(sessionId, title, landed) {
+        const out = await this.withLanded(sessionId, landed, async () => {
             await this.titles.ensureLoaded();
             const entries = this.titles.state.entries;
             if (entries.has(sessionId))
@@ -1107,6 +1120,7 @@ export class LocalSessionStore {
             await this.titles.persist();
             return true;
         });
+        return out.landed && out.value;
     }
     async writeSessionRowCells(sessionId, cells, how) {
         return this.withSessionWriteLock(sessionId, async () => {
@@ -1140,7 +1154,7 @@ export class LocalSessionStore {
         const meta = this.liveCellOf(sessionId);
         if (meta === undefined || (await this.rowHeaderOf(sessionId)) === undefined)
             return undefined;
-        return { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), placed: false, mirror: meta.execution?.role === "mirror", cells: this.rowCellsOf(sessionId) };
+        return { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), placed: false, deleting: false, mirror: meta.execution?.role === "mirror", cells: this.rowCellsOf(sessionId) };
     }
     rowCellsOf(sessionId) {
         return { title: this.titles.state.entries.get(sessionId) ?? null, pinned: this.pinned.state.entries.get(sessionId) === true };
@@ -1394,7 +1408,10 @@ export class LocalSessionStore {
             if (placement !== undefined)
                 return this.createPlacedHeld(sessionId, placement, opts ?? {});
             const session = await this.repo.create({ id: sessionId });
-            await this.writeMeta(sessionId, (before) => ({ incarnation: mintSessionIncarnation(), owner: before !== undefined && ownerRecorded(before) ? (readSessionMetaCell(before).owner ?? null) : null, createdAt: rowBornNow() }));
+            await this.writeMeta(sessionId, (before) => {
+                const born = before !== undefined && ownerRecorded(before) ? readSessionMetaCell(before) : undefined;
+                return { incarnation: mintSessionIncarnation(), owner: born?.owner ?? null, createdAt: rowBornNow(), ...(born?.sessionKind !== undefined ? { sessionKind: born.sessionKind } : {}) };
+            });
             return this.handOut(sessionId, session);
         });
     }
@@ -1456,7 +1473,7 @@ export class LocalSessionStore {
     async register(sessionId, owner) {
         await this.registerWithReceipt(sessionId, owner);
     }
-    async registerWithReceipt(sessionId, owner) {
+    async registerWithReceipt(sessionId, owner, kind) {
         return this.withSessionWriteLock(sessionId, async () => {
             await this.meta.ensureLoaded();
             if (this.cellStateOf(sessionId).state === "deleting")
@@ -1473,7 +1490,7 @@ export class LocalSessionStore {
                 if (ownerRecorded(before))
                     return undefined;
                 if (!existed)
-                    return { incarnation: born, owner, createdAt: rowBornNow(), clientWrites: 0 };
+                    return { incarnation: born, owner, createdAt: rowBornNow(), clientWrites: 0, ...(kind !== undefined ? { sessionKind: kind } : {}) };
                 return before === undefined ? { incarnation: first ?? cellChangedUnderLock(sessionId) } : undefined;
             });
             if (!existed && wrote)
@@ -1484,6 +1501,7 @@ export class LocalSessionStore {
     async touch(sessionId) {
         this.lastActivity.set(sessionId, new Date().toISOString());
         this.scheduleFlush();
+        await this.repo.touch?.(sessionId);
     }
     async release(sessionId) {
         this.pending.delete(sessionId);
@@ -1516,6 +1534,8 @@ export class LocalSessionStore {
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
                 continue;
             const meta = this.liveCellOf(row.sessionId);
+            if (!sessionKindListed(meta?.sessionKind, opts.sessionKind))
+                continue;
             const incarnation = meta === undefined ? undefined : incarnationFromCell(row.sessionId, meta.incarnation, "absent");
             all.push({ row: this.summaryOf(row, rollups), occupant: { owner, incarnation } });
         }
@@ -1555,8 +1575,13 @@ export class LocalSessionStore {
             ...rowTag,
             ...("unreadable" in listed ? { unreadable: sessionUnreadableOf(listed.unreadable) } : {}),
             ...this.listedLineageOf(sessionId),
+            ...this.listedKindOf(sessionId),
         };
     }
+    listedKindOf(sessionId) {
+        const kind = this.liveCellOf(sessionId)?.sessionKind;
+        return kind !== undefined ? { sessionKind: kind } : {};
+    }
     listedLineageOf(sessionId) {
         const lineage = forkLineageOfRow(sessionId, this.liveCellOf(sessionId)?.forkedFrom, undefined);
         return lineage.forkedFrom !== undefined ? { forkedFrom: lineage.forkedFrom } : {};
@@ -1679,9 +1704,11 @@ export class LocalSessionStore {
         const entries = await this.exportEntries(sessionId);
         if (entries === null)
             return null;
-        const afterSeq = opts?.afterSeq ?? -1;
+        const afterSeq = opts.afterSeq ?? -1;
         const slice = entries.slice(afterSeq + 1);
         async function* gen() {
+            if (slice.length > 0)
+                await opts.recheck();
             for (const e of slice)
                 yield e;
         }
@@ -1808,8 +1835,9 @@ export class LocalSessionStore {
     async commitStagedImport(sessionId, owner, staged, opts) {
         return this.withImportLock(sessionId, owner, async (importer) => {
             const current = await this.metaHeld(sessionId);
-            if (!ownerCellIs(opts.expectedOwner, current === undefined ? undefined : (current.owner ?? null)))
-                throw new StagedCommitOwnerChangedError(sessionId);
+            const held = current === undefined ? undefined : { owner: current.owner ?? null, incarnation: incarnationFromCell(sessionId, current.incarnation, "absent") };
+            if (opts.expectedOccupant === undefined ? held !== undefined : held === undefined || !sameOccupant(opts.expectedOccupant, held))
+                throw new StagedCommitOccupantChangedError(sessionId);
             await this.assertNotPlacedHeld(sessionId);
             const dstEntries = await this.exportEntries(sessionId);
             const rel = classifySyncRelationshipByIds(staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
@@ -1873,6 +1901,52 @@ export class LocalSessionStore {
             return this.deletingIds().map((sessionId) => ({ sessionId, owner: this.deletionOwnerOf(sessionId), token: this.deletingTokenOf(sessionId) }));
         },
     };
+    async idleOfKind(kind, idleBefore, page, live) {
+        await this.loadRowSidecars();
+        const maybe = [];
+        for (const sessionId of [...this.liveCellIds(), ...this.deletingIds()]) {
+            const cell = this.cellStateOf(sessionId);
+            if (cell.state === "none" || cell.state === "dropping" || cell.meta.sessionKind !== kind)
+                continue;
+            if (this.ageAnchorOf(sessionId, cell.meta, undefined) < idleBefore.getTime())
+                maybe.push({ sessionId, meta: cell.meta });
+        }
+        if (maybe.length === 0)
+            return [];
+        const recorded = new Map((await this.repo.list()).map((r) => [r.id, r.lastActiveAt]));
+        const seen = [];
+        for (const { sessionId, meta } of maybe) {
+            let archived = recorded.get(sessionId);
+            if (!recorded.has(sessionId) && (await this.archiveHeadOf(sessionId).catch(() => "unreadable")) !== undefined)
+                continue;
+            if (archived !== undefined && !Number.isFinite(archived))
+                archived = undefined;
+            const anchor = this.ageAnchorOf(sessionId, meta, archived);
+            if (!(anchor < idleBefore.getTime()))
+                continue;
+            seen.push({ sessionId, owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), lastActivityAt: new Date(anchor).toISOString() });
+        }
+        seen.sort((a, b) => (a.lastActivityAt !== b.lastActivityAt ? (a.lastActivityAt < b.lastActivityAt ? -1 : 1) : a.sessionId < b.sessionId ? -1 : 1));
+        const out = [];
+        for (const row of seen) {
+            if (out.length >= page.limit)
+                break;
+            if (!idleSessionAfter(row, page.after))
+                continue;
+            if (await live(row.sessionId, row.owner))
+                continue;
+            out.push(row);
+        }
+        return out;
+    }
+    ageAnchorOf(sessionId, meta, archived) {
+        const marks = [Date.parse(this.lastActivity.get(sessionId) ?? ""), archived ?? Number.NaN, Date.parse(rowCreatedAtOf(sessionId, meta))].filter((t) => Number.isFinite(t));
+        return marks.length === 0 ? Number.POSITIVE_INFINITY : Math.max(...marks);
+    }
+    unTouchedSince(sessionId, idleBefore) {
+        const touched = this.lastActivity.get(sessionId);
+        return touched === undefined || Date.parse(touched) < idleBefore.getTime();
+    }
     deletionOwnerOf(sessionId) {
         const cell = this.cellStateOf(sessionId);
         return cell.state === "none" ? null : (cell.meta.owner ?? null);
@@ -1903,23 +1977,42 @@ export class LocalSessionStore {
                 return { inProgress: true };
         }
         else {
+            if (opts.ageOut !== undefined && !(await this.ageOutHoldsHeld(sessionId, current, opts.ageOut)))
+                return undefined;
             const verdict = await judgeSessionWrite({ op: "delete", rootSessionId: sessionId }, { claim: () => this.runs.getActiveTaskId(sessionId), cell: async () => ({ role: "absent" }), deleting: async () => this.deletingTokenOf(sessionId) });
             if (verdict !== "proceed")
                 throw verdict.refuse;
         }
         const token = uuidv7();
         let incarnation;
+        let touchedMeanwhile = false;
         const committed = await this.meta.commit((draft) => {
+            if (opts.ageOut !== undefined && state.state !== "deleting" && !this.unTouchedSince(sessionId, opts.ageOut.idleBefore)) {
+                touchedMeanwhile = true;
+                return false;
+            }
             const before = draft.get(sessionId);
             const base = before === undefined ? { incarnation: mintSessionIncarnation() } : cellObjectOf(before);
             incarnation = before === undefined ? undefined : base.incarnation;
             draft.set(sessionId, { ...base, deleting: token });
             return true;
         }, "required");
+        if (touchedMeanwhile)
+            return undefined;
         if (!committed)
             throw new SessionError("storage", `LocalSessionStore: the deletion fence of session ${sessionId} could not be made durable — nothing of the session was removed; retry the delete`);
         return { token, incarnation };
     }
+    async ageOutHoldsHeld(sessionId, current, ageOut) {
+        if (current === undefined || this.liveReferenceOf === undefined)
+            return false;
+        if (incarnationFromCell(sessionId, current.incarnation, "absent") !== ageOut.incarnation || current.sessionKind !== ageOut.kind)
+            return false;
+        await this.loadRowSidecars();
+        if (!(this.ageAnchorOf(sessionId, current, undefined) < ageOut.idleBefore.getTime()))
+            return false;
+        return !(await this.liveReferenceOf(sessionId, current.owner ?? null));
+    }
     async bumpClientWritesHeld(sessionId) {
         await this.meta.ensureLoaded();
         if (this.cellStateOf(sessionId).state === "deleting")
@@ -1940,20 +2033,29 @@ export class LocalSessionStore {
             throw new SessionError("storage", `LocalSessionStore: the client-write count of session ${sessionId} could not be made durable — the write was not made; retry it`);
     }
     async withClientWrite(sessionId, write) {
+        return this.withSessionWriteLock(sessionId, () => this.countedSectionHeld(sessionId, write));
+    }
+    async withLanded(sessionId, landed, body) {
         return this.withSessionWriteLock(sessionId, async () => {
-            let open = true;
-            try {
-                return await write(async () => {
-                    if (!open)
-                        throw new Error(`LocalSessionStore.withClientWrite: session ${sessionId}'s client-write count was taken after its lock section ended`);
-                    await this.bumpClientWritesHeld(sessionId);
-                });
-            }
-            finally {
-                open = false;
-            }
+            await this.loadRowSidecars();
+            if (!judgeLandedRow(sessionId, landed, await this.lockedRowOf(sessionId)))
+                return { landed: false };
+            return { landed: true, value: await this.countedSectionHeld(sessionId, body) };
         });
     }
+    async countedSectionHeld(sessionId, body) {
+        let open = true;
+        try {
+            return await body(async () => {
+                if (!open)
+                    throw new Error(`LocalSessionStore: session ${sessionId}'s client-write count was taken after its lock section ended`);
+                await this.bumpClientWritesHeld(sessionId);
+            });
+        }
+        finally {
+            open = false;
+        }
+    }
     async withdrawBirth(birth, ownTaskId) {
         const runs = this.runs;
         return this.withSessionWriteLock(birth.sessionId, async (dropped) => {

package/dist/plugins/memory-engine-pg.js

@@ -9,6 +9,7 @@ import { assertMemoryScopeWidth } from "./memory-key-guards.js";
 import { exposureBandOf, exposureCarriage, originMarkedSqlPredicate, distilledCarriage } from "./memory-origin-law.js";
 import { applySqlPatches, } from "./memory-engine-sql-apply.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const PG_MEMORY_ENGINE_TABLES = {
     entry: "agent_memory_engine_entry",
     cursor: "agent_memory_engine_cursor",
@@ -301,4 +302,7 @@ export class PgMemoryEngineBackend {
        ON CONFLICT (scope) DO UPDATE SET cursor = $2`, [scope, cursor]);
     }
 }
+sealStoreClass(PgMemoryEngineBackend, "pg-memory-engine-backend", {
+    listHeaders: "exit", getByIds: "exit", search: "exit", applyPatches: "exit", getConsolidationCursor: "exit", setConsolidationCursor: "exit",
+});
 //# sourceMappingURL=memory-engine-pg.js.map

package/dist/plugins/memory-engine-sql-apply.js

@@ -1,6 +1,8 @@
 import { LandingsNeedAdmission, admittingLandings, computeEntryRev, requireLandingsAdmitted, } from "@sema-agent/core";
 import { memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
 import { pgHasUnstorable } from "./pg-safe-json.js";
+import { storeBoundaryFault } from "../terminal.js";
+import { markErrorOrigin } from "./error-origin.js";
 import { ambiguousOriginRefusal, createBatchCommittedBaseline, distilledWhitewashRefusal, originWhitewashRefusal, rememberBatchCommitted, unknownPatchOpRefusal, } from "./memory-origin-law.js";
 const FIRST_SUFFIX_STEP = 2;
 const candidateAt = (slug, n) => (n === FIRST_SUFFIX_STEP ? slug : `${slug}-${n - 1}`);
@@ -317,7 +319,8 @@ export async function applySqlPatches(patches, opts, leg) {
                 throw err;
             if (issued)
                 mayHaveWritten = true;
-            report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
+            const seen = storeBoundaryFault(err, "memory-engine.applyPatches");
+            report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${seen instanceof Error ? seen.message : String(seen)}` });
             return [];
         }
     };
@@ -345,7 +348,7 @@ export async function applySqlPatches(patches, opts, leg) {
         await admittingLandings(admit, attempt);
     }
     catch (err) {
-        throw err instanceof CallerThrow ? err.thrown : err;
+        throw err instanceof CallerThrow ? markErrorOrigin(err.thrown, "caller") : err;
     }
     finally {
         if (leg.appendHistory && history.length > 0)

package/dist/plugins/memory-engine-tidb.js

@@ -9,6 +9,7 @@ import { applySqlPatches, } from "./memory-engine-sql-apply.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { MEMORY_ENGINE_INDEXES, PG_MEMORY_ENGINE_TABLES } from "./memory-engine-pg.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const TIDB_MEMORY_ENGINE_TABLES = {
     entry: "agent_memory_engine_entry",
     cursor: "agent_memory_engine_cursor",
@@ -265,4 +266,7 @@ export class TiDBMemoryEngineBackend {
         await this.write(`INSERT INTO ${TIDB_MEMORY_ENGINE_TABLES.cursor} (scope, \`cursor\`) VALUES (?, ?) ON DUPLICATE KEY UPDATE \`cursor\` = VALUES(\`cursor\`)`, [scope, cursor]);
     }
 }
+sealStoreClass(TiDBMemoryEngineBackend, "tidb-memory-engine-backend", {
+    listHeaders: "exit", getByIds: "exit", search: "exit", applyPatches: "exit", getConsolidationCursor: "exit", setConsolidationCursor: "exit",
+});
 //# sourceMappingURL=memory-engine-tidb.js.map

package/dist/plugins/memory-optout-grant-store-sql.js

@@ -1,5 +1,6 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { PRINCIPAL_MAX_BYTES, RESERVED_PRINCIPALS, RESERVED_PRINCIPAL_PREFIXES } from "../principal-shape.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const MEMORY_OPTOUT_GRANT_TABLE = "memory_optout_grant";
 export const MEMORY_OPTOUT_DEFAULT_PRINCIPAL = "";
 export function buildMemoryOptOutVerdict(rows, principal) {
@@ -124,6 +125,9 @@ export class SqlMemoryOptOutGrantStore {
         return { principal, allow: input.allow, updatedAtMs: at, updatedBy: input.updatedBy, ...(note !== null ? { note } : {}) };
     }
 }
+sealStoreClass(SqlMemoryOptOutGrantStore, "sql-memory-opt-out-grant-store", {
+    resolveAllow: "exit", list: "exit", putDefault: "exit", putOverride: "exit", deleteOverride: "exit",
+});
 export class TiDBMemoryOptOutGrantStore extends SqlMemoryOptOutGrantStore {
     constructor(pool, now) {
         super(mysqlDriver(pool), "mysql", now);