@sema-agent/server 7.147.0 → 7.148.0

package/dist/http/routes/tasks.js

@@ -1,43 +1,45 @@
 import { redactErrorMessage, redactHead, redactTerminalResult } from "../../observability/run-terminal.js";
 import { runWithVerification, runCascade, taskNotificationDedupKey, uuidv7 } from "@sema-agent/core";
 import { heldFor } from "../../peer-seat.js";
-import { graftParkToolCallId, markChildrenStoppedByUserOnAbort, syncRefusalHttpStatus, zeroWorkRefusalFacts, releaseKeyIfZeroWorkRefusal, createPromptCommitReader, settleResumeAnchor, HEARTBEAT_MS } from "../../runs.js";
-import { atHostBoundary, sealResultForExit, outwardPlane } from "../../terminal.js";
+import { beatRunHeartbeat, graftParkToolCallId, markChildrenStoppedByUserOnAbort, syncRefusalHttpStatus, zeroWorkRefusalFacts, releaseKeyIfZeroWorkRefusal, createPromptCommitReader, settleResumeAnchor, TurnAnchorCapture, HEARTBEAT_MS } from "../../runs.js";
+import { atHostBoundary, failureCodeOf, sealResultForExit, outwardPlane } from "../../terminal.js";
 import { voidVerifierPauseCard } from "../../verifier-pause-card.js";
-import { withPrincipal } from "../../observability/principal-context.js";
+import { withSubject } from "../../observability/principal-context.js";
 import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals, nameFleetRowOnDelivery } from "../../fleet/fleet-bus.js";
 import { defaultSubagentTailBus } from "../../fleet/subagent-tail-bus.js";
 import { createLiveModelText, modelStreamOfTask } from "../../trace/model-segment.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKeyOf, NotifiedKeys } from "../../orchestration/workflow-completion-inbox.js";
-import { createForwardAppendFailedNote, createLedgerSink, createLedgerTwinEmit } from "../../trace/ledger-sink.js";
+import { createForwardAppendFailedNote, createLedgerSink } from "../../trace/ledger-sink.js";
+import { createHitlTransport } from "../../hitl-delivery.js";
 import { registerEngineNoticeLeg } from "../../trace/engine-notice-wire.js";
 import { clearTurnActivity, readTurnActivityMs, recordTurnActivity } from "../../turn-activity.js";
 import { buildCancelledLedgerRow, createRunAbort, mintCancelledResult } from "../../run-cancel-context.js";
 import { recordResourceWindow } from "../../resource-window.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { writeLiveFrame, writeLiveHeartbeat } from "../live-frame.js";
-import { contextUsageEventData, turnEndEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, compactionStartedEventData, workspaceChangedEventData, wiringManifestFaceEventData, toolRosterDeltaEventData, toolProgressEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, attachModelUsage, createPromptManifestSeat, liveIdentityFields } from "../../trace/project.js";
+import { contextUsageEventData, turnEndEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, compactionStartedEventData, workspaceChangedEventData, wiringManifestFaceEventData, toolRosterDeltaEventData, toolProgressEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, attachModelUsage, createPromptManifestSeat, identityFields } from "../../trace/project.js";
 import { cascadeConfig, fillRunPreviewOnDelivery, runMeta } from "../run-meta.js";
 import { idemCallerOf, inflightKeyOf, submissionIdemOf } from "../idempotency.js";
-import { replayOfExistingRun } from "../submit-replay.js";
-import { httpErrorCode, sendJson, sendError, sseHeaders } from "../send.js";
+import { isReplayedOutcome, replayedOutcome, replayOfExistingRun } from "../submit-replay.js";
+import { httpErrorCode, sendJson, sseHeaders } from "../send.js";
 import { collectSsePreamble } from "../sse-log.js";
 import { buildApprovalPreamble } from "../../approval-card.js";
-import { approvalPreambleReplays, createApprovalCardEmitter, declaredApprovalFrameFamilies, resolveApprovalLeg, resolveStreamApprovalGate } from "../../tool-approval.js";
+import { approvalPreambleReplays, declaredApprovalFrameFamilies, resolveApprovalLeg, resolveStreamApprovalGate } from "../../tool-approval.js";
 import { buildActiveRunConflict, isActiveRunConflictBody, toDoneFrameResult } from "../active-run-conflict.js";
 import { commitExecutionContext } from "../execution-context.js";
 import { rootSessionAbsentAnswer } from "../execution-context.js";
+import { recheckClaimBeforeLaunch, startClaimHeartbeat } from "../claim-heartbeat.js";
 import { timeClaim } from "../claim-latency.js";
 import { commitSessionInheritEnv } from "../session-inherit-env.js";
-import { headerStr, gatedPrincipal, explicitOperatorOk, runIdentityOf } from "../principal-gate.js";
-import { failOpenTagForDroppedFrame, recordFailOpen } from "../../observability/fail-open.js";
+import { headerStr, gatedPerson, gatedSubject, explicitOperatorOk, runIdentityOf } from "../principal-gate.js";
+import { recoveredSubject } from "../../owner-faces.js";
+import { recordFailOpen } from "../../observability/fail-open.js";
 import { buildSyncSubmitBody } from "../sync-submit-body.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
-import { persistSubmissionCtx } from "../submit-ctx.js";
+import { persistSubmissionCtx, SUBMIT_CTX_CLAIM_LOST } from "../submit-ctx.js";
 import { withModelReachScope } from "../../model-reach-scope.js";
 import { createInstructionSelectionLeg } from "../../instruction-selection.js";
-import { fieldConflictFacts } from "../../field-conflict.js";
 import { refusalBody } from "../refusal-body.js";
 import { heldWorkflowParkDecisions } from "../../parked-decide.js";
 import { createSessionWorkspaceRecorder, sessionWorkspaceStoreOf } from "../../session-workspace.js";
@@ -70,8 +72,8 @@ function refusalDoneResult(body) {
     const b = body;
     return { status: "failed", errorCode: String(b.errorCode), errorMessage: String(b.error) };
 }
-function doneResultOfOutcome(resp) {
-    return resp.status === 200 ? resp.body : refusalDoneResult(resp.body);
+function doneFrameOfOutcome(resp) {
+    return { type: "done", result: resp.status === 200 ? resp.body : refusalDoneResult(resp.body), ...(isReplayedOutcome(resp) ? { replay: true } : {}) };
 }
 const MULTI_ATTEMPT_NO_EVENT_CHANNEL_NOTICE = "verify / cascade ran with their normal multi-attempt semantics, but the synchronous /v1/tasks endpoint has no event channel — no status/progress frames exist to replay on this shape. For status / progress / delegated-child frames and the terminal done, submit via POST /v1/runs and read GET /v1/runs/:id/events; note that verify / cascade legs carry no per-turn stream there either (no wiring_manifest / text / turn_end frames — the engine runs those legs as result-returning attempts).";
 export async function handleTasks(req, res, match, ctx) {
@@ -99,18 +101,18 @@ export async function handleTasks(req, res, match, ctx) {
     const liveStream = match.decl.id === "tasks-submit-stream";
     {
         const rawIdem = headerStr(req.headers["idempotency-key"]);
-        const submitter = gatedPrincipal(req, deps.config);
+        const submitter = gatedSubject(req, deps.config);
         const keyedBody = rawIdem ? await readJson(req) : undefined;
         const idem = rawIdem ? submissionIdemOf(rawIdem, idemCallerOf(req, ctx), keyedBody) : undefined;
         const inflightKey = idem ? inflightKeyOf(idem, "sync") : undefined;
         const cached = inflightKey ? idemCache.peek(inflightKey) : undefined;
         const keyedRow = idem && !cached && deps.runStore ? await deps.runStore.getRunByIdem(idem.key) : undefined;
         if (keyedRow && deps.runStore) {
-            const replay = await replayOfExistingRun(keyedRow, { principal: submitter, idem }, "sync", deps, deps.runStore);
+            const replay = await replayOfExistingRun(keyedRow, { subject: submitter, idem }, "sync", deps, deps.runStore);
             if (liveStream && replay.status === 200) {
                 sseHeaders(res, { "x-task-id": keyedRow.taskId });
                 writeMetaFrame(res, keyedRow.taskId, keyedRow.sessionId);
-                writeLiveFrame(res, { type: "done", result: replay.body, replay: true });
+                writeLiveFrame(res, doneFrameOfOutcome(replay));
                 res.end();
             }
             else {
@@ -128,9 +130,9 @@ export async function handleTasks(req, res, match, ctx) {
                 hb.unref?.();
                 res.on("close", () => clearInterval(hb));
                 try {
-                    const resp = await cached;
+                    const resp = replayedOutcome(await cached);
                     if (!res.writableEnded)
-                        writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(resp), replay: true });
+                        writeLiveFrame(res, doneFrameOfOutcome(resp));
                 }
                 finally {
                     clearInterval(hb);
@@ -138,7 +140,7 @@ export async function handleTasks(req, res, match, ctx) {
                 res.end();
             }
             else {
-                const resp = await cached;
+                const resp = replayedOutcome(await cached);
                 sendSubmitResult(res, resp);
             }
             return;
@@ -150,7 +152,7 @@ export async function handleTasks(req, res, match, ctx) {
         if (!prepared)
             return;
         try {
-            runSlot = admitRun(req, res);
+            runSlot = await admitRun(req, res, prepared.seat);
             if (runSlot === undefined)
                 return;
             const declaredFamilies = declaredApprovalFrameFamilies(prepared.body.settings);
@@ -165,32 +167,32 @@ export async function handleTasks(req, res, match, ctx) {
                 };
             };
             const assembleApprovalLeg = (streamApprovalOn) => resolveApprovalLeg({ ...approvalLegInput(streamApprovalOn), nowMonotonicMs: performance.now() });
-            const principal = prepared.auth?.principal;
-            const wiringOperatorFace = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config);
+            const principal = prepared.auth?.subject;
+            const wiringOperatorFace = explicitOperatorOk(gatedPerson(req, deps.config), deps.config);
             let wiringReceipt;
             const instructionLeg = createInstructionSelectionLeg();
             const legWiringSections = () => ({ instructions: instructionLeg.segment(), skills: prepared.legFacts?.skills });
             const withRunReceipt = (out) => wiringReceipt !== undefined ? { ...out, wiringManifest: wiringReceipt } : out;
             if (liveStream) {
-                if (prepared.verify || prepared.cascade) {
-                    sendError(res, 400, "request.field_conflict", "verify / cascade are not supported on /v1/tasks/stream (both are multi-attempt, not a single stream) — use /v1/tasks or /v1/runs", fieldConflictFacts("cascade_verify", prepared.verify ? (prepared.cascade ? ["verify", "cascade"] : ["verify"]) : ["cascade"]));
-                    return;
-                }
                 const earlyDurableTid = facts.durableRuns(deps).available ? uuidv7() : undefined;
                 const streamLegStartedAt = Date.now();
                 const detachOnDisconnect = headerStr(req.headers["x-detach-on-disconnect"]) === "true";
-                if (detachOnDisconnect && earlyDurableTid === undefined) {
-                    sendError(res, 400, "request.precondition_unmet", "x-detach-on-disconnect requires a durable run (a run store + sessionId) — without one the detached result would be unqueryable");
-                    return;
-                }
                 reqState.streamTaskId = earlyDurableTid;
                 let usageKey;
                 let manifestSeat;
                 reqState.streamDetached = detachOnDisconnect;
+                let heldTerminal;
+                const writeTerminalFrame = (frame) => {
+                    if (heldTerminal === undefined && prepared.seat.keepsWithoutWithdraw)
+                        writeLiveFrame(res, frame);
+                    else
+                        heldTerminal = frame;
+                };
+                let stopClaimHeartbeat;
                 sseHeaders(res, earlyDurableTid ? { "x-task-id": earlyDurableTid } : undefined);
                 if (earlyDurableTid)
                     writeMetaFrame(res, earlyDurableTid, prepared.spec.sessionId, prepared.warnings);
-                const ac = createRunAbort(prepared.auth?.principal ?? null);
+                const ac = createRunAbort(prepared.auth?.subject ?? null);
                 let closed = false;
                 let detachLogged = false;
                 let disconnectParkGrace;
@@ -235,18 +237,9 @@ export async function handleTasks(req, res, match, ctx) {
                     checkpointStore: deps.checkpointStore,
                 });
                 const replaySessionId = approvalPreambleReplays(approvalLegInput(replayGate.active)) ? prepared.spec.sessionId : undefined;
-                const presentedOnConnection = new Set();
-                const presentedCompleted = new Set();
-                const admitPresentedComplete = (askId) => {
-                    if (!presentedOnConnection.has(askId))
-                        return true;
-                    if (presentedCompleted.has(askId))
-                        return false;
-                    presentedCompleted.add(askId);
-                    return true;
-                };
+                let connectionTransport;
                 if (replaySessionId) {
-                    const replayOwner = gatedPrincipal(req, deps.config) ?? null;
+                    const replayOwner = gatedSubject(req, deps.config) ?? null;
                     const askStore = replayGate.active ? replayGate.askStore : undefined;
                     let presentedAskIds = [];
                     const preambleFrames = await collectSsePreamble(async (signal) => {
@@ -265,13 +258,11 @@ export async function handleTasks(req, res, match, ctx) {
                         for (const f of preambleFrames)
                             writeLiveFrame(res, { ...f });
                         if (deps.toolApproval && preambleFrames.length > 0) {
-                            for (const askId of presentedAskIds)
-                                presentedOnConnection.add(askId);
                             const unwatch = deps.toolApproval.watchPresentedCards(presentedAskIds, (frame) => {
-                                if (res.writableEnded || res.destroyed || !admitPresentedComplete(frame.askId))
+                                if (res.writableEnded || res.destroyed)
                                     return;
                                 writeLiveFrame(res, { ...frame });
-                            });
+                            }, () => connectionTransport);
                             res.once("close", unwatch);
                         }
                     }
@@ -310,24 +301,28 @@ export async function handleTasks(req, res, match, ctx) {
                         if (created.ok)
                             recordResourceWindow(tid, prepared.spec.resourceSuspend);
                         if (created.existing) {
-                            const replay = await replayOfExistingRun(created.existing, { principal: submitter, idem }, "sync", deps, deps.runStore);
-                            writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(replay), replay: true });
+                            const replay = await replayOfExistingRun(created.existing, { subject: submitter, idem }, "sync", deps, deps.runStore);
+                            writeTerminalFrame(doneFrameOfOutcome(replay));
                             return replay;
                         }
                         if (created.sessionAbsent) {
                             const refused = rootSessionAbsentAnswer();
-                            writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(refused) });
+                            writeTerminalFrame(doneFrameOfOutcome(refused));
                             return refused;
                         }
                         if (!created.ok) {
-                            const conflict = await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId);
+                            const conflict = await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId);
                             const refused = { status: 409, body: conflict };
-                            writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(refused) });
+                            writeTerminalFrame(doneFrameOfOutcome(refused));
                             return refused;
                         }
+                        prepared.seat.noteOwnRun(tid);
+                        if (detachOnDisconnect)
+                            prepared.seat.markRecord();
+                        stopClaimHeartbeat = startClaimHeartbeat(deps.runStore, tid, principal ?? null, deps.metrics);
                         const placementReject = await commitExecutionContext(deps, { kind: "run", runStore: deps.runStore, taskId: tid }, prepared.execution);
                         if (placementReject) {
-                            writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(placementReject) });
+                            writeTerminalFrame(doneFrameOfOutcome(placementReject));
                             return placementReject;
                         }
                         durableTaskId = tid;
@@ -335,13 +330,18 @@ export async function handleTasks(req, res, match, ctx) {
                     }
                     if (deps.checkpointStore) {
                         const ctxRefusal = await persistSubmissionCtx(deps.checkpointStore, deps, durableTaskId !== undefined && deps.runStore ? { runStore: deps.runStore, taskId: durableTaskId } : undefined, prepared);
-                        if (ctxRefusal) {
-                            writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(ctxRefusal) });
+                        if (ctxRefusal !== undefined && ctxRefusal !== SUBMIT_CTX_CLAIM_LOST) {
+                            writeTerminalFrame(doneFrameOfOutcome(ctxRefusal));
                             return ctxRefusal;
                         }
                     }
+                    const lostClaim = durableTaskId !== undefined && deps.runStore ? await recheckClaimBeforeLaunch(deps, deps.runStore, prepared.spec.sessionId, durableTaskId) : undefined;
+                    if (lostClaim !== undefined) {
+                        writeTerminalFrame(doneFrameOfOutcome(lostClaim));
+                        return lostClaim;
+                    }
                     commitSessionInheritEnv(deps, prepared.spec.sessionId, prepared.body);
-                    markChildrenStoppedByUserOnAbort(ac.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
+                    markChildrenStoppedByUserOnAbort(ac.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.subject);
                     let ledgerSink;
                     let ledgerTerminal = false;
                     if (durableTaskId && deps.runStore) {
@@ -353,8 +353,9 @@ export async function handleTasks(req, res, match, ctx) {
                         manifestSeat = createPromptManifestSeat(deps.promptManifests, tid);
                         const owner = principal ?? null;
                         const abortFromVerb = () => ac.abort("cancel_verb");
+                        stopClaimHeartbeat?.();
                         durableHeartbeat = setInterval(() => {
-                            void rs.heartbeat(tid, owner).catch(() => undefined);
+                            beatRunHeartbeat(rs, tid, owner, () => ac.abort("stall_verdict"), () => undefined);
                             if (!ac.signal.aborted) {
                                 void Promise.resolve(rs.isCancelRequested?.(tid, owner)).then((c) => { if (c)
                                     abortFromVerb(); }).catch(() => undefined);
@@ -369,7 +370,7 @@ export async function handleTasks(req, res, match, ctx) {
                     let fleetPub;
                     try {
                         fleetPub = durableTaskId
-                            ? fleetRunPublisher(deps.fleetBus, { runId: durableTaskId, scope: gatedPrincipal(req, deps.config) ?? "default", rootTaskId: durableTaskId, sessionId: prepared.spec.sessionId, ...fleetRunLabels(prepared.acceptance.objectiveAtSubmit) })
+                            ? fleetRunPublisher(deps.fleetBus, { runId: durableTaskId, scope: gatedSubject(req, deps.config) ?? "default", rootTaskId: durableTaskId, sessionId: prepared.spec.sessionId, ...fleetRunLabels(prepared.acceptance.objectiveAtSubmit) })
                             : undefined;
                         if (fleetPub)
                             nameFleetRowOnDelivery(prepared.acceptance, fleetPub);
@@ -410,7 +411,7 @@ export async function handleTasks(req, res, match, ctx) {
                         live: (row) => {
                             if (res.writableEnded || res.destroyed) {
                                 if (noticeLedger === undefined)
-                                    recordFailOpen(failOpenTagForDroppedFrame("engine_notice"), "frame=engine_notice");
+                                    recordFailOpen("server.stream.frame-dropped-stream-closed", "frame=engine_notice");
                                 return;
                             }
                             writeLiveFrame(res, { type: "engine_notice", ...row });
@@ -425,7 +426,7 @@ export async function handleTasks(req, res, match, ctx) {
                         await deps.userInputLedger.announceUndrained({ sessionId: prepared.spec.sessionId, taskId: durableTaskId });
                     try {
                         const streamBody = async () => {
-                            await withPrincipal(principal, async () => {
+                            await withSubject(recoveredSubject(principal), async () => {
                                 const tailContentMode = prepared.spec.forwardSubagentEvents === true ? "on" : "progress_only";
                                 const childText = createLiveModelText();
                                 const topText = createLiveModelText();
@@ -510,6 +511,8 @@ export async function handleTasks(req, res, match, ctx) {
                                     const causeAtDone = ev.type === "done" ? ac.cause() : undefined;
                                     await deps.userInputLedger?.observeLegEvent(liveStream, ev);
                                     await prepared.acceptance.observe(ev);
+                                    if (ev.type === "done")
+                                        prepared.acceptance.settle(ev.result);
                                     await liveWorkspace.observe(ev);
                                     if (ledgerSink)
                                         await manifestSeat?.drain(ledgerSink.append);
@@ -523,7 +526,7 @@ export async function handleTasks(req, res, match, ctx) {
                                         finalizeTaskResult(ev.result, principal, prepared.spec.objective);
                                         noteRunOutcome(finalResult);
                                         await putRewindAnchor();
-                                        settleFleet(outwardPlane(finalResult.terminal).status, fleetRunResiduals(finalResult));
+                                        settleFleet(outwardPlane(finalResult.terminal).status, fleetRunResiduals(finalResult, failureCodeOf(finalResult.terminal)));
                                         if (ledgerSink && finalResult) {
                                             if (usageKey && deps.modelUsage && deps.runStore && durableTaskId) {
                                                 const rs2 = deps.runStore;
@@ -534,7 +537,7 @@ export async function handleTasks(req, res, match, ctx) {
                                             await ledgerSink.onDone(finalResult);
                                             ledgerTerminal = true;
                                         }
-                                        writeLiveFrame(res, { ...ev, result: finalResult });
+                                        writeTerminalFrame({ ...ev, result: finalResult });
                                         continue;
                                     }
                                     if (ledgerSink) {
@@ -617,12 +620,11 @@ export async function handleTasks(req, res, match, ctx) {
                                     }
                                     else if (ev.type === "turn_end" || ev.type === "message_committed" || ev.type === "context_usage") {
                                         const e = ev;
-                                        const ident = liveIdentityFields(e);
                                         const arm = ev.type === "turn_end"
-                                            ? { type: "turn_end", ...turnEndEventData(ev), ...ident }
+                                            ? { type: "turn_end", ...turnEndEventData(ev) }
                                             : ev.type === "message_committed"
-                                                ? { type: "message_committed", entryId: e.entryId, role: e.role, ...(e.toolCallId !== undefined ? { toolCallId: e.toolCallId } : {}), ...ident }
-                                                : { type: "context_usage", ...contextUsageEventData(ev), ...ident };
+                                                ? { type: "message_committed", entryId: e.entryId, role: e.role, ...(e.toolCallId !== undefined ? { toolCallId: e.toolCallId } : {}), ...identityFields(e) }
+                                                : { type: "context_usage", ...contextUsageEventData(ev) };
                                         writeLiveFrame(res, arm);
                                     }
                                     else {
@@ -633,22 +635,20 @@ export async function handleTasks(req, res, match, ctx) {
                             });
                         };
                         const askTaskId = durableTaskId ?? uuidv7();
-                        const askOwner = gatedPrincipal(req, deps.config) ?? null;
+                        const askOwner = gatedSubject(req, deps.config) ?? null;
                         const emitAsk = (frame) => {
                             if (res.writableEnded || res.destroyed) {
-                                recordFailOpen(failOpenTagForDroppedFrame(frame.type), `frame=${frame.type}`);
+                                recordFailOpen("server.stream.frame-dropped-stream-closed", `frame=${frame.type}`);
                                 return;
                             }
                             writeLiveFrame(res, { ...frame });
                         };
                         const faceAlive = () => !res.writableEnded && !res.destroyed;
-                        const emitElicitation = createLedgerTwinEmit({ sink: ledgerSink, writeLive: emitAsk, liveReachable: faceAlive });
-                        const writeQuestionLive = (frame) => {
-                            if (!faceAlive())
-                                throw new Error("live stream ended — question frame undeliverable");
-                            emitAsk(frame);
-                        };
-                        const emitQuestion = createLedgerTwinEmit({ sink: ledgerSink, writeLive: writeQuestionLive, liveReachable: faceAlive });
+                        const hitlTransport = createHitlTransport({
+                            ...(ledgerSink ? { ledger: ledgerSink.append } : {}),
+                            live: { write: (frame) => writeLiveFrame(res, { ...frame }), alive: faceAlive },
+                        });
+                        connectionTransport = hitlTransport;
                         await emitPendingWorkflowCompletions(deps.workflowCompletionInbox, prepared.spec.sessionId, askOwner, (frame) => {
                             if (closed || res.writableEnded || res.destroyed)
                                 throw new Error("stream ended before the completion frame was written");
@@ -659,16 +659,11 @@ export async function handleTasks(req, res, match, ctx) {
                             writeLiveFrame(res, frame);
                         }, { route: "sync-stream-open", connection: "live-sse", log: (m, x) => deps.logger?.info?.(m, x) });
                         const withElicit = deps.elicitation
-                            ? () => deps.elicitation.runWithContext({ taskId: askTaskId, owner: askOwner, emit: emitElicitation, abortSignal: ac.signal }, streamBody)
+                            ? () => deps.elicitation.runWithContext({ taskId: askTaskId, owner: askOwner, transport: hitlTransport, abortSignal: ac.signal }, streamBody)
                             : streamBody;
                         const withQuestion = () => deps.question
-                            ? deps.question.runWithContext({ taskId: askTaskId, owner: askOwner, emit: emitQuestion, abortSignal: ac.signal, deliverable: faceAlive }, withElicit)
+                            ? deps.question.runWithContext({ taskId: askTaskId, owner: askOwner, transport: hitlTransport, abortSignal: ac.signal }, withElicit)
                             : withElicit();
-                        const emitApproval = (frame) => {
-                            if (res.writableEnded || res.destroyed)
-                                throw new Error("live stream ended — approval card undeliverable");
-                            emitAsk(frame);
-                        };
                         const streamApprovalOn = resolveStreamApprovalGate({
                             toolApprovalEnabled: Boolean(deps.toolApproval),
                             streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
@@ -678,27 +673,6 @@ export async function handleTasks(req, res, match, ctx) {
                         const approvalLeg = assembleApprovalLeg(streamApprovalOn);
                         const legDeadlineMonotonic = approvalLeg.legDeadlineMonotonic;
                         const unattended = approvalLeg.unattended;
-                        const emitCard = createApprovalCardEmitter({
-                            ...(ledgerSink
-                                ? {
-                                    appendDurable: async (frame) => {
-                                        const { type, ...rest } = frame;
-                                        await ledgerSink.append(type, rest);
-                                    },
-                                }
-                                : {}),
-                            writeLive: (frame) => {
-                                if (res.writableEnded || res.destroyed)
-                                    throw new Error("live stream ended");
-                                if (frame.type === "approval_complete" && !admitPresentedComplete(frame.askId))
-                                    return;
-                                emitAsk(frame);
-                            },
-                        });
-                        const emitRevokeLive = (frame) => {
-                            if (!res.writableEnded && !res.destroyed)
-                                emitAsk(frame);
-                        };
                         const approvalCtx = deps.toolApproval && unattended === undefined
                             ? {
                                 taskId: askTaskId,
@@ -708,12 +682,12 @@ export async function handleTasks(req, res, match, ctx) {
                                 executionLane: prepared.execution.lane,
                                 ...(streamApprovalOn
                                     ? {
-                                        emitCard,
-                                        emitRevoke: emitRevokeLive,
+                                        family: "approval_request",
+                                        transport: hitlTransport,
                                         legKey: "",
                                         ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}),
                                     }
-                                    : { emit: emitApproval }),
+                                    : { family: "tool_approval", transport: hitlTransport }),
                             }
                             : undefined;
                         if (deps.toolApproval) {
@@ -754,7 +728,7 @@ export async function handleTasks(req, res, match, ctx) {
                             }
                             else {
                                 await putRewindAnchor();
-                                const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId);
+                                const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId, undefined, { axis: "run" });
                                 const dcCause = ac.cause();
                                 if (pending) {
                                     if (ledgerSink && !ledgerTerminal) {
@@ -808,7 +782,7 @@ export async function handleTasks(req, res, match, ctx) {
                             try {
                                 const row = await deps.runStore.getRun(durableTaskId);
                                 if (row?.status === "running") {
-                                    const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId);
+                                    const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId, undefined, { axis: "run" });
                                     const backstopCause = ac.cause();
                                     if (pending) {
                                         if (ledgerSink && !ledgerTerminal) {
@@ -827,7 +801,7 @@ export async function handleTasks(req, res, match, ctx) {
                                         const retryPlane = outwardPlane(finalResult.terminal);
                                         await deps.runStore.setTerminal(durableTaskId, retryPlane.status, finalResult, retryPlane.errorMessage ?? null);
                                         await releaseKeyIfZeroWorkRefusal(deps.runStore, durableTaskId, finalResult);
-                                        settleFleet(retryPlane.status, fleetRunResiduals(finalResult));
+                                        settleFleet(retryPlane.status, fleetRunResiduals(finalResult, failureCodeOf(finalResult.terminal)));
                                     }
                                     else if (backstopCause !== undefined) {
                                         const err = "stream aborted before completion (run cancelled)";
@@ -859,7 +833,14 @@ export async function handleTasks(req, res, match, ctx) {
                 };
                 counters.uncountedBillableInflight++;
                 try {
-                    const settling = idemCache.run(inflightKey, async () => withRunReceipt(await runStreamSubmitLeg()));
+                    const settling = idemCache.run(inflightKey, async () => {
+                        try {
+                            return withRunReceipt(await runStreamSubmitLeg());
+                        }
+                        finally {
+                            await prepared.seat.close();
+                        }
+                    });
                     if (!ranLive)
                         runSlot?.release();
                     resp = await settling;
@@ -872,16 +853,24 @@ export async function handleTasks(req, res, match, ctx) {
                 finally {
                     counters.uncountedBillableInflight--;
                     clearInterval(hb);
+                    stopClaimHeartbeat?.();
                     if (usageKey)
                         deps.modelUsage?.clear(usageKey);
                     manifestSeat?.release();
                 }
                 if (!ranLive && resp && !res.writableEnded) {
-                    writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(resp), replay: true });
+                    writeTerminalFrame(doneFrameOfOutcome(replayedOutcome(resp)));
                 }
+                await prepared.seat.deliverTerminal(() => {
+                    const frame = heldTerminal;
+                    heldTerminal = undefined;
+                    if (frame !== undefined && !res.writableEnded)
+                        writeLiveFrame(res, frame);
+                });
                 res.end();
             }
             else {
+                let stopSyncClaimHeartbeat;
                 const withSyncSubmitKeys = (body) => {
                     const extra = {
                         ...(prepared.verify || prepared.cascade ? { notice: MULTI_ATTEMPT_NO_EVENT_CHANNEL_NOTICE } : {}),
@@ -901,11 +890,13 @@ export async function handleTasks(req, res, match, ctx) {
                         if (created.ok)
                             recordResourceWindow(tid, prepared.spec.resourceSuspend);
                         if (created.existing)
-                            return await replayOfExistingRun(created.existing, { principal: submitter, idem }, "sync", deps, deps.runStore);
+                            return await replayOfExistingRun(created.existing, { subject: submitter, idem }, "sync", deps, deps.runStore);
                         if (created.sessionAbsent)
                             return rootSessionAbsentAnswer();
                         if (!created.ok)
-                            return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId) };
+                            return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId) };
+                        prepared.seat.noteOwnRun(tid);
+                        stopSyncClaimHeartbeat = startClaimHeartbeat(deps.runStore, tid, principal ?? null, deps.metrics);
                         const placementReject = await commitExecutionContext(deps, { kind: "run", runStore: deps.runStore, taskId: tid }, prepared.execution);
                         if (placementReject)
                             return placementReject;
@@ -914,19 +905,23 @@ export async function handleTasks(req, res, match, ctx) {
                     }
                     if (deps.checkpointStore) {
                         const ctxRefusal = await persistSubmissionCtx(deps.checkpointStore, deps, durableTaskId !== undefined && deps.runStore ? { runStore: deps.runStore, taskId: durableTaskId } : undefined, prepared);
-                        if (ctxRefusal)
+                        if (ctxRefusal !== undefined && ctxRefusal !== SUBMIT_CTX_CLAIM_LOST)
                             return ctxRefusal;
                     }
+                    const lostClaim = durableTaskId !== undefined && deps.runStore ? await recheckClaimBeforeLaunch(deps, deps.runStore, prepared.spec.sessionId, durableTaskId) : undefined;
+                    if (lostClaim !== undefined)
+                        return lostClaim;
                     commitSessionInheritEnv(deps, prepared.spec.sessionId, prepared.body);
                     const syncCancelCtrl = createRunAbort(principal ?? null);
-                    markChildrenStoppedByUserOnAbort(syncCancelCtrl.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
+                    markChildrenStoppedByUserOnAbort(syncCancelCtrl.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.subject);
                     if (durableTaskId && deps.runStore) {
                         const rs = deps.runStore;
                         const tid = durableTaskId;
                         const owner = principal ?? null;
                         const abortFromVerb = () => syncCancelCtrl.abort("cancel_verb");
+                        stopSyncClaimHeartbeat?.();
                         durableHeartbeat = setInterval(() => {
-                            void rs.heartbeat(tid, owner).catch(() => undefined);
+                            beatRunHeartbeat(rs, tid, owner, () => syncCancelCtrl.abort("stall_verdict"), () => undefined);
                             if (!syncCancelCtrl.signal.aborted) {
                                 void Promise.resolve(rs.isCancelRequested?.(tid, owner)).then((c) => { if (c)
                                     abortFromVerb(); }).catch(() => undefined);
@@ -957,14 +952,28 @@ export async function handleTasks(req, res, match, ctx) {
                         const plainLeg = async () => {
                             const stream = prepared.runner.runTaskStream(specWithSignal, undefined, heldDecisions);
                             const syncWorkspace = createSessionWorkspaceRecorder(sessionWorkspaceStoreOf(deps.sessionStorage), prepared.legFacts?.sessionWitness);
+                            const anchorKey = durableTaskId;
+                            const anchorStore = deps.resumeAnchorStore;
+                            const anchor = new TurnAnchorCapture(undefined, "sync", anchorStore && anchorKey ? async (entryId) => { await anchorStore.put(prepared.spec.sessionId, anchorKey, entryId, principal ?? null); } : undefined);
                             for await (const ev of stream) {
                                 observeSyncLegEvent(ev);
+                                switch (ev.type) {
+                                    case "human_input":
+                                        anchor.onHumanInput(ev);
+                                        break;
+                                    case "message_committed":
+                                        await anchor.onMessageCommitted(ev.role, ev.entryId);
+                                        break;
+                                    case "turn_end":
+                                        await anchor.onTurnEnd();
+                                        break;
+                                }
                                 await prepared.acceptance.observe(ev);
                                 await syncWorkspace.observe(ev);
                             }
                             return stream.result();
                         };
-                        result = atHostBoundary(await instructionLeg.run(prepared.spec.sessionId, () => withPrincipal(principal, () => prepared.verify ? verifyLeg(prepared.verify) : prepared.cascade ? cascadeLeg() : plainLeg())), prepared.spec.sessionId);
+                        result = atHostBoundary(await instructionLeg.run(prepared.spec.sessionId, () => withSubject(recoveredSubject(principal), () => prepared.verify ? verifyLeg(prepared.verify) : prepared.cascade ? cascadeLeg() : plainLeg())));
                     }
                     finally {
                         counters.uncountedBillableInflight--;
@@ -1020,18 +1029,25 @@ export async function handleTasks(req, res, match, ctx) {
                 let ranSyncLeg = false;
                 const settling = idemCache.run(inflightKey, async () => {
                     ranSyncLeg = true;
-                    return withRunReceipt(await runSyncSubmitLeg());
+                    try {
+                        return withRunReceipt(await runSyncSubmitLeg());
+                    }
+                    finally {
+                        await prepared.seat.close();
+                    }
                 });
                 if (!ranSyncLeg)
                     runSlot?.release();
-                const resp = await settling;
-                sendSubmitResult(res, resp);
+                const settled = await settling.finally(() => stopSyncClaimHeartbeat?.());
+                const resp = ranSyncLeg ? settled : replayedOutcome(settled);
+                await prepared.seat.deliverTerminal(() => sendSubmitResult(res, resp));
             }
             return;
         }
         finally {
             runSlot?.release();
             prepared.peerLease.release();
+            await prepared.seat.close();
         }
     }
 }

package/dist/http/routes/trace-usage.d.ts

@@ -1,15 +1,3 @@
-/**
- * [ref] A9 域模块 —— Task Trace 只读面 + 用量统计面。
- *
- * 路由:`GET /v1/tasks/source-summary`(跨租户 door 汇总,ops-only)、`GET /v1/tasks[/:id/{turns,stream,artifacts}]`
- * (S1 Task Trace API)、`GET /v1/usage/{summary,series,breakdown}`(web P4 / registry AnalyticsSource)。
- *
- * ⚠️ 三块都跑在全局 service-credential 门**之前**(与 /metrics 同款待遇)——只读 traceToken 单凭据的调用方
- * (registry 中继的姿势)在全局门会被 401,挂门后=门内 traceToken 支持成死代码(1.148 a2 实机抓获)。
- * [ref](7.105.0):门前不等于不设防 —— 本域坐在读路谓词段,先过 `dispatch.ts` 的 `readCredentialOk`
- * (部署配了 service 凭据时要「service token / traceToken / 已验 principal」之一),块内这几道门在它之后。
- * 因此本域在 `handle()` 里的位置就是契约的一部分:必须留在鉴权门上方,顺序不可与其他域对调。本域零可变状态。
- */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`