@litfamily/litcodex 1.0.0

package/dist/cli.js

@@ -0,0 +1,282 @@
+// Self-contained LitCodex CLI dispatcher. Side-effecting child processes remain
+// behind dedicated modules; unknown routes return a plain usage error.
+// `dispatch` is pure; `runCli` owns install/config/loop/hook process routes.
+import { createRequire } from "node:module";
+import { runForegroundAutoUpdate } from "./auto-update.js";
+import { readEffortChoice, readLeadModelChoice, readModelChoice, readSubagentEffortChoice, readSubagentModelChoice, } from "./cli-model-route.js";
+import { runConfigMigrateCli } from "./config-migration/cli.js";
+import { resolveCodexHome } from "./install/codex.js";
+import { runDoctorCli, runInstallCli, runUninstallCli } from "./install/index.js";
+import { managedMarketplaceRoot } from "./install/marketplace.js";
+import { buildInstallPlan } from "./install/plan.js";
+import { renderInstallPlan } from "./install/render-plan.js";
+import { renderBanner, shouldDecorate } from "./ui.js";
+import { maybeNotifyAndRefresh } from "./update-check.js";
+/** Error code emitted when a subcommand is not in the routing table. */
+export const UNKNOWN_COMMAND_CODE = "LITCODEX_INSTALL_UNKNOWN_COMMAND";
+/** Router usage code (EX_USAGE) for an unknown `config` sub-subcommand. */
+export const CONFIG_USAGE_EXIT_CODE = 64;
+const manifest = createRequire(import.meta.url)("../package.json");
+const ok = (stdout) => ({ stdout, stderr: "", exitCode: 0 });
+/**
+ * Pure dry-run install plan renderer for the synchronous router. Resolves typed options from the
+ * process env WITHOUT any spawn or fs write, then renders the ordered LitCodex plan text.
+ */
+function renderInstallDryRun(rest) {
+    const codexHome = resolveCodexHome(process.env);
+    const plan = buildInstallPlan({
+        dryRun: true,
+        noTui: rest.includes("--no-tui"),
+        autonomous: rest.includes("--codex-autonomous"),
+        force: rest.includes("--force"),
+        json: rest.includes("--json"),
+        yes: rest.includes("--yes"),
+        profile: readModelChoice(rest),
+        leadModel: readLeadModelChoice(rest),
+        effort: readEffortChoice(rest),
+        subagentModel: readSubagentModelChoice(rest),
+        subagentEffort: readSubagentEffortChoice(rest),
+        reconfigure: rest.includes("--reconfigure") || rest.includes("--managed-upgrade"),
+        codexHome,
+        repoUrl: managedMarketplaceRoot(codexHome),
+        repoRoot: process.cwd(),
+    });
+    return `${renderInstallPlan(plan)}\n`;
+}
+/**
+ * Pure synchronous router. For `install --dry-run` it renders the real plan (pure). For the other
+ * side-effecting routes it returns a non-error placeholder (the real work runs in `runCli`), so the
+ * routing-level contract (known route ≠ exit 1, no forwarder token) is unit-testable without I/O.
+ */
+const ROUTES = {
+    install: (rest, dryRun) => (dryRun ? ok(renderInstallDryRun(rest)) : ok("litcodex install\n")),
+    doctor: () => ok("litcodex doctor\n"),
+    uninstall: () => ok("litcodex uninstall\n"),
+    config: configRouteHandler,
+    loop: () => ok("litcodex loop\n"),
+    hook: () => ok("litcodex hook\n"),
+    observer: observerRouteHandler,
+    "skill-loop": () => ok("litcodex skill-loop\n"),
+};
+function observerRouteHandler(rest, dryRun) {
+    if (dryRun || rest.length > 0) {
+        return {
+            stdout: "",
+            stderr: "litcodex observer: this command accepts no arguments.\n",
+            exitCode: CONFIG_USAGE_EXIT_CODE,
+        };
+    }
+    return ok("litcodex observer\n");
+}
+/**
+ * Synchronous arm of the `config` route. The real `config migrate` work is async and is run by
+ * `runCli` BEFORE `dispatch`; this sync handler only handles routing-level outcomes: an unknown
+ * sub-subcommand → usage exit 64; a recognized `config migrate` → exit 0 placeholder.
+ */
+function configRouteHandler(rest) {
+    if (rest[0] === "migrate") {
+        return ok("");
+    }
+    const sub = rest[0] ?? "<none>";
+    return {
+        stdout: "",
+        stderr: `litcodex config: unknown subcommand "${sub}". Did you mean \`config migrate\`?\n`,
+        exitCode: CONFIG_USAGE_EXIT_CODE,
+    };
+}
+const KNOWN_SUBCOMMANDS = Object.keys(ROUTES);
+function renderHelp() {
+    return [
+        "litcodex — self-contained LitCodex CLI for Codex",
+        "",
+        "Usage:",
+        "  litcodex install [--dry-run] [options]   Install LitCodex into Codex",
+        "  litcodex doctor                          Diagnose the LitCodex install",
+        "  litcodex uninstall                       Remove LitCodex from Codex",
+        "  litcodex config migrate                  Migrate Codex config for LitCodex",
+        "  litcodex loop <sub>                      Run a Lit-Loop subcommand",
+        "  litcodex hook user-prompt-submit         Run the UserPromptSubmit hook",
+        "  litcodex observer                        Record one proposal from bounded stdin",
+        "  litcodex skill-loop <sub>                Review, apply, reject, or roll back skill proposals",
+        "  litcodex --dry-run <command>             Resolve a command without applying it",
+        "  litcodex --help                          Show this help",
+        "  litcodex --version                       Show the @litfamily/litcodex version",
+        "",
+        "Install model options:",
+        "  --model <gpt-6-astra|sol|gpt-5.6|luna|terra> Select the LEAD model (default: gpt-6-astra)",
+        "  --effort <low|medium|high|xhigh|max>     Select LEAD reasoning effort (Astra: all five)",
+        "  --subagent-model <gpt-6-astra|luna|gpt-5.6|terra> Select the helper route (default: luna)",
+        "  --subagent-effort <low|medium|high|xhigh|max> Select helper effort (Astra: all five)",
+        "  --yes                                    Keep defaults; never prompt",
+        "  --reconfigure                           Explicitly apply the choice to the root model/effort",
+        "  --no-auto-update                        Skip the foreground update barrier for this command",
+        "",
+        "Examples:",
+        "  litcodex install",
+        "  litcodex doctor",
+        "  litcodex --dry-run install --no-tui",
+        "",
+    ].join("\n");
+}
+function renderUnknown(subcommand) {
+    const usage = [
+        `${UNKNOWN_COMMAND_CODE}: unknown subcommand "${subcommand}".`,
+        `Known subcommands: ${KNOWN_SUBCOMMANDS.join(", ")}.`,
+        "Run `litcodex --help` for usage.",
+        "",
+    ].join("\n");
+    return { stdout: "", stderr: usage, exitCode: 1 };
+}
+function writeCliBanner(argv) {
+    if (argv.includes("--json") || argv.includes("--no-tui"))
+        return;
+    process.stdout.write(renderBanner({
+        version: manifest.version,
+        color: shouldDecorate({
+            isTty: Boolean(process.stdout.isTTY),
+            env: process.env,
+            noTui: argv.includes("--no-tui"),
+            json: argv.includes("--json"),
+        }) && !argv.includes("--dry-run"),
+    }));
+}
+/**
+ * Pure dispatcher. Parses argv (already sliced past `node bin`), strips the position-independent
+ * `--dry-run` flag, answers `--help`/`--version` locally, and routes the first non-flag token.
+ * Unknown token → exit 1. No process spawns. No forwarding.
+ */
+export function dispatch(argv) {
+    const dryRun = argv.includes("--dry-run");
+    const rest = argv.filter((token) => token !== "--dry-run");
+    if (rest.includes("--help") || rest.includes("-h")) {
+        return ok(renderHelp());
+    }
+    if (rest.includes("--version") || rest.includes("-v")) {
+        return ok(`${manifest.version}\n`);
+    }
+    const subcommand = rest[0];
+    if (subcommand === undefined) {
+        return ok(renderHelp());
+    }
+    const handler = ROUTES[subcommand];
+    if (handler === undefined) {
+        return renderUnknown(subcommand);
+    }
+    return handler(rest.slice(1), dryRun);
+}
+/**
+ * Async process entry used by `bin/litcodex.js`. It owns the side-effecting routes: install/doctor/
+ * uninstall (install/* modules, which are the ONLY code that ever spawns `codex`), `config migrate`
+ * (M13, in-process), and the bundled `@litcodex/lit-loop` runtime routes `loop`/`hook`/`observer`. Returns the
+ * integer exit code; the bin owns `process.exit`. No forwarding, no exec-wrapper, no harness.
+ */
+export async function runCli(argv) {
+    const dryRun = argv.includes("--dry-run");
+    const rest = argv.filter((token) => token !== "--dry-run");
+    const head = rest[0];
+    const isHelp = rest.includes("--help") || rest.includes("-h");
+    const isVersion = rest.includes("--version") || rest.includes("-v");
+    if (!isHelp && !isVersion && head === "observer") {
+        const observerResult = observerRouteHandler(rest.slice(1), dryRun);
+        if (observerResult.exitCode !== 0)
+            return dispatchExit(observerResult);
+        const { runSkillObserverCli } = await import("@litcodex/lit-loop/dist/skill-observer-cli.js");
+        return runSkillObserverCli(process.stdin, process.stdout, process.stderr);
+    }
+    if (!isHelp && !isVersion && head === "skill-loop") {
+        if (dryRun)
+            return dispatchExit({
+                stdout: "",
+                stderr: "litcodex skill-loop: --dry-run is not supported.\n",
+                exitCode: 64,
+            });
+        const { skillLoopCommand } = await import("@litcodex/lit-loop/dist/skill-loop-cli.js");
+        return skillLoopCommand(rest.slice(1), {
+            cwd: process.cwd(),
+            env: process.env,
+            stdout: process.stdout,
+            stderr: process.stderr,
+        });
+    }
+    if (!isHelp && !isVersion) {
+        if (head === "config" && rest[1] === "migrate") {
+            const passthrough = dryRun ? [...rest.slice(2), "--dry-run"] : rest.slice(2);
+            if (!passthrough.includes("--session-start"))
+                writeCliBanner(passthrough);
+            return runConfigMigrateCli(passthrough);
+        }
+        if (head === "install") {
+            // Preserve position-independent --dry-run: pass the args after `install`, re-injecting
+            // --dry-run (which `rest` already stripped) so the flag survives regardless of position.
+            const installArgs = dryRun ? [...rest.slice(1), "--dry-run"] : rest.slice(1);
+            const exitCode = await runInstallCli(installArgs);
+            const barrierExitCode = notifyAfterManagementCommand("install", argv, exitCode);
+            return barrierExitCode ?? exitCode;
+        }
+        if (head === "doctor") {
+            const exitCode = runDoctorCli(rest.slice(1));
+            const barrierExitCode = notifyAfterManagementCommand("doctor", argv, exitCode);
+            return barrierExitCode ?? exitCode;
+        }
+        if (head === "uninstall") {
+            return runUninstallCli(rest.slice(1));
+        }
+        if (head === "loop") {
+            const { loopCommand } = await import("@litcodex/lit-loop/dist/loop-cli.js");
+            return loopCommand(rest.slice(1), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin });
+        }
+        if (head === "hook") {
+            if (rest[1] !== "user-prompt-submit" && rest[1] !== "stop") {
+                return dispatchExit(renderUnknown(rest[1] ?? "hook"));
+            }
+            const hooks = await import("@litcodex/lit-loop/dist/hook-cli.js");
+            return rest[1] === "stop"
+                ? hooks.runStopSkillReviewHookCli(process.stdin, process.stdout, process.stderr)
+                : hooks.runUserPromptSubmitHookCli(process.stdin, process.stdout, process.stderr);
+        }
+    }
+    // The human-facing dispatcher routes get the same banner as install/doctor/uninstall. Machine
+    // routes return above so their JSON/additionalContext protocols remain byte-for-byte intact.
+    const result = dispatch(argv);
+    const exitCode = dispatchExit(result);
+    if (!isVersion && result.exitCode === 0 && result.stdout.length > 0) {
+        writeCliBanner(argv);
+    }
+    return exitCode;
+}
+/** Update notices run only after a successful management command has completed. */
+function notifyAfterManagementCommand(command, argv, exitCode) {
+    const gate = {
+        current: manifest.version,
+        command,
+        argv,
+        exitCode,
+        stdinTty: Boolean(process.stdin.isTTY),
+        stdoutTty: Boolean(process.stdout.isTTY),
+        stderrTty: Boolean(process.stderr.isTTY),
+        env: process.env,
+    };
+    const foregroundReceipt = runForegroundAutoUpdate({
+        ...gate,
+        current: manifest.version,
+        stderr: process.stderr,
+    });
+    maybeNotifyAndRefresh({
+        ...gate,
+        current: manifest.version,
+        stderr: process.stderr,
+    });
+    if (foregroundReceipt?.status === "unknown-state" || foregroundReceipt?.status === "failed")
+        return 3;
+    return undefined;
+}
+/** Write a pure dispatch result to the process streams and return its exit code. */
+function dispatchExit(result) {
+    if (result.stdout) {
+        process.stdout.write(result.stdout);
+    }
+    if (result.stderr) {
+        process.stderr.write(result.stderr);
+    }
+    return result.exitCode;
+}

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

@@ -0,0 +1,2 @@
+/** Back up an existing config before mutation. Returns the backup path or null. */
+export declare function backupConfigFile(configPath: string): Promise<string | null>;

package/dist/config-migration/backup.js

@@ -0,0 +1,42 @@
+// M13 — pre-write backup (S13 backup.ts).
+//
+// Copies an EXISTING config to <path>.litcodex-bak.<UTC-compact>.<pid> BEFORE
+// any mutation. Returns the backup path, or null when the source does not exist
+// (nothing to back up). Throws CodexConfigMigrationError(BACKUP_FAILED) on copy
+// failure. The backup name components are all controlled/sanitized — never
+// derived from file content (no backup-path injection).
+import { copyFile } from "node:fs/promises";
+import { CodexConfigMigrationError } from "./errors.js";
+/** Back up an existing config before mutation. Returns the backup path or null. */
+export async function backupConfigFile(configPath) {
+    const backupPath = `${configPath}.litcodex-bak.${compactTimestamp()}.${process.pid}`;
+    try {
+        await copyFile(configPath, backupPath);
+        return backupPath;
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            return null;
+        }
+        throw new CodexConfigMigrationError("BACKUP_FAILED", "Could not create a pre-write backup of the Codex config.", configPath, {
+            errno: errnoOf(error),
+        });
+    }
+}
+/** UTC ISO compact: YYYYMMDDTHHMMSSZ (sortable, no path-illegal chars). */
+function compactTimestamp() {
+    return new Date()
+        .toISOString()
+        .replace(/\.\d+Z$/, "Z")
+        .replace(/[:-]/g, "");
+}
+function isErrnoCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function errnoOf(error) {
+    if (error instanceof Error && "code" in error) {
+        const code = error.code;
+        return typeof code === "string" ? code : null;
+    }
+    return null;
+}

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

@@ -0,0 +1,23 @@
+export interface ReasoningProfile {
+    model: string;
+    model_reasoning_effort: string;
+    model_context_window?: number;
+    model_auto_compact_token_limit?: number;
+    plan_mode_reasoning_effort?: string;
+}
+/** A partial set of root keys used to detect a stale/managed config. */
+export type ProfileMatch = Readonly<Record<string, string | number>>;
+export interface ManagedProfile {
+    version: string;
+    match: ProfileMatch;
+}
+export interface ModelCatalog {
+    version: string;
+    current: ReasoningProfile;
+    roles: Readonly<Record<string, Partial<ReasoningProfile>>>;
+    managedProfiles: readonly ManagedProfile[];
+}
+/** Used whenever the on-disk catalog is missing, malformed, or schema-invalid. */
+export declare const FALLBACK_CATALOG: ModelCatalog;
+/** Read the catalog. Never throws — returns FALLBACK_CATALOG on any failure. */
+export declare function readModelCatalog(env?: NodeJS.ProcessEnv): Promise<ModelCatalog>;

package/dist/config-migration/catalog.js

@@ -0,0 +1,108 @@
+// M13 — model catalog reader (S13 catalog.ts).
+//
+// Loads the reasoning catalog. NEVER throws: on a missing file, malformed JSON,
+// or a schema failure it returns FALLBACK_CATALOG. The catalog ships as the
+// authored data file `model-catalog.json` at the package root, resolved at
+// runtime through Node's `createRequire(import.meta.url)` (NOT baked into dist/
+// by tsc). The package `files` array MUST therefore include `model-catalog.json`
+// (A3 G7 option (a): ["bin","dist","model-catalog.json","README.md","LICENSE"])
+// or a stripped tarball install crashes here at module load. An explicit
+// LITCODEX_MODEL_CATALOG_PATH env var overrides the bundled copy for testing.
+//
+// The authored catalog selects Luna with max effort for ordinary helper roles and
+// Astra with xhigh effort for the lead/planning/review routes. The historical `managedProfiles`
+// entries exist only for exact recognition; they are never fallback dispatch targets.
+// Host metadata is probed separately.
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+const bundledCatalog = createRequire(import.meta.url)("../../model-catalog.json");
+/** Used whenever the on-disk catalog is missing, malformed, or schema-invalid. */
+export const FALLBACK_CATALOG = parseCatalog(bundledCatalog) ?? {
+    version: "fallback.gpt-6-astra-xhigh",
+    current: {
+        model: "gpt-6-astra",
+        model_reasoning_effort: "xhigh",
+    },
+    roles: {
+        default: {
+            model: "gpt-5.6-luna",
+            model_reasoning_effort: "max",
+        },
+    },
+    managedProfiles: [
+        {
+            version: "legacy.gpt-5.5-272k",
+            match: {
+                model: "gpt-5.5",
+                model_context_window: 272_000,
+                model_reasoning_effort: "high",
+                plan_mode_reasoning_effort: "xhigh",
+            },
+        },
+    ],
+};
+/** Read the catalog. Never throws — returns FALLBACK_CATALOG on any failure. */
+export async function readModelCatalog(env = process.env) {
+    const override = env["LITCODEX_MODEL_CATALOG_PATH"]?.trim();
+    if (override === undefined || override === "") {
+        return FALLBACK_CATALOG;
+    }
+    try {
+        const parsed = parseCatalog(JSON.parse(await readFile(override, "utf8")));
+        return parsed ?? FALLBACK_CATALOG;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return FALLBACK_CATALOG;
+        }
+        throw error;
+    }
+}
+function parseCatalog(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    if (typeof value["version"] !== "string") {
+        return null;
+    }
+    const current = value["current"];
+    if (!isReasoningProfile(current)) {
+        return null;
+    }
+    const rawProfiles = value["managedProfiles"];
+    if (!Array.isArray(rawProfiles)) {
+        return null;
+    }
+    const managedProfiles = [];
+    for (const profile of rawProfiles) {
+        if (!isRecord(profile) || typeof profile["version"] !== "string" || !isMatchRecord(profile["match"])) {
+            return null;
+        }
+        managedProfiles.push({ version: profile["version"], match: profile["match"] });
+    }
+    const roles = isRecord(value["roles"]) ? value["roles"] : {};
+    return { version: value["version"], current, roles, managedProfiles };
+}
+function isReasoningProfile(value) {
+    return (isRecord(value) &&
+        typeof value["model"] === "string" &&
+        typeof value["model_reasoning_effort"] === "string" &&
+        (value["model_context_window"] === undefined || typeof value["model_context_window"] === "number") &&
+        (value["model_auto_compact_token_limit"] === undefined ||
+            typeof value["model_auto_compact_token_limit"] === "number") &&
+        (value["plan_mode_reasoning_effort"] === undefined || typeof value["plan_mode_reasoning_effort"] === "string"));
+}
+function isMatchRecord(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    for (const entry of Object.values(value)) {
+        if (typeof entry !== "string" && typeof entry !== "number") {
+            return false;
+        }
+    }
+    return true;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,16 @@
+import { type HostCapabilities } from "../install/host-capabilities.js";
+import type { Gpt56Profile, ReasoningEffort } from "./gpt56-policy.js";
+export interface ConfigMigrateCliArgs {
+    readonly sessionStart: boolean;
+    readonly json: boolean;
+    readonly cwd: string | null;
+    readonly dryRun: boolean;
+    readonly reconfigure: boolean;
+    readonly profile: Gpt56Profile;
+    readonly effort: ReasoningEffort;
+}
+export interface ConfigMigrateCliDeps {
+    readonly preflight?: (profile: Gpt56Profile, effort: ReasoningEffort) => HostCapabilities;
+}
+export declare function parseConfigMigrateArgs(argv: readonly string[]): ConfigMigrateCliArgs;
+export declare function runConfigMigrateCli(argv: readonly string[], out?: (text: string) => void, err?: (text: string) => void, deps?: ConfigMigrateCliDeps): Promise<number>;

package/dist/config-migration/cli.js

@@ -0,0 +1,186 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { modelContextsForWrites, probeHostCapabilities } from "../install/host-capabilities.js";
+import { CodexConfigMigrationError, exitCodeForMigrationError } from "./errors.js";
+import { migrateCodexConfig } from "./index.js";
+class ConfigMigrateArgumentError extends Error {
+    constructor(message, flag) {
+        super(message);
+        this.name = "ConfigMigrateArgumentError";
+        this.flag = flag;
+    }
+}
+export function parseConfigMigrateArgs(argv) {
+    let sessionStart = false;
+    let json = false;
+    let dryRun = false;
+    let reconfigure = false;
+    let profile = "astra";
+    let effort = "xhigh";
+    let effortExplicit = false;
+    let cwd = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--session-start")
+            sessionStart = true;
+        else if (arg === "--json")
+            json = true;
+        else if (arg === "--dry-run")
+            dryRun = true;
+        else if (arg === "--reconfigure" || arg === "--managed-upgrade")
+            reconfigure = true;
+        else if (arg === "--model") {
+            const value = argv[index + 1];
+            const parsed = modelProfile(value);
+            if (parsed === undefined)
+                throw invalidModel();
+            profile = parsed;
+            if (!effortExplicit)
+                effort = defaultEffort(parsed);
+            index += 1;
+        }
+        else if (arg === "--effort") {
+            const value = argv[index + 1];
+            if (!isReasoningEffort(value))
+                throw invalidEffort();
+            effort = value;
+            effortExplicit = true;
+            index += 1;
+        }
+        else if (arg === "--cwd") {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("--"))
+                throw invalidValue("--cwd requires a value", "--cwd");
+            cwd = value;
+            index += 1;
+        }
+        else if (arg?.startsWith("--cwd=")) {
+            cwd = arg.slice("--cwd=".length);
+            if (cwd === "")
+                throw invalidValue("--cwd requires a value", "--cwd");
+        }
+        else if (arg !== undefined)
+            throw invalidValue(`unknown option ${JSON.stringify(arg)}`, arg);
+    }
+    if (profile !== "astra" && (effort === "low" || effort === "medium"))
+        throw invalidEffort();
+    return { sessionStart, json, cwd, dryRun, reconfigure, profile, effort };
+}
+export async function runConfigMigrateCli(argv, out = (text) => process.stdout.write(text), err = (text) => process.stderr.write(text), deps = {}) {
+    let args;
+    try {
+        args = parseConfigMigrateArgs(argv);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigMigrateArgumentError))
+            throw error;
+        err(`${JSON.stringify({ ok: false, code: "CONFIG_INVALID_OPTION", message: error.message, details: { flag: error.flag } })}\n`);
+        return 2;
+    }
+    const mode = args.sessionStart ? "session-start" : "install";
+    const capabilities = (deps.preflight ?? directPreflight)(args.profile, args.effort);
+    if (capabilities.concurrency.status === "unavailable") {
+        err(`${JSON.stringify({ ok: false, code: "CONFIG_PREFLIGHT_FAILED", message: "config migrate preflight unavailable", capabilities })}\n`);
+        return args.sessionStart ? 0 : 2;
+    }
+    const options = {
+        mode,
+        cwd: args.cwd ?? process.cwd(),
+        reconfigure: args.reconfigure,
+        profile: args.profile,
+        effort: args.effort,
+        modelContexts: modelContextsForWrites(capabilities),
+    };
+    let result;
+    try {
+        result = await migrateCodexConfig({ ...options, dryRun: true });
+        if (!args.dryRun)
+            result = await migrateCodexConfig(options);
+    }
+    catch (error) {
+        if (args.sessionStart)
+            return 0;
+        if (error instanceof CodexConfigMigrationError) {
+            err(`${JSON.stringify({ ok: false, code: error.code, message: error.message, details: error.details })}\n`);
+            return exitCodeForMigrationError(error.code);
+        }
+        throw error;
+    }
+    if (args.json)
+        out(`${JSON.stringify({ ...result, capabilities })}\n`);
+    else
+        out(renderText(result, capabilities));
+    return 0;
+}
+function directPreflight(profile, effort) {
+    const override = process.env["CODEX_BIN"]?.trim();
+    const codexBin = override !== undefined && override !== "" ? override : "codex";
+    if (override !== undefined && override !== "" && !existsSync(override)) {
+        return unavailableCapabilities("codex-binary-unavailable", override);
+    }
+    const spawn = (command, argv, options) => {
+        const result = spawnSync(command, [...argv], {
+            encoding: "utf8",
+            stdio: options.stdio,
+            timeout: options.timeout,
+        });
+        return {
+            status: result.status,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            ...(result.error === undefined ? {} : { error: result.error }),
+        };
+    };
+    return probeHostCapabilities(codexBin, spawn, { profile, effort, env: process.env });
+}
+function unavailableCapabilities(reason, observedSource) {
+    const report = { status: "unavailable", reason, observedSource };
+    return {
+        concurrency: report,
+        autoCompaction: report,
+        modelContexts: { "gpt-5.6": null, "gpt-5.6-terra": null, "gpt-5.6-luna": null },
+    };
+}
+function renderText(result, capabilities) {
+    const userModified = result.skipped.filter((skip) => skip.reason === "user-modified");
+    const preserved = result.skipped.filter((skip) => skip.reason === "preserved");
+    const lines = [
+        `litcodex config: ${result.changed.length} updated, ${result.backups.length} backup(s), ${preserved.length} preserved, ${userModified.length} user-modified`,
+        ...result.changed.map((path) => `updated: ${path}`),
+        ...result.backups.map((path) => `backup: ${path}`),
+        ...preserved.map((skip) => `skipped: ${skip.path} (preserved; use --reconfigure only after review)`),
+        ...userModified.map((skip) => `skipped: ${skip.path} (user-modified)`),
+        `capability concurrency: ${capabilityText(capabilities.concurrency)}`,
+        `probe-only explicit context/auto-compaction override: ${capabilityText(capabilities.autoCompaction)}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function capabilityText(report) {
+    return `${report.status}; reason=${report.reason}; source=${report.observedSource}`;
+}
+function isReasoningEffort(value) {
+    return value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max";
+}
+function invalidModel() {
+    return invalidValue("--model requires one of: gpt-6-astra, luna", "--model");
+}
+function invalidEffort() {
+    return invalidValue("--effort requires one of: low, medium, high, xhigh, max (Astra); high, xhigh, max (existing models)", "--effort");
+}
+function modelProfile(value) {
+    if (value === "gpt-6-astra")
+        return "astra";
+    if (value === "luna")
+        return "luna";
+    return undefined;
+}
+function defaultEffort(profile) {
+    if (profile === "astra")
+        return "xhigh";
+    if (profile === "luna")
+        return "max";
+    return "xhigh";
+}
+function invalidValue(message, flag) {
+    return new ConfigMigrateArgumentError(message, flag);
+}

package/dist/config-migration/config-file-io.d.ts

@@ -0,0 +1,11 @@
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+export declare function readConfigFile(configPath: string): Promise<string>;
+export declare function configPathExists(configPath: string): Promise<boolean>;
+export declare function writeConfigFile(configPath: string, config: string, fs?: AtomicWriteFs): Promise<void>;
+export interface AtomicWriteFs {
+    readonly mkdir: typeof mkdir;
+    readonly writeFile: typeof writeFile;
+    readonly rename: typeof rename;
+    readonly rm: typeof rm;
+}
+export declare function writeConfigFileWith(configPath: string, config: string, fs: AtomicWriteFs): Promise<void>;