@sema-agent/server 7.52.0 → 7.53.0

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

@@ -4,18 +4,52 @@ import { CheckpointError, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendi
 import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema } from "../approval-card.js";
 import { parseJsonStrict as parseJson } from "./sql-row-helpers.js";
-import { createLogger } from "../observability/logger.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
-import { isDupKeyError } from "./sql-errors.js";
+import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
-const fingerprintLogger = createLogger();
+import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
+export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const MAX_TOOL_INPUT_CHARS = 8192;
 export const TERMINAL_BACKSTOP_MS = Math.max(60_000, (Number.isFinite(Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS)) ? Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) : 0) || 30 * 86_400_000);
 export const TERMINAL_GRACE_MS = 3_600_000;
 export function tokenFingerprint(token) {
     return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
 }
+const GATE_KIND_IS_LIVE_RUN_PARK = {
+    human: true,
+    irreversible_ask: true,
+    resource_limit: true,
+    needs_review: true,
+    plan_review: true,
+    task_done: false,
+};
+export const LIVE_RUN_GATE_KINDS = Object.keys(GATE_KIND_IS_LIVE_RUN_PARK).filter((k) => GATE_KIND_IS_LIVE_RUN_PARK[k]);
+export const TERMINAL_PARK_GATE_KINDS = Object.keys(GATE_KIND_IS_LIVE_RUN_PARK).filter((k) => !GATE_KIND_IS_LIVE_RUN_PARK[k]);
+export function pendingRowPrecedes(a, b, pick) {
+    if (pick === "oldest")
+        return a.createdAt < b.createdAt || (a.createdAt === b.createdAt && a.token < b.token);
+    return a.createdAt > b.createdAt || (a.createdAt === b.createdAt && a.token > b.token);
+}
+export async function assertCheckpointBidiColumnSchema(query, dialect) {
+    try {
+        await query("SELECT has_bidi_controls FROM checkpoint WHERE 1=0");
+    }
+    catch (err) {
+        if (!isMissingColumnError(err, dialect))
+            throw err;
+        throw new Error("checkpoint is missing the S-30 bidi-presence column (has_bidi_controls) — refusing to start. " +
+            "The park-mint write (put) and the operator-queue reads (GET /v1/approvals, /v1/approvals/stream) name the column " +
+            "unconditionally, so on this table every durable suspend fails at first park and every queue poll 500s — at runtime, " +
+            "after a healthy-looking boot. This repository ships no ALTER TABLE migrations, so the table must be recreated: run " +
+            "`DROP TABLE checkpoint;` on the " +
+            (dialect === "pg" ? "PostgreSQL" : "MySQL-protocol") +
+            " backend and restart — the schema is recreated at boot. The cost is bounded but real: the table holds IN-FLIGHT " +
+            "durable parks (suspended approvals/reviews awaiting a decision) — those cards are lost and their runs must be " +
+            "re-triggered; `checkpoint_ctx`, run rows and every other persistent face are untouched. " +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 const MAX_RULE_OFFER_SCAN = 32;
 function preboundBatchMembers(item) {
     if (typeof item !== "object" || item === null)
@@ -81,26 +115,6 @@ export function boundedToolInput(args) {
         return { truncated: true, bytes: json.length };
     return redacted;
 }
-function canonicalFingerprintJson(v) {
-    if (v === null || typeof v !== "object")
-        return JSON.stringify(v) ?? "null";
-    if (Array.isArray(v))
-        return `[${v.map(canonicalFingerprintJson).join(",")}]`;
-    const entries = Object.entries(v)
-        .filter(([, val]) => val !== undefined)
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${canonicalFingerprintJson(val)}`).join(",")}}`;
-}
-export function approvalPayloadFingerprint(v) {
-    try {
-        const fp = canonicalFingerprintJson([v.updatedInput ?? null, v.answer ?? null, v.reason ?? null]);
-        return fp;
-    }
-    catch (e) {
-        fingerprintLogger.warn("approval decision payload is not serializable — idempotent replay refused", { error: e instanceof Error ? e.message : String(e) });
-        return null;
-    }
-}
 export const DECIDED_REPLAY_SCAN_CAP = 8;
 export function approvalDecisionOfWinner(winner, boundCallId) {
     if (winner === undefined)
@@ -261,15 +275,42 @@ export class SqlCheckpointStore {
     isDupKey(e) {
         return isDupKeyError(this.db.dialect, e);
     }
+    ph(n) {
+        return this.db.dialect === "tidb" ? "?" : `$${n}`;
+    }
+    pendingRowQuery(select, sessionId, scope, binding) {
+        const params = [sessionId];
+        const where = [`session_id=${this.ph(1)}`, "status='pending'"];
+        if (scope !== undefined) {
+            params.push(scope);
+            where.push(`scope=${this.ph(params.length)}`);
+        }
+        const kinds = binding?.gateKinds;
+        if (kinds !== undefined) {
+            if (kinds.length === 0) {
+                where.push("1=0");
+            }
+            else {
+                const slots = kinds.map((k) => {
+                    params.push(k);
+                    return this.ph(params.length);
+                });
+                where.push(`gate_kind IN (${slots.join(",")})`);
+            }
+        }
+        const dir = binding?.pick === "oldest" ? "ASC" : "DESC";
+        return { sql: `SELECT ${select} FROM checkpoint WHERE ${where.join(" AND ")} ORDER BY created_at_ms ${dir}, token ${dir} LIMIT 1`, params };
+    }
     async put(token, cp) {
         const pa = cp.pendingAction;
         const version = checkpointVersionOf(cp);
         const toolInput = boundedToolInput(pa?.args);
         const ruleOffers = boundedRuleOffers(pa?.ruleOffers);
+        const hasBidiControls = pa?.hasBidiControls === true ? 1 : null;
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor, rule_suggestions) " +
-                "VALUES (?,?,?,?,'pending',?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor, rule_suggestions) " +
-                "VALUES ($1,$2,$3,$4,'pending',$5,$6,$7::jsonb,$8::jsonb,$9,$10,$11,$12,$13,$14,$15)"), [
+            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls) " +
+                "VALUES (?,?,?,?,'pending',?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls) " +
+                "VALUES ($1,$2,$3,$4,'pending',$5,$6,$7::jsonb,$8::jsonb,$9,$10,$11,$12,$13,$14,$15,$16)"), [
                 token,
                 cp.scope,
                 cp.sessionId,
@@ -285,6 +326,7 @@ export class SqlCheckpointStore {
                 pa?.boundInputHash ?? null,
                 ((g) => (g?.riskDescriptor ? this.json(g.riskDescriptor, "risk descriptor") : null))(cp.gate),
                 ruleOffers === undefined ? null : this.json(ruleOffers, "rule offers"),
+                hasBidiControls,
             ]);
         }
         catch (e) {
@@ -389,7 +431,7 @@ export class SqlCheckpointStore {
         return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
     }
     async listPending(scope) {
-        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.rule_suggestions, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id " +
+        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.rule_suggestions, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id " +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
@@ -413,6 +455,7 @@ export class SqlCheckpointStore {
                 deadline: r.deadline == null ? null : Number(r.deadline),
                 riskDescriptor: readRiskDescriptorCell(r.risk_descriptor),
                 ...(ruleOffers !== undefined ? { ruleOffers } : {}),
+                ...(Number(r.has_bidi_controls) === 1 ? { hasBidiControls: true } : {}),
             };
         });
         return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
@@ -429,10 +472,9 @@ export class SqlCheckpointStore {
         }
         return out;
     }
-    async findPendingTokenBySession(sessionId, scope) {
-        const { rows } = scope
-            ? await this.db.query(this.q("SELECT token FROM checkpoint WHERE session_id=? AND scope=? AND status='pending' LIMIT 1", "SELECT token FROM checkpoint WHERE session_id=$1 AND scope=$2 AND status='pending' LIMIT 1"), [sessionId, scope])
-            : await this.db.query(this.q("SELECT token FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT token FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
+    async findPendingTokenBySession(sessionId, scope, binding) {
+        const { sql, params } = this.pendingRowQuery("token", sessionId, scope || undefined, binding);
+        const { rows } = await this.db.query(sql, params);
         return rows[0] ? String(rows[0].token) : null;
     }
     async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
@@ -494,8 +536,9 @@ export class SqlCheckpointStore {
             };
         });
     }
-    async peekPendingScope(sessionId) {
-        const { rows } = await this.db.query(this.q("SELECT scope FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT scope FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
+    async peekPendingScope(sessionId, binding) {
+        const { sql, params } = this.pendingRowQuery("scope", sessionId, undefined, binding);
+        const { rows } = await this.db.query(sql, params);
         if (!rows[0])
             return undefined;
         return rows[0].scope ?? null;

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

@@ -1,6 +1,6 @@
 /**
  * device lane 四表持久层(design/device-executor-lane-v2 §6)—— `DeviceStore` 双方言实现
- * (`TiDBDeviceStore` / `PgDeviceStore`,SINGLE-FILE DUAL-DIALECT,design/158 A12 形:一个
+ * (`TiDBDeviceStore` / `PgDeviceStore`,SINGLE-FILE DUAL-DIALECT,[ref] A12 形:一个
  * `SqlDeviceStore` 接 `SqlDriver`,两个薄 ctor 子类落方言绑定)。语义真源 = `../device-store.js`
  * (类型 + 闭集 + InMemory 参照实现),准入链 = `../device-enrollment.js`。
  *
@@ -27,7 +27,8 @@
  *   - `INSERT IGNORE` vs `ON CONFLICT (pk) DO NOTHING`(`bindSession` 的首绑 CAS)。
  *   - `AUTO_INCREMENT` vs `BIGSERIAL`;`JSON` vs `JSONB`(+ `$n::jsonb` 显式 cast)。
  *   - `KEY …` 内联 vs 独立 `CREATE INDEX IF NOT EXISTS`。
- *   - 回读名单:PG 用 `UPDATE … RETURNING`,TiDB 无 RETURNING ⇒ 同事务 `UPDATE` 后 `SELECT`。
+ *   - 回读名单:两方言**同走**同事务 `UPDATE` 后 `SELECT`(PG 本可用 RETURNING,为保单一读路径不用——
+ *     见世代回读行注;本文件现行 SQL 零 RETURNING)。
  *   - 时长运算:`NOW(3) + INTERVAL ? SECOND` vs `now() + ($n::double precision * INTERVAL '1 second')`。
  *   - 键列字节等价:MySQL `VARBINARY` vs PG `VARCHAR … COLLATE "C"`(理由见 ../device-store.ts 头注;
  *     `utf8mb4_bin` **不够**,它仍是 PAD SPACE collation)。
@@ -48,7 +49,7 @@ import { type AcquireConnectionInput, type AcquireConnectionResult, type AppendA
  * ── 命名(**落库一律单数**,与设计稿的复数形不同)──────────────────────────────────────────────────
  * design v2 §6 的 DDL 写的是 `devices` / `device_sessions` / `device_enrollment_tokens`(复数),但本仓有一条
  * 常驻机器门:`test/schema-naming-invariants.test.ts` 判据① —— 建表的表名必须在 `TABLE_VOCABULARY` 闭集里
- * **且词表全是单数形**。#270 车1 的 `retention_hold` / `retention_tombstone` 是同一处先例(那份设计稿同样
+ * **且词表全是单数形**。[ref] 车1 的 `retention_hold` / `retention_tombstone` 是同一处先例(那份设计稿同样
  * 写的复数,落库单数)。所以四张表落库名为 `device` / `device_session` / `device_enroll_token` /
  * `device_audit`,**表结构与设计稿逐列一致**,只有名字随仓规。新表 = 先进词表再建。
  */

package/dist/plugins/e2b-orphan-reclaim.d.ts

@@ -1,5 +1,5 @@
 /**
- * #242([3738] / design/242 v1)— E2B 孤儿沙盒回收。
+ * [ref]([ref] / [ref] v1)— E2B 孤儿沙盒回收。
  *
  * 病:server 进程崩溃(SIGKILL/OOM)后 core Runner 的 `destroy()` 不跑,E2B 沙盒按自己的
  * timeout 窗继续存活计费;崩溃循环下泄漏累积。create 侧的归属打标早已在
@@ -13,13 +13,13 @@
  *   c. run 行在场:
  *        LIVE 词(running/suspended/needs_review)→ 活,跳过;
  *        TERMINAL 词                           → 孤儿,kill;
- *        两表皆不中的词                        → 词表纪律(#157):不杀 + failOpen(新词先安全后收编)。
+ *        两表皆不中的词                        → 词表纪律([ref]):不杀 + failOpen(新词先安全后收编)。
  *   d. 行不存在:
  *        startedAt 距今 < GRACE                → create→行落库窗口,跳过(防误杀新沙盒);
  *        ≥ GRACE                              → 真孤儿,kill(单库 fleet 方向下行跨副本可见)。
  *   e. `getRun` 抛错                          → 不杀 + failOpen(不知道 ≠ 孤儿)。
  *
- * v1 边界(design/242 §设计②,发车说明同步):跨部署**异库**共用一把 E2B key 的形不支持——
+ * v1 边界([ref] §设计②,发车说明同步):跨部署**异库**共用一把 E2B key 的形不支持——
  * 别家沙盒的 taskId 在本库查不到行,超 GRACE 会被误杀;前置=每部署独立 E2B key(本就是推荐姿势)。
  * metadata 无跨重启稳定的部署标识可用(instanceId 每 boot 变,恰是要回收上一世代)是结构原因。
  *

package/dist/plugins/file-history-store-sql.d.ts

@@ -9,7 +9,7 @@ export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
  *  two domains' objects disjoint so neither sweep can see the other's keys). */
 export declare const FILE_HISTORY_BLOB_KEY_PREFIX = "file-history/";
 /**
- * S-15 twin 保留条款(core 7.0.0 design/381 §片2 的 SQL 孪生)—— 构造期旋钮,键形与 core 内置后端
+ * [ref] twin 保留条款(core 7.0.0 [ref] §片2 的 SQL 孪生)—— 构造期旋钮,键形与 core 内置后端
  * `FileFileHistoryStoreOptions.retention` / `FileStorageBackendOptions.fileHistory.retention` **同域同名**。
  * 解析与校验**直调** core 的 `resolveFileHistoryRetention`(缺省 100 / `"unbounded"` 唯一不剪拼法 / 坏值
  * 同码 `config.retention_policy_invalid` 响亮拒),本店零第二套语义。
@@ -33,7 +33,7 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** §10 S-6 in-process lease state (design v1 D2: NOT persisted). Keys = `${scope}\x00${entryId}`. */
     private readonly spentAttempts;
     private readonly activeAttempts;
-    /** S-15 twin 保留条款:每 scope 存活的最新 boundary 数;`null` = `"unbounded"`(自剪关闭,GC 归宿主 `reap`)。
+    /** [ref] twin 保留条款:每 scope 存活的最新 boundary 数;`null` = `"unbounded"`(自剪关闭,GC 归宿主 `reap`)。
      *  由 core 的 `resolveFileHistoryRetention` 在构造期裁定 —— 与两只内置后端同一道门、同一句拒绝。 */
     private readonly boundaryKeep;
     constructor(db: SqlDriver, 
@@ -76,18 +76,19 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     }): Promise<FileHistoryResult>;
     private loadTracked;
     private loadVersions;
-    /** S-15 twin 保留条款:这个 entry 的键是否**已花掉**(被 reap 剪过)。台账 `file_history_reaped_entry`。
+    /** [ref] twin 保留条款:这个 entry 的键是否**已花掉**(被 reap 剪过)。台账 `file_history_reaped_entry`。
      *  `forUpdate`(r3-①连带):发布 tx 内的复核必须是**锁定读**——TiDB 悲观事务的普通 SELECT 按文档读
      *  start_ts,锁等待窗内提交的墓碑会被漏看(池上的预检无此虑:单语句即当前)。 */
     private entryReaped;
     /** adoptScope 的台账携带(InMemory 参照:正常臂 = 源∪目标,空源臂也带)。目标已有的行原样保留。 */
     private copyReapedEntries;
     /**
-     * S-15 twin 保留条款 —— boundary 提交后的自剪 pass(core InMemory `applyBoundaryRetention` 的 SQL 形)。
+     * [ref] twin 保留条款 —— boundary 提交后的自剪 pass(core InMemory `applyBoundaryRetention` 的 SQL 形)。
      *
      * 选择半场**共享** core 的 `fileHistoryBoundariesToKeep`(两只内置后端与本孪生不许在「哪个 boundary 死」上
-     * 分家;刚提交者恒 pin):本店的 oldest-first 序 = `published_at_ms, entry_id`(发布戳来自各副本 `Date.now()`,
-     * 同毫秒/时钟回拨用 entry_id 破平 —— 引擎铸的 uuidv7 即提交序;core 明写这只影响「剪哪一个同样合法的
+     * 分家;刚提交者恒 pin):本店的 oldest-first 序 = `publish_seq`(发布时在 scope 锁下按 MAX+1 分配,
+     * UNIQUE(scope, publish_seq) 兜底——严格全序,无破平之需;`published_at_ms` 走数据库钟且已降为信息位,
+     * 见 boundary 发布段行注;core 明写序只影响「剪哪一个同样合法的
      * boundary」,pin 保证永远不会剪掉本轮的)。`null` = 未超界 ⇒ 零 reap,一轮只付一次 SELECT。
      *
      * 在**提交之后、连接归还之后**跑(reap 自取第二条连接与 scope 锁):自剪失败不失败本轮 —— boundary 已
@@ -130,7 +131,7 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      *  path). Also the overwrite-dst session-sync wipe seam (import requires an EMPTY target graph). */
     deleteBySession(scope: string): Promise<number>;
     /** Async byte-GC: blobs referenced by NO version row (any scope), past the created_at grace window.
-     *  Domain-isolated by construction (this store's blob table only — S-15 D1). Reaper-driven. */
+     *  Domain-isolated by construction (this store's blob table only — [ref] D1). Reaper-driven. */
     sweepOrphanBlobs(): Promise<number>;
     /** Upload ONE content-addressed blob ahead of an importHistory (§5 streamed negotiation). Store-level
      *  integrity re-check (the route pre-verifies too — the internal caller might not). Never-throw. */
@@ -153,7 +154,7 @@ export declare class PgFileHistoryStore extends SqlFileHistoryStore {
     constructor(pool: PgPool, blobBackend?: BlobBackend, opts?: SqlFileHistoryStoreOptions);
 }
 /**
- * S-15 D1② — A7-recipe upgrade precondition assert (**refuse to start**, never a warn; the form and
+ * [ref] D1② — A7-recipe upgrade precondition assert (**refuse to start**, never a warn; the form and
  * rationale follow `assertPermissionRuleTicketSchema` verbatim: this repo ships no ALTER TABLE, and
  * `CREATE TABLE IF NOT EXISTS` is a no-op on an existing table whose columns predate this build).
  *

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

@@ -22,11 +22,11 @@
  * An in-memory INDEX (the same Maps MemoryRunStore holds) is hydrated on construction by scanning each runs/<taskId>/
  * run.json + the active claim files — so listRuns/listSessions/getActiveTaskId are O(in-mem) with byte-identical keyset sort to the SQL/Memory
  * twins. Every write touches BOTH the disk and the index on one path. Single-process (the FileStorageBackend boot lock
- * guarantees one writer per data dir), so there is no per-op lock — with ONE exception: #213's claim acquisition
+ * guarantees one writer per data dir), so there is no per-op lock — with ONE exception: [ref]'s claim acquisition
  * (`withClaimLock`) runs under a per-session in-process critical section, because judging a claim stale involves
  * awaits (the checkpoint probe) and the claim + run row must commit as one unit (the SQL twin's transaction). The
  * checkpoint-coupled suspended-run reapers run
- * off an injected {@link RunStoreCheckpointProbe} ([868]; wired by the local backend where checkpoint + run store
+ * off an injected {@link RunStoreCheckpointProbe} ([ref]; wired by the local backend where checkpoint + run store
  * share one root) and degrade to honest no-ops when the probe is absent — exactly like MemoryRunStore.
  */
 import { type UsageRow } from "../usage-analytics.js";
@@ -35,7 +35,7 @@ import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 /**
- * `RUN_STORE_STRICT_HYDRATE=on` 下 hydrate 列不出 `runs/` 时的**拒启**类型(S-46 件B;codex 对抗复审
+ * `RUN_STORE_STRICT_HYDRATE=on` 下 hydrate 列不出 `runs/` 时的**拒启**类型([ref] 件B;codex 对抗复审
  * R1-[high] 验真后从裸 `Error` 升成具名类型)。
  *
  * 🔴 **为什么必须是一个类型而不是一句文案**:`openStoreBackendWithFallback` 对**默认推导**的 local
@@ -60,16 +60,16 @@ export declare class FileRunStore {
     private readonly events;
     /** taskId → the open append log (one O_APPEND fd per run, lazily opened, held for lifetime). */
     private readonly eventLogs;
-    /** [868] the checkpoint-table stand-in (see memory-run-store.ts {@link RunStoreCheckpointProbe} — the full
+    /** [ref] the checkpoint-table stand-in (see memory-run-store.ts {@link RunStoreCheckpointProbe} — the full
      *  rationale lives on the interface); absent ⇒ the suspended-run reapers stay honest NO-OPs. */
     private checkpointProbe?;
-    /** #213 —— 本实例的 claim 身份(见 {@link ClaimOwner} 的选型注)。 */
+    /** [ref] —— 本实例的 claim 身份(见 {@link ClaimOwner} 的选型注)。 */
     private readonly claimOwner;
-    /** #213 —— sessionId → 该会话 claim 获取的临界区链尾(见 {@link withClaimLock})。 */
+    /** [ref] —— sessionId → 该会话 claim 获取的临界区链尾(见 {@link withClaimLock})。 */
     private readonly claimLocks;
-    /** 件6(#43 案 [4281]):启动期告警座(可选)。既有调用方不传 ⇒ 只走 fail-open 遥测那一半,不炸。 */
+    /** 件6(#43 案 [ref]):启动期告警座(可选)。既有调用方不传 ⇒ 只走 fail-open 遥测那一半,不炸。 */
     private readonly logger;
-    /** S-46 件B(census 第 29 行终局):`RUN_STORE_STRICT_HYDRATE` 的**部署级**表态。
+    /** [ref] 件B(census 第 29 行终局):`RUN_STORE_STRICT_HYDRATE` 的**部署级**表态。
      *  `true` ⇒ hydrate 的 readdir 失败拒启;缺席/`false` ⇒ 件6 的记债腿,行为字节不变。 */
     private readonly strictHydrate;
     constructor(root: string, opts?: {
@@ -88,7 +88,7 @@ export declare class FileRunStore {
      *  all-or-nothing; events.jsonl via readJsonlRecords drops a crash tail). A corrupt run.json (failed parse) is
      *  skipped — that run is lost, not a poison that fails the boot. */
     /**
-     * hydrate 期**逐文件**读盘的统一口(S-46 件B / codex 对抗复审 R4-[high])。
+     * hydrate 期**逐文件**读盘的统一口([ref] 件B / codex 对抗复审 R4-[high])。
      *
      * `readJsonlRecords` 对 ENOENT 答 `[]`、对其余读错(EACCES / EIO / EISDIR / ENOTDIR)**抛普通 Error**
      * (亲验 core `dist/stores/file/fs-atomic.js:110-112`)。那个普通 Error 从构造器冒出去之后,在**默认
@@ -123,7 +123,7 @@ export declare class FileRunStore {
         ok: false;
         activeTaskId: string;
     }>;
-    /** #213 —— createRun 临界区的后半段:落 claim 索引 + run 行(两者一体,行写失败即回滚 claim)。 */
+    /** [ref] —— createRun 临界区的后半段:落 claim 索引 + run 行(两者一体,行写失败即回滚 claim)。 */
     private commitNewRun;
     requestCancel(taskId: string, owner: string | null): Promise<boolean>;
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
@@ -134,15 +134,15 @@ export declare class FileRunStore {
     maxSeq(taskId: string): Promise<number>;
     retainedFrom(taskId: string): Promise<number>;
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;
-    /** [888] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
+    /** [ref] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
      *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
     setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
     /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard). */
     setSuspended(taskId: string): Promise<void>;
-    /** design/80 D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
+    /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
     setNeedsReview(taskId: string): Promise<void>;
     /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags.
-     *  S-51(codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
+     *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     getRun(taskId: string): Promise<RunRecord | undefined>;
@@ -211,24 +211,24 @@ export declare class FileRunStore {
      *  HOST/FILE LANE ONLY — the cross-replica tidb/pg store uses heartbeat→reapStale (a running row there may be alive
      *  on another replica; an unconditional reclaim would kill a live fleet run). */
     reclaimOrphanedAtBoot(isResumable?: (sessionId: string) => Promise<boolean>): Promise<number>;
-    /** [868] wire the checkpoint probe (LocalBackend.checkpoint(), where checkpoint + run store share one root). */
+    /** [ref] wire the checkpoint probe (LocalBackend.checkpoint(), where checkpoint + run store share one root). */
     setCheckpointProbe(probe: RunStoreCheckpointProbe): void;
-    /** [868] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired') and
+    /** [ref] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired') and
      *  PERSIST it — the file twin of the SQL UPDATE (`error`/`error_code` set directly, no result blob). */
     private failExpiredPark;
     /**
-     * [868] Durable F4 expiry — the file twin of TiDBRunStore.reapSuspended, driven by the injected checkpoint
+     * [ref] Durable F4 expiry — the file twin of TiDBRunStore.reapSuspended, driven by the injected checkpoint
      * probe instead of a SQL JOIN (formerly a NO-OP — one of the five closed doors in the "suspended run locks the
      * session forever" incident). Semantics verbatim from the SQL twin: suspended ∧ updatedAt < cutoff ∧ NOT
      * probe.hasPending(session) → failed 'approval expired before decision' / errorCode 'approval.expired' +
-     * release the task_active claim. The NOT-pending clause is the design/80 D-D blocker guard
+     * release the task_active claim. The NOT-pending clause is the [ref] D-D blocker guard
      * (SQL 孪生现在的真身:`run-store-sql.ts` 的 `reapSuspended`;`tidb-run-store.ts` 该壳文件已删(5.0.0)): a row whose checkpoint is STILL pending belongs to the checkpoint-state sweeps —
      * time-reaping it would orphan a model leg on a now-unlocked session. Probe absent ⇒ honest NO-OP.
      * MemoryRunStore is the parity oracle (byte-identical predicate; only the persist differs).
      */
     reapSuspended(olderThanMs: number): Promise<number>;
     /**
-     * [868] design/80 §3 inv#3 crash-safe backstop — the file twin of TiDBRunStore.failSuspendedWithExpiredCheckpoint
+     * [ref] [ref] §3 inv#3 crash-safe backstop — the file twin of TiDBRunStore.failSuspendedWithExpiredCheckpoint
      * (checkpoint-STATE-driven, not time-driven; scheduled UNCONDITIONALLY by the main.ts reaper, no
      * APPROVAL_TIMEOUT_SEC gate). Semantics verbatim from the SQL twin: (suspended ∨ needs_review) ∧
      * probe.hasExpired(session) ∧ NOT probe.hasPending(session) → same fail + claim release (wq64gmm5e: an
@@ -237,7 +237,7 @@ export declare class FileRunStore {
      */
     failSuspendedWithExpiredCheckpoint(): Promise<number>;
     /**
-     * #213 —— 裁定/接管路径上唯一许可的取行方式:**盘优先**,盘上没有才回退内存索引。
+     * [ref] —— 裁定/接管路径上唯一许可的取行方式:**盘优先**,盘上没有才回退内存索引。
      *
      * 复审 R2 [high]:反过来(索引优先)会在「同进程两只实例、两边索引都热」时出事 —— A 把 park 行
      * `markResuming` 成 running 并消费掉 checkpoint,B 的索引里还留着**旧的 park 对象**;B 于是读不到
@@ -246,20 +246,20 @@ export declare class FileRunStore {
      * 代价:只在 EEXIST 争用路径上多一次读文件,常路零开销。
      */
     private authoritativeRow;
-    /** #213 —— 越过内存索引直接读盘上的那一行(索引可能比另一实例的写晚一步;判据必须以盘为准)。
+    /** [ref] —— 越过内存索引直接读盘上的那一行(索引可能比另一实例的写晚一步;判据必须以盘为准)。
      *  读不出/坏行 ⇒ undefined,与 hydrate 的跳过口径一致。 */
     private readRowFromDisk;
     /**
      * A1/codex R2 —— 盘上扫该会话最新的非终局行:撕裂 claim(解析不出记录)唯一还能认主的通道。
-     * 内存索引不可用作判据 —— 同进程冷索引姊妹实例的行可能晚于本实例 hydrate 才落盘(L9/[1684] 同族),
+     * 内存索引不可用作判据 —— 同进程冷索引姊妹实例的行可能晚于本实例 hydrate 才落盘(L9/[ref] 同族),
      * 判据必须以盘为准。O(盘上 run 数),只在「claim 解析不出记录」这条罕见路径上走,常路零开销。
      * 行的读法与 hydrate/readRowFromDisk 同一套宽容口径(坏行跳过,不毒判定)。
      */
     private newestNonTerminalRowOnDisk;
-    /** 本进程要落盘的 claim 形(带持有者身份 —— #213 的活性证据)。 */
+    /** 本进程要落盘的 claim 形(带持有者身份 —— [ref] 的活性证据)。 */
     private claimRecord;
     /**
-     * #213 —— **每会话**的 claim 获取临界区。
+     * [ref] —— **每会话**的 claim 获取临界区。
      *
      * 为什么必须有:接管的判定链里有 `await`(checkpoint probe 的两条 EXISTS 谓词),两条并发 `createRun`
      * 会在同一枚陈旧 claim 上**各判各的**、然后**各接管各的** —— 第二条的 `rename` 搬走的是第一条刚写下的
@@ -274,10 +274,10 @@ export declare class FileRunStore {
      * 形状:每 session 一条 promise 链,后来者 await 前一位;链尾归零时删表项(不无界增长)。
      */
     private withClaimLock;
-    /** #213 —— 临界区内的 claim 获取本体:铸不下就裁定持有者,判陈旧则接管后重铸。有界重试(论证见 takeOverClaim)。 */
+    /** [ref] —— 临界区内的 claim 获取本体:铸不下就裁定持有者,判陈旧则接管后重铸。有界重试(论证见 takeOverClaim)。 */
     private acquireClaim;
     /**
-     * #213 —— 撞上 EEXIST 之后,对**现持有者**的裁定。默认方向是 `live`(挡住):只有能**证明**
+     * [ref] —— 撞上 EEXIST 之后,对**现持有者**的裁定。默认方向是 `live`(挡住):只有能**证明**
      * 持有者已死的形才判 `stale`。证不出来一律 fail-closed —— 单活不变式比自愈更重要。
      *
      * 三族:
@@ -289,14 +289,14 @@ export declare class FileRunStore {
      *  ③ 行 `suspended`/`needs_review`(park)—— park 按契约**没有在飞的腿**(腿返回 suspended 后就退出了,
      *     resume 腿会先 `markResuming` 翻回 running),所以这一族与「谁写的」无关,只问一件事:
      *     **还有东西可续吗**。有 pending ⇒ 可续(409 体里的 pendingGate 就是出路);有 expired ⇒ 归
-     *     [868] `failSuspendedWithExpiredCheckpoint` 那条腿收(它要落 `approval.expired` 这个终局语义,
+     *     [ref] `failSuspendedWithExpiredCheckpoint` 那条腿收(它要落 `approval.expired` 这个终局语义,
      *     本函数不许抢);两者皆无 ⇒ 这条 park 谁也续不动,而**没有任何一条排期腿够得着它**
      *     (reapStale 只碰 running;boot 回收刻意跳过 park;时间腿 reapSuspended 挂 APPROVAL_TIMEOUT_SEC,
      *     默认 0 = 不排期)⇒ 永久占用,判 stale。probe 缺席 ⇒ 证不出「无可续」⇒ fail-closed 判 live。
      */
     private judgeClaim;
     /**
-     * #213 —— 接管一枚已判定陈旧的 claim。返回 false = 现场已经变了 / 抢输了,调用方整轮重来。
+     * [ref] —— 接管一枚已判定陈旧的 claim。返回 false = 现场已经变了 / 抢输了,调用方整轮重来。
      * **整段同步**(无 await)⇒ 进程内不可被打断;跨进程由 rename 与单写者锁兜。
      *
      * ① **复核先行**(复审 codex R1 [critical]):judgeClaim 的 probe await 期间,resume 腿可能已经

package/dist/plugins/fork-routing-session-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * ForkRoutingSessionStore — the subRunner's session backing after core 1.350's fork 终修([1364]①/[1367]①).
+ * ForkRoutingSessionStore — the subRunner's session backing after core 1.350's fork 终修([ref]①/[ref]①).
  *
  * 问题形:core 的 `hostSessionFork` 在 HOST runner 的店里 fork,fork 子任务带 `requireExistingSession:true`
  * 在 opts.runner(subRunner)上执行——subRunner 拆店时子任务查不到刚 fork 出的会话,响亮失败
@@ -24,7 +24,7 @@
  * (requireExisting 的 host-first 重试仍落对店),中途 touch/noteTaskRun 缺路由=落 transient(no-op 级)。
  */
 import { type SessionStore, type AcquiredSession, type SessionStoreSummary, type SessionPlacement, type PlacedSessionRow } from "@sema-agent/core";
-/** acquire 选项形(core 5.48 SessionStore 契约):#292 placement=受信 spawner 的分区建会话声明。 */
+/** acquire 选项形(core 5.48 SessionStore 契约):[ref] placement=受信 spawner 的分区建会话声明。 */
 type AcquireOpts = {
     requireExisting?: boolean;
     placement?: SessionPlacement;
@@ -35,20 +35,20 @@ export declare class ForkRoutingSessionStore implements SessionStore {
     private readonly route;
     /** pin 时的店归属——unpin 恒回同店(LRU 逐出不拆对,见 pin/unpin)。 */
     private readonly pinnedAt;
-    /** [1593] 晋升名册(探针 Finding A 修):已 promoteToHost 的 id **永久**钉 host——路由表会被 LRU
+    /** [ref] 晋升名册(探针 Finding A 修):已 promoteToHost 的 id **永久**钉 host——路由表会被 LRU
      *  逐出,而私店的 forget 只清 entries 缓存行、底层 repo 行不清且 sweep 扫不到(core session-store.js
      *  亲读),逐出后 transient-first 的 requireExisting 会把陈旧快照端回给 revive。本集不逐出(上界=
      *  parked 子代数,天然小);pick/acquire 首查。 */
     private readonly promoted;
-    /** #292 placement 半场:placed id 名册(与 promoted 同姿势——不随路由 LRU 逐出)。placed 会话的
+    /** [ref] placement 半场:placed id 名册(与 promoted 同姿势——不随路由 LRU 逐出)。placed 会话的
      *  真居所恒=host(分区在 durable 店),任何形的 acquire/touch/release 都不得落 transient——
      *  否则 transient 的 claim-create 会铸出同 id 影子会话,requireExisting 的 transient-first 顺序
      *  会让影子遮蔽真转录(F-7 顺序对 placed 反向成害)。 */
     private readonly placed;
-    /** #292:host 店的 placements 声明透传(声明制——包装层不 duck-type,host 声明了才武装 placed
+    /** [ref]:host 店的 placements 声明透传(声明制——包装层不 duck-type,host 声明了才武装 placed
      *  路由;host 不声明时本店全行为与 5.47 前逐字节同)。 */
     readonly placements?: SessionStore["placements"];
-    /** #292:分区枚举透传(host 有才有——恒在的空实现会把「不能枚举」谎报成「没有 placed 会话」)。 */
+    /** [ref]:分区枚举透传(host 有才有——恒在的空实现会把「不能枚举」谎报成「没有 placed 会话」)。 */
     readonly listPlaced?: (kind: "subagent", opts?: {
         olderThanMs?: number;
         scope?: string;
@@ -56,10 +56,10 @@ export declare class ForkRoutingSessionStore implements SessionStore {
     constructor(host: SessionStore, transient: SessionStore);
     private remember;
     private pick;
-    /** #292:host 声明分区时的冷缓存判位探针。判据=host `requireExisting` acquire 的 `SessionMetadata.placement`
+    /** [ref]:host 声明分区时的冷缓存判位探针。判据=host `requireExisting` acquire 的 `SessionMetadata.placement`
      *  (5.48 additive,File/SQL/Ttl 三形都带——比 `placementOf` 面更普适:Ttl 缓存层不透传 placementOf)。
      *  placed 命中把 acquired 会话一并交回(调用方正需要它时零二次 acquire);非 placed/absent 的探针
-     *  acquire 一律 **forget** 收尾([4743] 义务①:验存在的 acquire 禁 release——release(placed)=真删)。 */
+     *  acquire 一律 **forget** 收尾([ref] 义务①:验存在的 acquire 禁 release——release(placed)=真删)。 */
     private hostPlacedProbe;
     acquire(sessionId?: string, opts?: AcquireOpts): Promise<AcquiredSession>;
     touch(sessionId: string): void | Promise<void>;
@@ -70,7 +70,7 @@ export declare class ForkRoutingSessionStore implements SessionStore {
     noteTaskRun(sessionId: string, taskId: string, runId?: string): void | Promise<void>;
     list(): Promise<SessionStoreSummary[]>;
     /**
-     * [1593] 子代 park 晋升:把住在 transient(TTL)店的子会话**整树拷贝**进 host durable 店,然后
+     * [ref] 子代 park 晋升:把住在 transient(TTL)店的子会话**整树拷贝**进 host durable 店,然后
      * 让该 id 从此路由到 host——`ensureChildSessionDurable` 的「主动晋升」半场(1.263 的只查不迁形在
      * 拆店生产形下恒否决 park:子会话从不在 host 店,core 收 veto 即 expire checkpoint + settle failed,
      * cli 真机 14ms~2s expired 即此)。

package/dist/plugins/image-bake-store-sql.d.ts

@@ -126,7 +126,7 @@ export declare class SqlImageBake {
     /**
      * Coarse 4-value lifecycle transition (the column the SSE reader polls for terminality).
      *
-     * @deprecated #193 车7(staleness-sweep P2-12):**test-only**——生产零调用。生产唯一写入路径是
+     * @deprecated [ref] 车7(staleness-sweep P2-12):**test-only**——生产零调用。生产唯一写入路径是
      * `ingestBakeLine`(routes/images.ts),它只经 `setState`(denormalize)与 `setTerminal` 驱动状态;
      * 本方法是绕开「status 只由 state/done 驱动」不变量的唯一直接写口,**禁止新增生产调用**。留而不删
      * 的唯一理由=三个集成测试用它铸中间态,整删随该套件下次翻新一并做。

package/dist/plugins/image-index-sql.d.ts

@@ -20,7 +20,7 @@ export declare class SqlImageIndex {
     /**
      * Register or update an index row (idempotent on repo+digest). Returns the row id.
      *
-     * @deprecated #193 车7(staleness-sweep P2-11):**生产零调用**——曾声称的 operator
+     * @deprecated [ref] 车7(staleness-sweep P2-11):**生产零调用**——曾声称的 operator
      * `/v1/images/register` 路径实际走 `registerBuilding`(routes/images.ts),本方法只剩集成测试当
      * seed 口在用。危险语义原样保留着:UNCONDITIONAL upsert 会把 `published` 行打回 `building`
      * (正是 §P2.10 静默 de-publish 病的成因,`registerBuilding` 因此才带 STATUS-MONOTONIC 守卫)。
@@ -39,7 +39,7 @@ export declare class SqlImageIndex {
      * isn't already `published` — a late/duplicate `done` for an already-promoted digest is a no-op on the
      * lifecycle, never a regression. Returns the row id.
      *
-     * Distinct from the unconditional `upsert` (#193 车7 更正:那条 operator `/v1/images/register` 路径
+     * Distinct from the unconditional `upsert` ([ref] 车7 更正:那条 operator `/v1/images/register` 路径
      * **也走本方法**——routes/images.ts:446 `idx.registerBuilding(...)`;`upsert` 已 @deprecated,只剩
      * 测试 seed 在用)。This is the bake auto-register's ONLY write into the index. Default status is `building` (P2 registers
      * node-local/quarantine `building` artifacts; P3's verify gate is what flips `building → published`).

package/dist/plugins/k8s-bg-scripts.d.ts

@@ -16,7 +16,7 @@ export declare function buildBgKillScript(dir: string): string;
  *  add 2s × N shells to the suspend/teardown path for a sub-second window. Kill (the model-facing wall) waits. */
 export declare function buildBgDisposeScript(dir: string): string;
 /**
- * design/116 detach: wrap a foreground exec so it is ADOPTABLE mid-flight, running the command as a real
+ * [ref] detach: wrap a foreground exec so it is ADOPTABLE mid-flight, running the command as a real
  * process-group LEADER so an adopted shell's KillShell / BG hard wall reap the WHOLE subtree.
  *
  * 🔴 review MED (why `setsid`, not bare `$$`): the wrapper `sh` that `kubectl exec` starts has a RUNTIME-DEPENDENT

package/dist/plugins/k8s-exec-protocol.d.ts

@@ -1,7 +1,7 @@
 /**
  * The confined, ADDITIVE pod-spec patch ({@link PodSpecPatch}/{@link applyPodSpecPatch}) + the exec-socket TLS
  * shape ({@link execSocketTlsOptions}) + the v4 channel status-frame parse ({@link exitCodeFromStatus}) — the
- * k8s adapter's protocol/patch layer, independent of pod lifecycle. Split out of `remote-env-k8s.ts` (design/158
+ * k8s adapter's protocol/patch layer, independent of pod lifecycle. Split out of `remote-env-k8s.ts` ([ref]
  * A13, internal-lossless — `remote-env-k8s.ts` re-exports every symbol below unchanged).
  */
 /**

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

@@ -1,7 +1,7 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
-/** 表名(#192 单数纪律;`schema-naming-invariants` 的闭集词表执法)。 */
+/** 表名([ref] 单数纪律;`schema-naming-invariants` 的闭集词表执法)。 */
 export declare const LEADER_RUN_TABLE = "leader_run";
 /** leader run 的四态 —— 与 `leader/endpoint.ts` 的 `LeaderRun["status"]` 同词表(闭集)。 */
 export type LeaderRunStatus = "running" | "completed" | "failed" | "needs_human";