@sema-agent/server 7.52.0 → 7.53.0

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -15,7 +15,7 @@ import { type SqlDriver } from "./sql-driver.js";
  */
 export declare function writerOfSqlRuleStore(store: PermissionRuleStore): PermissionRuleWriter | undefined;
 /**
- * 382P1(core 7.0.0 design/382 §4.3)—— 这是 **DURABLE 二员面**的 at-rest 形:`{global, project-with-root}`,
+ * 382P1(core 7.0.0 [ref] §4.3)—— 这是 **DURABLE 二员面**的 at-rest 形:`{global, project-with-root}`,
  * 与 core `isValidDurableScope` 逐格等价(`test/permission-rule-durable-face-pin.test.ts` 探针表钉住)。
  * `RuleScope` 联合自 v7 起有第三员 `session`,但它**结构上**不许进持久店(家在会话 overlay,随会话死):
  * at-rest 解码不认它 ⇒ 一条被外部写进来的 session 行整桶拒读(fail-closed),写臂另由 core 的
@@ -32,7 +32,7 @@ export declare const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
  * `tidb-pool.ts` 的 `SCHEMA_STATEMENTS` 用 `...TIDB_PERMISSION_RULE_STATEMENTS` 展开,于是三张表跟着
  * 中央 `ensureSchema` 在 **named-lock 的那条 conn** 上建(同 `TIDB_APPROVAL_ASK_STATEMENTS` 先例)。
  *
- * 列宽依据(#192 A10 的「每列的值由谁铸、有没有入口上限」口径):
+ * 列宽依据([ref] A10 的「每列的值由谁铸、有没有入口上限」口径):
  *  · `owner_key` / `record_id` / `ticket_id` / `approval_id` / `payload_hash` / `checksum` → 190:
  *    全是本仓自铸的键类值(sha256 hex 64 / uuid 36 / `sha256:` 前缀 71),190 是全仓键轴的统一宽度。
  *  · `principal` → 512:principal 入口上限是 `PRINCIPAL_MAX_LENGTH = 190`(`security.ts`),这里给
@@ -46,7 +46,7 @@ export declare const TIDB_PERMISSION_RULE_STATEMENTS: readonly string[];
  *  本函数留给只需要这三张表的集成测试)。 */
 export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise<void>;
 /**
- * #340 升级前置断言 —— **拒启**,不是 warn(codex 交叉复审 [high],验真后修;形照 #119 的
+ * [ref] 升级前置断言 —— **拒启**,不是 warn(codex 交叉复审 [high],验真后修;形照 [ref] 的
  * `assertToolResultProvenanceSchema` 先例)。
  *
  * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升
@@ -57,10 +57,11 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  *    `rule_store_error` —— 裁决照常 200,服务看起来完全健康;
  *  · CC 导入的 prepare 连 pending 记录都落不下;
  *  · 而 `/v1/capabilities` 的 `permissionRules` 仍然报 true ⇒ 本仓「says yes ⟺ route works」整句为假。
- * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 那正是 #157「禁静默降级」要挡的形态。
+ * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 那正是 [ref]「禁静默降级」要挡的形态。
  *
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
- * 只判「两列在不在」,不判宽度(两列都是 TEXT 族,没有截断轴)。
+ * 只判「五列在不在」(command / edited_json / offers_json 三列 TEXT 族 + version / selected_offer 两列
+ * INT),不判宽度(TEXT 族无截断轴,INT 无宽度轴)。
  *
  * 🔴 **只有可证的缺列才给破坏性指路**(codex 交叉复审 round2/round3 [high],两轮收窄后的终形):
  * 「探针失败」**不等于**「列不在」。超时、连接被重置、取消、资源不足、列级权限被拒、表整个不存在 ——
@@ -69,12 +70,12 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  * 终形判据 = **方言的缺列错误码**,一行一方言的闭集(见 {@link isMissingColumnError});其余错误
  * **原样 rethrow**,一个字都不加工。真库两条腿各自跑过这条路径(db-integration 的存量表格),所以
  * 这张码表不是抄手册抄来的,是实测钉住的。
- * 🔴 位置与 #119 同款:**不在** `ensureSchema` 里(那条通道的契约是「只发 CREATE」,有运行时门看着),
+ * 🔴 位置与 [ref] 同款:**不在** `ensureSchema` 里(那条通道的契约是「只发 CREATE」,有运行时门看着),
  * 放在 DDL 之后、任何路由装配之前 —— 还没开始服务,拒启的意义仍在;且**只在规则车道真会被装配时**跑
  * (`PERMISSION_RULES_ENABLED=false` 的部署根本不碰这张表,为它拒启是纯误伤,见调用点)。
  */
 /**
- * 「这个错误**是**『列不存在』吗」——判据属主自 #363 起收在 `sql-errors.ts`(与 `isDupKeyError` 同族、
+ * 「这个错误**是**『列不存在』吗」——判据属主自 [ref] 起收在 `sql-errors.ts`(与 `isDupKeyError` 同族、
  * 同理由:识别集复制一次就会漂,而这条谓词守的是一句**破坏性**指路)。本文件此前那份逐字实现已下车,
  * 语义一个字不变(闭集与 fail-safe 方向逐字见那边的头注)。
  */
@@ -82,7 +83,7 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
     rows: Record<string, unknown>[];
 }>, dialect: "tidb" | "pg"): Promise<void>;
 /**
- * #265 A7 升级前置断言 —— **拒启**(形与理由逐字照 {@link assertPermissionRuleApprovalSchema} 的配方,
+ * [ref] A7 升级前置断言 —— **拒启**(形与理由逐字照 {@link assertPermissionRuleApprovalSchema} 的配方,
  * 那条头注写了这道门为什么必须是拒启而不是 warn:本仓不发 `ALTER TABLE`,`CREATE TABLE IF NOT EXISTS`
  * 对存量表是空操作,而新列被**无条件**引用)。
  *
@@ -172,7 +173,7 @@ export interface RuleImportTicket {
     expiresAtMs: number;
 }
 /**
- * #265 A7 —— 一张票是**哪条导入车道**铸的(codex 交叉轮 R1-F2,验真后修)。
+ * [ref] A7 —— 一张票是**哪条导入车道**铸的(codex 交叉轮 R1-F2,验真后修)。
  *
  * 🔴 闭集且**不可变**:两条车道共用这张表,而它们的票语义刻意不同(cc-import 一次性 / local-import
  * 可恢复三态)。票不带这一位时,两条车道的兑付口互相**可以吃对方的票** —— 那不是"多一条路",那是让
@@ -195,7 +196,7 @@ export type RuleTicketRedeemResult = {
     reason: "unknown" | "wrong-principal" | "wrong-purpose" | "expired" | "consumed";
 };
 /**
- * [4232]③/[4235]③ —— 票的**判定钟**覆写(记账钟永远不覆写,见 `consume` 内注)。
+ * [ref]③/[ref]③ —— 票的**判定钟**覆写(记账钟永远不覆写,见 `consume` 内注)。
  *
  * 缺席 = 墙钟,既有行为逐字不变。在场 = 调用方(同意车道)按**单调锚**投影出来的那个时刻:
  * 铸票时刻的墙钟 + 自铸票起单调钟走过的量。它只能让判定更贴近**真实经过的时间**,给不了票额外寿命
@@ -205,7 +206,7 @@ export interface RuleTicketDecisionClock {
     decisionNowMs?: number;
 }
 /**
- * #265 A7 —— 一张票的**三态快照**(MINTED → CLAIMED → SETTLED)。
+ * [ref] A7 —— 一张票的**三态快照**(MINTED → CLAIMED → SETTLED)。
  *
  * 🔴 判别式联合而不是"一个态字符串 + 两个可选字段":三个态各自带的东西**互不相干**,而消费方对三者
  * 要做的事完全不同(首兑 / 判租约 / 逐字回放)。塌成一个可选包会让"已落定却读不出终局"这种矛盾态
@@ -213,7 +214,7 @@ export interface RuleTicketDecisionClock {
  * 对属主说一次谎)。
  *
  * `claimAgeMs` 由**店自己**用它的记账钟算,不交给调用方去减:认领戳(`consumed_at_ms`)是真墙钟,
- * 而车道手里那只是单调投影 —— 两只钟不在同一个域,跨域相减出来的"年龄"没有意义(本仓 [4232]③ 的
+ * 而车道手里那只是单调投影 —— 两只钟不在同一个域,跨域相减出来的"年龄"没有意义(本仓 [ref]③ 的
  * 教训:两只钟必须分家,谁的问题谁的钟答)。
  */
 export type RuleTicketSnapshot = {
@@ -226,7 +227,7 @@ export type RuleTicketSnapshot = {
     outcome: unknown;
 };
 /**
- * #265 A7 —— 抢认领的结果。赢家拿回**票上那两样不可变的东西**(`approval_id` / `payload_hash`),
+ * [ref] A7 —— 抢认领的结果。赢家拿回**票上那两样不可变的东西**(`approval_id` / `payload_hash`),
  * 与 {@link RuleTicketRedeemResult} 的成功臂同形:抢到认领之后要做的事与首次认领之后**一模一样**
  * (读记录 → 载荷比对 → 走批),所以两条路必须交出同一份素材,否则恢复臂就得自己再发一条读 ——
  * 而"认领之后还有一次可能失败的 I/O"正是本仓 round4 修掉的那个形。
@@ -242,27 +243,28 @@ export type RuleTicketReclaimResult = {
     ok: false;
 };
 /**
- * [4232]③ 同族的 **GC 宽限**:`reapExpired` 只收「按墙钟至少已死一个完整 TTL」的票行。
+ * [ref]③ 同族的 **GC 宽限**:`reapExpired` 只收「按墙钟至少已死一个完整 TTL」的票行。
  *
  * 为什么需要它:判定侧改单调锚之后,一张「按墙钟已过期、按单调钟还在窗内」的票是**可兑付**的;
  * 若 GC 仍按 `expires_at_ms <= now` 收行,判定修好了而行先没了 —— 用户拿到的从 `expired` 变成 `unknown`,
- * 缺陷只是换了个归因。宽限一个 TTL 覆盖住「铸票时钟慢了不到一个 TTL」这一族(含 [4232]③ 的真实构造)。
+ * 缺陷只是换了个归因。宽限一个 TTL 覆盖住「铸票时钟慢了不到一个 TTL」这一族(含 [ref]③ 的真实构造)。
  *
  * 残余(如实登记,不假称已解):墙钟被拨慢**超过**一个 TTL 时,行仍可能在单调窗内被收。彻底解需要行上
- * 存单调基准,而单调基准跨进程无意义(core [4235] 的判词)。补偿是现成的:prepare 廉价,重铸一张即可
+ * 存单调基准,而单调基准跨进程无意义(core [ref] 的判词)。补偿是现成的:prepare 廉价,重铸一张即可
  * ——这正是 core 建议的姿态(「接受 + 票廉价重铸」)。
  */
 export declare const RULE_IMPORT_TICKET_GC_GRACE_MS: number;
 /**
- * #265 A7 —— **数据库自己的钟**(毫秒),两方言各一句(codex 交叉轮 R5-F1,验真后修)。
+ * [ref] A7 —— **数据库自己的钟**(毫秒),两方言各一句(codex 交叉轮 R5-F1,验真后修)。
  *
  * 用处:`settled_at_ms` 的写入与清扫「已落定」那一支的截止**必须在同一个钟域**。它们此前各拿各副本的
- * 墙钟:落定那台若比跑清扫那台慢过一个宽限(本仓 [4232]③ 记过一次真实的 11 分钟 NTP 纠正),一份**刚刚**
+ * 墙钟:落定那台若比跑清扫那台慢过一个宽限(本仓 [ref]③ 记过一次真实的 11 分钟 NTP 纠正),一份**刚刚**
  * 生出来的权威回执下一拍就被删,而"落定之后必有一个完整的回放窗"是本批新许下的承诺 —— 它不能建立在
  * 「两台机器的钟差不多」这条没人声明过的假设上。数据库的钟是这两台副本**唯一**共享的那口钟。
  *
- * 🔴 射程**刻意只到这一支**:票的其余三列(`expires_at_ms` / `consumed_at_ms` / `created_at_ms`)仍在
- * 既有的副本墙钟域里 —— 那是 cc-import 车道的**既存已登记残余**([4232]③,收口方向逐字见
+ * 🔴 射程更新(车K 2026-08-30 对账):`consumed_at_ms` 自 R8-F2 起**也走本钟**(`consume` 的 UPDATE
+ * 直写本常量,见其行注);仍留在副本墙钟域的是 `expires_at_ms` / `created_at_ms` 两列 —— 那是
+ * cc-import 车道的**既存已登记残余**([ref]③,收口方向逐字见
  * `rules-consent.ts` 的 anchors 头注),把它一并搬走会改动两条车道共用的认领谓词,不在本批射程。
  * 这一句同时也是那次收口的**样板**:形已经在这里了,下一批照抄即可。
  */
@@ -292,8 +294,8 @@ export declare class SqlRuleImportTicketStore {
         ttlMs: number;
     }): Promise<RuleImportTicket>;
     /**
-     * **一次性原子认领**(F1 ③)。四个条件全部写在 `WHERE` 里 —— ticket 身份、principal 绑定、未过期、
-     * 未认领 —— 于是并发双 redeem 由引擎的行锁裁决,恰一条 `affected === 1`。
+     * **一次性原子认领**(F1 ③)。五个条件全部写在 `WHERE` 里 —— ticket 身份、principal 绑定、车道绑定
+     * (purpose,A7 R1-F2)、未认领、未过期 —— 于是并发双 redeem 由引擎的行锁裁决,恰一条 `affected === 1`。
      *
      * 🔴 **认领的 UPDATE 是这条方法的最后一次 I/O**(codex 交叉复审 round4 [high],验真后修)。
      * 旧形是「先 UPDATE 认领、再 SELECT 取 approvalId/payloadHash」——那条 SELECT 失败时本方法**抛错**,
@@ -302,8 +304,8 @@ export declare class SqlRuleImportTicketStore {
      * `approval_id` / `payload_hash` 自铸票起就是**不可变**列,先读与后读读到的是同一份字节。
      *
      * 🔴 **这仍然不是 read-then-write**(禁令的语义没有松动):**裁决**依旧只由那条条件 `UPDATE` 的
-     * `WHERE` 做出 —— 预读的三条否定项只用来**短路 + 归因**(把拒绝分成 unknown/wrong-principal/
-     * expired/consumed 四类给服务端日志;wire 面把四类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
+     * `WHERE` 做出 —— 预读的五条否定项只用来**短路 + 归因**(把拒绝分成 unknown/wrong-principal/
+     * wrong-purpose/expired/consumed 五类给服务端日志;wire 面把五类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
      * 只可能是我们在这两跳之间输给了一个并发认领者 —— 如实报 `consumed`,而不是把这次失败当成成功。
      */
     consume(ticketId: string, principal: string, purpose: RuleTicketPurpose, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
@@ -325,7 +327,7 @@ export declare class SqlRuleImportTicketStore {
      */
     release(ticketId: string, principal: string, claimId: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
     /**
-     * #265 A7 —— CLAIMED → **SETTLED**:把这一次兑付的终局写进行里。
+     * [ref] A7 —— CLAIMED → **SETTLED**:把这一次兑付的终局写进行里。
      *
      * 🔴 判据全写在 `WHERE` 里(与 `consume` 同一条纪律,**禁 read-then-write**):必须**持有认领**
      * (`consumed_at_ms IS NOT NULL`)且**尚未落定**(`redeemed_outcome IS NULL`)。两个写者同时到达时
@@ -338,14 +340,14 @@ export declare class SqlRuleImportTicketStore {
      */
     settle(ticketId: string, principal: string, claimId: string, outcome: unknown): Promise<boolean>;
     /**
-     * #265 A7 —— 读一张票的三态。**principal 绑定**与四类拒同源:别人的票 / 不存在的票一律 `undefined`
+     * [ref] A7 —— 读一张票的三态。**principal 绑定**与四类拒同源:别人的票 / 不存在的票一律 `undefined`
      * (调用方把它折成同一个 404,零存在性 oracle)。
      *
      * `claimAgeMs` 在**这里**算(店的记账钟),不交给调用方:见 {@link RuleTicketSnapshot} 的头注。
      */
     peek(ticketId: string, principal: string, purpose: RuleTicketPurpose): Promise<RuleTicketSnapshot | undefined>;
     /**
-     * #265 A7 —— **崩溃窗恢复**:把一次**可证陈旧**的认领抢过来。
+     * [ref] A7 —— **崩溃窗恢复**:把一次**可证陈旧**的认领抢过来。
      *
      * 病:`consume` 之后、`settle` 之前硬崩,票停在 CLAIMED 且永远不会自己走完。旧形(cc-import)对这
      * 一格没有答案 —— 票随 TTL 消失,人的确认丢掉;而 `release` 帮不上忙,它要求那个死掉的进程**还活着
@@ -373,7 +375,7 @@ export declare class SqlRuleImportTicketStore {
     private readRow;
 }
 /**
- * 孤儿 pending 审批记录的保留期(A-010.17)。
+ * 孤儿 pending 审批记录的保留期([ref])。
  *
  * 判据是「**可证已死**」,不是一个拍脑袋的时长:一条 pending 记录只能经 `redeemRuleTicket` 走活,
  * 而兑付要么发生在铸它的**那一次请求内**(`persistCardRule` 的 prepare→confirm→redeem 三步同请求),
@@ -406,7 +408,7 @@ export interface PermissionRuleStores {
     provider: SqlPermissionRuleStoreProvider;
     approvals: SqlRuleApprovalRecordStore;
     tickets: SqlRuleImportTicketStore;
-    /** #203 §3 —— boot 期休眠行审计的**窄读口**:库里已有几只桶(`permission_rule` 一行一桶)。
+    /** [ref] §3 —— boot 期休眠行审计的**窄读口**:库里已有几只桶(`permission_rule` 一行一桶)。
      *
      *  🔴 为什么数**桶**而不是数**规则**:数规则要把每一行的 `rules_json` 都读回来再解析(一只桶的规则集
      *  没有硬上限,顶注 §列宽依据已说明它是 LONGTEXT),那是一次无界的 boot 期扫描 —— 为一条诊断行付这个
@@ -414,7 +416,7 @@ export interface PermissionRuleStores {
      *  索引级 `COUNT(*)`。消费点(`boot/permission-rules-audit.ts`)的文案因此逐字说的是 bucket,不是 rule。 */
     countBuckets(): Promise<number>;
     /**
-     * 保留期腿(A-010.17)。返回删掉的**总行数**(两张表合计),给 reaper 的 `reapCount` 用。
+     * 保留期腿([ref])。返回删掉的**总行数**(两张表合计),给 reaper 的 `reapCount` 用。
      *
      * 病:这两张表此前**没有任何 retention 腿**,而它们都是只进不出的:
      *  · `permission_rule_ticket` —— 每一次 `POST /v1/rules/cc-import/prepare` 落一行,不管有没有人去
@@ -424,9 +426,12 @@ export interface PermissionRuleStores {
      *    没按确认」这条最常见的人类路径,每走一次留一条永远没人要的行(`discardPendingRecord` 只收
      *    「超帽当场拒」那一条路,不收「人改主意了」)。
      *
-     * 两条谓词都只删**可证已死**的行,所以本腿不需要旋钮(没有可调的语义):
-     *  · 票:`expires_at_ms <= now` —— `consume` 的硬条件是 `expires_at_ms > now`,过期票已不可兑付;
-     *  · 记录:`state = 'pending' AND created_at_ms < now − {@link RULE_PENDING_APPROVAL_RETENTION_MS}`。
+     * 两张表的谓词都只删**可证已死**的行,所以本腿不需要旋钮(没有可调的语义):
+     *  · 票(三支 OR,A7 交叉复审定形,逐支论证见 reapExpired 实现内注):甲=从未认领且已过期;
+     *    乙=已落定且落定后过 GC 宽限(按 `settled_at_ms` 判,走 DB 钟);丙=CLAIMED-未结且认领戳老过
+     *    废弃期(按 `consumed_at_ms` 判,走 DB 钟);
+     *  · 记录:`state = 'pending' AND created_at_ms < now − {@link RULE_PENDING_APPROVAL_RETENTION_MS}`,
+     *    再加 `NOT EXISTS`(载荷必须陪着把手活,R6-F1:仍有票引用的 pending 记录不删)。
      */
     reapExpired(nowMs: number): Promise<number>;
 }

package/dist/plugins/permission-rule-store-sql.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
+import { canonicalJson } from "../canonical-json.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -80,10 +81,14 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     tombstones_json LONGTEXT NOT NULL,
     quarantined_json LONGTEXT NOT NULL,
     -- observed_vector_json:同步游标面(design/182 §5.1 的观测向量)。整读整写的 JSON blob——
-    -- core 明令不得拆成一 actor 一行(会让「半个更新」变得可表达)。
+    -- core 明令不得拆成一 actor 一行(会让「半个更新」变得可表达)。⚠️ 现状如实(车K 2026-08-30 亲核):
+    -- 本店**零 UPDATE 写口**(ensureBucket 恒插 NULL,cas 的 SET 不含此列)⇒ 该列今日恒 NULL;读侧
+    -- (read 的 parse、checksum 的 observedVector 参与位)是为它备的座。「是否该有写口」已登记候裁,
+    -- 裁前不添写口、不删读座。
     observed_vector_json LONGTEXT NULL,
     last_round_at_ms BIGINT NULL,
-    -- checksum:core \`ruleStoreChecksum\` 同精神的完整性指纹(**只覆盖内容三列**,不含 rev/counter)。
+    -- checksum:core \`ruleStoreChecksum\` 同精神的完整性指纹(覆盖内容三列 + observed_vector 在场时的
+    -- 观测向量,不含 rev/counter——算法单点=buildRuleBucketChecksum)。
     -- 读回不符 ⇒ throw(绝不静默当空店 —— core 对读失败的姿势明令如此)。
     checksum VARCHAR(190) NOT NULL,
     created_at_ms BIGINT NOT NULL,
@@ -303,16 +308,6 @@ export function buildRuleOwnerKey(owner) {
 export function buildRuleBucketChecksum(body) {
     return `sha256:${createHash("sha256").update(canonicalJson(body), "utf8").digest("hex")}`;
 }
-function canonicalJson(v) {
-    if (v === null || typeof v !== "object")
-        return JSON.stringify(v) ?? "null";
-    if (Array.isArray(v))
-        return `[${v.map(canonicalJson).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)}:${canonicalJson(val)}`).join(",")}}`;
-}
 const NEXT_DOT_MAX_ATTEMPTS = 8;
 const EMPTY_BUCKET = { actor: "", counter: 0, rev: 0, rules: [], tombstones: [], quarantined: [] };
 function parseColumn(schema, raw, column, ownerKey) {

package/dist/plugins/pg-cost-quota.d.ts

@@ -5,7 +5,7 @@
  * bucket), PostgreSQL dialect instead of MySQL/TiDB. The two are kept in lock-step by ONE shared real-DB
  * integration suite (test/pg-cost-quota-integration.test.ts) running the SAME scenarios on BOTH engines.
  *
- * design/158 A12 C1b: this file used to carry a PRIVATE inline copy of the write-behind counter, hardwired
+ * [ref] A12 C1b: this file used to carry a PRIVATE inline copy of the write-behind counter, hardwired
  * to the `cost_quota` columns — the third copy of the same 150 lines. It is gone; both dialects now share
  * ONE dialect-parameterized implementation (write-behind-counter.ts), and the dialect deltas this header
  * used to enumerate ($n placeholders / ON CONFLICT increment / rowCount / BIGINT-as-string) are documented
@@ -16,7 +16,7 @@ import type { QuotaDecision, QuotaLimits, QuotaTracker } from "../observability/
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class PgCostQuota implements QuotaTracker {
     private readonly counter;
-    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
+    /** [ref]:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
     private limitMicroUsd;
     private refreshRequested;
     private refreshIntervalMs;

package/dist/plugins/pg-pool.js

@@ -9,6 +9,7 @@ import { ensureSchema as ensureImageIndexSchema } from "./image-index-sql.js";
 import { ensurePgImageBakeSchema as ensureImageBakeSchema } from "./image-bake-store-sql.js";
 import { ensurePgApprovalAskSchema } from "./approval-ask-store-sql.js";
 import { ensurePgMemoryOptOutGrantSchema } from "./memory-optout-grant-store-sql.js";
+import { ensurePgSessionCaptureOptOutSchema } from "./session-capture-record-store-sql.js";
 import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
 import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
@@ -90,6 +91,9 @@ export const PG_SCHEMA_STATEMENTS = [
      -- rule_suggestions:语义、铸行侧的窄读/脱敏/截断纪律、以及「NULL = 无供给 ⇒ 读口省键」的完整由来见
      -- MySQL 孪生(tidb-pool.ts 同名列的行内注)。
      rule_suggestions TEXT COLLATE "C",
+     -- has_bidi_controls(S-30① / #356②):bidi 在场位,语义与「1 或 NULL、恒不写 0」见 MySQL 孪生同名列的
+     -- 行内注。clay 批 TINYINT(1) 归一先例:PG 侧统一 SMALLINT。
+     has_bidi_controls SMALLINT,
      PRIMARY KEY (token)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_checkpoint_status_deadline ON checkpoint (status, deadline)`,
@@ -364,6 +368,7 @@ export async function ensurePgSchema(pool) {
         await ensureImageBakeSchema(client);
         await ensurePgApprovalAskSchema((text, params) => client.query(text, params));
         await ensurePgMemoryOptOutGrantSchema((text, params) => client.query(text, params));
+        await ensurePgSessionCaptureOptOutSchema((text, params) => client.query(text, params));
         await ensurePgAdoptionLogSchema((text, params) => client.query(text, params));
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
         await ensurePgLeaderRunSchema((text, params) => client.query(text, params));

package/dist/plugins/pg-query.d.ts

@@ -4,7 +4,7 @@
  *
  * HISTORY: this type used to be re-exported by `@sema-agent/core` from its pg REFERENCE adapter. core 1.424.0
  * removed the whole example-adapter export surface from the npm package (clay's package-hygiene ruling,
- * board [1803] — examples are in-repo samples, not user API). The type itself is server-owned wiring, so it
+ * board [ref] — examples are in-repo samples, not user API). The type itself is server-owned wiring, so it
  * moved here VERBATIM (same shape as core 1.423's `examples/adapters/pg-adapter.d.ts`); six plugins consume it.
  */
 export interface PgQueryResult {

package/dist/plugins/pg-rate-limiter.d.ts

@@ -6,7 +6,7 @@
  * (eventually consistent: a replica may briefly admit a few requests over the ceiling at a window
  * boundary before peers' counts propagate).
  *
- * design/158 A12 C1b: the `PgWriteBehindCounter` this file used to define inline now lives in
+ * [ref] A12 C1b: the `PgWriteBehindCounter` this file used to define inline now lives in
  * write-behind-counter.ts as the PG binding of ONE dialect-parameterized counter (the mysql2 twin is
  * `WriteBehindCounter`); the SQL-dialect deltas are documented and branched there.
  *
@@ -18,7 +18,7 @@ import type { RateDecision, RateGate, RateLimits } from "../observability/rate-l
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class PgRateLimiter implements RateGate {
     private readonly counter;
-    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
+    /** [ref]:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
     private limit;
     private refreshRequested;
     private refreshIntervalMs;

package/dist/plugins/pg-session-storage.d.ts

@@ -24,7 +24,7 @@ export declare class PgSessionStorage extends BaseSessionStorage {
     private readonly sessionId;
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
-    /** @see TiDBSessionStorage.getEpochAnchor — [976] S3 RB-14 pull seam, PG dialect twin
+    /** @see TiDBSessionStorage.getEpochAnchor — [ref] S3 [ref] pull seam, PG dialect twin
      *  (keyset-paged to exhaustion: a bounded scan over restatement-less pre-epoch compactions would
      *  misreport an epoch-bearing session as pre-epoch — codex HIGH). */
     getEpochAnchor(): Promise<PromptEpochDescriptor | undefined>;
@@ -49,9 +49,9 @@ export declare class PgSessionStorage extends BaseSessionStorage {
  */
 export declare class PgSessionStore implements SessionStore {
     private readonly pool;
-    /** #270 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    /** [ref] 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
     readonly retention: import("@sema-agent/core").RetentionDeclaration;
-    /** #292 C18(core 5.48.0 design/323):placement 声明(TiDB 孪生同格,义务逐条见
+    /** [ref] C18(core 5.48.0 [ref]):placement 声明(TiDB 孪生同格,义务逐条见
      *  `src/plugins/session-placement.ts` 顶注)。 */
     readonly placements: {
         readonly subagent: {
@@ -64,11 +64,11 @@ export declare class PgSessionStore implements SessionStore {
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
     /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
-     *  #292:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
+     *  [ref]:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
     register(sessionId: string, owner: string | null, placement?: SessionPlacement): Promise<void>;
-    /** #292 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
+    /** [ref] 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
-    /** #292 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
+    /** [ref] 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
      *  见 {@link TiDBSessionStore.listPlaced})。 */
     listPlaced(kind: "subagent", opts?: {
         olderThanMs?: number;
@@ -80,20 +80,20 @@ export declare class PgSessionStore implements SessionStore {
     /** E18 — the session's current leaf SessionTreeEntry.id (session_meta.leaf_id). @see TiDBSessionStore.getLeafId
      *  (single SELECT, no acquire/lock, cache-bypassing — safe to read mid-run for the resume-at turn-capture). */
     getLeafId(sessionId: string): Promise<string | null>;
-    /** [1196] 六轮复审:owner+leafId 单行原子快照(@see TiDBSessionStore.getHead——混世代组合防)。 */
+    /** [ref] 六轮复审:owner+leafId 单行原子快照(@see TiDBSessionStore.getHead——混世代组合防)。 */
     getHead(sessionId: string): Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
     /** Durable history is retained; just drop any in-flight cache entry.
-     *  🔴 #292 义务 4:**placed 会话例外 —— release 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
+     *  🔴 [ref] 义务 4:**placed 会话例外 —— release 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
      *  {@link TiDBSessionStore.release},本腿是它的 PG 孪生)。 */
     release(sessionId: string): Promise<void>;
     /** @see TiDBSessionStore.forget — 丢引用不动 durable 史(preflight 纪律的落点;PG 孪生)。 */
     forget(sessionId: string): void;
     /** @see TiDBSessionStore.deletePlacedSession — PG 孪生(条件删门 + meta 先删 + 失败上浮同义)。 */
     private deletePlacedSession;
-    /** #292:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
+    /** [ref]:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
     private assertNotPlaced;
     /** @see TiDBSessionStore.listSessions — session identity from session_meta (owner-filtered), task_run LEFT JOIN for preview. */
     listSessions(opts: {

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

@@ -23,7 +23,7 @@ type ConnectResult = {
     error: RemoteExecutionError;
 };
 /**
- * Test seam (design/61 §9.3 fault-injection): inject `spawn` and/or a `connectOnce` that replays an error
+ * Test seam ([ref] §9.3 fault-injection): inject `spawn` and/or a `connectOnce` that replays an error
  * sequence, so the retry policy + first-attach behaviour is deterministically testable without a real device
  * (the E2B-adapter bug that only surfaced in dogfood is the lesson this guards against).
  */

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

@@ -12,7 +12,7 @@ type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
  * 设备**结局帧**的错误码 → core `FileErrorCode`。
  *
  * `Record<DeviceOutcomeErrorCode, …>` 是**穷举**的:协议的结局码闭集加词而此处不加行 = 编译红
- * (#157 词表纪律;不是运行时 switch 的默认臂)。
+ * ([ref] 词表纪律;不是运行时 switch 的默认臂)。
  *
  * 🔴 三条不许折错的线:
  *  ① `outcome_unknown` **原样过境**——core 把它排除在 `RETRYABLE_REMOTE_ERROR_CODES` 之外正是为了
@@ -88,7 +88,7 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
         suspendable: boolean;
     };
     readonly externalContentTarget = true;
-    /** #211:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
+    /** [ref]:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
     readonly hostLocalPaths = false;
     cwd: string;
     /** 可选面(presence-typed,见文件头「铁律」段):构造期按设备声明装配,缺席就是缺席。 */

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

@@ -1,13 +1,13 @@
 /**
  * `RemoteContainerExecutionEnv` — the E2B implementation of core's `RemoteExecutionEnv` seam
- * (core src/core/remote-env.ts, design/48 §5). The service control plane owns this backend; core
+ * (core src/core/remote-env.ts, [ref] §5). The service control plane owns this backend; core
  * owns the seam shape (exactly like `CheckpointStore` / `SqlExecutor`).
  *
- * **Scope = design/48 §0.5 v1 minimal slice**: single worker, E2B managed, **Tier 2 only** (every
+ * **Scope = [ref] §0.5 v1 minimal slice**: single worker, E2B managed, **Tier 2 only** (every
  * op runs in a per-task E2B Firecracker VM — no tiering/classification), and the ~4 live seam methods
  * `connect` / `execStream` / `workspaceHandle` / `destroy` + the base `ExecutionEnv` (FileSystem + Shell).
  *
- * **v1.5 (design/49, core 1.69):** `suspendVM` (E2B `pause()`) / `resumeVM` (`Sandbox.connect(id)` auto-resume)
+ * **v1.5 ([ref], core 1.69):** `suspendVM` (E2B `pause()`) / `resumeVM` (`Sandbox.connect(id)` auto-resume)
  * / `postResumeInit` (reachability + at-rest-encryption red line) are IMPLEMENTED — core orchestrates them when
  * a task with this remote env hits a durable-approval `ask` (workspaceHandle → Checkpoint.state). `reconnect`
  * (cross-replica re-attach to a still-running VM) stays deferred to **v2** (v1.5 always snapshots → resumeVM).
@@ -48,7 +48,7 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
     /** Sandbox metadata (e.g. sessionId/taskId for fleet observability). */
     metadata?: Record<string, string>;
     /**
-     * 🔴 Out-of-band secret/config env injected sandbox-WIDE at create (design/48 §5 gap 7, OA Phase-B): every
+     * 🔴 Out-of-band secret/config env injected sandbox-WIDE at create ([ref] §5 gap 7, OA Phase-B): every
      * command + background process in the VM sees these, but the VALUES never enter the model prompt, the tool
      * `command` string, or the durable event log (which only records the command `args`, redacted). This is the
      * channel for a credential (e.g. a git token the agent uses via GIT_ASKPASS / a credential helper) WITHOUT
@@ -84,7 +84,7 @@ export interface RemoteContainerEnvDeps {
  * FIRST FileSystem/Shell/execStream call (auto `connect()`), so a task that never touches the hand pays zero
  * cost. `connect()` may still be called explicitly (idempotent + concurrency-memoized) if the control plane
  * wants to provision eagerly. `destroy()` on task end (the Runner calls it via `hasDestroy`); a never-used env's
- * destroy is a no-op (nothing to kill, no bill). One container per task (design/48 §5 §7 Q7).
+ * destroy is a no-op (nothing to kill, no bill). One container per task ([ref] §5 §7 Q7).
  */
 export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /** Current working directory for relative paths (FileSystem contract; mutable, core may reassign). */
@@ -113,7 +113,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  SAME env instance skips the reconnect and every later fs/exec runs against the dead VM. */
     private paused;
     constructor(config: RemoteContainerEnvConfig, deps?: RemoteContainerEnvDeps);
-    /** design/61 §9: E2B is a FULL RemoteExecutionEnv — an isolated, snapshot-suspendable microVM. (SSH/ADB
+    /** [ref] §9: E2B is a FULL RemoteExecutionEnv — an isolated, snapshot-suspendable microVM. (SSH/ADB
      *  adapters declare {isolation:false, suspendable:false} — real machines/devices, not snapshotable.) */
     readonly capabilities: {
         isolation: boolean;
@@ -122,13 +122,13 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     workspaceHandle(): WorkspaceHandle;
     /**
      * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
-     * (design/64 §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
+     * ([ref] §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
      * provisions the VM (like exec/fs); `undefined` if it can't connect → the LSP manager degrades.
      */
     getHost(port: number): Promise<string | undefined>;
     /**
      * Launch a long-running process as a TRUE E2B background command (resolves once launched, E2B keeps it alive)
-     * — for the LSP bridge (design/64 §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
+     * — for the LSP bridge ([ref] §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
      * command's process group on completion, which would kill an in-shell `&`/nohup child. Fire-and-forget.
      */
     startBackground(command: string): Promise<void>;
@@ -141,7 +141,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     }>;
     private doConnect;
     /**
-     * v1.5 (design/49): snapshot the workspace via E2B `pause()` (stores fs+memory+process; the snapshot id IS
+     * v1.5 ([ref]): snapshot the workspace via E2B `pause()` (stores fs+memory+process; the snapshot id IS
      * the sandbox id — a paused E2B sandbox is resumed by its id). Atomic contract (council): on failure the VM
      * is left UNTOUCHED (still running) so core can fall back to onAsk. Refuses if a command is in flight
      * (council #4) — never silently snapshot a running command. `abortSignal` bounds a hung pause (council BUG#2).
@@ -167,7 +167,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         error: RemoteExecutionError;
     }>;
     private doResumeVM;
-    /** Cross-replica re-attach to a still-running VM = v2 (design/49 council #15: v1.5 always snapshots→resumeVM). */
+    /** Cross-replica re-attach to a still-running VM = v2 ([ref] council #15: v1.5 always snapshots→resumeVM). */
     reconnect(_sessionToken: SessionToken): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -295,7 +295,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private remoteError;
 }
 /**
- * Build the deployment-level `RunnerDeps.executionEnvFactory` (design/48 v1b). Wiring this onto a
+ * Build the deployment-level `RunnerDeps.executionEnvFactory` ([ref] v1b). Wiring this onto a
  * deployment makes it a "code-agent worker": every task's hand runs in a per-task E2B VM. Deployments that do
  * NOT set this (e.g. OA / review) keep the in-process stub env — routing is **deployment-level** (the factory
  * ctx carries only sessionId/taskId, never a service scenario; that stays out of the generic core seam).

package/dist/plugins/remote-env-file-error.d.ts

@@ -11,7 +11,7 @@
  * 会把**已被取消的操作再打一遍**。host 腿没有这个问题,因为它直接用 `fs` + 自己的分类器
  * (AbortError → `aborted`)—— 也就是说这 4 条腿丢的正是 host 腿有的那个信息。
  *
- * 做成**一个共享函数而不是各腿各修一处**的理由:这一族有 28 个包装点,逐处修必然漏(core [1689] RB-74
+ * 做成**一个共享函数而不是各腿各修一处**的理由:这一族有 28 个包装点,逐处修必然漏(core [ref] [ref]
  * 那条教训:宣布"类修完成"而三个实现只落了一个)。收成一处之后,判据只有一条 ——
  * **文件面的 exec 包装必须走这里**,而这条能被机器检查(见 `test/env-adapter-file-error-parity.test.ts`)。
  */
@@ -19,7 +19,7 @@ import { FileError, type ExecutionError, type RemoteExecutionError } from "@sema
 /** exec 层的错误码 → 文件层的码。只映射**有对应语义**的那些,其余落 `unknown`(诚实降级)。 */
 export declare function fileErrorFromExec(e: ExecutionError | RemoteExecutionError, path?: string): FileError;
 /**
- * shell 命令 exit≠0 时把 **stderr** 分类成 `FileError` 的共享分类器(design/158 B6 R2 裁决:k8s 形=正形)。
+ * shell 命令 exit≠0 时把 **stderr** 分类成 `FileError` 的共享分类器([ref] B6 R2 裁决:k8s 形=正形)。
  *
  * 此前四腿三向分叉:ssh/adb 硬编码 `not_found`(把 EACCES 谎报成"不存在"——keyed-on-code 的调用方会
  * 对一个权限问题走"不存在"分支);local-docker 分类但无 fallback(缺文件报 unknown),且其

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

@@ -39,16 +39,16 @@ export interface HostEnvConfig {
      */
     workspaceDir?: string;
     /** R7 self-wake: the injected `SchedulerCapability` backend (the TOC self-wake scheduler write side).
-     *  When set, `hasScheduler(env)` is true and core mounts CronCreate/CronDelete/CronList(旧名 CronCancel;Sleep 已 design/136 撤除;挂载在 prepare-task 非 createHandsToolkit——L8 订正); when absent the env
+     *  When set, `hasScheduler(env)` is true and core mounts CronCreate/CronDelete/CronList(旧名 CronCancel;Sleep 已 [ref] 撤除;挂载在 prepare-task 非 createHandsToolkit——L8 订正); when absent the env
      *  reports `supported:false` → INERT (no scheduler tools). Injected at boot only on the single-user host lane. */
     scheduler?: SchedulerCapability;
-    /** design/103 background shell: `false` → INERT (multi-tenant host lane gate). Default (undefined) = on for the
+    /** [ref] background shell: `false` → INERT (multi-tenant host lane gate). Default (undefined) = on for the
      *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(🪦 旧名
      *  `HOST_BG_DISABLED` 自 server 3.0.0 起是 fail-loud 墓碑:设了即拒启并指路新名,不再被读取)。 */
     backgroundShell?: boolean;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
-    /** design/61 §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
+    /** [ref] §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
@@ -70,7 +70,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private prepared;
     /** Terminal once {@link destroy} ran — guards fs/exec from running against a removed workspace. */
     private destroyed;
-    /** [1116] 五轮复审:fg/bg spool 根=tmpdir 私有目录(core bgSpoolDir 同形)。workspace 是命令可写区,
+    /** [ref] 五轮复审:fg/bg spool 根=tmpdir 私有目录(core bgSpoolDir 同形)。workspace 是命令可写区,
      *  `git clean -fdx` 类清理会 unlink 活跃 spool(子进程经继承 fd 对 unlinked inode 继续写,而父进程
      *  按路径 statSync/read 静默断=输出丢失+轮转帽失效);顺带不再弄脏 user-owned workspace(TOC/CC
      *  persistent 形)。懒建;destroy 整树清。 */
@@ -78,7 +78,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     /** 🔴 在飞的 fg spool 目录登记表(2026-07-25)。`destroy()` 原来只看 `bgManager.hasShells()` 就 `rm -rf`
      *  spool 根 —— 而**前台** exec 的 spool 也在同一个根下,子进程通过继承的 fd 继续往已 unlink 的 inode 写,
      *  父进程按**路径** stat/read 于是什么都看不到 ⇒ 命令照跑、副作用照落盘,但 stdout 被静默截断,还返回
-     *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core RB-73 同形:写已释放的 inode。)
+     *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core [ref] 同形:写已释放的 inode。)
      *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     private readonly liveFgSpools;
     private ensureSpoolRoot;
@@ -142,7 +142,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         shellId: BackgroundShellId;
     }, BackgroundShellError>>;
     /**
-     * design/116 detach (core 1.207, clay 排 1.81): ADOPT a still-running FOREGROUND exec child as a background
+     * [ref] detach (core 1.207, clay 排 1.81): ADOPT a still-running FOREGROUND exec child as a background
      * shell — the mid-flight ctrl+b path. The exec child writes to pipes (not files, unlike a `launch`-spawned
      * bg shell), so adoption splices those live pipes into fresh bg spool files: pre-fill them with the output
      * captured so far (the detach TEE, fed from the exec's FIRST chunk → TaskOutput's first read has the full
@@ -171,12 +171,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     }, ExecutionError>>;
     /** 管道旧形(win32 / spool 打开失败的回退;行为=1.225 及以前的 exec 原样)。 */
     private execViaPipes;
-    /** [1116] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
+    /** [ref] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
      *  独占建(core openSpoolPair 同形)。失败=undefined(调用方回退管道形)。 */
     private openFgSpool;
-    /** [1116] spool 形 fg exec(core node-execution-env 1.318-1.321 机制移植;坑图=core CHANGELOG 同段)。 */
+    /** [ref] spool 形 fg exec(core node-execution-env 1.318-1.321 机制移植;坑图=core CHANGELOG 同段)。 */
     private execViaSpool;
-    /** [1116] spool 形 detach adoption:spool 路径+fg 游标直接进 HostBgState 的 FILE 面(launch 同形,poll
+    /** [ref] spool 形 detach adoption:spool 路径+fg 游标直接进 HostBgState 的 FILE 面(launch 同形,poll
      *  共码);同一文件单一字节流=天然无 decoder 接缝(mem-tee 版为此专门修过的病在此结构性不存在)。 */
     private adoptRunningExecSpool;
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
@@ -210,7 +210,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  ⇒ 用户仓库根目录按后台任务数累积 `bash-task-<hex>.output`(内容=命令输出)+ 每次 `createTempDir` 一个
      *  `tmp-XXXXXX/`,**永久**留在他们的 git 树里。两条独立判据说明这是偏差不是设计:①core 自己的 TOC 参照实现
      *  `NodeExecutionEnv.createTempFile` 放的是 `os.tmpdir()`;②**本适配器早就为了同一个理由把 spool 根搬去了
-     *  tmpdir**([1116] 五轮复审明写"不再弄脏 user-owned workspace"),只是 createTempFile/Dir 没跟上。
+     *  tmpdir**([ref] 五轮复审明写"不再弄脏 user-owned workspace"),只是 createTempFile/Dir 没跟上。
      *  改用本 env 自己的 tmp 根(`ensureSpoolRoot()`,已在 `os.tmpdir()` 下):
      *   · 用户目录不再被写入;
      *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);