@litfamily/litcodex 1.0.0

package/dist/config-migration/config-file-io.js

@@ -0,0 +1,62 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { CodexConfigMigrationError } from "./errors.js";
+export async function readConfigFile(configPath) {
+    try {
+        return await readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            return "";
+        }
+        throw new CodexConfigMigrationError("CONFIG_UNWRITABLE", "Could not read the Codex config file.", configPath, {
+            errno: errnoOf(error),
+        });
+    }
+}
+export async function configPathExists(configPath) {
+    try {
+        await readFile(configPath);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return !isErrnoCode(error, "ENOENT");
+        }
+        throw error;
+    }
+}
+export async function writeConfigFile(configPath, config, fs = NODE_ATOMIC_FS) {
+    return writeConfigFileWith(configPath, config, fs);
+}
+const NODE_ATOMIC_FS = { mkdir, writeFile, rename, rm };
+export async function writeConfigFileWith(configPath, config, fs) {
+    const temporaryPath = `${configPath}.litcodex-tmp.${process.pid}.${Date.now()}`;
+    try {
+        await fs.mkdir(dirname(configPath), { recursive: true });
+        await fs.writeFile(temporaryPath, `${config.trimEnd()}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        await fs.rename(temporaryPath, configPath);
+    }
+    catch (error) {
+        try {
+            await fs.rm(temporaryPath, { force: true });
+        }
+        catch (cleanupError) {
+            if (!(cleanupError instanceof Error))
+                throw cleanupError;
+        }
+        throw new CodexConfigMigrationError("CONFIG_UNWRITABLE", "Could not write the Codex config file.", configPath, {
+            errno: errnoOf(error),
+            temporaryPath,
+        });
+    }
+}
+function isErrnoCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function errnoOf(error) {
+    if (error instanceof Error && "code" in error) {
+        return typeof error.code === "string" ? error.code : null;
+    }
+    return null;
+}

package/dist/config-migration/config-paths.d.ts

@@ -0,0 +1,4 @@
+export declare function configPaths(args: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}): Promise<string[]>;

package/dist/config-migration/config-paths.js

@@ -0,0 +1,64 @@
+// M13 — config-path discovery (S13 config-paths.ts).
+//
+// Discovers the global $CODEX_HOME/config.toml plus every project-local
+// .codex/config.toml from `cwd` up to homedir(). Symlinked .codex dirs/files
+// are SKIPPED (lstat, not stat) so a symlinked .codex can never redirect a
+// write to an attacker-chosen target. CODEX_HOME is kept verbatim (host runtime
+// var, not a LitCodex-owned name). Returns deduped absolute paths, global first.
+import { lstat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+export async function configPaths(args) {
+    const { env, cwd } = args;
+    const codexHomeRaw = env["CODEX_HOME"]?.trim();
+    const codexHome = resolve(codexHomeRaw !== undefined && codexHomeRaw !== "" ? codexHomeRaw : join(homedir(), ".codex"));
+    const paths = new Set([join(codexHome, "config.toml")]);
+    for (const projectConfig of projectConfigPaths({ cwd, stopAt: homedir() })) {
+        if (!(await isRegularFile(projectConfig))) {
+            continue;
+        }
+        if (!(await isRegularDirectory(dirname(projectConfig)))) {
+            continue;
+        }
+        paths.add(projectConfig);
+    }
+    return [...paths];
+}
+function projectConfigPaths(args) {
+    const paths = [];
+    let current = resolve(args.cwd);
+    const stop = resolve(args.stopAt);
+    while (true) {
+        paths.push(join(current, ".codex", "config.toml"));
+        if (current === stop || current === dirname(current)) {
+            break;
+        }
+        current = dirname(current);
+    }
+    return paths;
+}
+async function isRegularFile(path) {
+    try {
+        return (await lstat(path)).isFile();
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            return false;
+        }
+        throw error;
+    }
+}
+async function isRegularDirectory(path) {
+    try {
+        return (await lstat(path)).isDirectory();
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isErrnoCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/dist/config-migration/errors.d.ts

@@ -0,0 +1,11 @@
+/** Closed set of failure classes the migration can raise. */
+export type CodexConfigMigrationCode = "UNSAFE_MODEL_ROUTE" | "CONFIG_MALFORMED" | "CONFIG_UNWRITABLE" | "BACKUP_FAILED" | "STATE_UNWRITABLE";
+/** Machine-readable migration error. `code` drives the install-mode exit code. */
+export declare class CodexConfigMigrationError extends Error {
+    readonly code: CodexConfigMigrationCode;
+    readonly configPath: string | null;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: CodexConfigMigrationCode, message: string, configPath: string | null, details?: Record<string, unknown>);
+}
+/** Install-mode exit code for a migration error (parent Exit-code table). */
+export declare function exitCodeForMigrationError(code: CodexConfigMigrationCode): number;

package/dist/config-migration/errors.js

@@ -0,0 +1,30 @@
+// M13 — machine-readable migration error + exit-code mapping (S13 errors.ts).
+//
+// The single throwable shape for the config-migration module. Install mode
+// surfaces it; the CLI maps `code` to a distinct exit code so the installer
+// (M12) can react. Session-start mode catches and swallows it (exit 0 always).
+/** Machine-readable migration error. `code` drives the install-mode exit code. */
+export class CodexConfigMigrationError extends Error {
+    constructor(code, message, configPath, details = {}) {
+        super(message);
+        this.name = "CodexConfigMigrationError";
+        this.code = code;
+        this.configPath = configPath;
+        this.details = details;
+    }
+}
+/** Install-mode exit code for a migration error (parent Exit-code table). */
+export function exitCodeForMigrationError(code) {
+    switch (code) {
+        case "UNSAFE_MODEL_ROUTE":
+            return 2;
+        case "CONFIG_MALFORMED":
+            return 2;
+        case "CONFIG_UNWRITABLE":
+            return 3;
+        case "BACKUP_FAILED":
+            return 4;
+        case "STATE_UNWRITABLE":
+            return 3;
+    }
+}

package/dist/config-migration/gpt56-policy.d.ts

@@ -0,0 +1,53 @@
+import type { ModelCatalog, ReasoningProfile } from "./catalog.js";
+import type { ManagedFileState } from "./state.js";
+export declare const GPT56_MODELS: {
+    readonly sol: "gpt-5.6";
+    readonly terra: "gpt-5.6-terra";
+    readonly luna: "gpt-5.6-luna";
+};
+export declare const ASTRA_MODEL = "gpt-6-astra";
+export declare const EXPLICIT_GPT56_SOL_MODEL = "gpt-5.6-sol";
+export type Gpt56Profile = keyof typeof GPT56_MODELS | "astra";
+export type Gpt56Effort = "high" | "xhigh" | "max";
+export type AstraEffort = "low" | "medium" | "high" | "xhigh" | "max";
+export type ReasoningEffort = Gpt56Effort | AstraEffort;
+export type Gpt56ModelContexts = Readonly<Record<(typeof GPT56_MODELS)[keyof typeof GPT56_MODELS], number | null>>;
+export type CatalogClass = "fresh" | "managed_legacy" | "existing_managed" | "explicit_sol_dispatch" | "other_gpt56" | "custom";
+export declare const GPT56_CONTEXT_WINDOW_LIMIT = 372000;
+export declare const GPT56_AUTO_COMPACT_TOKEN_LIMIT = 334800;
+export interface Gpt56ContextLimits {
+    readonly contextWindow: number;
+    readonly autoCompactTokenLimit: number;
+}
+export interface CatalogDecision {
+    readonly class: CatalogClass;
+    readonly originalDispatchId: string | null;
+    readonly apply: boolean;
+    readonly managed: boolean;
+    readonly reason: "fresh" | "current" | "managed-state" | "managed-legacy" | "user-modified";
+}
+export declare function unsafeEffectiveRoute(current: Partial<ReasoningProfile>): string | null;
+export declare function isKnownGpt56Model(model: string | undefined): boolean;
+/**
+ * Desired-route model under ChatGPT-subscription auth: both Sol representations (the bare
+ * `gpt-5.6` alias and the explicit `gpt-5.6-sol` id) dispatch as explicit Sol; other ids pass
+ * through unchanged. The API rejects the bare alias for ChatGPT accounts.
+ */
+export declare function chatgptDesiredRouteModel(model: string): string;
+type ProfileEffort<Profile extends Gpt56Profile> = Profile extends "astra" ? AstraEffort : Gpt56Effort;
+/** Select a profile while keeping Astra's wider effort set separate from legacy GPT-5.6. */
+export declare function selectedProfile<Profile extends Gpt56Profile>(profile: Profile, effort: ProfileEffort<Profile>): ReasoningProfile;
+export declare function alignedContextLimits(context: number | null | undefined): Gpt56ContextLimits | undefined;
+export declare function decideCatalogApplication(args: {
+    readonly current: Partial<ReasoningProfile>;
+    readonly target: ReasoningProfile;
+    readonly catalog: ModelCatalog;
+    readonly previousState?: ManagedFileState | undefined;
+    readonly reconfigure: boolean;
+}): CatalogDecision;
+export declare function classifyCatalogInput(args: {
+    readonly current: Partial<ReasoningProfile>;
+    readonly catalog: ModelCatalog;
+    readonly previousState?: ManagedFileState | undefined;
+}): Pick<CatalogDecision, "class" | "originalDispatchId">;
+export {};

package/dist/config-migration/gpt56-policy.js

@@ -0,0 +1,158 @@
+export const GPT56_MODELS = {
+    sol: "gpt-5.6",
+    terra: "gpt-5.6-terra",
+    luna: "gpt-5.6-luna",
+};
+export const ASTRA_MODEL = "gpt-6-astra";
+export const EXPLICIT_GPT56_SOL_MODEL = "gpt-5.6-sol";
+export const GPT56_CONTEXT_WINDOW_LIMIT = 372_000;
+export const GPT56_AUTO_COMPACT_TOKEN_LIMIT = 334_800;
+export function unsafeEffectiveRoute(current) {
+    const model = terminalModelId(current.model);
+    if (model === ASTRA_MODEL) {
+        if (current.model_reasoning_effort !== "low" &&
+            current.model_reasoning_effort !== "medium" &&
+            current.model_reasoning_effort !== "high" &&
+            current.model_reasoning_effort !== "xhigh" &&
+            current.model_reasoning_effort !== "max") {
+            return "gpt-6-astra requires low, medium, high, xhigh, or max reasoning effort";
+        }
+        return null;
+    }
+    if (model === GPT56_MODELS.luna && current.model_reasoning_effort === "xhigh") {
+        return "gpt-5.6-luna cannot use xhigh reasoning effort; use max";
+    }
+    if (model === GPT56_MODELS.luna &&
+        current.model_reasoning_effort !== "high" &&
+        current.model_reasoning_effort !== "max") {
+        return "gpt-5.6-luna requires high or max reasoning effort";
+    }
+    if (model === GPT56_MODELS.terra &&
+        current.model_reasoning_effort !== "high" &&
+        current.model_reasoning_effort !== "xhigh") {
+        return "gpt-5.6-terra requires high or xhigh reasoning effort";
+    }
+    return null;
+}
+export function isKnownGpt56Model(model) {
+    const terminal = terminalModelId(model);
+    return (terminal === GPT56_MODELS.sol ||
+        terminal === EXPLICIT_GPT56_SOL_MODEL ||
+        terminal === GPT56_MODELS.terra ||
+        terminal === GPT56_MODELS.luna ||
+        terminal === ASTRA_MODEL);
+}
+function terminalModelId(model) {
+    if (model === undefined)
+        return null;
+    const segments = model.trim().split("/");
+    const terminal = segments.at(-1)?.trim().toLowerCase();
+    return terminal === undefined || terminal === "" ? null : terminal;
+}
+/**
+ * Desired-route model under ChatGPT-subscription auth: both Sol representations (the bare
+ * `gpt-5.6` alias and the explicit `gpt-5.6-sol` id) dispatch as explicit Sol; other ids pass
+ * through unchanged. The API rejects the bare alias for ChatGPT accounts.
+ */
+export function chatgptDesiredRouteModel(model) {
+    const terminal = terminalModelId(model);
+    return terminal === GPT56_MODELS.sol || terminal === EXPLICIT_GPT56_SOL_MODEL ? EXPLICIT_GPT56_SOL_MODEL : model;
+}
+/** Select a profile while keeping Astra's wider effort set separate from legacy GPT-5.6. */
+export function selectedProfile(profile, effort) {
+    const selected = {
+        model: profile === "astra" ? ASTRA_MODEL : GPT56_MODELS[profile],
+        model_reasoning_effort: effort,
+    };
+    if (profile !== "astra" && (effort === "low" || effort === "medium")) {
+        throw new Error(`Invalid ${profile} model route: legacy GPT-5.6 models require high, xhigh, or max reasoning effort.`);
+    }
+    const unsafe = unsafeEffectiveRoute(selected);
+    if (unsafe !== null)
+        throw new Error(`Invalid ${profile} model route: ${unsafe}.`);
+    return selected;
+}
+export function alignedContextLimits(context) {
+    return context === GPT56_CONTEXT_WINDOW_LIMIT
+        ? { contextWindow: GPT56_CONTEXT_WINDOW_LIMIT, autoCompactTokenLimit: GPT56_AUTO_COMPACT_TOKEN_LIMIT }
+        : undefined;
+}
+export function decideCatalogApplication(args) {
+    const { current, target, catalog, previousState, reconfigure } = args;
+    const identity = classifyCatalogInput({ current, catalog, previousState });
+    if (Object.keys(current).length === 0) {
+        return { ...identity, apply: true, managed: true, reason: "fresh" };
+    }
+    if (reconfigure) {
+        return { ...identity, apply: true, managed: true, reason: "managed-state" };
+    }
+    if (isKnownCurrent(current)) {
+        return matchesExact(current, target)
+            ? { ...identity, apply: false, managed: true, reason: "current" }
+            : { ...identity, apply: reconfigure, managed: true, reason: reconfigure ? "managed-state" : "current" };
+    }
+    if (previousState?.managed === true && matchesExact(current, previousState.written)) {
+        return { ...identity, apply: false, managed: true, reason: "managed-legacy" };
+    }
+    for (const profile of catalog.managedProfiles) {
+        if (matchesExact(current, profile.match)) {
+            return {
+                ...identity,
+                apply: reconfigure,
+                managed: true,
+                reason: reconfigure ? "managed-state" : "managed-legacy",
+            };
+        }
+    }
+    return { ...identity, apply: false, managed: false, reason: "user-modified" };
+}
+export function classifyCatalogInput(args) {
+    const { current, catalog, previousState } = args;
+    const originalDispatchId = typeof current.model === "string" ? current.model : null;
+    if (Object.keys(current).length === 0)
+        return { class: "fresh", originalDispatchId };
+    if (originalDispatchId === GPT56_MODELS.sol ||
+        originalDispatchId === GPT56_MODELS.terra ||
+        originalDispatchId === GPT56_MODELS.luna ||
+        originalDispatchId === ASTRA_MODEL) {
+        return { class: "existing_managed", originalDispatchId };
+    }
+    if (previousState?.managed === true && matchesExact(current, previousState.written)) {
+        return { class: "managed_legacy", originalDispatchId };
+    }
+    if (originalDispatchId === EXPLICIT_GPT56_SOL_MODEL) {
+        return { class: "explicit_sol_dispatch", originalDispatchId };
+    }
+    if (catalog.managedProfiles.some((profile) => matchesExact(current, profile.match))) {
+        return { class: "managed_legacy", originalDispatchId };
+    }
+    if (originalDispatchId !== null && /^gpt-5\.6(?:$|-)/.test(originalDispatchId)) {
+        return { class: "other_gpt56", originalDispatchId };
+    }
+    return { class: "custom", originalDispatchId };
+}
+function isKnownCurrent(current) {
+    const model = current.model;
+    const effort = current.model_reasoning_effort;
+    const legacyManaged = (model === GPT56_MODELS.sol || model === GPT56_MODELS.terra) && (effort === "high" || effort === "xhigh");
+    const lunaManaged = model === GPT56_MODELS.luna && (effort === "high" || effort === "xhigh" || effort === "max");
+    const astraManaged = model === ASTRA_MODEL &&
+        (effort === "low" || effort === "medium" || effort === "high" || effort === "xhigh" || effort === "max");
+    return ((legacyManaged || lunaManaged || astraManaged) &&
+        isKnownContextLimitPair(current) &&
+        current.plan_mode_reasoning_effort === undefined);
+}
+function isKnownContextLimitPair(current) {
+    return ((current.model_context_window === undefined && current.model_auto_compact_token_limit === undefined) ||
+        (current.model_context_window === undefined && current.model_auto_compact_token_limit === 650_000) ||
+        (current.model_context_window === GPT56_CONTEXT_WINDOW_LIMIT &&
+            current.model_auto_compact_token_limit === GPT56_AUTO_COMPACT_TOKEN_LIMIT));
+}
+function matchesExact(current, profile) {
+    const currentEntries = Object.entries(current);
+    const profileEntries = Object.entries(profile);
+    if (currentEntries.length !== profileEntries.length) {
+        return false;
+    }
+    return profileEntries.every(([key, value]) => currentEntries.some(([currentKey, currentValue]) => currentKey === key && currentValue === value));
+}

package/dist/config-migration/index.d.ts

@@ -0,0 +1,63 @@
+import type { ModelCatalog, ReasoningProfile } from "./catalog.js";
+import { type Gpt56ModelContexts, type Gpt56Profile, type ReasoningEffort } from "./gpt56-policy.js";
+import type { ManagedFileState } from "./state.js";
+export type { ModelCatalog, ReasoningProfile } from "./catalog.js";
+export { readModelCatalog } from "./catalog.js";
+export type { CodexConfigMigrationCode } from "./errors.js";
+export { CodexConfigMigrationError } from "./errors.js";
+export { ensureCodexReasoningConfig, ensureLitCodexOutputStyleConfig, readLitCodexOutputStyleId, } from "./root-settings.js";
+export type { ManagedFileState, MigrationState } from "./state.js";
+export type { TomlShapeRejection, TomlShapeResult } from "./toml-shape.js";
+export { validateTomlShape } from "./toml-shape.js";
+export type MigrationMode = "session-start" | "install";
+export interface MigrateOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    mode?: MigrationMode;
+    dryRun?: boolean;
+    reconfigure?: boolean;
+    profile?: Gpt56Profile;
+    effort?: ReasoningEffort;
+    modelContexts?: Gpt56ModelContexts;
+    /** Override the sol model identifier (e.g. "gpt-5.6-sol" for ChatGPT-subscription auth). */
+    solModelOverride?: string;
+    /** Output style id to persist (e.g. "asd-ste100"). "off" removes the key. Omit to leave unchanged. */
+    style?: string;
+    /** Selected helper route; retained for installer compatibility (not written as a global key). */
+    subagentModel?: string;
+    /** Selected helper effort; retained for installer compatibility (not written as a global key). */
+    subagentEffort?: string;
+}
+export interface MigrateSkip {
+    path: string;
+    reason: "user-modified" | "preserved" | "current" | "error";
+}
+export interface MigrateResult {
+    changed: string[];
+    backups: string[];
+    skipped: MigrateSkip[];
+    stateWritten: boolean;
+}
+export interface MigrateFileOptions {
+    catalog: ModelCatalog;
+    previousState?: ManagedFileState | undefined;
+    mode: MigrationMode;
+    dryRun?: boolean | undefined;
+    reconfigure?: boolean | undefined;
+    target?: ReasoningProfile | undefined;
+    style?: string | undefined;
+    subagentModel?: string | undefined;
+    subagentEffort?: string | undefined;
+    nativeDefaultAgentConfigFile?: string | undefined;
+}
+export interface MigrateFileResult {
+    changed: boolean;
+    written: Partial<ReasoningProfile>;
+    managed: boolean;
+    backup: string | null;
+    skipReason: "user-modified" | "preserved" | "current" | null;
+}
+/** Orchestrate the migration across the discovered config paths. */
+export declare function migrateCodexConfig(options?: MigrateOptions): Promise<MigrateResult>;
+/** Per-file migration: read -> validate -> decide -> backup -> apply -> write. */
+export declare function migrateConfigFile(configPath: string, options: MigrateFileOptions): Promise<MigrateFileResult>;

package/dist/config-migration/index.js

@@ -0,0 +1,208 @@
+// Non-destructive config migration orchestrator. Install mode fails fast after
+// backup; session-start records per-file errors without blocking the Codex turn.
+import { dirname, join } from "node:path";
+import { backupConfigFile } from "./backup.js";
+import { readModelCatalog } from "./catalog.js";
+import { configPathExists, readConfigFile, writeConfigFile } from "./config-file-io.js";
+import { configPaths } from "./config-paths.js";
+import { CodexConfigMigrationError } from "./errors.js";
+import { decideCatalogApplication, selectedProfile, unsafeEffectiveRoute, } from "./gpt56-policy.js";
+import { ensureStableMultiAgent, hasManagedMultiAgentGuard, removeSubagentDefaults } from "./multi-agent-v2-guard.js";
+import { ensureNativeDefaultAgentConfig } from "./native-default-route.js";
+import { ensureGpt56ProfileFiles } from "./profile-files.js";
+import { ensureCodexReasoningConfig, ensureLitCodexOutputStyleConfig, readRootSettings } from "./root-settings.js";
+import { readState, resolveStatePath, writeState } from "./state.js";
+import { validateTomlShape } from "./toml-shape.js";
+import { assertNoUnsafeInstallRoutes } from "./unsafe-route-guard.js";
+export { readModelCatalog } from "./catalog.js";
+export { CodexConfigMigrationError } from "./errors.js";
+export { ensureCodexReasoningConfig, ensureLitCodexOutputStyleConfig, readLitCodexOutputStyleId, } from "./root-settings.js";
+export { validateTomlShape } from "./toml-shape.js";
+/** Orchestrate the migration across the discovered config paths. */
+export async function migrateCodexConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const mode = options.mode ?? "install";
+    const dryRun = options.dryRun ?? false;
+    const reconfigure = options.reconfigure ?? false;
+    const selected = options.profile ?? "astra";
+    const baseTarget = selectedProfile(selected, options.effort ?? (selected === "astra" ? "xhigh" : "max"));
+    const target = options.solModelOverride !== undefined && selected === "sol"
+        ? { ...baseTarget, model: options.solModelOverride }
+        : baseTarget;
+    // Opt-out short-circuit: no reads, no writes.
+    if (env["LITCODEX_CONFIG_MIGRATION_DISABLED"]?.trim() === "1") {
+        return { changed: [], backups: [], skipped: [], stateWritten: false };
+    }
+    const subagentModel = options.subagentModel ?? "gpt-5.6-luna";
+    const subagentEffort = options.subagentEffort ?? "max";
+    const unsafeSubagent = unsafeEffectiveRoute({ model: subagentModel, model_reasoning_effort: subagentEffort });
+    if (unsafeSubagent !== null) {
+        throw new CodexConfigMigrationError("UNSAFE_MODEL_ROUTE", `Requested subagent default route is unsafe: ${unsafeSubagent}.`, null, { model: subagentModel, effort: subagentEffort });
+    }
+    const catalog = await readModelCatalog(env);
+    const statePath = resolveStatePath(env);
+    const state = await readState(statePath);
+    const previousFiles = "files" in state ? state.files : undefined;
+    const paths = await configPaths({ env, cwd });
+    // Keep the managed generic role outside Codex's autodiscovered agents directory. The explicit
+    // native binding remains the only dispatch mechanism for omitted-agent children.
+    const nativeDefaultAgentConfigFile = join(dirname(paths[0] ?? ""), "litcodex-default.toml");
+    if (mode === "install")
+        await assertNoUnsafeInstallRoutes(paths);
+    const nextState = { catalogVersion: catalog.version, files: {} };
+    const changed = [];
+    const backups = [];
+    const skipped = [];
+    for (const configPath of paths) {
+        const previousState = previousFiles?.[configPath];
+        let result;
+        try {
+            result = await migrateConfigFile(configPath, {
+                catalog,
+                previousState,
+                mode,
+                dryRun,
+                reconfigure,
+                target,
+                style: options.style,
+                subagentModel,
+                subagentEffort,
+                nativeDefaultAgentConfigFile,
+            });
+        }
+        catch (error) {
+            if (mode === "install") {
+                throw error; // fail-fast; backup (if any) already written.
+            }
+            // session-start: swallow, record, continue. Never re-throw.
+            skipped.push({ path: configPath, reason: "error" });
+            continue;
+        }
+        if (result.changed) {
+            changed.push(configPath);
+        }
+        if (result.backup !== null) {
+            backups.push(result.backup);
+        }
+        if (result.skipReason !== null) {
+            skipped.push({ path: configPath, reason: result.skipReason });
+        }
+        nextState.files[configPath] = {
+            catalogVersion: catalog.version,
+            written: result.written,
+            managed: result.managed,
+        };
+    }
+    if (mode === "install") {
+        const profileResult = await ensureGpt56ProfileFiles({
+            codexHome: dirname(paths[0] ?? ""),
+            dryRun,
+            reconfigure,
+            ...(options.modelContexts === undefined ? {} : { modelContexts: options.modelContexts }),
+        });
+        changed.push(...profileResult.changed);
+        backups.push(...profileResult.backups);
+    }
+    let stateWritten = false;
+    if (dryRun) {
+        changed.sort();
+        backups.sort();
+        return { changed, backups, skipped, stateWritten: false };
+    }
+    try {
+        await writeState(statePath, nextState);
+        stateWritten = true;
+    }
+    catch (error) {
+        // A state-write failure must not strand a successfully-migrated config.
+        if (mode === "install" && changed.length === 0) {
+            throw new CodexConfigMigrationError("STATE_UNWRITABLE", "Could not write the LitCodex migration state file.", null, {
+                errno: errnoOf(error),
+                statePath,
+            });
+        }
+        skipped.push({ path: statePath, reason: "error" });
+    }
+    changed.sort();
+    backups.sort();
+    return { changed, backups, skipped, stateWritten };
+}
+/** Per-file migration: read -> validate -> decide -> backup -> apply -> write. */
+export async function migrateConfigFile(configPath, options) {
+    const { catalog, previousState, mode } = options;
+    const reconfigure = options.reconfigure ?? false;
+    const target = options.target ?? catalog.current;
+    const dryRun = options.dryRun ?? false;
+    const fileExisted = await configPathExists(configPath);
+    const before = await readConfigFile(configPath);
+    // Malformed detection (install: backup THEN throw; session-start: throw -> caught upstream).
+    const shape = validateTomlShape(before);
+    if (!shape.ok) {
+        let backup = null;
+        if (mode === "install" && fileExisted) {
+            backup = await backupConfigFile(configPath);
+        }
+        throw new CodexConfigMigrationError("CONFIG_MALFORMED", "Codex config could not be migrated safely; a backup was created.", configPath, {
+            reason: shape.reason,
+            line: shape.line,
+            backup,
+        });
+    }
+    const current = readRootSettings(before);
+    const unsafeRoute = unsafeEffectiveRoute(current);
+    if (unsafeRoute !== null) {
+        throw new CodexConfigMigrationError("UNSAFE_MODEL_ROUTE", `Codex config contains an unsafe effective model route: ${unsafeRoute}.`, configPath, { model: current.model ?? null, effort: current.model_reasoning_effort ?? null });
+    }
+    const decision = decideCatalogApplication({
+        current,
+        target,
+        catalog,
+        previousState,
+        reconfigure,
+    });
+    // Codex 0.144.0 reserves every unrecognized key in [agents] for an
+    // AgentRoleToml table. The global default_subagent_* keys are not in
+    // that pinned schema, so remove legacy LitCodex values before deciding
+    // whether any other managed settings need to change.
+    let config = removeSubagentDefaults(before);
+    if (decision.apply) {
+        config = ensureCodexReasoningConfig(config, target);
+    }
+    if (options.style !== undefined) {
+        config = ensureLitCodexOutputStyleConfig(config, options.style);
+    }
+    const guardManaged = decision.apply || hasManagedMultiAgentGuard(before);
+    if (guardManaged) {
+        config = ensureStableMultiAgent(config);
+    }
+    if (decision.apply && options.nativeDefaultAgentConfigFile !== undefined) {
+        config = ensureNativeDefaultAgentConfig(config, options.nativeDefaultAgentConfigFile, configPath);
+    }
+    const changed = config !== before;
+    let backup = null;
+    if (changed && !dryRun) {
+        // Backup BEFORE the write so a crash mid-write leaves the backup intact.
+        if (mode === "install" && fileExisted) {
+            backup = await backupConfigFile(configPath);
+        }
+        await writeConfigFile(configPath, config);
+    }
+    const written = decision.apply ? target : readRootSettings(config);
+    const managed = decision.apply ? true : decision.managed;
+    const skipReason = changed
+        ? null
+        : decision.reason === "managed-legacy"
+            ? "preserved"
+            : decision.managed
+                ? "current"
+                : "user-modified";
+    return { changed, written, managed, backup, skipReason };
+}
+function errnoOf(error) {
+    if (error instanceof Error && "code" in error) {
+        const code = error.code;
+        return typeof code === "string" ? code : null;
+    }
+    return null;
+}