humanish 0.100.0 → 0.101.0

package/dist/restricted-codex-session.js

@@ -4,7 +4,7 @@ import { access, chmod, lstat, mkdir, mkdtemp, open, readdir, realpath, rm, stat
 import { homedir, tmpdir } from "node:os";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { CODEX_IMAGE, CODEX_MAX_OUTPUT_BYTES, RESTRICTED_CODEX_ANALYSIS_IDENTITY, RESTRICTED_CODEX_ANALYSIS_MODELS, admitsRestrictedCodexConfig, admitsRestrictedCodexThread, codexRecord, restrictedCodexConfig, restrictedCodexFailure, restrictedCodexRequestError, restrictedCodexUsage } from "./restricted-codex-policy.js";
+import { CODEX_IMAGE, CODEX_MAX_OUTPUT_BYTES, CODEX_MAX_REQUEST_BYTES, RESTRICTED_CODEX_ANALYSIS_IDENTITY, RESTRICTED_CODEX_ANALYSIS_MODELS, admitsRestrictedCodexConfig, admitsRestrictedCodexThread, codexRecord, restrictedCodexConfig, restrictedCodexFailure, restrictedCodexRequestError, restrictedCodexUsage } from "./restricted-codex-policy.js";
 import { RestrictedCodexDeadline, RestrictedCodexStop, RestrictedCodexTransport, closeOwnedCodexProcess, ownCodexProcess } from "./restricted-codex-transport.js";
 function childEnvironment(source, home, scratch) {
     const result = { HOME: home, CODEX_HOME: home, TMPDIR: scratch };
@@ -13,6 +13,26 @@ function childEnvironment(source, home, scratch) {
             result[key] = source[key];
     return result;
 }
+function configArguments(overrides) {
+    return Object.entries(overrides).flatMap(([key, value]) => ["-c", `${key}=${JSON.stringify(value)}`]);
+}
+function validParticipant(options) {
+    if (!options)
+        return true;
+    const { tool } = options;
+    if ((options.authMode !== undefined && options.authMode !== "operator")
+        || typeof tool?.name !== "string" || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(tool.name)
+        || typeof tool.description !== "string" || tool.description.length === 0 || tool.description.length > 4096
+        || !tool.inputSchema || typeof tool.inputSchema !== "object" || Array.isArray(tool.inputSchema)
+        || typeof tool.call !== "function")
+        return false;
+    try {
+        return Buffer.byteLength(JSON.stringify(tool.inputSchema)) <= 256 * 1024;
+    }
+    catch {
+        return false;
+    }
+}
 async function isNativeExecutable(file, platform) {
     try {
         await access(file, constants.X_OK);
@@ -32,10 +52,22 @@ async function isNativeExecutable(file, platform) {
         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. */
 async function resolveExecutable(options, env) {
-    const platform = options.platform ?? process.platform;
+    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))) {
@@ -61,8 +93,10 @@ async function resolveExecutable(options, env) {
         return resolved;
     if (path.basename(resolved) === "codex.js" && path.basename(path.dirname(resolved)) === "bin") {
         const packageRoot = path.dirname(path.dirname(resolved));
-        const triple = platform === "darwin" ? "aarch64-apple-darwin" : "x86_64-unknown-linux-musl";
-        const nativePackage = platform === "darwin" ? "codex-darwin-arm64" : "codex-linux-x64";
+        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
@@ -111,20 +145,21 @@ async function checkVersion(file, env, cwd, spawnFn, deadline) {
         }
     }
 }
+const rawCompactionTypes = ["compaction", "compaction_summary", "context_compaction"];
+const analystRawItemTypes = ["message", "reasoning", ...rawCompactionTypes];
+const participantRawItemTypes = [...analystRawItemTypes, "custom_tool_call", "custom_tool_call_output",
+    "function_call", "function_call_output"];
 const unclosedChildren = new Set();
 function retainUnclosedChild(closed) {
     unclosedChildren.add(closed);
     void closed.then(() => { unclosedChildren.delete(closed); });
 }
-/** Each call owns a separate process, home and thread. An unresolved child blocks
- * new work, but ordinary participant turns may run concurrently. */
+/** Analysts/readiness keep their one-shot lifetime; participants own a session. */
 export async function runRestrictedCodexSession(request, options = {}, readinessOnly = false) {
-    const error = restrictedCodexRequestError(request);
-    if (error)
-        return restrictedCodexFailure(error);
-    if (unclosedChildren.size)
-        return restrictedCodexFailure("codex_busy");
-    return executeRestrictedCodexSession(request, options, readinessOnly);
+    const session = createRestrictedCodexSession(options);
+    const result = await session.run(request, readinessOnly);
+    return await session.close() ? result
+        : { ...restrictedCodexFailure("codex_cleanup_failed", result.dispatched, result.usage), failurePhase: "cleanup" };
 }
 async function writeRecoveryMarker(work, sourceEnv, reason) {
     const cache = sourceEnv.XDG_CACHE_HOME ?? path.join(sourceEnv.HOME ?? homedir(), ".cache");
@@ -163,128 +198,187 @@ function hasScopedIdentity(method, params, threadId, turnId) {
             && (turnId === undefined || params.turnId === turnId);
     return (params.threadId === undefined || params.threadId === threadId) && (params.turnId === undefined || params.turnId === turnId);
 }
-/** Exactly one fresh thread/turn; private host auth, no participant state reuse. */
-async function executeRestrictedCodexSession(request, options = {}, readinessOnly = false) {
-    const admissionError = restrictedCodexRequestError(request);
-    if (admissionError)
-        return restrictedCodexFailure(admissionError);
+function usageDelta(total, baseline) {
+    const delta = { input: total.input - baseline.input, output: total.output - baseline.output,
+        cachedInput: (total.cachedInput ?? 0) - (baseline.cachedInput ?? 0),
+        cacheWriteInput: (total.cacheWriteInput ?? 0) - (baseline.cacheWriteInput ?? 0) };
+    return Object.values(delta).every(value => Number.isSafeInteger(value) && value >= 0)
+        && delta.cachedInput + delta.cacheWriteInput <= delta.input ? delta : null;
+}
+export function createRestrictedCodexSession(options = {}) {
     const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
-    if (!(platform === "linux" && arch === "x64") && !(platform === "darwin" && arch === "arm64"))
-        return restrictedCodexFailure("codex_unsupported_platform");
-    const deadline = new RestrictedCodexDeadline(request.timeoutMs, request.signal);
     const sourceEnv = options.env ?? process.env;
+    const participant = options.participant, operatorAuth = participant?.authMode === "operator";
+    const reasoningEffort = participant?.reasoningEffort ?? "low";
     const spawnFn = options.spawnFn ?? ((file, args, settings) => spawn(file, args, settings));
     let work, authLink, transport;
-    let threadId, turnId, earlyTurnId;
-    let dispatched = false, completed = false, usage = null;
-    let generatedDeltaBytes = 0;
-    let outputItem;
-    let result = restrictedCodexFailure("codex_process_failed");
-    let phase = "startup";
-    const early = [];
-    let resolveTurn;
-    const finished = new Promise(resolve => { resolveTurn = resolve; });
-    const handleTurnEvent = (method, params) => {
-        if (!hasScopedIdentity(method, params, threadId, turnId)) {
-            deadline.stop("codex_protocol_error");
-            return;
-        }
-        const item = codexRecord(params.item);
-        if (method === "rawResponseItem/completed") {
-            if (!["message", "reasoning"].includes(String(item.type))) {
-                deadline.stop("codex_tool_call");
-                return;
-            }
-            if (item.type === "message" && Array.isArray(item.content)
-                && item.content.some(content => codexRecord(content).type === "refusal"))
-                deadline.stop("refusal");
-        }
-        if (method === "thread/tokenUsage/updated")
-            usage = restrictedCodexUsage(params.tokenUsage);
-        if (method === "item/started" || method === "item/completed") {
-            if (!["userMessage", "agentMessage", "reasoning"].includes(String(item.type))) {
-                deadline.stop("codex_tool_call");
-                return;
+    let threadId, cwd = "", scratch = "";
+    let identity;
+    let previousUsage = { input: 0, output: 0, cachedInput: 0, cacheWriteInput: 0 };
+    let pendingUsage;
+    let pendingInferenceUsage;
+    let resolvedModel;
+    let authentication;
+    let activeDeadline;
+    let interrupt;
+    let closed = false, cleanupTrusted = true;
+    let pending, closing, disposing;
+    const toolCallIds = new Set();
+    const dispose = () => {
+        closed = true;
+        return disposing ??= (async () => {
+            let cleaned = cleanupTrusted;
+            if (transport) {
+                cleaned = await transport.close(interrupt).catch(() => false) && cleaned;
+                if (!cleaned)
+                    retainUnclosedChild(transport.owned.closed);
             }
-            if (item.type === "agentMessage") {
-                if (item.delivery === "async" || (Array.isArray(item.questions) && item.questions.length > 0)) {
-                    deadline.stop("codex_tool_call");
-                    return;
+            let authReplaced = false;
+            if (authLink && cleaned) {
+                try {
+                    authReplaced = !(await lstat(authLink)).isSymbolicLink();
+                    if (!authReplaced)
+                        await unlink(authLink);
                 }
-                if (method === "item/completed" && item.phase !== "commentary") {
-                    if (typeof item.id !== "string" || typeof item.text !== "string" || Buffer.byteLength(item.text) > CODEX_MAX_OUTPUT_BYTES
-                        || (item.phase !== null && item.phase !== "final_answer") || (item.delivery !== null && item.delivery !== undefined)
-                        || (outputItem && (outputItem.id !== item.id || outputItem.text !== item.text))) {
-                        deadline.stop("invalid_response");
-                        return;
-                    }
-                    outputItem = { id: item.id, text: item.text };
+                catch (error) {
+                    if (codexRecord(error).code !== "ENOENT")
+                        cleaned = false;
                 }
             }
-        }
-        if (method === "turn/completed") {
-            const turn = codexRecord(params.turn);
-            if (turn.id !== turnId || completed) {
+            // Preserve unexpected login rotation for private recovery, never overwrite host auth.
+            if (authReplaced) {
+                cleaned = false;
+                if (work)
+                    await preserveUnexpectedAuth(work, sourceEnv).catch(() => undefined);
+            }
+            if (work && cleaned)
+                await rm(work, { recursive: true, force: true }).catch(() => { cleaned = false; });
+            if (work && !cleaned && !authReplaced)
+                await writeRecoveryMarker(work, sourceEnv, "process_cleanup_unconfirmed").catch(() => undefined);
+            return cleaned;
+        })();
+    };
+    async function execute(request, readinessOnly) {
+        const deadline = new RestrictedCodexDeadline(request.timeoutMs, request.signal);
+        activeDeadline = deadline;
+        let turnId, earlyTurnId;
+        let dispatched = false, usage = null;
+        let completed = false, compacted = false;
+        let toolRequestPending = false;
+        let latestUsage = null;
+        let inferenceUsage = participant ? [] : null;
+        const requestUsageBaseline = previousUsage;
+        let generatedDeltaBytes = 0;
+        let selectedModel = identity?.model;
+        const allowedRawItemTypes = participant ? participantRawItemTypes : analystRawItemTypes;
+        let outputItem;
+        let result = restrictedCodexFailure("codex_process_failed");
+        let phase = "startup";
+        const early = [];
+        let resolveTurn;
+        const finished = new Promise(resolve => { resolveTurn = resolve; });
+        let resolveTurnReady;
+        const turnReady = new Promise(resolve => { resolveTurnReady = resolve; });
+        const handleTurnEvent = (method, params) => {
+            if (!hasScopedIdentity(method, params, threadId, turnId)) {
                 deadline.stop("codex_protocol_error");
                 return;
             }
-            completed = true;
-            if (turn.status === "interrupted") {
-                deadline.stop("cancelled");
-                return;
+            const item = codexRecord(params.item);
+            // CLI 0.154 thread totals omit compaction requests. Retain known usage,
+            // but never label it complete when native compaction occurred in this turn.
+            if (method === "thread/compacted" || item.type === "contextCompaction" || rawCompactionTypes.includes(String(item.type)))
+                compacted = true;
+            if (method === "rawResponseItem/completed") {
+                if (!allowedRawItemTypes.includes(String(item.type))) {
+                    deadline.stop("codex_tool_call");
+                    return;
+                }
+                if (item.type === "custom_tool_call" && item.name !== "exec") {
+                    deadline.stop("codex_tool_call");
+                    return;
+                }
+                if (item.type === "function_call" && item.name !== "wait") {
+                    deadline.stop("codex_tool_call");
+                    return;
+                }
+                if (item.type === "message" && Array.isArray(item.content)
+                    && item.content.some(content => codexRecord(content).type === "refusal"))
+                    deadline.stop("refusal");
             }
-            if (turn.status !== "completed" || turn.error !== null || !outputItem) {
-                deadline.stop("invalid_response");
-                return;
+            if (method === "thread/tokenUsage/updated") {
+                const total = restrictedCodexUsage(params.tokenUsage);
+                // App-server reports cumulative thread usage. Receipts must charge only this turn.
+                usage = total && requestUsageBaseline ? usageDelta(total, requestUsageBaseline) : null;
+                if (inferenceUsage !== null) {
+                    const inferenceDelta = total && (latestUsage ?? requestUsageBaseline)
+                        ? usageDelta(total, (latestUsage ?? requestUsageBaseline)) : null;
+                    if (!inferenceDelta)
+                        inferenceUsage = null;
+                    else if (Object.values(inferenceDelta).some(value => value > 0))
+                        inferenceUsage.push(inferenceDelta);
+                }
+                pendingUsage = usage ?? undefined;
+                pendingInferenceUsage = inferenceUsage?.length ? inferenceUsage.map(item => ({ ...item })) : undefined;
+                latestUsage = total;
             }
-            try {
-                resolveTurn({ status: "completed", output: JSON.parse(outputItem.text), usage,
-                    usageComplete: usage !== null, dispatched: true, errorCode: null });
+            if (method === "item/started" || method === "item/completed") {
+                const allowedItems = participant
+                    ? ["userMessage", "agentMessage", "reasoning", "contextCompaction", "dynamicToolCall"]
+                    : ["userMessage", "agentMessage", "reasoning", "contextCompaction"];
+                if (!allowedItems.includes(String(item.type))) {
+                    deadline.stop("codex_tool_call");
+                    return;
+                }
+                if (item.type === "dynamicToolCall" && (item.tool !== participant?.tool.name || item.namespace !== null
+                    || (method === "item/started" && item.status !== "inProgress")
+                    || (method === "item/completed" && (item.status !== "completed" || item.success !== true)))) {
+                    deadline.stop("codex_tool_call");
+                    return;
+                }
+                if (item.type === "agentMessage") {
+                    if (item.delivery === "async" || (Array.isArray(item.questions) && item.questions.length > 0)) {
+                        deadline.stop("codex_tool_call");
+                        return;
+                    }
+                    if (method === "item/completed" && item.phase !== "commentary") {
+                        if (typeof item.id !== "string" || typeof item.text !== "string" || Buffer.byteLength(item.text) > CODEX_MAX_OUTPUT_BYTES
+                            || (item.phase !== null && item.phase !== "final_answer") || (item.delivery !== null && item.delivery !== undefined)
+                            || (outputItem && (outputItem.id !== item.id || outputItem.text !== item.text))) {
+                            deadline.stop("invalid_response");
+                            return;
+                        }
+                        outputItem = { id: item.id, text: item.text };
+                    }
+                }
             }
-            catch {
-                deadline.stop("invalid_response");
+            if (method === "turn/completed") {
+                const turn = codexRecord(params.turn);
+                if (turn.id !== turnId || completed || toolRequestPending) {
+                    deadline.stop("codex_protocol_error");
+                    return;
+                }
+                completed = true;
+                if (turn.status === "interrupted") {
+                    deadline.stop("cancelled");
+                    return;
+                }
+                if (turn.status !== "completed" || turn.error !== null || !outputItem) {
+                    deadline.stop("invalid_response");
+                    return;
+                }
+                try {
+                    pendingUsage = undefined;
+                    pendingInferenceUsage = undefined;
+                    resolveTurn({ status: "completed", output: JSON.parse(outputItem.text), usage,
+                        usageComplete: usage !== null && !compacted, dispatched: true, errorCode: null });
+                }
+                catch {
+                    deadline.stop("invalid_response");
+                }
             }
-        }
-    };
-    try {
-        deadline.check();
-        const file = await resolveExecutable(options, sourceEnv);
-        deadline.check();
-        work = await mkdtemp(path.join(options.tempRoot ?? tmpdir(), "humanish-codex-analysis-"));
-        await chmod(work, 0o700);
-        work = await realpath(work);
-        const home = path.join(work, "home"), cwd = path.join(work, "cwd"), scratch = path.join(work, "scratch");
-        for (const directory of [home, cwd, scratch])
-            await mkdir(directory, { mode: 0o700 });
-        const env = childEnvironment(sourceEnv, home, scratch);
-        await checkVersion(file, env, cwd, spawnFn, deadline);
-        const config = restrictedCodexConfig(request.model), configPath = path.join(home, "config.toml");
-        await writeFile(configPath, config.toml, { mode: 0o600, flag: "wx" });
-        const authHome = options.authHome ?? sourceEnv.CODEX_HOME ?? path.join(sourceEnv.HOME ?? homedir(), ".codex");
-        if (!path.isAbsolute(authHome))
-            throw new RestrictedCodexStop("codex_unsupported_auth");
-        let authFile;
-        try {
-            authFile = await realpath(path.join(authHome, "auth.json"));
-            if (!(await stat(authFile)).isFile())
-                throw new Error();
-        }
-        catch {
-            throw new RestrictedCodexStop("codex_login_required");
-        }
-        deadline.check();
-        authLink = path.join(home, "auth.json");
-        await symlink(authFile, authLink);
-        deadline.check();
-        const owned = ownCodexProcess(spawnFn(file, ["app-server", "--strict-config"], {
-            cwd, env, detached: false, stdio: ["pipe", "pipe", "pipe"]
-        }));
-        // Raw input notifications echo supplied image data. Bound that wire separately
-        // from the 2 MiB generated report, without dropping admitted evidence.
-        const frameLimit = Math.max(CODEX_MAX_OUTPUT_BYTES, Buffer.byteLength(JSON.stringify({ instructions: request.instructions,
-            evidence: request.evidence, images: request.images, schema: request.schema })) + 1024 * 1024);
-        transport = new RestrictedCodexTransport(owned, deadline, frameLimit);
-        transport.onNotification = (method, params) => {
+        };
+        const onNotification = (method, params) => {
             if (!dispatched)
                 return;
             if (!hasScopedIdentity(method, params, threadId, turnId ?? earlyTurnId)) {
@@ -304,7 +398,9 @@ async function executeRestrictedCodexSession(request, options = {}, readinessOnl
             }
             const item = codexRecord(params.item);
             // Tool requests must fail even if the turn-start acknowledgment is lost.
-            if ((method === "rawResponseItem/completed" && !["message", "reasoning"].includes(String(item.type)))
+            if ((method === "rawResponseItem/completed" && !allowedRawItemTypes.includes(String(item.type)))
+                || (method === "rawResponseItem/completed" && item.type === "custom_tool_call" && item.name !== "exec")
+                || (method === "rawResponseItem/completed" && item.type === "function_call" && item.name !== "wait")
                 || (["item/started", "item/completed"].includes(method) && item.type === "agentMessage"
                     && (item.delivery === "async" || (Array.isArray(item.questions) && item.questions.length > 0)))) {
                 deadline.stop("codex_tool_call");
@@ -314,118 +410,244 @@ async function executeRestrictedCodexSession(request, options = {}, readinessOnl
                 const value = codexRecord(params.turn).id;
                 if (typeof value !== "string" || value.length === 0 || (earlyTurnId !== undefined && value !== earlyTurnId))
                     deadline.stop("codex_protocol_error");
-                else
+                else {
                     earlyTurnId = value;
+                    interrupt = { threadId: threadId, turnId: value };
+                }
             }
             if (turnId === undefined)
                 early.push({ method, params });
             else
                 handleTurnEvent(method, params);
         };
-        phase = "initialize";
-        const initialize = await transport.rpc("initialize", {
-            clientInfo: { name: "humanish_analysis", version: "1.0.0" }, capabilities: { experimentalApi: true }
-        });
-        if (typeof initialize.userAgent !== "string" || !initialize.userAgent.includes(`/0.154.0 `)
-            || initialize.codexHome !== home || initialize.platformOs !== (platform === "darwin" ? "macos" : "linux") || initialize.platformFamily !== "unix")
-            throw new RestrictedCodexStop("codex_unsupported_version");
-        transport.notify("initialized", {});
-        phase = "config/read";
-        const effective = await transport.rpc("config/read", { includeLayers: true, cwd });
-        if (!admitsRestrictedCodexConfig(effective, configPath, request.model))
-            throw new RestrictedCodexStop("codex_unsafe_configuration");
-        phase = "account/read";
-        const account = await transport.rpc("account/read", { refreshToken: false });
-        if (account.account === null)
-            throw new RestrictedCodexStop("codex_login_required");
-        if (codexRecord(account.account).type !== "chatgpt" || account.requiresOpenaiAuth !== true)
-            throw new RestrictedCodexStop("codex_unsupported_auth");
-        phase = "thread/start";
-        const thread = await transport.rpc("thread/start", { cwd, ephemeral: true, experimentalRawEvents: true,
-            approvalPolicy: "never", sandbox: "read-only", model: request.model, modelProvider: "openai", allowProviderModelFallback: false,
-            environments: [], runtimeWorkspaceRoots: [], dynamicTools: [], baseInstructions: request.instructions, config: config.overrides });
-        if (!admitsRestrictedCodexThread(thread, request.model, cwd))
-            throw new RestrictedCodexStop("codex_unsafe_configuration");
-        threadId = String(codexRecord(thread.thread).id);
-        phase = "mcpServerStatus/list";
-        const mcp = await transport.rpc("mcpServerStatus/list", { limit: 100 });
-        if (!Array.isArray(mcp.data) || mcp.data.length !== 0 || mcp.nextCursor !== null)
-            throw new RestrictedCodexStop("codex_unsafe_configuration");
-        if (readinessOnly) {
-            result = { status: "completed", output: null, usage: null, usageComplete: false, dispatched: false, errorCode: null };
-        }
-        else {
-            phase = "turn/start";
-            const input = [{ type: "text", text: request.evidence, text_elements: [] }];
-            for (const [index, image] of request.images.entries()) {
-                deadline.check();
-                const match = CODEX_IMAGE.exec(image.dataUrl);
-                const imagePath = path.join(scratch, `evidence-${index}.${match[1] === "jpeg" ? "jpg" : match[1]}`);
-                await writeFile(imagePath, Buffer.from(match[2], "base64"), { mode: 0o600, flag: "wx" });
-                input.push({ type: "text", text: JSON.stringify({ captureEvidenceId: image.evidenceId }), text_elements: [] }, { type: "localImage", path: imagePath });
+        const onRequest = async (method, params) => {
+            const callId = params.callId;
+            if (!participant || method !== "item/tool/call" || params.threadId !== threadId || typeof params.turnId !== "string"
+                || params.turnId.length === 0 || params.turnId.length > 200 || params.namespace !== null
+                || params.tool !== participant.tool.name || typeof callId !== "string"
+                || callId.length === 0 || callId.length > 200 || toolCallIds.has(callId) || toolRequestPending)
+                throw new RestrictedCodexStop("codex_tool_call");
+            // Mark the request outstanding before waiting for a same-chunk turn/start
+            // acknowledgment, so an early completion can never be accepted.
+            toolRequestPending = true;
+            const activeTurnId = turnId ?? earlyTurnId ?? await deadline.wait(turnReady);
+            if (params.turnId !== activeTurnId)
+                throw new RestrictedCodexStop("codex_tool_call");
+            toolCallIds.add(callId);
+            deadline.pause();
+            const text = await deadline.wait(participant.tool.call(params.arguments));
+            if (typeof text !== "string" || Buffer.byteLength(text) > CODEX_MAX_REQUEST_BYTES)
+                throw new RestrictedCodexStop("invalid_response");
+            try {
+                JSON.parse(text);
             }
+            catch {
+                throw new RestrictedCodexStop("invalid_response");
+            }
+            return { success: true, contentItems: [{ type: "inputText", text }] };
+        };
+        try {
+            pendingUsage = undefined;
             deadline.check();
-            // Even a lost acknowledgment may have dispatched the request. Never claim zero cost.
-            dispatched = true;
-            const turn = await transport.rpc("turn/start", { threadId, cwd, approvalPolicy: "never", sandboxPolicy: { type: "readOnly" },
-                environments: [], runtimeWorkspaceRoots: [], effort: "low", model: request.model, outputSchema: request.schema, input });
-            const returnedTurnId = codexRecord(turn.turn).id;
-            if (typeof returnedTurnId !== "string" || returnedTurnId.length === 0 || returnedTurnId.length > 200
-                || (earlyTurnId !== undefined && earlyTurnId !== returnedTurnId))
-                throw new RestrictedCodexStop("codex_protocol_error");
-            turnId = returnedTurnId;
-            for (const event of early)
-                handleTurnEvent(event.method, event.params);
-            early.length = 0;
-            phase = "response";
-            result = await deadline.wait(finished);
-            deadline.check();
-        }
-    }
-    catch (error) {
-        const code = error instanceof RestrictedCodexStop ? error.code : "codex_process_failed";
-        result = { ...restrictedCodexFailure(code === "codex_cleanup_failed" ? code : deadline.code ?? code, dispatched, usage), failurePhase: phase };
-    }
-    finally {
-        // Deadline remains authoritative until acceptance; teardown has its own small grace.
-        deadline.close();
-        let cleaned = result.errorCode !== "codex_cleanup_failed";
-        if (transport) {
-            const cleanupTurn = turnId ?? earlyTurnId;
-            cleaned = await transport.close(dispatched && !completed && threadId && cleanupTurn
-                ? { threadId, turnId: cleanupTurn } : undefined).catch(() => false);
-            if (!cleaned)
-                retainUnclosedChild(transport.owned.closed);
-        }
-        let authReplaced = false;
-        if (authLink && cleaned) {
-            try {
-                const info = await lstat(authLink);
-                authReplaced = !info.isSymbolicLink();
-                if (!authReplaced)
-                    await unlink(authLink);
+            const frameLimit = Math.max(participant ? CODEX_MAX_REQUEST_BYTES : CODEX_MAX_OUTPUT_BYTES, Buffer.byteLength(JSON.stringify({ instructions: request.instructions,
+                evidence: request.evidence, images: request.images, schema: request.schema })) + 1024 * 1024);
+            if (!transport) {
+                const file = await resolveExecutable(options, sourceEnv);
+                deadline.check();
+                work = await mkdtemp(path.join(options.tempRoot ?? tmpdir(), "humanish-codex-analysis-"));
+                await chmod(work, 0o700);
+                work = await realpath(work);
+                const home = path.join(work, "home");
+                cwd = path.join(work, "cwd");
+                scratch = path.join(work, "scratch");
+                for (const directory of [home, cwd, scratch])
+                    await mkdir(directory, { mode: 0o700 });
+                const env = childEnvironment(sourceEnv, home, scratch);
+                await checkVersion(file, env, cwd, spawnFn, deadline);
+                const configMode = { participantCodeMode: participant !== undefined, reasoningEffort, operatorAuth };
+                const config = restrictedCodexConfig(request.model, configMode), configPath = path.join(home, "config.toml");
+                if (!operatorAuth) {
+                    await writeFile(configPath, config.toml, { mode: 0o600, flag: "wx" });
+                    const authHome = options.authHome ?? sourceEnv.CODEX_HOME ?? path.join(sourceEnv.HOME ?? homedir(), ".codex");
+                    if (!path.isAbsolute(authHome))
+                        throw new RestrictedCodexStop("codex_unsupported_auth");
+                    let authFile;
+                    try {
+                        authFile = await realpath(path.join(authHome, "auth.json"));
+                        if (!(await stat(authFile)).isFile())
+                            throw new Error();
+                    }
+                    catch {
+                        throw new RestrictedCodexStop("codex_login_required");
+                    }
+                    deadline.check();
+                    authLink = path.join(home, "auth.json");
+                    await symlink(authFile, authLink);
+                }
+                deadline.check();
+                const appServerArgs = ["app-server", "--strict-config", ...(operatorAuth ? configArguments(config.overrides) : [])];
+                const owned = ownCodexProcess(spawnFn(file, appServerArgs, {
+                    cwd, env: operatorAuth ? { ...sourceEnv } : env, detached: false, stdio: ["pipe", "pipe", "pipe"]
+                }));
+                transport = new RestrictedCodexTransport(owned, deadline, frameLimit);
+                transport.onNotification = onNotification;
+                transport.onRequestComplete = () => { toolRequestPending = false; };
+                phase = "initialize";
+                const initialize = await transport.rpc("initialize", {
+                    clientInfo: { name: "humanish_analysis", version: "1.0.0" }, capabilities: { experimentalApi: true }
+                });
+                if (typeof initialize.userAgent !== "string" || !initialize.userAgent.includes(`/0.154.0 `)
+                    || (!operatorAuth && initialize.codexHome !== home)
+                    || initialize.platformOs !== (platform === "darwin" ? "macos" : "linux") || initialize.platformFamily !== "unix")
+                    throw new RestrictedCodexStop("codex_unsupported_version");
+                transport.notify("initialized", {});
+                phase = "config/read";
+                const effective = await transport.rpc("config/read", { includeLayers: true, cwd });
+                if (!admitsRestrictedCodexConfig(effective, configPath, request.model, configMode))
+                    throw new RestrictedCodexStop("codex_unsafe_configuration");
+                const configuredModel = codexRecord(effective.config).model;
+                selectedModel = typeof configuredModel === "string" ? configuredModel : undefined;
+                phase = "account/read";
+                const account = await transport.rpc("account/read", { refreshToken: false });
+                if (account.account === null)
+                    throw new RestrictedCodexStop("codex_login_required");
+                const accountType = codexRecord(account.account).type;
+                if ((!operatorAuth && accountType !== "chatgpt") || (operatorAuth && !["chatgpt", "apiKey"].includes(String(accountType)))
+                    || account.requiresOpenaiAuth !== true)
+                    throw new RestrictedCodexStop("codex_unsupported_auth");
+                authentication = accountType === "apiKey" ? "api-key" : "chatgpt-account";
+                const mcpServers = codexRecord(codexRecord(effective.config).mcp_servers);
+                const mcpNames = Object.keys(mcpServers);
+                // Request overrides are split literally on dots by Codex. Limit names to
+                // TOML bare-key characters so each override targets the inherited entry.
+                if (mcpNames.length > 100 || mcpNames.some(name => !/^[A-Za-z0-9_-]{1,200}$/.test(name)))
+                    throw new RestrictedCodexStop("codex_unsafe_configuration");
+                const threadConfig = { ...config.overrides };
+                for (const name of mcpNames)
+                    threadConfig[`mcp_servers.${name}.enabled`] = false;
+                phase = "thread/start";
+                const thread = await transport.rpc("thread/start", { cwd, ephemeral: true, experimentalRawEvents: true,
+                    approvalPolicy: "never", sandbox: "read-only", model: selectedModel, modelProvider: "openai", allowProviderModelFallback: false,
+                    environments: [], runtimeWorkspaceRoots: [], dynamicTools: participant ? [{ type: "function", name: participant.tool.name,
+                            description: participant.tool.description, inputSchema: participant.tool.inputSchema }] : [],
+                    baseInstructions: request.instructions, config: threadConfig });
+                const returnedModel = codexRecord(thread.thread).model;
+                if (typeof returnedModel !== "string" || returnedModel.length === 0 || returnedModel.length > 200
+                    || (selectedModel !== undefined && returnedModel !== selectedModel)
+                    || !admitsRestrictedCodexThread(thread, returnedModel, cwd, reasoningEffort))
+                    throw new RestrictedCodexStop("codex_unsafe_configuration");
+                selectedModel = returnedModel;
+                resolvedModel = returnedModel;
+                threadId = String(codexRecord(thread.thread).id);
+                if (!operatorAuth) {
+                    phase = "mcpServerStatus/list";
+                    const mcp = await transport.rpc("mcpServerStatus/list", { limit: 100 });
+                    if (!Array.isArray(mcp.data) || mcp.data.length !== 0 || mcp.nextCursor !== null)
+                        throw new RestrictedCodexStop("codex_unsafe_configuration");
+                }
+                identity = { requestedModel: request.model, model: selectedModel, instructions: request.instructions };
+            }
+            else {
+                transport.beginRequest(deadline, frameLimit);
+                transport.onNotification = onNotification;
+                transport.onRequestComplete = () => { toolRequestPending = false; };
             }
-            catch (error) {
-                if (codexRecord(error).code !== "ENOENT")
-                    cleaned = false;
+            if (readinessOnly) {
+                result = { status: "completed", output: null, usage: null, usageComplete: false, dispatched: false, errorCode: null };
+            }
+            else {
+                phase = "turn/start";
+                if (participant)
+                    transport.onRequest = onRequest;
+                const input = [{ type: "text", text: request.evidence, text_elements: [] }];
+                for (const [index, image] of request.images.entries()) {
+                    deadline.check();
+                    const match = CODEX_IMAGE.exec(image.dataUrl);
+                    const imagePath = path.join(scratch, `evidence-${index}.${match[1] === "jpeg" ? "jpg" : match[1]}`);
+                    await writeFile(imagePath, Buffer.from(match[2], "base64"), { mode: 0o600 });
+                    input.push({ type: "text", text: JSON.stringify({ captureEvidenceId: image.evidenceId }), text_elements: [] }, { type: "localImage", path: imagePath });
+                }
+                deadline.check();
+                // Even a lost acknowledgment may have dispatched the request. Never claim zero cost.
+                dispatched = true;
+                const turn = await transport.rpc("turn/start", { threadId, cwd, approvalPolicy: "never", sandboxPolicy: { type: "readOnly" },
+                    environments: [], runtimeWorkspaceRoots: [], effort: reasoningEffort, model: selectedModel, outputSchema: request.schema, input });
+                const returnedTurnId = codexRecord(turn.turn).id;
+                if (typeof returnedTurnId !== "string" || returnedTurnId.length === 0 || returnedTurnId.length > 200
+                    || (earlyTurnId !== undefined && earlyTurnId !== returnedTurnId))
+                    throw new RestrictedCodexStop("codex_protocol_error");
+                turnId = returnedTurnId;
+                resolveTurnReady(turnId);
+                interrupt = { threadId: threadId, turnId };
+                for (const event of early)
+                    handleTurnEvent(event.method, event.params);
+                early.length = 0;
+                phase = "response";
+                result = await deadline.wait(finished);
+                deadline.check();
+                previousUsage = latestUsage;
+                interrupt = undefined;
             }
         }
-        // An unexpected replacement may contain rotated login state. Do not discard it
-        // or overwrite the host login. Leave this private control-plane directory for
-        // recovery and fail closed; no path or credential is included in the result.
-        if (authReplaced) {
-            cleaned = false;
-            if (work)
-                await preserveUnexpectedAuth(work, sourceEnv).catch(() => undefined);
+        catch (error) {
+            const code = error instanceof RestrictedCodexStop ? error.code : "codex_process_failed";
+            result = { ...restrictedCodexFailure(code === "codex_cleanup_failed" ? code : deadline.code ?? code, dispatched, usage), failurePhase: phase };
+        }
+        finally {
+            pendingUsage = undefined;
+            pendingInferenceUsage = undefined;
+            deadline.close();
+            activeDeadline = undefined;
+            if (transport)
+                transport.onNotification = () => undefined;
+            if (transport)
+                transport.onRequest = undefined;
+            if (transport)
+                transport.onRequestComplete = undefined;
+            if (result.errorCode !== null) {
+                if (result.errorCode === "codex_cleanup_failed")
+                    cleanupTrusted = false;
+                if (!await dispose())
+                    result = { ...restrictedCodexFailure("codex_cleanup_failed", dispatched, usage), failurePhase: "cleanup" };
+            }
         }
-        if (work && cleaned && !authReplaced)
-            await rm(work, { recursive: true, force: true }).catch(() => { cleaned = false; });
-        if (work && !cleaned && !authReplaced)
-            await writeRecoveryMarker(work, sourceEnv, "process_cleanup_unconfirmed").catch(() => undefined);
-        if (!cleaned)
-            result = { ...restrictedCodexFailure("codex_cleanup_failed", dispatched, usage), failurePhase: "cleanup" };
+        if (result.errorCode !== null && result.failurePhase === undefined)
+            result = { ...result, failurePhase: phase };
+        if (participant && usage !== null && inferenceUsage !== null && inferenceUsage.length > 0)
+            result = { ...result, inferenceUsage: inferenceUsage.map(item => ({ ...item })) };
+        return result;
     }
-    return result.errorCode !== null && result.failurePhase === undefined ? { ...result, failurePhase: phase } : result;
+    return {
+        get pendingUsage() { return pendingUsage; },
+        get pendingInferenceUsage() { return pendingInferenceUsage?.map(item => ({ ...item })); },
+        get resolvedModel() { return resolvedModel; },
+        get authentication() { return authentication; },
+        run(request, readinessOnly = false) {
+            const error = restrictedCodexRequestError(request, operatorAuth);
+            if (error)
+                return Promise.resolve(restrictedCodexFailure(error));
+            if (!validParticipant(participant))
+                return Promise.resolve(restrictedCodexFailure("invalid_request"));
+            if (closed || (identity && (identity.requestedModel !== request.model || identity.instructions !== request.instructions)))
+                return Promise.resolve(restrictedCodexFailure("invalid_request"));
+            if (pending || unclosedChildren.size)
+                return Promise.resolve(restrictedCodexFailure("codex_busy"));
+            const supportedPlatform = operatorAuth ? restrictedCodexNpmTarget(platform, arch) !== undefined
+                : (platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64");
+            if (!supportedPlatform)
+                return Promise.resolve(restrictedCodexFailure("codex_unsupported_platform"));
+            const task = execute(request, readinessOnly);
+            pending = task;
+            void task.finally(() => { if (pending === task)
+                pending = undefined; }).catch(() => undefined);
+            return task;
+        },
+        close() {
+            closed = true;
+            activeDeadline?.stop("cancelled");
+            return closing ??= (async () => { await pending; return dispose(); })();
+        }
+    };
 }
 export async function checkRestrictedCodexSessionReadiness(input = {}, options = {}) {
     return runRestrictedCodexSession({ model: RESTRICTED_CODEX_ANALYSIS_MODELS[0], instructions: "Analyze only supplied study evidence.",