@litfamily/litcodex 1.0.0

package/dist/config-migration/root-settings.js

@@ -0,0 +1,144 @@
+// M13 — surgical root-setting replace/insert (S13 root-settings.ts).
+//
+// Pure. Operates ONLY on the root scope (lines before the first [section]
+// header). Replaces/inserts managed scalars in-place while preserving unrelated
+// root keys, section-scoped keys, comments, and ordering.
+//
+// These five managed root keys are part of the Codex config schema. Callers
+// decide whether a file is authorized for mutation before invoking this helper.
+export const MANAGED_KEYS = [
+    "model",
+    "model_context_window",
+    "model_auto_compact_token_limit",
+    "model_reasoning_effort",
+    "plan_mode_reasoning_effort",
+];
+/** Replace, insert, or remove the five managed scalars among the ROOT lines only. Pure. */
+export function ensureCodexReasoningConfig(config, profile) {
+    let next = replaceOrInsertRootSetting(config, "model", JSON.stringify(profile.model));
+    next = replaceOrInsertRootSetting(next, "model_reasoning_effort", JSON.stringify(profile.model_reasoning_effort));
+    next =
+        profile.model_context_window === undefined
+            ? removeRootSetting(next, "model_context_window")
+            : replaceOrInsertRootSetting(next, "model_context_window", profile.model_context_window.toString());
+    next =
+        profile.model_auto_compact_token_limit === undefined
+            ? removeRootSetting(next, "model_auto_compact_token_limit")
+            : replaceOrInsertRootSetting(next, "model_auto_compact_token_limit", profile.model_auto_compact_token_limit.toString());
+    next =
+        profile.plan_mode_reasoning_effort === undefined
+            ? removeRootSetting(next, "plan_mode_reasoning_effort")
+            : replaceOrInsertRootSetting(next, "plan_mode_reasoning_effort", JSON.stringify(profile.plan_mode_reasoning_effort));
+    return next;
+}
+const LITCODEX_OUTPUT_STYLE_KEY = "litcodex_output_style";
+/** Write or remove the `litcodex_output_style` root key. "off" removes the key; other ids set it. */
+export function ensureLitCodexOutputStyleConfig(config, styleId) {
+    if (styleId === "off") {
+        return removeRootSetting(config, LITCODEX_OUTPUT_STYLE_KEY);
+    }
+    return replaceOrInsertRootSetting(config, LITCODEX_OUTPUT_STYLE_KEY, JSON.stringify(styleId));
+}
+/** Read `litcodex_output_style` from the root scope of a TOML config string. Returns undefined if absent. */
+export function readLitCodexOutputStyleId(config) {
+    for (const line of config.split(/\n/)) {
+        if (isSectionHeader(line))
+            break;
+        if (!isRootSetting(line, LITCODEX_OUTPUT_STYLE_KEY))
+            continue;
+        const value = parseTomlScalar(line.slice(line.indexOf("=") + 1));
+        return typeof value === "string" ? value : undefined;
+    }
+    return undefined;
+}
+function removeRootSetting(config, key) {
+    const lines = config.split(/\n/);
+    let inRoot = true;
+    return lines
+        .filter((line) => {
+        if (isSectionHeader(line)) {
+            inRoot = false;
+        }
+        return !inRoot || !isRootSetting(line, key);
+    })
+        .join("\n");
+}
+/** Read only the five managed keys from root scope (stops at first section). Pure. */
+export function readRootSettings(config) {
+    const settings = {};
+    for (const line of config.split(/\n/)) {
+        if (isSectionHeader(line)) {
+            break;
+        }
+        for (const key of MANAGED_KEYS) {
+            if (!isRootSetting(line, key)) {
+                continue;
+            }
+            const value = parseTomlScalar(line.slice(line.indexOf("=") + 1));
+            if (value !== undefined) {
+                settings[key] = value;
+            }
+        }
+    }
+    return settings;
+}
+function parseTomlScalar(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            return typeof parsed === "string" ? parsed : undefined;
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    const numeric = Number(trimmed);
+    return Number.isFinite(numeric) && trimmed !== "" ? numeric : undefined;
+}
+function replaceOrInsertRootSetting(config, key, value) {
+    const lines = config.split(/\n/);
+    const output = [];
+    let replaced = false;
+    let inserted = false;
+    let inRoot = true;
+    for (const line of lines) {
+        const sectionHeader = isSectionHeader(line);
+        if (inRoot && !inserted && sectionHeader) {
+            if (!replaced) {
+                output.push(`${key} = ${value}`);
+            }
+            inserted = true;
+        }
+        if (inRoot && isRootSetting(line, key)) {
+            if (!replaced) {
+                output.push(`${key} = ${value}`);
+                replaced = true;
+            }
+            continue;
+        }
+        output.push(line);
+        if (sectionHeader) {
+            inRoot = false;
+        }
+    }
+    if (!replaced && !inserted) {
+        output.push(`${key} = ${value}`);
+    }
+    return output.join("\n");
+}
+function isSectionHeader(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+function isRootSetting(line, key) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("#") || trimmed.startsWith("[")) {
+        return false;
+    }
+    const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    return match?.[1] === key;
+}

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

@@ -0,0 +1,16 @@
+import type { ReasoningProfile } from "./catalog.js";
+export interface ManagedFileState {
+    catalogVersion: string;
+    written: Partial<ReasoningProfile>;
+    managed: boolean;
+}
+export interface MigrationState {
+    catalogVersion: string;
+    files: Record<string, ManagedFileState>;
+}
+/** Resolve the state-file path from LITCODEX_* env, else the XDG-style default. */
+export declare function resolveStatePath(env: NodeJS.ProcessEnv): string;
+/** Read the state file. Never throws — returns {} on any error. */
+export declare function readState(statePath: string): Promise<MigrationState | Record<string, never>>;
+/** Write the state file (pretty JSON + trailing newline). Throws on write failure. */
+export declare function writeState(statePath: string, state: MigrationState): Promise<void>;

package/dist/config-migration/state.js

@@ -0,0 +1,40 @@
+// M13 — durable managed-config state (S13 state.ts).
+//
+// Tracks which config files LitCodex manages so a hand-edited managed key flips
+// the file to "user-modified" and is then left untouched forever. readState
+// swallows malformed/missing state and returns {}. Env vars use the LITCODEX_*
+// prefix (no legacy aliases).
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Resolve the state-file path from LITCODEX_* env, else the XDG-style default. */
+export function resolveStatePath(env) {
+    const explicit = env["LITCODEX_MODEL_CATALOG_STATE_PATH"]?.trim();
+    if (explicit !== undefined && explicit !== "") {
+        return explicit;
+    }
+    const dataRoot = env["LITCODEX_DATA"]?.trim();
+    const root = dataRoot !== undefined && dataRoot !== "" ? dataRoot : join(homedir(), ".local", "share", "litcodex");
+    return join(root, "model-catalog-state.json");
+}
+/** Read the state file. Never throws — returns {} on any error. */
+export async function readState(statePath) {
+    try {
+        const parsed = JSON.parse(await readFile(statePath, "utf8"));
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return {};
+        }
+        throw error;
+    }
+}
+/** Write the state file (pretty JSON + trailing newline). Throws on write failure. */
+export async function writeState(statePath, state) {
+    await mkdir(dirname(statePath), { recursive: true });
+    await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/config-migration/toml-shape.d.ts

@@ -0,0 +1,8 @@
+export type TomlShapeRejection = "unterminated-string" | "unbalanced-section-header" | "duplicate-multi-agent-v2";
+export interface TomlShapeResult {
+    ok: boolean;
+    reason: TomlShapeRejection | null;
+    line: number | null;
+}
+/** Validate the structural shape. Pure, never throws. */
+export declare function validateTomlShape(config: string): TomlShapeResult;

package/dist/config-migration/toml-shape.js

@@ -0,0 +1,141 @@
+// M13 — validateTomlShape structural gate (S13 addendum Gap B).
+//
+// The SOLE gate between "backup + CONFIG_MALFORMED exit 2" (install) and
+// "proceed to surgical rewrite". The accept/reject boundary is the CLOSED
+// grammar R1/R2/R3; nothing outside these three rules is rejected. Pure, never
+// throws. Returns the FIRST violation (R1 -> R2 -> R3, scanning top-to-bottom).
+//
+// Accepts exotic-but-valid TOML: multiline strings ("""/'''), arrays-of-tables
+// ([[...]]), inline arrays/tables, section-scoped clipped strings.
+const WELL_FORMED_HEADER = /^\s*\[\[?[^[\]]+\]\]?\s*(?:#[^\n]*)?$/;
+const GUARD_HEADER = "[features.multi_agent_v2]";
+/** Validate the structural shape. Pure, never throws. */
+export function validateTomlShape(config) {
+    const lines = config.split(/\n/);
+    let inRoot = true;
+    let guardCount = 0;
+    let multilineCloser = null;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? "";
+        const lineNo = i + 1;
+        // Inside an open multiline string: skip until the closer appears.
+        if (multilineCloser !== null) {
+            if (raw.includes(multilineCloser)) {
+                multilineCloser = null;
+            }
+            continue;
+        }
+        const trimmed = raw.trim();
+        const isHeader = trimmed.startsWith("[");
+        if (isHeader) {
+            // R2 — unbalanced [section] header. Strip quoted key segments FIRST so brackets inside a
+            // quoted key (e.g. a Windows project path `[projects."C:\…\[INBOX] MEMOS"]`, which Codex
+            // writes verbatim and is valid TOML) are not mistaken for stray section brackets.
+            if (!WELL_FORMED_HEADER.test(stripQuotedSpans(raw))) {
+                return reject("unbalanced-section-header", lineNo);
+            }
+            // R3 — duplicate [features.multi_agent_v2] table.
+            if (stripInlineComment(trimmed) === GUARD_HEADER) {
+                guardCount += 1;
+                if (guardCount >= 2) {
+                    return reject("duplicate-multi-agent-v2", lineNo);
+                }
+            }
+            inRoot = false;
+            continue;
+        }
+        // R1 — only root-scope scalar lines are checked.
+        if (inRoot) {
+            const opener = multilineOpener(raw);
+            if (opener !== null) {
+                // A multiline opener whose closer is NOT on the same line opens a block.
+                multilineCloser = opener;
+                continue;
+            }
+            if (hasUnterminatedQuote(raw, '"') || hasUnterminatedQuote(raw, "'")) {
+                return reject("unterminated-string", lineNo);
+            }
+        }
+    }
+    return { ok: true, reason: null, line: null };
+}
+function reject(reason, line) {
+    return { ok: false, reason, line };
+}
+/**
+ * Detect a multiline-string opener (`"""` or `'''`) whose closing delimiter is
+ * NOT present later on the same line. Returns the closer delimiter when the
+ * block stays open, else null.
+ */
+function multilineOpener(line) {
+    for (const delim of ['"""', "'''"]) {
+        const open = line.indexOf(delim);
+        if (open === -1) {
+            continue;
+        }
+        const close = line.indexOf(delim, open + delim.length);
+        if (close === -1) {
+            return delim;
+        }
+    }
+    return null;
+}
+/**
+ * R1 detection for a single delimiter: count unescaped delimiters on the value
+ * side of the `=`. An ODD count means the opening quote is never closed.
+ */
+function hasUnterminatedQuote(line, delim) {
+    const eq = line.indexOf("=");
+    if (eq === -1) {
+        return false;
+    }
+    const value = line.slice(eq + 1);
+    let count = 0;
+    let backslashes = 0;
+    for (const ch of value) {
+        if (ch === delim) {
+            // `"` counts only when preceded by an even number of backslashes.
+            if (backslashes % 2 === 0) {
+                count += 1;
+            }
+        }
+        backslashes = ch === "\\" ? backslashes + 1 : 0;
+    }
+    return count % 2 === 1;
+}
+function stripInlineComment(line) {
+    const idx = line.indexOf("#");
+    return idx === -1 ? line.trim() : line.slice(0, idx).trim();
+}
+/**
+ * Replace every quoted span (basic `"…"` or literal `'…'`) with a single inert placeholder, so a
+ * structural scan never sees `[`, `]`, `#`, or quote chars that live INSIDE a TOML string. Basic
+ * strings honor `\` escapes (so an escaped quote doesn't close early); literal strings do not.
+ * Used to bracket-balance a section header whose key may contain a quoted path (e.g. `[INBOX]`).
+ */
+function stripQuotedSpans(line) {
+    let out = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '"' || ch === "'") {
+            out += "Q"; // the whole quoted span collapses to one bracket-free key token
+            i += 1;
+            while (i < line.length) {
+                if (ch === '"' && line[i] === "\\") {
+                    i += 2; // skip an escaped char in a basic string (e.g. \" or \\)
+                    continue;
+                }
+                if (line[i] === ch) {
+                    i += 1; // closing quote
+                    break;
+                }
+                i += 1;
+            }
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}

package/dist/config-migration/unsafe-route-guard.d.ts

@@ -0,0 +1 @@
+export declare function assertNoUnsafeInstallRoutes(paths: readonly string[]): Promise<void>;

package/dist/config-migration/unsafe-route-guard.js

@@ -0,0 +1,17 @@
+import { readConfigFile } from "./config-file-io.js";
+import { CodexConfigMigrationError } from "./errors.js";
+import { unsafeEffectiveRoute } from "./gpt56-policy.js";
+import { readRootSettings } from "./root-settings.js";
+import { validateTomlShape } from "./toml-shape.js";
+export async function assertNoUnsafeInstallRoutes(paths) {
+    for (const configPath of paths) {
+        const before = await readConfigFile(configPath);
+        if (!validateTomlShape(before).ok)
+            continue;
+        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 });
+        }
+    }
+}

package/dist/install/agent-routing.d.ts

@@ -0,0 +1,19 @@
+import type { AuthMode } from "./auth-mode.js";
+import type { ReadonlyFsLike } from "./codex.js";
+import type { AgentRoute, AgentRoutingReport } from "./types.js";
+export declare const NATIVE_DEFAULT_AGENT_FILE = "litcodex-default.toml";
+/**
+ * Resolve a bundled role's installed path without making the native generic role discoverable.
+ * Codex scans `<CODEX_HOME>/agents/` for named roles; the managed `default` role is selected by
+ * the explicit native `[agents.default].config_file` binding and therefore lives beside that dir.
+ */
+export declare function installedAgentPath(codexHome: string, file: string): string;
+export declare function parseAgentRoute(file: string, content: string): AgentRoute;
+export declare function rewriteAgentRouteModel(content: string, from: string, to: string): string;
+/** Replace only the native route header, leaving user instructions and all other fields untouched. */
+export declare function rewriteAgentRouteHeader(content: string, route: Pick<AgentRoute, "model" | "effort">): string;
+export declare function agentRouteIssue(route: Pick<AgentRoute, "file" | "model" | "effort">): string | null;
+export declare function desiredAgentRoutes(authMode?: AuthMode): readonly AgentRoute[];
+export declare function inspectAgentRouting(fs: ReadonlyFsLike, codexHome: string, authMode?: AuthMode): AgentRoutingReport;
+export declare function routingReport(installedRoutes: readonly AgentRoute[], readFailures?: readonly string[], authMode?: AuthMode): AgentRoutingReport;
+export declare function summarizeAgentRoutes(routes: readonly AgentRoute[]): string;

package/dist/install/agent-routing.js

@@ -0,0 +1,145 @@
+import { join } from "node:path";
+import { FALLBACK_CATALOG } from "../config-migration/catalog.js";
+import { chatgptDesiredRouteModel, isKnownGpt56Model, unsafeEffectiveRoute } from "../config-migration/gpt56-policy.js";
+export const NATIVE_DEFAULT_AGENT_FILE = "litcodex-default.toml";
+const AGENT_FILES = [
+    NATIVE_DEFAULT_AGENT_FILE,
+    "litcodex-explorer.toml",
+    "litcodex-librarian.toml",
+    "litcodex-plan.toml",
+    "litcodex-metis.toml",
+    "litcodex-momus.toml",
+    "litcodex-litwork-reviewer.toml",
+];
+/**
+ * Resolve a bundled role's installed path without making the native generic role discoverable.
+ * Codex scans `<CODEX_HOME>/agents/` for named roles; the managed `default` role is selected by
+ * the explicit native `[agents.default].config_file` binding and therefore lives beside that dir.
+ */
+export function installedAgentPath(codexHome, file) {
+    return file === NATIVE_DEFAULT_AGENT_FILE ? join(codexHome, file) : join(codexHome, "agents", file);
+}
+export function parseAgentRoute(file, content) {
+    const header = routeHeader(content);
+    if (/^\s*(?:effort|reasoning_effort)\s*=/m.test(header)) {
+        throw new Error("effort conflicts with model_reasoning_effort");
+    }
+    return {
+        file,
+        role: file.replace(/^litcodex-/, "").replace(/\.toml$/, ""),
+        model: readRequiredTomlString(header, "model"),
+        effort: readRequiredTomlString(header, "model_reasoning_effort"),
+    };
+}
+export function rewriteAgentRouteModel(content, from, to) {
+    const header = routeHeader(content);
+    const escapedFrom = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const rewrittenHeader = header.replace(new RegExp(`^(model\\s*=\\s*")${escapedFrom}"`, "m"), `$1${to}"`);
+    return `${rewrittenHeader}${content.slice(header.length)}`;
+}
+/** Replace only the native route header, leaving user instructions and all other fields untouched. */
+export function rewriteAgentRouteHeader(content, route) {
+    const header = routeHeader(content);
+    const modelHeader = replaceRouteHeaderValue(header, "model", route.model);
+    const rewrittenHeader = replaceRouteHeaderValue(modelHeader, "model_reasoning_effort", route.effort);
+    return `${rewrittenHeader}${content.slice(header.length)}`;
+}
+export function agentRouteIssue(route) {
+    if (!isKnownGpt56Model(route.model))
+        return `${route.file} has unknown model: ${route.model}`;
+    const unsafe = unsafeEffectiveRoute({ model: route.model, model_reasoning_effort: route.effort });
+    return unsafe === null ? null : `${route.file} has unsafe route: ${unsafe}`;
+}
+export function desiredAgentRoutes(authMode) {
+    return AGENT_FILES.map((file) => {
+        const role = file.replace(/^litcodex-/, "").replace(/\.toml$/, "");
+        const desired = FALLBACK_CATALOG.roles[role] ?? {};
+        const profile = authMode === "chatgpt" && desired.model !== undefined
+            ? { ...desired, model: chatgptDesiredRouteModel(desired.model) }
+            : desired;
+        return routeFromProfile(file, role, profile);
+    });
+}
+export function inspectAgentRouting(fs, codexHome, authMode) {
+    const readFailures = [];
+    const legacyDefaultPath = join(codexHome, "agents", NATIVE_DEFAULT_AGENT_FILE);
+    if (fs.existsSync(legacyDefaultPath)) {
+        readFailures.push(`${NATIVE_DEFAULT_AGENT_FILE} is also present in the autodiscovered agents directory; remove the duplicate before reinstalling`);
+    }
+    const installedRoutes = AGENT_FILES.flatMap((file) => {
+        const path = installedAgentPath(codexHome, file);
+        if (!fs.existsSync(path))
+            return [];
+        try {
+            return [parseAgentRoute(file, fs.readFileSync(path, "utf8"))];
+        }
+        catch (error) {
+            readFailures.push(error instanceof Error && /ambiguous|unparseable|conflicts/.test(error.message)
+                ? `${file} is ambiguous or unparseable`
+                : `${file} is unreadable`);
+            return [];
+        }
+    });
+    return routingReport(installedRoutes, readFailures, authMode);
+}
+export function routingReport(installedRoutes, readFailures = [], authMode) {
+    const desiredRoutes = desiredAgentRoutes(authMode);
+    const issues = [...readFailures];
+    const preservedRoutes = [];
+    if (installedRoutes.length !== AGENT_FILES.length) {
+        issues.push(`agent TOMLs incomplete (${installedRoutes.length}/${AGENT_FILES.length} readable)`);
+    }
+    const desiredByRole = new Map(desiredRoutes.map((route) => [route.role, route]));
+    for (const route of installedRoutes) {
+        const routeIssue = agentRouteIssue(route);
+        const safeUserOwnedRoute = !isKnownGpt56Model(route.model) &&
+            unsafeEffectiveRoute({ model: route.model, model_reasoning_effort: route.effort }) === null;
+        if (routeIssue !== null && !safeUserOwnedRoute)
+            issues.push(routeIssue);
+        const desired = desiredByRole.get(route.role);
+        if (desired !== undefined && (desired.model !== route.model || desired.effort !== route.effort)) {
+            preservedRoutes.push(route);
+        }
+    }
+    return {
+        healthy: issues.length === 0,
+        issues,
+        desiredConfig: summarizeAgentRoutes(desiredRoutes),
+        installedTomls: installedRoutes.length === AGENT_FILES.length
+            ? summarizeAgentRoutes(installedRoutes)
+            : `incomplete (${installedRoutes.length}/${AGENT_FILES.length} readable)`,
+        preservedRoutes: preservedRoutes.length === 0 ? "none" : summarizeAgentRoutes(preservedRoutes),
+        spawnOverride: "not exposed by the verified host schema",
+        effectiveChild: "unverified without a child JSONL receipt; fail-closed",
+    };
+}
+export function summarizeAgentRoutes(routes) {
+    if (routes.length === 0)
+        return "not reported";
+    return routes.map((route) => `${route.role}=${route.model}/${route.effort}`).join(", ");
+}
+function routeFromProfile(file, role, profile) {
+    return {
+        file,
+        role,
+        model: profile.model ?? "unreported",
+        effort: profile.model_reasoning_effort ?? "unreported",
+    };
+}
+function readRequiredTomlString(content, key) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const matches = [...content.matchAll(new RegExp(`^${escapedKey}\\s*=\\s*"([^"\\r\\n]+)"\\s*$`, "gm"))];
+    if (matches.length !== 1 || matches[0]?.[1] === undefined) {
+        throw new Error(`${key} is ambiguous or unparseable`);
+    }
+    return matches[0][1];
+}
+function routeHeader(content) {
+    const boundaries = [content.search(/^\s*developer_instructions\s*=\s*"""/m), content.search(/^\s*\[/m)].filter((index) => index >= 0);
+    const boundary = boundaries.length === 0 ? content.length : Math.min(...boundaries);
+    return content.slice(0, boundary);
+}
+function replaceRouteHeaderValue(header, key, value) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return header.replace(new RegExp(`^(${escapedKey}\\s*=\\s*")[^"\\r\\n]+"`, "m"), `$1${value}"`);
+}

package/dist/install/agents-install.d.ts

@@ -0,0 +1,40 @@
+import type { AuthMode } from "./auth-mode.js";
+import type { AgentRoute, InstallStep, InstallStepResult } from "./types.js";
+export interface WritableFsLike {
+    existsSync(p: string): boolean;
+    /** Optional identity probe; injected memory filesystems may omit it. */
+    lstatSync?(p: string): {
+        isSymbolicLink(): boolean;
+        isDirectory(): boolean;
+    };
+    mkdirSync(p: string, o: {
+        recursive: true;
+    }): void;
+    readdirSync(p: string): string[];
+    readFileSync(p: string, e: "utf8"): string;
+    writeFileSync(p: string, d: string): void;
+}
+export interface AgentInstallDeps {
+    readonly now: () => number;
+    readonly repoRoot: string;
+    readonly codexHome?: string;
+    readonly writeFs?: WritableFsLike;
+    readonly agentsSourceDir?: string;
+    readonly authMode?: AuthMode;
+    /** Selected helper route; applied to the native generic default role on fresh/reconfigure. */
+    readonly subagentModel?: string;
+    readonly subagentEffort?: string;
+    readonly preparedAgentSources?: PreparedAgentSources;
+    /** Explicit `--reconfigure` is the only permission to update an existing role header. */
+    readonly reconfigure?: boolean;
+}
+export interface AgentSource {
+    readonly file: string;
+    readonly content: string;
+}
+export interface PreparedAgentSources {
+    readonly sources: readonly AgentSource[];
+    readonly agentRoutes: readonly AgentRoute[];
+}
+export declare function runAgentsInstall(step: InstallStep, deps: AgentInstallDeps): InstallStepResult;
+export declare function prepareAgentSources(deps: AgentInstallDeps): PreparedAgentSources;