@wix/pathgrade 1.0.25 → 1.0.27

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>;

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

@@ -0,0 +1,81 @@
+import { access, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+export const CODEX_DIRECT_MCP_NORMALIZED_HANDSHAKE = {
+    normalizerVersion: 1,
+    provider: 'codex',
+    controlPlane: 'app-server',
+    streamableHttp: true,
+    controlPlaneHeaders: true,
+    cancellation: 'turn-interrupt',
+    protocolMethods: ['mcpServer/tool/call', 'thread/start', 'turn/interrupt'],
+};
+/** Reviewed macOS arm64 pin captured by RFC 0006. Other platforms fail closed. */
+export const CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE = {
+    format: 'pathgrade-direct-mcp-runtime-profile-v1',
+    provider: 'codex',
+    platform: 'darwin',
+    architecture: 'arm64',
+    controlPlane: 'app-server',
+    command: {
+        absolutePath: '/Applications/ChatGPT.app/Contents/Resources/codex',
+        args: [],
+        versionArgs: ['--version'],
+    },
+    expectedVersion: 'codex-cli 0.151.0-alpha.7.1',
+    artifacts: [{
+            label: 'codex-cli-0.151.0-alpha.7.1',
+            absolutePath: '/Applications/ChatGPT.app/Contents/Resources/codex',
+            sha256: 'a5976fd714dc0801a6f40e0e2b3051f64f1e0468f6c0f279b7d2a7afb7623f43',
+        }],
+    requiredCapabilities: {
+        streamableHttp: true,
+        controlPlaneHeaders: true,
+        cancellation: 'turn-interrupt',
+    },
+    profileFingerprint: '79ed563e36c65404b385e2a8ebd1c02e33e4c6f86dac589a94b32d4a0cf7f169',
+    runtimeCapabilityFingerprint: '2ea3ca12b39fb6de97464ab539be3986d5fe2f9fda51b718198128a55ba11f27',
+};
+/** Code-owned relocatable identity lock for the admitted public Codex slice. */
+export const CODEX_DIRECT_MCP_DARWIN_ARM64_LOCK = {
+    format: 'pathgrade-direct-mcp-runtime-lock-v1',
+    provider: 'codex',
+    platform: 'darwin',
+    architecture: 'arm64',
+    controlPlane: 'app-server',
+    version: CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.expectedVersion,
+    commandArtifact: 'codex-cli-0.151.0-alpha.7.1',
+    args: CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.command.args,
+    versionArgs: CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.command.versionArgs,
+    artifacts: [{
+            id: 'codex-cli-0.151.0-alpha.7.1',
+            relativePath: 'codex',
+            sha256: CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.artifacts[0].sha256,
+        }],
+    capabilities: CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.requiredCapabilities,
+    normalizedHandshakeSha256: CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.runtimeCapabilityFingerprint,
+};
+/**
+ * Resolve one Codex candidate before admission. Selection is deterministic;
+ * identity failure never falls through to another process.
+ */
+export async function resolveCodexScenarioExecutable(environment) {
+    const bundled = CODEX_DIRECT_MCP_DARWIN_ARM64_PROFILE.command.absolutePath;
+    if (await isExecutable(bundled))
+        return realpath(bundled);
+    for (const directory of (environment.PATH ?? '').split(delimiter).filter(Boolean)) {
+        const candidate = join(directory, 'codex');
+        if (await isExecutable(candidate))
+            return realpath(candidate);
+    }
+    throw new Error('RUNTIME_NOT_ADMITTED: no Codex executable was discovered');
+}
+async function isExecutable(path) {
+    try {
+        await access(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { JsonObject, MatchExpr, ScenarioArtifact, ScenarioDiagnostic } from './types.js';
+export type CompileScenarioResult = {
+    ok: true;
+    artifact: ScenarioArtifact;
+} | {
+    ok: false;
+    diagnostics: ScenarioDiagnostic[];
+};
+export declare function matchExpression(args: JsonObject, expression: MatchExpr): boolean;
+export declare function compileScenario(source: unknown): CompileScenarioResult;
+export declare function compileScenarioText(text: string): CompileScenarioResult;
+export declare function isSha256(value: unknown): value is string;