@sema-agent/server 7.147.0 → 7.149.0

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, devOpenDeployment, systemFor, gatedSubject, sendPrincipalRefusal, sendUnauthorized, traceTokenPresented, verifiedIdentitySource } 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,10 @@ 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 readOnlyToken = !!mt && authorized(req, mt);
+            const freeArmOpen = !mt;
+            const voice = readOnlyToken || (!freeArmOpen && devOpenDeployment(deps.config)) ? undefined : actsForDeployment(req, deps.config, () => gatedSubject(req, deps.config));
+            const ok = readOnlyToken || voice === "deployment_token" || (voice === "dev_open" && freeArmOpen);
             if (!ok) {
                 sendUnauthorized(res, "operator");
                 return;
@@ -232,26 +294,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 +344,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

@@ -1,3 +1,4 @@
+import { type ClaimFace } from "./execution-context.js";
 import type { RunStore } from "../plugins/store-backend.js";
 import type { RunIdemBinding, RunRecord } from "../plugins/store-contracts.js";
 import type { PreparedTaskSubmission, RouteCtxBase, WorkflowDecisionDelivery } from "./route-ctx.js";
@@ -13,17 +14,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} 顶注)。缺席 ⇒ 只摊本会话已受理的决定行。 */
@@ -32,6 +33,12 @@ export interface DurableRunLegArgs {
      *  与 `POST /v1/tasks` 两口同形,在飞集里的这一条不再叠一枚席位。落点拒 / 续跑输入拒 / 409 / 抛 等没走到登记的出口不放,由提交门的 `finally` 兜底(`release` 幂等)。
      *  缺席 = 没有帽可放(`/decide` 第三条车道〔延续,不判帽〕、帽关着的部署)。 */
     runSlot?: RunSlot;
+    /**
+     * 这一面的两只答法(`execution-context.ts` 的 `ClaimFace`):认领之后写口交回的店的拒怎么答(`refused`),认领这一段(建行认领 → 执行放置 → 续跑输入 → workflow 决定落行 →
+     * 起跑之前的认领复核)有一次店往返没答出来怎么答(`faulted`,经 `faultedAnswerOf`;程序错照旧上抛)—— 与这一面认领之前那一读同答。认领已在出事的那一笔撤回(本请求铸的行删掉)。
+     * 提交面(`POST /v1/runs` / A2A)交 `SUBMISSION_CLAIM_FACE`;`/decide` 第三条车道交 `CONTINUATION_CLAIM_FACE`(子代的卡仍待决;决定落行那一笔的结局路由按同一只答法答)。
+     */
+    face: ClaimFace;
 }
 /**
  * 本腿的结局:一份收据,或「这次提交的一把幂等钥匙已经指向一条行」(店的原子赢或观察的**观察**臂 —— 本腿不碰
@@ -54,7 +61,7 @@ export type DurableRunLegOutcome = {
  * 建行 + 驱动。返回 `202` = 新行已建并在跑(体带 `taskId`/`sessionId`);`409` = 会话被别的 run 占着,
  * **没有**建行(体 = `buildActiveRunConflict` 的既有形,含 `errorCode: "conflict.session_active_run"`);
  * `existing` = 这次提交的钥匙(`idem.key` / `clientTaskId`)已经指向一条行,没建新行;落点拒(device 车道)与续跑输入一行装不下
- * (`413 request.payload_too_large`,`submit-ctx.ts`)= 行建了又撤了(终结 + 放认领 + 放幂等键),什么都没跑。
+ * (`413 request.payload_too_large`,`submit-ctx.ts`)= 行建了又撤了(删掉,认领与幂等键随行去),什么都没跑。
  * 协议渲染归调用方(HTTP `sendJson` / A2A 协议对象 / `/decide` 的受理体)。
  */
 export declare function mintAndDriveDurableRun(ctx: RouteCtxBase, runStore: RunStore, args: DurableRunLegArgs): Promise<DurableRunLegOutcome>;

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

@@ -1,28 +1,43 @@
 import { uuidv7 } from "@sema-agent/core";
 import { heldWorkflowParkDecisions } from "../parked-decide.js";
-import { HEARTBEAT_MS, runInBackground } from "../runs.js";
+import { runInBackground } from "../runs.js";
+import { recheckClaimBeforeLaunch, refusalAfterLostClaim, startClaimHeartbeat } from "./claim-heartbeat.js";
 import { heldFor } from "../peer-seat.js";
 import { fleetRunPublisher, fleetRunLabels, nameFleetRowOnDelivery } from "../fleet/fleet-bus.js";
 import { cascadeConfig, fillRunPreviewOnDelivery, runMeta } from "./run-meta.js";
+import { approvalLegOriginOf } from "../approval-leg-origin.js";
 import { declaredApprovalFrameFamilies, resolveStreamApprovalGate } from "../tool-approval.js";
 import { buildActiveRunConflict } from "./active-run-conflict.js";
-import { commitExecutionContext } from "./execution-context.js";
+import { commitExecutionContext, faultedAnswerOf } from "./execution-context.js";
 import { rootSessionAbsentAnswer } from "./execution-context.js";
 import { timeClaim } from "./claim-latency.js";
 import { commitSessionInheritEnv } from "./session-inherit-env.js";
 import { clearTurnActivity, readTurnActivityMs } from "../turn-activity.js";
 import { recordResourceWindow } from "../resource-window.js";
-import { persistSubmissionCtx } from "./submit-ctx.js";
-import { releaseClaimedRun } from "./claimed-run.js";
+import { persistSubmissionCtx, SUBMIT_CTX_CLAIM_LOST } from "./submit-ctx.js";
+import { withdrawClaimedRun } from "./claimed-run.js";
 import { headReadOf } from "../session-incarnation.js";
 import { createSessionWorkspaceRecorder, sessionWorkspaceStoreOf } from "../session-workspace.js";
 export async function mintAndDriveDurableRun(ctx, runStore, args) {
     const { deps } = ctx;
-    const { inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
     const sessionId = args.prepared.spec.sessionId;
     const taskId = args.clientTaskId ?? uuidv7();
     const trustedInternals = await heldWorkflowParkDecisions(deps, sessionId, args.workflowDecision?.carried);
-    const created = await timeClaim(deps.metrics, "run_claim", runStore.createRun(taskId, sessionId, args.prepared.auth?.principal ?? null, deps.instanceId ?? "default", { ...runMeta(args.prepared, args.source), identity: args.identity, idem: args.idem ?? null }));
+    let legId;
+    try {
+        const claimed = await claimAndCommit(ctx, runStore, args, sessionId, taskId);
+        if (!("holdingLeg" in claimed))
+            return claimed;
+        legId = claimed.holdingLeg;
+    }
+    catch (e) {
+        return faultedAnswerOf(e, args.face.faulted);
+    }
+    return launchDurableRun(ctx, runStore, args, sessionId, taskId, trustedInternals, legId);
+}
+async function claimAndCommit(ctx, runStore, args, sessionId, taskId) {
+    const { deps } = ctx;
+    const created = await timeClaim(deps.metrics, "run_claim", runStore.createRun(taskId, sessionId, args.prepared.auth?.subject ?? null, deps.instanceId ?? "default", { ...runMeta(args.prepared, args.source), identity: args.identity, idem: args.idem ?? null }));
     if (created.ok)
         clearTurnActivity(taskId);
     if (created.ok)
@@ -32,20 +47,20 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
     if (created.sessionAbsent)
         return rootSessionAbsentAnswer();
     if (!created.ok) {
-        return { status: 409, body: await buildActiveRunConflict({ runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
+        return { status: 409, body: await buildActiveRunConflict({ runStore, checkpointStore: deps.checkpointStore, governance: deps.config, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
     }
     fillRunPreviewOnDelivery(args.prepared.acceptance, runStore, taskId);
-    const owner = args.prepared.auth?.principal ?? null;
-    const preLaunchHeartbeat = setInterval(() => {
-        void runStore.heartbeat(taskId, owner).catch(() => { deps.metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
-    }, HEARTBEAT_MS);
-    preLaunchHeartbeat.unref?.();
+    args.prepared.seat.noteOwnRun(taskId);
+    const owner = args.prepared.auth?.subject ?? null;
+    const stopPreLaunchHeartbeat = startClaimHeartbeat(runStore, taskId, owner, deps.metrics);
     try {
-        const placementReject = await commitExecutionContext(deps, { kind: "run", runStore, taskId }, args.prepared.execution);
+        const placementReject = await commitExecutionContext(deps, { kind: "run", runStore, taskId, legId: created.legId }, args.prepared.execution);
         if (placementReject)
-            return placementReject;
+            return args.face.refused(placementReject);
         if (deps.checkpointStore) {
-            const ctxRefusal = await persistSubmissionCtx(deps.checkpointStore, deps, { runStore, taskId }, args.prepared);
+            const ctxRefusal = await persistSubmissionCtx(deps.checkpointStore, deps, { runStore, taskId, legId: created.legId }, args.prepared);
+            if (ctxRefusal === SUBMIT_CTX_CLAIM_LOST)
+                return await refusalAfterLostClaim(deps, runStore, sessionId, taskId);
             if (ctxRefusal)
                 return ctxRefusal;
         }
@@ -54,18 +69,26 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
                 await args.workflowDecision.commitBeforeLaunch(taskId);
             }
             catch (err) {
-                await releaseClaimedRun(runStore, taskId, `the workflow decision this run delivers could not be recorded: ${err instanceof Error ? err.message : String(err)}`, (releaseErr, step) => {
+                await withdrawClaimedRun(runStore, taskId, created.legId, (releaseErr, step) => {
                     deps.logger?.warn?.("workflow_decision_run_release_failed", { taskId, sessionId, step, err: releaseErr instanceof Error ? releaseErr.message : String(releaseErr) });
                 });
                 throw err;
             }
         }
+        const lostClaim = await recheckClaimBeforeLaunch(deps, runStore, sessionId, taskId, created.legId);
+        if (lostClaim !== undefined)
+            return lostClaim;
     }
     finally {
-        clearInterval(preLaunchHeartbeat);
+        stopPreLaunchHeartbeat();
     }
     commitSessionInheritEnv(deps, args.prepared.spec.sessionId, args.prepared.body);
-    const anchorOwner = args.prepared.auth?.principal ?? null;
+    return { holdingLeg: created.legId };
+}
+function launchDurableRun(ctx, runStore, args, sessionId, taskId, trustedInternals, legId) {
+    const { deps } = ctx;
+    const { inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
+    const anchorOwner = args.prepared.auth?.subject ?? null;
     const headOf = headReadOf(deps.sessionStorage);
     const captureTurnAnchor = deps.resumeAnchorStore && headOf
         ? async (eventId) => {
@@ -85,7 +108,7 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
         ...fleetRunLabels(args.prepared.acceptance.objectiveAtSubmit),
     });
     nameFleetRowOnDelivery(args.prepared.acceptance, fleetPub);
-    void heldFor(args.prepared.peerLease, () => runInBackground(args.prepared.runner, args.prepared.spec, runStore, taskId, deps.metrics, args.prepared.auth?.principal, args.prepared.verify, args.prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, args.prepared.spec.limits?.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, args.elicitOwner, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile, deps.promptManifests, deps.toolApproval
+    void heldFor(args.prepared.peerLease, () => runInBackground(args.prepared.runner, args.prepared.spec, runStore, taskId, { legId, runStaleSec: deps.config.runStaleSec }, deps.metrics, args.prepared.auth?.subject, args.prepared.verify, args.prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, args.prepared.spec.limits?.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, args.elicitOwner, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile, deps.promptManifests, deps.toolApproval
         ? {
             coordinator: deps.toolApproval,
             streamApprovalOn: resolveStreamApprovalGate({
@@ -97,10 +120,11 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
             windowMs: deps.config.streamApproval?.windowMs,
             windowMarginMs: deps.config.streamAskWindowMarginMs,
             declaredFamilies: declaredApprovalFrameFamilies(args.prepared.body.settings),
-            executionLane: args.prepared.execution.lane,
+            origin: approvalLegOriginOf(args.prepared.execution),
         }
-        : undefined, deps.checkpointStore, args.prepared.engineNotices, trustedInternals, deps.userInputLedger, args.prepared.acceptance, createSessionWorkspaceRecorder(sessionWorkspaceStoreOf(deps.sessionStorage), args.prepared.legFacts?.sessionWitness), args.prepared.legFacts?.skills));
+        : undefined, deps.checkpointStore, args.prepared.engineNotices, trustedInternals, deps.userInputLedger, args.prepared.acceptance, createSessionWorkspaceRecorder(sessionWorkspaceStoreOf(deps.sessionStorage), args.prepared.legFacts?.sessionWitness), args.prepared.legFacts?.skills, args.prepared.legFacts?.registeredCwd));
     args.runSlot?.release();
+    args.prepared.seat.markRecord();
     return { status: 202, body: { taskId, sessionId, status: "running", ...(args.prepared.warnings !== undefined ? { warnings: args.prepared.warnings } : {}) } };
 }
 //# sourceMappingURL=durable-run-leg.js.map

package/dist/http/execution-context.d.ts

@@ -1,44 +1,6 @@
-/**
- * **执行上下文** —— 每条执行起点从这一只解析器取同一型上下文:根会话是谁、这一位住客在根会话行上的执行放置是什么、这条执行走哪条车道、
- * 主体能不能用这条车道;认领之后的初始放置只有一只写口 {@link commitExecutionContext}。
- *
- * ## 规则(一句)
- * 根只有一个来源 = authorizer(`ServiceCoreDeps.authorize` 必填席,唯一铸点即登记点),根进 spec 只有一个写者 = {@link stampSpecRoot};
- * 执行放置**读只有一只** —— 会话店执行席 `seat.read(root)` 一次行读(住客 + 格),解析器读它、提交腿的门交来的 `judged` 比它、设备准入链判的也是这一读;
- * **写只有一只** —— 认领之后的 {@link commitExecutionContext}(按解析器那一读的住客定址,0 行按住客复读分类,永不对现住客重试)。
- *
- * ## 解析步序(设计 §3.2 表 ①–④;⑤ 取 rig 不在本版)
- *  ① 读:会话店不带执行席 ⇒ absent、`occupant` 缺(只一元车道表的部署可能);否则一次行读 —— 行不在 ⇒ 404 `resume.session_not_found`;`judged`(门判过的那一读)
- *     在场而与行头不是同一位住客(化身 ∧ 属主,写口同一只判官 `sameOccupant`)⇒ 同 404(他人在门与解析之间删掉并同 id 重登记,或同一化身的属主变了 ——
- *     local M10 认领 / identical 重戳 / SQL 导入提交点改属主 —— 判到新住客的车道就是错的);local 格是 `forking`
- *     ⇒ 409 `conflict.fork_in_progress`;读故障抛(不吞成 absent)。解析器不建行、不铸根。
- *     随后(同一步,就在那一读之后):这只根会话 id 在本进程被删过、而那一读的住客不是删前的属主 ⇒ 409 `conflict.session_id_retired`
- *     (表与规则 `deleted-session-ids.ts`,这里是它唯一的读点;店不带执行席 ⇒ fresh 判门判过的那一读,continuation 判不出 ⇒ 表里有就拒)。
- *  ② 定车道:`mirror` ⇒ 409 `conflict.session_mirror`(体带 `forkPath`);`writer(L)` 而 L 不在本部署的车道表 ⇒ 409 `execution_lane.not_served{boundLane}`;absent ⇒ 表首。
- *  ③ 授权:主体的执行车道裁定(`gateExecutionLane`,判据与码同 `runtime-caps-resolver.ts`);服务形不判。
- *  ④ 只 fresh:设备准入链(体 `deviceId` 只在 device 车道收;准入链三步 + 首绑目标三读,全读;判的是步 ① 那一读)。
- *
- * 入口三形(判别联合,{@link ExecutionEntry}):`fresh`(提交腿:根 = authorizer 交出的 `auth.sessionId`,`judged` = authorizer 判过的头)·
- * `continuation`(续跑家族与停驻赎回:根 = checkpoint / 停驻行的根;不带 `judged` —— 步 ① 那一读就是这条执行对根的唯一一读,认领之后由写口按它判;
- * run 外回退口 `POST /v1/sessions/:id/rewind-files` 同形:根 = 路径上的会话,它不认领、不提交放置,只取步 ①–③ 的拒)·
- * `service`(服务 run:没有会话根)。
- * `fresh` / `continuation` 两形型上恒带 `root: string`,`service` 形没有 `root` 键 —— 「按一只缺席的根去读行」在型上不可表达。
- *
- * ## 提交({@link commitExecutionContext};设计 §3.2「提交」)
- * 只在认领之后(四个 `createRun` 点、续跑家族 `markResuming` 之后、停驻赎回 `claimParkedAgent` 之后)调,是认领之后改执行放置的唯一写口:
- *  · 有设备意图(fresh ∧ device 车道)⇒ 首绑(设备店一只事务,按住客定址)或已绑臂的再断言(按住客再读 + 准入链再断言设备);
- *  · absent ⇒ place(非 device 车道);命中 = 成立;0 行按住客复读分类:同值 = 成立 · 异车道 ⇒ `execution_lane.tree_bound` · mirror ⇒ `conflict.session_mirror` ·
- *    gone(行不在或住客不是解析器那一位)⇒ 「会话不在」(提交腿 404 `resume.session_not_found`;停驻赎回答它自己的 `decide.not_parked`)—— **不对现住客重试**;
- *  · writer ⇒ 按住客再读断言仍是 writer(L);
- *  · 拒 ⇒ 先释放本次认领(run:终结 + 放认领 + 放幂等键;停驻:回滚认领)再交回拒答;店故障 ⇒ 释放后原样上抛(响亮,不当答案)。
- * claim 之后每一次店往返都带 {@link placementWriteDeadlineMs} 硬时限。
- *
- * ## 便利度不变(clay [ref] 硬约束)
- * 本文件**不产生任何审批**:只做「这条会话放在哪条车道 / 哪台设备上」的读、判与认领之后的一次写。device 车道上 `permissionMode: "bypassPermissions"` 的 run
- * 与 host 车道同构造同读数(判据钉在 device-first-bind 测试的「零额外审批」格)。
- */
 import type { IncomingMessage } from "node:http";
 import type { SessionHead, TaskSpec } from "@sema-agent/core";
+import { HttpError } from "../security.js";
 import { type DeviceOwner, type DeviceStore } from "../device-store.js";
 import { type DeviceEnrollment, type DeviceRejection } from "../device-enrollment.js";
 import type { ServiceConfig } from "../config.js";
@@ -88,8 +50,9 @@ export type ExecutionContext = {
 export type RootedExecutionContext = Extract<ExecutionContext, {
     readonly root: string;
 }>;
-/** 装配器(`resolveSpec`)收的那一半:根、入口形与解析器选定的车道(它不判放置、不选车道 —— `lane` 是解析器那一次的读数,装配器只读:项目包的车道门)。 */
-export type ExecutionRoot = Pick<RootedExecutionContext, "kind" | "root" | "lane">;
+/** 装配器(`resolveSpec`)收的那一半:根、入口形、解析器选定的车道与步 ① 那一读的住客(它不判放置、不选车道 —— `lane` 是解析器那一次的读数,装配器只读:项目包的车道门;
+ *  `occupant` 只给会话登记簿的围栏记「这一位住客」,换住客即清上一位的条目)。 */
+export type ExecutionRoot = Pick<RootedExecutionContext, "kind" | "root" | "lane" | "occupant">;
 /** 解析器读的部署件(全部取自同一只 `ServiceDeps`)。 */
 export interface ExecutionContextDeps {
     readonly config: ServiceConfig;
@@ -120,7 +83,7 @@ export declare function isRootSessionGoneError(err: unknown): boolean;
 /**
  * 调用方 device 域的**唯一铸造点**。`undefined` = 判不出域(无 principal,或凭据不带 tenant claim)—— 消费点必须响亮拒,禁静默空视图。
  *
- * 🔴 位置即契约:`{owner_tenant, owner_subject}` 是 O11 的 device-lane-local 复合身份(全局 principal 一个字节不动)。subject = `gatedPrincipal`(verified 链),
+ * 🔴 位置即契约:`{owner_tenant, owner_subject}` 是 O11 的 device-lane-local 复合身份(全局 principal 一个字节不动)。subject = `gatedPerson`(verified 链),
  * tenant = `ssoVerifiedScope`(registry auth-bridge JWT 的 `scope` claim)—— **两者都是签名真源,不是自报头**。管理面三读三写与首绑写协议全部从这一只函数取域;
  * 派生第二份就是把 O11 的判据本体复制成一份会漂的孪生。
  */
@@ -160,8 +123,31 @@ export type RootedTaskSpec = TaskSpec & {
  * 在场且等于根 ⇒ 同值,照盖;在场而**不等** ⇒ 400 `request.precondition_unmet`(嵌入方的装配器另点了一只会话 —— 它在型上不能这么写,
  * 走到这里只能是擦型或 JS 形;拒在建任何行之前)。续跑家族照它自己的折叠律把这只拒答成 409 `resume_blocked_by_policy`(`blockedBy` = 这只码,
  * `http/resume-legs.ts` 的 `resolveResumeSpecOrBlocked`:装配期的每一只 `HttpError` 在续跑腿上都这么折),同样什么都没续。
+ *
+ * **根「必须已在」(`requireExistingSession`)的唯一写者也是这里**(装配器不写它),按调用方交来的 {@link RootUse} 穷举 —— 用法由**选引擎入口的那条腿**交
+ * (受理漏斗:与它交给提交腿的 `cascade` 同一个值;续跑重建:`session`;续跑的梯子臂:`ladder_host`),不从提交体再读一遍:
+ *  · `session` —— 它是引擎在根上取会话时的「只接、不建」:解析器步 ① 读到过这一行(`occupant` 在场),或调用方自己要求了它(`requireExistingSession: true`;
+ *    店不带执行席时这是唯一的来源)⇒ 盖 `true`:门与引擎取会话之间这一行被删(属主删除 / 受理前拒的撤回),引擎答 `resume.session_not_found`,不在原 id 上重建一只
+ *    无主的空根;没读到行、调用方也没要求 ⇒ 不盖(只加不减:装配器交来的那一位原样留着);
+ *  · `ladder_host` —— 引擎在梯子上不取根,没有可盖的取会话 ⇒ 盖出的 spec 上**没有**这一位(交来的 spec 带着也剥掉:续跑的梯子臂从重建的那一份再盖);
+ *    根在不在、门后被删由宿主判 —— 受理口的属主门(调用方要求了它而行不在 ⇒ 404)与执行起点的认领(带 run 店的部署:根行锁之后判在不在 / 放置提交判行在 ⇒ 404)。
+ */
+export declare function stampSpecRoot(spec: ResolvedTaskSpec, ctx: ExecutionRoot, submission: SpecRootSubmission): RootedTaskSpec;
+/**
+ * 引擎拿这次提交的根做什么(闭集;{@link stampSpecRoot} 按它穷举 —— 加一种用法 ⇒ 那只 `switch` 编译红):
+ *  · `session` —— 引擎在根上取会话跑(单腿;验证门的实现腿与修复腿;续跑家族 —— 续跑、wake、宿主会话上新铸的一跑);
+ *  · `ladder_host` —— 根是梯子的宿主(`cascade: true` 的组合入口):每一级在引擎为它现铸的会话里冷跑,引擎不取根;根只是这条梯子停驻卡的归属(组合腿的 `hostSessionId`)。
  */
-export declare function stampSpecRoot(spec: ResolvedTaskSpec, ctx: ExecutionRoot): RootedTaskSpec;
+export type RootUse = "session" | "ladder_host";
+/**
+ * {@link stampSpecRoot} 的第三参:选引擎入口的那条腿交来的用法;调用方「根必须已在」的要求只属于 `session` 用法(梯子上它由宿主的门与认领判,型上没有这一键)。
+ */
+export type SpecRootSubmission = {
+    readonly use: "session";
+    readonly requireExistingSession?: unknown;
+} | {
+    readonly use: "ladder_host";
+};
 /**
  * run 店建行时根会话行已经不在(`CreateRunOutcome.sessionAbsent`:受理之后、认领之前会话被删)的**唯一**答复 ——
  * 四个建行点(同步 / 流式 / durable / wake)、解析期的「行不在 / 住客换了」与提交期的 `gone` 同答 404 `resume.session_not_found`,什么都没建、什么都没跑。
@@ -176,19 +162,100 @@ export interface ExecutionRefusal {
     readonly body: RefusalBody;
 }
 /**
- * 本次认领 —— 提交拒时要释放的东西。`run` = 四个建行点与续跑家族认领的 run 行(释放 = 终结 + 放认领 + 放幂等键,唯一写法 `releaseClaimedRun`);
- * `parked` = 停驻赎回的认领(释放 = 回滚认领;「会话不在」答那条腿既有的 `decide.not_parked`,不是提交腿的 404)。
+ * 本次认领 —— 提交没放行时要撤回的东西。撤回只有一张表({@link withdrawClaim}),按认领种类把认领撤回到**它取来时的样子**:
+ *  · `run` = 本请求铸的行(四个建行点 / wake 的现建行 / workflow 决定在宿主会话上的新一跑;`legId` = 建行交回的持有腿):取来之前没有这一行 ⇒ 每一种收场都删掉它
+ *    (唯一写法 `withdrawClaimedRun`:只认本腿持有的那一行,行仍在跑才删,认领与幂等键随行去;已被收割 / 终局 ⇒ 零删)—— 同一个 `taskId` / 同一把幂等键的重发是一次新提交;
+ *  · `resumed` = 续跑家族 `markResuming` 认领的停驻行:取来之前它停在等一张待决的卡 ⇒ 放回停驻(`restore`:认领方的写法 = 停驻的唯一提交点 `park-row-commit.ts` 的 `commitParkRow`;
+ *    认领与幂等键留着,卡仍待决,同一个决定可以再发;认领窗里落下的取消由认领方按取消收场 —— 停驻态会让下一次认领重置取消旗)。
+ *    唯一的例外是 `gone`:店答出这条 run 的会话已经不在,它再也续不了 ⇒ 终结(同 `run` 那一只写法);
+ *  · `parked` = 停驻赎回的认领:每一种收场都回滚认领。
+ * 答复不在认领上:写口交回店的拒答,各面经自己的 {@link ClaimFace} 答它。
  */
 export type ExecutionClaim = {
     readonly kind: "run";
     readonly runStore: RunStore;
     readonly taskId: string;
+    readonly legId: string;
+} | {
+    readonly kind: "resumed";
+    readonly runStore: RunStore;
+    readonly taskId: string;
+    readonly restore: () => Promise<void>;
 } | {
     readonly kind: "parked";
     readonly taskId: string;
     readonly rollback: (why: string) => Promise<unknown>;
-    readonly goneAnswer: ExecutionRefusal;
 };
+/**
+ * 认领之后、交给引擎之前那一段没放行的收场 —— **唯一**的类别判定。规则一句:**店答出的拒是答案,店的故障不是**。判在 {@link commitExecutionContext} 的两只出口上
+ * (结构判:交回拒答 vs 抛,不读错误文案);续跑腿「提交放行之后、交给引擎之前」那一段的抛同属 `faulted`(`resume-legs.ts`,经同一张撤回表):
+ *  · `gone` —— 店答出这条会话已经不在(行没了 / 住客换了,{@link isRootSessionGoneRefusal}):确定的答案,这条会话上什么都再也续不了;
+ *  · `refused` —— 店答出这条会话此刻不能在本处执行(已放在别的车道、写者在别处、设备拒):确定的答案,但会话还在 —— 与认领之前解析器读出同一个事实是同一个命运;
+ *  · `faulted` —— 店没答出来(故障 / 超时 / 程序错):证不出这条会话不能执行,不当答案用。答复只看(这一面 × 店有没有答出来):各面的瞬时答复({@link faultedAnswerOf}),
+ *    本服务自己的程序错照旧响亮 500。
+ */
+export type CommitEnding = "gone" | "refused" | "faulted";
+/**
+ * 提交点的拒答是不是「会话不在」那一只({@link rootSessionAbsentAnswer};唯一读者 —— 撤回表据它分 `gone` / `refused`,续跑家族与停驻赎回的 {@link ClaimFace} 据它决定那一只拒怎么答)。
+ * 只认这一只答复的码(与 {@link isRootSessionGoneError} 同一个判据,一个读拒答、一个读解析器的抛)。
+ */
+export declare function isRootSessionGoneRefusal(refusal: ExecutionRefusal): boolean;
+/**
+ * `faulted` 那一形的答复 —— 认领这一段(认领那一笔、认领之后的提交、续跑腿交给引擎之前的店往返、新提交起跑之前的店写)的一抛**只在这里**分两种:
+ * 店没答出来(判官的 `corrupt` / `connection` / `deployment` / `unclassified`)⇒ 这一面的瞬时答复(`answer`:新提交 {@link runStoreUnavailableAnswer} · 续跑家族
+ * `resume-ctx-read.ts` 的 `resumeClaimFaultAnswer` · 停驻赎回 `decide.store_unreachable`;每一面与它认领那一笔撞店故障同答);本服务自己的程序错(`defect`)⇒ 原样上抛,响亮成 500。
+ * 两种都不改撤回:认领已按 `faulted` 撤回(调用方在调本函数之前撤,或写口在抛之前撤)。判官加词而这里不表态 = 编译错。
+ * 设备注册簿那一次往返(设备店 / 准入链)也只经这里读:店没答出来 ⇒ 设备闭集的 {@link registryUnavailable},认领之前的准入与认领之后的首绑 / 再断言同答。
+ */
+export declare function faultedAnswerOf<A>(e: unknown, answer: () => A): A;
+/**
+ * 新提交(`POST /v1/tasks` 两腿、`POST /v1/runs` 与 A2A)撞店故障的**唯一**答复({@link SUBMISSION_CLAIM_FACE} 的 `faulted`)—— 503 `state.run_store_unavailable`:
+ * 认领之前那一次执行席读、认领那一笔(`createRun`)、认领之后的执行放置、续跑输入的写或起跑之前的认领复核,有一次店往返没答出来;本请求铸的行已撤回(删掉,认领与幂等键随行去),
+ * 什么都没起跑。稍后原样再发(同一个自带 `taskId` 也行);一直如此 ⇒ 请运维查库。句子不带店层 detail。🔴 形是给冻结门看的:`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
+ */
+export declare function runStoreUnavailableAnswer(): {
+    status: 503;
+    body: RefusalBody;
+};
+/**
+ * **一面的两只答法**(规则一句见文件头「一面一只答法」):这一面在认领之前那一读(解析器)、认领那一笔、认领之后每一笔、交给引擎之前的店往返上,
+ * 店答出的拒与店的故障各怎么答 —— 每一面只声明一次,各调用点只经它答,不各自选码:
+ *  · `refused` —— 写口交回的店的拒答(会话不在 / 本处此刻不能执行)在这一面的答复:与这一面认领之前解析器读出同一个事实同一只答;
+ *  · `faulted` —— 店没答出来在这一面的瞬时答复(经 {@link faultedAnswerOf} 读;本服务的程序错照旧上抛)。
+ * 三面:{@link SUBMISSION_CLAIM_FACE}(新提交)· {@link CONTINUATION_CLAIM_FACE}(续跑家族:决断 / `/resume` / `plan_review` / `/wake` / `/decide` 在宿主会话上起的新一跑)·
+ * 停驻赎回(`parked-decide.ts` 的 `parkedRedeemFace`,按子代句柄铸)。
+ */
+export interface ClaimFace {
+    readonly refused: (refusal: ExecutionRefusal) => ExecutionRefusal;
+    readonly faulted: () => ExecutionRefusal;
+}
+/** 新提交这一面:店答出的拒原样答(认领之前解析器那一只 typed 拒同码同体);店没答出来 ⇒ {@link runStoreUnavailableAnswer}。 */
+export declare const SUBMISSION_CLAIM_FACE: ClaimFace;
+/**
+ * 续跑家族这一面:会话不在({@link isRootSessionGoneRefusal})⇒ 原答 404 `resume.session_not_found`;其余店答出的拒 ⇒ {@link cardWaitingRefusalAnswer}(与认领之前同一只折法);
+ * 店没答出来 ⇒ `resume-ctx-read.ts` 的 `resumeClaimFaultAnswer`(503 `state.resume_context_unreadable`,卡仍待决)。
+ */
+export declare const CONTINUATION_CLAIM_FACE: ClaimFace;
+/**
+ * 一只拒在「有一张卡仍在等」的那几面上的答复(续跑家族与停驻赎回;认领之前的解析器拒与认领之后写口交回的拒同经这里)—— 认领之前那一只折法
+ * (`checkpoint-ctx.ts` 的 `resumeAssemblyRefusalAnswer`:409 `resume_blocked_by_policy`,`blockedBy` = 原码,原事实随体;自报瞬时的拒原码原状态)+ `retriable`(卡仍待决)。
+ */
+export declare function cardWaitingRefusalAnswer(refusal: ExecutionRefusal): ExecutionRefusal;
+/** 一只拒答 → typed 拒(`HttpError`;体经 `httpErrorRefusal` 读回同一份:码、句、机读事实)。解析器的拒与提交门认领之前的拒只认这一种载体。 */
+export declare function refusalHttpError(refusal: ExecutionRefusal): HttpError;
+/**
+ * **认领之前那一读**在一面上的唯一读法(提交门 / 续跑家族的重建 / 停驻赎回同调唯一的解析器 {@link resolveExecutionContext}):解析器的拒(typed `HttpError`)是答案,
+ * 原样上抛给这一面自己的折法;店没答出来 ⇒ 抛这一面的瞬时答复(`face.faulted`,载体 {@link refusalHttpError} 外套 {@link ClaimFaultAnswer} —— 与这一面认领那一笔撞店故障同答,
+ * 续跑家族的折叠口认它、不折);本服务的程序错原样上抛(响亮 500)。认领之前没有认领可撤,状态零改动。
+ */
+export declare function resolveBeforeClaim(deps: ExecutionContextDeps, entry: Extract<ExecutionEntry, {
+    readonly root: string;
+}>, face: ClaimFace): Promise<RootedExecutionContext>;
+/** {@link resolveBeforeClaim} 抛出的「店没答出来」答复(typed 拒;`answer` = 这一面的瞬时答复原体)。只有折叠口要认它(续跑家族不把它折成 409);提交门按 typed 拒原样答。 */
+export declare class ClaimFaultAnswer extends HttpError {
+    readonly answer: ExecutionRefusal;
+    constructor(answer: ExecutionRefusal);
+}
 /** {@link commitExecutionContext} 的依赖 —— 逐字取自 `ServiceDeps` 的同名键(同一只 deps 对象喂进来)。 */
 export interface ExecutionCommitDeps {
     readonly sessionStorage?: {
@@ -215,10 +282,18 @@ export declare function placementWriteDeadlineMs(runStaleSec: number | undefined
 export declare function devicePlacementErrorBody(rej: DeviceRejection): RefusalBody;
 /**
  * **认领之后的唯一写口**(四个 `createRun` 点、续跑家族 `markResuming` 之后、停驻赎回 `claimParkedAgent` 之后)。返回 `null` = 放行;
- * 否则本次认领已释放,调用方交回拒答。店故障 / 超时 ⇒ 释放后原样上抛(响亮,不当答案);设备意图那一支的注册簿故障答 {@link registryUnavailable}(设备闭集,同准入阶段)。
+ * 否则本次认领已按 {@link withdrawClaim} 撤回(店答出的拒 = `gone` / `refused`),调用方交回拒答。店故障 / 超时 ⇒ 认领按 `faulted` 撤回后原样上抛
+ * (响亮,不当答案:各调用方经 {@link faultedAnswerOf} 落自己这一面的瞬时码);设备意图那一支的注册簿往返(首绑 / 再断言)撞故障 ⇒ 交回设备闭集的 {@link registryUnavailable}
+ * (经 {@link faultedAnswerOf},与认领之前的准入同一只读法;程序错照旧上抛),执行席那一读撞故障与认领之前那一读同答(上抛)。
  *
  * 不变量(一句):**离开本函数的那一刻,这条会话(解析器那一位住客)的格就是这条执行的车道(device 车道:准入批准的那台设备);否则本次认领已释放、调用方拿到拒答。**
  * 它不说「此后不变」:认领持有期间根行住客与放置不被换绑 / 导入改动,那是各写者写事务内锁根行后读认领的保证(规则句),不在本函数重复判。
  */
 export declare function commitExecutionContext(deps: ExecutionCommitDeps, claim: ExecutionClaim, ctx: RootedExecutionContext): Promise<ExecutionRefusal | null>;
+/**
+ * **撤回本次认领的唯一一张表**(规则与各种类的落点见 {@link ExecutionClaim};类别见 {@link CommitEnding})。两个调用处:{@link commitExecutionContext} 的两只出口,
+ * 与续跑腿「提交放行之后、交给引擎之前」那一段的抛(`resume-legs.ts`,`faulted`)。`ending` 只在 `resumed` 上分叉(会话不在 ⇒ 终结;其余 ⇒ 放回停驻),另两种认领取来时就只有一个去处。
+ * 认领之后的其余几笔(续跑输入、决定落行、起跑之前的复核)撤本请求铸的行用 `run` 那一臂的同一只写法(`withdrawClaimedRun`)。
+ */
+export declare function withdrawClaim(deps: ExecutionCommitDeps, claim: ExecutionClaim, why: string, ending: CommitEnding): Promise<void>;
 //# sourceMappingURL=execution-context.d.ts.map