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

package/dist/domain/spec/model/mutators.js

@@ -0,0 +1,146 @@
+import { buildLifecycleStartFields, buildOperationLifecycleCompleteFields, buildRecordLifecycleCompleteFields, } from "../../shared/lifecycle.js";
+import { rewriteSpecRecord } from "../persistence/adapter.js";
+export function createSpecRecordMutators(input) {
+    const { root, specsFilePath, sessionId } = input;
+    const updateAgent = async (agentId, builder, forceFlush = false) => await rewriteSpecRecord({
+        root,
+        specsFilePath,
+        sessionId,
+        forceFlush,
+        mutate: (record) => {
+            const agents = [...record.agents];
+            const index = agents.findIndex((agent) => agent.agentId === agentId);
+            const current = index >= 0 ? agents[index] : undefined;
+            const updated = builder(current);
+            if (index >= 0) {
+                agents[index] = updated;
+            }
+            else {
+                agents.push(updated);
+            }
+            return {
+                ...record,
+                agents,
+            };
+        },
+    });
+    return {
+        recordAgentRunning: async ({ agentId, timestamp = new Date().toISOString(), }) => await updateAgent(agentId, (existing) => {
+            if (existing && isTerminalSpecAgentStatus(existing.status)) {
+                return existing;
+            }
+            return {
+                ...(existing ?? { agentId }),
+                status: "running",
+                ...buildLifecycleStartFields({
+                    existingStartedAt: existing?.startedAt,
+                    timestamp,
+                }),
+                completedAt: undefined,
+                outputPath: existing?.outputPath,
+                dataPath: existing?.dataPath,
+                contentHash: existing?.contentHash,
+                tokenUsage: existing?.tokenUsage,
+                error: null,
+            };
+        }),
+        recordAgentSnapshot: async (agent) => await updateAgent(agent.agentId, (existing) => existing
+            ? mergeSpecAgentEntries(existing, agent)
+            : normalizeSpecAgentEntry(agent), isTerminalSpecAgentStatus(agent.status)),
+        completeSpec: async ({ status, agents, error }) => await rewriteSpecRecord({
+            root,
+            specsFilePath,
+            sessionId,
+            mutate: (existing) => ({
+                ...existing,
+                status,
+                ...buildRecordLifecycleCompleteFields({ existing }),
+                ...(agents ? { agents: [...agents] } : {}),
+                ...(error !== undefined ? { error } : {}),
+            }),
+            forceFlush: true,
+        }),
+        readRecord: async () => await rewriteSpecRecord({
+            root,
+            specsFilePath,
+            sessionId,
+            mutate: (record) => record,
+        }),
+    };
+}
+function mergeSpecAgentEntries(existing, incoming) {
+    if (isTerminalSpecAgentStatus(existing.status) &&
+        !isTerminalSpecAgentStatus(incoming.status)) {
+        return existing;
+    }
+    if (incoming.status === "running") {
+        return {
+            ...existing,
+            ...incoming,
+            status: "running",
+            ...buildLifecycleStartFields({
+                existingStartedAt: existing.startedAt,
+                timestamp: incoming.startedAt,
+            }),
+            completedAt: undefined,
+            outputPath: incoming.outputPath ?? existing.outputPath,
+            dataPath: incoming.dataPath ?? existing.dataPath,
+            contentHash: incoming.contentHash ?? existing.contentHash,
+            tokenUsage: incoming.tokenUsage ?? existing.tokenUsage,
+            error: incoming.error !== undefined
+                ? incoming.error
+                : (existing.error ?? null),
+        };
+    }
+    const completedAt = incoming.completedAt ?? new Date().toISOString();
+    const startedAt = buildLifecycleStartFields({
+        existingStartedAt: existing.startedAt,
+        timestamp: incoming.startedAt ?? completedAt,
+    }).startedAt;
+    const lifecycle = buildOperationLifecycleCompleteFields({
+        existing: {
+            startedAt,
+            completedAt: existing.completedAt,
+        },
+        completedAt,
+    });
+    return {
+        ...existing,
+        ...incoming,
+        ...lifecycle,
+        outputPath: incoming.outputPath ?? existing.outputPath,
+        dataPath: incoming.dataPath ?? existing.dataPath,
+        contentHash: incoming.contentHash ?? existing.contentHash,
+        tokenUsage: incoming.tokenUsage ?? existing.tokenUsage,
+        error: incoming.error !== undefined ? incoming.error : (existing.error ?? null),
+    };
+}
+function normalizeSpecAgentEntry(agent) {
+    if (agent.status === "running") {
+        return {
+            ...agent,
+            ...buildLifecycleStartFields({
+                existingStartedAt: undefined,
+                timestamp: agent.startedAt,
+            }),
+            completedAt: undefined,
+            error: agent.error ?? null,
+        };
+    }
+    const completedAt = agent.completedAt ?? new Date().toISOString();
+    const startedAt = buildLifecycleStartFields({
+        existingStartedAt: undefined,
+        timestamp: agent.startedAt ?? completedAt,
+    }).startedAt;
+    return {
+        ...agent,
+        ...buildOperationLifecycleCompleteFields({
+            existing: { startedAt, completedAt: undefined },
+            completedAt,
+        }),
+        error: agent.error ?? null,
+    };
+}
+function isTerminalSpecAgentStatus(status) {
+    return status === "succeeded" || status === "failed";
+}

package/dist/domain/spec/model/types.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { type SpecAgentStatus, specAgentStatusSchema, type SpecRecordStatus, specRecordStatusSchema, TERMINAL_SPEC_AGENT_STATUSES, TERMINAL_SPEC_STATUSES } from "../../../status/index.js";
 export type { SpecAgentStatus, SpecRecordStatus };
 export { specAgentStatusSchema, specRecordStatusSchema, TERMINAL_SPEC_AGENT_STATUSES, TERMINAL_SPEC_STATUSES, };
+export declare const specContentHashSchema: z.ZodString;
 export declare const specAgentEntrySchema: z.ZodObject<{
     agentId: z.ZodString;
     status: z.ZodEnum<{
@@ -14,6 +15,7 @@ export declare const specAgentEntrySchema: z.ZodObject<{
     completedAt: z.ZodOptional<z.ZodString>;
     outputPath: z.ZodOptional<z.ZodString>;
     dataPath: z.ZodOptional<z.ZodString>;
+    contentHash: z.ZodOptional<z.ZodString>;
     tokenUsage: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         input_tokens: z.ZodOptional<z.ZodNumber>;
         output_tokens: z.ZodOptional<z.ZodNumber>;
@@ -66,6 +68,7 @@ export declare const specRecordSchema: z.ZodObject<{
         completedAt: z.ZodOptional<z.ZodString>;
         outputPath: z.ZodOptional<z.ZodString>;
         dataPath: z.ZodOptional<z.ZodString>;
+        contentHash: z.ZodOptional<z.ZodString>;
         tokenUsage: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             input_tokens: z.ZodOptional<z.ZodNumber>;
             output_tokens: z.ZodOptional<z.ZodNumber>;

package/dist/domain/spec/model/types.js

@@ -9,6 +9,10 @@ export { specAgentStatusSchema, specRecordStatusSchema, TERMINAL_SPEC_AGENT_STAT
 const IN_PROGRESS_SPEC_STATUSES = [
     "running",
 ];
+const SPEC_CONTENT_HASH_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+export const specContentHashSchema = z
+    .string()
+    .regex(SPEC_CONTENT_HASH_PATTERN);
 export const specAgentEntrySchema = z
     .object({
     agentId: agentIdSchema,
@@ -17,6 +21,7 @@ export const specAgentEntrySchema = z
     completedAt: z.string().optional(),
     outputPath: repoRelativeRecordPathSchema.optional(),
     dataPath: repoRelativeRecordPathSchema.optional(),
+    contentHash: specContentHashSchema.optional(),
     tokenUsage: extractedTokenUsageSchema.optional(),
     error: z.string().nullable().optional(),
 })

package/dist/domain/spec/persistence/adapter.d.ts

@@ -26,6 +26,7 @@ export interface RewriteSpecRecordOptions {
     specsFilePath: string;
     sessionId: string;
     mutate: (record: SpecRecord) => SpecRecord;
+    forceFlush?: boolean;
 }
 export interface AppendSpecRecordOptions {
     root: string;

package/dist/domain/spec/persistence/adapter.js

@@ -68,10 +68,15 @@ export async function appendSpecRecord(options) {
     }
 }
 export async function rewriteSpecRecord(options) {
-    const { root, specsFilePath, sessionId, mutate } = options;
+    const { root, specsFilePath, sessionId, mutate, forceFlush } = options;
     const paths = buildSpecPaths(root, specsFilePath);
     try {
-        return await specPersistence.rewriteRecord({ paths, sessionId, mutate });
+        return await specPersistence.rewriteRecord({
+            paths,
+            sessionId,
+            mutate,
+            forceFlush,
+        });
     }
     catch (error) {
         throw mapSessionStoreError(error, sessionStoreErrorMapper);

package/dist/domain/verify/competition/adapter.d.ts

@@ -1,6 +1,6 @@
 import type { CompetitionCommandAdapter } from "../../../competition/command-adapter.js";
 import { type ResolvedExtraContextFile } from "../../../competition/shared/extra-context.js";
-import type { TeardownController } from "../../../competition/shared/teardown.js";
+import { type TeardownController } from "../../../competition/shared/teardown.js";
 import type { AgentDefinition } from "../../../configs/agents/types.js";
 import type { EnvironmentConfig } from "../../../configs/environment/types.js";
 import type { VerifyProgressRenderer } from "../../../render/transcripts/verify.js";

package/dist/domain/verify/competition/adapter.js

@@ -4,15 +4,17 @@ import { detectAgentProcessFailureDetail } from "../../../agents/runtime/failure
 import { runSandboxedAgent } from "../../../agents/runtime/harness.js";
 import { stageExtraContextFiles, } from "../../../competition/shared/extra-context.js";
 import { composeStageSandboxPolicy } from "../../../competition/shared/sandbox-policy.js";
+import { registerScratchWorkspaceTeardownPaths, } from "../../../competition/shared/teardown.js";
 import { buildUnavailableTokenUsageResult, resolveTokenUsage, } from "../../../domain/shared/token-usage.js";
 import { emitStageProgressEvent } from "../../../render/transcripts/stage-progress.js";
 import { toErrorMessage } from "../../../utils/errors.js";
 import { pathExists } from "../../../utils/fs.js";
 import { prepareScratchAgentWorkspace } from "../../../workspace/agents.js";
+import { getVerificationRubricExecutionDirectoryPath, getVerificationRubricResultPath, } from "../../../workspace/artifact-paths.js";
 import { extractProviderNativeTokenUsageForSession } from "../../../workspace/chat/native-usage.js";
+import { VORATIQ_VERIFICATION_DIR } from "../../../workspace/constants.js";
 import { ensureWorkspaceDependencies } from "../../../workspace/dependencies.js";
 import { buildScopedAgentWorkspacePaths, } from "../../../workspace/layout.js";
-import { getVerificationRubricExecutionDirectoryPath, getVerificationRubricResultPath, VORATIQ_VERIFICATION_DIR, } from "../../../workspace/structure.js";
 import { verificationResultArtifactSchema, } from "../model/types.js";
 import { writeVerificationArtifact } from "./artifacts.js";
 import { assertNoVerificationIdentityLeak, assertRubricResultSelectorsMatchAliasMap, buildForbiddenVerificationIdentityTokens, parseRubricResultPayload, } from "./blinding.js";
@@ -34,7 +36,7 @@ export function createVerifyCompetitionAdapter(input) {
                     verifierId: candidate.agent.id,
                     template: candidate.template.template,
                 });
-                registerScratchWorkspaceTeardown(teardown, workspacePaths, candidate.agent.id, candidate.template.template);
+                registerScratchWorkspaceTeardownPaths(teardown, workspacePaths, `${candidate.agent.id}/${candidate.template.template}`);
                 return { candidate, workspacePaths };
             }),
             failures: [],
@@ -435,10 +437,3 @@ function compareVerificationsByTemplateThenVerifierId(left, right) {
     return (left.template.localeCompare(right.template) ||
         left.verifierId.localeCompare(right.verifierId));
 }
-function registerScratchWorkspaceTeardown(teardown, workspacePaths, verifierId, template) {
-    const labelPrefix = `${verifierId}/${template}`;
-    teardown.addPath(workspacePaths.workspacePath, `${labelPrefix} workspace`);
-    teardown.addPath(workspacePaths.contextPath, `${labelPrefix} context`);
-    teardown.addPath(workspacePaths.runtimePath, `${labelPrefix} runtime`);
-    teardown.addPath(workspacePaths.sandboxPath, `${labelPrefix} sandbox`);
-}

package/dist/domain/verify/competition/finalize.d.ts

@@ -1,5 +1,14 @@
 import type { VerificationMethodResultRef, VerificationStatus } from "../model/types.js";
 import type { ResolvedVerificationTarget } from "./target.js";
+/**
+ * Derive the session-level verification status from per-method outcomes.
+ *
+ * Session status is "succeeded" when at least one terminal method succeeds.
+ * Session status is "aborted" only when all terminal methods are aborted.
+ * Otherwise, the session is treated as "failed". When no terminal method
+ * snapshots exist yet, preserve the historical default of reporting
+ * "succeeded" rather than manufacturing a failure.
+ */
 export declare function deriveVerificationStatusFromMethods(methods: readonly VerificationMethodResultRef[]): VerificationStatus;
 export declare function maybePersistSelectedSpecPath(options: {
     root: string;

package/dist/domain/verify/competition/finalize.js

@@ -1,12 +1,31 @@
 import { loadVerificationSelectionPolicyOutput } from "../../../policy/index.js";
 import { rewriteVerificationRecord } from "../persistence/adapter.js";
+/**
+ * Derive the session-level verification status from per-method outcomes.
+ *
+ * Session status is "succeeded" when at least one terminal method succeeds.
+ * Session status is "aborted" only when all terminal methods are aborted.
+ * Otherwise, the session is treated as "failed". When no terminal method
+ * snapshots exist yet, preserve the historical default of reporting
+ * "succeeded" rather than manufacturing a failure.
+ */
 export function deriveVerificationStatusFromMethods(methods) {
-    if (methods.some((method) => method.status === "failed")) {
-        return "failed";
+    const terminalMethods = methods.filter((method) => method.status === "succeeded" ||
+        method.status === "failed" ||
+        method.status === "aborted");
+    const hasSucceeded = terminalMethods.some((method) => method.status === "succeeded");
+    if (hasSucceeded) {
+        return "succeeded";
     }
-    if (methods.some((method) => method.status === "aborted")) {
+    const hasTerminalMethods = terminalMethods.length > 0;
+    const allTerminalAborted = hasTerminalMethods &&
+        terminalMethods.every((method) => method.status === "aborted");
+    if (allTerminalAborted) {
         return "aborted";
     }
+    if (terminalMethods.some((method) => method.status === "failed")) {
+        return "failed";
+    }
     return "succeeded";
 }
 export async function maybePersistSelectedSpecPath(options) {

package/dist/domain/verify/competition/programmatic.js

@@ -5,8 +5,9 @@ import { emitStageProgressEvent } from "../../../render/transcripts/stage-progre
 import { toErrorMessage } from "../../../utils/errors.js";
 import { pathExists } from "../../../utils/fs.js";
 import { createDetachedWorktree, getGitStderr, removeWorktree, runGitCommand, } from "../../../utils/git.js";
+import { getVerificationProgrammaticResultPath } from "../../../workspace/artifact-paths.js";
+import { VORATIQ_VERIFICATION_DIR } from "../../../workspace/constants.js";
 import { buildAgentWorkspacePaths } from "../../../workspace/layout.js";
-import { getVerificationProgrammaticResultPath, VORATIQ_VERIFICATION_DIR, } from "../../../workspace/structure.js";
 import { executeProgrammaticChecks } from "../programmatic/runner.js";
 import { writeVerificationArtifact } from "./artifacts.js";
 const PROGRAMMATIC_CANDIDATE_MAX_PARALLEL = 2;

package/dist/domain/verify/competition/prompt.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { appendConstraints, appendOutputRequirements, buildWorkspaceArtifactRequirements, } from "../../../competition/shared/prompt-helpers.js";
 import { toExtraContextContextSubpath } from "../../../extra-context/contract.js";
-import { VORATIQ_VERIFICATION_DIR } from "../../../workspace/structure.js";
+import { VORATIQ_VERIFICATION_DIR } from "../../../workspace/constants.js";
 export async function loadRubricTemplate(options) {
     const { root, template } = options;
     const base = resolve(root, ".voratiq", VORATIQ_VERIFICATION_DIR, "templates", template);

package/dist/domain/verify/competition/shared-layout.js

@@ -2,9 +2,9 @@ import { copyFile, mkdir, rm, symlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative as relativePath, resolve, sep, } from "node:path";
 import { pathExists } from "../../../utils/fs.js";
 import { createDetachedWorktree, removeWorktree } from "../../../utils/git.js";
+import { MESSAGE_RESPONSE_FILENAME, VORATIQ_VERIFICATION_SESSIONS_DIR, } from "../../../workspace/constants.js";
 import { ensureWorkspaceDependencies } from "../../../workspace/dependencies.js";
 import { buildAgentWorkspacePaths, } from "../../../workspace/layout.js";
-import { MESSAGE_RESPONSE_FILENAME, VORATIQ_VERIFICATION_SESSIONS_DIR, } from "../../../workspace/structure.js";
 import { aliasForCandidate } from "./blinding.js";
 const BLINDED_VERIFY_SPEC_ARTIFACT_ALLOWLIST = [
     {

package/dist/domain/verify/model/types.d.ts

@@ -11,8 +11,8 @@ export type VerificationMethodKind = (typeof VERIFICATION_METHOD_KIND_VALUES)[nu
 export type VerificationScopeKind = (typeof VERIFICATION_SCOPE_KIND_VALUES)[number];
 export declare const verificationTargetKindSchema: z.ZodEnum<{
     message: "message";
-    reduce: "reduce";
     spec: "spec";
+    reduce: "reduce";
     run: "run";
 }>;
 export declare const verificationMethodKindSchema: z.ZodEnum<{
@@ -399,8 +399,8 @@ export declare const verificationIndexEntrySchema: z.ZodObject<{
     }>;
     targetKind: z.ZodEnum<{
         message: "message";
-        reduce: "reduce";
         spec: "spec";
+        reduce: "reduce";
         run: "run";
     }>;
     targetSessionId: z.ZodString;

package/dist/interactive/providers/launch.d.ts

@@ -6,6 +6,7 @@ export interface ProviderLaunchPreparationInput {
     agent: AgentDefinition;
     root: string;
     toolDeclarations: readonly NativeToolDeclaration[];
+    sessionScopedMcpEnv?: Record<string, string>;
     prompt?: string;
     launchMode?: "default" | "first-party";
     firstPartyMcpResolution?: FirstPartyMcpStatusAndArgs;
@@ -19,5 +20,6 @@ export interface ProviderLaunchPreparationResult {
 export declare function createBundledVoratiqToolDeclaration(options: {
     command: string;
     argsPrefix: readonly string[];
+    env?: Record<string, string>;
 }): NativeToolDeclaration;
 export declare function prepareProviderNativeLaunch(options: ProviderLaunchPreparationInput): Promise<ProviderLaunchPreparationResult>;

package/dist/interactive/providers/launch.js

@@ -10,6 +10,9 @@ export function createBundledVoratiqToolDeclaration(options) {
         name: BUNDLED_VORATIQ_TOOL_TARGET_NAME,
         command: options.command,
         args: [...options.argsPrefix, "mcp", "--stdio"],
+        ...(options.env && Object.keys(options.env).length > 0
+            ? { env: { ...options.env } }
+            : {}),
     };
 }
 export async function prepareProviderNativeLaunch(options) {
@@ -19,14 +22,18 @@ export async function prepareProviderNativeLaunch(options) {
     return await adapter.prepare(options);
 }
 function prepareCodexLaunch(options) {
-    const args = applyPositionalPrompt(applyNativeQaLaunchArgs("codex", sanitizeCodexArgs(options.agent)), options.prompt);
     const mcp = resolveFirstPartyMcpStatusAndArgs({
         launchMode: options.launchMode,
         toolDeclarations: options.toolDeclarations,
         firstPartyMcpResolution: options.firstPartyMcpResolution,
     });
+    const args = applyPositionalPrompt([
+        ...applyNativeQaLaunchArgs("codex", sanitizeCodexArgs(options.agent)),
+        ...buildCodexLaunchScopedMcpEnvArgs(options.sessionScopedMcpEnv),
+        ...mcp.additionalArgs,
+    ], options.prompt);
     return Promise.resolve({
-        args: [...args, ...mcp.additionalArgs],
+        args,
         env: {},
         toolAttachmentStatus: mcp.toolAttachmentStatus,
         artifactCaptureSupported: true,
@@ -144,6 +151,16 @@ function sanitizeGeminiArgs(agent) {
     }
     return ensureModelArg(sanitized, agent.model);
 }
+function buildCodexLaunchScopedMcpEnvArgs(env) {
+    if (!env) {
+        return [];
+    }
+    const args = [];
+    for (const [key, value] of Object.entries(env)) {
+        args.push("-c", `mcp_servers.${BUNDLED_VORATIQ_TOOL_TARGET_NAME}.env.${key}=${JSON.stringify(value)}`);
+    }
+    return args;
+}
 function ensureModelArg(argv, model) {
     const sanitized = [...argv];
     for (let index = 0; index < sanitized.length; index += 1) {

package/dist/interactive/providers/mcp.d.ts

@@ -6,6 +6,7 @@ export interface FirstPartyMcpStatusAndArgs {
 }
 export declare function resolveFirstPartyMcpStatus(options: {
     providerId: FirstPartyProviderId;
+    providerBinary?: string;
     root: string;
     toolDeclarations: readonly NativeToolDeclaration[];
     promptForMcpInstall?: PromptForMcpInstall;

package/dist/interactive/providers/mcp.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { basename } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { loadRepoSettings } from "../../configs/settings/loader.js";
 import { BUNDLED_VORATIQ_TOOL_TARGET_NAME, } from "./shared.js";
@@ -44,9 +45,11 @@ export async function resolveFirstPartyMcpStatus(options) {
     }
     const runCommand = options.mcpCommandRunner ?? runProviderMcpCommand;
     const adapter = firstPartyMcpAdapters[options.providerId];
+    const providerBinary = resolveProviderBinary(options.providerBinary, adapter.providerCommand);
     const initialInspection = summarizeFirstPartyMcpInspection({
         toolDeclarations: options.toolDeclarations,
         inspections: await adapter.inspectTools({
+            providerBinary,
             root: options.root,
             toolDeclarations: options.toolDeclarations,
             runCommand,
@@ -84,12 +87,14 @@ export async function resolveFirstPartyMcpStatus(options) {
     }
     await installVoratiqMcpForProvider({
         adapter,
+        providerBinary,
         root: options.root,
         toolDeclarations: initialInspection.missingToolDeclarations,
         runCommand,
     });
     const verifiedInspection = await verifyFirstPartyMcpStatus({
         adapter,
+        providerBinary,
         root: options.root,
         toolDeclarations: options.toolDeclarations,
         runCommand,
@@ -141,6 +146,7 @@ async function verifyFirstPartyMcpStatus(options) {
         lastSummary = summarizeFirstPartyMcpInspection({
             toolDeclarations: options.toolDeclarations,
             inspections: await options.adapter.inspectTools({
+                providerBinary: options.providerBinary,
                 root: options.root,
                 toolDeclarations: options.toolDeclarations,
                 runCommand: options.runCommand,
@@ -176,7 +182,7 @@ async function inspectGeminiMcpTools(options) {
         return inspections;
     }
     const result = await options.runCommand({
-        command: "gemini",
+        command: options.providerBinary,
         args: ["mcp", "list"],
         cwd: options.root,
     });
@@ -203,6 +209,7 @@ async function inspectCliMcpToolsViaGet(options) {
     const inspections = new Map();
     for (const tool of options.toolDeclarations) {
         inspections.set(tool.name, await inspectCliMcpTool({
+            providerBinary: options.providerBinary,
             providerCommand: options.providerCommand,
             root: options.root,
             declaration: tool,
@@ -213,6 +220,7 @@ async function inspectCliMcpToolsViaGet(options) {
 }
 async function inspectCodexMcpTools(options) {
     return await inspectCliMcpToolsViaGet({
+        providerBinary: options.providerBinary,
         providerCommand: "codex",
         root: options.root,
         toolDeclarations: options.toolDeclarations,
@@ -221,6 +229,7 @@ async function inspectCodexMcpTools(options) {
 }
 async function inspectClaudeMcpTools(options) {
     return await inspectCliMcpToolsViaGet({
+        providerBinary: options.providerBinary,
         providerCommand: "claude",
         root: options.root,
         toolDeclarations: options.toolDeclarations,
@@ -230,7 +239,7 @@ async function inspectClaudeMcpTools(options) {
 async function inspectCliMcpTool(options) {
     if (options.providerCommand === "codex") {
         const result = await options.runCommand({
-            command: "codex",
+            command: options.providerBinary,
             args: ["mcp", "get", "--json", options.declaration.name],
             cwd: options.root,
         });
@@ -260,7 +269,7 @@ async function inspectCliMcpTool(options) {
             };
     }
     const result = await options.runCommand({
-        command: "claude",
+        command: options.providerBinary,
         args: ["mcp", "get", options.declaration.name],
         cwd: options.root,
     });
@@ -345,11 +354,11 @@ function normalizeStringArray(value) {
     return [...value];
 }
 function matchesDeclarationCommandAndArgs(declaration, value) {
-    if (value.command !== declaration.command) {
+    const expectedArgs = declaration.args ? [...declaration.args] : [];
+    if (!areStringArraysEqual(value.args, expectedArgs)) {
         return false;
     }
-    const expectedArgs = declaration.args ? [...declaration.args] : [];
-    return areStringArraysEqual(value.args, expectedArgs);
+    return areEquivalentMcpCommands(value.command, declaration.command);
 }
 function areStringArraysEqual(left, right) {
     if (left.length !== right.length) {
@@ -362,6 +371,16 @@ function areStringArraysEqual(left, right) {
     }
     return true;
 }
+function areEquivalentMcpCommands(left, right) {
+    if (left === right) {
+        return true;
+    }
+    return isNodeExecutableCommand(left) && isNodeExecutableCommand(right);
+}
+function isNodeExecutableCommand(value) {
+    const normalized = basename(value).toLowerCase();
+    return normalized === "node" || normalized === "node.exe";
+}
 function buildCommandMismatchDetail(declaration, actual) {
     return [
         `Expected \`${formatCommandAndArgs(declaration.command, declaration.args ?? [])}\`,`,
@@ -425,7 +444,7 @@ function splitCommandLine(value) {
 async function installVoratiqMcpForProvider(options) {
     for (const toolDeclaration of options.toolDeclarations) {
         const result = await options.runCommand({
-            command: options.adapter.providerCommand,
+            command: options.providerBinary,
             args: options.adapter.buildAddArgs(toolDeclaration),
             cwd: options.root,
         });
@@ -535,7 +554,22 @@ async function runProviderMcpCommand(input) {
         stderr += chunk;
     });
     const exitCode = await new Promise((resolve) => {
+        let settled = false;
+        child.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (stderr.trim().length === 0) {
+                stderr = error.message;
+            }
+            resolve(null);
+        });
         child.on("close", (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
             resolve(typeof code === "number" ? code : null);
         });
     });
@@ -545,3 +579,7 @@ async function runProviderMcpCommand(input) {
         stderr,
     };
 }
+function resolveProviderBinary(candidate, fallback) {
+    const normalized = candidate?.trim();
+    return normalized && normalized.length > 0 ? normalized : fallback;
+}