@sema-agent/server 7.148.0 → 7.149.0

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;

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,6 +26,9 @@ 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 const RUN_STATUS_CLASS = {
     running: "live",

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,8 @@ 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 { createCloseAwarePool } from "./sql-driver.js";
 export function tidbPoolOptions(tidb) {
     const { host, port, user, password, database, connectionLimit } = tidb;
@@ -149,6 +149,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 +779,7 @@ export const SCHEMA_STATEMENTS = [
      pool VARCHAR(32) NOT NULL,
      PRIMARY KEY (pool)
    ) COLLATE utf8mb4_bin`,
+    migrationMarkerDdl("mysql"),
     ...TIDB_APPROVAL_ASK_STATEMENTS,
     ...TIDB_MEMORY_OPTOUT_GRANT_STATEMENTS,
     ...TIDB_SESSION_CAPTURE_OPTOUT_STATEMENTS,
@@ -817,19 +823,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 +866,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 {

package/dist/plugins/workspace-custody.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 执行环境工厂的工作区托管表 —— 「这只工作区现在归谁持有 / 能不能删」的唯一答者。local-docker(容器)与 host(本服务铸的临时目录)两条车道的工厂都经它铸环境、读它判删。
+ *
+ * ## 律
+ * 引擎 park-only 契约:`suspendable:false` 的远端环境断言工作区活过环境对象 —— 续跑由工厂重连到**同一只**工作区;引擎在续跑赢下之后丢掉停驻腿的环境、不销毁它
+ * (销毁了就是拆掉续跑腿正在用的工作区)。所以:
+ *  · **一只身份一只工作区**(身份 = 工厂上下文的 `taskId ?? sessionId`,与引擎交给工具的宿主任务号同一读法):同一身份还有一只没开始收场的环境 ⇒ 交回那一只
+ *    (停驻腿的环境引擎还拿着,续跑腿拿到的就是它);那一只正在收场 ⇒ 等它的收场落定再铸,它欠着的账交给新的这只;没有 ⇒ 铸一只入表。
+ *    同一身份同一时刻只有一条腿(会话锁 + run 认领),交回同一只不会让两条腿同时用它。
+ *  · **工作区的生命归持有它的环境,不归铸它的那一只**:表里每一只成员自己说它此刻持有哪只工作区;一只工作区能不能删 = 表里除问者之外还有没有成员持有它
+ *    ({@link WorkspaceCustody.holder})—— 没有才删,有就把删交给最后放手的那一只。
+ *
+ * ## 两条车道怎么读同一张表
+ *  · local-docker:工作区 = 身份派生名的那只容器;一只身份同一时刻只有一只没收场的成员(上面的交回律),容器名又由身份派生 ⇒ 不可能有第二个持有者,成员收场即删
+ *    (读 {@link WorkspaceCustody.envOf};欠账 = 删除没证实的那只容器,交给同一身份的下一只)。
+ *  · host:工作区 = 本服务铸的临时根;委派子代按父的工作目录落根 ⇒ 子代的环境与父的共持那只根(铸时问 {@link WorkspaceCustody.holder}「谁持有包含这一处的根」),
+ *    收场放手时问同一只「还有谁持有它」—— 父收场时子代还停驻在里面 ⇒ 父不删,子代最后一条腿收场时删。
+ *
+ * ## 出表
+ * 成员收场落定、什么都不欠、什么都不持有({@link CustodyMember.settled})⇒ 出表;没收场的成员(停驻腿的环境)一直在表里(停驻中被店层取消 / 过期的,引擎不销毁它,它持有的工作区
+ * 活到进程退出 —— local-docker 的容器由回收器按 run 行收,host 的目录由退出边界收)。
+ */
+/** 表里的一只成员(一只执行环境)向表说的四件事。 */
+export interface CustodyMember<Leftover> {
+    /** 收场的进度:没开始 ⇒ `undefined`(可以交回给同一身份的下一条腿);开始了 ⇒ 那一次收场(落定之后同一身份才铸新的)。 */
+    readonly releasing: Promise<void> | undefined;
+    /** 收场已落定。 */
+    readonly released: boolean;
+    /** 收场之后仍欠着、要交给同一身份下一只环境的账(local-docker:删除没证实的那只容器);不欠 ⇒ `undefined`。 */
+    readonly leftover: Leftover | undefined;
+    /** 什么都不再欠、不再持有 —— 出表。 */
+    readonly settled: boolean;
+}
+export interface WorkspaceCustody<E extends CustodyMember<L>, L> {
+    /**
+     * 这只身份的环境:还有一只没开始收场的 ⇒ 交回它;正在收场的 ⇒ 等它落定(再看一遍);都落定了 ⇒ 拿走欠账、铸一只入表。
+     * `mint` 抛 ⇒ 什么都不入表,原样抛。
+     */
+    envOf(identity: string, mint: (leftover: L | undefined) => E): Promise<E>;
+    /** 表里一只满足 `holds` 的成员(没有 ⇒ `undefined`)—— 「这只工作区现在还有谁持有」的唯一读法:问者把自己排除在 `holds` 里。 */
+    holder(holds: (member: E) => boolean): E | undefined;
+}
+export declare function createWorkspaceCustody<E extends CustodyMember<L>, L = never>(): WorkspaceCustody<E, L>;
+//# sourceMappingURL=workspace-custody.d.ts.map

package/dist/plugins/workspace-custody.js

@@ -0,0 +1,47 @@
+export function createWorkspaceCustody() {
+    const members = new Map();
+    const sweep = () => {
+        for (const member of members.keys())
+            if (member.settled)
+                members.delete(member);
+    };
+    return {
+        async envOf(identity, mint) {
+            for (;;) {
+                sweep();
+                const closing = [];
+                const owing = [];
+                for (const [member, id] of members) {
+                    if (id !== identity)
+                        continue;
+                    if (member.releasing === undefined)
+                        return member;
+                    if (!member.released)
+                        closing.push(member.releasing);
+                    else if (member.leftover !== undefined)
+                        owing.push(member);
+                }
+                if (closing.length > 0) {
+                    await Promise.allSettled(closing);
+                    continue;
+                }
+                let leftover;
+                for (const member of owing) {
+                    leftover = member.leftover;
+                    members.delete(member);
+                }
+                const env = mint(leftover);
+                members.set(env, identity);
+                return env;
+            }
+        },
+        holder(holds) {
+            sweep();
+            for (const member of members.keys())
+                if (holds(member))
+                    return member;
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=workspace-custody.js.map

package/dist/project-identity.d.ts

@@ -25,16 +25,17 @@ export declare function assertProjectLayerOwnable(scope: string, envName: string
  */
 export declare function normalizeGitRemoteUrl(url: string): string | undefined;
 /**
- * 任务根 → 项目层身份([ref]):当前档(`r` 优先,没有 origin 退 `p`)+ 本 checkout 的低档(`r` 档时 = 它的 `p` 档)。
- * 缺席形 = 找根的缺席词(`bare` / `unreadable`);git 配置在而读不了 ⇒ `unreadable`。
+ * 任务根 → 项目层身份(文件头「项目身份一条律」):按档序(`project-layer-key.ts` `PROJECT_IDENTITY_TIERS`)取本检出有的各档 ——
+ * 每一档 = 它的身份文本的 {@link digest24}(`m`:记号里的项目 id;`r`:归一后的网络 origin;`p`:canonical 项目根,恒有)。
+ * 链首 = 当前档,其余 = `lowerTiers`(折叠来源)。缺席 = 找根的缺席词(`bare` / `unreadable`);git 配置在而读不了、或记号读不出 ⇒ `unreadable`。
  */
-export declare function projectLayerIdentityOf(taskRoot: string): {
+export declare function projectLayerIdentityOf(taskRoot: string): Promise<{
     readonly root: string;
     readonly identity: ProjectLayerIdentity;
     readonly lowerTiers: readonly ProjectLayerIdentity[];
 } | {
     readonly absent: ProjectIdentityAbsentReason;
-};
+}>;
 /** 一个任务的项目层:core 声明席 + 本 checkout 要折进来的低档 / 退役层(按序,`memory-project-layer.ts` 折)。 */
 export interface ProjectLayerOfTask {
     readonly key: MemoryProjectKey;
@@ -43,11 +44,11 @@ export interface ProjectLayerOfTask {
 /**
  * 任务根 → 项目层([ref]:`userrepo:<属主段>/<档>.<摘要>`,属主 = `owner`,调用方由 `projectLayerOwnerOf(全局层)` 求得)。
  * `foldFrom` = 同一 checkout 能推出的旧层:退役 `repo:<同一路径哈希>`(一次性迁移,窗见 `plugins/one-time-migrations.ts` 登记表 M25)
- * + 当前档是 `r` 时它的 `p` 档(常设律)。
+ * + 当前档之下的每一档(常设律:`m` 档折 `r` / `p`,`r` 档折 `p`)。
  * `taskRoot === undefined` = 调用方**此刻不知道**任务根在本机哪里(根在沙箱/设备盘上;或 host 车道会话没登记 cwd、手落在 factory 现铸的
  * 临时目录)⇒ `unreadable` —— 「我看不到」,不是「这里没有项目」。
  */
-export declare function projectLayerForTaskRoot(taskRoot: string | undefined, owner: string): ProjectLayerOfTask;
+export declare function projectLayerForTaskRoot(taskRoot: string | undefined, owner: string): Promise<ProjectLayerOfTask>;
 /** {@link projectLayerForTaskRoot} 的声明席投影(core `TaskSpec.memory.projectKey`)。 */
-export declare function projectKeyForTaskRoot(taskRoot: string | undefined, owner: string): MemoryProjectKey;
+export declare function projectKeyForTaskRoot(taskRoot: string | undefined, owner: string): Promise<MemoryProjectKey>;
 //# sourceMappingURL=project-identity.d.ts.map