@sema-agent/server 7.3.0 → 7.5.0

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

@@ -99,8 +99,15 @@ function pendingActionToolCallId(blob) {
     }
     if (typeof parsed !== "object" || parsed === null)
         return { readable: false };
+    // 🔴 `sourceTaskId` 是 checkpoint 的**顶层**字段(不在 pendingAction 里),没有对应的列 ⇒ 只能从
+    // blob 读。它是和解三元组的第一维(#168 件1);形不合(有这个键但不是字符串)= 结构漂移,按本函数
+    // 一贯的收窄纪律判 `readable: false`,不静默折成缺席。
+    const rawSource = "sourceTaskId" in parsed ? parsed.sourceTaskId : null;
+    if (rawSource !== null && rawSource !== undefined && typeof rawSource !== "string")
+        return { readable: false };
+    const sourceTaskId = typeof rawSource === "string" ? rawSource : null;
     if (!("pendingAction" in parsed))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind: null }; // 无 pendingAction 的 park:确定不匹配
+        return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceTaskId }; // 无 pendingAction 的 park:确定不匹配
     const pa = parsed.pendingAction;
     if (typeof pa !== "object" || pa === null)
         return { readable: false };
@@ -108,7 +115,7 @@ function pendingActionToolCallId(blob) {
     if (kind !== null && typeof kind !== "string")
         return { readable: false };
     if (!("toolCallId" in pa))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind }; // plan_review / task_done / resource_limit 腿
+        return { readable: true, toolCallId: null, boundInputHash: null, kind, sourceTaskId }; // plan_review / task_done / resource_limit 腿
     const id = pa.toolCallId;
     if (typeof id !== "string")
         return { readable: false };
@@ -122,7 +129,7 @@ function pendingActionToolCallId(blob) {
     const bih = "boundInputHash" in pa ? pa.boundInputHash : null;
     if (bih !== null && typeof bih !== "string")
         return { readable: false };
-    return { readable: true, toolCallId: id, boundInputHash: bih, kind };
+    return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceTaskId };
 }
 const DUP_ENTRY = 1062; // MySQL/TiDB ER_DUP_ENTRY
 const PG_UNIQUE_VIOLATION = "23505";
@@ -228,6 +235,39 @@ const STEER_CAS_ATTEMPTS = 8;
 export class SqlCheckpointStore {
     db;
     logger;
+    /**
+     * `CheckpointStore.durability` 声明(#167 欠账,#168 件5)—— 行落在 MySQL-protocol / PostgreSQL 的
+     * `checkpoint` 表里,进程重启、副本轮换、整机重建都不丢 ⇒ `"durable"`,如实。
+     *
+     * 🔴 为什么这一格空着是有代价的:core 的 `resolveDeclaredDurability` 把**缺席**折成 `"process-local"`
+     * (它不能替一个没表态的店猜),于是静态装配面对每一个真持久部署都读出 `process_local`,
+     * `GET /v1/diagnostics/wiring` 的 park 车道读数与启动自检的那条警告都因此不可信 —— 而 park 正是流内
+     * 审批协议的降级目的地,「重启后还赎不赎得回」是运维必须能一眼看见的事。声明是店自己的责任,不是
+     * 消费侧靠 backend.kind 猜出来的。
+     */
+    durability = "durable";
+    /**
+     * `CheckpointStore.fidelity` 声明(core 5.17.0 [3052] 提货批 #172)——**如实按介质判**:本店把整个
+     * checkpoint 经 {@link SqlCheckpointStore.json} 编码进一个 JSON 列(TiDB 逐字文本 / PG lossless
+     * `::jsonb` 协议信封),读侧 `parseJson` 还原 ⇒ 能扛过 round-trip 的只有 JSON 值域,`"json"`。
+     *
+     * 🔴 为什么必须显式写、哪怕缺席也折向 json:core 的 `resolveDeclaredFidelity` 对缺席是 fail-closed
+     * (读 json),所以沉默不会立刻错——但沉默**表达不出**「我核对过我的介质就是这个宽度」。park 铸行
+     * 的 args / preview / 风险描述 / `boundInputHash` 全部从这一格算出的投影铸;哪天这四行编码里任何
+     * 一处改了介质(换存储格式、换列类型),声明在场才有东西可以红,沉默那格只会安静地按错宽度铸出
+     * 一份「审批人看到的 ≠ 盘上躺着的 ≠ resume 执行的」。同 `durability` 的 #168 件5 教训:表态是店
+     * 自己的责任,不是消费侧靠 backend.kind 猜。
+     *
+     * ⚠️ **已知残余(不是遮掩,是这两个词表达不了的那一格)**:PG 臂比 `"json"` 字面**略窄** ——
+     * {@link pgProtocolJsonStringify} 对含 NUL / lone surrogate 的串 fail-loud 拒绝(R4-H1 有意裁定:
+     * 复核面必须与真执行的 args 在 NUL 那一位上一致,「悄悄清洗再存」是不可接受的那一支),而 core 的
+     * json 宽度收下这些码位。`StoreFidelity` 的闭集只有 `"structured-clone" | "json"`,没有第三个词能说
+     * 「json 减去本介质存不下的码位」——声明 `"structured-clone"` 是大得多的谎,所以 `"json"` 仍是两者
+     * 里唯一诚实的选择。后果有界且 fail-closed:core 5.17.0 起 park 铸行失败会把 cause 带到 gate、追加
+     * 到 fallback 的 deny 上,这条 args 退回**同步门**由人判(不静默漏批、不挂死)。边界钉在
+     * `wiring-governance-operator.test.ts` 的 #172 组;已上报上游求一个能表达该宽度的词。
+     */
+    fidelity = "json";
     constructor(db, logger) {
         this.db = db;
         this.logger = logger;
@@ -236,8 +276,16 @@ export class SqlCheckpointStore {
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    /** JSON column binding: TiDB stores the string verbatim; PG goes through the LOSSLESS protocol envelope
-     *  (R4-H1 — the operator's review surface must agree with the executed args at the NUL position). */
+    /** JSON column binding. TiDB: plain `JSON.stringify`, stored verbatim. PG: `pgProtocolJsonStringify` —
+     *  ordinary `JSON.stringify` that **refuses** (throws `PgUnstorableError`) when the value carries a code
+     *  point PG cannot hold (NUL / lone surrogate); the `::jsonb` at the call site is just the bind cast, not
+     *  an escaping layer.
+     *
+     *  "LOSSLESS" in R4-H1 means exactly **"never silently lossy"**, not "encodes everything": the contrast is
+     *  with `pgSanitizeText`, the lossy U+FFFD-scarring path used for CONTENT faces. An approval row is not a
+     *  content face — the operator's review surface has to agree with the executed args AT the NUL position, so
+     *  scrubbing the byte and storing the scrubbed row is the unacceptable arm; refusing loudly is the chosen one.
+     *  That refusal is why {@link SqlCheckpointStore.fidelity} carries a documented residual (see it). */
     json(value, label) {
         return dialectProtocolJsonEncoder(this.db.dialect)(value, label);
     }
@@ -300,8 +348,12 @@ export class SqlCheckpointStore {
         // design/80 D-1: surface the reopen-by-reason + OCC fields off the AUTHORITATIVE columns (the blob is the
         // suspend-time snapshot; resolve/reopen mutate only the columns). Core's resume reads these to validate an
         // env_failed re-resume against the persisted winner, and to require the `rev` it observed is still live (OCC).
-        // resolvedOutcome is DERIVED from the stored full outcome (winnerFromOutcome → {boundCallId,decision,
-        // updatedInput?}), so it is preserved across a reopen for free (reopen leaves `outcome` untouched).
+        // resolvedOutcome is DERIVED from the stored full outcome by core's `winnerFromOutcome`, so it is preserved
+        // across a reopen for free (reopen leaves `outcome` untouched). Do NOT read a key list into this line: the
+        // derived shape is core's and it GROWS (`answer` since 5.7.0, `reason` since 5.16.0 — the operator's deny
+        // note IS persisted; an older copy of this comment enumerated only {boundCallId,decision,updatedInput?} and
+        // read as if it weren't). We store the whole outcome blob and round-trip it, so additive keys ride for free
+        // — `ResolvedOutcome` in core's `checkpoint-store.d.ts` is the single owner of that list.
         const outcomeRaw = parseJson(r.outcome);
         if (outcomeRaw)
             cp.resolvedOutcome = winnerFromOutcome(outcomeRaw);
@@ -595,9 +647,14 @@ export class SqlCheckpointStore {
      *    扫描(§8 C-6)。什么算读不出:blob 的 `version` 超出本 build 支持(`get()` 那条前向兼容门在这里
      *    不能 throw,否则一条超前行会让整个 session 的对账永久卡死)、或 blob JSON 坏。
      *
-     * 匹配是两段的:`tool_call_id` **列**是 `put()` 从 `pendingAction.toolCallId` 盖下来的权威投影,命中它
-     * 的行零解析即候选;列为 NULL 的行(无工具动作的 park,或列存在之前的旧行)才回落去解 blob——解得出且
-     * 相等才算候选,解不出就标 `unparseable`。
+     * 匹配是两段的:`tool_call_id` **列**是 `put()` 从 `pendingAction.toolCallId` 盖下来的权威投影,SQL 谓词
+     * 先按它(或 NULL)收窄;列为 NULL 的行(无工具动作的 park,或列存在之前的旧行)靠解 blob 补判——解得出
+     * 且相等才算候选,解不出就标 `unparseable`。
+     * 🔴 **没有「列命中即零解析」的快路径**(原注写过,已作废,别照它优化):函数体对**每一行**无条件解
+     * blob,原因有二 ——(a) 前向兼容门与 blob 可读性门必须门在**所有**命中路径之前(codex F3 + 确认轮:
+     * 列长得对不代表 blob 读得出,放行一条读不出的行去 `bindBatch` 会把 ask 钉成 PARKED + 一张本进程读不出
+     * 的 resume 坐标,而 PARKED 不可回滚);(b) `#168` 之后 blob 顶层的 `sourceTaskId` 是和解三元组的第一
+     * 维,列命中行结构上也必须解 blob 才拿得到它。
      */
     async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
         const { rows } = await this.db.query(this.q("SELECT token, status, created_at, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
@@ -605,11 +662,14 @@ export class SqlCheckpointStore {
             "WHERE scope=$1 AND session_id=$2 AND created_at>=$3 AND (tool_call_id=$4 OR tool_call_id IS NULL) ORDER BY created_at ASC"), [scope, sessionId, sinceMs, toolCallId]);
         const out = [];
         for (const r of rows) {
+            // `sourceTaskId: null` 是**所有 unparseable 臂的共同底**(读不出的行不许带出一个可用于身份比对的
+            // 值);健康臂在下面用 blob 解出来的值覆盖它。
             const base = {
                 token: String(r.token),
                 status: String(r.status),
                 createdAtMs: Number(r.created_at),
                 boundInputHash: r.bound_input_hash == null ? null : String(r.bound_input_hash),
+                sourceTaskId: null,
             };
             // 🔴 前向兼容门必须在**任何**命中路径之前(codex 复审 F3,2026-08-06 真缺陷):版本超前的行是
             // `get()` 明确拒读的行,而 `tool_call_id` 列命中与否跟能不能读懂 blob 毫无关系。若让列的快路径
@@ -652,7 +712,7 @@ export class SqlCheckpointStore {
             // 列在场时以列为准(权威投影);列为 NULL 的旧行回落用 blob 解出来的值。
             const effective = col ?? derived.toolCallId;
             if (effective === toolCallId)
-                out.push({ ...base, boundInputHash: effectiveHash, boundCallId: effective });
+                out.push({ ...base, boundInputHash: effectiveHash, sourceTaskId: derived.sourceTaskId, boundCallId: effective });
             // 解得出、但不是这只 ask 的 callId(或这条 park 本来就没有工具动作)⇒ **确定**不是候选:
             // 既不返回也不标坏行(标坏行会让收敛器把一条明确的「不匹配」当成「不确定」)。
         }

package/dist/plugins/local-checkpoint-store.d.ts

@@ -1,4 +1,4 @@
-import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
 import { type PendingCheckpoint } from "./checkpoint-store-sql.js";
 export interface LocalCheckpointStoreOptions {
     /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
@@ -8,6 +8,25 @@ export interface LocalCheckpointStoreOptions {
     ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
 }
 export declare class LocalCheckpointStore {
+    /**
+     * `CheckpointStore.durability` 声明(#167 欠账,#168 件5)——**如实按内核判**:本类的内核是 core 的
+     * `FileCheckpointStore`(crash-safe ledger + snapshot,自身声明 `"durable"`),本地 scope 注册表也落
+     * 在同一个盘上目录里 ⇒ 进程重启后 park 全部还在、还赎得回,`"durable"` 是诚实读数而不是抬举。
+     *
+     * 它与「session store 的 local 形声明 durable 就拒启」不矛盾:那条判据管的是**声明 vs 介质**,而这里
+     * 的介质就是盘。真正的 process-local 形(`InMemoryCheckpointStore`)由 core 自己声明 `"process-local"`。
+     */
+    readonly durability: StoreDurability;
+    /**
+     * `CheckpointStore.fidelity` 声明(core 5.17.0 [3052] 提货批 #172)——**如实按内核判**,与 durability
+     * 同一条判据:本类的读写内核是 core 的 `FileCheckpointStore`,它自己声明 `"json"`(盘上是 JSON 行),
+     * 包装层只加 scope/session 索引与 ctx 附属文件,不改这条 round-trip 的宽度 ⇒ 抄内核的读数是诚实的。
+     *
+     * ⚠️ 包装类**不继承**被包装者的声明(本类是委派不是子类),所以这一格必须自己写。它与内核那一格
+     * 是否仍然一致由测试盯着(`wiring-governance-operator.test.ts` 的 #172 组直接读内核那一格对表)——
+     * 内核哪天改宽度,包装层的声明会被那条钉当场揪出来,而不是靠人记得同步。
+     */
+    readonly fidelity: StoreFidelity;
     private readonly inner;
     private readonly scopesPath;
     private readonly sessionTokensPath;

package/dist/plugins/local-checkpoint-store.js

@@ -34,6 +34,25 @@ function ctxFileOf(sessionId) {
     return `${sanitizePathComponent(sessionId).slice(0, 48)}-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}.json`;
 }
 export class LocalCheckpointStore {
+    /**
+     * `CheckpointStore.durability` 声明(#167 欠账,#168 件5)——**如实按内核判**:本类的内核是 core 的
+     * `FileCheckpointStore`(crash-safe ledger + snapshot,自身声明 `"durable"`),本地 scope 注册表也落
+     * 在同一个盘上目录里 ⇒ 进程重启后 park 全部还在、还赎得回,`"durable"` 是诚实读数而不是抬举。
+     *
+     * 它与「session store 的 local 形声明 durable 就拒启」不矛盾:那条判据管的是**声明 vs 介质**,而这里
+     * 的介质就是盘。真正的 process-local 形(`InMemoryCheckpointStore`)由 core 自己声明 `"process-local"`。
+     */
+    durability = "durable";
+    /**
+     * `CheckpointStore.fidelity` 声明(core 5.17.0 [3052] 提货批 #172)——**如实按内核判**,与 durability
+     * 同一条判据:本类的读写内核是 core 的 `FileCheckpointStore`,它自己声明 `"json"`(盘上是 JSON 行),
+     * 包装层只加 scope/session 索引与 ctx 附属文件,不改这条 round-trip 的宽度 ⇒ 抄内核的读数是诚实的。
+     *
+     * ⚠️ 包装类**不继承**被包装者的声明(本类是委派不是子类),所以这一格必须自己写。它与内核那一格
+     * 是否仍然一致由测试盯着(`wiring-governance-operator.test.ts` 的 #172 组直接读内核那一格对表)——
+     * 内核哪天改宽度,包装层的声明会被那条钉当场揪出来,而不是靠人记得同步。
+     */
+    fidelity = "json";
     inner;
     scopesPath;
     sessionTokensPath;

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

@@ -38,6 +38,7 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { MailboxLease, MailboxStore } from "@sema-agent/core";
+type MailboxAppendMessage = Parameters<MailboxStore["append"]>[2];
 export declare const MAILBOX_TABLE = "mailboxes";
 export declare const MAILBOX_MSG_TABLE = "mailbox_messages";
 export declare function ensureTiDBMailboxSchema(pool: MySqlPool): Promise<void>;
@@ -46,11 +47,7 @@ export declare class TiDBMailboxStore implements MailboxStore {
     private readonly pool;
     constructor(pool: MySqlPool);
     private tx;
-    append(scope: string, handle: string, msg: {
-        from?: string;
-        content: string;
-        sentAt: number;
-    }): Promise<number>;
+    append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
@@ -66,11 +63,7 @@ export declare class PgMailboxStore implements MailboxStore {
     private tx;
     /** 身份键拒绝式([1439] 协议纪律):scope/handle/owner/from 清洗形变 = 路由/attribution 错位。 */
     private assertIdentity;
-    append(scope: string, handle: string, msg: {
-        from?: string;
-        content: string;
-        sentAt: number;
-    }): Promise<number>;
+    append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
@@ -80,4 +73,5 @@ export declare class PgMailboxStore implements MailboxStore {
         maxAgeMs?: number;
     }): Promise<number>;
 }
+export {};
 //# sourceMappingURL=mailbox-store-sql.d.ts.map

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

@@ -25,12 +25,58 @@ function assertKeyBytes(what, v) {
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
 }
+/** `hopChain` 的 JSON 文本列上界(TiDB `TEXT` = 65535 字节)。core 侧链本就有界
+ *  (`PEER_ADMISSION_DEFAULTS.maxChainLength` = 28,`PEER_HOP_CHAIN_WINDOW` = 32,元素是 peerAxisToken
+ *  短串)⇒ 正常形离这个数几个数量级远;守卫存在的理由是**关掉 MySQL 的静默截断类**(非严格模式下
+ *  超长 TEXT 写入只发 warning),截断后的 JSON 文本读侧 parse 失败 = 整条链静默变缺席,而缺席在
+ *  mailbox 上是有语义的(见下 encodeHopChain 注)。同 assertKeyBytes 精神:写入面 fail-loud。 */
+const HOP_CHAIN_MAX_BYTES = 60_000;
+/**
+ * `hopChain` 存取(core 5.17.0 design/176)。**JSON 文本列**,不是清洗面也不是身份键面:
+ *
+ *  - 为什么不清洗:链元素参与 core 的 `hop_loop` **等值比对**。内容面的 lossy 清洗(pgSanitizeText 的
+ *    U+FFFD 标记)会让两个不同 token 塌成同一个(误报环路)或让一个 token 变形(漏判环路)——两个
+ *    方向都是把准入判决改错,与 `content` 那种「读者读到近似文本仍可用」的容忍面性质不同。
+ *  - 为什么也不需要拒绝:`JSON.stringify` 是 **well-formed**(ES2019)——NUL 转义成 `\u0000`、lone
+ *    surrogate 转义成 `\udXXX`,产物恒是 ASCII 可存字节。于是 PG 的 unstorable 面根本不会被触及,
+ *    两方言都拿到逐字 round-trip,不必像 `from`/`scope`/`handle` 那样走拒绝式。
+ *  - **缺席 ≠ 空数组**:core 明示 mailbox 的 `hopChain` 在场性本身携带语义(「经 sema 准入门录入」vs
+ *    「外部/存量写入」,是整份契约里唯一允许从在场性推断的例外)。所以 NULL 读回 = 不铸键,`[]` 读回
+ *    = 铸一个空数组键,两者绝不互相折叠。
+ */
+function encodeHopChain(hopChain) {
+    if (hopChain === undefined)
+        return null;
+    const text = JSON.stringify(hopChain);
+    if (Buffer.byteLength(text, "utf8") > HOP_CHAIN_MAX_BYTES) {
+        throw new Error(`MailboxStore: hopChain exceeds the ${HOP_CHAIN_MAX_BYTES}-byte column (refusing — a truncated chain would silently read back as ABSENT, which mailbox treats as "not gate-admitted")`);
+    }
+    return text;
+}
+/** 读侧:NULL/缺席 ⇒ undefined(不铸键);坏行(非 JSON / 非字符串数组)⇒ 同样 undefined —— 一条读不
+ *  懂的链只能诚实降级成「没有链」,绝不半解析出一条会被拿去做环路比对的残链。 */
+function decodeHopChain(raw) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(bufToStr(raw));
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed) || parsed.some((x) => typeof x !== "string"))
+        return undefined;
+    return parsed;
+}
 function rowToMessage(r) {
+    const hopChain = decodeHopChain(r.hop_chain);
     return {
         seq: Number(r.seq),
         ...(r.from_id !== null && r.from_id !== undefined ? { from: bufToStr(r.from_id) } : {}),
         content: String(r.content),
         sentAt: Number(r.sent_at_ms),
+        ...(hopChain !== undefined ? { hopChain } : {}),
     };
 }
 export async function ensureTiDBMailboxSchema(pool) {
@@ -53,6 +99,10 @@ export async function ensureTiDBMailboxSchema(pool) {
     from_id VARBINARY(255) NULL,
     content LONGTEXT NOT NULL,
     sent_at_ms BIGINT NOT NULL,
+    -- hop_chain(core 5.17.0 design/176):peer 准入的 hop 链,JSON 文本;NULL = 缺席(**有语义**,
+    -- 见 encodeHopChain 头注:缺席 vs 空数组绝不互折)。TEXT 而非 LONGTEXT——链上界在 core(28 跳,
+    -- 短 token),写入面另有 HOP_CHAIN_MAX_BYTES fail-loud 守卫关掉静默截断类。
+    hop_chain TEXT NULL,
     PRIMARY KEY (scope_key, handle, seq),
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
   ) COLLATE utf8mb4_bin`);
@@ -75,6 +125,7 @@ export async function ensurePgMailboxSchema(q) {
     from_id VARCHAR(255) COLLATE "C",
     content TEXT NOT NULL,
     sent_at_ms BIGINT NOT NULL,
+    hop_chain TEXT, -- core 5.17.0 design/176(TiDB twin 同注:NULL = 缺席且有语义)
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_mbm_sent ON ${MAILBOX_MSG_TABLE} (scope_key, handle, sent_at_ms)`);
@@ -106,6 +157,7 @@ export class TiDBMailboxStore {
         assertIdentityChars("handle", handle);
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
+        const hopChain = encodeHopChain(msg.hopChain); // 事务外先编码:超界 fail-loud 必须在建盒/分配 seq 之前
         // ensure-first 形:先幂等 INSERT IGNORE 建盒(next_seq=1,首条/drop 后重建同臂)再 FOR UPDATE——
         // 「无行 FOR UPDATE + INSERT」的并发死锁/dup 撞车形整个消掉;seq 分配与 append 同事务(定谳 2)。
         return this.tx(async (c) => {
@@ -119,7 +171,7 @@ export class TiDBMailboxStore {
             }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = ? WHERE scope_key = ? AND handle = ?`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms) VALUES (?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain) VALUES (?, ?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt, hopChain]);
             return seq;
         });
     }
@@ -139,7 +191,7 @@ export class TiDBMailboxStore {
             }
             // FOR UPDATE = 当前读:TiDB 悲观事务的普通 SELECT 按 start_ts 快照(task-list twin 同案)——
             // 锁到 box 行后消息集必须读「现在」,否则 drop+重建窗内老消息混进新盒 lease(maxSeq 错位)。
-            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
+            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
                 return null; // 定谳 5:空盒 claim = null(box 行在也 null)
             const maxSeq = Number(msgs[msgs.length - 1].seq);
@@ -241,6 +293,7 @@ export class PgMailboxStore {
         const content = pgSanitizeText(msg.content); // 内容面 lossy(U+FFFD 标记,与 PG 转录 payload 同族)
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
+        const hopChain = encodeHopChain(msg.hopChain); // TiDB 同注:事务外先编码,超界 fail-loud 不留半个盒
         // ensure-first 形(TiDB 同注):幂等建盒再 FOR UPDATE,死锁/dup 撞车形消。
         return this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
@@ -260,7 +313,7 @@ export class PgMailboxStore {
             }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = $1 WHERE scope_key = $2 AND handle = $3`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms) VALUES ($1, $2, $3, $4, $5, $6)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain) VALUES ($1, $2, $3, $4, $5, $6, $7)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt, hopChain]);
             return seq;
         });
     }
@@ -273,7 +326,7 @@ export class PgMailboxStore {
             const box = boxes[0];
             if (box.lease_owner !== null && Number(box.lease_expires_at_ms) > now && String(box.lease_owner) !== owner)
                 return null;
-            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
+            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);

package/dist/question.d.ts

@@ -1,4 +1,4 @@
-import { type AskQuestionRequest, type QuestionAnswer, type AskQuestion } from "@sema-agent/core";
+import { type AskQuestionRequest, type OnQuestionOutcome, type QuestionAnswer, type AskQuestion } from "@sema-agent/core";
 /** 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`. */
@@ -6,10 +6,10 @@ export interface QuestionFrame {
     type: "question" | "question_complete";
     questionId: string;
     /** "question" only: the model's structured questions, secret-redacted. UNTRUSTED-for-display (shell renders; never
-     *  re-feeds a model). Absent on an over-cap payload (the ask then headless-defaults). */
+     *  re-feeds a model). Absent on an over-cap payload (the ask then reports unavailable — no frame is emitted at all). */
     questions?: AskQuestion[];
     /** "question_complete" only: whether the human answered (`answered`) or the ask was released unanswered
-     *  (`unanswered` — ttl/abort → the model got the headless default). Cosmetic dialog-dismiss. */
+     *  (`unanswered` — ttl/abort → core was told nobody was reachable). Cosmetic dialog-dismiss. */
     outcome?: "answered" | "unanswered";
     /** Server-signed emit timestamp (additive, [2805]§五→[2806]). Server-minted side-frame ⇒ no core-stream
      *  `eventId` to carry (absence is honest); this is the frame's own time coordinate. */
@@ -31,12 +31,14 @@ export interface QuestionRunContext {
      *  background leg (emit appends to the durable events tail, readable whenever a client attaches). */
     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`). */
 export interface QuestionThrottle {
-    /** Max concurrent in-flight questions per run leg (parallel tool calls can each ask). Breach ⇒ headless default. */
+    /** Max concurrent in-flight questions per run leg (parallel tool calls can each ask). Breach ⇒ unavailable. */
     maxConcurrentPerRun: number;
-    /** Max total questions one run leg surfaces to the human. Breach ⇒ headless default (flood defense). */
+    /** Max total questions one run leg surfaces to the human. Breach ⇒ unavailable (flood defense). */
     maxTotalPerRun: number;
-    /** An unanswered question auto-releases (headless default) after this (ms) — the human walked away; don't hold core. */
+    /** An unanswered question auto-releases as unavailable after this (ms) — the human walked away; don't hold core. */
     ttlMs: number;
 }
 export declare const DEFAULT_QUESTION_THROTTLE: QuestionThrottle;
@@ -54,7 +56,7 @@ export declare function parseQuestionResponse(body: unknown): {
  * Coordinates AskUserQuestion HITL for the singleton runner. Process-local + same-replica (the pending map is in memory,
  * like ElicitationCoordinator / steerableRuns): a respond that lands on another replica finds nothing → 404. Present
  * (passed into `RunnerDeps.onQuestion` + the respond route) ONLY when `ASK_QUESTION_ENABLED` — absent ⇒ core mounts the
- * AskUserQuestion tool with the headless default (a run never hangs; the model just can't get a live answer).
+ * AskUserQuestion tool with no seam at all (`seam_absent` continuation; the model just can't get a live answer).
  */
 export declare class QuestionCoordinator {
     private readonly als;
@@ -63,12 +65,13 @@ export declare class QuestionCoordinator {
     private readonly throttle;
     constructor(throttle?: QuestionThrottle);
     /** Run `fn` with the per-run question context ambient. On exit, release any still-pending question for this run (a
-     *  live-only question cannot outlive its leg → headless default) and drop the run's counters (no leak). */
+     *  live-only question cannot outlive its leg → unavailable) and drop the run's counters (no leak). */
     runWithContext<T>(ctx: QuestionRunContext, fn: () => Promise<T>): Promise<T>;
-    /** `RunnerDeps.onQuestion`. core calls this when the agent's AskUserQuestion tool fires; the resolved answer is what
-     *  the model sees. Headless default (`NO_HUMAN`) in every case with no live human, so the run never hangs. Arrow
-     *  property so it can be passed as `onQuestion: coordinator.question` with `this` bound. */
-    question: (req: AskQuestionRequest, signal?: AbortSignal) => Promise<QuestionAnswer>;
+    /** `RunnerDeps.onQuestion`. core calls this when the agent's AskUserQuestion tool fires; the resolved outcome is what
+     *  core acts on — a {@link QuestionAnswer} ONLY when a human really answered, otherwise `{kind:"unavailable"}` (core
+     *  then parks on a durable leg / continues with the `declined_unavailable` card on a non-durable one; either way the
+     *  run never hangs). Arrow property so it can be passed as `onQuestion: coordinator.question` with `this` bound. */
+    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. */
@@ -83,9 +86,10 @@ export declare class QuestionCoordinator {
      *  resolve-spec 的 durable question policy 用它在**判决时**分腿:有活流 ⇒ allow(问活人),无 ⇒
      *  ask(durable park)。ALS 让这个判断天然 per-leg,policy 组装期不必预知腿别。
      *  🔴 判据是「投递面此刻可达」而不只是「ALS 在场」(复审 A1):detach 腿断连后 run 仍在本作用域里跑,
-     *  只判 ALS 会把一条谁也收不到的问题判成 allow(挂满 ttl 后以空答喂模型),而 park 才是它该走的腿。
+     *  只判 ALS 会把一条谁也收不到的问题判成 allow——挂满 ttl 后以 unavailable 结算,非 durable 形 core
+     *  就此合成续跑,活人再没机会答;而 park 才是它该走的腿。
      *  谓词缺席 ⇒ 恒可达(后台腿的 durable events tail 语义)。谓词本身抛错按不可达处理:判决面
-     *  fail-closed 到 park(park 可由运维补答,空答不可回收)。 */
+     *  fail-closed 到 park(park 可由运维补答,续跑掉的问题不可回收)。 */
     hasLiveContext(): boolean;
     private countersFor;
 }