@sema-agent/server 7.58.0 → 7.60.0

package/dist/deployment-governance.js

@@ -1,5 +1,5 @@
-import { posix } from "node:path";
-import { FileError, StubExecutionEnv, combinePolicies, createAllowDenyPolicy, createDurableQuestionPolicy, createSensitivePathPolicy, err, ok, } from "@sema-agent/core";
+import { join, posix } from "node:path";
+import { FileError, StubExecutionEnv, combinePolicies, createAllowDenyPolicy, createDurableQuestionPolicy, createSensitivePathPolicy, createTranscriptIntegrityPolicy, err, ok, } from "@sema-agent/core";
 import { createDurableAskPolicy } from "./approval.js";
 export function createDurableQuestionGate(live) {
     if (live === undefined)
@@ -47,17 +47,23 @@ export function buildOnlySensitiveBaselineWarning(config, seat) {
         },
     };
 }
-export function createDeploymentGovernanceInputs(config, pathAdjudication) {
+export function createDeploymentGovernanceInputs(config, pathAdjudication, roots) {
     const sensitivePathPolicy = config.sensitiveWritePatterns.length > 0
         ? (() => {
+            const dataRootOpt = roots.engineDataRoot !== undefined ? { dataRoot: roots.engineDataRoot } : {};
             const realTarget = createSensitivePathPolicy({
                 env: pathAdjudication.env,
                 patterns: config.sensitiveWritePatterns,
                 ...(pathAdjudication.cwd !== undefined ? { rootPath: pathAdjudication.cwd } : {}),
+                ...dataRootOpt,
             });
+            const transcriptGuard = config.localDataRoot !== undefined
+                ? createTranscriptIntegrityPolicy({ sessionsDirs: [join(config.localDataRoot, "sessions")] })
+                : undefined;
+            const withTranscripts = (p) => (transcriptGuard ? combinePolicies(p, transcriptGuard) : p);
             if (pathAdjudication.cwd !== undefined)
-                return realTarget;
-            return combinePolicies(realTarget, createSensitivePathPolicy({ env: new RelativeTargetLexicalEnv(), patterns: config.sensitiveWritePatterns }));
+                return withTranscripts(realTarget);
+            return withTranscripts(combinePolicies(realTarget, createSensitivePathPolicy({ env: new RelativeTargetLexicalEnv(), patterns: config.sensitiveWritePatterns, ...dataRootOpt })));
         })()
         : undefined;
     return {

package/dist/http/routes/approvals-assistant.js

@@ -177,6 +177,9 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                     ...(s.spentMicroUsd !== undefined ? { spentMicroUsd: s.spentMicroUsd } : {}),
                     ...(s.deadline !== undefined ? { deadline: s.deadline } : {}),
                     ...(s.hasBidiControls === true ? { hasBidiControls: true } : {}),
+                    ...(s.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                    ...(s.denialLimitFallback !== undefined ? { denialLimitFallback: s.denialLimitFallback } : {}),
+                    ...(s.origin !== undefined ? { origin: s.origin } : {}),
                     objective: ctx?.body?.objective ?? null,
                     input,
                 };

package/dist/http/routes/capabilities.js

@@ -9,6 +9,7 @@ import { mcpInjectionHonored } from "../../task-mcp.js";
 import { sendJson, sendError } from "../send.js";
 import { resolveStreamApprovalGate } from "../../tool-approval.js";
 import { projectMemoryEngineCapability } from "../../memory-posture.js";
+import { projectSqlEngineCapability } from "../../sql-engine-posture.js";
 import { workflowModelAllowlistFor, selfOrchestrationDenial } from "../../task-workflow.js";
 import { centerEntitlementSourceWired } from "../../runtime-caps-resolver.js";
 import { judgeAutoModeArming } from "../../auto-mode-face.js";
@@ -76,6 +77,7 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             memory: false,
             memoryWrite: false,
             memoryEngine: projectMemoryEngineCapability(deps.memoryPosture),
+            sql: projectSqlEngineCapability(deps.sqlEngineFacts?.()),
             sessionBackgroundable: Boolean(deps.runStore),
             runMemoryCaptureOptOut: Boolean(deps.runStore),
             sharedMemory: Boolean(deps.sharedMemoryStore && deps.orgMemoryDirectory),

package/dist/http/routes/diagnostics.js

@@ -86,6 +86,7 @@ async function handleDiagnosticsBody(req, res, url, ctx, miss) {
         sendJson(res, 200, {
             static: deps.staticWiring,
             memoryPosture: deps.memoryPosture ?? null,
+            sqlEngine: deps.sqlEngineFacts?.() ?? null,
             configApply: deps.configApplyState?.() ?? null,
             mcpRevocations: deps.mcpRevocationState?.() ?? null,
             serverGates: buildServerWiringGates({

package/dist/http/server.d.ts

@@ -654,6 +654,12 @@ export interface ServiceDeploymentDeps {
      *  `GET /v1/capabilities` 的 `memoryEngine` 位(窄投影)。缺席 = 这个进程不是由 composition root 装
      *  起来的(测试夹具形)⇒ 诊断面报 null、能力位取诚实下限 false。 */
     memoryPosture?: import("../memory-posture.js").MemoryPosture;
+    /** S-131:SQL 引擎姿态的 **live getter**(`sql-engine-posture.ts` 的单一推导点 —— boot 期借一条池连接
+     *  触发驱动的连接初始化,读的是 `SET` 之后**回读复核**过的真值)。两个读面共用:
+     *  `GET /v1/diagnostics/wiring` 的 `sqlEngine` 段(operator-only,全量含版本)与 `GET /v1/capabilities`
+     *  的 `sql` 位(窄投影)。getter 而不是快照:池重连后驱动会重新初始化并刷新事实,快照会说谎。
+     *  缺席 / 返回 null = 本部署没有 SQL 后端(env-only worker、local 文件后端)—— 诚实缺席,不铸空壳。 */
+    sqlEngineFacts?: () => import("../plugins/sql-driver.js").SqlEngineFacts | null;
     /** ① core ruling — SPLIT: `capabilities.workflows` = the ENGINE-CAN axis, boot-computed from core's own
      *  `workflowsCapability(deps)` (hardened script runner ∧ governance), NOT the `Boolean(workflowRunStore)` store
      *  proxy. Orthogonal to `workflowsList` (the durable-list axis = `workflowRunStore`). Falls back to the store

package/dist/main.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { Runner, InMemoryToolResultStore, TtlSessionStore, uuidv7, defaultTaskRegistry, createAllowDenyPolicy, workflowsCapability, probeSearchBackend, describeStaticWiring, expandTiers, DEFAULT_SUBAGENT_TOOL_NAME } from "@sema-agent/core";
+import { Runner, createPermissionRuleStoreProvider, InMemoryToolResultStore, TtlSessionStore, uuidv7, defaultTaskRegistry, createAllowDenyPolicy, workflowsCapability, probeSearchBackend, describeStaticWiring, expandTiers, DEFAULT_SUBAGENT_TOOL_NAME } from "@sema-agent/core";
 import { createSessionTitler } from "./session-titler.js";
 import { posIntEnv } from "./session-watch.js";
 import { selectEnvironmentTool } from "./capabilities/select-environment-tool.js";
@@ -128,7 +128,7 @@ async function main() {
     }
     const configCenter = await createConfigCenterRuntime({ config, logger, metrics, localRoot });
     await configCenter.applyLocalRemoteExec();
-    const { backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore, taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState, usageWindowStore, memoryPosture, taskListLane, } = await openStores({ config, logger, metrics, localRoot });
+    const { backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore, taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState, usageWindowStore, memoryPosture, taskListLane, sqlEngineFacts, } = await openStores({ config, logger, metrics, localRoot });
     const instanceId = uuidv7();
     const sessionCaptureRecordStore = backend?.sessionCaptureRecords();
     const memoryBundleFaces = memoryEngine ? createMemoryBundleFaces(memoryEngine, { ...(sessionCaptureRecordStore !== undefined ? { captureRecordStore: sessionCaptureRecordStore } : {}) }) : undefined;
@@ -153,7 +153,12 @@ async function main() {
     }
     const { brain, pricing, counterDegradeHook, costQuota, modelUsageTracker, promptManifestTracker, fleetUsage, fleetLease, tracer, sideQueryAccounting, toolResultStore, sessionPolicyStore, fileHistoryStore, } = createBudgetAndTracing({ config, logger, metrics, backend, breakerState });
     const permissionRuleStores = config.permissionRulesEnabled && backend ? backend.permissionRule() : undefined;
-    const ruleConsent = permissionRuleStores ? createRuleConsentLane(permissionRuleStores) : undefined;
+    const permissionRuleProvider = permissionRuleStores
+        ? createPermissionRuleStoreProvider({ durable: permissionRuleStores.durable })
+        : undefined;
+    const ruleConsent = permissionRuleStores && permissionRuleProvider
+        ? createRuleConsentLane({ ...permissionRuleStores, provider: permissionRuleProvider })
+        : undefined;
     if (config.permissionRulesEnabled && permissionRuleStores === undefined) {
         logger.info("permission_rules_lane_unavailable", {
             knob: "PERMISSION_RULES_ENABLED",
@@ -268,7 +273,7 @@ async function main() {
         sessionCaptureRecordStore,
         memorySyncRunner, toolResultStore: runnerOffloadStore, sessionPolicyStore, runtimeCapsResolver, fileHistoryStore,
         legacyRewindBoundaryProbe: backend?.legacyRewindBoundaryProbe ? backend.legacyRewindBoundaryProbe.bind(backend) : undefined,
-        permissionRuleStore: permissionRuleStores?.provider,
+        permissionRuleStore: permissionRuleProvider,
         executionEnvFactory, lspManager, fleetBus, deploymentHooks, workflowRunStore, workflowJournalStore,
         workflowAgentRegistry, workflowNotifyGate, workflowCompletionInbox, deliverWorkflowCompletion, orgMemoryAdmission,
         governanceSeams,
@@ -475,6 +480,7 @@ async function main() {
     const parkedReviveInheritedGate = parkedReviveTool && config.durableApproval
         ? createParkedReviveInheritedGate({
             config, question, approvalExemptionStore, logger, localRoot,
+            memoryEngineRoot: memoryEngine?.root,
             approverSeat: createRunnerDepsOnAsk(toolApproval),
             ...(runnerDeps.runtimeCapsResolver ? { resolveRuntimeCaps: runnerDeps.runtimeCapsResolver } : {}),
             autoModeSeatMounted: runnerDeps.autoMode !== undefined,
@@ -694,6 +700,7 @@ async function main() {
         workflowModelAllowlist: workflowModelAllowlistSnapshot,
         staticWiring,
         memoryPosture,
+        sqlEngineFacts,
         instanceId,
         capabilities: {
             version: serviceVersion(),

package/dist/memory-scope.d.ts

@@ -84,6 +84,26 @@ engineWired: boolean): {
  * Returns the backend + the resolved config root (the root also rides on `RunnerDeps.memoryEngineDir` so
  * core derives the B3 control plane beside it).
  */
+/**
+ * S-133(7.59.0 合并重扫 wf_5ac18676 #1)—— **引擎数据根的唯一推导点**。模型是用 fs 工具往这里写记忆的
+ * ([ref] 记忆边界不变式,boot/memory-boundary.ts),所以三件事必须读**同一只**值:①boot 起哪只记忆后端的根
+ * (boot/stores.ts 三腿)、②`RunnerDeps.memoryEngineDir`、③守卫集 `createSensitivePathPolicy` 的 `dataRoot`
+ * (deployment-governance.ts:落在这个根**里面**的目标按相对根判,根自己的祖先段不算目标的账)。
+ * 此前 ③ 读的是 `config.localDataRoot`(本地**店**根:`LOCAL_DATA_ROOT → CONFIG_LOCAL_DIR → AGENT_DATA_DIR`),
+ * 而 ① 的 file 腿读的是 `MEMORY_ENGINE_DIR ?? AGENT_DATA_DIR`——两条链在「店根另指他处 + 记忆根坐在守卫段下
+ * (壳布局 `~/.sema/engine-data`)」时分家 ⇒ 记忆库每一次 Write 被硬拒(7.58.0 放行 ⇒ 回归);反向
+ * (`CONFIG_LOCAL_DIR=~/.sema` 当 dataRoot)则让配置根自身免检。两根本就是两件事:店根归誊本门,引擎根归本函数。
+ *
+ * 形与 boot/stores.ts 逐字同律:DB 记忆腿(pg/tidb)的根 = `<localDataRoot ?? fallbackRoot>/memory-work`
+ * (per-worker 物化区);file 腿 = `resolveMemoryEngineRoot(memoryEngineDir ?? fallbackRoot)`。**不判引擎是否
+ * 启用**——纯路径推导,禁用态下守卫仍以「若开引擎会写到哪」为根,与 core 缺省(`$AGENT_DATA_DIR`)同向。
+ */
+export declare function memoryEngineRootFor(config: Pick<ServiceConfig, "memoryEngineBackend" | "memoryEngineDir" | "localDataRoot">, fallbackRoot?: string): string;
+/** file 后端的根链(`MEMORY_ENGINE_DIR ?? fallback ?? $AGENT_DATA_DIR ?? ~/.ai-agent`)—— 与后端选择器**无关**:
+ *  `memoryEngineBackendFor` 恒造 file 后端(run-local 从 env 继承 `MEMORY_ENGINE_BACKEND=pg|tidb` 时仍是 file),
+ *  所以它的根必须走这条链而不是 `memoryEngineRootFor` 的分派(codex 修复验证轮 [medium]:分派会把 run-local 的
+ *  记忆搬到 `<localDataRoot>/memory-work`,存量记忆与控制面升级后隐形)。 */
+export declare function fileMemoryEngineRoot(config: Pick<ServiceConfig, "memoryEngineDir">, fallbackRoot?: string): string;
 export declare function memoryEngineBackendFor(config: ServiceConfig, fallbackRoot?: string): {
     backend: FileMemoryEngineBackend;
     root: string;

package/dist/memory-scope.js

@@ -60,12 +60,20 @@ export function buildMemoryRemoteLaneWarn(config, engineWired) {
                 "WORKER fs; verify the lane really shares it.",
         };
 }
+export function memoryEngineRootFor(config, fallbackRoot) {
+    if (config.memoryEngineBackend !== "file")
+        return join(config.localDataRoot ?? fallbackRoot ?? resolveMemoryEngineRoot(undefined), "memory-work");
+    return fileMemoryEngineRoot(config, fallbackRoot);
+}
+export function fileMemoryEngineRoot(config, fallbackRoot) {
+    return resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot);
+}
 export function memoryEngineBackendFor(config, fallbackRoot) {
     if (config.requirePrincipal === true || !config.memoryEngineEnabled)
         return undefined;
     if (memoryEngineRemoteLanePosture(config)?.posture === "dark")
         return undefined;
-    const root = resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot);
+    const root = fileMemoryEngineRoot(config, fallbackRoot);
     const dir = join(root, "memory");
     return { backend: new FileMemoryEngineBackend(dir, { controlDir: deriveControlPlaneDir(root, dir) }), root };
 }

package/dist/observability/run-terminal-log.d.ts

@@ -60,6 +60,10 @@ export declare function redactTerminalResult<T extends {
     remoteEnvFailures?: readonly {
         message?: string | undefined;
     }[] | undefined;
+    /** 🔴 形上**故意**是 `unknown`:本函数也是**读面**(旧持久 blob / 非 core Runner 的形不可信),
+     *  声明成 `{path,edits}[]` 会逼每一个喂坏形的调用点铸一次宽松断言 —— 而「坏形从哪来」正是本座要
+     *  处理的事(同一份不信任在 `remoteEnvFailures` 的实现里也已成文)。运行期逐项判形,不抛。 */
+    editedFiles?: unknown;
 } | null | undefined>(result: T): T;
 /** S-107(第五轮合并重扫 wf_f00c00bc 两根 [high]):同一个 `TaskResult` 除 run 行外还被逐字追加进 run_events 的 `done` 行
  *  (bg/verify/cascade/stream/resume 五腿),`failed` 行带原文 `errorMessage`,`GET /v1/runs/:id/events` 原样回放。

package/dist/observability/run-terminal-log.js

@@ -74,6 +74,7 @@ export function redactErrorMessage(raw) {
         return OVERSIZED_REDACTION_PLACEHOLDER;
     }
 }
+const MAX_EDITED_FILES = 1000;
 export function redactTerminalResult(result) {
     if (result === undefined || result === null)
         return result;
@@ -94,6 +95,19 @@ export function redactTerminalResult(result) {
             : r.remoteEnvFailures;
         changed = true;
     }
+    if (r.editedFiles !== undefined) {
+        out.editedFiles = Array.isArray(r.editedFiles)
+            ? r.editedFiles
+                .slice(0, MAX_EDITED_FILES)
+                .map((f) => {
+                if (f === null || typeof f !== "object")
+                    return f;
+                const path = f.path;
+                return typeof path === "string" ? { ...f, path: redactSecrets(path) } : f;
+            })
+            : r.editedFiles;
+        changed = true;
+    }
     return changed ? out : result;
 }
 export function redactLedgerEventData(type, data) {

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -14,10 +14,10 @@
  *    (`rev = rev + 1`),这样只要「行在且谓词命中」就必然 affected=1,不会被这个驱动怪癖
  *    误判成「CAS 输了」。本文件每一条 CAS UPDATE 都带 `rev = rev + 1`。
  * 3. 事务:走 `SqlDriver.connect()` → `conn.begin()` → 一串 `conn.query()` → `conn.commit()`,失败
- *    `conn.rollback()`(形照 image-bake-store-sql.ts 的 try/catch/finally 骨架)。本店没有 image-bake
- *    那种「NOT EXISTS 快照读」问题(每条 CAS 都是对已存在主键行的 `UPDATE … WHERE state=?`,MySQL/TiDB
- *    对被更新行本身恒是 current read,不受 REPEATABLE READ 快照影响),所以走普通 `begin()`,不需要
- *    `beginPessimistic()`。
+ *    `conn.rollback()`(形照 image-bake-store-sql.ts 的 try/catch/finally 骨架)。事务动词只有一个;
+ *    读语义(隔离级 / TiDB 悲观模式 / 事务内集合读必须锁读)的判据只有一处:{@link SqlTxConn.begin}
+ *    的 `@contract txn.read-semantics`。本店每条 CAS 都是对已存在主键行的 `UPDATE … WHERE state=?`
+ *    (DML 对被更新行恒是 current read,与快照无关),败方读数则一律 `SELECT … FOR UPDATE`。
  *
  * ── 方言差异(显式写在每个调用点,[ref] A12 doctrine)──────────────────────────────────────────
  *   - `?` 占位符(位置序)vs `$n`(显式编号)——动态列清单(`transitionAsk`/`resolveProvisional`,列集合
@@ -503,11 +503,11 @@ export declare class SqlApprovalAskStore implements ApprovalAskStore {
      * 取消臂的 STREAM_PENDING→VOID(此前走通用 `transitionAsk`,无败方读数)。
      *
      * **原子性证明(两方言各一句,红先钉在 db-integration 的 [ref] 组)**:
-     *  · 败方读数是**同一事务内**的 `SELECT … FOR UPDATE` —— TiDB 侧本事务显式 `BEGIN PESSIMISTIC`
-     *    (`beginPessimistic()`,不赌部署的 `tidb_txn_mode` 缺省):悲观锁定读是 CURRENT read,读到的是
-     *    并发赢家**已提交**的最新版本(乐观模式下 FOR UPDATE 读 start_ts 快照,会把赢家终局读旧 ——
-     *    正是 bindBatch 失败臂注记的那类方言分歧,这里用显式事务模式把它结构性关死);PG 侧
-     *    `beginPessimistic()` = 普通 `BEGIN`,READ COMMITTED 下 FOR UPDATE 本就等待并返回最新已提交版本。
+     *  · 败方读数是**同一事务内**的 `SELECT … FOR UPDATE` —— TiDB 侧的悲观锁定读是 CURRENT read,读到的是
+     *    并发赢家**已提交**的最新版本(乐观模式下 FOR UPDATE 读 start_ts 快照,会把赢家终局读旧 —— 正是
+     *    bindBatch 失败臂注记的那类方言分歧)。悲观模式**不赌部署的 `tidb_txn_mode` 缺省**:它是连接初始化
+     *    的结构保证,设不上就拒启({@link SqlTxConn.begin} 的 @contract txn.read-semantics)。PG 侧
+     *    `BEGIN` = READ COMMITTED,FOR UPDATE 本就等待并返回最新已提交版本。
      *  · CAS 输(affected=0)⇒ 行在 UPDATE 那一刻已非 STREAM_PENDING(或不在/错 scope),而非 pending 态
      *    在状态机上无回边 ⇒ 锁定读读到的恒 ≥ 线性化点,且 DECIDED 决议不可变 —— 答案自足。
      *  · 本事务在输臂上除批行 rev 自增外零写,rollback 无痕。

package/dist/plugins/approval-ask-store-sql.js

@@ -440,7 +440,7 @@ export class SqlApprovalAskStore {
         const dialect = this.db.dialect;
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             if (intent === "expire") {
                 const lockRes = await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET rev=rev+1 WHERE batch_id=?`, `UPDATE ${APPROVAL_BATCH_TABLE} SET rev=rev+1 WHERE batch_id=$1`), [batchId]);
                 if (lockRes.affected !== 1) {

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

@@ -18,9 +18,11 @@
  *    ——**所有** CAS UPDATE 因此必须带一个恒变列(`rev = rev + 1`)。本文件每一条 CAS UPDATE 都带。
  *    在本店这条尤其致命:心跳续租在「同一毫秒内重复心跳」时 SET 的值可能与当前值相同,没有 rev
  *    就会被判成「本连接已失权」⇒ 设备被自己的心跳踢下线。
- * 3. 事务:`SqlDriver.connect()` → `begin()`/`beginPessimistic()` → `query()` → `commit()`,失败
- *    `rollback()`。**失败臂的回读必须走当前这条 `conn`**(approval 店复审 F1 的真缺陷:走池级 query
- *    会与自己持有的连接死锁),且**先 rollback 再读**(读到最新已提交视图)。
+ * 3. 事务:`SqlDriver.connect()` → `begin()` → `query()` → `commit()`,失败 `rollback()`。读语义
+ *    (隔离级 / TiDB 悲观模式 / 事务内集合读必须锁读)的判据只有一处:`sql-driver.ts` 头注的
+ *    {@link SqlTxConn.begin} `@contract txn.read-semantics`。**失败臂的回读必须走当前这条 `conn`**
+ *    (approval 店复审 F1 的真缺陷:走池级 query 会与自己持有的连接死锁),且**先 rollback 再读**
+ *    (回滚后本连接回到 autocommit,那条 SELECT 自成事务 ⇒ 读到最新已提交视图)。
  *
  * ── 方言差异(A12 doctrine:每处显式写在调用点)────────────────────────────────────────────────────
  *   - `?`(位置序) vs `$n`(显式编号);动态 WHERE(`listAudit`)靠 `ph(dialect, n)` 生成。
@@ -129,20 +131,46 @@ export declare class SqlDeviceStore implements DeviceStore {
     heartbeatConnection(input: HeartbeatConnectionInput): Promise<boolean>;
     releaseConnection(deviceId: string, generation: number): Promise<boolean>;
     /**
-     * §4.3.2 首绑写协议 —— **单事务**:设备校验(active ∧ owner)与 `INSERT IGNORE` 在一个事务里。
+     * §4.3.2 首绑写协议 —— **单事务**:设备校验(active ∧ owner)与首绑 CAS 插入在一个事务里。
      *
-     * 🔴 `beginPessimistic` + `FOR UPDATE`:设备行必须是**当前读**。快照读下,一次与吊销并发的绑定会
-     * 读到「还 active」的旧版本,于是把 session 绑到一台**刚被吊销**的设备上(sql-driver.ts 头注点名的
-     * double-admit 形)。
-     * 并发首绑:`INSERT IGNORE` / `ON CONFLICT DO NOTHING` 的 affected 是引擎对「谁赢」的权威回答;
-     * 输家回读既有行 —— 同 deviceId = 幂等成功,异 deviceId = `conflict`(无未定义态)。
+     * 🔴 `FOR UPDATE`(设备行):设备行必须是**当前读**。普通读下,一次与吊销并发的绑定会读到「还 active」
+     * 的旧版本,于是把 session 绑到一台**刚被吊销**的设备上(double-admit 形)。锁读在两引擎都是当前读 ——
+     * 前提写在 {@link SqlTxConn.begin} 的 @contract txn.read-semantics。这把锁在 `devices` 表上,与下面
+     * 被插入的 `device_session` 行不是同一行。
+     *
+     * 🔴 形 B · cas-insert(S-127 / B-013)—— 本站点是全仓 `INSERT IGNORE` 的**正当用法**:
+     * `INSERT IGNORE` / `ON CONFLICT DO NOTHING` 的 affected(1/0)是引擎对「谁赢」的**权威**回答,而
+     * `ON DUPLICATE KEY UPDATE pk = pk` 的 affected 新行/既有行都是 1、分不出赢家 ⇒ 这里换不得动词。
+     * 代价必须付清:**同一事务此后不得对被插入的那一行做加锁读**。InnoDB 下撞重复键的 IGNORE 在既有行
+     * 取 **S 锁**,随后的 `SELECT … FOR UPDATE` 要升 X;两个并发首绑各持一把 S 互等 ⇒ ER_LOCK_DEADLOCK
+     * (TiDB 悲观事务无共享锁,这一形在它上面恒绿 —— 双库门看不见)。于是两条路径分家:
+     *  · **赢家**(affected === 1):行是自己刚插的,回执用**入参 + 插入时刻**直接构造,零回读。插入时刻
+     *    仍由 **DB 时钟**给出(插入前一句 `SELECT NOW(3)` / `SELECT now()`,再把它当参数写进 INSERT)——
+     *    时间权威留在 DB,回执里的 `boundAtMs` 与落库值**逐字节同一个**,不是应用侧的近似。
+     *  · **输家**(affected === 0):**结束当前事务**,在**新事务**里 `SELECT … FOR UPDATE` 观察。那一刻
+     *    赢家已提交,读到的是一把干净的 X 锁(无升级);判 同 deviceId = 幂等成功,异 deviceId =
+     *    `conflict`(无未定义态)。设备状态门在输家路径上已经过完,不需要重来。
      */
     bindSession(input: BindSessionInput): Promise<BindSessionResult>;
+    /**
+     * 首绑 CAS 的**输家观察**(形 B 的后半,S-127)—— 独立事务,与那次 `INSERT IGNORE` 无锁关系。
+     *
+     * 🔴 `FOR UPDATE`(**真库红修**,2026-08-28 双库跑当场抓到,mock 抓不到):TiDB 的悲观事务里**普通
+     * SELECT 仍是快照读**(读的是本事务 start_ts 的视图),只有加锁读才是当前读。放在新事务里读同样要
+     * 这把锁 —— 新事务的 start_ts 虽在赢家提交之后,但「读的是不是当前」这条判据不该靠时序巧合来满足。
+     * 与旧形的**唯一**差别:此刻我们手上没有那一行的 S 锁,于是这把 X 是**直接取**的,不是升级 ⇒ 两个
+     * 并发输家不会互等(B-013 的死锁形正是那次升级)。
+     *
+     * 行不在 = 赢家的绑定在这一瞬被 `unbindSession` 删了(真实可能,不是不变量破)。这仍然是**响亮**的:
+     * 首绑既没成、也说不出冲突对象,折成任何一种业务回执都是撒谎([ref]:未知失败不伪装成正常拒绝)。
+     */
+    private observeLostBind;
     /**
      * O4 显式换绑(2026-08-30 v2 稿 §2)—— **单事务**:目标设备门(当前读)+ 幂等短路 + 前态 CAS +
      * `session_rebound` 审计行一起提交。三形语义 oracle = `InMemoryDeviceStore.rebindSession`。
      *
-     * 🔴 `beginPessimistic` + 两次 `FOR UPDATE`(bindSession 的同一条真库红的射程):
+     * 🔴 两次 `FOR UPDATE`(bindSession 的同一条真库红的射程;当前读的前提见
+     * {@link SqlTxConn.begin} 的 @contract txn.read-semantics):
      *  · 设备行必须当前读 —— 快照读会把「与吊销并发的换绑」绑到一台刚被吊销的设备上(double-admit 形);
      *  · 绑定行必须当前读且**持锁到提交** —— 两个并发换绑(同 expectedRev)在锁上串行:赢家 rev+1 提交,
      *    输家的锁读看到新 rev ⇒ 走 `rev_conflict` 携当前行(单赢家,无未定义态)。锁读判等之后,CAS

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

@@ -367,7 +367,7 @@ export class SqlDeviceStore {
         }
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             const cas = await conn.query(this.q(`UPDATE ${DEVICE_ENROLL_TOKENS_TABLE} SET consumed_at = NOW(3), consumed_device_id = ?, consumed_pubkey = ?, rev = rev + 1
             WHERE token_hash = ? AND consumed_at IS NULL AND expires_at > NOW(3) AND target_tenant = ? AND target_subject = ?`, `UPDATE ${DEVICE_ENROLL_TOKENS_TABLE} SET consumed_at = now(), consumed_device_id = $1, consumed_pubkey = $2, rev = rev + 1
             WHERE token_hash = $3 AND consumed_at IS NULL AND expires_at > now() AND target_tenant = $4 AND target_subject = $5`), [input.device.deviceId, input.device.pubkey, input.tokenHash, input.requester.tenant, input.requester.subject]);
@@ -454,7 +454,7 @@ export class SqlDeviceStore {
         assertRevokeShape(input);
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             const cas = await conn.query(this.q(`UPDATE ${DEVICES_TABLE} SET status = 'revoked', revoked_at = NOW(3), revoked_by = ?, revoke_reason = ?, lease_expires_at = NULL, conn_generation = conn_generation + 1, rev = rev + 1
             WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? AND status = 'active'`, `UPDATE ${DEVICES_TABLE} SET status = 'revoked', revoked_at = now(), revoked_by = $1, revoke_reason = $2, lease_expires_at = NULL, conn_generation = conn_generation + 1, rev = rev + 1
             WHERE device_id = $3 AND owner_tenant = $4 AND owner_subject = $5 AND status = 'active'`), [input.revokedBy, input.reason ?? null, input.deviceId, input.owner.tenant, input.owner.subject]);
@@ -484,7 +484,7 @@ export class SqlDeviceStore {
         assertAcquireShape(input);
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             const cas = await conn.query(this.q(`UPDATE ${DEVICES_TABLE} SET conn_generation = conn_generation + 1, conn_epoch = ?, replica_id = ?, lease_expires_at = ${nowPlusSeconds("tidb", "?")}, connected_at = NOW(3), last_seen_at = NOW(3), rev = rev + 1
             WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? AND status = 'active' AND (lease_expires_at IS NULL OR lease_expires_at <= NOW(3))`, `UPDATE ${DEVICES_TABLE} SET conn_generation = conn_generation + 1, conn_epoch = $1, replica_id = $2, lease_expires_at = ${nowPlusSeconds("pg", "$3")}, connected_at = now(), last_seen_at = now(), rev = rev + 1
             WHERE device_id = $4 AND owner_tenant = $5 AND owner_subject = $6 AND status = 'active' AND (lease_expires_at IS NULL OR lease_expires_at <= now())`), [input.connEpoch, input.replicaId, input.leaseSeconds, input.deviceId, input.owner.tenant, input.owner.subject]);
@@ -523,7 +523,7 @@ export class SqlDeviceStore {
         assertDeviceOwnerShape(input.owner);
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             const dev = await conn.query(this.q(`SELECT status FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? FOR UPDATE`, `SELECT status FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3 FOR UPDATE`), [input.deviceId, input.owner.tenant, input.owner.subject]);
             if (!dev.rows[0]) {
                 await conn.rollback();
@@ -533,14 +533,33 @@ export class SqlDeviceStore {
                 await conn.rollback();
                 return { outcome: "device_revoked" };
             }
-            const ins = await conn.query(this.q(`INSERT IGNORE INTO ${DEVICE_SESSIONS_TABLE} (root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev) VALUES (?, ?, ?, ?, NOW(3), 0)`, `INSERT INTO ${DEVICE_SESSIONS_TABLE} (root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev) VALUES ($1, $2, $3, $4, now(), 0) ON CONFLICT (root_session_id) DO NOTHING`), [input.rootSessionId, input.deviceId, input.owner.tenant, input.owner.subject]);
+            const clock = await conn.query(this.q(`SELECT ${ms("tidb", NOW("tidb"), "bound_at_ms")}`, `SELECT ${ms("pg", NOW("pg"), "bound_at_ms")}`));
+            const boundAtMs = Number(clock.rows[0].bound_at_ms);
+            const ins = await conn.query(this.q(`INSERT IGNORE INTO ${DEVICE_SESSIONS_TABLE} (root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev) VALUES (?, ?, ?, ?, FROM_UNIXTIME(? / 1000), 0)`, `INSERT INTO ${DEVICE_SESSIONS_TABLE} (root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev) VALUES ($1, $2, $3, $4, to_timestamp($5::double precision / 1000.0), 0) ON CONFLICT (root_session_id) DO NOTHING`), [input.rootSessionId, input.deviceId, input.owner.tenant, input.owner.subject, boundAtMs]);
+            if (ins.affected === 1) {
+                await conn.commit();
+                return { outcome: "bound", row: { rootSessionId: input.rootSessionId, deviceId: input.deviceId, owner: input.owner, boundAtMs, rev: 0 } };
+            }
+            await conn.rollback();
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+        return await this.observeLostBind(input);
+    }
+    async observeLostBind(input) {
+        const conn = await this.db.connect();
+        try {
+            await conn.begin();
             const { rows } = await conn.query(this.q(`SELECT ${sessionCols("tidb")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = ? FOR UPDATE`, `SELECT ${sessionCols("pg")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = $1 FOR UPDATE`), [input.rootSessionId]);
             await conn.commit();
             const row = rows[0] ? mapSessionRow(rows[0]) : null;
             if (!row)
-                throw new Error("device-store: session binding vanished immediately after insert");
-            if (ins.affected === 1)
-                return { outcome: "bound", row };
+                throw new Error("device-store: the winning session binding vanished before the losing binder could observe it");
             const same = row.deviceId === input.deviceId && row.owner.tenant === input.owner.tenant && row.owner.subject === input.owner.subject;
             return { outcome: same ? "idempotent" : "conflict", row };
         }
@@ -556,7 +575,7 @@ export class SqlDeviceStore {
         assertRebindShape(input);
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             const dev = await conn.query(this.q(`SELECT status FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? FOR UPDATE`, `SELECT status FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3 FOR UPDATE`), [input.toDeviceId, input.owner.tenant, input.owner.subject]);
             if (!dev.rows[0] || parseDeviceStatus(bufToStr(dev.rows[0].status)) !== "active") {
                 await conn.rollback();

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

@@ -61,6 +61,11 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      * row-locks the scope's sentinel row — one lock, both dialects, and disjoint-key writers can no
      * longer interleave into a merged/torn graph. The ensure+lock loops because deleteBySession removes
      * the sentinel: a waiter woken by that delete sees zero rows and must re-ensure.
+     *
+     * Shape A (S-127): the MySQL ensure verb is `ON DUPLICATE KEY UPDATE scope = scope`, NOT `INSERT IGNORE`.
+     * On InnoDB a duplicate-key IGNORE takes an **S** lock on the existing sentinel and the `FOR UPDATE` right
+     * below has to upgrade it to X — two concurrent scope writers each holding an S deadlock (B-013). ON
+     * DUPLICATE takes X on the duplicate key, the same mode the locking read wants, so they serialize instead.
      */
     private lockScope;
     /** Returns the UPDATE's affected count — 0 = the record is gone (annulled) or was already observed;
@@ -74,7 +79,11 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
         env: ExecutionEnv;
         signal?: AbortSignal;
     }): Promise<FileHistoryResult>;
+    /** `forUpdate` = the {@link SqlTxConn.begin} `@contract txn.read-semantics` ③ arm: a collection read that
+     *  runs inside a transaction must be a LOCKING read (a plain SELECT is pinned to the transaction's start on
+     *  TiDB, so the lock-wait window's commits are invisible — B-022). Pool-level callers pass nothing. */
     private loadTracked;
+    /** `forUpdate` — see {@link loadTracked}: inside a transaction this is a collection read, so it locks. */
     private loadVersions;
     /** [ref] twin 保留条款:这个 entry 的键是否**已花掉**(被 reap 剪过)。台账 `file_history_reaped_entry`。
      *  `forUpdate`(r3-①连带):发布 tx 内的复核必须是**锁定读**——TiDB 悲观事务的普通 SELECT 按文档读
@@ -104,14 +113,18 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** PROTECTED RACE SEAM (test-only override): runs inside `restore` between the boundary-header check and
      *  the mapping read. Production body is empty. */
     protected duringRestorePlan(_scope: string, _entryId: string): Promise<void>;
-    /** PROTECTED RACE SEAM (test-only override): runs inside the publish tx AFTER `beginPessimistic` and
-     *  BEFORE the scope lock — the window where another replica's publish can commit while this tx's
-     *  snapshot is already pinned (TiDB snapshot-reads plain SELECTs, D2). Production body is empty. */
+    /** PROTECTED RACE SEAM (test-only override): runs inside the publish tx AFTER `begin()` and BEFORE
+     *  the scope lock — the window where another replica's publish can commit while this tx's snapshot is
+     *  already pinned. That window is exactly what B-022 rode: a plain SELECT taken after the lock is still
+     *  pinned to the transaction's start, so this tx's collection reads are LOCKING reads
+     *  ({@link SqlTxConn.begin} → `@contract txn.read-semantics`). Production body is empty. */
     protected beforePublishLock(_scope: string): Promise<void>;
     /** PROTECTED RACE SEAM (test-only override): runs inside `exportOf` between the boundary-header read and
      *  the mapping read. Production body is empty. */
     protected duringExportGraph(_scope: string): Promise<void>;
     private applyBoundaryRetention;
+    /** `forUpdate` — see {@link loadTracked}: the in-transaction re-check must be a LOCKING read, or it just
+     *  replays the pool-level pre-check's snapshot and its documented `null` arm becomes unreachable. */
     private boundaryExists;
     snapshot(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryResult>;
     restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryRestoreResult>;
@@ -141,6 +154,10 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     hasBlobs(hashes: string[]): Promise<Set<string>>;
     adoptScope(fromScope: string, toScope: string): Promise<FileHistoryResult>;
     private scopeEmpty;
+    /** `forUpdate` — see {@link loadTracked}. Every in-transaction caller passes `true`: the four reads are
+     *  one graph, and a graph materialized from a start-of-transaction snapshot disagrees with the LOCKING
+     *  emptiness probe that decided to materialize it (that disagreement answered a legal idempotent
+     *  re-import as `conflict` — B-022). */
     private exportOf;
     exportHistory(scope: string): Promise<FileHistoryExport | null>;
     importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;