@sema-agent/server 7.145.0 → 7.147.0

package/dist/http/routes/session-sync.js

@@ -1,10 +1,9 @@
 import { once } from "node:events";
-import { randomBytes } from "node:crypto";
-import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator, validateFileHistoryExport } from "@sema-agent/core";
+import { sessionLogDigest, sessionLogDigestsComparable, validateFileHistoryExport } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
 import { FileHistoryUnreadableError, blobGetterOf, exportSessionManifest, exportedFileHistory, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, wipeSessionAttendants } from "../../session-sync.js";
 import * as facts from "../../capability-facts.js";
-import { classifySyncRelationshipByIds, readImportAnchors, SyncConflictError } from "../../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, createStagedLogFeed, MalformedImportEntryError, newStagingToken, readImportAnchors, SyncConflictError } from "../../session-sync-kernel.js";
 import { isUuidShape, legacyUnownedSessionOk, sessionOwnerCellOf } from "../../security.js";
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, logRequestError, msg } from "../send.js";
 import { StampedSessionArchiveError } from "../../session-error-wire.js";
@@ -14,7 +13,6 @@ import { storeFaultClassOf } from "../../plugins/store-fault.js";
 import { fleetViewOf, gatedPrincipal, explicitOperatorOk, sendUnauthorized, sessionCallerOf } from "../principal-gate.js";
 const SYNC_BLOB_MAX_BYTES = 64 * 1024 * 1024;
 const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
-const SYNC_IMPORT_BATCH = 500;
 import { SHA256_HEX_RE } from "../../digest-form.js";
 import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
 import { readSessionRulesRecords, describeSessionRulesRecordProblem } from "../../session-policy-wire.js";
@@ -40,6 +38,21 @@ export function createSessionSyncLocal() {
     };
     return { pendingStagings, importLeases, touchImportLease, cleanupStaging };
 }
+async function firstPhaseRefusal(sessionStorage, sessionId, relation, consented) {
+    if (consented || (relation !== "fork" && relation !== "stale"))
+        return undefined;
+    if (sessionStorage.assertArchiveAnonymous !== undefined && (await readSessionAgent(sessionStorage, sessionId)) === undefined) {
+        try {
+            await sessionStorage.assertArchiveAnonymous(sessionId);
+        }
+        catch (e) {
+            if (e instanceof StampedSessionArchiveError)
+                return { kind: "stamped", error: e };
+            throw e;
+        }
+    }
+    return { kind: "needs_consent" };
+}
 export async function handleSessionSync(req, res, match, ctx) {
     const { deps } = ctx;
     const { readJson, readRawBody, safeDecode, rateLimited } = ctx.helpers;
@@ -360,16 +373,12 @@ export async function handleSessionSync(req, res, match, ctx) {
                 const anchors = anchorsRead.anchors;
                 const dstIds = (await sessionStorage.listEntryIds?.(sessionId)) ?? null;
                 const relA = classifySyncRelationshipByIds(entryIds, dstIds);
-                if ((relA.relation === "fork" || relA.relation === "stale") && resolution !== "overwrite-dst") {
-                    if (sessionStorage.assertArchiveAnonymous !== undefined && (await readSessionAgent(sessionStorage, sessionId)) === undefined) {
-                        try {
-                            await sessionStorage.assertArchiveAnonymous(sessionId);
-                        }
-                        catch (e) {
-                            if (e instanceof StampedSessionArchiveError && sendSessionError(res, e, "import"))
-                                return;
-                            throw e;
-                        }
+                const refusalA = await firstPhaseRefusal(sessionStorage, sessionId, relA.relation, resolution === "overwrite-dst");
+                if (refusalA !== undefined) {
+                    if (refusalA.kind === "stamped") {
+                        if (sendSessionError(res, refusalA.error, "import"))
+                            return;
+                        throw refusalA.error;
                     }
                     sendError(res, 409, "conflict", "sync conflict", { relation: relA });
                     return;
@@ -501,7 +510,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 }
                 const importingPrincipal = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
                 const operatorOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config);
-                const token = randomBytes(8).toString("hex");
+                const token = newStagingToken();
                 const handle = sessionStorage.beginImportStaging(sessionId, token);
                 const stagingId = handle.stagingId;
                 importLeases.set(sessionId, { at: Date.now(), stagingId });
@@ -527,13 +536,8 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
-                const validator = new StreamingImportValidator();
+                const feed = createStagedLogFeed(pending.handle);
                 let lineBuf = "";
-                let pendingBatch = [];
-                const flush = async () => { if (pendingBatch.length) {
-                    await pending.handle.appendBatch(pendingBatch);
-                    pendingBatch = [];
-                } };
                 class PrecheckError extends Error {
                     status;
                     constructor(status, msg) {
@@ -542,12 +546,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     }
                 }
                 const streamedIds = new Set();
-                const onEntry = (e) => {
-                    if (!e || typeof e !== "object" || typeof e.id !== "string")
-                        throw new PrecheckError(422, "malformed entry (missing id)");
-                    streamedIds.add(e.id);
-                    validator.step(e);
-                };
+                const onEntry = async (e) => { streamedIds.add(await feed.push(e)); };
                 const utf8 = new StringDecoder("utf8");
                 try {
                     for await (const chunk of req) {
@@ -568,10 +567,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                             catch {
                                 throw new PrecheckError(400, "malformed NDJSON line");
                             }
-                            onEntry(e);
-                            pendingBatch.push(e);
-                            if (pendingBatch.length >= SYNC_IMPORT_BATCH)
-                                await flush();
+                            await onEntry(e);
                         }
                     }
                     lineBuf += utf8.end();
@@ -584,11 +580,9 @@ export async function handleSessionSync(req, res, match, ctx) {
                         catch {
                             throw new PrecheckError(400, "malformed NDJSON line");
                         }
-                        onEntry(e);
-                        pendingBatch.push(e);
+                        await onEntry(e);
                     }
-                    await flush();
-                    validator.finish();
+                    await feed.finish();
                     if (streamedIds.size !== pending.declaredEntryIds.length || !pending.declaredEntryIds.every((id) => streamedIds.has(id))) {
                         throw new PrecheckError(422, "streamed entries do not match the Phase-A declared entryIds");
                     }
@@ -600,6 +594,10 @@ export async function handleSessionSync(req, res, match, ctx) {
                         sendError(res, e.status, "invalid_entries", e.message);
                         return;
                     }
+                    if (e instanceof MalformedImportEntryError) {
+                        sendError(res, 422, "invalid_entries", e.message);
+                        return;
+                    }
                     if (sendSessionError(res, e, "import"))
                         return;
                     throw e;
@@ -696,6 +694,12 @@ export async function handleSessionSync(req, res, match, ctx) {
                 }
                 const dst = await sessionStorage.exportEntries(sessionId);
                 const relation = classifySyncRelationshipByIds(body.entryIds, dst ? dst.map((e) => e.id) : null);
+                const refusal = await firstPhaseRefusal(sessionStorage, sessionId, relation.relation, false);
+                if (refusal?.kind === "stamped") {
+                    if (sendSessionError(res, refusal.error, "import"))
+                        return;
+                    throw refusal.error;
+                }
                 sendJson(res, 200, relation);
                 return;
             }

package/dist/http/routes/sessions-list.d.ts

@@ -2,7 +2,7 @@
  * [ref] A9 域模块 —— 会话列表 / 发件链接列表。
  *
  * 路由:`GET /v1/sessions`(CC /resume picker,keyset 分页)、`GET /v1/sendfile-links`。
- * owner-scope 与 trace 列表同一权威模型(`fleetViewOf` 读档:service 凭据不报主体 / 只读 trace 凭据 / dev-open = fleet-wide;带验过的主体 = 钉住那位主体)。本域零可变状态。
+ * owner-scope 与 trace 列表同一权威模型(`fleetViewOf` 读档:service 凭据不报主体〔部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 时不算〕/ 只读 trace 凭据 / dev-open = fleet-wide;带验过的主体 = 钉住那位主体)。本域零可变状态。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionListItem } from "../../security.js";

package/dist/http/routes/sessions.d.ts

@@ -1,7 +1,7 @@
 /**
  * [ref] A9 域模块 —— 单会话面。
  *
- * 路由:`/v1/sessions/:id` 的 init / settings / mcp / head / events(SSE)/ fork / PATCH(会话行可写位)/ DELETE / policy / workspace,
+ * 路由:`/v1/sessions/:id` 的 init / settings / mcp / head / events(SSE)/ fork / rewind-files(run 外只恢复代码)/ PATCH(会话行可写位)/ DELETE / policy / workspace,
  * 外加同段的 `deps.sessionAudit` 只读审计面。
  *
  * 单域独占状态(lens1 §C2 的 12 条里的 5 条)全部收进 `SessionsLocal`,每个 server 实例一份:
@@ -121,6 +121,12 @@ export declare const SESSIONS_ROUTES: readonly [{
     readonly pattern: RegExp;
     readonly label: "/v1/sessions/:id";
     readonly methods: readonly ["GET"];
+}, {
+    readonly id: "session-rewind-files";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/rewind-files";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
 }, {
     readonly id: "session-patch";
     readonly pattern: RegExp;

package/dist/http/routes/sessions.js

@@ -8,23 +8,29 @@ import { recordFailOpen } from "../../observability/fail-open.js";
 import { MCP_DIAL_DEADLINE_MS, raceDeadline } from "../mcp-dial-deadline.js";
 import { sentMemoryComplianceFailure } from "../memory-compliance-failure-reply.js";
 import { readLayerSeat, sentMemoryLayerRefusal } from "../memory-layer-reply.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../../deployment-shape.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS } from "../../task-settings.js";
 import { readWritableSessionPermissionRules } from "../../session-policy-wire.js";
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, sseHeaders, httpErrorBody } from "../send.js";
 import { fleetViewOf, gatedPrincipal, explicitOperatorOk, sessionCallerOf, sessionOwnerReadable, sendPrincipalRefusal, sendUnauthorized } from "../principal-gate.js";
 import { headReadOf, leafOfAdmittedHead, sessionFaceOfHead } from "../../session-incarnation.js";
-import { foldOwnerUnreadable, runRowReadableOnSessionFace } from "../owner-access.js";
+import { foldOwnerUnreadable, readOwnedSessionHead, runRowReadableOnSessionFace } from "../owner-access.js";
 import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { rosterAgentId } from "./agents-roster.js";
 import { projectSessionListRow } from "./sessions-list.js";
 import { readSessionRowPatch } from "../../session-row.js";
-import { forkPathOf } from "../execution-context.js";
+import { forkPathOf, resolveExecutionContext } from "../execution-context.js";
 import { executionPlacementView } from "../../execution-placement.js";
+import { resolveHistoryAnchor } from "../../history-anchor.js";
+import { engineRefusalAnswerOf } from "../engine-refusal.js";
+import { buildRewindFilesReply } from "../rewind-files-reply.js";
 import { ForkTargetUnsettledError, forkKeyOf } from "../../plugins/session-fork.js";
 import { fieldConflictFacts } from "../../field-conflict.js";
 import { buildBoundedToolNames } from "../../panel-tool-names.js";
 import { projectMcpAuthorization } from "../../mcp-authorization-face.js";
+import { presentHostWorkspaceOf } from "../../task-cwd.js";
+import { rewindFilesUnderPurpose } from "../../execution-env-purpose.js";
 const MCP_STATUS_TTL_MS = 5_000;
 const A2A_STATUS_TTL_MS = 5_000;
 const A2A_MATERIALIZE_TIMEOUT_MS = 10_000;
@@ -615,6 +621,7 @@ export async function handleSessions(req, res, match, ctx) {
                         memoryStatusCache.delete(cacheKey); });
                 }
                 const s = await pending;
+                const workerPathsDisclosed = DEPLOYMENT_SHAPE_PREDICATES.callerOwnsWorkerDisk.holds(deps.config);
                 sendJson(res, 200, {
                     sessionId,
                     autoConsolidationArmed: deps.memoryAutoConsolidationArmed,
@@ -624,6 +631,8 @@ export async function handleSessions(req, res, match, ctx) {
                     ...(s.foldedCount !== undefined ? { foldedCount: s.foldedCount } : {}),
                     ...(s.optOutSource !== undefined ? { optOutSource: s.optOutSource } : {}),
                     ...(s.lastCaptureAt !== undefined ? { lastCaptureAt: s.lastCaptureAt } : {}),
+                    ...(s.writeHome !== undefined && workerPathsDisclosed ? { writeHome: s.writeHome } : {}),
+                    ...(s.planes !== undefined && workerPathsDisclosed ? { planes: s.planes.map((row) => ({ plane: row.plane, ...(row.status.writeHome !== undefined ? { writeHome: row.status.writeHome } : {}) })) } : {}),
                 });
             }
             catch (err) {
@@ -739,6 +748,82 @@ export async function handleSessions(req, res, match, ctx) {
             }
         }
     }
+    if (match.decl.id === "session-rewind-files") {
+        if (ctx.helpers.rateLimited(req, res))
+            return;
+        const rewind = facts.sessionRewindFiles(deps);
+        if (!rewind.available) {
+            switch (rewind.why) {
+                case "file_history_store_absent":
+                    sendError(res, 501, "capability.snapshot_store_required", "rewinding a session's files is not available on this deployment: no file-history store is wired, so no file history was ever recorded");
+                    return;
+                case "session_head_face_absent":
+                    sendError(res, 501, "capability.session_store_required", "rewinding a session's files requires a durable session store (DB_BACKEND=mysql|pg|local)");
+                    return;
+                case "resume_anchor_store_absent":
+                    sendError(res, 501, "capability.session_store_required", "rewinding a session's files is not available on this deployment: no session-store backend holds the rewind anchor map");
+                    return;
+                case "execution_lane_handless":
+                    sendError(res, 501, "capability.unavailable", "rewinding a session's files is not available on this deployment: it mounts no execution environment (REMOTE_EXEC=none), so a session has no working tree to rewind");
+                    return;
+                case "workspace_rebuilt_per_task":
+                    sendError(res, 501, "capability.unavailable", "rewinding a session's files is not available on this deployment: each task's workspace is rebuilt when the task starts (fresh, or restored from a saved copy that a rewind cannot yet write into), so a rewind would not reach the files the next task works on");
+                    return;
+                case "session_store_shared":
+                    sendError(res, 501, "capability.unavailable", "rewinding a session's files is not available on this deployment yet: its session store is shared by several server instances (DB_BACKEND=mysql|pg), and a rewind cannot yet keep runs started on another instance off the session while it restores");
+                    return;
+                default:
+                    return assertNever(rewind.why);
+            }
+        }
+        const { anchors, sessionStorage } = rewind;
+        const sessionId = safeDecode(match.params.sessionId);
+        if (sessionId === null || !isUuidShape(sessionId)) {
+            sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
+            return;
+        }
+        const caller = sessionCallerOf(req, deps);
+        if (DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(deps.config) && caller.principal === undefined) {
+            sendPrincipalRefusal(res, req, deps.config);
+            return;
+        }
+        const owned = await readOwnedSessionHead(deps, sessionStorage, caller, sessionId, "owner_or_operator");
+        if (owned === undefined) {
+            sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            return;
+        }
+        const sessionOwner = owned.head.owner;
+        leafOfAdmittedHead(owned.head);
+        const read = readRewindFilesBody(await readJson(req));
+        if (read.kind === "refused") {
+            sendError(res, 400, read.errorCode, read.message);
+            return;
+        }
+        const execution = await resolveExecutionContext(deps, { kind: "continuation", root: sessionId, principal: sessionOwner ?? undefined });
+        if (execution.lane === "host" && (await presentHostWorkspaceOf(deps.perSessionCwd?.get(sessionId))) === undefined) {
+            sendError(res, 409, "conflict.session_workspace_unknown", "this server process does not know a working directory for this session that it can rewind into (no prompt carrying its cwd has been submitted since the server started, or the directory that prompt named no longer exists), so nothing was rewound; submit a prompt with its cwd first, then rewind");
+            return;
+        }
+        const entryId = await resolveHistoryAnchor("rewindFilesTo", anchors, sessionId, read.to, sessionOwner, "to");
+        const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
+        if (activeTaskId) {
+            sendError(res, 409, "conflict.session_active_run", `session has an active run (${activeTaskId}); its files cannot be rewound under it — wait for that run to end (or cancel it), then rewind`, { activeTaskId });
+            return;
+        }
+        let result;
+        try {
+            result = await rewindFilesUnderPurpose(deps.runner, { sessionId, to: entryId, dryRun: read.dryRun });
+        }
+        catch (e) {
+            const answer = engineRefusalAnswerOf(e);
+            if (answer === undefined)
+                throw e;
+            sendError(res, answer.status, answer.refusal.errorCode, answer.refusal.message);
+            return;
+        }
+        sendJson(res, 200, buildRewindFilesReply(result));
+        return;
+    }
     {
         if (match.decl.id === "session-fork") {
             const forkFact = facts.sessionFork(deps);
@@ -963,6 +1048,7 @@ export const SESSIONS_ROUTES = [
     { id: "session-memory-status", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/memory-status$/, label: "/v1/sessions/:id/memory-status", methods: ["GET"] },
     { id: "session-workspace", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/workspace(?:\/(?<key>[^/]+)(?:\/(?<sub>tree|file|archive))?)?$/, label: "/v1/sessions/:id/workspace", methods: ["GET"] },
     { id: "session-detail", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["GET"] },
+    { id: "session-rewind-files", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/rewind-files$/, label: "/v1/sessions/:id/rewind-files", credentialGated: ["POST"], methods: ["POST"] },
     { id: "session-patch", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["PATCH"] },
     { id: "session-delete", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["DELETE"] },
 ];
@@ -985,4 +1071,24 @@ function readForkTarget(raw, sourceId) {
     return { kind: "keyed", forkId, forkNonce };
 }
 const FORK_NONCE_MAX_CHARS = 255;
+const REWIND_TO_MAX_CHARS = 255;
+function readRewindFilesBody(raw) {
+    const shape = {
+        kind: "refused",
+        errorCode: "request.body_shape",
+        message: 'the rewind-files body must be an object { to: string, dryRun?: boolean } — acceptPartialRestore is not accepted: the engine\'s out-of-run rewind has no partial-restore policy, so a partial restore answers 200 with restore.outcome "partial" and every refused or failed file on its ledger',
+    };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return shape;
+    const keys = Object.keys(raw);
+    if (!keys.includes("to") || keys.some((k) => k !== "to" && k !== "dryRun"))
+        return shape;
+    const { to, dryRun } = raw;
+    if (typeof to !== "string" || to.length === 0 || to.length > REWIND_TO_MAX_CHARS) {
+        return { kind: "refused", errorCode: "request.field_invalid", message: `to must be a non-empty string of at most ${REWIND_TO_MAX_CHARS} characters: the handle of a prompt in this session (the handle rewindFilesTo takes)` };
+    }
+    if (dryRun !== undefined && typeof dryRun !== "boolean")
+        return { kind: "refused", errorCode: "request.field_invalid", message: "dryRun must be a boolean when given" };
+    return { kind: "read", to, dryRun: dryRun === true };
+}
 //# sourceMappingURL=sessions.js.map

package/dist/http/routes/tasks.js

@@ -16,7 +16,7 @@ import { buildCancelledLedgerRow, createRunAbort, mintCancelledResult } from "..
 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, 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, liveIdentityFields } 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";
@@ -27,6 +27,7 @@ import { approvalPreambleReplays, createApprovalCardEmitter, declaredApprovalFra
 import { buildActiveRunConflict, isActiveRunConflictBody, toDoneFrameResult } from "../active-run-conflict.js";
 import { commitExecutionContext } from "../execution-context.js";
 import { rootSessionAbsentAnswer } from "../execution-context.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";
@@ -76,7 +77,7 @@ const MULTI_ATTEMPT_NO_EVENT_CHANNEL_NOTICE = "verify / cascade ran with their n
 export async function handleTasks(req, res, match, ctx) {
     const { deps } = ctx;
     const { idemCache, inflightRuns, steerableRuns, counters } = ctx.registry;
-    const { readJson, rateLimited, quotaExceeded, leaseDenied, usageWindowDenied } = ctx.helpers;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied, usageWindowDenied, admitRun } = ctx.helpers;
     const { prepareSpec, finalizeTaskResult } = ctx.legs;
     const reqState = ctx.req;
     const source = ctx.req.source;
@@ -144,10 +145,14 @@ export async function handleTasks(req, res, match, ctx) {
         }
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)) || (await usageWindowDenied(req, res)))
             return;
+        let runSlot = undefined;
         const prepared = await prepareSpec(req, res, keyedBody, undefined, { liveStream });
         if (!prepared)
             return;
         try {
+            runSlot = admitRun(req, res);
+            if (runSlot === undefined)
+                return;
             const declaredFamilies = declaredApprovalFrameFamilies(prepared.body.settings);
             const approvalLegInput = (streamApprovalOn) => {
                 const legWalltimeMs = typeof prepared.spec.limits?.maxWalltimeMs === "number" ? prepared.spec.limits.maxWalltimeMs : undefined;
@@ -180,11 +185,12 @@ export async function handleTasks(req, res, match, ctx) {
                 }
                 reqState.streamTaskId = earlyDurableTid;
                 let usageKey;
+                let manifestSeat;
                 reqState.streamDetached = detachOnDisconnect;
                 sseHeaders(res, earlyDurableTid ? { "x-task-id": earlyDurableTid } : undefined);
                 if (earlyDurableTid)
                     writeMetaFrame(res, earlyDurableTid, prepared.spec.sessionId, prepared.warnings);
-                const ac = createRunAbort();
+                const ac = createRunAbort(prepared.auth?.principal ?? null);
                 let closed = false;
                 let detachLogged = false;
                 let disconnectParkGrace;
@@ -298,7 +304,7 @@ export async function handleTasks(req, res, match, ctx) {
                     };
                     if (deps.runStore) {
                         const tid = earlyDurableTid ?? uuidv7();
-                        const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), identity: runIdentityOf(req, deps.config, principal ?? null), idem: idem ?? null });
+                        const created = await timeClaim(deps.metrics, "run_claim", deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), identity: runIdentityOf(req, deps.config, principal ?? null), idem: idem ?? null }));
                         if (created.ok)
                             clearTurnActivity(tid);
                         if (created.ok)
@@ -344,6 +350,7 @@ export async function handleTasks(req, res, match, ctx) {
                         ledgerSink = createLedgerSink({ appendEvent: (seq, type, data) => rs.appendEvent(tid, seq, type, data), persistThinking: deps.config.traceThinking, onActivity: (kind, statusData) => recordTurnActivity(tid, kind, statusData), legSections: legWiringSections, usage: { modelUsage: deps.modelUsage, taskId: tid } });
                         usageKey = tid;
                         deps.modelUsage?.register(tid);
+                        manifestSeat = createPromptManifestSeat(deps.promptManifests, tid);
                         const owner = principal ?? null;
                         const abortFromVerb = () => ac.abort("cancel_verb");
                         durableHeartbeat = setInterval(() => {
@@ -355,6 +362,7 @@ export async function handleTasks(req, res, match, ctx) {
                         }, HEARTBEAT_MS);
                         durableHeartbeat.unref?.();
                         inflightRuns.set(tid, ac);
+                        runSlot?.release();
                         void Promise.resolve(rs.isCancelRequested?.(tid, owner)).then((c) => { if (c && !ac.signal.aborted)
                             abortFromVerb(); }).catch(() => undefined);
                     }
@@ -503,6 +511,8 @@ export async function handleTasks(req, res, match, ctx) {
                                     await deps.userInputLedger?.observeLegEvent(liveStream, ev);
                                     await prepared.acceptance.observe(ev);
                                     await liveWorkspace.observe(ev);
+                                    if (ledgerSink)
+                                        await manifestSeat?.drain(ledgerSink.append);
                                     if (ev.type === "done") {
                                         finalResult = await mintSubmitExitResult(ev.result, deps.checkpointStore);
                                         if (durableTaskId && finalResult)
@@ -849,7 +859,10 @@ export async function handleTasks(req, res, match, ctx) {
                 };
                 counters.uncountedBillableInflight++;
                 try {
-                    resp = await idemCache.run(inflightKey, async () => withRunReceipt(await runStreamSubmitLeg()));
+                    const settling = idemCache.run(inflightKey, async () => withRunReceipt(await runStreamSubmitLeg()));
+                    if (!ranLive)
+                        runSlot?.release();
+                    resp = await settling;
                 }
                 catch (e) {
                     deps.logger?.error("stream_error", { closed, err: redactHead(e instanceof Error ? e.message : String(e), 2000) });
@@ -861,6 +874,7 @@ export async function handleTasks(req, res, match, ctx) {
                     clearInterval(hb);
                     if (usageKey)
                         deps.modelUsage?.clear(usageKey);
+                    manifestSeat?.release();
                 }
                 if (!ranLive && resp && !res.writableEnded) {
                     writeLiveFrame(res, { type: "done", result: doneResultOfOutcome(resp), replay: true });
@@ -881,7 +895,7 @@ export async function handleTasks(req, res, match, ctx) {
                     let durableHeartbeat;
                     if (deps.runStore) {
                         const tid = uuidv7();
-                        const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), identity: runIdentityOf(req, deps.config, principal ?? null), idem: idem ?? null });
+                        const created = await timeClaim(deps.metrics, "run_claim", deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), identity: runIdentityOf(req, deps.config, principal ?? null), idem: idem ?? null }));
                         if (created.ok)
                             clearTurnActivity(tid);
                         if (created.ok)
@@ -904,7 +918,7 @@ export async function handleTasks(req, res, match, ctx) {
                             return ctxRefusal;
                     }
                     commitSessionInheritEnv(deps, prepared.spec.sessionId, prepared.body);
-                    const syncCancelCtrl = createRunAbort();
+                    const syncCancelCtrl = createRunAbort(principal ?? null);
                     markChildrenStoppedByUserOnAbort(syncCancelCtrl.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
                     if (durableTaskId && deps.runStore) {
                         const rs = deps.runStore;
@@ -920,11 +934,13 @@ export async function handleTasks(req, res, match, ctx) {
                         }, HEARTBEAT_MS);
                         durableHeartbeat.unref?.();
                         inflightRuns.set(tid, syncCancelCtrl);
+                        runSlot?.release();
                         void Promise.resolve(rs.isCancelRequested?.(tid, owner)).then((c) => { if (c && !syncCancelCtrl.signal.aborted)
                             abortFromVerb(); }).catch(() => undefined);
                     }
                     else if (durableTaskId) {
                         inflightRuns.set(durableTaskId, syncCancelCtrl);
+                        runSlot?.release();
                     }
                     const specWithSignal = { ...prepared.spec, signal: syncCancelCtrl.signal, ...(durableTaskId ? { taskId: durableTaskId } : {}) };
                     const observeSyncLegEvent = (ev) => {
@@ -1001,12 +1017,20 @@ export async function handleTasks(req, res, match, ctx) {
                     noteRunOutcome(result);
                     return { status: 200, body: withSyncSubmitKeys(buildSyncSubmitBody(exitResult)) };
                 };
-                const resp = await idemCache.run(inflightKey, async () => withRunReceipt(await runSyncSubmitLeg()));
+                let ranSyncLeg = false;
+                const settling = idemCache.run(inflightKey, async () => {
+                    ranSyncLeg = true;
+                    return withRunReceipt(await runSyncSubmitLeg());
+                });
+                if (!ranSyncLeg)
+                    runSlot?.release();
+                const resp = await settling;
                 sendSubmitResult(res, resp);
             }
             return;
         }
         finally {
+            runSlot?.release();
             prepared.peerLease.release();
         }
     }

package/dist/http/routes/trace-usage.js

@@ -102,7 +102,7 @@ export async function handleTraceUsage(req, res, match, ctx) {
             };
             const now = Date.now();
             const from = parseT(q.get("from"), now - 7 * 86_400_000);
-            const to = parseT(q.get("to"), now);
+            const to = parseT(q.get("to"), now + 1);
             if (Number.isNaN(from) || Number.isNaN(to) || from >= to) {
                 sendError(res, 400, "request.query_invalid", "invalid from/to (ISO-8601 or epoch-ms; from < to)");
                 return;

package/dist/http/run-concurrency-cap.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 在飞 run 并发帽 —— `RUN_MAX_CONCURRENT`(本副本全局)/ `RUN_MAX_CONCURRENT_PER_PRINCIPAL`(同一已验提交主体),缺省 0 = 关。
+ *
+ * ## 为什么有这一只
+ * 共享一台 GPU / 一只小模型网关的部署,调用方自己限并发不可靠(多个调用方、重试风暴、脚本一把梭)。`RATE_LIMIT_RPM` 是速率桶(每分钟几条),
+ * 不是「此刻有几条在跑」;一条 run 可以跑几十分钟,速率桶放行的新提交会在同一台机器上叠起来。本帽数的就是后一个量。
+ *
+ * ## 数什么
+ * **同一份**在飞集:`inflightRuns ∪ steerableRuns`({@link liveRunIdsOf} —— `drainState.inflight` 读的也是它;`isRunLiveOnThisReplica`(`http/server.ts`)是同一并集的逐 id 判,
+ * 另写成两只 `has` 的析取,不经本函数;计数只有这一处写法,不另造第二份)。按主体数时读 `inflightRuns` 值上的 `owner`({@link RunAbort.owner} —— 句柄与腿同寿,不另起旁表);
+ * 只在 `steerableRuns` 里的键没有属主可读,只计入全局(今天每条可 steer 的腿都同时登记在 `inflightRuns`,这是形式上的保守)。
+ * 数的是**本副本**:副本之间不共享,多副本部署的整体并发 = 各副本的帽之和。
+ *
+ * ## 判点(哪几扇门判、哪几扇不判)
+ * 判 = **新提交要起一条 run** 的三个提交门(`routes/runs.ts` 的 `createDurableRun` —— `POST /v1/runs` 与 A2A `message/send` 共用的建行腿、
+ * `routes/tasks.ts` 的 `POST /v1/tasks` 与 `POST /v1/tasks/stream`),且排在**幂等重放之后**(同键 / 自带 taskId 的重试拿回自己的回执,不吃新 429)。
+ * 不判 = 已有 run 的延续与作答:续跑、唤醒、审批 / 问答作答、`/decide` —— 它们不是新提交,在飞时照样占一格(被数;没有 run 行的老形续跑不登记进在飞集,不被数),
+ * 但拒它们会把一张已经在等人的卡卡死。所以帽闸的是**新提交**,不是在飞总数的硬上限:一条停驻的 run 续跑回来时,在飞数可以越过帽。
+ * leader 口的后台 run 不在 `inflightRuns` 里(drain 靠 `uncountedBillableInflight` 看见它),本帽不数它也不判它。
+ * 位置的两个如实:三个口的帽都排在受理漏斗(`prepareSpec`,可能为新会话做登记)**之后**、建行与 SSE 头之前 —— `POST /v1/runs` 与 A2A 口因自带 `taskId` 的重放在漏斗之后才答、帽必须排在它后面
+ * (与 lease / 治理窗的 429 同位),`POST /v1/tasks` 两口与它们同位;拒时漏斗已做的会话登记不撤。同键的并发重复提交若赶在首发还在受理(尚未落行、尚未进在飞合流)的窗里到达,按新提交判,
+ * 帽满时与其它准入门(速率 / 配额)同形可能拿到一次 429 + `Retry-After`,按它重投即拿回首发的回执。
+ *
+ * ## 席位(为什么放行不是「读一下数就完了」)
+ * 判完帽到这条 run 登记进 `inflightRuns` 之间隔着若干次 await(建行、执行放置、续跑输入落库 …)。并发一阵提交若都只「读数」,会全部在登记之前读到同一个数、
+ * 一起放行 —— 越帽。所以放行即**占一枚席位**({@link RunSlot}),在飞数 = 在飞集 + 未放的席位。席位在这条 run 登记进在飞集的那一拍放掉:
+ * 三个提交门同形:建行腿 `mintAndDriveDurableRun` 在 `runInBackground`(返回前同步登记)返回后就地放(`runSlot` 入参),`POST /v1/tasks` / `/v1/tasks/stream` 两腿在各自的
+ * `inflightRuns.set` 之后就地放;提交门的 `finally` 总再放一次兜底(早退、被别的门拒、抛 —— `release` 幂等)。登记到放席位之间没有 await,别的提交读不到
+ * 「既在集里又占着席位」的中间态,所以不重复计。
+ * 两个尾巴:合流进别人在飞建行的重复提交(同键赛过 `peek`)自己不建行 —— `POST /v1/tasks` 一族席位当场放回;`POST /v1/runs`(与 A2A 提交)的席位到这一次提交的整段结清(`.finally`)才放,
+ *   合流的那一次要等共享铸件结清,帽边上可多答一次 429;没有 run store 的部署上同步 / 流式腿根本不登记进在飞集
+ * (drain 靠 `uncountedBillableInflight` 数它们),它们的席位就活到请求结束 —— 帽照样数得到它们。
+ *
+ * ## 拒的形
+ * 429 `limit.rate_exceeded`(沿用现有限流码,不新铸一枚:消费端的分支同「稍后再来」)+ 体里机读 `reason`(闭集 {@link RATE_EXCEEDED_REASONS},今天一词)
+ * + `retryAfterSec`(固定 {@link RUN_CONCURRENCY_RETRY_AFTER_SEC});头 `Retry-After` 与体里同值,同其它限流 / 配额门的发送形(`res.setHeader("retry-after")` + `sendError`)。
+ * 拒在建行、认领会话与 SSE 头之前(受理漏斗已做的会话登记见上面「位置的两个如实」)。
+ *
+ * ## 谁需要 / 谁受伤 / 补偿
+ * 需要:共享一台 GPU 或一只小模型网关的家用 / 小团队部署。受伤:超帽者拿 429(新行为,缺省关)。补偿:缺省 0 = 关(升级零变化)+ `Retry-After` 给退避。
+ * 无主体请求(无头 service 凭据、`REQUIRE_PRINCIPAL=false` 的单用户部署)只受全局帽 —— 按主体帽对它不判(没有主体可分账)。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RunAbort } from "../run-cancel-context.js";
+import { type RefusalBody } from "./refusal-body.js";
+import type { FlatServiceDeps } from "./server.js";
+/**
+ * 本副本在飞 run 的 id 集 —— `inflightRuns`(durable 腿)∪ `steerableRuns`(活流)的**唯一**并集写法:
+ * `drainState.inflight`(排空等多久)、`isRunLiveOnThisReplica`(这条 run 是不是在本副本跑)与并发帽读的是同一份。
+ * 参数取 `ReadonlyMap`:读法不改登记簿。
+ */
+export declare function liveRunIdsOf(inflightRuns: ReadonlyMap<string, unknown>, steerableRuns: ReadonlyMap<string, unknown>): Set<string>;
+/** 并发帽拒的机读 `reason` 词。 */
+export declare const RUN_CONCURRENCY_CAP_REASON: "run_concurrency_cap";
+/**
+ * 429 `limit.rate_exceeded` 体上机读 `reason` 的**闭集**(穷举读它;加一种拒因 ⇒ 这里加一词,`switch` 的消费端编译红)。
+ * 其余 `limit.rate_exceeded` 的产地(速率桶、赎回准入、MCP 探活、烘焙提交)不带 `reason` —— 读法是「有 `reason` 才分」。
+ */
+export declare const RATE_EXCEEDED_REASONS: readonly ["run_concurrency_cap"];
+export type RateExceededReason = (typeof RATE_EXCEEDED_REASONS)[number];
+/** 退避提示:固定 5 秒(是提示不是承诺 —— 在飞的 run 可能再跑很久;帽满只说「稍后再来」)。 */
+export declare const RUN_CONCURRENCY_RETRY_AFTER_SEC = 5;
+/** 一枚席位:放行与登记进在飞集之间占着的那一格。`release` 幂等(登记点放一次,提交门的 `finally` 再放一次兜底)。 */
+export interface RunSlot {
+    release(): void;
+}
+/** 并发帽拒的 `{status, body, retryAfterSec}`(体经全仓唯一组句器;状态与退避供发送口用)。 */
+export declare function runConcurrencyRefusalOf(): {
+    readonly status: 429;
+    readonly body: RefusalBody;
+    readonly retryAfterSec: number;
+};
+export interface RunConcurrencyGate {
+    /**
+     * 提交门的并发帽准入:放行 ⇒ 交回席位(调用点登记那一拍 / `finally` 放);超帽 ⇒ 已应答 429(+ `Retry-After`),交回 `undefined`,调用点 `return`。
+     * 位序:在幂等重放、`rateLimited` / `quotaExceeded` / `leaseDenied` / `usageWindowDenied` 之后,任何建行 / 认领 / SSE 头之前。
+     */
+    admitRun(req: IncomingMessage, res: ServerResponse): RunSlot | undefined;
+}
+/** 装配口:`deps` 只读 `config`(两旋钮,每次判时现读)与 `logger`;在飞集由 server 装配层交来(两张登记簿本身,不拷)。 */
+export declare function createRunConcurrencyGate(ctx: {
+    deps: Pick<FlatServiceDeps, "config" | "logger">;
+    inflightRuns: ReadonlyMap<string, RunAbort>;
+    steerableRuns: ReadonlyMap<string, unknown>;
+}): RunConcurrencyGate;
+//# sourceMappingURL=run-concurrency-cap.d.ts.map