@sema-agent/server 7.147.0 → 7.148.0

package/dist/plugins/org-delivery-quota-store.js

@@ -1,3 +1,4 @@
+import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { atomicWriteFile, ensureDir } from "@sema-agent/core";
@@ -97,7 +98,7 @@ export class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
         }
         if (!parsed.ok) {
             this.unusable = `the cross-principal delivery quota file ${this.path} cannot be read (${parsed.problem}) — every delivery is refused until an operator moves it away (moving it resets the current window's counts)`;
-            (opts?.warn ?? ((event, fields) => console.warn(event, fields)))("org_delivery_quota_corrupt_read", { path: this.path, problem: parsed.problem });
+            (opts?.warn ?? createLogger().warn)("org_delivery_quota_corrupt_read", { path: this.path, problem: parsed.problem });
             return;
         }
         this.state = parsed.state;

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

@@ -15,7 +15,7 @@ export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordSt
     private readonly log;
     /** 本面的损坏闸([ref] 起由重放属主交回;置位后每个方法第一行响亮拒)。 */
     private readonly gate;
-    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回 `console.warn`)。 */
+    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回日志出口接缝的文本出口 `writeLogText`)。 */
     constructor(dir: string, warn?: Logger["warn"]);
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
     get corrupt(): boolean;
@@ -55,7 +55,7 @@ export declare class FileRuleImportTicketStore {
     private readonly gate;
     /** 单调钟(判定用)。与 {@link now}(墙钟,记账用)是两只不同的钟,别混。 */
     private readonly monotonic;
-    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回 `console.warn`)。 */
+    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回日志出口接缝的文本出口 `writeLogText`)。 */
     constructor(dir: string, now?: () => number, warn?: Logger["warn"], monotonic?: () => number);
     private readonly now;
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
@@ -128,7 +128,7 @@ export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
  * `onError` 接的是 core 规则文件的**披露面**(读不出来 / 校验和不符 / 撞上符号链接时它答零规则并
  * 说出来)。接住它打一条 warn 是**必须**的:那条路径上「零规则」与「真的没有规则」在读面上同形,
  * 不留痕就变成一次静默的 fail-closed(用户会突然被反复询问,却没有任何线索)。
- * `warn`([ref])接的是本仓审批记录 / 导入票两份日志的**腐读座**(逐行披露 + 计数;缺席 ⇒ `console.warn`)。
+ * `warn`([ref])接的是本仓审批记录 / 导入票两份日志的**腐读座**(逐行披露 + 计数;缺席 ⇒ 接缝的文本出口 `writeLogText`)。
  */
 export declare function createFilePermissionRuleStores(root: string, opts?: {
     onError?: (message: string) => void;

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type PermissionRuleWriter, type DurableRulePartition, type DurableRulePartitionProvider, type RuleScope, type RuleSyncFrontier, type RuleBehavior, type RuleCandidate, type RuleApprovalRecord, type StaleRuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
+import { type PermissionRuleWriter, type DurableRulePartition, type DurableRulePartitionProvider, type RuleScope, type RuleSyncFrontier, type RuleCandidate, type RuleApprovalRecord, type StaleRuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
 import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
@@ -59,7 +59,7 @@ export declare const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
  * 列宽依据([ref] A10 的「每列的值由谁铸、有没有入口上限」口径):
  *  · `owner_key` / `record_id` / `ticket_id` / `approval_id` / `payload_hash` / `checksum` → 190:
  *    全是本仓自铸的键类值(sha256 hex 64 / uuid 36 / `sha256:` 前缀 71),190 是全仓键轴的统一宽度。
- *  · `principal` → 512:principal 入口上限是 `PRINCIPAL_MAX_LENGTH = 190`(`security.ts`),这里给
+ *  · `principal` → 512:principal 入口上限是 `PRINCIPAL_MAX_BYTES = 190` UTF-8 字节(`principal-shape.ts`),这里给
  *    名类宽度 512 是**上界宽于入口**的方向(绝不制造静默截断面)。
  *  · `actor` → 190:本 backend 自铸的副本身份(`sql-<12 hex>`),按构造 ≤ 20 字符。
  *  · 内容列一律 LONGTEXT / TEXT:一只桶的规则集没有硬上限(导入一份大 settings 就能过 64K TEXT 墙)。
@@ -185,7 +185,7 @@ export declare function recordOwnerOf(record: {
     readonly principal?: unknown;
 }): RuleOwner | undefined;
 /**
- * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)要读的桶:**规则表里的每一只桶**(按 `owner_key` 分页,与 M11 同一只走法)。
+ * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)要读的桶:**规则表里的每一只桶**(按 `owner_key` 分页)。
  * 不从审批记录推:收编腿把规则桶整桶改键到新身份、而审批史按 D2 留在旧身份名下(`src/adoption/plan.ts` 的 `permission_rule#owner_key` 腿与
  * `permission-rule-approval-history` 一员)—— 从记录推出的属主集在收编之后漏掉新桶。属主读法只有引擎的 `readRuleOwner`(与本店读口同一只);
  * 读不出属主的行不点名任何可解析的桶(读腿同样解析不到它),不返回。`db` 是池或迁移握锁的那一条连接。
@@ -205,7 +205,7 @@ export declare function isSqlBucketVanished(e: unknown): boolean;
  *  · {@link BucketRefusedError} —— 判官四道(文法戳 / 指纹 / 行的 behavior / 引擎校验器)的拒;
  *  · {@link StoreCorruptError} —— 某只 JSON 列的体读不出(`not-json` / `malformed`),读腿在 {@link refusingUnreadableColumns} 把判官抛的列错误折成的店拒绝契约。
  * 两类都是这一行的确定性判决:原样再读也读不出,读腿对它同样整桶拒(零规则),所以它什么都不放行。
- * 别的抛出物**不是**这一类:连接 / 超时 / 权限(一次读失败证明不了以后也读不出);以及仍以 {@link SqlJsonColumnError} 穿出读腿的唯一一形 `not-text`
+ * 别的抛出物**不是**这一类:连接 / 超时 / 权限(一次读失败证明不了以后也读不出);以及仍以 `SqlJsonColumnError` 穿出读腿的唯一一形 `not-text`
  * (列没按文本投影:读腿与解码点漂了,是码缺陷不是坏数据 —— 按列错误类判它会把一次码漂读成「这只桶坏了」)。
  */
 export declare function isSqlBucketRefusal(e: unknown): boolean;
@@ -473,65 +473,6 @@ export declare const RULE_PENDING_APPROVAL_RETENTION_MS: number;
  * 补建完成之前(或某个副本还没起过新版),这条腿在存量库上仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
  */
 export declare const RULE_REAP_BATCH = 500;
-/**
- * M11 删掉的一行。只带桶键、态、工具名与 scope 的 root —— 规则正文不出本函数(命令行里可以有任何东西)。
- *
- * `kind` 是闭集(启动日志按它穷尽分句,`one-time-migrations.ts` `logOneTimeMigrations`):
- *  · `rule` —— 仍有活 add 的规则行(引擎读侧每跑一次丢它并告知;它从未生效,要的话按项目的完整路径重写);
- *  · `revoked-rule` —— 没有活 add 的规则行(判活用 core 的 `applyTombstones`:每个 add 都已被同桶墓碑撤掉,或这一行本来就没有 add):它在任何一侧都已不生效
- *    (allow / deny / ask 同判),无需处置;逐行 warn 的句子只说这个事实,不依赖桶里有没有墓碑、也不依赖态;
- *  · `tombstone` —— 一条撤销记录。它只盖得住同 (behavior, 文本, scope) 的规则 ⇒ 那些规则的 scope 与它同样不被收,随它一起删了或本来就不在,
- *    删它不会让任何被撤销的东西回来。
- */
-export interface UndurableScopeRuleRow {
-    /** 桶键(sha256,不是 principal 原文)。 */
-    readonly ownerKey: string;
-    readonly kind: "rule" | "revoked-rule" | "tombstone";
-    readonly behavior: RuleBehavior;
-    readonly tool: string;
-    /** scope 的 root,**过 `redactSecrets`**(本仓唯一脱敏器):坏 root 是最不可信的自由文本,可能夹着凭据形,而本读数进启动日志与拒因。 */
-    readonly scopeRoot: string;
-}
-/** M11 判成读不出、一个字节没动的桶。`why` = 唯一判官那次整桶拒**不带任何行内容**的拒因(读腿对这只桶照旧整桶拒,它仍是这只桶的属主)。 */
-export interface UnreadableRuleBucket {
-    /** 桶键(sha256,不是 principal 原文)。 */
-    readonly ownerKey: string;
-    readonly why: string;
-}
-/**
- * M11 写进的读数账 —— 三格与一次性迁移段那一只收据账(`one-time-migrations.ts` 的 `MigrationReceipts`)上的同名三格**同名同形**,迁移段把它的账直接递进来
- * ([ref]:一次起服一只收据账,M11 不另起第二套):删掉的行在那只桶的回写**提交的那一刻**追加,之后任何一步失败,拒因随账带走它们。
- */
-export interface UndurableScopePurgeReadings {
-    /** 删掉的行(一行一条读数;每只桶的回写提交之后才追加)。 */
-    readonly undurableScopeRuleRows: UndurableScopeRuleRow[];
-    /** 连续争不过在线写者(OCC 每次都输)而留到下一次起服的桶数。那些桶里的坏行这期间照旧由引擎读侧丢掉并告知。 */
-    undurableScopeRuleBucketsDeferred: number;
-    /** 读腿整桶拒的桶(形 / 指纹 / behavior 闭集 / 墓碑规范文本 / 单一验证器):一个字节不动,逐桶交出拒因,等人处置。 */
-    readonly undurableScopeRuleBucketsUnreadable: UnreadableRuleBucket[];
-}
-/** {@link purgeUndurableScopeRows} 要的最小查询口(一次性迁移段的 `MigrationDb` 同形;占位符按方言由本函数写)。 */
-export interface UndurableScopePurgeDb {
-    rows(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
-    exec(sql: string, params?: readonly unknown[]): Promise<number>;
-}
-/**
- * **M11** —— 把持久桶里 scope 不被 core `isValidDurableScope` 收的行(规则行与墓碑)删掉,一行一条读数。
- *
- * 这些行从哪来:7.119.0 及更早的本仓入口按「root 非空」收 project scope(`/v1/rules` 写口、两条导入面),引擎 7.45 也收;
- * 引擎 7.46.0 把 project root 收窄成完整绝对路径 ⇒ `project:myproj` 一类存量行在读侧被丢(`permission.rule_row_dropped`,每跑一条),
- * 而撤销口删不动它(引擎的写臂对这种 scope 的墓碑同样拒)。⇒ 一次性迁移,不留「撤销口对坏 scope 另开一条读法」的长期双读。
- *
- * 读法与写法都是**店的那一只**:每只桶先过唯一判官 {@link decodeBucketRow}(读腿用的同一只),判官整桶拒 ⇒ 这只桶**一个字节不动**,
- * 进 `undurableScopeRuleBucketsUnreadable`(桶键 + 不带行内容的拒因;读腿对它的整桶拒仍是它的属主,出路是人);判官放行 ⇒ 在那份合法状态上筛 scope,
- * 经写臂的同一只 {@link writeBucket} 整桶 OCC 回写(`WHERE owner_key = ? AND rev = ?`,rev+1,落盘字节与指纹同写臂)—— 不碰别的桶。
- * **硬删、不铸墓碑**:墓碑的作用是挡同步回灌,而引擎的 sync-join 对 scope 不合法的入站行本来就丢(`applySyncJoin`),
- * 本店也不实现同步(见 `apply` 的 sync-join 臂)。
- * 幂等:第二跑零命中零写(读不出的桶每一跑照报,直到有人处置)。
- * 读数写进调用方递进来的账(`into`,{@link UndurableScopePurgeReadings}):删掉的行在那只桶的回写提交之后追加 ⇒ 本函数半途抛出时,已删的行已经在账上;
- * 错误**原样**上抛(不加工、不自铸拒因句 —— 收据由迁移段那一只收据账随拒因带走,[ref])。
- */
-export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: SqlDialect, into: UndurableScopePurgeReadings, now?: () => number): Promise<void>;
 /** 三个 SQL 面的一次性装配束(one driver, three faces)。`durable` = [ref] 的 durable 分区后端;
  *  引擎接缝上的统一店由 `main.ts` 用 `createPermissionRuleStoreProvider({ durable })` 合成一次。 */
 export interface PermissionRuleStores {

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

@@ -1,13 +1,12 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, isValidDurableScope, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, principalNameOf, readRuleOffer2, } from "@sema-agent/core";
+import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, principalNameOf, readRuleOffer2, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ensureIndexes } from "./ensure-index.js";
-import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, SqlJsonColumnError, StoreCorruptError } from "./sql-json-column.js";
-import { redactSecrets } from "../trace/redact.js";
+import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, StoreCorruptError } from "./sql-json-column.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -63,11 +62,9 @@ function readBucketRowBehavior(raw, what, ownerKey) {
     return behavior;
 }
 class BucketRefusedError extends Error {
-    verdict;
     code;
     constructor(verdict, evidence, code) {
         super(`${verdict} ${evidence}`);
-        this.verdict = verdict;
         if (code !== undefined)
             this.code = code;
     }
@@ -593,13 +590,14 @@ export class SqlDurableRulePartitionProvider {
 export function recordOwnerOf(record) {
     return readRuleOwner(record.owner ?? { kind: "principal", principal: record.principal });
 }
+const RULE_BUCKET_SCAN_PAGE = 200;
 export async function listRuleBucketOwners(db) {
     const owners = [];
     let after = "";
     for (;;) {
         const { rows } = await db.query(db.dialect === "mysql"
-            ? `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`
-            : `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`, [after]);
+            ? `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${RULE_BUCKET_SCAN_PAGE}`
+            : `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${RULE_BUCKET_SCAN_PAGE}`, [after]);
         for (const row of rows) {
             after = String(row["owner_key"]);
             const principal = row["principal"] === null || row["principal"] === undefined ? undefined : String(row["principal"]);
@@ -607,7 +605,7 @@ export async function listRuleBucketOwners(db) {
             if (owner !== undefined)
                 owners.push(owner);
         }
-        if (rows.length < UNDURABLE_PURGE_PAGE)
+        if (rows.length < RULE_BUCKET_SCAN_PAGE)
             return owners;
     }
 }
@@ -861,84 +859,6 @@ export class SqlRuleImportTicketStore {
 }
 export const RULE_PENDING_APPROVAL_RETENTION_MS = 24 * 60 * 60_000;
 export const RULE_REAP_BATCH = 500;
-const UNDURABLE_PURGE_PAGE = 200;
-const UNDURABLE_PURGE_OCC_ATTEMPTS = 5;
-export async function purgeUndurableScopeRows(db, dialect, into, now = Date.now) {
-    const cols = `owner_key, ${bucketRowColumns(dialect)}`;
-    let after = "";
-    for (;;) {
-        const page = await db.rows(dialect === "mysql"
-            ? `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`
-            : `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`, [after]);
-        for (const first of page) {
-            const ownerKey = String(first.owner_key);
-            after = ownerKey;
-            let row = first;
-            let settled = false;
-            for (let attempt = 0; attempt < UNDURABLE_PURGE_OCC_ATTEMPTS && row !== undefined && !settled; attempt++) {
-                const outcome = await purgeOneBucket(db, dialect, ownerKey, row, now);
-                switch (outcome.kind) {
-                    case "purged":
-                        into.undurableScopeRuleRows.push(...outcome.rows);
-                        settled = true;
-                        break;
-                    case "unreadable":
-                        into.undurableScopeRuleBucketsUnreadable.push({ ownerKey, why: outcome.why });
-                        settled = true;
-                        break;
-                    case "clean":
-                        settled = true;
-                        break;
-                    case "conflict":
-                        row = (await db.rows(dialect === "mysql" ? `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?` : `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`, [ownerKey]))[0];
-                        if (row === undefined)
-                            settled = true;
-                        break;
-                    default: {
-                        const unknown = outcome;
-                        throw new Error(`M11: unhandled bucket outcome ${JSON.stringify(unknown)}`);
-                    }
-                }
-            }
-            if (!settled)
-                into.undurableScopeRuleBucketsDeferred += 1;
-        }
-        if (page.length < UNDURABLE_PURGE_PAGE)
-            break;
-    }
-}
-async function purgeOneBucket(db, dialect, ownerKey, row, now) {
-    let cur;
-    try {
-        cur = decodeBucketRow(ownerKey, row);
-    }
-    catch (e) {
-        return { kind: "unreadable", why: contentFreeRefusal(ownerKey, e) };
-    }
-    const badRules = cur.rules.filter((r) => !isValidDurableScope(r.scope));
-    const badTombstones = cur.tombstones.filter((t) => !isValidDurableScope(t.scope));
-    if (badRules.length === 0 && badTombstones.length === 0)
-        return { kind: "clean" };
-    const rootOf = (scope) => redactSecrets(scope.kind === "project" ? scope.root : scope.kind);
-    const rows = [
-        ...badRules.map((r) => ({ ownerKey, kind: applyTombstones([r], cur.tombstones).length > 0 ? "rule" : "revoked-rule", behavior: r.behavior, tool: r.tool, scopeRoot: rootOf(r.scope) })),
-        ...badTombstones.map((t) => {
-            const parsed = parseRuleText(t.rule, t.behavior);
-            if ("reject" in parsed)
-                throw new Error(`permission_rule bucket ${ownerKey}: a tombstone the bucket judge admitted does not parse here — refusing to touch the bucket`);
-            return { ownerKey, kind: "tombstone", behavior: t.behavior, tool: parsed.rule.tool, scopeRoot: rootOf(t.scope) };
-        }),
-    ];
-    const landed = await writeBucket((sql, params) => db.exec(sql, params), dialect, ownerKey, cur, { rules: cur.rules.filter((r) => !badRules.includes(r)), tombstones: cur.tombstones.filter((t) => !badTombstones.includes(t)) }, now());
-    return landed ? { kind: "purged", rows } : { kind: "conflict" };
-}
-function contentFreeRefusal(ownerKey, e) {
-    if (e instanceof BucketRefusedError)
-        return e.verdict;
-    if (e instanceof SqlJsonColumnError)
-        return `${e.where}: ${e.problem}`;
-    return `permission_rule bucket ${ownerKey}: the bucket judge threw ${e instanceof Error ? e.name : typeof e} (its text is withheld here: it may quote the row)`;
-}
 export function createSqlPermissionRuleStores(db, now) {
     const q = (mysql, pg) => (db.dialect === "mysql" ? mysql : pg);
     return {

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

@@ -1,33 +1,3 @@
-/**
- * PostgreSQL pool + central schema — the PG sibling of tidb-pool.ts, for the second run-store backend
- * (clay 2026-06-21). Schema ownership is CENTRAL (one ensurePgSchema, like tidb-pool's SCHEMA_STATEMENTS) — PG
- * stores assume the tables exist and NEVER create their own (a per-store `CREATE TABLE IF NOT EXISTS` is
- * first-writer-wins, so a trimmed table would shadow the full one and drop columns).
- *
- * Dialect deltas vs the MySQL DDL in tidb-pool.ts: JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), TINYINT(1)→SMALLINT,
- * inline `KEY …`→separate `CREATE INDEX`. checkpoint timestamps stay epoch-ms BIGINT (core's Checkpoint uses ms),
- * matching the TiDB schema byte-for-byte semantically. Only the tables PG backends implement so far are listed
- * (run-store + checkpoint); the remaining tidb-* tables are added as their PG stores land (tracked).
- *
- * ─────────────────────────────── SCHEMA POLICY (clay 裁 2026-07-26) ───────────────────────────────
- * THIS CODE IS THE SINGLE SOURCE OF TRUTH for the PG schema, and there is NO in-place migration seam in this statement array: a database that
- * lags behind the code is refused at boot with the exact `ALTER TABLE … ADD COLUMN …` statements printed, and the
- * deployer runs them themselves: the column-set check and its refusal never alter a database. The only DDL this
- * process runs by itself on a table that already exists is idempotent index creation (`ensureIndex`: indexes only,
- * never a column) and the registered one-time migrations (each has a window and a registry row in
- * `one-time-migrations.ts`) — adding / changing / renaming a column or dropping a table is done by those migrations
- * and by nothing else.
- *
- * Consequence, and it is a hard rule: **do NOT add new `ALTER TABLE` seams here.** Every column / default /
- * constraint change is folded into its own `CREATE TABLE`, and this array stays pure `CREATE TABLE` +
- * `CREATE INDEX`. The historical additive-ALTER seams were folded in on 2026-07-26 (they had all decayed
- * into permanent no-ops — the CREATEs already carried the columns).
- *
- * Because the seams are gone, the semantics they used to document now live as inline `--` comments ON THE
- * COLUMN inside the CREATE, not as TypeScript comments outside the template literal: the full-set SQL
- * baseline `docs/schema/baseline-pg.sql` is GENERATED from these statement strings, so only what is inside
- * the SQL survives the export. The baseline is a derived artifact — regenerate it, never hand-edit it.
- */
 import pg from "pg";
 import type { ServiceConfig } from "../config-types.js";
 export declare const PG_SCHEMA_STATEMENTS: readonly string[];
@@ -70,7 +40,7 @@ export type PgPoolWarnSink = (msg: string, meta?: Record<string, unknown>) => vo
  *     不留痕则只能靠间接症状发现;
  *   · 不动 shutdown.ts 的 uncaughtException 钩 —— exit 1 对**真**未捕获仍是正确姿势,旁路兜底
  *     会吞掉别人的崩溃([ref] 纪律:修源头,不下游兜)。
- *  `onIdleClientError` 缺省 console.warn(与本文件 `ensurePgSchema` 的既有告警姿势一致)——生产
+ *  `onIdleClientError` 缺省 = 日志出口接缝缺省 logger 的 `warn`(与装配后同一种 JSON 行)——生产
  *  装配(store-backend `createStoreBackend`)递结构化 logger 的 warn 座。 */
 export declare function createPgPool(opts: string | pg.PoolConfig, onIdleClientError?: PgPoolWarnSink): pg.Pool;
 /** A fixed bigint key for the `pg_advisory_lock` that serializes the whole `ensurePgSchema` DDL run (see below).

package/dist/plugins/pg-pool.js

@@ -1,9 +1,11 @@
+import { createLogger, writeLogText } from "../observability/logger.js";
 import pg from "pg";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
 import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { ensureSchema as ensureSessionSchema } from "../stores-sql/pg-session-storage.js";
 import { sessionExtDdl } from "./session-ext-table.js";
+import { CHECKPOINT_HOST_SESSION_COLUMN } from "./checkpoint-index-columns.js";
 import { ensureSchema as ensureToolResultSchema } from "../stores-sql/tool-result-store-sql.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
 import { ensureSchema as ensureRateLimitSchema } from "./pg-rate-limiter.js";
@@ -23,7 +25,7 @@ import { ensureIndexes } from "./ensure-index.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { INBOX_PAYLOAD_COLUMN } from "./inbox-payload-column.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
-import { PRINCIPAL_MAX_LENGTH } from "../security.js";
+import { PRINCIPAL_MAX_BYTES } from "../principal-shape.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -121,6 +123,8 @@ export const PG_SCHEMA_STATEMENTS = [
      -- JSON ⇒ 与同表 outcome 列同取 JSONB(协议信封无损,IS NULL 谓词两方言同义)。
      execution_outcome JSONB,
      execution_at_ms   BIGINT,
+     -- host_session_id:这张卡归在哪只会话上(MySQL 孪生同名同义;语义、写口与 M49 回填见 tidb-pool.ts 同名列的行内注)。
+     ${CHECKPOINT_HOST_SESSION_COLUMN.pg},
      PRIMARY KEY (token)
    )`,
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
@@ -150,22 +154,27 @@ export const PG_SCHEMA_STATEMENTS = [
      consumed_at_ms BIGINT         NOT NULL,
      expires_at_ms  BIGINT         NOT NULL,
      PRIMARY KEY (session_id, nonce)
+   )`,
+    `CREATE TABLE IF NOT EXISTS approval_nonce_floor (
+     singleton CHAR(1) COLLATE "C" NOT NULL DEFAULT 'x',
+     floor_ms  BIGINT  NOT NULL,
+     PRIMARY KEY (singleton)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_sender_quota (
-     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     from_scope      VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      attempts        INT          NOT NULL,
      PRIMARY KEY (from_scope)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_recipient_quota (
-     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     to_scope        VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      delivered       INT          NOT NULL,
      PRIMARY KEY (to_scope)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_pair_quota (
-     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
-     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     to_scope        VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+     from_scope      VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      delivered       INT          NOT NULL,
      PRIMARY KEY (to_scope, from_scope)
@@ -430,7 +439,7 @@ export function pgPoolClientErrorMeta(err) {
 }
 export function createPgPool(opts, onIdleClientError) {
     const pool = typeof opts === "string" ? new pg.Pool({ connectionString: opts }) : new pg.Pool(opts);
-    const warn = onIdleClientError ?? ((msg, meta) => console.warn(`[pg-pool] ${msg}`, meta));
+    const warn = onIdleClientError ?? createLogger().warn;
     const report = (msgName, state, err, count) => {
         const meta = pgPoolClientErrorMeta(err);
         try {
@@ -477,7 +486,7 @@ export async function releasePgEnsureSchemaLock(client, tag) {
         await client.query("SELECT pg_advisory_unlock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
     }
     catch (err) {
-        console.warn(`[${tag}] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (lock auto-frees on connection close):`, err);
+        writeLogText("stderr", `[${tag}] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (lock auto-frees on connection close):`, err);
     }
 }
 export async function ensurePgSchema(pool) {

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

@@ -20,7 +20,7 @@
  * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
  */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
@@ -159,18 +159,6 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     /** 收据句柄。还没连上(懒环境:续跑腿的引擎在 `resumeVM` **之前**先取它比车道)⇒ 未连接形 `{ sandboxId: "(unconnected)", provider, mountPath }`(与 k8s 车道同形),
      *  不抛 —— 抛了,续跑腿在恢复之前就失败。 */
     workspaceHandle(): WorkspaceHandle;
-    /**
-     * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
-     * ([ref] §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
-     * provisions the VM (like exec/fs); `undefined` if it can't connect → the LSP manager degrades.
-     */
-    getHost(port: number): Promise<string | undefined>;
-    /**
-     * Launch a long-running process as a TRUE E2B background command (resolves once launched, E2B keeps it alive)
-     * — for the LSP bridge ([ref] §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
-     * command's process group on completion, which would kill an in-shell `&`/nohup child. Fire-and-forget.
-     */
-    startBackground(command: string): Promise<void>;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -251,14 +239,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private stopKeepAlive;
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
-    exec(command: string, options?: ExecOpts): Promise<Result<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        detached?: {
-            shellId: string;
-        };
-    }, ExecutionError>>;
+    exec(command: string, options?: ExecOpts): Promise<Result<ExecResult, ExecutionError>>;
     /** 适配器自己的固定命令(文件面助手:readlink / realpath / rm / mktemp / 暂存写的提交)—— 与 {@link exec} 同一条路,起动形 `adapter`。 */
     private execInternal;
     private execAs;
@@ -355,10 +336,11 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      * confirmations: a refused `kill()` (logged; the exit is still awaited), a `wait()` that ends without an exit (the
      * connection deadline, a lost stream — the process may still run). With neither the count stays held and `suspendVM`
      * keeps refusing `command_in_flight` — the same arm as a start that never settles. No start promise (the op never ran)
-     * ⇒ released now. A failed start is released at once too, as in 7.129.0 — and that one is NOT a confirmation: there is
-     * no handle to kill or wait on, and a start whose reply was lost (the SDK's own 60 s handshake) may have spawned the
-     * process. Closing it means classifying the start failure (provider refused ⇒ not started; lost reply ⇒ held) — open,
-     * not done here.
+     * ⇒ released now. A start that FAILED is read by the same rule ({@link providerRefusedStart}): the provider answered a
+     * refusal of the request itself ⇒ no process was ever spawned — a confirmation, released; any other failure (the SDK's
+     * own handshake deadline, a dropped stream, an unreachable sandbox, anything else) has no answer in it — the provider may
+     * have spawned the process and the reply was lost ⇒ not a confirmation, held, and said once
+     * (`e2b_start_outcome_unknown`: the sandbox and the error's class, never the command).
      */
     private settleAbandonedStart;
     /**

package/dist/plugins/remote-env-e2b.js

@@ -140,19 +140,6 @@ export class RemoteContainerExecutionEnv {
     workspaceHandle() {
         return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cwd };
     }
-    async getHost(port) {
-        const conn = await this.ensureConnected();
-        return conn.ok ? conn.value.getHost(port) : undefined;
-    }
-    async startBackground(command) {
-        const conn = await this.ensureConnected();
-        if (!conn.ok)
-            return;
-        const s = this.startIn(engineStart(undefined), command, undefined);
-        if (!s.ok)
-            return void this.cfg.logger?.warn?.("remote_env_background_refused", { error: s.error.message });
-        await this.runIn(conn.value, s.value, { background: true });
-    }
     async connect(config) {
         if (config?.snapshotId) {
             return this.resumeVM(config.snapshotId, config.abortSignal ? { abortSignal: config.abortSignal } : undefined);
@@ -507,7 +494,7 @@ export class RemoteContainerExecutionEnv {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
                 timeoutMs: tee
-                    ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
+                    ? this.commandTimeoutMs(options?.timeout) + (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000
                     : this.commandTimeoutMs(options?.timeout),
                 onStdout: (d) => {
                     if (startCut)
@@ -554,12 +541,14 @@ export class RemoteContainerExecutionEnv {
         waitP.then(markResolved, markResolved);
         let fgSettled = false;
         let adoptedShellId;
+        let adoptedCause;
         let onDetach;
+        let onDetachSignal;
         const detachedP = detachSignal && tee
             ? new Promise((res) => {
-                onDetach = () => {
+                const adoptRunning = (cause) => {
                     if (detached || fgSettled || fgResolved || options?.abortSignal?.aborted)
-                        return;
+                        return false;
                     const adopted = this.bgManager.adoptSync((ctx) => {
                         waitP
                             .then((r) => ctx.onTerminal(false, r.exitCode))
@@ -572,22 +561,28 @@ export class RemoteContainerExecutionEnv {
                         return { handle, stdout: tee.stdout, stderr: tee.stderr };
                     });
                     if (!adopted)
-                        return;
+                        return false;
                     adoptedShellId = adopted.shellId;
+                    adoptedCause = cause;
                     detached = true;
                     res("detached");
+                    return true;
                 };
+                onDetach = adoptRunning;
+                const signalled = () => void adoptRunning();
+                onDetachSignal = signalled;
                 if (detachSignal.aborted)
-                    onDetach();
+                    signalled();
                 else
-                    detachSignal.addEventListener("abort", onDetach, { once: true });
+                    detachSignal.addEventListener("abort", signalled, { once: true });
             })
             : undefined;
+        const onWall = options?.autoBackgroundOnTimeout === true && detachedP !== undefined ? () => onDetach?.("timeout") === true : undefined;
         try {
             const fg = this.waitWithLiveness(handle, () => lastProgress, {
                 waitP,
                 disarmed: () => detached,
-                ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)) } } : {}),
+                ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)), ...(onWall !== undefined ? { onWall } : {}) } } : {}),
                 liveness: bounds.liveness,
                 captured,
             });
@@ -599,7 +594,7 @@ export class RemoteContainerExecutionEnv {
                     stdout: markTruncated(o.text, o.droppedBytes),
                     stderr: markTruncated(e.text, e.droppedBytes),
                     exitCode: 0,
-                    detached: { shellId: adoptedShellId },
+                    detached: { shellId: adoptedShellId, ...(adoptedCause !== undefined ? { cause: adoptedCause } : {}) },
                 });
             }
             if (options?.abortSignal?.aborted && !detached) {
@@ -618,8 +613,8 @@ export class RemoteContainerExecutionEnv {
         }
         finally {
             fgSettled = true;
-            if (onDetach && detachSignal)
-                detachSignal.removeEventListener("abort", onDetach);
+            if (onDetachSignal && detachSignal)
+                detachSignal.removeEventListener("abort", onDetachSignal);
             this.activeCommands--;
             options?.abortSignal?.removeEventListener("abort", onAbort);
         }
@@ -673,7 +668,7 @@ export class RemoteContainerExecutionEnv {
                 const bc = boundCut(first);
                 throw new RemoteExecutionError(bc.code, bc.message, e);
             }
-            throw this.remoteError(e, "connect_failed");
+            throw this.remoteError(e, providerTimedOut(e) ? "timeout" : "connect_failed");
         }
         handle
             .wait()
@@ -1083,7 +1078,15 @@ export class RemoteContainerExecutionEnv {
             late.kill().then(release, (e) => {
                 this.cfg.logger?.warn?.("e2b_abandoned_start_kill_failed", { sandboxId: this.sbx?.sandboxId, pid: late.pid, error: e instanceof Error ? e.name : typeof e });
             });
-        }, release);
+        }, (e) => {
+            if (providerRefusedStart(e))
+                return release();
+            this.cfg.logger?.warn?.("e2b_start_outcome_unknown", {
+                sandboxId: this.sbx?.sandboxId,
+                error: e instanceof Error ? e.name : typeof e,
+                effect: "the command start failed without the provider refusing it — the command may be running, so this sandbox is not suspended (command_in_flight) for the rest of its life",
+            });
+        });
     }
     commandTimeoutMs(timeoutSec) {
         return timeoutSec != null ? timeoutSec * 1000 : this.cfg.timeoutMs;
@@ -1115,6 +1118,8 @@ export class RemoteContainerExecutionEnv {
                 wallTimer = setTimeout(() => {
                     if (opts.disarmed?.())
                         return;
+                    if (wall.onWall?.() === true)
+                        return;
                     reject(createCutError({ code: "timeout", message: wallCutMessage(wall.totalMs) }, opts.captured()));
                     void handle.kill().catch(() => { });
                 }, wall.leftMs);
@@ -1232,6 +1237,10 @@ function boundCut(first) {
 function providerTimedOut(e) {
     return e?.name === "TimeoutError" || /timeout|timed out/i.test(errMsg(e));
 }
+const E2B_START_REFUSALS = new Set(["InvalidArgumentError", "AuthenticationError", "NotFoundError", "RateLimitError"]);
+function providerRefusedStart(e) {
+    return e instanceof Error && E2B_START_REFUSALS.has(e.name);
+}
 function anySignal(signals) {
     const ctor = AbortSignal;
     if (typeof ctor.any === "function")

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

@@ -1,4 +1,4 @@
-import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
+import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
@@ -264,14 +264,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     disposeBackgroundShells(opts?: {
         except?: readonly BackgroundShellId[];
     }): Promise<void>;
-    exec(command: string, options?: ExecOpts): Promise<Result<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        detached?: {
-            shellId: string;
-        };
-    }, ExecutionError>>;
+    exec(command: string, options?: ExecOpts): Promise<Result<ExecResult, ExecutionError>>;
     /** 管道旧形(win32 / spool 打开失败的回退;行为=1.225 及以前的 exec 原样)。 */
     private execViaPipes;
     /** [ref] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"