@sema-agent/server 7.124.1 → 7.125.1

package/dist/http/routes/tasks.js

@@ -1,6 +1,6 @@
 import { redactErrorMessage, redactHead, redactTerminalResult } from "../../observability/run-terminal.js";
 import { runWithVerification, runCascade, taskNotificationDedupKey, uuidv7 } from "@sema-agent/core";
-import { graftParkToolCallId, markChildrenStoppedByUserOnAbort, syncRefusalHttpStatus, HEARTBEAT_MS } from "../../runs.js";
+import { graftParkToolCallId, markChildrenStoppedByUserOnAbort, syncRefusalHttpStatus, releaseKeyIfZeroWorkRefusal, HEARTBEAT_MS } from "../../runs.js";
 import { sealResultForExit, outwardPlane } from "../../terminal.js";
 import { withPrincipal } from "../../observability/principal-context.js";
 import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals, isFleetAgentTerminalNotification } from "../../fleet/fleet-bus.js";
@@ -15,12 +15,13 @@ import { recordResourceWindow } from "../../resource-window.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { contextUsageEventData, turnEndEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestFaceEventData, toolRosterDeltaEventData, toolProgressEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, attachModelUsage, textEndEventData, liveIdentityFields } from "../../trace/project.js";
 import { cascadeConfig, runMeta } from "../run-meta.js";
-import { scopedIdempotencyKey } from "../idempotency.js";
+import { idemCallerOf, idemKeyOf, inflightKeyOf } from "../idempotency.js";
+import { replayOfExistingRun } from "../submit-replay.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
 import { collectSsePreamble } from "../sse-log.js";
 import { buildApprovalPreamble, buildApprovalPreambleSseFrames } from "../../approval-card.js";
 import { createApprovalCardEmitter, resolveApprovalLeg, resolveStreamApprovalGate } from "../../tool-approval.js";
-import { buildActiveRunConflict, toDoneFrameResult } from "../active-run-conflict.js";
+import { buildActiveRunConflict, isActiveRunConflictBody, toDoneFrameResult } from "../active-run-conflict.js";
 import { commitPlacement, devicePlacementErrorBody } from "../device-placement.js";
 import { commitSessionInheritEnv } from "../session-inherit-env.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
@@ -57,6 +58,18 @@ function sendSubmitResult(res, resp) {
         : raw;
     sendJson(res, 200, body);
 }
+function writeMetaFrame(res, taskId, sessionId) {
+    res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", taskId, ...(sessionId ? { sessionId } : {}) })}\n\n`);
+}
+function refusalDoneResult(body) {
+    if (isActiveRunConflictBody(body))
+        return toDoneFrameResult(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);
+}
 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) {
     const { deps } = ctx;
@@ -83,8 +96,24 @@ export async function handleTasks(req, res, match, ctx) {
     const liveStream = match.decl.id === "tasks-submit-stream";
     {
         const rawIdem = headerStr(req.headers["idempotency-key"]);
-        const idemKey = rawIdem ? scopedIdempotencyKey(rawIdem, source, gatedPrincipal(req, deps.config)) : undefined;
-        const cached = idemKey ? idemCache.peek(idemKey) : undefined;
+        const submitter = gatedPrincipal(req, deps.config);
+        const idemKey = rawIdem ? idemKeyOf(rawIdem, idemCallerOf(req, ctx), "run") : undefined;
+        const inflightKey = idemKey ? inflightKeyOf(idemKey, "sync") : undefined;
+        const cached = inflightKey ? idemCache.peek(inflightKey) : undefined;
+        const keyedRow = idemKey && !cached && deps.runStore ? await deps.runStore.getRunByIdem(idemKey) : undefined;
+        if (keyedRow && deps.runStore) {
+            const replay = await replayOfExistingRun(keyedRow, { principal: submitter }, "sync", deps, deps.runStore);
+            if (liveStream && replay.status === 200) {
+                sseHeaders(res, { "x-task-id": keyedRow.taskId });
+                writeMetaFrame(res, keyedRow.taskId, keyedRow.sessionId);
+                sseData(res, { type: "done", result: replay.body, replay: true });
+                res.end();
+            }
+            else {
+                sendSubmitResult(res, replay);
+            }
+            return;
+        }
         if (cached) {
             if (liveStream) {
                 sseHeaders(res);
@@ -97,7 +126,7 @@ export async function handleTasks(req, res, match, ctx) {
                 try {
                     const resp = await cached;
                     if (!res.writableEnded)
-                        sseData(res, { type: "done", result: resp.body, replay: true });
+                        sseData(res, { type: "done", result: doneResultOfOutcome(resp), replay: true });
                 }
                 finally {
                     clearInterval(hb);
@@ -136,9 +165,8 @@ export async function handleTasks(req, res, match, ctx) {
             let usageKey;
             reqState.streamDetached = detachOnDisconnect;
             sseHeaders(res, earlyDurableTid ? { "x-task-id": earlyDurableTid } : undefined);
-            if (earlyDurableTid) {
-                res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", taskId: earlyDurableTid, ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}) })}\n\n`);
-            }
+            if (earlyDurableTid)
+                writeMetaFrame(res, earlyDurableTid, prepared.spec.sessionId);
             const ac = createRunAbort();
             let closed = false;
             let detachLogged = false;
@@ -229,23 +257,30 @@ export async function handleTasks(req, res, match, ctx) {
                 };
                 if (deps.runStore && prepared.spec.sessionId) {
                     const tid = earlyDurableTid ?? uuidv7();
-                    const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", runMeta(prepared, source));
+                    const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), idemKey: idemKey ?? null });
                     if (created.ok)
                         clearTurnActivity(tid);
                     if (created.ok)
                         recordResourceWindow(tid, prepared.spec.resourceSuspend);
                     if (created.ok)
                         deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective, typeof prepared.spec.model === "string" ? prepared.spec.model : prepared.spec.model?.id);
+                    if (created.existing) {
+                        const replay = await replayOfExistingRun(created.existing, { principal: submitter }, "sync", deps, deps.runStore);
+                        sseData(res, { type: "done", result: doneResultOfOutcome(replay), replay: true });
+                        return replay;
+                    }
                     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);
-                        sseData(res, { type: "done", result: toDoneFrameResult(conflict) });
-                        return { status: 409, body: conflict };
+                        const refused = { status: 409, body: conflict };
+                        sseData(res, { type: "done", result: doneResultOfOutcome(refused) });
+                        return refused;
                     }
                     const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
                     if (placementReject) {
                         const body = devicePlacementErrorBody(placementReject);
-                        sseData(res, { type: "done", result: { status: "failed", errorCode: body.errorCode, errorMessage: body.error } });
-                        return { status: placementReject.status, body };
+                        const refused = { status: placementReject.status, body };
+                        sseData(res, { type: "done", result: doneResultOfOutcome(refused) });
+                        return refused;
                     }
                     durableTaskId = tid;
                 }
@@ -280,7 +315,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, ...fleetRunLabels(prepared.spec.objective) })
+                        ? fleetRunPublisher(deps.fleetBus, { runId: durableTaskId, scope: gatedPrincipal(req, deps.config) ?? "default", rootTaskId: durableTaskId, sessionId: prepared.spec.sessionId, ...fleetRunLabels(prepared.spec.objective) })
                         : undefined;
                 }
                 catch (e) {
@@ -658,8 +693,10 @@ export async function handleTasks(req, res, match, ctx) {
                             await deps.runStore.setSuspended(durableTaskId, finalResult);
                         else if (finalResult && finalPlane?.status === "needs_review" && deps.checkpointStore)
                             await deps.runStore.setNeedsReview(durableTaskId, finalResult);
-                        else if (finalResult && finalPlane)
+                        else if (finalResult && finalPlane) {
                             await deps.runStore.setTerminal(durableTaskId, finalPlane.status, finalResult, finalPlane.errorMessage ?? null);
+                            await releaseKeyIfZeroWorkRefusal(deps.runStore, durableTaskId, finalResult);
+                        }
                         else {
                             putRewindAnchor();
                             const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId);
@@ -734,6 +771,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));
                                 }
                                 else if (backstopCause !== undefined) {
@@ -766,7 +804,7 @@ export async function handleTasks(req, res, match, ctx) {
             };
             counters.uncountedBillableInflight++;
             try {
-                resp = await idemCache.run(idemKey, async () => withRunReceipt(await runStreamSubmitLeg()), (r) => r.body?.terminal.kind === "completed");
+                resp = await idemCache.run(inflightKey, async () => withRunReceipt(await runStreamSubmitLeg()));
             }
             catch (e) {
                 deps.logger?.error("stream_error", { closed, err: redactHead(e instanceof Error ? e.message : String(e), 2000) });
@@ -780,7 +818,7 @@ export async function handleTasks(req, res, match, ctx) {
                     deps.modelUsage?.clear(usageKey);
             }
             if (!ranLive && resp && !res.writableEnded) {
-                sseData(res, { type: "done", result: resp.body, replay: true });
+                sseData(res, { type: "done", result: doneResultOfOutcome(resp), replay: true });
             }
             res.end();
         }
@@ -792,11 +830,13 @@ export async function handleTasks(req, res, match, ctx) {
                 let durableHeartbeat;
                 if (deps.runStore && prepared.spec.sessionId) {
                     const tid = uuidv7();
-                    const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", runMeta(prepared, source));
+                    const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), idemKey: idemKey ?? null });
                     if (created.ok)
                         clearTurnActivity(tid);
                     if (created.ok)
                         recordResourceWindow(tid, prepared.spec.resourceSuspend);
+                    if (created.existing)
+                        return await replayOfExistingRun(created.existing, { principal: submitter }, "sync", deps, deps.runStore);
                     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) };
                     const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
@@ -872,8 +912,10 @@ export async function handleTasks(req, res, match, ctx) {
                 const resumeAtStatus = syncRefusalHttpStatus(result);
                 if (resumeAtStatus) {
                     const resumeAtPlane = outwardPlane(result.terminal);
-                    if (durableTaskId && deps.runStore)
+                    if (durableTaskId && deps.runStore) {
                         await deps.runStore.setTerminal(durableTaskId, "failed", sealResultForExit(result), resumeAtPlane.errorMessage ?? null);
+                        await releaseKeyIfZeroWorkRefusal(deps.runStore, durableTaskId, result);
+                    }
                     const retryAfterSec = resumeAtPlane.errorCode === "memory.admission_required" && result.retryAfterMs !== undefined
                         ? Math.max(1, Math.ceil(result.retryAfterMs / 1000))
                         : undefined;
@@ -895,7 +937,7 @@ export async function handleTasks(req, res, match, ctx) {
                 noteRunOutcome(result);
                 return { status: 200, body: withSyncSubmitKeys(buildSyncSubmitBody(exitResult)) };
             };
-            const resp = await idemCache.run(idemKey, async () => withRunReceipt(await runSyncSubmitLeg()), (r) => r.status < 400);
+            const resp = await idemCache.run(inflightKey, async () => withRunReceipt(await runSyncSubmitLeg()));
             sendSubmitResult(res, resp);
         }
         return;

package/dist/http/run-read-face.d.ts

@@ -0,0 +1,26 @@
+import { type RunRecord } from "../plugins/store-contracts.js";
+import type { RunStore } from "../plugins/store-backend.js";
+import type { ServiceConfig } from "../config-types.js";
+/** 读面要的部署配置两格(stale 折叠窗 + 基建计价)。 */
+export interface RunFaceDeps {
+    config: Pick<ServiceConfig, "runStaleSec" | "infraCostRates">;
+}
+export declare function readRunFace(deps: RunFaceDeps, runStore: RunStore, run: RunRecord): Promise<{
+    result: import("../plugins/store-contracts.js").PersistedTaskResult | undefined;
+    supervisorCost: import("../observability/cost-taxonomy.js").SupervisorCostBreakdown | undefined;
+    suggestions: string[] | undefined;
+    errorCode: string | undefined;
+    error: string | undefined;
+    jobId: string | undefined;
+    source: string | undefined;
+    heldBy: string | null;
+    cancelRequested: boolean;
+    crossSliceUsage?: import("../resource-window.js").CrossSliceUsage | undefined;
+    msSinceLastActivity?: number | undefined;
+    taskId: string;
+    sessionId: string;
+    status: "running" | import("@sema-agent/core").TaskStatus;
+}>;
+/** run 行读面的值形 —— 从唯一投影口的返回型派生(不手抄键表)。 */
+export type RunReadFace = Awaited<ReturnType<typeof readRunFace>>;
+//# sourceMappingURL=run-read-face.d.ts.map

package/dist/http/run-read-face.js

@@ -0,0 +1,67 @@
+import { persistedPlaneOf } from "../terminal.js";
+import { memoRedactedRead, memoRedactTerminalResult, redactErrorMessage, redactTerminalResult } from "../observability/run-terminal.js";
+import { RUN_HOLDER_DEATH_CODES, isTerminalRunStatus } from "../plugins/store-contracts.js";
+import { composeSupervisorCost, infraCost, infraUsageFromEvents, hasInfraPricing } from "../observability/cost-taxonomy.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { readTurnActivityMs } from "../turn-activity.js";
+import { buildCrossSliceUsage, readResourceWindow } from "../resource-window.js";
+export async function readRunFace(deps, runStore, run) {
+    const taskId = run.taskId;
+    const stale = run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > deps.config.runStaleSec * 1000;
+    const infraRates = deps.config.infraCostRates;
+    const needCost = Boolean(run.result?.stats && !stale && infraRates && hasInfraPricing(infraRates));
+    const needSuggestions = !stale && run.status === "completed";
+    const resourceWindow = run.status === "running" && !stale ? readResourceWindow(run.taskId) : undefined;
+    let events;
+    let eventsUnavailable = false;
+    if (needCost || needSuggestions || resourceWindow !== undefined) {
+        if (runStore.getEvents) {
+            events = await runStore.getEvents(taskId, 0).catch(() => {
+                eventsUnavailable = true;
+                return [];
+            });
+        }
+        else {
+            eventsUnavailable = true;
+        }
+    }
+    let supervisorCost;
+    if (needCost && events && run.result?.stats) {
+        const durMs = new Date(run.updatedAt).getTime() - new Date(run.createdAt).getTime();
+        const usage = infraUsageFromEvents(events, Number.isFinite(durMs) ? durMs : 0);
+        const st = run.result.stats;
+        supervisorCost = composeSupervisorCost(st.costBreakdown ?? null, st.costMicroUsd ?? 0, infraCost(usage, infraRates));
+    }
+    let suggestions;
+    if (needSuggestions && events) {
+        const sug = [...events].reverse().find((e) => e.type === "suggestions");
+        const arr = sug?.data?.suggestions;
+        if (Array.isArray(arr))
+            suggestions = arr.map((s) => String(s));
+    }
+    const lastActivityAt = run.status === "running" && !stale ? readTurnActivityMs(run.taskId) : undefined;
+    let crossSliceUsage;
+    if (resourceWindow !== undefined) {
+        if (eventsUnavailable || events === undefined)
+            recordFailOpen("server.runs.cross-slice-usage-unavailable");
+        else
+            crossSliceUsage = buildCrossSliceUsage(resourceWindow, events);
+    }
+    return {
+        taskId: run.taskId,
+        sessionId: run.sessionId,
+        status: stale ? "failed" : run.status,
+        ...(lastActivityAt !== undefined ? { msSinceLastActivity: Math.max(0, Date.now() - lastActivityAt) } : {}),
+        ...(crossSliceUsage !== undefined ? { crossSliceUsage } : {}),
+        result: isTerminalRunStatus(run.status) ? memoRedactTerminalResult("run.result", run.result ?? undefined) : redactTerminalResult(run.result ?? undefined),
+        supervisorCost,
+        suggestions,
+        errorCode: stale ? RUN_HOLDER_DEATH_CODES.stalled : (persistedPlaneOf(run.result).errorCode ?? run.errorCode ?? undefined),
+        error: stale ? "run stalled (instance lost?)" : isTerminalRunStatus(run.status) ? memoRedactedRead("run.error", run.error ?? undefined, redactErrorMessage) : redactErrorMessage(run.error ?? undefined),
+        jobId: run.jobId ?? undefined,
+        source: run.source ?? undefined,
+        heldBy: run.instanceId ?? null,
+        cancelRequested: run.cancelRequested,
+    };
+}
+//# sourceMappingURL=run-read-face.js.map

package/dist/http/server.d.ts

@@ -26,8 +26,6 @@ import type { Metrics } from "../observability/metrics.js";
 import { type RateGate } from "../observability/rate-limit.js";
 import type { QuotaTracker } from "../observability/cost-quota.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "../budget.js";
-import { scopedIdempotencyKey } from "./idempotency.js";
-export { scopedIdempotencyKey };
 import type { ConsolidationSeatLabel, ConsolidationValve } from "../boot/memory-consolidation.js";
 import { streamApprovals, checkQuestionAnswer } from "./routes/approvals-assistant.js";
 export { streamApprovals, checkQuestionAnswer };
@@ -354,8 +352,10 @@ export interface ServiceSeamDeps {
      * 缺席 = 本部署不是 host 车道(没有工厂读这一格)⇒ 提交点 no-op。装配 = `boot/stage-10-http-server.ts`(host 车道才给)。
      */
     bindSessionInheritEnv?: import("./session-inherit-env.js").SessionInheritEnvCommitCtx["bindSessionInheritEnv"];
-    /** Audit回溯: current context (+ summary) for a session, plus its owner. Enables GET /v1/sessions/:id. */
-    sessionAudit?: (sessionId: string) => Promise<({
+    /** Audit回溯: current context (+ summary) for a session, plus its owner. Enables GET /v1/sessions/:id. `opts.reader` (the
+     *  verified identity reading the view) ⇒ user message rows carry the rewind handle `taskId` (`audit.ts` `buildRewindHandles`);
+     *  an embedder's one-parameter implementation stays assignable (it simply never projects handles). */
+    sessionAudit?: (sessionId: string, opts?: import("../audit.js").SessionAuditReadOpts) => Promise<({
         owner: string | null;
     } & Record<string, unknown>) | undefined>;
     /** E21 session delete coordinator: purge a session's history (sessionStorage) PLUS the service-owned

package/dist/http/server.js

@@ -11,8 +11,7 @@ import {} from "../orchestration/workflow-completion-inbox.js";
 import {} from "../fleet/fleet-bus.js";
 import {} from "../tool-approval.js";
 import {} from "../observability/rate-limit.js";
-import { IdempotencyCache, scopedIdempotencyKey } from "./idempotency.js";
-export { scopedIdempotencyKey };
+import { IdempotencyCache } from "./idempotency.js";
 import { streamApprovals, checkQuestionAnswer } from "./routes/approvals-assistant.js";
 export { streamApprovals, checkQuestionAnswer };
 import { cascadeConfig } from "./run-meta.js";

package/dist/http/submit-replay.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 提交幂等的**唯一回执函数** —— 一把提交钥匙命中了一条既有 run 行之后,这次提交拿到什么。
+ *
+ * ## 律(一条)
+ * 幂等 = 资源行上的唯一键。`task_run` 上有两把:`idem_key`(`Idempotency-Key`,唯一铸法 `idemKeyOf(raw, caller, "run")`)
+ * 与 `task_id`(调用方自铸的 `body.taskId`;A2A 由 messageId 派生)。哪一把命中、在哪条提交腿上命中、是请求进门时
+ * 读行命中还是建行撞唯一键时观察到,一律经**本函数**作答 —— 提交面不再有第二个判官(进程内缓存只做在飞合流,
+ * 见 `http/idempotency.ts`)。
+ *
+ * ## 判定(两条,别的一律不放)
+ *  · 这次提交自带 taskId 而命中的行**不是**那一条(`Idempotency-Key` 指向别的行)⇒ 冲突;
+ *  · 调用方读不到这一行(属主门 = `runOwnerReadable`,「这个调用方读得到这一行 run 吗」的唯一谓词)⇒ 冲突。
+ * 冲突 ⇒ `409 conflict.run_exists`,体里**不回显**那条行的任何标识(不给跨租户预言机)。
+ *
+ * ## 回执两形(按提交腿)
+ *  · `durable`(`POST /v1/runs`、A2A `message/send`)—— `202 { taskId, sessionId, status }`(这条腿首答的既有形);
+ *  · `sync`(`POST /v1/tasks`;`/v1/tasks/stream` 把同一份体放进 `done.result`)—— `200 { …run 行读面, replay: true }`
+ *    (读面 = `GET /v1/runs/:id` 的 200 体,同一只投影口 `readRunFace`)。同步腿的首答是引擎结果,而重放时手里只有行;
+ *    `replay: true` 是这一形的判别位。
+ */
+import type { RunRecord } from "../plugins/store-contracts.js";
+import type { RunStore } from "../plugins/store-backend.js";
+import type { ServiceConfig } from "../config-types.js";
+import type { SubmitOutcome } from "./idempotency.js";
+/** 提交腿的回执形(闭集;穷举 `switch`,加一形不写这里 = 编译红)。 */
+export type SubmitReplayFace = "durable" | "sync";
+/** 发起这次提交的一方。 */
+export interface ReplayCaller {
+    /** 已验身份(`gatedPrincipal`)。 */
+    principal: string | undefined;
+    /** 这次提交自带的 taskId(`body.taskId`;A2A 派生值)。缺席 = 只凭 `Idempotency-Key` 命中。 */
+    clientTaskId?: string;
+}
+/** 一份提交回执是不是 {@link replayOfExistingRun} 铸的**冲突**体(判别位 = 机器码;铸点就在下面,码与它同文件)—— 把回执渲成别的协议形的
+ *  调用方(A2A)按它分句,不另抄码。 */
+export declare function isRunExistsConflictBody(body: unknown): boolean;
+export declare function replayOfExistingRun(row: RunRecord, caller: ReplayCaller, face: SubmitReplayFace, deps: {
+    config: ServiceConfig;
+}, runStore: RunStore): Promise<SubmitOutcome>;
+//# sourceMappingURL=submit-replay.d.ts.map

package/dist/http/submit-replay.js

@@ -0,0 +1,22 @@
+import { runOwnerReadable } from "./principal-gate.js";
+import { readRunFace } from "./run-read-face.js";
+export function isRunExistsConflictBody(body) {
+    return typeof body === "object" && body !== null && body.errorCode === "conflict.run_exists";
+}
+export async function replayOfExistingRun(row, caller, face, deps, runStore) {
+    const sameRun = caller.clientTaskId === undefined || caller.clientTaskId === row.taskId;
+    if (!sameRun || !runOwnerReadable(caller.principal, row.owner, deps.config)) {
+        return { status: 409, body: { error: "a run already exists for this submission's taskId or Idempotency-Key", errorCode: "conflict.run_exists" } };
+    }
+    switch (face) {
+        case "durable":
+            return { status: 202, body: { taskId: row.taskId, sessionId: row.sessionId, status: row.status } };
+        case "sync":
+            return { status: 200, body: { ...(await readRunFace(deps, runStore, row)), replay: true } };
+        default: {
+            const unknown = face;
+            throw new Error(`replayOfExistingRun: unknown submit face ${String(unknown)}`);
+        }
+    }
+}
+//# sourceMappingURL=submit-replay.js.map

package/dist/leader/endpoint.d.ts

@@ -1,5 +1,6 @@
 import type { LeaderResult } from "./leader.js";
 import { type LeaderRunRecord, type LeaderRunStatus, type NewLeaderRun, type LeaderRunTerminal } from "../plugins/leader-run-store-sql.js";
+import { type IdemCaller } from "../http/idempotency.js";
 /**
  * endpoint 消费的 store 面(结构型,不是 nominal union):真实现是 `SqlLeaderRunStore` 的两个方言孪生,
  * 测试用进程内假件。窄到只有 endpoint 真调的三个方法 —— 端点不该看见店的其余口。
@@ -10,6 +11,8 @@ export interface LeaderRunStore {
         run: LeaderRunRecord;
     }>;
     getRun(id: string): Promise<LeaderRunRecord | undefined>;
+    /** 按提交幂等键(已 scope 的定宽 hash)读行 —— `GET /v1/leader?idempotencyKey=` 的读口。 */
+    getByIdem(idemKey: string): Promise<LeaderRunRecord | undefined>;
     finishRun(id: string, patch: LeaderRunTerminal): Promise<boolean>;
 }
 export interface LeaderRequestBody {
@@ -36,11 +39,13 @@ export interface LeaderRun {
 }
 export interface LeaderEndpoint {
     /** Returns a {status,body} to send, or null if the (method,url) is not a leader route. Kicks the background
-     *  run for POST. `body` is the already-parsed request body (server reads it; undefined for GET). `requester`
-     *  (BL-4) is the authenticated principal: recorded as the run owner on POST and owner-checked on GET.
-     *  `idempotencyKey` is the caller's RAW `Idempotency-Key` header (POST only; scoped by owner before it
-     *  reaches the store — see {@link leaderIdemKey}). ASYNC because the durable arm reads/writes SQL. */
-    handle(method: string, url: string, body: unknown, requester?: string | null, idempotencyKey?: string | null): Promise<{
+     *  run for POST. `body` is the already-parsed request body (server reads it; undefined for GET). `caller` is the
+     *  request's identity (`idemCallerOf`): its verified principal (BL-4) is recorded as the run owner on POST and owner-checked
+     *  on GET; the whole identity scopes the idempotency key. `idempotencyKey` is the caller's RAW `Idempotency-Key` (POST: the
+     *  header; `GET /v1/leader`: the `idempotencyKey` query — the read port "which leader run did this key create"; scoped by the
+     *  caller's identity bit `principal ?? source` before it reaches the store — the one key minter `idemKeyOf(raw, caller, "leader")`).
+     *  ASYNC because the durable arm reads/writes SQL. */
+    handle(method: string, url: string, body: unknown, caller?: IdemCaller, idempotencyKey?: string | null): Promise<{
         status: number;
         body: object;
     } | null>;

package/dist/leader/endpoint.js

@@ -1,7 +1,8 @@
 import { uuidv7 } from "@sema-agent/core";
 import { redactErrorMessage, redactHead, redactLeaderResult, redactLeaderResultWithFlag } from "../observability/run-terminal.js";
 import { withPrincipal } from "../observability/principal-context.js";
-import { leaderIdemKey } from "../plugins/leader-run-store-sql.js";
+import {} from "../plugins/leader-run-store-sql.js";
+import { idemKeyOf } from "../http/idempotency.js";
 function statusForLeaderResult(result) {
     if (result.conflict)
         return "needs_human";
@@ -126,7 +127,9 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
         return { status: 200, body: { id: run.id, status: run.status, ...redactedView(run) } };
     }
     const NOT_FOUND = { status: 404, body: { error: "leader run not found", errorCode: "not_found.leader_run" } };
-    async function handle(method, url, body, requester, idempotencyKey) {
+    async function handle(method, url, body, caller, idempotencyKey) {
+        const requester = caller?.principal ?? null;
+        const idemCaller = caller ?? { principal: null, source: null };
         if (method === "POST" && url === "/v1/leader") {
             const b = body;
             if (!b || typeof b.objective !== "string" || b.objective.trim() === "") {
@@ -138,13 +141,13 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
                     return { status: 400, body: { error: `missing required field(s): ${missing.join(", ")}`, errorCode: "request.body_shape" } };
                 }
             }
-            const owner = requester ?? null;
+            const owner = requester;
             let scopedIdem = null;
             if (idempotencyKey != null) {
                 const bad = idemShapeError(idempotencyKey);
                 if (bad)
                     return { status: 400, body: { error: bad, errorCode: "request.body_shape" } };
-                scopedIdem = leaderIdemKey(idempotencyKey, owner);
+                scopedIdem = idemKeyOf(idempotencyKey, idemCaller, "leader");
             }
             reap();
             if (opts.store) {
@@ -172,10 +175,29 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
             drive(id, b, owner);
             return { status: 202, body: { leaderRunId: id, status: "running" } };
         }
+        const ownerOk = (owner) => owner == null || owner === requester;
+        if (method === "GET" && url === "/v1/leader") {
+            if (idempotencyKey == null)
+                return { status: 400, body: { error: "idempotencyKey is required: pass the raw Idempotency-Key the submission was sent with", errorCode: "request.query_invalid" } };
+            const bad = idemShapeError(idempotencyKey);
+            if (bad)
+                return { status: 400, body: { error: bad, errorCode: "request.query_invalid" } };
+            const key = idemKeyOf(idempotencyKey, idemCaller, "leader");
+            if (opts.store) {
+                const run = await opts.store.getByIdem(key);
+                if (!run || !ownerOk(run.owner))
+                    return NOT_FOUND;
+                return getBody(run);
+            }
+            const prior = memIdem.get(key);
+            const run = prior !== undefined ? runs.get(prior) : undefined;
+            if (!run || !ownerOk(run.owner))
+                return NOT_FOUND;
+            return getBody(run);
+        }
         const m = method === "GET" ? LEADER_ID_RE.exec(url) : null;
         if (m) {
             const id = m[1];
-            const ownerOk = (owner) => owner == null || owner === (requester ?? null);
             if (opts.store) {
                 const run = await opts.store.getRun(id);
                 if (!run || !ownerOk(run.owner))

package/dist/observability/cost-quota.d.ts

@@ -1,6 +1,6 @@
 /**
  * Per-principal CUMULATIVE cost quota ([ref]/27 follow-up). The per-task `maxCostUsd` gate caps a
- * SINGLE task; this caps a principal's spend ACROSS tasks within a rolling fixed window. Spend is the
+ * SINGLE task; this caps a principal's spend ACROSS tasks within a clock-aligned fixed window. Spend is the
  * authoritative integer `costMicroUsd` accumulated by the tracer (so it includes council/team
  * sub-tasks, via the principal ALS context). A new task is REFUSED once the window's accumulated cost
  * has crossed the ceiling — the in-flight task that crossed it still finishes (the per-task gate is the
@@ -9,14 +9,54 @@
  * In-memory, per-replica — same trade as the request rate limiter. A multi-replica deployment under-
  * counts across replicas (each tracks its own slice); a shared (TiDB) quota is the hardening step,
  * mirroring TiDBBreakerState. Documented, not silently wrong.
+ *
+ * 🔴 **一只锚**:配额窗 = 时钟对齐桶,公式只在 {@link alignedWindow} 一处。内存腿({@link CostQuota})与
+ * SQL 腿(`plugins/write-behind-counter.ts`,cost quota 与 rate limiter 共用)同 import 它;决策体由
+ * {@link decideQuota} 一处铸(关断哨兵、退避秒数都在里面)。修前内存腿从该键**首笔花费**开锚、SQL 腿按
+ * 时钟对齐 —— 同一个 `COST_QUOTA_WINDOW_SEC` 两种窗形,同一个 principal 的窗末取决于部署拓扑。
+ */
+/** 一只对齐窗的读数:同一次时钟读出的桶号与桶末(决策与退避都从它派生 ⇒ 同一 `now`,零二次读钟)。 */
+export interface AlignedWindow {
+    /** 读钟时刻(ms)。 */
+    readonly now: number;
+    /** 桶号 —— 记账键的一部分(内存腿的条目键、SQL 腿的 `window_bucket` 列)。 */
+    readonly bucket: number;
+    /** 当代桶末(ms,不含)= 下一桶起点;wire 上投影成 `windowResetsAt`。 */
+    readonly windowEndsAtMs: number;
+}
+/**
+ * 窗长(秒)的合法域 = 锚公式的定义域。env 腿(拒启)与 center 腿(整批拒)同调 {@link costQuotaWindowSecInRange},一个判据:
+ *  · 下界 1 s —— 退避秒数与 `Retry-After` 以整秒计;极小正数会让 `now / windowMs` 溢成 Infinity(桶号与窗末无意义)。
+ *  · 上界 1e10 s(≈ 317 年)—— 当代桶末必须是 `Date` 可表示的时刻(`windowResetsAt` 的 ISO 投影;Date 上界 8.64e15 ms)。
+ *    桶末 ≤ now + 窗长 ⇒ 1e10 s 下 ≤ now + 1e13 ms,离上界三个数量级;也盖得住拿超长窗当「终身额度」的用法。
  */
+export declare const COST_QUOTA_WINDOW_SEC_RANGE: {
+    readonly min: 1;
+    readonly max: 10000000000;
+};
+export declare function costQuotaWindowSecInRange(sec: number): boolean;
+/** 🔴 全仓**唯一**的桶公式(源码钉:`test/cost-quota.test.ts` 的「一只锚」格)。 */
+export declare function alignedWindow(now: number, windowMs: number): AlignedWindow;
+/** 到桶末的退避秒数(向上取整、不为负)—— 内存腿、SQL 腿、rate limiter 的唯一退避公式。 */
+export declare function retryAfterSecUntil(w: AlignedWindow): number;
 export interface QuotaDecision {
     allowed: boolean;
     usedMicroUsd: number;
     limitMicroUsd: number;
-    /** Seconds until the current window rolls over (only meaningful when !allowed). */
+    /** Seconds until the current window rolls over (0 when allowed). Derived from {@link windowEndsAtMs} at the same `now`. */
     retryAfterSec: number;
+    /** End of the current clock-aligned window (ms epoch, exclusive). ALWAYS a number — the OFF sentinel included
+     *  (the window length is still a configured fact; it reports the current bucket's end). */
+    windowEndsAtMs: number;
 }
+/**
+ * 决策体的**唯一**铸点(三实现 —— 内存 / TiDB / PG —— 同调,各自零公式、零关断字面量)。
+ * `limitMicroUsd <= 0` = 关断哨兵:恒放行、如实报 `limitMicroUsd: 0`、**不调** `readUsed`(内存腿零窗表访问、
+ * SQL 腿零计数读 —— off 态零 SQL 的承诺不受影响)。`readUsed` 收的是本次读钟的桶号,读到的花费与桶末同源。
+ */
+export declare function decideQuota(limitMicroUsd: number, w: AlignedWindow, readUsed: (bucket: number) => number): QuotaDecision;
+/** `windowEndsAtMs` 的 wire 投影(ISO 8601)—— `GET /v1/usage` 体与 429 `limit.cost_quota_exceeded` 体的同一只读法。 */
+export declare function quotaWindowResetsAt(d: Pick<QuotaDecision, "windowEndsAtMs">): string;
 /** The hot-path surface shared by the in-memory {@link CostQuota} (single replica) and the cross-replica
  *  {@link import("../plugins/tidb-cost-quota.js").TiDBCostQuota}. `key` is opaque (principal today;
  *  principal/team/feature later — [ref] N3), so both stores are key-based. */
@@ -34,28 +74,32 @@ export interface QuotaTracker {
 }
 export declare class CostQuota implements QuotaTracker {
     private readonly now;
+    /** 记账条目 = 键 × 桶号(键里带桶号,值里也带 —— `reap` 按桶号比,不解析键)。读写都只碰当代桶;一个键跨桶时
+     *  旧桶条目留到 `reap`(与 SQL 腿「旧桶行留到 DELETE」同形)。 */
     private windows;
     /** 🔴 不再 `readonly`:限额/窗长是比较参数,换代只动它们,窗内已累计的花费一个不动([ref] §5)。 */
     private limitMicroUsd;
     private windowMs;
-    /** @param limitMicroUsd ceiling per window (integer micro-USD; `<=0` = OFF sentinel). @param windowMs rolling window. */
+    /** @param limitMicroUsd ceiling per window (integer micro-USD; `<=0` = OFF sentinel). @param windowMs clock-aligned window length. */
     constructor(limitMicroUsd: number, windowMs: number, now?: () => number);
     /**
      * 值换代。两件事**语义不同**,别混:
      *  · **限额**换代 = 纯比较参数 ⇒ 窗内已累计的花费一个不动([ref] §5 定案:调小当场更严)。
      *  · **窗长**换代 = 换**记账周期** ⇒ 当代累计重开。
      *
-     * 🔴 后者是 codex R1-F4(真 finding,红先):SQL 腿的窗长是**桶键的一部分**(`floor(now/windowMs)`),
+     * 🔴 后者是 codex R1-F4(真 finding,红先):SQL 腿的窗长是**桶键的一部分**(桶号由 {@link alignedWindow} 算),
      * 换窗长后当代桶天然重算 ⇒ 已累计不跟着搬家;内存腿修前却保留原窗口累计。于是**同一条发布**在
      * 内存部署上继续拒绝超额 principal、在 PG/TiDB 部署上重新放行一整个额度 —— 后端相关的成本 fail-open。
-     * 统一取 SQL 腿那一侧(唯一能在两条腿上都实现的语义:SQL 侧无法把旧桶累计搬进新桶)。
+     * 统一取 SQL 腿那一侧(唯一能在两条腿上都实现的语义:SQL 侧无法把旧桶累计搬进新桶)。内存腿按桶号记账后
+     * 仍要显式清:两个窗长在同一时刻可能算出同一个桶号(SQL 腿的这一形是既有差异,见 `CONFIG-HOT-RELOAD.md`)。
      */
     setLimits(next: QuotaLimits): void;
     /** Is this principal under quota right now? (Reads only — does not consume.) */
     check(key: string): QuotaDecision;
-    /** Add spend for a principal, starting a fresh window if the prior one expired. */
+    /** Add spend for a principal into the CURRENT aligned bucket. */
     add(key: string, micro: number): void;
-    /** Drop expired windows (called from the background reaper) to bound memory. */
+    /** Drop entries of buckets older than the current one (called from the background reaper) to bound memory.
+     *  Never the current bucket; a bucket AHEAD of the clock (a backwards clock step) survives until the clock passes it. */
     reap(): number;
 }
 //# sourceMappingURL=cost-quota.d.ts.map