@velum-labs/routekit-tool-codex 1.3.2 → 1.5.0

package/README.md

@@ -21,7 +21,8 @@ import { codexTool } from "@velum-labs/routekit-tool-codex";
 
 ## Native client ownership
 
-The launcher uses the user's normal `CODEX_HOME`, applies gateway routing as
-process-scoped configuration, and keeps credentials in the environment. RouteKit
-does not observe, store, resume, or delete Codex sessions; use Codex's native
-history and commands directly.
+The launcher uses a RouteKit-owned `CODEX_HOME`, pins Codex authentication to
+its private file store, applies gateway routing as process-scoped configuration,
+and keeps gateway credentials in the environment. RouteKit does not observe,
+store, resume, or delete Codex sessions; use Codex's native history and commands
+directly.

package/dist/driver.js

@@ -1,4 +1,5 @@
-import { rmSync } from "node:fs";
+import { rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { Codex } from "@openai/codex-sdk";
 import { asHarnessError, buildChildEnv, createCachedHarnessDriver, HarnessError, nowIso, probeCliVersion, resolveDriverEnv, resumeStringField, SessionResourceRegistry, SingleFlightTurnController } from "@velum-labs/routekit-harness-core";
 import { ResourceScope } from "@velum-labs/routekit-runtime/lifecycle";
@@ -81,9 +82,10 @@ function codexOptionsFor(config, context, isolatedHome) {
         childEnv.CODEX_HOME = isolatedHome;
     return {
         codexPathOverride: config.command,
-        ...(config.provider.baseUrl !== undefined
-            ? {
-                config: {
+        config: {
+            cli_auth_credentials_store: "file",
+            ...(config.provider.baseUrl !== undefined
+                ? {
                     model_provider: "routekit",
                     model_providers: {
                         routekit: {
@@ -95,8 +97,8 @@ function codexOptionsFor(config, context, isolatedHome) {
                         }
                     }
                 }
-            }
-            : {}),
+                : {})
+        },
         ...(apiKey !== undefined ? { apiKey } : {}),
         env: childEnv
     };
@@ -359,17 +361,18 @@ class CodexInstance {
         return this.#status;
     }
     /**
-     * Gateway-routed sessions use an instance-owned `CODEX_HOME`, preventing the
-     * user's config and model cache from leaking into the routed session. An
-     * explicitly supplied home remains borrowed and is never removed here.
+     * Every RouteKit Codex session uses an instance-owned `CODEX_HOME`, preventing
+     * the user's config, auth state, and model cache from leaking into the child.
+     * An explicitly supplied home remains borrowed and is never removed here.
      */
     #createOwnedHome() {
-        if (this.#config.provider.baseUrl === undefined)
-            return undefined;
         const env = resolveDriverEnv(this.#context);
         if (env.CODEX_HOME !== undefined)
             return undefined;
         const home = createIsolatedCodexHome("routekit-codex-driver-", env);
+        writeFileSync(join(home, "config.toml"), 'cli_auth_credentials_store = "file"\n', {
+            mode: 0o600
+        });
         this.#resources.defer(() => rmSync(home, { recursive: true, force: true }));
         return home;
     }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { ToolIntegration } from "@velum-labs/routekit-tools";
 export declare const codexTool: ToolIntegration;
 export type { CodexDriverConfig } from "./driver.js";
 export { codexDriverConfigSchema, createCodexDriver } from "./driver.js";
-export type { CodexInstallInput, CodexInstallOwner, CodexInstallProfile, CodexInstallResult } from "./install.js";
-export { codexIntegrationBlock, codexIntegrationConfigPath, installCodexIntegration, uninstallCodexIntegration } from "./install.js";
+export type { CodexConfigLockScope, CodexInstallInput, CodexInstallOwner, CodexInstallProfile, CodexInstallResult } from "./install.js";
+export { acquireCodexConfigLock, codexIntegrationBlock, codexIntegrationConfigPath, installCodexIntegration, uninstallCodexIntegration, withCodexConfigLock } from "./install.js";
 export type { CodexAgentRole, CodexModelPreset } from "./launch.js";
-export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexPersistentModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexHomeModelsCache, readCodexModelsCache } from "./launch.js";
+export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexPersistentModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexHomeModelsCache, readCodexModelsCache, resolveRouteKitCodexHome } from "./launch.js";

package/dist/index.js

@@ -36,5 +36,5 @@ export const codexTool = {
     }
 };
 export { codexDriverConfigSchema, createCodexDriver } from "./driver.js";
-export { codexIntegrationBlock, codexIntegrationConfigPath, installCodexIntegration, uninstallCodexIntegration } from "./install.js";
-export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexPersistentModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexHomeModelsCache, readCodexModelsCache } from "./launch.js";
+export { acquireCodexConfigLock, codexIntegrationBlock, codexIntegrationConfigPath, installCodexIntegration, uninstallCodexIntegration, withCodexConfigLock } from "./install.js";
+export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexPersistentModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexHomeModelsCache, readCodexModelsCache, resolveRouteKitCodexHome } from "./launch.js";

package/dist/install.d.ts

@@ -1,8 +1,9 @@
-import type { ModelReasoningCapabilities } from "@velum-labs/routekit-contracts";
+import type { ModelReasoningCapabilities, ModelServiceTierCapabilities } from "@velum-labs/routekit-contracts";
 export type CodexInstallProfile = {
     modelId: string;
     description?: string;
     reasoning?: ModelReasoningCapabilities;
+    serviceTiers?: ModelServiceTierCapabilities;
 };
 export type CodexInstallOwner = {
     id: string;
@@ -18,6 +19,11 @@ export type CodexInstallInput = {
     models: readonly CodexInstallProfile[];
     /** Model selected when the single RouteKit profile is first opened. */
     defaultModel?: string;
+    /**
+     * Repository policy context for this managed provider. Codex sends provider
+     * headers for every model, so explicit-model requests carry this context too.
+     */
+    repositoryConnectionId?: string;
     /** Safe selector for the one persistent RouteKit profile. */
     profileId?: string;
     /**
@@ -49,3 +55,22 @@ export declare function uninstallCodexIntegration(input: {
     configPath: string;
     removed: boolean;
 };
+export type CodexConfigLockScope = Readonly<{
+    install(input: CodexInstallInput): CodexInstallResult;
+    uninstall(input: {
+        ownerId: string;
+        codexHome?: string;
+    }): {
+        configPath: string;
+        removed: boolean;
+    };
+    /** Restore interrupted owner writes without beginning a new install or uninstall. */
+    recover(ownerId: string): void;
+    release(): void;
+}>;
+/**
+ * Hold the same owner-neutral home lock across a larger async CLI transaction.
+ * Scoped methods avoid reacquiring the non-reentrant synchronous lock.
+ */
+export declare function acquireCodexConfigLock(codexHome?: string): Promise<CodexConfigLockScope>;
+export declare function withCodexConfigLock<A>(codexHome: string | undefined, callback: (scope: CodexConfigLockScope) => Promise<A> | A): Promise<A>;

package/dist/install.js

@@ -1,9 +1,11 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { parse as tomlParse, stringify as tomlStringify } from "smol-toml";
 import { SUBSCRIPTIONS } from "@velum-labs/routekit-registry";
+import { writeFileAtomic } from "@velum-labs/routekit-runtime/filesystem";
 import { gatewayOpenAiBaseUrl } from "@velum-labs/routekit-runtime/network";
+import { acquireLifecycleLock, acquireLifecycleLockSync } from "@velum-labs/routekit-runtime/service";
 import { codexPersistentModelCatalogJson, codexProfileFileToml, readCodexHomeModelsCache } from "./launch.js";
 export function codexIntegrationConfigPath(codexHome) {
     if (codexHome !== undefined)
@@ -35,9 +37,214 @@ function profileFileName(selector) {
     }
     return `${selector}.config.toml`;
 }
+function pendingPath(codexHome, ownerId) {
+    catalogFileName(ownerId);
+    return join(codexHome, `.${ownerId}-install-pending.json`);
+}
+function uninstallPendingPath(codexHome, ownerId) {
+    catalogFileName(ownerId);
+    return join(codexHome, `.${ownerId}-uninstall-pending.json`);
+}
+function configLockPath(codexHome) {
+    return join(resolve(codexHome), ".routekit-codex-config.lock");
+}
+function snapshot(path) {
+    let entry;
+    try {
+        entry = lstatSync(path);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT") {
+            return { content: null, mode: null };
+        }
+        throw cause;
+    }
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+        throw new Error(`Codex integration refuses a non-regular file: ${path}`);
+    }
+    return { content: readFileSync(path, "utf8"), mode: entry.mode & 0o777 };
+}
+function applySnapshot(path, value) {
+    if (value.content === null) {
+        rmSync(path, { force: true });
+        return;
+    }
+    const mode = value.mode ?? 0o600;
+    writeFileAtomic(path, value.content, { mode });
+}
+function sameSnapshot(left, right) {
+    return left.content === right.content && left.mode === right.mode;
+}
+function validSnapshot(value) {
+    if (!isRecord(value))
+        return false;
+    if (!((typeof value.content === "string" && Number.isInteger(value.mode)) ||
+        (value.content === null && value.mode === null)))
+        return false;
+    return value.mode === null || (typeof value.mode === "number" && value.mode >= 0 && value.mode <= 0o777);
+}
+function readPending(path) {
+    const entry = (() => {
+        try {
+            return lstatSync(path);
+        }
+        catch (cause) {
+            if (cause.code === "ENOENT")
+                return undefined;
+            throw cause;
+        }
+    })();
+    if (entry === undefined)
+        return;
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+        throw new Error(`Codex pending integration metadata is not a regular file: ${path}`);
+    }
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`Codex pending integration metadata is corrupt: ${path}`);
+    }
+}
+function recoverFiles(codexHome, path, files, committed) {
+    if (committed) {
+        // A completed operation must never be rolled back merely because journal
+        // cleanup failed after its commit marker was atomically published.
+        rmSync(path);
+        return;
+    }
+    // Validate every current file before restoring any: an external edit must
+    // never be partially rolled back, even after a process crash.
+    for (const file of files) {
+        const current = snapshot(join(codexHome, file.name));
+        if (!sameSnapshot(current, file.before) && !sameSnapshot(current, file.target)) {
+            throw new Error(`Codex settings changed during interrupted integration (${file.name}); ` +
+                "RouteKit refused to overwrite the external edit");
+        }
+    }
+    for (const file of files)
+        applySnapshot(join(codexHome, file.name), file.before);
+    rmSync(path);
+}
+function completeJournal(path, journal) {
+    writeFileAtomic(path, `${JSON.stringify({ ...journal, phase: "committed" })}\n`, {
+        mode: 0o600
+    });
+    try {
+        rmSync(path);
+    }
+    catch {
+        // The committed marker is published. Retain it for the next locked operation
+        // to clean up; reporting a failed install here would misstate its outcome.
+    }
+}
+function recoverPendingInstall(codexHome, ownerId) {
+    const path = pendingPath(codexHome, ownerId);
+    const parsed = readPending(path);
+    if (parsed === undefined)
+        return;
+    if (!isRecord(parsed) || parsed.version !== 1 || parsed.ownerId !== ownerId ||
+        (parsed.phase !== undefined && parsed.phase !== "committed") ||
+        !Array.isArray(parsed.files) || parsed.files.length !== 3) {
+        throw new Error(`Codex pending installation metadata is corrupt: ${path}`);
+    }
+    const files = [];
+    for (const value of parsed.files) {
+        if (!isRecord(value) || typeof value.name !== "string" ||
+            !validSnapshot(value.before) || !validSnapshot(value.target) ||
+            value.target.content === null) {
+            throw new Error(`Codex pending installation metadata is corrupt: ${path}`);
+        }
+        files.push({ name: value.name, before: value.before, target: value.target });
+    }
+    const names = files.map((value) => value.name);
+    if (names[0] !== catalogFileName(ownerId) ||
+        names[1] === undefined || !names[1].endsWith(".config.toml") ||
+        names[1].includes("/") || names[1].includes("\\") ||
+        names[2] !== "config.toml" || new Set(names).size !== 3) {
+        throw new Error(`Codex pending installation metadata is corrupt: ${path}`);
+    }
+    recoverFiles(codexHome, path, files, parsed.phase === "committed");
+}
+function withoutManagedBlock(before, ownerId) {
+    const split = splitManagedBlock(before, ownerId);
+    if (split.managed === undefined)
+        return undefined;
+    const head = normalize(split.before);
+    const tail = normalize(split.after);
+    return `${head}${head.length > 0 && tail.length > 0 ? "\n" : ""}${tail}`;
+}
+function recoverPendingUninstall(codexHome, ownerId) {
+    const path = uninstallPendingPath(codexHome, ownerId);
+    const parsed = readPending(path);
+    if (parsed === undefined)
+        return;
+    if (!isRecord(parsed) || parsed.version !== 1 || parsed.ownerId !== ownerId ||
+        (parsed.phase !== undefined && parsed.phase !== "committed") ||
+        !Array.isArray(parsed.files) || parsed.files.length < 1) {
+        throw new Error(`Codex pending uninstallation metadata is corrupt: ${path}`);
+    }
+    const files = [];
+    for (const value of parsed.files) {
+        if (!isRecord(value) || typeof value.name !== "string" ||
+            !validSnapshot(value.before) || !validSnapshot(value.target)) {
+            throw new Error(`Codex pending uninstallation metadata is corrupt: ${path}`);
+        }
+        files.push({ name: value.name, before: value.before, target: value.target });
+    }
+    const config = files[0];
+    const desired = config.before.content === null
+        ? undefined
+        : withoutManagedBlock(config.before.content, ownerId);
+    if (config.name !== "config.toml" || desired === undefined ||
+        config.target.content !== desired || config.target.mode !== config.before.mode) {
+        throw new Error(`Codex pending uninstallation metadata is corrupt: ${path}`);
+    }
+    const managed = splitManagedBlock(config.before.content, ownerId).managed;
+    const profileNames = new Set(ownedProfileFiles(managed, codexHome, ownerId).map((file) => basename(file)));
+    const catalog = ownedCatalogFile(managed, codexHome, ownerId);
+    const catalogName = catalog === undefined ? undefined : basename(catalog);
+    const names = new Set();
+    for (const file of files) {
+        if (names.has(file.name))
+            throw new Error(`Codex pending uninstallation metadata is corrupt: ${path}`);
+        names.add(file.name);
+    }
+    for (const file of files.slice(1)) {
+        const ownedProfile = profileNames.has(file.name) &&
+            file.before.content?.includes(`Managed by ${ownerId}`) === true;
+        if ((!ownedProfile && file.name !== catalogName) ||
+            file.before.content === null || file.target.content !== null || file.target.mode !== null) {
+            throw new Error(`Codex pending uninstallation metadata is corrupt: ${path}`);
+        }
+    }
+    recoverFiles(codexHome, path, files, parsed.phase === "committed");
+}
+function recoverPendingChanges(codexHome, ownerId) {
+    recoverPendingInstall(codexHome, ownerId);
+    recoverPendingUninstall(codexHome, ownerId);
+}
+function reachedInstallBoundary(boundary) {
+    const testingGlobal = globalThis;
+    testingGlobal.__routekitCodexInstallFaultInjector?.(boundary);
+}
+function reachedUninstallBoundary(boundary) {
+    const testingGlobal = globalThis;
+    testingGlobal.__routekitCodexUninstallFaultInjector?.(boundary);
+}
 function selectedProfileId(input) {
     return input.profileId ?? "routekit";
 }
+function repositoryConnectionHeader(connectionId) {
+    if (connectionId === undefined)
+        return undefined;
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(connectionId)) {
+        throw new Error("Codex repository connection id must be a UUID");
+    }
+    return {
+        "X-RouteKit-Repository-Connection-Id": connectionId.toLowerCase()
+    };
+}
 function selectedDefaultModel(input) {
     const model = input.defaultModel ?? input.models[0]?.modelId;
     if (model === undefined)
@@ -56,6 +263,7 @@ function orderedCatalogProfiles(profiles, defaultModel) {
 /** Serialize one additive, owner-marked Codex provider block. */
 export function codexIntegrationBlock(input) {
     const base = gatewayOpenAiBaseUrl(input.gatewayUrl);
+    const httpHeaders = repositoryConnectionHeader(input.repositoryConnectionId);
     const begin = marker(input.owner.id, "begin");
     const end = marker(input.owner.id, "end");
     const filesComment = profileFilesComment(input.owner.id);
@@ -63,11 +271,13 @@ export function codexIntegrationBlock(input) {
     const catalogFile = catalogFileName(input.owner.id);
     const profileId = selectedProfileId(input);
     const body = tomlStringify({
+        cli_auth_credentials_store: "file",
         model_providers: {
             [input.owner.providerId]: {
                 name: `${input.owner.displayName} gateway`,
                 base_url: base,
                 wire_api: "responses",
+                ...(httpHeaders !== undefined ? { http_headers: httpHeaders } : {}),
                 ...(input.auth !== undefined
                     ? {
                         auth: {
@@ -167,18 +377,6 @@ function normalize(content) {
     const trimmed = content.replace(/\s+$/, "");
     return trimmed.length === 0 ? "" : `${trimmed}\n`;
 }
-function removeOwnedProfileFile(path, ownerId) {
-    try {
-        if (!existsSync(path))
-            return;
-        if (!readFileSync(path, "utf8").includes(`Managed by ${ownerId}`))
-            return;
-        rmSync(path);
-    }
-    catch {
-        // Best-effort cleanup; an orphaned profile does not alter the main config.
-    }
-}
 function assertProfileFileCanBeManaged(path, ownerId) {
     if (!existsSync(path))
         return;
@@ -187,13 +385,14 @@ function assertProfileFileCanBeManaged(path, ownerId) {
     throw new Error(`refusing to overwrite an existing Codex profile: ${path}; ` +
         `rename it, then rerun the RouteKit install`);
 }
-export function installCodexIntegration(input) {
+function installCodexIntegrationUnlocked(input) {
     if (input.models.length === 0)
         throw new Error("at least one Codex catalog model is required");
     const defaultModel = selectedDefaultModel(input);
     const profileId = selectedProfileId(input);
     const configPath = codexIntegrationConfigPath(input.codexHome);
     const codexHome = dirname(configPath);
+    recoverPendingChanges(codexHome, input.owner.id);
     const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
     const { before, managed, after } = splitManagedBlock(existing, input.owner.id);
     const outside = parseTomlOrThrow(`${normalize(before)}\n${normalize(after)}`, `your Codex config (${configPath})`);
@@ -215,12 +414,44 @@ export function installCodexIntegration(input) {
     const persistentProfilePath = join(codexHome, profileFileName(profileId));
     assertProfileFileCanBeManaged(persistentProfilePath, input.owner.id);
     mkdirSync(codexHome, { recursive: true });
-    writeFileSync(catalogPath, codexPersistentModelCatalogJson(orderedCatalogProfiles(input.models, defaultModel).map((profile) => ({
-        id: profile.modelId,
-        ...(profile.reasoning !== undefined ? { reasoning: profile.reasoning } : {})
-    })), readCodexHomeModelsCache(codexHome)[0]), { mode: 0o600 });
-    writeFileSync(persistentProfilePath, `# Managed by ${input.owner.id}\n${codexProfileFileToml(defaultModel, input.owner.providerId, catalogPath)}`, { mode: 0o600 });
-    writeFileSync(configPath, next);
+    const files = [
+        {
+            name: catalogFileName(input.owner.id),
+            before: snapshot(catalogPath),
+            target: {
+                content: codexPersistentModelCatalogJson(orderedCatalogProfiles(input.models, defaultModel).map((profile) => ({
+                    id: profile.modelId,
+                    ...(profile.reasoning !== undefined ? { reasoning: profile.reasoning } : {}),
+                    ...(profile.serviceTiers !== undefined ? { serviceTiers: profile.serviceTiers } : {})
+                })), readCodexHomeModelsCache(codexHome)[0]),
+                mode: 0o600
+            }
+        },
+        {
+            name: profileFileName(profileId),
+            before: snapshot(persistentProfilePath),
+            target: {
+                content: `# Managed by ${input.owner.id}\n${codexProfileFileToml(defaultModel, input.owner.providerId, catalogPath)}`,
+                mode: 0o600
+            }
+        },
+        {
+            name: "config.toml",
+            before: snapshot(configPath),
+            target: { content: next, mode: snapshot(configPath).mode ?? 0o600 }
+        }
+    ];
+    const journal = pendingPath(codexHome, input.owner.id);
+    const pending = {
+        version: 1, ownerId: input.owner.id, files
+    };
+    writeFileAtomic(journal, `${JSON.stringify(pending)}\n`, { mode: 0o600 });
+    reachedInstallBoundary("pending");
+    for (const [index, file] of files.entries()) {
+        applySnapshot(join(codexHome, file.name), file.target);
+        reachedInstallBoundary(index === 0 ? "catalog" : index === 1 ? "profile" : "config");
+    }
+    completeJournal(journal, pending);
     return {
         configPath,
         catalogPath,
@@ -228,22 +459,119 @@ export function installCodexIntegration(input) {
         profiles: [profileId]
     };
 }
-export function uninstallCodexIntegration(input) {
+export function installCodexIntegration(input) {
+    const lock = acquireLifecycleLockSync(configLockPath(dirname(codexIntegrationConfigPath(input.codexHome))));
+    try {
+        return installCodexIntegrationUnlocked(input);
+    }
+    finally {
+        lock.release();
+    }
+}
+function uninstallCodexIntegrationUnlocked(input) {
     const configPath = codexIntegrationConfigPath(input.codexHome);
+    const codexHome = dirname(configPath);
+    recoverPendingChanges(codexHome, input.ownerId);
     if (!existsSync(configPath))
         return { configPath, removed: false };
     const existing = readFileSync(configPath, "utf8");
     const { before, managed, after } = splitManagedBlock(existing, input.ownerId);
     if (managed === undefined)
         return { configPath, removed: false };
-    for (const owned of ownedProfileFiles(managed, dirname(configPath), input.ownerId)) {
-        removeOwnedProfileFile(owned, input.ownerId);
+    const desired = withoutManagedBlock(existing, input.ownerId);
+    const config = snapshot(configPath);
+    const files = [
+        {
+            name: "config.toml",
+            before: config,
+            target: { content: desired, mode: config.mode }
+        }
+    ];
+    for (const path of ownedProfileFiles(managed, codexHome, input.ownerId)) {
+        const before = snapshot(path);
+        if (before.content?.includes(`Managed by ${input.ownerId}`) === true) {
+            files.push({
+                name: basename(path),
+                before,
+                target: { content: null, mode: null }
+            });
+        }
     }
-    const catalogPath = ownedCatalogFile(managed, dirname(configPath), input.ownerId);
-    if (catalogPath !== undefined)
-        rmSync(catalogPath, { force: true });
-    const head = normalize(before);
-    const tail = normalize(after);
-    writeFileSync(configPath, `${head}${head.length > 0 && tail.length > 0 ? "\n" : ""}${tail}`);
+    const catalogPath = ownedCatalogFile(managed, codexHome, input.ownerId);
+    if (catalogPath !== undefined) {
+        const before = snapshot(catalogPath);
+        if (before.content !== null) {
+            files.push({
+                name: basename(catalogPath),
+                before,
+                target: { content: null, mode: null }
+            });
+        }
+    }
+    const journal = uninstallPendingPath(codexHome, input.ownerId);
+    const pending = {
+        version: 1, ownerId: input.ownerId, files
+    };
+    writeFileAtomic(journal, `${JSON.stringify(pending)}\n`, { mode: 0o600 });
+    reachedUninstallBoundary("pending");
+    for (const [index, file] of files.entries()) {
+        applySnapshot(join(codexHome, file.name), file.target);
+        reachedUninstallBoundary(index === 0 ? "config" : file.name === catalogFileName(input.ownerId) ? "catalog" : "profile");
+    }
+    completeJournal(journal, pending);
     return { configPath, removed: true };
 }
+export function uninstallCodexIntegration(input) {
+    const lock = acquireLifecycleLockSync(configLockPath(dirname(codexIntegrationConfigPath(input.codexHome))));
+    try {
+        return uninstallCodexIntegrationUnlocked(input);
+    }
+    finally {
+        lock.release();
+    }
+}
+/**
+ * Hold the same owner-neutral home lock across a larger async CLI transaction.
+ * Scoped methods avoid reacquiring the non-reentrant synchronous lock.
+ */
+export async function acquireCodexConfigLock(codexHome) {
+    const configPath = resolve(codexIntegrationConfigPath(codexHome));
+    const lock = await acquireLifecycleLock(configLockPath(dirname(configPath)));
+    let released = false;
+    const assertScope = (inputHome) => {
+        if (released)
+            throw new Error("Codex configuration lock has already been released");
+        if (resolve(codexIntegrationConfigPath(inputHome)) !== configPath) {
+            throw new Error("Codex integration target does not match the locked home");
+        }
+    };
+    return {
+        install(input) {
+            assertScope(input.codexHome);
+            return installCodexIntegrationUnlocked(input);
+        },
+        uninstall(input) {
+            assertScope(input.codexHome);
+            return uninstallCodexIntegrationUnlocked(input);
+        },
+        recover(ownerId) {
+            assertScope(codexHome);
+            recoverPendingChanges(dirname(configPath), ownerId);
+        },
+        release() {
+            if (released)
+                return;
+            lock.release();
+            released = true;
+        }
+    };
+}
+export async function withCodexConfigLock(codexHome, callback) {
+    const scope = await acquireCodexConfigLock(codexHome);
+    try {
+        return await callback(scope);
+    }
+    finally {
+        scope.release();
+    }
+}

package/dist/launch.d.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { type ModelReasoningCapabilities } from "@velum-labs/routekit-contracts";
+import { type ModelReasoningCapabilities, type ModelServiceTierCapabilities } from "@velum-labs/routekit-contracts";
 import type { AgentProfile, ToolLaunchContext, ToolLaunchSpec } from "@velum-labs/routekit-tools";
 export type CodexModelPreset = Record<string, unknown>;
 /** Metadata persisted beside a RouteKit-owned Codex profile. */
@@ -7,6 +7,7 @@ export type CodexPersistentCatalogModel = {
     id: string;
     label?: string;
     reasoning?: ModelReasoningCapabilities;
+    serviceTiers?: ModelServiceTierCapabilities;
 };
 export declare function isCodexConfigFailure(code: number, stderr: string): boolean;
 export declare function tomlKey(name: string): string;
@@ -23,6 +24,8 @@ export declare function hasCodexLogin(home?: string): boolean;
  * cannot read or mutate the user's real Codex configuration.
  */
 export declare function createIsolatedCodexHome(prefix: string, env?: Record<string, string | undefined>): string;
+/** Stable RouteKit-owned Codex home used by interactive launchers. */
+export declare function resolveRouteKitCodexHome(env?: Record<string, string | undefined>): string;
 export declare function codexListedStockSlugs(home?: string): string[];
 export declare function codexCatalogEntries(spec: Pick<ToolLaunchSpec, "defaultModel" | "modelSelection" | "models">, template: CodexModelPreset, stockModels?: readonly CodexModelPreset[], options?: {
     appendUnlistedStock?: boolean;
@@ -48,6 +51,5 @@ export type CodexLaunchDependencies = {
     spawnProcess?: typeof spawn;
     env?: Record<string, string | undefined>;
 };
-export declare function resolveCodexHome(env?: Record<string, string | undefined>): string;
-/** Launch against the user's real Codex home; only generated catalog data is temporary. */
+/** Launch against a RouteKit-owned Codex home with file-only auth persistence. */
 export declare function launchCodex(ctx: ToolLaunchContext, deps?: CodexLaunchDependencies): Promise<number>;