@sema-agent/server 7.146.0 → 7.148.0

package/dist/runs.d.ts

@@ -94,7 +94,7 @@ export declare function taskHandleStop(registry: typeof defaultTaskRegistry, han
  * 已 fire 的信号永不回调,那样一次真实的人为断连会被吞成「无归因」(子代 settle 时记成 system)。
  * 语义上这两种时序是同一件事:本请求赢下了这条 session,而这条 session 的连接是被人断掉的。
  */
-export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, taskId: string, principal: string | null | undefined): void;
+export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, taskId: string, subject: string | null | undefined): void;
 export declare function resumeAtHttpStatus(result: {
     terminal: TerminalCause;
 }): number | undefined;
@@ -114,7 +114,7 @@ export declare function resumeAtHttpStatus(result: {
 export declare function syncRefusalHttpStatus(result: Pick<TaskResult, "terminal" | "stats">): number | undefined;
 /**
  * 同步腿零工作拒体的机读事实(交 `refusalBody` 的 `facts`)—— 唯一一处。入参是**出口封口 + 脱敏后**的终局(调用方递 `redactTerminalResult(sealResultForExit(result)).terminal`,
- * 与 run 记录读面 / 流式 `done.result` 上的 `terminal` 同一只来源),本函数只按码取它的 `detail.detail`,不另读、不另脱。码不在登记表里、终局不是 `failed`、
+ * 与 run 记录读面 / 流式 `done.result` 上的 `terminal` 同一只来源),本函数只按码取它的 `detail.detail` 经闭集映射({@link attachmentCauseFacts}),不另读、不另脱。码不在登记表里、终局不是 `failed`、
  * 引擎没给 `coded` 因由 ⇒ `{}`(缺席不造键)。
  * 两张工具名清单的码({@link ENGINE_TOOL_LIST_REFUSAL_CODES})是另一臂:体事实不取引擎的因由,取 `admissionReadings`(受理口对放行侧选择器清单的读数,`PreparedTaskSubmission.warnings`)
  * 去掉 `not_in_roster`、且 `code` 与终局的码相同(同一族清单)的那些 —— 与受理口 400 同一只机读位形;没有读数 ⇒ `{}`。
@@ -132,8 +132,8 @@ export declare function releaseKeyIfZeroWorkRefusal(runStore: {
     releaseIdemKey(taskId: string): Promise<void>;
 }, taskId: string, result: Pick<TaskResult, "terminal" | "stats">): Promise<void>;
 /**
- * E18 resume-at — per-turn anchor capture, shared by runInBackground AND the resume-leg driveResume so the (single,
- * tricky) capture rule can't drift between the two stream-drain loops.
+ * E18 resume-at — per-turn anchor capture, shared by runInBackground, the resume-leg driveResume AND the sync `POST /v1/tasks`
+ * leg's plain form so the (single, tricky) capture rule can't drift between the stream-drain loops.
  *
  * A "turn" in core = ONE assistant message + its tool batch. resume-at is valid ONLY at a SETTLED rewindable boundary
  * — core's prepare-task accepts "user messages or finished assistant-text turns" and REJECTS an assistant message that
@@ -151,44 +151,51 @@ export declare function releaseKeyIfZeroWorkRefusal(runStore: {
  * observable instead of a silent feature outage.
  */
 /**
- * 「这一次用户消息提交是不是一句**提问**」的唯一读法 —— 三处用户回退锚(后台腿与续跑腿的 {@link TurnAnchorCapture}、`/v1/tasks/stream`
- * 腿的 `userMsgEntryId`)同调这一只。
+ * 「这一次用户消息提交是不是这个 run 的**开场提示**」的唯一读法 —— 四处用户回退锚(后台腿 / 续跑腿 / 同步腿 `POST /v1/tasks` 的 {@link TurnAnchorCapture}、`/v1/tasks/stream`
+ * 腿的 `userMsgEntryId`)同调这一只;调用点零各自判、零按正文判,且都是「最后一次交出的赢」。
  *
- * 目标声明了附件时,引擎把每只附件铸成**一条自己的用户消息**,紧跟在目标后面提交(core `human_input.attachments` 顶注:
- * 「each attachment is delivered as its own message after the objective; its `message_committed` is the delivery」)。
- * 所以一次带 N 只附件的提交会出 1 + N 次 `message_committed{role:"user"}`,而「回到这条提问」的锚要的是**人的那条**
- * (core 的 `resumeAt` 认它:「a `resumeAt` that keeps the message keeps its group」;以附件帧作 `resumeAt` 引擎拒 `resume_at.not_a_message`),
- * 不是排在最后的附件帧。目标**之前**还可能有引擎排队的注入消息同批提交(亲读 core `engine/harness/agent-harness.js` 的 `takePrompts`:
- * 排队消息 ⇒ 目标 ⇒ 附件帧;真案 = 工作区是 git 仓且带图时,git 状态帧单独排在目标前面),所以「窗口里第一次用户提交」不是判据。
+ * **回退锚 = 该轮开场提示,一个 run 一个(开场窗 + 闩)**:run 一开始就开着一个**开场窗**,收集第一次模型输出之前的 user 提交;窗关上之后(闩上),同 run 的 user-role 提交 ——
+ * 用户打断时引擎收尾追加的「[Request interrupted by user]」、第一次模型调用前后排进来的 steer 正文、答完之后再来的 steer —— 一律不交。这是 CC「rewind to the message that started this turn」的
+ * 同义,与 core `resumeAt` 的 `before` 语义(叶 = 目标的 parent)配对:锚在开场提示上,切到它的 parent = 这一轮整个撤回;锚若漂到打断标记行上,
+ * parent 就是被撤回的那句提示本身,模型仍见它。同根:core 的文件历史边界按「本 run 第一条 user 提交」的 entry 键入(`rewindFilesTo` / `POST /v1/sessions/:id/rewind-files`
+ * 凭锚找边界),锚漂到没有自己边界的打断标记行上就解不到。打断标记行永远不是锚。
+ * 「一个 run」= 锚的键(`taskId`)的边界:读法实例每个 run 新建一只;续既有 run 的续跑腿不写用户锚(见 `resume-legs.ts`)。
  *
- * **为什么是「窗口 + 严格吻合」而不是读标记**:`message_committed` 上只有 `entryId / role / toolCallId?`,附件帧与用户真提交在事件上**不可辨认**;
- * 落盘的行上有标记(`attachment` 键;引擎收尾的中断标记带 `provenance: "engine-note"`),但事件到手的那一刻本仓读不到那一行
- * (会话店面没有按条目读的口,只有整日志导出),所以只能数。数的前提是「目标之后紧接恰好 N 只帧、其后才是别的」—— 前提成立才落锚,
- * **不成立就不猜**:猜错的锚会落在附件帧上(引擎拒)或引擎的中断标记上(回到的不是用户那句)。
+ * **窗里怎么认**。`message_committed` 上只有 `entryId / role / toolCallId?`:引擎排队在目标之前同批提交的消息(带图且工作区是 git 仓时单独排的 git 状态帧;会话空闲期间到的后台任务通知)、
+ * 目标、目标声明的附件帧、引擎收尾的中断标记,在事件上**不可辨认**(落盘的行上有标记 —— `attachment` 键、`provenance: "engine-note"` —— 但事件到手那一刻本仓读不到那一行:
+ * 会话店面没有按条目读的口,只有整日志导出),所以只能数。引擎的提交序(亲读 core `engine/harness/agent-harness.js` 的 `takePrompts`):排队消息 ⇒ 目标 ⇒ 附件帧;
+ * 中断标记只在打断收尾时追加(此时第一次模型输出没有出来,窗是被 `turn_end` 切断,不是被输出关上)。
+ *  · **临时锚**:不带附件的提交,窗里**第一条** user 提交到手那一刻就交出 —— 打断 / 取消 / 断连常发生在第一次模型输出之前,那时窗还没关,锚必须已经在;
+ *    它也是 core 文件历史边界的键(本 run 第一条 user 提交)。
+ *  · **校正**:窗被**非用户提交**(第一次助手消息 / 工具结果)关上 ⇒ 窗内共 k 条 user 提交、声明了 N 只附件帧:k ≥ N+1 时开场提示 = 倒数第 N+1 条(严格吻合)。
+ *    不带附件而 k > 1(目标之前有引擎排队的消息)⇒ 交出这一条,**盖过**临时锚(调用方「最后一次赢」,与修前同读:修前的读法就是『开场批里最后一条 user 提交』);k = 1 ⇒ 临时锚已是它,不再交。
+ *    带附件的提交没有临时锚(此刻还不知道哪几条是帧),只在关窗这一刻交一次;k < N+1(帧数不符)⇒ 不猜。
+ *  · 窗被 `turn_end` 先切断 ⇒ 第一次模型调用没出任何输出就收了(halt / interrupt / cancel / 空失败):窗里可能夹着引擎收尾的中断标记,数 N 会落在帧或标记上 ⇒ **不校正**,
+ *    临时锚(不带附件)原样留着,带附件的提交不猜、不落锚。切断即闩上。
+ *  · 带附件的提交,窗内又应用了一条别的输入(`human_input{applied}`,如第一次模型调用前排进来的 steer;事件先于它的正文提交到手)⇒ 窗里多了一条别人的消息,数 N 会落在帧后面的 steer 上 ⇒ 不猜。
+ *    不带附件的提交不看输入条数:多条 applied 输入可以合成一条提交(续跑把停驻的 steer 与 wake 文本并成一条续跑消息),按修前同读校正到窗内最后一条。排队未应用(`delivery: "queued"`)的输入不动窗。窗还开着时继续攒,直到被关上。
+ *  · 「不猜」= 这个 run 不落(带附件)或不校正(不带附件),且窗关上之后闩上 —— 其后的 user 提交(steer 正文、打断标记)不是开场提示,不顶上来;拿这次 run 的 taskId 去 `resumeAt`
+ *    得 404 `resume_at.unknown_event`(文案点名带附件这一类成因)。
+ * 窗关上之前一个 user 提交都没有就关了(续跑腿里先到的是工具结果 / 助手消息)⇒ 窗照开着,不闩:那一条之后第一条 user 提交才是这个 run 里的第一条。
  *
- * 读法:
- *  · `human_input{delivery:"applied"}` 带 N 只附件 ⇒ 开窗;窗内的用户提交只攒、不落锚(此刻还不知道它们是不是『目标 + N 只帧』)。
- *  · 窗被**非用户提交**(第一次助手消息 / 工具结果)关上 ⇒ 窗内共 k 次用户提交,k ≥ N+1 时提问 = 倒数第 N+1 次(严格吻合);k < N+1(帧数不符)⇒ 不猜。
- *  · 窗被 `turn_end` 先切断 ⇒ 第一次模型调用没出任何提交就收了(halt / interrupt / 空失败):窗里可能夹着引擎收尾的中断标记,数 N 会落在帧或标记上 ⇒ 不猜。
- *  · 窗内又应用了一条别的输入(`human_input{applied}`,如第一次模型调用前排进来的 steer;事件先于它的正文提交到手)⇒ 窗里多了一条别人的消息,数 N 会落在帧上 ⇒ 窗作废、不猜,
- *    之后的用户提交(含那条 steer 正文)是窗口之外的提交,最后一次赢。排队未应用(`delivery: "queued"`)的输入不动窗。
- *  · 「不猜」= 返回 `undefined`、这次提交不落锚;拿这次 run 的 taskId 去 `resumeAt` 得 404 `resume_at.unknown_event`(文案点名这一类成因)。
- *    窗口之外的用户提交(如 interrupt 带话的 steer 正文,在 `turn_end` 之后提交)照修前读法(是提问,最后一次赢)。
- * 返回这次提交之后的提问 `entryId`(调用方照旧「最后一次赢」地落锚),不是提问相关的提交返回 `undefined`。
+ * 已知边界(引擎在 `message_committed` 上带来源标 / 输入标之日见下):
+ *  · 被 `turn_end` 切断(第一次模型输出之前打断 / 取消)、不带附件、且由引擎排队的消息领头的 run —— 窗来不及校正,锚落在领头的那一条上(修前:取消 = 目标,halt / interrupt = 打断标记)。
+ *    它与 core 文件历史边界的键是同一条消息,`resumeAtMode:"before"` 的叶仍是整轮之前;含目标的 `resumeAt` 只留下领头那条。
+ *  · 不带附件、第一次模型输出之前就应用了一条 steer:校正到窗内最后一条 = steer 正文(与修前同读)。
  *
- * 退役条件:引擎在落盘的帧上(`message_committed`)带上附件标记之日,本读法整体换成「按标记判一次」(零计数、无窗口、无拒臂),
- * 窗口 / 严格吻合 / 不猜三臂与 `resume_at.unknown_event` 文案里对应的那一句一并删除。
+ * 退役条件:引擎在落盘的帧上(`message_committed`)带上来源标(附件标记 / 引擎消息标)之日,本读法整体换成「第一条非引擎消息」(零计数、无窗口、无校正、无拒臂),
+ * 窗口 / 严格吻合 / 不猜三臂与 `resume_at.unknown_event` 文案里对应的那一句一并删除,领头排队消息的边界随之消失。
  */
 export declare function createPromptCommitReader(): (ev: {
     readonly type: string;
 }) => string | undefined;
-/** 回退锚写在哪条腿上(探针行的 `leg=`):流式腿 `POST /v1/tasks/stream`、后台腿 `POST /v1/runs`、续跑腿。 */
-export type ResumeAnchorLeg = "stream" | "bg" | "resume";
+/** 回退锚写在哪条腿上(探针行的 `leg=`):流式腿 `POST /v1/tasks/stream`、同步腿 `POST /v1/tasks`(非流式)、后台腿 `POST /v1/runs`、续跑腿。 */
+export type ResumeAnchorLeg = "stream" | "sync" | "bg" | "resume";
 /**
- * 回退锚的**唯一**写法(三条腿同一只):**有界** await 写入(单行店操作期限 {@link BASELINE_IO_DEADLINE_MS},与项目指令基线的
+ * 回退锚的**唯一**写法(四条腿同一只):**有界** await 写入(单行店操作期限 {@link BASELINE_IO_DEADLINE_MS},与项目指令基线的
  * 读写同一只数、同一只 {@link withinIoDeadline} —— 同为单行 PK 写、同在腿的关键路径上);写失败或到期 ⇒ 不抛(锚是这次提示词能不能
  * 回退的手柄,不是 run 的成败),记一次登记过的 fail-open `server.resume-anchor.capture-failed`(`reason=error|timeout`;计数 + 探针行 + 一次性 warn)。
- * 调用方在本腿的终帧(流式腿的 `done`)**之前** await 它 ⇒ 客户端拿到终帧时锚已落定或已知没落定,没有「锚晚到」的窗;锚店挂住至多让终帧晚一个期限。
+ * 调用方在本腿的终帧(流式腿的 `done`、同步腿的 200 应答)**之前** await 它 ⇒ 客户端拿到终帧时锚已落定或已知没落定,没有「锚晚到」的窗;锚店挂住至多让终帧晚一个期限。
  * 到期只放手不取消:那次写照常在飞,迟到落定的锚照样可用(迟到的失败被吞,不重复计数)。
  * 用户面的读数仍只有一处:会话视图用户消息行的 `taskId?`(present-iff 锚在)与 `resumeAt` 的 404 `resume_at.unknown_event`。
  */
@@ -204,14 +211,19 @@ export declare class TurnAnchorCapture {
      *  `message_committed{role:"user"}` event — its `entryId` is the persisted user-message `SessionTreeEntry.id`,
      *  ALWAYS a valid `resumeAt` target (core accepts a user message; it rejects a tool-result / mid-tool-call
      *  assistant). This is the CC rewind target ("rewind to the prompt" = the code-restore parity path — a code
-     *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + rewindFiles undoes it).
+     *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + restoreFiles undoes it).
      *  Keyed by the run's taskId (the handle the shell already holds from the POST response — no eventId→entryId
-     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus. */
+     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus.
+     *  The anchor is the run's OPENING prompt (the reader's opening window: provisional on the first user commit, corrected
+     *  when the first model output closes the window, latched after); a later
+     *  user-role commit in the same run — the interruption marker, a steer — never moves it. The capture instance is per
+     *  run: a leg that CONTINUES an existing run (same taskId) wires no `captureUser` (its opening prompt was anchored
+     *  by the first leg). */
     private readonly captureUser?;
     /** The turn's FIRST text_delta eventId = the message's stable resume handle (also stamped on the durable text event). */
     firstTextEventId: string | undefined;
     private turnHadTool;
-    /** 用户提交是不是提问的唯一读法({@link createPromptCommitReader};附件帧不是提问)。 */
+    /** 用户提交是不是开场提示的唯一读法({@link createPromptCommitReader};开场窗 + 闩 —— 开场提示之后打断标记 / steer 不改锚;附件帧不是提问)。 */
     private readonly promptCommit;
     constructor(capture: ((eventId: string) => Promise<void>) | undefined, 
     /** 这只捕获器在哪条腿上(写失败的 fail-open 探针行带它)。 */
@@ -220,18 +232,24 @@ export declare class TurnAnchorCapture {
      *  `message_committed{role:"user"}` event — its `entryId` is the persisted user-message `SessionTreeEntry.id`,
      *  ALWAYS a valid `resumeAt` target (core accepts a user message; it rejects a tool-result / mid-tool-call
      *  assistant). This is the CC rewind target ("rewind to the prompt" = the code-restore parity path — a code
-     *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + rewindFiles undoes it).
+     *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + restoreFiles undoes it).
      *  Keyed by the run's taskId (the handle the shell already holds from the POST response — no eventId→entryId
-     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus. */
+     *  side map / no leaf-read inference needed). The assistant-turn capture above stays as an additive bonus.
+     *  The anchor is the run's OPENING prompt (the reader's opening window: provisional on the first user commit, corrected
+     *  when the first model output closes the window, latched after); a later
+     *  user-role commit in the same run — the interruption marker, a steer — never moves it. The capture instance is per
+     *  run: a leg that CONTINUES an existing run (same taskId) wires no `captureUser` (its opening prompt was anchored
+     *  by the first leg). */
     captureUser?: ((entryId: string) => Promise<void>) | undefined);
-    /** A `human_input` arrived — the objective's declared attachments open the frame window of {@link createPromptCommitReader}. */
+    /** A `human_input` arrived — the objective's declared attachments open the frame window of {@link createPromptCommitReader} (another applied input inside the window voids it). */
     onHumanInput(ev: {
         readonly type: string;
     }): void;
     /** A `message_committed` arrived — capture a USER-message rewind anchor (CC parity). Best-effort (a failure only
-     *  makes that one prompt non-rewindable). Only a user commit that is a PROMPT (not an attachment frame trailing the
-     *  objective — {@link createPromptCommitReader}; an attachment window is decided when a non-user commit closes it, so
-     *  the anchor of an attachment-carrying prompt lands on THAT call); assistant/toolResult committed entries are handled by
+     *  makes that one prompt non-rewindable). Only the run's OPENING prompt anchors (the opening window's user commit — not an
+     *  attachment frame trailing the objective, not the interruption marker / a steer that follows it —
+     *  {@link createPromptCommitReader}; an attachment window is decided when a non-user commit closes it, so the anchor of an
+     *  attachment-carrying prompt lands on THAT call); assistant/toolResult committed entries are handled by
      *  the turn-text path (assistant) or deliberately not anchored (toolResult — `resumeAt` rejects them). */
     onMessageCommitted(role: string | undefined, entryId: string | undefined): Promise<void>;
     /** A text_delta arrived — latch the first DEFINED eventId as the message handle (eventId is optional on the stream). */
@@ -273,8 +291,8 @@ export declare function graftParkToolCallId<T>(result: T, cs: ParkCheckpointRead
  * 续跑在没有认领的会话上驱动(`resume-legs.ts` 认领缺席的成因清单)。顺序承重:先放认领、后作废 ⇒ 两步之间(作废没做成时一直)就是那一形。
  * 停驻没落定的成因不在判据里(停驻行 / 用量行 / 结果到手之后的任何一笔账本写抛):判据只读手里那份结果。
  *
- * `held` = 手里那份结果过了宿主判官之后的形(判官提上来的嵌套停驻同样算;不在本 run 会话上的嵌套停驻 —— cascade 级上的卡 —— 判官不提,
- * 不归本腿作废)。不是停驻 ⇒ 零 I/O。不抛:作废没做成 ⇒ 卡回到「留在待决面上、由兜底收割收走」的形,响亮留痕。
+ * `held` = 手里那份结果过了宿主判官之后的形(判官提上来的嵌套停驻同样算 —— verify 的实现腿 / 修复轮、cascade 的级上卡,都归本 run 的会话)。
+ * 不是停驻 ⇒ 零 I/O。不抛:作废没做成 ⇒ 卡回到「留在待决面上、由兜底收割收走」的形,响亮留痕。
  */
 export declare function voidHeldParkCard(held: {
     readonly terminal: TerminalCause;
@@ -310,11 +328,13 @@ export declare function voidHeldParkCard(held: {
  * only — a suspended run is steered durably via the checkpoint's `setPendingSteer` instead, and only the
  * plain-stream path holds a steerable stream (the verify/cascade branches return a result, not a stream).
  */
-export declare function runInBackground(runner: Runner, spec: TaskSpec, runStore: RunStore, taskId: string, metrics?: Metrics, principal?: string, verify?: VerifyRoundsSpec, // 快审 F1:number 参升整对象——cost 顶随传
+export declare function runInBackground(runner: Runner, spec: TaskSpec, runStore: RunStore, taskId: string, metrics?: Metrics, 
+/** 本跑的属主主体(分区键;行属主 / ALS 读它)。 */
+principal?: string, verify?: VerifyRoundsSpec, // 快审 F1:number 参升整对象——cost 顶随传
 cascade?: CascadeConfig, instrumentDegenerate?: (result: TaskResult) => void, planCacheProbe?: {
     record: (scope: string | undefined, objective: string, completed: boolean) => void;
 }, persistThinking?: boolean, inflight?: Map<string, RunAbort>, preemptable?: Map<string, AbortController>, steerable?: Map<string, TaskStream>, modelUsage?: ModelUsageTracker, elicitation?: ElicitationCoordinator, 
-/** E23: the VERIFIED principal (gatedPrincipal) that may answer this run's elicitations — matches the respond
+/** E23: the VERIFIED principal (gatedSubject) that may answer this run's elicitations — matches the respond
  *  owner-gate's identity source (NOT the cost-attribution `principal`, which on a direct door is the self-asserted
  *  header → can be null while a JWT principal exists). Falls back to the run owner when not supplied. */
 elicitOwner?: string | null, 
@@ -417,6 +437,15 @@ workspaceRecorder?: SessionWorkspaceRecorder,
  * 缺席 = 嵌入方自带的装配器没铸 ⇒ 账本行不带技能段。
  */
 runSkills?: readonly RunSkillEntry[]): Promise<void>;
+/** 一次心跳要的那一面(run 店的带属主刷新;交回「行还在 running 吗」)。 */
+export interface RunHeartbeatStore {
+    heartbeat(taskId: string, owner: string | null): Promise<boolean>;
+}
+/**
+ * 🔴 **一次心跳**(四条腿的心跳拍与认领心跳 `http/claim-heartbeat.ts` 同一只 —— 判法只在这里):刷新,店交回「这条 run 的行还在 running 吗」;不在 ⇒ `onLost()`,持有者停下自己的腿。
+ * 判死一条行(观察口 / 认领冲突 / 收割器)拦不住它的执行者 —— 心跳打空今天不报,两个执行者会同写一只会话;这一答补上那一半。刷新失败不抛(`onError` 计数),下一拍再刷。
+ */
+export declare function beatRunHeartbeat(runStore: RunHeartbeatStore, taskId: string, owner: string | null, onLost: () => void, onError: () => void): void;
 /** How often a running instance refreshes its run's updated_at (liveness, independent of events).
  *  Must stay strictly below `runStaleSec` (asserted at startup AND on every hot config candidate) or the
  *  reaper would race live runs. [ref]:数值的单源是 `config-invariants.ts`(那条不变量的属主),两个消费面

package/dist/runs.js

@@ -1,5 +1,5 @@
 import { runWithVerification, runCascade, defaultTaskRegistry, taskNotificationDedupKey, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
-import { atHostBoundary, failureCodeOf, sealResultForExit, outwardPlane } from "./terminal.js";
+import { atHostBoundary, failureCodeOf, sealResultForExit, outwardPlane, outwardThrownMessage } from "./terminal.js";
 import { voidVerifierPauseCard } from "./verifier-pause-card.js";
 import { voidPendingCard } from "./card-void.js";
 import { NOT_IN_ROSTER, entryProblemsFacts } from "./entry-problems.js";
@@ -7,16 +7,20 @@ import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { TOOL_DECLARATION_HTTP_STATUS } from "./tool-declaration-http-status.js";
 import { isSessionErrorCode, sessionErrorHttp } from "./session-error-wire.js";
 import { redactErrorMessage } from "./observability/run-terminal.js";
-import { withPrincipal } from "./observability/principal-context.js";
+import { withSubject } from "./observability/principal-context.js";
+import { partsOf } from "./owner-brands.js";
+import { recoveredSubject } from "./owner-faces.js";
+import { taskSpecIdentityOf } from "./engine-identity.js";
 import { withModelReachScope } from "./model-reach-scope.js";
 import { createInstructionSelectionLeg } from "./instruction-selection.js";
 import { redactSecrets } from "./trace/redact.js";
-import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
+import { taskNotificationEventData, appendModelUsageDelta, attachModelUsage, createPromptManifestSeat } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
 import { registerEngineNoticeLeg } from "./trace/engine-notice-wire.js";
 import { recordTurnActivity } from "./turn-activity.js";
 import { buildCancelledLedgerRow, CANCELLED_CODE, createRunAbort, mintCancelledResult } from "./run-cancel-context.js";
-import { createApprovalCardEmitter, resolveApprovalLeg } from "./tool-approval.js";
+import { resolveApprovalLeg } from "./tool-approval.js";
+import { createHitlTransport } from "./hitl-delivery.js";
 import { fleetRunResiduals } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKeyOf, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
@@ -55,7 +59,9 @@ export async function taskHandleStop(registry, handle, access, agentStore) {
     registry.markStopSource(handle, "user");
     return registry.stopTask(handle, access);
 }
-export function markChildrenStoppedByUserOnAbort(signal, taskId, principal) {
+export function markChildrenStoppedByUserOnAbort(signal, taskId, subject) {
+    const recovered = recoveredSubject(subject);
+    const principal = taskSpecIdentityOf(recovered === undefined ? undefined : partsOf(recovered)).principal;
     const mark = () => {
         try {
             defaultTaskRegistry.markStopSourceForOwner({ owner: taskId, scope: principal ?? "default" }, "user", { skipSessionScoped: true });
@@ -78,11 +84,14 @@ const PREPARE_REFUSAL_HTTP_STATUS = {
     "rewind.child_scope_unsupported": 422,
     "rewind.capture_disabled": 422,
     "rewind.store_unconfigured": 409,
+    "rewind.session_busy": 409,
+    "rewind.files_env_unsupported": 409,
     "memory.capture_optout_unpersisted": 503,
     "config.memory_capture_spelling": 400,
     "config.invalid_checkpoint_store": 400,
     "config.skill_listing_budget_invalid": 400,
     "config.user_invoked_skill_unknown": 400,
+    "config.skill_deny_unreadable": 409,
     "config.image_invalid": 400,
     "config.user_attachment_invalid": 400,
     "config.tool_face_control": 400,
@@ -125,6 +134,15 @@ export function syncRefusalHttpStatus(result) {
     return resumeAtHttpStatus(result);
 }
 const ZERO_WORK_REFUSAL_DETAIL_CODES = new Set(["config.user_attachment_invalid"]);
+function attachmentCauseFacts(cause) {
+    if (cause === null || typeof cause !== "object")
+        return {};
+    const c = cause;
+    return {
+        ...(typeof c.path === "string" && c.path !== "" ? { field: c.path } : {}),
+        ...(typeof c.index === "number" && Number.isInteger(c.index) && c.index >= 0 ? { index: c.index } : {}),
+    };
+}
 const ENGINE_ENTRY_SPELLING_REASONS = new Set(["near_miss", "unknown_name"]);
 function engineReasonOf(detail) {
     if (detail === null || typeof detail !== "object")
@@ -153,7 +171,7 @@ export function zeroWorkRefusalFacts(terminal, admissionReadings = []) {
     if (cause === null || typeof cause !== "object")
         return {};
     const c = cause;
-    return c.kind === "coded" && c.detail !== undefined ? { detail: c.detail } : {};
+    return c.kind === "coded" ? attachmentCauseFacts(c.detail) : {};
 }
 const RETRY_CLASS_WORDS = { transient: true, terminal: true };
 function engineRetryClassOf(terminal) {
@@ -174,17 +192,25 @@ export async function releaseKeyIfZeroWorkRefusal(runStore, taskId, result) {
         await runStore.releaseIdemKey(taskId);
 }
 export function createPromptCommitReader() {
-    let attachmentWindow;
+    const commits = [];
+    let frames = 0;
+    let appliedInputs = 0;
+    let settled = false;
     return (ev) => {
+        if (settled)
+            return undefined;
         if (ev.type === "human_input") {
             const h = ev;
             if (h.delivery !== "applied")
                 return undefined;
-            attachmentWindow = Array.isArray(h.attachments) && h.attachments.length > 0 ? { frames: h.attachments.length, commits: [] } : undefined;
+            appliedInputs += 1;
+            if (appliedInputs === 1)
+                frames = Array.isArray(h.attachments) ? h.attachments.length : 0;
             return undefined;
         }
         if (ev.type === "turn_end") {
-            attachmentWindow = undefined;
+            if (commits.length > 0)
+                settled = true;
             return undefined;
         }
         if (ev.type !== "message_committed")
@@ -192,17 +218,17 @@ export function createPromptCommitReader() {
         const c = ev;
         const entryId = typeof c.entryId === "string" && c.entryId.length > 0 ? c.entryId : undefined;
         if (c.role === "user") {
-            if (attachmentWindow !== undefined) {
-                attachmentWindow.commits.push(entryId);
-                return undefined;
-            }
-            return entryId;
+            commits.push(entryId);
+            return frames === 0 && commits.length === 1 ? entryId : undefined;
         }
-        const closed = attachmentWindow;
-        attachmentWindow = undefined;
-        if (closed === undefined || closed.commits.length < closed.frames + 1)
+        if (commits.length === 0)
+            return undefined;
+        settled = true;
+        if (frames === 0)
+            return commits.length > 1 ? commits[commits.length - 1] : undefined;
+        if (appliedInputs > 1 || commits.length < frames + 1)
             return undefined;
-        return closed.commits[closed.commits.length - 1 - closed.frames];
+        return commits[commits.length - 1 - frames];
     };
 }
 export async function settleResumeAnchor(write, where) {
@@ -329,7 +355,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             });
     }
     const heartbeat = setInterval(() => {
-        void runStore.heartbeat(taskId, owner).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
+        beatRunHeartbeat(runStore, taskId, owner, () => cancelCtrl.abort("stall_verdict"), () => { metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
         if (!cancelCtrl.signal.aborted) {
             void runStore.isCancelRequested(taskId, owner).then((c) => { if (c)
                 cancelCtrl.abort("cancel_verb"); }).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "cancel" }); });
@@ -362,7 +388,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         acceptance?.settle(sealed);
     };
     const settleLegResult = async (engineResult) => {
-        const result = atHostBoundary(engineResult, spec.sessionId);
+        const result = atHostBoundary(engineResult);
         const parkWord = result.terminal.kind === "paused" ? outwardPlane(result.terminal).status : undefined;
         if (parkWord !== undefined && isParkLedgerEventType(parkWord)) {
             await parkLeg(parkWord, result);
@@ -385,20 +411,9 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     const flushModelUsage = () => appendModelUsageDelta(append, modelUsage, taskId);
     const withModelUsage = (result) => attachModelUsage(result, { append, getEvents: (id, after) => runStore.getEvents(id, after), modelUsage, taskId });
     modelUsage?.register(taskId);
-    const manifestLease = promptManifests?.register(taskId) ?? 0;
-    const flushPromptManifest = () => appendPromptManifest(append, promptManifests, taskId);
-    const elicitEmit = (frame) => {
-        const { type, ...rest } = frame;
-        return append(type, rest);
-    };
-    const questionEmit = (frame) => {
-        const { type, ...rest } = frame;
-        return append(type, rest);
-    };
-    const approvalEmit = (frame) => {
-        const { type, ...rest } = frame;
-        return append(type, rest);
-    };
+    const manifestSeat = createPromptManifestSeat(promptManifests, taskId);
+    const flushPromptManifest = () => manifestSeat.drain(append);
+    const hitlTransport = createHitlTransport({ ledger: append });
     const unregisterEngineNotice = registerEngineNoticeLeg({
         sessionId: spec.sessionId,
         ...(pendingEngineNotices !== undefined ? { pending: pendingEngineNotices } : {}),
@@ -522,12 +537,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await append("suggestions", { suggestions: suggestions.map((s) => redactSecrets(s)) });
             }
         };
-        await instructionLeg.run(spec.sessionId, () => withModelReachScope({ sessionId: spec.sessionId, taskId }, () => withPrincipal(principal, () => {
+        await instructionLeg.run(spec.sessionId, () => withModelReachScope({ sessionId: spec.sessionId, taskId }, () => withSubject(recoveredSubject(principal), () => {
             const withElicit = elicitation
-                ? () => elicitation.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: elicitEmit, abortSignal: cancelCtrl.signal }, runBody)
+                ? () => elicitation.runWithContext({ taskId, owner: elicitOwner ?? owner, transport: hitlTransport, abortSignal: cancelCtrl.signal }, runBody)
                 : runBody;
             const withQuestion = () => question
-                ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: questionEmit, abortSignal: cancelCtrl.signal }, withElicit)
+                ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, transport: hitlTransport, abortSignal: cancelCtrl.signal }, withElicit)
                 : withElicit();
             const withApproval = () => approval && approvalLeg.active && approvalLeg.unattended === undefined
                 ? approval.coordinator.runWithContext({
@@ -536,8 +551,8 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     abortSignal: cancelCtrl.signal,
                     ...(spec.sessionId ? { sessionId: spec.sessionId } : {}),
                     executionLane: approval.executionLane,
-                    emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
-                    emitRevoke: (f) => approvalEmit(f),
+                    family: "approval_request",
+                    transport: hitlTransport,
                     legKey: "",
                     ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}),
                 }, withQuestion)
@@ -600,8 +615,9 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             }
             else {
                 settledAsCancel = false;
-                const safeMsg = redactErrorMessage(message) ?? message;
-                await voidHeldParkCard(observedDone === undefined ? undefined : atHostBoundary(observedDone, spec.sessionId), spec.sessionId, checkpointCards, "bg");
+                const outwardMsg = outwardThrownMessage(err, message);
+                const safeMsg = redactErrorMessage(outwardMsg) ?? outwardMsg;
+                await voidHeldParkCard(observedDone === undefined ? undefined : atHostBoundary(observedDone), spec.sessionId, checkpointCards, "bg");
                 try {
                     await append("failed", { errorMessage: safeMsg });
                 }
@@ -634,7 +650,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 if (verdict.kind === "park")
                     fleetPublisher.onTerminal(verdict.word);
                 else if (verdict.result !== null)
-                    fleetPublisher.onTerminal(verdict.label, fleetRunResiduals(verdict.result));
+                    fleetPublisher.onTerminal(verdict.label, fleetRunResiduals(verdict.result, failureCodeOf(verdict.result.terminal)));
                 else
                     fleetPublisher.onTerminal(verdict.label, {
                         ...(verdict.label === CANCELLED_CODE ? { stoppedBy: "user" } : {}),
@@ -652,10 +668,16 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             for (const evict of subagentHandleEvictions)
                 evict();
             modelUsage?.clear(taskId);
-            promptManifests?.clear(taskId, manifestLease);
+            manifestSeat.release();
             clearInterval(heartbeat);
         }
     }
 }
+export function beatRunHeartbeat(runStore, taskId, owner, onLost, onError) {
+    void runStore.heartbeat(taskId, owner).then((running) => {
+        if (!running)
+            onLost();
+    }, onError);
+}
 export const HEARTBEAT_MS = LIVENESS_HEARTBEAT_MS;
 //# sourceMappingURL=runs.js.map

package/dist/runtime-caps-resolver.d.ts

@@ -23,8 +23,8 @@
  *  · `forceDurableGate`— prepare-task.js 的 durable/content mandate、活 content-ask 抑制、
  *                        durable question face（该处合取 `resolveCheckpointStore(spec, deps) !== undefined`
  *                        ⇒ **无 checkpoint 店的部署上这一面本就不成立**，该键在那里 inert）
- *  · `autoMode`        — prepare-task.js `=== true` **∧** `deps.autoMode !== undefined`（部署需先具备分类器；
- *                        显式 opt-in 极性，且 [ref] 起本侧传的是三态 org deny 位，见 toCoreRuntimeCaps 头注）
+ *  · `autoMode`        — 武装式 `spec.permissionMode === "auto"` **∧** `deps.autoMode !== undefined` **∧** `runtimeCaps?.autoMode !== false`
+ *                        （部署需先具备分类器；三态 org deny 位：`true` 与缺席同义、只有 `false` 是拒，见 toCoreRuntimeCaps 头注）
  *  · `bypassPermissions` — `dist/core/mode-policy.js` 的模式折叠（请求 `bypassPermissions` ∧ 本位 `=== false` ⇒ 这条腿跑在
  *                        `default`、发 `config.permission_mode_unavailable{by:"operator_deny"}`、回执 `foldedBy:"operator_deny"`）；
  *                        deny 形，缺席 = 不阻。[ref] D2 起由 center 的 `allowBypassPermissions` 写（此前本仓零写点）
@@ -66,6 +66,11 @@
  * 人的授予、搭上一个人的在飞请求、带上一个人的 etag 去换 304。在飞期间换了人,答复由传输层丢弃
  * (`http-client.ts` `requestPrincipalView`),按这一次取数失败走下面的 fail-closed 臂(降级项落在发起那一箱)。
  *
+ * 🔐 场景面同一条故障律、另一种拒法:同一次硬失败把场景那一面记成 `"unavailable"`(读数第三态,见 `capabilities/scenarios.ts`
+ * `ScenarioRulingRead`),场景门据它拒这条 run(503 `state.scenario_assignment_unavailable`)—— 场景面没有「拒掉放大位、照跑」的中间形:
+ * 受限主体的指派与白名单此刻不可知,落部署缺省或照放点名都可能比他的指派更宽。治理两键形不对同记 `"unavailable"`(经 `onError` 一行)。
+ * 缺席(无 principal / 中心不发两键)仍是 `undefined`;没接中心的部署根本没有本客户端。
+ *
  * The resolver maps center's `EntitlementRuntimeCaps` → the SUBSET core enforces ({@link RuntimeCaps}): center
  * also carries `allowUltracode` (a shell/UX reasoning-tier cap the engine has no primitive for), which we DROP —
  * this seam feeds the ENGINE, and `allowUltracode` is enforced at the service settings-resolution layer, not here.
@@ -77,7 +82,7 @@ import type { RuntimeCaps } from "@sema-agent/core";
 import type { EntitlementRuntimeCaps } from "@sema-agent/settings-schema";
 import { fetchPrincipalCaps, type ExecutionRuling } from "./web-admin-client/facade.js";
 import type { CenterEndpoint } from "./web-admin-client/center-request.js";
-import type { ScenarioRuling } from "./capabilities/scenarios.js";
+import type { ScenarioRulingRead } from "./capabilities/scenarios.js";
 import type { ServiceConfig } from "./config-types.js";
 import { type Logger } from "./observability/logger.js";
 /** test-only: reset the once-per-process trace so each test observes a fresh "first hit". */
@@ -102,6 +107,15 @@ export interface EntitlementsResolverOpts {
     /** Observability hook for a resolve failure (defaults to a `runtime_caps_resolve_failed` warn). */
     onError?: (err: Error, principal: string) => void;
 }
+/**
+ * 中心拒了 auto 时**是哪一键拒的**(闭集)。中心的 entitlement 里 auto 的拒位今天有两个键(`autoMode` 与 `allowAutoMode`,settings-schema 里一个事实两个源 ——
+ * 折成一键归那个仓),引擎只有一只拒位;读者(`GET /v1/capabilities` 的 `permissionModeAuto.refusedBy`)靠这一词分清该去改中心的哪一键。
+ * 中心折成一键之后两词退役、本词集随之删(零别名)。
+ */
+export declare const AUTO_MODE_REFUSED_BY: readonly ["center.autoMode", "center.allowAutoMode", "both"];
+export type AutoModeRefusedBy = (typeof AUTO_MODE_REFUSED_BY)[number];
+/** 中心这一答拒没拒 auto、哪一键拒的 —— 拒位与来源词的**同一只判**({@link toCoreRuntimeCaps} 的拒位读它)。缺席 = 中心没拒(任一键的 `true` 都不是授予,不覆盖另一键的 `false`)。 */
+export declare function autoModeRefusedByOf(ent: Pick<EntitlementRuntimeCaps, "autoMode" | "allowAutoMode">): AutoModeRefusedBy | undefined;
 /** Map center's `EntitlementRuntimeCaps` → the subset core's engine enforces. `allowUltracode` (shell/UX) is
  *  dropped on purpose (not a core primitive); `allowWorkflows` / `forceDurableGate` / `allowFork` are **three of the
  *  six** the engine reads — the other three (`allowObservers` / `autoMode` / `allowMemoryOptOut`) are documented
@@ -146,6 +160,12 @@ export declare function toCoreRuntimeCaps(ent: EntitlementRuntimeCaps | null | u
  * 所以本谓词为 false **不再**意味着 auto 不武装;「会不会武装」由 `auto-mode-face.ts` 的三项合取答。
  */
 export declare function centerEntitlementSourceWired(config: Pick<ServiceConfig, "webAdmin">): boolean;
+/** 只读腿的一次读数:拒位(caps)与中心拒 auto 的来源词出自**同一个**缓存项。 */
+export interface RuntimeCapsReading {
+    readonly caps: RuntimeCaps | undefined;
+    /** 只在中心亲口拒了 auto 时在场({@link AutoModeRefusedBy})。 */
+    readonly autoModeRefusedBy?: AutoModeRefusedBy;
+}
 /** The two per-principal faces served off ONE caps fetch + cache. */
 export interface PrincipalEntitlementsClient {
     /** core's `RunnerDeps.runtimeCapsResolver` seam — FAIL-CLOSED on error (deny workflows/fork/autoMode/bypassPermissions;
@@ -166,7 +186,7 @@ export interface PrincipalEntitlementsClient {
      *
      * 🔴 **界画在「这句话是谁说的」**(codex r2 [high] 逐条核后的定界,不是「读面完全不碰缓存」):
      *  · **成功项 = center 亲口答的那份** —— 与提交腿自己抓到的**逐字同一份**、同一条 `ttlMs`、同一个**已验证**
-     *    身份(读面的 principal 走 `gatedPrincipal` → `verifiedPrincipal`,与提交腿同源,读不到别人的格)。读面
+     *    身份(读面的 principal 走 `gatedSubject` → `verifiedPrincipal`,与提交腿同源,读不到别人的格)。读面
      *    只是把这个 principal 自己那一格**预热**了一下;org 撤销后的陈旧窗由部署级 `ttlMs` 定义,与哪一腿预热
      *    的无关(提交腿自己预热同样如此),本批**零改动**。
      *  · **降级项 = server 自铸的判决** —— center 从没说过这句 deny,是本层在故障时替它说的。让一次**读**铸的
@@ -180,18 +200,19 @@ export interface PrincipalEntitlementsClient {
      * 而它硬失败 ⇒ 该降级项当场升格为执法项(codex r1 [medium]:否则一条总抢在提交前面的轮询会让每次提交
      * 都重抓,denyTtl 的界对提交腿失效)。让它升格的是一次真提交自己吃到的硬失败,不是那次读。
      */
-    peekRuntimeCaps: (principal: string | undefined) => Promise<RuntimeCaps | undefined>;
-    /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest —
-     *  FAIL-OPEN on error / older center without scenario keys / no principal (undefined = no governance, legacy passthrough).
-     *  Scenario switching is not a privilege-amplifying face; a center blip must not pin users to `default`. */
-    scenarioRuling: (principal: string | undefined) => Promise<ScenarioRuling | undefined>;
+    peekRuntimeCapsReading: (principal: string | undefined) => Promise<RuntimeCapsReading>;
+    /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest — a three-state read
+     *  ({@link ScenarioRulingRead}): the ruling; `undefined` = absent (no principal ⇒ no center call; older center without
+     *  the scenario keys) = no governance; `"unavailable"` = the center could not answer (hard fetch failure — same error entry
+     *  as the caps face's fail-closed deny — or malformed ruling keys) ⇒ the gate refuses the run. */
+    scenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /**
-     * {@link PrincipalEntitlementsClient.scenarioRuling} 的**只读**孪生(同 {@link PrincipalEntitlementsClient.peekRuntimeCaps} 的界):同一只缓存 / 同一条抓取 /
-     * 同一份 fail-open 判决(`undefined` = 无治理),唯一的差别是 center 硬失败时本腿铸的 fail-closed 降级项**只对读面自己算数**,提交腿不认、照常重抓。
+     * {@link PrincipalEntitlementsClient.scenarioRuling} 的**只读**孪生(同 {@link PrincipalEntitlementsClient.peekRuntimeCapsReading} 的界):同一只缓存 / 同一条抓取 /
+     * 同一份三态读数(故障 ⇒ `"unavailable"`,读面与提交腿同拒),唯一的差别是 center 硬失败时本腿铸的降级项**只对读面自己算数**,提交腿不认、照常重抓。
      * 读面(`GET /v1/capabilities/mcp?scenario=` 的场景门)问中心裁定时必须走这一只 —— 经 `scenarioRuling` 问,center 抖动的那一拍会替这个主体的**真提交**
-     * 留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面成了别人被拒的原因,与 `peekRuntimeCaps` 的病灶同一类)。
+     * 留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面成了别人被拒的原因,与 `peekRuntimeCapsReading` 的病灶同一类)。
      */
-    peekScenarioRuling: (principal: string | undefined) => Promise<ScenarioRuling | undefined>;
+    peekScenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /** (stage7 P5) The resolved per-principal execution-lane ruling for resolveSpec's
      *  gateExecutionLane. FAIL-OPEN + audit on error (this phase is "honest-but-bypassable";
      *  tightening to fail-closed is a future, separate decision) / older center without the execution key / no principal. */
@@ -215,7 +236,8 @@ export declare function gateExecutionLane(ruling: ExecutionRuling | undefined, o
  * `(principal) => Promise<RuntimeCaps | undefined>`; `scenarioRuling` rides the SAME fetch/cache/in-flight
  * (zero extra center RTT — center attaches the ruling to the caps body). Wire ONLY when a center is
  * configured (and not in dry-run) — absent ⇒ core sees `undefined` ⇒ NO per-principal restriction, and the
- * scenario gate sees `undefined` ⇒ legacy body-or-default chain.
+ * scenario gate sees `undefined` (absent) ⇒ request-name-or-deployment-default chain. Present ⇒ a center that cannot answer
+ * reads `"unavailable"` on the scenario face (the gate refuses), never `undefined`.
  */
 export declare function createPrincipalEntitlementsClient(opts: EntitlementsResolverOpts): PrincipalEntitlementsClient;
 /** Back-compat face for core's seam-only consumers: the caps half of {@link createPrincipalEntitlementsClient}. */