voratiq 0.1.0-beta.21 → 0.1.0-beta.23

package/dist/interactive/substrate.js

@@ -6,7 +6,7 @@ import process from "node:process";
 import { collectProviderArtifacts, prepareProviderArtifactCaptureContext, } from "../agents/launch/chat.js";
 import { writeStagedPrompt } from "../agents/launch/prompt.js";
 import { resolveAgentProviderForDefinition } from "../agents/launch/provider-state.js";
-import { clearActiveInteractive, finalizeActiveInteractive, registerActiveInteractive, } from "../commands/interactive/lifecycle.js";
+import { clearActiveInteractive, finalizeActiveInteractive, getActiveInteractiveTerminationStatus, registerActiveInteractive, } from "../commands/interactive/lifecycle.js";
 import { createTeardownController, runTeardown, } from "../competition/shared/teardown.js";
 import { AgentBinaryAccessError, AgentBinaryMissingError, AgentDisabledError, AgentNotFoundError, } from "../configs/agents/errors.js";
 import { loadAgentById } from "../configs/agents/loader.js";
@@ -14,6 +14,7 @@ import { resolveFirstPartyLaunchPrompt } from "../domain/interactive/prompt.js";
 import { toErrorMessage } from "../utils/errors.js";
 import { isMissing } from "../utils/fs.js";
 import { generateSessionId } from "../utils/session-id.js";
+import { normalizeInteractiveTerm } from "../utils/terminal.js";
 import { resolveVoratiqCliTarget } from "../utils/voratiq-cli-target.js";
 import { createBundledVoratiqToolDeclaration, prepareProviderNativeLaunch, resolveFirstPartyMcpStatus, } from "./providers.js";
 import { appendInteractiveSessionRecord, ensureInteractiveSessionDirectories, resolveInteractiveSessionPaths, rewriteInteractiveSessionRecord, toInteractiveSessionRelativePath, } from "./records.js";
@@ -127,6 +128,7 @@ export async function prepareNativeInteractiveSession(options) {
             try {
                 firstPartyMcpResolution = await resolveFirstPartyMcpStatus({
                     providerId,
+                    providerBinary: agent.binary,
                     root: options.root,
                     toolDeclarations,
                     promptForMcpInstall: options.promptForMcpInstall,
@@ -169,6 +171,11 @@ export async function prepareNativeInteractiveSession(options) {
             agent,
             root: options.root,
             toolDeclarations,
+            sessionScopedMcpEnv: providerId === "codex"
+                ? {
+                    VORATIQ_INTERACTIVE_SESSION_ID: sessionId,
+                }
+                : undefined,
             prompt,
             launchMode: options.launchMode,
             firstPartyMcpResolution,
@@ -182,8 +189,8 @@ export async function prepareNativeInteractiveSession(options) {
         ...process.env,
         ...providerLaunch.env,
         VORATIQ_INTERACTIVE_SESSION_ID: sessionId,
-        VORATIQ_INTERACTIVE_SESSION_ROOT: paths.sessionRoot,
     };
+    delete invocationEnv.VORATIQ_INTERACTIVE_SESSION_ROOT;
     let artifactCaptureContext;
     if (providerLaunch.artifactCaptureSupported) {
         try {
@@ -191,6 +198,13 @@ export async function prepareNativeInteractiveSession(options) {
                 providerId,
                 sessionRoot: paths.sessionRoot,
                 searchEnv: invocationEnv,
+                selectionHint: providerId === "codex"
+                    ? {
+                        strategy: "codex-session-meta",
+                        cwd: cwd.path,
+                        minStartedAt: createdAt,
+                    }
+                    : undefined,
             });
         }
         catch {
@@ -251,9 +265,15 @@ export async function spawnPreparedInteractiveSession(prepared, options = {}) {
     if (stdio === "inherit") {
         process.stdout.write("\n");
     }
+    const spawnEnv = stdio === "inherit"
+        ? {
+            ...prepared.invocation.env,
+            TERM: normalizeInteractiveTerm(prepared.invocation.env),
+        }
+        : prepared.invocation.env;
     const child = spawn(prepared.invocation.command, prepared.invocation.args, {
         cwd: prepared.invocation.cwd,
-        env: prepared.invocation.env,
+        env: spawnEnv,
         stdio,
     });
     const completion = createProcessCompletionPromise(prepared, child);
@@ -321,9 +341,11 @@ function createProcessCompletionPromise(prepared, child) {
                 return;
             }
             finalized = true;
+            const terminationStatus = getActiveInteractiveTerminationStatus(prepared.sessionId);
+            const signalCountsAsSuccess = terminationStatus === "aborted" && options.signal !== null;
             const runtimeFailureMessage = options.spawnError
                 ? `Failed during provider execution: ${options.spawnError.message}`
-                : options.signal
+                : options.signal && !signalCountsAsSuccess
                     ? `Provider process terminated by signal ${options.signal}`
                     : options.exitCode && options.exitCode !== 0
                         ? `Provider process exited with code ${options.exitCode}`
@@ -509,10 +531,15 @@ function failure(kind, code, message, cause) {
     };
 }
 function buildBaseRecord(options) {
-    const { sessionId, createdAt, status, agentId, toolAttachmentStatus, chat, error, } = options;
+    const { sessionId, createdAt, status, agentId, toolAttachmentStatus, startedAt, completedAt, chat, error, } = options;
+    const resolvedStartedAt = startedAt ?? createdAt;
     return {
         sessionId,
         createdAt,
+        startedAt: resolvedStartedAt,
+        ...(status !== "running"
+            ? { completedAt: completedAt ?? resolvedStartedAt }
+            : {}),
         status,
         agentId,
         toolAttachmentStatus,

package/dist/mcp/server.d.ts

@@ -62,6 +62,7 @@ interface JsonRpcErrorResponse {
     };
 }
 type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+export declare const VORATIQ_GUIDE_RESOURCE_URI: "voratiq://guide";
 export declare function getVoratiqMcpToolDefinitions(): readonly McpToolDefinition[];
 export declare function createVoratiqMcpRequestHandler(options?: CreateVoratiqMcpRequestHandlerOptions): {
     handleRequest: (message: JsonRpcRequestMessage) => Promise<JsonRpcResponse>;

package/dist/mcp/server.js

@@ -1,9 +1,13 @@
 import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import process from "node:process";
 import { z } from "zod";
-import { externalApplyExecutionInputSchema, externalListInspectionInputSchema, externalMessageExecutionInputSchema, externalPruneExecutionInputSchema, externalReduceExecutionInputSchema, externalRunExecutionInputSchema, externalSpecExecutionInputSchema, externalVerifyExecutionInputSchema, } from "../cli/contract.js";
-import { operatorResultEnvelopeSchema, } from "../cli/operator-envelope.js";
-import { listJsonOutputSchema, } from "../contracts/list.js";
+import { externalApplyExecutionInputSchema, externalInspectionOperatorSchema, externalMessageExecutionInputSchema, externalPruneExecutionInputSchema, externalReduceExecutionInputSchema, externalRunExecutionInputSchema, externalSpecExecutionInputSchema, externalVerifyExecutionInputSchema, } from "../cli/contract.js";
+import { buildSwarmSessionAcknowledgementEnvelope, operatorResultEnvelopeSchema, } from "../cli/operator-envelope.js";
+import { listJsonModes, listJsonModeSchema, listJsonOutputSchema, } from "../contracts/list.js";
+import { VORATIQ_MCP_ACK_OPERATOR_ENV, VORATIQ_MCP_ACK_PATH_ENV, } from "../utils/swarm-session-ack.js";
 import { getVoratiqVersion } from "../utils/version.js";
 import { createEntrypointVoratiqCliTarget as createEntrypointCliTarget, resolveVoratiqCliTarget, } from "../utils/voratiq-cli-target.js";
 const JSON_RPC_VERSION = "2.0";
@@ -14,6 +18,8 @@ const JSON_RPC_INVALID_REQUEST = -32600;
 const JSON_RPC_METHOD_NOT_FOUND = -32601;
 const JSON_RPC_INVALID_PARAMS = -32602;
 const JSON_RPC_INTERNAL_ERROR = -32603;
+const SWARM_EARLY_ACK_TIMEOUT_MS = 15_000;
+const SWARM_EARLY_ACK_POLL_INTERVAL_MS = 100;
 export const VORATIQ_MCP_PROTOCOL_VERSION = "2025-11-25";
 export const VORATIQ_SUPPORTED_MCP_PROTOCOL_VERSIONS = [
     VORATIQ_MCP_PROTOCOL_VERSION,
@@ -23,6 +29,25 @@ export const VORATIQ_SUPPORTED_MCP_PROTOCOL_VERSIONS = [
 function isSupportedMcpProtocolVersion(protocolVersion) {
     return VORATIQ_SUPPORTED_MCP_PROTOCOL_VERSIONS.includes(protocolVersion);
 }
+const mcpListInspectionInputSchema = z.discriminatedUnion("mode", [
+    z
+        .object({
+        operator: externalInspectionOperatorSchema,
+        mode: z.literal(listJsonModes[0]),
+        verbose: z.boolean().optional(),
+        limit: z.number().int().positive().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        operator: externalInspectionOperatorSchema,
+        mode: z.literal(listJsonModes[1]),
+        sessionId: z.string().min(1),
+        verbose: z.boolean().optional(),
+        limit: z.number().int().positive().optional(),
+    })
+        .strict(),
+]);
 const initializeRequestParamsSchema = z
     .object({
     protocolVersion: z.string(),
@@ -70,7 +95,7 @@ const toolSpecs = [
     {
         name: "voratiq_message",
         operator: "message",
-        description: "Send an isolated prompt to one or more Voratiq agents and persist their independent replies as a durable message session.",
+        description: "Send an isolated prompt to one or more Voratiq agents and persist their independent replies as a recorded message session.",
         inputSchemaSource: externalMessageExecutionInputSchema,
         buildArgs: (input) => buildMessageExecutionArgs(input),
         outputContract: "execution",
@@ -86,8 +111,8 @@ const toolSpecs = [
     {
         name: "voratiq_list",
         operator: "list",
-        description: "List recorded Voratiq sessions for one operator (`spec`, `run`, `reduce`, `verify`, or `message`) in table or detail mode.",
-        inputSchemaSource: externalListInspectionInputSchema,
+        description: "List recorded Voratiq sessions for one operator (`spec`, `run`, `reduce`, `verify`, `message`, or `interactive`) in list or detail mode.",
+        inputSchemaSource: mcpListInspectionInputSchema,
         mcpInputSchema: createListMcpInputSchema(),
         buildArgs: (input) => buildListInspectionArgs(input),
         outputContract: "list",
@@ -107,7 +132,70 @@ const toolDefinitions = toolSpecs.map((tool) => ({
     description: tool.description,
     inputSchema: tool.mcpInputSchema ?? toToolInputJsonSchema(tool.inputSchemaSource),
 }));
-const VORATIQ_MCP_SERVER_INSTRUCTIONS = "Voratiq tools operate on Voratiq workflow state in the current repository. Use voratiq_list for questions about recent or specific spec, run, reduce, verify, or message sessions. Use voratiq_spec, voratiq_run, voratiq_reduce, voratiq_verify, voratiq_message, voratiq_apply, and voratiq_prune for the normal Voratiq workflow. Prefer these tools over shell inspection when the task is about Voratiq workflow history or state.";
+export const VORATIQ_GUIDE_RESOURCE_URI = "voratiq://guide";
+const VORATIQ_GUIDE_RESOURCE_CONTENT = `# Voratiq Operator Guide
+
+Voratiq is a workflow system built around composable operators that launch, evaluate, and manage multi-agent work against a repository. It gives interactive agents a structured way to delegate coding tasks, inspect recorded state, verify outcomes, and apply accepted changes without doing all of that inline.
+
+## Operator Classes
+
+Voratiq operators fall into two main classes:
+
+- **Swarm operators** dispatch agents to produce, synthesize, or evaluate work: spec, run, reduce, verify, message
+- **Control operators** inspect state or mutate accepted outcomes: list, apply, prune
+
+## Swarm Operators
+
+**spec** – Drafts or refines a specification for a task from a description, an existing spec, or related repository context. Launches one or more spec agents and records their outputs as a spec session.
+
+**run** – Executes a spec session by launching run agents that read the spec, work against a sandboxed workspace, and produce artifacts including diffs and transcripts. Records a run session.
+
+**reduce** – Summarizes artifacts from a spec, run, or message session into a single reduced output suitable for comparison or follow-on work. Records a reduce session.
+
+**verify** – Evaluates a spec, run, reduction, or message session and records a structured verdict. This is Voratiq's main decision operator: use it to compare outputs, choose stronger candidates, and decide whether work should be applied, inspected further, rerun, or redirected.
+
+**message** – Sends an isolated prompt to one or more agents and persists each reply independently as a message session. Use for standalone questions, reviews, or exploration that does not require a full spec/run workflow.
+
+## Control Operators
+
+**list** – Lists or inspects recorded sessions for a given operator. This is the primary way to inspect swarm sessions; use it to poll progress, retrieve session IDs, and inspect recorded workflow state.
+
+**apply** – Applies an accepted run diff into the current working tree. Synchronous and non-durable; only invoke after verifying that the target run is in an acceptable state.
+
+**prune** – Removes pruneable run workspaces or all pruneable state. Synchronous and non-durable; requires explicit confirmation.
+
+## Workflow Composition
+
+Operators compose into many workflow shapes rather than one required path. Common patterns include: using message for standalone exploration or review; using spec → verify to compare candidate specs before execution; using spec → run when a task needs structured execution; using run → verify to choose among competing implementations; using reduce when multiple outputs need synthesis before a decision; and using verify whenever a workflow needs a structured recommendation instead of ad hoc judgment. The list operator can be called at any point to inspect recorded state across all operators.
+
+## Swarm Session Behavior
+
+The five swarm operators are spec, run, reduce, verify, and message. Each one creates a recorded session and may return before the session is finished. Once a session has been created, treat that session as the unit of work. A returned sessionId means the work has been launched, not completed. Use voratiq_list to inspect active sessions.
+
+## Status Interpretation
+
+Session status is primary; recipient status is supporting detail.
+
+- **queued** means the session has been accepted and recorded but its work has not started yet.
+- **running** means the session is active and remains the canonical in-flight unit of work.
+- **succeeded** means the session reached a successful terminal state; inspect its outputs and decide what should happen next.
+- **failed** means the session reached a terminal failure state.
+- **unresolved** means the session reached a terminal state without a clear winner or confident decision.
+
+Mixed recipient states do not imply session failure. Some recipients may fail while others continue running, and the session remains active until its session status becomes terminal.
+
+## extraContext Contract
+
+The extraContext field accepts an array of file paths pointing to additional readable files staged alongside the operator workspace. Pass file paths only — not raw text content, and not paths to files that operators already see by default (such as standard repository context). Passing raw content or redundant paths increases token usage without providing new information.
+
+## maxParallel Semantics
+
+The maxParallel field controls the maximum number of agent recipients running in parallel for an operator invocation. Set it deliberately: it directly affects cost and latency. Higher values increase concurrency but also increase total token expenditure and can create contention. Do not treat maxParallel as a free dial to increase throughput without modeling the downstream cost and latency impact.
+
+## Key Discipline Rules
+
+Commit to one workflow objective per session; do not interleave unrelated operator calls in the same sequence. Wait for stage boundaries before acting on results: read voratiq_list output before proceeding from one stage to the next. Use voratiq_list as the primary control plane for inspecting recorded state rather than reading session files directly.`;
+const VORATIQ_MCP_SERVER_INSTRUCTIONS = "Voratiq tools operate on Voratiq workflow state in the current repository. Use voratiq_list for questions about recent or specific spec, run, reduce, verify, message, or interactive sessions. The swarm operators (voratiq_spec, voratiq_run, voratiq_reduce, voratiq_verify, voratiq_message) create recorded sessions and may acknowledge before finishing; once launched, treat the session as the unit of work. If a swarm call times out or returns a non-terminal status, inspect progress with voratiq_list instead of retrying. Use voratiq_apply and voratiq_prune for synchronous control actions. Prefer these tools over shell inspection when the task is about Voratiq workflow history or state.";
 const toolSpecsByName = new Map(toolSpecs.map((tool) => [tool.name, tool]));
 export function getVoratiqMcpToolDefinitions() {
     return toolDefinitions;
@@ -144,6 +232,7 @@ export function createVoratiqMcpRequestHandler(options = {}) {
                         tools: {
                             listChanged: true,
                         },
+                        resources: {},
                     },
                     instructions: VORATIQ_MCP_SERVER_INSTRUCTIONS,
                     serverInfo: {
@@ -185,6 +274,33 @@ export function createVoratiqMcpRequestHandler(options = {}) {
                 });
                 return createSuccessResponse(message.id, result);
             }
+            if (message.method === "resources/list") {
+                return createSuccessResponse(message.id, {
+                    resources: [
+                        {
+                            uri: VORATIQ_GUIDE_RESOURCE_URI,
+                            name: "Voratiq Operator Guide",
+                            description: "Complete reference for Voratiq operators, workflow composition, swarm-session behavior, extraContext contract, and maxParallel semantics.",
+                            mimeType: "text/plain",
+                        },
+                    ],
+                });
+            }
+            if (message.method === "resources/read") {
+                const uri = isRecord(message.params) ? message.params.uri : undefined;
+                if (uri === VORATIQ_GUIDE_RESOURCE_URI) {
+                    return createSuccessResponse(message.id, {
+                        contents: [
+                            {
+                                uri: VORATIQ_GUIDE_RESOURCE_URI,
+                                mimeType: "text/plain",
+                                text: VORATIQ_GUIDE_RESOURCE_CONTENT,
+                            },
+                        ],
+                    });
+                }
+                return createErrorResponse(message.id, JSON_RPC_INVALID_PARAMS, `Unknown resource URI: ${String(uri)}`);
+            }
             return createErrorResponse(message.id, JSON_RPC_METHOD_NOT_FOUND, `Method not found: ${message.method}`);
         },
         handleNotification(message) {
@@ -207,7 +323,10 @@ export async function runVoratiqMcpStdioServer(options = {}) {
     const pendingPayloads = [];
     let isDraining = false;
     let hasEnded = false;
+    let inFlightHandlers = 0;
+    let hasCompletedInitialize = false;
     let transportEncoding = "framed";
+    let writeChain = Promise.resolve();
     await new Promise((resolve, reject) => {
         const tryResolve = () => {
             if (!hasEnded) {
@@ -219,8 +338,53 @@ export async function runVoratiqMcpStdioServer(options = {}) {
             if (pendingPayloads.length > 0) {
                 return;
             }
+            if (inFlightHandlers > 0) {
+                return;
+            }
             resolve();
         };
+        const writeMessageSerialized = (outputEncoding, message) => {
+            writeChain = writeChain.then(() => {
+                writeMessage(stdout, outputEncoding, message);
+            });
+            return writeChain;
+        };
+        const handlePayload = async (payload, outputEncoding) => {
+            try {
+                const parsed = JSON.parse(payload);
+                const message = normalizeIncomingMessage(parsed);
+                if (!message) {
+                    await writeMessageSerialized(outputEncoding, createErrorResponse(null, JSON_RPC_INVALID_REQUEST, "Invalid JSON-RPC message."));
+                    return;
+                }
+                if ("id" in message) {
+                    const response = await requestHandler.handleRequest(message);
+                    await writeMessageSerialized(outputEncoding, response);
+                    if (message.method === "initialize" && !("error" in response)) {
+                        hasCompletedInitialize = true;
+                        await writeMessageSerialized(outputEncoding, createNotification("notifications/tools/list_changed"));
+                    }
+                    return;
+                }
+                await requestHandler.handleNotification(message);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    await writeMessageSerialized(outputEncoding, createErrorResponse(null, JSON_RPC_PARSE_ERROR, "Failed to parse JSON-RPC payload.", { message: error.message }));
+                    return;
+                }
+                await writeMessageSerialized(outputEncoding, createErrorResponse(null, JSON_RPC_INTERNAL_ERROR, "Unhandled MCP server error.", {
+                    message: toErrorMessage(error),
+                }));
+            }
+        };
+        const dispatchPayload = (payload, outputEncoding) => {
+            inFlightHandlers += 1;
+            return handlePayload(payload, outputEncoding).finally(() => {
+                inFlightHandlers -= 1;
+                tryResolve();
+            });
+        };
         const drainQueue = () => {
             if (isDraining) {
                 return;
@@ -228,36 +392,15 @@ export async function runVoratiqMcpStdioServer(options = {}) {
             isDraining = true;
             void (async () => {
                 while (pendingPayloads.length > 0) {
-                    const payload = pendingPayloads.shift();
-                    if (payload === undefined) {
+                    const queued = pendingPayloads.shift();
+                    if (queued === undefined) {
                         continue;
                     }
-                    try {
-                        const parsed = JSON.parse(payload);
-                        const message = normalizeIncomingMessage(parsed);
-                        if (!message) {
-                            writeMessage(stdout, transportEncoding, createErrorResponse(null, JSON_RPC_INVALID_REQUEST, "Invalid JSON-RPC message."));
-                            continue;
-                        }
-                        if ("id" in message) {
-                            const response = await requestHandler.handleRequest(message);
-                            writeMessage(stdout, transportEncoding, response);
-                            if (message.method === "initialize" && !("error" in response)) {
-                                writeMessage(stdout, transportEncoding, createNotification("notifications/tools/list_changed"));
-                            }
-                            continue;
-                        }
-                        await requestHandler.handleNotification(message);
-                    }
-                    catch (error) {
-                        if (error instanceof SyntaxError) {
-                            writeMessage(stdout, transportEncoding, createErrorResponse(null, JSON_RPC_PARSE_ERROR, "Failed to parse JSON-RPC payload.", { message: error.message }));
-                            continue;
-                        }
-                        writeMessage(stdout, transportEncoding, createErrorResponse(null, JSON_RPC_INTERNAL_ERROR, "Unhandled MCP server error.", {
-                            message: toErrorMessage(error),
-                        }));
+                    if (!hasCompletedInitialize) {
+                        await dispatchPayload(queued.payload, queued.transportEncoding);
+                        continue;
                     }
+                    void dispatchPayload(queued.payload, queued.transportEncoding);
                 }
                 isDraining = false;
                 tryResolve();
@@ -276,7 +419,10 @@ export async function runVoratiqMcpStdioServer(options = {}) {
                     break;
                 }
                 transportEncoding = extracted.transportEncoding;
-                pendingPayloads.push(extracted.payload);
+                pendingPayloads.push({
+                    payload: extracted.payload,
+                    transportEncoding,
+                });
                 buffer = Buffer.from(extracted.remaining);
             }
             drainQueue();
@@ -285,7 +431,10 @@ export async function runVoratiqMcpStdioServer(options = {}) {
             const trailingPayload = extractTrailingJsonLine(buffer);
             if (trailingPayload) {
                 transportEncoding = "jsonl";
-                pendingPayloads.push(trailingPayload);
+                pendingPayloads.push({
+                    payload: trailingPayload,
+                    transportEncoding,
+                });
                 buffer = Buffer.alloc(0);
                 drainQueue();
             }
@@ -498,10 +647,20 @@ function appendOptionalTrueFlag(args, flag, enabled) {
 }
 export { createEntrypointCliTarget, resolveVoratiqCliTarget };
 export function createDefaultCliJsonContractInvoker(target = resolveVoratiqCliTarget()) {
-    return async (input) => await invokeSubprocess({
-        command: target.command,
-        args: [...target.argsPrefix, ...input.args],
-    });
+    return async (input) => {
+        if (isSwarmExecutionOperator(input.operator)) {
+            return await invokeSwarmSubprocessWithEarlyAck({
+                command: target.command,
+                args: [...target.argsPrefix, ...input.args],
+                operator: input.operator,
+                cwd: process.cwd(),
+            });
+        }
+        return await invokeSubprocess({
+            command: target.command,
+            args: [...target.argsPrefix, ...input.args],
+        });
+    };
 }
 async function invokeSubprocess(options) {
     return await new Promise((resolve) => {
@@ -547,6 +706,142 @@ async function invokeSubprocess(options) {
         });
     });
 }
+async function invokeSwarmSubprocessWithEarlyAck(options) {
+    const ackDir = await mkdtemp(join(tmpdir(), "voratiq-mcp-ack-"));
+    const ackPath = join(ackDir, "ack.json");
+    return await new Promise((resolve) => {
+        let settled = false;
+        let shouldBufferOutput = true;
+        const child = spawn(options.command, options.args, {
+            cwd: options.cwd,
+            env: {
+                ...process.env,
+                [VORATIQ_MCP_ACK_PATH_ENV]: ackPath,
+                [VORATIQ_MCP_ACK_OPERATOR_ENV]: options.operator,
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const settle = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            void rm(ackDir, { recursive: true, force: true }).catch(() => { });
+            resolve(result);
+        };
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            if (shouldBufferOutput) {
+                stdoutChunks.push(chunk);
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (shouldBufferOutput) {
+                stderrChunks.push(chunk);
+            }
+        });
+        child.once("error", (error) => {
+            settle({
+                kind: "spawn_failed",
+                error,
+            });
+        });
+        child.once("close", (code) => {
+            settle({
+                kind: "success",
+                exitCode: code ?? 0,
+                stdout: stdoutChunks.join(""),
+                stderr: stderrChunks.join(""),
+            });
+        });
+        void waitForSwarmSessionObservation({
+            ackPath,
+            timeoutMs: SWARM_EARLY_ACK_TIMEOUT_MS,
+            pollIntervalMs: SWARM_EARLY_ACK_POLL_INTERVAL_MS,
+        })
+            .then((observation) => {
+            if (!observation) {
+                return;
+            }
+            shouldBufferOutput = false;
+            settle({
+                kind: "success",
+                exitCode: 0,
+                stdout: JSON.stringify(buildSwarmSessionAcknowledgementEnvelope({
+                    operator: options.operator,
+                    sessionId: observation.sessionId,
+                    status: observation.status,
+                })),
+                stderr: "",
+            });
+        })
+            .catch(() => { });
+    });
+}
+function isSwarmExecutionOperator(operator) {
+    return (operator === "spec" ||
+        operator === "run" ||
+        operator === "reduce" ||
+        operator === "verify" ||
+        operator === "message");
+}
+async function waitForSwarmSessionObservation(options) {
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        const observation = await readSwarmSessionRecord({
+            ackPath: options.ackPath,
+        });
+        if (observation) {
+            return observation;
+        }
+        await sleep(options.pollIntervalMs);
+    }
+    return undefined;
+}
+async function readSwarmSessionRecord(options) {
+    try {
+        const raw = await readFile(options.ackPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            return undefined;
+        }
+        const sessionId = parsed.sessionId;
+        if (typeof sessionId !== "string" || sessionId.length === 0) {
+            return undefined;
+        }
+        const status = parsed.status;
+        if (status !== "queued" &&
+            status !== "running" &&
+            status !== "succeeded" &&
+            status !== "failed") {
+            return undefined;
+        }
+        return {
+            sessionId,
+            status,
+        };
+    }
+    catch (error) {
+        if (isMissingPathError(error) || error instanceof SyntaxError) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function isMissingPathError(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
 function toToolInputJsonSchema(schema) {
     const jsonSchema = z.toJSONSchema(schema, {
         io: "input",
@@ -573,10 +868,8 @@ function createPruneMcpInputSchema() {
 function createListMcpInputSchema() {
     return toToolInputJsonSchema(z
         .object({
-        operator: z.enum(["spec", "run", "reduce", "verify", "message"]),
-        mode: z
-            .enum(["table", "detail"])
-            .describe("Use `detail` only when inspecting a specific session."),
+        operator: externalInspectionOperatorSchema,
+        mode: listJsonModeSchema.describe("Use `detail` only when inspecting a specific session."),
         sessionId: z
             .string()
             .min(1)

package/dist/policy/auto.d.ts

@@ -8,6 +8,5 @@ export interface AutoVerificationSelectionActionRequired {
 }
 export type AutoVerificationSelectionDisposition = AutoVerificationSelectionProceed | AutoVerificationSelectionActionRequired;
 export declare function classifyAutoVerificationSelection(options: {
-    targetKind: "spec" | "run";
     selection?: SelectionDecision;
 }): AutoVerificationSelectionDisposition;

package/dist/policy/auto.js

@@ -1,22 +1,11 @@
+const UNRESOLVED_VERIFICATION_MESSAGE = "Verification did not produce a resolvable candidate; manual review required.";
 export function classifyAutoVerificationSelection(options) {
-    const { targetKind, selection } = options;
+    const { selection } = options;
     if (selection?.state === "resolvable") {
         return { kind: "proceed" };
     }
     return {
         kind: "action_required",
-        detail: describeActionRequiredSelection({ targetKind, selection }),
+        detail: UNRESOLVED_VERIFICATION_MESSAGE,
     };
 }
-function describeActionRequiredSelection(options) {
-    const { targetKind, selection } = options;
-    if (selection?.state === "unresolved" &&
-        selection.unresolvedReasons.some((reason) => reason.code === "verifier_disagreement")) {
-        return targetKind === "spec"
-            ? "Verifiers disagreed on the preferred draft; manual selection required."
-            : "Verifiers disagreed on the preferred candidate; manual selection required.";
-    }
-    return targetKind === "spec"
-        ? "Verification did not select a draft; manual selection required."
-        : "Verification did not produce a resolvable candidate; manual selection required.";
-}