@sema-agent/server 7.146.0 → 7.147.0

package/dist/plugins/sql-driver.js

@@ -2,6 +2,30 @@ import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js"
 import { recordFailOpen } from "../observability/fail-open.js";
 import { errorKindOf } from "../observability/err-text.js";
 import { isConnectionUnusableError } from "./sql-errors.js";
+export class SqlStatementDeadlineExceeded extends Error {
+    deadlineMs;
+    constructor(deadlineMs) {
+        super(`SQL statement did not settle within ${deadlineMs}ms — the connection was destroyed (its transaction rolls back when it closes)`);
+        this.deadlineMs = deadlineMs;
+        this.name = "SqlStatementDeadlineExceeded";
+    }
+}
+function withStatementDeadline(run, opts, destroy) {
+    const deadlineMs = opts?.deadlineMs;
+    if (deadlineMs === undefined)
+        return run();
+    const running = run();
+    running.catch(() => undefined);
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            destroy();
+            reject(new SqlStatementDeadlineExceeded(deadlineMs));
+        }, deadlineMs);
+        timer.unref?.();
+    });
+    return Promise.race([running, expired]).finally(() => clearTimeout(timer));
+}
 export const TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT = 6_291_456;
 export const ROW_WALL_ALLOWANCE_BYTES = { json: 64 * 1024, blob: 1024 };
 export const STATEMENT_ALLOWANCE_BYTES = 1024;
@@ -299,15 +323,20 @@ function leaseOf(raw) {
     if (GUARDED_LEASES.has(raw))
         return raw;
     let destroyed = false;
+    let leaveQueue = () => undefined;
+    const gone = new Promise((resolve) => {
+        leaveQueue = resolve;
+    });
     const destroy = () => {
         if (destroyed)
             return;
         destroyed = true;
+        leaveQueue();
         raw.destroy();
     };
     let turn = Promise.resolve();
     const guard = (run) => {
-        const result = turn.then(async () => {
+        const result = Promise.race([turn, gone]).then(async () => {
             try {
                 return await run();
             }
@@ -388,7 +417,7 @@ export function mysqlDriver(pool) {
             if (broken !== undefined)
                 throw broken.error;
             const conn = {
-                query: (sql, params) => mysqlQuery(c, sql, params),
+                query: (sql, params, opts) => withStatementDeadline(() => mysqlQuery(c, sql, params), opts, () => c.destroy()),
                 begin: () => c.beginTransaction(),
                 commit: () => c.commit(),
                 rollback: () => c.rollback(),
@@ -440,8 +469,14 @@ export function pgDriver(pool) {
             const c = await pool.connect();
             const { facts, initOrdinal } = await establishSession(session, c, c, initPgSession);
             let destroyed = false;
+            const destroy = () => {
+                if (destroyed)
+                    return;
+                destroyed = true;
+                c.release(true);
+            };
             const conn = {
-                query: (sql, params) => pgQuery(c, sql, params),
+                query: (sql, params, opts) => withStatementDeadline(() => pgQuery(c, sql, params), opts, destroy),
                 begin: async () => {
                     await c.query("BEGIN");
                 },
@@ -449,7 +484,8 @@ export function pgDriver(pool) {
                     await c.query("COMMIT");
                 },
                 rollback: async () => {
-                    await c.query("ROLLBACK");
+                    if (!destroyed)
+                        await c.query("ROLLBACK");
                 },
                 release: () => {
                     if (!destroyed)
@@ -461,10 +497,7 @@ export function pgDriver(pool) {
                 facts,
                 initOrdinal,
                 id: typeof pid === "number" ? pid : null,
-                destroy: () => {
-                    destroyed = true;
-                    c.release(true);
-                },
+                destroy,
                 readGlobalPacketWall: async () => null,
             });
             return conn;

package/dist/plugins/sql-errors.d.ts

@@ -193,12 +193,15 @@ export declare function isConnectionFaultError(err: unknown): boolean;
  * **部署错配类故障**的识别表(闭集;逐行登记「为什么」)—— 到库的连接是好的、语句也是对的,是这套库的形与本部署的要求不符:**重试注定失败**,修表 / 授权之前什么都不会变
  * (与连接类互为反面:那一类是「什么都不改稍后再试可能成」)。读者:整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf` 的 `deployment` 一词 ——
  * 文件历史店的折点与会话同步拉取口(`503 state.file_history_unreadable`)据它判 `permanence: "terminal"`;审批队列读口并入「此刻读不出」的 503;各读者各自表态,**不在自己那里写码**。
+ * 起服建表(`session-ext-table.ts` 的 `ensureSessionExtTableMysql`)问的也是这一只:「库确定拒了这条 DDL」= 本表认得 ⇒ 当场拒启;认不出 ⇒ 原样上抛、开库等待窗重试 —— 不自带第二份分类。
+ * 外键四码(3780 / 1215 / 1822 / 1005)只可能出在建表 / 改表上,读写路径上的读者见不到它们 —— 加进本表对那几处零变化。
  *
  * 识别集 = 本表一张,按归因键登记:`code`(字符串)与 MySQL 协议的数字 `errno`(两键是同一件事的两种写法,代理 / 序列化往返可能只留一个;同本文件其余谓词的姿势)。
  * **与连接类互斥**:本表的任何一码都不在 {@link CONNECTION_FAULT_ERRORS} / {@link MYSQL_CONNECTION_UNUSABLE_ERRORS} 的识别集里,反之亦然(`test/store-fault-judge.test.ts` 钉两个方向)—— 同一只错只落一个词。
  *
- * **不在表里**(认不出一律不是;本批只收缺表与权限拒两形,其余是登记在案的未收项,不是「已裁定不判」):缺列(1054 / `42703`:升级前置断言 `assert*Schema` 族有自己的判据与出路)、
- * 认证类拒连(MySQL 1045、PG `28xxx`:凭据 / 白名单)、库级与列级的权限拒(MySQL 1044 / 1143)、TiDB 自己的忙 / 区域不可用一族(同连接类表的登记)。
+ * **不在表里**(认不出一律不是;今天收缺表、权限拒与外键建不成三形,其余是登记在案的未收项,不是「已裁定不判」):缺列(1054 / `42703`:升级前置断言 `assert*Schema` 族有自己的判据与出路)、
+ * 认证类拒连(MySQL 1045、PG `28xxx`:凭据 / 白名单)、库级与列级的权限拒(MySQL 1044 / 1143)、语法错(1064:多半是我方的语句,不是库的形)、
+ * TiDB 自己的忙 / 区域不可用 / 结构变更冲突一族(9001 / 9005 / 8028,同连接类表的登记)、锁等待超时(1205)。
  */
 export declare const DEPLOYMENT_FAULT_ERRORS: ReadonlyArray<{
     readonly code: string;

package/dist/plugins/sql-errors.js

@@ -148,6 +148,10 @@ export const DEPLOYMENT_FAULT_ERRORS = [
     { code: "42501", why: "PG insufficient_privilege(权限拒:库账号缺这张表 / 这类语句的授权 —— 授权之前重试注定失败)" },
     { code: "ER_NO_SUCH_TABLE", errno: 1146, why: "MySQL 协议(MySQL / MariaDB / TiDB)缺表:同 PG `42P01`" },
     { code: "ER_TABLEACCESS_DENIED_ERROR", errno: 1142, why: "MySQL 协议表级权限拒:库账号对这张表缺这类语句的授权,同 PG `42501`" },
+    { code: "ER_FK_INCOMPATIBLE_COLUMNS", errno: 3780, why: "MySQL 协议外键两侧列不相容(类型 / 字符集 / 排序规则对不上):被引表的形与外键要求不符,重试同一句仍不相容" },
+    { code: "ER_CANNOT_ADD_FOREIGN", errno: 1215, why: "MySQL 协议加不上外键(如被引表不是 InnoDB):库的形不收这条约束,改表之前重试注定失败" },
+    { code: "ER_FK_NO_INDEX_PARENT", errno: 1822, why: "MySQL 协议外键的被引列上缺索引:被引表的形不符,建索引之前重试注定失败" },
+    { code: "ER_CANT_CREATE_TABLE", errno: 1005, why: "MySQL 协议建表被存储引擎拒(errno 150 外键形不成 / 121 约束名已占 / 28 盘满):修库之前重试同一句仍被拒" },
 ];
 const DEPLOYMENT_FAULT_CODES = new Set(DEPLOYMENT_FAULT_ERRORS.map((r) => r.code));
 const DEPLOYMENT_FAULT_ERRNOS = new Set(DEPLOYMENT_FAULT_ERRORS.flatMap((r) => (r.errno === undefined ? [] : [r.errno])));

package/dist/plugins/store-backend.d.ts

@@ -33,9 +33,12 @@ import type { CounterDegradeHook } from "./write-behind-counter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
 import { type SqlSharedMemoryStore, type SharedMemoryScopeAuthorizer } from "./shared-memory-store-sql.js";
 import { type AdoptionLogStore } from "./adoption-log-sql.js";
-import { type SqlRetentionStore, type SqlRetentionStoreOptions } from "./retention-store-sql.js";
+import { type SqlTransactionHooks } from "../stores-sql/retention-store-sql.js";
+import type { EndedSpace } from "../workspace-space.js";
+import { type RetentionDestructiveInput, type RetentionExecutor, type RetentionExecutorOptions } from "./retention-deployment.js";
 import { type RetentionLaneStore } from "./retention-lane-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
+import { type SqlDriver } from "./sql-driver.js";
 import { type StoreDegradedReason } from "../store-posture.js";
 /** boot 期的一条日志座(级别由**座位**决定,不由参数携带):`createStoreBackend` 的 `onWarn` / `onError`
  *  两参与 `LocalBackend` 的同名字段共用此形。装配层把它们分别接到 `logger.warn` / `logger.error` 上。 */
@@ -65,7 +68,7 @@ export type ServiceSessionPolicyStore = SessionPolicyStore;
  * The SQL twins' blob exchange — core's {@link FileHistoryBlobExchange} group (`put` / `get` / `has`, all three or none, read only
  * through `blobExchangeOf` in `session-sync.ts`, which defers to core's judge) with ONE narrowing: a `put` refusal may carry
  * `blobCap`, the SQL blob judge's refusal on the connection that would have written the blob
- * ({@link import("./blob-backend.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
+ * ({@link import("../stores-sql/blob-index-sql.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
  * `blob_too_large_for_sql` (the judge's sentence, plus the machine-readable `wallSource` = where the cap came from). The content-address
  * refusal is core's own (`adopt_failed`, `permanence: "terminal"`, nothing stored); every other failure is a write fault the route answers 502.
  */
@@ -75,7 +78,7 @@ export type SqlBlobPutResult = {
     readonly ok: false;
     readonly error: FileHistoryError & {
         readonly blobCap?: {
-            readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+            readonly wallSource: import("../stores-sql/blob-index-sql.js").SqlBlobCapReading["source"];
         };
     };
 };
@@ -163,7 +166,8 @@ export interface StoreBackend {
      *  schema that the one-time migrations of server 7.74.0–7.125.x retired and **refuses** with `RetiredSchemaPresentError`
      *  (code `config.schema_mismatch`, exported from the package root) before it issues the first CREATE; only then does it create.
      *  The check lives in this method itself, so the public sequence `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
-     *  needs no step of its own. The LOCAL backend has no SQL pool and nothing to probe. */
+     *  needs no step of its own. The LOCAL backend has no SQL pool: its data root's engine high-water is judged when the backend is opened (before any store is built),
+     *  and a data root refused there surfaces here, as that refusal; otherwise this runs the local reconciliation (strict sidecars, archive snapshots). */
     ensureSchema(): Promise<void>;
     close(): Promise<void>;
     run(): RunStore;
@@ -354,7 +358,7 @@ export interface StoreBackend {
      * `local` 刻意省略 —— 与 {@link leaderRun} 逐字同一条理由:config 层已经把「`REMOTE_EXEC=device` 且
      * 无外部 SQL 店」整个组合拒启了(`device-durable-store` 不变量),所以 local 车道上根本不存在一个需要
      * 这四张表的 device worker。消费点按 `backend?.device?.()` 取,缺席 ⇒ `boot/device-lane.ts` 的
-     * `assertDeviceLaneWired` 响亮拒启(**不是**静默落进程内 stub)。
+     * `assertDeviceLaneWired` 响亮拒启(**不是**静默跑成无手)。
      */
     device?(): DeviceStore;
     /**
@@ -364,9 +368,9 @@ export interface StoreBackend {
      *
      * `taskAttachmentTable` 必填、无默认值 —— boot 只在配了对象存储时才 ensure 那张表,一条盲发的
      * DELETE 在无 MinIO 的部署上会以 unknown-table 打红整轮 sweep(理由逐字见
-     * `retention-store-sql.ts` 的 `SqlRetentionStoreOptions`)。
+     * `retention-deployment.ts` 的 `RetentionExecutorOptions`)。组合形见 {@link createSqlRetentionExecutor}。
      */
-    retention?(opts: SqlRetentionStoreOptions): SqlRetentionStore;
+    retention?(opts: RetentionExecutorOptions): RetentionExecutor;
     /**
      * [ref] 车2 —— 留存执行面的**非破坏性**半场:sweep 租约、legal-hold 的放置/解除、审计表的读与
      * 非破坏行的写。同样 SQL 专有(它写的三张表只在 SQL schema 里)。
@@ -403,6 +407,23 @@ export interface StoreBackend {
      *  `new FileUsageWindowStore(root)` 第二只实例、不接座 ⇒ 坏值只拒不披露,运维找不到是哪只文件。SQL 后端省略(它们有自己的 usage-window 双方言店)。 */
     fileUsageWindowStore?(): UsageWindowStore;
 }
+/**
+ * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十一张部署表,
+ * `plugins/retention-deployment.ts`,经 K4 事务内钩参与同一事务)。
+ *
+ * 破坏性三方法**每次调用**铸一只执行器、钩表绑这一次调用(`createRetentionDeploymentHooks` 的头注:审计行的判定时点三格与
+ * `checkpoint_ctx` 属主门的域是这一次调用的事实)。会话树删除的 `endedSpaces` 由部署从 `beforeDelete` 收到的行自算,
+ * 只在执行器**提交成功返回之后**挂上回执(回滚 ⇒ 执行器抛,不挂)。非破坏两口(域枚举 / 预览)不经钩。
+ */
+/**
+ * 一次破坏性调用的整张事务内钩表:部署的 `retention` 组(按这一次调用铸,`createRetentionDeploymentHooks`)+ 会话座的钩
+ * (`createSqlSessionWriteHooks`,会话店用的同一只工厂;留存删除走它的 `retention-delete` 臂)。`endedSpaces` 读部署那一半收到的行。
+ */
+export declare function createSqlRetentionCallHooks(db: SqlDriver, opts: RetentionExecutorOptions, input: RetentionDestructiveInput): {
+    readonly hooks: SqlTransactionHooks;
+    endedSpaces(): readonly EndedSpace[];
+};
+export declare function createSqlRetentionExecutor(db: SqlDriver, opts: RetentionExecutorOptions): RetentionExecutor;
 /** (c)(clay 拍 a+c,2026-07-27;[ref] 换店后域=file_history_blob,门与旋钮名不变)云形 blob 姿势门——
  *  boot 时调用(boot/stores.ts),纯函数可单测。SQL 后端(mysql|pg)把 blob 字节落单行的形已被两役
  *  实证撞 mysql-协议包墙(D-1 附件 → 对象存储裁定):大字节归对象存储。per-file 历史的 blob=单文件
@@ -471,7 +492,13 @@ export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootL
  *  而 LocalBackend 的 `ensureSchema` 是**空实现**,真正会抛的 mkdir + 数据根 BootLock 在构造函数里、
  *  落在 try 之外。于是那条降级臂对 local 形从来没生效过,注释宣称的行为与代码真做的事撕裂。
  *
- *  **降级臂只有一条:缺省推导的 local**(`dbBackend=local && !dbBackendExplicit`)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
+ *  **降级臂只有一条:缺省推导的 local 且数据根上什么都没有**(`dbBackend=local && !dbBackendExplicit`,数据根不存在或是空目录 —— 开店之前判)。
+ *  判据看的是**数据根的状态**,不是错误的种类:数据根上已有东西 ⇒ 这台部署有过持久面,开它时的**任何**失败(权限 / 只读挂载 / 子目录建不出 /
+ *  另一实例持锁 / adoption 在飞 / 账本重放不了 …)都按显式 `DB_BACKEND=local` 同待遇 —— 原样抛、拒启,不退内存(退了 = 已有的会话 / run 账本 /
+ *  问账整片看不见、新写只进内存,而 `/health` 照样 200)。只有「数据根不存在 / 空」那一形是「这台机器存不了盘」的诚实等价物,才许退内存 + 一行 warn。
+ *  修前按错误种类逐个豁免(adoption 一条、File 店族拒启一条、再往各店构造器里逐处包),漏一处就是一条 fail-open;按状态判之后,新店的新失败默认落在拒启一侧。
+ *  1.292 的口径据此收窄:只读挂载 / 建不出的根**在空 / 不存在时**仍退内存;已有数据的根拒启(出路:修好权限 / 挂载 / 停掉持锁的另一实例;要内存就显式写
+ *  `DB_BACKEND=memory`;要另起一个空根就把 `LOCAL_DATA_ROOT` 指过去)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
  *  `SESSION_BACKEND=auto` 与显式 `DB_BACKEND=mysql|pg` 同一待遇,库当下打不开 ⇒ 在 `STORE_LOCK_WAIT_MS` 的窗内重试
  *  ({@link openWithinWait}),到窗仍打不开 ⇒ 拒启(拒句 {@link buildSqlStoreOpenRefusal} 点名后端与库的显示安全形)。修前 `auto` 在这里
  *  静默落内存(只留一行 warn):会话 / 停驻 / run 账本进进程内存、重启即丢,而 `/health` 照样 200 —— [ref] P 类 fail-open。

package/dist/plugins/store-backend.js

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import { createCorruptReadSeat, createDurableAbsenceSeat } from "../observability/corrupt-read-seat.js";
 import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { AdoptionError, FileStorageBackend } from "@sema-agent/core";
 import { FileWorkflowJournalStore } from "@sema-agent/core";
 import { fileSessionCaptureRecordStore } from "@sema-agent/core";
@@ -34,10 +34,11 @@ import { TiDBUserInputLedgerStore, PgUserInputLedgerStore } from "./user-input-l
 import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-store-sql.js";
 import { TiDBSessionPolicyStore, PgSessionPolicyStore } from "../stores-sql/session-policy-store-sql.js";
 import { TiDBWorkflowJournalStore, PgWorkflowJournalStore } from "../stores-sql/workflow-journal-store-sql.js";
-import { TiDBFileHistoryStore, PgFileHistoryStore, FILE_HISTORY_BLOB_TABLE, FILE_HISTORY_BLOB_KEY_PREFIX } from "./file-history-store-sql.js";
-import { MinioBlobBackend, SqlBlobBackend } from "./blob-backend.js";
+import { TiDBFileHistoryStore, PgFileHistoryStore, FILE_HISTORY_BLOB_KEY_PREFIX } from "../stores-sql/file-history-store-sql.js";
+import { SqlBlobIndex } from "../stores-sql/blob-index-sql.js";
+import { MinioBlobBackend } from "./blob-backend.js";
 import { buildDisplaySafeUrl } from "../trace/redact.js";
-import { fileMemoryControlDirFor } from "../memory-scope.js";
+import { fileMemoryControlDirFor, memoryEngineRootFor } from "../memory-scope.js";
 import { createTidbPool, ensureSchema as ensureTidbSchema } from "./tidb-pool.js";
 import { createPgPool, ensurePgSchema, pgPoolOptions } from "./pg-pool.js";
 import { TiDBRunStore, PgRunStore } from "./run-store-sql.js";
@@ -52,48 +53,62 @@ import { TiDBCostQuota } from "./tidb-cost-quota.js";
 import { PgCostQuota } from "./pg-cost-quota.js";
 import { TiDBRateLimiter } from "./tidb-rate-limiter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
-import { TiDBSessionStore } from "./tidb-session-store.js";
-import { PgSessionStore } from "./pg-session-storage.js";
+import { TiDBSessionStore } from "../stores-sql/tidb-session-store.js";
+import { PgSessionStore } from "../stores-sql/pg-session-storage.js";
+import { SqlSessionStore } from "./session-store-sql.js";
 import { TiDBSharedMemoryStore, PgSharedMemoryStore } from "./shared-memory-store-sql.js";
 import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js";
-import { TiDBRetentionStore, PgRetentionStore, sqlStoreRetention } from "./retention-store-sql.js";
+import { SqlRetentionStore } from "../stores-sql/retention-store-sql.js";
+import { sqlStoreRetention } from "./retention-declaration.js";
+import { createRetentionDeploymentHooks } from "./retention-deployment.js";
+import { createSqlSessionWriteHooks } from "./session-store-sql.js";
 import { TiDBRetentionLaneStore, PgRetentionLaneStore } from "./retention-lane-store-sql.js";
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
 import { FILE_PERMISSION_RULE_DIR, createFilePermissionRuleStores, fileRuleBucketOwners, isFileBucketDamaged } from "./permission-rule-store-file.js";
 import { retireImportedLayerRootAllows } from "./imported-layer-root-retirement.js";
+import { buildDataDirLayout, tightenLocalDataDirModes } from "./local-data-dir-modes-m39.js";
+import { holdEngineHighWater } from "./local-engine-high-water.js";
+import { serviceVersion } from "../service-version.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { storeDegradedReasonFor } from "../store-posture.js";
 import { openWithinWait } from "./store-open-wait.js";
 export function workflowJournalOf(config, backend) {
     return config.selfOrchestrationEnabled && backend ? backend.workflowJournal() : undefined;
 }
-function historyBlobBackend(config, dialect, pool) {
+function fileHistoryOptions(config) {
     const s = config.snapshotBlobStore;
-    if (!s)
-        return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes, FILE_HISTORY_BLOB_TABLE, createLogger(config.logLevel));
-    return new MinioBlobBackend({
-        endpoint: s.endpoint,
-        bucket: s.bucket,
-        accessKey: s.accessKey,
-        secretKey: s.secretKey,
-        ...(s.region ? { region: s.region } : {}),
-        keyPrefix: `${s.keyPrefix ?? ""}${FILE_HISTORY_BLOB_KEY_PREFIX}`,
-        ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
-    }, { dialect, pool, table: FILE_HISTORY_BLOB_TABLE });
+    const placement = s
+        ? {
+            blobs: new MinioBlobBackend({
+                endpoint: s.endpoint,
+                bucket: s.bucket,
+                accessKey: s.accessKey,
+                secretKey: s.secretKey,
+                ...(s.region ? { region: s.region } : {}),
+                keyPrefix: `${s.keyPrefix ?? ""}${FILE_HISTORY_BLOB_KEY_PREFIX}`,
+                ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
+            }),
+        }
+        : {
+            ...(config.snapshotBlobSqlMaxBytes !== undefined ? { blobSqlMaxBytes: config.snapshotBlobSqlMaxBytes } : {}),
+            log: createLogger(config.logLevel),
+        };
+    return { ...config.fileHistory, ...placement };
 }
-function legacyBlobBackend(config, dialect, pool) {
+function legacyBlobIndex(config, dialect, pool) {
     const s = config.snapshotBlobStore;
-    if (!s)
-        return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes, undefined, createLogger(config.logLevel));
-    return new MinioBlobBackend({
-        endpoint: s.endpoint,
-        bucket: s.bucket,
-        accessKey: s.accessKey,
-        secretKey: s.secretKey,
-        ...(s.region ? { region: s.region } : {}),
-        ...(s.keyPrefix ? { keyPrefix: s.keyPrefix } : {}),
-        ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
-    }, { dialect, pool });
+    const bytes = s
+        ? new MinioBlobBackend({
+            endpoint: s.endpoint,
+            bucket: s.bucket,
+            accessKey: s.accessKey,
+            secretKey: s.secretKey,
+            ...(s.region ? { region: s.region } : {}),
+            ...(s.keyPrefix ? { keyPrefix: s.keyPrefix } : {}),
+            ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
+        })
+        : undefined;
+    return new SqlBlobIndex(dialect, pool, { table: "snapshot_blob", ...(bytes !== undefined ? { bytes } : {}), log: createLogger(config.logLevel) });
 }
 async function legacySweepImpl(config, dialect, pool) {
     const sql = "SELECT blob_hash FROM snapshot_blob";
@@ -108,7 +123,38 @@ async function legacySweepImpl(config, dialect, pool) {
     }
     if (orphans.length === 0)
         return 0;
-    return legacyBlobBackend(config, dialect, pool).deleteBlobs(orphans);
+    return legacyBlobIndex(config, dialect, pool).sweep(orphans);
+}
+export function createSqlRetentionCallHooks(db, opts, input) {
+    const deployment = createRetentionDeploymentHooks(db.dialect, opts, input);
+    return { hooks: { retention: deployment.hooks.retention, session: createSqlSessionWriteHooks(db) }, endedSpaces: deployment.endedSpaces };
+}
+export function createSqlRetentionExecutor(db, opts) {
+    const logged = opts.logger !== undefined ? { logger: opts.logger } : {};
+    const reads = new SqlRetentionStore(db, logged);
+    const forCall = (input) => {
+        const hooks = createSqlRetentionCallHooks(db, opts, input);
+        return { store: new SqlRetentionStore(db, { ...logged, transactionHooks: hooks.hooks }), hooks, call: { domain: input.domain, cutoffMs: input.cutoffMs } };
+    };
+    return {
+        retention: reads.retention,
+        listRetentionDomains: () => reads.listRetentionDomains(),
+        previewRetention: (input) => reads.previewRetention(input),
+        expireCheckpoints: async (input) => {
+            const one = forCall(input);
+            return one.store.expireCheckpoints(one.call);
+        },
+        deleteExpiredSessions: async (input) => {
+            const one = forCall(input);
+            const receipt = await one.store.deleteExpiredSessions(one.call);
+            const endedSpaces = one.hooks.endedSpaces();
+            return endedSpaces.length > 0 ? { ...receipt, endedSpaces } : receipt;
+        },
+        deleteOrphanToolResults: async (input) => {
+            const one = forCall(input);
+            return one.store.deleteOrphanToolResults(one.call);
+        },
+    };
 }
 export function assertCloudSnapshotBlobPosture(kind, config) {
     if (kind === "local" || config.snapshotBlobStore || config.snapshotBlobAllowSql)
@@ -141,12 +187,12 @@ class TiDBBackend {
     sendFileLedger() { return new TiDBSendFileLedger(this.pool); }
     userInputLedger() { return new TiDBUserInputLedgerStore(this.pool); }
     sessionPolicy(logger) { return new TiDBSessionPolicyStore(this.pool, logger); }
-    fileHistory() { return new TiDBFileHistoryStore(this.pool, historyBlobBackend(this.config, "mysql", this.pool), this.config.fileHistory); }
+    fileHistory() { return new TiDBFileHistoryStore(this.pool, fileHistoryOptions(this.config)); }
     memoryOptOutGrant() { return new TiDBMemoryOptOutGrantStore(this.pool); }
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new TiDBSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
     legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "mysql", this.pool); }
-    runOneTimeMigrations() { return runSqlOneTimeMigrations("mysql", this.pool, { lanes: deployedExecutionLanes(this.config) }); }
+    runOneTimeMigrations() { return runSqlOneTimeMigrations("mysql", this.pool, { lanes: deployedExecutionLanes(this.config), liveRunWindowMs: this.config.runStaleSec * 1000 }); }
     workflowJournal() { return new TiDBWorkflowJournalStore(this.pool); }
     outcomeSink() { return new TiDBOutcomeLedger(this.pool); }
     workflowRun(onWarn) { return new TiDBWorkflowRunStore(this.pool, onWarn); }
@@ -163,12 +209,12 @@ class TiDBBackend {
     imageBake() { return new TiDBImageBake(this.pool); }
     leaderRun() { return new TiDBLeaderRunStore(this.pool); }
     device() { return new TiDBDeviceStore(this.pool); }
-    retention(opts) { return new TiDBRetentionStore(this.pool, opts); }
+    retention(opts) { return createSqlRetentionExecutor(mysqlDriver(this.pool), opts); }
     retentionLane() { return new TiDBRetentionLaneStore(this.pool); }
     breaker(onWriteFail) { return new TiDBBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new TiDBCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new TiDBRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new TiDBSessionStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
+    session() { return new SqlSessionStore(mysqlDriver(this.pool), (hooks) => new TiDBSessionStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep), hooks })); }
     adoptionLog() { return new TiDBAdoptionLogStore(this.pool); }
     mysqlPool() { return this.pool; }
     pgPool() { return undefined; }
@@ -195,12 +241,12 @@ class PgBackend {
     sendFileLedger() { return new PgSendFileLedger(this.pool); }
     userInputLedger() { return new PgUserInputLedgerStore(this.pool); }
     sessionPolicy(logger) { return new PgSessionPolicyStore(this.pool, logger); }
-    fileHistory() { return new PgFileHistoryStore(this.pool, historyBlobBackend(this.config, "pg", this.pool), this.config.fileHistory); }
+    fileHistory() { return new PgFileHistoryStore(this.pool, fileHistoryOptions(this.config)); }
     memoryOptOutGrant() { return new PgMemoryOptOutGrantStore(this.pool); }
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new PgSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
     legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "pg", this.pool); }
-    runOneTimeMigrations() { return runSqlOneTimeMigrations("pg", this.pool, { lanes: deployedExecutionLanes(this.config) }); }
+    runOneTimeMigrations() { return runSqlOneTimeMigrations("pg", this.pool, { lanes: deployedExecutionLanes(this.config), liveRunWindowMs: this.config.runStaleSec * 1000 }); }
     workflowJournal() { return new PgWorkflowJournalStore(this.pool); }
     outcomeSink() { return new PgOutcomeLedger(this.pool); }
     workflowRun(onWarn) { return new PgWorkflowRunStore(this.pool, onWarn); }
@@ -217,12 +263,12 @@ class PgBackend {
     imageBake() { return new PgImageBake(this.pool); }
     leaderRun() { return new PgLeaderRunStore(this.pool); }
     device() { return new PgDeviceStore(this.pool); }
-    retention(opts) { return new PgRetentionStore(this.pool, opts); }
+    retention(opts) { return createSqlRetentionExecutor(pgDriver(this.pool), opts); }
     retentionLane() { return new PgRetentionLaneStore(this.pool); }
     breaker(onWriteFail) { return new PgBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new PgCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new PgRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new PgSessionStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
+    session() { return new SqlSessionStore(pgDriver(this.pool), (hooks) => new PgSessionStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep), hooks })); }
     adoptionLog() { return new PgAdoptionLogStore(this.pool); }
     mysqlPool() { return undefined; }
     pgPool() { return this.pool; }
@@ -250,26 +296,16 @@ class LocalBackend {
     discloseWarn;
     parkDecisionLedgerRoot;
     executionLanes;
-    constructor(root, config, onWarn, onError) {
+    dataDirLayout;
+    constructor(fileBackend, config, discloseWarn, onWarn, onError) {
         this.executionLanes = deployedExecutionLanes(config);
         this.onWarn = onWarn;
-        this.discloseWarn = onWarn ?? ((msg, meta) => console.warn(msg, meta));
+        this.discloseWarn = discloseWarn;
         this.onError = onError;
-        try {
-            this.fileBackend = acquireLocalBackendWithWait(() => new FileStorageBackend({
-                root,
-                ...(config.fileHistory !== undefined ? { fileHistory: config.fileHistory } : {}),
-                onCorruptRead: createDurableAbsenceSeat((msg, fields) => this.discloseWarn(msg, fields), root, "file-history = a rewind boundary or scope read as missing"),
-            }), config.storeLockWaitMs, (fields) => this.onWarn?.("store_dir_lock_wait", { ...fields }));
-        }
-        catch (e) {
-            if (e instanceof AdoptionError)
-                throw e;
-            const tail = buildStoreOpenRefusalTail(e, "http");
-            throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)}` +
-                (tail === undefined ? "" : ` ${tail}`));
-        }
+        this.fileBackend = fileBackend;
+        const root = localBackendRootOf(config);
         const corruptReadWarn = (msg, fields) => this.discloseWarn(msg, fields);
+        this.dataDirLayout = buildDataDirLayout({ configuredRoot: root, physicalRoot: this.fileBackend.root, memoryEngineRoot: memoryEngineRootFor(config, root) });
         this.runStore = new FileRunStore(this.fileBackend.root, {
             error: (msg, fields) => void (this.onError ?? this.onWarn)?.(msg, fields),
             strictHydrate: config.runStoreStrictHydrate,
@@ -297,22 +333,32 @@ class LocalBackend {
             : (plane) => fileSessionCaptureRecordStore(plane?.controlDir ?? ownControlDir);
     }
     async ensureSchema() {
+        this.executionLaneWordsRenamed += await this.sessionStore.renameRetiredExecutionLaneWordM40();
         await this.sessionStore.assertStrictSidecarsReadable();
         await this.sessionStore.settleArchiveSnapshots();
     }
+    executionLaneWordsRenamed = 0;
     async runOneTimeMigrations() {
+        tightenLocalDataDirModes(this.dataDirLayout, {
+            tightened: (msg, meta) => this.onWarn?.(msg, meta),
+            refused: (msg, meta) => this.discloseWarn(msg, meta),
+        });
         const archives = await this.sessionStore.migrateLocalArchives();
         const placements = await backfillLocalExecutionPlacements(this.runStore.sessionIdsWithRuns(), this.sessionStore.executionPlacementBackfill, { lanes: this.executionLanes });
-        const importedLayerRoot = { importedLayerRootAllowsRetired: [], importedLayerRootBucketsSkipped: [] };
+        const importedLayerRoot = { importedLayerRootAllowsRetired: [], importedLayerRootBucketsSkipped: [], importedLayerRootBucketsUnnamed: 0 };
         if (existsSync(join(this.fileBackend.root, FILE_PERMISSION_RULE_DIR))) {
             const rules = this.permissionRule();
             await retireImportedLayerRootAllows({ candidateOwners: () => fileRuleBucketOwners(rules), durable: rules.durable, isWholeBucketRefusal: isFileBucketDamaged, isVanishedBucket: () => false }, importedLayerRoot);
         }
+        const executionLaneWordsRenamed = this.executionLaneWordsRenamed + this.approvalAskStore.renameRetiredExecutionLaneWordM40();
+        this.executionLaneWordsRenamed = 0;
+        const askExecutionLanesBackfilled = backfillLocalAskExecutionLanes(this.approvalAskStore, { lanes: this.executionLanes });
         return {
             ...NO_SQL_MIGRATIONS,
             executionPlacementsBackfilled: placements.backfilled,
             executionPlacementSessionsUnreadable: placements.unreadable,
-            askExecutionLanesBackfilled: backfillLocalAskExecutionLanes(this.approvalAskStore, { lanes: this.executionLanes }),
+            askExecutionLanesBackfilled,
+            executionLaneWordsRenamed,
             askJournalRecordsUpgraded: this.approvalAskStore.upgradeJournalEnvelope(),
             localArchiveRowFactsBackfilled: archives.rowFactsBackfilled,
             localArchivesAnonymized: archives.anonymized,
@@ -396,9 +442,75 @@ class LocalBackend {
 export function counterStoreLabel(store, kind) {
     return store ? `shared(${kind ?? "unknown"})` : "in-process";
 }
+function openLocalBackend(config, onWarn, onError) {
+    const root = localBackendRootOf(config);
+    const discloseWarn = onWarn ?? ((msg, meta) => console.warn(msg, meta));
+    let fileBackend;
+    try {
+        fileBackend = acquireLocalBackendWithWait(() => new FileStorageBackend({
+            root,
+            ...(config.fileHistory !== undefined ? { fileHistory: config.fileHistory } : {}),
+            onCorruptRead: createDurableAbsenceSeat(discloseWarn, root, "file-history = a rewind boundary or scope read as missing"),
+        }), config.storeLockWaitMs, (fields) => onWarn?.("store_dir_lock_wait", { ...fields }));
+    }
+    catch (e) {
+        if (e instanceof AdoptionError)
+            throw e;
+        const tail = buildStoreOpenRefusalTail(e, "http");
+        throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)}` +
+            (tail === undefined ? "" : ` ${tail}`));
+    }
+    try {
+        holdEngineHighWater(fileBackend.root, serviceVersion());
+    }
+    catch (refusal) {
+        return new RefusedLocalBackend(fileBackend, refusal instanceof Error ? refusal : new Error(String(refusal)));
+    }
+    return new LocalBackend(fileBackend, config, discloseWarn, onWarn, onError);
+}
+class RefusedLocalBackend {
+    fileBackend;
+    refusal;
+    kind = "local";
+    constructor(fileBackend, refusal) {
+        this.fileBackend = fileBackend;
+        this.refusal = refusal;
+    }
+    refused() {
+        throw this.refusal;
+    }
+    async ensureSchema() {
+        return this.refused();
+    }
+    async runOneTimeMigrations() {
+        return this.refused();
+    }
+    async close() {
+        await this.fileBackend.dispose();
+    }
+    run() { return this.refused(); }
+    resumeAnchor() { return this.refused(); }
+    approvalExemption() { return this.refused(); }
+    approvalNonce() { return this.refused(); }
+    orgDeliveryQuota() { return this.refused(); }
+    approvalAsk() { return this.refused(); }
+    permissionRule() { return this.refused(); }
+    sendFileLedger() { return this.refused(); }
+    userInputLedger() { return this.refused(); }
+    sessionPolicy() { return this.refused(); }
+    fileHistory() { return this.refused(); }
+    memoryOptOutGrant() { return this.refused(); }
+    sessionCaptureRecords() { return this.refused(); }
+    workflowJournal() { return this.refused(); }
+    outcomeSink() { return this.refused(); }
+    checkpointReadView() { return this.refused(); }
+    session() { return this.refused(); }
+    mysqlPool() { return undefined; }
+    pgPool() { return undefined; }
+}
 export function createStoreBackend(config, onWarn, onError) {
     if (config.dbBackend === "local")
-        return new LocalBackend(config.localDataRoot ?? join(homedir(), ".ai-agent"), config, onWarn, onError);
+        return openLocalBackend(config, onWarn, onError);
     if (config.dbBackend === "pg") {
         if (!config.pg)
             return undefined;
@@ -419,9 +531,21 @@ function withRetiredSchemaProbe(inner, target, executionPlacementSwitch) {
     };
     return guarded;
 }
+function localBackendRootOf(config) {
+    return config.localDataRoot ?? join(homedir(), ".ai-agent");
+}
+function localDataRootHoldsData(root) {
+    try {
+        return readdirSync(root).length > 0;
+    }
+    catch (e) {
+        const code = e.code;
+        return code !== "ENOENT" && code !== "ENOTDIR";
+    }
+}
 export async function openStoreBackendWithFallback(config, logger) {
     const sqlEngine = config.dbBackend === "mysql" || config.dbBackend === "pg" ? config.dbBackend : undefined;
-    const mayFallback = config.dbBackend === "local" && !config.dbBackendExplicit;
+    const mayFallback = config.dbBackend === "local" && !config.dbBackendExplicit && !localDataRootHoldsData(localBackendRootOf(config));
     let backend;
     let inFlight;
     try {
@@ -448,8 +572,6 @@ export async function openStoreBackendWithFallback(config, logger) {
     }
     catch (err) {
         void inFlight?.close().catch(() => undefined);
-        if (err instanceof AdoptionError)
-            throw err;
         if (err instanceof StoreBootRefusalError)
             throw err;
         if (!mayFallback) {