@sema-agent/server 7.134.0 → 7.135.0

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

@@ -1,6 +1,6 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, isValidDurableScope, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, UNCOVERED_SEGMENT_REASONS, EMPTY_DURABLE_RULE_PARTITION, } from "@sema-agent/core";
+import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, isValidDurableScope, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, UNCOVERED_SEGMENT_REASONS, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, RULE_OFFER_KINDS, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
@@ -64,11 +64,24 @@ function readBucketRowBehavior(raw, what, ownerKey) {
 }
 class BucketRefusedError extends Error {
     verdict;
-    constructor(verdict, evidence) {
+    code;
+    constructor(verdict, evidence, code) {
         super(`${verdict} ${evidence}`);
         this.verdict = verdict;
+        if (code !== undefined)
+            this.code = code;
     }
 }
+function readBucketStamp(ownerKey, stamp) {
+    const absent = stamp === null || stamp === undefined;
+    const read = readRuleGrammarStamp(absent ? undefined : stamp, SESSION_RULES_GRAMMAR, { rules: `the rules in permission_rule bucket ${ownerKey}`, held: "rows" });
+    if (!("got" in read))
+        return absent ? undefined : read.grammar;
+    if (read.later === true) {
+        throw new BucketRefusedError(read.sentence, "— loading zero rules and refusing every write until then; the row is left as it is", PERMISSION_RULES_LATER_GRAMMAR_CODE);
+    }
+    throw new BucketRefusedError(read.sentence, "— refusing the whole bucket; the row is left as it is");
+}
 const WritablePersistedRuleSchema = PersistedRuleRowSchema.extend({ behavior: z.enum(RULE_BEHAVIORS) });
 const WritableRuleTombstoneSchema = RuleTombstoneSchema.extend({ behavior: z.enum(RULE_BEHAVIORS) });
 const FrontierSchema = z.record(z.string(), z.number().int().nonnegative().safe());
@@ -77,9 +90,9 @@ const RedeemedDotsSchema = z.record(z.string(), RuleDotSchema);
 const RuleEditedSchema = z
     .object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string(), warnings: z.array(z.enum(EDITED_RULE_BREADTH_WARNING_CODES)).optional() })
     .strict();
-const RuleOffer2Schema = z.union([
-    z.object({ kind: z.literal("single"), candidate: z.number().int().nonnegative().safe() }).strict(),
-    z
+const RULE_OFFER2_ARMS = {
+    single: z.object({ kind: z.literal("single"), candidate: z.number().int().nonnegative().safe() }).strict(),
+    batch: z
         .object({
         kind: z.literal("batch"),
         candidates: z.array(z.number().int().nonnegative().safe()),
@@ -88,7 +101,8 @@ const RuleOffer2Schema = z.union([
         uncoveredDetail: z.array(z.object({ segment: z.string(), reason: z.enum(UNCOVERED_SEGMENT_REASONS) }).strict()).optional(),
     })
         .strict(),
-]);
+};
+export const RuleOffer2Schema = z.union([RULE_OFFER2_ARMS.single, RULE_OFFER2_ARMS.batch]);
 export const PERMISSION_RULE_TABLE = "permission_rule";
 export const PERMISSION_RULE_APPROVAL_TABLE = "permission_rule_approval";
 export const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
@@ -113,9 +127,13 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     observed_vector_json LONGTEXT NULL,
     last_round_at_ms BIGINT NULL,
     -- checksum:core \`ruleStoreChecksum\` 同精神的完整性指纹(覆盖内容三列 + observed_vector 在场时的
-    -- 观测向量,不含 rev/counter——算法单点=buildRuleBucketChecksum)。
+    -- 观测向量 + grammar 非 NULL 时的文法戳,不含 rev/counter——算法单点=buildRuleBucketChecksum)。
     -- 读回不符 ⇒ throw(绝不静默当空店 —— core 对读失败的姿势明令如此)。
     checksum VARCHAR(190) NOT NULL,
+    -- grammar:这只桶的规则行写在哪一版**规则文法**里(引擎 \`SESSION_RULES_GRAMMAR\` 的数,每次写盖章;core 7.55.0 起 File 店同样每桶一戳)。
+    -- NULL = 戳存在之前写下的存量行,按本引擎的文法读、下一次写盖戳;晚于本引擎的戳整桶拒(码 permission_rules.later_grammar,一个字节不动)。
+    -- 非 NULL 的戳进 checksum(戳列与指纹同一条语句写;存量 NULL 行的指纹与升级前逐字节相同):不读戳的旧副本按旧算法重算比不上,整桶拒。可空整数:PG 的 INTEGER 驱动交回 number(BIGINT 会交回串)。
+    grammar INT NULL,
     created_at_ms BIGINT NOT NULL,
     updated_at_ms BIGINT NOT NULL,
     PRIMARY KEY (owner_key)
@@ -277,6 +295,7 @@ export async function ensurePgPermissionRuleSchema(q) {
     observed_vector_json TEXT COLLATE "C",
     last_round_at_ms BIGINT,
     checksum VARCHAR(190) COLLATE "C" NOT NULL,
+    grammar INTEGER,
     created_at_ms BIGINT NOT NULL,
     updated_at_ms BIGINT NOT NULL,
     PRIMARY KEY (owner_key)
@@ -357,15 +376,16 @@ async function refusingUnreadableColumns(what, fn) {
     }
 }
 function bucketRowColumns(dialect) {
-    return `actor, counter, rev, ${jsonColumnText(dialect, "rules_json")}, ${jsonColumnText(dialect, "tombstones_json")}, ${jsonColumnText(dialect, "quarantined_json")}, ${jsonColumnText(dialect, "observed_vector_json")}, checksum`;
+    return `actor, counter, rev, ${jsonColumnText(dialect, "rules_json")}, ${jsonColumnText(dialect, "tombstones_json")}, ${jsonColumnText(dialect, "quarantined_json")}, ${jsonColumnText(dialect, "observed_vector_json")}, checksum, grammar`;
 }
 function decodeBucketRow(ownerKey, row) {
     const at = `${PERMISSION_RULE_TABLE} bucket ${ownerKey}`;
+    const grammar = readBucketStamp(ownerKey, row.grammar);
     const rulesRaw = decodeJsonColumn(row.rules_json, readRulesJson, `${at}.rules_json`);
     const tombstonesRaw = decodeJsonColumn(row.tombstones_json, readTombstonesJson, `${at}.tombstones_json`);
     const quarantinedRaw = decodeJsonColumn(row.quarantined_json, readQuarantinedJson, `${at}.quarantined_json`);
     const observedVector = row.observed_vector_json === null || row.observed_vector_json === undefined ? undefined : decodeJsonColumn(row.observed_vector_json, readObservedVectorJson, `${at}.observed_vector_json`);
-    const expected = buildRuleBucketChecksum({ rules: rulesRaw, tombstones: tombstonesRaw, quarantined: quarantinedRaw, ...(observedVector !== undefined ? { observedVector } : {}) });
+    const expected = buildRuleBucketChecksum({ rules: rulesRaw, tombstones: tombstonesRaw, quarantined: quarantinedRaw, ...(observedVector !== undefined ? { observedVector } : {}), ...(grammar !== undefined ? { grammar } : {}) });
     if (String(row.checksum ?? "") !== expected) {
         throw new BucketRefusedError(`permission_rule bucket ${ownerKey} failed its integrity check`, `(stored ${String(row.checksum)}, computed ${expected}) — refusing the whole bucket rather than reporting a partial rule set`);
     }
@@ -392,6 +412,14 @@ function decodeBucketRow(ownerKey, row) {
         tombstones,
         quarantined,
         ...(observedVector !== undefined ? { observedVector } : {}),
+        ...(grammar !== undefined ? { grammar } : {}),
+    };
+}
+function fencedCasWhere(dialect, firstPlaceholder, ownerKey, cas) {
+    const ph = (offset) => (dialect === "tidb" ? "?" : `$${firstPlaceholder + offset}`);
+    return {
+        sql: `owner_key = ${ph(0)} AND ${cas.column} = ${ph(1)} AND (grammar IS NULL OR grammar <= ${ph(2)})`,
+        params: [ownerKey, cas.expected, SESSION_RULES_GRAMMAR],
     };
 }
 async function writeBucket(exec, dialect, ownerKey, cur, next, nowMs) {
@@ -401,16 +429,17 @@ async function writeBucket(exec, dialect, ownerKey, cur, next, nowMs) {
     }
     const body = { rules: next.rules, tombstones: next.tombstones, quarantined: cur.quarantined, ...(cur.observedVector !== undefined ? { observedVector: cur.observedVector } : {}) };
     const enc = dialectProtocolJsonEncoder(dialect);
+    const where = fencedCasWhere(dialect, 7, ownerKey, { column: "rev", expected: cur.rev });
     const affected = await exec(dialect === "tidb"
-        ? `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = ?, tombstones_json = ?, quarantined_json = ?, checksum = ?, rev = rev + 1, updated_at_ms = ? WHERE owner_key = ? AND rev = ?`
-        : `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = $1, tombstones_json = $2, quarantined_json = $3, checksum = $4, rev = rev + 1, updated_at_ms = $5 WHERE owner_key = $6 AND rev = $7`, [
+        ? `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = ?, tombstones_json = ?, quarantined_json = ?, checksum = ?, grammar = ?, rev = rev + 1, updated_at_ms = ? WHERE ${where.sql}`
+        : `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = $1, tombstones_json = $2, quarantined_json = $3, checksum = $4, grammar = $5, rev = rev + 1, updated_at_ms = $6 WHERE ${where.sql}`, [
         enc(next.rules, "permission_rule.rules_json"),
         enc(next.tombstones, "permission_rule.tombstones_json"),
         enc(cur.quarantined, "permission_rule.quarantined_json"),
-        buildRuleBucketChecksum(body),
+        buildRuleBucketChecksum({ ...body, grammar: SESSION_RULES_GRAMMAR }),
+        SESSION_RULES_GRAMMAR,
         nowMs,
-        ownerKey,
-        cur.rev,
+        ...where.params,
     ]);
     return affected === 1;
 }
@@ -446,9 +475,9 @@ class SqlDurableRulePartition {
     async ensureBucket() {
         const nowMs = this.now();
         const empty = { rules: [], tombstones: [], quarantined: [] };
-        await this.db.query(this.q(`INSERT IGNORE INTO ${PERMISSION_RULE_TABLE} (owner_key, owner_kind, principal, actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, last_round_at_ms, checksum, created_at_ms, updated_at_ms)
-         VALUES (?, ?, ?, ?, 0, 0, ?, ?, ?, NULL, NULL, ?, ?, ?)`, `INSERT INTO ${PERMISSION_RULE_TABLE} (owner_key, owner_kind, principal, actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, last_round_at_ms, checksum, created_at_ms, updated_at_ms)
-         VALUES ($1, $2, $3, $4, 0, 0, $5, $6, $7, NULL, NULL, $8, $9, $10) ON CONFLICT (owner_key) DO NOTHING`), [
+        await this.db.query(this.q(`INSERT IGNORE INTO ${PERMISSION_RULE_TABLE} (owner_key, owner_kind, principal, actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, last_round_at_ms, checksum, grammar, created_at_ms, updated_at_ms)
+         VALUES (?, ?, ?, ?, 0, 0, ?, ?, ?, NULL, NULL, ?, ?, ?, ?)`, `INSERT INTO ${PERMISSION_RULE_TABLE} (owner_key, owner_kind, principal, actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, last_round_at_ms, checksum, grammar, created_at_ms, updated_at_ms)
+         VALUES ($1, $2, $3, $4, 0, 0, $5, $6, $7, NULL, NULL, $8, $9, $10, $11) ON CONFLICT (owner_key) DO NOTHING`), [
             this.ownerKey,
             this.owner.kind,
             this.owner.kind === "principal" ? this.owner.principal : null,
@@ -456,14 +485,15 @@ class SqlDurableRulePartition {
             this.enc([], "permission_rule.rules_json"),
             this.enc([], "permission_rule.tombstones_json"),
             this.enc([], "permission_rule.quarantined_json"),
-            buildRuleBucketChecksum(empty),
+            buildRuleBucketChecksum({ ...empty, grammar: SESSION_RULES_GRAMMAR }),
+            SESSION_RULES_GRAMMAR,
             nowMs,
             nowMs,
         ]);
     }
     async list() {
         const s = await this.read();
-        return { rules: applyTombstones(s.rules, s.tombstones), tombstones: s.tombstones, rev: s.rev, checksum: buildRuleBucketChecksum({ rules: s.rules, tombstones: s.tombstones, quarantined: s.quarantined, ...(s.observedVector !== undefined ? { observedVector: s.observedVector } : {}) }) };
+        return { rules: applyTombstones(s.rules, s.tombstones), tombstones: s.tombstones, rev: s.rev, checksum: buildRuleBucketChecksum({ rules: s.rules, tombstones: s.tombstones, quarantined: s.quarantined, ...(s.observedVector !== undefined ? { observedVector: s.observedVector } : {}), ...(s.grammar !== undefined ? { grammar: s.grammar } : {}) }) };
     }
     async quarantined() {
         return (await this.read()).quarantined;
@@ -475,13 +505,15 @@ class SqlDurableRulePartition {
         nextDot: async () => {
             await this.ensureBucket();
             for (let attempt = 0; attempt < NEXT_DOT_MAX_ATTEMPTS; attempt++) {
-                const { rows } = await this.db.query(this.q(`SELECT actor, counter FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
+                const { rows } = await this.db.query(this.q(`SELECT actor, counter, grammar FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter, grammar FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
                 const row = rows[0];
                 if (row === undefined)
                     throw new Error(`permission_rule bucket ${this.ownerKey} vanished while minting a dot`);
+                readBucketStamp(this.ownerKey, row.grammar);
                 const cur = Number(row.counter);
                 const next = cur + 1;
-                const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TABLE} SET counter = ?, updated_at_ms = ? WHERE owner_key = ? AND counter = ?`, `UPDATE ${PERMISSION_RULE_TABLE} SET counter = $1, updated_at_ms = $2 WHERE owner_key = $3 AND counter = $4`), [next, this.now(), this.ownerKey, cur]);
+                const where = fencedCasWhere(this.db.dialect, 3, this.ownerKey, { column: "counter", expected: cur });
+                const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TABLE} SET counter = ?, updated_at_ms = ? WHERE ${where.sql}`, `UPDATE ${PERMISSION_RULE_TABLE} SET counter = $1, updated_at_ms = $2 WHERE ${where.sql}`), [next, this.now(), ...where.params]);
                 if (affected === 1)
                     return { actor: String(row.actor), counter: next };
             }
@@ -554,6 +586,12 @@ export class SqlDurableRulePartitionProvider {
         return new SqlDurableRulePartition(this.db, { kind: "local-owner" }, this.now);
     }
 }
+export function recordOwnerOf(record) {
+    return readRuleOwner(record.owner ?? { kind: "principal", principal: record.principal });
+}
+export function refusedOwnerSentence(recordId) {
+    return `refusing to create approval record ${recordId}: its owner is not one the engine reads as an owner (a principal name must be a non-blank string; the kind must be a member of the owner set) — nothing was written`;
+}
 export class SqlRuleApprovalRecordStore {
     db;
     now;
@@ -575,9 +613,12 @@ export class SqlRuleApprovalRecordStore {
         const row = rows[0];
         if (row === undefined)
             return undefined;
-        const ownerKind = String(row.owner_kind);
         const principal = row.principal === null || row.principal === undefined ? undefined : String(row.principal);
-        const identity = ownerKind === "principal" ? { principal: principal ?? "" } : { owner: { kind: "local-owner" } };
+        const rowOwner = readRuleOwner({ kind: row.owner_kind, ...(principal !== undefined ? { principal } : {}) });
+        if (rowOwner === undefined) {
+            throw new Error(`${PERMISSION_RULE_APPROVAL_TABLE} row ${id} carries an owner the engine does not read as an owner (owner_kind ${JSON.stringify(String(row.owner_kind))}) — refusing the record rather than reading it as another owner's`);
+        }
+        const identity = rowOwner.kind === "principal" ? { principal: rowOwner.principal } : { owner: rowOwner };
         if (Number(row.version) !== RULE_APPROVAL_RECORD_SCHEMA) {
             return { staleSchema: true, id: String(row.record_id), ...identity };
         }
@@ -612,7 +653,9 @@ export class SqlRuleApprovalRecordStore {
     }
     async create(record) {
         const nowMs = this.now();
-        const owner = record.owner ?? { kind: "principal", principal: record.principal ?? "" };
+        const owner = recordOwnerOf(record);
+        if (owner === undefined)
+            throw new Error(refusedOwnerSentence(record.id));
         await this.db.query(this.q(`INSERT INTO ${PERMISSION_RULE_APPROVAL_TABLE} (record_id, owner_key, owner_kind, principal, kind, state, version, rev, candidates_json, offers_json, selected_offer, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso, created_at_ms, updated_at_ms)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, `INSERT INTO ${PERMISSION_RULE_APPROVAL_TABLE} (record_id, owner_key, owner_kind, principal, kind, state, version, rev, candidates_json, offers_json, selected_offer, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso, created_at_ms, updated_at_ms)
          VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19)`), [

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

@@ -36,7 +36,7 @@ export declare class PgCostQuota implements QuotaTracker {
  *  DATETIME(3)→TIMESTAMPTZ(3), inline `KEY idx_window`→separate CREATE INDEX). DISJOINT from other stores'
  *  tables, so a self-contained ensureSchema is safe (the central pg-pool aggregation is done separately). */
 export declare const PG_COST_QUOTA_SCHEMA: string[];
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const COST_QUOTA_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for the cost_quota table (the PG twin of tidb-pool.ts ensureSchema). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;

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

@@ -80,7 +80,7 @@ export declare const ENSURE_SCHEMA_LOCK_KEY = 4906;
  * `tidb-pool.ts acquireEnsureSchemaLock` 的逐条同形(循环共用 `ensure-schema-lock-policy.ts`)。轮到拿到为止;坏连接连续抛上抛
  * (每条 DDL 本来就各自幂等),而不是把启动挂死。
  *
- * 🔴 **为什么不能再用阻塞的 `pg_advisory_lock()`**(S-287 复审 H1,对 7.82.1 的回归):本仓自 S-287 起在
+ * 🔴 **为什么不能再用阻塞的 `pg_advisory_lock()`**([ref] 复审 H1,对 7.82.1 的回归):本仓自 [ref] 起在
  * 锁窗内发 `CREATE INDEX CONCURRENTLY`,而 CIC 的末相要**等掉同库里所有 xmin 比它老的运行中后端**
  * (`WaitForOlderSnapshots`)。一条卡在 `SELECT pg_advisory_lock($1)` 里的副本**正是**一条持着快照的运行中
  * 查询 —— 它等锁、锁等 CIC、CIC 等它:三方互等。命中形是「全新 PG 库 + 多副本同时起」(表刚建完 ⇒ 索引
@@ -101,7 +101,7 @@ export declare function releasePgEnsureSchemaLock(client: pg.PoolClient, tag: st
  *  calls ensurePgSchema), and in production every replica calls it at boot. Concurrent DDL on the SAME table makes
  *  PG raise `tuple concurrently updated` in its catalog. We serialize the entire run behind a session-level
  *  advisory lock, acquired NON-BLOCKINGLY with polling ({@link acquirePgEnsureSchemaLock} — 阻塞形会与本函数
- *  自 S-287 起发的 `CREATE INDEX CONCURRENTLY` 三方互等,理由写在那只函数的头注里): the first caller does
+ *  自 [ref] 起发的 `CREATE INDEX CONCURRENTLY` 三方互等,理由写在那只函数的头注里): the first caller does
  *  the real CREATE/index work, the rest poll from OUTSIDE the database then find every statement already
  *  satisfied (IF NOT EXISTS ⇒ no-op), so there is no catalog race. The DDL semantics are
  *  unchanged — only its timing is serialized. The advisory lock is SESSION (connection)-level, so the lock and

package/dist/plugins/pg-pool.js

@@ -93,6 +93,8 @@ export const PG_SCHEMA_STATEMENTS = [
      reopen_reason VARCHAR(32) COLLATE "C",
      terminal_at_ms BIGINT,
      gate_kind    VARCHAR(32) COLLATE "C",
+     -- approval_card(core 7.55.0 #1468 P1 阶段二):门上的卡词照存;语义、读者与「本仓不发 ALTER」见 MySQL 孪生(tidb-pool.ts 同名列的行内注)。
+     approval_card TEXT COLLATE "C",
      bound_input_hash VARCHAR(190) COLLATE "C",
      -- pending_steer_queue / pending_steer_rev:队列化后的 durable steering(core 5.14.0 #147)。两列的语义、
      -- 退役的单座列 pending_steer 为何删列(以及存量库里仍带着它时的拒启臂)、48000 字节预算、
@@ -340,8 +342,9 @@ export const PG_SCHEMA_STATEMENTS = [
      summary        TEXT COLLATE "C"         NOT NULL,
      enqueued_at_ms BIGINT       NOT NULL,
      -- 1.109 delivery envelope. kind NULL = a LEGACY \`workflow_complete\` row (the shape that predates the
-     -- envelope); readers must keep treating NULL as that kind, it is not "unknown". payload = the kind's
-     -- body, NULL for the legacy shape.
+     -- envelope); readers must keep treating NULL as that kind, it is not "unknown". payload = the kind's JSON
+     -- extras: task_notification: task_type / result / …; workflow_complete: at most {"completionId": …} (the
+     -- engine's own correlation id, verbatim; NULL when the engine minted none).
      kind           VARCHAR(24) COLLATE "C",
      payload        TEXT COLLATE "C",
      PRIMARY KEY (session_id, run_id),

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

@@ -40,7 +40,7 @@ export declare class PgRateLimiter implements RateGate {
  * atomic ON CONFLICT increment.
  */
 export declare const PG_RATE_LIMITER_SCHEMA: string[];
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const RATE_LIMIT_INDEXES: readonly IndexSpec[];
 /** Self-contained schema bootstrap for tests (the rate_limit table is disjoint from other stores). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
 import { type SessionRowPatch } from "../session-row.js";
@@ -16,7 +16,7 @@ import { type IndexSpec } from "./ensure-index.js";
  * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_SESSION_SCHEMA: string[];
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const SESSION_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for this store's tables (the test calls this; production aggregation is separate). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
@@ -51,7 +51,7 @@ export declare class PgSessionStorage extends BaseSessionStorage {
 }
 /**
  * PostgreSQL-backed {@link SessionStore} — the PG twin of {@link TiDBSessionStore}. Maps the
- * `SessionStore` surface (acquire / register / ownerOf / touch / release) onto {@link PgSessionStorage}.
+ * `SessionStore` surface (acquire / register / headOf / touch / release) onto {@link PgSessionStorage}.
  */
 export declare class PgSessionStore implements SessionStore {
     private readonly pool;
@@ -75,11 +75,11 @@ export declare class PgSessionStore implements SessionStore {
     private load;
     /** Idempotently create a session_meta row with an owner (core `SessionStore.register`). Existing owner is never overwritten. */
     register(sessionId: string, owner: string | null): Promise<void>;
-    /** acquire 的建行(唯一一处;S-1770 委派继承律,只住在 `createPlacedSessionRow`,本店交既有读写口 —— TiDB 孪生同名方法同注)。 */
+    /** acquire 的建行(唯一一处;[ref] 委派继承律,只住在 `createPlacedSessionRow`,本店交既有读写口 —— TiDB 孪生同名方法同注)。 */
     private createOnAcquire;
-    /** S-1770 委派继承律的认领口(TiDB 孪生 {@link TiDBSessionStore.claimOwnerless} 同义;句 = `CLAIM_OWNERLESS_PLACED_SQL`,规则在 `delegated-session-owner.ts`)。 */
+    /** [ref] 委派继承律的认领口(TiDB 孪生 {@link TiDBSessionStore.claimOwnerless} 同义;句 = `CLAIM_OWNERLESS_PLACED_SQL`,规则在 `delegated-session-owner.ts`)。 */
     claimOwnerless(sessionId: string, incarnation: string, owner: string): Promise<boolean>;
-    /** 若干来源行的会话面(属主 + 化身)一次读回(TiDB 孪生同义;化身经与 `sessionFaceOf` 同一只解码,空 ⇒ 响亮拒)。 */
+    /** 若干来源行的会话面(属主 + 化身)一次读回(TiDB 孪生同义;活住客的投影 `sessionFaceFromRow`,空化身 ⇒ 响亮拒)。 */
     private sourceFaces;
     /** The one session_meta INSERT. Existing owner is never overwritten.
      *  [ref]:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
@@ -92,21 +92,9 @@ export declare class PgSessionStore implements SessionStore {
         olderThanMs?: number;
         scope?: string;
     }): Promise<PlacedSessionRow[]>;
-    /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
-    ownerOf(sessionId: string): Promise<string | null | undefined>;
-    /** S-790:属主 + 化身一次读(TiDB 孪生 {@link TiDBSessionStore.sessionFaceOf} 同义;空化身 ⇒ 响亮拒)。 */
-    sessionFaceOf(sessionId: string): Promise<SessionFace | undefined>;
-    /** core `SessionStore.incarnationOf`:{@link sessionFaceOf} 的化身那一半(TiDB 孪生同义)。 */
-    incarnationOf(sessionId: string): Promise<string | undefined>;
+    /** core `SessionStore.headOf` —— 属主、住客、叶子一条 PK SELECT 一行(TiDB 孪生 {@link TiDBSessionStore.headOf} 同义:本店按 id 读一行的唯一读口)。 */
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
     touch(sessionId: string): Promise<void>;
-    /** 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>;
-    /** [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.
      *  🔴 [ref] 义务 4:**placed 会话例外 —— release 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
      *  {@link TiDBSessionStore.release},本腿是它的 PG 孪生)。 */

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

@@ -15,9 +15,10 @@ import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChan
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
-import { SESSION_META_INCARNATION_COLUMN, carriedIncarnation, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { SESSION_META_INCARNATION_COLUMN, carriedIncarnation, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
+import { forkCopyOf, forkPointOf } from "./session-fork.js";
 const isDupKey = isPgUniqueViolation;
 function baselineQuery(text, values) {
     return { text, values, query_timeout: BASELINE_IO_DEADLINE_MS };
@@ -219,7 +220,7 @@ export class PgSessionStore {
     }
     async register(sessionId, owner) {
         if (typeof owner !== "string" && owner !== null) {
-            if ((await this.ownerOf(sessionId)) !== undefined)
+            if ((await this.headOf(sessionId)) !== undefined)
                 return;
             assertFirstOwnerWritable(sessionId, owner);
         }
@@ -231,7 +232,7 @@ export class PgSessionStore {
         await createPlacedSessionRow(sessionId, placement, {
             readFaces: (ids) => this.sourceFaces(ids),
             insert: (owner) => this.insertMeta(sessionId, owner, placement),
-            readOwner: () => this.ownerOf(sessionId),
+            readOwner: async () => (await this.headOf(sessionId))?.owner,
         }, this.log);
     }
     async claimOwnerless(sessionId, incarnation, owner) {
@@ -266,20 +267,12 @@ export class PgSessionStore {
         const res = await this.pool.query(sql, params);
         return res.rows.map((r) => placedRowFromRow(String(r.session_id), r, r.updated_at instanceof Date ? r.updated_at.getTime() : undefined));
     }
-    async ownerOf(sessionId) {
-        const res = await this.pool.query("SELECT owner FROM session_meta WHERE session_id = $1", [sessionId]);
+    async headOf(sessionId) {
+        const res = await this.pool.query("SELECT owner, incarnation, leaf_id FROM session_meta WHERE session_id = $1", [sessionId]);
         if (res.rows.length === 0)
             return undefined;
-        return res.rows[0].owner ?? null;
-    }
-    async sessionFaceOf(sessionId) {
-        const res = await this.pool.query("SELECT owner, incarnation FROM session_meta WHERE session_id = $1", [sessionId]);
-        if (res.rows.length === 0)
-            return undefined;
-        return sessionFaceFromRow(sessionId, res.rows[0].owner ?? null, res.rows[0].incarnation);
-    }
-    async incarnationOf(sessionId) {
-        return (await this.sessionFaceOf(sessionId))?.incarnation;
+        const r = res.rows[0];
+        return headFromRow(sessionId, r.owner ?? null, r.incarnation, r.leaf_id ?? null);
     }
     async touch(sessionId) {
         await this.pool.query("UPDATE session_meta SET updated_at = $1 WHERE session_id = $2", [
@@ -287,16 +280,6 @@ export class PgSessionStore {
             sessionId,
         ]);
     }
-    async getLeafId(sessionId) {
-        const r = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = $1", [sessionId]);
-        return r.rows[0] ? (r.rows[0].leaf_id ?? null) : null;
-    }
-    async getHead(sessionId) {
-        const r = await this.pool.query("SELECT owner, leaf_id FROM session_meta WHERE session_id = $1", [sessionId]);
-        if (r.rows.length === 0)
-            return undefined;
-        return { owner: r.rows[0].owner ?? null, leafId: r.rows[0].leaf_id ?? null };
-    }
     async release(sessionId) {
         this.pending.delete(sessionId);
         const placed = await this.placementOf(sessionId);
@@ -440,8 +423,12 @@ export class PgSessionStore {
             return null;
         const leafId = metaRes.rows[0].leaf_id ?? null;
         const forkOwner = forkOwnerOf(owner, metaRes.rows[0].owner ?? null) ?? null;
+        const storage = await PgSessionStorage.wake(this.pool, sourceId);
+        if (storage === null)
+            return null;
+        const point = await forkPointOf(storage);
         const eventRes = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("pg", "payload")}, ts FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [sourceId]);
-        const rows = eventRes.rows;
+        const { rows, leafId: forkLeafId } = forkCopyOf(eventRes.rows, leafId, point);
         const newId = uuidv7();
         const now = new Date();
         const conn = await this.pool.connect();
@@ -452,7 +439,7 @@ export class PgSessionStore {
                 const payload = String(r.payload);
                 await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
             }
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [newId, forkOwner, now, now, leafId, rows.length, mintSessionIncarnation()]);
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [newId, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation()]);
             await conn.query("COMMIT");
             return newId;
         }

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

@@ -35,13 +35,13 @@ export interface AdbEnvDeps {
 /** [R78]#1: adb stderr markers that mean the DEVICE TRANSPORT died mid-op (not a normal command failure) —
  *  typed retryable (reconnect + retry per idempotency), never a fake command result. Exported for tests.
  *
- *  🔴 **S-401 把这个判据的输入面改了一半(复审 F12 纠正:原来写的「此前 stderr 恒空 ⇒ 整条是死码」是
+ *  🔴 **[ref] 把这个判据的输入面改了一半(复审 F12 纠正:原来写的「此前 stderr 恒空 ⇒ 整条是死码」是
  *  **overclaim**,被本车自己的真机读数推翻)**。`exec-out` 合流的是**设备**的 stderr;**adb 客户端自己的**
  *  诊断在两种传输下都照样走宿主 stderr。真机实测(同一台设备,拔掉 serial):
  *  `adb -s BOGUS exec-out 'true'` ⇒ host exit **255** + stderr `error: device 'BOGUS' not found`;
  *  `adb -s BOGUS shell -T -- 'true'` ⇒ host exit **1** + stderr `adb: device 'BOGUS' not found`。
- *  ⇒ 本判据在 S-401 之前**对 adb 客户端级的传输故障是工作的**(这也正是原作者把词表写成这些 adb 自家
- *  措辞的原因);S-401 改变的是**设备侧 stderr 从此也进这条通道**。
+ *  ⇒ 本判据在 [ref] 之前**对 adb 客户端级的传输故障是工作的**(这也正是原作者把词表写成这些 adb 自家
+ *  措辞的原因);[ref] 改变的是**设备侧 stderr 从此也进这条通道**。
  *
  *  ⚠️ **随之而来的、如实登记的一格**:分流之后落到这里的 stderr **既有 adb 自己的诊断,也有设备命令自己的
  *  输出**(adb 客户端把两者写在同一个 fd 上,真机实测无法在传输层分开)。于是设备上一条自己打印
@@ -53,7 +53,7 @@ export interface AdbEnvDeps {
 export declare function isAdbTransportLost(stderr: string): boolean;
 export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     /**
-     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
      * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,在设备 shell 里解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
@@ -82,7 +82,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     get homeDir(): string | undefined;
     /** 家目录的座(声明胜 · 否则首连时实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道**不对证**声明:Android 没有 POSIX 登录家目录,声明是运维的断言,照单全收。 */
     private readonly homeSeat;
-    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 Android 设备的 shell 里(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+    /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 Android 设备的 shell 里(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
     private readonly cfg;
@@ -156,7 +156,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     joinPath(parts: string[]): Promise<Result<string, FileError>>;
     /** 文件面的门 —— 与 host/local-docker/k8s/e2b 的姿态对齐(它们的文件面在未连/已拆时都 fail-closed)。
      *
-     *  🔴 **S-401 复审 F2:这道门此前只查 `destroyed`,不查 `connected`**,于是 `readBinaryFile` /
+     *  🔴 **[ref] 复审 F2:这道门此前只查 `destroyed`,不查 `connected`**,于是 `readBinaryFile` /
      *  `readTextFile` / `readTextLines` / `appendFile` 能在**从没连过**的 env 上直接打一次真设备往返。
      *  在本批之前那只是个不一致;本批**新开的 `shell_v2` fail-closed 闸就长在 `connect()` 里**,
      *  所以「不查 connected」= 那道闸对整个读面**不生效** —— 而 `readTextFile` 把错误文本当文件内容返回
@@ -177,7 +177,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
-    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+    /** [ref] / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
      *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
      *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
@@ -207,7 +207,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     /** Spawn the adb binary with the given args; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private adb;
     /**
-     * 🔴 **S-401 —— 本适配器跑设备命令的唯一往返形**(`exec` / `execStream` / `readBinaryFile` 三个调用点
+     * 🔴 **[ref] —— 本适配器跑设备命令的唯一往返形**(`exec` / `execStream` / `readBinaryFile` 三个调用点
      * 共用一只;此前 `exec-out` 写了三遍,于是「传输到底给不给退出码」这件事没有属主)。
      *
      * **`adb shell`(shell protocol v2)而不是 `adb exec-out`。** 协议出处 = adb 自己的 `adb help`:
@@ -226,7 +226,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      * 与链原语 `remote-shell.ts` 的 `runSymlinkChain`(第 8 处)认的都是 `exitCode !== 0`,而这条传输恒答 0
      * ⇒ adb 腿上 `realpath` / `readlink` / `stat` / `ls` / `cat` **永不失败**,`canonicalPath` 把那行**错误
      * 文本**当成 canonical key 交给敏感路径门。⚠️ **复审 F15 纠正:原文写「五处」是数错了**,而且漏掉的
-     * 第 8 处恰恰是最贵的一处 —— `canonicalChain`(S-362 / core 7.21.0 [ref],上一版刚接)在 exit 恒 0 下会把
+     * 第 8 处恰恰是最贵的一处 —— `canonicalChain`([ref] / core 7.21.0 [ref],上一版刚接)在 exit 恒 0 下会把
      * **合流进 stdout 的错误文本当成链上的跳**解析出来,等于给 core 的路径判官递一条**伪造的** symlink 链。
      *
      * 🔴 **`-T` 与 `--` 都是承重件,不是装饰**:
@@ -242,7 +242,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      * {@link createCwdGuardedCall} 组出的那一串(带工作目录时含 cwd 守卫前缀:cd 失败 ⇒ 整条不跑)。
      */
     private deviceShellArgs;
-    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}(S-410:cwd 不可用 ⇒ 命令不跑;
+    /** 本腿只定工作目录(缺省 cwd 规则 + 绝对化);串的形状归 {@link buildCwdEnvCommand} / {@link createCwdGuardedCall}([ref]:cwd 不可用 ⇒ 命令不跑;
      *  车PL:buffered `exec` 上守卫触发 ⇒ `spawn_error`)。 */
     private workingDirOf;
 }

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

@@ -52,7 +52,7 @@ export interface DeviceEnvLogger {
     info?(msg: string, fields?: Record<string, unknown>): void;
 }
 export interface DeviceEnvFactoryDeps {
-    /** S-213④ / core [ref]:设备上执行用户的 home(`ExecutionEnv.homeDir` 座)。由 `boot/execution-env.ts`
+    /** [ref]④ / core [ref]:设备上执行用户的 home(`ExecutionEnv.homeDir` 座)。由 `boot/execution-env.ts`
      *  从唯一属主 `executionLaneHomeDir` 递进;缺席 ⇒ 本 env 声明「没有 home」,`~/` 规则判 unreadable。 */
     homeDir?: string;
     hub: DeviceWsHub;
@@ -60,7 +60,7 @@ export interface DeviceEnvFactoryDeps {
     enrollment: DeviceEnrollment;
     /** 指令级默认超时(ms;`DEVICE_EXEC_TIMEOUT_MS`,§4.7)。core 的 per-command `timeout` 可收紧它。 */
     execTimeoutMs?: number;
-    /** §4.3.3 蜂道:`deviceCwdHonored` 闸下由 resolve-spec 注册的 per-session cwd(**单写者**)。 */
+    /** §4.3.3 蜂道:部署形表行 `callerCwd` 闸下由 resolve-spec 注册的 per-session cwd(**单写者**)。 */
     perSessionCwd?: ReadonlyMap<string, string>;
     perSessionShellEnv?: ReadonlyMap<string, Record<string, string>>;
     logger?: DeviceEnvLogger;
@@ -72,7 +72,7 @@ interface DeviceEnvConfig {
     deviceId: string;
     owner: DeviceOwner;
     cwd: string;
-    /** S-213④ / core [ref] —— 员工设备上执行用户的 home(`ExecutionEnv.homeDir` 座)。缺席 ⇒ 本 env 声明
+    /** [ref]④ / core [ref] —— 员工设备上执行用户的 home(`ExecutionEnv.homeDir` 座)。缺席 ⇒ 本 env 声明
      *  「我没有 home」,`~/` 形权限规则对本腿判 unreadable(fail-closed)。值经 `boot/execution-env.ts`
      *  从唯一属主 `executionLaneHomeDir` 递进;设备是运行期连进来的,boot 期只有运维显式声明才有值。 */
     homeDir?: string;
@@ -86,7 +86,7 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     private readonly cfg;
     /** core `ExecutionEnv.homeDir`([ref]):设备上执行用户的 home。见 `DeviceEnvConfig.homeDir`。 */
     readonly homeDir?: string | undefined;
-    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在设备上(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+    /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在设备上(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
     /**
@@ -96,7 +96,7 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
      * 落到一个空工作区上而链路上没有任何一层会报错。
      */
     /**
-     * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
+     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
      * 就是**命令真正跑的那块文件系统**的权威答案(设备 WS 协议的**必答** `canonicalPath` op)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
@@ -324,9 +324,10 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
  *     对比:「绑了但现在不在线」是运行期事实 ⇒ 构造成功,`connect()` 回 typed `device.offline`。
  *
  * 🔴 **工厂的每一只拒都是 typed 拒**(core 7.54.0 [ref] r3 契约:工厂抛的 `.code` 原样成失败终局的码):经 {@link deviceFactoryRefusal} 一处铸,码取
- * `DEVICE_ERROR_CODES` 闭集(装配错误取 `config.placement_root_invalid`),句子里的 `[码]` 与 `.code` 同值。修前抛裸 `Error`,码只在句子里。
+ * `DEVICE_ERROR_CODES` 闭集(装配 / 数据错误取 {@link DEVICE_FACTORY_CONFIG_CODES}:placement 根为空 · 有效工作目录非绝对路径),句子里的 `[码]` 与 `.code` 同值。修前抛裸 `Error`,码只在句子里
+ * (有效工作目录那一只直到 7.135.0 仍是裸 `Error`;钉:本工厂与 {@link effectiveDeviceCwd} 的函数体里没有 `new Error(`)。
  *
- * 🔴 **续跑腿的投递围栏**(core 7.54.0 [ref] r3 / #2061,`ExecutionEnvFactoryContext.resumeWorkspace`):行记下了设备(`resumeWorkspace.deviceId`)⇒
+ * 🔴 **续跑腿的投递围栏**(core 7.54.0 [ref] r3 / [ref],`ExecutionEnvFactoryContext.resumeWorkspace`):行记下了设备(`resumeWorkspace.deviceId`)⇒
  * 本工厂**只**在那台设备上铸 —— placement 根此刻绑的不是它(换绑过)⇒ 抛 typed `device.identity_mismatch`(换绑后赎回的同一个词,零新码),
  * 句子点名两台设备;不连另一台、不改道(新设备没有那个工作区)。读当前绑定只为判出这一拒与取属主,铸的设备恒是行记下的那一台。
  * 「绑的就是它但现在不在线」与新跑同形:构造成功、`connect()` 回 typed `device.offline`(从不连别的设备)。
@@ -335,12 +336,12 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
 export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): ExecutionEnvFactory;
 /**
  * §4.3.3 的 cwd 优先序 —— 与 host 腿的 `effectiveHostWorkspace` **同源**:
- *   ① 本 session 显式注册的 cwd(`deviceCwdHonored` 闸下由 resolve-spec 写);
+ *   ① 本 session 显式注册的 cwd(部署形表行 `callerCwd` 闸下由 resolve-spec 写);
  *   ② `ctx.parentCwd`(委派子代:自己没注册过 cwd,继承父的工作目录 —— 少了它子代会丢工作目录);
  *   ③ 设备入籍时登记并落库的 `workspaceRoot`(缺 cwd 时的解析基准,有明确 wire 契约,不是「executor
  *      默认根」这种空话)。
  *
- * 🔴 **这一只解析源同时守它的后置条件:结果必是 POSIX 绝对路径,否则响亮抛。** 协议文档对 executor 的承诺是
+ * 🔴 **这一只解析源同时守它的后置条件:结果必是 POSIX 绝对路径,否则响亮抛 typed 拒(`.code` = `config.device_cwd_invalid`)。** 协议文档对 executor 的承诺是
  * 「exec / execStream 的指令帧恒带绝对 `cwd`」—— 不带或带相对的,都会把「用哪个目录」这件事留给 executor
  * 自己猜(同一个事实两种读法)。判据是入籍口那**同一只**谓词 `isDeviceAbsolutePath`(`device-store.ts`):入籍口用它拒相对的
  * `workspaceRoot`;这里的判留作存量行守卫(入籍口收紧之前落库的相对根)并守另两个来源 —— 委派链的父 cwd 来自引擎,不经入籍口。