@sema-agent/server 7.145.0 → 7.147.0

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";
@@ -33,16 +33,17 @@ import { FileUserInputLedgerStore } from "./user-input-ledger-file.js";
 import { TiDBUserInputLedgerStore, PgUserInputLedgerStore } from "./user-input-ledger-sql.js";
 import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-store-sql.js";
 import { TiDBSessionPolicyStore, PgSessionPolicyStore } from "../stores-sql/session-policy-store-sql.js";
-import { TiDBWorkflowJournalStore, PgWorkflowJournalStore } from "./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 { TiDBWorkflowJournalStore, PgWorkflowJournalStore } from "../stores-sql/workflow-journal-store-sql.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";
-import { TiDBCheckpointStore, PgCheckpointStore } from "./checkpoint-store-sql.js";
-import { TiDBToolResultStore, PgToolResultStore } from "./tool-result-store-sql.js";
+import { TiDBCheckpointStore, PgCheckpointStore } from "../stores-sql/checkpoint-store-sql.js";
+import { TiDBToolResultStore, PgToolResultStore } from "../stores-sql/tool-result-store-sql.js";
 import { TiDBImageIndex, PgImageIndex } from "./image-index-sql.js";
 import { TiDBImageBake, PgImageBake } from "./image-bake-store-sql.js";
 import { TiDBLeaderRunStore, PgLeaderRunStore } from "./leader-run-store-sql.js";
@@ -52,45 +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 } from "./permission-rule-store-file.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";
-function historyBlobBackend(config, dialect, pool) {
+export function workflowJournalOf(config, backend) {
+    return config.selfOrchestrationEnabled && backend ? backend.workflowJournal() : undefined;
+}
+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";
@@ -105,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)
@@ -138,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); }
@@ -160,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; }
@@ -192,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); }
@@ -214,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; }
@@ -247,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,
@@ -294,24 +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() {
-        const holderDeathCodeRowsBackfilled = this.runStore.migrateLegacyHolderDeathCodes();
+        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: () => rules.approvals.importRecordOwners(), durable: rules.durable, isWholeBucketRefusal: () => false, isVanishedBucket: () => false }, importedLayerRoot);
+            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,
-            holderDeathCodeRowsBackfilled,
             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,
@@ -395,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;
@@ -418,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 {
@@ -447,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) {

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

@@ -37,13 +37,19 @@ import type { SessionUnreadable } from "../session-error-wire.js";
  * F1 [high] 实测:`DB_BACKEND` 未设时坏账本 ⇒ `{backend: undefined, degraded: true}`,不是拒启)。
  * 收法:**一个基类,一条重抛**。新 File 店的拒启只要 `extends StoreBootRefusalError` 就自动落在正确的
  * 一侧;忘了继承是**可见**的(它是一个必须显式选择的父类),而忘了往 if 链里加一行是不可见的。
- * (core 的 `AdoptionError` 不在本仓,改不了它的继承链 ⇒ 降级臂保留它那一条 `instanceof`,共两条。)
+ * (core 的 `AdoptionError` 不在本族:它的标记住在数据根里,而降级臂只对**空 / 不存在**的数据根开(`openStoreBackendWithFallback` 的数据根判据),
+ * 它到不了降级那一步 ⇒ 降级臂不为它单开一条。local 形上本族同样先被那条判据兜住;族规仍在,管的是拒句的属主与 SQL 族。)
  *
  * 族的含义是「**确定的拒启表态**」,不限 File 店:SQL `ensureSchema()` 里库带着已退役 schema 的拒启(`RetiredSchemaPresentError`)也属此族。三处读它,读法一致 ——
  * 降级臂不吞(穿过 `mayFallback`)、SQL 开库的等待窗不重试它(`store-open-wait.ts`:再等也等不来另一个答案)、「库打不开」的拒句不改写它(它自己的拒句才是真话)。
  */
 export declare class StoreBootRefusalError extends Error {
 }
+/**
+ * 起服对账一族的拒启码(机读;附录 A / 拒启码表的登记名)。含义 = 「本构建读不出 / 建不出的持久形,开始服务之前判」:SQL 列册对账与退役 schema 两道(`schema-consistency.ts`)、
+ * 会话部署格旁表建不出(`session-ext-table.ts`)、local 数据根的严格边档对账(`local-session-store.ts`)。码住在族基类旁边:读它的几只模块彼此不必互相 import。
+ */
+export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
 /**
  * 取消便签里的**大脑相位**快照 —— core `BrainStatus` 帧经 `brainStatusEventData` 投影后的五键子集。
  *
@@ -168,20 +174,10 @@ export declare const RUN_HOLDER_DEATH_CODES: {
     readonly orphaned: "run.orphaned";
 };
 export type RunHolderDeathCode = (typeof RUN_HOLDER_DEATH_CODES)[keyof typeof RUN_HOLDER_DEATH_CODES];
-/**
- * 一次性迁移 **M6** 的判据(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):7.116.0 之前写下的死亡判决行只有句子、码列为空 ——
- * 该行应有的码。两处用:local 腿的起服写回(`FileRunStore.migrateLegacyHolderDeathCodes`)与 SQL 两孪生行映射里的**读侧半场**(滚动升级窗里旧副本
- * 还会写这种行,起服写回覆盖不到;本函数随 M6 一起删)。只认两句落款的原字节(接管臂括注形按前缀认);码列已有值 / 非 `failed` / 别的句子 ⇒ 原样。
- */
-export declare function readLegacyHolderDeathCode(row: {
-    readonly status: string;
-    readonly error: string | null;
-    readonly errorCode: string | null;
-}): string | null;
 /**
  * run 行上是不是一份**持有者死亡判决**:`failed`,且行上的码是 {@link RUN_HOLDER_DEATH_CODES} 之一。判决只说「持有它的那个进程死在这条腿收场之前」,
  * 不说是谁 —— 持有者是谁读行上的 `instanceId`(判决不改它)。读者 = 用户输入受理账本的收敛判词(`src/user-input-ledger.ts` `judgeOpen`)。
- * 旧行(只有句子)由一次性迁移 M6 补上码(起服写回 + SQL 滚动窗的读侧半场,{@link readLegacyHolderDeathCode}),所以这里不再按句子判。
+ * 只认码、不按句子判:7.116.0 起两只死亡判决的写者恒同写码;只有句子、码列为空的行(更早的写者铸的)不是死亡判决(随包 MIGRATION 写了)。
  * 正常失败(别的码 / 无码)/ park 过期收割(`approval.expired`:腿 park 过)都**不是**死亡判决。
  */
 export declare function isHolderDeathVerdict(run: Pick<RunRecord, "status" | "errorCode">): boolean;
@@ -555,7 +551,8 @@ export interface SessionRunRollupSource {
 }
 /**
  * 会话**此刻的 run 认领**(单活槽)的窄读面 —— run 店的 `getActiveTaskId`,同一个问题在 SQL 孪生里是写事务内对 `task_active` 的锁定读。
- * local 会话店的执行席在 `markMirror` 的写锁内读它,判序与 SQL 孪生同(行不在 / 住客不同 / writer / mirror 先判,认领只拦「absent → mirror」这一笔写)。
+ * local 会话店在写锁内读它:执行席的 `markMirror`(判序与 SQL 孪生同:行不在 / 住客不同 / writer / mirror 先判,认领只拦「absent → mirror」这一笔写),
+ * 与导入三写口(整段 `importEntries` / `replaceEntries` / 暂存提交;判官 `judgeImportWrite` 与 SQL 事务内钩的 `import` 臂同一只:先认领后本处写者)。
  */
 export interface SessionRunClaimSource {
     getActiveTaskId(sessionId: string): Promise<string | undefined>;

package/dist/plugins/store-contracts.js

@@ -1,5 +1,6 @@
 export class StoreBootRefusalError extends Error {
 }
+export const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
 export const ABORT_CAUSES = ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
 export const RUN_STALLED_ERROR = "run stalled (instance lost?)";
 export const RUN_ORPHANED_ERROR = "run orphaned by engine restart";
@@ -8,15 +9,6 @@ export function buildRunOrphanedError(heldBy) {
 }
 export const RUN_HOLDER_DEATH_CODES = { stalled: "run.stalled", orphaned: "run.orphaned" };
 const RUN_HOLDER_DEATH_CODE_WORDS = new Set(Object.values(RUN_HOLDER_DEATH_CODES));
-export function readLegacyHolderDeathCode(row) {
-    if (row.errorCode !== null || row.status !== "failed" || row.error === null)
-        return row.errorCode;
-    if (row.error === RUN_STALLED_ERROR)
-        return RUN_HOLDER_DEATH_CODES.stalled;
-    if (row.error === RUN_ORPHANED_ERROR || row.error.startsWith(`${RUN_ORPHANED_ERROR} (`))
-        return RUN_HOLDER_DEATH_CODES.orphaned;
-    return null;
-}
 export function isHolderDeathVerdict(run) {
     return run.status === "failed" && run.errorCode !== null && RUN_HOLDER_DEATH_CODE_WORDS.has(run.errorCode);
 }

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

@@ -0,0 +1,63 @@
+/**
+ * 后端级按龄清扫动词 —— 一个后端的按龄清扫只有一只动词 `sweep({ nowMs })`,答每条腿删了几行。
+ *
+ * ## 律(一条)
+ * 维护 tick 只调这一只动词,不逐店探「有没有某个按龄删的方法」;每条腿的界只有一种读法({@link buildStoreSweepBounds}:部署旋钮 → 引擎的词 `maxAgeMs`,
+ * 即工具结果店 `ToolResultStore.reap(now, { maxAgeMs })`、名册 `RosterGcOptions.maxAgeMs` 的那个词;journal 店的按龄删同收 `maxAgeMs`),**每次清扫现读** —— `TOOL_RESULT_TTL_SEC` 是热键,
+ * 改了下一拍就按新值删;没给界的腿,或本后端那只座没有按龄删的面,一行不删、答 0。
+ * 形照引擎 SQL 后端包的同名动词(`SqlStorageBackend.sweep` / `SqlSweepLeg` / `SqlSweepReceipt`):腿名逐字用它的词。
+ *
+ * ## 射程(如实)
+ * 今天的三条腿:`tool-results-aged`(工具结果店的契约成员 `reap`)、`roster-aged`(名册 SQL 孪生的按龄删;File / 内存名册没有这一面 ⇒ 0)与
+ * `workflow-journal-expired`(journal SQL 孪生的按龄删 `reapExpired`,见 {@link createJournalSweepLeg};只在开了 self-orchestration 且有后端时有这只店,
+ * core 的 File journal 店没有这一面 ⇒ 0)。引擎包的腿闭集另有 `file-history-orphan-blobs`,随它的座搬进 `src/stores-sql/` 时并进来;信箱的 `reap` 是按收件箱
+ * 作用域的契约成员,引擎包的清扫腿里没有它,本动词也不收。实现仍是各座自己的方法;目录搬进引擎包之后,SQL 后端的这只动词就是包的 `sweep`。
+ *
+ * ## 失败
+ * 腿互不牵连:一条腿抛(同步抛或拒)不拦别的腿。全腿成功 ⇒ 答回执;有腿失败 ⇒ 以 {@link StoreSweepError} 拒,带上成功腿的计数与失败腿的原因,
+ * 调用方按腿各自上报。
+ */
+import type { ServiceConfig } from "../config.js";
+/** 本后端跑的清扫腿(闭集;词与引擎 SQL 后端包的 `SqlSweepLeg` 同字)。 */
+export declare const STORE_SWEEP_LEGS: readonly ["roster-aged", "tool-results-aged", "workflow-journal-expired"];
+export type StoreSweepLeg = (typeof STORE_SWEEP_LEGS)[number];
+/** 一次清扫每条腿删了几行。 */
+export type StoreSweepReceipt = Readonly<Record<StoreSweepLeg, number>>;
+/** 一条腿的界(部署陈述;词 = 引擎的 `maxAgeMs`)。 */
+export interface StoreSweepBound {
+    readonly maxAgeMs: number;
+}
+/** 各腿的界(缺一条 = 那条腿不删)。 */
+export type StoreSweepBounds = Readonly<Partial<Record<StoreSweepLeg, StoreSweepBound>>>;
+/**
+ * 部署旋钮 → 各腿的界:本仓唯一的读法。`TOOL_RESULT_TTL_SEC`(秒,> 0,热键)→ `tool-results-aged`;`ROSTER_RETENTION_MS`(毫秒,下限 1 分钟)→ `roster-aged`;
+ * `WORKFLOW_JOURNAL_RETENTION_MS`(毫秒,下限 1 分钟)→ `workflow-journal-expired`。
+ * 组合点把它包成读法函数交给 {@link createStoreSweep},每次清扫现读一次 —— 交起服那一刻的值会让热发布的新界不生效。
+ */
+export declare function buildStoreSweepBounds(config: Pick<ServiceConfig, "toolResultTtlSec" | "rosterRetentionMs" | "workflowJournalRetentionMs">): StoreSweepBounds;
+/** 一条腿的实现:删掉存了超过 `bound.maxAgeMs` 的行,答删了几行。 */
+export type StoreSweepLegRun = (nowMs: number, bound: StoreSweepBound) => Promise<number> | number;
+/**
+ * journal 店的按龄删 → `workflow-journal-expired` 腿:截止线 = 动词交来的 `nowMs` − 动词交来的 `maxAgeMs`(界每次清扫现读,腿不自存)。
+ * 店没有这一面(core 的 File / 内存 journal 店)或没有店(self-orchestration 关 / 无后端)⇒ 无腿,动词答 0。
+ */
+export declare function createJournalSweepLeg(store: {
+    reapExpired?(now: number, maxAgeMs: number): Promise<number>;
+} | undefined): StoreSweepLegRun | undefined;
+export interface StoreSweep {
+    sweep(input: {
+        readonly nowMs: number;
+    }): Promise<StoreSweepReceipt>;
+}
+/** 有腿失败的那次清扫:`receipt` 里失败腿记 0,`failed` 按腿带原因。 */
+export declare class StoreSweepError extends Error {
+    readonly receipt: StoreSweepReceipt;
+    readonly failed: ReadonlyMap<StoreSweepLeg, unknown>;
+    constructor(receipt: StoreSweepReceipt, failed: ReadonlyMap<StoreSweepLeg, unknown>);
+}
+export declare function createStoreSweep(spec: {
+    readonly legs: Readonly<Partial<Record<StoreSweepLeg, StoreSweepLegRun>>>;
+    /** 界的读法:每次清扫调一次(只收函数 —— 起服那一刻的界对象交不进来)。 */
+    readonly bounds: () => StoreSweepBounds;
+}): StoreSweep;
+//# sourceMappingURL=store-sweep.d.ts.map

package/dist/plugins/store-sweep.js

@@ -0,0 +1,48 @@
+export const STORE_SWEEP_LEGS = ["roster-aged", "tool-results-aged", "workflow-journal-expired"];
+export function buildStoreSweepBounds(config) {
+    return {
+        "roster-aged": { maxAgeMs: config.rosterRetentionMs },
+        "tool-results-aged": { maxAgeMs: config.toolResultTtlSec * 1000 },
+        "workflow-journal-expired": { maxAgeMs: config.workflowJournalRetentionMs },
+    };
+}
+export function createJournalSweepLeg(store) {
+    const reap = store?.reapExpired?.bind(store);
+    return reap === undefined ? undefined : (nowMs, { maxAgeMs }) => reap(nowMs, maxAgeMs);
+}
+export class StoreSweepError extends Error {
+    receipt;
+    failed;
+    constructor(receipt, failed) {
+        super(`store sweep: leg(s) ${[...failed.keys()].join(", ")} failed`);
+        this.receipt = receipt;
+        this.failed = failed;
+        this.name = "StoreSweepError";
+    }
+}
+export function createStoreSweep(spec) {
+    const runLeg = async (leg, nowMs, bounds) => {
+        const run = spec.legs[leg];
+        const bound = bounds[leg];
+        if (run === undefined || bound === undefined)
+            return { leg, removed: 0 };
+        try {
+            return { leg, removed: await run(nowMs, bound) };
+        }
+        catch (error) {
+            return { leg, error };
+        }
+    };
+    return {
+        async sweep({ nowMs }) {
+            const bounds = spec.bounds();
+            const settled = await Promise.all(STORE_SWEEP_LEGS.map((leg) => runLeg(leg, nowMs, bounds)));
+            const receipt = Object.fromEntries(settled.map((s) => [s.leg, "removed" in s ? s.removed : 0]));
+            const failed = new Map(settled.flatMap((s) => ("error" in s ? [[s.leg, s.error]] : [])));
+            if (failed.size > 0)
+                throw new StoreSweepError(receipt, failed);
+            return receipt;
+        },
+    };
+}
+//# sourceMappingURL=store-sweep.js.map

package/dist/plugins/task-attachment-store.d.ts

@@ -2,7 +2,7 @@
  * TaskAttachmentStore —— D-1 通用文件上传的**独立附件 store**(clay 拍 2026-07-27:不复用 fileSnapshot
  * 的 content-addressed blob 面,新建)。TiDB/PG 双方言 + local 文件店(local-task-attachment-store.ts)。
  *
- * 为什么独立而不是骑 SqlBlobBackend/snapshot_blob:那套的引用追踪=「本域 manifest 里没有的即 orphan」,
+ * 为什么独立而不是骑快照 blob 的索引(snapshot_blob):那套的引用追踪=「本域 manifest 里没有的即 orphan」,
  * 附件不在任何一域的 manifest 里 ⇒ 会被孤儿扫在 1h grace 后误收。生命周期也不同:
  * snapshot blob 跟 session 的工作树;**附件跟 task/session 的绑定**(上传先行、提交时绑定、E21 随会话
  * 级联删、未绑定的按 TTL 收割)。
@@ -11,8 +11,8 @@
  *  - `owner` = auth principal ?? "default"(单库 tenant 轴;无 principal 部署全 default = 单用户语义)。
  *    读/删门在 SQL WHERE 完成(filter-before-reduce,roster 语义条 1 同姿)——他人行连结果集都不进。
  *  - **字节本体在对象存储(clay 裁 2026-07-27:云形态对象存储必配,「现在就接」)**:SQL 只存 meta
- *    (索引/owner 门/生命周期),bytes 走 {@link AttachmentBytesStore}(生产=既有 MinioBlobBackend,
- *    读侧内建 sha 校验)。对象键=**sha256**(同内容天然去重;跨 owner 共享对象 ⇒ 对象删除必须过
+ *    (索引/owner 门/生命周期),bytes 走 {@link AttachmentBytesStore}(字节口 {@link BlobBackend} —— 生产 = 对象存储
+ *    MinioBlobBackend;读侧的 sha 校验是本店作为索引属主的事:{@link readAtAddress})。对象键=**sha256**(同内容天然去重;跨 owner 共享对象 ⇒ 对象删除必须过
  *    零引用检查)+ **附件专属 keyPrefix**(与快照 blob 命名空间隔离——同 sha 不同生命周期,混用会互删)。
  *    删除次序:meta 先(E21 purge 永不被 MinIO 网络抖动卡死,blob-backend 异步删裁定同旨),对象删
  *    =零引用检查后 best-effort(失败只 log:无 meta 的对象经 API 不可达;彻底清收敛作 follow-up 记账)。
@@ -32,6 +32,7 @@ import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
 import type { Pool as PgPool } from "pg";
 import { type IndexSpec } from "./ensure-index.js";
+import { type BlobBackend } from "./blob-backend.js";
 /**
  * 一条附件 meta 的**形属主**(整仓唯一那份键集)。
  *
@@ -79,12 +80,9 @@ export interface TaskAttachmentStore {
     sweepOrphanObjects?(graceMs: number, nowMs?: number): Promise<number>;
 }
 export declare const TASK_ATTACHMENT_TABLE = "task_attachment";
-/** 字节面 seam —— MinioBlobBackend 的结构子集(hash 键控;读侧 sha 校验在实现内)。`listObjects` 可选
+/** 字节面 = 字节口 {@link BlobBackend}(sha256 键控;读侧 sha 校验在本店,{@link readAtAddress})+ 对象存储的两只可选读面。`listObjects` 可选
  *  (D-1 孤儿对象 GC 的列举面;测试桩/无列举后端缺席=sweep 诚实 0,不装作扫过)。 */
-export interface AttachmentBytesStore {
-    putBlob(hash: string, bytes: Uint8Array): Promise<void>;
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    deleteBlobs(hashes: string[]): Promise<number>;
+export interface AttachmentBytesStore extends BlobBackend {
     listObjects?(): AsyncGenerator<{
         hash: string;
         lastModifiedMs: number;