@sema-agent/server 7.146.0 → 7.148.0

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

@@ -51,8 +51,9 @@ export declare function createTidbPool(config: ServiceConfig): Pool;
  *  3. 生成的全集 SQL 基线导出到 `docs/schema/baseline-mysql.sql`(由本数组机器生成;它是**产物**,不是真源
  *     —— 冲突时以本文件为准并重新生成)。
  *
- * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + image_bake_admit 种子行),只是语句数组现在是纯
- * CREATE,不再有 information_schema 探针。
+ * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + image_bake_admit 种子行),语句数组是纯 CREATE。数组之外只有一只只读探针:会话部署格旁表
+ * `session_ext` 的外键列要抄被引列 `session_meta.session_id` 的字符集 / 排序规则(MySQL 外键两侧必须相同,而存量库上它随建库年代不同),建它之前读一次
+ * `information_schema.COLUMNS`(`session-ext-table.ts` 的 `ensureSessionExtTableMysql`;探针只读、不导出任何 ALTER)。
  */
 export declare const SCHEMA_STATEMENTS: readonly string[];
 /** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */

package/dist/plugins/tidb-pool.js

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 import mysql from "mysql2/promise";
 import { TIDB_APPROVAL_ASK_STATEMENTS } from "./approval-ask-store-sql.js";
 import { TIDB_MEMORY_OPTOUT_GRANT_STATEMENTS } from "./memory-optout-grant-store-sql.js";
@@ -5,17 +6,18 @@ import { TIDB_SESSION_CAPTURE_OPTOUT_STATEMENTS } from "./session-capture-record
 import { TIDB_LEADER_RUN_STATEMENTS } from "./leader-run-store-sql.js";
 import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
-import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
-import { SESSION_META_INCARNATION_COLUMN } from "../session-incarnation.js";
-import { sessionMetaPlacementColumnsDdl } from "./execution-placement-sql.js";
-import { SESSION_META_WORKSPACE_COLUMN } from "./session-workspace-cell.js";
+import { TIDB_RETENTION_TOMBSTONE_STATEMENTS } from "../stores-sql/retention-store-sql.js";
+import { TIDB_RETENTION_LANE_STATEMENTS } from "./retention-lane-store-sql.js";
+import { SESSION_META_INCARNATION_COLUMN, SESSION_META_LINEAGE_COLUMNS } from "../session-incarnation.js";
+import { ensureSessionExtTableMysql } from "./session-ext-table.js";
+import { CHECKPOINT_HOST_SESSION_COLUMN } from "./checkpoint-index-columns.js";
 import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
-import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
-import { PRINCIPAL_MAX_UTF8_BYTES } from "../security.js";
+import { INBOX_PAYLOAD_COLUMN } from "./inbox-payload-column.js";
+import { PRINCIPAL_MAX_BYTES } from "../principal-shape.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
-import { SESSION_INDEXES } from "./pg-session-storage.js";
+import { SESSION_INDEXES } from "../stores-sql/pg-session-storage.js";
 import { TOOL_RESULT_INDEXES } from "../stores-sql/tool-result-store-sql.js";
 import { COST_QUOTA_INDEXES } from "./pg-cost-quota.js";
 import { RATE_LIMIT_INDEXES } from "./pg-rate-limiter.js";
@@ -25,7 +27,8 @@ import { IMAGE_BAKE_INDEXES } from "./image-bake-store-sql.js";
 import { APPROVAL_ASK_INDEXES } from "./approval-ask-store-sql.js";
 import { ADOPTION_LOG_INDEXES } from "./adoption-log-sql.js";
 import { PERMISSION_RULE_INDEXES } from "./permission-rule-store-sql.js";
-import { RETENTION_INDEXES } from "./retention-store-sql.js";
+import { RETENTION_TOMBSTONE_INDEXES } from "../stores-sql/retention-store-sql.js";
+import { RETENTION_LANE_INDEXES } from "./retention-lane-store-sql.js";
 import { LEADER_RUN_INDEXES } from "./leader-run-store-sql.js";
 import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
 import { createCloseAwarePool } from "./sql-driver.js";
@@ -63,23 +66,8 @@ export const SCHEMA_STATEMENTS = [
      updated_at  DATETIME(3)  NOT NULL,
      leaf_id     VARCHAR(64)  NULL,
      leaf_seq    BIGINT       NOT NULL DEFAULT 0,
-     -- title: ONE column, two writers, one law (src/session-row.ts): the user's write (PATCH /v1/sessions/:id →
-     -- writeSessionRowCells, unconditional unless the PATCH carries expectedRowTag; null = cleared back to the automatic title) and the auto-titler (cheap-model
-     -- one-liner on a submit that finds it NULL; setTitleIfNull, fills NULL only) — a user-set title is never overwritten,
-     -- a cleared one is filled again. Width = SESSION_TITLE_MAX_CHARS (the wire bound).
-     title       VARCHAR(${SESSION_TITLE_MAX_CHARS}) NULL,
-     -- pinned: the user's pin (PATCH /v1/sessions/:id → writeSessionRowCells); every list row carries it, false by default.
-     pinned      BOOLEAN      NOT NULL DEFAULT FALSE,
-     -- instruction_source(S-690):本会话**上一次 run** 选中的项目指令文件 = 换源通告(instructions.source_changed)
-     -- 的基线。NULL = 还没有任何 run 记过(首 run 只写不发);'' = 记过、那一次没有项目指令文件;其余 = 链成员相对路径
-     -- (CLAUDE.md / .claude/CLAUDE.md / AGENTS.md / .claude/AGENTS.md)。服务端元数据:不进模型上下文、不进 wire
-     -- 会话面;住在会话行上 ⇒ 随会话删除 / 留存清扫一起消失,fork 出的新行为 NULL(新会话首 run 同样只写不发)。
-     instruction_source VARCHAR(64) NULL,
-     -- workspace:本会话上一条腿**自己的**最后一帧 workspace_changed(引擎 7.58.0 的整份快照:cwd / root / entered / project / remote)。
-     -- NULL = 还没有任何腿记过;唯一写者 = 腿的记录座(src/session-workspace.ts),列属主 = src/plugins/session-workspace-cell.ts
-     -- (列定义、形读者、编解码;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里给出 ALTER)。下一条腿的 TaskSpec.projectId 读它的 project.id。
-     -- 服务端元数据:不进 wire 会话面、不进模型上下文;住在会话行上 ⇒ 随会话删除 / 留存清扫一起消失,fork 出的新行为 NULL。
-     ${SESSION_META_WORKSPACE_COLUMN.mysql},
+     -- 本服务记在会话上的格(标题 / 置顶 / 换源通告基线 / 位置与项目 / 执行放置那一格 / fork 键)不住这张引擎座表:旁表 session_ext
+     -- (下一条语句;建表 / 列 / 外键级联的唯一属主 = src/plugins/session-ext-table.ts,一会话一行,随本行删除级联)。
      -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组,**创建时一次落行、
      -- first-write 不可变**(register 的 ON DUPLICATE 臂永不重写这六列)。判别位 = placement_kind:
      -- 在场 ⇒ 该会话住在 placement 分区里(不上宿主枚举、claim 形 acquire 恒拒、release=真删除、
@@ -97,11 +85,9 @@ export const SCHEMA_STATEMENTS = [
      -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由本建表语句生成)。
      -- 不上 wire、不进模型上下文、日志只打前 8 位。
      ${SESSION_META_INCARNATION_COLUMN.mysql},
-     -- 执行放置:根会话行上**这一位住客**的一格 —— execution_role('writer' | 'mirror' | NULL = absent)、execution_lane、device 车道的设备与绑定属主、
-     -- 放下时刻、换绑序号;写只按住客谓词 (session_id, incarnation, owner) ∧ placement_kind IS NULL(换了住客 = 这一格不在)。fork_key = 建这一行的那次
-     -- fork 请求的键(只由 fork 创建点写,此后每个写携带)。规则在 src/execution-placement.ts,列定义与语句的唯一属主 = src/plugins/execution-placement-sql.ts
-     -- (存量库缺这些列 ⇒ 起服列册对账拒启;加列只由一次性迁移做)。
-     ${sessionMetaPlacementColumnsDdl("mysql")},
+     -- fork 谱系(建这一行的那次 fork 的源会话 id + 源行那一刻的住客令牌;只由 fork 的建行写,core forkRowCells 铸):NULL = 不是 fork 建的行,
+     -- 或这两列落地之前建的 fork(源已不可知,不回填)。列定义的唯一属主 = src/session-incarnation.ts 的 SESSION_META_LINEAGE_COLUMNS。
+     ${SESSION_META_LINEAGE_COLUMNS.mysql},
      PRIMARY KEY (session_id),
      KEY idx_session_meta_owner (owner),
      -- listPlaced 的检索腿(kind + 租户 + 年龄升序);普通会话这三列全 NULL ⇒ 不占索引选择性。
@@ -368,9 +354,14 @@ export const SCHEMA_STATEMENTS = [
      -- 两列同生同灭(stamp 在场 ⇔ 记录在场);reopen 见到记录即拒(已结算的动作不可重开)。
      execution_outcome JSON   NULL,
      execution_at_ms   BIGINT NULL,
+     -- host_session_id:这张卡**归在哪只会话上**(兑现它的那条 run 的会话;cascade 的级上卡 = 调用方的会话,其余 = session_id)。写口 put 由
+     -- plugins/checkpoint-index-columns.ts 的 hostSessionOf 求值一次;存量行由一次性迁移 M49 自 session_id 回填。按会话找卡的读口(决断 / 取消 / 收割 /
+     -- 续跑输入回收 / 运维队列行)只读它;session_id 只答「这是哪段对话」。列定义的唯一属主 = 同模块的 CHECKPOINT_HOST_SESSION_COLUMN。
+     ${CHECKPOINT_HOST_SESSION_COLUMN.mysql},
      PRIMARY KEY (token),
      KEY idx_checkpoint_status_deadline (status, deadline),
-     KEY idx_checkpoint_session_status (session_id, status)
+     KEY idx_checkpoint_session_status (session_id, status),
+     KEY idx_checkpoint_host_session_status (host_session_id, status)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
      session_id    VARCHAR(190) NOT NULL,
@@ -401,22 +392,27 @@ export const SCHEMA_STATEMENTS = [
      expires_at_ms  BIGINT       NOT NULL,
      PRIMARY KEY (session_id, nonce),
      KEY idx_approval_nonce_expires (expires_at_ms)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS approval_nonce_floor (
+     singleton CHAR(1) NOT NULL DEFAULT 'x',
+     floor_ms  BIGINT  NOT NULL,
+     PRIMARY KEY (singleton)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS org_delivery_sender_quota (
-     from_scope      VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     from_scope      VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
      window_start_ms BIGINT         NOT NULL,
      attempts        INT            NOT NULL,
      PRIMARY KEY (from_scope)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS org_delivery_recipient_quota (
-     to_scope        VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     to_scope        VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
      window_start_ms BIGINT         NOT NULL,
      delivered       INT            NOT NULL,
      PRIMARY KEY (to_scope)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS org_delivery_pair_quota (
-     to_scope        VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
-     from_scope      VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     to_scope        VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+     from_scope      VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
      window_start_ms BIGINT         NOT NULL,
      delivered       INT            NOT NULL,
      PRIMARY KEY (to_scope, from_scope)
@@ -634,7 +630,8 @@ export const SCHEMA_STATEMENTS = [
      -- payload: bounded + redacted JSON extras of the entry's kind. task_notification: task_type / result / …;
      -- workflow_complete: at most {"completionId": …, "diagnostics": …} (the engine's own correlation id, verbatim; the engine's diagnostic
      -- teaching text, redacted + bounded at enqueue; each key absent when the engine minted none, NULL when neither).
-     payload        TEXT         NULL,
+     -- Column definition owner = inbox-payload-column.ts (INBOX_PAYLOAD_COLUMN); the entry byte budget derives from the same type word.
+     ${INBOX_PAYLOAD_COLUMN.mysql},
      PRIMARY KEY (session_id, run_id),
      UNIQUE KEY uq_wfinbox_seq (seq),
      KEY idx_wfinbox_session_seq (session_id, seq)
@@ -816,7 +813,8 @@ export const SCHEMA_STATEMENTS = [
    ) COLLATE utf8mb4_bin`,
     ...TIDB_ADOPTION_LOG_STATEMENTS,
     ...TIDB_PERMISSION_RULE_STATEMENTS,
-    ...TIDB_RETENTION_STATEMENTS,
+    ...TIDB_RETENTION_LANE_STATEMENTS,
+    ...TIDB_RETENTION_TOMBSTONE_STATEMENTS,
 ];
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
 export async function acquireEnsureSchemaLock(conn, tag = "ensureSchema") {
@@ -830,7 +828,7 @@ export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
         await conn.query("SELECT RELEASE_LOCK(?)", [ENSURE_SCHEMA_LOCK]);
     }
     catch (err) {
-        console.warn(`[${tag}] RELEASE_LOCK('${ENSURE_SCHEMA_LOCK}') failed (lock auto-frees on connection close):`, err);
+        writeLogText("stderr", `[${tag}] RELEASE_LOCK('${ENSURE_SCHEMA_LOCK}') failed (lock auto-frees on connection close):`, err);
     }
 }
 export const SCHEMA_INDEXES = [
@@ -845,7 +843,8 @@ export const SCHEMA_INDEXES = [
     ...APPROVAL_ASK_INDEXES,
     ...ADOPTION_LOG_INDEXES,
     ...PERMISSION_RULE_INDEXES,
-    ...RETENTION_INDEXES,
+    ...RETENTION_LANE_INDEXES,
+    ...RETENTION_TOMBSTONE_INDEXES,
     ...LEADER_RUN_INDEXES,
 ];
 export async function ensureSchema(pool) {
@@ -857,6 +856,10 @@ export async function ensureSchema(pool) {
         for (const stmt of SCHEMA_STATEMENTS) {
             await conn.query(stmt);
         }
+        await ensureSessionExtTableMysql(async (sql) => {
+            const [rows] = await conn.query(sql);
+            return Array.isArray(rows) ? rows : [];
+        });
         await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES ('standard')");
         await ensureIndexes((text, params) => conn.query(text, params), "mysql", SCHEMA_INDEXES);
     }

package/dist/plugins/user-input-ledger-sql.d.ts

@@ -15,7 +15,7 @@
  *
  * ## 会话树删除([ref])
  * `deleteBySession` = `DELETE … WHERE session_id = ?`(真删行;File 孪生是一行会话级墓碑,同义)。两条删会话树的级联各有一臂:在线删除协调器
- * 经本动词;托管留存的事务化孪生(`retention-store-sql.ts` `purgeSessionTrees` ④)在**自己的事务**里对本表发同一只谓词(`session_id` 单键,
+ * 经本动词;托管留存的事务化孪生(`retention-deployment.ts` `deleteDeploymentSessionRows` ④,执行器的 `beforeDelete` 钩)在**自己的事务**里对本表发同一只谓词(`session_id` 单键,
  * 多值集合按方言)—— 它不调店,理由见该文件顶注的布局裁定(一个事务 ⇒ 一条连接 ⇒ 一个属主)。谓词走 `(session_id, state, accepted_at_ms)` 索引的前缀。
  *
  * ## 读不出的行([ref] L6):逐行跳过,游标按原始行推进

package/dist/plugins/web-search.js

@@ -2,7 +2,9 @@ import { validateHeaderValue } from "node:http";
 import { createSearxngSearchBackend } from "@sema-agent/core";
 import { findUrlCredential, findUrlUserinfo, isHierarchicalUrl } from "@sema-agent/settings-schema";
 import { redactSecrets } from "../trace/redact.js";
+import { createEgressFetch } from "../egress-redirect.js";
 import { buildRequestUrlCredentialRefusal, urlCredentialFacts } from "../url-credential-refusal.js";
+import { readUpstreamJson } from "../upstream-body.js";
 export const WEB_SEARCH_PROVIDERS = ["brave", "tavily", "searxng"];
 function isWebSearchProvider(word) {
     return WEB_SEARCH_PROVIDERS.includes(word);
@@ -99,7 +101,7 @@ async function braveSearch(fetchImpl, cfg, query, max, signal) {
     const res = await fetchImpl(url, { headers: { Accept: "application/json", "X-Subscription-Token": token }, signal });
     if (!res.ok)
         throw await httpFailure("brave", res);
-    const data = (await res.json());
+    const data = (await readUpstreamJson(res));
     return normalize(data.web?.results, (r) => ({ title: r.title, url: r.url, snippet: r.description }), max, "brave");
 }
 async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
@@ -117,7 +119,7 @@ async function tavilySearch(fetchImpl, cfg, query, max, signal, opts) {
     });
     if (!res.ok)
         throw await httpFailure("tavily", res);
-    const data = (await res.json());
+    const data = (await readUpstreamJson(res));
     return normalize(data.results, (r) => ({ title: r.title, url: r.url, snippet: r.content }), max, "tavily");
 }
 async function searxngSearch(fetchImpl, cfg, query, max, signal, timeoutMs, opts) {
@@ -151,7 +153,7 @@ function redactedBackendFailure(e) {
     return safe === text ? e : new Error(safe);
 }
 export function createWebSearchBackend(cfg) {
-    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const fetchImpl = createEgressFetch("declare the final search address as WEB_SEARCH_ENDPOINT", cfg.fetchImpl);
     const maxResults = Math.max(1, Math.min(20, cfg.maxResults ?? DEFAULT_MAX_RESULTS));
     const timeoutMs = Math.max(1000, cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const search = async (query, signal, opts) => {

package/dist/plugins/workflow-run-store-sql.d.ts

@@ -62,7 +62,7 @@ import type { WorkflowNotifyJournalStore, WorkflowNotifyJournalEntry } from "../
 import { type WorkflowAgentSessionIndex, type WorkflowAgentSessionRow } from "../orchestration/workflow-agent-session-index.js";
 import { type WorkflowParkDecision, type WorkflowParkDecisionStore } from "../orchestration/workflow-park-decision.js";
 import type { SqlRunStore } from "./run-store-sql.js";
-import { type SqlDriver } from "./sql-driver.js";
+import { type SqlDialect, type SqlDriver, type SqlExec } from "./sql-driver.js";
 type WorkflowRun = Parameters<WorkflowRunStore["put"]>[1];
 /** Row cap guard: a run blob beyond this is NOT stored on update (the prior revision stays) — TiDB's
  *  ~6 MiB txn-entry limit would otherwise throw the (best-effort) progress write into the workflow loop.
@@ -148,6 +148,11 @@ export declare class SqlWorkflowRunStore implements WorkflowRunStore {
         keep?: number;
     }): Promise<number>;
 }
+/**
+ * 立一只会话的**清除围栏**(session 全宽,`run_id = ''`;窗 = `PURGE_FENCE_MS`):此后同属主的 enqueue 落空(`purgedOwner` 缺席 = 属主未知 ⇒ 围全部)。
+ * 语句源唯一:信箱自己的 `purge` 与删净会话的执行体(`retention-deployment.ts` 的部署行,在执行体那一个事务里)同调。Upsert = 再清一次刷新窗。
+ */
+export declare function writeInboxPurgeFenceOn(exec: SqlExec, dialect: SqlDialect, sessionId: string, purgedOwner: string | null | undefined, now: number): Promise<void>;
 /** Dual-dialect `WorkflowCompletionInbox`. See the file header for the dialect-delta ledger. */
 export declare class SqlWorkflowCompletionInbox implements WorkflowCompletionInbox {
     protected readonly db: SqlDriver;

package/dist/plugins/workflow-run-store-sql.js

@@ -168,6 +168,16 @@ export class SqlWorkflowRunStore {
 }
 const KIND_SERVED = "served";
 const KIND_PURGE = "purge";
+export async function writeInboxPurgeFenceOn(exec, dialect, sessionId, purgedOwner, now) {
+    const known = purgedOwner !== undefined ? 1 : 0;
+    await exec.query(dialect === "mysql"
+        ? "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES (?,?,?,?,?,?) " +
+            "ON DUPLICATE KEY UPDATE owner = VALUES(owner), owner_known = VALUES(owner_known), until_ms = VALUES(until_ms)"
+        : "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,'',$3,$4,$5) " +
+            "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET owner = EXCLUDED.owner, owner_known = EXCLUDED.owner_known, until_ms = EXCLUDED.until_ms", dialect === "mysql"
+        ? [sessionId, KIND_PURGE, "", purgedOwner ?? null, known, now + PURGE_FENCE_MS]
+        : [sessionId, KIND_PURGE, purgedOwner ?? null, known, now + PURGE_FENCE_MS]);
+}
 export class SqlWorkflowCompletionInbox {
     db;
     onWarn;
@@ -241,11 +251,7 @@ export class SqlWorkflowCompletionInbox {
     async purge(sessionId, purgedOwner) {
         const now = Date.now();
         await this.sweepFences(now);
-        await this.db.query(this.q("INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES (?,?,?,?,?,?) " +
-            "ON DUPLICATE KEY UPDATE owner = VALUES(owner), owner_known = VALUES(owner_known), until_ms = VALUES(until_ms)", "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,'',$3,$4,$5) " +
-            "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET owner = EXCLUDED.owner, owner_known = EXCLUDED.owner_known, until_ms = EXCLUDED.until_ms"), this.db.dialect === "mysql"
-            ? [sessionId, KIND_PURGE, "", purgedOwner ?? null, purgedOwner !== undefined ? 1 : 0, now + PURGE_FENCE_MS]
-            : [sessionId, KIND_PURGE, purgedOwner ?? null, purgedOwner !== undefined ? 1 : 0, now + PURGE_FENCE_MS]);
+        await writeInboxPurgeFenceOn(this.db, this.db.dialect, sessionId, purgedOwner, now);
         await this.db.query(this.q("DELETE FROM workflow_completion_inbox WHERE session_id = ?", "DELETE FROM workflow_completion_inbox WHERE session_id = $1"), [sessionId]);
     }
     async markTerminalServed(sessionId, runId) {

package/dist/principal-jwt.d.ts

@@ -1,5 +1,6 @@
 import type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.js";
 import { type ApprovalEnvelope } from "./approval-hmac.js";
+import { type Person } from "./owner-brands.js";
 /**
  * 验签允许的**时钟不一致容差**(秒)—— 本仓这条轴上的单一来源。
  *
@@ -45,8 +46,6 @@ export declare function verifyPrincipalJwt(token: string, keys: PrincipalJwtKey[
  * 形:`sha256(utf8(editedPlan))` hex —— 与 `approvalBnd` 同摘要、同编码;逐字节,不归一化(签名器与 worker
  * 必须对同一串字节达成一致,任何"归一化"都是第二个写者)。
  */
-/** 良构 Unicode(无孤立代理项)。`u` 旗下配对代理项是一个码点、不匹配 `\p{Surrogate}`;只有孤立的才命中。 */
-export declare function isWellFormedUnicode(s: string): boolean;
 export declare function editedPlanBinding(editedPlan: string): string;
 /**
  * JWT `cnf.bnd` = **「这份身份凭据被签发去决哪一张卡」**(动作身份),故只哈希前三位。
@@ -79,10 +78,11 @@ export interface SingleUseProof {
      */
     readonly acceptedBeforeMs: number;
 }
-/** {@link verifyDirectDoorProof} 的判决。`singleUse` 在场 = 调用方必须在改任何状态**之前**消费它一次。 */
+/** {@link verifyDirectDoorProof} 的判决。`singleUse` 在场 = 调用方必须在改任何状态**之前**消费它一次。`principal` = 这一次决定的证明推出的人
+ *  (带 `Person` 品牌:本函数是它的铸点之一 —— 决定口用它替换请求身份,`http/owner-access.ts` 的 `callerOfDecision` 按请求的场景铸决定者的主体)。 */
 export type DirectDoorProofResult = {
     ok: true;
-    principal: string;
+    principal: Person;
     singleUse?: SingleUseProof;
 } | {
     ok: false;

package/dist/principal-jwt.js

@@ -1,5 +1,7 @@
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { verifyApprovalHmac } from "./approval-hmac.js";
+import { mintPerson } from "./owner-brands.js";
+import { PRINCIPAL_MAX_BYTES, isWellFormedUnicode, principalShapeProblem } from "./principal-shape.js";
 export const PRINCIPAL_JWT_CLOCK_SKEW_SEC = 30;
 function b64urlToBuf(s) {
     return Buffer.from(s, "base64url");
@@ -72,9 +74,6 @@ export function verifyPrincipalJwt(token, keys, expect) {
     const bnd = typeof payload.cnf?.bnd === "string" ? payload.cnf.bnd : undefined;
     return { sub: payload.sub, bnd, acceptedBeforeMs: (Math.floor(payload.exp + skew) + 1) * 1000 };
 }
-export function isWellFormedUnicode(s) {
-    return !/\p{Surrogate}/u.test(s);
-}
 export function editedPlanBinding(editedPlan) {
     if (!isWellFormedUnicode(editedPlan))
         throw new Error("editedPlanBinding: editedPlan is not well-formed Unicode (lone surrogate) — utf8 hashing would be lossy");
@@ -104,8 +103,24 @@ export function verifyDirectDoorProof(proof, envelope, config, opts) {
     const ok = verifyApprovalHmac(envelope, proof.mac, proof.kid, config.approvalHmacKeys);
     if (!ok)
         return { ok: false, status: 401, errorCode: "approval_mac_invalid", error: "approval envelope MAC invalid" };
+    const shape = principalShapeProblem(verified.sub);
+    switch (shape) {
+        case undefined:
+            break;
+        case "not_a_name":
+            return { ok: false, status: 400, errorCode: "principal_not_a_name", error: "principal token subject is not a principal name — the issuer must sign a visible-character identity" };
+        case "reserved":
+            return { ok: false, status: 400, errorCode: "principal_reserved", error: "principal token subject is a reserved identifier (an internal scope sentinel or a scenario subject) — the issuer must sign the person's own identifier" };
+        case "too_long":
+            return { ok: false, status: 400, errorCode: "principal_too_long", error: `principal token subject exceeds ${PRINCIPAL_MAX_BYTES} UTF-8 bytes` };
+        default: {
+            const unknownShape = shape;
+            throw new Error(`verifyDirectDoorProof: unknown principal shape problem ${String(unknownShape)}`);
+        }
+    }
+    const principal = mintPerson(verified.sub);
     return actionBinding
-        ? { ok: true, principal: verified.sub }
-        : { ok: true, principal: verified.sub, singleUse: { nonce: envelope.boundCallId, acceptedBeforeMs: verified.acceptedBeforeMs } };
+        ? { ok: true, principal }
+        : { ok: true, principal, singleUse: { nonce: envelope.boundCallId, acceptedBeforeMs: verified.acceptedBeforeMs } };
 }
 //# sourceMappingURL=principal-jwt.js.map

package/dist/principal-shape.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 🔴 **主体长度的唯一定义:至多这么多个 UTF-8 字节。** 凡判「这只串当不当得了主体 / 主体身份键」的长度,一律读它、按字节数(`Buffer.byteLength(s, "utf8")`):
+ * 本文件的判官、收件箱的键判官(收件箱 scope 就是主体)、记忆退出名单的判、两处运维 `?scope=` 查询、规则面的运维目标、配额三表两方言的身份列宽。
+ * 为什么是字节:主体原样落进的最窄一类列是按字节计宽的 `VARBINARY(190)`(收件箱 / 后台子代 / 名册的键列);按字符计宽的 `VARCHAR(190)`(TiDB utf8mb4 与 PG
+ * 都数码点)装得下任何 190 字节的串(一个码点至少一个字节)。所以 190 字节 ≤ 「190 家族」每一只主体列,升到本尺不需要改任何既有列。
+ * 不同源的 190(会话 / run / 工具调用 id 列的历史宽度惯例、断路器键、跨会话信封来源位、编码后的记忆 scope 列、令牌 scope 声明)不读本常量。
+ */
+export declare const PRINCIPAL_MAX_BYTES = 190;
+/**
+ * 良构 Unicode(无孤立代理项)的唯一判式 —— 主体名判官的一格(下面),也是收件箱键判官与编辑计划绑定摘要的同一读法(住在叶子里,三处都能值导入、不成环)。
+ * `u` 旗下配对代理项是一个码点、不匹配 `\p{Surrogate}`;只有孤立的才命中。
+ */
+export declare function isWellFormedUnicode(s: string): boolean;
+/** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
+ *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
+ *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的超范围面。
+ *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
+ *  resource-suspend scope family); `"__none__"` = the missing-principal read placeholder of the approval
+ *  queue faces up to 7.132.x (7.133.0 reads the anonymous group `"_"` instead; still reserved because a 7.132.x replica in the same
+ *  rolling upgrade lists that scope for anonymous callers, so a tenant by that name would merge with them there); `"_leader"` = leader durable-approval scope
+ *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
+ *  (`_leader-resource-<workerId>`, src/leader/wire.ts); prefix `"_orphan:"` = the owner written on a delegated session whose
+ *  delegation ancestors are gone (`_orphan:<sessionId>`, src/delegated-session-owner.ts) — a caller allowed to authenticate as it
+ *  would read that transcript; prefix `"_scn:"` = a subject that carries a scenario (`_scn:<scenario>:<person>`, `owner-brands.ts` `subjectOf`) —
+ *  a caller allowed to authenticate as it would BE another person's scenario partition. NB the `_leader-` prefix REQUIRES the hyphen — a tenant named
+ *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
+export declare const RESERVED_PRINCIPALS: readonly string[];
+export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
+/** The principal-shape rule as a VERDICT (the one judge; {@link assertPrincipalShape} is its throwing reader). `undefined` = a
+ *  principal may carry this string; otherwise which rule it breaks. A reader that only needs "can this string be anyone?" (the
+ *  organization delivery gate's recipient: a string that breaks the rule is nobody, refused with the same bytes as an unknown
+ *  principal) reads the verdict instead of catching the throw.
+ *
+ *  Order: "is it a name at all" first — the other two rules presuppose a name (a reserved identifier / a name too wide for the
+ *  column), and the `reserved` sentence echoes the value while the `not_a_name` sentence never does (a string that names nobody may be a
+ *  pasted credential). An empty string is `not_a_name` here (the engine's judge says so); so is a string that is not well-formed Unicode (a lone
+ *  surrogate is no character). A header reader that treats a blank header as "no principal" decides that before asking. `too_long` counts UTF-8 bytes
+ *  ({@link PRINCIPAL_MAX_BYTES}). */
+export type PrincipalShapeProblem = "not_a_name" | "reserved" | "too_long";
+export declare function principalShapeProblem(principal: string): PrincipalShapeProblem | undefined;
+//# sourceMappingURL=principal-shape.d.ts.map

package/dist/principal-shape.js

@@ -0,0 +1,19 @@
+import { principalNameOf } from "@sema-agent/core";
+import { ORPHAN_SESSION_OWNER_PREFIX } from "./delegated-session-owner.js";
+import { SCENARIO_SUBJECT_PREFIX } from "./owner-brands.js";
+export const PRINCIPAL_MAX_BYTES = 190;
+export function isWellFormedUnicode(s) {
+    return !/\p{Surrogate}/u.test(s);
+}
+export const RESERVED_PRINCIPALS = ["_", "__none__", "_leader"];
+export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-", ORPHAN_SESSION_OWNER_PREFIX, SCENARIO_SUBJECT_PREFIX];
+export function principalShapeProblem(principal) {
+    if (principalNameOf(principal) === undefined || !isWellFormedUnicode(principal))
+        return "not_a_name";
+    if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p)))
+        return "reserved";
+    if (Buffer.byteLength(principal, "utf8") > PRINCIPAL_MAX_BYTES)
+        return "too_long";
+    return undefined;
+}
+//# sourceMappingURL=principal-shape.js.map

package/dist/question.d.ts

@@ -1,4 +1,5 @@
 import { type AskQuestionRequest, type OnQuestionOutcome, type QuestionAnswer, type AskQuestion } from "@sema-agent/core";
+import { type HitlTransport } from "./hitl-delivery.js";
 /** A live question frame delivered to whoever tails this run's stream. `type` IS the SSE event name (mirrors the
  *  named-event convention; the payload also carries `type` so a proxy that strips event names still works). The shell
  *  renders `question` as a dialog and dismisses on `question_complete`. */
@@ -23,30 +24,20 @@ export interface QuestionFrame {
     /** "question" only: `serverNowMs + expiresInMs` — absolute deadline on the server's clock. */
     expiresAtMs?: number;
 }
-/** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's stream; `abortSignal`
- *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts.
+/** The per-run context `onQuestion` recovers via ALS. `transport` = the leg's ONE HITL transport (shared with the elicitation
+ *  and approval contexts of the same leg; `hitl-delivery.ts` owns the law: ledger first, then live — a frame the ledger
+ *  cannot take never reaches the live face). `abortSignal` (the run's own cancel signal) releases a question parked
+ *  awaiting a human when the run aborts.
  *
- *  🔴 ONE LAW for every leg: a question frame that enters a run's stream has a LEDGER TWIN (the row
- *  `GET /v1/runs/:id/events` replays — a page reload recovers the open card from it); the leg decides only whether it
- *  ALSO writes a live socket. The background leg has no socket, so its `emit` IS the durable append; the synchronous
- *  stream leg lands the same frame in the ledger first and then writes the SSE connection (`createLedgerTwinEmit`).
  *  The ledger carries the CARD, not the answer door: `POST /v1/questions/:id/respond` stays live-only (this replica's
- *  memory, `ttlMs`), so a replayed card is answerable only until its own `expiresAtMs` and only on this replica. */
+ *  memory, `ttlMs`), so a replayed card is answerable only until its own `expiresAtMs` and only on this replica.
+ *  The adjudication probe ({@link QuestionCoordinator.hasLiveContext}) reads the same transport's `reachable()` — one
+ *  reading of "can this leg's face show a card right now?". */
 export interface QuestionRunContext {
     taskId: string;
     owner: string | null;
-    emit: (frame: QuestionFrame) => void | Promise<void>;
+    transport: HitlTransport<QuestionFrame>;
     abortSignal?: AbortSignal;
-    /** OPTIONAL reachability predicate for this leg's LIVE delivery face — one reading, two consumers:
-     *  {@link QuestionCoordinator.hasLiveContext} (the park-vs-live adjudication probe) and the OPEN frame itself (a face
-     *  that cannot show the card right now refuses the ask on the spot, the same failed-delivery arm, instead of parking it
-     *  to TTL on a ledger row nobody is watching). CONSTRAINT: a leg whose face can go away WHILE the leg keeps running MUST
-     *  supply it — `/v1/tasks/stream` under `x-detach-on-disconnect: true` keeps executing inside this ALS scope after the
-     *  client left. Without the predicate the adjudication would read "live" and hand the leg to a face nobody can reach.
-     *  ABSENT ⇒ always reachable, which is exactly right for the background leg (its face IS the durable events tail,
-     *  readable whenever a client attaches). The CLOSE frame never asks it: it is a record, and it lands in the ledger twin
-     *  whether or not the socket is still there. */
-    deliverable?: () => boolean;
 }
 /** The per-run question window the deployment owns (core caps nothing). Env: `QUESTION_MAX_CONCURRENT_PER_RUN` /
  *  `QUESTION_MAX_TOTAL_PER_RUN` / `QUESTION_TTL_MS` (see `ServiceConfig.questionThrottle`). */
@@ -91,7 +82,7 @@ export declare class QuestionCoordinator {
     question: (req: AskQuestionRequest, signal?: AbortSignal) => Promise<OnQuestionOutcome>;
     /** `POST /v1/questions/:id/respond` — resolve a parked question with the shell's answer. Owner-gated with a 404 (no
      *  existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica) both get 404. Returns the
-     *  HTTP {status, body}; the HTTP layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
+     *  HTTP {status, body}; the HTTP layer owns auth (gatedSubject + REQUIRE_PRINCIPAL) before calling. */
     respond(id: string, principal: string | undefined, body: unknown): {
         status: number;
         body: unknown;
@@ -103,10 +94,9 @@ export declare class QuestionCoordinator {
      *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
      *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。
      *  🔴 判据是「投递面此刻可达」而不只是「ALS 在场」(复审 A1):detach 腿断连后 run 仍在本作用域里跑,
-     *  只判 ALS 会把一条谁也收不到的问题判成 allow——挂满 ttl 后以 unavailable 结算,非 durable 形 core
-     *  就此合成续跑,活人再没机会答;而 park 才是它该走的腿。
-     *  谓词缺席 ⇒ 恒可达(后台腿的 durable events tail 语义)。谓词本身抛错按不可达处理:判决面
-     *  fail-closed 到 park(park 可由运维补答,续跑掉的问题不可回收)。 */
+     *  只判 ALS 会把一条谁也收不到的问题判成 allow;park 才是它该走的腿。读的是本腿传输的 `reachable()`
+     *  (有直写面 ⇒ 直写此刻活着;只有账本 ⇒ 恒真,后台腿的 durable events tail 语义;谓词读不出 ⇒ 假,判决面 fail-closed 到 park)。
+     *  只服务判决面:判决放行之后的开帧投递只读传输律(有账本的腿上死直写 = 卡在账本里,送到)。 */
     hasLiveContext(): boolean;
     private countersFor;
 }

package/dist/question.js

@@ -3,17 +3,9 @@ import { uuidv7 } from "@sema-agent/core";
 import { redactDeep } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { refusalBody } from "./http/refusal-body.js";
+import { keyAdmits, ownerCellOf, recoveredSubject } from "./owner-faces.js";
+import { createHitlOpenRace } from "./hitl-delivery.js";
 const MAX_QUESTIONS_BYTES = 16384;
-function isFaceReachable(ctx) {
-    if (ctx.deliverable === undefined)
-        return true;
-    try {
-        return ctx.deliverable();
-    }
-    catch {
-        return false;
-    }
-}
 export const DEFAULT_QUESTION_THROTTLE = {
     maxConcurrentPerRun: 2,
     maxTotalPerRun: 20,
@@ -113,39 +105,29 @@ export class QuestionCoordinator {
         signal?.addEventListener("abort", onAbort, { once: true });
         ctx.abortSignal?.addEventListener("abort", onAbort, { once: true });
         this.pending.set(id, { settle, owner: ctx.owner, taskId: ctx.taskId });
-        const emitted = (async () => {
-            if (!isFaceReachable(ctx))
-                throw new Error("question delivery face unreachable — the open frame has nobody to show it to");
-            const now = Date.now();
-            await ctx.emit({ type: "question", questionId: id, questions, serverNowMs: now, expiresInMs: this.throttle.ttlMs, expiresAtMs: now + this.throttle.ttlMs });
-            return isFaceReachable(ctx) ? "ok" : "landed-face-gone";
-        })()
-            .then((r) => r, () => "failed");
-        const delivery = await Promise.race([emitted, answerP.then(() => "stalled")]);
-        if (delivery === "ok" || delivery === "landed-face-gone") {
+        const now = Date.now();
+        const race = createHitlOpenRace({
+            targets: [{ transport: ctx.transport, frame: { type: "question", questionId: id, questions, serverNowMs: now, expiresInMs: this.throttle.ttlMs, expiresAtMs: now + this.throttle.ttlMs } }],
+            settled: answerP,
+        });
+        const phase = await race.phase;
+        if (phase === "delivered") {
             rc.total += 1;
-            if (delivery === "landed-face-gone") {
-                recordFailOpen("server.question.open-frame-undelivered", `question=${id} face-gone-while-landing`);
-                settle(UNAVAILABLE, "unanswered");
-            }
         }
-        else if (delivery === "failed") {
+        else if (phase === "undelivered") {
             recordFailOpen("server.question.open-frame-undelivered", `question=${id}`);
             settle(UNAVAILABLE, "unanswered");
         }
-        const answer = await answerP;
-        void emitted
-            .then((result) => {
-            if (result === "failed") {
-                if (delivery === "stalled")
+        else {
+            void race.landing.then((late) => {
+                if (late === "delivered")
+                    rc.total += 1;
+                else
                     recordFailOpen("server.question.open-frame-undelivered", `question=${id}`);
-                return undefined;
-            }
-            if (delivery === "stalled")
-                rc.total += 1;
-            return ctx.emit({ type: "question_complete", questionId: id, outcome: lastOutcome, serverNowMs: Date.now() });
-        })
-            .catch(() => recordFailOpen("server.question.complete-breadcrumb-dropped", `question=${id}`));
+            });
+        }
+        const answer = await answerP;
+        race.close({ type: "question_complete", questionId: id, outcome: lastOutcome, serverNowMs: Date.now() });
         return answer;
     };
     respond(id, principal, body) {
@@ -153,7 +135,7 @@ export class QuestionCoordinator {
         if (!parsed.ok)
             return { status: 400, body: refusalBody({ errorCode: "request.body_shape", message: parsed.error }) };
         const entry = this.pending.get(id);
-        if (!entry || (entry.owner !== null && entry.owner !== principal)) {
+        if (!entry || !keyAdmits("ask.answer", { subject: recoveredSubject(principal), operator: false }, ownerCellOf(entry.owner))) {
             return { status: 404, body: refusalBody({ errorCode: "question.not_pending", message: "no pending question for this id (answered, expired, or not on this replica)" }) };
         }
         entry.settle(parsed.value, "answered");
@@ -164,7 +146,7 @@ export class QuestionCoordinator {
     }
     hasLiveContext() {
         const ctx = this.als.getStore();
-        return ctx !== undefined && isFaceReachable(ctx);
+        return ctx !== undefined && ctx.transport.reachable();
     }
     countersFor(taskId) {
         let rc = this.counters.get(taskId);