@sema-agent/server 7.147.0 → 7.148.0

package/dist/http/approval-sweeps.js

@@ -2,18 +2,21 @@ import { redactHead } from "../observability/run-terminal.js";
 const errText = (e) => redactHead(e instanceof Error ? e.message : String(e), 2000);
 import { checkpointRevOf } from "@sema-agent/core";
 import { findParkOrigin } from "../parked-decide.js";
-import { decodeCheckpointScope } from "../security.js";
+import { recoveredSubject } from "../owner-faces.js";
 import { hostDecisionFacts } from "../host-decision.js";
 import {} from "../tool-approval.js";
 import { APPROVAL_GATE_KINDS } from "../approval-content-kind.js";
 import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
-import { gatedPrincipal, hasServiceAuth } from "./principal-gate.js";
+import { gatedPerson } from "./principal-gate.js";
+import { hasServiceAuth } from "../identity-source.js";
 import { costQuotaRefusalOf } from "./request-guards.js";
 import { admissionRefusalOf, readinessOf } from "./readiness.js";
+import { rowReadRefusalAnswer } from "./resume-legs.js";
 import { readResumeCtx } from "./resume-ctx-read.js";
 import { isResumeBlockedByPolicy } from "./checkpoint-ctx.js";
 import { storedBodyReplayRefusal } from "./stored-body-replay.js";
 import { refusalBody } from "./refusal-body.js";
+import { DENY_SWEEP_PAGE_ROWS } from "../plugins/checkpoint-store-face.js";
 const BLOCKED_SCALAR_KEYS = ["errorCode", "blockedBy", "field", "reason", "count", "cap", "index"];
 function blockedScalars(body) {
     const out = {};
@@ -28,14 +31,16 @@ function blockedScalars(body) {
 }
 const BLOCKED_WARNED_MAX = 1024;
 export function createApprovalSweeps(ctx) {
-    const { deps, resumeCheckpoint, mayDiscloseRowError } = ctx;
+    const { deps, resumeCheckpoint, decisionRowAdmits } = ctx;
     const blockedWarned = new Map();
+    let sweepAfter;
+    let sweepCycle = 0;
     const noteResumeBlocked = (cardToken, sessionId, status, body) => {
         deps.metrics?.inc("deny_sweep_resume_blocked_total");
         const fields = { status, ...blockedScalars(body) };
         if (cardToken !== undefined) {
             const fingerprint = JSON.stringify(fields);
-            if (blockedWarned.get(cardToken) === fingerprint)
+            if (blockedWarned.get(cardToken)?.fingerprint === fingerprint)
                 return;
             blockedWarned.delete(cardToken);
             if (blockedWarned.size >= BLOCKED_WARNED_MAX) {
@@ -43,7 +48,7 @@ export function createApprovalSweeps(ctx) {
                 if (oldest.done !== true)
                     blockedWarned.delete(oldest.value);
             }
-            blockedWarned.set(cardToken, fingerprint);
+            blockedWarned.set(cardToken, { fingerprint, cycle: sweepCycle });
         }
         deps.logger?.warn?.("deny_sweep_resume_blocked", { sessionId, ...fields });
     };
@@ -70,7 +75,7 @@ export function createApprovalSweeps(ctx) {
             return;
         let expired;
         try {
-            expired = await cs.listExpiredApprovalGates(now);
+            expired = await cs.listExpiredApprovalGates(now, DENY_SWEEP_PAGE_ROWS, sweepAfter);
         }
         catch (e) {
             deps.metrics?.inc("deny_sweep_list_failed_total");
@@ -80,42 +85,50 @@ export function createApprovalSweeps(ctx) {
             });
             return;
         }
+        const cycleEnds = expired.length < DENY_SWEEP_PAGE_ROWS;
+        sweepAfter = cycleEnds ? undefined : expired[expired.length - 1]?.position;
         const parkSources = deps.backgroundAgentStore !== undefined || deps.workflowAgentSessionIndex !== undefined;
         const cardOf = async (sessionId) => {
             let token;
             let binding = {};
+            let runSessionId;
             try {
                 token = (await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS })) ?? undefined;
                 if (!token)
-                    return { token, parked: false, rev: undefined, binding };
+                    return { token, parked: false, rev: undefined, binding, runSessionId };
+                runSessionId = (await cs.hostSessionOfCard(token)) ?? undefined;
                 const cp = await cs.get(token);
                 if (!cp)
-                    return { token, parked: false, rev: undefined, binding };
+                    return { token, parked: false, rev: undefined, binding, runSessionId };
                 const pa = cp.pendingAction;
                 binding = { checkpointToken: token, ...(pa.kind === "tool_approval" ? { boundCallId: pa.toolCallId, boundInputHash: pa.boundInputHash } : {}) };
                 const rev = checkpointRevOf(cp);
                 if (!parkSources)
-                    return { token, parked: false, rev, binding };
+                    return { token, parked: false, rev, binding, runSessionId };
                 const origin = await findParkOrigin({
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
                     ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
                         ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
                         : {}),
                 }, { token, scope: cp.scope, sessionId: cp.sessionId });
-                return { token, parked: origin !== undefined, rev, binding };
+                return { token, parked: origin !== undefined, rev, binding, runSessionId };
             }
             catch {
-                return { token, parked: false, rev: undefined, binding };
+                return { token, parked: false, rev: undefined, binding, runSessionId };
             }
         };
-        const storedBodyUnservable = async (sessionId) => {
-            const read = await readResumeCtx(cs.getCtx(sessionId), { sessionId, opener: deps.checkpointCtxSealing });
+        const storedBodyUnservable = async (runSessionId) => {
+            if (runSessionId === undefined)
+                return undefined;
+            const read = await readResumeCtx(cs.getCtx(runSessionId), { sessionId: runSessionId, opener: deps.checkpointCtxSealing });
             if (read.kind === "corrupt")
                 return undefined;
             if (read.kind === "unsealable")
                 return undefined;
             if (read.kind === "absent")
                 return undefined;
+            if (read.kind === "unreadable")
+                return undefined;
             return storedBodyReplayRefusal(read.ctx, deps.config);
         };
         const expirePolicyBlockedCard = async (cardToken, observedRev, sessionId, body) => {
@@ -141,16 +154,24 @@ export function createApprovalSweeps(ctx) {
         };
         let parkedSkipped = 0;
         const replaySkipped = [];
-        const seenCards = new Set();
         for (const { sessionId } of expired) {
-            const { token: cardToken, parked, rev: cardRev, binding: cardBinding } = await cardOf(sessionId);
-            if (cardToken !== undefined)
-                seenCards.add(cardToken);
+            const { token: cardToken, parked, rev: cardRev, binding: cardBinding, runSessionId } = await cardOf(sessionId);
+            const warned = cardToken === undefined ? undefined : blockedWarned.get(cardToken);
+            if (warned !== undefined)
+                warned.cycle = sweepCycle;
             if (parked) {
                 parkedSkipped += 1;
                 continue;
             }
-            const unservable = await storedBodyUnservable(sessionId);
+            let unservable;
+            try {
+                unservable = await storedBodyUnservable(runSessionId);
+            }
+            catch (e) {
+                deps.metrics?.inc("deny_sweep_row_failed_total");
+                deps.logger?.warn?.("deny_sweep_row_failed", { sessionId, err: errText(e), note: "reading this expired approval's stored request threw, so it was not resumed this tick; the rest of the page was swept, and this row is tried again when the sweep comes round to it" });
+                continue;
+            }
             if (unservable !== undefined) {
                 replaySkipped.push({ sessionId, kind: unservable.kind });
                 continue;
@@ -172,9 +193,12 @@ export function createApprovalSweeps(ctx) {
             if (isResumeBlockedByPolicy(out) && cardToken !== undefined && cardRev !== undefined)
                 await expirePolicyBlockedCard(cardToken, cardRev, sessionId, out.body);
         }
-        for (const token of [...blockedWarned.keys()])
-            if (!seenCards.has(token))
-                blockedWarned.delete(token);
+        if (cycleEnds) {
+            for (const [token, warned] of [...blockedWarned])
+                if (warned.cycle !== sweepCycle)
+                    blockedWarned.delete(token);
+            sweepCycle += 1;
+        }
         if (parkedSkipped > 0)
             deps.logger?.info?.("deny_sweep_parked_skipped", { count: parkedSkipped });
         if (replaySkipped.length > 0) {
@@ -197,31 +221,31 @@ export function createApprovalSweeps(ctx) {
         if (refusal !== undefined)
             return { status: refusal.status, body: refusal.body };
         if (deps.costQuota && req.httpReq) {
-            const quotaPrincipal = gatedPrincipal(req.httpReq, deps.config);
-            if (quotaPrincipal !== undefined) {
-                const d = deps.costQuota.check(quotaPrincipal);
+            const quotaPerson = gatedPerson(req.httpReq, deps.config);
+            if (quotaPerson !== undefined) {
+                const d = deps.costQuota.check(quotaPerson);
                 if (!d.allowed) {
                     deps.metrics?.inc("cost_quota_rejected_total");
                     return costQuotaRefusalOf(d);
                 }
             }
         }
+        const answerer = { subject: recoveredSubject(req.principal), operator: false };
         let cp;
         try {
             cp = await cs.get(req.gateToken);
         }
         catch (e) {
-            if (!(await mayDiscloseRowError(cs, req.gateToken, { principal: req.principal, explicitOperator: false }))) {
+            if (!(await decisionRowAdmits(cs, req.gateToken, answerer, undefined))) {
                 deps.logger?.warn?.("parked_late_decision_unreadable_row_withheld", { askId: req.askId });
                 return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
             }
-            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
+            return rowReadRefusalAnswer(e);
         }
         if (!cp) {
             return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
-        const cpPrincipal = decodeCheckpointScope(cp.scope);
-        if (cpPrincipal !== undefined && cpPrincipal !== req.principal) {
+        if (!(await decisionRowAdmits(cs, req.gateToken, answerer, cp.scope))) {
             deps.logger?.warn?.("parked_late_decision_scope_mismatch", { askId: req.askId });
             return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
@@ -232,8 +256,8 @@ export function createApprovalSweeps(ctx) {
             ...(req.updatedInput !== undefined ? { updatedInput: req.updatedInput } : {}),
         };
         const remember = req.remember === "session" ? { grantedBy: req.principal ?? null, laneCannotRecord: "decide_once" } : undefined;
-        const out = await resumeCheckpoint(cp.sessionId, req.decision, req.note, hostDecisionFacts(req.decider, req.principal), req.httpReq, undefined, binding, remember, true, { principal: req.principal, explicitOperator: false });
-        return { status: out.status, body: out.body, ...(remember !== undefined ? { rememberApplied: out.rememberApplied === true } : {}) };
+        const out = await resumeCheckpoint(cp.sessionId, req.decision, req.note, hostDecisionFacts(req.decider, req.principal), req.httpReq, undefined, binding, remember, true, answerer);
+        return { status: out.status, body: out.body, ...(remember !== undefined ? { rememberApplied: out.rememberApplied === true } : {}), gateGeneration: checkpointRevOf(cp) };
     }
     return { denyExpiredApprovals, redeemParkedAsk };
 }

package/dist/http/caller-trust.d.ts

@@ -19,9 +19,12 @@
  * **判的是哪些表**:请求体上不经人答就生效的规则表 —— `settings.permissions` 的每个成员桶(逐 `membersOf("permissions")`),以及请求**按名点用**(`userInvokedSkills`)的
  * 自带技能的两只清单(引擎 `seedSkillGrants`:人点的名就是表态,不出 `Skill` 卡 ⇒ `allowedTools` 是 `allow` 成员的孪生、`disallowedTools` 是 `deny` 的孪生,键 → 成员一张表
  * {@link SKILL_LIST_MEMBER})。没点用的自带技能不判:它的清单要经 `Skill` 卡上的人点头才生效 —— 那正是契约给低于门槛的放宽指定的同意出口。
+ * **部署 / 中心的技能不判**(点名了也不判):它们的两只清单是运维授权,与 `APPROVAL_GRANT` 同级 —— 来处只有部署的 `SKILLS_DIR` / 本地配置源与中心的 `skills` · `plugins` 域,
+ * 契约给这两个域的写角色(`domainWriteRole`)不低于本表 `global` 的门槛(治理写角色),同名时部署的那只胜出、请求体那只被丢(`buildRunSkills`)⇒ 调用方没有改写它们清单的路;
+ * 点名只是选用。契约哪天把那两个域的写角色压到治理写角色之下,`test/caller-trust.test.ts` 的角色阶钉红,这条读法要重审。
  * 准入只经契约导出:桶非空且 `!isAtLeast(档, memberAdmission(…).minTrust)` ⇒ 不准入;不按方向开特例(契约的层准入同样先判 floor)。
- * 不准入 ⇒ 受理口 400,体与条目问题同形(`entry-problems.ts`:`field` + `detail.problems` + `total`),原因词 = 契约 `LAYER_ADMISSION_VERDICTS` 的 `below_trust_floor`,
- * 另带 `detail.callerTrust`(这次请求的档)。响亮拒而不是静默丢:契约要求低于门槛的放宽不得静默吞,出路是同意(答卡)或运维的 allow 表。
+ * 不准入 ⇒ 受理口 400,体与条目问题同形(`entry-problems.ts`:根上的 `field` + `problems` + `total`),原因词 = 契约 `LAYER_ADMISSION_VERDICTS` 的 `below_trust_floor`,
+ * 另带根上的 `callerTrust`(这次请求的档)。响亮拒而不是静默丢:契约要求低于门槛的放宽不得静默吞,出路是同意(答卡)或运维的 allow 表。
  *
  * 读者(都读同一次求值,不各算一份):提交受理口(`admission.ts` `prepareSpec`,三提交面共用)与能力位 `settings.permissions.callerTrust`(`routes/capabilities.ts`)。
  * 续跑腿不读本档:存储体在自己的受理口按当时的档准入过。
@@ -30,7 +33,7 @@ import type { IncomingMessage } from "node:http";
 import { type MinTrust, type SafetyMergeMember, type UserRole } from "@sema-agent/settings-schema";
 import type { SkillSpec } from "@sema-agent/core";
 import type { ServiceConfig } from "../config-types.js";
-import { type EntryProblem } from "../entry-problems.js";
+import { type EntryProblemsFacts } from "../entry-problems.js";
 import type { ParsedTaskSettings } from "../task-settings.js";
 /**
  * 档是**怎么**推出来的(闭集;拒句按它说出路)。加一个词 ⇒ {@link basisClause} 的穷举 switch 编译红。
@@ -61,13 +64,8 @@ export interface RequestRuleTables {
 /** 受理口拒体:句子 + 机读位(原样进 `sendError` 的 facts)。 */
 export interface RequestTrustRefusal {
     readonly message: string;
-    readonly facts: {
-        readonly field: string;
-        readonly detail: {
-            readonly problems: readonly EntryProblem[];
-            readonly total: number;
-            readonly callerTrust: MinTrust;
-        };
+    readonly facts: EntryProblemsFacts & {
+        readonly callerTrust: MinTrust;
     };
 }
 /**

package/dist/http/caller-trust.js

@@ -72,10 +72,9 @@ export function requestTrustRefusal(tables, reading) {
     }
     if (first === undefined)
         return undefined;
-    const facts = entryProblemsFacts(problems);
     return {
         message: `${first.table.field} needs trust "${first.minTrust}" (${whatItDoes(first.table.source, first.loosens)}) and this request is admitted at "${reading.trust}": ${basisClause(reading)}. Below that trust these rules are not applied — ${outletOf(first.table.source, first.loosens)}.`,
-        facts: { field: facts.field, detail: { ...facts.detail, callerTrust: reading.trust } },
+        facts: { ...entryProblemsFacts(problems), callerTrust: reading.trust },
     };
 }
 function whatItDoes(source, loosens) {

package/dist/http/claim-heartbeat.d.ts

@@ -0,0 +1,49 @@
+/**
+ * **认领之后、起跑之前**的两件事(三条提交腿 —— 流式 / 同步 / 后台 —— 同一只):
+ *  · {@link startClaimHeartbeat}:认领赢的那一拍起心跳(落点 / 续跑输入 / 决定落行几笔店写都在起跑之前,任何一笔卡过收割窗,收割器就会把这条还活着的行判死、放掉认领);
+ *    起跑那一拍交给腿自己的心跳,每条收场出口停掉它;
+ *  · {@link claimStillHeld}:引擎起跑之前的最后一读 —— 认领此刻还是不是这条 run 的(一次栅栏写,也是一次心跳)。不是 ⇒ 不起引擎(收割已放掉认领,会话可能已被删、
+ *    已归别的 run;起跑就是在一只别人的会话上跑,或让引擎在原 id 上重建一只无主的根)。
+ * 如实的边:栅栏的担保止于它那一拍 —— 复核之后、引擎起跑之前腿上还有一两次店读(停驻决定 / 受理账本),这一窗里心跳持续失败到收割窗以外
+ * (或进程停住那么久)⇒ 仍可能在失去认领之后起跑。「失认领后绝不起跑」要一只把认领带进引擎的栅栏,不在本模块。
+ */
+import { type RunHeartbeatStore } from "../runs.js";
+import { type ClaimFenceStore } from "../plugins/store-contracts.js";
+import type { RunStore } from "../plugins/store-backend.js";
+import type { FlatServiceDeps } from "./server.js";
+import { buildActiveRunConflict } from "./active-run-conflict.js";
+import { rootSessionAbsentAnswer } from "./execution-context.js";
+import { type RefusalBody } from "./refusal-body.js";
+import { headReadOf } from "../session-incarnation.js";
+/** 认领赢的那一拍起心跳(与后台腿 `runInBackground` 同一只周期、同一条带属主的刷新);交回停表。行已不在跑 ⇒ 心跳自停(起跑之前的复核随后答失认领)。刷新失败不抛(计数),下一拍再刷。 */
+export declare function startClaimHeartbeat(runStore: RunHeartbeatStore, taskId: string, owner: string | null, metrics: {
+    inc(name: string, labels?: Record<string, string>): void;
+} | undefined): () => void;
+/** 起跑之前的认领复核:栅栏里什么都不写,只问「还持有吗」(一次栅栏写也是一次心跳)。 */
+export declare function claimStillHeld(runStore: ClaimFenceStore, sessionId: string, taskId: string): Promise<boolean>;
+/**
+ * 三条提交腿起跑之前的那一只复核(唯一调用形):持有 ⇒ `undefined`(照起);没持有 ⇒ {@link refusalAfterLostClaim} 的答复;栅栏自己抛(店一时不通)⇒
+ * 先按 {@link releaseClaimedRun} 撤掉本请求刚认领的这条 run(终结行 + 放幂等键,不留一条没起跑的 `running` 行占着会话等收割),再原样上抛。
+ */
+export declare function recheckClaimBeforeLaunch(deps: Pick<FlatServiceDeps, "checkpointStore" | "config" | "logger"> & LostClaimSessionFace, runStore: ClaimFenceStore & LostClaimStore, sessionId: string, taskId: string): Promise<Awaited<ReturnType<typeof refusalAfterLostClaim>> | undefined>;
+/** 失认领答复读会话店的那一面:只问头读(`headReadOf` 判店有没有它)—— 不要整只会话店。 */
+export interface LostClaimSessionFace {
+    readonly sessionStorage?: Parameters<typeof headReadOf>[0];
+}
+/** 失认领答复与撤回本次 run 读写的那几面。 */
+export type LostClaimStore = Pick<RunStore, "getActiveTaskId" | "getRun" | "setTerminal" | "releaseIdemKey">;
+/**
+ * 起跑之前认领复核没过的答复(三条提交腿同一只;三臂按「此刻是谁的事实」分,各读各的):
+ *  · 认领此刻在别的 run 上 ⇒ 409 冲突体(与建行时认领输同一只材料,`conflict.session_active_run`);
+ *  · 会话店的头读答「没有这只会话」⇒ 404 `resume.session_not_found`(四个建行点「会话不在」同一只答复)—— 只有读到它不在才这么答;
+ *  · 否则(本条行已被死亡判决终局 —— 观察口 / 认领冲突 / 收割器之一 —— 没人持认领,会话在;或店没有头读、说不出它不在)⇒ 409 `conflict.claim_lost`:说的是本条 run 的事实(判决在起跑之前结清了它),不说会话。
+ * 三臂都不放键、不终结行(行已被收割终局;键随那条终局行,与收割的既有读法同 —— 撤回出口删本次那一条 run 行时键随行去,`plugins/session-birth.ts`)。
+ */
+export declare function refusalAfterLostClaim(deps: Pick<FlatServiceDeps, "checkpointStore" | "config"> & LostClaimSessionFace, runStore: LostClaimStore, sessionId: string, taskId: string): Promise<{
+    status: 409;
+    body: Awaited<ReturnType<typeof buildActiveRunConflict>>;
+} | ReturnType<typeof rootSessionAbsentAnswer> | {
+    status: 409;
+    body: RefusalBody;
+}>;
+//# sourceMappingURL=claim-heartbeat.d.ts.map

package/dist/http/claim-heartbeat.js

@@ -0,0 +1,46 @@
+import { beatRunHeartbeat, HEARTBEAT_MS } from "../runs.js";
+import { FENCE_LANDED } from "../plugins/store-contracts.js";
+import { buildActiveRunConflict } from "./active-run-conflict.js";
+import { rootSessionAbsentAnswer } from "./execution-context.js";
+import { readTurnActivityMs } from "../turn-activity.js";
+import { releaseClaimedRun } from "./claimed-run.js";
+import { refusalBody } from "./refusal-body.js";
+import { headReadOf } from "../session-incarnation.js";
+export function startClaimHeartbeat(runStore, taskId, owner, metrics) {
+    const timer = setInterval(() => {
+        beatRunHeartbeat(runStore, taskId, owner, () => clearInterval(timer), () => {
+            metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" });
+        });
+    }, HEARTBEAT_MS);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+export async function claimStillHeld(runStore, sessionId, taskId) {
+    if ("db" in runStore)
+        return (await runStore.whileHoldingClaim(sessionId, taskId, async () => undefined)).held;
+    return runStore.whileHoldingClaim(sessionId, taskId, () => FENCE_LANDED);
+}
+export async function recheckClaimBeforeLaunch(deps, runStore, sessionId, taskId) {
+    let held;
+    try {
+        held = await claimStillHeld(runStore, sessionId, taskId);
+    }
+    catch (err) {
+        await releaseClaimedRun(runStore, taskId, `the claim re-check before launch failed: ${err instanceof Error ? err.message : String(err)}`, (releaseErr, step) => {
+            deps.logger?.warn?.("claim_recheck_release_failed", { taskId, sessionId, step, err: releaseErr instanceof Error ? releaseErr.message : String(releaseErr) });
+        });
+        throw err;
+    }
+    return held ? undefined : await refusalAfterLostClaim(deps, runStore, sessionId, taskId);
+}
+export async function refusalAfterLostClaim(deps, runStore, sessionId, taskId) {
+    const holder = await runStore.getActiveTaskId(sessionId);
+    if (holder !== undefined && holder !== taskId) {
+        return { status: 409, body: await buildActiveRunConflict({ runStore, checkpointStore: deps.checkpointStore, governance: deps.config, turnActivity: readTurnActivityMs }, sessionId, holder) };
+    }
+    const headOf = headReadOf(deps.sessionStorage);
+    if (headOf !== undefined && (await headOf(sessionId)) === undefined)
+        return rootSessionAbsentAnswer();
+    return { status: 409, body: refusalBody({ errorCode: "conflict.claim_lost", message: "the run this request claimed was settled by the stale-run verdict before the engine started it (its claim heartbeat did not land within the reap window) — nothing ran" }) };
+}
+//# sourceMappingURL=claim-heartbeat.js.map

package/dist/http/claimed-run.d.ts

@@ -1,7 +1,8 @@
 /**
- * 一条提交腿**刚认领**的 run 在起跑之前就收场 —— 撤掉本请求建的东西的**唯一**写法。三个调用点:device 落点拒
- * (`execution-context.ts` `commitExecutionContext`)、续跑输入写不进(`submit-ctx.ts` `persistSubmitCtx`)与 workflow 决定行没落成
- * (`durable-run-leg.ts` 的 fresh 投递腿;此刻认领可能已被收割归了别人 —— 两步都按这一跑自己的 taskId,碰不到别人的认领)。
+ * 一条提交腿**刚认领**的 run 在起跑之前就收场 —— 撤掉本请求建的东西的**唯一**写法。四个调用点:device 落点拒
+ * (`execution-context.ts` `commitExecutionContext`)、续跑输入写不进(`submit-ctx.ts` `persistSubmitCtx`)、workflow 决定行没落成
+ * (`durable-run-leg.ts` 的 fresh 投递腿;此刻认领可能已被收割归了别人 —— 两步都按这一跑自己的 taskId,碰不到别人的认领)与
+ * 起跑之前的认领复核答不出(`claim-heartbeat.ts` `recheckClaimBeforeLaunch`,同理按自己的 taskId)。
  *
  * 撤两步,**各自独立**(一步失败不拦另一步,残余最小):
  *  · 终结这条 run 行(`setTerminal` 是按 taskId 的 CAS,首写者赢 ⇒ 重复调用是 no-op)—— 随之释放它的 `task_active` 认领;

package/dist/http/dispatch.d.ts

@@ -16,6 +16,7 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { ServiceConfig } from "../config-types.js";
+import { type HealthReader } from "./health-reader.js";
 import type { RouteCtxBase, RunRegistry } from "./route-ctx.js";
 import type { FlatServiceDeps } from "./server.js";
 /** `/health` 的 `mods` 段(运维声明的 mod 包装上了几只;present-iff 装上了)—— 段的键集属主,自铸 wire 值登记表 `healthModsKey` 绑它。 */
@@ -28,7 +29,7 @@ export interface HealthDeploymentModsSection {
  *
  * 病:这几族(trace-usage / workflows / fleet)排在全局门之前,理由只有一条 —— 只读 `TRACE_TOKEN` 单凭据的调用方
  * (registry 用量 / 轨迹中继)在全局门会被 401。可排在门前之后,每一族只剩**块内**自己那道门:fleet / workflows
- * 只在 `REQUIRE_PRINCIPAL` 时要身份,trace 认 `gatedPrincipal`(BFF 形上就是调用方自己写的 principal 头)。于是
+ * 只在 `REQUIRE_PRINCIPAL` 时要身份,trace 认 `gatedSubject`(BFF 形上就是调用方自己写的 principal 头)。于是
  * 配了 service token、没开 REQUIRE_PRINCIPAL 的部署上,`POST /v1/tasks` 吃凭据,这三族读路对端口全开。
  *
  * 规则(一条,三族同读;fail-closed):
@@ -40,6 +41,12 @@ export interface HealthDeploymentModsSection {
  * 「这个请求带没带这台部署认的凭据」,不回答「它能看谁的行」。
  */
 export declare function readCredentialOk(req: IncomingMessage, config: ServiceConfig): boolean;
+/**
+ * `GET /health` 这次请求的**读者档**(`health-reader.ts` 头注:三档与每档拿什么)—— 读的是上面那一只读路谓词,不另立第二份「凭据」读法:
+ * 没配服务凭据 ⇒ `open`(谓词的第一臂);配了而谓词认 ⇒ `credentialed`;配了而谓词不认 ⇒ `anonymous`。
+ * 调用点必须在鉴权桥预认证**之后**(已验登录令牌是谓词的一臂,读的是预认证挂上的身份)。
+ */
+export declare function healthReaderOf(req: IncomingMessage, config: ServiceConfig): HealthReader;
 export declare function createDispatch(ctx: {
     deps: FlatServiceDeps;
     noteActivity: (url: string) => void;

package/dist/http/dispatch.js

@@ -1,16 +1,22 @@
 import { createHash } from "node:crypto";
-import { setSsoPrincipal, setSsoScope, setSsoRole, setSsoPrincipalInc, isDestructiveSessionWrite, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../security.js";
+import { setSsoPrincipal, setSsoScope, setSsoRole, setSsoPrincipalInc, isDestructiveSessionWrite, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER, HttpError, SCENARIO_HEADER, scenarioHeaderOf, scenarioHeaderUnknownError, verifiedPerson } from "../security.js";
+import { partsOf } from "../owner-brands.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { publicStoreProbeError } from "../store-live-probe.js";
 import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
 import { admitBridgeIdentity } from "../auth-bridge.js";
 import { ROUTE_METHOD_ORDER } from "./route-ctx.js";
 import { READ_CREDENTIAL_ROUTES, PUBLIC_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, billableKindOf, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute, isProbePath, isSubscriptionRequest } from "./route-table.js";
-import { sendJson, sendError, isSseResponse, endSseWithError } from "./send.js";
+import { sendJson, sendError, sendHttpError, isSseResponse, endSseWithError } from "./send.js";
 import { admissionRefusalOf, readinessOf, healthReadinessKeys, sendReadyz, sendBillableRefusal, billableRefusalOf, billableRefusalFrame } from "./readiness.js";
 import { ENGINE_SIGNAL_KEY, buildEngineSignal, fleetMembershipKeys, healthConfigLedgerKeys, healthDrainingKeys, mintEngineSignal, restartActionable } from "../fleet/engine-signal.js";
 import { buildHealthSelfReport } from "./health-self-report.js";
-import { deploymentModPackages as deploymentModPackagesFact } from "../capability-facts.js";
-import { actsForDeployment, admitRunIdentity, authorized, systemFor, gatedPrincipal, sendPrincipalRefusal, sendUnauthorized, traceTokenPresented, verifiedIdentitySource, hasServiceAuth, devOpenDeployment } from "./principal-gate.js";
+import { projectHealthBody } from "./health-reader.js";
+import { projectHealthStoreSection, unwiredStorePosture } from "../store-posture.js";
+import { autoBackgroundOnTimeout as autoBackgroundOnTimeoutFact, autoBackgroundOnTimeoutWord, deploymentModPackages as deploymentModPackagesFact } from "../capability-facts.js";
+import { hostBackgroundShellEnabled } from "../config.js";
+import { actsForDeployment, admitRunIdentity, authorized, bearerPresentedButUnverified, systemFor, gatedSubject, sendPrincipalRefusal, sendUnauthorized, traceTokenPresented, verifiedIdentitySource, devOpenDeployment } from "./principal-gate.js";
+import { hasServiceAuth } from "../identity-source.js";
 import { inflightTotal } from "../fleet/drain-entry.js";
 const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
 export function readCredentialOk(req, config) {
@@ -20,6 +26,11 @@ export function readCredentialOk(req, config) {
         return true;
     return traceTokenPresented(req, config);
 }
+export function healthReaderOf(req, config) {
+    if (!hasServiceAuth(config))
+        return "open";
+    return readCredentialOk(req, config) ? "credentialed" : "anonymous";
+}
 function cors(res, req, origins, principalHeader) {
     if (!origins || origins.length === 0)
         return;
@@ -36,7 +47,7 @@ function cors(res, req, origins, principalHeader) {
         return;
     res.setHeader("access-control-allow-origin", allow);
     res.setHeader("access-control-allow-methods", [...ROUTE_METHOD_ORDER, "OPTIONS"].join(", "));
-    res.setHeader("access-control-allow-headers", `content-type, authorization, last-event-id, ${principalHeader}, idempotency-key, x-detach-on-disconnect, ${PRINCIPAL_TOKEN_HEADER}, ${APPROVAL_MAC_HEADER}, ${APPROVAL_MAC_KID_HEADER}, if-none-match`);
+    res.setHeader("access-control-allow-headers", `content-type, authorization, last-event-id, ${principalHeader}, ${SCENARIO_HEADER}, idempotency-key, x-detach-on-disconnect, ${PRINCIPAL_TOKEN_HEADER}, ${APPROVAL_MAC_HEADER}, ${APPROVAL_MAC_KID_HEADER}, if-none-match`);
     res.setHeader("access-control-expose-headers", "x-task-id, retry-after");
 }
 export function createDispatch(ctx) {
@@ -60,7 +71,29 @@ export function createDispatch(ctx) {
                     endSseWithError(r, frame);
         };
     }
-    async function dispatchSegment(rows, req, res, url, search, method, allow, ctx, admit) {
+    function scenarioHeaderAnswered(req, res) {
+        if (scenarioHeaderOf(req) === undefined)
+            return false;
+        try {
+            if (DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(deps.config) && (bearerPresentedButUnverified(req, deps.config) || verifiedPerson(req, deps.config) === undefined)) {
+                sendPrincipalRefusal(res, req, deps.config);
+                return true;
+            }
+            const subject = gatedSubject(req, deps.config);
+            const scenario = subject === undefined ? undefined : partsOf(subject).scenario;
+            const known = deps.scenarioGate.known();
+            if (scenario === undefined || !known.includes(scenario))
+                throw scenarioHeaderUnknownError(String(scenario), known);
+            return false;
+        }
+        catch (e) {
+            if (!(e instanceof HttpError))
+                throw e;
+            sendHttpError(res, e);
+            return true;
+        }
+    }
+    async function dispatchSegment(rows, req, res, url, search, method, allow, ctx, admit, judgesIdentity = true) {
         for (const row of rows) {
             if (row.enabled !== undefined && !row.enabled(deps))
                 continue;
@@ -74,11 +107,32 @@ export function createDispatch(ctx) {
                 sendUnauthorized(res, "credential");
                 return true;
             }
+            if (judgesIdentity && scenarioHeaderAnswered(req, res))
+                return true;
             await row.handler(req, res, { decl: found.decl, params: found.params, search }, ctx);
             return true;
         }
         return false;
     }
+    async function attachBridgeIdentity(req) {
+        if (deps.webAdminJwtVerifier) {
+            const authz = req.headers.authorization ?? "";
+            const rawBearer = /^Bearer\s/i.test(authz) ? authz.replace(/^Bearer\s+/i, "") : "";
+            if (rawBearer && looksLikeJwt(rawBearer)) {
+                const identity = admitBridgeIdentity(await deps.webAdminJwtVerifier.verify(rawBearer), { logger: deps.logger, metrics: deps.metrics });
+                if (identity) {
+                    setSsoPrincipal(req, identity.principal);
+                    req.headers[deps.config.principalHeader.toLowerCase()] = identity.principal;
+                    setSsoScope(req, identity.scope);
+                    if (identity.role)
+                        setSsoRole(req, identity.role);
+                    if (identity.principalInc !== undefined)
+                        setSsoPrincipalInc(req, identity.principalInc);
+                    deps.logger?.info?.("auth_bridge_principal_accepted", { principal: identity.principal, scope: identity.scope });
+                }
+            }
+        }
+    }
     async function handle(req, res) {
         const startedAt = Date.now();
         const method = req.method ?? "GET";
@@ -127,6 +181,8 @@ export function createDispatch(ctx) {
             return;
         }
         if (req.method === "GET" && url === "/health") {
+            await attachBridgeIdentity(req);
+            const reader = healthReaderOf(req, deps.config);
             const signal = mintEngineSignal(deps);
             const engineSignal = buildEngineSignal(signal);
             const declaredMods = deploymentModPackagesFact(deps);
@@ -134,7 +190,7 @@ export function createDispatch(ctx) {
                 .update(JSON.stringify({ model: deps.config.model.id, sessionBackend: deps.config.sessionBackend, dbBackend: deps.config.dbBackend, dataRoot: deps.config.localDataRoot, configProvider: deps.config.configProvider, remoteExec: deps.config.remoteExec.provider, port: deps.config.port }))
                 .digest("hex")
                 .slice(0, 16);
-            sendJson(res, 200, {
+            const fullBody = {
                 status: "ok",
                 ...(typeof deps.capabilities?.version === "string" ? { version: deps.capabilities.version } : {}),
                 ...healthDrainingKeys(signal),
@@ -158,7 +214,10 @@ export function createDispatch(ctx) {
                         },
                     };
                 })(),
-                ...(deps.storePosture?.degradedReason !== undefined ? { durable: false, storeDegraded: true } : {}),
+                ...(deps.sandboxCapacity !== undefined ? { sandboxCapacity: deps.sandboxCapacity.health() } : {}),
+                ...(deps.storePosture?.degradedReason !== undefined ? { storeDegraded: true } : {}),
+                store: projectHealthStoreSection(deps.storePosture ?? unwiredStorePosture(deps.config.dbBackend)),
+                autoBackgroundOnTimeout: autoBackgroundOnTimeoutWord(autoBackgroundOnTimeoutFact(deps.config, hostBackgroundShellEnabled())),
                 ...healthReadinessKeys(signal.verdict),
                 model: deps.config.model.id,
                 sessionBackend: deps.sessionStoreLabel ?? deps.config.sessionBackend,
@@ -201,7 +260,8 @@ export function createDispatch(ctx) {
                     };
                 })(),
                 [ENGINE_SIGNAL_KEY]: engineSignal,
-            });
+            };
+            sendJson(res, 200, projectHealthBody(reader, fullBody));
             return;
         }
         if (req.method === "GET" && url === "/readyz") {
@@ -214,8 +274,8 @@ export function createDispatch(ctx) {
                 return;
             }
             const mt = deps.config.metricsToken;
-            const devOpen = devOpenDeployment(deps) && !mt;
-            const ok = devOpen || (!!mt && authorized(req, mt)) || actsForDeployment(req, deps.config, () => gatedPrincipal(req, deps.config));
+            const devOpen = devOpenDeployment(deps.config) && !mt;
+            const ok = devOpen || (!!mt && authorized(req, mt)) || actsForDeployment(req, deps.config, () => gatedSubject(req, deps.config));
             if (!ok) {
                 sendUnauthorized(res, "operator");
                 return;
@@ -232,26 +292,10 @@ export function createDispatch(ctx) {
             res.end(deps.metrics.render());
             return;
         }
-        if (deps.webAdminJwtVerifier) {
-            const authz = req.headers.authorization ?? "";
-            const rawBearer = /^Bearer\s/i.test(authz) ? authz.replace(/^Bearer\s+/i, "") : "";
-            if (rawBearer && looksLikeJwt(rawBearer)) {
-                const identity = admitBridgeIdentity(await deps.webAdminJwtVerifier.verify(rawBearer), { logger: deps.logger, metrics: deps.metrics });
-                if (identity) {
-                    setSsoPrincipal(req, identity.principal);
-                    req.headers[deps.config.principalHeader.toLowerCase()] = identity.principal;
-                    setSsoScope(req, identity.scope);
-                    if (identity.role)
-                        setSsoRole(req, identity.role);
-                    if (identity.principalInc !== undefined)
-                        setSsoPrincipalInc(req, identity.principalInc);
-                    deps.logger?.info?.("auth_bridge_principal_accepted", { principal: identity.principal, scope: identity.scope });
-                }
-            }
-        }
+        await attachBridgeIdentity(req);
         if (await dispatchSegment(READ_CREDENTIAL_ROUTES, req, res, url, search, method, allow.pre, ctx, (r) => readCredentialOk(r, deps.config)))
             return;
-        if (await dispatchSegment(PUBLIC_ROUTES, req, res, url, search, method, allow.pre, ctx))
+        if (await dispatchSegment(PUBLIC_ROUTES, req, res, url, search, method, allow.pre, ctx, undefined, false))
             return;
         const identitySource = verifiedIdentitySource(req, deps.config);
         admitRunIdentity(req, identitySource, deps.logger);
@@ -298,7 +342,9 @@ export function createDispatch(ctx) {
         if (await dispatchSegment(POST_CREDENTIAL_ROUTES, req, res, url, search, method, allow.post, ctx))
             return;
         if (allow.pre.length > 0 || allow.post.length > 0) {
-            if (allow.post.length > 0 && deps.config.requirePrincipal && gatedPrincipal(req, deps.config) === undefined) {
+            if (allow.post.length > 0 && scenarioHeaderAnswered(req, res))
+                return;
+            if (allow.post.length > 0 && deps.config.requirePrincipal && gatedSubject(req, deps.config) === undefined) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
             }

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

@@ -13,17 +13,17 @@ export interface DurableRunLegArgs {
     idem?: RunIdemBinding;
     /** 🔒 这条 run 的 **fleet 行 scope** —— 必须与 `GET /v1/fleet/stream` 过滤用的是同一个身份,且绝不是
      *  自报的 `x-agent-principal` 头(自报头会把行打到受害者的 scope 上,或打到 `default` 而真属主的流把它
-     *  过滤掉)。提交门传 `gatedPrincipal(req) ?? "default"`;`/decide` 的第三条车道传 resume 家族的
+     *  过滤掉)。提交门传 `gatedSubject(req) ?? "default"`;`/decide` 的第三条车道传 resume 家族的
      *  `resumeFleetScope(req, auth)`(同一条 wire 上两条腿因此同答)。 */
     fleetScope: string;
     /** 🔒 这条 run 的 **elicit / question 应答方**(E23:与 respond 门读的是同一个已验身份,不是自报头)。
-     *  提交门传 `gatedPrincipal(req) ?? null` = 提交者本人;`/decide` 的第三条车道传**卡属主**(= 原提交者,
+     *  提交门传 `gatedSubject(req) ?? null` = 提交者本人;`/decide` 的第三条车道传**卡属主**(= 原提交者,
      *  不是代为按下按钮的 operator —— 与 resume 腿那条成文口径逐字同源)。`null` = 匿名/开放部署。 */
     elicitOwner: string | null;
     /** run 行元数据的 `source` 列(调用方的系统身份;内部车道传自己的车道名)。只作归因。 */
     source: string | null;
     /** run 行身份元组(`RunRecord.identity`)—— 调用方经 `runIdentityOf(req, config, 属主)` 读凭据门铸下的那一份交进来(本腿不碰请求);
-     *  属主 = `prepared.auth.principal`(本腿建行写进 `owner` 的同一个值)。`/decide` 第三条车道同一只读法:按下按钮的不是卡属主 ⇒ 空。 */
+     *  属主 = `prepared.auth.subject`(本腿建行写进 `owner` 的同一个值)。`/decide` 第三条车道同一只读法:按下按钮的不是卡属主 ⇒ 空。 */
     identity: RunIdentity | null;
     /** `/decide` 第三条车道的 fresh 投递腿交来的那一件决定投递(带着的决定 + 起跑之前落行的那一笔;语义与 TRUSTED 纪律的属主 =
      *  `route-ctx.ts` 的 {@link WorkflowDecisionDelivery} 顶注)。缺席 ⇒ 只摊本会话已受理的决定行。 */