@sema-agent/core 7.5.2 → 7.6.0

package/dist/core/mcp.js

@@ -3,7 +3,8 @@ import { MCP_NAMESPACE } from "./protocol-table.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { classifyMcpFailure, describeHttpTransportFailure } from "./mcp-failure.js";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -204,6 +205,10 @@ function armMcpIdleWatchdog(health, idleMs, outerSignal) {
 export function mcpStartupTimeoutMs() {
     return parseEnvMs("MCP_TIMEOUT");
 }
+function markMcpFailure(e, details) {
+    e.details = details;
+    return e;
+}
 const MCP_SPEC_ERROR_CODE_NAMES = new Map([
     [-32020, "header mismatch (the server saw an HTTP header that disagreed with the tool parameter mapped onto it)"],
     [-32021, "missing required client capability (the server requires a capability this client does not declare)"],
@@ -237,90 +242,6 @@ function remoteErrorText(err, opts) {
     const raw = err instanceof Error ? err.message : String(err);
     return redactSecrets(opts?.collapse === true ? collapseMcpErrorPrefix(raw) : raw);
 }
-function isTransportLost(err) {
-    if (err instanceof McpError && err.code === ErrorCode.ConnectionClosed)
-        return true;
-    return err instanceof Error && /not connected|connection closed/i.test(err.message);
-}
-const NETWORK_CODES_NEVER_DELIVERED = new Set([
-    "ECONNREFUSED",
-    "ENOTFOUND",
-    "EAI_AGAIN",
-    "EHOSTUNREACH",
-    "ENETUNREACH",
-    "UND_ERR_CONNECT_TIMEOUT",
-]);
-export function networkErrorCode(err, depth = 0) {
-    if (depth > 5 || !(err instanceof Error))
-        return undefined;
-    const code = err.code;
-    if (typeof code === "string" && /^(?:E[A-Z_]+|UND_ERR_[A-Z_]+)$/.test(code))
-        return code;
-    if (err instanceof AggregateError) {
-        for (const inner of err.errors) {
-            const found = networkErrorCode(inner, depth + 1);
-            if (found !== undefined)
-                return found;
-        }
-    }
-    return networkErrorCode(err.cause, depth + 1);
-}
-export function describeHttpTransportFailure(err) {
-    if (err instanceof McpError)
-        return undefined;
-    if (err instanceof StreamableHTTPError) {
-        const status = typeof err.code === "number" && err.code > 0 ? err.code : undefined;
-        return {
-            condition: status !== undefined
-                ? `its HTTP endpoint answered ${status} instead of an MCP response`
-                : "its HTTP endpoint answered something that is not an MCP response",
-            delivered: "unknown",
-            ...(status !== undefined ? { httpStatus: status } : {}),
-        };
-    }
-    const code = networkErrorCode(err);
-    if (code !== undefined) {
-        return NETWORK_CODES_NEVER_DELIVERED.has(code)
-            ? { condition: `its HTTP endpoint could not be reached (${code})`, delivered: "no" }
-            : { condition: `the connection to its HTTP endpoint failed (${code})`, delivered: "unknown" };
-    }
-    if (err instanceof TypeError && /fetch failed|terminated|network/i.test(err.message)) {
-        return { condition: "the HTTP request to its endpoint failed at the network layer", delivered: "unknown" };
-    }
-    return undefined;
-}
-export const MCP_FAILURE_CODES = ["connect_refused", "connection_failed", "network", "not_mcp_response", "spawn_failed", "connection_closed", "timeout", "protocol", "invalid_config", "unknown"];
-export function mcpFailureCodeOf(err, transport) {
-    if (err instanceof McpError) {
-        if (err.code === ErrorCode.ConnectionClosed)
-            return "connection_closed";
-        if (err.code === ErrorCode.RequestTimeout)
-            return "timeout";
-        return "protocol";
-    }
-    const http = describeHttpTransportFailure(err);
-    if (http !== undefined) {
-        if (http.httpStatus !== undefined)
-            return `http_${http.httpStatus}`;
-        if (err instanceof StreamableHTTPError)
-            return "not_mcp_response";
-        const code = networkErrorCode(err);
-        if (code === undefined)
-            return "network";
-        if (code === "ERR_INVALID_URL")
-            return "invalid_config";
-        if (code.startsWith("ERR_"))
-            return "unknown";
-        if (transport === "stdio")
-            return "spawn_failed";
-        if (transport === undefined)
-            return "connection_failed";
-        return http.delivered === "no" ? "connect_refused" : "connection_failed";
-    }
-    if (isTransportLost(err))
-        return "connection_closed";
-    return "unknown";
-}
 function writeEffectWarning(writeEffect) {
     return writeEffect
         ? " This tool is write-capable: treat its side effects as POSSIBLY APPLIED and verify the actual state before retrying."
@@ -341,72 +262,63 @@ function rethrowHonestMcpError(err, ctx) {
     sanitizeMcpErrorTextInPlace(err);
     if (ctx.idle?.signal.reason === IDLE_WATCHDOG_ABORT_REASON) {
         const serverLabel = inlineUntrusted(ctx.server);
-        const e = new Error(`${ctx.what} on MCP server "${serverLabel}" received no response for ${ctx.idle.idleMs}ms (idle watchdog — ` +
+        finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" received no response for ${ctx.idle.idleMs}ms (idle watchdog — ` +
             `distinct from the ${ctx.timeoutMs}ms total ceiling above). The server may still be alive but is not ` +
             `responding; the client stopped waiting.${writeEffectWarning(ctx.writeEffect)} (Set MCP_IDLE_TIMEOUT_STDIO ` +
-            `/ MCP_IDLE_TIMEOUT_HTTP (ms) to change this bound.)`, { cause: err });
-        e.errorKind = "timeout";
-        e.details = { timedOut: true, timeoutMs: ctx.idle.idleMs, idleTimeout: true, server: ctx.server };
-        finish(e);
+            `/ MCP_IDLE_TIMEOUT_HTTP (ms) to change this bound.)`, { cause: err }), { code: "timeout", delivered: "unknown", server: ctx.server, timeoutMs: ctx.idle.idleMs, idleTimeout: true }));
     }
     if (ctx.signal?.aborted)
         finish(err);
     const serverLabel = inlineUntrusted(ctx.server);
     const fenceServerText = (label, raw) => delimitUntrusted(label, truncateMcpErrorText(raw));
-    if (err instanceof McpError && err.code === ErrorCode.RequestTimeout) {
-        const data = err.data;
-        const totalMs = typeof data?.maxTotalTimeout === "number" ? data.maxTotalTimeout : undefined;
-        const e = new Error(totalMs !== undefined
-            ? `${ctx.what} on MCP server "${serverLabel}" exceeded its total time ceiling of ${totalMs}ms (the call stayed alive — e.g. via progress notifications — but ran past the total wall-clock budget). The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT_TOTAL environment variable (ms) to change this ceiling; MCP_TOOL_TIMEOUT only tunes the per-call timer, currently ${ctx.timeoutMs}ms.)`
-            : `${ctx.what} on MCP server "${serverLabel}" timed out after ${ctx.timeoutMs}ms. The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT environment variable (ms) to change this limit.)`, { cause: err });
-        e.errorKind = "timeout";
-        e.details =
-            totalMs !== undefined
-                ? { timedOut: true, timeoutMs: totalMs, totalTimeout: true, server: ctx.server }
-                : { timedOut: true, timeoutMs: ctx.timeoutMs, server: ctx.server };
-        finish(e);
-    }
-    if (isTransportLost(err)) {
-        const e = new Error(`The connection to MCP server "${serverLabel}" was lost while ${ctx.what} was in flight. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}`, { cause: err });
-        e.errorKind = "transport_lost";
-        e.details = { transportLost: true, server: ctx.server };
-        finish(e);
-    }
-    const httpFailure = describeHttpTransportFailure(err);
-    if (httpFailure !== undefined) {
-        const detail = remoteErrorText(err);
-        const fenced = `\nThe transport error follows as external/untrusted data:\n${fenceServerText(`${ctx.server} transport error`, detail)}`;
-        const e = new Error(httpFailure.delivered === "no"
-            ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
-            : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err });
-        e.errorKind = httpFailure.delivered === "no" ? "server_disconnected" : "transport_lost";
-        e.details = {
-            server: ctx.server,
-            ...(httpFailure.delivered === "no" ? {} : { transportLost: true }),
-            ...(httpFailure.httpStatus !== undefined ? { httpStatus: httpFailure.httpStatus } : {}),
-        };
-        finish(e);
-    }
-    if (err instanceof McpError) {
-        const condition = describeMcpSpecErrorCode(err.code);
-        if (condition !== undefined) {
-            const e = new Error(`${ctx.what} on MCP server "${serverLabel}" was rejected with MCP protocol error ${err.code} — ${condition}. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, err.message)}`, { cause: err });
-            e.errorKind = "protocol_error";
-            e.details = { server: ctx.server, specErrorCode: err.code };
-            finish(e);
+    const failure = classifyMcpFailure(err, { phase: "request" });
+    const details = (extra) => ({ code: failure.kind, delivered: failure.delivered, server: ctx.server, ...extra });
+    switch (failure.kind) {
+        case "timeout": {
+            const data = err.data;
+            const totalMs = typeof data?.maxTotalTimeout === "number" ? data.maxTotalTimeout : undefined;
+            finish(markMcpFailure(new Error(totalMs !== undefined
+                ? `${ctx.what} on MCP server "${serverLabel}" exceeded its total time ceiling of ${totalMs}ms (the call stayed alive — e.g. via progress notifications — but ran past the total wall-clock budget). The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT_TOTAL environment variable (ms) to change this ceiling; MCP_TOOL_TIMEOUT only tunes the per-call timer, currently ${ctx.timeoutMs}ms.)`
+                : `${ctx.what} on MCP server "${serverLabel}" timed out after ${ctx.timeoutMs}ms. The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT environment variable (ms) to change this limit.)`, { cause: err }), totalMs !== undefined ? details({ timeoutMs: totalMs, totalTimeout: true }) : details({ timeoutMs: ctx.timeoutMs })));
+        }
+        case "connection_closed":
+            finish(markMcpFailure(new Error(`The connection to MCP server "${serverLabel}" was lost while ${ctx.what} was in flight. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}`, { cause: err }), details()));
+        case "http_status":
+        case "not_mcp_response":
+        case "connect_refused":
+        case "connection_failed": {
+            const httpFailure = describeHttpTransportFailure(err);
+            const detail = remoteErrorText(err);
+            const fenced = `\nThe transport error follows as external/untrusted data:\n${fenceServerText(`${ctx.server} transport error`, detail)}`;
+            finish(markMcpFailure(new Error(failure.delivered === "no"
+                ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
+                : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err }), details(failure.httpStatus !== undefined ? { httpStatus: failure.httpStatus } : undefined)));
+        }
+        case "protocol": {
+            const code = err.code;
+            const condition = describeMcpSpecErrorCode(code);
+            if (condition !== undefined) {
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" was rejected with MCP protocol error ${code} — ${condition}. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, err.message)}`, { cause: err }), details({ specErrorCode: code })));
+            }
+            if (ctx.attributeServer) {
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err))}`, { cause: err }), details()));
+            }
+            finish(markMcpFailure(err, details()));
+        }
+        case "spawn_failed":
+        case "invalid_config":
+        case "unknown": {
+            if (ctx.attributeServer) {
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err))}`, { cause: err }), details()));
+            }
+            if (err instanceof Error)
+                finish(markMcpFailure(err, details()));
+            finish(err);
         }
     }
-    if (ctx.attributeServer) {
-        const msg = remoteErrorText(err);
-        finish(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, msg)}`, { cause: err }));
-    }
-    finish(err);
 }
 function throwDeadServer(server, what) {
-    const e = new Error(`MCP server "${inlineUntrusted(server)}" is disconnected (its transport closed earlier in this task). ${what} was not attempted. This server's tools and resources will keep failing until the server is available again — do not retry them; use an alternative if one exists.`);
-    e.errorKind = "server_disconnected";
-    e.details = { server };
-    throw e;
+    throw markMcpFailure(new Error(`MCP server "${inlineUntrusted(server)}" is disconnected (its transport closed earlier in this task). ${what} was not attempted. This server's tools and resources will keep failing until the server is available again — do not retry them; use an alternative if one exists.`), { code: "connection_closed", delivered: "no", server });
 }
 export { normalizeNameSegment as normalizeMcpName, clampNameSegment } from "./protocol-naming.js";
 export * from "./image-downsample.js";
@@ -516,6 +428,7 @@ export function resolveProtocolHttpHeaders(protocol, t, principal) {
     }
     return t.headers;
 }
+export const declaredEndpointFetch = (url, init) => fetch(url, { ...init, redirect: "manual" });
 function buildTransport(spec, principal, kind) {
     const t = spec.transport;
     if (kind === "stdio") {
@@ -532,6 +445,7 @@ function buildTransport(spec, principal, kind) {
     const headers = resolveProtocolHttpHeaders(MCP_NAMESPACE.id, t, principal);
     return new StreamableHTTPClientTransport(new URL(t.url), {
         requestInit: headers ? { headers } : undefined,
+        fetch: declaredEndpointFetch,
     });
 }
 let autoResizer;
@@ -893,7 +807,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             }
             else {
                 warnings.push(asServerWarning(spec, r.reason));
-                statuses.push({ name: spec.name, status: "failed", errorCode: mcpFailureCodeOf(r.reason, dialKinds[i]), error: namedMcpFailureText(r.reason) });
+                const { kind, delivered, httpStatus } = classifyMcpFailure(r.reason, { phase: "connect", transport: dialKinds[i] });
+                statuses.push({ name: spec.name, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(r.reason) });
             }
         }
         const resourceTools = buildResourceTools(resourceServers, isServerRevoked);
@@ -933,8 +848,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     const advertised = new Set(listed.tools.map((t) => t.name));
                     const retainedRaw = listed.incomplete !== undefined ? h.listedRaw.filter((t) => !advertised.has(t.name)) : [];
                     const mergedRaw = retainedRaw.length > 0 ? [...listed.tools, ...retainedRaw] : listed.tools;
-                    cacheMcpToolMetadata(h.client, retainedRaw.length > 0 ? [...retainedRaw, ...listed.tools] : listed.tools);
-                    const { serverTools, serverAxes, dropped } = intakeListedTools({ tools: mergedRaw }, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked, h.transportKind);
+                    const { serverTools, serverAxes, dropped, accepted } = intakeListedTools({ tools: mergedRaw }, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked, h.transportKind);
+                    cacheMcpToolMetadata(h.client, accepted);
                     const priorNames = h.tools.map((t) => t.name);
                     const newNames = serverTools.map((t) => t.name);
                     const added = newNames.filter((n) => !priorNames.includes(n));
@@ -1305,7 +1220,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 if (isServerRevoked(server)) {
                     return {
                         content: [{ type: "text", text: `${what} was refused: MCP server "${server}" was revoked by the operator mid-session. The request was NOT sent. This server stays on this run's tool roster — every call to it is refused the same way, so don't retry it.` }],
-                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server },
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", delivered: "no", server },
                         terminate: false,
                         isError: true,
                     };
@@ -1364,7 +1279,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 if (isServerRevoked(server)) {
                     return {
                         content: [{ type: "text", text: `${what} was refused: MCP server "${server}" was revoked by the operator mid-session. The request was NOT sent. This server stays on this run's tool roster — every call to it is refused the same way, so don't retry it.` }],
-                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server },
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", delivered: "no", server },
                         terminate: false,
                         isError: true,
                     };
@@ -1524,8 +1439,8 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             announce.fn?.();
         };
         const listed = await listToolsLenient(client, startupOpts);
-        cacheMcpToolMetadata(client, listed.tools);
-        const { serverTools, serverAxes, dropped, advisories } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
+        const { serverTools, serverAxes, dropped, advisories, accepted } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
+        cacheMcpToolMetadata(client, accepted);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1567,6 +1482,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
+    const accepted = [];
     const advisories = [];
     const mintedNames = new Map();
     for (const t of listed.tools) {
@@ -1607,6 +1523,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             advisories.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaAdvisory, 240) });
         }
         const remoteName = t.name;
+        const taskRequired = t.execution !== null && typeof t.execution === "object" && t.execution.taskSupport === "required";
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
         const mintedBy = mintedNames.get(namespacedName);
         if (mintedBy !== undefined) {
@@ -1639,7 +1556,15 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                 if (isServerRevoked?.(spec.name) === true) {
                     return {
                         content: [{ type: "text", text: `The call to MCP server "${spec.name}" was refused: the server was revoked by the operator mid-session. The call was NOT sent, so the server did not execute it. This server stays on this run's tool roster — every call to it is refused the same way, so don't retry it.` }],
-                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server: spec.name },
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", delivered: "no", server: spec.name },
+                        terminate: false,
+                        isError: true,
+                    };
+                }
+                if (taskRequired) {
+                    return {
+                        content: [{ type: "text", text: "The call was refused: this tool requires task-based execution (MCP tasks), which this client does not drive. The call was NOT sent, so the server did not execute it. Every call to this tool is refused the same way, so don't retry it." }],
+                        details: { error: "mcp.task_required", code: "mcp.task_required", delivered: "no", server: spec.name },
                         terminate: false,
                         isError: true,
                     };
@@ -1693,7 +1618,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                     if (reminderDisclosure !== undefined) {
                         observeReminderMarkEcho({ text: msg, mark: reminderDisclosure.mark, outlet: "mcp", counts: reminderDisclosure.counts });
                     }
-                    throw new Error(msg);
+                    throw Object.assign(new Error(msg), { details: { code: "mcp.tool_error", delivered: "yes", server: spec.name } });
                 }
                 const content = gateMcpOutput(mapped);
                 const sc = res.structuredContent;
@@ -1731,8 +1656,9 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             },
         };
         serverTools.push(declaredContentOrigin !== undefined ? withContentOrigin(mounted, declaredContentOrigin) : mounted);
+        accepted.push(t);
     }
-    return { serverTools, serverAxes, dropped, advisories };
+    return { serverTools, serverAxes, dropped, advisories, accepted };
 }
 function asServerWarning(spec, err) {
     const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err)})`, { cause: sanitizedCause(err) });

package/dist/core/pause-registry.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The pause registry — ONE table for the three faces of a durable pause (why it stopped / what it left
+ * hanging / what brings it back), the three word types and the resume match DERIVED from it, and the
+ * registry-bound `gate` × `pendingAction` pair with its checked constructor. A vocabulary module on the
+ * floor: it types against `checkpoint-store.ts` (type-only, no runtime edge) and `checkpoint-store.ts`
+ * reaches down for the pair type.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { Checkpoint, CheckpointGate, CheckpointRow, PendingAction, ResumeOutcome } from "./checkpoint-store.js";
+/**
+ * THE registry of pauses — one row per way a run can stop and wait, and the ONE place the three faces
+ * of that pause are declared together: WHY it stopped (`CheckpointGate.kind`, the row key), WHAT it left
+ * hanging (`pending` — the {@link PendingAction} kind the row carries), and WHAT BRINGS IT BACK (`resume`
+ * — the {@link ResumeOutcome} gate word a caller must answer with). The three vocabularies used to be
+ * three independent `as const` lists whose correspondence lived in a six-arm disjunction in the resume
+ * entry and two FACET comments; adding a kind of pause meant three declarations, one disjunction arm and
+ * two comments, and missing any of them was silent. Now the three word types, the resume match and the
+ * facet are DERIVED from this table: adding a pause = adding a row, and the fences below red the build
+ * until every declaration agrees with it.
+ *
+ *  - `facet` — the deadline semantic a deployment's reaper applies (see {@link Checkpoint.deadline}):
+ *    `A` = approval gates, whose `deadline` is an SLA resolve-deny; `B` = unattended-TTL gates, whose
+ *    `deadline` is an abandonment TTL (`expire`/`reap` only — never a resolve-deny; these pauses produce
+ *    no `tool_end` and therefore no settlement); `-` = the non-gate park (`task_done`).
+ *  - `taskStatus` — the `TaskResult.status` word a run assembles when it stops at this gate (approvals and
+ *    resource slices read `suspended`; the two review pauses read `needs_review`).
+ *  - `terminal` — `task_done` is the 1C handle / deployment-park convention, not a run pause core mints.
+ */
+export declare const PAUSE_REGISTRY: {
+    readonly human: {
+        readonly pending: "tool_approval";
+        readonly resume: "policy_ask";
+        readonly facet: "A";
+        readonly taskStatus: "suspended";
+        readonly terminal: false;
+    };
+    readonly irreversible_ask: {
+        readonly pending: "tool_approval";
+        readonly resume: "policy_ask";
+        readonly facet: "A";
+        readonly taskStatus: "suspended";
+        readonly terminal: false;
+    };
+    readonly resource_limit: {
+        readonly pending: "resource_limit";
+        readonly resume: "resource_limit";
+        readonly facet: "B";
+        readonly taskStatus: "suspended";
+        readonly terminal: false;
+    };
+    readonly needs_review: {
+        readonly pending: "review";
+        readonly resume: "dry_run_review";
+        readonly facet: "B";
+        readonly taskStatus: "needs_review";
+        readonly terminal: false;
+    };
+    readonly plan_review: {
+        readonly pending: "plan_review";
+        readonly resume: "plan_review";
+        readonly facet: "B";
+        readonly taskStatus: "needs_review";
+        readonly terminal: false;
+    };
+    readonly task_done: {
+        readonly pending: "task_done";
+        readonly resume: "task_done";
+        readonly facet: "-";
+        readonly taskStatus: "suspended";
+        readonly terminal: true;
+    };
+};
+/** The pause kinds — the row keys of {@link PAUSE_REGISTRY}; `CheckpointGate.kind` is fenced to equal it. */
+export type GateKind = keyof typeof PAUSE_REGISTRY;
+/** The pending-action kinds — the `pending` column; `PendingAction.kind` is fenced to equal it. */
+export type PendingKind = (typeof PAUSE_REGISTRY)[GateKind]["pending"];
+/** The resume gate words — the `resume` column plus `wake` (the un-park verb, which is not a gate decision
+ *  and so has no registry row); `ResumeOutcome.gate` is fenced to equal it. */
+export type ResumeGate = (typeof PAUSE_REGISTRY)[GateKind]["resume"] | "wake";
+/** Runtime twin of {@link GateKind}. */
+export declare function isGateKind(v: unknown): v is GateKind;
+/** The one resume-match predicate: does this outcome gate word answer a checkpoint of this kind? `wake`
+ *  answers any (it passed its own, stricter, non-gate validation upstream); every other word must be the
+ *  row's `resume` column. Replaces a six-arm hand-written disjunction. */
+export declare function resumeGateMatches(gateKind: GateKind, outcomeGate: ResumeGate): boolean;
+/**
+ * The one CONSTRUCTOR of a registry-bound pause pair from a gate and a pending action that arrive
+ * separately typed (a mint site that chooses its gate in a ternary, a store deserializing a row, a test
+ * fixture taking overrides). The generic binds the pending action's kind to the gate's registry row at
+ * the call site; the runtime check is the belt for the wide call (`CheckpointGate` × `PendingAction`) and
+ * for a deserialized row, where the type says nothing about the bytes. A pair the registry does not pair
+ * is refused loudly here rather than persisted and discovered at resume.
+ */
+export declare function pauseOf<K extends GateKind>(gate: Extract<CheckpointGate, {
+    kind: K;
+}>, pendingAction: Extract<PendingAction, {
+    kind: (typeof PAUSE_REGISTRY)[K]["pending"];
+}>): CheckpointPause<K>;
+/** The loose input shape of {@link checkpointFrom}: a row's fields with its gate and pending action typed
+ *  independently (as a deserializer or a fixture holds them). */
+export type CheckpointFields = CheckpointRow & {
+    gate: CheckpointGate;
+    pendingAction: PendingAction;
+};
+/** Build a {@link Checkpoint} from independently typed fields — {@link pauseOf} binds (and checks) the pair. */
+export declare function checkpointFrom(fields: CheckpointFields): Checkpoint;
+/** Compile-time fences (each `never` while the declaration and the registry agree, in BOTH directions). */
+export type GateDeclarationCoversEveryRegistryRow = AssertAllKeysHandled<Exclude<GateKind, CheckpointGate["kind"]>>;
+export type RegistryCoversEveryGateDeclaration = AssertAllKeysHandled<Exclude<CheckpointGate["kind"], GateKind>>;
+export type PendingDeclarationCoversEveryRegistryColumn = AssertAllKeysHandled<Exclude<PendingKind, PendingAction["kind"]>>;
+export type RegistryCoversEveryPendingDeclaration = AssertAllKeysHandled<Exclude<PendingAction["kind"], PendingKind>>;
+export type ResumeDeclarationCoversEveryRegistryColumn = AssertAllKeysHandled<Exclude<ResumeGate, ResumeOutcome["gate"]>>;
+export type RegistryCoversEveryResumeDeclaration = AssertAllKeysHandled<Exclude<ResumeOutcome["gate"], ResumeGate>>;
+/**
+ * One row's `gate` × `pendingAction` pair, BOUND by {@link PAUSE_REGISTRY}: a `needs_review` gate carries a
+ * `review` pending action and nothing else, an approval gate a `tool_approval`, and so on. Distributed over
+ * the registry rows so that a row literal pairing a gate with another kind's pending action does not
+ * type-check — the invariant that used to be a sentence in a comment is now the shape of the type.
+ */
+type PairOf<K extends GateKind> = {
+    gate: Extract<CheckpointGate, {
+        kind: K;
+    }>;
+    pendingAction: Extract<PendingAction, {
+        kind: (typeof PAUSE_REGISTRY)[K]["pending"];
+    }>;
+};
+export type CheckpointPause<K extends GateKind = GateKind> = {
+    [P in K]: PairOf<P>;
+}[K];
+export {};

package/dist/core/pause-registry.js

@@ -0,0 +1,27 @@
+export const PAUSE_REGISTRY = {
+    human: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
+    irreversible_ask: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
+    resource_limit: { pending: "resource_limit", resume: "resource_limit", facet: "B", taskStatus: "suspended", terminal: false },
+    needs_review: { pending: "review", resume: "dry_run_review", facet: "B", taskStatus: "needs_review", terminal: false },
+    plan_review: { pending: "plan_review", resume: "plan_review", facet: "B", taskStatus: "needs_review", terminal: false },
+    task_done: { pending: "task_done", resume: "task_done", facet: "-", taskStatus: "suspended", terminal: true },
+};
+export function isGateKind(v) {
+    return typeof v === "string" && Object.prototype.hasOwnProperty.call(PAUSE_REGISTRY, v);
+}
+export function resumeGateMatches(gateKind, outcomeGate) {
+    return outcomeGate === "wake" || PAUSE_REGISTRY[gateKind].resume === outcomeGate;
+}
+export function pauseOf(gate, pendingAction) {
+    if (!isGateKind(gate.kind))
+        throw new Error(`checkpoint gate kind "${String(gate.kind)}" is not a registered pause`);
+    const expected = PAUSE_REGISTRY[gate.kind].pending;
+    if (pendingAction.kind !== expected) {
+        throw new Error(`a "${gate.kind}" checkpoint carries a "${String(pendingAction.kind)}" pending action — the pause registry pairs it with "${expected}"`);
+    }
+    return { gate, pendingAction };
+}
+export function checkpointFrom(fields) {
+    const { gate, pendingAction, ...row } = fields;
+    return { ...row, ...pauseOf(gate, pendingAction) };
+}

package/dist/core/runner/assemble-result.d.ts

@@ -1,5 +1,5 @@
 import type { AssistantMessage } from "../../internal/llm.js";
-import type { NestedUsage, TaskResult, TaskSpec } from "../types.js";
+import type { NestedUsage, PausedCause, TaskResult, TaskSpec, TerminalCause } from "../types.js";
 /** Per-task usage/cost accumulator (filled across the run loop, surfaced as `TaskResult.stats`). */
 export interface Stats {
     turns: number;
@@ -194,40 +194,16 @@ export interface ResultFlags {
      *  NOT `suspended` — slotted ABOVE `suspendRef` and the aborted branches (this suspend never minted a
      *  checkpoint, so `suspendRef` is unset anyway; the ordering makes the intent explicit). */
     suspendLoop?: boolean;
-    /** design/45: the task deliberately suspended at a durable tool gate (capture + abort fired). When set,
-     *  the result is `status:"suspended"` carrying this token/gate — a clean pause, NOT a failure, so it is
-     *  slotted ABOVE the `!final`/aborted branches (slot 8.5: it beats them but yields to a real
-     *  budget/threw failure that happened to coincide). The abort it used sets `final.stopReason="aborted"`
-     *  but does not set `threw`, so it never reaches the `flags.threw` branch. */
-    suspendRef?: {
-        token: import("../checkpoint-store.js").CheckpointToken;
-        /** The non-secret identity twin ({@link import("../checkpoint-store.js").Checkpoint.checkpointId}). */
-        checkpointId?: string;
-        gate: import("../checkpoint-store.js").CheckpointGate;
-        /** RB-439-b: how the paused workspace comes back (`"park_only"` = a non-suspendable target that was
-         *  never actually paused). Echoed on `TaskResult.workspaceRestoreMode`; absent for a process-local
-         *  suspend, which captured no remote workspace. */
-        restoreMode?: "snapshot" | "park_only";
-    };
-    /** design/76 §2.5 (dry-run / shadow) + design/80 D-B (plan-gate): the task deliberately paused at a
-     *  REVIEW-PAUSE gate — `{kind:"needs_review"}` (a profile's dry-run interception produced a predicted
-     *  state-diff a human/judge must REVIEW) OR `{kind:"plan_review"}` (a profile's plan-gate produced a
-     *  proposed PLAN a human must approve/edit/reject). When set, the result is `status:"needs_review"` +
-     *  errorCode `"review.pending"`, carrying this token/gate (keyed off ref-PRESENCE, not `gate.kind`, so it
-     *  serves both review kinds uniformly). It is the DUAL of `suspendRef` but for DIFFERENT semantics (a human
-     *  REVIEW, not a pre-action tool-call APPROVAL), so it has its OWN flag and its OWN assemble slot (8.6,
-     *  between `suspendRef` 8.5 and the aborted branches 9) — **never both set at once** (the commit-side
-     *  discriminant in prepare-task branches on `gate.kind` and sets exactly one). Disjoint from `suspendRef`
-     *  so this branch is reachable: keying status off `suspendRef` alone (reusing it) would report `"suspended"`
-     *  and make this dead code (v4 MAJOR-A). Like `suspendRef`, it used an abort to stop the loop (no `threw`),
-     *  so it never hits the failure branches above. */
-    reviewRef?: {
-        token: import("../checkpoint-store.js").CheckpointToken;
-        checkpointId?: string;
-        gate: import("../checkpoint-store.js").CheckpointGate;
-        /** RB-439-b: the review pause pauses the same workspace the approval pause does — same discriminant. */
-        restoreMode?: "snapshot" | "park_only";
-    };
+    /** The run's ONE committed durable pause (the holder's `pausedRef.current.cause`): the run stopped at a
+     *  gate — an approval or content ask, a resource slice, a platform pause, a plan or dry-run review —
+     *  and a checkpoint is durably committed. It used an abort to stop the loop (`final.stopReason ===
+     *  "aborted"`) but set no `threw`/timeout/turns, so it is slotted ABOVE the `!final`/aborted arms (a
+     *  clean pause, not a failure) and BELOW the real budget/threw failures (a limit that coincided still
+     *  owns the ending). WHICH terminal status it reads (`suspended` / `needs_review`) is the pause's own
+     *  `gate.kind` registry row, not a second flag: the two same-shaped refs that used to split the approval
+     *  family from the review family — and the slot order between them that only ever mattered if both were
+     *  somehow set — are gone with the commit-side routing that fed them. */
+    paused?: PausedCause;
 }
 /**
  * Extract a machine-readable code from a thrown error (e.g. `SessionError.code`, a Node error code).
@@ -236,6 +212,23 @@ export interface ResultFlags {
  * prefer the first specific code over a generic `"unknown"` wrapper.
  */
 export declare function errorCodeOf(err: unknown): string | undefined;
+/**
+ * WHY the run ended — the ONE terminal arbitration ({@link TerminalCause}). First match wins, in the
+ * slot order documented on {@link assembleResult} (a public contract: do not reorder). Every plane
+ * field a result shows (`status`, `errorCode`, `errorMessage`, `blockedReason`, the checkpoint seats)
+ * is projected from the value this returns by {@link terminalProjection}, so a terminal that carries a
+ * token cannot be reported under a status that does not, and a review pause cannot be reported as an
+ * approval pause: the pairing is the cause's shape, not the arbitration's discipline.
+ *
+ * `apiFailure` rides beside the cause rather than inside it on purpose: it is the message's own
+ * provider-failure disclosure, filled only when a provider failure IS the terminal (the same
+ * in-presence rule the usage-window wait hint states for itself), and it is not part of the cause's
+ * public projection.
+ */
+export declare function terminalCauseOf(final: AssistantMessage | undefined, stats: Pick<Stats, "humanReview">, flags: ResultFlags): {
+    terminal: TerminalCause;
+    apiFailure: TaskResult["apiFailure"];
+};
 /**
  * Build the final {@link TaskResult} from the run's terminal state. **The errorCode priority chain is a
  * public contract** (callers `switch` on these strings) — first match wins, in this exact order
@@ -252,12 +245,10 @@ export declare function errorCodeOf(err: unknown): string | undefined;
  *   6. `threw` + conflict→ `"conflict"`
  *   7. `threw` (other)   → `errorCodeOf(threw)`
  *   8. `blockedReason`   → status `"blocked"` (no errorCode)
- *   8.5 `suspendRef`     → status `"suspended"` + checkpointToken/gate (design/45 B4 — a deliberate
- *       durable pause beats the abort it used, but yields to a real budget/threw failure above)
- *   8.6 `reviewRef`     → status `"needs_review"` + `"review.pending"` + checkpointToken/gate (design/76 §2.5
- *       — a dry-run post-prediction REVIEW pause; the DUAL of 8.5, between it and the aborts, same red-line:
- *       a `suspendRef` at 8.5 still wins if both were somehow set, proving slot order — but the commit-side
- *       discriminant guarantees only one is ever set)
+ *   8.5 `paused`         → status by the pause's registry row (`suspended` for an approval / resource
+ *       slice / platform pause, `needs_review` + `"review.pending"` for a plan or dry-run review) +
+ *       checkpointToken/gate (design/45 B4 — a deliberate durable pause beats the abort it used, but
+ *       yields to a real budget/threw failure above)
  *   9. `abortedLive` | stopReason aborted → `"limits.max_walltime_exceeded"` | `"limits.max_turns_exceeded"` | undefined
  *       (audit A-1: hoisted ABOVE no-final — the loop exits cleanly on abort, so `final` may be a
  *       normal message or absent; a plain user interrupt carries NO errorCode — switch on `status`),