@sema-agent/server 7.52.0 → 7.53.0

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

@@ -35,7 +35,7 @@ export interface K8sEnvConfig {
         backoffMs?: number;
     };
     /**
-     * Workspace-snapshot store (design/48 §5 WorkspaceHandle/SnapshotId). When set, the Kata pod
+     * Workspace-snapshot store ([ref] §5 WorkspaceHandle/SnapshotId). When set, the Kata pod
      * gains a DURABLE workspace across suspend/resume: `suspendVM` tars the workspace and uploads it to S3, then
      * deletes the pod; `resumeVM` provisions a fresh pod and restores the tar. This raises `capabilities.suspendable`
      * to `true` — but only the *workspace* is durable (files restored byte-for-byte); in-VM process/memory state
@@ -43,7 +43,7 @@ export interface K8sEnvConfig {
      * tolerate. Unset → `suspendable:false` (the original checkpoint + cold-rebuild degrade).
      *
      * 🔴 Credentials are ADAPTER-HELD: the sandbox only ever receives a short-lived, single-object PRESIGNED URL
-     * (never the access/secret key) — a credential reaching code that runs untrusted work is the design/53 lethal
+     * (never the access/secret key) — a credential reaching code that runs untrusted work is the [ref] lethal
      * trifecta. The presigned URL is used only inside an adapter-issued exec at suspend/resume time, so it never
      * reaches an agent turn.
      */
@@ -60,7 +60,7 @@ export interface K8sEnvConfig {
     sessionId?: string;
     /**
      * 🔴 ADDITIVE pod-spec patch (a SERVICE-side adapter seam, NOT a core seam: the K8s pod shape is
-     * provider-specific, so it stays in the adapter per design/48). A deployment supplies extra volumes / volumeMounts
+     * provider-specific, so it stays in the adapter per [ref]). A deployment supplies extra volumes / volumeMounts
      * / securityContext so the pod can carry e.g. a REAL read-only oracle mount (the RSI L8 immutable-mount probe) or
      * a hardened grader env (the graderEnvFactory). DEFAULT absent ⇒ the pod is byte-identical. The patch is TRUSTED
      * deployment config (like the rest of K8sEnvConfig) AND is STRUCTURALLY CONFINED: {@link applyPodSpecPatch} can
@@ -90,7 +90,7 @@ export interface ExecSocket {
     terminate?(): void;
 }
 /**
- * Test seam (design/61 §9.3 fault-injection): inject the REST `request` and/or the exec-socket factory, so pod
+ * Test seam ([ref] §9.3 fault-injection): inject the REST `request` and/or the exec-socket factory, so pod
  * lifecycle, retry policy, channel framing and liveness are deterministically testable without a cluster.
  */
 export interface K8sEnvDeps {
@@ -183,7 +183,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * provision a pod, then download + untar the snapshot into the workspace. A missing object (empty/plan-only
      * snapshot) resumes as a clean workspace.
      *
-     * [1467]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
+     * [ref]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
      * 配置根(cfg.mountPath),往 priorHandle.mountPath 绑=往容器 rootfs untar 大工作区,ephemeral-storage
      * 触顶即 pod 驱逐(恢复中途死,比「根变了 fail-closed reopen」更糟)。所以 untar 落当前根、handle 回报
      * 真生效根(core 契约明许:「做不到就诚实返回实际 mountPath,勿回显未兑现值」);跨 K8S_MOUNT_PATH
@@ -191,7 +191,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      */
     resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<ConnectResult>;
     /**
-     * Honest post-resume consistency (design/48 §5 council #8): the workspace FILES are restored byte-for-byte
+     * Honest post-resume consistency ([ref] §5 council #8): the workspace FILES are restored byte-for-byte
      * from the snapshot, so read-before-edit hashing already lines up — there's nothing to re-fetch. In-VM
      * process state (a language server) is gone by design; core/the LSP manager re-establishes it lazily. So
      * this is a successful no-op rather than the previous `unsupported` (which forced a cold rebuild).
@@ -224,7 +224,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
         };
     }, ExecutionError>>;
     /**
-     * LSP surface (lsp/manager.ts `isLspCapable` duck-type, design/64 §13.1): cluster-internal address for a
+     * LSP surface (lsp/manager.ts `isLspCapable` duck-type, [ref] §13.1): cluster-internal address for a
      * port on the sandbox pod. The E2B counterpart returns a public proxy host; a pod has none — the WORKER
      * must be able to reach pod IPs (in-cluster deployment, or on-node), and the transport is plain `ws://`
      * (cluster network, no TLS — the per-session bridge token still gates access like on E2B).

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

@@ -182,7 +182,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     /** Spawn the docker binary with argv; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private docker;
     /** Lazy connect for an exec path → ExecutionError on failure (fail closed, never throws). */
-    /** S1([1870]):容器内**用户命令**的 shell。缺省 /bin/sh;首次连接后探测一次 `command -v bash`,
+    /** S1([ref]):容器内**用户命令**的 shell。缺省 /bin/sh;首次连接后探测一次 `command -v bash`,
      *  有则切 bash(TB 实测 dash 三病:$'\t' 静默错字节/[[ ]] 127/进程替换)。镜像无 bash(alpine 裸底)
      *  ⇒ 保 sh(修前字节形,诚实降级);探测自身失败同。容器**创建**引导命令(mkdir && tail)不走
      *  本 shell——无 bash 语法且探测尚不可能。 */

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

@@ -5,7 +5,7 @@ export interface SshEnvConfig {
     host: string;
     port?: number;
     username: string;
-    /** PEM private key — from the adapter-held secret env (NEVER the workspace). design/61 §5 #2. */
+    /** PEM private key — from the adapter-held secret env (NEVER the workspace). [ref] §5 #2. */
     privateKey: string;
     passphrase?: string;
     /** Workspace root; relative paths resolve against it. Default "." (the login dir). */
@@ -15,7 +15,7 @@ export interface SshEnvConfig {
     /**
      * Per-command wall-clock bound (ms) when the caller gives none — NOT the connection lifetime.
      *
-     * ⚠️ **值与孪生腿不一致,原因未成文**(2026-08-08,#176 二轮扫描 finding,**候裁**):本腿默认
+     * ⚠️ **值与孪生腿不一致,原因未成文**(2026-08-08,[ref] 二轮扫描 finding,**候裁**):本腿默认
      * `5 * 60_000`(见构造处),而同判据的另外两条腿 —— `remote-env-host.ts` / `remote-env-local-docker.ts`
      * 的 `DEFAULT_COMMAND_TIMEOUT_MS` —— 都是 `30 * 60_000`,JSDoc 措辞还逐字同源。三处无共享常量、无对表
      * 钉,ssh 这一处也没有任何注释说明 5min 是刻意收紧(git 史是 history-free snapshot,「30min 是后来调
@@ -28,12 +28,12 @@ export interface SshEnvConfig {
     commandTimeoutMs?: number;
     /** File-transfer (sftp) bound (ms). */
     dataTimeoutMs?: number;
-    /** connect retry (idempotent establishment only — withRetry, design/61 §2A). */
+    /** connect retry (idempotent establishment only — withRetry, [ref] §2A). */
     retry?: {
         maxAttempts?: number;
         backoffMs?: number;
     };
-    /** #296 / C-R21:主机密钥校验策略(两旋钮,语义见 {@link SshHostKeyPolicy});缺席 = 两旋钮都没配。 */
+    /** [ref] / [ref]:主机密钥校验策略(两旋钮,语义见 {@link SshHostKeyPolicy});缺席 = 两旋钮都没配。 */
     hostKey?: SshHostKeyPolicy;
 }
 type ConnectResult = {
@@ -44,7 +44,7 @@ type ConnectResult = {
     error: RemoteExecutionError;
 };
 /**
- * Test seam (design/61 §9.3 fault-injection): inject a `connectOnce` that replays an error sequence, so the
+ * Test seam ([ref] §9.3 fault-injection): inject a `connectOnce` that replays an error sequence, so the
  * retry policy (retryable codes / maxAttempts / "first fail → second success") is deterministically testable
  * without a live host.
  */
@@ -61,12 +61,12 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private conn?;
     private sftpPromise?;
     private destroyed;
-    /** [1165] 代际闸:destroy/reconnect 各自 +1。逻辑连接操作(startConnect)起飞时抓拍一次并贯穿全部
+    /** [ref] 代际闸:destroy/reconnect 各自 +1。逻辑连接操作(startConnect)起飞时抓拍一次并贯穿全部
      *  重试轮(四轮复审:抓拍若在 connectOnce 内,被顶替代的下一轮重试会抓到**新**代际混进新代)——
      *  每轮起跳先查代际/destroyed(陈旧=不再开 socket),ready 到达再查一次(在飞握手 late-ready=end
      *  不赋 conn)。关死「A 在飞→reconnect 起 B→A 竞后抢占/成孤儿活连接」的全部竞窗。 */
     private connEpoch;
-    /** [1165] 四轮复审 single-flight:connect()/reconnect()/懒连接三路共用一条代际键在飞记录——任何一路
+    /** [ref] 四轮复审 single-flight:connect()/reconnect()/懒连接三路共用一条代际键在飞记录——任何一路
      *  在飞时其余路 join 同一 promise(同代际),绝不并起两条连接;settle 时按记录身份清(旧败诺清不掉
      *  新记录)。五轮复审:①记录带 kind——并发 reconnect join 已在飞的 replace 记录(不再各自 bump 代际
      *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
@@ -86,11 +86,11 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     }>;
     /** 五轮复审:per-caller 可中止等待(共享诺不动,只退本 caller)。 */
     private raceConnAbort;
-    /** [1165] 四轮复审:三路(connect/reconnect/懒连接)唯一的连接发起点——同代际在飞记录 join,settle
+    /** [ref] 四轮复审:三路(connect/reconnect/懒连接)唯一的连接发起点——同代际在飞记录 join,settle
      *  身份清;代际抓拍一次贯穿全部重试轮,每轮起跳先查(陈旧/destroyed=不再开 socket,用不可重试的
      *  aborted 码即刻收敛 withRetry)。五轮复审:共享尝试零 caller 信号(取消面全在 per-caller race)。 */
     private startConnect;
-    /** [1165] exec/execStream/sftp 共用的懒连接入口。已连=零开销直过;未连=走完整 connect()(含重试策略)。
+    /** [ref] exec/execStream/sftp 共用的懒连接入口。已连=零开销直过;未连=走完整 connect()(含重试策略)。
      *  caller 的 signal 只中止**它自己的等待**(共享在飞尝试继续伺服其他等待者;彻底取消归 destroy 的代际
      *  闸管,handshake 余命 ≤ readyTimeout 有界)。 */
     private ensureConnected;

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

@@ -1,5 +1,5 @@
 /**
- * [848] remote scratchpad(server 半场)— the REMOTE sandbox lanes' session scratchpad convention.
+ * [ref] remote scratchpad(server 半场)— the REMOTE sandbox lanes' session scratchpad convention.
  *
  * host lane already has one (env-facts.ts ensureScratchpadDir, worker-local under localDataRoot). The remote
  * lanes (e2b/k8s/local-docker/ssh) run their hands OFF this box, so a worker-local dir would be a lie — the

package/dist/plugins/resume-anchor-store-sql.d.ts

@@ -1,5 +1,5 @@
 /**
- * Durable resume-at anchor map (E18) — SINGLE-FILE DUAL-DIALECT (design/158 A12 收编). The service-owned
+ * Durable resume-at anchor map (E18) — SINGLE-FILE DUAL-DIALECT ([ref] A12 收编). The service-owned
  * eventId→entryId translation: the shell holds the live E2 `eventId` (core never persists it); core's
  * `TaskSpec.resumeAt` takes a persisted `SessionTreeEntry.id`. Keyed (session_id, event_id) so `resolve`
  * is a PK point-lookup. `owner` is the single-DB-fleet null-safe defense-in-depth guard, the data-layer

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

@@ -1,6 +1,6 @@
 /**
- * 托管留存执行面的**非破坏性 SQL 半场** —— SINGLE-FILE DUAL-DIALECT(design/158 A12;先例 =
- * `retention-store-sql.ts` 本身)。#270 车2,设计稿 `docs/DESIGN-270-retention-lane.md` v1.3。
+ * 托管留存执行面的**非破坏性 SQL 半场** —— SINGLE-FILE DUAL-DIALECT([ref] A12;先例 =
+ * `retention-store-sql.ts` 本身)。[ref] 车2,设计稿 `docs/DESIGN-270-retention-lane.md` v1.3。
  *
  * ── 为什么与车1 的 `retention-store-sql.ts` 分家(而不是往那只店上再挂三组方法)────────────────────
  * 车1 那只店是 core `ManagedRetentionCapability` 的**实现体**:它的每一个公开方法都是一次**破坏性**

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

@@ -1,6 +1,6 @@
 /**
- * 托管留存(managed retention)执行面的 **store 半场** —— SINGLE-FILE DUAL-DIALECT(design/158 A12 定型半场;
- * 先例 = `leader-run-store-sql.ts` / `checkpoint-store-sql.ts`)。#270 车1,设计稿
+ * 托管留存(managed retention)执行面的 **store 半场** —— SINGLE-FILE DUAL-DIALECT([ref] A12 定型半场;
+ * 先例 = `leader-run-store-sql.ts` / `checkpoint-store-sql.ts`)。[ref] 车1,设计稿
  * `docs/DESIGN-270-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的
  * `core/retention.d.ts`(`ManagedRetentionCapability` / `RetentionReceipt` / `RetentionDeclaration`)。
  *
@@ -39,7 +39,7 @@
  *   - schema 属主:MySQL DDL 由本文件导出、展开进 `tidb-pool.ts` 的 `SCHEMA_STATEMENTS`;PG DDL 由本文件的
  *     `ensurePgRetentionSchema` 导出、由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合(与 leader-run 同姿势)。
  *
- * ── 命名(#192 纪律,与设计稿的复数写法的**有意**偏离)────────────────────────────────────────────
+ * ── 命名([ref] 纪律,与设计稿的复数写法的**有意**偏离)────────────────────────────────────────────
  * 设计稿 §5/§2 写的是 `retention_holds` / `retention_tombstones`;本仓的表名闭集词表是**单数**制且由
  * `test/schema-naming-invariants.test.ts` 机器执法(「一张表是一类行的集合,表名说的是『一行是什么』」)。
  * ⇒ 落库名一律单数:`retention_audit` / `retention_hold` / `retention_lease` / `retention_tombstone`。
@@ -136,7 +136,7 @@ export interface SqlRetentionStoreOptions {
      */
     taskAttachmentTable: boolean;
     /**
-     * #318 `task_list_meta` / `task_list_item` 两表是否在场。**必填,没有默认值**(与
+     * [ref] `task_list_meta` / `task_list_item` 两表是否在场。**必填,没有默认值**(与
      * `taskAttachmentTable` 同一条理由:盲发 DELETE 会在没建表的库上把整轮 sweep 打红)。
      * 生产上 `boot/task-list-lane.ts` 在**任何 SQL 后端**都无条件 ensure 这两张表 ⇒ 装配层照实传 true;
      * 纯内存/local 车道压根没有 SQL 留存腿。
@@ -282,17 +282,17 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *      COMMIT,一个并发的 PUT hold 在此期间提交不了(它抢同一把锁)——一段恒真的"复核"比没有更坏。
      *
      * 视界判据**两条臂都写出来**:`deadline` 在场按 deadline,缺席按 `created_at_ms`。少了后一条臂,一条
-     * 没有审批 TTL 的 pending 行就永远过不了期(design/80 §3 inv#3 的 terminal_at_ms 要挡的正是这种永久泄漏)。
+     * 没有审批 TTL 的 pending 行就永远过不了期([ref] §3 inv#3 的 terminal_at_ms 要挡的正是这种永久泄漏)。
      *
-     * 🔴 **pin 释放 = 本方法的 `pending → expired` 翻转本身**(core [4180] 定谳:retention.ts 契约那句
-     * 「AND release the associated session pins」是真意,[4175] 引错了对象——它引的是引擎 live-path reap
+     * 🔴 **pin 释放 = 本方法的 `pending → expired` 翻转本身**(core [ref] 定谳:retention.ts 契约那句
+     * 「AND release the associated session pins」是真意,[ref] 引错了对象——它引的是引擎 live-path reap
      * 的 JSDoc)。本仓 SQL 后端**没有独立的 pin 存储**:钉住 session 的正是 `checkpoint.status='pending'`
      * 这一状态(它是 deleteExpiredSessions 活引用四腿之一,见下方 lineage 注 :79x),所以状态翻转 = 引用
-     * 解除 = pin 释放——不需要第二个写操作,而幂等(重跑对已 expired 行零命中)恰好满足 [4180] 的
-     * 「释放已释放 pin=no-op」要求。单写者不变式按 [4180] 改述:**每行的 pin 恰好释放一次,由终局该行
+     * 解除 = pin 释放——不需要第二个写操作,而幂等(重跑对已 expired 行零命中)恰好满足 [ref] 的
+     * 「释放已释放 pin=no-op」要求。单写者不变式按 [ref] 改述:**每行的 pin 恰好释放一次,由终局该行
      * 的车道执行**——live 行归 reaper,retention 行归本方法,两行集不交(下一段的 live-pin skip 正是
      * 「不交」的执行判据)。
-     * 边界形([4175] 建议,[4180] 确认仍成立):**live-pinned 且已过视界**的行(`task_active` 还占着这条
+     * 边界形([ref] 建议,[ref] 确认仍成立):**live-pinned 且已过视界**的行(`task_active` 还占着这条
      * 会话)⇒ skip 计数、不动那行 —— 不在一条活会话脚下抽掉它的 resume 坐标,与 legal-hold 的 skip 同形。
      *
      * receipt 口径:`deleted` = **本次 CAS 赢下的行数**(过期销毁的是那道 pending 门,行本身按设计留在库里
@@ -304,7 +304,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * 抽成一处是因为它同时被「可过期候选」与「被 pin 的计数」两条查询用,手抄两份必分家。
      */
     private horizonArms;
-    /** 「这条 checkpoint 的会话被一次活跑占着」= [4175] 的 live-pinned 判据(SQL 谓词形,两方言同文本)。 */
+    /** 「这条 checkpoint 的会话被一次活跑占着」= [ref] 的 live-pinned 判据(SQL 谓词形,两方言同文本)。 */
     private static readonly PINNED_EXISTS;
     /**
      * **可过期**的候选 token(保护谓词写在 SQL 里、扣在 `LIMIT` **之前**)。

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

@@ -1,9 +1,9 @@
 /**
- * RosterStore SQL twins(agent-team S1 server 半场,[1070]① 提货单)——core `RunnerDeps.rosterStore`
+ * RosterStore SQL twins(agent-team S1 server 半场,[ref]① 提货单)——core `RunnerDeps.rosterStore`
  * 的 TiDB/PG 双方言实现:具名子 agent 的持久名册(具名 spawn advisory 写入;SendMessage 活注册表
  * miss 后咨询;v1=诚实指针 roster_only,非跨 run resume)。
  *
- * 语义三条([1070]① 必守,与 core roster-store.js 参考实现字节对齐):
+ * 语义三条([ref]① 必守,与 core roster-store.js 参考实现字节对齐):
  *  1. resolve **查询内** filter-before-reduce:access 轴在 SQL WHERE 完成(scope 先拒 → owner 匹配 →
  *     sessionScoped 显式位才认 session 匹配),绝不先取全集再内存过滤(跨租户行连查询结果都不进);
  *  2. 同 `(normalizedName, owner, scope)` 域 upsert(core upsertKey 同键);
@@ -15,7 +15,7 @@
  * spawn 可共享毫秒、多副本时钟可偏斜,无第三键的 LIMIT 1 非确定)。诚实记账:同毫秒并写时选择=
  * agent_id 字典序最大,与 core 单进程的「后遍历者赢」可能不同——多副本本就无全序,确定性优先。
  *
- * normalize 私拷已回收(2026-07-19):core 公共出口落地(黑板 [1070]① 所请的 additive 导出),按
+ * normalize 私拷已回收(2026-07-19):core 公共出口落地(黑板 [ref]① 所请的 additive 导出),按
  * 头注预案换回单行 import。⚠️ 语义仍是**存储键**:DB 行按 normalize 后的键写入——core 若改语义,
  * 存量行查不回;test/roster-store-db-integration.test.ts 的 golden corpus 钉守这条(非私拷漂移钉,
  * 是「core 变语义必须先过迁移裁量」的告警钉)。
@@ -35,7 +35,7 @@ export declare class TiDBRosterStore implements RosterStore {
     resolve(name: string, access: RosterAccess): Promise<RosterEntry | undefined>;
     list(): Promise<RosterEntry[]>;
     releaseAgent(agentId: string): Promise<void>;
-    /** [1522] MED2(server 扩展,非 core 接口;core RB-23②③ 派给部署的清理半场):TTL 清理——
+    /** [ref] MED2(server 扩展,非 core 接口;core [ref]②③ 派给部署的清理半场):TTL 清理——
      *  task-scoped 具名 spawn 的 owner=宿主 taskId=每 run 一新行,无清理=线性无界。按 recorded_at_ms
      *  (最后一次 upsert 触碰)删,latest 语义不受影响(活跃名恒被新 spawn 刷新)。 */
     reapOlderThan(cutoffMs: number): Promise<number>;
@@ -48,7 +48,7 @@ export declare class PgRosterStore implements RosterStore {
     resolve(name: string, access: RosterAccess): Promise<RosterEntry | undefined>;
     list(): Promise<RosterEntry[]>;
     releaseAgent(agentId: string): Promise<void>;
-    /** [1522] MED2(TiDB twin 同案注)。 */
+    /** [ref] MED2(TiDB twin 同案注)。 */
     reapOlderThan(cutoffMs: number): Promise<number>;
 }
 export {};

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

@@ -1,5 +1,5 @@
 /**
- * Async run registry (S1) + replayable event log (S2) — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场).
+ * Async run registry (S1) + replayable event log (S2) — SINGLE-FILE DUAL-DIALECT ([ref] A12 定型半场).
  * ONE implementation, TWO dialects; the historical `TiDBRunStore` / `PgRunStore` class names survive as thin
  * ctor subclasses so every consumer (store-backend.ts, the run/reaper/session/usage suites) is untouched.
  *
@@ -15,12 +15,12 @@
  *   - `?` placeholders vs `$n` (transaction control itself is normalized by `SqlDriver`/`SqlTxConn` —
  *     mysql2's native begin/commit/rollback vs PG's statement form; see sql-driver.ts)
  *   - dup-key classification (createRun's task_active claim race) — the PREDICATE has a single owner
- *     (`sql-errors.ts`, A-032 P1-①); only the dialect DISPATCH is visible here
+ *     (`sql-errors.ts`, [ref] P1-①); only the dialect DISPATCH is visible here
  *
  * ⚠️ The run ACTIVE-status word list written out in the `status IN (…)` / `NOT IN (…)` fragments below
  * is the closed set owned by `store-contracts.ts` (`isTerminalRunStatus` / `isParkedRunStatus`). The SQL
  * text stays literal ON PURPOSE (A12: both dialects readable side by side), so the tie is a PARITY GATE:
- * `test/source-hygiene-gate.test.ts` → "A-032 P1-② run 活状态 SQL 字面 ↔ store-contracts 闭集属主 parity".
+ * `test/source-hygiene-gate.test.ts` → "[ref] P1-② run 活状态 SQL 字面 ↔ store-contracts 闭集属主 parity".
  * core adding a TaskStatus member turns that gate red on every fragment here — update them in the same batch.
  *   - null-safe owner compare: `<=>` (TiDB) vs `IS NOT DISTINCT FROM` (PG) — a null-owner run still matches
  *     `owner=null` on both, single-DB-fleet defense-in-depth (see {@link requestCancel})
@@ -51,7 +51,7 @@ export declare class SqlRunStore {
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
-    /** Dup-key classification — single owner in `sql-errors.ts` (A-032 P1-①; the old local form read
+    /** Dup-key classification — single owner in `sql-errors.ts` ([ref] P1-①; the old local form read
      *  only mysql2's string `code`, so an error carrying just `errno` fell through the claim-race arm). */
     private isDupKey;
     /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
@@ -88,7 +88,7 @@ export declare class SqlRunStore {
     /** Whether a cancel has been requested for this run (polled by the owning instance's heartbeat tick).
      *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
-    /** design/80 seam #2: request PREEMPT (graceful durable yield, ≠ cancel's kill) of a RUNNING run — durable +
+    /** [ref] seam #2: request PREEMPT (graceful durable yield, ≠ cancel's kill) of a RUNNING run — durable +
      *  cross-replica. Sets the flag the owning instance's heartbeat tick polls (it then aborts its preemptSignal →
      *  the task suspends at the next clean turn boundary, gate resource_limit/reason preempt); a same-replica caller
      *  additionally aborts the in-flight preempt controller for instant effect. Only flags a `running` row
@@ -112,7 +112,7 @@ export declare class SqlRunStore {
      *  colliding on the (task_id, seq) PK. */
     maxSeq(taskId: string): Promise<number>;
     /** Mark terminal AND release the single-active-run claim atomically — if the DELETE were a separate
-     *  statement that failed, the session would stay permanently locked. [888] FIRST terminal writer wins:
+     *  statement that failed, the session would stay permanently locked. [ref] FIRST terminal writer wins:
      *  the UPDATE is CAS'd POSITIVELY on the live statuses (running/suspended/needs_review) — every call site
      *  is a settle-once flow whose backstops may double-fire (cancel × leg-throw × reaper), and an
      *  unconditional write let the LAST racer overwrite errorCode (a `cancelled` row flipping to a generic
@@ -121,18 +121,18 @@ export declare class SqlRunStore {
      *  unconditional (idempotent; the first writer already released it). */
     setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
     /**
-     * Durable F4 (design/45): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
+     * Durable F4 ([ref]): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
      * 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. The token-bearing result is NOT stored (the submitter polling
      * this row must never receive the capability token); only the status flips.
      */
     setSuspended(taskId: string): Promise<void>;
     /**
-     * design/80 D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
+     * [ref] D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
      * pre-action `plan_review`; core assemble-result slot 8.6). Like {@link setSuspended} this is a NON-terminal park
      * that KEEPS the `task_active` session claim (it does NOT delete it — only {@link setTerminal} does), so the
      * resume path (`getActiveTaskId` → `markResuming`) can find + claim the row. core treats a review pause "like a
-     * suspend, an INTENTIONAL durable pause" (design/76 §2.5) — the service MUST park it the same way, else the run is
+     * suspend, an INTENTIONAL durable pause" ([ref] §2.5) — the service MUST park it the same way, else the run is
      * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
      * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
      * (reaper-revert guard, mirrors setSuspended). The park→resume→claim invariant is pinned on BOTH REAL engines by
@@ -153,7 +153,7 @@ export declare class SqlRunStore {
      * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns true
      * if it claimed the flip (false ⇒ the reaper already expired it, or it isn't suspended).
      *
-     * S-51(codex R1 [medium],红先双库证):认领 = **接管 `instance_id`**。此前该列只在 createRun 铸、此处不动,
+     * [ref](codex R1 [medium],红先双库证):认领 = **接管 `instance_id`**。此前该列只在 createRun 铸、此处不动,
      * 于是 A 创建、C 认领 resume 的行永远记 A —— 而 steer/interrupt 的「他副本」臂与 sendHandleMiss 都拿这列当
      * 「当前持有者」证据:verify 形 resume 腿(不登记 steerable)在 C 上跑时,C 读到 A≠C 就谎报「run 在别的副本」。
      * 语义自此成文:`instance_id` = **当前持有副本**(createRun 铸、markResuming 认领接管);CAS 输不改列
@@ -286,7 +286,7 @@ export declare class SqlRunStore {
      * the run + RELEASE its task_active (unlock the session). Mirrors the checkpoint reaper's CAS-expire (≈ deny);
      * idempotent across replicas. Returns count.
      *
-     * 🔴 design/80 D-D (blocker fix): SKIPS any row whose checkpoint is STILL pending — that row is
+     * 🔴 [ref] D-D (blocker fix): SKIPS any row whose checkpoint is STILL pending — that row is
      * owned by a checkpoint-state-driven sweep (the SLA deny-sweep for human/irreversible_ask, or
      * failSuspendedWithExpiredCheckpoint once the checkpoint is expired). Without this guard, this time-based
      * UPDATE fired at the SAME instant as the deny-sweep (deadline == createdAt + ttl, both keyed on the TTL),
@@ -302,7 +302,7 @@ export declare class SqlRunStore {
      */
     reapSuspended(olderThanMs: number): Promise<number>;
     /**
-     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at_ms` sweep): fail a
+     * [ref] §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at_ms` sweep): fail a
      * suspended run whose durable checkpoint was ALREADY EXPIRED by `reapExpired` (past its `deadline` or its
      * absolute `terminal_at_ms`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
      * approval-TTL gate), CHECKPOINT-STATE-driven not time-driven, so it aligns EXACTLY with the per-row

package/dist/plugins/scheduler-support.d.ts

@@ -10,7 +10,7 @@ type Result<T, E> = {
     ok: false;
     error: E;
 };
-/** Default caps (fail-closed bounds; design/105 §3.9). Override per deployment. */
+/** Default caps (fail-closed bounds; [ref] §3.9). Override per deployment. */
 export declare const DEFAULT_SCHEDULER_CAPS: {
     readonly supported: true;
     readonly maxScheduledPerScope: 32;

package/dist/plugins/send-user-file.d.ts

@@ -1,7 +1,7 @@
 /** SigV4 physical ceiling (AWS: X-Amz-Expires max 604800s = 7 days). */
 export declare const PRESIGN_MAX_TTL_SEC = 604800;
 /**
- * Multi-tenant governance (clay ruling 2026-07-14, blackboard [768]② variant a with a HASHED segment): every
+ * Multi-tenant governance (clay ruling 2026-07-14, blackboard [ref]② variant a with a HASHED segment): every
  * object key carries a per-tenant SCOPE SEGMENT so tenants can be listed/revoked by prefix on the store itself,
  * WITHOUT leaking the principal into the (user-visible, forwardable) URL. The segment is
  * `HMAC-SHA256(secretKey, "sendfile-scope:" + scope)` hex, truncated to 32 chars:

package/dist/plugins/session-capture-record-store-sql.d.ts

@@ -0,0 +1,99 @@
+/**
+ * [ref] seam②([ref] §2.1b,core 7.0.2 [ref] 件2;黑板 [ref]/[ref]/[ref] 键形对齐)——
+ * **会话 capture opt-out 记录的 SQL 载体** `session_capture_optout`:core `SessionCaptureRecordStore`
+ * 的 Promise 形实现。SINGLE-FILE DUAL-DIALECT([ref] A12 形,照 memory-optout-grant-store-sql.ts:
+ * 一个 `SqlSessionCaptureRecordStore` 接 `SqlDriver`,两个薄 ctor 子类落方言绑定)。
+ *
+ * ── 为什么要这只店(core layout.d.ts §2.1b 原文方向)────────────────────────────────────────────
+ * core 缺省载体 = 控制面文件三腿(`fileSessionCaptureRecordStore`)。无状态多副本部署上文件形对 resume
+ * 副本不可见 ——「record not found」恰好朝**继续采集**的方向坏(server F1 点名的形)。SQL 载体让一条
+ * 一次性隐私记录跨副本存活;供给它同时是 §2.1b 的能力信号:远端车道的 `capture:"off"` 声明从
+ * 409 `config.memory_capture_unsupported` 稳态转为真持久([ref] 前的稳态自此解除)。
+ *
+ * ── 三腿逐腿失败法(core 契约,dist layout.d.ts + 文件三腿实现逐字亲读;引擎消费点 engine.js 亲读)──
+ *   · `mark` **create-only / first-record-wins,恒不 reject**:dup-key ⇒ `"existed"`(幂等重宣告,
+ *     第一条记录赢 —— 恒不 UPDATE);其余任何失败(断连/超时/超宽键)⇒ `"unpersisted"`
+ *     (383 §2.8:只存在于进程内的 opt-out 会被第一次 resume 打破,「没落住」是具名拒绝,调用方必须
+ *     拒跑 —— 永不静默降级)。引擎侧对 rejection 也折 `"unpersisted"`(engine.js mark 的 `.then(settle,
+ *     () => "unpersisted")`),本店仍自行 catch:契约写在店上,不赖调用方兜底。
+ *   · `read` **fail-closed**:行在而解不出 ⇒ 返回**合成记录**(句式与 core 文件腿逐字同形 ——
+ *     损坏不许把一条隐私请求洗回采集);无行 ⇒ `undefined`(缺席才是「采集开」);存在性本身不可立
+ *     (SQL 故障)⇒ **reject**(引擎 catch 折 INDETERMINATE fault 轴:故障永不谎报成「用户请求过」,
+ *     也永不谎报成「没有记录」)。
+ *   · `list` 枚举失败 ⇒ **reject**(读不出的名册不是空名册 —— consolidation 资格臂据此 fail-closed 拒整理,
+ *     engine.consolidationEligibility 亲读);单行解不出 ⇒ 合成记录(绝不静默漏行:漏一行 = 蒸馏器放大
+ *     一条作者要求扣留的内容)。
+ *
+ * ── 键形法:**编码规范形**(codex R2-[high] 验真后改形;grant 店的「形状拒」在这里是错的)────────
+ * 提交面把 sessionId 定为**任意不透明串**(server.ts submit 门:「LENGTH-ONLY — NOT a uuidv7 shape
+ * check」,≤64 字符,run-local `--session` / 匿名分享 id 等都合法)——带空白/控制字符的 id 是**在契约内**
+ * 的真会话,店若按字节形状拒它,后果=该会话在 SQL 部署上「opt-out 永远落不住(unpersisted)+ 采集态
+ * 永远 indeterminate(commits 全抑制)」,是部署契约不兼容,不是输入加固。所以键列**不存生字节**,存
+ * `encodeURIComponent(sessionId)` 规范形 —— 与 **core 文件三腿给文件名做的编码逐字同源**(layout.js
+ * `captureOptOutPath` 亲读),两载体一个键法:
+ *   · 编码字母表(`A-Za-z0-9-_.!~*'()%`)天然**无空白无控制字符** ⇒ TiDB utf8mb4_bin 的 PAD SPACE
+ *     尾空格折行隐患在字母表层面消灭,任意合法 id 字节精确、互不串行;
+ *   · 64 字符 id 编码上界 192 ⇒ 列宽 255 恒容;编码后超 255 的 id(>64 字符,提交面本就拒)在 `mark`
+ *     上答 `"unpersisted"`、在 `read` 上答 `undefined` —— 后者是**可证明的缺席**(本店写腿从不落这种键,
+ *     列宽也物理放不下),不是 indeterminate;
+ *   · `list` 逐行做**规范形往返校验**(decode 失败 / re-encode ≠ 原字节 ⇒ 整名册 **reject**):带外/损坏
+ *     写入的非规范键(如生尾空格 "s1 ")若被静默放行,roster 键与 lineage 贡献者键精确比对不上 ⇒
+ *     consolidation 资格臂**漏排除** opt-out 会话 = 蒸馏放大被扣留内容(codex R2-[medium] 验真);
+ *     reject 让资格臂 fail-closed 拒整理(`memory.consolidation_governance_unreadable`),方向正确。
+ *
+ * ── 列 ──────────────────────────────────────────────────────────────────────────────────────────
+ *   session_id  VARCHAR(255) PK  会话 id 的 encodeURIComponent 规范形(见上;宽=64 字符 id 的编码上界)
+ *   at_ms       BIGINT NOT NULL  记录时刻(core `SessionCaptureOptOutRecord.at`,恒引擎钟)
+ *   reason      TEXT NOT NULL    自由文本(verb 的 reason ≤500 由 wire 验;声明腿/SDK 直连宿主不设上限
+ *                                —— TEXT 而不是 VARCHAR(500):列溢出会把一条隐私请求变成 "unpersisted",
+ *                                为省字节引入那个失败向不值)
+ * 刻意**无** updated_* 审计列:记录是一次性单向的(first-record-wins,恒不改写),`at_ms` 就是全部时间事实。
+ *
+ * ── 方言差异(显式写在调用点,A12 doctrine)──────────────────────────────────────────────────────
+ *   · `?` vs `$n` 占位符;
+ *   · create-only:两方言都走**裸 INSERT + dup-key 判**(`sql-errors.ts` 的 `isDupKeyError` 单一登记谓词)
+ *     而不是 `INSERT IGNORE` / `ON CONFLICT DO NOTHING` —— IGNORE 在 MySQL 协议下连带吞掉溢出/截断类
+ *     错误(把「没落住」洗成「落了」),DO NOTHING 则要靠 affected==0 反推 dup(与「没插但也没错」不可
+ *     判别)。裸 INSERT 让三种结局(插入成功/键已在/真失败)各有各的信号,恰是 mark 三态要的判别度。
+ *   · BIGINT 读回:TiDB number,PG string —— `readAtMs` 两形都认,其余按行级损坏折合成记录(见 read 法)。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import type { SessionCaptureOptOutMarkOutcome, SessionCaptureOptOutRecord, SessionCaptureRecordStore } from "@sema-agent/core";
+import type { PgQueryFn } from "./pg-query.js";
+import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
+export declare const SESSION_CAPTURE_OPTOUT_TABLE = "session_capture_optout";
+/** 键列宽(64 字符 id 的 encodeURIComponent 上界 192 ≤ 255;DDL 与守卫同源此常量)。 */
+export declare const SESSION_CAPTURE_KEY_WIDTH = 255;
+/** 键的规范形 = core 文件三腿给文件名做的同一只编码(layout.js `captureOptOutPath` 亲读)。 */
+export declare function encodeSessionCaptureKey(sessionId: string): string;
+/**
+ * `list` 的规范形往返校验(codex R2-[medium]):表里的键必须恰是某个 id 的 `encodeURIComponent` 输出。
+ * decode 失败 ⇒ **抛**具名错(原错随 `cause` 上交,不折默认值 —— [ref] 门② SHAPE C:catch 不许只 return
+ * 默认值);re-encode ≠ 原字节(如带外写入的生尾空格键、小写十六进制)⇒ 返回 `undefined`;两形调用方都
+ * **拒整本名册**(fail-closed:一个比对不上 lineage 贡献者的键 = 资格臂漏排除 = 蒸馏放大被扣留内容)。
+ */
+export declare function decodeCanonicalSessionCaptureKey(raw: string): string | undefined;
+/** 双方言 SessionCaptureRecordStore(Promise 形三腿)。见文件头的逐腿失败法。 */
+export declare class SqlSessionCaptureRecordStore implements SessionCaptureRecordStore {
+    private readonly driver;
+    private readonly dialect;
+    constructor(driver: SqlDriver, dialect: SqlDialect);
+    /** create-only / first-record-wins;**恒不 reject**(任何失败 ⇒ `"unpersisted"`,调用方必须拒跑)。 */
+    mark(sessionId: string, record: SessionCaptureOptOutRecord): Promise<SessionCaptureOptOutMarkOutcome>;
+    /** fail-closed 读:无行 ⇒ undefined;行在解不出 ⇒ 合成记录;SQL 故障 ⇒ reject(引擎折 fault 轴)。 */
+    read(sessionId: string): Promise<SessionCaptureOptOutRecord | undefined>;
+    /** 全名册。枚举失败 ⇒ reject(读不出的名册不是空名册);值列损坏 ⇒ 合成记录,绝不静默漏行;
+     *  **键**非规范形 ⇒ reject 整本(codex R2-[medium]:一个比对不上 lineage 贡献者的键若被静默放行,
+     *  资格臂就漏排除该会话 = 蒸馏放大被扣留内容;拒整本让 consolidation fail-closed 拒整理)。 */
+    list(): Promise<Record<string, SessionCaptureOptOutRecord>>;
+}
+export declare class TiDBSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {
+    constructor(pool: MySqlPool);
+}
+export declare class PgSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {
+    constructor(pool: PgPool);
+}
+export declare const TIDB_SESSION_CAPTURE_OPTOUT_STATEMENTS: readonly string[];
+export declare function ensurePgSessionCaptureOptOutSchema(q: PgQueryFn): Promise<void>;
+//# sourceMappingURL=session-capture-record-store-sql.d.ts.map

package/dist/plugins/session-capture-record-store-sql.js

@@ -0,0 +1,110 @@
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { isDupKeyError } from "./sql-errors.js";
+export const SESSION_CAPTURE_OPTOUT_TABLE = "session_capture_optout";
+const UNREADABLE_RECORD_REASON = "capture opt-out record present but unreadable (kept fail-closed)";
+export const SESSION_CAPTURE_KEY_WIDTH = 255;
+export function encodeSessionCaptureKey(sessionId) {
+    return encodeURIComponent(sessionId);
+}
+export function decodeCanonicalSessionCaptureKey(raw) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch (err) {
+        throw new Error(`session capture opt-out roster holds a non-canonical key (undecodable: ${err instanceof Error ? err.message : String(err)}) — refusing the enumeration fail-closed`, { cause: err });
+    }
+    return encodeURIComponent(decoded) === raw ? decoded : undefined;
+}
+function ph(dialect, n) {
+    return dialect === "pg" ? `$${n}` : "?";
+}
+function readAtMs(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v === "string" && /^\d+$/.test(v))
+        return Number(v);
+    if (typeof v === "bigint")
+        return Number(v);
+    return undefined;
+}
+function toRecord(r) {
+    const at = readAtMs(r.at_ms);
+    const reason = r.reason;
+    if (at === undefined || typeof reason !== "string")
+        return { at: 0, reason: UNREADABLE_RECORD_REASON };
+    return { at, reason };
+}
+export class SqlSessionCaptureRecordStore {
+    driver;
+    dialect;
+    constructor(driver, dialect) {
+        this.driver = driver;
+        this.dialect = dialect;
+    }
+    async mark(sessionId, record) {
+        const key = encodeSessionCaptureKey(sessionId);
+        if (key.length > SESSION_CAPTURE_KEY_WIDTH)
+            return "unpersisted";
+        const d = this.dialect;
+        try {
+            await this.driver.query(`INSERT INTO ${SESSION_CAPTURE_OPTOUT_TABLE} (session_id, at_ms, reason) VALUES (${ph(d, 1)}, ${ph(d, 2)}, ${ph(d, 3)})`, [key, record.at, record.reason]);
+            return "created";
+        }
+        catch (err) {
+            if (isDupKeyError(d, err))
+                return "existed";
+            return "unpersisted";
+        }
+    }
+    async read(sessionId) {
+        const key = encodeSessionCaptureKey(sessionId);
+        if (key.length > SESSION_CAPTURE_KEY_WIDTH)
+            return undefined;
+        const res = await this.driver.query(`SELECT at_ms, reason FROM ${SESSION_CAPTURE_OPTOUT_TABLE} WHERE session_id = ${ph(this.dialect, 1)}`, [key]);
+        const row = res.rows[0];
+        if (row === undefined)
+            return undefined;
+        return toRecord(row);
+    }
+    async list() {
+        const res = await this.driver.query(`SELECT session_id, at_ms, reason FROM ${SESSION_CAPTURE_OPTOUT_TABLE} ORDER BY session_id ASC`);
+        const out = Object.create(null);
+        for (const r of res.rows) {
+            const raw = r.session_id;
+            const decoded = typeof raw === "string" ? decodeCanonicalSessionCaptureKey(raw) : undefined;
+            if (decoded === undefined) {
+                throw new Error(`session capture opt-out roster holds a non-canonical key (out-of-band or corrupted row) — refusing the whole enumeration fail-closed: a key that cannot round-trip the canonical encoding cannot be matched against lineage contributors, and a silently passed-through one would let consolidation amplify withheld content`);
+            }
+            out[decoded] = toRecord(r);
+        }
+        return out;
+    }
+}
+export class TiDBSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {
+    constructor(pool) {
+        super(mysqlDriver(pool), "tidb");
+    }
+}
+export class PgSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {
+    constructor(pool) {
+        super(pgDriver(pool), "pg");
+    }
+}
+export const TIDB_SESSION_CAPTURE_OPTOUT_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS ${SESSION_CAPTURE_OPTOUT_TABLE} (
+    session_id VARCHAR(255) NOT NULL,
+    at_ms BIGINT NOT NULL,
+    reason TEXT NOT NULL,
+    PRIMARY KEY (session_id)
+  ) COLLATE utf8mb4_bin`,
+];
+export async function ensurePgSessionCaptureOptOutSchema(q) {
+    await q(`CREATE TABLE IF NOT EXISTS ${SESSION_CAPTURE_OPTOUT_TABLE} (
+    session_id VARCHAR(255) COLLATE "C" NOT NULL,
+    at_ms BIGINT NOT NULL,
+    reason TEXT COLLATE "C" NOT NULL,
+    PRIMARY KEY (session_id)
+  )`);
+}
+//# sourceMappingURL=session-capture-record-store-sql.js.map

package/dist/plugins/session-placement.d.ts

@@ -1,5 +1,5 @@
 /**
- * #292 C18(core 5.48.0 design/323「不造新店」提货批,黑板 [4743] 点名义务)——**subagent 转录持久化**
+ * [ref] C18(core 5.48.0 [ref]「不造新店」提货批,黑板 [ref] 点名义务)——**subagent 转录持久化**
  * 的 placement 语义,SQL 孪生共用的一份判据。
  *
  * ## 这是什么