@sema-agent/server 7.146.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" }) };
         }
@@ -231,8 +255,9 @@ export function createApprovalSweeps(ctx) {
             ...(req.gateBoundInputHash !== null ? { boundInputHash: req.gateBoundInputHash } : {}),
             ...(req.updatedInput !== undefined ? { updatedInput: req.updatedInput } : {}),
         };
-        const out = await resumeCheckpoint(cp.sessionId, req.decision, req.note, hostDecisionFacts(req.decider, req.principal), req.httpReq, undefined, binding, undefined, true, { principal: req.principal, explicitOperator: false });
-        return { status: out.status, body: out.body };
+        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, 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/checkpoint-ctx.d.ts

@@ -157,6 +157,14 @@ export type StoredBodyReplayRefusal =
  | {
     readonly kind: "settings_env_credential";
     readonly refusal: Refusal;
+}
+/** 存体里有本版读者读不出、而本部署会采纳的成员(hooks / settings.env / permissions / MCP transport / A2A headers …;判据 `unread-request-members.ts`):`refusal` = 拒点 `resolveSpec` 抛的那只 400
+ *  (`request.field_invalid`,`field` = 第一个坐标,句子点名全部坐标)的码、句子与机读位,答复折成 409 `resume_blocked_by_policy`;`members` = 判据交回的坐标(键路径与下标,不带值;与拒句同一个上限,截断由问点做),`memberCount` = 总数 —— 运维行读这两格。 */
+ | {
+    readonly kind: "unread_members";
+    readonly refusal: Refusal;
+    readonly members: readonly string[];
+    readonly memberCount: number;
 } | {
     readonly kind: "permission_mode_reading";
     readonly stored: PermissionMode | undefined;
@@ -202,6 +210,13 @@ export interface ResumeRefusalAnswer {
  * · (`retriable`,卡在才在)。
  */
 export declare function resumeBlockedByPolicyAnswer(inner: Refusal): ResumeRefusalAnswer;
+/**
+ * 续跑腿上认领之前一只 typed 拒的**唯一折法**(`resume-legs.ts` 的两处折叠口同调:装配 `resolveResumeSpec` 与停驻赎回的执行上下文)。一条律:
+ * 拒体自报这一拍答不出(`permanence: "transient"` —— 依赖此刻不可用,不是政策:今天 = 中心答不出场景裁定)⇒ 原码原状态原体(同一张卡在依赖恢复后可再决;
+ * SLA 拒扫腿按「其余 ≥400」逐拍重试,不把它当确定性拒过期掉);其余 ⇒ {@link resumeBlockedByPolicyAnswer}(准入策略挡住,`blockedBy` = 原码)。
+ * 两形之后都由调用方经 {@link resumeRefusalWithCard} 追加 `retriable`(卡仍 pending)。
+ */
+export declare function resumeAssemblyRefusalAnswer(status: number, inner: Refusal): ResumeRefusalAnswer;
 /**
  * 一次续跑的答复是不是 {@link resumeBlockedByPolicyAnswer} 铸的那一只(409 `resume_blocked_by_policy`)—— SLA 拒扫腿据此区分「同一份字节在本版永远被拒」与别的 ≥400
  * (后者可能是瞬时的,照旧逐拍重试)。码的写端与读端住在同一个模块,读端不在别处第二次手拼这个字面。
@@ -229,6 +244,8 @@ export declare function storedBodyReplayLogFields(refusal: StoredBodyReplayRefus
     storedMode?: PermissionMode | null;
     floor?: PermissionMode;
     key?: ReplayRefusedRetiredKey;
+    members?: readonly string[];
+    memberCount?: number;
     note: string;
 };
 /**

package/dist/http/checkpoint-ctx.js

@@ -97,6 +97,9 @@ export function resumeBlockedByPolicyAnswer(inner) {
         body: refusalBody({ errorCode: "resume_blocked_by_policy", message: `resume blocked by an admission policy change: ${inner.message} — nothing was resumed; if the task is still suspended on its approval, cancel it (POST /v1/runs/:id/cancel) to end it without another model turn`, facts: { blockedBy: inner.errorCode, ...inner.facts } }),
     };
 }
+export function resumeAssemblyRefusalAnswer(status, inner) {
+    return inner.facts?.permanence === "transient" ? { status, body: refusalBody(inner) } : resumeBlockedByPolicyAnswer(inner);
+}
 export function isResumeBlockedByPolicy(answer) {
     return answer.status === 409 && typeof answer.body === "object" && answer.body !== null && answer.body.errorCode === "resume_blocked_by_policy";
 }
@@ -111,6 +114,8 @@ export function storedBodyReplayLogFields(refusal) {
             return { kind: refusal.kind, layer: refusal.entry.layer, note: "this session's stored request carries a tool-list entry the engine reads as empty (a skill disallowedTools, an agent definition's denyTools / allowTools, the request's excludeTools / allowTools, or the rules in settings.permissions.deny / ask: a retired name, a case twin, a spelling no tool name can have, a rule core's grammar cannot compile, or a ~/ path rule on a lane with no home), or a permission list that is malformed or over the entry cap in either direction; it is not replayed — the task stays suspended until someone cancels it and resubmits with the entry fixed" };
         case "settings_env_credential":
             return { kind: refusal.kind, note: "this session's stored request carries credentials in settings.env (a credential variable name of this engine, or a value shaped like a secret) and the one-time window that dropped them on resume has closed; it is not replayed — the task stays suspended until someone cancels it and resubmits with the credentials moved into the engine's environment" };
+        case "unread_members":
+            return { kind: refusal.kind, members: refusal.members, memberCount: refusal.memberCount, note: "this session's stored request carries members this version's readers cannot take as written (named in the refusal: settings.hooks / settings.env / an MCP server's transport / an A2A peer's headers …) and this deployment would apply them; replaying it would run without them, so it is not replayed — the task stays suspended until someone cancels it and resubmits with those members in the current form" };
         case "permission_mode_reading":
             return { kind: refusal.kind, storedMode: refusal.stored ?? null, floor: refusal.floor, note: "this session's stored request was written before the operator's AUTONOMY plan floor was recorded in the task (earlier versions re-applied it on every resume); replaying it now would run under its submitted permission mode — the task stays suspended until someone cancels it, or AUTONOMY is set to read-only so it can finish with read-only hands" };
         case "retired_request_key":
@@ -133,6 +138,7 @@ function storedBodyReplayArmAnswer(refusal, readerVersion) {
         case "inert_tool_list":
             return resumeBlockedByPolicyAnswer(refusal.entry.extra === undefined ? { errorCode: refusal.entry.code, message: refusal.entry.message } : { errorCode: refusal.entry.code, message: refusal.entry.message, facts: refusal.entry.extra });
         case "settings_env_credential":
+        case "unread_members":
             return resumeBlockedByPolicyAnswer(refusal.refusal);
         case "permission_mode_reading": {
             const answer = permissionModeReadingRefusal();

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/claim-latency.d.ts

@@ -0,0 +1,10 @@
+/** `step` 标签的闭集:一个往返一个词。 */
+export declare const EXECUTION_CLAIM_STEPS: readonly ["run_claim", "placement_commit"];
+export type ExecutionClaimStep = (typeof EXECUTION_CLAIM_STEPS)[number];
+/** 计时落点:`Metrics` 的 `observe` 子集(deps 上没有指标注册表、或只带计数的桩 ⇒ 不计,行为逐字不变)。 */
+export interface ClaimLatencySink {
+    observe?(name: string, value: number, labels?: Record<string, string>): void;
+}
+/** 量一次认领往返(秒)。`claim` 是刚发出的往返(调用点在实参位置发起它,时钟随即起);抛也计、上抛原错。 */
+export declare function timeClaim<T>(sink: ClaimLatencySink | undefined, step: ExecutionClaimStep, claim: Promise<T>): Promise<T>;
+//# sourceMappingURL=claim-latency.d.ts.map

package/dist/http/claim-latency.js

@@ -0,0 +1,12 @@
+import { EXECUTION_CLAIM_METRIC } from "../observability/metrics.js";
+export const EXECUTION_CLAIM_STEPS = ["run_claim", "placement_commit"];
+export async function timeClaim(sink, step, claim) {
+    const started = performance.now();
+    try {
+        return await claim;
+    }
+    finally {
+        sink?.observe?.(EXECUTION_CLAIM_METRIC, (performance.now() - started) / 1000, { step });
+    }
+}
+//# sourceMappingURL=claim-latency.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;