@sema-agent/server 7.147.0 → 7.149.0

package/dist/http/approval-sweeps.js

@@ -2,18 +2,22 @@ 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 { CARD_EXPIRE_OUTCOME, expireCardUnderStoredScope } from "../card-settle-stored-scope.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 +32,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 +49,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 +76,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 +86,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) => {
@@ -128,7 +142,7 @@ export function createApprovalSweeps(ctx) {
                     deps.logger?.warn?.("deny_sweep_policy_blocked_expire_skipped", { sessionId, skipReason: cp.status !== "pending" ? "not_pending" : "card_changed", ...blockedScalars(body) });
                     return;
                 }
-                won = await cs.expire(cardToken, cp.scope);
+                won = (await expireCardUnderStoredScope(cs, cardToken)) === CARD_EXPIRE_OUTCOME.expired;
             }
             catch (e) {
                 deps.logger?.warn?.("deny_sweep_policy_blocked_expire_failed", { sessionId, err: errText(e) });
@@ -141,16 +155,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 +194,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 +222,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, { cs, runs: deps.runStore, token: req.gateToken, logger: deps.logger });
         }
         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 +257,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 withdrawClaimedRun} 撤掉本请求刚认领的这条 run(删掉本请求铸的这一行 —— `legId` = 建行交回的持有腿,不留一条没起跑的 `running` 行占着会话等收割),再原样上抛。
+ */
+export declare function recheckClaimBeforeLaunch(deps: Pick<FlatServiceDeps, "checkpointStore" | "config" | "logger"> & LostClaimSessionFace, runStore: ClaimFenceStore & LostClaimStore, sessionId: string, taskId: string, legId: 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" | "withdrawMintedRun">;
+/**
+ * 起跑之前认领复核没过的答复(三条提交腿同一只;三臂按「此刻是谁的事实」分,各读各的):
+ *  · 认领此刻在别的 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 { withdrawClaimedRun } 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, legId) {
+    let held;
+    try {
+        held = await claimStillHeld(runStore, sessionId, taskId);
+    }
+    catch (err) {
+        await withdrawClaimedRun(runStore, taskId, legId, (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,14 +1,22 @@
 /**
- * 一条提交腿**刚认领**的 run 在起跑之前就收场 —— 撤掉本请求建的东西的**唯一**写法。三个调用点:device 落点拒
- * (`execution-context.ts` `commitExecutionContext`)、续跑输入写不进(`submit-ctx.ts` `persistSubmitCtx`)与 workflow 决定行没落成
- * (`durable-run-leg.ts` 的 fresh 投递腿;此刻认领可能已被收割归了别人 —— 两步都按这一跑自己的 taskId,碰不到别人的认领)。
+ * 一条提交腿认领的 run 在起跑之前就收场 —— 撤回这次认领,撤回到**它取来时的样子**(撤回表的唯一属主 = `execution-context.ts` 的 `withdrawClaim`),按认领种类两种写法:
  *
- * 撤两步,**各自独立**(一步失败不拦另一步,残余最小):
- *  · 终结这条 run 行(`setTerminal` 是按 taskId 的 CAS,首写者赢 ⇒ 重复调用是 no-op)—— 随之释放它的 `task_active` 认领;
- *  · 放开它占的提交幂等键(拒绝答复邀请重试;同键重试必须真跑,不是回放这次拒绝 —— `RunStore.releaseIdemKey`)。
- * 撤不掉不致命、但要响:每一步的失败各交给调用方按自己的名字留痕(`onFailure`)。终结没落下 ⇒ 起跑前的心跳随调用腿收场停下(或从没起过),`reapStale`
- * 在 `REAP_RUN_STALE_SEC` 之后把这条行翻 failed 并释放会话;幂等键没放开 ⇒ 同键重提回放这条行的回执(两形都是修前每一次的样子)。
+ * {@link withdrawClaimedRun}(本模块)—— **本请求铸的行**(四个建行点 / wake 的现建行 / workflow 决定在宿主会话上的新一跑):取来之前没有这一行 ⇒ 删掉它
+ * (店的 `withdrawMintedRun`:本请求的行 = 这一个 `taskId` 上建行交回的那一只持有腿 —— 别的腿持着的行一个字节不动;行仍在跑 ⇒ 删行、它的事件与它的认领,
+ * 幂等键在行上随行去;已被收割 / 别的终局写先到 ⇒ 零删,那一份就是它的结局)。
+ * 调用点:撤回表的 `run` 臂(认领之后的提交拒 / 店故障、续跑腿交给引擎之前的抛)、续跑输入写不进(`submit-ctx.ts` `persistSubmitCtx`)、
+ * workflow 决定行没落成(`durable-run-leg.ts` 的 fresh 投递腿)与起跑之前的认领复核答不出(`claim-heartbeat.ts` `recheckClaimBeforeLaunch`)。
+ * 行从没交给引擎、提交没放行 ⇒ 同一个自带 `taskId` / 同一把 `Idempotency-Key` 的重发是一次新提交(真跑),不是这次拒的回放。
+ * 撤不掉(店整个不可达)不致命、但要响:失败交给调用方按自己的名字留痕(`onFailure`);行留在 `running`、起跑前的心跳随调用腿收场停下(或从没起过),
+ * `reapStale` 在 `REAP_RUN_STALE_SEC` 之后把它翻 failed 并释放会话(幂等键随那条终局行 —— 同键重提回放它,与撤不掉的终结写同一残余)。
+ *
+ * {@link releaseClaimedRun}(本模块)—— **续跑认领的停驻行续不了**(店答出它的会话已不在):这一行取来之前就在,不删 ⇒ 终结、放开认领与提交幂等键。撤两步,**各自独立**
+ * (一步失败不拦另一步,残余最小):终结(`setTerminal` 按 taskId 的 CAS,首写者赢 ⇒ 重复调用是 no-op,随之释放 `task_active` 认领)· 放开幂等键(`RunStore.releaseIdemKey`)。
+ *
+ * **还续得了**(续跑认领的停驻行,会话还在、它等的那张卡仍待决)⇒ 行回到认领之前的停驻词,认领、幂等键原样留着,同一张卡可以再决 ——
+ * 这是一次停驻,写法是停驻的唯一提交点 `park-row-commit.ts` 的 `commitParkRow`(续跑腿经 `commitResumePark`),不在本模块。
  */
 import type { RunStore } from "../plugins/store-backend.js";
+export declare function withdrawClaimedRun(runStore: Pick<RunStore, "withdrawMintedRun">, taskId: string, legId: string, onFailure: (err: unknown, step: "withdraw") => void): Promise<void>;
 export declare function releaseClaimedRun(runStore: Pick<RunStore, "setTerminal" | "releaseIdemKey">, taskId: string, why: string, onFailure: (err: unknown, step: "terminal" | "idem_key") => void): Promise<void>;
 //# sourceMappingURL=claimed-run.d.ts.map

package/dist/http/claimed-run.js

@@ -1,3 +1,11 @@
+export async function withdrawClaimedRun(runStore, taskId, legId, onFailure) {
+    try {
+        await runStore.withdrawMintedRun(taskId, legId);
+    }
+    catch (err) {
+        onFailure(err, "withdraw");
+    }
+}
 export async function releaseClaimedRun(runStore, taskId, why, onFailure) {
     try {
         await runStore.setTerminal(taskId, "failed", null, why);

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;