litcodex-ai 0.3.0

package/dist/config-migration/errors.js

@@ -0,0 +1,28 @@
+// 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 "CONFIG_MALFORMED":
+            return 2;
+        case "CONFIG_UNWRITABLE":
+            return 3;
+        case "BACKUP_FAILED":
+            return 4;
+        case "STATE_UNWRITABLE":
+            return 3;
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { ModelCatalog, ReasoningProfile } from "./catalog.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 } 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;
+}
+export interface MigrateSkip {
+    path: string;
+    reason: "user-modified" | "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;
+}
+export interface MigrateFileResult {
+    changed: boolean;
+    written: Partial<ReasoningProfile>;
+    managed: boolean;
+    backup: string | null;
+    skipReason: "user-modified" | "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,210 @@
+// M13 — config-migration orchestrator (S13 index.ts).
+//
+// Installs LitCodex's managed Codex config settings WITHOUT ever overwriting the
+// whole file or clobbering unrelated keys/sections/comments. Two modes differ in
+// failure semantics:
+//   - "install"       — back up each existing config BEFORE any write; on the
+//                       first error, throw CodexConfigMigrationError (the CLI /
+//                       installer maps it to a non-zero exit).
+//   - "session-start" — fire-and-forget; never throws to the caller for a
+//                       per-file error so a Codex turn can never be blocked.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { backupConfigFile } from "./backup.js";
+import { readModelCatalog } from "./catalog.js";
+import { configPaths } from "./config-paths.js";
+import { CodexConfigMigrationError } from "./errors.js";
+import { forceDisableMultiAgentV2 } from "./multi-agent-v2-guard.js";
+import { ensureCodexReasoningConfig, readRootSettings } from "./root-settings.js";
+import { readState, resolveStatePath, writeState } from "./state.js";
+import { validateTomlShape } from "./toml-shape.js";
+export { readModelCatalog } from "./catalog.js";
+export { CodexConfigMigrationError } from "./errors.js";
+export { ensureCodexReasoningConfig } 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;
+    // Opt-out short-circuit: no reads, no writes.
+    if (env["LITCODEX_CONFIG_MIGRATION_DISABLED"]?.trim() === "1") {
+        return { changed: [], backups: [], skipped: [], stateWritten: false };
+    }
+    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 });
+    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 });
+        }
+        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.changed && result.skipReason !== null) {
+            skipped.push({ path: configPath, reason: result.skipReason });
+        }
+        nextState.files[configPath] = {
+            catalogVersion: catalog.version,
+            written: result.written,
+            managed: result.managed,
+        };
+    }
+    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 dryRun = options.dryRun ?? false;
+    const fileExisted = await pathExists(configPath);
+    const before = await readConfig(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 decision = shouldApplyCatalog(before, catalog, previousState);
+    let config = before;
+    if (decision.apply) {
+        config = ensureCodexReasoningConfig(config, catalog.current);
+    }
+    const afterGuard = forceDisableMultiAgentV2(config);
+    if (afterGuard !== config) {
+        config = afterGuard;
+    }
+    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);
+        }
+        try {
+            await mkdir(dirname(configPath), { recursive: true });
+            await writeFile(configPath, `${config.trimEnd()}\n`);
+        }
+        catch (error) {
+            throw new CodexConfigMigrationError("CONFIG_UNWRITABLE", "Could not write the Codex config file.", configPath, {
+                errno: errnoOf(error),
+            });
+        }
+    }
+    const written = decision.apply ? catalog.current : readRootSettings(config);
+    const managed = decision.apply ? true : decision.managed;
+    const skipReason = changed ? null : decision.managed ? "current" : "user-modified";
+    return { changed, written, managed, backup, skipReason };
+}
+function shouldApplyCatalog(config, catalog, previousState) {
+    const current = readRootSettings(config);
+    if (Object.keys(current).length === 0) {
+        return { apply: true, reason: "empty", managed: true };
+    }
+    if (matchesProfile(current, catalog.current)) {
+        return { apply: false, reason: "current", managed: true };
+    }
+    if (previousState?.managed === true && matchesProfile(current, previousState.written)) {
+        return { apply: true, reason: "managed-state", managed: true };
+    }
+    for (const profile of catalog.managedProfiles) {
+        if (matchesProfile(current, profile.match)) {
+            return { apply: true, reason: profile.version, managed: true };
+        }
+    }
+    return { apply: false, reason: "user-modified", managed: false };
+}
+function matchesProfile(current, profile) {
+    const record = current;
+    for (const [key, value] of Object.entries(profile)) {
+        if (record[key] !== value) {
+            return false;
+        }
+    }
+    return true;
+}
+async function readConfig(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),
+        });
+    }
+}
+async function pathExists(path) {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            return false;
+        }
+        // A non-ENOENT read error (EACCES/EISDIR) — treat as "exists" so install
+        // mode attempts a backup and surfaces the real failure downstream.
+        return true;
+    }
+}
+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/multi-agent-v2-guard.d.ts

@@ -0,0 +1,2 @@
+/** Force [features.multi_agent_v2] enabled = false. Pure + idempotent. */
+export declare function forceDisableMultiAgentV2(config: string): string;

package/dist/config-migration/multi-agent-v2-guard.js

@@ -0,0 +1,106 @@
+// M13 — multi_agent_v2 disable guard (S13 multi-agent-v2-guard.ts).
+//
+// Pure, idempotent, byte-identical on re-run. Forces
+// `[features.multi_agent_v2] enabled = false`, removes the conflicting
+// `[features]` boolean shorthand, and inserts the LitCodex managed comment
+// exactly once (de-duped by the openai/codex#26753 marker).
+//
+// VERIFY-LIVE (A3 Part C #5): the multi_agent_v2 HTTP-400 failure
+// (openai/codex#26753) is UNVERIFIED against the live Codex — confirm the bug is
+// still live at runtime; keep the marker stable for idempotency regardless.
+const MANAGED_COMMENT_MARKER = "openai/codex#26753";
+const MANAGED_DISABLE_COMMENT = [
+    "# Managed by LitCodex: multi_agent_v2 is re-disabled on every Codex session start",
+    `# because enabling it fails every turn with HTTP 400 (${MANAGED_COMMENT_MARKER}).`,
+    "# Opt out: LITCODEX_CONFIG_MIGRATION_DISABLED=1.",
+    "",
+].join("\n");
+/** Force [features.multi_agent_v2] enabled = false. Pure + idempotent. */
+export function forceDisableMultiAgentV2(config) {
+    const result = removeEnabledFeaturesShorthand(config);
+    const section = findSection(result, "[features.multi_agent_v2]");
+    if (section === null) {
+        if (hasDisabledFeaturesShorthand(result)) {
+            return result;
+        }
+        return ensureManagedComment(appendDisabledSection(result));
+    }
+    const enabledTruePattern = /^(\s*)enabled\s*=\s*true[ \t]*(#[^\n]*)?$/m;
+    if (enabledTruePattern.test(section.text)) {
+        const patched = section.text.replace(enabledTruePattern, (_match, indent, comment) => comment ? `${indent}enabled = false ${comment}` : `${indent}enabled = false`);
+        return ensureManagedComment(result.slice(0, section.start) + patched + result.slice(section.end));
+    }
+    if (/^\s*enabled\s*=\s*false[ \t]*(?:#[^\n]*)?$/m.test(section.text)) {
+        return result;
+    }
+    const headerEnd = section.text.indexOf("\n");
+    const insertAt = headerEnd === -1 ? section.text.length : headerEnd + 1;
+    const patched = `${section.text.slice(0, insertAt)}${headerEnd === -1 ? "\n" : ""}enabled = false\n${section.text.slice(insertAt)}`;
+    return ensureManagedComment(result.slice(0, section.start) + patched + result.slice(section.end));
+}
+function ensureManagedComment(config) {
+    if (config.includes(MANAGED_COMMENT_MARKER)) {
+        return config;
+    }
+    const section = findSection(config, "[features.multi_agent_v2]");
+    if (section === null) {
+        return config;
+    }
+    return config.slice(0, section.start) + MANAGED_DISABLE_COMMENT + config.slice(section.start);
+}
+function removeEnabledFeaturesShorthand(config) {
+    const section = findSection(config, "[features]");
+    if (section === null) {
+        return config;
+    }
+    const shorthandPattern = /^\s*multi_agent_v2\s*=\s*true[ \t]*(?:#[^\n]*)?[ \t]*\n?/m;
+    if (!shorthandPattern.test(section.text)) {
+        return config;
+    }
+    const patched = section.text.replace(shorthandPattern, "");
+    return config.slice(0, section.start) + patched + config.slice(section.end);
+}
+function hasDisabledFeaturesShorthand(config) {
+    const section = findSection(config, "[features]");
+    if (section === null) {
+        return false;
+    }
+    return /^\s*multi_agent_v2\s*=\s*false[ \t]*(?:#[^\n]*)?$/m.test(section.text);
+}
+function appendDisabledSection(config) {
+    const trimmed = config.trimEnd();
+    const prefix = trimmed.length === 0 ? "" : `${trimmed}\n\n`;
+    return `${prefix}[features.multi_agent_v2]\nenabled = false\n`;
+}
+/** Strip a trailing inline comment (best-effort; quoted keys with # out of scope). */
+function stripTrailingComment(line) {
+    const idx = line.indexOf("#");
+    return idx === -1 ? line : line.slice(0, idx).trim();
+}
+function findSection(config, headerLine) {
+    const lines = config.match(/[^\n]*\n?|$/g) ?? [];
+    let offset = 0;
+    let start = -1;
+    for (const line of lines) {
+        if (line.length === 0) {
+            break;
+        }
+        const trimmed = line.trim();
+        if (start === -1) {
+            if (stripTrailingComment(trimmed) === headerLine) {
+                start = offset;
+            }
+        }
+        else {
+            const bare = stripTrailingComment(trimmed);
+            if (bare.startsWith("[") && bare.endsWith("]")) {
+                return { start, end: offset, text: config.slice(start, offset) };
+            }
+        }
+        offset += line.length;
+    }
+    if (start === -1) {
+        return null;
+    }
+    return { start, end: config.length, text: config.slice(start) };
+}

package/dist/config-migration/root-settings.d.ts

@@ -0,0 +1,6 @@
+import type { ReasoningProfile } from "./catalog.js";
+export declare const MANAGED_KEYS: readonly ["model", "model_context_window", "model_reasoning_effort", "plan_mode_reasoning_effort"];
+/** Replace/insert the four managed scalars among the ROOT lines only. Pure. */
+export declare function ensureCodexReasoningConfig(config: string, profile: ReasoningProfile): string;
+/** Read only the four managed keys from root scope (stops at first section). Pure. */
+export declare function readRootSettings(config: string): Partial<ReasoningProfile>;

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

@@ -0,0 +1,104 @@
+// 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 the four managed scalars in-place, preserving every
+// unrelated root key, section-scoped key, comment, and ordering. model + effort
+// fields are JSON.stringify'd (QUOTED); model_context_window is an UNQUOTED
+// integer. Section-scoped occurrences of the same key are never touched.
+//
+// VERIFY-LIVE (A3 Part C #5): the four managed key names are taken from the
+// reference Codex schema — confirm against the live ~/.codex/config.toml schema
+// at runtime, do not block.
+export const MANAGED_KEYS = [
+    "model",
+    "model_context_window",
+    "model_reasoning_effort",
+    "plan_mode_reasoning_effort",
+];
+/** Replace/insert the four 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_context_window", profile.model_context_window.toString());
+    next = replaceOrInsertRootSetting(next, "model_reasoning_effort", JSON.stringify(profile.model_reasoning_effort));
+    next = replaceOrInsertRootSetting(next, "plan_mode_reasoning_effort", JSON.stringify(profile.plan_mode_reasoning_effort));
+    return next;
+}
+/** Read only the four 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,107 @@
+// 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.
+            if (!WELL_FORMED_HEADER.test(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();
+}