@sema-agent/server 7.131.0 → 7.133.0

package/dist/delegated-session-owner.d.ts

@@ -0,0 +1,185 @@
+/**
+ * 🔴 **委派子代会话的属主 —— 一条律;三处写点,各自的来源集;属主 = 判断时见证到的,写只 CAS 子行自己**(S-1770)。
+ *
+ * ## 律
+ * 一只委派子代会话(引擎为委派铸的 placed 会话,或停驻时从私店拷进宿主店的子代会话)的属主**不是它自己的事实**:它是发起它的那棵委派树的
+ * **根会话的属主**。树根是**铸行那一刻存在的那只根行**(id + 住客化身,`session-incarnation.ts`);此后同 id 另起的会话不是这棵树的根。所以写下的属主 =
+ * **判断时见证到的**(读法顺序按写点交来的来源集):
+ *  1. 根会话在本店有行 ⇒ 它的属主(根无主 ⇒ 子代也无主 —— 与根同读数,不是另一种读数);
+ *  2. 根行不在 ⇒ 父会话的行(同上);
+ *  3. 来源集里一只都不在本店(孤行)⇒ 写一只**任何已验身份都不可能等于**的哨兵属主 `_orphan:<子代 id>`(前缀登记在 `security.ts` 的保留主体前缀里,
+ *     鉴权边界拒任何报出它的主体)+ 写落下之后一行 warn `delegated_session_owner_orphaned`。宁可没人能读,也不让谁都能读。
+ * 一只记下的根 / 父是空串(`''`)⇒ 读作没有那一格(与 `session-placement.ts` 的 `placementFromRow` 同一个读法;M23 的扫描句在同一条语句里对连接键套
+ * `NULLIF(…, '')`,与判据同读)。
+ * **写只 CAS 子行自己**:`owner IS NULL ∧ incarnation = 判断时读到的子行化身 ∧ placed`({@link CLAIM_OWNERLESS_PLACED_SQL},两方言各一句)。判断与写之间
+ * 根 / 父被删、被同 id 重建、换住客 —— 写进去的仍是**判断时那棵树**的属主,这正是律要的:不锁根、不读根、不要求「根到写时还是那个根」。之后与任何会话一样
+ * 首写不可变(`register` 的首写律)。判断那一刻的检查照旧在判断里做、不进 CAS:宿主行记下的根是不是这一棵;调用方见证之后根行换没换住客
+ * (停驻挂点,{@link assertRootStillWitnessed})。
+ *
+ * **根先于父**:父的属主按同一条律恒等于根的属主,读根一次就到;而读父会把「父行是升级前写下的无主 placed 行」(滚动升级窗里旧副本建的、
+ * 一次性迁移还没回填的)那一格 NULL 传下去。父只在根行不在时才读。
+ *
+ * ## 无主的子代行
+ * 属主为 NULL 的 placed 行有两种来历:律给的(根无主 —— 一棵无身份调用方的树),或还没定下的(7.132.x 及更早写下的;判断时它读到的来源本身还是一只无主的
+ * 委派子代行)。会话行属主门上的无主放行臂对它**只对 fleet 调用方成立**(出示 service 凭据、不报主体;唯一判据 `security.ts` 的 `ownerlessRowOpen`,
+ * 会话面 / fork / 删除 / 审批豁免 / notify 同读;dev-open 照旧 fleet-wide),具名主体与没有 service 凭据的无身份调用方一律与别人的行同体 404 ——
+ * 所以还没定下的行只是暂时只有 fleet 面读得到,不是谁都能读。它们由一次性迁移 M23(窗内每次起服)或这一行的下一次停驻(停驻挂点的认领)
+ * 定下;两处都不承诺「一次收敛」。
+ * **只有记录委派树的店才认领**:SQL 两店的 placed 行记着委派树(placement 元组);local 店不实现 placement、不记委派树 ⇒ 没有可按的树 ⇒ 不认领
+ * (它的无主子代行在停驻挂点照「属主不是律给的那一只 ⇒ 拒」处置;收口是 local 店的 placement 协议)。不按更松的判据认领。
+ *
+ * ## 三处写点 —— 律一只,**来源集按写点不同**(都调这里,不各写一份判据)
+ *  · **SQL 两店按 placement 建行**(`plugins/tidb-session-store.ts` / `plugins/pg-session-storage.ts` 的 acquire,{@link createPlacedSessionRow}):来源 = placement 上的
+ *    根、父两只 id({@link ownerSourcesOf});读来源 → 判 → 一条 INSERT(属主与 placement 同一笔落库,首写律)。读来源之后来源才变有主(滚动升级窗里别的副本的
+ *    M23 回填了无主的父)⇒ 写下的仍是判断时的读数 —— 按律如此;那一行若因此无主,照上一节处置。
+ *  · **停驻挂点**(`plugins/session-store.ts` 的 `ensureChildSessionDurableWithPromotion`;快路 + 晋升):来源 = **调用方交出的委派树根,只有这一只**,连同
+ *    调用方判断那一刻读到的根行住客({@link DelegationRootWitness};见证值,判断用,不进 CAS):请求腿 = 本请求经鉴权解析的会话,住客 = 受理时那一读
+ *    (`boot/resolve-spec.ts`);`/decide` 的赎回腿 = 行上的 `rootSessionId`,住客 = 赎回腿 claim 前后两读的那一位(`parked-revive-surface.ts`,每一行都交)。
+ *    挂点先读一次根行:它在而住客不是见证的那一位 ⇒ 根被删、同 id 换了住客 ⇒ **拒**(不按新住客晋升 / 认领,{@link assertRootStillWitnessed});它不在 ⇒ 律给哨兵
+ *    (根真没了)。不回落父:core 的挂点 `ensureChildSessionDurable(sessionId)` 只交子代 id,父 id 在这一写点拿不到;两条候选读法都读不到东西 ——
+ *    ① 读 `session_meta(子代).placement_parent_session_id`:晋升的拷贝分支恰恰只在子代**没有** placed 行时才走(有 placed 行 ⇒ 快路),这一列按构造为空;
+ *    ② 登记簿(后台子代行 / core 注册簿):core 接口没有「按子代 sessionId 查行」的读口,SQL 表 `background_agent.session_id` 无索引,加一条只在一处用的私有读腿
+ *       = 多一只读法;`scope` 列还把匿名折成 `"default"`(与真名 `default` 的租户不可分)。行上没有根(没有会话的取用形)⇒ 来源集空 ⇒ 哨兵。
+ *    宿主行的属主经 {@link settleDelegatedOwner} 定下:宿主行记着委派树而不是这一棵 ⇒ 拒(两边属主都是 null 也拒);记着这一棵 ⇒ 按**它记录的** placement(根、父)
+ *    再判一次(与 M23 对同一行同读数 —— 见证只答「是不是这一棵、根住客换没换」,来源集取行上记的),无主 ⇒ 认领(CAS 子行),认领试了没落下 ⇒ 拒;然后比对 ——
+ *    不是律给的那一只 ⇒ 停驻否决(晋升建行前那一道与停驻快路同一只函数、同一句拒因)。
+ *  · **一次性迁移 M23**(`plugins/one-time-migrations.ts`):存量 placed 行,来源 = 根、父(扫描时同一条语句连读两行);回填 = 认领(同一句,绑扫描读到的子行化身)。
+ * local 店不实现 placement(子代住私店、只经停驻挂点进宿主店),没有第一处与第三处,也不认领(上一节)。
+ */
+import type { SessionPlacement } from "@sema-agent/core";
+import { type SessionFace, type SessionFaceReader } from "./session-incarnation.js";
+/** 孤行哨兵属主的前缀(保留主体前缀:`security.ts` 的 `RESERVED_PRINCIPAL_PREFIXES` 登记它,任何身份来源报出带它的主体都在鉴权边界被拒)。 */
+export declare const ORPHAN_SESSION_OWNER_PREFIX = "_orphan:";
+/** 一只推不出属主的子代会话的哨兵属主(每只会话一个值:即便哪天有谁误配出这个串,也只够得着这一只)。 */
+export declare function orphanSessionOwner(sessionId: string): string;
+/** 这只属主是不是孤行哨兵(自己推不出、或继承自一只推不出的祖先 —— 两者都没有任何调用方匹配)。前缀的知识只住在本模块。 */
+export declare function isOrphanSessionOwner(owner: string | null): boolean;
+/** 一只来源行在本店的读数:`undefined` = 本店没有这一行;`null` = 行在、无主;串 = 属主(与 `ownerOf` 的三态同义)。 */
+export type SourceOwnerReading = string | null | undefined;
+/** 律的判决:继承自哪一行(属主可以是 `null` = 来源行无主),或孤行(哨兵属主)。 */
+export type InheritedOwner = {
+    readonly kind: "inherited";
+    readonly owner: string | null;
+    readonly from: string;
+} | {
+    readonly kind: "orphan";
+    readonly owner: string;
+};
+/** placement 上律要读的两格(调用方交的 `SessionPlacement`,或店里落库的那一份元组)。 */
+export type PlacementSources = Pick<SessionPlacement, "rootSessionId" | "parentSessionId">;
+/** placement 上的来源 id,按读法顺序(根在前、父在后;去空、去重 —— 一层子代的根就是父)。 */
+export declare function ownerSourcesOf(placement: PlacementSources): readonly string[];
+/** 律本身(纯函数)。`sources` = 按读法顺序的 `[来源 id, 本店读数]`;第一只**在本店有行**的来源给出属主,一只都没有 ⇒ 孤行。 */
+export declare function inheritedOwnerOf(childId: string, sources: ReadonlyArray<readonly [string, SourceOwnerReading]>): InheritedOwner;
+/**
+ * 判据读到的**委派树**:记下的根(`null` = 没有根 —— 缺或空串)+ 判据那一读里根行的住客(化身;`null` = 那一读里根行不在本店)。
+ * 只在判断里用(停驻挂点:宿主行记下的根是不是这一棵、调用方见证之后根住客换没换);**不进认领句**(律:写只 CAS 子行自己)。
+ */
+export interface DelegationTree {
+    readonly root: string | null;
+    readonly rootIncarnation: string | null;
+}
+/** 律的一次判:判决 + 读的来源 id(warn 行用)+ 判据读到的委派树(判断用)。 */
+export interface JudgedOwner {
+    readonly inherited: InheritedOwner;
+    readonly sources: readonly string[];
+    readonly tree: DelegationTree;
+}
+/**
+ * **唯一的判据**(纯函数;三处写点都调它):按记录的来源(placement 上的根、父)与它们此刻在本店的会话面(属主 + 化身;本店没有的 id 不在表里)判一次 ——
+ * 律给出属主(判断时见证到的),同时交出判据读到的委派树(判断用)。
+ */
+export declare function judgeDelegatedOwner(childId: string, placement: PlacementSources, faces: ReadonlyMap<string, SessionFace>): JudgedOwner;
+/** 一次读回若干来源行的会话面(属主 + 化身;本店没有的 id 不在表里)。 */
+export type SourceFacesReader = (ids: readonly string[]) => Promise<ReadonlyMap<string, SessionFace>>;
+/** 按律读一次来源行、判一次(纯读,不告警 —— 孤行 warn 只在写落下之后,{@link reportWrittenOwner})。读失败照原样上抛(调用方的写随之失败,不猜一个属主)。 */
+export declare function readDelegatedOwner(childId: string, placement: PlacementSources, read: SourceFacesReader): Promise<JudgedOwner>;
+/** 孤行那一行 warn 的去处(logger 的子集)。 */
+export interface OrphanOwnerLog {
+    warn(msg: string, fields?: Record<string, unknown>): void;
+}
+/** 写点的名字(warn 行的 `site` 字段:运维据它知道是哪一笔写下的哨兵)。`promotion` = 停驻挂点(晋升建行,或对宿主无主行的认领)。 */
+export type DelegatedOwnerSite = "placed_create" | "promotion";
+/** 一笔写**已落下**之后调:写下的是孤行哨兵 ⇒ 一行 warn(写失败的那一笔走不到这里,不留下「已写」的话)。继承来的属主(含继承自孤行祖先的哨兵)不告。 */
+export declare function reportWrittenOwner(log: OrphanOwnerLog, site: DelegatedOwnerSite, childId: string, judged: JudgedOwner): void;
+/**
+ * 委派继承律的**认领句**(唯一的写法;停驻挂点对宿主无主行的认领与一次性迁移 M23 的回填**同一只**,都按 {@link claimOwnerlessParams} 绑参;窗随 M23)。
+ * **只 CAS 子行自己**:这一位住客(判断时读到的化身)、仍无主、placed 行(原文 CAS,第二次命中零行)。不读根、不锁根、不连接 —— 判断与写之间根 / 父的变化
+ * 不改变写进去的值(律:属主 = 判断时见证到的,本文件头注)。两方言只差占位符。
+ * MySQL 协议下 mysql2 缺省带 FOUND_ROWS,但条件里有 `owner IS NULL` ⇒ 匹配行数 = 改写行数。
+ */
+export declare const CLAIM_OWNERLESS_PLACED_SQL: Readonly<Record<"tidb" | "pg", string>>;
+/** 认领句的绑参(两方言同序;店与 M23 都经它,不各排一份):`incarnation` = 判断时读到的子行化身。 */
+export declare function claimOwnerlessParams(sessionId: string, incarnation: string, owner: string): readonly [string, string, string];
+/** 店的认领口(SQL 两店 + 缓存包装层同一个签名):这只会话的那一位住客(`incarnation`)仍是无主的 placed 行 ⇒ 写 `owner`,返回是否写成。 */
+export type OwnerlessClaim = (sessionId: string, incarnation: string, owner: string) => Promise<boolean>;
+/** 一只 SQL 店建 placed 行要交的 I/O(两店按各自方言交,都是店的既有读写口;读法与顺序只住在 {@link createPlacedSessionRow})。 */
+export interface PlacedRowWriter {
+    /** 来源行的会话面一次读回。 */
+    readonly readFaces: SourceFacesReader;
+    /** 建行那一条 INSERT(属主与 placement 同一条落库;行已在 ⇒ 一个字节不动,首写律)。 */
+    insert(owner: string | null): Promise<void>;
+    /** 写后读回本行的属主(店的 `ownerOf`:`undefined` = 行不在)—— 只为判「本笔的哨兵落没落下」。 */
+    readOwner(): Promise<string | null | undefined>;
+}
+/**
+ * **SQL 两店建 placed 行的那一只**:读来源 → 判 → INSERT(属主 = 判断时见证到的,与 placement 同一笔落库)。INSERT 是首写律(行已在 ⇒ 不动),
+ * 所以落库的那一行未必是本笔写的(同 id 的另一位建行者先落了)⇒ 读回属主:带着本笔判出的孤行哨兵才告一行 warn;别的 ⇒ 什么都没写下,不告。
+ * 不写后复核:判断之后来源才变有主,写下的仍是判断时的读数(律;那一行若因此无主,由无主放行臂的判据挡住非 fleet 调用方、由 M23 / 下一次停驻定下 —— 本文件头注)。
+ */
+export declare function createPlacedSessionRow(sessionId: string, placement: PlacementSources, io: PlacedRowWriter, log: OrphanOwnerLog): Promise<void>;
+/**
+ * 停驻挂点的**见证**:调用方交出的委派树根 + 调用方判断那一刻读到的根行住客(化身;`null` = 那一读里根行不在)。请求腿 = 鉴权解析的会话与受理时那一读;
+ * 赎回腿 = 行上的根与 claim 前后两读的那一位住客。
+ */
+export interface DelegationRootWitness {
+    readonly sessionId: string;
+    readonly incarnation: string | null;
+}
+/**
+ * 「根行的化身已换 ⇒ 拒」在停驻挂点的那一道(挂点的见证是更早的一读,不是这一读):此刻根行在、而住客不是见证的那一位(见证那一读里不在,或是另一位)⇒ 抛。
+ * 根行此刻不在 ⇒ 不抛(根真没了 ⇒ 律给哨兵,不是「换了住客」)。这是**判断**的一部分;判断之后、写之前根的变化不改变写进去的值(律:属主 = 判断时见证到的)。
+ */
+export declare function assertRootStillWitnessed(sessionId: string, witness: DelegationRootWitness | undefined, judged: JudgedOwner): void;
+/** 记录委派树的宿主店多交的两只口(SQL 两店与缓存包装层;local 店两只都没有 ⇒ 没有可按的树 ⇒ 不认领)。 */
+export interface DelegationTreeStore {
+    /** 本行落库的 placement 元组(`undefined` = 本行不是 placed 行 ⇒ 不记委派树)。 */
+    readonly placementOf: (sessionId: string) => Promise<PlacementSources | undefined>;
+    readonly claimOwnerless: OwnerlessClaim;
+}
+/** 停驻挂点要的宿主店口(属主读 / 属主 + 化身一次读;记录委派树的店另有 {@link DelegationTreeStore})。 */
+export interface DelegatedOwnerHost {
+    readonly ownerOf: (sessionId: string) => Promise<string | null | undefined>;
+    readonly sessionFaceOf: SessionFaceReader;
+    /** 缺席 = 这只店不记委派树(不实现 placement)。 */
+    readonly trees: DelegationTreeStore | undefined;
+}
+/**
+ * 「这只宿主店能不能承载委派子代的属主」—— 只判这一处(停驻快路与晋升建行读同一只):`ownerOf` + 住客脸都在 ⇒ 绑好的 {@link DelegatedOwnerHost};缺任一只 ⇒ `undefined`
+ * (调用方响亮拒:读不回属主的宿主店上,停驻出来的就是一只谁都能读的转录)。记录委派树的两只口(`placementOf` + `claimOwnerless`)**同在或同缺**:同在 ⇒ `trees`;
+ * 同缺 ⇒ 不记委派树;只有一只 ⇒ `undefined`(记着树却认领不了,或认领却读不回树 —— 半只店不猜)。住客脸的「能不能」沿用 `sessionFaceReadOf` 的同一处判法。
+ */
+export declare function delegatedOwnerHostOf(store: {
+    readonly ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
+    readonly placementOf?: (sessionId: string) => Promise<PlacementSources | undefined>;
+    readonly claimOwnerless?: OwnerlessClaim;
+}): DelegatedOwnerHost | undefined;
+/** {@link settleDelegatedOwner} 的结果:这一笔是否写下了属主(认领成了);`judged` = 宿主行记着委派树时按**它记录的树**的那一次判(缺席 = 行不记委派树,按调用方的判)。 */
+export interface SettledOwner {
+    readonly claimed: boolean;
+    readonly judged: JudgedOwner | undefined;
+}
+/**
+ * 宿主店里这只会话的行属主**按律定下来**(停驻快路与晋升建行前**同一只函数、同一句拒因**;拒句不带任何一方的属主值 —— 它会进停驻否决的错误面)。
+ * `owner` / `tree` = 调用方按见证的根判出的属主与委派树(晋升建行写下的就是它)。
+ *  1. 宿主行**记着委派树**(SQL 店的 placed 行):记下的根 ≠ `tree.root` ⇒ 抛(不以属主是否 null 为前提:那是另一棵树的行);是这一棵 ⇒ **按它记录的 placement(根、父)
+ *     再判一次**(唯一判据 {@link judgeDelegatedOwner} —— 与 M23 / 建行复核对这一行同读数:根不在取父),调用方那一读之后根住客变了 ⇒ 抛({@link assertRootStillWitnessed},
+ *     调用方的读数当见证);行无主而律给出属主 ⇒ 认领(CAS 刚读到的那一位住客;写进去的是这一次判的读数)—— **试了没落下 ⇒ 抛**(这一行在判断之后被写过 /
+ *     删过 / 换了住客,不由事后的属主比对放行);
+ *  2. 不记委派树的行(local 店的行、SQL 店的普通行)不认领、不再判;
+ *  3. 比对 —— 此刻的属主不是律给的那一只(记着委派树 ⇒ 按记录的树判的那一只;否则 = `owner`)⇒ 抛。
+ */
+export declare function settleDelegatedOwner(host: DelegatedOwnerHost, sessionId: string, owner: string | null, tree: DelegationTree): Promise<SettledOwner>;
+/** 按 id 逐只读会话面的店(`sessionFaceOf`)→ {@link SourceFacesReader}。 */
+export declare function sourceFacesVia(sessionFaceOf: SessionFaceReader): SourceFacesReader;
+//# sourceMappingURL=delegated-session-owner.d.ts.map

package/dist/delegated-session-owner.js

@@ -0,0 +1,119 @@
+import { sessionFaceReadOf } from "./session-incarnation.js";
+export const ORPHAN_SESSION_OWNER_PREFIX = "_orphan:";
+export function orphanSessionOwner(sessionId) {
+    return `${ORPHAN_SESSION_OWNER_PREFIX}${sessionId}`;
+}
+export function isOrphanSessionOwner(owner) {
+    return owner !== null && owner.startsWith(ORPHAN_SESSION_OWNER_PREFIX);
+}
+function sourceIdOf(id) {
+    return id === undefined || id === "" ? undefined : id;
+}
+export function ownerSourcesOf(placement) {
+    const out = [];
+    for (const id of [sourceIdOf(placement.rootSessionId), sourceIdOf(placement.parentSessionId)]) {
+        if (id !== undefined && !out.includes(id))
+            out.push(id);
+    }
+    return out;
+}
+export function inheritedOwnerOf(childId, sources) {
+    for (const [id, reading] of sources) {
+        if (reading !== undefined)
+            return { kind: "inherited", owner: reading, from: id };
+    }
+    return { kind: "orphan", owner: orphanSessionOwner(childId) };
+}
+export function judgeDelegatedOwner(childId, placement, faces) {
+    const sources = ownerSourcesOf(placement);
+    const inherited = inheritedOwnerOf(childId, sources.map((id) => [id, faces.get(id)?.owner]));
+    const root = sourceIdOf(placement.rootSessionId) ?? null;
+    return { inherited, sources, tree: { root, rootIncarnation: root === null ? null : (faces.get(root)?.incarnation ?? null) } };
+}
+export async function readDelegatedOwner(childId, placement, read) {
+    const ids = ownerSourcesOf(placement);
+    return judgeDelegatedOwner(childId, placement, ids.length === 0 ? new Map() : await read(ids));
+}
+export function reportWrittenOwner(log, site, childId, judged) {
+    if (judged.inherited.kind !== "orphan")
+        return;
+    log.warn("delegated_session_owner_orphaned", {
+        sessionId: childId,
+        site,
+        sources: judged.sources,
+        owner: judged.inherited.owner,
+        note: "a delegated session's owner could not be derived: none of the sessions it was delegated from has a row in this session store (none was named, or they are gone), " +
+            "so the session was written with an owner no caller can match — only fleet-wide and operator faces reach it. If someone should read it, set its owner in the session store by hand",
+    });
+}
+export const CLAIM_OWNERLESS_PLACED_SQL = {
+    tidb: "UPDATE session_meta SET owner = ? WHERE session_id = ? AND incarnation = ? AND owner IS NULL AND placement_kind IS NOT NULL",
+    pg: "UPDATE session_meta SET owner = $1 WHERE session_id = $2 AND incarnation = $3 AND owner IS NULL AND placement_kind IS NOT NULL",
+};
+export function claimOwnerlessParams(sessionId, incarnation, owner) {
+    return [owner, sessionId, incarnation];
+}
+export async function createPlacedSessionRow(sessionId, placement, io, log) {
+    const judged = await readDelegatedOwner(sessionId, placement, io.readFaces);
+    await io.insert(judged.inherited.owner);
+    if (judged.inherited.kind === "orphan" && (await io.readOwner()) === judged.inherited.owner)
+        reportWrittenOwner(log, "placed_create", sessionId, judged);
+}
+export function assertRootStillWitnessed(sessionId, witness, judged) {
+    if (witness === undefined || judged.tree.rootIncarnation === null || judged.tree.rootIncarnation === witness.incarnation)
+        return;
+    throw new Error(`session "${sessionId}" cannot be parked as this delegated session: its delegation tree's root session was deleted and its id registered again since the delegation was judged, ` +
+        "so the root's current owner is not the owner of this delegation tree");
+}
+export function delegatedOwnerHostOf(store) {
+    const ownerOf = store.ownerOf;
+    const sessionFaceOf = sessionFaceReadOf(store);
+    const placementOf = store.placementOf;
+    const claimOwnerless = store.claimOwnerless;
+    if (typeof ownerOf !== "function" || sessionFaceOf === undefined)
+        return undefined;
+    if ((typeof placementOf === "function") !== (typeof claimOwnerless === "function"))
+        return undefined;
+    const trees = typeof placementOf === "function" && typeof claimOwnerless === "function"
+        ? { placementOf: (id) => placementOf.call(store, id), claimOwnerless: (id, incarnation, owner) => claimOwnerless.call(store, id, incarnation, owner) }
+        : undefined;
+    return { ownerOf: (id) => ownerOf.call(store, id), sessionFaceOf, trees };
+}
+export async function settleDelegatedOwner(host, sessionId, owner, tree) {
+    const refuse = () => new Error(`session "${sessionId}" cannot be parked as this delegated session: the host session store holds a session with this id that is not this delegation tree's ` +
+        "(a different owner, or a different recorded delegation root), and the transcript is neither copied into it nor attested by it");
+    const face = await host.sessionFaceOf(sessionId);
+    const trees = host.trees;
+    const recorded = face === undefined || trees === undefined ? undefined : await trees.placementOf(sessionId);
+    let expected = owner;
+    let judged;
+    let claimed = false;
+    if (face !== undefined && trees !== undefined && recorded !== undefined) {
+        if ((sourceIdOf(recorded.rootSessionId) ?? null) !== tree.root)
+            throw refuse();
+        judged = await readDelegatedOwner(sessionId, recorded, sourceFacesVia(host.sessionFaceOf));
+        if (tree.root !== null)
+            assertRootStillWitnessed(sessionId, { sessionId: tree.root, incarnation: tree.rootIncarnation }, judged);
+        expected = judged.inherited.owner;
+        if (face.owner === null && expected !== null) {
+            claimed = await trees.claimOwnerless(sessionId, face.incarnation, expected);
+            if (!claimed)
+                throw refuse();
+        }
+    }
+    if ((await host.ownerOf(sessionId)) !== expected)
+        throw refuse();
+    return { claimed, judged };
+}
+export function sourceFacesVia(sessionFaceOf) {
+    return async (ids) => {
+        const out = new Map();
+        for (const id of ids) {
+            const face = await sessionFaceOf(id);
+            if (face !== undefined)
+                out.set(id, face);
+        }
+        return out;
+    };
+}
+//# sourceMappingURL=delegated-session-owner.js.map

package/dist/device-protocol.d.ts

@@ -7,9 +7,11 @@
  *
  * 为什么是精选而不是把 `device-ws-protocol.ts` 整只暴露:那个模块里还有**服务端**自己的半场(帧解析与准入、
  * 验签、各种铸 id)。把它们变成公开面,等于替实现细节背上 semver。这里只再导出 executor **会用到**的:
- * 闭集常量、两向帧型、以及构造握手签名字节所需的两只纯函数。要加名字 = 改这只文件 + 同批改
+ * 闭集常量、两向帧型、构造握手签名字节所需的两只纯函数,以及两份「随协议修订号走」的事实:结局码按修订号分行的增量表
+ * (`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` + 取集函数 `deviceOutcomeErrorCodesAt`:executor 按自己声明的修订号裁剪会发的词)与
+ * helloAck 数值位的界表(`DEVICE_HELLO_ACK_BOUNDS` + 判据 `deviceHelloAckNumberFlaw`:executor 读到越界值 ⇒ 协议违例)。要加名字 = 改这只文件 + 同批改
  * `test/device-protocol-subpath.test.ts` 的闭集(新增公开面必须是一次有意的动作)。
  */
-export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, buildHelloSignaturePayload, decodeUlid16, } from "./device-ws-protocol.js";
-export type { DeviceFrameType, DeviceServerFrameType, DeviceHelloRejectCode, DeviceByeReason, DeviceGoodbyeReason, DeviceChunkKind, DeviceCancelState, DeviceInstructionKind, DeviceOutcomeErrorCode, WireFileInfo, WireWriteExpectation, DeviceInstructionOutcome, DeviceInstructionArgsByKind, DeviceChallengeFrame, DeviceHelloAckFrame, DeviceHelloRejectFrame, DeviceInstructionFrame, DevicePayloadFrame, DeviceServerFrame, DeviceHelloFrame, DeviceFrame, DeviceResultFrame, DeviceChunkFrame, DeviceGoodbyeFrame, DeviceHeartbeatFrame, } from "./device-ws-protocol.js";
+export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
+export type { DeviceFrameType, DeviceServerFrameType, DeviceHelloRejectCode, DeviceByeReason, DeviceGoodbyeReason, DeviceChunkKind, DeviceCancelState, DeviceInstructionKind, DeviceOutcomeErrorCode, DeviceProtocolRevision, DeviceHelloAckNumericField, WireFileInfo, WireWriteExpectation, DeviceInstructionOutcome, DeviceInstructionArgsByKind, DeviceChallengeFrame, DeviceHelloAckFrame, DeviceHelloRejectFrame, DeviceInstructionFrame, DevicePayloadFrame, DeviceServerFrame, DeviceHelloFrame, DeviceFrame, DeviceResultFrame, DeviceChunkFrame, DeviceGoodbyeFrame, DeviceHeartbeatFrame, } from "./device-ws-protocol.js";
 //# sourceMappingURL=device-protocol.d.ts.map

package/dist/device-protocol.js

@@ -1,2 +1,2 @@
-export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, buildHelloSignaturePayload, decodeUlid16, } from "./device-ws-protocol.js";
+export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
 //# sourceMappingURL=device-protocol.js.map

package/dist/device-ws-hub.js

@@ -2,7 +2,8 @@ import http from "node:http";
 import { createHash } from "node:crypto";
 import { WebSocketServer } from "ws";
 import { DEVICE_DRAINING_CODE, DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, assertDeviceIdShape, } from "./device-store.js";
-import { DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKind, buildHelloSignaturePayload, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
+import { MAX_TIMER_DELAY_MS } from "./config-types.js";
+import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKind, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
 const OUTCOME_UNKNOWN_SENTENCE = "outcome unknown — the command may have already executed on the device; verify its effect before re-running";
 const SETTLED_MEMO_MAX = 512;
 const DRAIN_RETRY_AFTER_SEC = 15;
@@ -45,6 +46,23 @@ const ALLOWED_SUCCESS_OUTCOME_KINDS = {
     createTempDir: ["write"],
     createTempFile: ["write"],
 };
+const HELLO_ACK_FIELD_SOURCES = {
+    heartbeatIntervalMs: "option heartbeatIntervalMs",
+    maxInflight: "option maxInflightPerDevice (env DEVICE_MAX_INFLIGHT_PER_DEVICE)",
+    reconnectGraceMs: "option reconnectGraceMs (env DEVICE_RECONNECT_GRACE_MS)",
+    cancelGraceMs: "option cancelGraceMs",
+    chunkGapTimeoutMs: "option chunkGapTimeoutMs",
+    executionCeilingGraceMs: "option execGraceMs (sent as helloAck.executionCeilingGraceMs)",
+};
+function assertHelloAckNumbersInBounds(values) {
+    for (const field of Object.keys(DEVICE_HELLO_ACK_BOUNDS)) {
+        const flaw = deviceHelloAckNumberFlaw(field, values[field]);
+        if (flaw !== null) {
+            throw new Error(`device lane: ${HELLO_ACK_FIELD_SOURCES[field]}=${String(values[field])} ${flaw} — it is sent to every executor verbatim in helloAck ` +
+                `(docs/DEVICE-EXECUTOR-PROTOCOL.md §1.5), so an out-of-range value is refused at startup instead of being clamped or replaced by a default`);
+        }
+    }
+}
 export function createDeviceWsHub(options) {
     const { store, enrollment, replicaId, logger, metrics } = options;
     const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15_000;
@@ -57,6 +75,7 @@ export function createDeviceWsHub(options) {
     const cancelGraceMs = options.cancelGraceMs ?? 10_000;
     const reconnectGraceMs = options.reconnectGraceMs ?? 120_000;
     const chunkGapTimeoutMs = options.chunkGapTimeoutMs ?? 30_000;
+    assertHelloAckNumbersInBounds({ heartbeatIntervalMs, maxInflight: maxInflightPerDevice, reconnectGraceMs, cancelGraceMs, chunkGapTimeoutMs, executionCeilingGraceMs: execGraceMs });
     const supersede = options.supersede ?? "stale_only";
     const chunkBufferMaxEntries = options.chunkBufferMaxEntries ?? 64;
     const chunkBufferMaxBytes = options.chunkBufferMaxBytes ?? 2 * 1024 * 1024;
@@ -960,7 +979,7 @@ export function createDeviceWsHub(options) {
         p.ceilingTimer = setTimeout(() => {
             metrics?.inc("device_outcome_unknown_total", { cause: "exec_ceiling" });
             settleUnknown(p, `the device did not report a result within timeoutMs+grace (${input.timeoutMs}+${execGraceMs}ms)`);
-        }, input.timeoutMs + execGraceMs);
+        }, Math.min(input.timeoutMs + execGraceMs, MAX_TIMER_DELAY_MS));
         let onAbort;
         if (input.signal) {
             if (input.signal.aborted)

package/dist/device-ws-protocol.d.ts

@@ -1,9 +1,16 @@
 import type { ExecutionErrorCode, FileErrorCode } from "@sema-agent/core";
 /** 唯一的 upgrade 路径(§5.1:`GET /v1/device/ws`)。 */
 export declare const DEVICE_WS_PATH = "/v1/device/ws";
-/** 本 server 铸/认的协议版本。加帧/加字段 = additive 不升版;改语义 = 升版(§5.6)。 */
-export declare const DEVICE_PROTOCOL_VERSION = 1;
-/** 低于此版本 ⇒ `helloReject: protocol_version_unsupported`(响亮拒,不静默降级,[ref])。 */
+/**
+ * 本 server 铸/认的协议**修订号**(wire 上的 `protocolVersion`)。
+ *
+ * 规则(§5.6):加帧 / 加字段 = additive 不升号;改语义 = 升号;**executor → server 方向的闭集加词也升号** —— 修订号是 executor 在发 hello 之前
+ * 唯一能读到的「这台 server 受理什么」的事实(challenge 帧带它),所以 server 受理的词集必须是修订号的函数
+ * ({@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION},协议文档同名表),不另发第二份列表。闭集变了而修订号没变 = 同一个修订号两种受理集
+ * (7.132.0 给结局码加 `liveness_no_output` 时没抬号,本版补到 2)。类型锁:抬了号而表没有这一行 ⇒ 编译红。
+ */
+export declare const DEVICE_PROTOCOL_VERSION: DeviceProtocolRevision;
+/** 低于此版本 ⇒ `helloReject: protocol_version_unsupported`(响亮拒,不静默降级,[ref])。兼容窗 = [MIN, 当前]。 */
 export declare const DEVICE_MIN_PROTOCOL_VERSION = 1;
 /** 签名的 domain tag —— 换域即换 tag,防止别处的 Ed25519 签名被拿来当握手用。 */
 export declare const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
@@ -60,10 +67,24 @@ export type DeviceInstructionKind = (typeof DEVICE_INSTRUCTION_KINDS)[number];
 export declare function asInstructionKind(v: string): DeviceInstructionKind | null;
 /**
  * 结果帧的错误码闭集 = core 的 `FileErrorCode ∪ ExecutionErrorCode`(§5.1「error code 全闭集」:
- * 未知值映射为协议错误而非透传 string)。`satisfies` 保证这里没有 core 不认识的词。
+ * 未知值映射为协议错误而非透传 string)—— **按修订号分行的增量表,是这个闭集唯一的一份来源**:
+ * 修订号 N 的词集 = 行 ≤ N 的并({@link deviceOutcomeErrorCodesAt}),{@link DEVICE_OUTCOME_ERROR_CODES} 是当前修订号的那一份(派生)。
+ * 已发布修订号的行不许改(测试冻结了集合哈希);加词 = 抬 {@link DEVICE_PROTOCOL_VERSION} + 加一行。`satisfies` 保证这里没有 core 不认识的词。
  */
-export declare const DEVICE_OUTCOME_ERROR_CODES: readonly ["aborted", "already_exists", "auth_failed", "callback_error", "invalid", "is_directory", "not_directory", "not_found", "not_supported", "outcome_unknown", "permission_denied", "precondition_failed", "shell_unavailable", "spawn_error", "suspended", "target_unavailable", "timeout", "transport_lost", "unknown"];
-export type DeviceOutcomeErrorCode = (typeof DEVICE_OUTCOME_ERROR_CODES)[number];
+export declare const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION: {
+    readonly 1: readonly ["aborted", "already_exists", "auth_failed", "callback_error", "invalid", "is_directory", "not_directory", "not_found", "not_supported", "outcome_unknown", "permission_denied", "precondition_failed", "shell_unavailable", "spawn_error", "suspended", "target_unavailable", "timeout", "transport_lost", "unknown"];
+    readonly 2: readonly ["liveness_no_output"];
+};
+/** 本包认得的协议修订号(= 增量表的行键)。 */
+export type DeviceProtocolRevision = keyof typeof DEVICE_OUTCOME_ERROR_CODES_BY_REVISION;
+export type DeviceOutcomeErrorCode = (typeof DEVICE_OUTCOME_ERROR_CODES_BY_REVISION)[DeviceProtocolRevision][number];
+/**
+ * 协议修订号 `revision` 受理的结局码全集(行 ≤ revision 的并,字典序)。executor 按**自己声明的修订号**取这一份来裁剪自己会发的词
+ * (声明哪个修订号见协议文档 §1.2)。不是本包认得的修订号 ⇒ 抛 `RangeError`(不静默给空集或全集)。
+ */
+export declare function deviceOutcomeErrorCodesAt(revision: number): readonly DeviceOutcomeErrorCode[];
+/** 当前修订号受理的结局码全集(派生自增量表;server 解析 `result` 帧时判的就是它)。 */
+export declare const DEVICE_OUTCOME_ERROR_CODES: readonly DeviceOutcomeErrorCode[];
 /**
  * **编译期**对账的另一半:core 往 `FileErrorCode`/`ExecutionErrorCode` 加一个词而本表没跟 ⇒ `Exclude`
  * 不再是 `never` ⇒ `return v` 编译红。`satisfies` 只挡「本表多写了 core 不认的词」,这条挡「本表漏了
@@ -229,6 +250,7 @@ export type DeviceChallengeFrame = {
 export type DeviceHelloAckFrame = {
     t: "helloAck";
     ok: true;
+    /** 六个数值位(本位与 `maxInflight` 与下面四个宽限位)的合法域见 {@link DEVICE_HELLO_ACK_BOUNDS};server 起服校验,wire 上恒在界。 */
     heartbeatIntervalMs: number;
     maxInflight: number;
     /** ⚠️ canonical 十进制**字符串**(F18:SQL BIGINT 超 2^53,wire 不声明装不下 SQL 类型的字段)。 */
@@ -256,6 +278,48 @@ export type DeviceHelloRejectFrame = {
     code: DeviceHelloRejectCode;
     minProtocolVersion?: number;
 };
+/**
+ * helloAck 六个数值位的**合法域**(闭区间、整数)—— 一处成文:汇聚端创建时按它校验(越界 ⇒ 响亮拒启,不夹取、不换成缺省),
+ * 运维旋钮(`DEVICE_RECONNECT_GRACE_MS` / `DEVICE_MAX_INFLIGHT_PER_DEVICE`)的解析器与配置目录行读它,协议文档 §1.5 的 Form 栏由它派生(机器门逐行对账)。
+ * 所以 **wire 上恒在界**:executor 读到越界值 ⇒ 当协议违例关连接(与 `bad_shape` 同形),**不**读成缺省。
+ *
+ *  · ms 位下界 `0` = 该计时器不留宽限(立即到点)—— 真含义,放行;`heartbeatIntervalMs` 下界 `1`:`0` 的心跳周期无法执行(忙等),
+ *    且汇聚端据它判 STALE(`0 × misses` ⇒ 一连上就失联);
+ *  · ms 位上界 = {@link MAX_TIMER_DELAY_MS}(汇聚端自己拿这些值武装 `setTimeout`,更大的值被折成 1 ms —— 宽限被静默抹掉);
+ *  · `maxInflight` 下界 `1`(`0` ⇒ 每次派发都 `device.busy`),无上界(安全整数内)。
+ */
+export declare const DEVICE_HELLO_ACK_BOUNDS: {
+    readonly heartbeatIntervalMs: {
+        readonly min: 1;
+        readonly max: 2147483647;
+    };
+    readonly maxInflight: {
+        readonly min: 1;
+        readonly max: number;
+    };
+    readonly reconnectGraceMs: {
+        readonly min: 0;
+        readonly max: 2147483647;
+    };
+    readonly cancelGraceMs: {
+        readonly min: 0;
+        readonly max: 2147483647;
+    };
+    readonly chunkGapTimeoutMs: {
+        readonly min: 0;
+        readonly max: 2147483647;
+    };
+    readonly executionCeilingGraceMs: {
+        readonly min: 0;
+        readonly max: 2147483647;
+    };
+};
+export type DeviceHelloAckNumericField = keyof typeof DEVICE_HELLO_ACK_BOUNDS;
+/**
+ * helloAck 某数值位的值是否在界:在界 ⇒ `null`;越界(含非数 / NaN / 小数)⇒ 一句话(`must be an integer in [0, 2147483647]`)。
+ * 汇聚端创建时用它拒启;executor 收到 helloAck 后用它判(越界 ⇒ 协议违例)。值不是数时同样越界(`unknown` 入参:直接喂 `JSON.parse` 的字段)。
+ */
+export declare function deviceHelloAckNumberFlaw(field: DeviceHelloAckNumericField, value: unknown): string | null;
 export type DeviceInstructionFrame = {
     [K in DeviceInstructionKind]: {
         t: "instruction";

package/dist/device-ws-protocol.js

@@ -1,6 +1,7 @@
 import { createPublicKey, randomBytes, randomInt, verify as edVerify } from "node:crypto";
+import { MAX_TIMER_DELAY_MS, inWholeNumberBounds, wholeNumberBoundsRule } from "./config-types.js";
 export const DEVICE_WS_PATH = "/v1/device/ws";
-export const DEVICE_PROTOCOL_VERSION = 1;
+export const DEVICE_PROTOCOL_VERSION = 2;
 export const DEVICE_MIN_PROTOCOL_VERSION = 1;
 export const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
 export const DEVICE_WS_LIMITS = {
@@ -42,27 +43,42 @@ const INSTRUCTION_KIND_SET = new Set(DEVICE_INSTRUCTION_KINDS);
 export function asInstructionKind(v) {
     return INSTRUCTION_KIND_SET.has(v) ? v : null;
 }
-export const DEVICE_OUTCOME_ERROR_CODES = [
-    "aborted",
-    "already_exists",
-    "auth_failed",
-    "callback_error",
-    "invalid",
-    "is_directory",
-    "not_directory",
-    "not_found",
-    "not_supported",
-    "outcome_unknown",
-    "permission_denied",
-    "precondition_failed",
-    "shell_unavailable",
-    "spawn_error",
-    "suspended",
-    "target_unavailable",
-    "timeout",
-    "transport_lost",
-    "unknown",
-];
+export const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION = {
+    1: [
+        "aborted",
+        "already_exists",
+        "auth_failed",
+        "callback_error",
+        "invalid",
+        "is_directory",
+        "not_directory",
+        "not_found",
+        "not_supported",
+        "outcome_unknown",
+        "permission_denied",
+        "precondition_failed",
+        "shell_unavailable",
+        "spawn_error",
+        "suspended",
+        "target_unavailable",
+        "timeout",
+        "transport_lost",
+        "unknown",
+    ],
+    2: ["liveness_no_output"],
+};
+export function deviceOutcomeErrorCodesAt(revision) {
+    if (!Number.isInteger(revision) || revision < 1 || revision > DEVICE_PROTOCOL_VERSION) {
+        throw new RangeError(`device-ws: no outcome-code set for protocol revision ${String(revision)} (this package knows revisions 1..${DEVICE_PROTOCOL_VERSION})`);
+    }
+    const out = [];
+    for (const [rev, codes] of Object.entries(DEVICE_OUTCOME_ERROR_CODES_BY_REVISION)) {
+        if (Number(rev) <= revision)
+            out.push(...codes);
+    }
+    return out.sort();
+}
+export const DEVICE_OUTCOME_ERROR_CODES = deviceOutcomeErrorCodesAt(DEVICE_PROTOCOL_VERSION);
 const OUTCOME_ERROR_CODE_SET = new Set(DEVICE_OUTCOME_ERROR_CODES);
 export function assertCoreOutcomeErrorCodesAreCovered(v) {
     return v;
@@ -70,6 +86,18 @@ export function assertCoreOutcomeErrorCodesAreCovered(v) {
 export const DEVICE_FRAME_REJECT_REASONS = ["frame_too_large", "not_json", "not_object", "unknown_type", "bad_shape"];
 export const DEVICE_FRAME_GATE_REJECT_REASONS = ["pre_hello", "generation_mismatch", "unknown_instruction", "instruction_not_committed", "device_mismatch"];
 export const DEVICE_FRAME_AUDIT_REASONS = [...DEVICE_FRAME_REJECT_REASONS, ...DEVICE_FRAME_GATE_REJECT_REASONS];
+export const DEVICE_HELLO_ACK_BOUNDS = {
+    heartbeatIntervalMs: { min: 1, max: MAX_TIMER_DELAY_MS },
+    maxInflight: { min: 1, max: Number.MAX_SAFE_INTEGER },
+    reconnectGraceMs: { min: 0, max: MAX_TIMER_DELAY_MS },
+    cancelGraceMs: { min: 0, max: MAX_TIMER_DELAY_MS },
+    chunkGapTimeoutMs: { min: 0, max: MAX_TIMER_DELAY_MS },
+    executionCeilingGraceMs: { min: 0, max: MAX_TIMER_DELAY_MS },
+};
+export function deviceHelloAckNumberFlaw(field, value) {
+    const bounds = DEVICE_HELLO_ACK_BOUNDS[field];
+    return inWholeNumberBounds(bounds, value) ? null : `must be ${wholeNumberBoundsRule(bounds)}`;
+}
 function reject(reason, detail) {
     return { ok: false, reason, detail };
 }

package/dist/elicitation.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7, delimitUntrusted } from "@sema-agent/core";
 import { redactSecrets, redactDeep } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { refusalBody } from "./http/refusal-body.js";
 const MAX_ELICIT_MESSAGE_CHARS = 4096;
 const MAX_ELICIT_SCHEMA_BYTES = 8192;
 export const DEFAULT_ELICITATION_THROTTLE = {
@@ -145,10 +146,10 @@ export class ElicitationCoordinator {
     respond(id, principal, body) {
         const parsed = parseElicitationResponse(body);
         if (!parsed.ok)
-            return { status: 400, body: { error: parsed.error, errorCode: "request.body_shape" } };
+            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)) {
-            return { status: 404, body: { error: "no pending elicitation for this id (answered, expired, or not on this replica)", errorCode: "elicitation.not_pending" } };
+            return { status: 404, body: refusalBody({ errorCode: "elicitation.not_pending", message: "no pending elicitation for this id (answered, expired, or not on this replica)" }) };
         }
         entry.settle(parsed.value);
         return { status: 200, body: { elicitationId: id, delivery: "applied", action: parsed.value.action } };