@sema-agent/server 7.134.0 → 7.135.0

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

@@ -780,6 +780,10 @@ const OUTCOME_TO_REMOTE_ERROR = {
     transport_lost: "transport_lost",
     unknown: "unknown",
 };
+const DEVICE_FACTORY_CONFIG_CODES = {
+    PLACEMENT_ROOT_INVALID: "config.placement_root_invalid",
+    CWD_INVALID: "config.device_cwd_invalid",
+};
 function deviceFactoryRefusal(code, message) {
     return Object.assign(new Error(message), { code });
 }
@@ -788,7 +792,7 @@ export function deviceExecutionEnvFactory(deps) {
     return async (ctx) => {
         const rootSessionId = ctx.placementRootSessionId;
         if (typeof rootSessionId !== "string" || rootSessionId.length === 0) {
-            throw deviceFactoryRefusal("config.placement_root_invalid", "device lane: ExecutionEnvFactoryContext.placementRootSessionId is empty [config.placement_root_invalid] — " +
+            throw deviceFactoryRefusal(DEVICE_FACTORY_CONFIG_CODES.PLACEMENT_ROOT_INVALID, `device lane: ExecutionEnvFactoryContext.placementRootSessionId is empty [${DEVICE_FACTORY_CONFIG_CODES.PLACEMENT_ROOT_INVALID}] — ` +
                 "the device placement is keyed on the run tree's placement root; defaulting to the child sessionId would read as a NEW placement (v2 §4.3.2 / core design/380 O1①)");
         }
         const binding = await deps.store.getSessionBinding(rootSessionId);
@@ -827,7 +831,7 @@ export function deviceExecutionEnvFactory(deps) {
 export function effectiveDeviceCwd(sessionCwd, parentCwd, row) {
     const [source, cwd] = sessionCwd !== undefined ? ["session cwd", sessionCwd] : parentCwd !== undefined ? ["parent cwd", parentCwd] : ["device workspaceRoot", row.workspaceRoot];
     if (!isDeviceAbsolutePath(cwd)) {
-        throw new Error(`device lane: the effective working directory (${source}) ${JSON.stringify(cwd)} is not an absolute path — every exec / execStream instruction carries an absolute \`cwd\`, ` +
+        throw deviceFactoryRefusal(DEVICE_FACTORY_CONFIG_CODES.CWD_INVALID, `device lane: the effective working directory (${source}) ${JSON.stringify(cwd)} is not an absolute path [${DEVICE_FACTORY_CONFIG_CODES.CWD_INVALID}] — every exec / execStream instruction carries an absolute \`cwd\`, ` +
             "and the executor must never be left to guess a base directory. Fix the source named above (a device's workspaceRoot is fixed at enrollment: enroll again with an absolute path)");
     }
     return cwd;

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

@@ -42,7 +42,7 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
     /** Sandbox lifetime in ms (E2B billing window). Default {@link DEFAULT_TIMEOUT_MS}. */
     timeoutMs?: number;
     /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
+     * [ref]④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
      * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
      * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
      * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
@@ -101,7 +101,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     cwd: string;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
-    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 e2b 沙箱里(模板镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+    /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 e2b 沙箱里(模板镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
     private readonly cfg;
@@ -257,7 +257,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  缺它 ⇒ 合法的悬空链接让整个工具调用失败。必须返回**原始链接目标**(`readlink` 不带 `-f`)。
      *  本腿的文件面也走 `exec`(与 canonicalPath 同通道),所以实现方式与 shell 腿一致。 */
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。本腿的文件面走原生 SDK 的
+    /** [ref] / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。本腿的文件面走原生 SDK 的
      *  `exec`([ref] B6 的既有裁决:host 与 e2b 是原生 API 腿,**不并**进 `posix-shell-fs` 基座),但
      *  「链怎么走、怎么读」与四条 shell 腿**是同一份**:脚本与读法的单一属主在 `remote-shell.ts`,这里只多一行
      *  传输。一次往返、上限 64、只锚不折、遇环即止;`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。

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

@@ -25,7 +25,7 @@ export interface HostEnvConfig {
      */
     env?: Record<string, string>;
     /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
+     * [ref]④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
      * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
      * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
      * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
@@ -66,7 +66,7 @@ export interface HostEnvConfig {
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
     /** [ref] §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
     /**
-     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
      * 就是**命令真正跑的那块文件系统**的权威答案(worker 本机的 `fs.realpath`)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
@@ -94,7 +94,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
     /**
-     * core 7.49.0 #1554:shell 子进程**真拿到的** `CDPATH` 条目(`[]` = 没有)—— 删除守卫按它解裸 `cd <dir>`。本车道的命令就是本机子进程,
+     * core 7.49.0 [ref]:shell 子进程**真拿到的** `CDPATH` 条目(`[]` = 没有)—— 删除守卫按它解裸 `cd <dir>`。本车道的命令就是本机子进程,
      * env 是本类自己组合的(继承姿态 + `cfg.env`),所以说得出:读同一只组合({@link childEnv} 的**读面**,不披露、不钉 shell),切法与 core
      * `NodeExecutionEnv` 同(缺席 / 空串 ⇒ `[]`,否则按 `:` 切)。逐命令的 `options.env` 由引擎自己交,它知道。
      * 🔴 读面**不依赖 shell 落定**:core 判 Bash 的策略链在任何 exec 之前就读它(shell 解析在 exec 路径上才发生),所以这里不能碰
@@ -118,13 +118,13 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core [ref] 同形:写已释放的 inode。)
      *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     private readonly liveFgSpools;
-    /** 🔴 S-539 在飞的 fs **写**登记表(`liveFgSpools` 同律:「还有人在动这棵树,就别删它」)。
+    /** 🔴 [ref] 在飞的 fs **写**登记表(`liveFgSpools` 同律:「还有人在动这棵树,就别删它」)。
      *  为什么按 promise 存而不是计数:只有 promise 才能被 `destroy()` **await**;计数只能轮询。 */
     private readonly inflightFs;
     /** 一次性:慢 drain 只抱怨一次(一条按次数刷屏的 teardown 读数没人会看)。 */
     private inflightFsDrainWarned;
     /**
-     * 🔴 S-539 —— 把一只**会在 workspace / spool 根里建路径或改路径**的 fs 动作登记为「在飞」,直到它 settle。
+     * 🔴 [ref] —— 把一只**会在 workspace / spool 根里建路径或改路径**的 fs 动作登记为「在飞」,直到它 settle。
      *
      * ── 病(旧 `destroy()` 的自称与实情)──────────────────────────────────────────────────────────
      * `destroy()` 只 await 了 `ensurePrepared()` 那只 memo(`preparing`),于是它顶注里的
@@ -150,7 +150,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *    把 destroy 挂死 —— 拿一条新的可用性病换一条不存在的正确性收益。
      * 判据因此是一句话:**「可能建路径或改路径的那些面」进在飞集合**,不是「过了 fsReady 的都进」。
      *
-     * ── 不止文件面(S-541)─────────────────────────────────────────────────────────────────────────
+     * ── 不止文件面([ref])─────────────────────────────────────────────────────────────────────────
      * 判据是「会不会建/改路径」,**不是**「在不在 `env` 的文件面上」。后台 shell 的 `launch`(`makeBgDriver`)
      * 在 spool 根下 `mkdir` 一棵子树,而它整段期间 `bgManager.hasShells()` 还是 false(`shells.set` 在
      * `await launch(ctx)` 之后)⇒ 同一条竞态的另一张脸,同一只集合治。见那处头注。
@@ -162,7 +162,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      * 🔴 两条都不能要,所以有第三条(合并复审 [high] 打出来的):
      *  ① 无界等 —— workspace 里的 FIFO / 特殊文件会让一次 `writeFile` **永不 settle**,而拆除在 run 收尾路径上
      *     ⇒ 整条收尾停摆。用一条新的可用性病换一条正确性收益,不划算。
-     *  ② 到点就照删 —— 把 S-539 的竞态**原样**搬回来(rm 与在飞 mkdir 再次在线程池里赛跑),只是把窗口从
+     *  ② 到点就照删 —— 把 [ref] 的竞态**原样**搬回来(rm 与在飞 mkdir 再次在线程池里赛跑),只是把窗口从
      *     「总是」改成「慢的时候」;一条确定的病换一条间歇的病,更糟。
      *  ③ **到点就不再占着调用方,但 rm 依旧排在那批写之后**(`destroy()` 里的 `void …then(removeOwnedTrees)`)。
      *     次序保证一个字节不松,teardown 变成「有界返回」。teardown 契约(core 1.258.2)禁的是**抛**,不是**慢**;
@@ -254,7 +254,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
     /**
-     * S-745(core 7.32.0 #1107)—— `BackgroundShellCapability.killBackgroundNow` 座位:退出边界 / 会话收敛的**同步硬收**面经它对
+     * [ref](core 7.32.0 [ref])—— `BackgroundShellCapability.killBackgroundNow` 座位:退出边界 / 会话收敛的**同步硬收**面经它对
      * 本 env 的一行发**一枪组 SIGKILL**(pid 不出 env,调用方只握不透明的 shellId)。同步、永不抛、幂等;答 `killed` /
      * `already_gone` / `no_pgid`(win32 恒 `no_pgid`)。从没起过 shell 的 env(`_bgManager` 未建)⇒ 这个 id 不是本 env 的 ⇒
      * `already_gone`;**不**顺手新建 manager(拆除路径上不造东西,与 `disposeBackgroundShells` 同一条)。
@@ -302,10 +302,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
-    /** S-539:整只方法体(**含** `fsReady` 那道门)走 `withInflightFs` —— 登记必须与调用方同一同步段,
+    /** [ref]:整只方法体(**含** `fsReady` 那道门)走 `withInflightFs` —— 登记必须与调用方同一同步段,
      *  否则 destroy 的快照可能刚好在 `await this.fsReady(...)` 的让出点上取完。见那处头注。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
-    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面是唯一能在 `destroyed` **之后**过门的写面
+    /** [ref](写面一律 `withInflightFs`,见那处头注)。本面是唯一能在 `destroyed` **之后**过门的写面
      *  (`lingeringBgWrite`):那一族登记在 destroy 的快照**之后**,所以 destroy 不会去等它们 —— 正确,
      *  它们按设计跨 destroy 存活(等它们等于等后台 shell)。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
@@ -314,7 +314,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     /**
-     * S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。host 腿是 node:fs 腿:走法(对整条拼法 `readlink`、再对每一跳
+     * [ref] / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。host 腿是 node:fs 腿:走法(对整条拼法 `readlink`、再对每一跳
      * `readlink`,**上限**、**只锚不折**、**遇环即止**、win32 宿主上跳到共享(UNC)时**记下该跳并停止探测** —— 不碰网络)是 core 导出的
      * `walkSymlinkChain`,本腿只供它**逐跳的读口**;上限、播种、锚法、UNC 判都在那一只里,本仓不再重写第二遍。
      *
@@ -328,12 +328,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
-    /** S-539(写面一律 `withInflightFs`,见那处头注)。 */
+    /** [ref](写面一律 `withInflightFs`,见那处头注)。 */
     createDir(p: string, options?: {
         recursive?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Result<void, FileError>>;
-    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面**不会**复活目录(`fs.rm` 只删),进在飞集合的理由是
+    /** [ref](写面一律 `withInflightFs`,见那处头注)。本面**不会**复活目录(`fs.rm` 只删),进在飞集合的理由是
      *  同一条:destroy 的 rm 把树从它脚下抽走 ⇒ 一次本该 ok 的删返回 `not_found`。判据是「可能建或改路径」,
      *  不是「可能复活目录」—— 少一条例外就少一处以后要重新想清楚的地方。 */
     remove(p: string, options?: {
@@ -353,10 +353,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);
      *   · ephemeral 形反而更好:`destroy()` 在**有后台 shell 在册**时不删这个根,而 workspace 是会被 rm 的。
      *  ⚠️ 这是 **host-only**:k8s/local-docker 的临时文件必须落在**容器内**可见的 cwd,ssh/e2b 本来就用远端系统 tmp。 */
-    /** S-539(写面一律 `withInflightFs`,见那处头注)。这一面建在 **spool 根**下,而 destroy 也会整树删那个根 ——
+    /** [ref](写面一律 `withInflightFs`,见那处头注)。这一面建在 **spool 根**下,而 destroy 也会整树删那个根 ——
      *  `fs.mkdtemp` 不建父目录,所以它不会复活什么,坏处是一次本该成功的调用返回 `not_found`。 */
     createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /** S-539(写面一律 `withInflightFs`,见那处头注;spool 根同 `createTempDir`)。 */
+    /** [ref](写面一律 `withInflightFs`,见那处头注;spool 根同 `createTempDir`)。 */
     createTempFile(options?: {
         prefix?: string;
         suffix?: string;
@@ -365,7 +365,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     /** Resolve a (possibly relative) path against {@link cwd} like the other adapters. Host paths are platform-native. */
     private resolve;
     /**
-     * S-260 ②:**建之前**先判「我这个用户能不能在那儿建」。
+     * [ref] ②:**建之前**先判「我这个用户能不能在那儿建」。
      *
      * 不判的话,唯一的读数是 `failed to create host workspace …: EACCES: permission denied, mkdir '<随机子目录>'`
      * —— 它说的是那个**随机**子目录建不出来,而真正的事实是**父目录**(`HOST_WORKSPACE_BASE`,缺省

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

@@ -169,7 +169,7 @@ export interface K8sEnvDeps {
 }
 /**
  * One run's space occupant — the space key of both lanes keyed by it (the space lane, the cache volume) — a closed set of three
- * readings of the session row's cell, read by id from the session store (`SessionStore.incarnationOf`) when the run's env is built:
+ * readings of the session row's cell, read by id from the session store (`SessionStore.headOf`) when the run's env is built:
  *  - known: `incarnation` — the partition (`<prefix>/<incarnation>/space/…`): the session OCCUPANT's incarnation token
  *    (`session-incarnation.ts`, the one owner of "is this the same occupant"). Why not the session id: the space lane is read by
  *    whoever runs next in the session, so its partition decides WHO reads — a session id deleted and registered again (by anyone)
@@ -180,7 +180,7 @@ export interface K8sEnvDeps {
  *    (deleted / never registered), or this replica holds no commit fence to key one by (see `occupantOf`) ⇒ a lane keyed by it
  *    does not open (no restore, no save, no volume) and says so in one line;
  *  - faulted: `fault` — the read did not answer (it threw, did not come within the lane's store wall `rpcTimeoutMs` — `incarnation_read_timeout`,
- *    or answered something that is not a token): the code of the store's error (never its text), `incarnation_read_failed` without one. A space we could not read is not "no space" ⇒ a lane keyed by
+ *    or the row it answered carries no occupant token — `session.incarnation_missing`): the code of the store's error (never its text), `incarnation_read_failed` without one. A space we could not read is not "no space" ⇒ a lane keyed by
  *    it refuses this env (`RemoteK8sExecutionEnv.provision`, the one pod seat): the run never starts on a workspace it believes is its own.
  * Never a fallback to the session id.
  */
@@ -203,7 +203,7 @@ export interface ReclaimFailure {
  *  `workspace_cache_reclaim_failed` from the reclaim seat: the delete-by-label failed or answered non-2xx (`delete_failed`), or the reclaim call's
  *  deadline passed before it was sent or while it was in flight (`budget` — the same word the object half's `stage` uses for the same cause). */
 export interface CacheReclaimFailure {
-    readonly reason: Exclude<CacheReclaimReason, "occupant_unreadable">;
+    readonly reason: CacheReclaimReason;
     readonly detail: string;
 }
 /** The control-plane wall of an env built from `config` (`rpcTimeoutMs`) — the one reading: the env's own requests, the commit-fence calls and the
@@ -231,7 +231,7 @@ export { exitCodeFromStatus } from "./k8s-exec-protocol.js";
 export declare const K8S_SANDBOX_NAMESPACE_DEFAULT = "sandboxes";
 export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /**
-     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
      * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,经 pod exec 解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
@@ -271,7 +271,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     get homeDir(): string | undefined;
     /** 家目录的座(声明胜 · 否则 pod 就绪那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证(与 local-docker / ssh 同一只判官、同一句拒)。 */
     private readonly homeSeat;
-    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+    /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
     private readonly cfg;
@@ -551,7 +551,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** The pause before a restore's next attempt (`retry.backoffMs`, the adapter's one retry pause). `false` ⇒ aborted (now or during it). */
     private restorePause;
     /**
-     * `latest` names an archive that is not there (S-1438): one `workspace_latest_dangling{space, key, deleted}` line and the
+     * `latest` names an archive that is not there ([ref]): one `workspace_latest_dangling{space, key, deleted}` line and the
      * pointer is deleted (the next run must not trip on it again); the run continues on the empty workspace. A pointer
      * delete that fails rides on the same line (`deleted: false` + the error) — the next run then says it once more.
      * This env is the space's only writer here (the commit fence admits one per space), so the delete is a plain one.
@@ -701,7 +701,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+    /** [ref] / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
      *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
      *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
@@ -726,7 +726,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  bound for a file op, so the lane liveness bound stays on (a stalled transfer is cut by it); the data bound is this
      *  adapter's own ceiling (`capMs`), not a statement. */
     private execData;
-    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}(S-410:cwd 不可用 ⇒ 命令不跑;
+    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}([ref]:cwd 不可用 ⇒ 命令不跑;
      *  车PL:buffered `exec` 上守卫触发 ⇒ `spawn_error`)。 */
     private workingDirOf;
 }

package/dist/plugins/remote-env-local-docker.d.ts

@@ -71,7 +71,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     cwd: string;
     /** core `ExecutionEnv.homeDir`([ref]):本容器里执行用户的 home —— 声明胜,否则开容器那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
     get homeDir(): string | undefined;
-    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在容器里(镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+    /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在容器里(镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
     private readonly cfg;
@@ -165,7 +165,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+    /** [ref] / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
      *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
      *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;

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

@@ -54,7 +54,7 @@ export interface SshEnvDeps {
 }
 export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     /**
-     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
      * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,在真机上解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
@@ -92,7 +92,7 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private homeChecked?;
     /** 目标机答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每个面原样回它(同一目标机同一登录用户同一答案:不再问、不再发命令)。 */
     private homeRefusal?;
-    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在远端登录 shell 里(目标机的 profile / env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+    /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在远端登录 shell 里(目标机的 profile / env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
     private readonly cfg;
@@ -188,7 +188,7 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private posixFsInst?;
     private get posixFs();
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+    /** [ref] / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
      *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
      *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
@@ -209,7 +209,7 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
-    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}(S-410:cwd 不可用 ⇒ 命令不跑;
+    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}([ref]:cwd 不可用 ⇒ 命令不跑;
      *  车PL:buffered `exec` 上守卫触发 ⇒ `spawn_error`)。 */
     private workingDirOf;
     private connErr;

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

@@ -18,8 +18,8 @@
  *
  * Lanes: e2b/k8s/local-docker = one sandbox per task; ssh = a shared persistent host, where the
  * sessionId-scoped subdir is exactly what keeps sessions apart. adb is NOT a lane (no standard /tmp on
- * Android); host keeps its own worker-local scratchpad — neither is wrapped (main.ts gates on
- * {@link isRemoteScratchpadLane}).
+ * Android); host keeps its own worker-local scratchpad — neither is wrapped (the boot gates on the
+ * deployment-shape row `remoteScratchpad`).
  *
  * Trust: sessionId is minted by us (uuid), but it is caller-adjacent — defence in depth, the path is only
  * built for `[A-Za-z0-9._-]+` ids ({@link remoteScratchpadDirFor}); anything else ⇒ NOT decorated (+warn),
@@ -32,7 +32,6 @@ import type { ExecutionEnvFactory } from "@sema-agent/core";
 export interface RemoteScratchpadLogger {
     warn?(event: string, fields?: Record<string, unknown>): void;
 }
-export declare function isRemoteScratchpadLane(provider: string | undefined): boolean;
 /** THE remote scratchpad path convention: `/tmp/scratchpad/<sessionId>` (raw id — the sandbox is already
  *  session/task-scoped tenancy, no hash segment needed). Returns undefined for an absent/unsafe id — the
  *  single validity rule shared by the factory decorator AND the envFacts advertisement. */

package/dist/plugins/remote-scratchpad.js

@@ -1,8 +1,4 @@
 import { redactHead } from "../observability/run-terminal.js";
-const REMOTE_SCRATCHPAD_LANES = new Set(["e2b", "k8s", "local-docker", "ssh", "device"]);
-export function isRemoteScratchpadLane(provider) {
-    return provider !== undefined && REMOTE_SCRATCHPAD_LANES.has(provider);
-}
 const SESSION_ID_RE = /^[A-Za-z0-9._-]+$/;
 export function remoteScratchpadDirFor(sessionId) {
     if (!sessionId || sessionId === "." || sessionId === ".." || !SESSION_ID_RE.test(sessionId))

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

@@ -25,10 +25,10 @@ export declare function armPipeDestroyGrace(child: ChildProcess): ReturnType<typ
 /** POSIX single-quote a string for safe interpolation into a remote shell command (the only metacharacter
  *  inside '' is ' itself, closed/escaped/reopened). */
 export declare function shellQuote(s: string): string;
-/** S-410:cwd 守卫在**远端**的退出码 —— 包装层自己失败、命令没跑(POSIX 包装工具 `env(1)` / `nohup(1)` / `timeout(1)` 的惯用码;126 / 127 是 shell
+/** [ref]:cwd 守卫在**远端**的退出码 —— 包装层自己失败、命令没跑(POSIX 包装工具 `env(1)` / `nohup(1)` / `timeout(1)` 的惯用码;126 / 127 是 shell
  *  自己的「不可执行 / 找不到」)。buffered `exec` 经 {@link createCwdGuardedCall} 把它收成 `spawn_error`(车PL);命令自己也可能退 125,判别见那只函数。 */
 export declare const CWD_UNAVAILABLE_EXIT = 125;
-/** S-410:cwd 守卫触发时写进 stderr 的那一行的开头(后接 ` [<nonce>]: <目录> (cd failed; command not run)`),也是 `spawn_error` 消息的主句。 */
+/** [ref]:cwd 守卫触发时写进 stderr 的那一行的开头(后接 ` [<nonce>]: <目录> (cd failed; command not run)`),也是 `spawn_error` 消息的主句。 */
 export declare const CWD_UNAVAILABLE_LINE = "sema: working directory unavailable";
 /** 车PL 验修 ②:settled 面上 cd 成功之后、命令之前打到 stderr 的那一行的开头(后接 ` [<同一 nonce>]`)。腿在交出之前把它剥掉。 */
 export declare const CWD_STARTED_LINE = "sema: command started";
@@ -57,7 +57,7 @@ export interface CwdEnvCommand {
  */
 export type CwdGuardFace = "settled" | "raw";
 /**
- * 🔴 S-410(7.103.1)—— 三条远端 shell 腿(ssh / k8s / adb)交给远端 `sh -c` 的那一串**唯一**的组装:进工作目录 →(settled 面)打 started 行 →
+ * 🔴 [ref](7.103.1)—— 三条远端 shell 腿(ssh / k8s / adb)交给远端 `sh -c` 的那一串**唯一**的组装:进工作目录 →(settled 面)打 started 行 →
  * 导出任务 env → 跑命令。各腿只决定 `dir`(自己的缺省 cwd 规则 + 路径绝对化),串的形状只在这里。
  *
  * 形:`cd '<dir>' || { echo '<marker>: <dir> (cd failed; command not run)' >&2; exit 125; }; echo '<started>' >&2; export K='v'; … <command>`
@@ -109,7 +109,7 @@ export interface CwdGuardedCall extends CwdStartedStderrFilter {
  * (<cd 自己的话>)")`。
  *
  * 为什么是 spawn_error:core 的 ExecutionEnv 契约把「命令没跑(死 cwd 在列)」给了它;core 的 Bash 工具只在 `spawn_error` / `shell_unavailable` 上
- * 走死 cwd 诊断(`diagnoseDeadCwd`:目录真没了 ⇒ 复位到任务根、答「reset to <root>; re-run」)。S-410 初版把同一形报成 `{ ok:true, exitCode:125 }`,
+ * 走死 cwd 诊断(`diagnoseDeadCwd`:目录真没了 ⇒ 复位到任务根、答「reset to <root>; re-run」)。[ref] 初版把同一形报成 `{ ok:true, exitCode:125 }`,
  * core 读作命令自己失败 ⇒ cwd 不复位,前缀又挡在模型自救的 `cd` / `mkdir` 前面 ⇒ 本轮后续 Bash 全退 125。host 腿(`remote-env-host.ts` 的
  * `child.on("error")`)本就报 `spawn_error`,四条腿一条规则。
  *
@@ -146,7 +146,7 @@ export declare function numEnvOr(name: string, def: number, min: number): number
  *
  * 🔴 **整条命令包在一个 `{ …; }` 里**,让它**只有一个退出状态**,不依赖调用方加的前缀是什么形。今天三条远端 shell 腿的文件面探针
  *   (本命令经 `PosixShellFs` 发出)**不带 cwd**(车PL 验修 ③:只用绝对路径,不进目录 ⇒ 前面没有 {@link buildCwdEnvCommand} 的守卫前缀);
- *   local-docker 用 `docker exec -w <dir>`,e2b 走 SDK 的 `cwd`,都不拼前缀。S-410 之前三条远端腿给它拼过 `cd <dir> && <命令>`,在那个形下
+ *   local-docker 用 `docker exec -w <dir>`,e2b 走 SDK 的 `cwd`,都不拼前缀。[ref] 之前三条远端腿给它拼过 `cd <dir> && <命令>`,在那个形下
  *   这里连着犯过两次错,记下来是因为它们是**同一个坑的两面**,换任何一种链式前缀都会再来:
  *   · 写成 `command -v … || { …; }`:`||` 与前缀的 `&&` 结成一条链(`cd X && command -v … || { … }`),
  *     **`cd` 失败时跑的是探测的失败臂** —— 报「readlink 不在」而真相是「那个目录没了」,运维去修一个没坏的东西;
@@ -165,7 +165,7 @@ export declare function buildSymlinkChainCommand(absPath: string): string;
  *
  * 三件事**只在这里**做一次(四条 shell 腿 + e2b 共读):
  *  · **环即止** —— 出现重复跳时在**重复的那一跳之前**截断(CC `vr` 的 `d.has(u)` 同律),且 seen 表用
- *    **被寻址的拼法播种**(S-408,core 裁 2026-09-17:契约句「不重复被寻址的拼法」的正解是**起点本身不是一跳**——
+ *    **被寻址的拼法播种**([ref],core 裁 2026-09-17:契约句「不重复被寻址的拼法」的正解是**起点本身不是一跳**——
  *    链视图列的是「从被寻址拼法出发经过的中间拼法」,链绕回起点即结束、起点不再列;成环的事实由终点判决
  *    `canonicalPath`(realpath ELOOP ⇒ unresolvable ⇒ 拒)承担,不由链视图承担)。于是 `a -> b`、`b -> a`,问 `a`,
  *    答 `[b]`,与 core `NodeExecutionEnv.canonicalChain`(`new Set([resolved])` 播种)逐字节同形。此前本族从空表

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

@@ -15,9 +15,9 @@
  *
  * ── 方言差异台账(显式,永不藏进抽象;A12 判据)───────────────────────────────────────────────────
  *   - `?` 占位符 vs `$n`;
- *   - 幂等建行(哨兵形 A,S-127):`ON DUPLICATE KEY UPDATE <pk> = <pk>` vs `ON CONFLICT (…) DO NOTHING`
+ *   - 幂等建行(哨兵形 A,[ref]):`ON DUPLICATE KEY UPDATE <pk> = <pk>` vs `ON CONFLICT (…) DO NOTHING`
  *     —— MySQL 侧刻意**不用** `INSERT IGNORE`:重复键的 IGNORE 取 S 锁,与随后的 `FOR UPDATE` 之间是
- *     S→X 升级,InnoDB 上两并发事务互等即 ER_LOCK_DEADLOCK(B-013);ON DUPLICATE 的重复键取的就是 X;
+ *     S→X 升级,InnoDB 上两并发事务互等即 ER_LOCK_DEADLOCK([ref]);ON DUPLICATE 的重复键取的就是 X;
  *   - upsert:`ON DUPLICATE KEY UPDATE col = VALUES(col)` vs `ON CONFLICT (…) DO UPDATE SET col = EXCLUDED.col`;
  *   - 条件自增:`IF(cond, 0, 1)` vs `CASE WHEN cond THEN 0 ELSE 1 END`(本文件不用 —— 见 `acquire` 顶注:
  *     自增判据在**应用层**算,因为它同时要产出返回给调用方的 token);
@@ -124,9 +124,9 @@ export declare class SqlRetentionLaneStore implements RetentionLaneStore {
      * **本 tick 零写静默跳过**。
      *
      * 事务三步,一步不能省:
-     *  ① 幂等建一条 `expires_at_ms = 0` 的**哨兵行**(形 A,S-127:MySQL `ON DUPLICATE KEY UPDATE
+     *  ① 幂等建一条 `expires_at_ms = 0` 的**哨兵行**(形 A,[ref]:MySQL `ON DUPLICATE KEY UPDATE
      *     singleton = singleton` / PG `ON CONFLICT DO NOTHING`)—— 它永远不会改写一条既存租约(两方言的这
-     *     两个动词都只在缺行时写),且重复键取的是 **X** 锁,与 ② 的 `FOR UPDATE` 同锁模式(B-013:
+     *     两个动词都只在缺行时写),且重复键取的是 **X** 锁,与 ② 的 `FOR UPDATE` 同锁模式([ref]:
      *     `INSERT IGNORE` 在这里取 S 再升 X,InnoDB 上两副本抢租互等直接死锁);
      *  ② `SELECT … FOR UPDATE` —— 行现在必定存在,锁真的拿得到;
      *  ③ 判 + `UPDATE`,同事务提交。

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

@@ -28,7 +28,7 @@
  * ── 方言差异台账(显式,永不藏进抽象;A12 判据)───────────────────────────────────────────────────
  *   - `?` 占位符 vs `$n`;多值集合 MySQL 用 `IN (?,?,…)`、PG 用 `= ANY($n::text[])`(先例:
  *     workflow-run-store-sql 的 reap)
- *   - 幂等建行:哨兵形(形 A,S-127)`ON DUPLICATE KEY UPDATE <pk> = <pk>` vs `ON CONFLICT (…) DO NOTHING`
+ *   - 幂等建行:哨兵形(形 A,[ref])`ON DUPLICATE KEY UPDATE <pk> = <pk>` vs `ON CONFLICT (…) DO NOTHING`
  *     —— 随后有同行 `FOR UPDATE` 的建行**必须**用 ON DUPLICATE(重复键取 X,同锁模式);墓碑那种
  *     「只读 affected 不加锁读」的写点(形 B)才保留 `INSERT IGNORE`
  *   - 级联 DELETE 的 JOIN 形:`DELETE te FROM a te JOIN b …` vs `DELETE FROM a te USING b …`
@@ -92,7 +92,7 @@ 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` 头注。 */
+/** [ref]:本 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 语义不受影响)。 */
@@ -211,10 +211,10 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * 事务**首步**:拿本域的互斥行锁,并读出「这个域是不是冻结中」(§5 F2 承重)。
      *
      * 两步,缺一不可:
-     *  ① 幂等建一条 `held = 0` 的**哨兵行**(形 A,S-127:MySQL `ON DUPLICATE KEY UPDATE domain = domain` /
+     *  ① 幂等建一条 `held = 0` 的**哨兵行**(形 A,[ref]:MySQL `ON DUPLICATE KEY UPDATE domain = domain` /
      *     PG `ON CONFLICT DO NOTHING`)—— 它永远不会改写一条既存的 hold(两方言的这两个动词都只在缺行时
      *     写),只保证**接下来那把行锁有东西可锁**;重复键取的是 **X** 锁,与 ② 的 `FOR UPDATE` 同锁模式
-     *     (`INSERT IGNORE` 在这里取 S 再升 X = InnoDB 上两个并发 sweep 互等的死锁形,B-013);
+     *     (`INSERT IGNORE` 在这里取 S 再升 X = InnoDB 上两个并发 sweep 互等的死锁形,[ref]);
      *  ② `SELECT held … FOR UPDATE` —— 现在这行必定存在,于是锁真的拿到了。
      *
      * 🔴 为什么必须先造行(codex 交叉复审 R1-[high],验真后改):`FOR UPDATE` 锁不住缺席行(TiDB 无 gap

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

@@ -26,7 +26,7 @@ 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` 头注。 */
+/** [ref]:本 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 {

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

@@ -121,7 +121,7 @@ export declare class SqlRunStore {
      * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a
      * terminal state or the reaper expires it.
      *
-     * 🔴 S-173:park 也落 `result` 列 —— 存的是**摘掉恢复凭据、脱过敏的投影**(`sealRunRowResult`,与 `setTerminal`
+     * 🔴 [ref]:park 也落 `result` 列 —— 存的是**摘掉恢复凭据、脱过敏的投影**(`sealRunRowResult`,与 `setTerminal`
      * 同一只入口、同列同序列化),不是引擎交出的原件:`paused.token` / `failed.nestedPause.token` 两座在落列前摘掉,
      * 所以 poll 这一行的调用方(`GET /v1/runs/:id → result`)拿到的是「停在哪扇门上」而拿不到 resume 能力。
      * `result = null` = 这条腿没观察到 park 结果(断连竞态 / 重开 re-park),列写空 —— 与修前行形同。
@@ -175,7 +175,7 @@ export declare class SqlRunStore {
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** Shared row→record mapper — byte-identical between dialects (both drivers hand back the same column
      *  names + comparable JS types after SqlDriver's result normalization).
-     *  🔴 **读它的每一条查询都必须选 {@link runRowCols}**(S-230):映射器对「没被 SELECT 的列」是
+     *  🔴 **读它的每一条查询都必须选 {@link runRowCols}**([ref]):映射器对「没被 SELECT 的列」是
      *  结构性失明的 —— `undefined ?? null` 与 `Boolean(undefined)` 都会安静地铸出一个**看上去合法的假值**。
      *  修前 `listRuns` 的两条方言臂就漏选 `instance_id`,于是列表面的每一行 `instanceId` 恒 `null`
      *  (今天没有消费点,所以没人发现)。列表收成一个常量 = 这类漏选从此不可能发生。 */
@@ -208,7 +208,7 @@ export declare class SqlRunStore {
      *  the very placeholder-numbering divergence this file exists to keep visible. */
     listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
-     * S-297 —— 这个会话**最近一条腿**的窄指针(`/mcp` 面板的 `lastLegMcp` 与任何「上一条 run 是谁」的读面共用)。
+     * [ref] —— 这个会话**最近一条腿**的窄指针(`/mcp` 面板的 `lastLegMcp` 与任何「上一条 run 是谁」的读面共用)。
      *
      * 排序口径与 {@link listSessions} 的 `rn=1` 窗函数**逐字同一句**(`created_at DESC, task_id DESC`)——
      * 两处答的是同一个问题「哪一条是最新的」,口径分叉会让列表面的 `lastRunId` 与本读口指向不同的 run。
@@ -252,12 +252,12 @@ export declare class SqlRunStore {
      * 那批,具名那批连同它们的 task_event 全部存活 —— 而 `session_meta` 已经删了,留存腿的 sessionCandidates
      * 再也枚举不到这棵树 ⇒ 孤儿行**没有任何清理路径**,路由却回 `{deleted:true}`。那就是一次**报成成功的
      * 右删失效**(anchors 腿的注逐字写着这句)。删除决策的属主门在**路由层**(DELETE /v1/sessions/:id 先
-     * `ownerOf` 再比对 scope,fleet-wide 臂同门),本方法的唯一生产调用点是那条路由后面的 purge 协调器。
+     * 经会话店唯一的按 id 读 `headOf` 取属主再比对 scope,fleet-wide 臂同门),本方法的唯一生产调用点是那条路由后面的 purge 协调器。
      *
      * 🔴 **化身围栏**(`expectedSessionOwner`;codex 交叉复审 R1-[high],验真后修)—— 属主门下来了,但会话
      * **身份**必须在同一个事务里重新确认。会话 id 由调用方自选、且删除之后**可被别人重新登记**
      * (`register` 是 INSERT … ON DUPLICATE KEY / ON CONFLICT,老行没了就是一条新行,新 owner):于是
-     * 「路由 `ownerOf` 已验权」这句话在两只并发 purge 交错时会过期 —— A 与 A' 同时通过属主门,A' 跑完整条
+     * 「路由已按 `headOf` 读到的属主验权」这句话在两只并发 purge 交错时会过期 —— A 与 A' 同时通过属主门,A' 跑完整条
      * purge 把 meta 删掉,租户 B 用同一个 uuid 重新登记并跑完一次 run,慢半拍的 A 才走到这里 ⇒ 按 session_id
      * 单键删就把 **B 的**行删了(修前的行级属主门恰好挡住这一形,因为 B 的行 owner≠A 的会话主)。
      * ⇒ 事务头部 `SELECT owner FROM session_meta WHERE session_id = ? FOR UPDATE`,行不在或 owner 与路由验过的
@@ -304,7 +304,7 @@ export declare class SqlRunStore {
     }>;
     /** Earliest retained event seq for a task (0 if none) → the `retainedFrom` field of `GET /v1/tasks/:id/turns`.
      *  Not an eviction boundary: the ledger has no partial head trim (the only deletion takes the whole session tree),
-     *  so a value > 1 means head rows whose write failed after consuming their seq (S-211 ①). */
+     *  so a value > 1 means head rows whose write failed after consuming their seq ([ref] ①). */
     retainedFrom(taskId: string): Promise<number>;
     /** Events with seq strictly greater than `afterSeq` (use 0 for the whole stream). */
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;
@@ -348,9 +348,9 @@ export declare class SqlRunStore {
      *
      * Same alias-qualification divergence as {@link reapSuspended} — see its header note.
      *
-     * S-173:两条收割腿都把 `result` 列写回 NULL —— park 行上那份 park 结果(`terminal.kind:"paused"`)说的是
+     * [ref]:两条收割腿都把 `result` 列写回 NULL —— park 行上那份 park 结果(`terminal.kind:"paused"`)说的是
      * 「停在门上」,而这一刻行被打成 `failed`/`approval.expired`;留着它 = 一行两句互相矛盾的话(读面还会从它
-     * 投出 `review.pending` 之类的 park 码)。收割后的行形因此与 S-173 之前逐字同(结果空,码在 error_code 列)。
+     * 投出 `review.pending` 之类的 park 码)。收割后的行形因此与 [ref] 之前逐字同(结果空,码在 error_code 列)。
      */
     failSuspendedWithExpiredCheckpoint(): Promise<number>;
 }

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

@@ -1,5 +1,5 @@
 /**
- * **启动期「库 ≟ 代码」列集对账探针**(S-547)—— 存量库缺列/多列一律**响亮拒启**。
+ * **启动期「库 ≟ 代码」列集对账探针**([ref])—— 存量库缺列/多列一律**响亮拒启**。
  *
  * ── 病(test T-47 三库一致的真读数)───────────────────────────────────────────────────────────────
  * 7.91.2 建的 `session_policy`(那时还没有 `gen` 列)+ 一行数据,7.92.0 的二进制接上去:`CREATE TABLE
@@ -44,7 +44,7 @@
  * (探针先于它的第一条 CREATE)—— 一次会拒的起服不许先在库里建出几十张本版新表(`task_run` 还带着新列),否则拒句里「没动过库」就是假话,
  * 按拒句指路去 7.125.x 起服的人会撞上「库比 7.125.x 新」的第二道拒。嵌入方走公开序列 `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
  * 即得到这一问,零动作。
- * 残余(如实):运维在第一次起带迁移的版本之前就把两件退役 schema 都手工删掉的库,残留的旧拼法由门记录的读腿接住 —— 7.129.0 起(core 7.51.0 #1731)
+ * 残余(如实):运维在第一次起带迁移的版本之前就把两件退役 schema 都手工删掉的库,残留的旧拼法由门记录的读腿接住 —— 7.129.0 起(core 7.51.0 [ref])
  * 那只读腿按 core 的档案读法读,`unresolvable` 是 core 退役词注册表里的词 ⇒ 记录原词原样读回、不改写(`trace/project.ts` `screenedGate`);local 文件车道
  * 没有表与列,没有这一问 —— 引擎 File 店里已决 checkpoint 的记录按契约物理不可变,本仓没有合法缝改写它们,同由那条读腿接住。
  */

package/dist/plugins/schema-ensure-legs.d.ts

@@ -5,7 +5,7 @@ export type SchemaDialect = "mysql" | "pg";
 export declare const LOCK_RE: RegExp;
 /**
  * **「一个新库对 ensure 探针怎么答」的唯一属主**(合并复审 车HB 后收口:此前生成器录制器、`test/ensure-schema.test.ts`
- * 的假池、`test/schema-baseline-generated.test.ts` ③c 的假驱动各抄一份,S-287 加了索引探针 + PG 锁改 `got === true`
+ * 的假池、`test/schema-baseline-generated.test.ts` ③c 的假驱动各抄一份,[ref] 加了索引探针 + PG 锁改 `got === true`
  * 之后三份各漂一处 —— 假池答零行诱发 68 条 ALTER、③c 答 `got: 1` 让 PG 锁永远拿不到)。
  * 返回 `undefined` = 不是探针,由调用方录制 / 执行;三条例外的理由见上面三条正则的注。
  */
@@ -18,7 +18,7 @@ export declare function answerEnsureProbe(text: string): {
  * (`scripts/db-lane-warm.ts` 的按车分库暖库)实现同一组签名 ⇒ {@link MYSQL_LEGS} / {@link PG_LEGS} 是这
  * 两条用途的**单源**:加一条 boot ensure 腿只改那两个数组一处,基线生成与车道库暖库同时跟上。
  *
- * 为什么必须单源(S-285/S-256/S-343 真案):暖库此前手抄了「中央两条」(`ensureSchema`/`ensurePgSchema`),
+ * 为什么必须单源([ref]/[ref]/[ref] 真案):暖库此前手抄了「中央两条」(`ensureSchema`/`ensurePgSchema`),
  * 其余 per-store 腿(现值 mysql 10 / pg 11)在**新建的**车道库上从没被建过 ⇒ 新车道首跑几十格红,而发车机那只老库因为历史上
  * 被跑过一次就有表,于是这个缺口在老库上**恒绿**。两张手抄清单迟早分叉,正是本仓反复吃的亏。
  */
@@ -36,7 +36,7 @@ export interface EnsureDriver {
  * 就是这么漏掉一整张表的 —— 那种漏在两条方言上**同时**发生,判据 ④ 的方言对拍完美对称 ⇒ 永不报警)。
  * ⇒ 遍历与自报清单必须同一份数组,否则清单会自己腐掉,对账就成了自说自话。
  *
- * 第三个消费方(S-285/S-256/S-343):`scripts/db-lane-warm.ts` 拿**同一份数组**对真库跑一遍 ⇒ 按车分库的
+ * 第三个消费方([ref]/[ref]/[ref]):`scripts/db-lane-warm.ts` 拿**同一份数组**对真库跑一遍 ⇒ 按车分库的
  * 新库与生产 boot 建出同一套表。判据 ③c 钉住「warm 跑过的腿名 == 本清单」,任何人把它抄成第二份就当场红。
  */
 export interface EnsureLeg {

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

@@ -1,6 +1,6 @@
 /**
  * 中央 schema(`tidb-pool.ts` 的 `SCHEMA_STATEMENTS` ⇄ `pg-pool.ts` 的 `PG_SCHEMA_STATEMENTS` 这一对孪生)
- * 所拥有的那批表的索引**声明** —— S-287,两方言**共用同一份**。
+ * 所拥有的那批表的索引**声明** —— [ref],两方言**共用同一份**。
  *
  * ## 为什么自成一个模块
  * 两只池各自 `import` 了自己的驱动(`mysql2/promise` / `pg`,都是**值**导入)。若把这份声明放进其中一只,

package/dist/plugins/schema-live-columns.d.ts

@@ -1,5 +1,5 @@
 /**
- * 库里**实际**的列集 —— 唯一读者(S-547 列册探针 `schema-consistency.ts` 的对账读它;`ensure-index.ts` 的索引补建在失败之后判「是不是这张表
+ * 库里**实际**的列集 —— 唯一读者([ref] 列册探针 `schema-consistency.ts` 的对账读它;`ensure-index.ts` 的索引补建在失败之后判「是不是这张表
  * 缺这条索引的列」也读它)。叶子模块:不值依赖任何模块(列册探针那边经录制驱动 / 建表腿值依赖 `ensure-index.ts`,读者若住在那边,
  * `ensure-index.ts` 读它就是一个运行时环)。方言词是 `ensure-index.ts` 的闭集(类型边,擦除)。
  */