@sema-agent/server 7.132.0 → 7.134.0

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

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { ServiceConfig } from "../config-types.js";
+import { type DurableOwnerKey, type Principal, type SessionCaller, type SessionOwnerCell } from "../security.js";
 /** Coerce a possibly-repeated request header to a single string (or undefined). */
 export declare function headerStr(v: string | string[] | undefined): string | undefined;
 export declare function safeEqual(a: string, b: string): boolean;
@@ -11,6 +12,9 @@ export declare function systemFor(req: IncomingMessage, config: ServiceConfig):
 /** "presented credentials must verify":Authorization 带 Bearer/token scheme 且三路全验不过 → true。
  *  其他 scheme(Basic 等,非我方凭证空间)不管——由原有门语义处置,避免误伤未知代理注头。 */
 export declare function bearerPresentedButUnverified(req: IncomingMessage, config: ServiceConfig): boolean;
+/** 「这次请求出示了这台部署的只读 trace 凭据(`TRACE_TOKEN`)」—— 一句,三处读:凭据验不过判({@link bearerPresentedButUnverified})、门前读路谓词
+ *  (`dispatch.ts` 的 `readCredentialOk`)、fleet 读档的只读臂({@link fleetViewOf})。没配 ⇒ 恒 false。 */
+export declare function traceTokenPresented(req: IncomingMessage, config: ServiceConfig): boolean;
 /** loopback 三形(IPv4 / IPv6 / IPv4-mapped)—— 一处定义,diagnostics 门与任何「本机自用」判据同吃。缺席 ⇒ false(fail-closed)。 */
 export declare function isLoopbackAddress(addr: string | undefined): boolean;
 /**
@@ -27,7 +31,7 @@ export type IdentitySource = (typeof IDENTITY_SOURCES)[number];
  * 有可验身份时才是身份,零凭据下它只是谁都能写的字符串;而 JWT 身份不依赖静态 token 的在场。
  */
 export declare function verifiedIdentitySource(req: IncomingMessage, config: ServiceConfig): IdentitySource | undefined;
-export declare function gatedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
+export declare function gatedPrincipal(req: IncomingMessage, config: ServiceConfig): Principal | undefined;
 /**
  * 「**出示了凭证但验不过** ≠ **没出示**」在 **direct-door principal JWT** 面上的形 —— 本仓
  * {@link bearerPresentedButUnverified} 早就是同一条律在 Bearer 面的形,这里只是把它推到另一面。
@@ -61,8 +65,8 @@ export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingM
  * 每面一句模块级常量(冻结门按常量解引用逐字钉)。三句都**不含任何值**(令牌 / 头名 / 路径实参一概不回显),且**不区分**
  * 「没带」与「带错」—— 同一道门上两者逐字同体,区分就是探测面。
  *  · `credential` —— 全局凭据门(`dispatch.ts`):部署配了 service token,请求没带或带的不认(registry 登录令牌验不过同属此面);
- *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):service token 开得了,指标口另认只读的
- *    `METRICS_TOKEN`(它在全局门之前判);
+ *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):不带主体头的 service token 开得了(带主体头的是那位主体,
+ *    {@link actsForDeployment}),指标口另认只读的 `METRICS_TOKEN`、`source-summary` 另认只读的 `TRACE_TOKEN`(都在全局门之前判);
  *  · `identity` —— 过了凭据门(或这台部署没配 service token)、但这一口要一个**验过的调用方身份**:属主寻址的读 / 写面、规则面、
  *    记忆面。在配了 service token 的部署上,「带 service token 却没身份」只会落在只认身份的口(规则 / 记忆 / 会话策略)上 ——
  *    这时再叫调用方「去带 service token」是假出路,所以这一面的句子只讲身份。
@@ -70,7 +74,7 @@ export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingM
  */
 export type UnauthorizedFace = "credential" | "operator" | "identity";
 export declare const UNAUTHORIZED_CREDENTIAL = "unauthorized \u2014 the request carries no credential this deployment accepts: send the deployment's service token as a Bearer token in the Authorization header (its operator set it as SERVICE_AUTH_TOKEN or SERVICE_AUTH_TOKENS; a sema-up deployment keeps SERVICE_AUTH_TOKEN in ~/.sema-up/<project>/.env on the machine that ran sema-up)";
-export declare const UNAUTHORIZED_OPERATOR = "unauthorized \u2014 this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header (the metrics endpoints also accept the read-only METRICS_TOKEN)";
+export declare const UNAUTHORIZED_OPERATOR = "unauthorized \u2014 this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header without a principal header (a service-token request that names a principal acts for that principal, not for the deployment), or a read-only token this endpoint accepts (METRICS_TOKEN for the metrics endpoints, TRACE_TOKEN for the task source summary)";
 export declare const UNAUTHORIZED_IDENTITY = "unauthorized \u2014 this endpoint acts for a named caller and the request carries no caller identity this deployment verifies: identify the caller the way this deployment does (a registry sign-in token as the Bearer token, a signed principal token on a direct-door deployment, or the principal header set by a trusted front end)";
 export declare function sendUnauthorized(res: ServerResponse, face: UnauthorizedFace): void;
 /**
@@ -91,7 +95,7 @@ export declare function sendUnauthorized(res: ServerResponse, face: Unauthorized
  * 放宽它是一次独立裁定。需要 operator 臂的读面在**自己的调用点**显式并上 {@link explicitOperatorOk} ——
  * 那样「谁多给了 operator 一条路」在代码上看得见,而不是被偷偷塞进共享谓词里。
  */
-export declare function runOwnerReadable(principal: string | undefined, owner: string | null, config: ServiceConfig): boolean;
+export declare function runOwnerReadable(principal: Principal | undefined, owner: DurableOwnerKey | null, config: Pick<ServiceConfig, "requirePrincipal">): boolean;
 /** 「这台部署配了任何一把 service 凭证吗」—— fail-closed 写门族的真值源,也是身份来源 `service_token` 接没接线的那一句。**单一属主**:`handle()` 的
  *  凭证门、[ref] 的 parked 赎回席、[ref] 的 consolidation 阀门启动期告警、以及下面 {@link wiredIdentitySources} 读同一句(手抄迟早只改一处,而这条判据
  *  决定的是「无凭证部署上写口开不开」)。住在本叶(与 {@link systemFor} 同处)而不是 `dispatch.ts`:身份原语只依赖本叶。 */
@@ -112,36 +116,83 @@ export declare function wiredIdentitySources(w: IdentityWiring): readonly Identi
  * 没配 service token、没装鉴权桥、没开直连门)、**也没声明**只读 trace token 或 `REQUIRE_PRINCIPAL`:请求里没有任何东西替主体头作保,头是谁都能自报的
  * **标签**(过滤 / 展示用),不是身份。装了鉴权桥的部署(SSO 单开)带登录令牌的调用方是验过的身份 ⇒ 不是 dev-open(修前只看 token / `REQUIRE_PRINCIPAL`,
  * 这一形被读成 dev-open,任何人 fleet-wide 读全部会话)。
- * 四处读它、不各写一份:会话列表的 fleet-wide 第一臂(`isFleetWide`)、会话写面的 fleet-wide 第一臂(`sessionOwnerScopeForWrite`)、
+ * 三处读它、不各写一份:fleet 调用方的第一臂({@link sessionCallerOf} —— fleet 面的 {@link fleetViewOf} 与会话行属主门都经它)、
  * 会话面的属主谓词({@link sessionOwnerReadable})、`/metrics` 族的免凭据臂(`dispatch.ts`)—— 于是「调用方是谁」在列表、单会话面与指标面上只有一只读法。
  */
 export declare function devOpenDeployment(w: IdentityWiring): boolean;
+/**
+ * service 凭据**代部署本身**说话:出示了这台部署的 service 凭据({@link systemFor}),且不代任何验过的主体。带主体头的 service 凭据请求是前端(BFF)
+ * 代那位主体发的 —— 它读那位主体,不读全舰队;部署姿态(单用户 / 多租)不改这一句(单用户形上的主体头同样是「这次请求为谁」)。
+ * 两处读它:fleet 调用方的凭据臂({@link sessionCallerOf})与 `/metrics` 族的 service 臂(`dispatch.ts`)。先判凭据、后取主体:`principal` 只在出示了
+ * service 凭据时才求值(调用点那一次 {@link gatedPrincipal}),没带凭据的请求不因主体头的形而改答。
+ */
+export declare function actsForDeployment(req: IncomingMessage, config: ServiceConfig, principal: () => Principal | undefined): boolean;
+/**
+ * 🔴 **「这个调用方是不是 fleet 调用方(看得到所有租户)」的唯一铸点**({@link SessionCaller}):验过的主体 + 是不是 fleet —— {@link devOpenDeployment} 上的任何
+ * 调用方,或 {@link actsForDeployment}(出示 service 凭据、不报主体)。带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据;operator 不在这里
+ * (运维口各自读 {@link explicitOperatorOk})。读者:会话行属主门(无主 placed 行的放行臂)与 fleet 面的 {@link fleetViewOf} —— 同一问一只读法。
+ */
+export declare function sessionCallerOf(req: IncomingMessage, w: IdentityWiring): SessionCaller;
+/** fleet 面的两档(闭集):`read` = 只读面,只读 trace 凭据在这一档也是 fleet;`write` = 写面,只认 {@link sessionCallerOf}(读凭据不能变成跨租户写权)。 */
+export type FleetFace = "read" | "write";
+/** 一次 fleet 面判定的读数:`fleetWide` = 看全舰队(不钉人);否则 `gateOwner` = 钉住的那位验过的主体,`null` = 没有可用身份(调用点答 401 identity)。 */
+export interface FleetView {
+    readonly fleetWide: boolean;
+    readonly gateOwner: Principal | null;
+}
+/**
+ * 🔴 **fleet 面「看全舰队,还是钉住一位主体」的唯一读法**。fleet 判据只有一个来源 —— {@link sessionCallerOf};本函数只把它投成 fleet 面要的两格,
+ * 并按档并上只读 trace 凭据(读档)。读者 —— 读档:舰队流、会话列表、发件链接列表、后台名册、trace 五口、用量三口、`/v1/tasks/source-summary`;
+ * 写档:删除、fork、同步族(拉取与推送同门)。
+ */
+export declare function fleetViewOf(req: IncomingMessage, w: IdentityWiring, face: FleetFace): FleetView;
 /**
  * **「这个调用方能不能动这只会话」的唯一谓词**(会话面:视图 / head / 事件流 / 记忆状态与自助抹除 / 改名置顶 / 后台任务 / MCP 重连 /
- * 面板的上一腿 MCP 投影)。= {@link devOpenDeployment} ∨ {@link runOwnerReadable}:没有身份边界的部署上不钉任何人(与会话列表同读,
- * 列表把这只会话列给谁,谁就读得到它);有身份边界的部署上就是 run 面那一条谓词,一字不变。
+ * 面板的上一腿 MCP 投影)。没有身份边界的部署({@link devOpenDeployment})上不钉任何人(与会话列表同读,列表把这只会话列给谁,谁就读得到它);
+ * 有身份边界的部署上:
+ *  · **无主的行**经无主臂的唯一判据 `ownerlessRowOpen`(`security.ts`):普通会话照旧对任何调用方开放;委派子代的 placed 行只对 fleet 调用方
+ *    ({@link sessionCallerOf})开放 —— 任何具名主体、没有 service 凭据的无身份调用方都与别人的行同体(调用点答 404)(S-1770)。
+ *    代价如实:属主还没定下的子代行连它将来的属主也暂时读不到(由一次性迁移 M23 / 那一行的下一次停驻定下);
+ *  · 有主的行就是 run 面那一条谓词({@link runOwnerReadable}),一字不变。
  * run 面(poll / events / cancel …)不读本谓词 —— 那是 run 资源的门,另一只。
  */
-export declare function sessionOwnerReadable(principal: string | undefined, owner: string | null, w: IdentityWiring): 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.
- *  🔴 SINGLE mint point (E1): a byte-identical twin `explicitOperator` used to live below (image-visibility lane)
- *  and two more hand-inlined copies sat in approvals-assistant — a future hardening of this judgment would have
- *  missed them. All call sites now consume THIS function; do not re-introduce a sibling. */
-export declare function explicitOperatorOk(principal: string | undefined, operatorPrincipals: readonly string[]): boolean;
+export declare function sessionOwnerReadable(caller: SessionCaller, cell: SessionOwnerCell, w: IdentityWiring): boolean;
+/**
+ * 运维名册 —— 「谁是 operator」读的两格(都住在部署配置里):具名名单 `OPERATOR_PRINCIPALS` 与单用户形的显式声明 `OPERATOR_SINGLE_USER`。
+ * 两者互斥(声明只在单用户形、名单为空时成立;否则拒启 —— 一个事实一个来源,`config-invariants.ts` 的 `operator-single-user`)。
+ */
+export type OperatorRoster = Pick<ServiceConfig, "operatorPrincipals" | "operatorSingleUser">;
+/**
+ * 🔴 **「谁是 operator」的唯一读法**(S-1050,[ref] ① 裁 A;IMAGE-API-DESIGN.md §P2.4a MUST-FIX 的那一只门)。
+ *  · 名单为空 ⇒ **没人是**(没有任何形把「空名单」读成「人人是」—— 那条读法 `isOperator` 已删);
+ *  · 名单非空 ⇒ 验过的主体在名单里才是;
+ *  · 单用户形显式声明 `OPERATOR_SINGLE_USER=true` ⇒ 这台部署的**每个调用方**都是(单用户形只有一位用户,能到这台部署的就是他;边界是部署自己的
+ *    凭据门 —— 没配凭据的部署上,能连上端口的都是)。声明只在单用户形成立(起服不变量)。
+ * `principal` 必须是验过的身份(`gatedPrincipal`),绝不是自述头。全部运维面(审批队列、steer.trusted、记忆运维口、bake 门……)读这一只;
+ * 🔴 SINGLE mint point (E1):不要再造兄弟。
+ */
+export declare function explicitOperatorOk(principal: string | undefined, roster: OperatorRoster): boolean;
+/** 「这台部署**有没有**运维」的唯一读法(名单非空 ∨ 单用户声明在场)—— 能力事实 `operatorLane`、整理阀门的可达性告警、起服提示同读这一只。 */
+export declare function operatorRosterPresent(roster: OperatorRoster): boolean;
+/**
+ * 起服提示(S-1050):单用户形(`REQUIRE_PRINCIPAL` 未开)+ 没有运维名册 + 这台部署有审批底座 ⇒ 一行 warn。这一形在「空名单 = 人人是」那条读法退役之后
+ * 丢的东西就是审批队列的运维视图(跨 scope 列表 / `?owner=` / 无主体调用方的整个队列),补回它只要一行配置 —— 不拒启:升级那一拍打掉一台今天跑得好好的
+ * 单用户机器比一条提示重。多租形不提示(它另有拒启不变量);没有审批底座的形什么都没少。
+ */
+export declare function buildOperatorUndeclaredNotice(config: OperatorRoster & Pick<ServiceConfig, "requirePrincipal">, approvalFaceWired: boolean): {
+    event: "operator_undeclared_single_user";
+    fields: {
+        detail: string;
+    };
+} | undefined;
 /** operator 面族在「名单为空」这一形上的**唯一**拒发口:事实 `operatorLane`(`capability-facts.ts`)为假 ⇒ 这一面对任何
  *  身份都打不通 = 这台部署上不可用 ⇒ 501,不是鉴权拒(403 只留给「名单非空而你不在名单上」)。能力位读的是同一只事实。 */
 export declare function sendOperatorPrincipalsRequired(res: ServerResponse): void;
-/** May `principal` act as an OPERATOR on the F4 approval queue? Empty `operatorPrincipals` = legacy
- *  behavior (the shared service token IS the operator boundary → everyone authenticated is an operator).
- *  Otherwise only listed principals are operators. */
-export declare function isOperator(principal: string | undefined, operatorPrincipals: readonly string[]): boolean;
-/** Operator check WITHOUT the empty-list "everyone is an operator" legacy fallback — an EMPTY `operatorPrincipals`
- *  yields `false` (no one is an operator). Use this where empty-operators-means-all would be a SECURITY hole rather
- *  than a back-compat convenience: image VISIBILITY scoping (a tenant-scoped image must not leak to every caller
- *  just because OPERATOR_PRINCIPALS is unset). Adversarial-review HIGH: `isOperator([], p)=true` made
- *  `latestPublished(..., {operator:true})` bypass tenant visibility for any caller on an operator-less deployment.
- *  (The byte-identical `explicitOperator` twin that used to live here was folded into `explicitOperatorOk` above —
- *  one judgment, one mint point.) */
+/**
+ * 「这台部署没有运维名册」时**唯一**的出路句 —— 与 {@link operatorRosterPresent} 同一对旋钮,所以句子不比事实少说一条出路:
+ * 名单 `OPERATOR_PRINCIPALS`(具名运维;多租形只有这一条),或单用户形的显式声明 `OPERATOR_SINGLE_USER=true`(只在 `REQUIRE_PRINCIPAL` 未开且名单为空时成立,
+ * 否则起服拒 —— 句子把它限定在单用户部署上)。拒发口 {@link sendOperatorPrincipalsRequired}、能力事实闭集 `operator_principals_empty` 的义、记忆整理阀门的起服告警
+ * 都说这一句,别处不再各写一份。
+ */
+export declare function buildOperatorRosterWayOut(): string;
 //# sourceMappingURL=principal-gate.d.ts.map

package/dist/http/principal-gate.js

@@ -1,5 +1,5 @@
 import { timingSafeEqual } from "node:crypto";
-import { PRINCIPAL_TOKEN_HEADER, verifiedPrincipal, ssoVerifiedPrincipal } from "../security.js";
+import { PRINCIPAL_TOKEN_HEADER, verifiedPrincipal, ssoVerifiedPrincipal, ownerlessRowOpen, mintPrincipal } from "../security.js";
 import { sendError } from "./send.js";
 export function headerStr(v) {
     return Array.isArray(v) ? v[0] : v;
@@ -30,10 +30,13 @@ export function bearerPresentedButUnverified(req, config) {
         return false;
     if (systemFor(req, config) !== undefined)
         return false;
-    if (config.traceToken && authorized(req, config.traceToken))
+    if (traceTokenPresented(req, config))
         return false;
     return true;
 }
+export function traceTokenPresented(req, config) {
+    return !!config.traceToken && authorized(req, config.traceToken);
+}
 export function isLoopbackAddress(addr) {
     return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
 }
@@ -50,7 +53,8 @@ export function verifiedIdentitySource(req, config) {
 export function gatedPrincipal(req, config) {
     if (bearerPresentedButUnverified(req, config))
         return undefined;
-    return verifiedPrincipal(req, config);
+    const verified = verifiedPrincipal(req, config);
+    return verified === undefined ? undefined : mintPrincipal(verified);
 }
 export function principalTokenPresentedButUnverified(req, config) {
     if (!config.directDoorActive)
@@ -67,7 +71,7 @@ export function sendPrincipalRefusal(res, req, config) {
     sendError(res, 401, "auth.principal_required", `missing principal header '${config.principalHeader}'`);
 }
 export const UNAUTHORIZED_CREDENTIAL = "unauthorized — the request carries no credential this deployment accepts: send the deployment's service token as a Bearer token in the Authorization header (its operator set it as SERVICE_AUTH_TOKEN or SERVICE_AUTH_TOKENS; a sema-up deployment keeps SERVICE_AUTH_TOKEN in ~/.sema-up/<project>/.env on the machine that ran sema-up)";
-export const UNAUTHORIZED_OPERATOR = "unauthorized — this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header (the metrics endpoints also accept the read-only METRICS_TOKEN)";
+export const UNAUTHORIZED_OPERATOR = "unauthorized — this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header without a principal header (a service-token request that names a principal acts for that principal, not for the deployment), or a read-only token this endpoint accepts (METRICS_TOKEN for the metrics endpoints, TRACE_TOKEN for the task source summary)";
 export const UNAUTHORIZED_IDENTITY = "unauthorized — this endpoint acts for a named caller and the request carries no caller identity this deployment verifies: identify the caller the way this deployment does (a registry sign-in token as the Bearer token, a signed principal token on a direct-door deployment, or the principal header set by a trusted front end)";
 export function sendUnauthorized(res, face) {
     switch (face) {
@@ -86,10 +90,13 @@ export function sendUnauthorized(res, face) {
         }
     }
 }
+function sameIdentity(principal, owner) {
+    return principal === owner;
+}
 export function runOwnerReadable(principal, owner, config) {
     if (owner === null)
         return true;
-    if (principal === owner)
+    if (principal !== undefined && sameIdentity(principal, owner))
         return true;
     return !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
 }
@@ -116,18 +123,61 @@ export function wiredIdentitySources(w) {
 export function devOpenDeployment(w) {
     return wiredIdentitySources(w).length === 0 && !w.config.traceToken && !w.config.requirePrincipal;
 }
-export function sessionOwnerReadable(principal, owner, w) {
-    return devOpenDeployment(w) || runOwnerReadable(principal, owner, w.config);
+export function actsForDeployment(req, config, principal) {
+    return systemFor(req, config) !== undefined && principal() === undefined;
 }
-export function explicitOperatorOk(principal, operatorPrincipals) {
-    return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
+export function sessionCallerOf(req, w) {
+    const principal = gatedPrincipal(req, w.config);
+    return { principal, fleet: devOpenDeployment(w) || actsForDeployment(req, w.config, () => principal) };
 }
-export function sendOperatorPrincipalsRequired(res) {
-    sendError(res, 501, "capability.operator_principals_required", "this endpoint is operator-only and OPERATOR_PRINCIPALS is empty, so no caller can be an operator on this deployment; configure OPERATOR_PRINCIPALS to enable it");
+export function fleetViewOf(req, w, face) {
+    const caller = sessionCallerOf(req, w);
+    const fleetWide = caller.fleet || readOnlyFleetCredential(req, w.config, face);
+    return { fleetWide, gateOwner: fleetWide ? null : caller.principal || null };
+}
+function readOnlyFleetCredential(req, config, face) {
+    switch (face) {
+        case "read":
+            return traceTokenPresented(req, config);
+        case "write":
+            return false;
+        default: {
+            const unknownFace = face;
+            throw new Error(`fleetViewOf: unknown fleet face ${String(unknownFace)}`);
+        }
+    }
 }
-export function isOperator(principal, operatorPrincipals) {
-    if (operatorPrincipals.length === 0)
+export function sessionOwnerReadable(caller, cell, w) {
+    if (devOpenDeployment(w))
         return true;
-    return principal !== undefined && operatorPrincipals.includes(principal);
+    if (cell.owner === null)
+        return ownerlessRowOpen(cell, caller);
+    return runOwnerReadable(caller.principal, cell.owner, w.config);
+}
+export function explicitOperatorOk(principal, roster) {
+    if (roster.operatorSingleUser === true)
+        return true;
+    return roster.operatorPrincipals.length > 0 && principal !== undefined && roster.operatorPrincipals.includes(principal);
+}
+export function operatorRosterPresent(roster) {
+    return roster.operatorSingleUser === true || roster.operatorPrincipals.length > 0;
+}
+export function buildOperatorUndeclaredNotice(config, approvalFaceWired) {
+    if (config.requirePrincipal === true || operatorRosterPresent(config) || !approvalFaceWired)
+        return undefined;
+    return {
+        event: "operator_undeclared_single_user",
+        fields: {
+            detail: "this single-user deployment declares no operator: OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not set, so no caller is an operator — " +
+                "GET /v1/approvals, its stream, /v1/assistant/inbox and /v1/assistant/tasks show each caller only its own pending approvals (a caller that sends no principal sees only the anonymous ones - the cards and tasks that were submitted without a principal - never a named principal's) and ignore ?owner=. " +
+                "To act as this deployment's operator, add one line: OPERATOR_SINGLE_USER=true",
+        },
+    };
+}
+export function sendOperatorPrincipalsRequired(res) {
+    sendError(res, 501, "capability.operator_principals_required", `this endpoint is operator-only and this deployment has no operator roster (OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not declared), so no caller can be an operator; ${buildOperatorRosterWayOut()}`);
+}
+export function buildOperatorRosterWayOut() {
+    return "configure OPERATOR_PRINCIPALS with the named operator principals, or — on a single-user deployment (REQUIRE_PRINCIPAL off) — declare OPERATOR_SINGLE_USER=true";
 }
 //# sourceMappingURL=principal-gate.js.map

package/dist/http/readiness.d.ts

@@ -23,6 +23,7 @@
  */
 import type { ServerResponse } from "node:http";
 import type { ServingLeaseView } from "../fleet/engine-signal.js";
+import { type RefusalBody } from "./refusal-body.js";
 /**
  * 就绪原因闭集,**数组序 = 优先序**:`/health.readyReason` 取首条的句、计费门取首条的拒绝码。
  * draining 在前 —— 一台正在下线的副本「去找替补」(Retry-After 15)比「稍后重试本机」(5)更对。
@@ -86,11 +87,8 @@ export declare function admissionRefusalOf(verdict: ReadinessVerdict, lease: Ser
  *  `{status, body}` 的赎回席只取体(它的路由刻意不带头,见 `approval-sweeps.ts` 该臂注)。 */
 export interface BillableRefusal {
     readonly status: 503;
-    readonly body: {
-        readonly error: string;
-        readonly errorCode: string;
-        readonly message: string;
-    };
+    /** `error` 是冻结的词(`draining` / `model_roster_pending` / `lease_expired`),`message` 是给人读的句子(机读事实里的一键)。 */
+    readonly body: RefusalBody;
     readonly retryAfterSec: 15 | 5 | 60;
 }
 /**
@@ -100,6 +98,14 @@ export interface BillableRefusal {
  * 停机因由声明口一起退役(排空口的体改成契约 `DrainRequest`,没有因由字段);`lease_expired` 一臂新增。
  */
 export declare function billableRefusalOf(reason: AdmissionRefusal): BillableRefusal;
+/**
+ * 订阅面终帧要的 `{ errorCode, message }` —— 与提交面 503 体**同一只铸点**的产物:`errorCode` 是体的码,`message` 是体里 `message` 键的那句话(`error` 是冻结的词,
+ * 句子在 `message`)。从体里读,不另抄一份;体里没有那句话是铸点坏了 ⇒ 响亮抛(不静默发一帧没有句子的终帧)。
+ */
+export declare function billableRefusalFrame(refusal: BillableRefusal): {
+    readonly errorCode: string;
+    readonly message: string;
+};
 /** 发送形:`Retry-After` + 体(`dispatch.ts` 的 billable 门与 a2a `message/send` 同调)。走 `sendError` —— errorCode
  *  是它的必填位置参(对抗复审 #3:修前这里是 `sendJson(res, r.status, r.body)`,与 leader 口的豁免行逐字同文,
  *  在 error-code-key-gate 上借了别人的豁免过门);体键序与修前逐字同(`error, errorCode, message, reason?`)。 */

package/dist/http/readiness.js

@@ -1,4 +1,5 @@
 import { sendJson, sendError } from "./send.js";
+import { refusalBody } from "./refusal-body.js";
 export const READINESS_REASONS = ["draining", "model_roster_pending"];
 export function readinessOf(deps) {
     const [first, ...rest] = READINESS_REASONS.filter((r) => holds(r, deps));
@@ -60,17 +61,23 @@ export function admissionRefusalOf(verdict, lease, kind) {
 export function billableRefusalOf(reason) {
     switch (reason) {
         case "draining":
-            return { status: 503, body: { error: "draining", errorCode: "draining", message: "this instance is draining for shutdown/upgrade — retry against the replacement instance" }, retryAfterSec: 15 };
+            return { status: 503, body: refusalBody({ errorCode: "draining", message: "draining", facts: { message: "this instance is draining for shutdown/upgrade — retry against the replacement instance" } }), retryAfterSec: 15 };
         case "model_roster_pending":
-            return { status: 503, body: { error: "model_roster_pending", errorCode: "state.model_roster_pending", message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" }, retryAfterSec: 5 };
+            return { status: 503, body: refusalBody({ errorCode: "state.model_roster_pending", message: "model_roster_pending", facts: { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" } }), retryAfterSec: 5 };
         case "lease_expired":
-            return { status: 503, body: { error: "lease_expired", errorCode: "state.lease_expired", message: "this instance has not renewed its serving lease with the fleet center for longer than its outage limit — it takes no new work; cancel, approvals, resume and reads stay open here — retry new work against another instance" }, retryAfterSec: 60 };
+            return { status: 503, body: refusalBody({ errorCode: "state.lease_expired", message: "lease_expired", facts: { message: "this instance has not renewed its serving lease with the fleet center for longer than its outage limit — it takes no new work; cancel, approvals, resume and reads stay open here — retry new work against another instance" } }), retryAfterSec: 60 };
         default: {
             const unhandled = reason;
             throw new Error(`admission refusal without a billable refusal: ${String(unhandled)}`);
         }
     }
 }
+export function billableRefusalFrame(refusal) {
+    const message = refusal.body["message"];
+    if (typeof message !== "string")
+        throw new Error(`billable refusal body without its message sentence: ${refusal.body.errorCode}`);
+    return { errorCode: refusal.body.errorCode, message };
+}
 export function sendBillableRefusal(res, refusal) {
     const { error, errorCode, ...extra } = refusal.body;
     res.setHeader("retry-after", String(refusal.retryAfterSec));

package/dist/http/refusal-body.d.ts

@@ -18,4 +18,16 @@ export type RefusalBody = {
 } & Record<string, unknown>;
 /** 拒体:`{ error, errorCode, ...facts }`。 */
 export declare function refusalBody(r: Refusal): RefusalBody;
+/**
+ * 引擎拒一次续跑时的**三个机读判别位** → 拒体的同名事实键(唯一读法;续跑家族的每一只拒答都读它):
+ * `detail.code` ⇒ `blockedBy`(挡住它的准入码)· `detail.field` ⇒ `field`(哪一侧 / 哪一格)· `detail.reason` ⇒ `reason`(同码多臂时哪一臂)。
+ * 一员在场 ⇔ 它是非空串;其余(缺席、非串、空串)一律不铸键 —— 引擎没说就是没说,本层不编值,也不把一个非串原样推上 wire。
+ * 载体有两种,读法同一只:同步腿的 `CheckpointError.detail`(`http/resume-legs.ts` `checkpointRefusalAnswer`),与后台停驻子代赎回回执的
+ * `details.detail`(`parked-decide.ts` 的 422 `parked_resume.startup_failed`;引擎 7.54.0 起它把认领前那只失败的同三位交到回执上)。
+ */
+export declare function resumeRefusalFacts(detail: unknown): {
+    blockedBy?: string;
+    field?: string;
+    reason?: string;
+};
 //# sourceMappingURL=refusal-body.d.ts.map

package/dist/http/refusal-body.js

@@ -1,4 +1,15 @@
 export function refusalBody(r) {
     return { error: r.message, errorCode: r.errorCode, ...r.facts };
 }
+export function resumeRefusalFacts(detail) {
+    if (typeof detail !== "object" || detail === null)
+        return {};
+    const d = detail;
+    const word = (v) => typeof v === "string" && v !== "";
+    return {
+        ...(word(d.code) ? { blockedBy: d.code } : {}),
+        ...(word(d.field) ? { field: d.field } : {}),
+        ...(word(d.reason) ? { reason: d.reason } : {}),
+    };
+}
 //# sourceMappingURL=refusal-body.js.map

package/dist/http/request-guards.d.ts

@@ -4,6 +4,8 @@
  * ctx 字段 1 只(`deps`):本族对外围的耦合就这一格,它也是这一族的可测性读数。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type SessionOwnerCell } from "../security.js";
+import { type RefusalBody } from "./refusal-body.js";
 import type { FlatServiceDeps } from "./server.js";
 import type { LeaseRefusalAdmission } from "../fleet-lease.js";
 import { type QuotaDecision } from "../observability/cost-quota.js";
@@ -18,6 +20,13 @@ import { type SqlWallSource, type SqlWallsReading } from "../plugins/sql-driver.
  * 两腿的折算与 SQL 快照 blob 的缺省帽读同一份(`plugins/sql-driver.ts`,余量各只在那里定义一次)。两腿都拒时报行墙那条(行墙句逐字沿用)。
  * 入参是**已判好的墙**(`sql-driver.ts` `sqlWallsOf` —— 事实缺席时的落点只在那里定义,与 blob 帽同一只判官、同一个方向);本函数不读事实、不判缺席,
  * 墙从哪来(`sources` 里**被拒的那一堵**的出处)原样带进判决(`wallSource`),拒句按它分两形:库报的墙点名库的上限与旋钮,假定的墙(事实还没建立,或事实在场但这一堵读失败、退了文档缺省)只说「库的这个上限没读到、按最保守的墙拒」。
+ *
+ * 🔴 **包墙腿是同一只规则的提前一跑,不是第二套规则**(S-1746 主会话裁定):包墙是物理连接的事实(会话值,连接建立时从全局拷一份、此后不变),
+ * 终判在将要执行写入的那条连接上 —— 那是库自己(续跑输入那一笔被拒 ⇒ 店的带码拒 ⇒ 同一个 413;会话日志那一笔走它既有的失败面);SQL 快照 blob 则由
+ * `blob-backend.ts` 经 `connectJudged` 在写入连接上判。受理时手里没有那条连接,判官 `sqlWallsOf` 读的 `facts` 是池里**最近一次初始化**的那条连接的读数
+ * (`SqlDriver.facts`:池见过的最新读数,只在有连接初始化时才更新),同一个折算 `packetWallStatementBytes`:拒 ⇒ 413 在任何副作用之前;收 ⇒ 写入那条连接上的判决仍是终判。
+ * 这个读数是**缓存**,DBA 调了全局值之后、下一条连接初始化之前,它与库此刻的值两个方向都可能不一致:调大 ⇒ 受理口仍按旧的小值拒(新墙本装得下的体也 413,
+ * 直到有连接按新值初始化 —— 快照 blob 的旧连接自换就会带来一条);调小 ⇒ 受理口按旧的大值放行,写入那条连接上的库再拒(续跑输入那一笔 = 同一个 413)。
  * 两堵墙都不存在(PG / 没有 SQL 后端)⇒ `null`。一堵墙「够不着」(行墙门限 ≥ 请求体上限;包墙门限 ≥ 请求体上限的 2×,即转义上界也到不了)时那一腿不量,
  * 两腿都够不着就连 `JSON.stringify` 都不调 —— 默认的 PG / MySQL 8(包墙 64 MiB)/ 无 SQL 后端部署零额外开销。
  * 受理口(`admission.ts` `prepareSpec`)按它答 413 `request.payload_too_large`,句子按 `by` × `wallSource` 点名真正拒绝的那堵墙;两位都是闭集,加一臂 = 编译红。
@@ -36,16 +45,11 @@ export interface SubmitBodyRefusal {
 export declare function refuseSubmitBody(walls: SqlWallsReading, body: unknown): SubmitBodyRefusal | null;
 /**
  * S-866 ③ —— 租约拒绝的应答形({@link leaseRefusalOf} 的产物;`{status, body}` 交回形 + 镜像头用的 `retryAfterSec`)。
- * 体键序固定 `error, errorCode, …`(冻结门 `FROZEN_RESULT_BODY` 按这个字面形锚)。
+ * 体经唯一组句器铸(键序 `error, errorCode, …机读位`;冻结门 `FROZEN_RESULT_BODY` 读 `refusalBody({ errorCode, message, … })` 这一形)。
  */
 export interface LeaseRefusal {
     readonly status: 429 | 503;
-    readonly body: {
-        readonly error: string;
-        readonly errorCode: string;
-        readonly retryAfterSec: number;
-        readonly [extra: string]: unknown;
-    };
+    readonly body: RefusalBody;
     readonly retryAfterSec: number;
 }
 /**
@@ -60,20 +64,13 @@ export interface LeaseRefusal {
 export declare function leaseRefusalOf(adm: LeaseRefusalAdmission): LeaseRefusal;
 /**
  * 成本配额越顶 → 429 `limit.cost_quota_exceeded` 的**唯一**体铸点(三只门同调:路由门 `quotaExceeded`、属主门
- * `ownerCostQuotaDenied`、赎回席 `approval-sweeps.ts`;修前三份手抄)。体键序 `error, errorCode, …`(冻结门
- * `FROZEN_RESULT_BODY` 按这个字面形锚)。`retryAfterSec` 与 `windowResetsAt` 同源于决策的 `windowEndsAtMs`
+ * `ownerCostQuotaDenied`、赎回席 `approval-sweeps.ts`;修前三份手抄)。体经唯一组句器铸(键序 `error, errorCode, …机读位`;冻结门
+ * `FROZEN_RESULT_BODY` 读 `refusalBody({ errorCode, message, … })` 这一形)。`retryAfterSec` 与 `windowResetsAt` 同源于决策的 `windowEndsAtMs`
  * (同一次读钟),`Retry-After` 头由各发送点从体里的 `retryAfterSec` 镜像。
  */
 export declare function costQuotaRefusalOf(d: QuotaDecision): {
     status: 429;
-    body: {
-        error: string;
-        errorCode: string;
-        usedMicroUsd: number;
-        limitMicroUsd: number;
-        retryAfterSec: number;
-        windowResetsAt: string;
-    };
+    body: RefusalBody;
 };
 export declare function createRequestGuards(ctx: {
     deps: FlatServiceDeps;
@@ -92,27 +89,14 @@ export declare function createRequestGuards(ctx: {
     leaseDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
     usageWindowDenialFor: (key: string) => Promise<{
         status: number;
-        body: {
-            error: string;
-            errorCode: string;
-            retryAfterSec: number;
-        };
+        body: RefusalBody;
         retryAfterSec: number;
     } | undefined>;
     usageWindowDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
     rateLimited: (req: IncomingMessage, res: ServerResponse) => boolean;
     safeDecode: (seg: string) => string | null;
-    isFleetWide: (req: IncomingMessage) => boolean;
-    sessionOwnerScope: (req: IncomingMessage) => {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
-    sessionOwnerScopeForWrite: (req: IncomingMessage) => {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
     runOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null) => boolean;
-    sessionOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null) => boolean;
+    sessionOwnerOk: (req: IncomingMessage, res: ServerResponse, cell: SessionOwnerCell) => boolean;
     runSessionAcceptOk: (req: IncomingMessage, res: ServerResponse, run: {
         sessionId: string | null;
     }, face: string, notFoundError?: string) => boolean;