@sema-agent/server 7.149.0 → 7.150.0

package/dist/plugins/one-time-migrations.js

@@ -30,7 +30,9 @@ import { isUnusableArchive } from "../execution-placement.js";
 import { IDENTITY_COLUMN_NAME, SCENARIO_PREFIX_LIKE, SCENARIO_PREFIX_MARKER_ID, ScenarioPrefixSwitchRefusedError } from "./scenario-prefix-switch-m42.js";
 import { MIGRATION_MARKER_TABLE, SKILL_EXEMPTION_CUTOFF_ID, markIfAbsentSql, migrationMarkerDdl } from "./one-time-migration-marker.js";
 import { describeUpgradeDriftTail, expectedTableShapes } from "./schema-consistency.js";
-import { stopThenStartAction } from "./stop-then-start-sentence.js";
+import { olderReplicaEvidenceSentence, stopThenStartAction } from "./stop-then-start-sentence.js";
+import { buildThisReplicaRegistration, knowsCapability, readReplicaRegistrations, registerReplica } from "./replica-registration.js";
+import { assertReplicaTablesPresent, assertServingRequirementsMet } from "./serving-requirement.js";
 const RETIRED_SESSION_RULE_BUCKETS = ["commandAllow", "commandDeny"];
 export function buildMigrationReceipts() {
     return {
@@ -197,20 +199,6 @@ const OLD_GRAMMAR_SESSION_RULES_COLUMN = "rule_entries_old_grammar";
 const RETIRED_ASK_CAUSE_COLUMN = "denied_reason";
 const ASK_EXECUTION_LANE_COLUMN = "execution_lane";
 export const ONE_TIME_MIGRATIONS = [
-    {
-        id: "M12",
-        introducedIn: "7.122.0",
-        releasedOn: "2026-10-09",
-        removableAfter: "2026-11-08",
-        removal: "删模式词读法记号的判据与拒臂:`http/stored-body-replay.ts` 的 `permissionModeReadingUnstated`;`http/checkpoint-ctx.ts` 的 `permissionModeReadingStated` / `permissionModeReadingRefusal` / `PERMISSION_MODE_READINGS`、" +
-            "`StoredBodyReplayRefusal` 的 `permission_mode_reading` 臂及其日志字段与答复臂、`buildCheckpointCtx` 与 `withPermissionModeRewritten` 两处记号写点" +
-            "(后者删后 `resume-legs.ts` `drivePlanReview` 里对它的那一处调用回到只换体的 `{ ...ctx, body }`)、`CheckpointCtx.permissionModeReading`、" +
-            "`http/stored-body-replay.ts` 里 `StoredReplayDeployment` 的 `autonomy` 位与 `storedBodyReplayRefusal` 读 `deployment.autonomy` 的那一句(这一位只服务这一问;四个问点传 `deps.config` 整份,home 位还服务 `permissions` 一问,不动);" +
-            "`test/stored-request-prompt-profile-m30.test.ts` 的 SHARED 表里 `StoredBodyReplayRefusal` 那一行(rows 含 M12;M30 的登记行组已先删时该表已不在,这一句无事可做):rows 去掉 M12、整行并入同文件的 SITES(值 = 该行的 files 数组)",
-        afterRemoval: "没有响亮臂:删码之后仍停驻、在 7.121.x 及以前写下的行(把 `APPROVAL_TERMINAL_BACKSTOP_MS` 调长的部署,或跳过了带本条的版本直接升的库)在设了 " +
-            "`AUTONOMY=plan` 的部署上按体里的原词重放(运维的 plan 不再被按段重钳)—— 升级前把这些停驻的 run 决掉 / 取消,或升级窗内设 `AUTONOMY=read-only`",
-        reportKeys: [],
-    },
     {
         id: "M13",
         introducedIn: "7.123.0",
@@ -630,15 +618,18 @@ export const ONE_TIME_MIGRATIONS = [
         introducedIn: "7.147.0",
         releasedOn: "2026-11-07",
         removableAfter: "2026-12-07",
-        removal: "删 `src/plugins/execution-lane-rename-m40.ts` 整只文件;本文件的 M40 步(`renameRetiredExecutionLaneWordsM40` / `refuseWhileRunsHeartbeat`〔它读的 `readLiveRunHeartbeat` / `LiveRunHeartbeat` 由 M41 / M42 共读,两条也已删码时随之删〕/ `ExecutionLaneRenameRefusedError` / " +
-            "`EXECUTION_LANE_RENAME_REFUSED_CODE` / `ExecutionLaneRenameInput`,`migrateStepsOn` 第一步那一行与 `SqlOneTimeMigrationInput` 里的那一半)、报告 / 收据 / 日志 / `NO_SQL_MIGRATIONS` 的 `executionLaneWordsRenamed`、头注 M40 段;" +
-            "`store-backend.ts` 的 `LocalBackend.ensureSchema` 第一步与 `executionLaneWordsRenamed` 字段、两只 SQL 后端递 `liveRunWindowMs` 的那一半;" +
+        removal: "删 `src/plugins/execution-lane-rename-m40.ts` 整只文件;本文件的 M40 步(`renameRetiredExecutionLaneWordsM40` / `refuseWhileRunsHeartbeat`〔读证据的那一处调用;证据读法 `readOlderReplicaEvidence` 与判活窗输入归 M52 行〕/ `ExecutionLaneRenameRefusedError` / " +
+            "`EXECUTION_LANE_RENAME_REFUSED_CODE`,`migrateStepsOn` 第一步那一行)、报告 / 收据 / 日志 / `NO_SQL_MIGRATIONS` 的 `executionLaneWordsRenamed`、头注 M40 段;" +
+            "`store-backend.ts` 的 `LocalBackend.ensureSchema` 第一步与 `executionLaneWordsRenamed` 字段;" +
             "`local-session-store.ts` 的内核 `renameRetiredExecutionLaneWordsInCellsM40` 与数据根准入的具名读者 `readSessionMetaSidecarInWindow`(在内存里套的那一步;准入的解码点改用 `readSessionMetaSidecar`);" +
             "`LocalSessionStore.renameRetiredExecutionLaneWordM40`、`FileApprovalAskStore.renameRetiredExecutionLaneWordM40` 与内核的 `renameExecutionLaneWord`;" +
             "`approval-ask-store-sql.ts` / `execution-placement-sql.ts` 拒句里的 `retiredExecutionLaneHintM40(…)` 补句;`test/execution-lane-rename-m40.test.ts` 整只文件与 `test/execution-placement-switch-db-integration.test.ts` 的 M40 组",
         afterRemoval: "既有读口的拒臂接住(响亮,不再改名):仍带旧词的行 —— 跳过了带本条的版本直接升的库、窗关之后还在写的更早版本副本 —— SQL 问行读口拒、会话执行格读口拒(`ExecutionPlacementRowError`)," +
             "local 会话元数据边档整只严格拒启(`config.schema_mismatch`),local 问账日志由 M32 回填的词表外拒臂拒启(M32 删码之后:那只问行原样装回)。出路 = 升级时先过一次带本条的版本并起服",
-        stopThenStart: "renames the retired execution-lane word \"in-process\" to \"none\" on stored approval asks and sessions; a replica of an earlier version would keep writing the old word after the rename",
+        stopThenStart: {
+            reason: "renames the retired execution-lane word \"in-process\" to \"none\" on stored approval asks and sessions; a replica of an earlier version would keep writing the old word after the rename",
+            owedOn: owesExecutionLaneRenameM40,
+        },
         reportKeys: ["executionLaneWordsRenamed"],
     },
     {
@@ -649,10 +640,13 @@ export const ONE_TIME_MIGRATIONS = [
         removal: "删本文件的 M41 步(`moveSessionCellsToSideTable` / `refuseSessionExtMoveWhileRunsHeartbeat` / `deploymentColumnsOnMeta` / `SessionExtMoveRefusedError` / `SESSION_EXT_MOVE_REFUSED_CODE` / " +
             "`SessionExtMoveRefusalReason` / `sameCell` / `SESSION_EXT_MOVE_PAGE`,`migrateStepsOn` 里那两行)、报告 / 收据 / 日志 / `NO_SQL_MIGRATIONS` 的 `sessionExtRowsMoved` / `sessionMetaColumnsDropped`、头注 M41 段;" +
             "M32 读形里的 `cellsOnSideTable` 判(它读本条的 `deploymentColumnsOnMeta`):M32 还在时改成恒旁表形 —— 删 M32 写 `session_meta` 八列的那些臂(② ④ ④b ⑥ 与 ③ 的 `migrateDeviceBindingsStatement` 臂)," +
-            "留 ③ 的旁表臂(`migrateDeviceBindingsOntoSideTableStatements`:围栏拒句的「采旧」在任何库上仍要能落到执行格);M32 先于本条删码时这些随 M32 一并删;`readLiveRunHeartbeat` 在 M40 与 M42 也已删码时随之删;`test/session-ext-move-db-integration.test.ts` 整只文件",
+            "留 ③ 的旁表臂(`migrateDeviceBindingsOntoSideTableStatements`:围栏拒句的「采旧」在任何库上仍要能落到执行格);M32 先于本条删码时这些随 M32 一并删;`test/session-ext-move-db-integration.test.ts` 整只文件。能力名单 `REPLICA_CAPABILITIES` 里的 `M41` 不删(只增)",
         afterRemoval: "跳过了带本条的版本直接升上来的库:`session_meta` 上仍带部署格列 ⇒ 起服列册对账拒启(`config.schema_mismatch`,那几列是本树之外的多余列,拒句不给 ALTER —— 出路是带本条的版本);" +
             "部署格从旁表读,旧列上的值不被任何读者读。出路 = 升级时先过一次带本条的版本并起服",
-        stopThenStart: "moves the session deployment cells from session_meta to session_ext and then retires the old columns; a cell an earlier replica writes between the copy and the retirement is lost, and every cell write it makes afterwards fails",
+        stopThenStart: {
+            reason: "moves the session deployment cells from session_meta to session_ext and then retires the old columns; a cell an earlier replica writes between the copy and the retirement is lost, and every cell write it makes afterwards fails",
+            owedOn: owesSessionExtMoveM41,
+        },
         reportKeys: ["sessionExtRowsMoved", "sessionMetaColumnsDropped"],
         shapeChanges: [{ kind: "drop", table: "session_meta", columns: SESSION_EXT_MOVED_COLUMNS.map((c) => c.name) }],
     },
@@ -662,11 +656,14 @@ export const ONE_TIME_MIGRATIONS = [
         releasedOn: "2026-11-08",
         removableAfter: "2026-12-08",
         removal: "删 `src/plugins/scenario-prefix-switch-m42.ts` 整只文件;本文件的 M42 步(`switchScenarioPrefixM42` / `scannedIdentityColumnsM42`,`migrateStepsOn` 第一步那一行)、报告 / 收据 / 日志的 `scenarioPrefixSourcesScanned`、头注 M42 段;" +
-            "`readLiveRunHeartbeat` / `LiveRunHeartbeat` 在 M40 与 M41 也已删码时随之删;`store-backend.ts` 的 `LocalBackend.runOneTimeMigrations` 里 M42 那一腿(`switchLocalScenarioPrefixM42`)与四只 File 店的 `scenarioPrefixOwnerRowsM42`(run / 会话 / 问 / 附件);`test/scenario-prefix-switch-m42.test.ts` 与 `test/scenario-prefix-switch-db-integration.test.ts` 两只文件。" +
+            "`store-backend.ts` 的 `LocalBackend.runOneTimeMigrations` 里 M42 那一腿(`switchLocalScenarioPrefixM42`)与四只 File 店的 `scenarioPrefixOwnerRowsM42`(run / 会话 / 问 / 附件);`test/scenario-prefix-switch-m42.test.ts` 与 `test/scenario-prefix-switch-db-integration.test.ts` 两只文件。" +
             "标记表 `one-time-migration-marker.ts` 不随删(常设:中央建表语句建它,`Skill` 豁免截点那一行的家);库里留下的 `M42` 标记行 / 数据根里的标记文件无人再读,不删",
         afterRemoval: "没有响亮臂(如实):跳过了带本条的版本直接升的库,存量里以 `_scn:` 开头的身份被恢复管线读作某个人的场景(拆不出合文法的场景与人的 ⇒ `owner.malformed_subject` 响亮)。" +
             "出路 = 升级时先过一次带本条的版本并起服(它扫一次、命中即拒启点名)",
-        stopThenStart: "scans stored identities for the reserved scenario prefix and records a marker; an earlier replica does not reserve the prefix and would keep accepting such identities after the scan",
+        stopThenStart: {
+            reason: "scans stored identities for the reserved scenario prefix and records a marker; an earlier replica does not reserve the prefix and would keep accepting such identities after the scan",
+            owedOn: owesScenarioPrefixSwitchM42,
+        },
         reportKeys: ["scenarioPrefixSourcesScanned"],
     },
     {
@@ -789,9 +786,25 @@ export const ONE_TIME_MIGRATIONS = [
             "报告 / 收据 / `changedAnything` / `readingFields` / `NO_SQL_MIGRATIONS` 的 `sessionDeletingSwitchMarked`、头注 M51 段;`test/session-deleting-state-db-integration.test.ts` 的 M51 组;" +
             "库里留下的 `M51` 标记行无人再读,不删。**不随本条删**:在删态本身(列、围栏、规则 L 的在删半、终刀判令牌 —— 常设)、标记表 `one-time-migration-marker.ts`(常设)",
         afterRemoval: "没有响亮臂(也无需):窗 30 天之后更早版本的副本早已不在;跳过了带本条的版本直接升上来的库 —— 跨两版以上的混跑本就不被支持(7.147.0 起的停-迁-起)。出路 = 升级时先过一次带本条的版本并起服",
-        stopThenStart: "switches session deletion to a deleting state that every replica must read; an earlier replica does not read it and would accept a submission on a session this version is deleting",
+        stopThenStart: {
+            reason: "switches session deletion to a deleting state that every replica must read; an earlier replica does not read it and would accept a submission on a session this version is deleting",
+            owedOn: owesSessionDeletingSwitchM51,
+        },
         reportKeys: ["sessionDeletingSwitchMarked"],
     },
+    {
+        id: "M52",
+        introducedIn: "7.150.0",
+        releasedOn: "2026-11-09",
+        removableAfter: "2026-12-09",
+        removal: "删 `readOlderReplicaEvidence` 的心跳一半(按 `instance_id` 分组读 `task_run` 心跳的那一句、减去登记为知道该迁移的持有者那一步)与它的判活窗输入:`LiveRunWindowInput`、`SqlOneTimeMigrationInput` 里的那一半、" +
+            "`store-backend.ts` 的 `buildSqlOneTimeMigrationInput` 读 `runStaleSec` 的那一半、夹具 `test/helpers/db-schema-boot.ts` 的 `liveRunWindowMs`;停-迁-起守卫若已全部删码(M40 / M41 / M42 / M43 / M51 的窗都早于本条关)," +
+            "连同 `readOlderReplicaEvidence` 与 `stop-then-start-sentence.ts` 的 `OlderReplicaEvidence` / `OlderReplicaHolder` / `olderReplicaEvidenceSentence` 一并删;" +
+            "`test/run-liveness-single-source-gate.test.ts` ② 的 `one-time-migrations.ts` 白名单行与 ③ `store-backend.ts` 理由里「一次性迁移守卫」半句;`test/older-replica-evidence-db-integration.test.ts` 的证据组;头注 M52 段。" +
+            "**不随本条删**:副本能力登记(`replica-registration.ts`,能力名单只增)与起服准入(`serving-requirement.ts`)—— 常设",
+        afterRemoval: "没有响亮臂(如实):早于副本登记的副本不登记,删码之后它们对停-迁-起守卫完全不可见,忙与闲同 —— 发布日之后的天数不证明旧进程不在;出路只有运维:起带停-迁-起迁移的版本之前停光早于本条的副本",
+        reportKeys: [],
+    },
 ];
 export function migrationWindowOpen(window, today) {
     return window.removableAfter === null || today <= window.removableAfter;
@@ -808,7 +821,7 @@ export function migrationCarried(id) {
     return ONE_TIME_MIGRATIONS.some((w) => w.id === id);
 }
 export function stopThenStartMigrations(registry = ONE_TIME_MIGRATIONS) {
-    return registry.flatMap((row) => (row.stopThenStart === undefined ? [] : [{ id: row.id, reason: row.stopThenStart }]));
+    return registry.flatMap((row) => (row.stopThenStart === undefined ? [] : [{ id: row.id, ...row.stopThenStart }]));
 }
 export const NO_SQL_MIGRATIONS = {
     sessionRuleColumn: "file-store",
@@ -898,16 +911,27 @@ async function columnExists(db, dialect, table, column) {
 export function createSqlImportedLayerRootSource(exec) {
     return { candidateOwners: async () => ({ owners: await listRuleBucketOwners(exec), unnamedBuckets: 0 }), durable: new SqlDurableRulePartitionProvider(exec), isWholeBucketRefusal: isSqlBucketRefusal, isVanishedBucket: isSqlBucketVanished };
 }
-export async function runSqlOneTimeMigrations(dialect, pool, input) {
-    return dialect === "mysql" ? withMysqlLock(pool, (db) => migrateOn(db, "mysql", input)) : withPgLock(pool, (db) => migrateOn(db, "pg", input));
+export async function runSqlOneTimeMigrations(dialect, pool, input, me = buildThisReplicaRegistration()) {
+    const head = async (db) => {
+        await assertReplicaTablesPresent(db, dialect, me);
+        await registerReplica(db, dialect, me, Date.now());
+        await assertServingRequirementsMet(db, me);
+    };
+    const locked = async (db) => {
+        await assertServingRequirementsMet(db, me);
+        return migrateOn(db, dialect, input);
+    };
+    return dialect === "mysql" ? withMysqlLock(pool, head, locked) : withPgLock(pool, head, locked);
 }
-async function withMysqlLock(pool, run) {
+async function withMysqlLock(pool, head, run) {
     const conn = await pool.getConnection();
     let locked = false;
     try {
+        const db = mysqlDb(conn);
+        await head(db);
         await acquireEnsureSchemaLock(conn, "oneTimeMigrations");
         locked = true;
-        return await run(mysqlDb(conn));
+        return await run(db);
     }
     finally {
         if (locked)
@@ -915,13 +939,15 @@ async function withMysqlLock(pool, run) {
         conn.release();
     }
 }
-async function withPgLock(pool, run) {
+async function withPgLock(pool, head, run) {
     const client = await pool.connect();
     let locked = false;
     try {
+        const db = pgDb(client);
+        await head(db);
         await acquirePgEnsureSchemaLock(client, "oneTimeMigrations");
         locked = true;
-        return await run(pgDb(client));
+        return await run(db);
     }
     finally {
         if (locked)
@@ -1096,20 +1122,37 @@ async function markWithdrawEnabledM43(db, dialect, receipts, input) {
     const marked = await db.rows(dialect === "mysql" ? `SELECT 1 AS present FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = ?` : `SELECT 1 AS present FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = $1`, [WITHDRAW_MARK_ID]);
     if (marked.length > 0)
         return;
-    if ((await readLiveRunHeartbeat(db, dialect, input)) !== undefined)
+    if ((await readOlderReplicaEvidence(db, dialect, input, "M43")) !== undefined)
         return;
     receipts.withdrawMarkWritten += await db.exec(markIfAbsentSql(dialect), [WITHDRAW_MARK_ID, Date.now()]);
 }
+async function migrationMarked(read, dialect, id) {
+    if (!(await tableExists({ rows: read }, dialect, MIGRATION_MARKER_TABLE)))
+        return false;
+    return (await read(`SELECT 1 AS present FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = '${id}'`)).length > 0;
+}
+async function owesExecutionLaneRenameM40(read, dialect) {
+    return (await executionLaneWordRowsM40(read, dialect)).pendingRows > 0;
+}
+async function owesSessionExtMoveM41(read, dialect) {
+    return (await deploymentColumnsOnMeta({ rows: read }, dialect)).length > 0;
+}
+async function owesScenarioPrefixSwitchM42(read, dialect) {
+    return !(await migrationMarked(read, dialect, SCENARIO_PREFIX_MARKER_ID));
+}
+async function owesSessionDeletingSwitchM51(read, dialect) {
+    return !(await migrationMarked(read, dialect, SESSION_DELETING_MARK_ID));
+}
 export const SESSION_DELETING_MARK_ID = "M51";
 export const SESSION_DELETING_SWITCH_REFUSED_CODE = "config.session_deleting_switch_refused";
 export class SessionDeletingSwitchRefusedError extends StoreBootRefusalError {
     code = SESSION_DELETING_SWITCH_REFUSED_CODE;
-    reason = "live_runs";
-    constructor(live, tail = "") {
-        super(`${SESSION_DELETING_SWITCH_REFUSED_CODE} (reason: live_runs): this version deletes a session through a deleting state that every replica must read ` +
-            `(a submission on a session being deleted is refused), but ${live.liveRuns} running run(s) heartbeated on this database within the last ${live.windowSec}s (REAP_RUN_STALE_SEC) — ` +
+    reason = "older_replica";
+    constructor(evidence, tail = "") {
+        super(`${SESSION_DELETING_SWITCH_REFUSED_CODE} (reason: older_replica): this version deletes a session through a deleting state that every replica must read ` +
+            `(a submission on a session being deleted is refused), but ${olderReplicaEvidenceSentence(evidence)} — ` +
             "a replica of an earlier version may still be serving; it does not read that state and would accept a submission on a session this version is deleting. Nothing was changed and no marker was written. " +
-            stopThenStartAction(live.after) +
+            stopThenStartAction(evidence.after) +
             tail);
         this.name = "SessionDeletingSwitchRefusedError";
     }
@@ -1117,12 +1160,11 @@ export class SessionDeletingSwitchRefusedError extends StoreBootRefusalError {
 async function switchSessionDeletingM51(db, dialect, receipts, input) {
     if (!(await tableExists(db, dialect, MIGRATION_MARKER_TABLE)))
         await execUntil(db, migrationMarkerDdl(dialect), () => tableExists(db, dialect, MIGRATION_MARKER_TABLE));
-    const marked = await db.rows(dialect === "mysql" ? `SELECT 1 AS present FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = ?` : `SELECT 1 AS present FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = $1`, [SESSION_DELETING_MARK_ID]);
-    if (marked.length > 0)
+    if (!(await owesSessionDeletingSwitchM51((sql) => db.rows(sql), dialect)))
         return;
-    const heartbeat = await readLiveRunHeartbeat(db, dialect, input);
-    if (heartbeat !== undefined)
-        throw new SessionDeletingSwitchRefusedError(heartbeat, await describeUpgradeDriftTail((sql) => db.rows(sql), dialect));
+    const evidence = await readOlderReplicaEvidence(db, dialect, input, "M51");
+    if (evidence !== undefined)
+        throw new SessionDeletingSwitchRefusedError(evidence, await describeUpgradeDriftTail((sql) => db.rows(sql), dialect));
     receipts.sessionDeletingSwitchMarked += await db.exec(markIfAbsentSql(dialect), [SESSION_DELETING_MARK_ID, Date.now()]);
 }
 export async function scannedIdentityColumnsM42(db, dialect) {
@@ -1142,8 +1184,7 @@ export async function scannedIdentityColumnsM42(db, dialect) {
 export async function switchScenarioPrefixM42(db, dialect, receipts, input) {
     if (!(await tableExists(db, dialect, MIGRATION_MARKER_TABLE)))
         await execUntil(db, migrationMarkerDdl(dialect), () => tableExists(db, dialect, MIGRATION_MARKER_TABLE));
-    const marked = await db.rows(dialect === "mysql" ? `SELECT 1 AS present FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = ?` : `SELECT 1 AS present FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = $1`, [SCENARIO_PREFIX_MARKER_ID]);
-    if (marked.length > 0)
+    if (!(await owesScenarioPrefixSwitchM42((sql) => db.rows(sql), dialect)))
         return;
     const columns = await scannedIdentityColumnsM42(db, dialect);
     const hits = [];
@@ -1156,9 +1197,9 @@ export async function switchScenarioPrefixM42(db, dialect, receipts, input) {
     receipts.scenarioPrefixSourcesScanned += columns.length;
     if (hits.length > 0)
         throw new ScenarioPrefixSwitchRefusedError("stored_prefix", hits, undefined, await describeUpgradeDriftTail((sql) => db.rows(sql), dialect));
-    const live = await readLiveRunHeartbeat(db, dialect, input);
-    if (live !== undefined)
-        throw new ScenarioPrefixSwitchRefusedError("live_runs", [], live, await describeUpgradeDriftTail((sql) => db.rows(sql), dialect));
+    const evidence = await readOlderReplicaEvidence(db, dialect, input, "M42");
+    if (evidence !== undefined)
+        throw new ScenarioPrefixSwitchRefusedError("older_replica", [], evidence, await describeUpgradeDriftTail((sql) => db.rows(sql), dialect));
     await db.exec(markIfAbsentSql(dialect), [SCENARIO_PREFIX_MARKER_ID, Date.now()]);
 }
 export const EXECUTION_LANE_RENAME_REFUSED_CODE = "config.execution_lane_rename_refused";
@@ -1191,16 +1232,20 @@ export class ExecutionLaneRenameWriteRefusedError extends StoreBootRefusalError
     }
 }
 const EXECUTION_LANE_TABLES = [APPROVAL_ASK_TABLE, "session_meta", SESSION_EXT_TABLE];
-export async function renameRetiredExecutionLaneWordsM40(db, dialect, receipts, input) {
+async function executionLaneWordRowsM40(read, dialect) {
     const tables = [];
     for (const table of EXECUTION_LANE_TABLES)
-        if (await columnExists(db, dialect, table, "execution_lane"))
+        if (await columnExists({ rows: read }, dialect, table, "execution_lane"))
             tables.push(table);
     let pendingRows = 0;
     for (const table of tables) {
-        const [row] = await db.rows(`SELECT COUNT(*) AS n FROM ${table} WHERE execution_lane = ${dialect === "mysql" ? "?" : "$1"}`, [RETIRED_EXECUTION_LANE_WORD_M40]);
+        const [row] = await read(`SELECT COUNT(*) AS n FROM ${table} WHERE execution_lane = '${RETIRED_EXECUTION_LANE_WORD_M40}'`);
         pendingRows += Number(row?.["n"] ?? 0);
     }
+    return { tables, pendingRows };
+}
+export async function renameRetiredExecutionLaneWordsM40(db, dialect, receipts, input) {
+    const { tables, pendingRows } = await executionLaneWordRowsM40((sql) => db.rows(sql), dialect);
     if (pendingRows === 0)
         return;
     await refuseWhileRunsHeartbeat(db, dialect, pendingRows, input);
@@ -1208,34 +1253,54 @@ export async function renameRetiredExecutionLaneWordsM40(db, dialect, receipts,
         receipts.executionLaneWordsRenamed += await db.exec(dialect === "mysql" ? `UPDATE ${table} SET execution_lane = ? WHERE execution_lane = ?` : `UPDATE ${table} SET execution_lane = $1 WHERE execution_lane = $2`, [RENAMED_EXECUTION_LANE_M40, RETIRED_EXECUTION_LANE_WORD_M40]);
     }
 }
-async function readLiveRunHeartbeat(db, dialect, input) {
+export async function readOlderReplicaEvidence(db, dialect, input, migrationId) {
     if (!(await tableExists(db, dialect, "task_run")))
         return undefined;
     const since = new Date(Date.now() - input.liveRunWindowMs);
-    const [row] = await db.rows(`SELECT COUNT(*) AS n, MAX(updated_at) AS newest FROM task_run WHERE status = 'running' AND updated_at >= ${dialect === "mysql" ? "?" : "$1"}`, [since]);
-    const liveRuns = Number(row?.["n"] ?? 0);
+    const groups = (await db.rows(`SELECT instance_id, COUNT(*) AS n, MAX(updated_at) AS newest FROM task_run WHERE status = 'running' AND updated_at >= ${dialect === "mysql" ? "?" : "$1"} GROUP BY instance_id`, [since]))
+        .map((r) => ({ holder: typeof r["instance_id"] === "string" ? r["instance_id"] : undefined, runs: Number(r["n"] ?? 0), newest: r["newest"] }))
+        .filter((g) => g.runs > 0);
+    if (groups.length === 0)
+        return undefined;
+    const registered = await readReplicaRegistrations({ query: async (sql, params) => ({ rows: await db.rows(sql, params), affected: 0 }) }, dialect, groups.flatMap((g) => (g.holder === undefined ? [] : [g.holder])));
+    let unregisteredRuns = 0;
+    let newestMs = Number.NaN;
+    const registeredWithout = [];
+    for (const g of groups) {
+        const r = g.holder === undefined ? undefined : registered.get(g.holder);
+        if (r !== undefined && knowsCapability(r.capabilities, migrationId))
+            continue;
+        if (r === undefined)
+            unregisteredRuns += g.runs;
+        else
+            registeredWithout.push({ instanceId: r.instanceId, releaseLine: r.releaseLine, hostName: r.hostName, pid: r.pid, runs: g.runs });
+        const cell = g.newest instanceof Date ? g.newest : new Date(String(g.newest));
+        if (!Number.isNaN(cell.getTime()) && !(cell.getTime() <= newestMs))
+            newestMs = cell.getTime();
+    }
+    const liveRuns = unregisteredRuns + registeredWithout.reduce((n, h) => n + h.runs, 0);
     if (liveRuns === 0)
         return undefined;
-    const newestCell = row?.["newest"];
-    const newest = newestCell instanceof Date ? newestCell : new Date(String(newestCell));
     const now = Date.now();
-    const restartAtMs = (Number.isNaN(newest.getTime()) ? now : newest.getTime()) + input.liveRunWindowMs;
+    const restartAtMs = (Number.isNaN(newestMs) ? now : newestMs) + input.liveRunWindowMs;
     return {
+        migration: migrationId,
         liveRuns,
         windowSec: Math.round(input.liveRunWindowMs / 1000),
         restartAfter: new Date(restartAtMs).toISOString(),
         after: `${new Date(restartAtMs).toISOString()} (${Math.max(0, Math.ceil((restartAtMs - now) / 1000))}s from now)`,
+        unregisteredRuns,
+        registeredWithout: registeredWithout.sort((a, b) => a.instanceId.localeCompare(b.instanceId)),
     };
 }
 async function refuseWhileRunsHeartbeat(db, dialect, pendingRows, input) {
-    const heartbeat = await readLiveRunHeartbeat(db, dialect, input);
-    if (heartbeat === undefined)
+    const evidence = await readOlderReplicaEvidence(db, dialect, input, "M40");
+    if (evidence === undefined)
         return;
-    const { liveRuns, windowSec, restartAfter, after } = heartbeat;
-    throw new ExecutionLaneRenameRefusedError(pendingRows, liveRuns, restartAfter, `${pendingRows} stored rows (approval asks / sessions) carry the execution lane word "${RETIRED_EXECUTION_LANE_WORD_M40}", the name an earlier version gave the lane with no execution environment, ` +
-        `which this version calls "${RENAMED_EXECUTION_LANE_M40}" and does not read; this boot renames them (one-time migration M40), but ${liveRuns} running runs on this database heartbeat within the last ${windowSec}s ` +
-        `(REAP_RUN_STALE_SEC) — a replica of an earlier version is still serving, and it would keep writing the old word after the rename. No stored row was changed. ` +
-        stopThenStartAction(after) +
+    throw new ExecutionLaneRenameRefusedError(pendingRows, evidence.liveRuns, evidence.restartAfter, `${pendingRows} stored rows (approval asks / sessions) carry the execution lane word "${RETIRED_EXECUTION_LANE_WORD_M40}", the name an earlier version gave the lane with no execution environment, ` +
+        `which this version calls "${RENAMED_EXECUTION_LANE_M40}" and does not read; this boot renames them (one-time migration M40), but ${olderReplicaEvidenceSentence(evidence)} ` +
+        `— a replica of an earlier version may still be serving, and it would keep writing the old word after the rename. No stored row was changed. ` +
+        stopThenStartAction(evidence.after) +
         (await describeUpgradeDriftTail((sql) => db.rows(sql), dialect)));
 }
 export const SESSION_EXT_MOVE_REFUSED_CODE = "config.session_ext_move_refused";
@@ -1266,13 +1331,13 @@ export async function refuseSessionExtMoveWhileRunsHeartbeat(db, dialect, input)
     const columns = await deploymentColumnsOnMeta(db, dialect);
     if (columns.length === 0)
         return;
-    const heartbeat = await readLiveRunHeartbeat(db, dialect, input);
-    if (heartbeat === undefined)
+    const evidence = await readOlderReplicaEvidence(db, dialect, input, "M41");
+    if (evidence === undefined)
         return;
-    throw new SessionExtMoveRefusedError("live_runs", `${columns.length} session cells (${columns.map((c) => c.name).join(", ")}) still live on session_meta; this version keeps them on the side table ${SESSION_EXT_TABLE} and moves them on this boot ` +
-        `(one-time migration M41: copy, verify, then drop the columns), but ${heartbeat.liveRuns} running runs on this database heartbeat within the last ${heartbeat.windowSec}s (REAP_RUN_STALE_SEC) — ` +
-        "a replica of an earlier version is still serving; a cell it writes between the copy and the drop would be lost, and every cell write it makes after the drop fails. Nothing was changed. " +
-        stopThenStartAction(heartbeat.after) +
+    throw new SessionExtMoveRefusedError("older_replica", `${columns.length} session cells (${columns.map((c) => c.name).join(", ")}) still live on session_meta; this version keeps them on the side table ${SESSION_EXT_TABLE} and moves them on this boot ` +
+        `(one-time migration M41: copy, verify, then drop the columns), but ${olderReplicaEvidenceSentence(evidence)} — ` +
+        "a replica of an earlier version may still be serving; a cell it writes between the copy and the drop would be lost, and every cell write it makes after the drop fails. Nothing was changed. " +
+        stopThenStartAction(evidence.after) +
         (await describeUpgradeDriftTail((sql) => db.rows(sql), dialect)));
 }
 export async function moveSessionCellsToSideTable(db, dialect, receipts) {

package/dist/plugins/pg-pool.js

@@ -27,6 +27,8 @@ import { INBOX_PAYLOAD_COLUMN } from "./inbox-payload-column.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { PRINCIPAL_MAX_BYTES } from "../principal-shape.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";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -421,6 +423,8 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (store_id, path)
    )`,
     migrationMarkerDdl("pg"),
+    replicaRegistrationDdl("pg"),
+    servingRequirementDdl("pg"),
 ];
 export function pgPoolOptions(pgCfg, dbQueryTimeoutMs) {
     return {

package/dist/plugins/posix-shell-fs.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchorUnder } from "./exec-path-law.js";
 import { FileError, } from "@sema-agent/core";
 import { runSymlinkChain, shellQuote, kindFromMode } from "./remote-shell.js";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
@@ -60,11 +61,12 @@ export function createPosixShellFs(deps) {
             const names = r.value.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
             const out = [];
             for (const name of names) {
-                const info = await fs.statFileInfo(path.posix.join(abs, name), abortSignal);
+                const entry = anchorUnder(path.posix, abs, name);
+                const info = await fs.statFileInfo(entry, abortSignal);
                 if (info.ok)
                     out.push(info.value);
                 else
-                    out.push({ name, path: path.posix.join(abs, name), kind: "file", size: 0, mtimeMs: 0 });
+                    out.push({ name, path: entry, kind: "file", size: 0, mtimeMs: 0 });
             }
             return ok(out);
         },

package/dist/plugins/remote-env-adb.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
@@ -65,7 +66,7 @@ export class RemoteAdbExecutionEnv {
         this.injectedConnectOnce = deps?.connectOnce;
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return { sandboxId: this.cfg.serial, provider: PROVIDER, mountPath: this.cwd };
@@ -328,7 +329,7 @@ export class RemoteAdbExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async fsGate(p) {
         if (this.destroyed)

package/dist/plugins/remote-env-device.js

@@ -1,4 +1,5 @@
 import { posix } from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import { ExecutionError, FileError, RemoteExecutionError, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEVICE_ERROR_CODES, isDeviceAbsolutePath, } from "../device-store.js";
@@ -174,7 +175,7 @@ export class RemoteDeviceExecutionEnv {
             "performing a NON-atomic write here is exactly the silent downgrade guarded writes exist to prevent (#157). Refusing; the per-task factory mints a correctly-shaped env on the next task.", absPath);
     }
     resolve(p) {
-        return isDeviceAbsolutePath(p) ? posix.normalize(p) : posix.normalize(posix.join(this.cwd, p));
+        return anchoredPath(DEVICE_PATH_FAMILY, this.cwd, p);
     }
     instructionCwd(requested) {
         return requested === undefined ? this.cwd : this.resolve(requested);
@@ -183,7 +184,7 @@ export class RemoteDeviceExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(posix.join(...parts));
+        return ok(joinedPath(DEVICE_PATH_FAMILY, parts));
     }
     workspaceHandle() {
         return {
@@ -557,7 +558,7 @@ export class RemoteDeviceExecutionEnv {
                 return this.wrongOutcome("stat", o.kind, abs);
             if (!o.info)
                 return { ok: false, error: new FileError("unknown", "device returned a stat outcome without info — protocol violation", abs) };
-            return ok(toFileInfo(o.info));
+            return ok(toFileInfo(o.info, abs));
         });
     }
     async doReadLink(p, abortSignal) {
@@ -642,7 +643,7 @@ export class RemoteDeviceExecutionEnv {
                 return this.wrongOutcome("stat", o.kind, abs);
             if (!o.entries)
                 return { ok: false, error: new FileError("unknown", "device returned a stat outcome without entries — protocol violation", abs) };
-            return ok(o.entries.map(toFileInfo));
+            return ok(o.entries.map((w) => toFileInfo(w, anchorUnder(DEVICE_PATH_FAMILY, abs, posix.basename(w.path)))));
         });
     }
     async writeFile(p, content, abortSignal) {
@@ -738,8 +739,9 @@ function mergedEnv(taskEnv, commandEnv) {
 function markTruncated(text, truncated) {
     return truncated === true ? `${text}\n[output truncated by the device executor]` : text;
 }
-function toFileInfo(w) {
-    return { name: posix.basename(w.path), path: w.path, kind: w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : "file", size: w.size, mtimeMs: w.mtimeMs };
+const DEVICE_PATH_FAMILY = { sep: posix.sep, isAbsolute: isDeviceAbsolutePath };
+function toFileInfo(w, at) {
+    return { name: posix.basename(at), path: at, kind: w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : "file", size: w.size, mtimeMs: w.mtimeMs };
 }
 function toWireExpectation(e) {
     return {

package/dist/plugins/remote-env-e2b.d.ts

@@ -45,7 +45,7 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers, LaneHomeCo
     template?: string;
     /** Sandbox lifetime in ms (E2B billing window). Default {@link DEFAULT_TIMEOUT_MS}. */
     timeoutMs?: number;
-    /** Workspace root inside the VM; remote paths normalize against it. Default {@link DEFAULT_MOUNT_PATH}. */
+    /** Workspace root inside the VM; a relative path is anchored at it (`exec-path-law.ts`: anchored, never folded). Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
     /** Outbound network for the sandbox (clay: service needs external-network capability). Default `true`. */
     allowInternetAccess?: boolean;
@@ -365,6 +365,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private ensureConnected;
     private fsReady;
     private tempResult;
+    /** 提供方的条目 → `FileInfo`。`path` 取本环境的拼法(`at`:被问的那只路径 / 列目录时锚在它之下的条目),不取提供方回报的那一份
+     *  —— 提供方可能已把 `..` 折掉,而执行缝路径律(`exec-path-law.ts`)要求条目名在交来的路径之下、能原样再交回来。 */
     private toFileInfo;
     private fileError;
     /** A thrown provider error → this exec's error. The two cuts (aborted, the provider's own command deadline) are a command that RAN: they carry what it had

package/dist/plugins/remote-env-e2b.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
@@ -862,7 +863,7 @@ export class RemoteContainerExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readTextFile(p, abortSignal) {
         const sbx = await this.fsReady(p);
@@ -934,8 +935,9 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
-            const info = await this.rpc("files.getInfo", (signal) => sbx.value.files.getInfo(this.resolve(p), { signal }), abortSignal);
-            return ok(this.toFileInfo(info));
+            const abs = this.resolve(p);
+            const info = await this.rpc("files.getInfo", (signal) => sbx.value.files.getInfo(abs, { signal }), abortSignal);
+            return ok(this.toFileInfo(info, abs));
         }
         catch (e) {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
@@ -946,8 +948,9 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
-            const entries = await this.rpc("files.list", (signal) => sbx.value.files.list(this.resolve(p), { signal }), abortSignal);
-            return ok(entries.map((e) => this.toFileInfo(e)));
+            const abs = this.resolve(p);
+            const entries = await this.rpc("files.list", (signal) => sbx.value.files.list(abs, { signal }), abortSignal);
+            return ok(entries.map((e) => this.toFileInfo(e, anchorUnder(path.posix, abs, e.name))));
         }
         catch (e) {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
@@ -1044,7 +1047,7 @@ export class RemoteContainerExecutionEnv {
         return this.tempResult(r, "mktemp");
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     async rpc(label, op, userSignal, timeoutMs = this.cfg.rpcTimeoutMs) {
         const deadline = new AbortController();
@@ -1163,11 +1166,11 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `${op} failed`) };
         return ok(r.value.stdout.trim());
     }
-    toFileInfo(e) {
+    toFileInfo(e, at) {
         const kind = e.symlinkTarget ? "symlink" : e.type === FileType.DIR ? "directory" : "file";
         return {
             name: e.name,
-            path: e.path,
+            path: at,
             kind,
             size: e.size ?? 0,
             mtimeMs: e.modifiedTime ? e.modifiedTime.getTime() : 0,

package/dist/plugins/remote-env-host.d.ts

@@ -112,7 +112,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     /**
      * core 7.56.0 [ref]:shell 子进程继承的环境里**收不到**的条目(名 + 规则,从不带值)—— 与 {@link cdPath} 同一只组合的读面
      * (`server-secret-env.ts` 的 `withheldFromHostSubprocess`:继承组合扣下的发现,减去 `cfg.env` 这条显式授予重供的键)。逐命令的 `options.env`
-     * 是引擎自己交的显式授予,它知道(core KL-1963-b 同一残余)。只读:不披露、不计数、不碰 shell。
+     * 是引擎自己交的显式授予,它知道(core [ref] 同一残余)。只读:不披露、不计数、不碰 shell。
      */
     get withheldEnv(): readonly SecretEnvFinding[];
     private readonly workspaceDir;