@sema-agent/server 7.131.0 → 7.132.0

package/dist/plugins/remote-env-local-docker.js

@@ -2,10 +2,12 @@ import path from "node:path";
 import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
+import { hostSubprocessEnv } from "../server-secret-env.js";
+import { LANE_HOME_PROBE_COMMAND, judgeLaneHome } from "../lane-home-probe.js";
 import { randomBytes } from "node:crypto";
 import { shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
-import { commandBoundsOf, livenessCutMessage } from "../exec-bounds.js";
+import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -30,6 +32,7 @@ export class RemoteLocalDockerExecutionEnv {
     handle;
     destroyed = false;
     connecting;
+    homeRefusal;
     constructor(config, deps = {}) {
         if (!config.image || !config.image.trim()) {
             config = { ...config, image: config.image ?? "" };
@@ -62,6 +65,8 @@ export class RemoteLocalDockerExecutionEnv {
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (this.homeRefusal)
+            return { ok: false, error: this.homeRefusal };
         if (config?.abortSignal?.aborted)
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
         if (this.containerId)
@@ -112,12 +117,39 @@ export class RemoteLocalDockerExecutionEnv {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
+        if (this.homeDir !== undefined && !(await this.untilOrAborted(this.probeContainerShell(), config?.abortSignal))) {
+            await this.forceRemove().catch(() => { });
+            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while detecting the container's shell") };
+        }
+        const home = await this.homeVerdict(config?.abortSignal);
+        if (home !== undefined) {
+            await this.forceRemove().catch(() => { });
+            return { ok: false, error: home };
+        }
+        if (this.destroyed) {
+            await this.forceRemove().catch(() => { });
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
+        }
         this.containerId = run.value.stdout.trim() || this.containerName;
         this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
         if (config?.secrets?.length) {
         }
         return ok(this.handle);
     }
+    async homeVerdict(signal) {
+        if (this.homeDir === undefined)
+            return undefined;
+        const probe = await this.docker(this.execRaw(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.controlTimeoutMs });
+        const verdict = judgeLaneHome(PROVIDER, this.homeDir, probe.ok && probe.value.exitCode === 0 ? { ok: true, stdout: probe.value.stdout } : { ok: false, reason: probe.ok ? `exit ${probe.value.exitCode}` : probe.error.message });
+        if (verdict === undefined)
+            return undefined;
+        if (!probe.ok && probe.error.code === "aborted")
+            return new RemoteExecutionError("aborted", "connect aborted while reading the environment's home");
+        const error = new RemoteExecutionError("connect_failed", verdict.refusal);
+        if (verdict.answered)
+            this.homeRefusal = error;
+        return error;
+    }
     async suspendVM(_options) {
         return unsupported("suspendVM");
     }
@@ -130,11 +162,25 @@ export class RemoteLocalDockerExecutionEnv {
     async reconnect(sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (this.homeRefusal)
+            return { ok: false, error: this.homeRefusal };
         if (sessionToken && sessionToken !== this.containerName) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `reconnect token '${String(sessionToken)}' does not match this env's container '${this.containerName}'`) };
         }
+        if (this.connecting !== undefined && this.containerId === undefined) {
+            const joined = await this.connecting;
+            if (!joined.ok || this.containerId !== undefined)
+                return joined;
+        }
         const insp = await this.docker(["inspect", "-f", "{{.State.Running}}", this.containerName], { timeoutMs: this.cfg.controlTimeoutMs });
         if (insp.ok && insp.value.exitCode === 0 && insp.value.stdout.trim() === "true") {
+            if (this.containerId === undefined && this.homeDir !== undefined)
+                await this.probeContainerShell();
+            const home = this.containerId === undefined ? await this.homeVerdict() : undefined;
+            if (home !== undefined)
+                return { ok: false, error: home };
+            if (this.destroyed || this.homeRefusal)
+                return { ok: false, error: this.homeRefusal ?? new RemoteExecutionError("connect_failed", "execution env destroyed during reconnect") };
             this.containerId = this.containerName;
             this.handle ??= { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
             return ok(this.handle);
@@ -179,7 +225,7 @@ export class RemoteLocalDockerExecutionEnv {
         if (!ready.ok)
             throw new RemoteExecutionError("connect_failed", ready.error.message, ready.error);
         const execArgs = this.execArgv(command, options?.cwd, options?.env);
-        const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(execArgs), { stdio: ["ignore", "pipe", "pipe"] });
+        const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(execArgs), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
         const queue = [];
         let finished = false;
         let failure;
@@ -286,7 +332,8 @@ export class RemoteLocalDockerExecutionEnv {
                         child.kill("SIGKILL");
                     }
                     catch { }
-                    throw new RemoteExecutionError("timeout", livenessCutMessage(liveness));
+                    const cut = buildLivenessCut(liveness);
+                    throw new RemoteExecutionError(cut.code, cut.message);
                 }
             }
             while (queue.length)
@@ -427,6 +474,9 @@ export class RemoteLocalDockerExecutionEnv {
     async createTempFile(options) {
         return this.posixFs.createTempFile(options);
     }
+    cliEnv() {
+        return hostSubprocessEnv({ site: "server.remote-env-local-docker.spawn-env", policy: "all", allow: [] });
+    }
     withHostFlag(args) {
         return this.cfg.dockerHost ? ["-H", this.cfg.dockerHost, ...args] : args;
     }
@@ -447,7 +497,7 @@ export class RemoteLocalDockerExecutionEnv {
         return new Promise((resolve) => {
             let settled = false;
             let forceSettleTimer;
-            const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: ["ignore", "pipe", "pipe"] });
+            const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
             const killGrace = () => {
                 try {
                     child.kill("SIGKILL");
@@ -505,11 +555,29 @@ export class RemoteLocalDockerExecutionEnv {
         });
     }
     containerShell = "/bin/sh";
-    containerShellProbed = false;
-    async probeContainerShell() {
-        if (this.containerShellProbed)
-            return;
-        this.containerShellProbed = true;
+    containerShellReady;
+    async untilOrAborted(shared, signal) {
+        if (!signal) {
+            await shared;
+            return true;
+        }
+        if (signal.aborted)
+            return false;
+        let onAbort;
+        const aborted = new Promise((res) => {
+            onAbort = () => res(false);
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        const won = await Promise.race([shared.then(() => true), aborted]);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+        return won;
+    }
+    probeContainerShell() {
+        this.containerShellReady ??= this.detectContainerShell();
+        return this.containerShellReady;
+    }
+    async detectContainerShell() {
         try {
             const r = await this.docker(["exec", this.containerName, "/bin/sh", "-c", "command -v bash"], { timeoutMs: this.cfg.controlTimeoutMs });
             if (r.ok && r.value.exitCode === 0 && r.value.stdout.trim().length > 0)

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

@@ -94,6 +94,10 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private inFlight?;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
+    /** 家目录声明 × 实测的判定,按连接记(同一条连接只问一次;重连换了连接再问 —— 登录用户不变时答案相同,代价一次往返)。 */
+    private homeChecked?;
+    /** 目标机答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每个面原样回它(同一目标机同一登录用户同一答案:不再问、不再发命令)。 */
+    private homeRefusal?;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在远端登录 shell 里(目标机的 profile / env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -119,6 +123,17 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
      *  caller 的 signal 只中止**它自己的等待**(共享在飞尝试继续伺服其他等待者;彻底取消归 destroy 的代际
      *  闸管,handshake 余命 ≤ readyTimeout 有界)。 */
     private ensureConnected;
+    /** 家目录判定的 per-caller 可中止等待(共享的判定承诺不动,只退本 caller)。 */
+    private raceVerdictAbort;
+    /**
+     * 家目录:声明在场(`homeDir`,只来自 `REMOTE_EXEC_HOME_DIR` —— 本车道没有自己的缺省)⇒ 在这条连接上问一次 `$HOME`(登录用户的 shell 答的,
+     * 与命令同一个用户、同一份登录 env),交唯一判官 `judgeLaneHome`。答了而不一致 / 不是绝对路径 ⇒ 拒记在环境上(每个面原样回它),命令一条都不发;
+     * 没答上(通道开不出 / 非零退出 / 超时)⇒ 这一次同样不开、不记,下一次调用重问。
+     * 问的是裸命令(不经工作目录守卫:工作目录进不去不影响家目录的答案)。上界 = 握手的 `readyTimeoutMs`(问一个环境变量,不是跑用户命令)。
+     */
+    private homeVerdict;
+    /** 连接本身(不含家目录判定):{@link ensureConnected} 的第一半。 */
+    private ensureTransport;
     private connectOnce;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
         ok: true;

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

@@ -3,10 +3,11 @@ import { Client } from "ssh2";
 import { createSshHostKeyVerifier } from "../ssh-host-key.js";
 import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, kindFromMode } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
-import { commandBoundsOf, livenessCutMessage } from "../exec-bounds.js";
+import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
+import { LANE_HOME_PROBE_COMMAND, judgeLaneHome } from "../lane-home-probe.js";
 const PROVIDER = "ssh";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
@@ -25,6 +26,8 @@ export class RemoteSshExecutionEnv {
     connEpoch = 0;
     inFlight;
     homeDir;
+    homeChecked;
+    homeRefusal;
     cdPath = "unknown";
     cfg;
     injectedConnectOnce;
@@ -103,6 +106,107 @@ export class RemoteSshExecutionEnv {
         return record.promise;
     }
     async ensureConnected(signal) {
+        for (let round = 0; round < 3; round++) {
+            if (this.homeRefusal)
+                return { ok: false, error: this.homeRefusal };
+            const transport = await this.ensureTransport(signal);
+            if (!transport.ok || this.homeDir === undefined)
+                return transport;
+            const conn = this.conn;
+            if (!conn)
+                return { ok: false, error: new ExecutionError("shell_unavailable", "SSH connection dropped right after connect") };
+            if (this.homeChecked?.conn !== conn) {
+                const checked = { conn, verdict: this.homeVerdict(conn, this.homeDir) };
+                this.homeChecked = checked;
+                void checked.verdict.then((r) => {
+                    if (!r.ok && this.homeRefusal === undefined && this.homeChecked === checked)
+                        this.homeChecked = undefined;
+                });
+            }
+            const verdict = await this.raceVerdictAbort(this.homeChecked.verdict, signal);
+            if (signal?.aborted)
+                return { ok: false, error: new ExecutionError("aborted", "aborted while checking the environment's home") };
+            if (!verdict.ok)
+                return verdict;
+            if (this.conn === conn)
+                return verdict;
+        }
+        return { ok: false, error: new ExecutionError("shell_unavailable", "SSH connection kept being replaced while the environment's home was being checked") };
+    }
+    async raceVerdictAbort(shared, signal) {
+        if (!signal)
+            return shared;
+        if (signal.aborted)
+            return { ok: false, error: new ExecutionError("aborted", "aborted while checking the environment's home") };
+        let onAbort;
+        const aborted = new Promise((res) => {
+            onAbort = () => res({ ok: false, error: new ExecutionError("aborted", "aborted while checking the environment's home") });
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        const raced = await Promise.race([shared, aborted]);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+        return raced;
+    }
+    homeVerdict(conn, declared) {
+        return new Promise((resolve) => {
+            let out = "";
+            let settled = false;
+            let channel;
+            let channelClosed = false;
+            const closeChannel = (ch) => {
+                if (ch === undefined || channelClosed)
+                    return undefined;
+                try {
+                    ch.close();
+                    return undefined;
+                }
+                catch (e) {
+                    return `the probe channel could not be closed: ${e instanceof Error ? e.message : String(e)}`;
+                }
+            };
+            const settle = (probe) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const closeTrouble = closeChannel(channel);
+                if (closeTrouble !== undefined && !probe.ok)
+                    probe = { ok: false, reason: `${probe.reason}; ${closeTrouble}` };
+                const verdict = judgeLaneHome(PROVIDER, declared, probe);
+                if (verdict === undefined)
+                    return resolve(ok(undefined));
+                const error = new ExecutionError("shell_unavailable", verdict.refusal);
+                if (verdict.answered)
+                    this.homeRefusal = error;
+                resolve({ ok: false, error });
+            };
+            const timer = setTimeout(() => settle({ ok: false, reason: `no answer within ${this.cfg.readyTimeoutMs}ms` }), this.cfg.readyTimeoutMs);
+            try {
+                conn.exec(LANE_HOME_PROBE_COMMAND, (err, stream) => {
+                    if (err)
+                        return settle({ ok: false, reason: err.message });
+                    if (settled)
+                        return void closeChannel(stream);
+                    channel = stream;
+                    stream
+                        .on("data", (d) => {
+                        if (out.length < 4096)
+                            out += d.toString("utf8");
+                    })
+                        .on("close", (code) => {
+                        channelClosed = true;
+                        settle(code === 0 ? { ok: true, stdout: out } : { ok: false, reason: code == null ? "the channel closed without an exit status" : `exit ${code}` });
+                    });
+                    stream.stderr.on("data", () => { });
+                });
+            }
+            catch (e) {
+                settle({ ok: false, reason: e instanceof Error ? e.message : String(e) });
+            }
+        });
+    }
+    async ensureTransport(signal) {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "SSH env destroyed — no lazy reconnect after teardown") };
         if (signal?.aborted)
@@ -435,8 +539,10 @@ export class RemoteSshExecutionEnv {
                     if (waitTimer !== undefined)
                         clearTimeout(waitTimer);
                 }
-                if (liveness !== undefined && !finished && Date.now() - lastChunk >= liveness.ms)
-                    throw new RemoteExecutionError("timeout", livenessCutMessage(liveness));
+                if (liveness !== undefined && !finished && Date.now() - lastChunk >= liveness.ms) {
+                    const cut = buildLivenessCut(liveness);
+                    throw new RemoteExecutionError(cut.code, cut.message);
+                }
             }
             while (queue.length)
                 yield queue.shift();

package/dist/plugins/remote-shell.d.ts

@@ -134,7 +134,6 @@ export declare function drainNumEnvWarnings(): Array<{
     raw: string;
 }>;
 export declare function numEnvOr(name: string, def: number, min: number): number;
-export declare const SYMLINK_CHAIN_MAX_HOPS = 64;
 /**
  * 一次往返走完叶 symlink 链的 POSIX sh 脚本(**纯数据**:返回一个命令串 ⇒ `build*`,CLAUDE.md 工厂律)。
  *

package/dist/plugins/remote-shell.js

@@ -1,4 +1,4 @@
-import { ExecutionError } from "@sema-agent/core";
+import { ExecutionError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { randomBytes } from "node:crypto";
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
@@ -120,7 +120,6 @@ export function numEnvOr(name, def, min) {
     }
     return Math.max(min, (Number.isFinite(n) ? n : 0) || def);
 }
-export const SYMLINK_CHAIN_MAX_HOPS = 64;
 export function buildSymlinkChainCommand(absPath) {
     return (`{ if ! command -v readlink >/dev/null 2>&1; then printf 'readlink: not found\\n' >&2; exit 127; fi; ` +
         `c=${shellQuote(absPath)}; n=0; ` +

package/dist/plugins/retention-store-sql.js

@@ -2,6 +2,7 @@ import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
 import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { incarnationFromCell } from "../session-incarnation.js";
 export const MANAGED_RETENTION = "managed";
 export const UNMANAGED_RETENTION = "none";
 export const RETENTION_AUDIT_TABLE = "retention_audit";
@@ -302,7 +303,10 @@ export class SqlRetentionStore {
         const { rows } = await exec.query(this.q(`SELECT sm.session_id, sm.incarnation FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < ? AND NOT ${this.liveReferenceExists()} ` +
             `ORDER BY sm.updated_at ASC LIMIT ?${suffix}`, `SELECT sm.session_id, sm.incarnation FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < $2 AND NOT ${this.liveReferenceExists()} ` +
             `ORDER BY sm.updated_at ASC LIMIT $3${suffix}`), [...w.params, new Date(input.cutoffMs), RETENTION_SESSION_BATCH]);
-        return rows.map((r) => ({ id: String(r.session_id), incarnation: typeof r.incarnation === "string" ? r.incarnation : "" }));
+        return rows.map((r) => {
+            const id = String(r.session_id);
+            return { id, incarnation: incarnationFromCell(id, r.incarnation, "absent") };
+        });
     }
     async countOrphanToolResultCandidates(exec, input) {
         return (await this.orphanToolResultCandidates(exec, input)).length;
@@ -337,7 +341,7 @@ export class SqlRetentionStore {
                     tombstones = await this.writeTombstones(conn, input.domain, "session", ids);
                 }
                 await this.writeAuditRow(conn, { domain: input.domain, action: "deleted_sessions", audit, deleted, skipped, tombstones });
-                const endedSpaces = doomed.filter((d) => d.incarnation !== "").map((d) => ({ sessionId: d.id, spaceKey: d.incarnation }));
+                const endedSpaces = doomed.flatMap((d) => (d.incarnation === undefined ? [] : [{ sessionId: d.id, spaceKey: d.incarnation }]));
                 return { domain: input.domain, deleted, skipped, tombstones, ...(endedSpaces.length > 0 ? { endedSpaces } : {}) };
             });
         }

package/dist/plugins/schema-consistency.d.ts

@@ -30,9 +30,29 @@
  * information_schema 查询抛错、或整库一行都读不出来 ⇒ **拒启**。探针的语义是「我证明了库等于代码」,
  * 证不出来时放行等于把一条保护性断言静默降级成祝福([ref]:保护型缺席必须 fail-closed)。
  * `recordFailOpen` 在这条腿上**不适用** —— 它是 F 类(装饰/缓存)的登记口,不是 P 类保护臂的逃生门。
+ *
+ * ── 第二道对账:跳版升级的库带着**退役** schema(先于建表)──────────────────────────────────────
+ * 一次性迁移 M1–M3(7.74.0–7.125.x)删掉了整树快照索引表 `snapshot_manifest` 与单座 steering 列 `checkpoint.pending_steer`,并把账本 / 已决行里
+ * 旧拼法 `unresolvable` 改写成 `ancestor_marked`;三条窗关后已删码。从没在带那三条的版本上起过服的库(跳版升级)两件退役 schema 至少一件仍在 ⇒
+ * 旧拼法的改写同样没跑过 ⇒ {@link assertRetiredSchemaAbsent} 响亮拒启({@link RetiredSchemaPresentError},同一个拒启码 `config.schema_mismatch`),
+ * 点名在场的坐标与出路(先在 7.125.x 起服一次让那三条跑完,再升)。**旧拼法不另扫**:那是一条对账本 `task_event` 的无索引整表扫(全站最大的表,
+ * PG 池级 `statement_timeout` 会把它切成拒启、每次起服重演);两件 schema 的在场就是「这只库没经过带迁移的版本」的判据(7.74.0 之前的每一版 DDL
+ * 都建它们,7.74.0 起都不再建;能写下旧拼法的 7.64.0–7.71.0 恒带两者)。
+ * 这一道**没有窗**(跳版升级的库永远可能出现),所以它住在起服对账一族而不在一次性迁移文件里 —— 那个文件里每一条都有窗,最后一条删掉时整个文件
+ * 一起删、零例外。判据读本族**唯一**的列册读者 {@link readLiveColumns}(PG 读查询真正会解析到的关系,与第一道同一读法),不另造表 / 列在场探针。
+ * **先于一切 DDL**:唯一的读处是探针口 {@link assertRetiredSchemaAbsentOnPool},唯一的调用点是 `store-backend.ts` 里 SQL 两后端的 `ensureSchema()` 包装
+ * (探针先于它的第一条 CREATE)—— 一次会拒的起服不许先在库里建出几十张本版新表(`task_run` 还带着新列),否则拒句里「没动过库」就是假话,
+ * 按拒句指路去 7.125.x 起服的人会撞上「库比 7.125.x 新」的第二道拒。嵌入方走公开序列 `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
+ * 即得到这一问,零动作。
+ * 残余(如实):运维在第一次起带迁移的版本之前就把两件退役 schema 都手工删掉的库,残留的旧拼法由门记录的读腿接住 —— 7.129.0 起(core 7.51.0 #1731)
+ * 那只读腿按 core 的档案读法读,`unresolvable` 是 core 退役词注册表里的词 ⇒ 记录原词原样读回、不改写(`trace/project.ts` `screenedGate`);local 文件车道
+ * 没有表与列,没有这一问 —— 引擎 File 店里已决 checkpoint 的记录按契约物理不可变,本仓没有合法缝改写它们,同由那条读腿接住。
  */
+import type { Pool as MysqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
 import { type SchemaDialect } from "./schema-ensure-legs.js";
 import { type SchemaProbeRead } from "./schema-live-columns.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 /** 一列:名字 + 它在 `CREATE TABLE` 里的**原样定义文本**(生成 ADD COLUMN 指路用,不另手写)。 */
 export interface ParsedColumn {
     readonly name: string;
@@ -73,4 +93,38 @@ export declare function describeSchemaMismatch(dialect: SchemaDialect, mismatche
  * 失败方向见文件头注:读抛 / 整库零行 ⇒ 拒。
  */
 export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SchemaDialect): Promise<void>;
+/**
+ * 跳版升级的库的拒启:退役 schema(快照索引表 / 单座列)任一仍在。**具名类型**:锚类型不锚文案(日志消费端与测试按 `code` / 类型分派);
+ * 码取列册对账同一个 `config.schema_mismatch`,运维面一个拒启码一个读法。拒句点名在场的坐标、说明第三条(旧拼法改写)同样没跑过、给出路。
+ * 继承 {@link StoreBootRefusalError}:这是一句**确定**的拒启表态(再等也等不来另一个答案)—— `ensureSchema()` 里它不被 SQL 开库的等待窗重试、不被改写成「库打不开」的拒句。
+ */
+export declare class RetiredSchemaPresentError extends StoreBootRefusalError {
+    readonly found: readonly string[];
+    /** 机读码(与列册对账的拒启同一个)。 */
+    readonly code = "config.schema_mismatch";
+    constructor(found: readonly string[]);
+}
+/**
+ * 退役 schema 的判据(纯读,**唯一一只**;规则见文件头「第二道对账」一节):经列册读者 {@link readLiveColumns} 读一次库里的列集,
+ * 快照索引表 / 单座列任一在场 ⇒ 抛 {@link RetiredSchemaPresentError}。新库(建表之前一列都没有)⇒ 不在场、过。读抛 ⇒ 原样上抛(拒启;不是确定的拒启表态,
+ * 开库等待窗照常重试 —— 与修前两条目录探针抛出时同一个去向)。
+ */
+export declare function assertRetiredSchemaAbsent(read: SchemaProbeRead, dialect: SchemaDialect): Promise<void>;
+/** 探针口的池参数:方言与它的池一起走(判别联合 ⇒ 不靠调用方断言「这个池是哪种」)。 */
+export type RetiredSchemaProbeTarget = {
+    readonly dialect: "tidb";
+    readonly pool: MysqlPool;
+} | {
+    readonly dialect: "pg";
+    readonly pool: PgPool;
+};
+/**
+ * **探针口**(退役 schema 唯一的读处):库一连上、**任何 DDL 之前**在一条借来的连接上读一遍,在场 ⇒ 抛 {@link RetiredSchemaPresentError}。本仓唯一调用点 =
+ * `store-backend.ts` 的 `withRetiredSchemaProbe`(SQL 两后端的 `ensureSchema()` 自身:探针先于建表的先后只写在那一处)。**不在包根上**:
+ * 嵌入方经公开序列的 `ensureSchema()` 得到这一问,不需要自己排序列。
+ *
+ * 不取 `ensureSchema` 那把 advisory 锁:本口纯读(列册读),不改任何东西,与别的副本正在跑的建表 / 迁移互不相干 —— 退役 schema 只会被 7.125.x 的迁移删去、
+ * 不会被谁凭空建回。用完即还连接,拒启时连接也已归还。
+ */
+export declare function assertRetiredSchemaAbsentOnPool(target: RetiredSchemaProbeTarget): Promise<void>;
 //# sourceMappingURL=schema-consistency.d.ts.map

package/dist/plugins/schema-consistency.js

@@ -1,5 +1,6 @@
 import { recordEnsureStatements } from "./schema-ensure-legs.js";
 import { readLiveColumns } from "./schema-live-columns.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 const QUOTES = new Set(["'", '"', "`"]);
 function stripLineComments(sql) {
     let out = "";
@@ -159,4 +160,55 @@ export async function assertSchemaMatchesCode(read, dialect) {
     if (mismatches.length > 0)
         throw new Error(describeSchemaMismatch(dialect, mismatches));
 }
+const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
+const RETIRED_STEER_SEAT = { table: "checkpoint", column: "pending_steer" };
+export class RetiredSchemaPresentError extends StoreBootRefusalError {
+    found;
+    code = SCHEMA_MISMATCH_ERROR_CODE;
+    constructor(found) {
+        super(`${SCHEMA_MISMATCH_ERROR_CODE}: this database still carries schema that the one-time migrations of server 7.74.0–7.125.x retired — refusing to start. ` +
+            `Found: ${found.join("; ")}. ` +
+            `Both come from builds that predate those migrations, so this database never booted a build that still carried them — which also means the third one never ran: ` +
+            `ask-origin gates stored under the retired spelling \`unresolvable\` (in task_event.data and in checkpoint.execution_outcome) were not rewritten to \`ancestor_marked\`. ` +
+            `This build carries none of the three and will not guess. ` +
+            `Way out: start a server 7.125.x build once against this database and let its one-time migrations finish (it drops the table and the column and rewrites the spelling; ` +
+            `while the column still holds a steering instruction that can be delivered it refuses and names the rows and its own ways out), then upgrade to this build. ` +
+            `On PostgreSQL this check reads the relation an unqualified name resolves to along search_path, while the 7.125.x migrations look only at current_schema(): ` +
+            `if the table or the checkpoint table carrying the column lives in a schema later on search_path, run the 7.125.x build with that schema first on its search_path ` +
+            `(for example ALTER ROLE <role> SET search_path = <that schema>, <the rest>), then restore the search_path and start this build. ` +
+            `The check behind this refusal is read-only and runs before this build creates any table or rewrites anything: it changed nothing in the database.`);
+        this.found = found;
+        this.name = "RetiredSchemaPresentError";
+    }
+}
+export async function assertRetiredSchemaAbsent(read, dialect) {
+    const live = await readLiveColumns(read, dialect);
+    const found = [];
+    if (live.has(RETIRED_SNAPSHOT_TABLE))
+        found.push(`table ${RETIRED_SNAPSHOT_TABLE} (the retired whole-tree snapshot index)`);
+    if (live.get(RETIRED_STEER_SEAT.table)?.has(RETIRED_STEER_SEAT.column) === true) {
+        found.push(`column ${RETIRED_STEER_SEAT.table}.${RETIRED_STEER_SEAT.column} (the retired single-seat steering column)`);
+    }
+    if (found.length > 0)
+        throw new RetiredSchemaPresentError(found);
+}
+export async function assertRetiredSchemaAbsentOnPool(target) {
+    if (target.dialect === "tidb") {
+        const conn = await target.pool.getConnection();
+        try {
+            await assertRetiredSchemaAbsent(async (sql) => (await conn.query(sql))[0], "mysql");
+        }
+        finally {
+            conn.release();
+        }
+        return;
+    }
+    const client = await target.pool.connect();
+    try {
+        await assertRetiredSchemaAbsent(async (sql) => (await client.query(sql)).rows, "pg");
+    }
+    finally {
+        client.release();
+    }
+}
 //# sourceMappingURL=schema-consistency.js.map

package/dist/plugins/session-epoch-anchor.d.ts

@@ -0,0 +1,13 @@
+/** One row of the scan: its `seq` and the `payload` column projected as text (`jsonColumnText`). */
+export interface EpochAnchorRow {
+    readonly seq: string | number;
+    readonly payload: unknown;
+}
+/**
+ * Page the rows `seq < beforeSeq` whose type is `prompt_epoch` or `compaction`, newest first (the backend's own SQL;
+ * an empty page = no older row).
+ */
+export type EpochAnchorPage = (beforeSeq: number) => Promise<readonly EpochAnchorRow[]>;
+/** The nearest epoch carrier below `floorSeq`, as stored; see the file header. */
+export declare function scanEpochAnchor(sessionId: string, floorSeq: number, page: EpochAnchorPage): Promise<unknown>;
+//# sourceMappingURL=session-epoch-anchor.d.ts.map

package/dist/plugins/session-epoch-anchor.js

@@ -0,0 +1,23 @@
+import { decodeSessionEventPayload } from "./session-event-payload.js";
+export async function scanEpochAnchor(sessionId, floorSeq, page) {
+    if (floorSeq <= 0)
+        return undefined;
+    let cursor = floorSeq;
+    for (;;) {
+        const rows = await page(cursor);
+        if (rows.length === 0)
+            return undefined;
+        for (const row of rows) {
+            const entry = decodeSessionEventPayload(row.payload, sessionId, row.seq);
+            if (entry.type === "prompt_epoch")
+                return entry;
+            if (entry.type === "compaction") {
+                const details = entry.details;
+                if (typeof details === "object" && details !== null && "promptEpoch" in details && details.promptEpoch !== undefined)
+                    return details.promptEpoch;
+            }
+        }
+        cursor = Number(rows[rows.length - 1].seq);
+    }
+}
+//# sourceMappingURL=session-epoch-anchor.js.map

package/dist/plugins/shared-memory-store-sql.d.ts

@@ -125,12 +125,18 @@ export interface SqlSharedMemoryStoreOptions {
      *  hope (core puts no cap on the provider's window, so the provider must state its own). */
     maxListLimit?: number;
 }
+/**
+ * WRITE-side store-id admission. The rule is core's own judge ({@link isSharedMemoryStoreId}): a row failing it would be dropped
+ * from every listing — an id the model cannot echo back is worse than an absent one — so we refuse to store it in the first place.
+ * This module keeps no copy of the pattern (nor of the `__` ban): the protocol table's namespace separator is core's to spell.
+ */
 export declare function assertStoreId(storeId: string): void;
 export declare function assertScopeKey(scopeKey: string): void;
 /**
- * WRITE-side document-path admission. Deliberately at least as strict as core's READ-side listing gate
- * (`isListablePath`): a row core would silently drop is refused here where an operator can see it. The
- * ONE rule that is stricter on purpose is the non-BMP refusal — see the header's ORDERING section.
+ * WRITE-side document-path admission: core's own judge ({@link isSharedMemoryDocumentPath} — the SAME predicate core's listing
+ * gate applies, so a row core would silently drop is refused here where an operator can see it), plus the two rules that are
+ * stricter on purpose and are this store's own: the column width, and the non-BMP refusal — see the header's ORDERING section.
+ * This module keeps no copy of core's rule (forbidden characters, segment shape, suffix table).
  */
 export declare function assertDocumentPath(path: string): void;
 /**

package/dist/plugins/shared-memory-store-sql.js

@@ -1,20 +1,17 @@
-import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
+import { isSharedMemoryDocumentPath, isSharedMemoryStoreId, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
 const isDupKey = isDupKeyError;
 export const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
 export const SHARED_MEMORY_STORE_TABLE = "shared_memory_store";
 export const SHARED_MEMORY_ENTRY_TABLE = "shared_memory_entry";
-const STORE_ID_RE = /^[A-Za-z0-9_.-]{1,64}$/;
 const ORG_SCOPE_RE = /^org:\S{1,185}$/;
-const FORBIDDEN_PATH_CHARS = /[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Default_Ignorable_Code_Point}\u2028\u2029\\]/u;
-const DOCUMENT_SUFFIXES = [".md", ".txt", ".json", ".jsonl"];
 const PATH_MAX_CHARS = 512;
 const DESCRIPTION_MAX_CHARS = 512;
 const DEFAULT_MAX_LIST_LIMIT = 500;
 export function assertStoreId(storeId) {
-    if (!STORE_ID_RE.test(storeId) || storeId.includes("__")) {
-        throw new Error(`shared-memory store id ${JSON.stringify(storeId)} is not usable: it must match /^[A-Za-z0-9_.-]{1,64}$/ and must not contain "__"`);
+    if (!isSharedMemoryStoreId(storeId)) {
+        throw new Error(`shared-memory store id ${JSON.stringify(storeId)} is not usable: core's shared-memory store-id rule refuses it`);
     }
 }
 export function assertScopeKey(scopeKey) {
@@ -26,18 +23,10 @@ export function assertDocumentPath(path) {
     const refuse = (why) => {
         throw new Error(`shared-memory document path ${JSON.stringify(path)} is not usable: ${why}`);
     };
-    if (!path.startsWith("/"))
-        refuse("it must be absolute (leading \"/\")");
     if (path.length > PATH_MAX_CHARS)
         refuse(`it is ${path.length} UTF-16 units, over the ${PATH_MAX_CHARS} the column stores`);
-    if (FORBIDDEN_PATH_CHARS.test(path))
-        refuse("it carries a control/format/private-use character or a backslash");
-    const segments = path.slice(1).split("/");
-    if (!segments.every((s) => s !== "" && !s.startsWith(".")))
-        refuse("every folder segment must be non-empty and must not start with \".\"");
-    const last = segments.at(-1);
-    if (last === undefined || !DOCUMENT_SUFFIXES.some((s) => last.endsWith(s)))
-        refuse(`the filename must end in ${DOCUMENT_SUFFIXES.join(", ")}`);
+    if (!isSharedMemoryDocumentPath(path))
+        refuse("core's shared-memory document-path rule refuses it");
     for (const ch of path) {
         if (ch.codePointAt(0) > 0xffff)
             refuse("it carries a supplementary-plane character, which would make SQL ordering and core's UTF-16 cursor ordering disagree");