@prohost/cli 0.2.1 → 0.2.3

package/dist/agent/codex.js

@@ -0,0 +1,901 @@
+/**
+ * The one place that knows anything about Codex CLI specifically.
+ *
+ * The sibling of `claude.ts`, and it exists for the same reason: `exec.ts` is
+ * deliberately agent-agnostic — prompt on stdin, reply on stdout — and that
+ * lowest common denominator costs a Codex run the two things it can actually
+ * have. A run has no memory of the previous one, and it has no tools for
+ * looking anything up in the workspace it is answering about. Until this
+ * module existed, a `codex` brain ran bare while a `claude` brain got both, so
+ * the same mention answered by two hosts produced visibly different work.
+ *
+ * Everything here was verified against a real `codex-cli 0.144.1` rather than
+ * taken from documentation; the surprises are called out where they are relied
+ * on. Output and configuration used to prove the MCP boundary are deliberately
+ * load-bearing: if that proof is incomplete, the unsandboxed run must not
+ * start. Session continuity and reply parsing still fail independently.
+ */
+import { MCP_SERVER_NAME } from './mcp.js';
+import { shellQuote } from './shell.js';
+/**
+ * Environment variable the API key is handed to Codex in.
+ *
+ * Codex resolves MCP headers from the environment at request time
+ * (`env_http_headers`), which is why the key travels this way rather than in
+ * the config override. The override is part of the command line, and a command
+ * line is world-readable out of `ps`; a child's environment is not. This is the
+ * one place the Codex path is meaningfully *safer* than the Claude one, which
+ * has to keep the key in a `0600` file on disk.
+ */
+export const MCP_API_KEY_ENV_VAR = 'PROHOST_MCP_API_KEY';
+/**
+ * Is this exec command Codex CLI in non-interactive mode?
+ *
+ * A **heuristic**, and deliberately as narrow as {@link isClaudeExec}: it
+ * matches when the first word of the command is `codex` (or a path ending in
+ * `/codex`) *and* the command uses the `exec` subcommand (or its `e` alias).
+ * Both halves matter. Interactive `codex` has no `--json` and no `resume`
+ * subcommand, so shaping it would break a command that works today.
+ *
+ * Three things are deliberately not shaped, each because appending to it would
+ * do harm rather than nothing:
+ *
+ *  * `codex exec resume …` and `codex exec review …`. The host already chose a
+ *    sub-subcommand; appending our own `resume` would produce two of them.
+ *  * Anything after a `--` sentinel, which is the host saying "stop parsing".
+ *  * A command carrying its own unquoted prompt, e.g. `codex exec hello`. Codex
+ *    takes exactly one prompt positional, so both the `-` this harness appends
+ *    and a `resume <id>` would be a second one — `error: unexpected argument
+ *    '-' found`, on a command that works today. Such a host keeps the plain
+ *    contract; the place to put standing instructions is now the agent's
+ *    ProhostAI profile, which arrives in the prompt itself.
+ *
+ * Shell syntax is different: recognisable Codex exec commands containing it
+ * stay classified as Codex so the harness can fail closed before spawn. Letting
+ * one fall through as a plain command would also drop the verified MCP boundary.
+ */
+export function isCodexExec(command, platform = process.platform) {
+    // Strip one matching quote pair for classification only. The real command is
+    // never rebuilt from these words: any quote makes the shell-syntax check
+    // below fail closed before a run. This small normalization is what prevents
+    // `codex exec '--enable' plugins` from falling through to the unshaped/plain
+    // path merely because the shell removes quotes our whitespace scan cannot.
+    const words = command
+        .trim()
+        .split(/\s+/)
+        .map((word) => {
+        const match = /^(['"])(.*)\1$/.exec(word);
+        return match?.[2] ?? word;
+    });
+    const trimmed = command.trim();
+    const quote = trimmed[0];
+    const closingQuote = quote === "'" || quote === '"' ? trimmed.indexOf(quote, 1) : -1;
+    const first = closingQuote > 0 ? trimmed.slice(1, closingQuote) : (words[0] ?? '');
+    const base = first.split(/[\\/]/).pop() ?? '';
+    if (base !== 'codex' && base !== 'codex.cmd' && base !== 'codex.exe')
+        return false;
+    const rest = words.slice(1);
+    if (!rest.includes('exec') && !rest.includes('e'))
+        return false;
+    // Once this is recognisably a Codex exec command, unsupported shell syntax
+    // must stay on the Codex path so preparation can refuse it. Treating it as a
+    // plain command would run the same Codex binary without the verified MCP
+    // boundary, exactly the failure this classifier exists to prevent.
+    if (codexShellSyntax(command, platform))
+        return true;
+    if (words.includes('--'))
+        return false;
+    // A host who already picked `resume` or `review` gets left alone entirely.
+    if (rest.includes('resume') || rest.includes('review'))
+        return false;
+    return !hasExplicitPrompt(words);
+}
+/**
+ * Shell syntax a shaped Codex command cannot safely preserve.
+ *
+ * Codex commands are eventually executed with `shell: true`, while the harness
+ * currently operates on whitespace-delimited words. Quotes, escapes,
+ * expansions, globs, comments and control/redirection operators all make those
+ * two views differ. Rather than guess at POSIX plus cmd.exe tokenization, only
+ * the deliberately boring argv-shaped subset is accepted. A matching command
+ * is still classified as Codex and then rejected before spawn.
+ */
+export function codexShellSyntax(command, platform = process.platform) {
+    // Backslash is a POSIX escape, but an ordinary path separator to cmd.exe.
+    // Windows's own expansion/escape characters (`%`, `^`, `!`) remain rejected,
+    // along with the control and quoting syntax shared by both shells.
+    const unsupported = platform === 'win32'
+        ? /['"$`|&;<>(){}*?\[\]~#\r\n%^!]/
+        : /['"\\$`|&;<>(){}*?\[\]~#\r\n%^!]/;
+    const match = unsupported.exec(command);
+    return match?.[0];
+}
+/**
+ * Does the command already carry a prompt of the host's own?
+ *
+ * Anything after the `exec` token that is not a flag, not a flag's value, and
+ * not the bare `-` stdin marker can only be Codex's one `[PROMPT]` positional.
+ */
+function hasExplicitPrompt(words) {
+    const execIndex = words.findIndex((word, index) => index > 0 && (word === 'exec' || word === 'e'));
+    if (execIndex === -1)
+        return false;
+    for (let i = execIndex + 1; i < words.length; i += 1) {
+        const word = words[i] ?? '';
+        if (word === '-' || word.startsWith('-'))
+            continue;
+        if (VALUE_TAKING_FLAGS.has(words[i - 1] ?? ''))
+            continue;
+        return true;
+    }
+    return false;
+}
+/**
+ * Flags that take a following value, for the bare-`-` scan below.
+ *
+ * Not a complete model of Codex's command line — just enough to tell the prompt
+ * positional `-` from a `-` that is somebody's argument.
+ */
+const VALUE_TAKING_FLAGS = new Set([
+    '-c',
+    '--config',
+    '-m',
+    '--model',
+    '-i',
+    '--image',
+    '-o',
+    '--output-last-message',
+    '-s',
+    '--sandbox',
+    '-C',
+    '--cd',
+    '-p',
+    '--profile',
+    '--add-dir',
+    '--output-schema',
+    '--color',
+    '--local-provider',
+    '--enable',
+    '--disable',
+]);
+/**
+ * Drop the prompt positional from the host's command.
+ *
+ * The README has recommended `codex exec -` since 0.2.0, and `codex exec -` is
+ * the form most people write anyway. We re-add the `-` ourselves at the very
+ * end, after any `resume <id>` — leaving the host's in place would make it the
+ * `SESSION_ID` positional and push `resume` into being a second one, which
+ * Codex rejects outright.
+ *
+ * A `-` that follows a value-taking flag is that flag's argument, not the
+ * prompt, so it stays.
+ */
+function withoutPromptPositional(words) {
+    return words.filter((word, index) => word !== '-' || VALUE_TAKING_FLAGS.has(words[index - 1] ?? ''));
+}
+/**
+ * Escape a value for a TOML basic string.
+ *
+ * The `-c` override is parsed as TOML, so the URL lands inside double quotes
+ * and has to survive that. Control characters are escaped rather than passed
+ * through because TOML rejects raw ones and the whole override would fail to
+ * parse — taking the agent's tools with it.
+ */
+function tomlString(value) {
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/[\u0000-\u001f\u007f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    return `"${escaped}"`;
+}
+/**
+ * The `-c` override that registers the ProhostAI MCP server.
+ *
+ * Codex takes a streamable-HTTP MCP server with **arbitrary** headers, which is
+ * what makes this possible at all: `codex mcp add --url` offers only
+ * `--bearer-token-env-var`, and a bearer token is the *wrong credential* for
+ * this endpoint — the server validates `Authorization: Bearer` as an OAuth
+ * access token, checks it first, and does not fall through to `X-API-Key` when
+ * it fails. A pairing hands out an `X-API-Key`. The `-c` path reaches the same
+ * config layer with none of that restriction.
+ *
+ * `env_http_headers` rather than `http_headers`: both work and both were
+ * verified against the running binary, but the former names an environment
+ * variable to read the value from instead of carrying the value itself, which
+ * keeps a live API key off a command line that anyone on the machine can read
+ * out of `ps`.
+ */
+export function prohostMcpEntry(mcpUrl) {
+    return (`${tomlString(MCP_SERVER_NAME)}={url=${tomlString(mcpUrl)}, ` +
+        `env_http_headers={"X-API-Key"=${tomlString(MCP_API_KEY_ENV_VAR)}}}`);
+}
+/**
+ * The whole `mcp_servers` override for a run, ProhostAI server included.
+ *
+ * It is one override, and it has to be: `-c` overrides are applied in order,
+ * and a later whole-table assignment **replaces** an earlier dotted one rather
+ * than merging with it. `-c mcp_servers.prohost={…} -c mcp_servers={…}` — the
+ * shape this had until it was measured — therefore drops the ProhostAI server
+ * outright, on every run that disables anything, while the harness went on
+ * logging "ProhostAI tools wired in" and the prompt went on telling the agent
+ * it had them. (Deep-merging is what happens between the CLI override and the
+ * *config file*, which is what made the wrong shape look right.)
+ */
+export function buildMcpOverride(mcpUrl) {
+    return mcpServersOverride([prohostMcpEntry(mcpUrl)]);
+}
+/**
+ * Encode a JSON value as a TOML inline value.
+ *
+ * Only needed for `extra-mcp.json`, whose entries are written by the operator
+ * in Claude Code's JSON shape and have to reach Codex through `-c`, which parses
+ * its value as TOML. Deliberately total over what JSON can hold and nothing
+ * more: a value it cannot represent returns `null` and the whole server is
+ * skipped with a warning, because a half-encoded table would not merely lose
+ * that server — a `-c` override that fails to parse takes the entire config
+ * down with it, ProhostAI server included.
+ *
+ * `null` is dropped from tables rather than encoded, TOML having no null.
+ */
+function tomlValue(value) {
+    if (typeof value === 'string')
+        return tomlString(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : null;
+    if (Array.isArray(value)) {
+        const items = value.map(tomlValue);
+        return items.some((item) => item === null) ? null : `[${items.join(', ')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const pairs = [];
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === null || entry === undefined)
+                continue;
+            const encoded = tomlValue(entry);
+            if (encoded === null)
+                return null;
+            pairs.push(`${tomlString(key)}=${encoded}`);
+        }
+        return `{${pairs.join(', ')}}`;
+    }
+    return null;
+}
+/**
+ * Turn `extra-mcp.json` entries into `mcp_servers` table fragments.
+ *
+ * The name is quoted rather than written as a dotted path, which is what lets
+ * *any* name work. `-c` splits on the first `=` and reads everything before it
+ * as a dotted path, so `-c mcp_servers.fly.io.enabled=false` addresses
+ * `mcp_servers.fly.io` — three segments, not two — and Codex rejects the whole
+ * config with `invalid transport in mcp_servers.fly`. Quoting the segment does
+ * not help either: `mcp_servers."fly.io"` fails the same way, because the
+ * splitting happens before any TOML is parsed. Putting the name inside the
+ * *value* sidesteps the path parser entirely.
+ *
+ * Claude's JSON shape carries literal `headers` and stdio `env` values. Those
+ * must not be copied literally into Codex's `-c` argument: command lines are
+ * readable by other local processes. Translate them to Codex's indirection
+ * fields and put the values in the child environment instead. `type` is also a
+ * Claude-only discriminator; Codex infers the transport from `url`/`command`.
+ */
+export function extraMcpEntries(servers, platform = process.platform) {
+    const entries = [];
+    const skipped = [];
+    const env = {};
+    let secretIndex = 0;
+    const stringRecord = (value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return null;
+        const pairs = Object.entries(value);
+        if (pairs.some(([, entry]) => typeof entry !== 'string'))
+            return null;
+        return Object.fromEntries(pairs);
+    };
+    // Literal headers need generated environment names. Reserve every name any
+    // extra already references *before* allocating one: otherwise an earlier
+    // header can claim PROHOST_EXTRA_MCP_SECRET_0 and a later extra's env_vars or
+    // env_http_headers can read that credential across the server boundary.
+    // Windows environment-variable lookup is case-insensitive. Keep the emitted
+    // spelling untouched, but compare identities the same way the child process
+    // will, so a lower-case alias cannot read the paired or generated credential.
+    const envNameKey = (name) => (platform === 'win32' ? name.toUpperCase() : name);
+    const prohibitedEnvName = envNameKey(MCP_API_KEY_ENV_VAR);
+    const isProhibitedEnvName = (name) => envNameKey(name) === prohibitedEnvName;
+    const reservedEnvNames = new Set([prohibitedEnvName]);
+    const assignedEnvValues = new Map();
+    for (const definition of Object.values(servers)) {
+        const declaredEnvVars = definition.env_vars;
+        if (Array.isArray(declaredEnvVars)) {
+            for (const name of declaredEnvVars) {
+                if (typeof name === 'string')
+                    reservedEnvNames.add(envNameKey(name));
+            }
+        }
+        const declaredHeaderEnv = stringRecord(definition.env_http_headers);
+        if (declaredHeaderEnv) {
+            for (const name of Object.values(declaredHeaderEnv))
+                reservedEnvNames.add(envNameKey(name));
+        }
+        const literalEnv = definition.env;
+        if (literalEnv && typeof literalEnv === 'object' && !Array.isArray(literalEnv)) {
+            for (const name of Object.keys(literalEnv))
+                reservedEnvNames.add(envNameKey(name));
+        }
+    }
+    const secretVariable = () => {
+        let variable;
+        do
+            variable = `PROHOST_EXTRA_MCP_SECRET_${secretIndex++}`;
+        while (reservedEnvNames.has(envNameKey(variable)) || assignedEnvValues.has(envNameKey(variable)));
+        reservedEnvNames.add(envNameKey(variable));
+        return variable;
+    };
+    for (const [name, original] of Object.entries(servers)) {
+        const definition = { ...original };
+        const definitionEnv = {};
+        let invalid = false;
+        delete definition.type;
+        const declaredHeaderEnv = definition.env_http_headers;
+        if (declaredHeaderEnv !== undefined) {
+            const indirect = stringRecord(declaredHeaderEnv);
+            if (indirect === null || Object.values(indirect).some(isProhibitedEnvName)) {
+                skipped.push(name);
+                continue;
+            }
+        }
+        const declaredEnvVars = definition.env_vars;
+        if (declaredEnvVars !== undefined &&
+            (!Array.isArray(declaredEnvVars) ||
+                declaredEnvVars.some((entry) => typeof entry !== 'string') ||
+                declaredEnvVars.some((entry) => typeof entry === 'string' && isProhibitedEnvName(entry)))) {
+            skipped.push(name);
+            continue;
+        }
+        const literalHeaders = definition.headers ?? definition.http_headers;
+        if (literalHeaders !== undefined) {
+            const headers = stringRecord(literalHeaders);
+            const existing = definition.env_http_headers;
+            const indirect = existing === undefined ? {} : stringRecord(existing);
+            if (headers === null || indirect === null) {
+                skipped.push(name);
+                continue;
+            }
+            if (Object.values(indirect).some(isProhibitedEnvName)) {
+                skipped.push(name);
+                continue;
+            }
+            for (const [header, value] of Object.entries(headers)) {
+                const variable = secretVariable();
+                definitionEnv[variable] = value;
+                indirect[header] = variable;
+            }
+            definition.env_http_headers = indirect;
+            delete definition.headers;
+            delete definition.http_headers;
+        }
+        if (definition.env !== undefined) {
+            const variables = stringRecord(definition.env);
+            const existing = definition.env_vars;
+            if (variables === null ||
+                (existing !== undefined &&
+                    (!Array.isArray(existing) || existing.some((entry) => typeof entry !== 'string')))) {
+                skipped.push(name);
+                continue;
+            }
+            const names = new Set(existing);
+            const definitionEnvNames = new Set(Object.keys(definitionEnv).map(envNameKey));
+            for (const [variable, value] of Object.entries(variables)) {
+                const envKey = envNameKey(variable);
+                const assignedValue = assignedEnvValues.get(envKey);
+                if (isProhibitedEnvName(variable) ||
+                    (assignedValue !== undefined && assignedValue !== value) ||
+                    definitionEnvNames.has(envKey)) {
+                    invalid = true;
+                    break;
+                }
+                definitionEnv[variable] = value;
+                definitionEnvNames.add(envKey);
+                names.add(variable);
+            }
+            if (invalid || [...names].some(isProhibitedEnvName)) {
+                skipped.push(name);
+                continue;
+            }
+            definition.env_vars = [...names];
+            delete definition.env;
+        }
+        const encoded = tomlValue(definition);
+        if (encoded === null) {
+            skipped.push(name);
+            continue;
+        }
+        entries.push(`${tomlString(name)}=${encoded}`);
+        for (const [variable, value] of Object.entries(definitionEnv)) {
+            if (value === undefined)
+                continue;
+            const envKey = envNameKey(variable);
+            if (!assignedEnvValues.has(envKey))
+                env[variable] = value;
+            assignedEnvValues.set(envKey, value);
+        }
+    }
+    return { entries, skipped, env };
+}
+/**
+ * Table fragments that switch off the servers the operator's Codex install has.
+ *
+ * This is the Codex answer to `--strict-mcp-config`, and it took a real binary
+ * to find. Two mechanisms that look like they should work do not: replacing the
+ * table wholesale does **not** replace it — Codex deep-merges config overrides,
+ * so the operator's servers survive alongside whatever the override adds — and
+ * `--ignore-user-config` does work but drops the operator's *entire* config
+ * with it, taking their model, profile and sandbox settings along for a
+ * security fix they did not ask to pay for that way.
+ *
+ * Setting `enabled=false` per server is the surgical one, verified end to end
+ * against `codex-cli 0.144.1`: the server is then reported `disabled` by
+ * `codex mcp list`, its own definition is left intact, other servers are
+ * untouched, and its tools are genuinely absent from the model's tool list
+ * mid-run.
+ *
+ * Names the extras file defines are left alone. Codex would deep-merge
+ * `enabled=false` into the operator's definition of the same name and produce a
+ * server the operator asked for twice and got zero times, which is a worse
+ * outcome than the collision itself.
+ */
+export function disableMcpEntries(configuredNames, keep = []) {
+    const kept = new Set([MCP_SERVER_NAME, ...keep]);
+    return configuredNames.filter((name) => !kept.has(name)).map((name) => `${tomlString(name)}={enabled=false}`);
+}
+/**
+ * Fold every entry into the single `-c mcp_servers={…}` override.
+ *
+ * One override rather than one per server, because they all reach the same
+ * table and Codex merges rather than replaces — so the combined form is
+ * equivalent, shorter on the command line, and (unlike the dotted-path form)
+ * imposes no constraint on what a server may be called.
+ */
+export function mcpServersOverride(entries) {
+    return entries.length > 0 ? `mcp_servers={${entries.join(', ')}}` : undefined;
+}
+/**
+ * Ask the binary what MCP servers it has, optionally under a `-c` override.
+ *
+ * Asking rather than parsing `~/.codex/config.toml` is deliberate twice over.
+ * `codex mcp list --json` already honours `CODEX_HOME` and the binary's normal
+ * config layering — and, measured on an ordinary install, it
+ * reports servers that appear **nowhere** in that file (plugins contribute
+ * their own). A config file we half-understand is exactly how an isolation
+ * guarantee ends up with a hole in it.
+ *
+ * Passing an override makes this a *verifier*: the listing then reflects the
+ * config the run would actually get, so "did the disable take" is a question
+ * with an answer rather than an assumption.
+ *
+ * The working directory is equally load-bearing. Codex discovers trusted
+ * project `.codex/config.toml` layers from cwd, so a probe in the harness's
+ * launch directory cannot certify a run executed in `$PROHOST_HOME/workspace`
+ * or an explicit `--workdir`. Every probe uses the eventual run cwd.
+ *
+ * Returns `null` — distinct from `[]` — when the question could not be
+ * answered, which for an override also means "that override does not load".
+ * The caller must treat the two differently: an empty list means there is
+ * nothing to disable, while `null` means we do not know, and a run that cannot
+ * enumerate must say so rather than claim an isolation it did not apply.
+ */
+export function listMcpServers(binary, runner, override, cwd) {
+    const command = override ? `${binary} mcp list --json -c ${shellQuote(override, process.platform)}` : `${binary} mcp list --json`;
+    let result;
+    try {
+        result = runner(command, cwd);
+    }
+    catch {
+        return null;
+    }
+    if (result.status !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (!Array.isArray(parsed))
+            return null;
+        const servers = [];
+        for (const entry of parsed) {
+            // Skipping an entry would turn an output shape we do not understand into
+            // "there is no server here". This parser is an isolation verifier, so one
+            // malformed item makes the entire answer unknown and the run fails closed.
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                return null;
+            const record = entry;
+            if (typeof record.name !== 'string' || record.name.length === 0)
+                return null;
+            servers.push({ name: record.name, enabled: record.enabled !== false });
+        }
+        return servers;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Disable entries, checked against the binary before they are used.
+ *
+ * Not paranoia — a measured failure. `{enabled=false}` merges onto a server's
+ * existing definition, and a server contributed by a **plugin** has no entry in
+ * `mcp_servers` to merge onto, so the override defines a table with no
+ * transport and Codex refuses the entire config: `invalid transport in
+ * mcp_servers.github`. Shipped unverified, that would not have leaked a
+ * server — it would have broken *every* run for anyone with a Codex plugin
+ * installed, which is a far worse outcome than the hole it was closing.
+ *
+ * So the entries are tried before they are trusted: one probe for the whole
+ * set, and only if that fails, one probe per server to find which ones can be
+ * disabled and which cannot. The happy path costs a single extra command per
+ * survey; the slow path is paid only by installs that need it.
+ *
+ * `failed` is the honest part. A server that cannot be disabled is still
+ * reachable from the run, and the caller has to say so out loud rather than
+ * report an isolation it only partly achieved.
+ */
+export function disableEntriesThatLoad(binary, runner, targets, cwd) {
+    if (targets.length === 0)
+        return { entries: [], failed: [] };
+    const disabled = (names) => {
+        const override = mcpServersOverride(disableMcpEntries(names));
+        if (!override)
+            return [];
+        const listing = listMcpServers(binary, runner, override, cwd);
+        // A config that does not load disables nothing, and a server the listing
+        // still reports as enabled was not disabled whatever the override said.
+        if (listing === null)
+            return [];
+        const off = new Set(listing.filter((server) => !server.enabled).map((server) => server.name));
+        return names.filter((name) => off.has(name));
+    };
+    const all = disabled(targets);
+    if (all.length === targets.length)
+        return { entries: disableMcpEntries(targets), failed: [] };
+    // The combined override was rejected, or took only partially. Fall back to
+    // asking about each server on its own, so one plugin-provided server cannot
+    // cost the isolation of every other server the operator has.
+    const usable = targets.filter((name) => disabled([name]).length === 1);
+    // Then ask again about the survivors *together*. Individually-valid entries
+    // combining into a valid one is an inference, and an inference is what put
+    // the unverified override in here to begin with — a combination Codex
+    // rejected would break every run rather than leak a server.
+    const verified = disabled(usable);
+    return {
+        entries: disableMcpEntries(verified),
+        failed: targets.filter((name) => !verified.includes(name)),
+    };
+}
+/**
+ * The `codex` binary out of the host's `--exec` command.
+ *
+ * The host may have written a path (`/opt/homebrew/bin/codex`), and the
+ * enumeration above has to ask the *same* binary the run will use — a different
+ * one on `PATH` could be a different version reading a different `CODEX_HOME`.
+ */
+export function codexBinary(command) {
+    return command.trim().split(/\s+/)[0] ?? 'codex';
+}
+/**
+ * Is the host running Codex under a named profile?
+ *
+ * Worth asking because it is a hole in the isolation that cannot be closed from
+ * here. `codex exec -p work` additionally loads `$CODEX_HOME/work.config.toml`,
+ * and `codex mcp list` has no way to be asked about a profile: `-p` and
+ * `--profile` are rejected outright, and `-c profile="work"` is refused as a
+ * removed legacy form. So a server defined only inside a profile is invisible
+ * to the enumeration and stays reachable from the run.
+ *
+ * Nothing here can fix that — reading the profile file ourselves is the
+ * config-parsing this deliberately avoids, and it is exactly how an isolation
+ * guarantee ends up with a hole nobody knows about. What it can do is tell the
+ * operator, which is what the caller does with this.
+ */
+export function codexProfileName(command) {
+    const words = command.trim().split(/\s+/);
+    for (let i = 0; i < words.length; i += 1) {
+        if (words[i] === '-p' || words[i] === '--profile')
+            return words[i + 1];
+        const long = /^--profile=(.+)$/.exec(words[i] ?? '');
+        if (long)
+            return long[1];
+        // clap accepts a short option's value joined to the flag (`-pwork`) and
+        // with an equals sign (`-p=work`). Missing these would let the real run load
+        // profile-only MCP servers while the profile-less probe certified the base
+        // config.
+        const short = /^-p=?(.+)$/.exec(words[i] ?? '');
+        if (short)
+            return short[1];
+    }
+    return undefined;
+}
+/**
+ * A host flag that can make the actual run's MCP inventory differ from the
+ * plain `codex mcp list` probe.
+ *
+ * Replaying arbitrary config arguments into a separate shell command would
+ * require parsing the operator's shell syntax exactly. Guessing is not an
+ * isolation boundary, so reject the small set of flags that can alter cwd,
+ * config, or plugin loading. `-C`/`--cd` matters because Codex discovers
+ * project-local config from the directory it runs in. Dedicated model/sandbox
+ * flags remain supported.
+ */
+export function codexMcpInventoryFlag(command) {
+    const words = command.trim().split(/\s+/);
+    for (const word of words) {
+        if (word === '-c' ||
+            /^-c(?:=)?.+/.test(word) ||
+            word === '--config' ||
+            word.startsWith('--config=') ||
+            word === '--enable' ||
+            word.startsWith('--enable=') ||
+            word === '--disable' ||
+            word.startsWith('--disable=') ||
+            word === '--ignore-user-config' ||
+            word === '-C' ||
+            /^-C(?:=)?.+/.test(word) ||
+            word === '--cd' ||
+            word.startsWith('--cd=')) {
+            return word;
+        }
+    }
+    return undefined;
+}
+/** Already present in the host's own command — never add a second one. */
+function has(words, ...flags) {
+    return flags.some((flag) => words.includes(flag));
+}
+/**
+ * Both spellings of "bypass approvals and the sandbox".
+ *
+ * `--yolo` is a hidden alias of the long form; Codex rejects the pair outright.
+ */
+const BYPASS_FLAGS = ['--yolo', '--dangerously-bypass-approvals-and-sandbox'];
+/**
+ * Append the flags this harness needs to a Codex command.
+ *
+ * Four things get added, and each one is load-bearing:
+ *
+ * `--json` turns stdout into a JSONL event stream, which is the only way to
+ * read the thread id back out (and so the only way sessions can continue).
+ *
+ * `--skip-git-repo-check` is not optional. The harness runs the agent in
+ * `$PROHOST_HOME/workspace`, which is not a git repository, and Codex refuses
+ * to start there — `Not inside a trusted directory and --skip-git-repo-check
+ * was not specified.` Without this flag **every** Codex run fails before the
+ * model is ever reached.
+ *
+ * `--yolo` mirrors Claude Code's `--dangerously-skip-permissions`, for the same
+ * reason: in a non-interactive run nobody is there to approve a command, so a
+ * sandboxed brain silently declines the work it was hired for. It is a hidden
+ * alias of `--dangerously-bypass-approvals-and-sandbox`, and passing both spells
+ * is a hard clap error (`cannot be used multiple times`) — so a host who already
+ * wrote either one must not get ours on top, or every run of theirs fails.
+ *
+ * `resume` goes **after** the host's own flags, not before them. `codex exec
+ * resume` accepts a strict subset of `codex exec`'s flags (no `-s`, `-C`,
+ * `--add-dir`, `-p`), and a flag placed after `resume` is parsed by `resume`.
+ * `codex exec -s workspace-write resume <id>` parses; `codex exec resume <id>
+ * -s workspace-write` is rejected. Appending keeps the host's flags where Codex
+ * still understands them.
+ */
+export function codexCommand(base, flags = {}) {
+    const platform = flags.platform ?? process.platform;
+    const quote = (value) => shellQuote(value, platform);
+    const gated = flags.skipPermissions === false;
+    // `--safe-tools` has to *remove* a bypass the host wrote, not merely decline
+    // to add one. Until 0.2.2 this README recommended `--exec 'codex exec -
+    // --yolo'`, so the flag is sitting in existing installs — and leaving it
+    // there would have the harness log "tools are permission-gated" and the
+    // prompt tell the agent that approvals will stop it, over a run that is in
+    // fact fully unsandboxed. A safety switch that quietly does nothing is worse
+    // than not having one.
+    const words = withoutPromptPositional(base.trim().split(/\s+/)).filter((word) => !gated || !BYPASS_FLAGS.includes(word));
+    const parts = [...words];
+    if (flags.sessionId)
+        parts.push('resume', quote(flags.sessionId));
+    if (!has(words, '--json'))
+        parts.push('--json');
+    if (!has(words, '--skip-git-repo-check'))
+        parts.push('--skip-git-repo-check');
+    if (!gated && !has(words, ...BYPASS_FLAGS)) {
+        parts.push('--yolo');
+    }
+    const override = mcpServersOverride(flags.mcpEntries ?? []);
+    if (override)
+        parts.push('-c', quote(override));
+    // The prompt arrives on stdin, and `-` is how Codex is told to read it.
+    // Explicit rather than implied: `codex exec` with no positional does read
+    // stdin, but `codex exec resume <id>` treats a missing positional as "no
+    // prompt", and it also prints a `Reading prompt from stdin...` banner that
+    // the `-` form suppresses.
+    parts.push('-');
+    return parts.join(' ');
+}
+/**
+ * Wording Codex uses when a tool call was refused rather than attempted.
+ *
+ * The verified string is `user cancelled MCP tool call`, emitted on a
+ * `mcp_tool_call` item with `status: "failed"` when there is no approver — the
+ * exact situation every run of this harness is in. The rest of the alternation
+ * is defensive: the phrasing is not ours to depend on across Codex versions,
+ * and the cost of matching one word too many is a log line, while the cost of
+ * matching one too few is the failure mode this whole function exists to end.
+ */
+const DENIAL_WORDING = /cancell?ed|rejected|denied|not (approved|permitted|allowed)|requires approval/i;
+function asObject(candidate) {
+    try {
+        const parsed = JSON.parse(candidate);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function text(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Pull a human-readable complaint out of whatever shape a failure event has. */
+function failureMessage(event) {
+    const error = event.error;
+    if (typeof error === 'string')
+        return text(error);
+    if (error && typeof error === 'object') {
+        const record = error;
+        return text(record.message) ?? text(record.reason);
+    }
+    return text(event.message);
+}
+/**
+ * Read the reply and the thread id out of `--json` stdout.
+ *
+ * Codex emits **JSONL**, not one object: `thread.started` (carrying
+ * `thread_id`), `turn.started`, an `item.completed` per item the turn produced,
+ * then `turn.completed`. Only `agent_message` items are the answer — reasoning
+ * and command items share the stream — and the last one is what a person would
+ * have seen at the end of the run.
+ *
+ * Lines that are not JSON are skipped rather than treated as corruption,
+ * because they are *expected*: an unreachable MCP server puts `ERROR
+ * rmcp::transport::worker: …` straight into this stream, and the run around it
+ * succeeds normally. This was observed, not guessed at.
+ *
+ * As in `parseClaudeOutput`, output with no reply in it is a **failure** rather
+ * than a fallback to posting the raw text. We asked for JSON; anything else
+ * means something went wrong that we do not understand, and the one thing that
+ * must not happen is that reaching a customer's conversation.
+ *
+ * Refused tool calls come back too, as the Codex counterpart of Claude Code's
+ * `permission_denials`. Codex has no such field, but it does emit the fact: a
+ * refused call is an `item.completed` carrying a `mcp_tool_call` with
+ * `status: "failed"` and `error.message: "user cancelled MCP tool call"`, which
+ * is what a run with nobody at the terminal gets every time. Names are spelled
+ * `mcp__<server>__<tool>` so the harness's log line reads identically whichever
+ * brain produced it — and because that is genuinely how Codex names the tool to
+ * the model (verified against 0.144.1, same convention as Claude Code).
+ */
+export function parseCodexOutput(stdout) {
+    let sessionId;
+    let reply;
+    let failure;
+    const denials = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith('{'))
+            continue;
+        const event = asObject(trimmed);
+        if (!event)
+            continue;
+        const type = event.type;
+        if (type === 'thread.started') {
+            sessionId = text(event.thread_id) ?? sessionId;
+            continue;
+        }
+        if (type === 'turn.failed' || type === 'error') {
+            failure = failureMessage(event) ?? failure ?? 'codex reported a failed turn';
+            continue;
+        }
+        if (type === 'item.completed') {
+            const item = event.item;
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const record = item;
+                // Last one wins: a turn can emit several, and the final one is the
+                // answer the run ended on.
+                if (record.type === 'agent_message')
+                    reply = text(record.text) ?? reply;
+                const denied = denialName(record);
+                if (denied && !denials.includes(denied))
+                    denials.push(denied);
+            }
+        }
+    }
+    // A failed turn that still produced a message is a failure. The message in
+    // that case is the explanation ("I ran out of…"), not an answer, and posting
+    // it would put the failure in front of a customer as if the agent had chosen
+    // to say it.
+    if (failure)
+        return { ok: false, sessionId, denials, error: failure };
+    if (reply)
+        return { ok: true, sessionId, denials, text: reply };
+    const sample = stdout.trim().slice(0, 200);
+    return {
+        ok: false,
+        sessionId,
+        denials,
+        error: sample
+            ? `codex produced no agent message (asked for --json). First 200 chars: ${sample}`
+            : 'codex returned no output',
+    };
+}
+/**
+ * Name the tool this item was refused, or `undefined` if it wasn't refused.
+ *
+ * A *failed* call is not a *denied* one — an MCP server that 500s also lands
+ * here — so the error text has to say refusal before this reports one.
+ * Over-reporting would put "the agent was refused these tools" in the log for a
+ * server that was merely down, sending the operator to their permissions when
+ * the problem is their network.
+ */
+function denialName(item) {
+    if (item.status !== 'failed')
+        return undefined;
+    const error = item.error;
+    const message = typeof error === 'string' ? error : error && typeof error === 'object' ? text(error.message) : undefined;
+    if (!message || !DENIAL_WORDING.test(message))
+        return undefined;
+    if (item.type === 'mcp_tool_call') {
+        const server = text(item.server);
+        const tool = text(item.tool);
+        if (server && tool)
+            return `mcp__${server}__${tool}`;
+        if (tool)
+            return tool;
+    }
+    // Only the MCP shape above was verified against a real binary. Anything else
+    // that reports itself refused is still worth naming — by its item type, which
+    // is the only handle we can be sure of — rather than dropped for not matching
+    // a shape we have seen.
+    return text(item.type);
+}
+/**
+ * Does this look like the resume having been rejected, rather than the agent
+ * having failed at its actual work?
+ *
+ * Two ways a Codex resume can fail where a fresh run would have worked: the
+ * thread is gone (rollout files get cleaned up and the ledger cannot know), or
+ * the host's own flags are ones `codex exec resume` does not accept, which clap
+ * reports as `unexpected argument`. Both must degrade to a fresh session
+ * instead of breaking that surface forever.
+ *
+ * The `thread.started` guard is what keeps this from firing on an ordinary bad
+ * turn. Codex echoes the thread id in that event on **success**, so the
+ * "output mentions the session id" heuristic — which is all `claude.ts` can
+ * do — would match a resumed run that started fine and then failed at its
+ * work, and retrying that runs the agent, and its tools, a second time for
+ * nothing.
+ */
+export function looksLikeCodexResumeFailure(output, sessionId) {
+    if (!sessionId)
+        return false;
+    if (/"type"\s*:\s*"thread\.started"/.test(output))
+        return false;
+    if (/unexpected argument|unrecognized subcommand|invalid value|error: unexpected/i.test(output)) {
+        return true;
+    }
+    // The first branch is the message the binary actually prints for a thread it
+    // no longer has on disk, captured from a real run:
+    //   Error: thread/resume: thread/resume failed: no rollout found for thread
+    //   id <uuid> (code -32600)
+    // The rest are broader, because the wording is not ours to depend on.
+    if (/no rollout found|no (conversation|session|thread)[^\n]{0,40}found|(session|thread)[^\n]{0,40}not found|resume[^\n]{0,20}(failed|invalid|expired)/i.test(output)) {
+        return true;
+    }
+    return output.includes(sessionId);
+}