super-dsh 0.1.10-e → 0.1.11-a

package/agent-codex/dist/codex-provider-gateway.js

@@ -1,34 +1,3 @@
-/**
- * codex-provider-gateway.ts — the adapter-owned Remote behind the Hub's Codex
- * settings panel (2026-10-03 user ruling; reworked 2026-10-04).
- *
- * Why a Remote and not a hub route: the provider list is ADAPTER config
- * (dev-rules §12), so the adapter owns it and the hub only forwards.
- * `TypertRemoteService` + `@Remote` is the whole mechanism — standard (TC39)
- * method decorators recorded on the class prototype, read back at dispatch time
- * by the gateway's source-claim scan. No codegen, no compiler-injected metadata,
- * which is why a plain `tsc` adapter build can ship one.
- *
- * Wire contract (`superd-hub/src/client/runtime-settings-api.ts` builds each
- * envelope; the hub carrier forwards `envelope.method` verbatim):
- *
- *   request   POST /hub/api?agent=codex
- *             { type:'client-request', rpcId, method:'codexProviders/<op>',
- *               payload: { args: { request?: … } } }
- *   response  { type:'server-response', rpcId, result:{ ok:true, value:<view> } }
- *
- * There is no `select`: which provider a SESSION runs on is DSH's own
- * per-session `model/selection`, chosen from the harness's model selector. This
- * panel is a list editor — add, edit, remove — plus the reconcile with the
- * user's `config.toml` that {@link syncFromNative} performs.
- *
- * The class is a delegation shell on purpose: every operation is a plain
- * function over (worldHome, codexHome), so the entire contract — the key
- * privacy rule, the validation, the sync, the view projection — is pinnable
- * under `node --test` with no Cordis Context and no real home.
- *
- * @module agent-codex/codex-provider-gateway
- */
 var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
     var useValue = arguments.length > 2;
     for (var i = 0; i < initializers.length; i++) {
@@ -63,6 +32,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { OPENAI_OAUTH_ID, hasOpenAiOAuth, openAiOAuthEntry } from "./codex-oauth.js";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { isProviderId, isWireProtocol, providerStorePath, readProviderStore, removeProvider, syncNativeProviders, upsertProvider, writeProviderStore, } from "./codex-providers.js";
 import { providerCatalogDir, readNativeProviders, readNativeSelection, } from "./codex-native-config.js";
@@ -134,6 +104,8 @@ function keyAvailable(codexHome, entry) {
     return nonEmpty(process.env[entry.auth.name]) !== undefined;
 }
 function project(codexHome, entry) {
+    if (entry.kind === "openai-oauth")
+        return { id: entry.id, label: entry.label, protocol: "responses", models: openAiOAuthEntry(codexHome).models, authKind: "oauth", hasKey: hasOpenAiOAuth(codexHome) };
     return {
         id: entry.id,
         label: entry.label,
@@ -172,10 +144,22 @@ export function syncFromNative(worldHome, codexHome) {
     const store = readProviderStore(worldHome);
     const imported = readNativeProviders(codexHome).map(toImport);
     const result = syncNativeProviders(store, imported);
-    if (result.added.length > 0 || result.updated.length > 0) {
-        writeProviderStore(worldHome, result.store);
-    }
-    return result;
+    const legacyAlias = result.store.providers.some(entry => entry.id === OPENAI_OAUTH_ID && entry.kind !== "openai-oauth");
+    const blockedNativeIds = [...new Set([...(result.store.blockedNativeIds ?? []), ...(legacyAlias ? [OPENAI_OAUTH_ID] : [])])];
+    const oauth = hasOpenAiOAuth(codexHome) && !blockedNativeIds.includes(OPENAI_OAUTH_ID);
+    const existed = store.providers.some(entry => entry.kind === "openai-oauth");
+    // Keep collided identities on disk so ambiguous old routes fail closed. They
+    // are quarantined by readEffectiveProviderStore, not silently repurposed.
+    const providers = result.store.providers.flatMap(entry => entry.kind === "openai-oauth"
+        ? legacyAlias || oauth ? [openAiOAuthEntry(codexHome)] : [] : [entry]);
+    if (oauth && !existed)
+        providers.push(openAiOAuthEntry(codexHome));
+    const effective = { ...result.store, providers, ...(blockedNativeIds.length === 0 ? {} : { blockedNativeIds }) };
+    const blockedChanged = JSON.stringify(blockedNativeIds) !== JSON.stringify(store.blockedNativeIds ?? []);
+    const identityChanged = !legacyAlias && oauth !== existed;
+    if (result.added.length > 0 || result.updated.length > 0 || identityChanged || blockedChanged)
+        writeProviderStore(worldHome, effective);
+    return { ...result, store: effective };
 }
 /** The view for one (already loaded) store. */
 function viewOf(worldHome, codexHome, store, syncedAt, note) {
@@ -189,13 +173,19 @@ function viewOf(worldHome, codexHome, store, syncedAt, note) {
     // Only a SEEDED keyed entry defers to auth.json, so only it can be shadowed
     // by a ChatGPT login. An entry holding its own key bypasses the auth manager
     // entirely through the launch's synthetic `env_key`.
-    const deferred = store.providers.some((entry) => entry.auth.kind === "apiKey" && entry.auth.value === "");
+    const deferred = store.providers.some((entry) => entry.kind !== "openai-oauth" && entry.auth.kind === "apiKey" && entry.auth.value === "");
     const shadowed = deferred && chatgptAuthMode(codexHome)
         ? 'Codex is signed in with a ChatGPT account, which takes precedence over a saved API key — a provider that relies on auth.json will not run until you sign out (`codex logout`) or give this provider its own key.'
         : undefined;
-    const combined = [note, shadowed].filter((part) => part !== undefined).join(" ");
+    const nativeAlias = readNativeProviders(codexHome).some(entry => entry.id === OPENAI_OAUTH_ID);
+    const blocked = store.blockedNativeIds?.includes(OPENAI_OAUTH_ID) === true;
+    const duplicate = store.providers.filter(entry => entry.id === OPENAI_OAUTH_ID).length > 1;
+    const collision = blocked || duplicate || (nativeAlias && store.providers.some(entry => entry.kind === "openai-oauth"))
+        ? 'OpenAI OAuth discovery is blocked by an openai-oauth provider ID conflict. Existing third-party routes and keys are preserved. Rename the conflicting native provider table; historical session routes need explicit repair before this ID can be reused.'
+        : undefined;
+    const combined = [note, shadowed, collision].filter((part) => part !== undefined).join(" ");
     return {
-        providers: store.providers.map((entry) => project(codexHome, entry)),
+        providers: store.providers.filter(entry => !(duplicate && entry.id === OPENAI_OAUTH_ID)).map((entry) => project(codexHome, entry)),
         native,
         protocols: PROTOCOL_OPTIONS,
         paths: {
@@ -243,6 +233,8 @@ export function normalizeSaveRequest(request, existing) {
     }
     const raw = request["provider"];
     const id = raw["id"];
+    if (id === OPENAI_OAUTH_ID && (existing === undefined || existing.kind === "openai-oauth"))
+        throw new TypeError("OpenAI OAuth is a reserved native provider; configure authentication in Codex");
     if (!isProviderId(id)) {
         throw new TypeError(`codexProviders/save: id must match /^[a-z0-9][a-z0-9-]*$/ (got ${JSON.stringify(id)})`);
     }
@@ -328,6 +320,8 @@ export function normalizeSaveRequest(request, existing) {
 export function saveProvider(worldHome, codexHome, request, syncedAt) {
     const store = readProviderStore(worldHome);
     const id = isRecord(request) && isRecord(request["provider"]) ? request["provider"]["id"] : undefined;
+    if (store.providers.filter(entry => entry.id === id).length > 1)
+        throw new TypeError("codexProviders/save: duplicate provider ID is ambiguous; explicitly repair the conflicting identities before editing");
     const existing = store.providers.find((entry) => entry.id === id);
     const entry = normalizeSaveRequest(request, existing);
     const next = upsertProvider(store, entry);
@@ -340,6 +334,10 @@ export function removeProviderEntry(worldHome, codexHome, request, syncedAt) {
     if (id === undefined)
         throw new TypeError("codexProviders/remove: id must be a non-empty string");
     const store = readProviderStore(worldHome);
+    if (id === OPENAI_OAUTH_ID && store.providers.some(entry => entry.id === id && entry.kind === "openai-oauth"))
+        throw new TypeError("OpenAI OAuth is a read-only native provider");
+    if (store.providers.filter(entry => entry.id === id).length > 1)
+        throw new TypeError("codexProviders/remove: duplicate provider ID is ambiguous; explicitly repair the conflicting identities before removing");
     const next = removeProvider(store, id);
     writeProviderStore(worldHome, next);
     return viewOf(worldHome, codexHome, next, syncedAt);

package/agent-codex/dist/codex-providers.js

@@ -99,6 +99,9 @@ export function providerEntry(value) {
     if (value === null || typeof value !== "object")
         return undefined;
     const record = value;
+    if (record["kind"] === "openai-oauth" && record["id"] === "openai-oauth") {
+        return { id: "openai-oauth", label: "OpenAI OAuth", kind: "openai-oauth", origin: "native", baseUrl: "", protocol: "responses", auth: { kind: "apiKey", value: "" }, models: [] };
+    }
     const id = record["id"];
     const label = str(record["label"]);
     const baseUrl = str(record["baseUrl"]);
@@ -144,7 +147,9 @@ export function readProviderStore(worldHome) {
     const rawRemoved = record["removed"];
     const removed = (Array.isArray(rawRemoved) ? rawRemoved : [])
         .filter((value) => typeof value === "string" && value.trim() !== "");
-    return { version: 1, providers, ...(removed.length === 0 ? {} : { removed }) };
+    const blockedNativeIds = Array.isArray(record["blockedNativeIds"])
+        ? [...new Set(record["blockedNativeIds"].filter((id) => id === "openai-oauth"))] : [];
+    return { version: 1, providers, ...(removed.length === 0 ? {} : { removed }), ...(blockedNativeIds.length === 0 ? {} : { blockedNativeIds }) };
 }
 /**
  * Persist the store atomically (tmp + rename) and 0600 — the file holds API
@@ -155,7 +160,7 @@ export function writeProviderStore(worldHome, store) {
     const path = providerStorePath(worldHome);
     mkdirSync(dirname(path), { recursive: true });
     const temp = `${path}.tmp-${process.pid}`;
-    writeFileSync(temp, `${JSON.stringify(store, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    writeFileSync(temp, `${JSON.stringify({ ...store, providers: store.providers.map(entry => entry.kind === "openai-oauth" ? { id: entry.id, label: entry.label, kind: entry.kind, origin: "native" } : entry) }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
     renameSync(temp, path);
 }
 /**
@@ -176,7 +181,8 @@ export function upsertProvider(store, entry) {
     // carry the tombstone forward, and the next sync would keep skipping the
     // endpoint the user just re-added.
     const { removed: _stale, ...rest } = store;
-    return { ...rest, providers, ...(removed.length === 0 ? {} : { removed }) };
+    const blockedNativeIds = [...new Set([...(store.blockedNativeIds ?? []), ...(entry.id === "openai-oauth" && entry.kind !== "openai-oauth" ? [entry.id] : [])])];
+    return { ...rest, providers, ...(removed.length === 0 ? {} : { removed }), ...(blockedNativeIds.length === 0 ? {} : { blockedNativeIds }) };
 }
 /**
  * Drop one provider, and TOMBSTONE its endpoint so the reconcile cannot bring
@@ -193,7 +199,8 @@ export function removeProvider(store, id) {
         return { ...store, providers };
     const key = endpointKey(entry.baseUrl);
     const removed = store.removed?.includes(key) === true ? store.removed : [...store.removed ?? [], key];
-    return { ...store, providers, removed };
+    const blockedNativeIds = [...new Set([...(store.blockedNativeIds ?? []), ...(entry.id === "openai-oauth" && entry.kind !== "openai-oauth" ? [entry.id] : [])])];
+    return { ...store, providers, removed, ...(blockedNativeIds.length === 0 ? {} : { blockedNativeIds }) };
 }
 /**
  * The comparison key for "the same endpoint". Codex itself treats two provider
@@ -330,7 +337,13 @@ export function syncNativeProviders(store, imported) {
         if (store.removed?.includes(key) === true)
             continue;
         const wantedId = incoming.nativeId !== undefined && isProviderId(incoming.nativeId) ? incoming.nativeId : undefined;
-        const at = providers.findIndex((entry) => (wantedId !== undefined && entry.id === wantedId) || endpointKey(entry.baseUrl) === key);
+        // A native identity is not an endpoint table. Never refresh it, rename a
+        // conflicting native table behind the user's back, or select a duplicate id.
+        if (wantedId === "openai-oauth" && (providers.some(entry => entry.id === wantedId && entry.kind === "openai-oauth")
+            || providers.filter(entry => entry.id === wantedId).length > 1))
+            continue;
+        const at = providers.findIndex((entry) => entry.kind !== "openai-oauth" &&
+            ((wantedId !== undefined && entry.id === wantedId) || endpointKey(entry.baseUrl) === key));
         if (at === -1) {
             const id = uniqueProviderId(wantedId ?? providerIdFromEndpoint(baseUrl), providers.map((entry) => entry.id));
             providers.push({
@@ -370,7 +383,7 @@ export function syncNativeProviders(store, imported) {
     }
     const removed = store.removed ?? [];
     const next = removed.length === 0
-        ? { version: 1, providers }
-        : { version: 1, providers, removed };
+        ? { ...store, version: 1, providers }
+        : { ...store, version: 1, providers, removed };
     return { store: next, added, updated };
 }

package/agent-codex/dist/codex-runtime-fetch.js

@@ -0,0 +1,293 @@
+/**
+ * codex-runtime-fetch.ts — the lazy, durable Codex runtime the app-server line
+ * falls back to when the operator has NO codex of their own.
+ *
+ * 2026-10-06 user ruling (amends the 2026-10-05 core-discovery order): the
+ * exact-pin `@openai/codex` package must NEVER ride the installation — it went
+ * out as a real `dependencies` entry in 0.1.11, so every registry consumer
+ * downloaded the pinned CLI binary package AND its six aliased platform
+ * binaries (linux-x64/arm64, darwin-x64/arm64, win32-x64/arm64) at install
+ * time. That is the omp-sdk/agy-sdk/codex-sdk rule violated one week after it
+ * was written: SDKs and binaries are second-class — anything a line needs, it
+ * fetches at RUNTIME into its world home, and installs stay clean (no
+ * postinstall, no allow-build, no dependency that ships a binary).
+ *
+ * So the discovery order in codex-runtime.ts is
+ *   CODEX_BIN → PATH CLI → desktop core → world-home runtime (this module),
+ * and this module is the only supplier of that last tier: on the first real
+ * prompt, when override, CLI and desktop all missed, the pinned
+ * `@openai/codex@0.160.0` tree is fetched into
+ *
+ *   <worldHome>/codex-runtime/
+ *     package.json                 written by us (private, never published)
+ *     node_modules/                `npm install --exact --ignore-scripts --omit=dev`
+ *     node_modules/@openai/codex/bin/codex.js   the entry discovery returns
+ *   <worldHome>/codex-runtime.json       marker — written LAST, after the smoke run
+ *   <worldHome>/codex-runtime.lock       atomic (mkdir) bootstrap lock
+ *   <worldHome>/codex-runtime.error.log  written ONLY by a failed fetch
+ *
+ * Why the world home rather than the package root: the package root is the
+ * installed tarball — read-only in every real consumer install, and shared by
+ * every world. The world home (`<dshHome>/agents/codex`) is per-runtime,
+ * writable, and already the home of this adapter's own DSH state.
+ *
+ * Readiness is the ENTRY FILE (checked on every discovery, zero network) plus
+ * the marker's package version: a pin bump in a future adapter must refetch,
+ * and the sync resolver alone would happily keep using the old tree.
+ *
+ * The npm invocation is deliberately `--ignore-scripts`: the codex packages
+ * ship their binaries inside the tarballs, so a fetch needs zero lifecycle
+ * scripts — exactly the property this ruling exists to protect.
+ */
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { resolveCodexRuntime } from "./codex-runtime.js";
+/** The pinned Codex CLI package this line fetches (ships the app-server binary). */
+export const CODEX_RUNTIME_PACKAGE = "@openai/codex";
+/** Pin of {@link CODEX_RUNTIME_PACKAGE}; bumping it must refetch the tree. */
+export const CODEX_RUNTIME_VERSION = "0.160.0";
+/** The entry `resolveCodexRuntime` returns, relative to the runtime dir. */
+const CODEX_ENTRY_RELATIVE = ["node_modules", CODEX_RUNTIME_PACKAGE, "bin", "codex.js"];
+export function codexRuntimeLayout(worldHome) {
+    const dir = join(worldHome, "codex-runtime");
+    return {
+        dir,
+        manifest: join(dir, "package.json"),
+        entry: join(dir, ...CODEX_ENTRY_RELATIVE),
+        marker: join(worldHome, "codex-runtime.json"),
+        lock: join(worldHome, "codex-runtime.lock"),
+        errorLog: join(worldHome, "codex-runtime.error.log"),
+    };
+}
+/** Read the install marker; undefined when absent or unreadable. */
+export function readCodexRuntimeRecord(worldHome) {
+    const { marker } = codexRuntimeLayout(worldHome);
+    if (!existsSync(marker))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(marker, "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fast path: a fetched runtime exists, matches `identity`, and its entry file
+ * is still on disk. Everything else must (re)fetch or (re)discover.
+ */
+export function codexRuntimeCurrent(worldHome, identity) {
+    const record = readCodexRuntimeRecord(worldHome);
+    if (record === undefined)
+        return undefined;
+    if (record.pluginVersion !== identity.pluginVersion)
+        return undefined;
+    if (record.packageVersion !== identity.packageVersion)
+        return undefined;
+    if (!existsSync(codexRuntimeLayout(worldHome).entry))
+        return undefined;
+    return record;
+}
+/** The npm argv the runtime tree is installed with (kept pure for the test). */
+export function codexInstallArgv(packageVersion = CODEX_RUNTIME_VERSION) {
+    return [
+        "install",
+        "--save-exact",
+        "--ignore-scripts",
+        "--omit=dev",
+        `${CODEX_RUNTIME_PACKAGE}@${packageVersion}`,
+    ];
+}
+/** A held lock older than this is treated as abandoned and reclaimed. */
+const LOCK_STALE_MS = 30 * 60 * 1000;
+/** The smoke run's wall-clock cap: `--version` must never wedge a turn. */
+const SMOKE_TIMEOUT_MS = 60_000;
+const execFileAsync = promisify(execFile);
+/**
+ * The PRODUCTION {@link CodexRuntimeFetchDeps}: real npm/Node invocations plus
+ * the marker identity read from this package's own manifest. Kept IN THE
+ * MODULE so the manual pre-warm script and the first-prompt lazy fetch share
+ * ONE implementation — a second copy is exactly how the two paths would drift.
+ */
+export function createCodexRuntimeDeps(options = {}) {
+    const pluginDir = options.pluginDir ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    return {
+        run: async (cmd, args, opts) => {
+            await execFileAsync(cmd, args, { cwd: opts?.cwd, env: options.env, maxBuffer: 64 * 1024 * 1024 });
+        },
+        smoke: async (cmd, args, opts) => {
+            const { stdout } = await execFileAsync(cmd, args, {
+                cwd: opts?.cwd,
+                env: options.env,
+                timeout: opts?.timeoutMs,
+                maxBuffer: 1024 * 1024,
+            });
+            return stdout;
+        },
+        pluginVersion: readPluginVersion(pluginDir),
+        log: (line) => process.stderr.write(`[agent-codex] ${line}\n`),
+        ...(options.env === undefined ? {} : { env: options.env }),
+    };
+}
+/** The version of the adapter package at `pluginDir` (the marker identity half). */
+export function readPluginVersion(pluginDir) {
+    const raw = readFileSync(join(pluginDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== "string" || parsed.version === "") {
+        throw new Error(`codex: ${join(pluginDir, "package.json")} carries no version`);
+    }
+    return parsed.version;
+}
+/**
+ * Sync discovery across the whole ladder INCLUDING the fetched runtime; a
+ * miss throws (which is the fetch trigger, never surfaced to the user).
+ */
+function discoverWith(worldHome, deps) {
+    return resolveCodexRuntime({
+        ...(deps.discovery ?? {}),
+        ...(deps.env === undefined ? {} : { env: deps.env }),
+        packageEntryCandidates: [codexRuntimeLayout(worldHome).entry],
+    });
+}
+/**
+ * Return a usable Codex runtime for `<worldHome>`, fetching the pinned
+ * package first when the operator's own CODEX_BIN / PATH CLI / desktop core
+ * all miss.
+ *
+ * Idempotent: an operator-provided runtime short-circuits without touching
+ * the network, and so does a complete, matching fetched runtime. Concurrent
+ * callers: the bootstrap is guarded by a `mkdir` lock — a second caller that
+ * finds a FRESH lock throws a clear "fetch in progress" error, while an
+ * abandoned lock (older than {@link LOCK_STALE_MS}) is reclaimed so a crashed
+ * fetch cannot brick the line.
+ *
+ * Failures append to `<worldHome>/codex-runtime.error.log` and throw a single
+ * actionable error — never a partial runtime behind a success marker.
+ */
+export async function ensureCodexRuntime(worldHome, deps) {
+    const usable = (() => {
+        try {
+            return discoverWith(worldHome, deps);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    // An operator runtime (override/CLI/desktop) is always taken as-is; a fetched
+    // runtime is taken only when its pin still matches — a bumped pin refetches.
+    if (usable !== undefined && usable.source !== "package")
+        return usable;
+    const identity = { pluginVersion: deps.pluginVersion, packageVersion: CODEX_RUNTIME_VERSION };
+    if (usable !== undefined && codexRuntimeCurrent(worldHome, identity) !== undefined)
+        return usable;
+    const layout = codexRuntimeLayout(worldHome);
+    mkdirSync(worldHome, { recursive: true });
+    acquireLock(layout, deps);
+    try {
+        // Re-check inside the lock: a peer may have completed the fetch in the
+        // window between our check and the lock, in which case we pay nothing.
+        const raced = (() => {
+            try {
+                return discoverWith(worldHome, deps);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (raced !== undefined && (raced.source !== "package" || codexRuntimeCurrent(worldHome, identity) !== undefined))
+            return raced;
+        try {
+            await buildRuntime(layout, deps, identity);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const stamp = new Date().toISOString();
+            try {
+                appendFileSync(layout.errorLog, `[${stamp}] codex runtime fetch failed: ${detail}\n`);
+            }
+            catch {
+                /* the trace is best-effort; the throw below is the contract */
+            }
+            throw new Error(`codex: could not fetch the runtime (${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION}) at ${layout.dir}: ${detail}. ` +
+                `Pre-warm it by hand with \`npm run fetch-codex-runtime\`, or install a Codex CLI and set CODEX_BIN. Trace: ${layout.errorLog}`);
+        }
+        const resolved = discoverWith(worldHome, deps);
+        deps.log(`codex: runtime ready at ${layout.dir} (${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION})`);
+        return resolved;
+    }
+    finally {
+        rmSync(layout.lock, { recursive: true, force: true });
+    }
+}
+/** The idempotent build steps; the marker is written last, after the smoke run. */
+async function buildRuntime(layout, deps, identity) {
+    mkdirSync(layout.dir, { recursive: true });
+    // npm needs a manifest to own the tree; `private` + a throwaway version keep
+    // it unambiguously not-a-publishable-package, and an existing one is left
+    // alone so a later install can still be reproduced by hand.
+    if (!existsSync(layout.manifest)) {
+        writeFileSync(layout.manifest, JSON.stringify({ name: "codex-runtime", private: true, version: "0.0.0" }, null, 2) + "\n");
+    }
+    deps.log(`codex: fetching ${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION} into ${layout.dir}`);
+    await deps.run("npm", codexInstallArgv(), { cwd: layout.dir });
+    if (!existsSync(layout.entry)) {
+        throw new Error(`npm install produced no ${layout.entry} (the package layout changed?)`);
+    }
+    // Smoke step: run the fetched entry's `--version`. This exercises the real
+    // platform-binary pick the entry performs at run time — a tree whose binary
+    // does not match this host fails HERE, at the fetch, with a trace on disk,
+    // instead of at the first prompt inside the agent's cold-start error path.
+    // The entry is resolved ABSOLUTE before the cwd switch — the smoke run
+    // changes the working directory, and a relative worldHome would otherwise
+    // re-resolve against it (same trap as the `-c model_catalog_json` lesson).
+    const smokeEntry = resolve(layout.entry);
+    deps.log(`codex: smoke-running ${CODEX_RUNTIME_PACKAGE}@${CODEX_RUNTIME_VERSION} --version`);
+    const stdout = await deps.smoke(process.execPath, [smokeEntry, "--version"], { cwd: layout.dir, timeoutMs: SMOKE_TIMEOUT_MS });
+    const smokeVersion = stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (smokeVersion === "") {
+        throw new Error(`smoke run of ${layout.entry} --version produced no output`);
+    }
+    // Marker LAST — a crash before this point leaves an incomplete runtime that
+    // the next call heals, never a false success.
+    const record = {
+        ...identity,
+        entryPath: layout.entry,
+        smokeVersion,
+        installedAt: new Date().toISOString(),
+    };
+    writeFileSync(layout.marker, JSON.stringify(record, null, 2) + "\n");
+    rmSync(layout.errorLog, { force: true });
+}
+/**
+ * mkdir-based mutex. Returns owning the lock; throws when a fresh lock is held
+ * by someone else; reclaims a lock older than {@link LOCK_STALE_MS}.
+ */
+function acquireLock(layout, deps) {
+    for (;;) {
+        try {
+            mkdirSync(layout.lock);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        let ageMs;
+        try {
+            ageMs = Date.now() - statSync(layout.lock).mtimeMs;
+        }
+        catch {
+            continue; // released between the mkdir attempt and the stat — retry now
+        }
+        if (ageMs > LOCK_STALE_MS) {
+            deps.log(`codex: reclaiming stale runtime lock (age ${Math.round(ageMs / 1000)}s)`);
+            rmSync(layout.lock, { recursive: true, force: true });
+            continue;
+        }
+        throw new Error(`codex: another runtime fetch is already in progress (lock ${layout.lock}). ` +
+            `Retry once it finishes; if no fetch is running, remove that lock directory.`);
+    }
+}

package/agent-codex/dist/codex-runtime.js

@@ -0,0 +1,120 @@
+/** Resolve an installed Codex runtime at first use, without modifying its home. */
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+function readableFile(path) {
+    try {
+        accessSync(path, constants.R_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function executable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function desktopPaths(discovery) {
+    if (discovery.desktopCandidates !== undefined)
+        return discovery.desktopCandidates;
+    const explicit = discovery.env.CODEX_DESKTOP_BIN?.trim();
+    const paths = explicit ? [explicit] : [];
+    if (discovery.platform === "linux") {
+        paths.push("/usr/lib/chatgpt/resources/codex", "/usr/lib/codex/resources/codex", "/opt/Codex/resources/codex", "/opt/codex/resources/codex");
+    }
+    else if (discovery.platform === "darwin") {
+        for (const root of ["/Applications", posix.join(discovery.homeDir, "Applications")]) {
+            for (const app of ["Codex.app", "ChatGPT.app"])
+                paths.push(posix.join(root, app, "Contents/Resources/codex"));
+        }
+    }
+    else if (discovery.platform === "win32") {
+        const local = discovery.env.LOCALAPPDATA;
+        if (local) {
+            for (const app of ["Codex", "ChatGPT"])
+                paths.push(win32.join(local, "Programs", app, "resources", "codex.exe"));
+        }
+    }
+    return paths;
+}
+function isNodeScript(command, discovery) {
+    let target = command;
+    try {
+        target = discovery.realpath(command);
+    }
+    catch {
+        // Explicit nonexistent paths are rejected by the file check below.
+    }
+    return /\.(?:[cm]?js)$/i.test(target);
+}
+export function resolveCodexRuntime(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const isFile = options.isFile ?? readableFile;
+    const isExecutable = options.isExecutable ?? executable;
+    const path = platform === "win32" ? win32 : posix;
+    const shellWrapper = (command) => platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+    const discovery = {
+        platform,
+        env,
+        homeDir: options.homeDir ?? homedir(),
+        ...(options.desktopCandidates === undefined ? {} : { desktopCandidates: options.desktopCandidates }),
+        ...(options.packageEntryCandidates === undefined ? {} : { packageEntryCandidates: options.packageEntryCandidates }),
+        isFile,
+        isExecutable,
+        realpath: options.realpath ?? realpathSync,
+        findCommand: options.findCommand ?? ((name) => {
+            const suffixes = platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")] : [""];
+            for (const directory of (env.PATH ?? "").split(platform === "win32" ? ";" : ":")) {
+                if (directory === "")
+                    continue;
+                for (const suffix of suffixes) {
+                    const candidate = path.join(directory, `${name}${suffix}`);
+                    if (shellWrapper(candidate))
+                        continue;
+                    if (isFile(candidate) && isExecutable(candidate))
+                        return candidate;
+                }
+            }
+            return undefined;
+        }),
+    };
+    const usable = (command) => !shellWrapper(command) && isFile(command) && (isNodeScript(command, discovery) || isExecutable(command));
+    const selected = (command, source) => ({ command, nodeScript: isNodeScript(command, discovery), source });
+    const override = env.CODEX_BIN?.trim();
+    if (override) {
+        const command = /[\\/]/.test(override) ? override : discovery.findCommand(override) ?? override;
+        if (shellWrapper(command))
+            throw new Error(`CODEX_BIN ${override} is a Windows .cmd/.bat shell wrapper. Set CODEX_BIN to the native codex.exe executable or the @openai/codex JavaScript entry instead.`);
+        if (!usable(command))
+            throw new Error(`CODEX_BIN ${override} is not a readable JavaScript entry or executable Codex runtime. Fix CODEX_BIN or remove the override.`);
+        return selected(command, "override");
+    }
+    const cli = discovery.findCommand("codex");
+    if (cli !== undefined && usable(cli))
+        return selected(cli, "cli");
+    for (const candidate of desktopPaths(discovery)) {
+        if (!shellWrapper(candidate) && isFile(candidate) && isExecutable(candidate))
+            return selected(candidate, "desktop");
+    }
+    // Last resort only: the runtime the fetch layer materialized into the world
+    // home. It cannot pre-exist on a clean install — the fetch only runs when the
+    // override, CLI and desktop all missed, so checking it last is exact.
+    for (const entry of discovery.packageEntryCandidates ?? []) {
+        if (!shellWrapper(entry) && isFile(entry))
+            return { command: entry, nodeScript: true, source: "package" };
+    }
+    throw new Error("cannot locate a Codex runtime: install a Codex CLI (or the desktop app) on PATH, " +
+        "set CODEX_BIN to its executable or JavaScript entry, " +
+        "or let the adapter fetch the pinned @openai/codex package into the world home at first prompt.");
+}
+/** Compatibility interface for callers that need only the selected path. */
+export function resolveCodexCommand(options = {}) {
+    return resolveCodexRuntime(options).command;
+}