@sema-agent/server 7.37.0 → 7.38.0-rc.2

package/dist/plugins/tidb-session-store.js

@@ -16,6 +16,7 @@ import { TiDBSessionStorage } from "./tidb-session-storage.js";
 import { escapeLike } from "./sql-escape.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
+import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, // 两孪生店同源(理由见 kernel 处顶注:同值双抄单边改值 ⇒ 两后端 GC 判定分家)
  } from "../session-sync-kernel.js";
 export class TiDBSessionStore {
@@ -23,6 +24,10 @@ export class TiDBSessionStore {
     /** #270 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而实现体在别处」逐字见
      *  `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
     retention = MANAGED_RETENTION;
+    /** #292 C18(core 5.48.0 design/323):placement **声明**。六条义务的实装点逐条见
+     *  {@link SQL_SESSION_PLACEMENTS} 顶注与本类的 acquire / listSessions / release / listPlaced /
+     *  placementOf 各处的 `#292` 注。 */
+    placements = SQL_SESSION_PLACEMENTS;
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     pending = new Map();
     constructor(pool) {
@@ -31,42 +36,95 @@ export class TiDBSessionStore {
     async acquire(sessionId, opts) {
         if (!sessionId) {
             const id = uuidv7();
-            await this.register(id, null);
-            return this.load(id);
+            // #292 义务:placement 与行**同一条 INSERT** 落库(创建时一次落行,first-write 不可变)。
+            await this.register(id, null, opts?.placement);
+            return this.load(id, false, opts);
         }
         // design/114 Phase3 (F1): a `requireExisting` acquire NEVER creates and can REJECT (not_found) — it MUST bypass
         // the shared create-dedup `pending`, else a concurrent create-capable waiter awaiting that same promise would
         // inherit the not_found rejection instead of creating-on-miss. Two concurrent requireExisting opens each just
         // wake independently (both resolve or both fail loud) — harmless (it only opens, never double-creates).
         if (opts?.requireExisting)
-            return this.load(sessionId, true);
+            return this.load(sessionId, true, opts);
+        // #292:准入判据**按调用方逐一判**(core `TtlSessionStore` 的同款纪律)——共享的 in-flight promise
+        // 只共享「会话被唤醒」这件事,绝不让一个 claim 形等待者继承可信创建方的准入,或反过来。
         const inflight = this.pending.get(sessionId);
-        if (inflight)
-            return inflight;
-        const p = this.load(sessionId).finally(() => this.pending.delete(sessionId));
+        if (inflight) {
+            const acquired = await inflight;
+            assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
+            return acquired;
+        }
+        const p = this.load(sessionId, false, opts).finally(() => this.pending.delete(sessionId));
         this.pending.set(sessionId, p);
         return p;
     }
-    async load(sessionId, requireExisting = false) {
+    async load(sessionId, requireExisting = false, opts) {
         let storage = await TiDBSessionStorage.wake(this.pool, sessionId);
+        if (storage) {
+            // #292 义务 6(claim 关门)+ 镜像方向:判据吃的是**已持久化**的元组(wake 顺路带回,零额外往返)。
+            assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
+            return { session: new StoredSession(storage), sessionId };
+        }
+        // design/114 Phase3: `requireExisting` ⇒ FAIL LOUD on a genuinely missing session (no session_meta row),
+        // never the silent create-on-miss that turns a reuse-style warm-resume into a fresh empty run. core's
+        // prepare-task maps this store `not_found` to the caller-facing `resume.session_not_found`.
+        if (requireExisting)
+            throw new SessionError("not_found", `session ${sessionId} not found`);
+        // No meta row yet (a caller-chosen brand-new id the service didn't pre-register). Create it
+        // ownerless; only the caller who chose this id can reach it, and it holds no prior data.
+        await this.register(sessionId, null, opts?.placement);
+        storage = await TiDBSessionStorage.wake(this.pool, sessionId);
+        // 刚 register 完却唤不醒 = 有人在这两步之间把行删了(带外 purge / 留存腿)。旧形在这里是一个
+        // `storage!` 非空断言,真撞上时炸成一条无信息的 `TypeError: reading 'getMetadata' of null`
+        // (本批实测撞到过一次:邻车在同一测试库上整表 DELETE)。改成响亮且**说得出发生了什么**的错。
         if (!storage) {
-            // design/114 Phase3: `requireExisting` ⇒ FAIL LOUD on a genuinely missing session (no session_meta row),
-            // never the silent create-on-miss that turns a reuse-style warm-resume into a fresh empty run. core's
-            // prepare-task maps this store `not_found` to the caller-facing `resume.session_not_found`.
-            if (requireExisting)
-                throw new SessionError("not_found", `session ${sessionId} not found`);
-            // No meta row yet (a caller-chosen brand-new id the service didn't pre-register). Create it
-            // ownerless; only the caller who chose this id can reach it, and it holds no prior data.
-            await this.register(sessionId, null);
-            storage = await TiDBSessionStorage.wake(this.pool, sessionId);
+            throw new SessionError("storage", `session ${sessionId} vanished between register and wake (a concurrent purge won the race) — retry`);
         }
+        // #292 镜像方向(pre-claim squat):带 placement 的创建必须**回读**到持久化的同组元组——并发的
+        // claim 形若抢先建出普通行,我们的 INSERT 是 no-op,回读即缺席 ⇒ 响亮拒(不是静默降级成普通会话)。
+        assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
         return { session: new StoredSession(storage), sessionId };
     }
-    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten. */
-    async register(sessionId, owner) {
+    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
+     *  #292:`placement` 在场时与行同一条 INSERT 落六列;ON DUPLICATE 臂是 no-op ⇒ 已存在的行的元组
+     *  **永不被重写**(first-write 不可变,义务 5 的写侧半场)。 */
+    async register(sessionId, owner, placement) {
         const now = new Date();
-        await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) " +
-            "VALUES (?,?,?,?,NULL,0) ON DUPLICATE KEY UPDATE session_id = session_id", [sessionId, owner, now, now]);
+        await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, " +
+            "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +
+            "VALUES (?,?,?,?,NULL,0,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE session_id = session_id", [sessionId, owner, now, now, ...placementInsertValues(placement, now)]);
+    }
+    /**
+     * #292 义务 6 的廉价探针 —— 一行 PK SELECT:`undefined` = 普通会话或无此行。
+     * (release 的冷缓存腿、包装店的暖命中准入判、诊断面共用这一只。)
+     */
+    async placementOf(sessionId) {
+        const [rows] = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = ?`, [sessionId]);
+        return placementFromRow(rows[0]);
+    }
+    /**
+     * #292 义务 5 —— placed 分区的**自有枚举**(联合 reap 的分区腿输入)。
+     *
+     * 年龄锚 = `COALESCE(updated_at, placed_at)`:`updated_at` 是本店的「最后活动」标记(register 时置、
+     * 每次 append/touch 推进),取不到才回落 `placed_at` —— 与 core File 店「mtime 优先、placedAt 回落」
+     * 的读法同义。行按年龄升序、上界 {@link LIST_PLACED_BATCH}(理由见那里)。
+     * join 半缺(scope/handle 任一为 NULL)⇒ `tupleIncomplete` 诚实变体,消费方对它 fail-closed。
+     */
+    async listPlaced(kind, opts) {
+        const params = [kind];
+        let sql = `SELECT session_id, updated_at, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE placement_kind = ?`;
+        if (opts?.scope !== undefined) {
+            sql += " AND placement_scope = ?";
+            params.push(opts.scope);
+        }
+        if (opts?.olderThanMs !== undefined) {
+            sql += " AND COALESCE(updated_at, placed_at) < ?";
+            params.push(new Date(Date.now() - opts.olderThanMs));
+        }
+        sql += " ORDER BY COALESCE(updated_at, placed_at) ASC LIMIT ?";
+        params.push(LIST_PLACED_BATCH);
+        const [rows] = await this.pool.query(sql, params);
+        return rows.map((r) => placedRowFromRow(String(r.session_id), r, r.updated_at instanceof Date ? r.updated_at.getTime() : undefined));
     }
     /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     async ownerOf(sessionId) {
@@ -97,9 +155,58 @@ export class TiDBSessionStore {
             return undefined;
         return { owner: rows[0].owner ?? null, leafId: rows[0].leaf_id ?? null };
     }
-    /** Durable history is retained; just drop any in-flight cache entry. */
+    /**
+     * Durable history is retained; just drop any in-flight cache entry.
+     *
+     * 🔴 #292 义务 4 —— **placed 会话例外:release 是真删除**(durable 史一并)。联合 reap 先按 rev 条件删
+     * 掉 agent 行、赢了才调本方法终结转录;若这里还按「归还租约」走,一条 30 天的转录就会失去属主行地
+     * 悬着(正是这条义务要关死的 strand)。判据取**持久化元组**(冷缓存/重启后照样成立,不依赖任何进程
+     * 内状态);删除本身是 ABA 安全的**条件删**(`placement_kind IS NOT NULL`)——探针与删除之间若真有
+     * 「行被删掉又以同 id 重建成普通会话」的世代翻转,条件删当场落空,不会误杀那只无辜的新会话。
+     * 删除失败**响亮上浮**(`SessionError("storage")`):吞掉失败等于让 reap 数一条「已终结」而字节还在
+     * (core File 店同批的 rmSync 失败上浮是同一条法)。
+     */
     async release(sessionId) {
         this.pending.delete(sessionId);
+        const placed = await this.placementOf(sessionId);
+        if (placed === undefined)
+            return; // 普通会话:acquire/release 语义逐字节不变(义务 3)
+        await this.deletePlacedSession(sessionId);
+    }
+    /**
+     * core B-17 的 `forget` 面 —— **丢引用,不动 durable 史**(与 {@link release} 的分工:release 是
+     * 生命周期终结口,forget 是「我用完了这只句柄」)。#292 之后这条分工是承重的:release 对 placed
+     * 会话已是真删除,于是每一处「只为验存在 / 写完收工」的收尾都必须落在 forget 上(preflight 纪律,
+     * [4743] 义务①)。本店的进程内状态只有 in-flight 去重表,故实现就是丢那一格。
+     */
+    forget(sessionId) {
+        this.pending.delete(sessionId);
+    }
+    /** 真删除一只 placed 会话的两张表(条件删门在 `placement_kind IS NOT NULL`;事务内 meta 先删=提交点,
+     *  与 {@link deleteSession} 同序)。任何 I/O 失败上浮成 `SessionError("storage")`,绝不吞。 */
+    async deletePlacedSession(sessionId) {
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            const [metaRes] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND placement_kind IS NOT NULL", [sessionId]);
+            if (metaRes.affectedRows > 0)
+                await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
+            await conn.commit();
+        }
+        catch (err) {
+            try {
+                await conn.rollback();
+            }
+            catch {
+                /* ignore */
+            }
+            throw err instanceof SessionError
+                ? err
+                : new SessionError("storage", `placed session ${sessionId} could not be deleted: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
+        }
+        finally {
+            conn.release();
+        }
     }
     // ───────────────────────── SessionRepo seam (§0.5 session-ownership) ─────────────────────────
     // E16/E17/E21: the service EXTENDS core's `SessionRepo` (list/fork/delete) over its OWN session_meta /
@@ -118,7 +225,10 @@ export class TiDBSessionStore {
      */
     async listSessions(opts) {
         const params = [];
-        const where = [];
+        // 🔴 #292 义务 2:placed 会话**永不上宿主枚举面**——壳的 /resume 选择器不许把一条子代转录当成可
+        // 续聊的会话摆出来(而且它一旦被选中,claim 形 acquire 还会当场拒)。谓词打在**持久化列**上 ⇒
+        // 重启后照样成立(义务的「restart-stable」一半)。
+        const where = ["sm.placement_kind IS NULL"];
         if (opts.owner) {
             // [4198] 窄互认第二臂的第三条件在此:`includeUnowned` 时谓词放宽到「本人的 ∪ 无主的」。
             // 仍然**不是** `owner IS NOT DISTINCT FROM ?`——具名的别人一行都不多给。
@@ -357,14 +467,28 @@ export class TiDBSessionStore {
      * point, so a mid-replace crash (post-delete, pre-insert) leaves orphan-free state (no meta = invisible to wake).
      */
     async replaceEntries(sessionId, owner, entries) {
+        // 🔴 #292:placed 会话不接受 session-sync 的整段换装。两条理由各自独立成立:①这条路径 DELETE 掉
+        // meta 行再重插,会**重写掉** placement 元组(first-write 不可变的写侧破口);②即便元组保住,一条
+        // 子代转录的内容被外部 push 覆盖,等于 agent 行还指着它、里面已经是别人的历史。⇒ 响亮拒。
+        await this.assertNotPlaced(sessionId, "replace"); // 快路(零工:命中即拒,不进事务)
         const validated = validateEntriesForImport(entries); // fail-closed gate BEFORE any write (mirrors importEntries)
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            // 🔴 #292(codex 对抗复审 R1-[high] 的同族窗,验真后修):上面那道快路是**事务外**的 ⇒ 与本事务
+            // 之间有 TOCTOU 窗。真门在事务内:①锁读一次元组(存在的行被行锁住;MySQL 的 gap lock 还会挡住
+            // 同键的并发 INSERT);②meta 的 DELETE 加 `placement_kind IS NULL` 硬条件 —— 即便判据被绕过,
+            // 一条 placed 行也**不可能**被这条路径删掉(placed 行的 owner 恒 NULL,而 replace(owner=null)
+            // 的属主门恰好匹配它 —— 没有这个条件,一次匿名 push 就能把子代转录整只换掉)。
+            const [placedRows] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
+            if (placedRows[0]?.placement_kind != null) {
+                await conn.rollback();
+                throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${String(placedRows[0].placement_kind)} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
+            }
             // Purge the existing log first (idempotent: a missing session deletes 0 rows). Events first, then the
             // owner-guarded meta delete (`owner <=> ?` — a legacy null-owner session matches owner=null), defense-in-depth.
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
-            await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ?", [sessionId, owner]);
+            await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
             // …then re-insert the validated log (entries + meta-as-commit-point) via the SHARED body.
             await this.insertValidatedLog(conn, sessionId, owner, validated);
             await conn.commit();
@@ -416,6 +540,13 @@ export class TiDBSessionStore {
     beginImportStaging(realSessionId, token) {
         return new TiDBStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
     }
+    /** #292:「这个 id 是 placed ⇒ 该写路径不适用」的共用拒绝(session-sync 的两条换装腿共用)。 */
+    async assertNotPlaced(sessionId, what) {
+        const placed = await this.placementOf(sessionId);
+        if (placed !== undefined) {
+            throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placed.kind} placement partition — a session-sync ${what} cannot overwrite a delegation transcript`);
+        }
+    }
     /**
      * 2c session-sync P1d-β (staged-row inspection) — read the rows STAGED under `stagingId` (NO session_meta probe — a
      * staging id has no meta row by construction, so {@link exportEntries} would return null), oldest-first. The Phase-B
@@ -569,7 +700,15 @@ class TiDBStagingHandle {
             // commit/append to the dst). The staged ids ARE the source (already dense 0..N-1 under the staging id).
             const [stagedRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const [dstRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
-            const [dstMeta] = await conn.query("SELECT 1 FROM session_meta WHERE session_id = ?", [this.realSessionId]);
+            // `placement_kind` 捎带在既有的存在性探针上(#292:placed 目的地拒绝整段换装,理由与
+            // `replaceEntries` 的同款注逐字同——两条腿是同一件事的两种写法)。这里**刻意不加 `FOR UPDATE`**:
+            // 它对**缺席行**在 PG 上什么都锁不到(窗关不上),在 MySQL 上又会 gap-lock 住整段键区间(把一次
+            // 本可以合法先到的 placement 创建堵成锁等待)——两边都不划算。真门在提交前的那次权威复读(见下)。
+            const [dstMeta] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ?", [this.realSessionId]);
+            if (dstMeta[0]?.placement_kind != null) {
+                await conn.rollback();
+                throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${String(dstMeta[0].placement_kind)} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
+            }
             const srcIds = stagedRows.map((r) => String(r.entry_id));
             const dstIds = dstMeta[0] ? dstRows.map((r) => String(r.entry_id)) : null; // no dst meta ⇒ fresh (no dst log to relate to)
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
@@ -612,6 +751,17 @@ class TiDBStagingHandle {
             const now = new Date();
             await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES (?,?,?,?,?,?) " +
                 "ON DUPLICATE KEY UPDATE owner = VALUES(owner), updated_at = VALUES(updated_at), leaf_id = VALUES(leaf_id), leaf_seq = VALUES(leaf_seq)", [this.realSessionId, owner, now, now, leafId, srcIds.length]);
+            // 🔴 #292(codex 对抗复审 R1-[high],验真后修)—— **提交前的最后一道门**:上面那次 upsert 之后,
+            // 这一行**一定**被本事务锁住(不管它是我们刚插的、还是并发方先插我们随后 UPDATE 的),于是这次
+            // 复读是**权威**的。病:目标行在(1)的探针时**还不存在** ⇒ 探针无行可锁(PG 的 FOR UPDATE 对
+            // 缺席行不锁任何东西),另一事务可以在此期间把同 id 铸成 placed 转录;没有这道复读,本事务会把
+            // 它的事件整段换掉、并把 owner/leaf 改写成 push 方的 —— agent 行还指着那条会话,里面已经是别人
+            // 的历史。命中即整事务回滚(事件的 DELETE/rename 一并撤销),响亮 `placement_refused`。
+            const [afterMeta] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ?", [this.realSessionId]);
+            if (afterMeta[0]?.placement_kind != null) {
+                await conn.rollback();
+                throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${String(afterMeta[0].placement_kind)} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
+            }
             await conn.commit();
             return { relation: rel.relation };
         }

package/dist/plugins/write-behind-counter.d.ts

@@ -60,7 +60,8 @@ export declare class SqlWriteBehindCounter {
     private readonly dialect;
     private readonly pool;
     private readonly t;
-    private readonly windowMs;
+    /** 🔴 不再 `readonly`(#322):`costQuotaWindowSec` 热更新经 {@link setWindowMs} 换代,语义见那里。 */
+    private windowMs;
     private readonly now;
     private readonly onDegraded?;
     private readonly queryTimeoutMs;
@@ -70,7 +71,9 @@ export declare class SqlWriteBehindCounter {
     private flushing;
     private flushStartedAt;
     private failStreak;
-    constructor(dialect: CounterDialect, pool: MySqlPool | PgPool, t: CounterTable, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook | undefined, // S9: observability tap — never affects counting
+    constructor(dialect: CounterDialect, pool: MySqlPool | PgPool, t: CounterTable, 
+    /** 🔴 不再 `readonly`(#322):`costQuotaWindowSec` 热更新经 {@link setWindowMs} 换代,语义见那里。 */
+    windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook | undefined, // S9: observability tap — never affects counting
     queryTimeoutMs?: number);
     /** The ONLY place the two drivers' query shapes diverge. Returns {rows, affected}. */
     private exec;
@@ -103,6 +106,18 @@ export declare class SqlWriteBehindCounter {
     reap(): Promise<number>;
     startRefresh(intervalMs?: number): this;
     stop(): void;
+    /** #322:刷新环是否在跑(关断哨兵的判据:off 态必须**零 SQL**,含这条后台环)。 */
+    refreshRunning(): boolean;
+    /**
+     * #322 批1:窗长换代(`costQuotaWindowSec` 热更新)。
+     *
+     * 🔴 如实语义:窗长是**桶键的一部分**(`floor(now/windowMs)`),不是行里的一个可改字段。换窗长 ⇒ 当代
+     * 桶重算 ⇒ 本副本对「当前窗已用多少」的读数从新桶起算(旧桶的行还在库里,按它自己的窗长归属)。
+     * 未 flush 的本地增量仍带着**它自己的**桶键(rowKey 里已含),所以它们仍落回原来那个桶,不会被搬家。
+     * 这与限额值的换代不同(那个是纯比较参数,窗内计数一个不动),因此单独成注:运营改窗长要知道自己在
+     * 换的是**记账周期**,不是一个阈值。
+     */
+    setWindowMs(windowMs: number): void;
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class WriteBehindCounter extends SqlWriteBehindCounter {

package/dist/plugins/write-behind-counter.js

@@ -20,7 +20,9 @@ export class SqlWriteBehindCounter {
     flushing = false;
     flushStartedAt = 0; // S9 review MED-1: hang-watchdog anchor // reentrancy guard: a flush slower than the timer interval must not overlap
     failStreak = new Map(); // S9: consecutive-failure runs, per kind
-    constructor(dialect, pool, t, windowMs, now = () => Date.now(), onDegraded, // S9: observability tap — never affects counting
+    constructor(dialect, pool, t, 
+    /** 🔴 不再 `readonly`(#322):`costQuotaWindowSec` 热更新经 {@link setWindowMs} 换代,语义见那里。 */
+    windowMs, now = () => Date.now(), onDegraded, // S9: observability tap — never affects counting
     // S9 deeper fix: per-query inactivity timeout. mysql2's is the client-side `{sql, timeout}` form (the
     // connection is held until the hung command really ends, so a poisoned connection is never reused
     // mid-query); node-pg's is `query_timeout` on the QueryConfig. Overridable via DB_QUERY_TIMEOUT_MS
@@ -203,6 +205,22 @@ export class SqlWriteBehindCounter {
             clearInterval(this.timer);
         this.timer = undefined;
     }
+    /** #322:刷新环是否在跑(关断哨兵的判据:off 态必须**零 SQL**,含这条后台环)。 */
+    refreshRunning() {
+        return this.timer !== undefined;
+    }
+    /**
+     * #322 批1:窗长换代(`costQuotaWindowSec` 热更新)。
+     *
+     * 🔴 如实语义:窗长是**桶键的一部分**(`floor(now/windowMs)`),不是行里的一个可改字段。换窗长 ⇒ 当代
+     * 桶重算 ⇒ 本副本对「当前窗已用多少」的读数从新桶起算(旧桶的行还在库里,按它自己的窗长归属)。
+     * 未 flush 的本地增量仍带着**它自己的**桶键(rowKey 里已含),所以它们仍落回原来那个桶,不会被搬家。
+     * 这与限额值的换代不同(那个是纯比较参数,窗内计数一个不动),因此单独成注:运营改窗长要知道自己在
+     * 换的是**记账周期**,不是一个阈值。
+     */
+    setWindowMs(windowMs) {
+        this.windowMs = windowMs;
+    }
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class WriteBehindCounter extends SqlWriteBehindCounter {

package/dist/runs.d.ts

@@ -277,6 +277,8 @@ approval?: {
     windowMarginMs: number;
 }): Promise<void>;
 /** How often a running instance refreshes its run's updated_at (liveness, independent of events).
- *  Must stay strictly below `runStaleSec` (asserted at startup) or the reaper would race live runs. */
+ *  Must stay strictly below `runStaleSec` (asserted at startup AND on every hot config candidate) or the
+ *  reaper would race live runs. #322:数值的单源是 `config-invariants.ts`(那条不变量的属主),两个消费面
+ *  ——心跳环与 run-stale 判据——因此不可能各读各的。 */
 export declare const HEARTBEAT_MS = 30000;
 //# sourceMappingURL=runs.d.ts.map

package/dist/runs.js

@@ -10,6 +10,7 @@ import { fleetRunResiduals, isFleetAgentTerminalNotification } from "./fleet/fle
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
 import { recordFailOpen } from "./observability/fail-open.js"; // #310:通告 durable 写失败的留痕口
+import { LIVENESS_HEARTBEAT_MS } from "./config-invariants.js"; // #322:心跳周期的单源 = 它服务的那条不变量
 /**
  * stoppedBy (core 1.252): a service cancel is a USER stop — mark the run's still-running background
  * children BEFORE core's teardown reaps them (bare abort = attribution falls back to "system"; core's own
@@ -1012,6 +1013,8 @@ approval) {
     }
 }
 /** How often a running instance refreshes its run's updated_at (liveness, independent of events).
- *  Must stay strictly below `runStaleSec` (asserted at startup) or the reaper would race live runs. */
-export const HEARTBEAT_MS = 30_000;
+ *  Must stay strictly below `runStaleSec` (asserted at startup AND on every hot config candidate) or the
+ *  reaper would race live runs. #322:数值的单源是 `config-invariants.ts`(那条不变量的属主),两个消费面
+ *  ——心跳环与 run-stale 判据——因此不可能各读各的。 */
+export const HEARTBEAT_MS = LIVENESS_HEARTBEAT_MS;
 //# sourceMappingURL=runs.js.map

package/dist/trace/engine-notice-wire.d.ts

@@ -4,7 +4,7 @@
  * 三码同族:都是「这条 session 的记忆姿态」的披露,resume 之后仍然相关 ⇒ 也进 durable 账本
  * (cli 断连补看走既有 events 重放腿,[4634](ii))。
  */
-export declare const ENGINE_NOTICE_WIRE_CODES: readonly ["memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived"];
+export declare const ENGINE_NOTICE_WIRE_CODES: readonly ["memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed"];
 export type EngineNoticeWireCode = (typeof ENGINE_NOTICE_WIRE_CODES)[number];
 /** 白名单谓词(单点):路由与门都读这一个,不许第二处手抄码串。 */
 export declare function isEngineNoticeWireCode(code: string): code is EngineNoticeWireCode;

package/dist/trace/engine-notice-wire.js

@@ -18,12 +18,17 @@
  * **不投**(fail-closed 方向 = 宁缺席不串台;猜一个"当前活跃会话"就是串台的定义)。日志终点仍逐字
  * 保留 ⇒ 运维观察面零回退,事实一条不丢。
  *
- * ## 白名单的演化机制(设计稿 ④)
- * 本表是**过渡形**。core [4631] 已认领 `NOTICE_AUDIENCE` **码级注册表**(code → "user"|"operator",
- * 闭集映射,随 5.46 / 最迟 5.47)+ `EngineNotice.sessionId` 顶层可选。到货后本表**退役为消费该表**,
- * 不在本仓自造第二份「哪类码该上 wire」的判定语义。
- * 🔴 在此之前的固定动作:**每一次 core 提货批**,LEDGER 对表 core `EngineNotice` 码册的新增码,
- * 三选一登记(入册 / 明拒 + 理由 / 申裁),登记在 `docs/CORE-CONSUMPTION-LEDGER.md` 的该批行里。
+ * ## 白名单的演化机制(设计稿 ④)—— **注册表已到货(core 5.47/5.48)**
+ * core [4631] 认领的 `NOTICE_AUDIENCE` **码级注册表**(code → "user"|"operator";缺席读 `"operator"`,
+ * 保守默认)已随 5.47/5.48 到货,`EngineNotice.sessionId` 顶层键亦然。#292 提货批的处置是
+ * **消费它当上界,而不是当场把本表整只退役**:
+ *  · 本表是**投递可行性**的判定(有没有 sessionId 归属键、core 侧的去重单位是不是 sink),
+ *    `NOTICE_AUDIENCE` 是**受众**的判定(这条码是给谁看的)——两者是合取,不是同一件事;
+ *  · 于是机器门(`test/engine-notice-wire.test.ts` ⑥)现在**双向**咬:白名单里出现一个 core 判
+ *    `"operator"` 的码 ⇒ 红(本仓不许自造第二份受众语义);core 判 `"user"` 的码没入册也没明拒 ⇒ 红。
+ *  · 真正的整表退役条件 = 上游把「归属键在不在」也纳入注册表(那时本表退化成一次查表),届时删。
+ * 🔴 固定动作不变:**每一次 core 提货批**对表 core `EngineNotice` 码册的新增码,三选一登记
+ * (入册 / 明拒 + 理由 / 申裁),并在 `docs/core-consumption/LEDGER.json` 的该批行里留痕。
  * 漏对表的后果不是报错而是**静默缺席**:新码永远不上 wire,消费端(cli)无从知道该码存在。
  */
 import { redactSecrets } from "./redact.js";
@@ -44,6 +49,19 @@ export const ENGINE_NOTICE_WIRE_CODES = [
     /** design/324 #324①:`memoryDelegationEvidence:"attested-only"` 下,一次静态面本会打的污染标记被豁免。
      *  core 去重单位 = **prepared leg**。`detail: { reason, subagentType?, sessionId? }` */
     "memory.delegation_static_mark_waived",
+    /** design/336 §4/§6.3(core 5.47/5.48 到货,#292 提货批对表入册):**instruction-hold 生命周期**三码。
+     *  同族三条都是「这条 session 的记忆此刻处在什么姿态」的披露,与既有三码同一条判据:
+     *   · core `NOTICE_AUDIENCE` 明列 **"user"**(到货的码级注册表,见本文件顶注的演化机制);
+     *   · 铸点在 `memoryHoldNotices(report, sessionId)`,`detail.sessionId` 随 harvest 报告一起给 ⇒ 投得出去;
+     *   · core 去重单位 = **harvest**(检查点收与终局收是两件事),不是 sink ⇒ 上 per-session 流不翻面。
+     *  `detail: { count, paths, sessionId? }`(paths 已 neutralize + 截 20 条)。 */
+    "memory.hold_opened",
+    /** 同族:被扣住的 instruction 条目在写者会话干净结算(或宿主阀门放行)后重走全套门并提交。
+     *  `detail: { count, paths, sessionId? }` */
+    "memory.hold_released",
+    /** 同族:被扣住的条目移交控制面隔离区。`detail: { count, disposed: [{ path, terminal }], sessionId? }`
+     *  —— 🔴 `terminal:"expired"` 是**超时不是定罪**(core 铸文逐字如此),消费端不得渲染成裁决语气。 */
+    "memory.hold_disposed",
 ];
 const WIRE_CODES = new Set(ENGINE_NOTICE_WIRE_CODES);
 /** 白名单谓词(单点):路由与门都读这一个,不许第二处手抄码串。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.37.0",
+  "version": "7.38.0-rc.2",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,8 +54,8 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.46.0",
-    "@sema-agent/registry-core": "^0.18.0",
+    "@sema-agent/core": "^5.50.0",
+    "@sema-agent/registry-core": "^0.19.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",