@sema-agent/server 7.82.0 → 7.83.0

package/dist/plugins/pg-session-storage.js

@@ -8,6 +8,7 @@ import { contentForkRelation, fastForwardSharedContentDiverged } from "../sessio
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
+import { ensureIndexes } from "./ensure-index.js";
 const isDupKey = isPgUniqueViolation;
 function parseEntry(p) {
     return (typeof p === "string" ? JSON.parse(p) : p);
@@ -36,8 +37,6 @@ export const PG_SESSION_SCHEMA = [
      placed_at                   TIMESTAMPTZ(3),
      PRIMARY KEY (session_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_session_meta_owner ON session_meta (owner)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_meta_placement ON session_meta (placement_kind, placement_scope, placed_at)`,
     `CREATE TABLE IF NOT EXISTS session_event (
      session_id  VARCHAR(64) COLLATE "C" NOT NULL,
      seq         BIGINT      NOT NULL,
@@ -48,12 +47,17 @@ export const PG_SESSION_SCHEMA = [
      ts          TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (session_id, seq)
    )`,
-    `CREATE UNIQUE INDEX IF NOT EXISTS uq_session_event_entry ON session_event (session_id, entry_id)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_event_type ON session_event (session_id, type, seq)`,
+];
+export const SESSION_INDEXES = [
+    { table: "session_meta", name: "idx_session_meta_owner", columns: ["owner"] },
+    { table: "session_meta", name: "idx_session_meta_placement", columns: ["placement_kind", "placement_scope", "placed_at"] },
+    { table: "session_event", name: "uq_session_event_entry", columns: ["session_id", "entry_id"], unique: true },
+    { table: "session_event", name: "idx_session_event_type", columns: ["session_id", "type", "seq"] },
 ];
 export async function ensureSchema(pool) {
     for (const stmt of PG_SESSION_SCHEMA)
         await pool.query(stmt);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", SESSION_INDEXES);
 }
 export class PgSessionStorage extends BaseSessionStorage {
     pool;

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

@@ -41,7 +41,23 @@ export interface AdbEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
 }
 /** [R78]#1: adb stderr markers that mean the DEVICE TRANSPORT died mid-op (not a normal command failure) —
- *  typed retryable (reconnect + retry per idempotency), never a fake command result. Exported for tests. */
+ *  typed retryable (reconnect + retry per idempotency), never a fake command result. Exported for tests.
+ *
+ *  🔴 **S-401 把这个判据的输入面改了一半(复审 F12 纠正:原来写的「此前 stderr 恒空 ⇒ 整条是死码」是
+ *  **overclaim**,被本车自己的真机读数推翻)**。`exec-out` 合流的是**设备**的 stderr;**adb 客户端自己的**
+ *  诊断在两种传输下都照样走宿主 stderr。真机实测(同一台设备,拔掉 serial):
+ *  `adb -s BOGUS exec-out 'true'` ⇒ host exit **255** + stderr `error: device 'BOGUS' not found`;
+ *  `adb -s BOGUS shell -T -- 'true'` ⇒ host exit **1** + stderr `adb: device 'BOGUS' not found`。
+ *  ⇒ 本判据在 S-401 之前**对 adb 客户端级的传输故障是工作的**(这也正是原作者把词表写成这些 adb 自家
+ *  措辞的原因);S-401 改变的是**设备侧 stderr 从此也进这条通道**。
+ *
+ *  ⚠️ **随之而来的、如实登记的一格**:分流之后落到这里的 stderr **既有 adb 自己的诊断,也有设备命令自己的
+ *  输出**(adb 客户端把两者写在同一个 fd 上,真机实测无法在传输层分开)。于是设备上一条自己打印
+ *  `Connection reset by peer` 的命令(curl/nc)会被判成 `transport_lost`:本次命令结果不返回、`connected`
+ *  置假、下一次 exec fail-closed 直到 reconnect。**刻意不收窄词表**——词表收窄的方向是「漏判一次真掉线」,
+ *  那是 fail-open;误判的方向是多断一次连接,是 fail-closed。[ref] 轴上后者必须赢(能力探测的失败方向要与
+ *  能力语义方向一致)。ssh / k8s 两腿不吃这一格,因为它们的传输层自己给「通道关闭却没有 exit status」这个
+ *  **结构**信号;adb 的 shell v2 没有等价物,所以这里只能靠标记词,**这条臂就把话说在这里**。 */
 export declare function isAdbTransportLost(stderr: string): boolean;
 export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     /**
@@ -123,8 +139,15 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
     absolutePath(p: string): Promise<Result<string, FileError>>;
     joinPath(parts: string[]): Promise<Result<string, FileError>>;
-    /** 文件面的终态门 —— 读面此前**连 `connected` 都不查**,所以 destroy 之后还能从真设备读出文件内容。
-     *  与 host/local-docker/k8s/e2b 的姿态对齐(它们的文件面都在 destroy 后 fail-closed)。 */
+    /** 文件面的门 —— 与 host/local-docker/k8s/e2b 的姿态对齐(它们的文件面在未连/已拆时都 fail-closed)。
+     *
+     *  🔴 **S-401 复审 F2:这道门此前只查 `destroyed`,不查 `connected`**,于是 `readBinaryFile` /
+     *  `readTextFile` / `readTextLines` / `appendFile` 能在**从没连过**的 env 上直接打一次真设备往返。
+     *  在本批之前那只是个不一致;本批**新开的 `shell_v2` fail-closed 闸就长在 `connect()` 里**,
+     *  所以「不查 connected」= 那道闸对整个读面**不生效** —— 而 `readTextFile` 把错误文本当文件内容返回
+     *  正是本 P1 点名的症状之一。闸的射程必须覆盖它要保护的每一个面,否则它只是一句话。
+     *  ⇒ 规则收成一条:**这只 env 在 connect 成功之前、destroy 之后,文件面一个字都不答。**
+     *  (`exec`/`execStream` 本就是这条规则,见 `:257`/`:276`;文件面从此同判,不再是两套。) */
     private fsGate;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
     readTextFile(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
@@ -162,6 +185,42 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     }): Promise<Result<string, FileError>>;
     /** Spawn the adb binary with the given args; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private adb;
+    /**
+     * 🔴 **S-401 —— 本适配器跑设备命令的唯一往返形**(`exec` / `execStream` / `readBinaryFile` 三个调用点
+     * 共用一只;此前 `exec-out` 写了三遍,于是「传输到底给不给退出码」这件事没有属主)。
+     *
+     * **`adb shell`(shell protocol v2)而不是 `adb exec-out`。** 协议出处 = adb 自己的 `adb help`:
+     * `-x: disable remote exit codes and stdout/stderr separation` —— 即**不带** `-x` 的 `adb shell` 就是
+     * 「远端退出码 + stdout/stderr 分流」那一形。`exec-out` 走的是另一条 `exec:` 服务:单条裸流,设备
+     * stderr **合流进 stdout**,宿主进程退出码**恒 0**。
+     *
+     * 真机实测(车GV 2026-09-17,SM-S721B / Android 15 / toybox 0.8.11 / adb 1.0.41 `35.0.2`,设备 features
+     * 含 `shell_v2`),逐条复现而不是从文档推断:
+     * - `exec-out 'false'` ⇒ 宿主 exit **0**;`shell -T -- 'false'` ⇒ **1**;`shell -T -- 'exit 7'` ⇒ **7**
+     * - `exec-out 'realpath -- <坏链>'` ⇒ exit 0 + 错误文本在 **stdout**;`shell -T --` ⇒ exit 1 + 在 **stderr**
+     * - 1 MiB 随机字节 `cat` 回读:两形 md5 **相同**(`shell -T` 无 CRLF 转换、无包裹字节),故 binary 面照用
+     * - 同一条 `realpath` 的墙钟:`shell -T` 68 ms/次 vs `exec-out` 79 ms/次(n=10)—— 不是性能代价
+     *
+     * 修前的后果链([ref] 安全轴静默 fail-open):共享基座 `posix-shell-fs.ts` 的**每一处**失败判据(7 处)
+     * 与链原语 `remote-shell.ts` 的 `runSymlinkChain`(第 8 处)认的都是 `exitCode !== 0`,而这条传输恒答 0
+     * ⇒ adb 腿上 `realpath` / `readlink` / `stat` / `ls` / `cat` **永不失败**,`canonicalPath` 把那行**错误
+     * 文本**当成 canonical key 交给敏感路径门。⚠️ **复审 F15 纠正:原文写「五处」是数错了**,而且漏掉的
+     * 第 8 处恰恰是最贵的一处 —— `canonicalChain`(S-362 / core 7.21.0 [ref],上一版刚接)在 exit 恒 0 下会把
+     * **合流进 stdout 的错误文本当成链上的跳**解析出来,等于给 core 的路径判官递一条**伪造的** symlink 链。
+     *
+     * 🔴 **`-T` 与 `--` 都是承重件,不是装饰**:
+     * - `-T` = 不分配 pty。带 pty 的交互 shell 会把 stderr 并进 stdout 并做 CRLF 转换(council §9.2 的那句话
+     *   本身没错,错的是它被用来给 `exec-out` 背书)。给了命令的 `adb shell` 默认本就不开 pty,`-T` 是**显式**
+     *   关闭,不依赖那个默认。
+     * - `--` = 终止 adb 自己的旗标解析。没有它,**首字符为 `-` 的设备命令会被 adb 当成自己的旗标吃掉**
+     *   (真机复现:`adb shell -T '-x'` 不报错,直接变成一个挂住的交互 shell)—— 而 `-x` 恰好就是关掉
+     *   远端退出码与分流的那根旗标,即「一条以 `-x` 开头的命令能静默把本修关回去」。真机验证 `--` 之后的
+     *   参数原样落到设备 shell(`adb shell -T -- '-x'` ⇒ 设备答 `/system/bin/sh: -c: requires an argument`)。
+     *
+     * 命令永远是**最后一个**参数,整条包在一个 argv 元素里(设备侧 `sh -c` 收全串,与 `withCwdEnv` 的
+     * `cd … && …` 前缀语义一致)。
+     */
+    private deviceShellArgs;
     private withCwdEnv;
 }
 /**

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

@@ -5,7 +5,7 @@ import { spawn } from "node:child_process";
 import { shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
-import { fileErrorFromExec } from "./remote-env-file-error.js";
+import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "adb";
 const ok = (value) => ({ ok: true, value });
@@ -76,6 +76,18 @@ export class RemoteAdbExecutionEnv {
         const state = st.value.stdout.trim();
         const err = `${st.value.stdout} ${st.value.stderr}`.toLowerCase();
         if (state === "device") {
+            const feats = await this.adb(["-s", this.cfg.serial, "features"], { signal, timeoutMs: this.cfg.commandTimeoutMs });
+            if (!feats.ok)
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `adb features failed: ${feats.error.message}`, feats.error) };
+            if (feats.value.exitCode !== 0) {
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `adb features exited ${feats.value.exitCode} for ${this.cfg.serial}: ${feats.value.stderr.trim().slice(0, 200) || "(no stderr)"} — could not read the device's feature list this attempt`) };
+            }
+            if (!/(^|\s)shell_v2(\s|$)/.test(feats.value.stdout.trim())) {
+                return {
+                    ok: false,
+                    error: new RemoteExecutionError("unsupported", `device ${this.cfg.serial} does not advertise the 'shell_v2' feature, so this adapter cannot establish that its command round-trip carries a real exit code with stderr kept separate — the two properties every filesystem judgment on this lane depends on to tell failure from success. Refusing to connect rather than run on an unverifiable transport: attach a device that supports adb shell protocol v2.`),
+                };
+            }
             this.connected = true;
             return ok(this.workspaceHandle());
         }
@@ -112,7 +124,7 @@ export class RemoteAdbExecutionEnv {
         if (!this.connected)
             return { ok: false, error: new ExecutionError("shell_unavailable", "ADB device not connected — call connect() first") };
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
-        const r = await this.adb(["-s", this.cfg.serial, "exec-out", wrapped], {
+        const r = await this.adb(this.deviceShellArgs(wrapped), {
             signal: options?.abortSignal,
             timeoutMs: options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs,
             onStdout: options?.onStdout,
@@ -130,7 +142,7 @@ export class RemoteAdbExecutionEnv {
         if (!this.connected)
             throw new RemoteExecutionError("connect_failed", "ADB device not connected — call connect() first");
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
-        const child = this.spawnFn(this.cfg.adbPath, ["-s", this.cfg.serial, "exec-out", wrapped], { stdio: ["ignore", "pipe", "pipe"] });
+        const child = this.spawnFn(this.cfg.adbPath, this.deviceShellArgs(wrapped), { stdio: ["ignore", "pipe", "pipe"] });
         const queue = [];
         let finished = false;
         let failure;
@@ -176,6 +188,7 @@ export class RemoteAdbExecutionEnv {
             if (queue.length >= 512 && !paused) {
                 paused = true;
                 child.stdout.pause();
+                child.stderr.pause();
             }
             signalReady();
         };
@@ -206,6 +219,7 @@ export class RemoteAdbExecutionEnv {
                 if (paused) {
                     paused = false;
                     child.stdout.resume();
+                    child.stderr.resume();
                 }
                 if (failure)
                     throw failure;
@@ -244,6 +258,8 @@ export class RemoteAdbExecutionEnv {
     fsGate(p) {
         if (this.destroyed)
             return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
+        if (!this.connected)
+            return { ok: false, error: new FileError("unknown", "ADB device not connected — call connect() first", this.resolve(p)) };
         return undefined;
     }
     async readBinaryFile(p, abortSignal) {
@@ -251,21 +267,11 @@ export class RemoteAdbExecutionEnv {
         if (gated)
             return gated;
         const abs = this.resolve(p);
-        const r = await this.adb(["-s", this.cfg.serial, "exec-out", `cat ${shellQuote(abs)}`], { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs, binary: true });
+        const r = await this.adb(this.deviceShellArgs(`cat ${shellQuote(abs)}`), { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs, binary: true });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
-        const errOut = r.value.stderr.trim();
-        if (errOut) {
-            if (/no such file/i.test(errOut))
-                return { ok: false, error: new FileError("not_found", errOut, abs) };
-            if (/permission denied/i.test(errOut))
-                return { ok: false, error: new FileError("permission_denied", errOut, abs) };
-            if (/is a directory/i.test(errOut))
-                return { ok: false, error: new FileError("is_directory", errOut, abs) };
-            return { ok: false, error: new FileError("unknown", errOut, abs) };
-        }
         if (r.value.exitCode !== 0)
-            return { ok: false, error: new FileError("unknown", `adb exec-out cat exited ${r.value.exitCode}`, abs) };
+            return { ok: false, error: classifyFsStderr(r.value.stderr.trim() || `adb cat exited ${r.value.exitCode}`, abs) };
         return ok(r.value.stdoutBytes ?? new Uint8Array(0));
     }
     async readTextFile(p, abortSignal) {
@@ -284,6 +290,9 @@ export class RemoteAdbExecutionEnv {
         return ok(lines);
     }
     async writeFile(p, content, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
         const abs = this.resolve(p);
         const dir = path.posix.dirname(abs);
         if (dir && dir !== "." && dir !== "/") {
@@ -436,6 +445,9 @@ export class RemoteAdbExecutionEnv {
             });
         });
     }
+    deviceShellArgs(command) {
+        return ["-s", this.cfg.serial, "shell", "-T", "--", command];
+    }
     withCwdEnv(command, cwd, env) {
         const parts = [];
         const dir = cwd ?? this.cwd;

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

@@ -1012,8 +1012,8 @@ export class RemoteHostExecutionEnv {
         if (!ready.ok)
             return ready;
         const hops = [];
-        const seen = new Set();
         let cur = this.resolve(p);
+        const seen = new Set([cur]);
         for (let i = 0; i < SYMLINK_CHAIN_MAX_HOPS; i += 1) {
             let target;
             try {

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

@@ -64,16 +64,12 @@ export declare function buildSymlinkChainCommand(absPath: string): string;
  * {@link buildSymlinkChainCommand} 的 stdout → `SymlinkChain.hops`。
  *
  * 三件事**只在这里**做一次(四条 shell 腿 + e2b 共读):
- *  · **环即止** —— 出现重复跳时在**重复的那一跳之前**截断(CC `vr` 的 `d.has(u)` 同律)。
- *    🔴 **一条如实登记的、与 core 参考实现的分歧(合并复审车GU 亲核两树,验真后**披露不修**)**:本族(六腿同形)
- *    的 seen 表**从空开始**,而 core 的 `NodeExecutionEnv.canonicalChain` 用**被寻址的拼法**给它播种
- *    (`new Set([resolved])`)。于是**环绕回起点**的那一类链上两边差一跳:`a -> b`、`b -> a`,问 `a`,本族答
- *    `[b, a]`,core 答 `[b]`。**只在真有环时可观察**(无环链上 seen 永远碰不到起点,两边逐字节相同),而有环的
- *    链上那次写本来就会以 `ELOOP` 失败。不修的两条理由:①方向是**多报一跳**(判官多一个视图 ⇒ 多问,从不
- *    造成误放行),而改成与 core 同形是**摘掉**一个视图 —— 在 [ref] 轴上那是错的方向,要动得先有裁定;
- *    ②那一跳是 `b` **真的写下的**目标,契约句「不重复被寻址的拼法」两种读法都讲得通(core 读作「起点不入表」,
- *    本族读作「每条链接写下的目标都入表」),属**待 core 裁**的一格,不是本仓单方面能定的。
- *    ⚠️ 故各腿头注里「与 core 同形 / 逐字节对得上」那句话的射程是**无环链**;有环的那一格以本段为准。
+ *  · **环即止** —— 出现重复跳时在**重复的那一跳之前**截断(CC `vr` 的 `d.has(u)` 同律),且 seen 表用
+ *    **被寻址的拼法播种**(S-408,core 裁 2026-09-17:契约句「不重复被寻址的拼法」的正解是**起点本身不是一跳**——
+ *    链视图列的是「从被寻址拼法出发经过的中间拼法」,链绕回起点即结束、起点不再列;成环的事实由终点判决
+ *    `canonicalPath`(realpath ELOOP ⇒ unresolvable ⇒ 拒)承担,不由链视图承担)。于是 `a -> b`、`b -> a`,问 `a`,
+ *    答 `[b]`,与 core `NodeExecutionEnv.canonicalChain`(`new Set([resolved])` 播种)逐字节同形。此前本族从空表
+ *    开始、答 `[b, a]`(7.82.0 及之前;多一个冗余视图 —— 判官对 `a` 已按拼法判过一次),裁定后对齐。
  *    脚本侧不做:
  *    POSIX sh 里维护一张 seen 表要么靠内嵌换行的 `case` 模式(易碎),要么另起一个进程;放在这里则
  *    **一份实现**被四条腿与 e2b 共用,且与 host 腿的 Node 循环逐字节对得上。代价如实登记:链上真有环时,
@@ -83,7 +79,7 @@ export declare function buildSymlinkChainCommand(absPath: string): string;
  *    处理,不假装支持)。残留如实写出来:目标拼法真带首尾空白时,trim 后的跳可能与真目标差几个字节 ——
  *    方向上只会让一条跳**匹配不到**受保护行(少问,不是多放行),而终点判决(`canonicalPath`)完全不经本路。
  */
-export declare function symlinkChainHopsFromStdout(stdout: string): string[];
+export declare function symlinkChainHopsFromStdout(stdout: string, addressed: string): string[];
 /** {@link runSymlinkChain} 的传输面 —— 各腿的 `exec` 收敛成的那一个形(与 `PosixShellFs` 基座的 `run` 同形)。 */
 export type ShellChainRun = (cmd: string) => Promise<Result<{
     stdout: string;

package/dist/plugins/remote-shell.js

@@ -47,9 +47,9 @@ export function buildSymlinkChainCommand(absPath) {
         `*) d="${"${c%/*}"}"; case "$d" in "") c="/$t" ;; */) c="$d$t" ;; *) c="$d/$t" ;; esac ;; esac; ` +
         `printf '%s\\n' "$c"; n=$((n+1)); done; }`);
 }
-export function symlinkChainHopsFromStdout(stdout) {
+export function symlinkChainHopsFromStdout(stdout, addressed) {
     const hops = [];
-    const seen = new Set();
+    const seen = new Set([addressed]);
     for (const raw of stdout.split("\n")) {
         const hop = raw.trim();
         if (hop === "")
@@ -69,6 +69,6 @@ export async function runSymlinkChain(absPath, run) {
         return { ok: false, error: fileErrorFromExec(r.error, absPath) };
     if (r.value.exitCode !== 0)
         return { ok: false, error: classifyFsStderr(r.value.stderr, absPath, "unknown") };
-    return { ok: true, value: { hops: symlinkChainHopsFromStdout(r.value.stdout) } };
+    return { ok: true, value: { hops: symlinkChainHopsFromStdout(r.value.stdout, absPath) } };
 }
 //# sourceMappingURL=remote-shell.js.map

package/dist/plugins/retention-store-sql.d.ts

@@ -49,6 +49,7 @@ import type { ManagedRetentionCapability, RetentionDeclaration, RetentionReceipt
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 /**
  * 三只**被托管**的 SQL 店(session / checkpoint / tool-result)共用的 `retention` 声明常量。
  *
@@ -90,6 +91,8 @@ export declare const TIDB_RETENTION_STATEMENTS: readonly string[];
 /** PG 方言的建表语句(MySQL 孪生的逐条翻译:AUTO_INCREMENT→BIGSERIAL,逐列 `COLLATE "C"`,内联 KEY→独立
  *  CREATE INDEX)。语义逐字见 MySQL 孪生的行内注,此处不复述(两份注释迟早分叉)。 */
 export declare const PG_RETENTION_SCHEMA: readonly string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgRetentionSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const RETENTION_INDEXES: readonly IndexSpec[];
 /** PG 侧的幂等 schema apply(由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合;裸 `PgQueryFn` 形,与
  *  approval-ask / leader-run 同姿势 —— DDL 仍跑在中央那条 client 上,advisory lock 的 session 语义不受影响)。 */
 export declare function ensurePgRetentionSchema(query: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;

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

@@ -1,5 +1,6 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const MANAGED_RETENTION = "managed";
 export const UNMANAGED_RETENTION = "none";
 export const RETENTION_AUDIT_TABLE = "retention_audit";
@@ -93,8 +94,6 @@ export const PG_RETENTION_SCHEMA = [
      error         TEXT COLLATE "C"         NULL,
      PRIMARY KEY (id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_retention_audit_domain ON ${RETENTION_AUDIT_TABLE} (domain, id)`,
-    `CREATE INDEX IF NOT EXISTS idx_retention_audit_executed ON ${RETENTION_AUDIT_TABLE} (executed_at_ms)`,
     `CREATE TABLE IF NOT EXISTS ${RETENTION_HOLD_TABLE} (
      domain       VARCHAR(190) COLLATE "C" NOT NULL,
      -- held:1 = 冻结中,0 = 只是那把域级互斥行锁的哨兵。完整判据(为什么 presence 形不成立)见 MySQL 孪生。
@@ -119,11 +118,16 @@ export const PG_RETENTION_SCHEMA = [
      -- 主键带 domain(理由逐字见 MySQL 孪生:会话 id 是调用方可自选的,跨租户同名合法)。
      PRIMARY KEY (domain, kind, row_key)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_retention_tombstone_key ON ${RETENTION_TOMBSTONE_TABLE} (kind, row_key)`,
+];
+export const RETENTION_INDEXES = [
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_domain", columns: ["domain", "id"] },
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_executed", columns: ["executed_at_ms"] },
+    { table: `${RETENTION_TOMBSTONE_TABLE}`, name: "idx_retention_tombstone_key", columns: ["kind", "row_key"] },
 ];
 export async function ensurePgRetentionSchema(query) {
     for (const stmt of PG_RETENTION_SCHEMA)
         await query(stmt);
+    await ensureIndexes(query, "pg", RETENTION_INDEXES);
 }
 class RetentionAborted extends Error {
     why;

package/dist/plugins/roster-store-sql.d.ts

@@ -23,8 +23,11 @@
 import type { Pool } from "mysql2/promise";
 import { type RosterStore, type RosterEntry, type RosterAccess } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
+import { type IndexSpec } from "./ensure-index.js";
 export declare const ROSTER_TABLE = "agent_roster";
 export declare function ensureTiDBRosterSchema(pool: Pool): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgRosterSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const ROSTER_INDEXES: readonly IndexSpec[];
 export declare function ensurePgRosterSchema(q: PgQueryFn): Promise<void>;
 export declare class TiDBRosterStore implements RosterStore {
     private readonly pool;

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

@@ -1,4 +1,5 @@
 import { normalizeAgentName } from "@sema-agent/core";
+import { ensureIndexes } from "./ensure-index.js";
 export const ROSTER_TABLE = "agent_roster";
 function rowToEntry(r) {
     return {
@@ -42,7 +43,11 @@ export async function ensureTiDBRosterSchema(pool) {
     PRIMARY KEY (name_key, owner_key, scope_key),
     KEY idx_roster_agent (agent_id)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", ROSTER_INDEXES);
 }
+export const ROSTER_INDEXES = [
+    { table: `${ROSTER_TABLE}`, name: "idx_roster_agent", columns: ["agent_id"] },
+];
 export async function ensurePgRosterSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${ROSTER_TABLE} (
     name_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -66,7 +71,7 @@ export async function ensurePgRosterSchema(q) {
     recorded_at_ms BIGINT NOT NULL,
     PRIMARY KEY (name_key, owner_key, scope_key)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_roster_agent ON ${ROSTER_TABLE} (agent_id)`);
+    await ensureIndexes(q, "pg", ROSTER_INDEXES);
 }
 function upsertParams(entry, now) {
     return [

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

@@ -0,0 +1,21 @@
+/**
+ * 中央 schema(`tidb-pool.ts` 的 `SCHEMA_STATEMENTS` ⇄ `pg-pool.ts` 的 `PG_SCHEMA_STATEMENTS` 这一对孪生)
+ * 所拥有的那批表的索引**声明** —— S-287,两方言**共用同一份**。
+ *
+ * ## 为什么自成一个模块
+ * 两只池各自 `import` 了自己的驱动(`mysql2/promise` / `pg`,都是**值**导入)。若把这份声明放进其中一只,
+ * 另一只就得把对方的驱动一起拖进进程 —— 单后端部署因此多驮一个它永远用不到的驱动。声明是纯数据、零驱动
+ * 依赖,所以它住在两只池**之外**,谁都可以白拿。
+ *
+ * ## 谁应用它
+ *  · **PG**:`pg-pool.ts` 的 `ensurePgSchema`,在所有 `CREATE TABLE` 之后(PG 方言没有内联 `KEY`);
+ *  · **MySQL/TiDB**:`tidb-pool.ts` 的 `ensureSchema`,同样在所有 `CREATE TABLE` 之后 —— 新建库上这批索引
+ *    早已随 `CREATE TABLE` 的内联 `KEY` 到货,`ensureIndex` 的探测因此**一条 DDL 都不发**;只有存量库
+ *    (建表那天还没有这条索引)才真的发一次 `ALTER TABLE … ADD INDEX`。
+ *
+ * 🔴 每条声明的**列序**必须与 `tidb-pool.ts` 那张表的内联 `KEY` 逐字一致(等值前缀在前、排序列在后);
+ *    两处列序分叉 = 两方言的访问路径分叉,而探测只看索引名、看不出列序不同。
+ */
+import type { IndexSpec } from "./ensure-index.js";
+export declare const CENTRAL_SCHEMA_INDEXES: readonly IndexSpec[];
+//# sourceMappingURL=schema-indexes.d.ts.map

package/dist/plugins/schema-indexes.js

@@ -0,0 +1,25 @@
+export const CENTRAL_SCHEMA_INDEXES = [
+    { table: "task_run", name: "idx_task_run_session_status", columns: ["session_id", "status"] },
+    { table: "task_run", name: "idx_task_run_owner", columns: ["owner"] },
+    { table: "task_run", name: "idx_task_run_created", columns: ["created_at"] },
+    { table: "task_run", name: "idx_task_run_job", columns: ["job_id"] },
+    { table: "task_active", name: "idx_task_active_task", columns: ["task_id"] },
+    { table: "checkpoint", name: "idx_checkpoint_status_deadline", columns: ["status", "deadline"] },
+    { table: "checkpoint", name: "idx_checkpoint_session_status", columns: ["session_id", "status"] },
+    { table: "resume_anchor", name: "idx_resume_anchor_session", columns: ["session_id"] },
+    { table: "approval_nonce", name: "idx_approval_nonce_expires", columns: ["expires_at_ms"] },
+    { table: "sendfile_link", name: "idx_sendfile_link_scope", columns: ["scope", "id"] },
+    { table: "session_policy", name: "idx_session_policy_session", columns: ["session_id"] },
+    { table: "snapshot_blob", name: "idx_snapshot_blob_created", columns: ["created_at"] },
+    { table: "file_history_version", name: "idx_file_history_version_blob", columns: ["blob_hash"] },
+    { table: "file_history_boundary_file", name: "idx_file_history_bf_key", columns: ["scope", "key_hash"] },
+    { table: "file_history_blob", name: "idx_file_history_blob_created", columns: ["created_at"] },
+    { table: "workflow_run", name: "idx_wfrun_scope_created", columns: ["scope", "created_at_ms"] },
+    { table: "workflow_run", name: "idx_wfrun_scope_status", columns: ["scope", "status"] },
+    { table: "workflow_agent_session", name: "idx_wfagentsess_run", columns: ["run_id"] },
+    { table: "workflow_completion_inbox", name: "idx_wfinbox_session_seq", columns: ["session_id", "seq"] },
+    { table: "workflow_inbox_fence", name: "idx_wffence_until", columns: ["until_ms"] },
+    { table: "workflow_notify_journal", name: "idx_wfnotify_acked", columns: ["acked"] },
+    { table: "shared_memory_store", name: "idx_shared_memory_store_scope", columns: ["scope_key", "store_id"] },
+];
+//# sourceMappingURL=schema-indexes.js.map

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

@@ -26,6 +26,7 @@
  */
 import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
+import { type IndexSpec } from "./ensure-index.js";
 export interface TaskAttachmentRecord {
     id: string;
     owner: string;
@@ -116,6 +117,8 @@ export declare function materializeAttachmentsInto(env: {
     }>;
 }, store: TaskAttachmentStore, sessionId: string): Promise<number>;
 export declare function ensureTiDBTaskAttachmentSchema(pool: Pool): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgTaskAttachmentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const TASK_ATTACHMENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgTaskAttachmentSchema(q: PgQueryFn): Promise<void>;
 /** bytes → 4 MiB 块序列(共享切块器,两方言 + 完整性校验共用)。 */
 export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {

package/dist/plugins/task-attachment-store.js

@@ -1,3 +1,4 @@
+import { ensureIndexes } from "./ensure-index.js";
 export const TASK_ATTACHMENT_TABLE = "task_attachment";
 export function materializedRelPaths(atts) {
     const used = new Set();
@@ -76,7 +77,12 @@ export async function ensureTiDBTaskAttachmentSchema(pool) {
     KEY idx_att_session (session_id),
     KEY idx_att_unbound (created_at_ms)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", TASK_ATTACHMENT_INDEXES);
 }
+export const TASK_ATTACHMENT_INDEXES = [
+    { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_session", columns: ["session_id"] },
+    { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_unbound", columns: ["created_at_ms"] },
+];
 export async function ensurePgTaskAttachmentSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
     id VARCHAR(64) COLLATE "C" NOT NULL,
@@ -91,8 +97,7 @@ export async function ensurePgTaskAttachmentSchema(q) {
     bound_at_ms BIGINT,
     PRIMARY KEY (id)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_att_session ON ${TASK_ATTACHMENT_TABLE} (session_id)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_att_unbound ON ${TASK_ATTACHMENT_TABLE} (created_at_ms)`);
+    await ensureIndexes(q, "pg", TASK_ATTACHMENT_INDEXES);
 }
 export class TiDBTaskAttachmentStore {
     pool;

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

@@ -1,6 +1,7 @@
 import mysql from "mysql2/promise";
 import type { Pool, PoolConnection } from "mysql2/promise";
 import type { ServiceConfig } from "../config-types.js";
+import { type IndexSpec } from "./ensure-index.js";
 /**
  * Shared TiDB (MySQL wire-compatible) connection pool for the durable Session center (L1).
  * Owned by `main.ts`; closed on shutdown.
@@ -57,11 +58,22 @@ export declare const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
  *  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
- *  rest sleeping (not blocked in-DB). Return false only after exhausting retries (the caller then DEGRADES to
- *  unserialized rather than blocking boot forever — the DDL is still individually idempotent). */
-export declare function acquireEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<boolean>;
+ *  rest sleeping (not blocked in-DB). Polls until acquired (7.83.0: never degrades to unserialized — the S-287
+ *  `ADD INDEX` leg is not race-safe); a connection whose probe keeps throwing surfaces as a boot failure. */
+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>;
+/**
+ * S-287:`SCHEMA_STATEMENTS` 建的那批表**在存量库上可能缺的索引**(声明与 PG 侧逐条共用同一份 —— 见
+ * `plugins/ensure-index.ts` 头注与 `plugins/schema-indexes.ts`)。
+ *
+ * 组合口径与 `SCHEMA_STATEMENTS` **一一对应**:凡是它建的表,索引声明就进这个数组;它不建的表
+ * (device / roster / background-agent / mailbox / task-attachment / memory 两族……由 `boot/stores.ts`
+ * 各自的 `ensureTiDB*Schema` 腿建)由那条腿自己应用自己的声明 —— 否则这里会对一张还不存在的表发 ALTER。
+ *
+ * 新建库上这批索引早已随 `CREATE TABLE` 的内联 `KEY` 到货 ⇒ `ensureIndex` 的探测全部命中、**零 DDL**。
+ */
+export declare const SCHEMA_INDEXES: readonly IndexSpec[];
 /** Create tables if absent (+ seed the image-bake admission sentinel). Safe to call on every startup.
  *
  *  Per the SCHEMA POLICY on {@link SCHEMA_STATEMENTS} this is a pure CREATE run — there are NO additive

package/dist/plugins/tidb-pool.js

@@ -6,6 +6,21 @@ import { TIDB_LEADER_RUN_STATEMENTS } from "./leader-run-store-sql.js";
 import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
+import { ensureIndexes } from "./ensure-index.js";
+import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
+import { SESSION_INDEXES } from "./pg-session-storage.js";
+import { TOOL_RESULT_INDEXES } from "./tool-result-store-sql.js";
+import { COST_QUOTA_INDEXES } from "./pg-cost-quota.js";
+import { RATE_LIMIT_INDEXES } from "./pg-rate-limiter.js";
+import { OUTCOME_LEDGER_INDEXES } from "./outcome-ledger-sql.js";
+import { IMAGE_INDEX_INDEXES } from "./image-index-sql.js";
+import { IMAGE_BAKE_INDEXES } from "./image-bake-store-sql.js";
+import { APPROVAL_ASK_INDEXES } from "./approval-ask-store-sql.js";
+import { ADOPTION_LOG_INDEXES } from "./adoption-log-sql.js";
+import { PERMISSION_RULE_INDEXES } from "./permission-rule-store-sql.js";
+import { RETENTION_INDEXES } from "./retention-store-sql.js";
+import { LEADER_RUN_INDEXES } from "./leader-run-store-sql.js";
+import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
 export function tidbPoolOptions(tidb) {
     const { host, port, user, password, database, connectionLimit } = tidb;
     const limit = connectionLimit ?? 10;
@@ -670,20 +685,10 @@ export const SCHEMA_STATEMENTS = [
 ];
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
 export async function acquireEnsureSchemaLock(conn, tag = "ensureSchema") {
-    await new Promise((r) => setTimeout(r, Math.floor(Math.random() * 400)));
-    for (let attempt = 0; attempt < 40; attempt++) {
-        try {
-            const [rows] = await conn.query("SELECT GET_LOCK(?, 0) AS got", [ENSURE_SCHEMA_LOCK]);
-            if (Number(rows[0]?.got) === 1)
-                return true;
-        }
-        catch (err) {
-            console.warn(`[${tag}] GET_LOCK('${ENSURE_SCHEMA_LOCK}') attempt ${attempt + 1}/40:`, err?.message ?? err);
-        }
-        await new Promise((r) => setTimeout(r, 100 + Math.min(attempt, 3) * 100 + Math.floor(Math.random() * 150)));
-    }
-    console.warn(`[${tag}] could not acquire '${ENSURE_SCHEMA_LOCK}' after retries`);
-    return false;
+    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}')` });
 }
 export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
     try {
@@ -693,14 +698,32 @@ export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
         console.warn(`[${tag}] RELEASE_LOCK('${ENSURE_SCHEMA_LOCK}') failed (lock auto-frees on connection close):`, err);
     }
 }
+export const SCHEMA_INDEXES = [
+    ...CENTRAL_SCHEMA_INDEXES,
+    ...SESSION_INDEXES,
+    ...TOOL_RESULT_INDEXES,
+    ...COST_QUOTA_INDEXES,
+    ...RATE_LIMIT_INDEXES,
+    ...OUTCOME_LEDGER_INDEXES,
+    ...IMAGE_INDEX_INDEXES,
+    ...IMAGE_BAKE_INDEXES,
+    ...APPROVAL_ASK_INDEXES,
+    ...ADOPTION_LOG_INDEXES,
+    ...PERMISSION_RULE_INDEXES,
+    ...RETENTION_INDEXES,
+    ...LEADER_RUN_INDEXES,
+];
 export async function ensureSchema(pool) {
     const conn = await pool.getConnection();
-    const locked = await acquireEnsureSchemaLock(conn);
+    let locked = false;
     try {
+        await acquireEnsureSchemaLock(conn);
+        locked = true;
         for (const stmt of SCHEMA_STATEMENTS) {
             await conn.query(stmt);
         }
         await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES ('standard')");
+        await ensureIndexes((text, params) => conn.query(text, params), "mysql", SCHEMA_INDEXES);
     }
     finally {
         if (locked)

package/dist/plugins/tool-result-store-sql.d.ts

@@ -2,10 +2,13 @@ import type { ToolResultProvenance, ToolResultStore, ToolResultSlice, ToolResult
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 /** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
  *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
  *  tables, so a self-contained ensureSchema is safe (central pg-pool aggregation is done separately). */
 export declare const PG_TOOL_RESULT_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const TOOL_RESULT_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for the tool_result table (for the integration test to call). */
 export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>;
 /**