litcodex-ai 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LitCodex Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/wjgoarxiv/litcodex/master/cover.png" alt="LitCodex — loop-native agent harness for Codex" width="100%" />
+</div>
+
+<h1 align="center">litcodex-ai</h1>
+
+<p align="center">
+  <em>The <strong>LitCodex</strong> installer + CLI for <a href="https://github.com/openai/codex">Codex</a> — type <code>lit</code> and Codex loops until the goal is verified.</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/litcodex-ai?color=ff6a00&label=litcodex-ai" alt="npm version" />
+  <img src="https://img.shields.io/badge/platform-Codex%20CLI-ff6a00" alt="Codex CLI" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-3c873a" alt="node >= 20" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
+</p>
+
+---
+
+> [!NOTE]
+> `litcodex` is a **self-contained** CLI: it registers the `litcodex` Codex plugin and the bare-`lit`
+> `UserPromptSubmit` hook with no `npx` forwarding to any other package. One install, no accounts.
+
+## Install
+
+```sh
+npm install -g litcodex-ai
+litcodex install
+```
+
+`litcodex install` registers the marketplace + plugin and installs the hook into Codex, preserving
+your existing `~/.codex/config.toml` — it backs up before any change and never overwrites unrelated
+keys. Preview the plan first with `litcodex --dry-run install`.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `litcodex install [--dry-run]` | Register the LitCodex Codex plugin + hook (dry-run prints the plan, mutates nothing) |
+| `litcodex doctor` | Diagnose the installation |
+| `litcodex uninstall` | Remove the LitCodex registration |
+| `litcodex config migrate` | Apply the managed Codex config keys (backup-before-write) |
+| `litcodex loop <create\|status\|run\|checkpoint\|record-evidence\|doctor>` | Drive the lit-loop runtime |
+| `litcodex hook user-prompt-submit` | The Codex hook entrypoint (invoked by the host) |
+
+## How it works
+
+Once installed, typing a bare **`lit`** in Codex activates **lit-loop** — an evidence-bound,
+autonomous work loop that decomposes the task, records real evidence per step, and keeps going until
+every success criterion passes. Durable loop state lives under `.litcodex/lit-loop/` in your project
+(`brief.md`, `goals.json`, `ledger.jsonl`, `evidence/`).
+
+LitCodex also ships a sibling family of triggers — `litwork`, `lit-plan`, `litgoal` — plus a 20-skill
+library and hook components, all registered as a single Codex plugin.
+
+> [!TIP]
+> See the [repository README](https://github.com/wjgoarxiv/litcodex#readme) for the full quickstart,
+> the mode family, the loop model, and troubleshooting.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/litcodex.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Authored ESM entry for the `litcodex` bin (A3 D1: self-contained CLI).
+//
+// This file owns the shebang and process.exit. It imports the compiled,
+// self-contained dispatcher from ../dist/cli.js and runs it. It performs NO
+// forwarding and spawns NO child process — all routing lives in the dispatcher.
+
+import { runCli } from "../dist/cli.js";
+
+const exitCode = await runCli(process.argv.slice(2));
+
+process.exit(exitCode);

package/dist/cli.d.ts

@@ -0,0 +1,23 @@
+/** Error code emitted when a subcommand is not in the routing table. */
+export declare const UNKNOWN_COMMAND_CODE: "LITCODEX_INSTALL_UNKNOWN_COMMAND";
+/** Router usage code (EX_USAGE) for an unknown `config` sub-subcommand. */
+export declare const CONFIG_USAGE_EXIT_CODE: 64;
+/** Outcome of dispatching an argv vector. Pure: no process side effects. */
+export interface DispatchResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * 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 declare function dispatch(argv: readonly string[]): DispatchResult;
+/**
+ * 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`. Returns the
+ * integer exit code; the bin owns `process.exit`. No forwarding, no exec-wrapper, no harness.
+ */
+export declare function runCli(argv: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,183 @@
+// Self-contained LitCodex CLI dispatcher (A3 D1).
+//
+// This compiles to dist/cli.js and is imported by bin/litcodex.js. It owns the routing table for
+// every litcodex subcommand and is fully self-contained: it NEVER spawns a child process itself and
+// NEVER forwards to a separate package. The ONLY child process the installer ever spawns is `codex`,
+// and that spawn lives behind the install/* modules (dist/install/*.js), never in this file —
+// keeping dist/cli.js free of any spawn/forwarder token. Unknown subcommands exit 1 with a
+// plain-text usage notice (LITCODEX_INSTALL_UNKNOWN_COMMAND).
+//
+// Two surfaces:
+//   - `dispatch` — the PURE synchronous router (help/version/unknown + a pure dry-run install plan).
+//     No I/O, no spawn; used by the routing unit tests.
+//   - `runCli` — the async process entry the bin awaits. It owns the real, side-effecting routes:
+//     install/doctor/uninstall (install/* modules), `config migrate` (M13, in-process), and the
+//     bundled lit-loop runtime routes `loop <sub>` and `hook user-prompt-submit`.
+import { createRequire } from "node:module";
+import { runConfigMigrateCli } from "./config-migration/cli.js";
+import { resolveCodexHome } from "./install/codex.js";
+import { runDoctorCli, runInstallCli, runUninstallCli } from "./install/index.js";
+import { LITCODEX_REPO_URL } from "./install/marketplace.js";
+import { buildInstallPlan } from "./install/plan.js";
+import { renderInstallPlan } from "./install/render-plan.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 plan = buildInstallPlan({
+        dryRun: true,
+        noTui: rest.includes("--no-tui"),
+        autonomous: rest.includes("--codex-autonomous"),
+        force: rest.includes("--force"),
+        json: rest.includes("--json"),
+        codexHome: resolveCodexHome(process.env),
+        repoUrl: LITCODEX_REPO_URL,
+        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"),
+};
+/**
+ * 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 --dry-run <command>             Resolve a command without applying it",
+        "  litcodex --help                          Show this help",
+        "  litcodex --version                       Show the litcodex-ai version",
+        "",
+        "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 };
+}
+/**
+ * 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`. 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 isHelp = rest.includes("--help") || rest.includes("-h");
+    const isVersion = rest.includes("--version") || rest.includes("-v");
+    if (!isHelp && !isVersion) {
+        const head = rest[0];
+        if (head === "config" && rest[1] === "migrate") {
+            const passthrough = dryRun ? [...rest.slice(2), "--dry-run"] : rest.slice(2);
+            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);
+            return runInstallCli(installArgs);
+        }
+        if (head === "doctor") {
+            return runDoctorCli(rest.slice(1));
+        }
+        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") {
+                return dispatchExit(renderUnknown(rest[1] ?? "hook"));
+            }
+            const { runUserPromptSubmitHookCli } = await import("@litcodex/lit-loop/dist/hook-cli.js");
+            return runUserPromptSubmitHookCli(process.stdin, process.stdout, process.stderr);
+        }
+    }
+    return dispatchExit(dispatch(argv));
+}
+/** 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,22 @@
+export interface ReasoningProfile {
+    model: string;
+    model_context_window: number;
+    model_reasoning_effort: string;
+    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,99 @@
+// 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 by this `import ... with { type: "json" }` (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.
+//
+// VERIFY-LIVE (A3 Part C #5): the `current` model/window/effort values
+// (gpt-5.5 / 400000 / high / xhigh) and the legacy `managedProfiles` are
+// UNVERIFIED against the live Codex model catalog — confirm at runtime, do not
+// block. They are config data, not legacy brand tokens.
+import { readFile } from "node:fs/promises";
+import bundledCatalog from "../../model-catalog.json" with { type: "json" };
+/** Used whenever the on-disk catalog is missing, malformed, or schema-invalid. */
+export const FALLBACK_CATALOG = parseCatalog(bundledCatalog) ?? {
+    version: "fallback.gpt-5.5-400k-high",
+    current: {
+        model: "gpt-5.5",
+        model_context_window: 400_000,
+        model_reasoning_effort: "high",
+        plan_mode_reasoning_effort: "xhigh",
+    },
+    roles: {
+        default: {
+            model: "gpt-5.5",
+            model_context_window: 400_000,
+            model_reasoning_effort: "high",
+            plan_mode_reasoning_effort: "xhigh",
+        },
+    },
+    managedProfiles: [{ version: "legacy.gpt-5.5-272k", match: { model: "gpt-5.5", model_context_window: 272_000 } }],
+};
+/** 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_context_window"] === "number" &&
+        typeof value["model_reasoning_effort"] === "string" &&
+        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,14 @@
+export interface ConfigMigrateCliArgs {
+    sessionStart: boolean;
+    json: boolean;
+    cwd: string | null;
+    dryRun: boolean;
+}
+/** Parse the sliced `config migrate` argv (everything after `config migrate`). */
+export declare function parseConfigMigrateArgs(argv: readonly string[]): ConfigMigrateCliArgs;
+/**
+ * Run the config-migrate route in-process. Resolves args, calls
+ * migrateCodexConfig, renders, returns an exit code. Returns (does not throw)
+ * for mapped errors. session-start mode swallows everything and returns 0.
+ */
+export declare function runConfigMigrateCli(argv: readonly string[], out?: (text: string) => void, err?: (text: string) => void): Promise<number>;

package/dist/config-migration/cli.js

@@ -0,0 +1,85 @@
+// M13 — `config migrate` CLI glue (S13 cli.ts + addendum Gap A).
+//
+// Pure-of-process-spawn CLI entry. Parses the already-sliced `config migrate`
+// args, runs migrateCodexConfig IN-PROCESS, renders stdout/stderr, returns an
+// exit code per the parent Exit-code table. NEVER spawns a child process and
+// NEVER forwards. session-start mode always returns 0.
+import { CodexConfigMigrationError, exitCodeForMigrationError } from "./errors.js";
+import { migrateCodexConfig } from "./index.js";
+/** Parse the sliced `config migrate` argv (everything after `config migrate`). */
+export function parseConfigMigrateArgs(argv) {
+    let sessionStart = false;
+    let json = false;
+    let dryRun = false;
+    let cwd = null;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--session-start") {
+            sessionStart = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--cwd") {
+            const next = argv[i + 1];
+            if (next !== undefined) {
+                cwd = next;
+                i += 1;
+            }
+        }
+        else if (arg?.startsWith("--cwd=")) {
+            cwd = arg.slice("--cwd=".length);
+        }
+    }
+    return { sessionStart, json, cwd, dryRun };
+}
+/**
+ * Run the config-migrate route in-process. Resolves args, calls
+ * migrateCodexConfig, renders, returns an exit code. Returns (does not throw)
+ * for mapped errors. session-start mode swallows everything and returns 0.
+ */
+export async function runConfigMigrateCli(argv, out = (text) => process.stdout.write(text), err = (text) => process.stderr.write(text)) {
+    const args = parseConfigMigrateArgs(argv);
+    const mode = args.sessionStart ? "session-start" : "install";
+    const cwd = args.cwd ?? process.cwd();
+    let result;
+    try {
+        result = await migrateCodexConfig({ mode, cwd, dryRun: args.dryRun });
+    }
+    catch (error) {
+        if (args.sessionStart) {
+            return 0; // fire-and-forget: never block a turn.
+        }
+        if (error instanceof CodexConfigMigrationError) {
+            err(`${JSON.stringify({ ok: false, code: error.code, configPath: error.configPath, message: error.message, details: error.details })}\n`);
+            return exitCodeForMigrationError(error.code);
+        }
+        throw error;
+    }
+    if (args.json) {
+        out(`${JSON.stringify(result)}\n`);
+    }
+    else {
+        out(renderText(result));
+    }
+    return 0;
+}
+function renderText(result) {
+    const userModified = result.skipped.filter((s) => s.reason === "user-modified");
+    const lines = [
+        `litcodex config: ${result.changed.length} file(s) updated, ${result.backups.length} backup(s) created, ${userModified.length} skipped (user-modified)`,
+    ];
+    for (const path of result.changed) {
+        lines.push(`updated: ${path}`);
+    }
+    for (const path of result.backups) {
+        lines.push(`backup:  ${path}`);
+    }
+    for (const skip of userModified) {
+        lines.push(`skipped: ${skip.path} (user-modified)`);
+    }
+    return `${lines.join("\n")}\n`;
+}

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 = "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;