@sema-agent/server 7.147.0 → 7.148.0

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

@@ -1,3 +1,5 @@
+import { seatText } from "../../trace/exit-seat.js";
+import { isHolderDeathVerdict } from "../../plugins/store-contracts.js";
 import { projectEvents, taskSummary, mapTraceEvent } from "../../trace/project.js";
 import { redactLedgerEventForRead } from "../../observability/run-terminal.js";
 import { projectArtifacts } from "../../trace/artifacts.js";
@@ -6,7 +8,9 @@ import { sleep } from "../sse-log.js";
 import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_MS } from "../send.js";
 import { filterFingerprint } from "../cursor-fingerprint.js";
-import { fleetViewOf, sendUnauthorized } from "../principal-gate.js";
+import { sendUnauthorized } from "../principal-gate.js";
+import { admitRunById, enter, entryIsFleet, readVisibleRun, routeListFilter, runRowAt } from "../owner-access.js";
+import { listFilterOf } from "../../owner-faces.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 const TOOL_RESULT_LIMIT_CAP = 262_144;
@@ -15,7 +19,7 @@ export async function handleTraceUsage(req, res, match, ctx) {
     const { deps } = ctx;
     const { safeDecode } = ctx.helpers;
     if (match.decl.id === "tasks-source-summary") {
-        if (!fleetViewOf(req, deps, "read").fleetWide) {
+        if (!routeListFilter(req, deps, match.decl.id).fleetWide) {
             sendUnauthorized(res, "operator");
             return;
         }
@@ -35,11 +39,10 @@ export async function handleTraceUsage(req, res, match, ctx) {
         match.decl.id === "task-trace-stream" ||
         match.decl.id === "task-trace-artifacts" ||
         match.decl.id === "task-tool-result") {
-        const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
-        if (!fleetWide && gateOwner === null) {
-            sendUnauthorized(res, "identity");
+        const traceEntry = enter(req, res, deps, match.decl.id);
+        if (traceEntry === undefined)
             return;
-        }
+        const gateOwner = listFilterOf(traceEntry.face, traceEntry.caller).gateOwner;
         const runs = facts.durableRuns(deps);
         if (!runs.available) {
             sendError(res, 501, "capability.run_store_required", "trace API requires a durable run store (DB_BACKEND=mysql|pg|local)");
@@ -48,31 +51,33 @@ export async function handleTraceUsage(req, res, match, ctx) {
         const runStore = runs.runStore;
         const query = new URLSearchParams(match.search);
         const taskId = match.params.taskId;
-        let ownedRun;
-        if (taskId && gateOwner !== null) {
-            const run = await runStore.getRun(taskId);
-            if (!run || (run.owner !== null && run.owner !== gateOwner)) {
-                sendError(res, 404, "not_found.run", "task not found");
+        let admittedRun;
+        const readDeferred = match.decl.id === "task-tool-result" && entryIsFleet(traceEntry);
+        if (taskId !== undefined && !readDeferred) {
+            const admitted = await admitRunById(traceEntry, res, runStore, taskId);
+            if (admitted === undefined)
                 return;
-            }
-            ownedRun = run;
+            admittedRun = admitted.row;
         }
         switch (match.decl.id) {
             case "task-trace-list":
                 await handleTaskList(res, runStore, query, gateOwner);
                 return;
             case "task-trace-turns":
-                await handleTaskTurns(res, runStore, taskId, query);
+                await handleTaskTurns(res, runStore, admittedRun, query);
                 return;
             case "task-trace-stream":
-                await streamTaskTrace(req, res, runStore, taskId, deps.config.runStaleSec * 1000, match.search);
+                await streamTaskTrace(req, res, runStore, admittedRun, match.search);
                 return;
             case "task-trace-artifacts":
-                await handleTaskArtifacts(res, runStore, taskId);
+                await handleTaskArtifacts(res, runStore, admittedRun);
                 return;
-            case "task-tool-result":
-                await handleToolResult(res, deps.toolResultStore, runStore, taskId, ownedRun, safeDecode(match.params.ref), query);
+            case "task-tool-result": {
+                const ownedRun = admittedRun;
+                const readRun = ownedRun !== undefined ? async () => ownedRun : () => readVisibleRun(traceEntry, runStore, taskId);
+                await handleToolResult(res, deps.toolResultStore, taskId, readRun, safeDecode(match.params.ref), query);
                 return;
+            }
             default:
                 return assertNever(match.decl.id);
         }
@@ -88,7 +93,7 @@ export async function handleTraceUsage(req, res, match, ctx) {
                 return;
             }
             const runStore = runs.runStore;
-            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
+            const { fleetWide, gateOwner } = routeListFilter(req, deps, match.decl.id);
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -176,16 +181,12 @@ async function handleTaskList(res, runStore, query, forceOwner) {
     const nextCursor = hasMore && last ? encodeCursor({ createdAt: last.createdAt, taskId: last.taskId }, f) : undefined;
     sendJson(res, 200, { tasks, ...(nextCursor ? { nextCursor } : {}) });
 }
-async function handleTaskArtifacts(res, runStore, taskId) {
-    const run = await runStore.getRun(taskId);
-    if (!run) {
-        sendError(res, 404, "not_found.run", "task not found");
-        return;
-    }
+async function handleTaskArtifacts(res, runStore, run) {
+    const taskId = run.taskId;
     const events = await runStore.getEvents(taskId, 0);
     sendJson(res, 200, { artifacts: projectArtifacts(events, { taskId, jobId: run.jobId }) });
 }
-async function handleToolResult(res, store, runStore, taskId, ownedRun, ref, query) {
+async function handleToolResult(res, store, taskId, readRun, ref, query) {
     const intParam = (name, cap) => {
         const raw = query.get(name);
         if (raw === null)
@@ -212,7 +213,7 @@ async function handleToolResult(res, store, runStore, taskId, ownedRun, ref, que
     const notFound = () => sendError(res, 404, "not_found.tool_result", "tool result not found");
     if (ref === null)
         return notFound();
-    const run = ownedRun ?? (await runStore.getRun(taskId));
+    const run = await readRun();
     if (!run)
         return notFound();
     const owner = store?.ownerOf ? await store.ownerOf(ref) : undefined;
@@ -227,12 +228,8 @@ async function handleToolResult(res, store, runStore, taskId, ownedRun, ref, que
     sendJson(res, 200, { content: slice.content, offset: slice.offset, totalChars: slice.totalChars });
 }
 const readFaceEvent = (ev) => ({ ...ev, data: redactLedgerEventForRead(ev.type, ev.data) });
-async function handleTaskTurns(res, runStore, taskId, query) {
-    const run = await runStore.getRun(taskId);
-    if (!run) {
-        sendError(res, 404, "not_found.run", "task not found");
-        return;
-    }
+async function handleTaskTurns(res, runStore, run, query) {
+    const taskId = run.taskId;
     const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 20) || 20));
     const cursorSeq = Number(query.get("cursor") ?? 0) || 0;
     const [events, retainedFrom] = await Promise.all([runStore.getEvents(taskId, 0), runStore.retainedFrom(taskId)]);
@@ -243,12 +240,8 @@ async function handleTaskTurns(res, runStore, taskId, query) {
     const nextCursor = eligible.length > limit && oldest ? String(oldest.seq) : undefined;
     sendJson(res, 200, { turns, ...(nextCursor ? { nextCursor } : {}), retainedFrom });
 }
-async function streamTaskTrace(req, res, runStore, taskId, staleMs, search) {
-    const run0 = await runStore.getRun(taskId);
-    if (!run0) {
-        sendError(res, 404, "not_found.run", "task not found");
-        return;
-    }
+async function streamTaskTrace(req, res, runStore, admitted, search) {
+    const taskId = admitted.taskId;
     const lastId = Number(req.headers["last-event-id"] ?? new URLSearchParams(search).get("from") ?? 0);
     let from = Number.isFinite(lastId) ? lastId : 0;
     sseHeaders(res);
@@ -259,26 +252,27 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs, search) {
     });
     const start = Date.now();
     let lastBeat = Date.now();
+    let deliveredTerminal = false;
     const write = (events) => {
         for (const ev of events) {
             const out = mapTraceEvent(ev.type, ev.seq, (readFaceEvent(ev).data ?? {}));
             if (out)
                 res.write(`id: ${ev.seq}\nevent: ${out.event}\ndata: ${JSON.stringify(out.data)}\n\n`);
             from = ev.seq;
+            if (ev.type === "done" || ev.type === "failed")
+                deliveredTerminal = true;
         }
     };
     while (!closed) {
-        const [events, run] = await Promise.all([runStore.getEvents(taskId, from), runStore.getRun(taskId)]);
+        const [events, raw] = await Promise.all([runStore.getEvents(taskId, from), runStore.getRun(taskId)]);
         write(events);
-        if (!run)
+        if (!raw)
             break;
+        const run = await runRowAt("task-trace-stream", runStore, raw);
         if (run.status !== "running") {
             write(await runStore.getEvents(taskId, from));
-            break;
-        }
-        const stale = Date.now() - new Date(run.updatedAt).getTime() > staleMs;
-        if (stale && events.length === 0) {
-            res.write(`event: error\ndata: ${JSON.stringify({ type: "error", errorCode: "WORKER_DOWN", message: "run stalled (instance lost?)" })}\n\n`);
+            if (!deliveredTerminal && isHolderDeathVerdict(run))
+                res.write(`event: error\ndata: ${JSON.stringify({ type: "error", errorCode: "WORKER_DOWN", message: seatText("trace-frame-text", run.error ?? "") })}\n\n`);
             break;
         }
         if (Date.now() - start > SSE_MAX_STREAM_MS) {

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

@@ -2,7 +2,6 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { type WorkflowRun } from "@sema-agent/core";
 import { type Admit } from "../../trace/projection-table.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
-/** SVC-5 的 steer 路——`handle()` 里位置在 tasks/runs 之后(鉴权门之后),故是**独立**的域入口。 */
 /** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
  *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 export declare function handleWorkflows(req: IncomingMessage, res: ServerResponse, match: RouteMatch<WorkflowsRouteId>, ctx: RouteCtx): Promise<void>;
@@ -20,7 +19,7 @@ export interface GroupForest {
     readonly roots: readonly WorkflowGroupRow[];
     readonly childrenOf: ReadonlyMap<WorkflowGroupRow, readonly WorkflowGroupRow[]>;
 }
-/** 详情面九张表的铸键与 `rows` 读到的根:原记录 + 本次投影建一次的组森林。 */
+/** 详情面十一张表的铸键与 `rows` 读到的根:原记录 + 本次投影建一次的组森林。 */
 export interface WorkflowDetailRoot {
     readonly run: WorkflowRun;
     readonly forest: GroupForest;
@@ -171,6 +170,28 @@ export declare const WORKFLOW_RUN_STATS_DISPOSITIONS: {
         };
     };
 };
+/**
+ * run 级预算超支(core `WorkflowRun.budgetOvershoot`:终局 run 真花超了上限才有,条件铸)。展示面审(core 型亲读):三格全是令牌数 ——
+ * `budgetTokens` 配置的上限、`spentTokens` 已结算的实花、`unsettledTokens` 终局时仍在飞的腿上观测到的花费(估计值,消费方与前者相加;引擎只在非零时写这一格,缺席与零同读)——
+ * 没有文本成员 ⇒ 逐成员 `forward`,不过脱敏器,也不开自由数据通道。
+ */
+export declare const WORKFLOW_BUDGET_OVERSHOOT_DISPOSITIONS: {
+    readonly budgetTokens: "forward";
+    readonly spentTokens: "forward";
+    readonly unsettledTokens: "forward";
+};
+/**
+ * run 级总超时截断(core `WorkflowRun.timeoutInterruption`:总超时的截止线在 run 到达终局之前已经触发才有,条件铸)。展示面审(core 型亲读):五格全是毫秒数与计数 ——
+ * `timeoutMs` 触发的那条线、`agentsCompleted` / `agentsFailed` / `agentsInFlight` 截断那一刻的三个计数(时点快照,`agentsFailed` 不是 run 级 `agentFailures`)、
+ * `approvalWaitedMs` 单条腿等审批的最长一段(下界,缺席 = 部署没供给,不是零)—— 没有文本成员 ⇒ 逐成员 `forward`,不过脱敏器,也不开自由数据通道。
+ */
+export declare const WORKFLOW_TIMEOUT_INTERRUPTION_DISPOSITIONS: {
+    readonly timeoutMs: "forward";
+    readonly agentsCompleted: "forward";
+    readonly agentsFailed: "forward";
+    readonly agentsInFlight: "forward";
+    readonly approvalWaitedMs: "forward";
+};
 export declare const WORKFLOW_RUN_DISPOSITIONS: {
     readonly id: "forward";
     readonly scope: "forward";
@@ -200,6 +221,22 @@ export declare const WORKFLOW_RUN_DISPOSITIONS: {
         };
     };
     readonly agentFailures: "forward";
+    readonly budgetOvershoot: {
+        readonly nested: {
+            readonly budgetTokens: "forward";
+            readonly spentTokens: "forward";
+            readonly unsettledTokens: "forward";
+        };
+    };
+    readonly timeoutInterruption: {
+        readonly nested: {
+            readonly timeoutMs: "forward";
+            readonly agentsCompleted: "forward";
+            readonly agentsFailed: "forward";
+            readonly agentsInFlight: "forward";
+            readonly approvalWaitedMs: "forward";
+        };
+    };
     readonly startedAt: "forward";
     readonly endedAt: "forward";
     readonly createdAt: "forward";
@@ -350,8 +387,6 @@ export declare const WORKFLOW_RUN_DISPOSITIONS: {
     readonly sourceTaskId: "strip";
     readonly originatingSessionId: "strip";
     readonly effectiveArgs: "strip";
-    readonly budgetOvershoot: "strip";
-    readonly timeoutInterruption: "strip";
     readonly resultFull: "strip";
     readonly completionId: "strip";
     readonly resume: "strip";

package/dist/http/routes/workflows.js

@@ -10,16 +10,27 @@ import { projectByTable } from "../../trace/projection-table.js";
 const JOURNAL_PROJECTION_MEMO_CAP = 1024;
 const journalProjectionMemo = new Map();
 import { sendJson, sendError, sseHeaders } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedSubject, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import { partsOf } from "../../owner-brands.js";
+import { taskSpecIdentityOf } from "../../engine-identity.js";
 import { assertNever } from "../route-ctx.js";
+import { callerOf, sessionAsserted } from "../owner-access.js";
 import * as facts from "../../capability-facts.js";
 import { steerBodyKeyIssue } from "../../request-key-closure.js";
+function sendWorkflowAbsent(res) {
+    sendError(res, 404, "not_found.workflow", "workflow not found");
+}
+const WORKFLOW_SESSION_ASSERTION = {
+    "workflow-detail": { phase: "accept", label: "workflow.detail" },
+    "workflow-journal": { phase: "accept", label: "workflow.journal" },
+    "workflow-stream": { phase: "accept", label: "workflow.stream" },
+    "workflow-agent-steer": { phase: "accept", label: "workflow.agent-steer" },
+};
 export async function handleWorkflows(req, res, match, ctx) {
     const { deps } = ctx;
-    const { runSessionAcceptOk } = ctx.helpers;
     {
-        const principal = gatedPrincipal(req, deps.config);
-        if (deps.config.requirePrincipal && !principal) {
+        const subject = gatedSubject(req, deps.config);
+        if (deps.config.requirePrincipal && !subject) {
             sendPrincipalRefusal(res, req, deps.config);
             return;
         }
@@ -38,7 +49,7 @@ export async function handleWorkflows(req, res, match, ctx) {
             return;
         }
         const runStore = runs.store;
-        const scope = principal ?? "default";
+        const scope = taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)).principal ?? "default";
         const wfId = match.params.runId;
         const isStream = match.decl.id === "workflow-stream";
         if (match.decl.id === "workflows-list") {
@@ -62,11 +73,13 @@ export async function handleWorkflows(req, res, match, ctx) {
         }
         const run = await getWorkflowRun(runStore, wfId, scope);
         if (!run || run.scope !== scope) {
-            sendError(res, 404, "not_found.workflow", "workflow not found");
+            sendWorkflowAbsent(res);
             return;
         }
-        if (!runSessionAcceptOk(req, res, { sessionId: run.originatingSessionId ?? null }, match.decl.id === "workflow-journal" ? "workflow.journal" : isStream ? "workflow.stream" : "workflow.detail", "workflow not found"))
+        if (!sessionAsserted(WORKFLOW_SESSION_ASSERTION[match.decl.id], req, run.originatingSessionId, callerOf(req, deps).operator)) {
+            sendWorkflowAbsent(res);
             return;
+        }
         if (match.decl.id === "workflow-journal") {
             if (journalStore === undefined)
                 throw new Error("workflow-journal reached without the workflowsJournal journal witness");
@@ -154,7 +167,7 @@ export async function handleWorkflows(req, res, match, ctx) {
 }
 export async function handleWorkflowAgentSteer(req, res, match, ctx) {
     const { deps } = ctx;
-    const { readJson, rateLimited, quotaExceeded, leaseDenied, safeDecode, runSessionAcceptOk } = ctx.helpers;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied, safeDecode } = ctx.helpers;
     switch (match.decl.id) {
         case "workflow-agent-steer":
             break;
@@ -169,7 +182,8 @@ export async function handleWorkflowAgentSteer(req, res, match, ctx) {
             sendWorkflowsUnavailable(res, runs.why);
             return;
         }
-        const principal = gatedPrincipal(req, deps.config);
+        const subject = gatedSubject(req, deps.config);
+        const principal = subject === undefined ? undefined : partsOf(subject).person;
         if (deps.config.requirePrincipal && principal === undefined) {
             sendPrincipalRefusal(res, req, deps.config);
             return;
@@ -197,14 +211,16 @@ export async function handleWorkflowAgentSteer(req, res, match, ctx) {
             return;
         }
         const trusted = explicitOperatorOk(principal, deps.config);
-        const ownerScope = principal ?? "default";
+        const ownerScope = taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)).principal ?? "default";
         const wfRun = await getWorkflowRun(runs.store, wfRunId, ownerScope);
         if (!trusted && !wfRun) {
-            sendError(res, 404, "not_found.workflow", "workflow not found");
+            sendWorkflowAbsent(res);
             return;
         }
-        if (wfRun && !runSessionAcceptOk(req, res, { sessionId: wfRun.originatingSessionId ?? null }, "workflow.agent-steer", "workflow not found"))
+        if (wfRun && !sessionAsserted(WORKFLOW_SESSION_ASSERTION["workflow-agent-steer"], req, wfRun.originatingSessionId, callerOf(req, deps).operator)) {
+            sendWorkflowAbsent(res);
             return;
+        }
         const sendNotRunningWf = (error) => sendError(res, 409, "steering.not_running", error);
         const redacted = redactSteerIn(body.content, label);
         const resolution = deps.workflowAgentRegistry?.resolve(wfRunId, label);
@@ -364,6 +380,18 @@ export const WORKFLOW_RUN_STATS_DISPOSITIONS = {
     costMicroUsd: "forward",
     nested: { nested: WORKFLOW_RUN_STATS_NESTED_DISPOSITIONS },
 };
+export const WORKFLOW_BUDGET_OVERSHOOT_DISPOSITIONS = {
+    budgetTokens: "forward",
+    spentTokens: "forward",
+    unsettledTokens: "forward",
+};
+export const WORKFLOW_TIMEOUT_INTERRUPTION_DISPOSITIONS = {
+    timeoutMs: "forward",
+    agentsCompleted: "forward",
+    agentsFailed: "forward",
+    agentsInFlight: "forward",
+    approvalWaitedMs: "forward",
+};
 export const WORKFLOW_RUN_DISPOSITIONS = {
     id: "forward",
     scope: "forward",
@@ -373,6 +401,8 @@ export const WORKFLOW_RUN_DISPOSITIONS = {
     description: { redact: "redactSecrets" },
     stats: { nested: WORKFLOW_RUN_STATS_DISPOSITIONS },
     agentFailures: "forward",
+    budgetOvershoot: { nested: WORKFLOW_BUDGET_OVERSHOOT_DISPOSITIONS },
+    timeoutInterruption: { nested: WORKFLOW_TIMEOUT_INTERRUPTION_DISPOSITIONS },
     startedAt: "forward",
     endedAt: "forward",
     createdAt: "forward",
@@ -396,8 +426,6 @@ export const WORKFLOW_RUN_DISPOSITIONS = {
     sourceTaskId: "strip",
     originatingSessionId: "strip",
     effectiveArgs: "strip",
-    budgetOvershoot: "strip",
-    timeoutInterruption: "strip",
     resultFull: "strip",
     completionId: "strip",
     resume: "strip",

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

@@ -32,40 +32,48 @@
  * (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`)。
+ * 429 `limit.rate_exceeded`(沿用现有限流码,不新铸一枚:消费端的分支同「稍后再来」)+ 体里机读 `reason`(闭集 {@link RATE_EXCEEDED_REASONS},今天两词)
+ * + `retryAfterSec`(固定 {@link RATE_EXCEEDED_RETRY_AFTER_SEC});头 `Retry-After` 与体里同值,同其它限流 / 配额门的发送形(`res.setHeader("retry-after")` + `sendError`)。
  * 拒在建行、认领会话与 SSE 头之前(受理漏斗已做的会话登记见上面「位置的两个如实」)。
  *
  * ## 谁需要 / 谁受伤 / 补偿
  * 需要:共享一台 GPU 或一只小模型网关的家用 / 小团队部署。受伤:超帽者拿 429(新行为,缺省关)。补偿:缺省 0 = 关(升级零变化)+ `Retry-After` 给退避。
  * 无主体请求(无头 service 凭据、`REQUIRE_PRINCIPAL=false` 的单用户部署)只受全局帽 —— 按主体帽对它不判(没有主体可分账)。
+ *
+ * ## 同一扇门的第二个拒因:沙箱容量(`sandbox_capacity`)
+ * local-docker 车道容器帽(`DOCKER_MAX_CONTAINERS`,`plugins/local-docker-capacity.ts`)的真闸在起容器处(子代、续跑腿、首个工具调用都只能在那里拒);
+ * 本门是它在提交面的早答:**闸里此刻有起动在等空位** ⇒ 新提交 429 `sandbox_capacity`(新 run 只会接到队尾)。门读闸的队列(`SandboxCapacityView.waiting`),
+ * 不调 docker、不另数;队列空而车道满时新提交照常放行,它的首个工具调用在起容器处等。判在两只 run 帽之前(拒时不占席位),与 run 帽同四口同位、同不判续跑 / 唤醒 / 作答。
  */
 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";
+import type { TerminalSeat } from "./route-ctx.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` 的消费端编译红)。
+ * `run_concurrency_cap` = 本副本在飞 run 已到并发帽;`sandbox_capacity` = local-docker 车道容器帽前已有起动在等空位。
  * 其余 `limit.rate_exceeded` 的产地(速率桶、赎回准入、MCP 探活、烘焙提交)不带 `reason` —— 读法是「有 `reason` 才分」。
  */
-export declare const RATE_EXCEEDED_REASONS: readonly ["run_concurrency_cap"];
+export declare const RATE_EXCEEDED_REASONS: readonly ["run_concurrency_cap", "sandbox_capacity"];
 export type RateExceededReason = (typeof RATE_EXCEEDED_REASONS)[number];
-/** 退避提示:固定 5 秒(是提示不是承诺 —— 在飞的 run 可能再跑很久;帽满只说「稍后再来」)。 */
-export declare const RUN_CONCURRENCY_RETRY_AFTER_SEC = 5;
+/** 退避提示:固定 5 秒(是提示不是承诺 —— 在飞的 run / 在跑的容器可能再跑很久;满只说「稍后再来」)。两个拒因同值。 */
+export declare const RATE_EXCEEDED_RETRY_AFTER_SEC = 5;
 /** 一枚席位:放行与登记进在飞集之间占着的那一格。`release` 幂等(登记点放一次,提交门的 `finally` 再放一次兜底)。 */
 export interface RunSlot {
     release(): void;
 }
-/** 并发帽拒的 `{status, body, retryAfterSec}`(体经全仓唯一组句器;状态与退避供发送口用)。 */
-export declare function runConcurrencyRefusalOf(): {
+/**
+ * 提交门 429 的 `{status, body, retryAfterSec}`(一只铸点出闭集里每个拒因;体经全仓唯一组句器;状态与退避供发送口用)。
+ * 每个拒因一臂字面句(穷举 `switch`:加词而没写臂 ⇒ tsc 红;字面句让 `test/api-error-text-freeze.test.ts` 逐字冻住)。
+ */
+export declare function rateExceededRefusalOf(reason: RateExceededReason): {
     readonly status: 429;
     readonly body: RefusalBody;
     readonly retryAfterSec: number;
@@ -75,11 +83,11 @@ export interface RunConcurrencyGate {
      * 提交门的并发帽准入:放行 ⇒ 交回席位(调用点登记那一拍 / `finally` 放);超帽 ⇒ 已应答 429(+ `Retry-After`),交回 `undefined`,调用点 `return`。
      * 位序:在幂等重放、`rateLimited` / `quotaExceeded` / `leaseDenied` / `usageWindowDenied` 之后,任何建行 / 认领 / SSE 头之前。
      */
-    admitRun(req: IncomingMessage, res: ServerResponse): RunSlot | undefined;
+    admitRun(req: IncomingMessage, res: ServerResponse, seat: TerminalSeat): Promise<RunSlot | undefined>;
 }
-/** 装配口:`deps` 只读 `config`(两旋钮,每次判时现读)与 `logger`;在飞集由 server 装配层交来(两张登记簿本身,不拷)。 */
+/** 装配口:`deps` 只读 `config`(两旋钮,每次判时现读)、`logger` 与沙箱容量闸的只读面(缺席 ⇒ 不判);在飞集由 server 装配层交来(两张登记簿本身,不拷)。 */
 export declare function createRunConcurrencyGate(ctx: {
-    deps: Pick<FlatServiceDeps, "config" | "logger">;
+    deps: Pick<FlatServiceDeps, "config" | "logger" | "sandboxCapacity">;
     inflightRuns: ReadonlyMap<string, RunAbort>;
     steerableRuns: ReadonlyMap<string, unknown>;
 }): RunConcurrencyGate;

package/dist/http/run-concurrency-cap.js

@@ -1,54 +1,67 @@
-import { gatedPrincipal } from "./principal-gate.js";
+import { gatedPerson } from "./principal-gate.js";
+import { personOf } from "../owner-brands.js";
+import { recoveredSubject } from "../owner-faces.js";
 import { refusalBody } from "./refusal-body.js";
 import { sendError } from "./send.js";
 export function liveRunIdsOf(inflightRuns, steerableRuns) {
     return new Set([...inflightRuns.keys(), ...steerableRuns.keys()]);
 }
-export const RUN_CONCURRENCY_CAP_REASON = "run_concurrency_cap";
-export const RATE_EXCEEDED_REASONS = [RUN_CONCURRENCY_CAP_REASON];
-export const RUN_CONCURRENCY_RETRY_AFTER_SEC = 5;
+export const RATE_EXCEEDED_REASONS = ["run_concurrency_cap", "sandbox_capacity"];
+export const RATE_EXCEEDED_RETRY_AFTER_SEC = 5;
 const UNTRACKED_SLOT = { release: () => undefined };
-export function runConcurrencyRefusalOf() {
-    return {
-        status: 429,
-        body: refusalBody({
-            errorCode: "limit.rate_exceeded",
-            message: "too many runs are in flight on this server right now — nothing was started; retry after the Retry-After interval",
-            facts: { reason: RUN_CONCURRENCY_CAP_REASON, retryAfterSec: RUN_CONCURRENCY_RETRY_AFTER_SEC },
-        }),
-        retryAfterSec: RUN_CONCURRENCY_RETRY_AFTER_SEC,
-    };
+export function rateExceededRefusalOf(reason) {
+    const facts = { reason, retryAfterSec: RATE_EXCEEDED_RETRY_AFTER_SEC };
+    switch (reason) {
+        case "run_concurrency_cap":
+            return { status: 429, body: refusalBody({ errorCode: "limit.rate_exceeded", message: "too many runs are in flight on this server right now — nothing was started; retry after the Retry-After interval", facts }), retryAfterSec: RATE_EXCEEDED_RETRY_AFTER_SEC };
+        case "sandbox_capacity":
+            return { status: 429, body: refusalBody({ errorCode: "limit.rate_exceeded", message: "sandbox capacity reached: container starts are already waiting for a free slot — nothing was started; retry after the Retry-After interval", facts }), retryAfterSec: RATE_EXCEEDED_RETRY_AFTER_SEC };
+    }
 }
 export function createRunConcurrencyGate(ctx) {
     const { deps, inflightRuns, steerableRuns } = ctx;
     const seats = new Set();
-    function admitRun(req, res) {
+    async function refuse(res, exit, reason) {
+        const refusal = rateExceededRefusalOf(reason);
+        const { error, errorCode, ...extra } = refusal.body;
+        await exit.deliverTerminal(() => {
+            res.setHeader("retry-after", String(refusal.retryAfterSec));
+            sendError(res, refusal.status, errorCode, error, extra);
+        });
+        return undefined;
+    }
+    async function admitRun(req, res, exit) {
+        const waiting = deps.sandboxCapacity?.waiting() ?? 0;
+        if (waiting > 0) {
+            deps.logger?.info?.("sandbox_capacity_refused", { waiting });
+            return refuse(res, exit, "sandbox_capacity");
+        }
         const { runMaxConcurrent: globalCap, runMaxConcurrentPerPrincipal: ownCap } = deps.config;
         if (globalCap === 0 && ownCap === 0)
             return UNTRACKED_SLOT;
-        const owner = gatedPrincipal(req, deps.config);
+        const person = gatedPerson(req, deps.config);
         const live = liveRunIdsOf(inflightRuns, steerableRuns);
         const inFlight = live.size + seats.size;
         let scope;
         if (globalCap > 0 && inFlight >= globalCap)
             scope = "global";
-        else if (ownCap > 0 && owner !== undefined) {
-            const holders = [...[...live].map((id) => inflightRuns.get(id)?.owner), ...[...seats].map((seat) => seat.owner)];
-            if (holders.filter((o) => o === owner).length >= ownCap)
+        else if (ownCap > 0 && person !== undefined) {
+            const holders = [...[...live].map((id) => personOfHolder(inflightRuns.get(id)?.owner)), ...[...seats].map((seat) => seat.person)];
+            if (holders.filter((p) => p === person).length >= ownCap)
                 scope = "principal";
         }
         if (scope !== undefined) {
-            deps.logger?.info?.("run_concurrency_cap_refused", { scope, inFlight, cap: scope === "global" ? globalCap : ownCap, hasPrincipal: owner !== undefined });
-            const refusal = runConcurrencyRefusalOf();
-            const { error, errorCode, ...extra } = refusal.body;
-            res.setHeader("retry-after", String(refusal.retryAfterSec));
-            sendError(res, refusal.status, errorCode, error, extra);
-            return undefined;
+            deps.logger?.info?.("run_concurrency_cap_refused", { scope, inFlight, cap: scope === "global" ? globalCap : ownCap, hasPrincipal: person !== undefined });
+            return refuse(res, exit, "run_concurrency_cap");
         }
-        const seat = { owner };
+        const seat = { person };
         seats.add(seat);
         return { release: () => void seats.delete(seat) };
     }
     return { admitRun };
 }
+function personOfHolder(owner) {
+    const subject = recoveredSubject(owner);
+    return subject === undefined ? undefined : personOf(subject);
+}
 //# sourceMappingURL=run-concurrency-cap.js.map

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

@@ -1,12 +1,10 @@
 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">;
+    config: Pick<ServiceConfig, "infraCostRates">;
 }
-/** 一条行是不是「看起来失联」:盘上 `running`、而最后一次心跳早于 `runStaleSec` —— 读面把它折成 `failed`(`run.stalled`)。读它的人只此一只判据(读面与同步重放回执同读)。 */
-export declare function runRowStale(deps: RunFaceDeps, run: RunRecord): boolean;
 /**
  * 一条行上的结果**当作出口结果读**(封口 + 脱敏的读入口)—— 读面的 `result` 与同步提交的重放体读的是同一只:
  * 终局行按 taskId+updatedAt 记忆的读入口,非终局行(停驻 / 在跑)走店入口那一套封口的读入口;行上没有结果 ⇒ `undefined`。
@@ -26,7 +24,7 @@ export declare function readRunFace(deps: RunFaceDeps, runStore: RunStore, run:
     msSinceLastActivity?: number | undefined;
     taskId: string;
     sessionId: string;
-    status: "running" | import("@sema-agent/core").TaskStatus;
+    status: import("@sema-agent/core").TaskStatus | "running";
 }>;
 /** run 行读面的值形 —— 从唯一投影口的返回型派生(不手抄键表)。 */
 export type RunReadFace = Awaited<ReturnType<typeof readRunFace>>;