@tickernelz/paperclip-pro-adapter-codex-local 2026.925.0

package/dist/server/execute.js

@@ -0,0 +1,1290 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { inferOpenAiCompatibleBiller } from "@tickernelz/paperclip-pro-adapter-utils";
+import { buildCodexAuthInboundProvision } from "./codex-auth-merge-scripts.js";
+import { copyBackCodexAuth } from "./codex-auth-copyback.js";
+import { ensureCodexAuthCacheEntryDir, isCodexAuthCacheEnabled, resolveCodexAuthCacheEntryPath, selectVendCredential, } from "./codex-auth-cache.js";
+import { adapterExecutionTargetIsRemote, adapterExecutionTargetRemoteCwd, overrideAdapterExecutionTargetRemoteCwd, adapterExecutionTargetSessionIdentity, adapterExecutionTargetSessionMatches, adapterExecutionTargetUsesPaperclipBridge, describeAdapterExecutionTarget, ensureAdapterExecutionTargetCommandResolvable, ensureAdapterExecutionTargetRuntimeCommandInstalled, prepareAdapterExecutionTargetRuntime, adapterExecutionTargetDuplexObservabilityRecorder, adapterExecutionTargetEnablesSandboxDuplexBridge, readAdapterExecutionTarget, resolveAdapterExecutionTargetTimeoutSec, resolveAdapterExecutionTargetCommandForLogs, runAdapterExecutionTargetProcess, runAdapterExecutionTargetShellCommand, startAdapterExecutionTargetPaperclipBridge, } from "@tickernelz/paperclip-pro-adapter-utils/execution-target";
+import { asString, asNumber, parseObject, buildPaperclipEnv, buildInvocationEnvForLogs, ensureAbsoluteDirectory, ensurePaperclipSkillSymlink, ensurePathInEnv, refreshPaperclipWorkspaceEnvForExecution, isPaperclipSkillSourceMissing, readPaperclipRuntimeSkillEntries, readPaperclipIssueWorkModeFromContext, renderTemplate, renderPaperclipWakePrompt, selectPaperclipTaskMarkdown, isPaperclipRecoveryWakePayload, DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE, DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE, joinPromptSections, } from "@tickernelz/paperclip-pro-adapter-utils/server-utils";
+import { parseLocalProcessFilesystemScope, parseLocalProcessSandboxExtraPaths, parseLocalProcessNetworkAllowlist, parseLocalProcessNetworkScope, } from "@tickernelz/paperclip-pro-adapter-utils/local-process-sandbox";
+import { parseCodexJsonl, classifyCodexAuthRefreshFailure, extractCodexRetryNotBefore, isCodexHarnessCrash, isCodexProviderQuotaError, isCodexTransientUpstreamError, isCodexUnknownSessionError, } from "./parse.js";
+import { codexHomeHasUsableAuth, evaluateCodexCredentialReadiness, isManagedCodexHomePath, pathExists, prepareManagedCodexHome, resolveManagedCodexHomeDir, resolveSharedCodexHomeDir, seedManagedCodexHome, stageCodexHomeForSync, mergeManagedCodexMcpGateways, writeManagedCodexMcpConfig, } from "./codex-home.js";
+import { CODEX_SANDBOX_AUTH_EXISTS_COMMAND, CODEX_SANDBOX_AUTH_PRECEDENCE_WARNING, CODEX_SANDBOX_AUTH_PRECEDENCE_WARNING_LOG_LINE, resolveCodexAuthPrecedence, } from "./auth-precedence.js";
+import { prepareCodexRuntimeConfig } from "./runtime-config.js";
+import { resolveCodexDesiredSkillNames } from "./skills.js";
+import { buildCodexExecArgs } from "./codex-args.js";
+import { SANDBOX_INSTALL_COMMAND } from "../index.js";
+import { CODEX_OUTPUT_INACTIVITY_MONITOR_SIGTERM_GRACE_MS, createCodexOutputInactivityMonitor, formatOutputInactivityMonitorErrorMessage, resolveCodexInactivityTimeout, } from "./output-inactivity-monitor.js";
+import { CODEX_PROCESS_ACTIVITY_POLL_INTERVAL_MS, createCodexProcessActivityMonitor, } from "./process-activity-monitor.js";
+import { createCodexAcpExecutor, resolveCodexExecutionEngineForRun, } from "./acp.js";
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const executeCodexAcp = createCodexAcpExecutor();
+const CODEX_ROLLOUT_NOISE_RE = /^\d{4}-\d{2}-\d{2}T[^\s]+\s+ERROR\s+codex_core::rollout::list:\s+state db missing rollout path for thread\s+[a-z0-9-]+$/i;
+function stripCodexRolloutNoise(text) {
+    const parts = text.split(/\r?\n/);
+    const kept = [];
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (!trimmed) {
+            kept.push(part);
+            continue;
+        }
+        if (CODEX_ROLLOUT_NOISE_RE.test(trimmed))
+            continue;
+        kept.push(part);
+    }
+    return kept.join("\n");
+}
+function firstNonEmptyLine(text) {
+    return (text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean) ?? "");
+}
+// Benign stderr lines that never explain a nonzero exit and must not be
+// surfaced as the run error: Codex always prints the YOLO approvals warning
+// because this adapter passes the approvals-bypass flag itself, and
+// "[paperclip] ..." lines are diagnostics the adapter injected (e.g. ACP
+// fallback notes). Keep this list conservative so real errors are never
+// skipped.
+const BENIGN_CODEX_STDERR_LINE_RES = [
+    /^YOLO mode is enabled\b/i,
+    /^\[paperclip\]/,
+];
+function isBenignCodexStderrLine(line) {
+    return BENIGN_CODEX_STDERR_LINE_RES.some((re) => re.test(line));
+}
+export function firstMeaningfulStderrLine(text) {
+    const meaningful = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line && !isBenignCodexStderrLine(line));
+    return meaningful ?? firstNonEmptyLine(text);
+}
+function signalCodexChild(target, signal) {
+    if (process.platform !== "win32" && target.processGroupId && target.processGroupId > 0) {
+        try {
+            process.kill(-target.processGroupId, signal);
+            return true;
+        }
+        catch {
+            // Fall back to direct child signal if group signaling fails (e.g. group already gone).
+        }
+    }
+    if (target.pid && target.pid > 0) {
+        try {
+            process.kill(target.pid, signal);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function hasNonEmptyEnvValue(env, key) {
+    const raw = env[key];
+    return typeof raw === "string" && raw.trim().length > 0;
+}
+function resolveCodexBillingType(env) {
+    // Codex uses API-key auth when OPENAI_API_KEY is present; otherwise rely on local login/session auth.
+    return hasNonEmptyEnvValue(env, "OPENAI_API_KEY") ? "api" : "subscription";
+}
+function resolveCodexBiller(env, billingType) {
+    const openAiCompatibleBiller = inferOpenAiCompatibleBiller(env, "openai");
+    if (openAiCompatibleBiller === "openrouter")
+        return "openrouter";
+    return billingType === "subscription" ? "chatgpt" : openAiCompatibleBiller ?? "openai";
+}
+async function isLikelyPaperclipRepoRoot(candidate) {
+    const [hasWorkspace, hasPackageJson, hasServerDir, hasAdapterUtilsDir] = await Promise.all([
+        pathExists(path.join(candidate, "pnpm-workspace.yaml")),
+        pathExists(path.join(candidate, "package.json")),
+        pathExists(path.join(candidate, "server")),
+        pathExists(path.join(candidate, "packages", "adapter-utils")),
+    ]);
+    return hasWorkspace && hasPackageJson && hasServerDir && hasAdapterUtilsDir;
+}
+async function isLikelyPaperclipRuntimeSkillPath(candidate, skillName, options = {}) {
+    if (path.basename(candidate) !== skillName)
+        return false;
+    const skillsRoot = path.dirname(candidate);
+    if (path.basename(skillsRoot) !== "skills")
+        return false;
+    if (options.requireSkillMarkdown !== false && !(await pathExists(path.join(candidate, "SKILL.md")))) {
+        return false;
+    }
+    let cursor = path.dirname(skillsRoot);
+    for (let depth = 0; depth < 6; depth += 1) {
+        if (await isLikelyPaperclipRepoRoot(cursor))
+            return true;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    return false;
+}
+async function pruneBrokenUnavailablePaperclipSkillSymlinks(skillsHome, allowedSkillNames, onLog) {
+    const allowed = new Set(Array.from(allowedSkillNames));
+    const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (allowed.has(entry.name) || !entry.isSymbolicLink())
+            continue;
+        const target = path.join(skillsHome, entry.name);
+        const linkedPath = await fs.readlink(target).catch(() => null);
+        if (!linkedPath)
+            continue;
+        const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+        if (await pathExists(resolvedLinkedPath))
+            continue;
+        if (!(await isLikelyPaperclipRuntimeSkillPath(resolvedLinkedPath, entry.name, {
+            requireSkillMarkdown: false,
+        }))) {
+            continue;
+        }
+        await fs.unlink(target).catch(() => { });
+        await onLog("stdout", `[paperclip] Removed stale Codex skill "${entry.name}" from ${skillsHome}\n`);
+    }
+}
+function resolveCodexSkillsDir(codexHome) {
+    return path.join(codexHome, "skills");
+}
+function readCodexTransientFallbackMode(context) {
+    const value = asString(context.codexTransientFallbackMode, "").trim();
+    switch (value) {
+        case "same_session":
+        case "safer_invocation":
+        case "fresh_session":
+        case "fresh_session_safer_invocation":
+            return value;
+        default:
+            return null;
+    }
+}
+function fallbackModeUsesSaferInvocation(mode) {
+    return mode === "safer_invocation" || mode === "fresh_session_safer_invocation";
+}
+function fallbackModeUsesFreshSession(mode) {
+    return mode === "fresh_session" || mode === "fresh_session_safer_invocation";
+}
+function managedMcpGatewaysFromContext(context) {
+    const managedMcp = parseObject(context.paperclipManagedMcp);
+    if (managedMcp.managedMcpOnly !== true)
+        return [];
+    const gateways = Array.isArray(managedMcp.gateways) ? managedMcp.gateways : [];
+    return gateways
+        .map((raw) => {
+        const gateway = parseObject(raw);
+        const name = asString(gateway.name, "").trim();
+        const endpointPath = asString(gateway.endpointPath, "").trim();
+        const bearerToken = asString(gateway.bearerToken, "").trim();
+        if (!name || !endpointPath || !bearerToken)
+            return null;
+        return { name, endpointPath, bearerToken };
+    })
+        .filter((gateway) => Boolean(gateway));
+}
+/**
+ * Probe the sandbox for its own `~/.codex/auth.json`. "unknown" means the
+ * probe itself failed (timeout, transport error, or a shell failure other
+ * than `test`'s clean false) — callers that gate on the result must not
+ * report that as a missing credential.
+ */
+async function probeSandboxCodexAuthJson(input) {
+    if (!input.target || input.target.kind !== "remote" || input.target.transport !== "sandbox") {
+        return "absent";
+    }
+    try {
+        const result = await runAdapterExecutionTargetShellCommand(input.runId, input.target, CODEX_SANDBOX_AUTH_EXISTS_COMMAND, {
+            cwd: input.cwd,
+            env: {},
+            timeoutSec: 5,
+        });
+        if (result.timedOut)
+            return "unknown";
+        if (result.exitCode === 0)
+            return "present";
+        return result.exitCode === 1 ? "absent" : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function sandboxCodexAuthJsonExists(input) {
+    return (await probeSandboxCodexAuthJson(input)) === "present";
+}
+/**
+ * Execute-time credential gate. A managed home with no host-side credentials
+ * is still launchable when the run targets a sandbox whose image carries its
+ * own Codex login (`~/.codex/auth.json` baked in during image setup): the
+ * inbound auth merge ships the credential-less host home and keeps the
+ * sandbox's credential, so the host is not a required credential source —
+ * on managed cloud hosts a local Codex login never exists at all. The
+ * sandbox is probed before the run is declared unlaunchable; non-sandbox
+ * targets keep the strict host-side requirement.
+ */
+export async function assertCodexCredentialsLaunchable(input) {
+    const credentialReadiness = await evaluateCodexCredentialReadiness({
+        env: input.env ?? process.env,
+        companyId: input.companyId,
+        configuredCodexHome: input.configuredCodexHome,
+        configuredApiKey: input.configuredApiKey,
+    });
+    if (!credentialReadiness.managed || credentialReadiness.ready)
+        return;
+    const targetIsSandbox = input.target?.kind === "remote" && input.target.transport === "sandbox";
+    if (targetIsSandbox) {
+        const sandboxAuthJson = await probeSandboxCodexAuthJson({
+            runId: input.runId,
+            target: input.target,
+            cwd: input.cwd,
+        });
+        if (sandboxAuthJson === "present") {
+            await input.onLog("stdout", `Using the sandbox's own Codex login; managed home "${input.effectiveCodexHome}" has no host credentials.\n`);
+            return;
+        }
+        if (sandboxAuthJson === "unknown") {
+            // The probe failing is an operational problem, not evidence that the
+            // sandbox lacks a login — proceeding lets a genuinely credentialed
+            // sandbox run, and a credential-less one still fails at Codex's first
+            // request with the provider's own error.
+            await input.onLog("stderr", `Could not verify the sandbox's Codex login (probe failed); proceeding. ` +
+                `If the sandbox has no credentials, Codex will fail at its first request.\n`);
+            return;
+        }
+        throw new Error(`no Codex credentials provisioned for managed home "${input.effectiveCodexHome}" ` +
+            `(no usable auth.json, OPENAI_API_KEY is empty, and the sandbox has no Codex login). ` +
+            `Use a sandbox image that is signed in to Codex, configure a per-agent OPENAI_API_KEY, ` +
+            `or sign in to Codex on the host with a ChatGPT subscription.`);
+    }
+    throw new Error(`no Codex credentials provisioned for managed home "${input.effectiveCodexHome}" ` +
+        `(no usable auth.json and OPENAI_API_KEY is empty). ` +
+        `Sign in to Codex on the host with a ChatGPT subscription, or configure a per-agent ` +
+        `OPENAI_API_KEY.`);
+}
+async function emitSandboxAuthPrecedenceWarningIfNeeded(input) {
+    if (!input.target || input.target.kind !== "remote" || input.target.transport !== "sandbox") {
+        return;
+    }
+    const sandboxAuthJson = await sandboxCodexAuthJsonExists({
+        runId: input.runId,
+        target: input.target,
+        cwd: input.cwd,
+    });
+    const resolution = resolveCodexAuthPrecedence({
+        configuredApiKey: input.configuredApiKey,
+        hostAuthJson: input.hostAuthJson,
+        sandboxAuthJson,
+    });
+    if (!resolution.shouldWarn)
+        return;
+    await input.onLog("stderr", CODEX_SANDBOX_AUTH_PRECEDENCE_WARNING_LOG_LINE);
+    await input.onEvent?.({
+        eventType: "codex.auth_precedence_warning",
+        stream: "system",
+        level: "warn",
+        message: CODEX_SANDBOX_AUTH_PRECEDENCE_WARNING,
+        payload: {
+            configuredApiKey: input.configuredApiKey,
+            hostAuthJson: input.hostAuthJson,
+            sandboxAuthJson,
+            winner: resolution.winner,
+            sandboxLoginShadowed: resolution.sandboxLoginShadowed,
+        },
+    });
+}
+function buildCodexTransientHandoffNote(input) {
+    return [
+        "Paperclip session handoff:",
+        input.previousSessionId ? `- Previous session: ${input.previousSessionId}` : "",
+        "- Rotation reason: repeated Codex transient remote-compaction failures",
+        `- Fallback mode: ${input.fallbackMode}`,
+        input.continuationSummaryBody
+            ? `- Issue continuation summary: ${input.continuationSummaryBody.slice(0, 1_500)}`
+            : "",
+        "Continue from the current task state. Rebuild only the minimum context you need.",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+export async function ensureCodexSkillsInjected(onLog, options = {}) {
+    const allSkillsEntries = options.skillsEntries
+        ?? (await readPaperclipRuntimeSkillEntries({}, __moduleDir)).filter((entry) => !isPaperclipSkillSourceMissing(entry));
+    const desiredSkillNames = options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.key);
+    const desiredSet = new Set(desiredSkillNames);
+    const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.key));
+    if (skillsEntries.length === 0)
+        return;
+    const skillsHome = options.skillsHome ?? resolveCodexSkillsDir(resolveSharedCodexHomeDir());
+    await fs.mkdir(skillsHome, { recursive: true });
+    const linkSkill = options.linkSkill;
+    for (const entry of skillsEntries) {
+        const target = path.join(skillsHome, entry.runtimeName);
+        try {
+            const existing = await fs.lstat(target).catch(() => null);
+            if (existing?.isSymbolicLink()) {
+                const linkedPath = await fs.readlink(target).catch(() => null);
+                const resolvedLinkedPath = linkedPath
+                    ? path.resolve(path.dirname(target), linkedPath)
+                    : null;
+                if (resolvedLinkedPath &&
+                    resolvedLinkedPath !== entry.source &&
+                    (await isLikelyPaperclipRuntimeSkillPath(resolvedLinkedPath, entry.runtimeName))) {
+                    await fs.unlink(target);
+                    if (linkSkill) {
+                        await linkSkill(entry.source, target);
+                    }
+                    else {
+                        await fs.symlink(entry.source, target);
+                    }
+                    await onLog("stdout", `[paperclip] Repaired Codex skill "${entry.runtimeName}" into ${skillsHome}\n`);
+                    continue;
+                }
+            }
+            const result = await ensurePaperclipSkillSymlink(entry.source, target, linkSkill);
+            if (result === "skipped")
+                continue;
+            await onLog("stdout", `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Codex skill "${entry.runtimeName}" into ${skillsHome}\n`);
+        }
+        catch (err) {
+            await onLog("stderr", `[paperclip] Failed to inject Codex skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    await pruneBrokenUnavailablePaperclipSkillSymlinks(skillsHome, skillsEntries.map((entry) => entry.runtimeName), onLog);
+}
+export async function execute(ctx) {
+    const engineSelection = await resolveCodexExecutionEngineForRun(ctx);
+    if (engineSelection.unavailableReason) {
+        return {
+            exitCode: 1,
+            signal: null,
+            timedOut: false,
+            errorCode: "adapter_engine_unavailable",
+            errorMessage: engineSelection.unavailableReason,
+            resultJson: {
+                executionRecovery: { kind: "bootstrap", providerWorkStarted: false },
+            },
+        };
+    }
+    if (engineSelection.engine === "acp") {
+        return executeCodexAcp(ctx);
+    }
+    const { runId, agent, runtime, config, context, onLog, onMeta, onEvent, onSpawn, authToken } = ctx;
+    const promptTemplate = asString(config.promptTemplate, context.conversationMode === true
+        ? DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE
+        : DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE);
+    const command = asString(config.command, "codex");
+    const model = asString(config.model, "");
+    const workspaceContext = parseObject(context.paperclipWorkspace);
+    const workspaceCwd = asString(workspaceContext.cwd, "");
+    const workspaceSource = asString(workspaceContext.source, "");
+    const workspaceStrategy = asString(workspaceContext.strategy, "");
+    const workspaceId = asString(workspaceContext.workspaceId, "");
+    const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
+    const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+    const workspaceBranch = asString(workspaceContext.branchName, "");
+    const workspaceWorktreePath = asString(workspaceContext.worktreePath, "");
+    const agentHome = asString(workspaceContext.agentHome, "");
+    const workspaceHints = Array.isArray(context.paperclipWorkspaces)
+        ? context.paperclipWorkspaces.filter((value) => typeof value === "object" && value !== null)
+        : [];
+    const runtimeServiceIntents = Array.isArray(context.paperclipRuntimeServiceIntents)
+        ? context.paperclipRuntimeServiceIntents.filter((value) => typeof value === "object" && value !== null)
+        : [];
+    const runtimeServices = Array.isArray(context.paperclipRuntimeServices)
+        ? context.paperclipRuntimeServices.filter((value) => typeof value === "object" && value !== null)
+        : [];
+    const runtimePrimaryUrl = asString(context.paperclipRuntimePrimaryUrl, "");
+    const executionTarget = readAdapterExecutionTarget({
+        executionTarget: ctx.executionTarget,
+        legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
+    });
+    const targetWorkspaceRealization = executionTarget?.workspaceRealization ?? null;
+    const configuredCwd = asString(config.cwd, "");
+    const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+    const effectiveWorkspaceCwd = targetWorkspaceRealization?.mode === "in_place"
+        ? targetWorkspaceRealization.authoritativeRoot
+        : useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
+    const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+    const envConfig = parseObject(config.env);
+    const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
+    let configuredCodexHome = typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0
+        ? path.resolve(envConfig.CODEX_HOME.trim())
+        : null;
+    const connectorSourceHome = configuredCodexHome;
+    const connectorSkillDigest = typeof config.paperclipConnectorSkillDigest === "string"
+        && /^[a-f0-9]{64}$/.test(config.paperclipConnectorSkillDigest) ? config.paperclipConnectorSkillDigest : null;
+    if (connectorSkillDigest) {
+        // Never mount assignment-specific skills into the shared company/user home.
+        // A different skill revision gets a new home, so revoked/changed resources
+        // cannot survive as stale symlinks or bleed into another agent's session.
+        configuredCodexHome = path.join(resolveManagedCodexHomeDir(process.env, agent.companyId), "connector-runtimes", agent.id, connectorSkillDigest);
+    }
+    const codexSkillEntries = (await readPaperclipRuntimeSkillEntries(config, __moduleDir))
+        // A missing-source entry would become a dangling skill symlink; skip it.
+        .filter((entry) => !isPaperclipSkillSourceMissing(entry));
+    const desiredSkillNames = resolveCodexDesiredSkillNames(config, codexSkillEntries);
+    if (!executionTargetIsRemote) {
+        await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+    }
+    const configuredOpenAiApiKey = typeof envConfig.OPENAI_API_KEY === "string" && envConfig.OPENAI_API_KEY.trim().length > 0
+        ? envConfig.OPENAI_API_KEY.trim()
+        : null;
+    // A configured CODEX_HOME that lives under the Paperclip-managed company tree
+    // (the per-agent home set by the server isolation guard) still needs auth
+    // seeded — it ships with no credentials and OPENAI_API_KEY="" by default.
+    // Only a genuine external/user-supplied override is treated as self-managed
+    // and left untouched.
+    const configuredHomeIsManaged = configuredCodexHome != null &&
+        isManagedCodexHomePath(process.env, agent.companyId, configuredCodexHome);
+    // Identity-anchored cache vend (host to sandbox). Before the managed home is
+    // seeded from the shared source `auth.json`, refresh the shared credential with
+    // a strictly-newer cached copy of the SAME identity. The vend reads the host
+    // identity first and resolves only that identity's cache slot; when the host
+    // holds no credential it does nothing (no random pick). This keeps the change
+    // additive: the managed home still symlinks the shared `auth.json`, now at its
+    // freshest same-identity copy. The off-switch (default on) skips the vend.
+    if (!config.managedAiConnection && isCodexAuthCacheEnabled(process.env)) {
+        const sharedHomeAuthPath = path.join(resolveSharedCodexHomeDir(process.env), "auth.json");
+        // This caller reads `process.env` directly and holds no separate `env`
+        // object, so `selectVendCredential` falls back to its own `process.env`
+        // default for the merge lock root.
+        await selectVendCredential(sharedHomeAuthPath, (accountId) => resolveCodexAuthCacheEntryPath(process.env, accountId, agent.companyId), (line) => onLog("stdout", `${line}\n`)).catch(async (error) => {
+            // The vend is best-effort and additive. A vend failure must never block a
+            // run: log and fall through to seed from the unrefreshed shared credential.
+            await onLog("stderr", `[paperclip] Codex auth cache: vend skipped after an error; using the shared credential as-is.\n`);
+            void error;
+        });
+    }
+    if (configuredCodexHome == null || (connectorSkillDigest && connectorSourceHome == null)) {
+        await prepareManagedCodexHome(process.env, onLog, agent.companyId, {
+            apiKey: configuredOpenAiApiKey,
+        });
+    }
+    if (configuredHomeIsManaged && configuredCodexHome) {
+        const seedEnv = connectorSkillDigest ? {
+            ...process.env, CODEX_HOME: connectorSourceHome ?? resolveManagedCodexHomeDir(process.env, agent.companyId),
+        } : process.env;
+        await seedManagedCodexHome(configuredCodexHome, seedEnv, onLog, {
+            apiKey: configuredOpenAiApiKey,
+        });
+    }
+    const defaultCodexHome = resolveManagedCodexHomeDir(process.env, agent.companyId);
+    const effectiveCodexHome = configuredCodexHome ?? defaultCodexHome;
+    await fs.mkdir(effectiveCodexHome, { recursive: true });
+    // Never launch a managed CODEX_HOME with no credentials. Without auth.json
+    // and with OPENAI_API_KEY="" the provider rejects every request with
+    // "401 Missing bearer"; fail fast with a clear adapter error instead of
+    // emitting unauthenticated calls. External overrides manage their own auth.
+    // This is the execute-time backstop for the control plane's pre-dispatch
+    // configuration-incomplete gate (see server heartbeat); both decide host
+    // readiness through the same `evaluateCodexCredentialReadiness` predicate,
+    // and sandbox targets are additionally allowed to supply their own login
+    // (the pre-dispatch gate defers sandbox-destined runs here for exactly that
+    // probe).
+    await assertCodexCredentialsLaunchable({
+        runId,
+        companyId: agent.companyId,
+        configuredCodexHome,
+        configuredApiKey: configuredOpenAiApiKey,
+        effectiveCodexHome,
+        target: executionTarget,
+        cwd,
+        onLog,
+    });
+    // Merge custom model providers (PAPERCLIP_CODEX_PROVIDERS) into the managed
+    // CODEX_HOME's config.toml BEFORE the home is shipped to a remote execution
+    // target, so both local and sandboxed Codex processes pick up the routing.
+    // An explicit env.CODEX_HOME override is treated as user-managed and skipped.
+    const envConfigStrings = Object.fromEntries(Object.entries(envConfig).filter((entry) => typeof entry[1] === "string"));
+    const preparedRuntimeConfig = await prepareCodexRuntimeConfig({
+        env: envConfigStrings,
+        codexHome: configuredCodexHome ? null : effectiveCodexHome,
+    });
+    // Curated allowlist dir staged for the remote `home` asset (see below). Held
+    // here so the outer `finally` can remove it on every exit path (teardown and
+    // error), never only the happy path.
+    let stagedCodexHomeDir = null;
+    try {
+        for (const note of preparedRuntimeConfig.notes) {
+            await onLog("stdout", `[paperclip] ${note}\n`);
+        }
+        const paperclipBaseEnv = buildPaperclipEnv(agent);
+        const runtimeMcpGateways = (ctx.runtimeMcp?.getServers() ?? []).map((server) => ({
+            name: server.name,
+            endpointPath: server.url,
+            bearerToken: server.token,
+        }));
+        const managedMcpGateways = mergeManagedCodexMcpGateways(runtimeMcpGateways, managedMcpGatewaysFromContext(context));
+        const managedMcp = await writeManagedCodexMcpConfig({
+            codexHome: effectiveCodexHome,
+            apiBaseUrl: paperclipBaseEnv.PAPERCLIP_API_URL,
+            gateways: managedMcpGateways,
+        });
+        if (managedMcpGateways.length > 0) {
+            await onLog("stdout", `[paperclip] Wrote ${managedMcpGateways.length} managed MCP gateway(s) into Codex config "${managedMcp.configPath}".\n`);
+        }
+        for (const warning of managedMcp.warnings) {
+            await onLog("stderr", `[paperclip] ${warning}\n`);
+        }
+        // Inject skills into the same CODEX_HOME that Codex will actually run with
+        // (managed home in the default case, or an explicit override from adapter config).
+        const codexSkillsDir = resolveCodexSkillsDir(effectiveCodexHome);
+        await ensureCodexSkillsInjected(onLog, {
+            skillsHome: codexSkillsDir,
+            skillsEntries: codexSkillEntries,
+            desiredSkillNames,
+        });
+        const timeoutSec = resolveAdapterExecutionTargetTimeoutSec(executionTarget, asNumber(config.timeoutSec, 0));
+        const graceSec = asNumber(config.graceSec, 20);
+        let effectiveExecutionCwd = targetWorkspaceRealization?.mode === "in_place"
+            ? targetWorkspaceRealization.authoritativeRoot
+            : adapterExecutionTargetRemoteCwd(executionTarget, cwd);
+        const preparedExecutionTargetRuntime = executionTargetIsRemote
+            ? await (async () => {
+                await onLog("stdout", `[paperclip] Syncing ${targetWorkspaceRealization?.mode === "in_place" ? "CODEX_HOME" : "workspace and CODEX_HOME"} to ${describeAdapterExecutionTarget(executionTarget)}.\n`);
+                // Stage only the files Codex actually needs into a curated temp dir and
+                // ship THAT as the `home` asset, instead of the whole managed
+                // CODEX_HOME + a name denylist. Staged AFTER the config.toml rewrites
+                // (provider merge + MCP block splice above) and skills injection, so the
+                // staged config.toml/skills reflect their final state. Symlinks (incl.
+                // the single-use `auth.json`) are dereferenced to bytes. This drops the
+                // large runtime state (`sessions/`, `*.sqlite`, `plugins/`, …) that the
+                // 4-name denylist missed and that a sandbox run never needs.
+                stagedCodexHomeDir = await stageCodexHomeForSync(effectiveCodexHome, { runId });
+                return await prepareAdapterExecutionTargetRuntime({
+                    runId,
+                    target: executionTarget,
+                    adapterKey: "codex",
+                    timeoutSec,
+                    workspaceLocalDir: cwd,
+                    workspaceRemoteDir: targetWorkspaceRealization?.mode === "in_place"
+                        ? targetWorkspaceRealization.authoritativeRoot
+                        : undefined,
+                    syncWorkspace: targetWorkspaceRealization?.mode !== "in_place",
+                    installCommand: SANDBOX_INSTALL_COMMAND,
+                    detectCommand: command,
+                    onProgress: (line) => onLog("stdout", line),
+                    onRuntimeProgress: ctx.onRuntimeProgress,
+                    assets: [
+                        {
+                            key: "home",
+                            localDir: stagedCodexHomeDir,
+                            followSymlinks: true,
+                            // Inbound (host→sandbox) auth-merge contribution: stages the two
+                            // merge scripts and runs the merge-extract command so a sandbox
+                            // that already carries a Codex `auth.json` keeps whichever
+                            // credential is newer. The sandbox runtime core stays adapter-
+                            // agnostic — it just invokes this generic `provision` seam.
+                            provision: buildCodexAuthInboundProvision(),
+                            // Outbound (sandbox→host) auth copy-back contribution: at
+                            // teardown, read the sandbox's `auth.json` and — guarded by the
+                            // same direction-agnostic decision predicate under a directory
+                            // lock — atomically install it onto the shared host credential
+                            // when it is a strictly-newer same-identity subscription copy.
+                            // The sandbox core stays adapter-agnostic; it just awaits this
+                            // generic `restore` seam per asset before destroying the sandbox.
+                            // Target is the shared symlink SOURCE (what managed homes point
+                            // `auth.json` at), not the in-sandbox symlink.
+                            restore: async ({ assetDir, readFile }) => void (await copyBackCodexAuth({
+                                readSandboxAuth: () => readFile(path.posix.join(assetDir, "auth.json")),
+                                hostAuthPath: path.join(config.managedAiConnection ? effectiveCodexHome : resolveSharedCodexHomeDir(process.env), "auth.json"),
+                                log: (line) => onLog("stdout", `${line}\n`),
+                                // Additive cache write (sandbox to host): also cache the
+                                // sandbox subscription credential in its per-identity slot,
+                                // keyed by the real `account_id`. Company-scoped root; the
+                                // helper ensures the slot directory private and containment-
+                                // guarded. The off-switch (default on) is read inside.
+                                resolveCacheEntryPath: config.managedAiConnection ? undefined : (accountId) => ensureCodexAuthCacheEntryDir(process.env, accountId, agent.companyId),
+                                env: process.env,
+                            })),
+                            // No `exclude` denylist: `stagedCodexHomeDir` already contains
+                            // ONLY the allowlisted files (auth/config/skills), so there is
+                            // nothing to filter out.
+                        },
+                    ],
+                });
+            })()
+            : null;
+        if (preparedExecutionTargetRuntime?.workspaceRemoteDir) {
+            effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir;
+        }
+        const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
+        const executionTargetIsSandbox = runtimeExecutionTarget?.kind === "remote" && runtimeExecutionTarget.transport === "sandbox";
+        const restoreRemoteWorkspace = preparedExecutionTargetRuntime
+            ? () => preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line))
+            : null;
+        let paperclipBridge = null;
+        const remoteCodexHome = executionTargetIsRemote
+            ? preparedExecutionTargetRuntime?.assetDirs.home ??
+                path.posix.join(effectiveExecutionCwd, ".paperclip-runtime", "codex", "home")
+            : null;
+        await emitSandboxAuthPrecedenceWarningIfNeeded({
+            runId,
+            target: runtimeExecutionTarget,
+            cwd: effectiveExecutionCwd,
+            configuredApiKey: Boolean(configuredOpenAiApiKey),
+            hostAuthJson: await codexHomeHasUsableAuth(effectiveCodexHome),
+            onLog,
+            onEvent,
+        });
+        const env = { ...paperclipBaseEnv };
+        env.PAPERCLIP_RUN_ID = runId;
+        const wakeTaskId = (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
+            (typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||
+            null;
+        const wakeReason = typeof context.wakeReason === "string" && context.wakeReason.trim().length > 0
+            ? context.wakeReason.trim()
+            : null;
+        const wakeCommentId = (typeof context.wakeCommentId === "string" && context.wakeCommentId.trim().length > 0 && context.wakeCommentId.trim()) ||
+            (typeof context.commentId === "string" && context.commentId.trim().length > 0 && context.commentId.trim()) ||
+            null;
+        const approvalId = typeof context.approvalId === "string" && context.approvalId.trim().length > 0
+            ? context.approvalId.trim()
+            : null;
+        const approvalStatus = typeof context.approvalStatus === "string" && context.approvalStatus.trim().length > 0
+            ? context.approvalStatus.trim()
+            : null;
+        const linkedIssueIds = Array.isArray(context.issueIds)
+            ? context.issueIds.filter((value) => typeof value === "string" && value.trim().length > 0)
+            : [];
+        const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);
+        if (wakeTaskId) {
+            env.PAPERCLIP_TASK_ID = wakeTaskId;
+        }
+        if (issueWorkMode) {
+            env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;
+        }
+        if (wakeReason) {
+            env.PAPERCLIP_WAKE_REASON = wakeReason;
+        }
+        if (wakeCommentId) {
+            env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
+        }
+        if (approvalId) {
+            env.PAPERCLIP_APPROVAL_ID = approvalId;
+        }
+        if (approvalStatus) {
+            env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;
+        }
+        if (linkedIssueIds.length > 0) {
+            env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
+        }
+        refreshPaperclipWorkspaceEnvForExecution({
+            env,
+            envConfig,
+            workspaceCwd: effectiveWorkspaceCwd,
+            workspaceSource,
+            workspaceStrategy,
+            workspaceId,
+            workspaceRepoUrl,
+            workspaceRepoRef,
+            workspaceBranch,
+            workspaceWorktreePath,
+            workspaceHints,
+            agentHome,
+            executionTargetIsRemote,
+            executionCwd: effectiveExecutionCwd,
+        });
+        if (targetWorkspaceRealization) {
+            env.PAPERCLIP_WORKSPACE_REALIZATION_MODE = targetWorkspaceRealization.mode;
+            env.PAPERCLIP_WORKSPACE_AUTHORITATIVE_ROOT = targetWorkspaceRealization.authoritativeRoot;
+        }
+        if (runtimeServiceIntents.length > 0) {
+            env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
+        }
+        if (runtimeServices.length > 0) {
+            env.PAPERCLIP_RUNTIME_SERVICES_JSON = JSON.stringify(runtimeServices);
+        }
+        if (runtimePrimaryUrl) {
+            env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;
+        }
+        env.CODEX_HOME = remoteCodexHome ?? effectiveCodexHome;
+        if (authToken) {
+            env.PAPERCLIP_API_KEY = authToken;
+        }
+        if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
+            paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
+                runId,
+                target: runtimeExecutionTarget,
+                enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
+                duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
+                runtimeRootDir: preparedExecutionTargetRuntime?.runtimeRootDir,
+                adapterKey: "codex",
+                timeoutSec,
+                hostApiToken: env.PAPERCLIP_API_KEY,
+                onLog,
+            });
+            if (paperclipBridge) {
+                Object.assign(env, paperclipBridge.env);
+            }
+        }
+        const effectiveEnv = Object.fromEntries(Object.entries({ ...process.env, ...env }).filter((entry) => typeof entry[1] === "string"));
+        const billingType = resolveCodexBillingType(effectiveEnv);
+        const networkScope = parseLocalProcessNetworkScope(config.networkScope);
+        const filesystemScope = parseLocalProcessFilesystemScope(config.filesystemScope);
+        const localProcessSandbox = (filesystemScope || networkScope) && !executionTargetIsRemote
+            ? {
+                workspaceDir: effectiveExecutionCwd,
+                filesystemScope,
+                managedPaths: [{ path: effectiveCodexHome, access: "rw" }],
+                extraPaths: parseLocalProcessSandboxExtraPaths(config.filesystemExtraPaths),
+                pathAliases: targetWorkspaceRealization?.mode === "copy"
+                    ? targetWorkspaceRealization.pathAliases
+                    : [],
+                outboundRestorePaths: targetWorkspaceRealization?.outboundRestorePaths ?? [],
+                homeDir: filesystemScope ? effectiveCodexHome : null,
+                networkScope,
+                networkAllowlist: parseLocalProcessNetworkAllowlist(config.networkAllowlist),
+                networkTrustedUrls: [
+                    paperclipBaseEnv.PAPERCLIP_API_URL,
+                    ...runtimeMcpGateways.map((gateway) => gateway.endpointPath),
+                ],
+                command: asString(config.filesystemSandboxCommand, "bwrap"),
+            }
+            : null;
+        if (localProcessSandbox) {
+            const scopes = [filesystemScope ? "workspace filesystem" : null, networkScope ? `${networkScope} network` : null]
+                .filter(Boolean)
+                .join(" and ");
+            await onLog("stdout", `[paperclip] Confining Codex with ${scopes} scope.\n`);
+        }
+        const runtimeEnv = Object.fromEntries(Object.entries(ensurePathInEnv(effectiveEnv)).filter((entry) => typeof entry[1] === "string"));
+        await ensureAdapterExecutionTargetRuntimeCommandInstalled({
+            runId,
+            target: executionTarget,
+            installCommand: ctx.runtimeCommandSpec?.installCommand,
+            detectCommand: ctx.runtimeCommandSpec?.detectCommand,
+            cwd,
+            env: runtimeEnv,
+            timeoutSec,
+            graceSec,
+            onLog,
+        });
+        await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);
+        const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
+        const loggedEnv = buildInvocationEnvForLogs(env, {
+            runtimeEnv,
+            includeRuntimeKeys: ["HOME"],
+            resolvedCommand,
+        });
+        const monitorResolution = resolveCodexInactivityTimeout(config.outputInactivityTimeoutMs);
+        if (monitorResolution.mode === "disabled") {
+            await onLog("stdout", `[paperclip] Codex output inactivity monitor is DISABLED via adapterConfig.outputInactivityTimeoutMs=null. Hung codex runs will only be detected by the platform-level silent-run safety net.\n`);
+        }
+        else if (monitorResolution.mode === "default" && "reason" in monitorResolution) {
+            await onLog("stdout", `[paperclip] Ignoring non-positive adapterConfig.outputInactivityTimeoutMs; falling back to default ${monitorResolution.timeoutMs}ms.\n`);
+        }
+        const runtimeSessionParams = parseObject(runtime.sessionParams);
+        const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
+        const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
+        const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
+        const canResumeSession = runtimeSessionId.length > 0 &&
+            (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
+            adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
+        const codexTransientFallbackMode = readCodexTransientFallbackMode(context);
+        const forceSaferInvocation = fallbackModeUsesSaferInvocation(codexTransientFallbackMode);
+        const forceFreshSession = fallbackModeUsesFreshSession(codexTransientFallbackMode);
+        const sessionId = canResumeSession && !forceFreshSession ? runtimeSessionId : null;
+        if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
+            await onLog("stdout", `[paperclip] Codex session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`);
+        }
+        else if (runtimeSessionId && !canResumeSession) {
+            await onLog("stdout", `[paperclip] Codex session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`);
+        }
+        const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
+        const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
+        let instructionsPrefix = "";
+        let instructionsChars = 0;
+        if (instructionsFilePath) {
+            try {
+                const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
+                instructionsPrefix =
+                    `${instructionsContents}\n\n` +
+                        `The above agent instructions were loaded from ${instructionsFilePath}. ` +
+                        `Resolve any relative file references from ${instructionsDir}.\n\n`;
+                instructionsChars = instructionsPrefix.length;
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                await onLog("stdout", `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`);
+            }
+        }
+        const repoAgentsNote = "Codex exec automatically applies repo-scoped AGENTS.md instructions from the current workspace; Paperclip does not currently suppress that discovery.";
+        const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+        const templateData = {
+            agentId: agent.id,
+            companyId: agent.companyId,
+            runId,
+            company: { id: agent.companyId },
+            agent,
+            run: { id: runId, source: "on_demand" },
+            context,
+        };
+        const renderedBootstrapPrompt = !sessionId && bootstrapPromptTemplate.trim().length > 0
+            ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+            : "";
+        const taskContextNote = selectPaperclipTaskMarkdown(context, { resumedSession: Boolean(sessionId) });
+        const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, {
+            resumedSession: Boolean(sessionId),
+            conversationMode: context.conversationMode === true,
+            suppressIssueDescription: taskContextNote.length > 0,
+        });
+        const shouldUseResumeDeltaPrompt = Boolean(sessionId) && wakePrompt.length > 0;
+        const promptInstructionsPrefix = shouldUseResumeDeltaPrompt ? "" : instructionsPrefix;
+        instructionsChars = promptInstructionsPrefix.length;
+        const continuationSummary = parseObject(context.paperclipContinuationSummary);
+        const continuationSummaryBody = asString(continuationSummary.body, "").trim() || null;
+        const codexFallbackHandoffNote = forceFreshSession
+            ? buildCodexTransientHandoffNote({
+                previousSessionId: runtimeSessionId || runtime.sessionId || null,
+                fallbackMode: codexTransientFallbackMode ?? "fresh_session",
+                continuationSummaryBody,
+            })
+            : "";
+        const commandNotes = (() => {
+            if (!instructionsFilePath) {
+                const notes = [repoAgentsNote];
+                if (forceSaferInvocation) {
+                    notes.push("Codex transient fallback requested safer invocation settings for this retry.");
+                }
+                if (forceFreshSession) {
+                    notes.push("Codex transient fallback forced a fresh session with a continuation handoff.");
+                }
+                return notes;
+            }
+            if (instructionsPrefix.length > 0) {
+                if (shouldUseResumeDeltaPrompt) {
+                    const notes = [
+                        `Loaded agent instructions from ${instructionsFilePath}`,
+                        "Skipped stdin instruction reinjection because an existing Codex session is being resumed with a wake delta.",
+                        repoAgentsNote,
+                    ];
+                    if (forceSaferInvocation) {
+                        notes.push("Codex transient fallback requested safer invocation settings for this retry.");
+                    }
+                    if (forceFreshSession) {
+                        notes.push("Codex transient fallback forced a fresh session with a continuation handoff.");
+                    }
+                    return notes;
+                }
+                const notes = [
+                    `Loaded agent instructions from ${instructionsFilePath}`,
+                    `Prepended instructions + path directive to stdin prompt (relative references from ${instructionsDir}).`,
+                    repoAgentsNote,
+                ];
+                if (forceSaferInvocation) {
+                    notes.push("Codex transient fallback requested safer invocation settings for this retry.");
+                }
+                if (forceFreshSession) {
+                    notes.push("Codex transient fallback forced a fresh session with a continuation handoff.");
+                }
+                return notes;
+            }
+            const notes = [
+                `Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
+                repoAgentsNote,
+            ];
+            if (forceSaferInvocation) {
+                notes.push("Codex transient fallback requested safer invocation settings for this retry.");
+            }
+            if (forceFreshSession) {
+                notes.push("Codex transient fallback forced a fresh session with a continuation handoff.");
+            }
+            return notes;
+        })();
+        if (executionTargetIsSandbox) {
+            commandNotes.push("Added --skip-git-repo-check for sandbox execution because Codex requires an explicit trust bypass in headless remote workspaces.");
+        }
+        if (preparedRuntimeConfig.notes.length > 0) {
+            commandNotes.unshift(...preparedRuntimeConfig.notes);
+        }
+        const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
+            ? ""
+            : renderTemplate(promptTemplate, templateData);
+        const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+        const prompt = joinPromptSections([
+            promptInstructionsPrefix,
+            renderedBootstrapPrompt,
+            wakePrompt,
+            codexFallbackHandoffNote,
+            sessionHandoffNote,
+            taskContextNote,
+            renderedPrompt,
+        ]);
+        const promptMetrics = {
+            promptChars: prompt.length,
+            instructionsChars,
+            bootstrapPromptChars: renderedBootstrapPrompt.length,
+            wakePromptChars: wakePrompt.length,
+            sessionHandoffChars: sessionHandoffNote.length,
+            taskContextChars: taskContextNote.length,
+            heartbeatPromptChars: renderedPrompt.length,
+        };
+        const runAttempt = async (resumeSessionId) => {
+            const execArgs = buildCodexExecArgs(forceSaferInvocation ? { ...config, fastMode: false } : config, {
+                resumeSessionId,
+                skipGitRepoCheck: executionTargetIsSandbox,
+                networkAccess: env.PAPERCLIP_RUNNER_NETWORK_ACCESS !== "disabled",
+            });
+            const args = execArgs.args;
+            const commandNotesWithFastMode = execArgs.fastModeIgnoredReason == null
+                ? commandNotes
+                : [...commandNotes, execArgs.fastModeIgnoredReason];
+            if (onMeta) {
+                await onMeta({
+                    adapterType: "codex_local",
+                    command: resolvedCommand,
+                    cwd: effectiveExecutionCwd,
+                    commandNotes: commandNotesWithFastMode,
+                    commandArgs: args.map((value, idx) => {
+                        if (idx === args.length - 1 && value !== "-")
+                            return `<prompt ${prompt.length} chars>`;
+                        return value;
+                    }),
+                    env: loggedEnv,
+                    prompt,
+                    promptMetrics,
+                    context,
+                });
+            }
+            let monitorFired = false;
+            let monitorTerminationSignal = null;
+            let monitorElapsedMs = 0;
+            let monitorTimeoutMs = 0;
+            let killTarget = null;
+            let sigkillTimer = null;
+            let monitorLogPromise = null;
+            const processActivityMonitor = { current: null };
+            const resolvedMonitorTimeoutMs = monitorResolution.mode === "disabled" ? null : monitorResolution.timeoutMs;
+            const monitor = monitorResolution.mode === "disabled"
+                ? null
+                : createCodexOutputInactivityMonitor({
+                    timeoutMs: monitorResolution.timeoutMs,
+                    onFire: (state) => {
+                        monitorFired = true;
+                        monitorElapsedMs = (state.firedAt ?? Date.now()) - state.lastEventAt;
+                        monitorTimeoutMs = monitorResolution.timeoutMs;
+                        const message = formatOutputInactivityMonitorErrorMessage(monitorElapsedMs);
+                        const elapsedSec = Math.round(monitorElapsedMs / 1000);
+                        const timeoutSecLabel = Math.round(monitorResolution.timeoutMs / 1000);
+                        const logLine = `[paperclip] adapter.invoke ${message}; ` +
+                            `timeoutMs=${monitorResolution.timeoutMs} elapsedSinceLastEventMs=${monitorElapsedMs} ` +
+                            `outputChunkCount=${state.outputChunkCount} outputBytes=${state.outputBytes} ` +
+                            `parsedEvents=${state.parsedEventCount} processActivityCount=${state.processActivityCount} ` +
+                            `(timeout=${timeoutSecLabel}s elapsed=${elapsedSec}s); ` +
+                            `terminating codex child via SIGTERM (5s grace, then SIGKILL).\n`;
+                        // Issue the log without awaiting on the kill hot path, but capture
+                        // the promise so the surrounding try/finally can await flush before
+                        // the run resolves. Without this the diagnostic that explains the
+                        // kill could be dropped if the child exits faster than onLog flushes.
+                        monitorLogPromise = Promise.resolve(onLog("stderr", logLine)).catch(() => { });
+                        const target = killTarget;
+                        if (!target || (target.pid == null && target.processGroupId == null)) {
+                            return;
+                        }
+                        const sentSig = signalCodexChild(target, "SIGTERM");
+                        if (sentSig)
+                            monitorTerminationSignal = "SIGTERM";
+                        sigkillTimer = setTimeout(() => {
+                            sigkillTimer = null;
+                            const stillSent = signalCodexChild(target, "SIGKILL");
+                            if (stillSent)
+                                monitorTerminationSignal = "SIGKILL";
+                        }, CODEX_OUTPUT_INACTIVITY_MONITOR_SIGTERM_GRACE_MS);
+                        if (typeof sigkillTimer.unref === "function") {
+                            sigkillTimer.unref();
+                        }
+                    },
+                });
+            const wrappedOnSpawn = async (meta) => {
+                killTarget = { pid: meta.pid ?? null, processGroupId: meta.processGroupId };
+                if (monitor && resolvedMonitorTimeoutMs !== null && !executionTargetIsRemote) {
+                    processActivityMonitor.current = createCodexProcessActivityMonitor({
+                        pid: meta.pid,
+                        processGroupId: meta.processGroupId,
+                        intervalMs: Math.min(CODEX_PROCESS_ACTIVITY_POLL_INTERVAL_MS, Math.max(1_000, Math.floor(resolvedMonitorTimeoutMs / 4))),
+                        onActivity: () => monitor.noteProcessActivity(),
+                    });
+                }
+                if (onSpawn) {
+                    await onSpawn(meta);
+                }
+            };
+            try {
+                const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
+                    cwd,
+                    env,
+                    stdin: prompt,
+                    timeoutSec,
+                    graceSec,
+                    onSpawn: wrappedOnSpawn,
+                    onRuntimeProgress: ctx.onRuntimeProgress,
+                    onLog: async (stream, chunk) => {
+                        monitor?.noteOutputChunk(stream, chunk);
+                        if (stream === "stdout") {
+                            await onLog(stream, chunk);
+                            return;
+                        }
+                        const cleaned = stripCodexRolloutNoise(chunk);
+                        if (!cleaned.trim())
+                            return;
+                        await onLog(stream, cleaned);
+                    },
+                    runLogTail: paperclipBridge?.runLogTail,
+                    settleRunDisposition: paperclipBridge?.settleRunDisposition,
+                    localProcessSandbox,
+                });
+                const cleanedStderr = stripCodexRolloutNoise(proc.stderr);
+                return {
+                    proc: {
+                        ...proc,
+                        stderr: cleanedStderr,
+                    },
+                    rawStderr: proc.stderr,
+                    parsed: parseCodexJsonl(proc.stdout),
+                    monitor: monitorFired
+                        ? {
+                            fired: true,
+                            terminationSignal: monitorTerminationSignal,
+                            elapsedMsSinceLastEvent: monitorElapsedMs,
+                            timeoutMs: monitorTimeoutMs,
+                        }
+                        : { fired: false },
+                };
+            }
+            finally {
+                processActivityMonitor.current?.stop();
+                monitor?.stop();
+                if (sigkillTimer) {
+                    clearTimeout(sigkillTimer);
+                    sigkillTimer = null;
+                }
+                if (monitorLogPromise) {
+                    await monitorLogPromise;
+                    monitorLogPromise = null;
+                }
+            }
+        };
+        const toResult = (attempt, clearSessionOnMissingSession = false, isRetry = false) => {
+            if (attempt.monitor?.fired) {
+                const errorMessage = formatOutputInactivityMonitorErrorMessage(attempt.monitor.elapsedMsSinceLastEvent);
+                return {
+                    exitCode: null,
+                    signal: attempt.monitor.terminationSignal ?? attempt.proc.signal,
+                    timedOut: false,
+                    errorMessage,
+                    errorCode: "codex_output_inactivity_monitor",
+                    errorFamily: null,
+                    usage: attempt.parsed.usage,
+                    usageBasis: attempt.parsed.usageBasis,
+                    sessionId: null,
+                    sessionParams: null,
+                    sessionDisplayId: null,
+                    provider: "openai",
+                    biller: resolveCodexBiller(effectiveEnv, billingType),
+                    model,
+                    billingType,
+                    costUsd: null,
+                    resultJson: {
+                        stdout: attempt.proc.stdout,
+                        stderr: attempt.proc.stderr,
+                        outputInactivityMonitor: {
+                            kind: "output_inactivity",
+                            timeoutMs: attempt.monitor.timeoutMs,
+                            elapsedMsSinceLastEvent: attempt.monitor.elapsedMsSinceLastEvent,
+                            terminationSignal: attempt.monitor.terminationSignal,
+                        },
+                    },
+                    summary: attempt.parsed.summary,
+                    clearSession: clearSessionOnMissingSession,
+                };
+            }
+            if (attempt.proc.timedOut) {
+                return {
+                    exitCode: attempt.proc.exitCode,
+                    signal: attempt.proc.signal,
+                    timedOut: true,
+                    errorMessage: `Timed out after ${timeoutSec}s`,
+                    clearSession: clearSessionOnMissingSession,
+                };
+            }
+            const canFallbackToRuntimeSession = !isRetry && !forceFreshSession;
+            const resolvedSessionId = attempt.parsed.sessionId ??
+                (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
+            const resolvedSessionParams = resolvedSessionId
+                ? {
+                    sessionId: resolvedSessionId,
+                    cwd: effectiveExecutionCwd,
+                    ...(executionTargetIsRemote
+                        ? {
+                            remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
+                        }
+                        : {}),
+                    ...(workspaceId ? { workspaceId } : {}),
+                    ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
+                    ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
+                }
+                : null;
+            const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
+            const stderrLine = firstMeaningfulStderrLine(attempt.proc.stderr);
+            const fallbackErrorMessage = parsedError ||
+                stderrLine ||
+                `Codex exited with code ${attempt.proc.exitCode ?? -1}`;
+            const transientRetryNotBefore = (attempt.proc.exitCode ?? 0) !== 0
+                ? extractCodexRetryNotBefore({
+                    stdout: attempt.proc.stdout,
+                    stderr: attempt.proc.stderr,
+                    errorMessage: fallbackErrorMessage,
+                })
+                : null;
+            const authRefreshFailure = (attempt.proc.exitCode ?? 0) !== 0
+                ? classifyCodexAuthRefreshFailure({
+                    stdout: attempt.proc.stdout,
+                    stderr: attempt.proc.stderr,
+                    errorMessage: fallbackErrorMessage,
+                })
+                : null;
+            const providerQuota = (attempt.proc.exitCode ?? 0) !== 0 &&
+                !authRefreshFailure &&
+                isCodexProviderQuotaError({
+                    stdout: attempt.proc.stdout,
+                    stderr: attempt.proc.stderr,
+                    errorMessage: fallbackErrorMessage,
+                });
+            const transientUpstream = (attempt.proc.exitCode ?? 0) !== 0 &&
+                !authRefreshFailure &&
+                !providerQuota &&
+                isCodexTransientUpstreamError({
+                    stdout: attempt.proc.stdout,
+                    stderr: attempt.proc.stderr,
+                    errorMessage: fallbackErrorMessage,
+                });
+            const harnessCrash = !authRefreshFailure &&
+                !providerQuota &&
+                !transientUpstream &&
+                isCodexHarnessCrash({
+                    exitCode: attempt.proc.exitCode,
+                    sawProtocolEvent: attempt.parsed.sawProtocolEvent,
+                    sawProtocolTerminalEvent: attempt.parsed.sawProtocolTerminalEvent,
+                });
+            const errorFamily = authRefreshFailure ??
+                (providerQuota ? "provider_quota" : transientUpstream || harnessCrash ? "transient_upstream" : null);
+            return {
+                exitCode: attempt.proc.exitCode,
+                signal: attempt.proc.signal,
+                timedOut: false,
+                errorMessage: (attempt.proc.exitCode ?? 0) === 0
+                    ? null
+                    : fallbackErrorMessage,
+                errorCode: 
+                // Forward the transport-level error code from the run-disposition
+                // seam first. A lost duplex control channel surfaces the typed
+                // `duplex_channel_lost` code before any provider classification.
+                attempt.proc.errorCode
+                    ? attempt.proc.errorCode
+                    : authRefreshFailure
+                        ? authRefreshFailure
+                        : providerQuota
+                            ? "provider_quota"
+                            : transientUpstream
+                                ? "codex_transient_upstream"
+                                : harnessCrash
+                                    ? "codex_harness_crash"
+                                    : null,
+                errorFamily,
+                retryNotBefore: transientRetryNotBefore ? transientRetryNotBefore.toISOString() : null,
+                usage: attempt.parsed.usage,
+                usageBasis: attempt.parsed.usageBasis,
+                sessionId: resolvedSessionId,
+                sessionParams: resolvedSessionParams,
+                sessionDisplayId: resolvedSessionId,
+                provider: "openai",
+                biller: resolveCodexBiller(effectiveEnv, billingType),
+                model,
+                billingType,
+                costUsd: null,
+                resultJson: {
+                    stdout: attempt.proc.stdout,
+                    stderr: attempt.proc.stderr,
+                    ...(errorFamily ? { errorFamily } : {}),
+                    ...(transientRetryNotBefore ? { retryNotBefore: transientRetryNotBefore.toISOString() } : {}),
+                    ...(transientRetryNotBefore ? { transientRetryNotBefore: transientRetryNotBefore.toISOString() } : {}),
+                    ...(providerQuota && transientRetryNotBefore ? { providerQuotaRetryNotBefore: transientRetryNotBefore.toISOString() } : {}),
+                },
+                summary: attempt.parsed.summary,
+                clearSession: Boolean((clearSessionOnMissingSession || forceFreshSession) && !resolvedSessionId),
+            };
+        };
+        let executionError = null;
+        try {
+            const initial = await runAttempt(sessionId);
+            if (sessionId &&
+                !initial.proc.timedOut &&
+                !initial.proc.signal &&
+                // A started session can emit stale-rollout warnings for other threads.
+                // After Ctrl-C those warnings must not restart the cancelled turn.
+                !initial.parsed.sessionId &&
+                (initial.proc.exitCode ?? 0) !== 0 &&
+                isCodexUnknownSessionError(initial.proc.stdout, initial.rawStderr)) {
+                await onLog("stdout", `[paperclip] Codex resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`);
+                const retry = await runAttempt(null);
+                const retryResult = toResult(retry, true, true);
+                if (retryResult.errorMessage) {
+                    executionError = new Error(retryResult.errorMessage);
+                }
+                return retryResult;
+            }
+            const result = toResult(initial, false, false);
+            if (result.errorMessage) {
+                executionError = new Error(result.errorMessage);
+            }
+            return result;
+        }
+        catch (error) {
+            executionError = error;
+            throw error;
+        }
+        finally {
+            if (paperclipBridge) {
+                await paperclipBridge.stop();
+            }
+            if (restoreRemoteWorkspace) {
+                try {
+                    await onLog("stdout", `[paperclip] Restoring workspace changes from ${describeAdapterExecutionTarget(executionTarget)}.\n`);
+                    await restoreRemoteWorkspace();
+                }
+                catch (error) {
+                    await Promise.resolve(onLog("stderr", `[paperclip] Failed to restore workspace changes from ${describeAdapterExecutionTarget(executionTarget)}: ${error instanceof Error ? error.message : String(error)}\n`)).catch(() => undefined);
+                    // A provider failure remains the primary outcome. When provider work
+                    // succeeded, however, silently accepting a failed copy-back can lose
+                    // the only workspace edits before a replacement sandbox starts.
+                    if (executionError === null)
+                        throw error;
+                }
+            }
+        }
+    }
+    finally {
+        // Remove the staged CODEX_HOME allowlist temp dir on every exit path
+        // (teardown AND error), never only the happy path. Cleanup failure is
+        // logged, not fatal — a leaked temp dir must not crash the run.
+        if (stagedCodexHomeDir) {
+            await fs.rm(stagedCodexHomeDir, { recursive: true, force: true }).catch(async (error) => {
+                await onLog("stderr", `[paperclip] Failed to remove staged Codex home "${stagedCodexHomeDir}": ${error instanceof Error ? error.message : String(error)}\n`);
+            });
+        }
+        // Restore the managed config.toml so PAPERCLIP_CODEX_PROVIDERS changes
+        // (or removal) between runs never leave stale provider routing behind. This
+        // finally starts the moment prepareCodexRuntimeConfig returns, so a throw
+        // anywhere in the remaining setup (skill injection, remote runtime
+        // preparation, command building) restores the original config.toml too.
+        // If the process dies before reaching this, the next
+        // prepareCodexRuntimeConfig restores the original from the pre-run backup
+        // written at prepare time.
+        await preparedRuntimeConfig.cleanup();
+    }
+}
+//# sourceMappingURL=execute.js.map