@sema-agent/server 7.148.0 → 7.150.0

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

@@ -9,6 +9,7 @@ import { type RunStallWiring } from "./store-contracts.js";
 import { type StoreOpenLane } from "./store-open-refusal.js";
 import { type OneTimeMigrationReport, type SqlOneTimeMigrationInput } from "./one-time-migrations.js";
 import { LocalSessionStore } from "./local-session-store.js";
+import { type LocalStoreDeclaration } from "../local-store-declaration.js";
 import type { LocalSessionRows } from "./local-session-window.js";
 import type { SessionHeadReader } from "./caching-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
@@ -41,9 +42,10 @@ import { type SqlTransactionHooks } from "../stores-sql/retention-store-sql.js";
 import type { SessionEraser } from "../session-erase.js";
 import { type RetentionDestructiveInput, type RetentionExecutor, type RetentionExecutorOptions } from "./retention-deployment.js";
 import { type RetentionLaneStore } from "./retention-lane-store-sql.js";
+import { type LocalDataRootAdmission } from "./local-data-root-admission.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 import { type SqlDriver } from "./sql-driver.js";
-import { type StoreDegradedReason } from "../store-posture.js";
+import { type StoreDegradedReason, type StoreDurability as MediumDurability } from "../store-posture.js";
 /** boot 期的一条日志座(级别由**座位**决定,不由参数携带):`createStoreBackend` 的 `onWarn` / `onError`
  *  两参与 `LocalBackend` 的同名字段共用此形。装配层把它们分别接到 `logger.warn` / `logger.error` 上。 */
 export type BootLogSink = (msg: string, meta?: Record<string, unknown>) => void;
@@ -54,6 +56,10 @@ export type BootLogSink = (msg: string, meta?: Record<string, unknown>) => void;
 export interface StoreBackendObservers {
     readonly runStallVerdicts?: (landed: number) => void;
 }
+/** 开店时递进来的起服事实(只 local 腿读):数据根介质的判定(起服第 2 段的取证;缺席 = 这条入口没有起服证据 ⇒ 按 `unknown` 读 —— 判不出的介质不放宽 local 店的声明)。 */
+export interface StoreOpenFacts {
+    readonly dataRootMedium?: MediumDurability;
+}
 /** run 店落死亡判决的两样:窗 = 后端持有的配置对象的 `runStaleSec`(热发布原地改写 ⇒ getter 读到热值;判活窗只有这一个来源)+ 计数座。 */
 export declare function createRunStallWiring(config: Pick<ServiceConfig, "runStaleSec">, observers: StoreBackendObservers | undefined): RunStallWiring;
 export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
@@ -426,6 +432,8 @@ export interface StoreBackend {
      *  拒绝句不带盘上位置)的同时,路径进本 backend 的 `file_store_corrupt_read` 披露座(逐命中 warn)。修前 `boot/stores.ts` 在同一数据根上自己
      *  `new FileUsageWindowStore(root)` 第二只实例、不接座 ⇒ 坏值只拒不披露,运维找不到是哪只文件。SQL 后端省略(它们有自己的 usage-window 双方言店)。 */
     fileUsageWindowStore?(): UsageWindowStore;
+    /** **local 后端专有**:构造时交给两半店(会话店顶层、检查点店)的那一份声明(唯一读者 `localStoreDeclarationOf`)—— 装配值从这里读回,不重算。SQL 后端省略。 */
+    localStoreDeclaration?(): LocalStoreDeclaration;
 }
 /**
  * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十三张部署表,
@@ -459,7 +467,7 @@ export declare function createSqlSessionEraser(db: SqlDriver, opts: RetentionExe
  *  ({@link SQL_BLOB_POSTURE_FACTS})。云形缺 MinIO ⇒ fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` =
  *  显式接受 SQL 店 + per-blob 帽(单机/测试台形;pg 上帽只来自 `SNAPSHOT_BLOB_SQL_MAX_BYTES`)。local 后端不经此门(file 店,无 SQL 包墙)。 */
 export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "local", config: Pick<ServiceConfig, "snapshotBlobStore" | "snapshotBlobAllowSql">): void;
-/** SQL 一次性迁移段的输入(两只 SQL 后端同一份;各条目那一半的来源见 `SqlOneTimeMigrationInput`):M32 的车道表 · M40 的判活窗 = 收割器的同一个窗 · M48 的部署形读数(表里那一行)。 */
+/** SQL 一次性迁移段的输入(两只 SQL 后端同一份;各条目那一半的来源见 `SqlOneTimeMigrationInput`):M32 的车道表 · M52 的判活窗(停-迁-起证据的心跳一半)= 收割器的同一个窗 · M48 的部署形读数(表里那一行)。 */
 export declare function buildSqlOneTimeMigrationInput(config: ServiceConfig): SqlOneTimeMigrationInput;
 /**
  * LOCAL backend (clay 2026-06-25 seamless local↔cloud; P0.5 variant-2 + variant-1 file-backed 2026-06-26): a DB-less StoreBackend
@@ -517,25 +525,31 @@ export interface LocalStoreBackend extends StoreBackend {
     toolResult(): ToolResultStoreFull;
     /** local 后端恒有(引擎 File 后端的用量窗账本;接口上可选的那一口在这里必在)。 */
     fileUsageWindowStore(): UsageWindowStore;
+    /** local 后端恒有(构造时交给两半店的声明;接口上可选的那一口在这里必在)。 */
+    localStoreDeclaration(): LocalStoreDeclaration;
 }
 /** 引擎 File 后端上会话店之外、本仓没有自己一份口的店(run-local 的 Runner 接它们;工具结果 / 用量窗 / 会话规则走既有的 `toolResult()` / `fileUsageWindowStore()` / `sessionPolicy()` 口)。 */
 export type LocalEngineFileStores = Pick<FileStorageBackend, "checkpointStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore">;
 /** 打开 local 数据根的入口参数:哪条路在开(只决定拒句的措辞 —— 表头与「换根」半句)与三只 boot 期日志座(见 {@link createStoreBackend})。 */
 export interface LocalBackendOpenOptions {
     readonly lane: StoreOpenLane;
+    /** 这只根的数据根准入读数(必填;{@link admitLocalDataRoot} 铸,调用方在它对这只根的第一笔写之前取 —— 打开就是第一笔写的调用方当场取,见 {@link createStoreBackend})。 */
+    readonly admission: LocalDataRootAdmission;
     readonly onWarn?: BootLogSink;
     readonly onError?: BootLogSink;
     readonly observers?: StoreBackendObservers;
+    /** 起服事实(数据根介质的判定;HTTP 服务递第 2 段的取证,缺席 ⇒ `unknown`)。 */
+    readonly facts?: StoreOpenFacts;
 }
 /**
  * **local 后端打开数据根**(唯一的路 —— 本仓每一条打开 local 数据根的入口都经它:`createStoreBackend` 的 local 腿(HTTP 服务)与 run-local;一个数据根一只会话行店、一份装配):
- * 取锁(引擎 File 后端)→ **判与抬引擎版本高水位**({@link holdEngineHighWater},同步一段;判前钩 = 判或记收令牌欠账 {@link holdArchiveTokenAdoptionDuty},抬之前)→ 本仓的店。
+ * 数据根准入(调用方交来的读数 `opts.admission`,判已在本进程第一笔写之前做完)→ 取锁(引擎 File 后端:建根、锁文件、引擎自己的店目录与空账本)→
+ * **锁内一步**({@link holdLocalDataRootAdmission}:核物理数据根与准入那一次观察都没动 → 跳版臂记 / 销账 → 抬引擎版本高水位)→ 本仓的店。
  * 打开之后的公开序列两条入口相同:`ensureSchema()`(起服对账)→ `runOneTimeMigrations()` → 才读会话。
- * 判与抬住在这里而不是 `ensureSchema()` 里,因为围栏以**第一笔落盘**界定:本仓的店在构造里就会写(撕裂的问账日志留证 + 压实、撕裂的 run 认领挪开、会话收尾的活跃边档落盘),
- * 判必须先于它们(被拒 = 本仓的店一只都没开、不抬、不改既有文件的字节;判拒发生在钥匙对与空账本已落、店尚未开之后;下一版改为判拒先于任何写),抬必须先于它们(写到一半崩了,水位已是本构建)。所以这一段之后才有店,没有任何一只店先于它。
- * 拒(判拒 / 本构建版本读不出 / 抬写不进 / 本仓的店构造时抛)⇒ 交回一只 {@link RefusedLocalBackend}:只握着锁,`ensureSchema()` 交出那一只拒(公开序列在它该在的那一步拒,降级臂按拒的族判),
- * `close()` 只放锁 —— 没有店、没有收尾写。
- * 残余(如实):引擎 `FileStorageBackend` 的构造把取锁与它自己的店放在同一步(建子目录、店目录锁、撕裂账本尾的收拢)—— 那几笔在判之前,本仓在两者之间没有座(要 core 给)。
+ * 抬住在这里而不是 `ensureSchema()` 里,因为围栏以**第一笔落盘**界定:本仓的店在构造里就会写(撕裂的问账日志留证 + 压实、撕裂的 run 认领挪开、会话收尾的活跃边档落盘),
+ * 抬必须先于它们(写到一半崩了,水位已是本构建)。所以这一段之后才有店,没有任何一只店先于它。
+ * 锁内一步拒(准入判过的输入在准入之后被另一只引擎动过 / 记账或抬写不进)或本仓的店构造时抛 ⇒ 交回一只 {@link RefusedLocalBackend}:只握着锁,`ensureSchema()` 交出那一只拒
+ * (公开序列在它该在的那一步拒,降级臂按拒的族判),`close()` 只放锁 —— 没有店、没有收尾写。
  */
 export declare function openLocalBackend(config: ServiceConfig, opts: LocalBackendOpenOptions): LocalStoreBackend;
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily); the next
@@ -573,7 +587,7 @@ export declare function localBackendRootOf(config: Pick<ServiceConfig, "localDat
 export declare function openStoreBackendWithFallback(config: ServiceConfig, logger: {
     warn: (msg: string, meta?: Record<string, unknown>) => void;
     error?: (msg: string, meta?: Record<string, unknown>) => void;
-}, observers?: StoreBackendObservers): Promise<{
+}, observers?: StoreBackendObservers, localAdmission?: LocalDataRootAdmission, facts?: StoreOpenFacts): Promise<{
     backend: StoreBackend | undefined;
     degradedReason: StoreDegradedReason | undefined;
 }>;

package/dist/plugins/store-backend.js

@@ -15,15 +15,18 @@ import { StoreBootRefusalError } from "./store-contracts.js";
 import { databaseAnswerCodesOf, isDeploymentFaultError } from "./sql-errors.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
-import { NO_SQL_MIGRATIONS, assertExecutionPlacementSwitchAdmissibleOnPool, backfillLocalAskExecutionLanes, backfillLocalExecutionPlacements, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { NO_SQL_MIGRATIONS, migrationCarried, assertExecutionPlacementSwitchAdmissibleOnPool, backfillLocalAskExecutionLanes, backfillLocalExecutionPlacements, runSqlOneTimeMigrations } from "./one-time-migrations.js";
 import { deployedExecutionLanes } from "../execution-lane-caps.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { LOCAL_MARKER_FILE, switchLocalScenarioPrefixM42 } from "./scenario-prefix-switch-m42.js";
-import { LOCAL_LEGACY_SKILL_EXEMPTION_MARKER_FILE, dropLocalLegacySkillExemptionsM46 } from "./approval-exemption-skill-m46.js";
+import { dropLocalLegacySkillExemptionsM46 } from "./approval-exemption-skill-m46.js";
+import { LOCAL_SKILL_EXEMPTION_CUTOFF_FILE, assertSkillExemptionCutoffHeldOnPool } from "./approval-exemption-skill-cutoff.js";
+import { SKILL_EXEMPTION_CUTOFF_ID } from "./one-time-migration-marker.js";
 import { LocalTaskAttachmentStore } from "./local-task-attachment-store.js";
 import { assertRetiredSchemaAbsentOnPool } from "./schema-consistency.js";
-import { LocalSessionStore, archiveTokenAdoptionCarried, holdArchiveTokenAdoptionDuty, createLocalSessionRepo } from "./local-session-store.js";
-import { SESSION_DURABILITY, SESSION_PLACEMENTS } from "./session-placement.js";
+import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
+import { localStoreDeclarationOf } from "../local-store-declaration.js";
+import { SESSION_PLACEMENTS } from "./session-placement.js";
 import { LocalCheckpointStore, dropLocalCheckpointCtxStrict } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { TiDBApprovalExemptionStore, PgApprovalExemptionStore, FileApprovalExemptionStore } from "./approval-exemption-store.js";
@@ -76,8 +79,7 @@ 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 { admitLocalDataRoot, holdLocalDataRootAdmission } from "./local-data-root-admission.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { localDataRootHoldsData, storeDegradedReasonFor } from "../store-posture.js";
 import { openWithinWait } from "./store-open-wait.js";
@@ -377,10 +379,12 @@ class LocalBackend {
     parkDecisionLedgerRoot;
     executionLanes;
     identityBoundary;
+    storeDeclaration;
     dataDirLayout;
-    constructor(fileBackend, config, discloseWarn, onWarn, onError, observers) {
+    constructor(fileBackend, config, discloseWarn, onWarn, onError, observers, facts) {
         this.executionLanes = deployedExecutionLanes(config);
         this.identityBoundary = DEPLOYMENT_SHAPE_PREDICATES.identityBoundary.holds(config);
+        this.storeDeclaration = localStoreDeclarationOf(config, facts?.dataRootMedium ?? "unknown");
         this.onWarn = onWarn;
         this.discloseWarn = discloseWarn;
         this.onError = onError;
@@ -397,7 +401,7 @@ class LocalBackend {
         const physicalRoot = this.fileBackend.root;
         this.sessionStore = new LocalSessionStore(createLocalSessionRepo(physicalRoot), this.runStore, physicalRoot, {
             log: createLogger(config.logLevel),
-            durability: SESSION_DURABILITY,
+            durability: this.storeDeclaration.durability,
             placements: SESSION_PLACEMENTS,
             withdrawCheckpointCtx: (sessionId) => dropLocalCheckpointCtxStrict(physicalRoot, sessionId),
         });
@@ -420,7 +424,6 @@ class LocalBackend {
     }
     async ensureSchema() {
         this.executionLaneWordsRenamed += await this.sessionStore.renameRetiredExecutionLaneWordM40();
-        await this.sessionStore.assertStrictSidecarsReadable();
         await this.sessionStore.finishPendingDrops();
         await this.sessionStore.settleArchiveSnapshots();
         const adoption = await this.sessionStore.adoptArchiveTokensM47();
@@ -443,11 +446,24 @@ class LocalBackend {
         });
         const runErrorCodeColumnRewritten = this.runStore.migrateRunErrorCodeColumnM44();
         const runObjectivePreviewRewritten = this.runStore.migrateRunObjectivePreviewM45();
-        const shellSentinelOwnersCleared = this.identityBoundary ? 0 : (await this.sessionStore.clearShellSentinelOwnersM48()) + this.runStore.clearShellSentinelOwnersM48();
+        const shellSentinelOwnerRowsRetained = [];
+        let shellSentinelOwnersCleared = 0;
+        if (this.identityBoundary) {
+            for (const [surface, rows] of [
+                ["session_meta", await this.sessionStore.countShellSentinelOwnersM48()],
+                ["task_run", this.runStore.countShellSentinelOwnersM48()],
+            ]) {
+                if (rows > 0)
+                    shellSentinelOwnerRowsRetained.push({ surface, rows });
+            }
+        }
+        else {
+            shellSentinelOwnersCleared = (await this.sessionStore.clearShellSentinelOwnersM48()) + this.runStore.clearShellSentinelOwnersM48();
+        }
         const checkpointHostSessionsBackfilled = existsSync(join(this.fileBackend.root, "checkpoint-session-tokens.json")) || existsSync(join(this.fileBackend.root, "checkpoint-scopes.json"))
             ? await this.checkpointStoreOf().backfillHostSessionsM49()
             : 0;
-        const legacySkillExemptionsDropped = dropLocalLegacySkillExemptionsM46(join(this.fileBackend.root, LOCAL_LEGACY_SKILL_EXEMPTION_MARKER_FILE), this.approvalExemptionStore);
+        const legacySkillExemptionsDropped = dropLocalLegacySkillExemptionsM46(join(this.fileBackend.root, LOCAL_SKILL_EXEMPTION_CUTOFF_FILE), this.approvalExemptionStore);
         const archives = await this.sessionStore.migrateLocalArchives();
         const placements = await backfillLocalExecutionPlacements(this.runStore.sessionIdsWithRuns(), this.sessionStore.executionPlacementBackfill, { lanes: this.executionLanes });
         const importedLayerRoot = { importedLayerRootAllowsRetired: [], importedLayerRootBucketsSkipped: [], importedLayerRootBucketsUnnamed: 0 };
@@ -467,6 +483,7 @@ class LocalBackend {
             runErrorCodeColumnRewritten,
             runObjectivePreviewRewritten,
             shellSentinelOwnersCleared,
+            shellSentinelOwnerRowsRetained,
             checkpointHostSessionsBackfilled,
             legacySkillExemptionsDropped,
             executionPlacementsBackfilled: placements.backfilled,
@@ -524,6 +541,7 @@ class LocalBackend {
     userInputLedger() { return this.userInputLedgerStore; }
     checkpointStoreOf() {
         return (this.checkpointStoreInst ??= new LocalCheckpointStore(this.fileBackend.root, {
+            durability: this.storeDeclaration.durability,
             getActiveTaskId: (sessionId) => this.runStore.getActiveTaskId(sessionId),
             readSessionOwner: async (sessionId) => (await this.sessionStore.headOf(sessionId))?.owner,
         }));
@@ -544,6 +562,7 @@ class LocalBackend {
     checkpointStoreInst;
     sessionPolicy() { return (this.sessionPolicyInst ??= createClientCountedPolicyStore(this.fileBackend.sessionPolicyStore, this.sessionStore)); }
     sessionPolicyInst;
+    localStoreDeclaration() { return this.storeDeclaration; }
     fileUsageWindowStore() { return this.fileBackend.usageWindowStore; }
     fileHistory() { return this.fileBackend.fileHistoryStore; }
     memoryOptOutGrant() { return undefined; }
@@ -568,7 +587,7 @@ const LOCAL_OPEN_REFUSAL_HEAD = {
     "run-local": (root) => `cannot open local data dir ${root}`,
 };
 export function openLocalBackend(config, opts) {
-    const { lane, onWarn, onError, observers } = opts;
+    const { lane, admission, onWarn, onError, observers, facts } = opts;
     const root = localBackendRootOf(config);
     const discloseWarn = onWarn ?? createLogger().warn;
     let fileBackend;
@@ -587,25 +606,24 @@ export function openLocalBackend(config, opts) {
             (tail === undefined ? "" : ` ${tail}`));
     }
     try {
-        const physicalRoot = fileBackend.root;
-        holdEngineHighWater(physicalRoot, serviceVersion(), (prior) => holdArchiveTokenAdoptionDuty(physicalRoot, prior, archiveTokenAdoptionCarried()));
+        holdLocalDataRootAdmission(fileBackend.root, admission);
     }
     catch (refusal) {
-        return new RefusedLocalBackend(fileBackend, refusal instanceof Error ? refusal : new Error(String(refusal)));
+        return new RefusedLocalBackend(() => fileBackend.dispose(), refusal instanceof Error ? refusal : new Error(String(refusal)));
     }
     try {
-        return new LocalBackend(fileBackend, config, discloseWarn, onWarn, onError, observers);
+        return new LocalBackend(fileBackend, config, discloseWarn, onWarn, onError, observers, facts);
     }
     catch (failure) {
-        return new RefusedLocalBackend(fileBackend, failure instanceof Error ? failure : new Error(String(failure)));
+        return new RefusedLocalBackend(() => fileBackend.dispose(), failure instanceof Error ? failure : new Error(String(failure)));
     }
 }
 class RefusedLocalBackend {
-    fileBackend;
+    release;
     refusal;
     kind = "local";
-    constructor(fileBackend, refusal) {
-        this.fileBackend = fileBackend;
+    constructor(release, refusal) {
+        this.release = release;
         this.refusal = refusal;
     }
     refused() {
@@ -618,7 +636,7 @@ class RefusedLocalBackend {
         return this.refused();
     }
     async close() {
-        await this.fileBackend.dispose();
+        await this.release();
     }
     run() { return this.refused(); }
     resumeAnchor() { return this.refused(); }
@@ -640,12 +658,13 @@ class RefusedLocalBackend {
     engineFileStores() { return this.refused(); }
     toolResult() { return this.refused(); }
     fileUsageWindowStore() { return this.refused(); }
+    localStoreDeclaration() { return this.refused(); }
     mysqlPool() { return undefined; }
     pgPool() { return undefined; }
 }
 export function createStoreBackend(config, onWarn, onError, observers) {
     if (config.dbBackend === "local")
-        return openLocalBackend(config, { lane: "http", onWarn, onError, observers });
+        return openAdmittedLocalBackend(config, undefined, { onWarn, onError, observers });
     if (config.dbBackend === "pg") {
         if (!config.pg)
             return undefined;
@@ -657,11 +676,24 @@ export function createStoreBackend(config, onWarn, onError, observers) {
     const pool = createTidbPool(config);
     return withRetiredSchemaProbe(new TiDBBackend(pool, config, observers), { dialect: "mysql", pool }, { lanes: deployedExecutionLanes(config) });
 }
+function openAdmittedLocalBackend(config, admission, sinks) {
+    let admitted = admission;
+    if (admitted === undefined) {
+        try {
+            admitted = admitLocalDataRoot(localBackendRootOf(config));
+        }
+        catch (refusal) {
+            return new RefusedLocalBackend(async () => undefined, refusal instanceof Error ? refusal : new Error(String(refusal)));
+        }
+    }
+    return openLocalBackend(config, { lane: "http", admission: admitted, ...sinks });
+}
 function withRetiredSchemaProbe(inner, target, executionPlacementSwitch) {
     const guarded = Object.create(inner);
     guarded.ensureSchema = async () => {
         await assertRetiredSchemaAbsentOnPool(target);
         await assertExecutionPlacementSwitchAdmissibleOnPool(target.dialect, target.pool, executionPlacementSwitch);
+        await assertSkillExemptionCutoffHeldOnPool(target, migrationCarried(SKILL_EXEMPTION_CUTOFF_ID));
         await inner.ensureSchema();
     };
     return guarded;
@@ -669,7 +701,7 @@ function withRetiredSchemaProbe(inner, target, executionPlacementSwitch) {
 export function localBackendRootOf(config) {
     return config.localDataRoot ?? join(homedir(), ".ai-agent");
 }
-export async function openStoreBackendWithFallback(config, logger, observers) {
+export async function openStoreBackendWithFallback(config, logger, observers, localAdmission, facts) {
     const sqlEngine = config.dbBackend === "mysql" || config.dbBackend === "pg" ? config.dbBackend : undefined;
     const mayFallback = config.dbBackend === "local" && !config.dbBackendExplicit && !localDataRootHoldsData(localBackendRootOf(config));
     let backend;
@@ -678,7 +710,9 @@ export async function openStoreBackendWithFallback(config, logger, observers) {
         const attempt = async () => {
             let built;
             try {
-                built = createStoreBackend(config, (msg, meta) => logger.warn(msg, meta), logger.error === undefined ? undefined : (msg, meta) => logger.error(msg, meta), observers);
+                const onWarn = (msg, meta) => logger.warn(msg, meta);
+                const onError = logger.error === undefined ? undefined : (msg, meta) => logger.error(msg, meta);
+                built = config.dbBackend === "local" ? openAdmittedLocalBackend(config, localAdmission, { onWarn, onError, observers, ...(facts !== undefined ? { facts } : {}) }) : createStoreBackend(config, onWarn, onError, observers);
                 inFlight = built;
                 if (built)
                     await built.ensureSchema();

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

@@ -21,6 +21,7 @@
 import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core";
 import type { RunIdentity } from "../identity-source.js";
 import type { SessionUnreadable } from "../session-error-wire.js";
+import type { ReadDenyFloorSummary } from "../read-deny-floor-notice.js";
 /**
  * **File 店族的 boot 期拒启基类**([ref];把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
  *
@@ -50,6 +51,19 @@ export declare class StoreBootRefusalError extends Error {
  * 会话部署格旁表建不出(`session-ext-table.ts`)、local 数据根的严格边档对账(`local-session-store.ts`)。码住在族基类旁边:读它的几只模块彼此不必互相 import。
  */
 export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
+/**
+ * **SQL 库的列形不是本构建读得动的形 ⇒ 起服拒**的唯一出口:整库列册对账的三条拒(列集不符 / information_schema 读不出 / 整库零行,`schema-consistency.ts`)与六只单表探针的拒启
+ * (`checkpoint` · `tool_result` · `file_history_*` · `approval_ask` · `permission_rule_approval` · `permission_rule_ticket`)都经这一只类抛 —— 运维按码(`code` 字段 + 消息首词,同一个
+ * {@link SCHEMA_MISMATCH_ERROR_CODE})判「要跑 ALTER」,不必先猜是哪一只判官拒的。两只判官答同一问(这张表缺不缺列),出口只有一个。
+ *
+ * 属 {@link StoreBootRefusalError} 族:这是一句**确定**的拒启表态(再等也等不来另一个答案)—— 判官万一挪进 `ensureSchema()` 的开库等待窗,它不被重试、不被改写成「库打不开」。
+ * 消息**必须**以码领头:调用方交整句(对账的 `describeSchemaMismatch`、探针的 `probedMissingColumnRefusal` 都是码领头的整句),构造期核一次 —— 缺码 = 编程错,当场响,不是静默补一个。
+ */
+export declare class SchemaMismatchRefusedError extends StoreBootRefusalError {
+    /** 机读码(与退役 schema / 旁表建不出 / local 数据根的拒启同一个)。 */
+    readonly code = "config.schema_mismatch";
+    constructor(message: string, options?: ErrorOptions);
+}
 /**
  * 取消便签里的**大脑相位**快照 —— core `BrainStatus` 帧经 `brainStatusEventData` 投影后的五键子集。
  *
@@ -142,6 +156,14 @@ export type AbortCause = (typeof ABORT_CAUSES)[number];
 export interface PersistedResultSideKeys {
     cancelContext?: RunCancelContext;
     abortCause?: AbortCause;
+    /**
+     * 这条 run **照跑了**,而它的读拒行不按字节守:读拒表有行、执行环境不守读拒字节地板、部署没要求地板(`READ_DENY_FLOOR_REQUIRED` 未设)。
+     * `{ code: "config.read_deny_floor_unkept", message }` —— 与这条 run 事件流上那一帧 `engine_notice` 同码同句(句子点名 `REMOTE_EXEC=<车道>` 与出路
+     * `READ_DENY_FLOOR_REQUIRED=true`)。判官是引擎(每 run 准备期一次,结果按 `runId` 接上);说法的唯一属主 `read-deny-floor-notice.ts`,挂点 = 出口封口
+     * (`terminal.ts` 的 `sealResultForExit`)。拒起的 run 不带它(那一句在失败终局的句子里)。为什么属于 run 账本而不属于 core 的任务结果:引擎只发通告、
+     * 不在结果上留这件事,而句子里的执行环境与旋钮名是本仓的部署事实。
+     */
+    readDenyFloor?: ReadDenyFloorSummary;
 }
 /**
  * 落库/上 wire 的终局结果 = core 的 `TaskResult` **加上** server 自铸的可缺席侧记键({@link PersistedResultSideKeys})。
@@ -226,11 +248,15 @@ export interface RunRecord {
      *  MY replica" (consult the in-process inflight/steerable map authoritatively) from "held elsewhere" (fall
      *  back to the durable cross-replica flag). null for pre-column rows. */
     instanceId: string | null;
+    /** **持有腿**(`task_run.leg_id`):此刻持有这条行的那一条腿的身份 —— 认领铸它({@link mintRunLegId}:建行 = 首腿、续跑认领 = 新腿),交回给认领者;
+     *  停驻写的 CAS 只许持有腿落下(`setSuspended` / `setNeedsReview` 的 `legId`)。与 {@link instanceId} 是两件事:那一列答「活腿在哪台副本上」(路由),
+     *  这一列答「是不是这一条腿」。`null` = 没有持有腿的记录(列之前的行;更早版本的副本建 / 认领的行)—— 本版的腿从不持有它。不上 wire。 */
+    legId: string | null;
     /** 🔴 [ref] P-45 —— 这条 run 上**挂没挂着取消请求**(耐久 `cancel_requested` 列的投影,跨副本)。
      *
      *  语义就是那一列的字节:`POST /v1/runs/:id/cancel` 的 running 臂 CAS 成功即置位,持有副本的心跳拍
-     *  poll 到它就 abort;`markResuming`(续跑认领)把它清零 —— 一次撞上 suspend 的取消不许在恢复之后
-     *  再杀一遍(那条 reset 的理由逐字在 run-store-sql `markResuming` 上)。
+     *  poll 到它就 abort;旗是对**持有腿**的请求 —— 停驻写不落在挂着的旗上(停驻 CAS 认它,停驻提交读到旗就以取消收场),
+     *  `markResuming`(续跑认领 = 换持有腿)把它清零,旗随旧腿去。
      *
      *  为什么是**行上的一位**而不是读面再查一次:列早就在(三个后端同名),只是行投影没带它 —— 正是
      *  本仓 L1 键集门盯的那族「投影剥键」。读面每次 poll 再发一条 `isCancelRequested` 查询,是给热路径
@@ -275,9 +301,12 @@ export interface NewRunMeta {
     objectivePreview?: string | null;
     idem?: RunIdemBinding | null;
 }
+/** 铸一只持有腿({@link RunRecord.legId})—— 三只 run 店的两个认领口(`createRun` / `markResuming`)都调它,别处不铸。唯一值而非计数:同一 `taskId` 的行被删后重建,
+ *  新行的持有腿与旧腿的永不相等(旧腿迟到的停驻写不会落到新行上);认领者随写拿到它,不必读回。 */
+export declare function mintRunLegId(): string;
 /**
  * `RunStore.createRun` 的结局 —— 四形,一形一句话:
- *  · `{ ok: true }` —— 新行已建、会话 claim 已拿;
+ *  · `{ ok: true, legId }` —— 新行已建、会话 claim 已拿;`legId` = 这次认领铸下的持有腿({@link RunRecord.legId}),首腿的停驻写凭它;
  *  · `{ ok: false, existing }` —— 这次提交的一把**幂等钥匙**已经指向一条行:`idem_key`(`Idempotency-Key`)或
  *    `task_id`(调用方自铸的 `body.taskId`)—— 两把钥匙是**同一条律**(资源行上的唯一键),先认 `idem_key` 再认 `task_id`。
  *    这是「原子赢或观察」的**观察**臂:行原样交回,没建新行、没动会话;回执由提交面的唯一回执函数判。
@@ -288,6 +317,7 @@ export interface NewRunMeta {
  */
 export type CreateRunOutcome = {
     ok: true;
+    legId: string;
     existing?: undefined;
     activeTaskId?: undefined;
     sessionAbsent?: undefined;
@@ -309,10 +339,14 @@ export type CreateRunOutcome = {
 };
 /**
  * 认领栅栏交给 `write` 的那一行 run 此刻的事实(SQL = 锁住那一行读的;进程内 = 同步段里读的)。认领与 `running` 只认 taskId,而续跑腿让同一个 taskId
- * 停驻之后回到 `running`、认领仍在 —— 「接下这笔写的那条腿还是不是这条 run 的腿」要按腿问的写者拿它问(今天:副本 `instanceId`,续跑的 CAS 赢点把它改成接手的副本)。
+ * 停驻之后回到 `running`、认领仍在 —— 「接下这笔写的那条腿还是不是这条 run 的腿」要按腿问的写者拿它问:
+ *  · `legId` = 行此刻的持有腿({@link RunRecord.legId},认领铸、交给认领者)。持认领的腿自己的写问「是不是我」—— 判据 {@link createLegCtxClaim},
+ *    与停驻写的 CAS(`setSuspended` / `setNeedsReview`)、撤回(`withdrawMintedRun`)同一只身份读法;
+ *  · `instanceId` = 行此刻的副本。切档口(`routes/run-permission-mode.ts` `switchLegHolds`)问的是「是不是我切过的那条腿」,它手上是本副本活流登记簿里的流对象。
  */
 export interface FencedRun {
     readonly instanceId: string | null;
+    readonly legId: string | null;
 }
 /** SQL 认领栅栏的结局:`held: false` = 认领此刻不是这条 run 的(或它已不在跑),`write` 一次都没调。 */
 export type ClaimFenced<T> = {
@@ -346,7 +380,7 @@ export type ClaimFenceStore = import("./run-store-sql.js").SqlRunStore | InProce
 /**
  * 🔴 [ref] **一笔续跑输入写所凭的那只认领**(检查点店的写口 `putCtx` 交认领的那一形与 `rewriteCtxWhileClaimed` 收它):
  * `fence` = 写者持认领的那只 run 店(栅栏的来源就是认领本身 —— 检查点店不在构造期另绑一份 run 店),`taskId` = 持认领的 run,
- * `legHolds` = 腿判据(在栅栏里对锁住 / 同步段里那一行同步问一次,只读、不许 await)。
+ * `legHolds` = 腿判据(在栅栏里对锁住 / 同步段里那一行同步问一次,只读、不许 await;持认领的腿经 {@link createLegCtxClaim} 按持有腿判)。
  * 装配契约:SQL 检查点店只收同一库上的 SQL run 店(两店出自同一后端;店按判别位 `db` 判 SQL 形且方言同,错形响亮抛),local 检查点店只收进程内栅栏。
  */
 export interface CtxWriteClaim {
@@ -354,6 +388,12 @@ export interface CtxWriteClaim {
     readonly taskId: string;
     readonly legHolds: (run: FencedRun) => boolean;
 }
+/**
+ * 持认领的腿写续跑输入所凭的那只认领(提交腿 `http/submit-ctx.ts` 与续跑腿的写回 `http/resume-legs.ts` 同调这一只):腿判据 = 「被锁那一行此刻的持有腿就是本腿」——
+ * `legId` = 认领交给本腿的那一只(建行 `createRun` 的 `{ ok: true, legId }` / 续跑认领 `markResuming` 的交回值)。同一副本上同一 taskId 被后来的腿重新认领 ⇒
+ * 持有腿已换 ⇒ 零写(副本没变,只问副本的判据分不开这两条腿)。
+ */
+export declare function createLegCtxClaim(fence: ClaimFenceStore, taskId: string, legId: string): CtxWriteClaim;
 /**
  * `RunRecord["status"]`(= `"running" | TaskStatus`)的**唯一分类表** —— 词表的属主 = 判据的属主,
  * 与类型定义同住一个文件。四个类:

package/dist/plugins/store-contracts.js

@@ -1,7 +1,20 @@
 import { RUN_STALE_SEC_DEFAULT } from "../run-stale-default.js";
+import { randomUUID } from "node:crypto";
 export class StoreBootRefusalError extends Error {
 }
 export const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
+export class SchemaMismatchRefusedError extends StoreBootRefusalError {
+    code = SCHEMA_MISMATCH_ERROR_CODE;
+    constructor(message, options) {
+        super(codeLed(message), options);
+        this.name = "SchemaMismatchRefusedError";
+    }
+}
+function codeLed(message) {
+    if (!message.startsWith(`${SCHEMA_MISMATCH_ERROR_CODE}: `))
+        throw new TypeError(`a ${SCHEMA_MISMATCH_ERROR_CODE} refusal must lead with its code`);
+    return message;
+}
 export const ABORT_CAUSES = ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb", "stall_verdict"];
 export const RUN_STALLED_ERROR = "run stalled (instance lost?)";
 export const RUN_ORPHANED_ERROR = "run orphaned by engine restart";
@@ -13,7 +26,13 @@ const RUN_HOLDER_DEATH_CODE_WORDS = new Set(Object.values(RUN_HOLDER_DEATH_CODES
 export function isHolderDeathVerdict(run) {
     return run.status === "failed" && run.errorCode !== null && RUN_HOLDER_DEATH_CODE_WORDS.has(run.errorCode);
 }
+export function mintRunLegId() {
+    return randomUUID();
+}
 export const FENCE_LANDED = Symbol("in-process-claim-fence.landed");
+export function createLegCtxClaim(fence, taskId, legId) {
+    return { fence, taskId, legHolds: (run) => run.legId === legId };
+}
 export const RUN_STATUS_CLASS = {
     running: "live",
     completed: "succeeded",

package/dist/plugins/tidb-pool.d.ts

@@ -51,7 +51,7 @@ export declare function createTidbPool(config: ServiceConfig): Pool;
  *  3. 生成的全集 SQL 基线导出到 `docs/schema/baseline-mysql.sql`(由本数组机器生成;它是**产物**,不是真源
  *     —— 冲突时以本文件为准并重新生成)。
  *
- * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + image_bake_admit 种子行),语句数组是纯 CREATE。数组之外只有一只只读探针:会话部署格旁表
+ * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + 两只种子行:image_bake_admit 与 `Skill` 豁免截点),语句数组是纯 CREATE。数组之外只有一只只读探针:会话部署格旁表
  * `session_ext` 的外键列要抄被引列 `session_meta.session_id` 的字符集 / 排序规则(MySQL 外键两侧必须相同,而存量库上它随建库年代不同),建它之前读一次
  * `information_schema.COLUMNS`(`session-ext-table.ts` 的 `ensureSessionExtTableMysql`;探针只读、不导出任何 ALTER)。
  */
@@ -59,17 +59,22 @@ export declare const SCHEMA_STATEMENTS: readonly string[];
 /** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */
 export declare const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
 /** Acquire {@link ENSURE_SCHEMA_LOCK} on `conn` (the lock is CONNECTION-level, so the caller MUST then run all the
- *  serialized work on this SAME connection and release with {@link releaseEnsureSchemaLock}). Returns whether it was
- *  acquired. Exported so test setup that does ad-hoc DDL (e.g. a DROP-then-recreate) can serialize against
+ *  serialized work on this SAME connection and release with {@link releaseEnsureSchemaLock}). Resolves once the lock is
+ *  held. Exported so test setup that does ad-hoc DDL (e.g. a DROP-then-recreate) can serialize against
  *  ensureSchema runs using the IDENTICAL lock.
  *
  *  Under heavy concurrency (the integration suite fans ~20 callers at the SAME named lock; or a fleet boots N
  *  replicas at once) a BLOCKING GET_LOCK(name, 30) would park ~19 sessions in a pessimistic WAIT on TiDB's advisory-
  *  lock row — which both exhausts TiDB's "pessimistic lock retry limit" (surfacing as a thrown error) AND starves the
- *  app's OWN `SELECT … FOR UPDATE` paths (image-bake admission/lease) of pessimistic-lock budget. So we acquire
- *  NON-BLOCKING (GET_LOCK(name, 0) returns 0 immediately if held) and POLL with jittered backoff: one holder, the
+ *  app's OWN `SELECT … FOR UPDATE` paths (image-bake admission/lease) of pessimistic-lock budget. So the lock is taken
+ *  NON-BLOCKING (GET_LOCK(name, 0) returns 0 immediately if held) and POLLED with jittered backoff: one holder, the
  *  rest sleeping (not blocked in-DB). Polls until acquired (7.83.0: never degrades to unserialized — the [ref]
- *  `ADD INDEX` leg is not race-safe); a connection whose probe keeps throwing surfaces as a boot failure. */
+ *  `ADD INDEX` leg is not race-safe); a connection whose probe keeps throwing surfaces as a boot failure.
+ *
+ *  The probe statement, the reading of its answer, the engine's "pessimistic lock retry limit reached" sentence (read as
+ *  "somebody else is on the lock row" — the same fact as `got = 0`, NOT a broken connection) and the polling law all
+ *  live in ONE place, `ensure-schema-lock-policy.ts`; every other lock in this repo (the adoption arc lock) is taken
+ *  through the same acquirer. */
 export declare function acquireEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;
 /** Release {@link ENSURE_SCHEMA_LOCK} on `conn` (best-effort — the lock also auto-frees when the connection closes). */
 export declare function releaseEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;

package/dist/plugins/tidb-pool.js

@@ -1,4 +1,3 @@
-import { writeLogText } from "../observability/logger.js";
 import mysql from "mysql2/promise";
 import { TIDB_APPROVAL_ASK_STATEMENTS } from "./approval-ask-store-sql.js";
 import { TIDB_MEMORY_OPTOUT_GRANT_STATEMENTS } from "./memory-optout-grant-store-sql.js";
@@ -30,7 +29,10 @@ import { PERMISSION_RULE_INDEXES } from "./permission-rule-store-sql.js";
 import { RETENTION_TOMBSTONE_INDEXES } from "../stores-sql/retention-store-sql.js";
 import { RETENTION_LANE_INDEXES } from "./retention-lane-store-sql.js";
 import { LEADER_RUN_INDEXES } from "./leader-run-store-sql.js";
-import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
+import { acquireAdvisoryLock, releaseAdvisoryLock } from "./ensure-schema-lock-policy.js";
+import { SKILL_EXEMPTION_CUTOFF_ID, markIfAbsentSql, migrationMarkerDdl } from "./one-time-migration-marker.js";
+import { replicaRegistrationDdl } from "./replica-registration.js";
+import { servingRequirementDdl } from "./serving-requirement.js";
 import { createCloseAwarePool } from "./sql-driver.js";
 export function tidbPoolOptions(tidb) {
     const { host, port, user, password, database, connectionLimit } = tidb;
@@ -149,6 +151,11 @@ export const SCHEMA_STATEMENTS = [
      -- deliberately-absent idx_error_code note below.
      error_code  VARCHAR(64)  NULL,
      instance_id VARCHAR(64)  NULL,
+     -- leg_id: the HOLDING LEG — minted at every claim (createRun = first leg, markResuming = the resuming leg) and handed to the claimer; a park
+     -- write lands only for the leg that holds the row (setSuspended / setNeedsReview CAS on it). instance_id says WHERE the live leg is (routing),
+     -- leg_id says WHICH leg it is. NULL = no holding leg on record (a row written before the column existed, or created by an earlier-version
+     -- replica; an earlier-version replica's resume claim leaves the column as it found it).
+     leg_id      VARCHAR(36)  NULL,
      -- job_id (work-view correlation substrate): groups the runs of one logical task across BOTH client doors.
      job_id      VARCHAR(64)  NULL,
      -- source (credential-derived system identity, clay 2026-06-12): which door submitted the run
@@ -774,6 +781,9 @@ export const SCHEMA_STATEMENTS = [
      pool VARCHAR(32) NOT NULL,
      PRIMARY KEY (pool)
    ) COLLATE utf8mb4_bin`,
+    migrationMarkerDdl("mysql"),
+    replicaRegistrationDdl("mysql"),
+    servingRequirementDdl("mysql"),
     ...TIDB_APPROVAL_ASK_STATEMENTS,
     ...TIDB_MEMORY_OPTOUT_GRANT_STATEMENTS,
     ...TIDB_SESSION_CAPTURE_OPTOUT_STATEMENTS,
@@ -817,19 +827,18 @@ export const SCHEMA_STATEMENTS = [
     ...TIDB_RETENTION_TOMBSTONE_STATEMENTS,
 ];
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
+const ENSURE_SCHEMA_LOCK_ID = { dialect: "mysql", name: ENSURE_SCHEMA_LOCK };
+const lockConnOf = (conn) => ({
+    query: async (sql, params) => {
+        const [rows] = await conn.query(sql, params);
+        return { rows };
+    },
+});
 export async function acquireEnsureSchemaLock(conn, tag = "ensureSchema") {
-    await pollUntilLocked(async () => {
-        const [rows] = await conn.query("SELECT GET_LOCK(?, 0) AS got", [ENSURE_SCHEMA_LOCK]);
-        return Number(rows[0]?.got) === 1;
-    }, { tag, label: `GET_LOCK('${ENSURE_SCHEMA_LOCK}')` });
+    await acquireAdvisoryLock(lockConnOf(conn), ENSURE_SCHEMA_LOCK_ID, tag);
 }
 export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
-    try {
-        await conn.query("SELECT RELEASE_LOCK(?)", [ENSURE_SCHEMA_LOCK]);
-    }
-    catch (err) {
-        writeLogText("stderr", `[${tag}] RELEASE_LOCK('${ENSURE_SCHEMA_LOCK}') failed (lock auto-frees on connection close):`, err);
-    }
+    await releaseAdvisoryLock(lockConnOf(conn), ENSURE_SCHEMA_LOCK_ID, tag);
 }
 export const SCHEMA_INDEXES = [
     ...CENTRAL_SCHEMA_INDEXES,
@@ -861,6 +870,7 @@ export async function ensureSchema(pool) {
             return Array.isArray(rows) ? rows : [];
         });
         await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES ('standard')");
+        await conn.query(markIfAbsentSql("mysql"), [SKILL_EXEMPTION_CUTOFF_ID, Date.now()]);
         await ensureIndexes((text, params) => conn.query(text, params), "mysql", SCHEMA_INDEXES);
     }
     finally {