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

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

@@ -23,6 +23,7 @@ import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntrie
 import { escapeLike } from "./sql-escape.js";
 import { pgSafeJsonStringify } from "./pg-safe-json.js";
 import { toIso } from "./sql-row-helpers.js";
+import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, // 两孪生店同源(理由见 kernel 处顶注)
  } from "../session-sync-kernel.js";
@@ -52,9 +53,22 @@ export const PG_SESSION_SCHEMA = [
      -- Write-once auto-title (setTitleIfNull / probeTitle): NULL = "untitled", i.e. still claimable; the
      -- three-state probe distinguishes it from "no such session". PG twin of the TiDB COLUMN_MIGRATIONS leg.
      title       VARCHAR(120) COLLATE "C",
+     -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组(TiDB 孪生同名同宽,
+     -- 语义与六条义务见 src/plugins/session-placement.ts 顶注):创建时一次落行、first-write 不可变;
+     -- placement_kind 在场 ⇒ 住在 placement 分区(不上宿主枚举 / claim 形 acquire 恒拒 / release=真删除 /
+     -- 留存视界腿不碰);(placement_scope, placement_handle) = 与 background_agent 行的 join 键;
+     -- placed_at = 分区 GC 的年龄锚。
+     placement_kind              VARCHAR(32)  COLLATE "C",
+     placement_scope             VARCHAR(190) COLLATE "C",
+     placement_parent_session_id VARCHAR(190) COLLATE "C",
+     placement_root_session_id   VARCHAR(190) COLLATE "C",
+     placement_handle            VARCHAR(190) COLLATE "C",
+     placed_at                   TIMESTAMPTZ(3),
      PRIMARY KEY (session_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_session_meta_owner ON session_meta (owner)`,
+    // listPlaced 的检索腿(TiDB 孪生的 KEY idx_session_meta_placement 同形)。
+    `CREATE INDEX IF NOT EXISTS idx_session_meta_placement ON session_meta (placement_kind, placement_scope, placed_at)`,
     `CREATE TABLE IF NOT EXISTS session_event (
      session_id  VARCHAR(64) COLLATE "C" NOT NULL,
      seq         BIGINT      NOT NULL,
@@ -110,14 +124,18 @@ export class PgSessionStorage extends BaseSessionStorage {
     }
     /** @see TiDBSessionStorage.wake — F3 bounded `[floor..leaf]` rebuild; null if the session does not exist. */
     static async wake(pool, sessionId) {
-        const metaRes = await pool.query("SELECT created_at, leaf_id, leaf_seq FROM session_meta WHERE session_id = $1", [sessionId]);
+        const metaRes = await pool.query(
+        // #292 C18(TiDB 孪生同形):placement 六列捎带在既有 meta SELECT 上,acquire 热路径零额外往返。
+        `SELECT created_at, leaf_id, leaf_seq, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
         const meta = metaRes.rows[0];
         if (!meta)
             return null;
         const { floorEntryId, floorSeq } = await PgSessionStorage.computeFloor(pool, sessionId);
         const eventRes = await pool.query("SELECT payload FROM session_event WHERE session_id = $1 AND seq >= $2 ORDER BY seq ASC", [sessionId, floorSeq]);
         const entries = eventRes.rows.map((r) => parseEntry(r.payload));
-        const metadata = { id: sessionId, createdAt: toIso(meta.created_at) };
+        // #292 C18:持久化元组骑 core 5.48 的 `SessionMetadata.placement`(TiDB 孪生逐字同义)。
+        const placement = placementFromRow(meta);
+        const metadata = { id: sessionId, createdAt: toIso(meta.created_at), ...(placement !== undefined ? { placement } : {}) };
         return new PgSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, floorEntryId, floorSeq);
     }
     /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). @see TiDBSessionStorage.computeFloor */
@@ -210,6 +228,9 @@ export class PgSessionStore {
     pool;
     /** #270 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
     retention = MANAGED_RETENTION;
+    /** #292 C18(core 5.48.0 design/323):placement 声明(TiDB 孪生同格,义务逐条见
+     *  `src/plugins/session-placement.ts` 顶注)。 */
+    placements = SQL_SESSION_PLACEMENTS;
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     pending = new Map();
     constructor(pool) {
@@ -218,38 +239,75 @@ export class PgSessionStore {
     async acquire(sessionId, opts) {
         if (!sessionId) {
             const id = uuidv7();
-            await this.register(id, null);
-            return this.load(id);
+            await this.register(id, null, opts?.placement); // #292:元组与行同一条 INSERT(TiDB 孪生同义)
+            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. (Twin of TiDBSessionStore.acquire.)
         if (opts?.requireExisting)
-            return this.load(sessionId, true);
+            return this.load(sessionId, true, opts);
+        // #292:准入按调用方逐一判(共享 promise 不许让 claim 形继承可信创建方的准入;TiDB 孪生同义)。
         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 PgSessionStorage.wake(this.pool, sessionId);
+        if (storage) {
+            assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts); // #292 claim 关门
+            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. core's prepare-task maps this `not_found` to `resume.session_not_found`.
+        if (requireExisting)
+            throw new SessionError("not_found", `session ${sessionId} not found`);
+        await this.register(sessionId, null, opts?.placement);
+        storage = await PgSessionStorage.wake(this.pool, sessionId);
+        // 刚 register 完却唤不醒 = 并发 purge 抢在两步之间(TiDB 孪生同款注:旧形的 `storage!` 断言会炸成
+        // 一条无信息的 TypeError)。
         if (!storage) {
-            // design/114 Phase3: `requireExisting` ⇒ FAIL LOUD on a genuinely missing session (no session_meta row),
-            // never the silent create-on-miss. core's prepare-task maps this `not_found` to `resume.session_not_found`.
-            if (requireExisting)
-                throw new SessionError("not_found", `session ${sessionId} not found`);
-            await this.register(sessionId, null);
-            storage = await PgSessionStorage.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):回读缺失/异组 ⇒ 响亮拒(TiDB 孪生同义)。
+        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;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
+    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 ($1,$2,$3,$4,NULL,0) ON CONFLICT (session_id) DO NOTHING", [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 ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, ...placementInsertValues(placement, now)]);
+    }
+    /** #292 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
+    async placementOf(sessionId) {
+        const res = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
+        return placementFromRow(res.rows[0]);
+    }
+    /** #292 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
+     *  见 {@link TiDBSessionStore.listPlaced})。 */
+    async listPlaced(kind, opts) {
+        const params = [kind];
+        const ph = (v) => {
+            params.push(v);
+            return `$${params.length}`;
+        };
+        let sql = `SELECT session_id, updated_at, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE placement_kind = $1`;
+        if (opts?.scope !== undefined)
+            sql += ` AND placement_scope = ${ph(opts.scope)}`;
+        if (opts?.olderThanMs !== undefined)
+            sql += ` AND COALESCE(updated_at, placed_at) < ${ph(new Date(Date.now() - opts.olderThanMs))}`;
+        sql += ` ORDER BY COALESCE(updated_at, placed_at) ASC LIMIT ${ph(LIST_PLACED_BATCH)}`;
+        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));
     }
     /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     async ownerOf(sessionId) {
@@ -277,9 +335,51 @@ export class PgSessionStore {
             return undefined;
         return { owner: r.rows[0].owner ?? null, leafId: r.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 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
+     *  {@link TiDBSessionStore.release},本腿是它的 PG 孪生)。 */
     async release(sessionId) {
         this.pending.delete(sessionId);
+        const placed = await this.placementOf(sessionId);
+        if (placed === undefined)
+            return; // 普通会话:语义逐字节不变(义务 3)
+        await this.deletePlacedSession(sessionId);
+    }
+    /** @see TiDBSessionStore.forget — 丢引用不动 durable 史(preflight 纪律的落点;PG 孪生)。 */
+    forget(sessionId) {
+        this.pending.delete(sessionId);
+    }
+    /** @see TiDBSessionStore.deletePlacedSession — PG 孪生(条件删门 + meta 先删 + 失败上浮同义)。 */
+    async deletePlacedSession(sessionId) {
+        const conn = await this.pool.connect();
+        try {
+            await conn.query("BEGIN");
+            const metaRes = await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND placement_kind IS NOT NULL", [sessionId]);
+            if ((metaRes.rowCount ?? 0) > 0)
+                await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
+            await conn.query("COMMIT");
+        }
+        catch (err) {
+            try {
+                await conn.query("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();
+        }
+    }
+    /** #292:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
+    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`);
+        }
     }
     // ───────────────────────── SessionRepo seam (§0.5) — PG twin of TiDBSessionStore ─────────────────────────
     // Behaviourally identical to {@link TiDBSessionStore.listSessions/fork/deleteSession}; only the SQL dialect
@@ -291,7 +391,8 @@ export class PgSessionStore {
             params.push(v);
             return `$${params.length}`;
         };
-        const where = [];
+        // 🔴 #292 义务 2:placed 会话不上宿主枚举面(TiDB 孪生逐字同义,理由见那里)。
+        const where = ["sm.placement_kind IS NULL"];
         // [4198] 窄互认第二臂的第三条件(TiDB 孪生逐字同义):`includeUnowned` ⇒「本人的 ∪ 无主的」。
         if (opts.owner)
             where.push(opts.includeUnowned ? `(sm.owner = ${ph(opts.owner)} OR sm.owner IS NULL)` : `sm.owner = ${ph(opts.owner)}`);
@@ -454,13 +555,21 @@ export class PgSessionStore {
      *  defense-in-depth), then re-insert via the SHARED body (entries + session_meta LAST as the commit point), ALL in
      *  ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry) — unlike importEntries' fresh-only INSERT. */
     async replaceEntries(sessionId, owner, entries) {
+        await this.assertNotPlaced(sessionId, "replace"); // 快路(事务外,零工拒);真门在事务内(TiDB 孪生同款注)
         const validated = validateEntriesForImport(entries); // fail-closed gate BEFORE any write (mirrors importEntries)
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
+            // #292(codex R1-[high] 同族窗):事务内锁读 + DELETE 的 `placement_kind IS NULL` 硬条件
+            // (TiDB 孪生逐字同义 —— placed 行 owner 恒 NULL,而 replace(owner=null) 的属主门恰好匹配它)。
+            const placedRes = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
+            if (placedRes.rows[0]?.placement_kind != null) {
+                await conn.query("ROLLBACK");
+                throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placedRes.rows[0].placement_kind} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
+            }
             // Purge first (idempotent: a missing session deletes 0 rows). Events, then the owner-guarded meta delete.
             await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
-            await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2", [sessionId, owner]);
+            await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 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.query("COMMIT");
@@ -605,7 +714,12 @@ class PgStagingHandle {
             await conn.query("BEGIN");
             const staged = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const dst = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
-            const dstMeta = await conn.query("SELECT 1 FROM session_meta WHERE session_id = $1", [this.realSessionId]);
+            // `placement_kind` 捎带在存在性探针上(#292:placed 目的地拒整段换装;TiDB 孪生同形)。
+            const dstMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
+            if (dstMeta.rows[0]?.placement_kind != null) {
+                await conn.query("ROLLBACK");
+                throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${dstMeta.rows[0].placement_kind} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
+            }
             const srcIds = staged.rows.map((r) => String(r.entry_id));
             const dstIds = dstMeta.rows.length > 0 ? dst.rows.map((r) => String(r.entry_id)) : null;
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
@@ -636,6 +750,14 @@ class PgStagingHandle {
             const now = new Date();
             await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES ($1,$2,$3,$4,$5,$6) " +
                 "ON CONFLICT (session_id) DO UPDATE SET owner = EXCLUDED.owner, updated_at = EXCLUDED.updated_at, leaf_id = EXCLUDED.leaf_id, leaf_seq = EXCLUDED.leaf_seq", [this.realSessionId, owner, now, now, leafId, srcIds.length]);
+            // 🔴 #292(codex R1-[high]):**提交前的最后一道门** —— upsert 之后这一行必被本事务锁住,故这次
+            // 复读是权威的;它关的是「探针时行还不存在、并发方随后把同 id 铸成 placed」那半个窗(PG 的
+            // FOR UPDATE 对缺席行不锁任何东西)。理由与失败经济学逐字见 TiDB 孪生同处的注。
+            const afterMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
+            if (afterMeta.rows[0]?.placement_kind != null) {
+                await conn.query("ROLLBACK");
+                throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${afterMeta.rows[0].placement_kind} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
+            }
             await conn.query("COMMIT");
             return { relation: rel.relation };
         }

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

@@ -491,11 +491,20 @@ export class SqlRetentionStore {
      * (`originatingSessionId` 住在 run blob 里 ⇒ JSON 提取是真方言分叉)。fork 子代**结构上没有边**,
      * 理由见 {@link SqlRetentionStore.deleteExpiredSessions} 的头注。
      */
+    /* 🔴 #292 C18 追加的**第五条腿**(placed 分区,core 5.48 design/323 义务 4 的 server 侧兑现):
+     *  一只 `placement_kind` 在场的会话是某条委派的**转录**,它的删除权**独家**属于联合 reap
+     *  (`reapDurableAgents`:先按 rev 条件删 agent 行、赢了才 `release` 终结转录;以及行已不在时的分区
+     *  收割腿)。让视界腿也去删它会造出两个删除权威,而它们的交叠恰好是这条义务要关死的那个状态:
+     *  行还在、指着一份已经不存在的转录(core 的 `delegation.transcript_integrity` 通告说的就是它)。
+     *  ⇒ 把「placed」当成一条**活引用**:候选谓词排除它,`countProtectedSessions` 同时把它记成 skipped
+     *  (两侧共用本函数 ⇒ 不可能分家)。它不会因此永生:分区收割腿按 `backgroundAgentRetentionMs` 的
+     *  年龄 + 「行确实不在」联合判定后真删。 */
     liveReferenceExists() {
         const workflow = this.db.dialect === "tidb"
             ? `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND JSON_UNQUOTE(JSON_EXTRACT(wr.run, '$.originatingSessionId')) = sm.session_id)`
             : `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND wr.run::json->>'originatingSessionId' = sm.session_id)`;
-        return (`(EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = sm.session_id)` +
+        return (`(sm.placement_kind IS NOT NULL` + // #292:placed 转录的删除权独家归联合 reap(见本函数上方的第五条腿注)
+            ` OR EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = sm.session_id)` +
             ` OR EXISTS (SELECT 1 FROM checkpoint c2 WHERE c2.session_id = sm.session_id AND c2.status = 'pending')` +
             ` OR EXISTS (SELECT 1 FROM background_agent ba WHERE ba.status IN ('running','parked')` +
             `   AND (ba.session_id = sm.session_id OR ba.parent_session_id = sm.session_id OR ba.root_session_id = sm.session_id))` +

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

@@ -0,0 +1,113 @@
+/**
+ * #292 C18(core 5.48.0 design/323「不造新店」提货批,黑板 [4743] 点名义务)——**subagent 转录持久化**
+ * 的 placement 语义,SQL 孪生共用的一份判据。
+ *
+ * ## 这是什么
+ *
+ * core 5.48.0 给 `SessionStore` 开了一组**全 optional** 的 placement 面:一只**声明** `placements`
+ * (「本店懂 placement 语义,且落在 subagent 分区里的会话是这个耐久度」)+ `acquire(id,{placement})`
+ * 的创建形 + `listPlaced` / `placementOf` 两只读面。声明即承诺**六条义务**(core `SessionStore.placements`
+ * 顶注逐字):
+ *
+ *  1. placed 会话享受所声明的耐久度(重启后 `acquire(id,{requireExisting:true})` 仍到得了);
+ *  2. placed 会话**不上宿主枚举面**(壳的 /resume 列表不许把子代转录当成可续聊会话);
+ *  3. **未** placed 的会话,acquire 语义逐字节不变;
+ *  4. `release(placedId)` 是**真删除**(durable 史一并),联合 reap 的「行与会话同亡」靠它;
+ *  5. placement **first-write 不可变**:re-open(`requireExisting`,带不带 placement 参数)返回同一
+ *     会话且**永不重写**元组;
+ *  6. placed id **不可被 claim**:后来的 claim 形 acquire(无 `requireExisting`、无创建 placement)
+ *     撞上已存在的 placed id ⇒ 响亮拒 `SessionError("placement_refused")`,绝不附着。
+ *
+ * ## 为什么判据住在这里而不是各写一份
+ *
+ * 本仓成文教训(`memory-origin-law.ts` 顶注同族、`key-resolver.ts` 顶注「链只有一条」):两支方言各
+ * 抄一份准入判据,迟早在某一支上少一个分支——而少掉的那一支**没有任何报错面**,表现只是「这台机器上
+ * 一个陌生人可以把自己接到别人子代的转录上」。所以准入判据(两个方向)、列名、行→元组的映射都在
+ * 这一处;两支后端只负责在自己的 I/O 点上调用它。
+ *
+ * ## 判据的两个方向(缺一不可,core `TtlSessionStore.assertPlacementAdmission` 的镜像)
+ *
+ * ① **claim 关门**:已 placed 的行拒绝 claim 形 acquire;
+ * ② **镜像方向(pre-claim squat 竞态)**:子会话 id 在 spawn 帧上**先于**子代 prepare 公布,于是一次
+ *    并发的 claim 形 acquire 可能抢先建出**普通**会话,而后带 placement 的可信调用方拿到的就是一只
+ *    宿主可枚举、release 不真删的普通会话 ——「声明了 full tier 却在静默说谎」。⇒ 在**声明了分区**的
+ *    店上,带 placement 的 acquire 必须回读到**已持久化**且同一元组身份的行,回读缺失/异组=响亮拒。
+ */
+import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord } from "@sema-agent/core";
+/**
+ * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`)。
+ *
+ * 🔴 声明制,不是鸭子类型:core 的铸造门判「row store ∧ session 店声明」,不声明的店**不收** placed
+ * 语义(合法降级:placement 参数被忽略,会话就是普通会话)。所以这一格只有在上面六条义务**全部**在
+ * 本店实装之后才允许存在——它是一句关于本店行为的承诺,不是一个功能开关。
+ * `durable` 的依据:两支孪生的会话史落在 `session_meta`+`session_event` 两张真表上,进程重启后
+ * `acquire(id,{requireExisting:true})` 从事件日志重放(义务 1 的机器证在
+ * `test/session-placement-db-integration.test.ts` 的跨进程复活格)。
+ */
+export declare const SQL_SESSION_PLACEMENTS: {
+    readonly subagent: {
+        readonly durability: "durable";
+    };
+};
+/**
+ * `session_meta` 上承载 placement 元组的六列,**两方言同名**(单点定义:列名手抄两份必漂,而漂掉的
+ * 那一支只会表现为「这台机器上 placed 行读不出来」——静默,不报错)。
+ * `placed_at` 是 GC 的年龄锚(core `PlacedSessionRow.placedAt`);其余五列是元组本身。
+ */
+export declare const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
+/** 一行 `session_meta` 的 placement 列(两方言的驱动都把列名原样带回,故一份形)。 */
+export interface PlacementColumns {
+    placement_kind?: unknown;
+    placement_scope?: unknown;
+    placement_parent_session_id?: unknown;
+    placement_root_session_id?: unknown;
+    placement_handle?: unknown;
+    placed_at?: unknown;
+}
+/**
+ * 行 → 持久化的 placement 元组(`undefined` = 这是一只普通会话)。
+ *
+ * 🔴 判别位是 `placement_kind`:它在场即 placed。`placed_at` 缺失(带外 SQL 写进半只元组)时回落
+ * `0` 而**不是**把整只元组读成缺席——把「元组半缺」读成「没有 placement」等于让义务 2/4/6 在那一行上
+ * 集体失效(宿主枚举会重新列出它、release 退回租约语义);`listPlaced` 那一侧另有 `tupleIncomplete`
+ * 的诚实变体负责让 GC 对它 fail-closed。
+ */
+export declare function placementFromRow(row: PlacementColumns | undefined): SessionPlacementRecord | undefined;
+/**
+ * 行 → 一条 {@link PlacedSessionRow}(`listPlaced` 的行形)。
+ *
+ * core 契约:join 键是**完整**的 `(scope, handle)`;缺任何一半 ⇒ 返回 `tupleIncomplete` 的诚实变体,
+ * 消费方对它 fail-closed(永不按年龄收割)。一个「无行」与「另一个租户有行」分不清的 join 不许删东西。
+ */
+export declare function placedRowFromRow(sessionId: string, row: PlacementColumns, lastActivityMs?: number): PlacedSessionRow;
+/** 创建时一次落行的六个绑定值(顺序 = {@link PLACEMENT_SELECT_COLUMNS});无 placement ⇒ 六个 NULL。 */
+export declare function placementInsertValues(placement: SessionPlacement | undefined, placedAt: Date): [string | null, string | null, string | null, string | null, string | null, Date | null];
+/** `acquire` 的 opts 面(core `SessionStore.acquire` 的第二参,窄成本模块要判的两键)。 */
+export interface PlacementAcquireOpts {
+    requireExisting?: boolean;
+    placement?: SessionPlacement;
+}
+/**
+ * 准入判据 —— **两个方向**(顶注 ①②;core `TtlSessionStore.assertPlacementAdmission` 的 SQL 镜像,
+ * 逐条同义,文案自铸)。
+ *
+ * @param persisted 该 id 在库里**已持久化**的元组(缺席 = 普通会话 / 无此行)。
+ *
+ * · 方向①(claim 关门):`persisted` 在场 + 非 `requireExisting` + 调用方没带创建 placement ⇒ 拒。
+ *   `requireExisting`(读/复活形,义务 5)与「创建调用及其幂等重取」(带 placement 的可信内部链)
+ *   是仅有的两个合法形。placement 不可变意味着带 placement 的参数**永远重写不了**任何东西——持久化
+ *   的那一份恒赢,所以放行它不开任何后门。
+ * · 方向②(镜像/squat):带 placement 的创建形回读到**缺席**或**异组**元组 ⇒ 拒。缺席 = 并发的
+ *   claim 形抢先建出了普通会话(或带外写把元组抹了);异组 = 同 id 上坐着另一条委派链的转录。
+ *   两者都不许让「声明了 durable 分区」这句话在静默中变成谎。
+ */
+export declare function assertPlacementAdmission(sessionId: string, persisted: SessionPlacementRecord | undefined, opts?: PlacementAcquireOpts): void;
+/**
+ * 一次 `listPlaced` 最多带回的行数。
+ *
+ * core 契约不设上界,但两支孪生面对的是一张可以很大的真表:无界 SELECT 会让一次 reap tick 把整个
+ * placed 分区拉进内存。行按**年龄升序**(最老先出)⇒ 截断的语义是「本 tick 先收最老的一批,下一 tick
+ * 接着收」,而不是「有些行永远看不见」。判据消费方(core 的分区收割腿)本就是每 tick 重新枚举的。
+ */
+export declare const LIST_PLACED_BATCH = 1000;
+//# sourceMappingURL=session-placement.d.ts.map

package/dist/plugins/session-placement.js

@@ -0,0 +1,153 @@
+/**
+ * #292 C18(core 5.48.0 design/323「不造新店」提货批,黑板 [4743] 点名义务)——**subagent 转录持久化**
+ * 的 placement 语义,SQL 孪生共用的一份判据。
+ *
+ * ## 这是什么
+ *
+ * core 5.48.0 给 `SessionStore` 开了一组**全 optional** 的 placement 面:一只**声明** `placements`
+ * (「本店懂 placement 语义,且落在 subagent 分区里的会话是这个耐久度」)+ `acquire(id,{placement})`
+ * 的创建形 + `listPlaced` / `placementOf` 两只读面。声明即承诺**六条义务**(core `SessionStore.placements`
+ * 顶注逐字):
+ *
+ *  1. placed 会话享受所声明的耐久度(重启后 `acquire(id,{requireExisting:true})` 仍到得了);
+ *  2. placed 会话**不上宿主枚举面**(壳的 /resume 列表不许把子代转录当成可续聊会话);
+ *  3. **未** placed 的会话,acquire 语义逐字节不变;
+ *  4. `release(placedId)` 是**真删除**(durable 史一并),联合 reap 的「行与会话同亡」靠它;
+ *  5. placement **first-write 不可变**:re-open(`requireExisting`,带不带 placement 参数)返回同一
+ *     会话且**永不重写**元组;
+ *  6. placed id **不可被 claim**:后来的 claim 形 acquire(无 `requireExisting`、无创建 placement)
+ *     撞上已存在的 placed id ⇒ 响亮拒 `SessionError("placement_refused")`,绝不附着。
+ *
+ * ## 为什么判据住在这里而不是各写一份
+ *
+ * 本仓成文教训(`memory-origin-law.ts` 顶注同族、`key-resolver.ts` 顶注「链只有一条」):两支方言各
+ * 抄一份准入判据,迟早在某一支上少一个分支——而少掉的那一支**没有任何报错面**,表现只是「这台机器上
+ * 一个陌生人可以把自己接到别人子代的转录上」。所以准入判据(两个方向)、列名、行→元组的映射都在
+ * 这一处;两支后端只负责在自己的 I/O 点上调用它。
+ *
+ * ## 判据的两个方向(缺一不可,core `TtlSessionStore.assertPlacementAdmission` 的镜像)
+ *
+ * ① **claim 关门**:已 placed 的行拒绝 claim 形 acquire;
+ * ② **镜像方向(pre-claim squat 竞态)**:子会话 id 在 spawn 帧上**先于**子代 prepare 公布,于是一次
+ *    并发的 claim 形 acquire 可能抢先建出**普通**会话,而后带 placement 的可信调用方拿到的就是一只
+ *    宿主可枚举、release 不真删的普通会话 ——「声明了 full tier 却在静默说谎」。⇒ 在**声明了分区**的
+ *    店上,带 placement 的 acquire 必须回读到**已持久化**且同一元组身份的行,回读缺失/异组=响亮拒。
+ */
+import { SessionError } from "@sema-agent/core";
+/**
+ * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`)。
+ *
+ * 🔴 声明制,不是鸭子类型:core 的铸造门判「row store ∧ session 店声明」,不声明的店**不收** placed
+ * 语义(合法降级:placement 参数被忽略,会话就是普通会话)。所以这一格只有在上面六条义务**全部**在
+ * 本店实装之后才允许存在——它是一句关于本店行为的承诺,不是一个功能开关。
+ * `durable` 的依据:两支孪生的会话史落在 `session_meta`+`session_event` 两张真表上,进程重启后
+ * `acquire(id,{requireExisting:true})` 从事件日志重放(义务 1 的机器证在
+ * `test/session-placement-db-integration.test.ts` 的跨进程复活格)。
+ */
+export const SQL_SESSION_PLACEMENTS = { subagent: { durability: "durable" } };
+/**
+ * `session_meta` 上承载 placement 元组的六列,**两方言同名**(单点定义:列名手抄两份必漂,而漂掉的
+ * 那一支只会表现为「这台机器上 placed 行读不出来」——静默,不报错)。
+ * `placed_at` 是 GC 的年龄锚(core `PlacedSessionRow.placedAt`);其余五列是元组本身。
+ */
+export const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
+/** DATETIME/TIMESTAMPTZ 单元格 → epoch ms。两支池都返回 `Date`(mysql2 `timezone:"Z"` / node-pg 原生),
+ *  字符串臂是防御性回落(驱动配置若变,宁可解析一次也不要静默把 placedAt 读成 NaN)。 */
+function toEpochMs(v) {
+    if (v == null)
+        return undefined;
+    if (v instanceof Date)
+        return v.getTime();
+    const ms = new Date(String(v)).getTime();
+    return Number.isFinite(ms) ? ms : undefined;
+}
+const asStringOrUndefined = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
+/**
+ * 行 → 持久化的 placement 元组(`undefined` = 这是一只普通会话)。
+ *
+ * 🔴 判别位是 `placement_kind`:它在场即 placed。`placed_at` 缺失(带外 SQL 写进半只元组)时回落
+ * `0` 而**不是**把整只元组读成缺席——把「元组半缺」读成「没有 placement」等于让义务 2/4/6 在那一行上
+ * 集体失效(宿主枚举会重新列出它、release 退回租约语义);`listPlaced` 那一侧另有 `tupleIncomplete`
+ * 的诚实变体负责让 GC 对它 fail-closed。
+ */
+export function placementFromRow(row) {
+    if (row === undefined)
+        return undefined;
+    const kind = asStringOrUndefined(row.placement_kind);
+    if (kind === undefined)
+        return undefined;
+    return {
+        kind: kind,
+        ...(asStringOrUndefined(row.placement_scope) !== undefined ? { scope: asStringOrUndefined(row.placement_scope) } : {}),
+        ...(asStringOrUndefined(row.placement_parent_session_id) !== undefined ? { parentSessionId: asStringOrUndefined(row.placement_parent_session_id) } : {}),
+        ...(asStringOrUndefined(row.placement_root_session_id) !== undefined ? { rootSessionId: asStringOrUndefined(row.placement_root_session_id) } : {}),
+        ...(asStringOrUndefined(row.placement_handle) !== undefined ? { handle: asStringOrUndefined(row.placement_handle) } : {}),
+        placedAt: toEpochMs(row.placed_at) ?? 0,
+    };
+}
+/**
+ * 行 → 一条 {@link PlacedSessionRow}(`listPlaced` 的行形)。
+ *
+ * core 契约:join 键是**完整**的 `(scope, handle)`;缺任何一半 ⇒ 返回 `tupleIncomplete` 的诚实变体,
+ * 消费方对它 fail-closed(永不按年龄收割)。一个「无行」与「另一个租户有行」分不清的 join 不许删东西。
+ */
+export function placedRowFromRow(sessionId, row, lastActivityMs) {
+    const placedAt = toEpochMs(row.placed_at) ?? lastActivityMs ?? 0;
+    const scope = asStringOrUndefined(row.placement_scope);
+    const handle = asStringOrUndefined(row.placement_handle);
+    return scope !== undefined && handle !== undefined
+        ? { sessionId, placedAt, scope, handle }
+        : { sessionId, placedAt, tupleIncomplete: true };
+}
+/** 创建时一次落行的六个绑定值(顺序 = {@link PLACEMENT_SELECT_COLUMNS});无 placement ⇒ 六个 NULL。 */
+export function placementInsertValues(placement, placedAt) {
+    if (placement === undefined)
+        return [null, null, null, null, null, null];
+    return [
+        placement.kind,
+        placement.scope ?? null,
+        placement.parentSessionId ?? null,
+        placement.rootSessionId ?? null,
+        placement.handle ?? null,
+        placedAt,
+    ];
+}
+/**
+ * 准入判据 —— **两个方向**(顶注 ①②;core `TtlSessionStore.assertPlacementAdmission` 的 SQL 镜像,
+ * 逐条同义,文案自铸)。
+ *
+ * @param persisted 该 id 在库里**已持久化**的元组(缺席 = 普通会话 / 无此行)。
+ *
+ * · 方向①(claim 关门):`persisted` 在场 + 非 `requireExisting` + 调用方没带创建 placement ⇒ 拒。
+ *   `requireExisting`(读/复活形,义务 5)与「创建调用及其幂等重取」(带 placement 的可信内部链)
+ *   是仅有的两个合法形。placement 不可变意味着带 placement 的参数**永远重写不了**任何东西——持久化
+ *   的那一份恒赢,所以放行它不开任何后门。
+ * · 方向②(镜像/squat):带 placement 的创建形回读到**缺席**或**异组**元组 ⇒ 拒。缺席 = 并发的
+ *   claim 形抢先建出了普通会话(或带外写把元组抹了);异组 = 同 id 上坐着另一条委派链的转录。
+ *   两者都不许让「声明了 durable 分区」这句话在静默中变成谎。
+ */
+export function assertPlacementAdmission(sessionId, persisted, opts) {
+    if (opts?.requireExisting === true)
+        return; // 读/复活形:义务 5 的合法入口,两方向都不判
+    if (persisted !== undefined && opts?.placement === undefined) {
+        throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${persisted.kind} placement partition — a claim-form acquire cannot attach to it (read it with requireExisting, or address the agent through its a* handle)`);
+    }
+    if (opts?.placement === undefined)
+        return;
+    const want = opts.placement;
+    if (persisted === undefined) {
+        throw new SessionError("placement_refused", `session ${sessionId} exists OUTSIDE the ${want.kind} placement partition it was declared into — refusing to run a subagent transcript on it (a concurrent claim-form create won this id, or the tuple was written away out of band)`);
+    }
+    if (persisted.kind !== want.kind || persisted.scope !== want.scope || persisted.handle !== want.handle) {
+        throw new SessionError("placement_refused", `session ${sessionId}'s persisted placement does not match the declared one (persisted ${persisted.kind}/${persisted.scope ?? "-"}/${persisted.handle ?? "-"} vs declared ${want.kind}/${want.scope ?? "-"}/${want.handle ?? "-"}) — refusing a cross-tuple attach`);
+    }
+}
+/**
+ * 一次 `listPlaced` 最多带回的行数。
+ *
+ * core 契约不设上界,但两支孪生面对的是一张可以很大的真表:无界 SELECT 会让一次 reap tick 把整个
+ * placed 分区拉进内存。行按**年龄升序**(最老先出)⇒ 截断的语义是「本 tick 先收最老的一批,下一 tick
+ * 接着收」,而不是「有些行永远看不见」。判据消费方(core 的分区收割腿)本就是每 tick 重新枚举的。
+ */
+export const LIST_PLACED_BATCH = 1000;
+//# sourceMappingURL=session-placement.js.map

package/dist/plugins/session-store.js

@@ -57,7 +57,13 @@ export async function ensureSessionDurable(hostStore, sessionId) {
             throw new Error(`session "${sessionId}" exists in the durable store but is empty (no leaf entry) — likely a claim-create shell row, not real durable content`);
     }
     finally {
-        await hostStore.release(acquired.sessionId);
+        // 🔴 #292 C18(core 5.48.0 [4743] 点名义务①,**preflight/探活法**):这是一次「只为验存在」的
+        // acquire ⇒ 收尾必须是 `forget`(丢暖引用),**绝不能**是 `release`。core 5.48 起
+        // `release(placedId)` 被重定义为**真删除**,而本函数正是 park 前的探活腿:一条跨重启 parked 的
+        // 子代转录在这里被 release 一次就等于**删掉转录 + 烧掉那次审批**(core 发车前重扫的 P1 同款撞点,
+        // 四域复现)。缺 `forget` 面 ⇒ 什么都不做(core B-17 判例:绝不代之以 release);两支 SQL 孪生与
+        // 包装店都实装了 forget,所以生产路径上这一步是真的丢引用,不是 no-op。
+        await hostStore.forget?.(acquired.sessionId);
     }
 }
 /**

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

@@ -5,12 +5,17 @@
  * `maxCostUsd` gate). `scope_key` is opaque (principal today; team/feature later — design/30 N3).
  */
 import type { Pool } from "mysql2/promise";
-import type { QuotaDecision, QuotaTracker } from "../observability/cost-quota.js";
+import type { QuotaDecision, QuotaLimits, QuotaTracker } from "../observability/cost-quota.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class TiDBCostQuota implements QuotaTracker {
-    private readonly limitMicroUsd;
     private readonly counter;
+    /** #322:限额=比较参数(行里只有花费);窗长换代经 counter.setWindowMs(桶键语义见那里)。 */
+    private limitMicroUsd;
+    private refreshRequested;
+    private refreshIntervalMs;
     constructor(pool: Pool, limitMicroUsd: number, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
+    setLimits(next: QuotaLimits): void;
+    private syncRefresh;
     check(scopeKey: string): QuotaDecision;
     add(scopeKey: string, micro: number): void;
     flush(): Promise<void>;