@sema-agent/server 7.76.1 → 7.76.2

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,29 @@ 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;
 /** 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,20 @@ 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 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];

package/dist/http/routes/runs.js

@@ -23,7 +23,7 @@ import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
 import { readTurnActivityMs } from "../../turn-activity.js";
 import { mintCancelledResult } from "../../run-cancel-context.js";
 import { buildCrossSliceUsage, readResourceWindow } from "../../resource-window.js";
-import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { headerStr, gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { ActorAssertionWire } from "@sema-agent/settings-schema";
 import { mintAndDriveDurableRun } from "../durable-run-leg.js";
 import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage } from "../route-ctx.js";
@@ -82,7 +82,7 @@ export const RUN_TASK_STOP_RE = /^\/v1\/runs\/([^/]+)\/tasks\/([^/]+)\/stop$/;
 async function subagentReadGate(req, res, deps, runId) {
     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 null;
     }
     const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
@@ -197,7 +197,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         const taskId = runMatch[1];
         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 run = await deps.runStore.getRun(taskId);
@@ -279,7 +279,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             return;
         }
         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 taskId = cancelMatch[1];
@@ -407,7 +407,7 @@ async function handleRunsBody(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 = steerMatch[1];
@@ -686,7 +686,7 @@ async function handleRunsBody(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 = interruptMatch[1];
@@ -832,7 +832,7 @@ async function handleRunsBody(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 = compactMatch[1];
@@ -899,7 +899,7 @@ async function handleRunsBody(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 = detachMatch[1];
@@ -1117,7 +1117,7 @@ async function handleRunVerbsBody(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 runId = safeDecode(subVerbMatch[1]);
@@ -1214,7 +1214,7 @@ async function handleRunVerbsBody(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 id = elicitMatch[1];
@@ -1240,7 +1240,7 @@ async function handleRunVerbsBody(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 id = questionMatch[1];
@@ -1266,7 +1266,7 @@ async function handleRunVerbsBody(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 id = approvalMatch[1];
@@ -1303,7 +1303,7 @@ async function handleRunVerbsBody(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;
         }
         let rawBody;