@wix/pathgrade 1.0.24 → 1.0.26

package/dist/internal/direct-mcp-v2/cleanup.js

@@ -0,0 +1,182 @@
+import { lstat, opendir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { removeSandboxRoot } from '../../providers/sandbox-lifecycle.js';
+export async function persistTrialArtifact(path, content, phase) {
+    const pending = `${path}.pending`;
+    const destination = phase === 'provisional' ? pending : path;
+    const temporary = `${destination}.${process.pid}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode: 0o600 });
+        await rename(temporary, destination);
+        if (phase === 'final')
+            await rm(pending, { force: true });
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        if (phase === 'final')
+            await rm(pending, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export class TrialResourceRegistry {
+    resources = new Map();
+    register(resource) {
+        if (this.resources.has(resource.opaqueId))
+            throw new Error(`duplicate resource ID ${resource.opaqueId}`);
+        this.resources.set(resource.opaqueId, resource);
+    }
+    entries() { return [...this.resources.values()]; }
+}
+function within(root, path) {
+    const difference = relative(root, path);
+    return difference === '' || (!difference.startsWith('..') && !isAbsolute(difference));
+}
+export async function scanBearerSurfaces(roots, bearer) {
+    if (bearer.length === 0)
+        throw new Error('bearer must be non-empty');
+    const entries = [];
+    for (const declaredRoot of roots) {
+        try {
+            const root = await realpath(declaredRoot);
+            const pending = [root];
+            const visited = new Set();
+            while (pending.length > 0) {
+                const path = pending.pop();
+                try {
+                    const stat = await lstat(path);
+                    if (stat.isSymbolicLink()) {
+                        const target = await realpath(path);
+                        if (!within(root, target))
+                            entries.push({ path, status: 'clean', reason: 'symlink target outside approved root was not followed' });
+                        else if (!visited.has(target))
+                            pending.push(target);
+                    }
+                    else if (stat.isDirectory()) {
+                        const canonicalPath = await realpath(path);
+                        if (visited.has(canonicalPath))
+                            continue;
+                        visited.add(canonicalPath);
+                        const directory = await opendir(path);
+                        for await (const entry of directory)
+                            pending.push(resolve(path, entry.name));
+                    }
+                    else if (stat.isFile()) {
+                        const content = await readFile(path);
+                        entries.push({ path, status: content.includes(Buffer.from(bearer)) ? 'bearer-found' : 'clean' });
+                    }
+                    else
+                        entries.push({ path, status: 'skipped', reason: 'not a regular file, directory, or symlink' });
+                }
+                catch (error) {
+                    entries.push({ path, status: 'unreadable', reason: error instanceof Error ? error.message : String(error) });
+                }
+            }
+        }
+        catch (error) {
+            entries.push({ path: declaredRoot, status: 'unreadable', reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return entries.sort((left, right) => left.path.localeCompare(right.path, 'en'));
+}
+export async function cleanupTrial(options) {
+    const released = [];
+    const failures = [];
+    for (const resource of [...options.registry.entries()].reverse()) {
+        try {
+            await resource.close();
+            if (resource.isOpen())
+                throw new Error('resource remained open after close');
+            released.push(resource.opaqueId);
+        }
+        catch (error) {
+            failures.push({ opaqueId: resource.opaqueId, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const scans = await scanBearerSurfaces(options.scanRoots, options.bearer);
+    const bearerFound = scans.some((entry) => entry.status === 'bearer-found');
+    if (scans.some((entry) => entry.status === 'unreadable' || entry.status === 'skipped'))
+        failures.push({ opaqueId: 'surface-scan', reason: 'scan was incomplete' });
+    if (bearerFound)
+        failures.push({ opaqueId: 'surface-scan', reason: 'bearer found in writable surface' });
+    const report = { scans, released: released.sort(), failures, scratchDeleted: false, bearerFound };
+    if (!bearerFound) {
+        try {
+            await options.persistRedacted(report, 'provisional');
+        }
+        catch (error) {
+            failures.push({ opaqueId: 'artifact-persistence', reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    else
+        failures.push({ opaqueId: 'artifact-persistence', reason: 'persistence refused because bearer remained' });
+    options.zeroBearer?.();
+    try {
+        const parent = await realpath(options.approvedScratchParent);
+        const scratch = await realpath(options.scratchPath);
+        if (scratch === parent || !within(parent, scratch))
+            throw new Error('scratch path is outside its approved parent');
+        await (options.removeScratch ?? removeSandboxRoot)(scratch);
+        report.scratchDeleted = true;
+    }
+    catch (error) {
+        failures.push({ opaqueId: 'scratch', reason: error instanceof Error ? error.message : String(error) });
+    }
+    if (!bearerFound) {
+        try {
+            await options.persistRedacted(report, 'final');
+        }
+        catch (error) {
+            failures.push({ opaqueId: 'artifact-finalization', reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return report;
+}
+export class IdempotentTrialCleaner {
+    options;
+    result;
+    constructor(options) {
+        this.options = options;
+    }
+    dispose() {
+        this.result ??= cleanupTrial(this.options);
+        return this.result;
+    }
+}
+export class TrialExecutionError extends Error {
+    constructor(message, options) {
+        super(message, { cause: options.primary });
+        this.name = 'TrialExecutionError';
+        this.secondary = options.secondary;
+    }
+    secondary;
+}
+export async function runWithUnconditionalSettlement(options) {
+    let providerResult;
+    let providerError;
+    const secondary = [];
+    try {
+        providerResult = await options.sendTurn();
+    }
+    catch (error) {
+        providerError = error;
+    }
+    finally {
+        try {
+            await options.finalize({ providerResult, providerError, cancellationRequested: options.cancellationRequested ?? false });
+        }
+        catch (error) {
+            secondary.push(error);
+        }
+        try {
+            await options.cleanup();
+        }
+        catch (error) {
+            secondary.push(error);
+        }
+    }
+    if (providerError !== undefined || secondary.length > 0) {
+        throw new TrialExecutionError(providerError instanceof Error ? providerError.message : 'trial settlement failed', { primary: providerError, secondary });
+    }
+    // SAFETY: reaching this line proves sendTurn resolved and neither it nor settlement recorded an error.
+    return providerResult;
+}

package/dist/internal/direct-mcp-v2/codex-direct-mcp.d.ts

@@ -0,0 +1,41 @@
+import { type CleanupReport } from './cleanup.js';
+import { type AppServerSessionHandle } from '../../agents/codex-app-server/transport.js';
+import type { EvidenceEnvelope, ScenarioArtifact, ScenarioMachineV2 } from './types.js';
+export declare const CODEX_DIRECT_MCP_FLAG = "PATHGRADE_INTERNAL_CODEX_DIRECT_MCP_V2";
+export type CodexDirectMcpChecks = {
+    runtimeAdmitted: boolean;
+    secretFreeProject: boolean;
+    directCall: boolean;
+    structuredToolError: boolean;
+    fencedCancellation: boolean;
+    providerTerminal: boolean;
+    hostQuiescent: boolean;
+    postCancelReuse: boolean;
+    privateReplay: boolean;
+    cleanup: boolean;
+};
+export type CodexDirectMcpTrialResult = {
+    selected: true;
+    profileFingerprint: string;
+    artifact: ScenarioArtifact;
+    evidence: readonly EvidenceEnvelope[];
+    checks: CodexDirectMcpChecks;
+    cleanup: CleanupReport;
+    cancellationStatus: string;
+};
+export declare function isCodexDirectMcpSelected(environment?: NodeJS.ProcessEnv): boolean;
+export declare function codexDirectMcpDisableReason(): string | undefined;
+/** Test-only reset for proving the fail-closed process latch. */
+export declare function __resetCodexDirectMcpDisablementForTesting(): void;
+export declare function runCodexDirectMcpTrial(options: {
+    scenario: ScenarioMachineV2;
+    environment?: NodeJS.ProcessEnv;
+    model?: string;
+    artifactDirectory?: string;
+    createControlPlane?: (context: {
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+        binary: string;
+    }) => AppServerSessionHandle;
+}): Promise<CodexDirectMcpTrialResult>;
+export declare function mapCodexProviderEnvironment(environment: NodeJS.ProcessEnv, codexHome: string): NodeJS.ProcessEnv;

package/dist/internal/direct-mcp-v2/codex-direct-mcp.js

@@ -0,0 +1,436 @@
+import { copyFile, mkdir, mkdtemp, realpath, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { compileScenario } from './compiler.js';
+import { IdempotentTrialCleaner, persistTrialArtifact, TrialExecutionError, TrialResourceRegistry } from './cleanup.js';
+import { PrivateReplayVault, replayPrivateEvidence, verifyEvidenceChain } from './evidence.js';
+import { ScenarioHostReducer } from './host-reducer.js';
+import { materializeProjection } from './materialize.js';
+import { projectEndpoints } from './projection.js';
+import { admitRuntimeProfile } from './runtime-profile.js';
+import { CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE, CODEX_DIRECT_MCP_NORMALIZED_HANDSHAKE } from './codex-profile.js';
+import { createInvocationBarrier, startScenarioHttpHost } from './scenario-http-host.js';
+import { spawnAppServerTransport } from '../../agents/codex-app-server/transport.js';
+import { mergeCodexScenarioConfigs } from '../../agents/codex-app-server/scenario-mount.js';
+export const CODEX_DIRECT_MCP_FLAG = 'PATHGRADE_INTERNAL_CODEX_DIRECT_MCP_V2';
+const disabledProfiles = new Map();
+export function isCodexDirectMcpSelected(environment = process.env) {
+    const fingerprint = CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.profileFingerprint;
+    return environment[CODEX_DIRECT_MCP_FLAG] === '1' && !disabledProfiles.has(fingerprint);
+}
+export function codexDirectMcpDisableReason() {
+    return disabledProfiles.get(CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.profileFingerprint);
+}
+/** Test-only reset for proving the fail-closed process latch. */
+// oxlint-disable-next-line inhuman/no-empty-wrappers -- This test seam exposes Map.clear without exposing mutable production state.
+export function __resetCodexDirectMcpDisablementForTesting() {
+    disabledProfiles.clear();
+}
+export async function runCodexDirectMcpTrial(options) {
+    const environment = options.environment ?? process.env;
+    const profile = CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE;
+    if (!isCodexDirectMcpSelected(environment)) {
+        const reason = disabledProfiles.get(profile.profileFingerprint);
+        throw new Error(reason ? `Codex direct MCP disabled for admitted profile: ${reason}` : `${CODEX_DIRECT_MCP_FLAG} is disabled`);
+    }
+    try {
+        return await executeTrial({ ...options, environment });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        disabledProfiles.set(profile.profileFingerprint, reason.slice(0, 500));
+        throw error;
+    }
+}
+async function executeTrial(options) {
+    const compiled = compileScenario(options.scenario);
+    if (!compiled.ok)
+        throw new Error(`Scenario compilation failed: ${JSON.stringify(compiled.diagnostics)}`);
+    const profile = CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE;
+    const barrierCase = findEffectfulSuccessCase(compiled.artifact);
+    const createdScratchParent = await mkdtemp(join(tmpdir(), 'pathgrade-codex-direct-mcp-'));
+    let scratchParent;
+    try {
+        scratchParent = await realpath(createdScratchParent);
+    }
+    catch (error) {
+        await rm(createdScratchParent, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    const scratchPath = join(scratchParent, 'trial');
+    const workspacePath = join(scratchPath, 'workspace');
+    const codexHome = join(scratchPath, 'codex-home');
+    try {
+        await mkdir(workspacePath, { recursive: true });
+        await mkdir(codexHome, { recursive: true });
+    }
+    catch (error) {
+        await rm(scratchParent, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    const trialId = `codex-${randomBytes(12).toString('hex')}`;
+    const macKey = randomBytes(32);
+    const replayVault = new PrivateReplayVault(randomBytes(32));
+    const reducer = new ScenarioHostReducer(trialId, compiled.artifact, macKey, replayVault);
+    reducer.markCompiled();
+    const barrier = createInvocationBarrier(barrierCase.caseId);
+    const host = await startScenarioHttpHost({ artifact: compiled.artifact, reducer, barrier }).catch(async (error) => {
+        macKey.fill(0);
+        replayVault.dispose();
+        reducer.dispose();
+        await rm(scratchParent, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    });
+    const registry = new TrialResourceRegistry();
+    let handle;
+    let transport;
+    let hostOpen = true;
+    let controlPlaneOpen = false;
+    let hostQuiescentBeforeCleanup = false;
+    registry.register({ opaqueId: 'scenario-host', kind: 'listener', close: async () => { await host.dispose(); hostOpen = false; }, isOpen: () => hostOpen });
+    registry.register({ opaqueId: 'scenario-transports', kind: 'transport', close: () => host.dispose(), isOpen: () => host.activeTransportCount() !== 0 });
+    let persisted = false;
+    const artifactDirectory = options.artifactDirectory;
+    const cleaner = new IdempotentTrialCleaner({
+        registry,
+        scanRoots: [workspacePath, codexHome],
+        scratchPath,
+        approvedScratchParent: scratchParent,
+        bearer: host.bearer.toString(),
+        persistRedacted: async (report, phase) => {
+            if (!artifactDirectory) {
+                if (phase === 'final')
+                    persisted = true;
+                return;
+            }
+            const path = join(artifactDirectory, 'trial-evidence.json');
+            await mkdir(dirname(path), { recursive: true });
+            const value = { artifactDigest: compiled.artifact.artifactDigest, evidence: reducer.ledger.events(), cleanup: { ...report, scans: report.scans.map((entry) => ({ ...entry, path: entry.path.replace(scratchParent, '<scratch>') })) } };
+            await persistTrialArtifact(path, `${JSON.stringify(value)}\n`, phase);
+            if (phase === 'final')
+                persisted = true;
+        },
+        zeroBearer: () => { host.bearer.fill(0); macKey.fill(0); replayVault.dispose(); },
+    });
+    try {
+        const runtimeEnv = await prepareCodexEnvironment(options.environment, codexHome);
+        const admission = await admitRuntimeProfile(profile, {
+            provider: 'codex',
+            platform: process.platform,
+            architecture: process.arch,
+            environment: runtimeEnv,
+            forbiddenSecrets: [host.bearer.toString(), `Bearer ${host.bearer.toString()}`],
+            initializeControlPlane: async () => {
+                handle = options.createControlPlane?.({ cwd: workspacePath, env: runtimeEnv, binary: profile.command.absolutePath })
+                    ?? spawnAppServerTransport({
+                        binary: profile.command.absolutePath,
+                        args: profile.command.args,
+                        cwd: workspacePath,
+                        env: runtimeEnv,
+                        logStderrOnExit: false,
+                    });
+                controlPlaneOpen = true;
+                transport = handle.transport;
+                try {
+                    const initialized = await transport.sendRequest('initialize', {
+                        clientInfo: { name: 'pathgrade-direct-mcp', version: '2.0.0', title: null },
+                        capabilities: { experimentalApi: true, optOutNotificationMethods: null },
+                    });
+                    const admittedVersion = profile.expectedVersion.replace(/^codex-cli\s+/, '');
+                    if (!initialized.userAgent?.includes(admittedVersion))
+                        throw new Error('Codex initialize userAgent did not match admitted version');
+                    transport.sendNotification('initialized', null);
+                    return {
+                        normalizedHandshake: CODEX_DIRECT_MCP_NORMALIZED_HANDSHAKE,
+                        capabilities: profile.requiredCapabilities,
+                        close: async () => { await handle?.close(); controlPlaneOpen = false; },
+                    };
+                }
+                catch (error) {
+                    await handle.close().catch(() => undefined);
+                    controlPlaneOpen = false;
+                    throw error;
+                }
+            },
+        });
+        if (!admission.ok || !transport || !handle) {
+            throw new Error(`RUNTIME_NOT_ADMITTED: ${admission.ok ? 'control plane unavailable' : admission.reason}`);
+        }
+        const admittedTransport = transport;
+        const admittedHandle = handle;
+        registry.register({ opaqueId: 'codex-app-server', kind: 'process', close: async () => { await admittedHandle.close(); controlPlaneOpen = false; }, isOpen: () => controlPlaneOpen });
+        reducer.markAdmitted();
+        const projected = projectEndpoints(host.endpoints, admission.profile);
+        if (!Array.isArray(projected))
+            throw new Error(`Projection rejected: ${projected.reason}`);
+        const configs = projected.map((plan) => materializeProjection(plan, {
+            resolve(secretRef) {
+                if (secretRef !== host.secretRef)
+                    throw new Error(`Unknown secret reference: ${secretRef}`);
+                return `Bearer ${host.bearer.toString()}`;
+            },
+        }));
+        const mcpConfig = mergeCodexScenarioConfigs(configs);
+        reducer.markReady();
+        const started = await admittedTransport.sendRequest('thread/start', {
+            cwd: workspacePath,
+            approvalPolicy: 'never',
+            sandbox: 'read-only',
+            ephemeral: true,
+            model: options.model ?? options.environment.PATHGRADE_DIRECT_MCP_CODEX_MODEL ?? 'gpt-5.6-luna',
+            config: mcpConfig,
+        });
+        const threadId = started.thread.id;
+        const serverId = host.endpoints[0]?.serverId;
+        if (!serverId)
+            throw new Error('Scenario produced no Codex MCP endpoint');
+        reducer.beginTurn('direct-call', 'codex');
+        const directResult = await admittedTransport.sendRequest('mcpServer/tool/call', {
+            threadId, server: serverId, tool: barrierCase.pureToolId, arguments: barrierCase.pureArgs,
+            meta: { source: 'pathgrade-direct-mcp-contract' },
+        });
+        if (directResult.isError === true)
+            throw new Error('Direct MCP success call returned isError');
+        reducer.finalize('settled');
+        reducer.beginTurn('structured-error', 'codex');
+        const errorResult = await admittedTransport.sendRequest('mcpServer/tool/call', {
+            threadId, server: serverId, tool: barrierCase.effectfulToolId, arguments: barrierCase.errorArgs,
+            meta: { source: 'pathgrade-direct-mcp-contract' },
+        });
+        if (errorResult.isError !== true || !errorResult.structuredContent?.pathgrade?.code)
+            throw new Error('Codex did not preserve the structured scenario tool error');
+        reducer.finalize('settled');
+        reducer.beginTurn('cancelled-turn', 'codex');
+        const providerSignals = [];
+        const turnCompletions = createTurnCompletionMonitor(admittedTransport);
+        const stopCollectingSignals = admittedTransport.onNotification((notification) => {
+            // SAFETY: only optional diagnostic fields are read from the exact-pinned Codex notification schema.
+            const params = notification.params;
+            if (notification.method === 'item/completed')
+                providerSignals.push(`item:${params?.item?.type ?? 'unknown'}:${params?.item?.status ?? 'unknown'}:${params?.item?.server ?? ''}:${params?.item?.tool ?? ''}`);
+            if (notification.method === 'turn/completed')
+                providerSignals.push(`turn:${params?.turn?.status ?? params?.status ?? 'unknown'}`);
+            if (notification.method === 'mcpServer/startupStatus/updated')
+                providerSignals.push(`startup:${params?.name ?? 'unknown'}:${params?.status ?? 'unknown'}:${params?.error ? 'error' : 'clean'}`);
+        });
+        let observingProvider = true;
+        registry.register({
+            opaqueId: 'codex-provider-observers',
+            kind: 'descriptor',
+            close: async () => {
+                if (!observingProvider)
+                    return;
+                stopCollectingSignals();
+                turnCompletions.dispose();
+                observingProvider = false;
+            },
+            isOpen: () => observingProvider,
+        });
+        const turnStarted = await admittedTransport.sendRequest('turn/start', {
+            threadId,
+            input: [{
+                    type: 'text',
+                    text: `Mandatory contract action: invoke the ${serverId}.${barrierCase.effectfulToolId} MCP tool exactly once with arguments ${JSON.stringify(barrierCase.successArgs)}. Do not answer with text before the tool finishes, do not call another tool, and do not use shell commands or edit files. A response without this MCP invocation is invalid.`,
+                    text_elements: [],
+                }],
+        });
+        const turnId = turnStarted.turn?.id ?? turnStarted.turnId;
+        if (!turnId)
+            throw new Error('Codex turn/start returned no turn id');
+        const terminal = turnCompletions.waitFor(turnId, 120_000);
+        const entered = await withTimeout(Promise.race([
+            barrier.reached().then(() => 'barrier'),
+            terminal.then((status) => `terminal:${status}`),
+        ]), 90_000, 'Codex produced neither a blocking MCP invocation nor a terminal');
+        if (entered !== 'barrier')
+            throw new Error(`Codex reached ${entered} before the blocking MCP transition (${providerSignals.join(',')})`);
+        reducer.fence();
+        await withTimeout(admittedTransport.sendRequest('turn/interrupt', { threadId, turnId }), 15_000, 'Timed out sending Codex turn interrupt');
+        reducer.abortUncommitted('provider-cancelled');
+        barrier.release();
+        const [cancellationStatus] = await Promise.all([terminal, host.waitForQuiescence(30_000)]);
+        hostQuiescentBeforeCleanup = host.activeTransportCount() === 0;
+        if (!hostQuiescentBeforeCleanup)
+            throw new Error('Scenario host was not quiescent after cancellation');
+        stopCollectingSignals();
+        turnCompletions.dispose();
+        observingProvider = false;
+        reducer.observeProviderTerminal();
+        if (cancellationStatus !== 'interrupted')
+            throw new Error(`Codex cancellation terminal was ${cancellationStatus}`);
+        reducer.finalize('cancelled-clean');
+        reducer.beginTurn('post-cancel-reuse', 'codex');
+        const reused = await admittedTransport.sendRequest('mcpServer/tool/call', {
+            threadId, server: serverId, tool: barrierCase.effectfulToolId, arguments: barrierCase.successArgs,
+            meta: { source: 'pathgrade-direct-mcp-contract' },
+        });
+        if (reused.isError === true)
+            throw new Error('Post-cancel direct MCP reuse failed');
+        reducer.finalize('settled');
+        const replay = replayPrivateEvidence({ artifact: compiled.artifact, evidence: reducer.ledger.events(), vault: replayVault, macKey });
+        if (!replay.ok || replay.poisoned || replay.finalState !== reducer.state)
+            throw new Error(`Private replay failed: ${replay.ok ? 'state mismatch' : replay.reason}`);
+        const chain = verifyEvidenceChain(reducer.ledger.events(), compiled.artifact.artifactDigest);
+        if (!chain.ok)
+            throw new Error(`Evidence chain failed: ${chain.reason}`);
+        reducer.dispose();
+        const cleanup = await cleaner.dispose();
+        await rm(scratchParent, { recursive: true, force: true });
+        if (!persisted || cleanup.failures.length > 0 || cleanup.bearerFound || !cleanup.scratchDeleted)
+            throw new Error(`CLEANUP_FAILED: ${JSON.stringify(cleanup.failures)}`);
+        return {
+            selected: true,
+            profileFingerprint: profile.profileFingerprint,
+            artifact: compiled.artifact,
+            evidence: reducer.ledger.events(),
+            checks: {
+                runtimeAdmitted: true,
+                secretFreeProject: true,
+                directCall: true,
+                structuredToolError: true,
+                fencedCancellation: true,
+                providerTerminal: true,
+                hostQuiescent: hostQuiescentBeforeCleanup,
+                postCancelReuse: true,
+                privateReplay: true,
+                cleanup: true,
+            },
+            cleanup,
+            cancellationStatus,
+        };
+    }
+    catch (error) {
+        barrier.release();
+        try {
+            if (reducer.phase === 'ACTIVE')
+                reducer.fence();
+            if (reducer.phase === 'FENCING')
+                reducer.abortUncommitted('trial-failed');
+            if (reducer.phase !== 'DISPOSED' && reducer.phase !== 'NEW' && reducer.phase !== 'COMPILED' && reducer.phase !== 'ADMITTED')
+                reducer.finalize('poisoned', 'trial-failed');
+        }
+        catch (lifecycleFailure) {
+            // Preserve the primary failure; the cleaner reports any remaining resources.
+            void lifecycleFailure;
+        }
+        reducer.dispose();
+        let cleanupError;
+        try {
+            const report = await cleaner.dispose();
+            if (report.failures.length > 0 || report.bearerFound || !report.scratchDeleted)
+                cleanupError = new Error(`CLEANUP_FAILED: ${JSON.stringify(report.failures)}`);
+        }
+        catch (failure) {
+            cleanupError = failure instanceof Error ? failure : new Error(String(failure));
+        }
+        await rm(scratchParent, { recursive: true, force: true }).catch(() => undefined);
+        if (cleanupError)
+            throw new TrialExecutionError(error instanceof Error ? error.message : 'Codex direct MCP trial failed', { primary: error, secondary: [cleanupError] });
+        throw error;
+    }
+}
+async function prepareCodexEnvironment(environment, codexHome) {
+    const result = mapCodexProviderEnvironment(environment, codexHome);
+    if (!result.OPENAI_API_KEY) {
+        const source = join(environment.CODEX_HOME || join(homedir(), '.codex'), 'auth.json');
+        const destination = join(codexHome, 'auth.json');
+        try {
+            await copyFile(source, destination);
+        }
+        catch (error) {
+            throw new Error(`Codex live cancellation requires OPENAI_API_KEY or readable managed auth at ${source}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return result;
+}
+export function mapCodexProviderEnvironment(environment, codexHome) {
+    const { APP_OPENAI_API_KEY: appApiKey, APP_OPENAI_BASE_URL: appBaseUrl, ...providerEnvironment } = environment;
+    const result = { ...providerEnvironment, CODEX_HOME: codexHome };
+    const apiKey = environment.OPENAI_API_KEY ?? appApiKey;
+    const baseUrl = environment.OPENAI_BASE_URL ?? appBaseUrl;
+    if (apiKey)
+        result.OPENAI_API_KEY = apiKey;
+    if (baseUrl)
+        result.OPENAI_BASE_URL = baseUrl;
+    return result;
+}
+function findEffectfulSuccessCase(artifact) {
+    const state = artifact.canonicalIr.states[artifact.canonicalIr.initialState];
+    const entries = Object.entries(state.tools);
+    const effectful = entries.find(([, tool]) => tool.effectful && tool.cases.some((entry) => entry.outcome.kind === 'success' && 'exactArgs' in entry.when && entry.transition));
+    const error = entries.find(([, tool]) => tool.cases.some((entry) => entry.outcome.kind === 'tool-error' && 'exactArgs' in entry.when));
+    const pure = entries.find(([, tool]) => !tool.effectful && tool.cases.some((entry) => entry.outcome.kind === 'success' && 'exactArgs' in entry.when || 'all' in entry.when));
+    if (!effectful || !error || !pure)
+        throw new Error('Codex vertical requires an effectful success, structured error, and pure success in the initial state');
+    const successCase = effectful[1].cases.find((entry) => entry.outcome.kind === 'success' && 'exactArgs' in entry.when && entry.transition);
+    const errorCase = error[1].cases.find((entry) => entry.outcome.kind === 'tool-error' && 'exactArgs' in entry.when);
+    const pureCase = pure[1].cases.find((entry) => entry.outcome.kind === 'success');
+    return {
+        caseId: successCase.id,
+        effectfulToolId: effectful[0].split('/')[1],
+        pureToolId: pure[0].split('/')[1],
+        successArgs: 'exactArgs' in successCase.when ? successCase.when.exactArgs : {},
+        errorArgs: 'exactArgs' in errorCase.when ? errorCase.when.exactArgs : {},
+        pureArgs: 'exactArgs' in pureCase.when ? pureCase.when.exactArgs : deriveArgs(pureCase.when.all),
+    };
+}
+function deriveArgs(predicates) {
+    const result = {};
+    for (const predicate of predicates) {
+        if (predicate.pointer.startsWith('/') && 'equals' in predicate)
+            result[predicate.pointer.slice(1)] = predicate.equals;
+    }
+    return result;
+}
+function createTurnCompletionMonitor(transport) {
+    const completed = new Map();
+    const waiters = new Map();
+    const off = transport.onNotification((notification) => {
+        if (notification.method !== 'turn/completed')
+            return;
+        // SAFETY: the exact-pinned Codex schema permits nested and legacy flattened terminal fields.
+        const params = notification.params;
+        const turnId = params?.turn?.id ?? params?.turnId;
+        if (!turnId)
+            return;
+        const status = params?.turn?.status ?? params?.status ?? 'unknown';
+        const waiter = waiters.get(turnId);
+        if (waiter) {
+            waiters.delete(turnId);
+            clearTimeout(waiter.timer);
+            waiter.resolve(status);
+        }
+        else
+            completed.set(turnId, status);
+    });
+    return {
+        waitFor(turnId, timeoutMs) {
+            const status = completed.get(turnId);
+            if (status !== undefined) {
+                completed.delete(turnId);
+                return Promise.resolve(status);
+            }
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    waiters.delete(turnId);
+                    reject(new Error('Timed out waiting for Codex turn terminal'));
+                }, timeoutMs);
+                waiters.set(turnId, { resolve, timer });
+            });
+        },
+        dispose() {
+            off();
+            completed.clear();
+            for (const waiter of waiters.values())
+                clearTimeout(waiter.timer);
+            waiters.clear();
+        },
+    };
+}
+async function withTimeout(promise, timeoutMs, message) {
+    let timer;
+    return Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), timeoutMs); })])
+        .finally(() => { if (timer)
+        clearTimeout(timer); });
+}

package/dist/internal/direct-mcp-v2/codex-profile.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeLock } from './runtime-lock.js';
+import type { JsonObject, RuntimeCapabilityProfile } from './types.js';
+export declare const CODEX_DIRECT_MCP_NORMALIZED_HANDSHAKE: JsonObject;
+/** Reviewed macOS arm64 pin captured by RFC 0006. Other platforms fail closed. */
+export declare const CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE: RuntimeCapabilityProfile;
+/** Code-owned relocatable identity lock for the admitted public Codex slice. */
+export declare const CODEX_DIRECT_MCP_DARWIN_ARM64_LOCK: RuntimeLock;
+/**
+ * Resolve one Codex candidate before admission. Selection is deterministic;
+ * identity failure never falls through to another process.
+ */
+export declare function resolveCodexScenarioExecutable(environment: Readonly<Record<string, string | undefined>>): Promise<string>;