@sema-agent/server 7.76.1 → 7.77.0

package/dist/fleet/subagent-tail-bus.d.ts

@@ -7,7 +7,9 @@ export type SubagentTailFrame = Record<string, unknown> & {
     type: string;
 };
 /** core forward 事件 → wire 投影(sync 主流五分支同源;不认识的帧类型=null 不发——tail 面只承诺
- *  content 六类,新 core 帧类型先经这里显式收编再出 wire)。 */
+ *  content 六类,新 core 帧类型先经这里显式收编再出 wire)。
+ *  ⚠️ **本函数是无状态逐帧投影**:`reasoning_end`(S-310 的推理权威段)不在这里 —— 它要按句柄攒段,
+ *  住在 {@link SubagentTailBus.onForwardFrame}(publish 侧是唯一知道句柄的地方)。 */
 export declare function projectTailFrame(e: Record<string, unknown> & {
     type?: string;
 }): SubagentTailFrame | null;
@@ -50,9 +52,33 @@ export declare class SubagentTailBus {
      * 不需要"先有内容帧"才能学到"没有内容帧"。
      */
     private readonly modeByHandle;
+    /**
+     * 句柄 → 该句柄这条 tail 流上**在攒的推理段**(S-310)。
+     *
+     * 键必须是句柄,理由与 {@link modeByHandle} 同源再加一条硬的:两个并发子代的 `reasoning_delta` 在
+     * **同一个** forward sink 上交错到达,一只累积器会把两份思考拼成一段、再盖上其中一个的身份键。
+     *
+     * 生命期 = **有人在听的那段时间**:攒段住在 `hasSubscribers` 快门之内(tail 是 live-only 面,没人听
+     * 就不投影也不攒),最后一个订阅者走掉或句柄终态({@link forgetHandle})时整条删掉 ⇒ 本表恒被
+     * 订阅者数量所界,不需要第二道容量闸。
+     */
+    private readonly segByHandle;
     /** 三条 run 腿的 forward 回调里逐帧调(在 `hasSubscribers` 快门**之前**——没人在听时也要学,
      *  否则晚开的 tail 永远读不到供给形)。同值重复写是 no-op(热路径只付一次 Map.get)。 */
     noteHandleContentMode(bgAgentId: string, mode: TailContentMode): void;
+    /**
+     * 🔴 **三条 run 腿的 forward 回调唯一入口**(S-310 收口)——登记供给形 → 段界收段 → 逐帧投影 → publish。
+     *
+     * 此前这四步以**同一段六行代码**抄在三条腿上(sync 流腿、verify-resume 腿、resume-stream 腿),
+     * 差别为零;S-310 要给 tail 面补 `reasoning_end` 时,那就是第四、第五、第六份拷贝。收成一扇门之后
+     * 腿上只剩「句柄在不在」这一句判断,三腿不可能再分家(`test/subagent-tail-stream.test.ts` G18-G20)。
+     *
+     * 顺序即语义:权威段**先于**触发它的结构帧上 wire(消费端「整段替换已攒 delta」的替换点不与卡片交错),
+     * 与账本腿「文本行先于结构行」逐字同构。
+     */
+    onForwardFrame(bgAgentId: string, mode: TailContentMode, e: Record<string, unknown> & {
+        type?: string;
+    }): void;
     /**
      * 句柄终态时**撤销**登记(三条腿的 `onTaskNotification` 观察者调,与 `task_settled` 帧同处)。
      *
@@ -69,7 +95,7 @@ export declare class SubagentTailBus {
      * 的答案。core 今天把终态通知排在最后一条 forward 之后(fleet-bus 同注),复活又是人手动作,这条窗
      * 实际上不可达;真要关死需要给句柄加墓碑态,代价大于一位诊断标签的收益,故不做。
      */
-    forgetHandleContentMode(bgAgentId: string): void;
+    forgetHandle(bgAgentId: string): void;
     /** 路由读(按 tail 的 target 句柄)。缺席 = 不知道,路由出 `"unknown"`。 */
     handleContentMode(bgAgentId: string): TailContentMode | undefined;
     /** 两条 run 腿的 fwdInternals 调用点:帧已投影(projectTailFrame),null 不进来。 */

package/dist/fleet/subagent-tail-bus.js

@@ -1,5 +1,6 @@
 import { redactSecrets } from "../trace/redact.js";
 import { taskProgressEventData, toolStartEventData, toolEndEventData, textEndEventData } from "../trace/project.js";
+import { createReasoningSegments } from "../trace/model-segment.js";
 const TAIL_QUEUE_CAP = 512;
 export function projectTailFrame(e) {
     const t = e.type;
@@ -41,12 +42,31 @@ const HOST_MODE_CAP = 4096;
 export class SubagentTailBus {
     subs = new Map();
     modeByHandle = new Map();
+    segByHandle = new Map();
     noteHandleContentMode(bgAgentId, mode) {
         if (this.modeByHandle.get(bgAgentId) === mode)
             return;
         putBounded(this.modeByHandle, bgAgentId, mode);
     }
-    forgetHandleContentMode(bgAgentId) {
+    onForwardFrame(bgAgentId, mode, e) {
+        this.noteHandleContentMode(bgAgentId, mode);
+        if (!this.hasSubscribers(bgAgentId))
+            return;
+        let segs = this.segByHandle.get(bgAgentId);
+        if (segs === undefined) {
+            segs = createReasoningSegments();
+            this.segByHandle.set(bgAgentId, segs);
+        }
+        for (const end of segs.onEvent(e))
+            this.publish(bgAgentId, end);
+        const f = projectTailFrame(e);
+        if (f)
+            this.publish(bgAgentId, f);
+    }
+    forgetHandle(bgAgentId) {
+        for (const end of this.segByHandle.get(bgAgentId)?.cut() ?? [])
+            this.publish(bgAgentId, end);
+        this.segByHandle.delete(bgAgentId);
         this.modeByHandle.delete(bgAgentId);
     }
     handleContentMode(bgAgentId) {
@@ -84,8 +104,10 @@ export class SubagentTailBus {
             sub.closed = true;
             sub.wake?.();
             set.delete(sub);
-            if (set.size === 0 && this.subs.get(bgAgentId) === set)
+            if (set.size === 0 && this.subs.get(bgAgentId) === set) {
                 this.subs.delete(bgAgentId);
+                this.segByHandle.delete(bgAgentId);
+            }
         };
         const it = {
             [Symbol.asyncIterator]() {

package/dist/http/principal-gate.d.ts

@@ -1,4 +1,4 @@
-import type { IncomingMessage } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
 import type { ServiceConfig } from "../config-types.js";
 /** Coerce a possibly-repeated request header to a single string (or undefined). */
 export declare function headerStr(v: string | string[] | undefined): string | undefined;
@@ -21,6 +21,48 @@ export declare function isLoopbackAddress(addr: string | undefined): boolean;
  */
 export declare function verifiedIdentitySource(req: IncomingMessage, config: ServiceConfig): "sso" | "direct_door_jwt" | "service_token" | undefined;
 export declare function gatedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
+/**
+ * 「**出示了凭证但验不过** ≠ **没出示**」在 **direct-door principal JWT** 面上的形 —— 本仓
+ * {@link bearerPresentedButUnverified} 早就是同一条律在 Bearer 面的形,这里只是把它推到另一面。
+ *
+ * 判据三段,缺一不成立:①这台机器是直连门(BFF/gated 上 `principalHeader` 由上游验过,本函数恒 false ⇒
+ * 那条部署形上零行为变化);②`X-Approval-Principal-Token` **在场**(缺席 = 真的没出示,那是
+ * `auth.principal_required` 的语义,不许借本码);③它**验不过**({@link verifiedPrincipal} 回 undefined)。
+ */
+export declare function principalTokenPresentedButUnverified(req: IncomingMessage, config: ServiceConfig): boolean;
+/**
+ * 🔴 **`requirePrincipal` 部署上「这次请求没有可用身份」的唯一 401 铸点**(S-305,7.76.2)。
+ *
+ * 此前 45 个路由各自手抄同一行 `sendError(res, 401, "auth.principal_required", …)`,于是直连门上
+ * 「JWT 出示了但过期/签不上」与「什么头都没带」在 wire 上**同形**(黑盒实测:plan_review 带过期 JWT
+ * 拿到 `auth.principal_required`,而契约与路由层的 `verifyDirectDoorProof` 说的是 `principal_unverified`)。
+ * 两件事的处置完全不同 —— 前者「重签一张再来」,后者「你压根没接上身份面」。
+ *
+ * 一条规则、一处落点:{@link principalTokenPresentedButUnverified} 为真 ⇒ `401 principal_unverified`
+ * (既有码,文案与 `principal-jwt.ts` 的验签层同句);否则 `401 auth.principal_required`(原样)。
+ * 路由层 `verifyDirectDoorProof` 自己那条 `principal_unverified` 臂保留 —— 它守的是 decide/plan_review
+ * 调用链上的**证明三件套**,与本门(身份面)是两道门。
+ */
+export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingMessage, config: ServiceConfig): void;
+/**
+ * 🔴 **「这个调用方读得到这一行 run 吗」的唯一谓词**(S-297 抽取;此前只活在 `server.ts runOwnerOk` 的
+ * 函数体里,而 `runOwnerOk` 把**判断**与**404 怎么发**焊在一起 —— 于是任何需要同一条判断但不想 404 的
+ * 读面(如 `/mcp` 面板的 `lastLegMcp`:非属主就不投这个键、面板照常 200)只能手抄一份,而手抄那份必然
+ * 漏掉下面这条窄互认臂:`explicitOperatorOk` 顶注已经为同族的病写过「SINGLE mint point,不要再造兄弟」)。
+ *
+ * 三条放行臂,别的一律不放:
+ *  · `owner === null` —— 无属主的行(dev / 存量),本来就是开放的;
+ *  · `principal === owner` —— 自己的行。⚠️ `principal` 必须是**验过**的身份(`gatedPrincipal`),
+ *    不是自述头 —— `owner` 是创建时从验过的 principal 落库的,拿自述头来比就等于谁都能读别人的 run;
+ *  · [ref] C8 **窄互认**:非 `requirePrincipal` 部署上那批 `anon:shell-live` 哨兵行 + 无身份的调用方
+ *    (cli 停发哨兵头后的存量会话,否则「能续跑但看不见」)。`gatedPrincipal` 的回值是 `string | undefined`
+ *    ⇒ 原文那半个 `principal === null` 比较结构上不可达,抽取时一并去掉(语义逐字不变)。
+ *
+ * **不含 operator 臂**(刻意,[ref]⑥ 台账):跨属主 operator 在 poll/events/cancel 三读面上今天就是 404,
+ * 放宽它是一次独立裁定。需要 operator 臂的读面在**自己的调用点**显式并上 {@link explicitOperatorOk} ——
+ * 那样「谁多给了 operator 一条路」在代码上看得见,而不是被偷偷塞进共享谓词里。
+ */
+export declare function runOwnerReadable(principal: string | undefined, owner: string | null, config: ServiceConfig): boolean;
 /** The EXPLICIT operator gate (IMAGE-API-DESIGN.md §P2.4a MUST-FIX) — NOT the bare `isOperator` (whose empty-list
  *  "true-for-all" is an unrestricted-write exec door the instant OPERATOR_PRINCIPALS is empty). Requires a non-empty
  *  operator set AND a present principal IN it. The same form the preempt/resume endpoints already use.

package/dist/http/principal-gate.js

@@ -1,5 +1,6 @@
 import { timingSafeEqual } from "node:crypto";
-import { verifiedPrincipal, ssoVerifiedPrincipal } from "../security.js";
+import { PRINCIPAL_TOKEN_HEADER, verifiedPrincipal, ssoVerifiedPrincipal } from "../security.js";
+import { sendError } from "./send.js";
 export function headerStr(v) {
     return Array.isArray(v) ? v[0] : v;
 }
@@ -50,6 +51,27 @@ export function gatedPrincipal(req, config) {
         return undefined;
     return verifiedPrincipal(req, config);
 }
+export function principalTokenPresentedButUnverified(req, config) {
+    if (!config.directDoorActive)
+        return false;
+    if (headerStr(req.headers[PRINCIPAL_TOKEN_HEADER]) === undefined)
+        return false;
+    return verifiedPrincipal(req, config) === undefined;
+}
+export function sendPrincipalRefusal(res, req, config) {
+    if (principalTokenPresentedButUnverified(req, config)) {
+        sendError(res, 401, "principal_unverified", "principal token failed verification");
+        return;
+    }
+    sendError(res, 401, "auth.principal_required", `missing principal header '${config.principalHeader}'`);
+}
+export function runOwnerReadable(principal, owner, config) {
+    if (owner === null)
+        return true;
+    if (principal === owner)
+        return true;
+    return !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
+}
 export function explicitOperatorOk(principal, operatorPrincipals) {
     return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
 }

package/dist/http/routes/a2a-serve.js

@@ -6,7 +6,7 @@ import { isParkedRunStatus, isTerminalRunStatus } from "../../plugins/store-cont
 import { HttpError } from "../../security.js";
 import { scopedIdempotencyKey } from "../idempotency.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal } from "../principal-gate.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { createDurableRun } from "./runs.js";
 export const A2A_PROTOCOL_VERSION = "1.0";
 export const A2A_VERSION_HEADER = "a2a-version";
@@ -344,7 +344,7 @@ async function handleA2aRpcBody(req, res, url, ctx, miss) {
     res.setHeader(A2A_VERSION_HEADER, A2A_PROTOCOL_VERSION);
     if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
         deps.metrics?.inc("a2a_serve_rejected_total", { reason: "principal_required" });
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     let payload;

package/dist/http/routes/admin-config-refresh.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 export const ADMIN_CONFIG_REFRESH_PATH = "/v1/admin/config/refresh";
 const OPERATOR_ONLY_MESSAGE = "config refresh is operator-only: the caller principal is not in OPERATOR_PRINCIPALS (an empty list means NO one is an operator — configure it to enable this endpoint)";
 export async function handleAdminConfigRefresh(req, res, url, ctx) {
@@ -16,7 +16,7 @@ async function handleAdminConfigRefreshBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/admin-drain.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 export const ADMIN_DRAIN_PATH = "/v1/admin/drain";
 export const MAX_DRAIN_REASON_CHARS = 256;
 const OPERATOR_ONLY_MESSAGE = "drain declaration is operator-only: the caller principal is not in OPERATOR_PRINCIPALS (an empty list means NO one is an operator — configure it to enable this endpoint)";
@@ -17,7 +17,7 @@ async function handleAdminDrainBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/admin-memory-optout.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { memoryOptOutPrincipalShapeProblem } from "../../plugins/memory-optout-grant-store-sql.js";
 export const ADMIN_MEMORY_OPTOUT_PATH = "/v1/admin/memory-optout";
 export const ADMIN_MEMORY_OPTOUT_OVERRIDE_RE = /^\/v1\/admin\/memory-optout\/([^/]+)$/;
@@ -38,7 +38,7 @@ async function handleBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/adoption.js

@@ -2,7 +2,7 @@ import { createAdoptionRunner } from "../../adoption/runner.js";
 import { AdoptionRequestSchema } from "../../adoption/wire.js";
 import { checkAdoptionPrincipalShape, checkAdoptionWidths } from "../../adoption/plan.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 const ADOPTION_ID_RE = /^\/v1\/adoption\/([^/]+)$/;
 function sendOutcome(res, out) {
     switch (out.kind) {
@@ -54,7 +54,7 @@ async function handleAdoptionBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/approvals-assistant.js

@@ -14,7 +14,7 @@ import { fleetRunLabels } from "../../fleet/fleet-bus.js";
 import { sleep } from "../sse-log.js";
 import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_MS } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, isOperator } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, isOperator, sendPrincipalRefusal } from "../principal-gate.js";
 import { governanceOriginOf } from "../active-run-conflict.js";
 import { sendResumeOutcome } from "../route-ctx.js";
 export const ASSISTANT_PREEMPT_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/preempt$/;
@@ -246,7 +246,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
             if (deps.config.requirePrincipal && principal === undefined) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             if (!deps.config.resourceSuspend || !deps.checkpointStore) {
@@ -310,7 +310,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
             if (deps.config.requirePrincipal && principal === undefined) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             const taskId = resumeMatch[1];
@@ -338,7 +338,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
             if (deps.config.requirePrincipal && principal === undefined) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             const taskId = planReviewMatch[1];

package/dist/http/routes/attachments.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { uuidv7, sanitizePathComponent } from "@sema-agent/core";
 import { HttpError } from "../../security.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal } from "../principal-gate.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 export async function handleAttachments(req, res, url, ctx) {
     const miss = { fell: false };
     await handleAttachmentsBody(req, res, url, ctx, miss);
@@ -23,7 +23,7 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
             }
             const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && principal === undefined) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             const owner = principal ?? "default";

package/dist/http/routes/config-catalog.js

@@ -1,6 +1,6 @@
 import { DOMAINS } from "@sema-agent/settings-schema";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { configKnobTable } from "../../config.js";
 import { buildConfigCatalog } from "../../config-catalog.js";
 export const CONFIG_CATALOG_PATH = "/v1/config/catalog";
@@ -23,7 +23,7 @@ function handleConfigCatalogBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/devices.js

@@ -1,5 +1,5 @@
 import { sendError, sendJson } from "../send.js";
-import { explicitOperatorOk, gatedPrincipal } from "../principal-gate.js";
+import { explicitOperatorOk, gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { ssoVerifiedScope } from "../../security.js";
 import { assertDeviceIdShape, assertRootSessionIdShape, sameDeviceOwner, } from "../../device-store.js";
 const DEVICE_NOT_FOUND_MESSAGE = "device not found";
@@ -60,7 +60,7 @@ async function handleDevicesBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && principal === undefined) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     const store = deps.deviceStore;

package/dist/http/routes/fleet.js

@@ -2,7 +2,7 @@ import { hookNoticeWire } from "../../fleet/fleet-bus.js";
 import { FLEET_SNAPSHOT_TERMINAL_MAX_ROWS, isTerminalWorkflowRowStatus, recentTerminalWorkflowRows } from "../../fleet/fleet-terminal-window.js";
 import { taskNotificationFoldKey } from "../../orchestration/workflow-completion-inbox.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
-import { gatedPrincipal } from "../principal-gate.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 export async function handleFleet(req, res, url, ctx) {
     const miss = { fell: false };
     await handleFleetBody(req, res, url, ctx, miss);
@@ -20,7 +20,7 @@ async function handleFleetBody(req, res, url, ctx, miss) {
         const { fleetWide } = sessionOwnerScope(req);
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal && !fleetWide) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const fleetParams = new URL(req.url ?? "", "http://x").searchParams;

package/dist/http/routes/leader.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, headerStr } from "../principal-gate.js";
+import { gatedPrincipal, headerStr, sendPrincipalRefusal } from "../principal-gate.js";
 export async function handleLeader(req, res, url, ctx) {
     const miss = { fell: false };
     await handleLeaderBody(req, res, url, ctx, miss);
@@ -13,7 +13,7 @@ async function handleLeaderBody(req, res, url, ctx, miss) {
         const isLeaderGet = req.method === "GET" && /^\/v1\/leader\/[^/]+$/.test(url);
         if (isLeaderPost || isLeaderGet) {
             if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             const requester = gatedPrincipal(req, deps.config) ?? null;

package/dist/http/routes/memory-bundle.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
 import { buildOriginFencedBundle, readOriginAware } from "../../memory-origin-fence.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 export const MEMORY_BUNDLE_EXPORT_PATH = "/v1/memory/export";
 export const MEMORY_BUNDLE_IMPORT_PATH = "/v1/memory/import";
 const ExportRequestSchema = z.object({ scopes: z.array(z.string().min(1)).min(1) });
@@ -72,7 +72,7 @@ async function handleMemoryBundleBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/memory-compliance.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { ControlPlaneCorruptError } from "@sema-agent/core";
 import { erasureInputSmugglesPrototypeKey } from "../../memory-operator-faces.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 export const MEMORY_ERASE_PATH = "/v1/memory/erase";
 export const MEMORY_PROVENANCE_RE = /^\/v1\/memory\/entries\/([^/]+)\/provenance$/;
 const EraseRequestSchema = z.object({
@@ -61,7 +61,7 @@ async function handleMemoryComplianceBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/memory-consolidation.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ControlPlaneCorruptError } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 export const MEMORY_CONSOLIDATION_STATUS_PATH = "/v1/admin/memory/consolidation";
 export const MEMORY_CONSOLIDATION_RUN_PATH = "/v1/admin/memory/consolidation/run";
 const RunRequestSchema = z.object({ scope: z.string().optional() }).strict();
@@ -86,7 +86,7 @@ async function handleMemoryConsolidationBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/memory-origin.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { ControlPlaneCorruptError } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
 import { buildOriginFence, readOriginAware } from "../../memory-origin-fence.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 export const MEMORY_ORIGIN_EXTERNAL_PATH = "/v1/memory/origin/external";
 export const MEMORY_ORIGIN_CLEARANCES_PATH = "/v1/memory/origin/clearances";
 export const MEMORY_ORIGIN_CLEAR_RE = /^\/v1\/memory\/origin\/entries\/([^/]+)\/clear$/;
@@ -123,7 +123,7 @@ async function handleMemoryOriginBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/memory-policy.js

@@ -2,7 +2,7 @@ import { formatUserScope } from "@sema-agent/core";
 import { parseMemorySyncRequest } from "../../memory-sync.js";
 import { sendJson, sendError } from "../send.js";
 import { buildOriginFence, readOriginAware } from "../../memory-origin-fence.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 const ORG_PREFIX = "org:";
 export const MEMORY_EXPORT_MAX_LIMIT = 500;
 function encodeExportCursor(c) {
@@ -171,7 +171,7 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
     if (url === "/v1/policy" && req.method === "GET") {
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         sendJson(res, 200, {

package/dist/http/routes/notify-wake.js

@@ -1,6 +1,6 @@
 import { taskNotificationInboxEntry } from "../../orchestration/workflow-completion-inbox.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { sendResumeOutcome } from "../route-ctx.js";
 export const SESSION_WAKE_RE = /^\/v1\/sessions\/[^/]+\/wake$/;
 export async function handleNotifyWake(req, res, url, ctx) {
@@ -18,7 +18,7 @@ async function handleNotifyWakeBody(req, res, url, ctx, miss) {
             return;
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const notifySession = decodeURIComponent(url.split("/")[3]);
@@ -112,7 +112,7 @@ async function handleNotifyWakeBody(req, res, url, ctx, miss) {
             return;
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const wakeSession = decodeURIComponent(url.split("/")[3]);

package/dist/http/routes/observability.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, isOperator, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, isOperator, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 export async function handleObservability(req, res, url, ctx) {
     const miss = { fell: false };
     await handleObservabilityBody(req, res, url, ctx, miss);
@@ -34,7 +34,7 @@ async function handleObservabilityBody(req, res, url, ctx, miss) {
     if (url === "/v1/usage" && req.method === "GET") {
         const principal = gatedPrincipal(req, deps.config);
         if (!principal) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const windowSec = deps.config.costQuotaWindowSec;

package/dist/http/routes/retention-ops.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { RETENTION_AUDIT_DEFAULT_LIMIT, RETENTION_AUDIT_MAX_LIMIT } from "../../plugins/retention-lane-store-sql.js";
 const HOLD_RE = /^\/v1\/ops\/retention\/holds\/([^/]*)$/;
 const AUDIT_PATH = "/v1/ops/retention/audit";
@@ -40,7 +40,7 @@ async function handleRetentionBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {

package/dist/http/routes/run-memory-capture.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { isParkedRunStatus, isTerminalRunStatus } from "../../plugins/store-contracts.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal } from "../principal-gate.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage } from "../route-ctx.js";
 export const RUN_MEMORY_CAPTURE_OPTOUT_RE = /^\/v1\/runs\/([^/]+)\/memory\/capture-optout$/;
 const BodySchema = z.object({ reason: z.string().min(1).max(500).optional() }).strict();
@@ -25,7 +25,7 @@ async function handleBody(req, res, url, ctx, miss) {
     }
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && principal === undefined) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return;
     }
     const taskId = m[1];