@sema-agent/server 7.132.0 → 7.133.0

package/dist/http/durable-run-leg.d.ts

@@ -1,35 +1,6 @@
-/**
- * **一条 durable run 的「建行 + 驱动」单一属主**(S-218 提取;此前整段住在 `routes/runs.ts` 的
- * `createDurableRun` 里,只服务 HTTP/A2A 两条提交门)。
- *
- * 🔴 为什么提成模块:`/decide` 的 workflow 第三条车道在**宿主不在 park 上**时,同样要在宿主会话上起
- * 一跑新 turn 把决定交给宿主的模型(S-218)。这条链上挂着 `createRun` 的会话 claim(以及它唯一诚实的
- * 409 出路)、checkpoint ctx 落库、fleet 行发布、resume/rewind 两族锚点捕获、审批 ALS、通告投递……
- * 手抄第二份 = 把这十来件事复制成两份会漂的实现,而漂开的那天没有任何东西会说话(`createDurableRun`
- * 当年从路由体里提取出来时,头注写的就是同一条判词)。方向:`routes/runs.ts` 与 `http/server.ts`
- * 都 import 本模块,本模块谁都不 import —— 与 `http/run-meta.ts` 同一条「两个域共用一件 ⇒ 单独成文件」。
- *
- * 边界(本腿**不**含的东西,留给各自的门):同键重放的回执(`http/submit-replay.ts`)、`Idempotency-Key` 的在飞合流、
- * lease / 治理窗 pre-admission、属主门。它们是**提交面**的判据(读请求、写响应),而本腿只吃已经备好的
- * `PreparedTaskSubmission` 并交回一份收据 —— 这正是它能被一条没有 `ServerResponse` 的内部车道复用的原因。
- */
-import { type RunInternals } from "@sema-agent/core";
 import type { RunStore } from "../plugins/store-backend.js";
 import type { RunIdemBinding, RunRecord } from "../plugins/store-contracts.js";
-import type { PreparedTaskSubmission, RouteCtxBase } from "./route-ctx.js";
-/**
- * 🔴 **TRUSTED run internals** —— 由**部署方**(不是模型、不是请求体、不是工具参数)铸给这一跑的
- * core 内部席位。今天唯一成员 `workflowParkedResume` = 人对一条 parked workflow 子代的决定
- * (语义属主 = core `RunInternals.workflowParkedResume` 的 d.ts 顶注:「A host that decided a workflow
- * child's parked checkpoint launches the run that re-invokes `Workflow({resumeFromRunId})` with the
- * decision here」)。
- *
- * 为什么单独命名而不是直接摊 `RunInternals`:`RunInternals` 里绝大多数席位是**执行腿自己**铸的
- * (onForwardEvent / onTaskNotification / onActivity …),把整只类型开给调用方等于邀请第二个写者;
- * 本类型只开「部署方可以决定的那一格」,新增一格时**必须**在这里显式点名,编译期看得见。
- * 缺席 ⇒ 对两条腿都是完整 no-op。
- */
-export type TrustedRunInternals = Pick<RunInternals, "workflowParkedResume">;
+import type { PreparedTaskSubmission, RouteCtxBase, WorkflowDecisionDelivery } from "./route-ctx.js";
 export interface DurableRunLegArgs {
     /** `prepareSpec` 的产物,或内部车道按同一条 `resolveSpec` 装配出来的等价形。 */
     prepared: PreparedTaskSubmission;
@@ -49,8 +20,9 @@ export interface DurableRunLegArgs {
     elicitOwner: string | null;
     /** run 行元数据的 `source` 列(调用方的系统身份;内部车道传自己的车道名)。 */
     source: string | null;
-    /** 见 {@link TrustedRunInternals}。缺席 ⇒ 与本位存在之前逐字相同。 */
-    trustedInternals?: TrustedRunInternals;
+    /** `/decide` 第三条车道的 fresh 投递腿交来的那一件决定投递(带着的决定 + 起跑之前落行的那一笔;语义与 TRUSTED 纪律的属主 =
+     *  `route-ctx.ts` 的 {@link WorkflowDecisionDelivery} 顶注)。缺席 ⇒ 只摊本会话已受理的决定行。 */
+    workflowDecision?: WorkflowDecisionDelivery;
 }
 /**
  * 本腿的结局:一份收据,或「这次提交的一把幂等钥匙已经指向一条行」(店的原子赢或观察的**观察**臂 —— 本腿不碰

package/dist/http/durable-run-leg.js

@@ -1,5 +1,6 @@
 import { uuidv7 } from "@sema-agent/core";
-import { runInBackground } from "../runs.js";
+import { heldWorkflowParkDecisions } from "../parked-decide.js";
+import { HEARTBEAT_MS, runInBackground } from "../runs.js";
 import { fleetRunPublisher, fleetRunLabels } from "../fleet/fleet-bus.js";
 import { cascadeConfig, runMeta } from "./run-meta.js";
 import { resolveStreamApprovalGate } from "../tool-approval.js";
@@ -9,12 +10,14 @@ import { commitSessionInheritEnv } from "./session-inherit-env.js";
 import { clearTurnActivity, readTurnActivityMs } from "../turn-activity.js";
 import { recordResourceWindow } from "../resource-window.js";
 import { persistSubmitCtx } from "./submit-ctx.js";
+import { releaseClaimedRun } from "./claimed-run.js";
 import { serviceVersion } from "../service-version.js";
 export async function mintAndDriveDurableRun(ctx, runStore, args) {
     const { deps } = ctx;
     const { inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
     const sessionId = args.prepared.spec.sessionId ?? uuidv7();
     const taskId = args.clientTaskId ?? uuidv7();
+    const trustedInternals = await heldWorkflowParkDecisions(deps, sessionId, args.workflowDecision?.carried);
     const created = await runStore.createRun(taskId, sessionId, args.prepared.auth?.principal ?? null, deps.instanceId ?? "default", { ...runMeta(args.prepared, args.source), idem: args.idem ?? null });
     if (created.ok)
         clearTurnActivity(taskId);
@@ -25,13 +28,34 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
     if (!created.ok) {
         return { status: 409, body: await buildActiveRunConflict({ runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
     }
-    const placementReject = await commitPlacement(deps, runStore, taskId, args.prepared.bindingIntent);
-    if (placementReject)
-        return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
-    if (deps.checkpointStore) {
-        const ctxRefusal = await persistSubmitCtx(deps.checkpointStore, deps, { runStore, taskId }, sessionId, { body: args.prepared.body, memoryScope: args.prepared.auth?.memoryScope, writerVersion: serviceVersion() });
-        if (ctxRefusal)
-            return ctxRefusal;
+    const owner = args.prepared.auth?.principal ?? null;
+    const preLaunchHeartbeat = setInterval(() => {
+        void runStore.heartbeat(taskId, owner).catch(() => { deps.metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
+    }, HEARTBEAT_MS);
+    preLaunchHeartbeat.unref?.();
+    try {
+        const placementReject = await commitPlacement(deps, runStore, taskId, args.prepared.bindingIntent);
+        if (placementReject)
+            return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
+        if (deps.checkpointStore) {
+            const ctxRefusal = await persistSubmitCtx(deps.checkpointStore, deps, { runStore, taskId }, sessionId, { body: args.prepared.body, memoryScope: args.prepared.auth?.memoryScope, writerVersion: serviceVersion() });
+            if (ctxRefusal)
+                return ctxRefusal;
+        }
+        if (args.workflowDecision !== undefined) {
+            try {
+                await args.workflowDecision.commitBeforeLaunch(taskId);
+            }
+            catch (err) {
+                await releaseClaimedRun(runStore, taskId, `the workflow decision this run delivers could not be recorded: ${err instanceof Error ? err.message : String(err)}`, (releaseErr, step) => {
+                    deps.logger?.warn?.("workflow_decision_run_release_failed", { taskId, sessionId, step, err: releaseErr instanceof Error ? releaseErr.message : String(releaseErr) });
+                });
+                throw err;
+            }
+        }
+    }
+    finally {
+        clearInterval(preLaunchHeartbeat);
     }
     commitSessionInheritEnv(deps, args.prepared.spec.sessionId, args.prepared.body);
     const anchorOwner = args.prepared.auth?.principal ?? null;
@@ -65,7 +89,7 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
             windowMs: deps.config.streamApproval?.windowMs,
             windowMarginMs: deps.config.streamAskWindowMarginMs,
         }
-        : undefined, deps.checkpointStore, args.prepared.engineNotices, args.trustedInternals, deps.userInputLedger, args.prepared.acceptance);
-    return { status: 202, body: { taskId, sessionId, status: "running" } };
+        : undefined, deps.checkpointStore, args.prepared.engineNotices, trustedInternals, deps.userInputLedger, args.prepared.acceptance);
+    return { status: 202, body: { taskId, sessionId, status: "running", ...(args.prepared.warnings !== undefined ? { warnings: args.prepared.warnings } : {}) } };
 }
 //# sourceMappingURL=durable-run-leg.js.map

package/dist/http/owner-access.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 🔴 **属主存取器**(S-487 RH-3 第一期)——「这个调用方读得到这一行 run / 会话吗」的行只经这里取得。
+ *
+ * ## 律(一条)
+ * 判官只有一只:run 行 = `principal-gate.ts` 的 `runOwnerReadable`(三条放行臂,含 [ref] C8 窄互认),会话行 = `sessionOwnerReadable`
+ * (dev-open 不钉人;无主行经 `security.ts` 的 `ownerlessRowOpen`;有主行就是 run 那一只)。本模块**不判第二遍、不另写一条**:它只做三件事 ——
+ *  · 取行(或收下调用点已读到的行)并把行上的属主铸成 `DurableOwnerKey`(品牌铸点之一,见 `security.ts`);
+ *  · 过判官,读不到 ⇒ `undefined` —— 与「没有这一行」**同一个值**,路由手里拿不到它无权看的行,也就没有第二种拒绝形可漏存在性;
+ *  · operator 臂由调用点以闭集 {@link OwnerArm} 声明,这里统一并 `explicitOperatorOk`(此前各口手抄 `explicitOperatorOk(...) || owner === principal`)。
+ *
+ * ## 射程(第一期)
+ * 迁进来的口:leader 登记表的读与幂等重放、A2A `tasks/get`、preempt、审批豁免面;`request-guards.ts` 的 `runOwnerOk` 与提交撞键的回执函数
+ * (`submit-replay.ts`)经 {@link runRowReadable} 读同一只判官。其余按 run / 会话寻址的口(`runOwnerOk` 16 处、`sessionOwnerOk` 10 处)第二期整体换成
+ * {@link readOwnedRun} / {@link readOwnedSession} 并删两只 helper;裸 store 读口按文件计数钉在 `test/owner-gate-single-owner.test.ts`(增即红)。
+ */
+import type { ServiceConfig } from "../config-types.js";
+import type { RunRecord } from "../plugins/store-contracts.js";
+import { type OwnerAwareSessionStore, type Principal, type SessionCaller, type SessionOwnerCell } from "../security.js";
+import { type IdentityWiring, type OperatorRoster } from "./principal-gate.js";
+/** 调用点挂哪条臂(闭集):`owner` = 只有属主判官;`owner_or_operator` = 属主判官 ∨ 显式运维(`explicitOperatorOk`,唯一读法)。 */
+export type OwnerArm = "owner" | "owner_or_operator";
+/** 存取器读的配置格:判官要 `requirePrincipal`(C8 臂的单用户条件),operator 臂要运维名册。 */
+export type OwnerAccessConfig = Pick<ServiceConfig, "requirePrincipal"> & OperatorRoster;
+/**
+ * 一行 run 行的属主过判官。`owner`:串 = 有主,`null` = 无主(开放);**`undefined` = 属主格坏了**(型上是 `string | null`,盘上的 run.json 少了这个键时
+ * 运行期会读成缺席 —— 文件店的形判据不验它)⇒ 谁都读不到(fail-closed,不猜成无主;operator 臂照常并)。leader 登记行的 `owner` 是可选键、缺席 = 无主,
+ * 那是 leader 记录型自己的语义,由 {@link createLeaderRunVisibility} 在 leader 边界上显式折成 `null`,不在这里混读。
+ */
+export declare function runRowReadable(config: OwnerAccessConfig, principal: Principal | undefined, owner: string | null | undefined, arm: OwnerArm): boolean;
+/**
+ * 按**会话**寻址的面上读一行 run 行(会话面板的上一腿 MCP 投影:读的是这只会话最新那条 run 的账本行):判官 = 会话面那一只(`sessionOwnerReadable`:
+ * dev-open 不钉人,与会话列表同读);run 行不是委派子代的 placed 会话行 ⇒ 无主时 `placed: false`(与 run 面对无主 run 的读法同)。
+ */
+export declare function runRowReadableOnSessionFace(w: IdentityWiring & {
+    readonly config: OwnerAccessConfig;
+}, caller: SessionCaller, owner: string | null, arm: OwnerArm): boolean;
+/** run 行读口:行 | `undefined`(没有这一行 ≡ 读不到,同一个值)。 */
+export declare function readOwnedRun(config: OwnerAccessConfig, runStore: {
+    getRun(taskId: string): Promise<RunRecord | undefined>;
+}, principal: Principal | undefined, taskId: string, arm: OwnerArm): Promise<RunRecord | undefined>;
+/**
+ * 会话行读口:属主一读 + 无主时 placement 一格(`sessionOwnerCellOf`,S-1770)+ 会话面判官。`undefined` = 没有这只会话(`ownerOf` 答 `undefined`)≡ 读不到。
+ * 读回的那一格交给调用点(要按属主作答的口用它)。店的读失败照常抛(500,绝不当成「读不到」或「读得到」)。
+ */
+export declare function readOwnedSession(w: IdentityWiring & {
+    readonly config: OwnerAccessConfig;
+}, store: Pick<OwnerAwareSessionStore, "placementOf"> & {
+    ownerOf(sessionId: string): Promise<string | null | undefined>;
+}, caller: SessionCaller, sessionId: string, arm: OwnerArm): Promise<SessionOwnerCell | undefined>;
+/**
+ * leader 登记表的判官形(boot 装配一次,`createLeaderEndpoint` 的必填席)—— leader 模块不再自判属主(修前它手抄 `owner == null || owner === requester`,
+ * 缺 C8 窄互认臂而注称 mirrors runOwnerOk)。leader 腿的调用方身份经幂等身份结构(`IdemCaller.principal`,即 `gatedPrincipal` 的回值)转手而来,
+ * 这里是 `Principal` 的「上游已验」适配铸点(第二期随那只结构带品牌而删)。`config` 是活的配置对象(每次调用现读)。
+ */
+export declare function createLeaderRunVisibility(config: OwnerAccessConfig): (principal: string | null | undefined, owner: string | null | undefined) => boolean;
+//# sourceMappingURL=owner-access.d.ts.map

package/dist/http/owner-access.js

@@ -0,0 +1,42 @@
+import { mintDurableOwnerKey, mintPrincipal, sessionOwnerCellOf } from "../security.js";
+import { explicitOperatorOk, runOwnerReadable, sessionOwnerReadable } from "./principal-gate.js";
+function operatorArmHolds(config, principal, arm) {
+    switch (arm) {
+        case "owner":
+            return false;
+        case "owner_or_operator":
+            return explicitOperatorOk(principal, config);
+        default: {
+            const unknownArm = arm;
+            throw new Error(`owner access: unknown arm ${String(unknownArm)}`);
+        }
+    }
+}
+export function runRowReadable(config, principal, owner, arm) {
+    if (operatorArmHolds(config, principal, arm))
+        return true;
+    if (owner === undefined)
+        return false;
+    return runOwnerReadable(principal, owner === null ? null : mintDurableOwnerKey(owner), config);
+}
+export function runRowReadableOnSessionFace(w, caller, owner, arm) {
+    if (operatorArmHolds(w.config, caller.principal, arm))
+        return true;
+    const cell = owner === null ? { owner: null, placed: false } : { owner: mintDurableOwnerKey(owner) };
+    return sessionOwnerReadable(caller, cell, w);
+}
+export async function readOwnedRun(config, runStore, principal, taskId, arm) {
+    const row = await runStore.getRun(taskId);
+    return row !== undefined && runRowReadable(config, principal, row.owner, arm) ? row : undefined;
+}
+export async function readOwnedSession(w, store, caller, sessionId, arm) {
+    const owner = await store.ownerOf(sessionId);
+    if (owner === undefined)
+        return undefined;
+    const cell = await sessionOwnerCellOf(store, sessionId, owner);
+    return operatorArmHolds(w.config, caller.principal, arm) || sessionOwnerReadable(caller, cell, w) ? cell : undefined;
+}
+export function createLeaderRunVisibility(config) {
+    return (principal, owner) => runRowReadable(config, principal == null ? undefined : mintPrincipal(principal), owner ?? null, "owner");
+}
+//# sourceMappingURL=owner-access.js.map

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;
@@ -27,7 +28,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 面的形,这里只是把它推到另一面。
@@ -91,7 +92,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`:身份原语只依赖本叶。 */
@@ -116,32 +117,56 @@ export declare function wiredIdentitySources(w: IdentityWiring): readonly Identi
  * 会话面的属主谓词({@link sessionOwnerReadable})、`/metrics` 族的免凭据臂(`dispatch.ts`)—— 于是「调用方是谁」在列表、单会话面与指标面上只有一只读法。
  */
 export declare function devOpenDeployment(w: IdentityWiring): boolean;
+/** 会话行属主门的调用方的唯一铸点({@link SessionCaller}):验过的主体 + 是不是 fleet 调用方 —— {@link devOpenDeployment} 上的任何调用方,
+ *  或出示了这台部署的 service 凭据(`systemFor`)、不报主体的调用方(带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据)。 */
+export declare function sessionCallerOf(req: IncomingMessage, w: IdentityWiring): SessionCaller;
 /**
  * **「这个调用方能不能动这只会话」的唯一谓词**(会话面:视图 / 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;
@@ -50,7 +50,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)
@@ -86,10 +87,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 +120,41 @@ 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 sessionCallerOf(req, w) {
+    const principal = gatedPrincipal(req, w.config);
+    return { principal, fleet: devOpenDeployment(w) || (principal === undefined && systemFor(req, w.config) !== undefined) };
+}
+export function sessionOwnerReadable(caller, cell, w) {
+    if (devOpenDeployment(w))
+        return true;
+    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 explicitOperatorOk(principal, operatorPrincipals) {
-    return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
+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 none) 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 OPERATOR_PRINCIPALS is empty, so no caller can be an operator on this deployment; configure OPERATOR_PRINCIPALS to enable it");
+    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 isOperator(principal, operatorPrincipals) {
-    if (operatorPrincipals.length === 0)
-        return true;
-    return principal !== undefined && operatorPrincipals.includes(principal);
+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/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,11 +89,7 @@ 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>;
@@ -112,7 +105,7 @@ export declare function createRequestGuards(ctx: {
         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;