@claudexor/harness-codex 1.0.0 → 2.1.2

package/dist/index.js

@@ -1,14 +1,18 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { codexTranscriptModel, codexTranscriptRateLimits } from "./transcript.js";
-import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
-import { ConformanceReport as ConformanceReportSchema, HarnessManifest as HarnessManifestSchema } from "@claudexor/schema";
-import { HarnessUnavailableError, normalizeEffort, playwrightMcpArgs, providerScrubEnv, resolveNpxBin, runCapture, runCliHarness } from "@claudexor/core";
 import { resolveSecret } from "@claudexor/secrets";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ConformanceReport as ConformanceReportSchema, HarnessManifest as HarnessManifestSchema, } from "@claudexor/schema";
+import { abortSignalFromSpec, browserMcpCommand, HarnessUnavailableError, normalizeEffort, providerScrubEnv, resolveHarnessBinary, runCapture, runCliHarness, selectStrictAuthRoute, selectedAuthAvailable, selectedAuthReady, shouldVerifyApiKey, } from "@claudexor/core";
 import { CLAUDEXOR_VERSION, nowIso, redactSecrets } from "@claudexor/util";
 import { parseCodexEvent } from "./parse.js";
+import { probeCodexCredentialProfile, resolveCodexProfileRoute } from "./profile.js";
+import { smokeIsolatedApiKey } from "./smoke.js";
+export { canonicalCodexProfileHome } from "./profile.js";
 import { estimateCodexCostUsd } from "./pricing.js";
-const BIN = process.env.CLAUDEXOR_CODEX_BIN || "codex";
+import { codexImageArgs } from "./attachments.js";
+export const BIN = process.env.CLAUDEXOR_CODEX_BIN || "codex";
 /**
  * Ordered (weakest→strongest) reasoning-effort levels codex's
  * `model_reasoning_effort` config accepts. SINGLE source: the manifest's
@@ -16,90 +20,41 @@ const BIN = process.env.CLAUDEXOR_CODEX_BIN || "codex";
  * `max` hint clamps to `xhigh` (the ceiling) via the shared normalizer.
  */
 const CODEX_EFFORT_LEVELS = ["low", "medium", "high", "xhigh"];
+/** Exported for focused route-policy tests; runtime uses this exact selector. */
+export const selectCodexRunAuthRoute = selectStrictAuthRoute;
+export { CODEX_FILE_AUTH_ARGS, CODEX_FILE_AUTH_OVERRIDE, codexApiKey, codexAuthModeAt, defaultNativeCodexHome, ensureCodexApiAuth, probeLogin, } from "./auth.js";
+import { CODEX_FILE_AUTH_ARGS, codexApiKey, codexAuthModeAt, defaultNativeCodexHome, ensureCodexApiAuth, hasApiKey, probeLogin, } from "./auth.js";
 /**
- * Resolve an OpenAI API key for codex from the environment. Claudexor-managed
- * `api_key` auth mirrors the harness's own variable (`OPENAI_API_KEY`); a
- * dedicated `CLAUDEXOR_CODEX_API_KEY` can override it for multi-key setups.
- */
-function codexApiKey() {
-    // The hermetic kill switch is honored inside resolveSecret (single owner).
-    const stored = resolveSecret("openai");
-    return process.env.CLAUDEXOR_CODEX_API_KEY || process.env.CODEX_API_KEY || process.env.OPENAI_API_KEY || stored || undefined;
-}
-/**
- * Seed `api_key` auth into an isolated CODEX_HOME. Codex does not read
- * `OPENAI_API_KEY` from the environment when run against an empty config dir
- * (it requires `auth.json`), so an envelope-scoped CODEX_HOME would otherwise
- * fail with 401 even though a key is available. We write the same file
- * `codex login --with-api-key` produces. No-op when not isolated (use codex's
- * native auth), when no key is available, or when auth already exists.
- */
-export function ensureCodexApiAuth(env, allowApiKey = true) {
-    if (!allowApiKey)
-        return;
-    const home = env?.["CODEX_HOME"];
-    if (!home)
-        return;
-    const apiKey = codexApiKey();
-    if (!apiKey)
-        return;
-    const authPath = join(home, "auth.json");
-    if (existsSync(authPath))
-        return;
-    try {
-        mkdirSync(home, { recursive: true });
-        writeFileSync(authPath, JSON.stringify({ auth_mode: "apikey", OPENAI_API_KEY: apiKey }) + "\n", { mode: 0o600 });
-    }
-    catch {
-        /* best-effort: codex will surface an auth error if this did not take */
-    }
-}
-/** The user's real codex home (native ChatGPT/subscription session lives here). */
-export function defaultNativeCodexHome() {
-    const override = process.env.CLAUDEXOR_CODEX_NATIVE_HOME;
-    if (override && override.trim())
-        return override;
-    return join(homedir(), ".codex");
-}
-/**
- * Seed the user's NATIVE codex session (`auth.json`, ChatGPT/subscription mode)
- * into an isolated CODEX_HOME so a Max/Pro subscriber with NO API key can run
- * inside a Claudexor envelope. This is the "subscription-first must actually
- * work" fix: previously the scoped empty CODEX_HOME hid the native session and
- * the run failed demanding an API key.
- *
- * Copies ONLY if the scoped auth is absent and a native `auth.json` exists; never
- * overwrites (codex refreshes the token in place). Returns true when scoped auth
- * is present afterwards. No-op when not isolated or no native session exists.
+ * A TOML basic-string literal for a `-c key=value` override. `developer_instructions`
+ * is a documented additive Codex config key (layered as a developer block BEFORE
+ * AGENTS.md, not a replacement); passing per-invocation `-c` keeps it isolated
+ * to this run (never a shared-config mutation). Instructions may contain quotes
+ * and newlines, so they are TOML-escaped.
  */
-export function ensureCodexNativeAuth(env, nativeHome = defaultNativeCodexHome()) {
-    const home = env?.["CODEX_HOME"];
-    if (!home)
-        return false;
-    const dest = join(home, "auth.json");
-    if (existsSync(dest))
-        return true; // already seeded (api or native)
-    const src = join(nativeHome, "auth.json");
-    if (!existsSync(src))
-        return false;
-    try {
-        mkdirSync(home, { recursive: true });
-        copyFileSync(src, dest);
-        try {
-            chmodSync(dest, 0o600);
-        }
-        catch {
-            /* best-effort: perms */
-        }
-        return existsSync(dest);
-    }
-    catch {
-        return false;
+function tomlBasicString(value) {
+    // TOML basic-string escapes, built by code point so the SOURCE carries no
+    // literal control characters: a backslash and quote are escaped, a literal
+    // newline/tab/CR become their escapes (a raw newline is invalid in a basic
+    // string), other control chars become \uXXXX, and everything else is literal.
+    let out = '"';
+    for (const ch of value) {
+        const code = ch.charCodeAt(0);
+        if (ch === "\\")
+            out += "\\\\";
+        else if (ch === '"')
+            out += '\\"';
+        else if (code === 10)
+            out += "\\n";
+        else if (code === 13)
+            out += "\\r";
+        else if (code === 9)
+            out += "\\t";
+        else if (code < 32 || code === 127)
+            out += "\\u" + code.toString(16).padStart(4, "0");
+        else
+            out += ch;
     }
-}
-/** True when a native codex session exists and can be seeded into an envelope. */
-function nativeCodexSeedable() {
-    return existsSync(join(defaultNativeCodexHome(), "auth.json"));
+    return out + '"';
 }
 function sandboxArgs(access) {
     switch (access) {
@@ -114,83 +69,61 @@ function sandboxArgs(access) {
             return [];
     }
 }
-async function detectVersion() {
+async function detectVersion(abortSignal) {
     try {
-        const r = await runCapture(BIN, ["--version"], { timeoutMs: 10_000 });
+        const r = await runCapture(BIN, ["--version"], {
+            timeoutMs: 10_000,
+            abortSignal,
+            cancelSignal: "SIGTERM",
+            cancelKillDelayMs: 0,
+        });
         return r.stdout.trim() || `${BIN} (version unknown)`;
     }
     catch {
         return null;
     }
 }
-async function loggedIn() {
-    try {
-        const r = await runCapture(BIN, ["login", "status"], { timeoutMs: 10_000 });
-        return r.code === 0;
-    }
-    catch {
-        return false;
-    }
-}
-function hasApiKey() {
-    return Boolean(codexApiKey());
+export function redactCodexDoctorDetail(text) {
+    return redactSecrets(text).slice(0, 500);
 }
-function hasScopedCodexAuth(env) {
-    const home = env?.["CODEX_HOME"];
-    return Boolean(home && existsSync(join(home, "auth.json")));
+export function codexNativeEnv(base, codexHome) {
+    return {
+        ...(base ?? {}),
+        ...providerScrubEnv(),
+        CODEX_HOME: codexHome ?? defaultNativeCodexHome(),
+    };
 }
-async function smokeIsolatedApiKey() {
-    if (!codexApiKey())
-        return { ok: false, detail: "no API key fallback available" };
-    const dir = mkdtempSync(join(tmpdir(), "claudexor-codex-smoke-"));
-    const codexHome = join(dir, ".codex");
-    try {
-        ensureCodexApiAuth({ CODEX_HOME: codexHome });
-        const r = await runCapture(BIN, ["exec", "--json", "--sandbox", "read-only", "--skip-git-repo-check", "Reply exactly OK"], {
-            cwd: dir,
-            env: {
-                HOME: dir,
-                XDG_CONFIG_HOME: join(dir, ".config"),
-                CODEX_HOME: codexHome,
-                OPENAI_API_KEY: null,
-                CODEX_API_KEY: null,
-                CLAUDEXOR_CODEX_API_KEY: null,
-            },
-            timeoutMs: 25_000,
-        });
-        const text = `${r.stdout}\n${r.stderr}`;
-        if (r.code === 0 && text.includes("\"turn.completed\"") && text.includes("OK")) {
-            return { ok: true, detail: "isolated CODEX_HOME smoke passed" };
-        }
-        return { ok: false, detail: redactCodexDoctorDetail(text || `codex exited with code ${r.code}`) };
-    }
-    catch (err) {
-        return { ok: false, detail: redactCodexDoctorDetail(err instanceof Error ? err.message : String(err)) };
+function codexNativeReadiness(login) {
+    if (login.probeError) {
+        return {
+            source: "native_session",
+            availability: "unknown",
+            verification: "not_run",
+            detail: `login-status probe failed: ${redactCodexDoctorDetail(login.probeError)}`,
+        };
     }
-    finally {
-        // codex can still be flushing session files into CODEX_HOME when the smoke
-        // returns. Cleanup is best-effort: a leaked OS tmp dir must never decide
-        // doctor/readiness truth (the smoke verdict is the codex run itself).
-        try {
-            rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
-        }
-        catch {
-            /* OS tmp reaper owns the leftovers */
-        }
+    if (login.method === "chatgpt") {
+        return {
+            source: "native_session",
+            availability: "available",
+            verification: "passed",
+            detail: "vendor status confirmed a native ChatGPT session in the exact run environment",
+        };
     }
-}
-function redactCodexDoctorDetail(text) {
-    return redactSecrets(text).slice(0, 500);
-}
-/** Codex forwards images via `-i/--image <FILE>` (repeatable; file path only —
- *  it rejects remote URLs). Non-image attachments have no native codex surface. */
-function codexImageArgs(attachments) {
-    const out = [];
-    for (const a of attachments ?? []) {
-        if (a.kind === "image")
-            out.push("-i", a.path);
+    if (login.authed) {
+        return {
+            source: "native_session",
+            availability: "available",
+            verification: "failed",
+            detail: `Codex is authenticated via ${login.method}, not ChatGPT subscription auth`,
+        };
     }
-    return out;
+    return {
+        source: "native_session",
+        availability: "unavailable",
+        verification: "not_run",
+        detail: "native Codex session is not logged in",
+    };
 }
 /**
  * Inject the Playwright browser MCP as stateless `-c mcp_servers.browser.*`
@@ -204,11 +137,12 @@ function codexImageArgs(attachments) {
 export function codexBrowserArgs(browser, externalContextPolicy) {
     if (!browser || externalContextPolicy === "off")
         return [];
+    const mcp = browserMcpCommand(browser);
     return [
         "-c",
-        `mcp_servers.browser.command=${JSON.stringify(resolveNpxBin())}`,
+        `mcp_servers.browser.command=${JSON.stringify(mcp.command)}`,
         "-c",
-        `mcp_servers.browser.args=${JSON.stringify(playwrightMcpArgs(browser))}`,
+        `mcp_servers.browser.args=${JSON.stringify(mcp.args)}`,
         "-c",
         "mcp_servers.browser.startup_timeout_sec=90",
         "-c",
@@ -248,18 +182,26 @@ export function codexExecArgs(spec, opts = {}) {
     // effort not tunable -> pass no flag.
     const effort = normalizeEffort(spec.effort_hint, CODEX_EFFORT_LEVELS);
     if (spec.resume_session_id) {
-        const args = ["exec", "resume", spec.resume_session_id, "--json", ...sandboxConfigArgs(spec.access), "--skip-git-repo-check"];
-        // Structured output, LIVE-VERIFIED (0.137): --output-schema <FILE>.
+        const args = [
+            "exec",
+            "resume",
+            spec.resume_session_id,
+            "--json",
+            ...CODEX_FILE_AUTH_ARGS,
+            ...sandboxConfigArgs(spec.access),
+            "--skip-git-repo-check",
+        ];
         if (opts.outputSchemaPath)
             args.push("--output-schema", opts.outputSchemaPath);
         if (spec.model_hint)
             args.push("-m", spec.model_hint);
         if (effort)
             args.push("-c", `model_reasoning_effort="${effort}"`);
+        if (spec.instructions && spec.instructions.trim())
+            args.push("-c", `developer_instructions=${tomlBasicString(spec.instructions)}`);
         args.push(...codexWebArgs(spec.external_context_policy ?? "auto"));
         // ALL `-c` config overrides go BEFORE `-i` so the variadic `-i/--image
-        // <FILE>...` can't swallow them as image paths; then images, then `--` so the
-        // positional prompt survives, then the prompt.
+        // <FILE>...` can't swallow them as image paths.
         args.push(...codexBrowserArgs(spec.browser, spec.external_context_policy));
         args.push(...nodeReplArgs);
         const imageArgs = codexImageArgs(spec.attachments);
@@ -273,14 +215,16 @@ export function codexExecArgs(spec, opts = {}) {
         args.push(spec.prompt);
         return args;
     }
-    const args = ["exec", "--json", ...sandboxArgs(spec.access), "--skip-git-repo-check"];
-    // Structured output, LIVE-VERIFIED (0.137): --output-schema <FILE>.
+    const args = ["exec", "--json", ...CODEX_FILE_AUTH_ARGS];
+    args.push(...sandboxArgs(spec.access), "--skip-git-repo-check");
     if (opts.outputSchemaPath)
         args.push("--output-schema", opts.outputSchemaPath);
     if (spec.model_hint)
         args.push("-m", spec.model_hint);
     if (effort)
         args.push("-c", `model_reasoning_effort="${effort}"`);
+    if (spec.instructions && spec.instructions.trim())
+        args.push("-c", `developer_instructions=${tomlBasicString(spec.instructions)}`);
     args.push(...codexWebArgs(spec.external_context_policy ?? "auto"));
     // ALL `-c` config overrides BEFORE `-i` (variadic) so they can't be eaten as
     // image paths; then images, then `--`, then the prompt. See resume branch.
@@ -318,18 +262,29 @@ function codexWebArgs(policy) {
             return ["-c", 'web_search="cached"'];
     }
 }
-export function createCodexAdapter() {
+export function createCodexAdapter(deps = {}) {
+    const runtime = {
+        detectVersion,
+        probeLogin,
+        hasApiKey,
+        codexApiKey,
+        resolveProfileSecret: (ref) => resolveSecret(ref),
+        smokeIsolatedApiKey,
+        runCliHarness,
+        ...deps,
+    };
     return {
         id: "codex",
         async discover() {
-            const version = await detectVersion();
+            const version = await runtime.detectVersion();
             if (version === null) {
                 throw new HarnessUnavailableError("codex CLI not found on PATH (set CLAUDEXOR_CODEX_BIN to override)");
             }
-            const apiKey = hasApiKey();
-            const authed = await loggedIn();
+            const apiKey = runtime.hasApiKey();
+            const login = await runtime.probeLogin(BIN, { env: codexNativeEnv() });
+            const nativeSessionAvailable = login.method === "chatgpt";
             const authModes = [
-                ...(authed ? ["local_session"] : []),
+                ...(nativeSessionAvailable ? ["local_session"] : []),
                 ...(apiKey ? ["api_key"] : []),
             ];
             return HarnessManifestSchema.parse({
@@ -361,36 +316,48 @@ export function createCodexAdapter() {
                     // Current + still-API-available ids per the vendor Codex models page,
                     // verified against the installed CLI recorded below.
                     known_models: [
+                        "gpt-5.6",
+                        "gpt-5.6-sol",
+                        "gpt-5.6-terra",
+                        "gpt-5.6-luna",
                         "gpt-5.5",
                         "gpt-5.4",
                         "gpt-5.4-mini",
                         "gpt-5.3-codex-spark",
-                        "gpt-5.3-codex",
-                        "gpt-5.2",
                     ],
-                    known_models_verified_against: "0.137.0",
+                    known_models_verified_against: "0.144.1",
                 },
                 capability_profile: {
                     auth: {
-                        supported_sources: ["native_session", "api_key_env", "provider_auth_file"],
-                        preferred_source: apiKey ? "provider_auth_file" : authed ? "native_session" : null,
+                        supported_sources: ["native_session", "provider_auth_file"],
+                        preferred_source: nativeSessionAvailable
+                            ? "native_session"
+                            : apiKey
+                                ? "provider_auth_file"
+                                : null,
                         credential_transports: [
                             { source: "native_session", kind: "config_file", relocatable_by: ["CONFIG_DIR"] },
                             { source: "provider_auth_file", kind: "config_file", relocatable_by: ["CONFIG_DIR"] },
-                            { source: "api_key_env", kind: "config_file", relocatable_by: ["CONFIG_DIR"] },
                         ],
                     },
                     access_control: { readonly_mechanism: "fs_sandbox" },
-                    isolation: { supported_containment: ["env_or_file_injection"] },
-                    // Codex accepts images via `codex exec -i/--image <FILE>` (file path; remote URLs rejected).
-                    image_input: "file_path",
+                    isolation: { supported_containment: ["host_user_context", "env_or_file_injection"] },
+                    attachment_inputs: [
+                        {
+                            kind: "image",
+                            mime_types: ["image/png", "image/jpeg", "image/gif", "image/webp"],
+                            max_bytes: 20 * 1024 * 1024,
+                            max_count: 20,
+                            transport: "file_path",
+                        },
+                    ],
                 },
                 auth_modes: authModes,
                 access_profiles_supported: ["readonly", "workspace_write", "full", "inherit_native"],
             });
         },
         async doctor(_spec) {
-            const version = await detectVersion();
+            const version = await runtime.detectVersion(_spec.abortSignal);
             if (version === null) {
                 return ConformanceReportSchema.parse({
                     harness_id: "codex",
@@ -399,145 +366,240 @@ export function createCodexAdapter() {
                     reasons: ["codex CLI not found (install Codex or set CLAUDEXOR_CODEX_BIN)"],
                 });
             }
-            const apiKey = hasApiKey();
-            const authed = await loggedIn();
-            // Native session readiness is FIRST-CLASS: a logged-in subscription whose
-            // auth.json we can seed into the envelope is `ok` with no paid API smoke.
-            // (Bible: a stored key STRING alone is still not proof -> api-key route
-            // keeps the isolated smoke.) This is what makes subscription-first real.
-            const nativeReady = authed && nativeCodexSeedable();
-            const smoke = !nativeReady && apiKey ? await smokeIsolatedApiKey() : { ok: false, detail: nativeReady ? "skipped (native session ready)" : "no API key fallback available" };
-            const ok = nativeReady || smoke.ok;
-            const allIntents = ["plan", "spec", "implement", "repair", "create_from_scratch", "review", "verify", "synthesize", "explain", "audit", "orchestrate"];
+            const requestedSource = _spec.authSource;
+            const probeNative = requestedSource === undefined || requestedSource === "native_session";
+            const probeApi = requestedSource === undefined || requestedSource === "provider_auth_file";
+            const login = probeNative
+                ? await runtime.probeLogin(BIN, {
+                    env: codexNativeEnv(_spec.env),
+                    abortSignal: _spec.abortSignal,
+                })
+                : { authed: false, method: "logged_out", probeError: null };
+            const nativeSource = codexNativeReadiness(login);
+            const nativeReady = nativeSource.verification === "passed";
+            const apiKey = probeApi && runtime.hasApiKey();
+            const preference = requestedSource === "native_session"
+                ? "subscription"
+                : requestedSource === "provider_auth_file"
+                    ? "api_key"
+                    : (_spec.authPreference ?? "auto");
+            const shouldSmokeKey = probeApi && shouldVerifyApiKey({ preference, apiKeyAvailable: apiKey, nativeReady });
+            const smoke = shouldSmokeKey
+                ? await runtime.smokeIsolatedApiKey(_spec.abortSignal)
+                : {
+                    ok: false,
+                    detail: apiKey
+                        ? "verification not run for the unselected API-key route"
+                        : "no API key fallback available",
+                };
+            const ok = selectedAuthReady({ preference, nativeReady, apiKeyReady: smoke.ok });
+            const selectedAvailable = selectedAuthAvailable({
+                preference,
+                nativeAvailable: nativeSource.availability === "available",
+                apiKeyAvailable: apiKey,
+            });
+            const probeUnknown = preference !== "api_key" && nativeSource.availability === "unknown";
+            const allIntents = [
+                "plan",
+                "spec",
+                "implement",
+                "repair",
+                "create_from_scratch",
+                "review",
+                "verify",
+                "synthesize",
+                "explain",
+                "audit",
+                "orchestrate",
+            ];
+            const binPath = resolveHarnessBinary(BIN);
+            const apiSource = {
+                source: "provider_auth_file",
+                availability: apiKey ? "available" : "unavailable",
+                verification: smoke.ok ? "passed" : shouldSmokeKey ? "failed" : "not_run",
+                detail: smoke.detail,
+            };
+            const authSources = requestedSource === "native_session"
+                ? [nativeSource]
+                : requestedSource === "provider_auth_file"
+                    ? [apiSource]
+                    : requestedSource !== undefined
+                        ? [
+                            {
+                                source: requestedSource,
+                                availability: "unavailable",
+                                verification: "not_run",
+                                detail: `Codex does not support ${requestedSource}`,
+                            },
+                        ]
+                        : [nativeSource, apiSource];
             return ConformanceReportSchema.parse({
                 harness_id: "codex",
-                status: ok ? "ok" : authed || apiKey ? "degraded" : "unavailable",
+                status: ok ? "ok" : selectedAvailable || probeUnknown ? "degraded" : "unavailable",
                 checks: [
-                    { id: "installed", status: "pass", detail: version },
-                    { id: "native_session", status: nativeReady ? "pass" : "fail", detail: nativeReady ? "native codex session seedable into envelope" : authed ? "logged in but ~/.codex/auth.json not found" : "not logged in (run `codex login`)" },
-                    { id: "stored_key", status: apiKey ? "pass" : "fail", detail: apiKey ? "openai secret/env available (api-key fallback)" : "no openai key fallback" },
-                    { id: "isolated_api_smoke", status: smoke.ok ? "pass" : nativeReady ? "skip" : apiKey ? "fail" : "skip", detail: smoke.detail },
+                    {
+                        id: "installed",
+                        status: "pass",
+                        detail: binPath ? `${version} at ${binPath}` : version,
+                    },
+                    ...(probeNative
+                        ? [
+                            {
+                                id: "native_session",
+                                status: nativeReady ? "pass" : "fail",
+                                detail: nativeReady
+                                    ? "vendor status confirmed native ChatGPT auth in the exact run environment"
+                                    : login.probeError
+                                        ? `login-status probe failed (NOT an auth verdict): ${redactCodexDoctorDetail(login.probeError)}`
+                                        : login.authed
+                                            ? `logged in via ${login.method}, not ChatGPT subscription auth`
+                                            : "not logged in (run `codex login`)",
+                            },
+                        ]
+                        : []),
+                    ...(probeApi
+                        ? [
+                            {
+                                id: "stored_key",
+                                status: apiKey ? "pass" : "fail",
+                                detail: apiKey
+                                    ? "openai secret/env available (API-key fallback)"
+                                    : "no openai key fallback",
+                            },
+                            {
+                                id: "isolated_api_smoke",
+                                status: smoke.ok ? "pass" : shouldSmokeKey ? "fail" : "skip",
+                                detail: smoke.detail,
+                            },
+                        ]
+                        : []),
                 ],
+                auth_sources: authSources,
                 enabled_intents: ok ? allIntents : [],
                 disabled_intents: ok ? [] : allIntents,
                 reasons: ok
                     ? []
-                    : apiKey
-                        ? [`isolated Codex API-key smoke failed: ${smoke.detail}`]
-                        : ["not authenticated (run `codex login` for native/subscription use, or store an openai API key fallback)"],
+                    : preference === "subscription"
+                        ? [
+                            login.probeError
+                                ? `Codex native-session probe failed: ${redactCodexDoctorDetail(login.probeError)}`
+                                : login.authed
+                                    ? `Codex is authenticated via ${login.method}, not a ChatGPT subscription session`
+                                    : "Codex subscription route is not ready (run `codex login`)",
+                        ]
+                        : preference === "api_key"
+                            ? [
+                                apiKey
+                                    ? `isolated Codex API-key smoke failed: ${smoke.detail}`
+                                    : "Codex API-key route is not configured",
+                            ]
+                            : apiKey
+                                ? [`isolated Codex API-key smoke failed: ${smoke.detail}`]
+                                : [
+                                    "not authenticated (run `codex login` for native/subscription use, or store an openai API key fallback)",
+                                ],
             });
         },
         run(spec) {
-            return runCodex(spec);
+            return runCodex(spec, runtime);
         },
         review(spec) {
-            return runCodex(spec);
+            return runCodex(spec, runtime);
+        },
+        probeCredentialProfile(profile, abortSignal) {
+            return probeCodexCredentialProfile(profile, runtime, abortSignal);
         },
     };
 }
-async function* runCodex(spec) {
-    const nativeAuthed = await loggedIn();
-    const key = codexApiKey();
-    const preferApi = spec.auth_preference === "api_key";
-    const scopedHome = Boolean(spec.env?.["CODEX_HOME"]);
-    const scopedHomeNeedsAuth = scopedHome && !hasScopedCodexAuth(spec.env);
-    // Seed credentials into the scoped CODEX_HOME. BOTH auth routes are supported
-    // with auto-fallback: `subscription` seeds the native session (auth.json copied
-    // from ~/.codex — the fix that makes subscription-first actually work inside an
-    // envelope); `api_key` seeds the OpenAI key. Order follows auth_preference, and
-    // each falls back to the other so a run is not stranded when one source is gone.
-    let authRoute = null;
-    if (scopedHomeNeedsAuth) {
-        const trySub = () => {
-            const ok = nativeAuthed ? ensureCodexNativeAuth(spec.env) : false;
-            if (ok)
-                authRoute = "subscription";
-            return ok;
-        };
-        const tryKey = () => {
+async function* runCodex(spec, runtime) {
+    const profile = spec.credential_profile;
+    const authPreference = spec.auth_preference ?? "auto";
+    let nativeEnv = codexNativeEnv(spec.env);
+    let key;
+    let tempCodexHome = null;
+    let authRoute;
+    if (profile) {
+        const resolved = await resolveCodexProfileRoute(profile, spec.env, runtime, abortSignalFromSpec(spec));
+        if (resolved.refusal !== null) {
+            yield { type: "error", session_id: spec.session_id, ts: nowIso(), error: resolved.refusal };
+            yield { type: "completed", session_id: spec.session_id, ts: nowIso() };
+            return;
+        }
+        ({ nativeEnv, tempCodexHome } = resolved);
+        key = resolved.key ?? undefined;
+        authRoute = resolved.route;
+    }
+    else {
+        const nativeLogin = authPreference === "api_key"
+            ? { authed: false, method: "logged_out", probeError: null }
+            : await runtime.probeLogin(BIN, {
+                env: nativeEnv,
+                abortSignal: abortSignalFromSpec(spec),
+            });
+        const nativeSessionReady = nativeLogin.method === "chatgpt" && nativeLogin.probeError === null;
+        const trySubscription = () => nativeSessionReady;
+        const tryApiKey = () => {
+            key ??= runtime.codexApiKey();
             if (!key)
                 return false;
-            ensureCodexApiAuth(spec.env, true);
-            const ok = hasScopedCodexAuth(spec.env);
-            if (ok)
-                authRoute = "api_key";
-            return ok;
+            tempCodexHome = mkdtempSync(join(tmpdir(), "claudexor-codex-auth-"));
+            ensureCodexApiAuth({ CODEX_HOME: tempCodexHome });
+            if (codexAuthModeAt(tempCodexHome) === "api_key")
+                return true;
+            rmSync(tempCodexHome, { recursive: true, force: true });
+            tempCodexHome = null;
+            return false;
         };
-        const seeded = preferApi ? tryKey() || trySub() : trySub() || tryKey();
-        if (!seeded) {
-            yield {
-                type: "error",
-                session_id: spec.session_id,
-                ts: nowIso(),
-                error: "no usable codex auth for this envelope: native session not seedable (run `codex login`) and no OpenAI API key fallback available",
-            };
+        authRoute = selectCodexRunAuthRoute(authPreference, trySubscription, tryApiKey);
+        if (authRoute === null) {
+            const error = authPreference === "subscription"
+                ? "Codex subscription auth was explicitly requested but vendor status did not confirm a native ChatGPT session (run `codex login`)"
+                : authPreference === "api_key"
+                    ? "Codex API-key auth was explicitly requested but no usable OpenAI API key route is ready"
+                    : "no usable Codex auth: native ChatGPT session is not ready and no OpenAI API key fallback is ready";
+            yield { type: "error", session_id: spec.session_id, ts: nowIso(), error };
             yield { type: "completed", session_id: spec.session_id, ts: nowIso() };
             return;
         }
-        // An EXPLICIT auth preference that could not be honored is disclosed as a
-        // typed marker; the orchestrator lifts it into route.fallback.auth_switched.
-        const preferred = preferApi ? "api_key" : "subscription";
-        if (spec.auth_preference !== "auto" && authRoute && authRoute !== preferred) {
-            yield {
-                type: "message",
-                session_id: spec.session_id,
-                ts: nowIso(),
-                text: `[auth] ${preferred} route unavailable; fell back to ${authRoute}`,
-                payload: { auth_switched: true, from_auth_mode: preferred === "subscription" ? "local_session" : "api_key", to_auth_mode: authRoute === "subscription" ? "local_session" : "api_key" },
-            };
-        }
     }
-    // Codex authenticates from the seeded auth.json (never an env key), so scrub
-    // EVERY provider secret + base-URL redirect from the child — including other
-    // providers' keys (the cross-provider leak fix), via the single core table.
-    const env = {
-        ...spec.env,
-        ...providerScrubEnv(),
-    };
-    // Non-envelope run (no scoped CODEX_HOME): an explicit `api_key` preference is
-    // HONORED even when natively logged in (a private temp CODEX_HOME seeded with
-    // the key; codex ignores OPENAI_API_KEY without an auth.json) — and a missing
-    // key falls back to the native session with a typed disclosure. Without a
-    // preference, the key route is only the no-native fallback.
-    let tempCodexHome = null;
-    if (!scopedHome && key && (preferApi || !nativeAuthed)) {
-        tempCodexHome = mkdtempSync(join(tmpdir(), "claudexor-codex-auth-"));
-        env["CODEX_HOME"] = tempCodexHome;
-        ensureCodexApiAuth({ CODEX_HOME: tempCodexHome });
-        // Same disclosure as the envelope path: an explicit subscription preference
-        // that lands on the billed key route is never silent.
-        if (spec.auth_preference === "subscription") {
-            yield {
-                type: "message",
-                session_id: spec.session_id,
-                ts: nowIso(),
-                text: "[auth] subscription route unavailable (not logged in); fell back to api_key",
-                payload: { auth_switched: true, from_auth_mode: "local_session", to_auth_mode: "api_key" },
-            };
-        }
-    }
-    else if (!scopedHome && preferApi && !key && nativeAuthed) {
+    // Auto is subscription-first. Selecting its API-key fallback is a paid-route
+    // switch and must remain typed/visible; explicit routes never fall back.
+    if (!profile && authPreference === "auto" && authRoute === "api_key") {
         yield {
             type: "message",
             session_id: spec.session_id,
             ts: nowIso(),
-            text: "[auth] api_key route unavailable (no key); fell back to subscription",
-            payload: { auth_switched: true, from_auth_mode: "api_key", to_auth_mode: "local_session" },
+            text: "[auth] native subscription route unavailable; auto selected api_key",
+            payload: {
+                auth_switched: true,
+                from_auth_mode: "local_session",
+                to_auth_mode: "api_key",
+                reason: "readiness_preferred",
+            },
         };
     }
+    // Native auth uses the vendor-owned CODEX_HOME (which may resolve credentials
+    // through a config file or OS keychain); API auth uses an isolated generated
+    // auth file. Neither route inherits provider env credentials or redirects.
+    const env = authRoute === "subscription" ? nativeEnv : { ...spec.env, ...providerScrubEnv() };
+    // Non-envelope API-key routes use a private CODEX_HOME because Codex ignores
+    // OPENAI_API_KEY against its normal auth store. `tryApiKey` created and
+    // verified this file before route selection returned api_key.
+    if (authRoute === "api_key" && tempCodexHome) {
+        env["CODEX_HOME"] = tempCodexHome;
+    }
     // Disable Codex.app's headless-incompatible node_repl MCP, but ONLY when the
     // config codex will actually load (the resolved CODEX_HOME, else ~/.codex)
     // already defines it — never create a transport-less partial entry on a scoped
     // home (that broke codex startup, the "invalid transport" regression).
-    // Structured output: codex takes a FILE path; write the schema into the
-    // scoped CODEX_HOME (outside the worktree — never lands in a diff). A
-    // native-session run has no scoped home, so the schema goes to a private
-    // tmp dir instead — the capability must not silently vanish on that route.
+    // Structured output: codex takes a FILE path. API routes may use their
+    // isolated CODEX_HOME; native routes must never write helper files into the
+    // vendor-owned native home, so they use a private temp directory.
     let outputSchemaPath = null;
     let tempSchemaDir = null;
     if (spec.output_schema !== undefined && spec.output_schema !== null) {
         try {
-            let dir = env["CODEX_HOME"];
+            let dir = authRoute === "subscription" ? undefined : env["CODEX_HOME"];
             if (!dir) {
                 tempSchemaDir = mkdtempSync(join(tmpdir(), "claudexor-codex-schema-"));
                 dir = tempSchemaDir;
@@ -545,11 +607,22 @@ async function* runCodex(spec) {
             outputSchemaPath = join(dir, `claudexor-output-schema-${spec.session_id}.json`);
             writeFileSync(outputSchemaPath, JSON.stringify(spec.output_schema));
         }
-        catch {
-            outputSchemaPath = null; // fail-open to fenced-JSON parsing
+        catch (err) {
+            // FAIL-CLOSED (Quiz-6a): output_schema is a contract — running the
+            // child UNCONSTRAINED because a local schema file failed to write would
+            // silently drop it. Fail loudly; the caller retries or reroutes.
+            throw new Error(`codex output-schema file could not be written (${err instanceof Error ? err.message : String(err)}); refusing to run unconstrained`);
         }
     }
-    const args = codexExecArgs(spec, { suppressNodeRepl: codexConfigHasNodeRepl(env["CODEX_HOME"]), outputSchemaPath });
+    const args = codexExecArgs(spec, {
+        suppressNodeRepl: codexConfigHasNodeRepl(env["CODEX_HOME"]),
+        outputSchemaPath,
+    });
+    // Route evidence: the auth mode this child ACTUALLY runs under, read from
+    // the same auth.json codex loads (typed `auth_mode` field — chatgpt vs
+    // apikey). Disclosed on the started event; quota attribution consumes it.
+    const credentialRoute = authRoute === "subscription" ? "vendor_native" : "managed_api_key";
+    const credentialSource = authRoute === "subscription" ? "native_session" : "api_key_env";
     // Codex reports tokens but no $cost; estimate it from the (hint/configured)
     // model so the budget ledger does not see every codex run as free.
     const model = spec.model_hint ?? process.env.CLAUDEXOR_CODEX_MODEL ?? null;
@@ -557,8 +630,9 @@ async function* runCodex(spec) {
     // codex recorded in its own rollout transcript; cache that one read.
     let codexThreadId;
     let transcriptModel;
+    const parseState = {}; // per-run finality (see CodexParseState)
     try {
-        yield* runCliHarness({
+        yield* runtime.runCliHarness({
             bin: BIN,
             args,
             spec,
@@ -570,7 +644,7 @@ async function* runCodex(spec) {
                 const raw = obj;
                 if (raw?.type === "thread.started" && typeof raw.thread_id === "string")
                     codexThreadId = raw.thread_id;
-                const out = parseCodexEvent(obj, sessionId);
+                const out = parseCodexEvent(obj, sessionId, parseState);
                 if (out === null)
                     return null;
                 for (const ev of out) {
@@ -578,14 +652,24 @@ async function* runCodex(spec) {
                     // exists to catch silent fallback, so an unobserved model must stay
                     // unobserved. Record the requested model for diagnostics only.
                     if (ev.type === "started" && spec.model_hint && !ev.observed_model) {
-                        ev.payload = { ...(ev.payload ?? {}), requested_model: spec.model_hint, observed_model_source: "unobserved" };
+                        ev.payload = {
+                            ...(ev.payload ?? {}),
+                            requested_model: spec.model_hint,
+                            observed_model_source: "unobserved",
+                        };
                     }
+                    // The route is fixed before spawn; attach it to every event so a
+                    // later usage/quota record remains independently attributable.
+                    ev.credential_route = credentialRoute;
+                    ev.credential_source = credentialSource;
+                    if (profile)
+                        ev.credential_profile_id = profile.profile_id;
                     // codex's --json stream never carries the model, but the CLI
                     // records it in its own session rollout. Try to recover it as soon as
                     // the rollout's turn_context appears, then attach the transcript-sourced
                     // observation to the next normalized event. This keeps route proof from
                     // depending on reaching the final usage event under slow reviewer runs.
-                    if (!ev.observed_model) {
+                    if (!ev.observed_model && spec.evidence_policy !== "stream_only") {
                         transcriptModel ??= codexTranscriptModel(env["CODEX_HOME"], codexThreadId) ?? undefined;
                         if (transcriptModel) {
                             ev.observed_model = transcriptModel;
@@ -596,7 +680,10 @@ async function* runCodex(spec) {
                     // deletes on exit, so the native session it created is gone next turn.
                     // Strip its id from the event so it never poisons the thread resume map
                     // (a later `codex exec resume <ghost>` would deterministically fail).
-                    if (ev.type === "started" && tempCodexHome && ev.payload && "native_session_id" in ev.payload) {
+                    if (ev.type === "started" &&
+                        tempCodexHome &&
+                        ev.payload &&
+                        "native_session_id" in ev.payload) {
                         const { native_session_id: _dropped, ...rest } = ev.payload;
                         ev.payload = { ...rest, resume_disabled: "ephemeral_codex_home" };
                     }
@@ -609,11 +696,17 @@ async function* runCodex(spec) {
                     }
                     // Quota headroom: attach codex's own rate-window record to the usage event
                     // (fresh read per usage — the rollout accretes as the turn ends).
-                    if (ev.type === "usage" && !ev.quota) {
+                    if (ev.type === "usage" && !ev.quota && spec.evidence_policy !== "stream_only") {
                         const rl = codexTranscriptRateLimits(env["CODEX_HOME"], codexThreadId);
                         if (rl)
                             ev.quota = rl;
                     }
+                    if (ev.quota && profile && ev.quota.subject_id == null) {
+                        ev.quota = { ...ev.quota, subject_id: profile.profile_id };
+                    }
+                    // A profiled run's quota windows belong to THE PROFILE's account
+                    // (round-17 #2): the rollout record carries no subject, and an
+                    // unstamped null would register as the engine-default subject.
                 }
                 return out;
             },