humanish 0.105.0 → 0.106.0

package/dist/actors/codex/app-server.js

@@ -0,0 +1,268 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { digestText, tailText } from "../../evidence/redaction.js";
+import { prepareContainedOutputDirectory, prepareContainedOutputFile, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { CodexStdioClient } from "./app-server-client.js";
+import { CodexTraceRecorder, isRecord, readNestedString, redactCodexEnvelope, renderTranscript, } from "./app-server-trace.js";
+export async function runCodexAppServerSession(options) {
+    const preparedRunRoot = await prepareSelectedOutputDirectory(process.cwd(), options.runRoot);
+    return runCodexAppServerSessionInPreparedRoot(options, preparedRunRoot);
+}
+/** Internal UI seam: the selected root was already prepared and must not be re-authorized. */
+export async function runCodexAppServerSessionInPreparedRoot(options, runRoot) {
+    const startedAt = new Date();
+    const startedMs = Date.now();
+    const artifacts = CODEX_APP_SERVER_ARTIFACTS;
+    await prepareContainedOutputDirectory(runRoot, CODEX_APP_SERVER_DIRECTORY);
+    await Promise.all([
+        prepareContainedOutputFile(runRoot, artifacts.eventsPath),
+        prepareContainedOutputFile(runRoot, artifacts.tracePath),
+        prepareContainedOutputFile(runRoot, artifacts.transcriptPath),
+    ]);
+    const commandParts = resolveAppServerCommand(options.actorCommand);
+    const childEnv = resolveCodexAppServerEnv(process.env);
+    const apiKey = appServerApiKeyForLogin(childEnv);
+    const child = spawn(commandParts.command, commandParts.args, {
+        cwd: options.cwd,
+        env: childEnv,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const recorder = new CodexTraceRecorder({
+        commandName: commandParts.name,
+        cwd: options.cwd,
+        experimentalApi: options.experimentalApi === true,
+        promptDigest: digestText(options.prompt),
+        startedAt: startedAt.toISOString(),
+    });
+    const envelopes = [];
+    let completed = false;
+    let timedOut = false;
+    let completionStatus;
+    let completionReason = "Codex app-server turn did not complete.";
+    const client = new CodexStdioClient(child, `${commandParts.command} ${commandParts.args.join(" ")}`.trim(), recordingHandlers(recorder, envelopes, options.cwd, (message) => {
+        if (message.method === "thread/started")
+            recorder.recordThread(isRecord(message.params) ? message.params.thread : undefined);
+        if (message.method === "turn/started")
+            recorder.turnId = readNestedString(message, ["params", "turn", "id"]) ?? recorder.turnId;
+        if (message.method === "turn/completed") {
+            completionStatus = readNestedString(message, ["params", "turn", "status"]);
+            completionReason = completionStatus
+                ? `turn completed with status ${completionStatus}`
+                : "turn completed";
+            completed = true;
+            child.kill("SIGTERM");
+        }
+    }));
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        setTimeout(() => child.kill("SIGKILL"), 2_000).unref();
+    }, options.timeoutMs);
+    timeout.unref();
+    const finish = async (status, reason) => {
+        clearTimeout(timeout);
+        client.rejectPending(reason);
+        const trace = recorder.buildTrace({
+            completedAt: new Date().toISOString(),
+            durationMs: Date.now() - startedMs,
+            reason,
+            status,
+        });
+        return writeRunArtifacts(runRoot, artifacts, envelopes, trace, client, status, reason);
+    };
+    try {
+        const initialize = client.request("initialize", {
+            clientInfo: {
+                name: "humanish_cli",
+                title: "Humanish CLI",
+                version: "0.1.0",
+            },
+            capabilities: {
+                experimentalApi: options.experimentalApi === true,
+            },
+        });
+        client.notify("initialized", {});
+        await client.response(initialize, "initialize");
+        if (apiKey) {
+            await client.response(client.request("account/login/start", {
+                type: "apiKey",
+                apiKey,
+            }), "account/login/start");
+        }
+        const threadResponse = await client.response(client.request("thread/start", {
+            cwd: options.cwd,
+            approvalPolicy: normalizeApprovalPolicy(options.approvalPolicy),
+            sandbox: normalizeSandbox(options.sandbox),
+            serviceName: options.serviceName ?? "humanish",
+            ...(options.model === undefined ? {} : { model: options.model }),
+        }), "thread/start");
+        recorder.recordThread(threadResponse.thread, options.model);
+        const threadId = recorder.threadId;
+        if (!threadId) {
+            throw new Error("thread/start did not return a thread id");
+        }
+        const turnResponse = await client.response(client.request("turn/start", {
+            threadId,
+            cwd: options.cwd,
+            approvalPolicy: normalizeApprovalPolicy(options.approvalPolicy),
+            sandboxPolicy: normalizeTurnSandbox(options.sandbox, options.cwd),
+            input: [{ type: "text", text: options.prompt, text_elements: [] }],
+        }), "turn/start");
+        recorder.turnId = readNestedString(turnResponse, ["turn", "id"]) ?? recorder.turnId;
+        // turn/completed and the timeout both signal the child, so every outcome waits for it to close.
+        await client.closed;
+        if (timedOut) {
+            return finish("timed_out", `Codex app-server turn exceeded ${options.timeoutMs}ms timeout.`);
+        }
+        if (completed) {
+            const status = completionStatus === "completed"
+                ? "passed"
+                : completionStatus === "failed"
+                    ? "failed"
+                    : "blocked";
+            return finish(status, completionReason);
+        }
+        return finish(client.exitCode === 0 ? "passed" : "blocked", `Codex app-server process exited before turn completion${client.exitCode === undefined ? "" : ` with code ${client.exitCode}`}.`);
+    }
+    catch (error) {
+        child.kill("SIGTERM");
+        await client.closed;
+        return finish("blocked", error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Client handlers that put every message into the trace and the redacted event log, decline server
+ * requests by default, and pass notifications to `notification`.
+ */
+function recordingHandlers(recorder, envelopes, cwd, notification) {
+    return {
+        envelope: (direction, message) => {
+            const redacted = redactCodexEnvelope(message, cwd);
+            recorder.observeEnvelope(direction, redacted);
+            envelopes.push(JSON.stringify({ at: new Date().toISOString(), direction, message: redacted }));
+            if (direction === "server")
+                recorder.observeServerMessage(message);
+        },
+        serverRequest: (message) => {
+            const result = defaultServerRequestResponse(message);
+            recorder.recordApproval(message, result);
+            return result;
+        },
+        notification,
+        warning: (source, message) => recorder.addWarning(source, message),
+        error: (source, message) => recorder.addError(source, message),
+    };
+}
+export const CODEX_APP_SERVER_DIRECTORY = "codex-app-server";
+export const CODEX_APP_SERVER_ARTIFACTS = {
+    eventsPath: path.join(CODEX_APP_SERVER_DIRECTORY, "events.ndjson"),
+    tracePath: path.join(CODEX_APP_SERVER_DIRECTORY, "summary.json"),
+    transcriptPath: path.join(CODEX_APP_SERVER_DIRECTORY, "transcript.txt"),
+};
+/** Writes events.ndjson, summary.json and transcript.txt, then returns the result that names them. */
+async function writeRunArtifacts(runRoot, artifacts, envelopes, trace, exit, status, reason) {
+    const transcriptText = renderTranscript(trace);
+    await writeContainedOutputFile(runRoot, artifacts.eventsPath, `${envelopes.join("\n")}${envelopes.length > 0 ? "\n" : ""}`, "utf8");
+    await writeContainedOutputFile(runRoot, artifacts.tracePath, `${JSON.stringify(trace, null, 2)}\n`, "utf8");
+    await writeContainedOutputFile(runRoot, artifacts.transcriptPath, transcriptText.length > 0
+        ? transcriptText
+        : "No Codex app-server transcript output captured.\n", "utf8");
+    return {
+        status,
+        reason,
+        durationMs: trace.durationMs,
+        ...(exit.exitCode === undefined ? {} : { exitCode: exit.exitCode }),
+        ...(exit.signal === undefined ? {} : { signal: exit.signal }),
+        ...(trace.threadId === undefined ? {} : { threadId: trace.threadId }),
+        ...(trace.turnId === undefined ? {} : { turnId: trace.turnId }),
+        ...(trace.sessionId === undefined ? {} : { sessionId: trace.sessionId }),
+        ...(trace.model === undefined ? {} : { model: trace.model }),
+        ...(trace.server.codexCliVersion === undefined
+            ? {}
+            : { codexCliVersion: trace.server.codexCliVersion }),
+        experimentalApi: trace.client.experimentalApi,
+        counts: trace.counts,
+        tail: tailText(transcriptText, 6_000),
+        trace,
+        ...artifacts,
+    };
+}
+function resolveAppServerCommand(overrideCommand) {
+    const commandParts = overrideCommand && overrideCommand.length > 0
+        ? overrideCommand
+        : ["codex", "app-server", "--listen", "stdio://"];
+    const [command, ...args] = commandParts;
+    return {
+        command: command ?? "codex",
+        args,
+        name: path.basename(command ?? "codex"),
+    };
+}
+function resolveCodexAppServerEnv(env) {
+    const privateApiKey = env.HUMANISH_PRIVATE_CODEX_API_KEY?.trim();
+    const privateAccessToken = env.HUMANISH_PRIVATE_CODEX_ACCESS_TOKEN?.trim();
+    return {
+        ...env,
+        TERM: env.TERM ?? "xterm-256color",
+        ...(privateApiKey && !env.CODEX_API_KEY ? { CODEX_API_KEY: privateApiKey } : {}),
+        ...(privateApiKey && !env.OPENAI_API_KEY ? { OPENAI_API_KEY: privateApiKey } : {}),
+        ...(privateAccessToken && !env.CODEX_ACCESS_TOKEN
+            ? { CODEX_ACCESS_TOKEN: privateAccessToken }
+            : {}),
+    };
+}
+function appServerApiKeyForLogin(env) {
+    return (env.HUMANISH_PRIVATE_CODEX_API_KEY?.trim() ||
+        env.CODEX_API_KEY?.trim() ||
+        env.OPENAI_API_KEY?.trim() ||
+        undefined);
+}
+function defaultServerRequestResponse(message) {
+    switch (message.method) {
+        case "item/commandExecution/requestApproval":
+            return { decision: "decline" };
+        case "item/fileChange/requestApproval":
+            return { decision: "decline" };
+        case "applyPatchApproval":
+        case "execCommandApproval":
+            return { decision: "denied" };
+        case "item/tool/requestUserInput":
+            return { answers: {} };
+        case "mcpServer/elicitation/request":
+            return { action: "decline" };
+        default:
+            return {};
+    }
+}
+function normalizeApprovalPolicy(value) {
+    if (value === "on-failure")
+        return "on-failure";
+    if (value === "on-request")
+        return "on-request";
+    if (value === "untrusted")
+        return "untrusted";
+    return "never";
+}
+function normalizeSandbox(value) {
+    if (value === "danger-full-access")
+        return "danger-full-access";
+    if (value === "workspace-write")
+        return "workspace-write";
+    return "read-only";
+}
+function normalizeTurnSandbox(value, cwd) {
+    const mode = normalizeSandbox(value);
+    if (mode === "workspace-write") {
+        return {
+            type: "workspaceWrite",
+            writableRoots: [cwd],
+            networkAccess: false,
+            excludeTmpdirEnvVar: false,
+            excludeSlashTmp: false,
+        };
+    }
+    if (mode === "danger-full-access") {
+        return { type: "dangerFullAccess" };
+    }
+    return { type: "readOnly", networkAccess: false };
+}

package/dist/actors/codex/qualified-versions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Codex CLI releases the restricted launcher admits, per host, oldest first. Each qualified
+ * release needs a receipt under docs/goals/computer-use-actor/receipts/ that meets
+ * docs/architecture/restricted-codex-analysis.md ("Admitting a Codex CLI release"). Removing a
+ * release stops new launches; saved bundles stay readable through the separate reader lists in
+ * src/actors/contract.ts.
+ *
+ * A release string is a compatibility check, not binary attestation: the launcher compares what
+ * `codex --version`, initialize and thread start report, and a modified binary can report any
+ * of them.
+ */
+export declare const QUALIFIED_CODEX_CLI_VERSIONS: {
+    readonly "linux-x64": readonly ["0.154.0", "0.157.1", "0.159.2", "0.159.3"];
+    readonly "darwin-arm64": readonly ["0.154.0"];
+};
+/**
+ * The pre-existing admission, not a qualification. Hosted participants on these hosts ran
+ * 0.154.0 while it was the only admitted release, and they keep it; no qualification has run
+ * on either host, and no later release is admitted there.
+ */
+export declare const PREEXISTING_CODEX_CLI_ADMISSIONS: {
+    readonly "linux-arm64": readonly ["0.154.0"];
+    readonly "darwin-x64": readonly ["0.154.0"];
+};
+type QualifiedHost = keyof typeof QUALIFIED_CODEX_CLI_VERSIONS;
+type PreexistingHost = keyof typeof PREEXISTING_CODEX_CLI_ADMISSIONS;
+export type CodexHost = QualifiedHost | PreexistingHost;
+export type AdmittedCodexCliVersion = (typeof QUALIFIED_CODEX_CLI_VERSIONS)[QualifiedHost][number] | (typeof PREEXISTING_CODEX_CLI_ADMISSIONS)[PreexistingHost][number];
+export declare function codexHost(platform: NodeJS.Platform, arch: string): CodexHost | undefined;
+/** Releases that passed qualification on this host; the pre-existing admission is excluded. */
+export declare function qualifiedCodexCliVersions(platform: NodeJS.Platform, arch: string): readonly AdmittedCodexCliVersion[];
+/** Everything the launcher starts on this host: qualified releases or the pre-existing one. */
+export declare function admittedCodexCliVersions(platform: NodeJS.Platform, arch: string): readonly AdmittedCodexCliVersion[];
+/** What a declaration names before the installed CLI is detected: the host's newest release. */
+export declare function defaultCodexCliVersion(platform?: NodeJS.Platform, arch?: string): AdmittedCodexCliVersion;
+/** The version from `codex --version` output (`codex-cli 0.157.1`); any other shape is undefined. */
+export declare function parseCodexCliVersion(stdout: string): string | undefined;
+/**
+ * doctor's recovery for an unadmitted CLI: the release it found, what this host admits, and the
+ * exact command that installs the newest admitted release.
+ */
+export declare function codexVersionRecovery(detected: string | undefined, platform?: NodeJS.Platform, arch?: string): string;
+/** For refusal messages: the admitted releases on this host, or every host when it has none. */
+export declare function describeQualifiedCodexCliVersions(platform?: NodeJS.Platform, arch?: string): string;
+export {};

package/dist/actors/codex/qualified-versions.js

@@ -0,0 +1,87 @@
+/**
+ * Codex CLI releases the restricted launcher admits, per host, oldest first. Each qualified
+ * release needs a receipt under docs/goals/computer-use-actor/receipts/ that meets
+ * docs/architecture/restricted-codex-analysis.md ("Admitting a Codex CLI release"). Removing a
+ * release stops new launches; saved bundles stay readable through the separate reader lists in
+ * src/actors/contract.ts.
+ *
+ * A release string is a compatibility check, not binary attestation: the launcher compares what
+ * `codex --version`, initialize and thread start report, and a modified binary can report any
+ * of them.
+ */
+export const QUALIFIED_CODEX_CLI_VERSIONS = {
+    "linux-x64": ["0.154.0", "0.157.1", "0.159.2", "0.159.3"],
+    "darwin-arm64": ["0.154.0"],
+};
+/**
+ * The pre-existing admission, not a qualification. Hosted participants on these hosts ran
+ * 0.154.0 while it was the only admitted release, and they keep it; no qualification has run
+ * on either host, and no later release is admitted there.
+ */
+export const PREEXISTING_CODEX_CLI_ADMISSIONS = {
+    "linux-arm64": ["0.154.0"],
+    "darwin-x64": ["0.154.0"],
+};
+const HOST_LABELS = {
+    "linux-x64": "Linux x64",
+    "darwin-arm64": "macOS arm64",
+    "linux-arm64": "Linux arm64",
+    "darwin-x64": "macOS x64",
+};
+export function codexHost(platform, arch) {
+    const host = `${platform}-${arch}`;
+    return Object.hasOwn(QUALIFIED_CODEX_CLI_VERSIONS, host) ||
+        Object.hasOwn(PREEXISTING_CODEX_CLI_ADMISSIONS, host)
+        ? host
+        : undefined;
+}
+/** Releases that passed qualification on this host; the pre-existing admission is excluded. */
+export function qualifiedCodexCliVersions(platform, arch) {
+    const host = codexHost(platform, arch);
+    return host !== undefined && Object.hasOwn(QUALIFIED_CODEX_CLI_VERSIONS, host)
+        ? QUALIFIED_CODEX_CLI_VERSIONS[host]
+        : [];
+}
+/** Everything the launcher starts on this host: qualified releases or the pre-existing one. */
+export function admittedCodexCliVersions(platform, arch) {
+    const host = codexHost(platform, arch);
+    if (host === undefined)
+        return [];
+    return Object.hasOwn(QUALIFIED_CODEX_CLI_VERSIONS, host)
+        ? QUALIFIED_CODEX_CLI_VERSIONS[host]
+        : PREEXISTING_CODEX_CLI_ADMISSIONS[host];
+}
+/** What a declaration names before the installed CLI is detected: the host's newest release. */
+export function defaultCodexCliVersion(platform = process.platform, arch = process.arch) {
+    return (admittedCodexCliVersions(platform, arch).at(-1) ??
+        QUALIFIED_CODEX_CLI_VERSIONS["linux-x64"].at(-1));
+}
+/** The version from `codex --version` output (`codex-cli 0.157.1`); any other shape is undefined. */
+export function parseCodexCliVersion(stdout) {
+    return /^codex-cli ([0-9][0-9A-Za-z.+-]{0,63})$/.exec(stdout.trim())?.[1];
+}
+function describeHost(host) {
+    return Object.hasOwn(QUALIFIED_CODEX_CLI_VERSIONS, host)
+        ? QUALIFIED_CODEX_CLI_VERSIONS[host].join(", ")
+        : `${PREEXISTING_CODEX_CLI_ADMISSIONS[host].join(", ")} (pre-existing admission, not qualified)`;
+}
+/**
+ * doctor's recovery for an unadmitted CLI: the release it found, what this host admits, and the
+ * exact command that installs the newest admitted release.
+ */
+export function codexVersionRecovery(detected, platform = process.platform, arch = process.arch) {
+    const found = detected === undefined
+        ? "The installed Codex CLI did not report a recognizable version"
+        : `Found Codex CLI ${detected}`;
+    const install = `npm install -g @openai/codex@${defaultCodexCliVersion(platform, arch)}`;
+    return `${found}; ${describeQualifiedCodexCliVersions(platform, arch)}. Install the newest with \`${install}\`, then sign in with a ChatGPT account (\`codex login\`).`;
+}
+/** For refusal messages: the admitted releases on this host, or every host when it has none. */
+export function describeQualifiedCodexCliVersions(platform = process.platform, arch = process.arch) {
+    const host = codexHost(platform, arch);
+    if (host !== undefined)
+        return `${HOST_LABELS[host]} accepts Codex CLI ${describeHost(host)}`;
+    return Object.keys(HOST_LABELS)
+        .map((key) => `${HOST_LABELS[key]}: ${describeHost(key)}`)
+        .join("; ");
+}

package/dist/actors/codex/restricted-executable.d.ts

@@ -0,0 +1,17 @@
+import { type RestrictedCodexDeadline, type RestrictedCodexSpawn } from "./restricted-transport.js";
+/** The environment of every Codex child: a private home and scratch, and PATH and locale. */
+export declare function childEnvironment(source: NodeJS.ProcessEnv, home: string, scratch: string): NodeJS.ProcessEnv;
+/** Official npm launcher target map for the Unix hosts supported by this transport. */
+export declare function restrictedCodexNpmTarget(platform: NodeJS.Platform, arch: string): {
+    triple: string;
+    packageName: string;
+} | undefined;
+/** Resolve PATH without running a shell. The npm launcher is resolved to its
+ * native optional package so cleanup owns the real app-server child. */
+export declare function resolveExecutable(options: {
+    executable?: string;
+    platform?: NodeJS.Platform;
+    arch?: string;
+}, env: NodeJS.ProcessEnv): Promise<string>;
+/** Returns the detected release after checking it against the admitted list. */
+export declare function checkVersion(file: string, env: NodeJS.ProcessEnv, cwd: string, spawnFn: RestrictedCodexSpawn, deadline: RestrictedCodexDeadline, admitted: readonly string[], expected: string | undefined): Promise<string>;

package/dist/actors/codex/restricted-executable.js

@@ -0,0 +1,147 @@
+// Finding and admitting the Codex CLI a restricted launch runs: the native executable behind PATH
+// or the npm launcher, the environment its children get, and the `--version` check against the
+// host's admitted releases.
+import { constants } from "node:fs";
+import { access, open, realpath } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { parseCodexCliVersion } from "./qualified-versions.js";
+import { RestrictedCodexStop, closeOwnedCodexProcess, ownCodexProcess, retainUnclosedChild, } from "./restricted-transport.js";
+/** The environment of every Codex child: a private home and scratch, and PATH and locale. */
+export function childEnvironment(source, home, scratch) {
+    const result = { HOME: home, CODEX_HOME: home, TMPDIR: scratch };
+    for (const key of ["PATH", "LANG", "USER", "LOGNAME"])
+        if (typeof source[key] === "string")
+            result[key] = source[key];
+    return result;
+}
+async function isNativeExecutable(file, platform) {
+    try {
+        await access(file, constants.X_OK);
+        const handle = await open(file, "r");
+        try {
+            const buffer = Buffer.alloc(4);
+            const read = await handle.read(buffer, 0, 4, 0);
+            return (read.bytesRead === 4 &&
+                (platform === "darwin"
+                    ? ["cffaedfe", "feedfacf", "cafebabe", "bebafeca", "cafebabf"].includes(buffer.toString("hex"))
+                    : buffer.equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46]))));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** Official npm launcher target map for the Unix hosts supported by this transport. */
+export function restrictedCodexNpmTarget(platform, arch) {
+    if (platform === "linux" && arch === "x64")
+        return { triple: "x86_64-unknown-linux-musl", packageName: "codex-linux-x64" };
+    if (platform === "linux" && arch === "arm64")
+        return { triple: "aarch64-unknown-linux-musl", packageName: "codex-linux-arm64" };
+    if (platform === "darwin" && arch === "x64")
+        return { triple: "x86_64-apple-darwin", packageName: "codex-darwin-x64" };
+    if (platform === "darwin" && arch === "arm64")
+        return { triple: "aarch64-apple-darwin", packageName: "codex-darwin-arm64" };
+    return undefined;
+}
+/** Resolve PATH without running a shell. The npm launcher is resolved to its
+ * native optional package so cleanup owns the real app-server child. */
+export async function resolveExecutable(options, env) {
+    const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
+    let selected = options.executable;
+    if (selected === undefined) {
+        for (const directory of (env.PATH ?? "")
+            .split(path.delimiter)
+            .filter((entry) => path.isAbsolute(entry))) {
+            const candidate = path.join(directory, "codex");
+            try {
+                await access(candidate, constants.X_OK);
+                selected = candidate;
+                break;
+            }
+            catch {
+                /* Continue PATH. */
+            }
+        }
+    }
+    if (selected === undefined || !path.isAbsolute(selected))
+        throw new RestrictedCodexStop("codex_unavailable");
+    let resolved;
+    try {
+        resolved = await realpath(selected);
+    }
+    catch {
+        throw new RestrictedCodexStop("codex_unavailable");
+    }
+    if (await isNativeExecutable(resolved, platform))
+        return resolved;
+    if (path.basename(resolved) === "codex.js" && path.basename(path.dirname(resolved)) === "bin") {
+        const packageRoot = path.dirname(path.dirname(resolved));
+        const target = restrictedCodexNpmTarget(platform, arch);
+        if (!target)
+            throw new RestrictedCodexStop("codex_unavailable");
+        const { triple, packageName: nativePackage } = target;
+        const candidates = [];
+        try {
+            // Match the npm launcher's resolution: optional packages may be hoisted or
+            // linked by the package manager rather than nested inside @openai/codex.
+            const manifest = createRequire(resolved).resolve(`@openai/${nativePackage}/package.json`);
+            candidates.push(path.join(path.dirname(manifest), "vendor", triple, "bin", "codex"));
+        }
+        catch {
+            /* Older packages may bundle the native executable directly. */
+        }
+        candidates.push(path.join(packageRoot, "vendor", triple, "bin", "codex"));
+        for (const candidate of candidates) {
+            if (await isNativeExecutable(candidate, platform))
+                return realpath(candidate);
+        }
+    }
+    throw new RestrictedCodexStop("codex_unavailable");
+}
+/** Returns the detected release after checking it against the admitted list. */
+export async function checkVersion(file, env, cwd, spawnFn, deadline, admitted, expected) {
+    deadline.check();
+    const owned = ownCodexProcess(spawnFn(file, ["--version"], { cwd, env, detached: false, stdio: ["pipe", "pipe", "pipe"] }));
+    let text = "", bytes = 0, exitCode = null;
+    const timer = setTimeout(() => deadline.stop("timeout"), 15_000);
+    owned.child.on("error", () => deadline.stop("codex_unavailable"));
+    owned.child.stdin.on("error", () => deadline.stop("codex_unavailable"));
+    owned.child.stdout.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 4096)
+            deadline.stop("response_too_large");
+        else
+            text += chunk.toString("utf8");
+    });
+    owned.child.stderr.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 4096)
+            deadline.stop("response_too_large");
+    });
+    owned.child.on("exit", (code) => {
+        exitCode = code;
+    });
+    try {
+        await deadline.wait(owned.closed);
+        if (exitCode !== 0)
+            throw new RestrictedCodexStop("codex_unavailable");
+        const version = parseCodexCliVersion(text);
+        if (version === undefined ||
+            !admitted.includes(version) ||
+            (expected !== undefined && version !== expected))
+            throw new RestrictedCodexStop("codex_unsupported_version", version);
+        return version;
+    }
+    finally {
+        clearTimeout(timer);
+        if (!(await closeOwnedCodexProcess(owned))) {
+            retainUnclosedChild(owned.closed);
+            // oxlint-disable-next-line no-unsafe-finally -- a Codex process that did not close invalidates the version check
+            throw new RestrictedCodexStop("codex_cleanup_failed");
+        }
+    }
+}