// Holds INV-TOML-01 from structure/overview.md; keep the id here if this file is split or renamed.
import { existsSync, readFileSync } from "node:fs";
import { contextCompatibleBaseLine } from "../context-compat";
import { resolveEffectiveProjectModelProvider } from "../project-config-warnings";
import {
  OCX_ROUTING_MARKER_LINE,
  REALTIME_WS_BASE_URL_KEY,
  isOcxRoutingMarkerLine,
  isRootOpenaiBaseUrlLine,
  isRootRealtimeWsBaseUrlLine,
  providerTableStart,
  providerTableString,
  rootTomlString,
} from "../injected-marker";
import {
  CODEX_CONFIG_PATH,
  defaultCodexCatalogPathForConfig,
  resolveCodexCatalogPath,
  sameCodexCatalogPath,
  tomlString,
} from "../paths";
import { normalizeStructuralWhitespace, rootAssignmentKey, rootSourceLines, sourceAssignment, sourceAssignmentSpan, sourceText, type SourceLine } from "../toml-source-lines";
import { readBoundedCodexConfig } from "./bounded-config-reader";
import {
  type CodexRoutingTarget,
  providerBaseHost,
  routingTargetOrigin,
  usesProviderTable,
  validateCodexRoutingTarget,
} from "./routing-target";

export function externalCodexModelProvider(content: string): string | null {
  const provider = resolveEffectiveProjectModelProvider(content).provider;
  if (!provider || provider === "openai" || provider === "opencodex") return null;
  // A provider table counts as an external owner only when it carries a `base_url` — a
  // gateway names somebody else's endpoint. A base-url-less table is the Codex desktop
  // app's own native-routing placeholder (since app 26.924 each app-managed rewrite
  // writes `model_provider = "custom"` plus such a table, stripping the injected root
  // keys alongside), which re-injects cleanly because the injector strips a root
  // `model_provider` line first. A REAL external provider must carry a base_url.
  if (providerTableStart(content.split("\n"), provider) !== -1 && providerTableString(content, provider, "base_url") === null) {
    return null;
  }
  return provider;
}

/**
 * The ownership answer for read/write paths — inject, sync, connect, restore, and the
 * shutdown gate. It deliberately reads the whole file like Codex does (links included):
 * a large or link-mediated config is still a valid config, and these callers must
 * classify it exactly rather than degrade to "undetermined".
 */
export function currentExternalCodexModelProvider(): string | null {
  if (!existsSync(CODEX_CONFIG_PATH)) return null;
  return externalCodexModelProvider(readFileSync(CODEX_CONFIG_PATH, "utf8"));
}

/**
 * The same ownership answer for read-only observation (the settings GET / poll path),
 * through a bounded read so a special or oversized config.toml cannot stall a request.
 * A present-but-unreadable config throws so the caller reports undetermined ownership
 * instead of "none".
 */
export function observedExternalCodexModelProvider(): string | null {
  const content = readBoundedCodexConfig(CODEX_CONFIG_PATH);
  return content === null ? null : externalCodexModelProvider(content);
}

/**
 * Detect the file's dominant line ending. Structural edits retain physical line endings;
 * the full injection/removal pipeline still normalizes to LF at its boundary and converts
 * back on write so generated blocks do not leave a mixed-EOL file.
 */
export function dominantEol(content: string): "\r\n" | "\n" {
  const crlf = (content.match(/\r\n/g) ?? []).length;
  if (crlf === 0) return "\n";
  const bareLf = (content.match(/\n/g) ?? []).length - crlf;
  return crlf >= bareLf ? "\r\n" : "\n";
}

/** Normalize all line endings to `eol` (CRLF first collapsed to LF, then expanded). */
export function applyEol(content: string, eol: "\r\n" | "\n"): string {
  const lf = content.replace(/\r\n/g, "\n");
  return eol === "\n" ? lf : lf.replace(/\n/g, "\r\n");
}

/** Label Codex shows for the injected provider when the operator has not chosen one. */
export const DEFAULT_CODEX_PROVIDER_DISPLAY_NAME = "OpenCodex Proxy";

/** Longest label accepted, matching the display-label policy used for provider names. */
const MAX_CODEX_PROVIDER_DISPLAY_NAME_LENGTH = 128;

/** Would this label put a control character into config.toml? */
function hasControlCharacter(value: string): boolean {
  // Checked by code point rather than by a control-character regex, which needs a lint
  // suppression this repository's hygiene gate rejects — and which reads no more clearly.
  for (const character of value) {
    const code = character.codePointAt(0) ?? 0;
    if (code < 0x20 || code === 0x7f) return true;
  }
  return false;
}

/**
 * Which label to write, given whatever the config holds.
 *
 * Presentation only, and deliberately separate from identity: routing resolves through the
 * provider id `opencodex` in the root `model_provider` line and the `[model_providers.opencodex]`
 * header, neither of which is derived from this value. So a rename cannot reroute a thread or
 * orphan a row that already names that id (#4810).
 *
 * Every rejected value falls back to the default rather than being emitted or omitted. Codex
 * refuses to load a provider with no name, so writing a blank one would break the whole config
 * file rather than one thread — strictly worse than the branding it was meant to remove. That is
 * also why there is no way to suppress the field: suppression here means choosing a neutral
 * label. A control character or an over-long value is rejected for the same reason, because
 * `tomlString` would faithfully encode something Codex may still reject.
 */
export function resolveCodexProviderDisplayName(configured?: string): string {
  const trimmed = (configured ?? "").trim();
  if (!trimmed) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
  if (trimmed.length > MAX_CODEX_PROVIDER_DISPLAY_NAME_LENGTH) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
  if (hasControlCharacter(trimmed)) return DEFAULT_CODEX_PROVIDER_DISPLAY_NAME;
  return trimmed;
}

export function buildProviderTableBlock(
  port: number,
  supportsWebsockets?: boolean,
  includeApiAuthHeader?: boolean,
  hostname?: string,
): string;
export function buildProviderTableBlock(
  target: CodexRoutingTarget,
  supportsWebsockets?: boolean,
): string;
export function buildProviderTableBlock(
  portOrTarget: number | CodexRoutingTarget,
  supportsWebsockets = false,
  includeApiAuthHeader = false,
  hostname?: string,
): string {
  const target = typeof portOrTarget === "number"
    ? validateCodexRoutingTarget({
        baseUrl: `http://${providerBaseHost(hostname)}:${portOrTarget}/v1`,
        requiresAdmissionToken: includeApiAuthHeader,
        tokenEnv: "OPENCODEX_API_AUTH_TOKEN",
      })
    : validateCodexRoutingTarget(portOrTarget);
  return buildProviderTableBlockForTarget(target, supportsWebsockets);
}

export function buildProviderTableBlockForTarget(
  target: CodexRoutingTarget,
  supportsWebsockets = false,
  displayName?: string,
): string {
  const lines = [
    "",
    OCX_ROUTING_MARKER_LINE,
    "[model_providers.opencodex]",
    `name = ${tomlString(resolveCodexProviderDisplayName(displayName))}`,
    `base_url = ${tomlString(target.baseUrl)}`,
    'wire_api = "responses"',
    // false only in the authless Desktop opt-in (#1107); true keeps the App/TUI account gate.
    `requires_openai_auth = ${target.desktopAuthless === true ? "false" : "true"}`,
  ];
  if (target.requiresAdmissionToken) {
    // codex-cli 0.146+ contract (#2073): env_key sends Authorization: Bearer $VAR and
    // hard-errors on a missing/empty variable instead of silently omitting auth. It
    // coexists with requires_openai_auth (env_key wins wire auth; the flag keeps the
    // login/account UX), and the server substitutes stored main auth for our admission
    // bearer (#1686), so the modern form is strictly better than the legacy
    // env_http_headers table this line used to emit.
    lines.push(`env_key = ${tomlString(target.tokenEnv)}`);
  }
  if (supportsWebsockets) lines.push("supports_websockets = true");
  return lines.join("\n") + "\n";
}

export function buildOpenaiBaseUrlLine(
  port: number,
  hostname?: string,
): string;
export function buildOpenaiBaseUrlLine(target: CodexRoutingTarget): string;
export function buildOpenaiBaseUrlLine(
  portOrTarget: number | CodexRoutingTarget,
  hostname?: string,
): string {
  return typeof portOrTarget === "number"
    ? `openai_base_url = "http://${providerBaseHost(hostname)}:${portOrTarget}/v1"`
    : buildOpenaiBaseUrlLineForTarget(validateCodexRoutingTarget(portOrTarget));
}

function buildOpenaiBaseUrlLineForTarget(target: CodexRoutingTarget): string {
  return `openai_base_url = ${tomlString(target.baseUrl)}`;
}

/**
 * Realtime sideband override (codex-rs `experimental_realtime_ws_base_url`), written with the
 * SAME value as `openai_base_url`. Desktop voice creates its WebRTC call through the proxy
 * (`POST /v1/live`, answered under the Pool account the proxy selects) but, since openai/codex
 * 438c9e98d (#35830), joins the sideband at `wss://api.openai.com/v1/live/{callId}` with the
 * app's own login unless this key redirects it. Two accounts, one call: the join 404s. Pointing
 * the key at the proxy sends the join through `GET /v1/live/{callId}` (src/server/live.ts),
 * where the same Pool account is reused. codex-rs turns `http` into `ws` and appends
 * `/live/{callId}` itself; the value must stay the canonical `/v1` root.
 */
export function buildRealtimeWsBaseUrlLine(target: CodexRoutingTarget): string {
  return `${REALTIME_WS_BASE_URL_KEY} = ${tomlString(target.baseUrl)}`;
}

/**
 * Design B root-key injection: place `OCX_SECTION_MARKER` + `openai_base_url` at the document
 * ROOT (before the first table header). Idempotent: an existing marker-owned line is rewritten
 * in place. A user's OWN root `openai_base_url` (no marker above it) is respected — we keep it
 * and inject nothing, reporting `keptUserBaseUrl` so the caller can surface it.
 */
export function setRootOpenaiBaseUrl(
  content: string,
  port: number,
  hostname?: string,
): { content: string; keptUserBaseUrl: boolean };
export function setRootOpenaiBaseUrl(
  content: string,
  target: CodexRoutingTarget,
): { content: string; keptUserBaseUrl: boolean };
export function setRootOpenaiBaseUrl(
  content: string,
  portOrTarget: number | CodexRoutingTarget,
  hostname?: string,
): { content: string; keptUserBaseUrl: boolean } {
  if (typeof portOrTarget !== "number") {
    return setRootOpenaiBaseUrlForTarget(content, validateCodexRoutingTarget(portOrTarget));
  }
  return setRootUrl(content, contextCompatibleBaseLine(content, buildOpenaiBaseUrlLine(portOrTarget, hostname)));
}

function ownedRootUrl(lines: SourceLine[], index: number, key: string): boolean {
  return lines[index]!.structural && rootTomlString(lines[index]!.text, key) !== null
    && index > 0 && lines[index - 1]!.structural && isOcxRoutingMarkerLine(lines[index - 1]!.text);
}

function insertRootSourceLines(content: string, added: string[]): string {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  const eol = dominantEol(content);
  if (rootEnd === lines.length) {
    return content.replace(/(?:\r?\n)+$/, "") + eol + added.join(eol) + eol;
  }
  let at = rootEnd;
  while (at > 0 && lines[at - 1]!.structural && lines[at - 1]!.text.trim() === "") at -= 1;
  lines.splice(at, 0, ...added.map(text => ({ text, eol, structural: true })));
  return bom + sourceText(lines);
}

function setRootUrl(content: string, key: string): { content: string; keptUserBaseUrl: boolean } {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  for (let index = 0; index < rootEnd; index++) {
    if (!lines[index]!.structural || !isRootOpenaiBaseUrlLine(lines[index]!.text)) continue;
    if (!ownedRootUrl(lines, index, "openai_base_url")) return { content, keptUserBaseUrl: true };
    lines[index - 1]!.text = OCX_ROUTING_MARKER_LINE;
    lines[index]!.text = key;
    return { content: bom + sourceText(lines), keptUserBaseUrl: false };
  }
  return { content: insertRootSourceLines(content, [OCX_ROUTING_MARKER_LINE, key]), keptUserBaseUrl: false };
}

export function setRootOpenaiBaseUrlForTarget(
  content: string,
  target: CodexRoutingTarget,
): { content: string; keptUserBaseUrl: boolean } {
  return setRootUrl(content, contextCompatibleBaseLine(content, buildOpenaiBaseUrlLineForTarget(target)));
}

/**
 * Companion to `setRootOpenaiBaseUrlForTarget` for the realtime sideband override. Same
 * ownership rule, applied per key: the line is ours only when the marker sits directly
 * above it; a user's own line (no marker above it) is kept and nothing is injected. The
 * key gets its OWN marker line rather than sharing the routing override's, so a user line
 * that happens to sit right under our `openai_base_url` is never mistaken for ours.
 * Placement: directly after the marker-owned `openai_base_url` pair. Only ever called on
 * the Design B (loopback) path right after the routing override was written — the legacy
 * provider-table form needs the admission-token header, which the sideband cannot carry.
 */
export function setRootRealtimeWsBaseUrl(
  content: string,
  target: CodexRoutingTarget,
): { content: string; keptUserRealtimeWsBaseUrl: boolean } {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  const key = buildRealtimeWsBaseUrlLine(validateCodexRoutingTarget(target));
  for (let index = 0; index < rootEnd; index++) {
    if (!lines[index]!.structural || !isRootRealtimeWsBaseUrlLine(lines[index]!.text)) continue;
    if (!ownedRootUrl(lines, index, REALTIME_WS_BASE_URL_KEY)) return { content, keptUserRealtimeWsBaseUrl: true };
    lines[index - 1]!.text = OCX_ROUTING_MARKER_LINE;
    lines[index]!.text = key;
    return { content: bom + sourceText(lines), keptUserRealtimeWsBaseUrl: false };
  }
  for (let index = 0; index < rootEnd; index++) {
    if (!isRootOpenaiBaseUrlLine(lines[index]!.text) || !ownedRootUrl(lines, index, "openai_base_url")) continue;
    const eol = dominantEol(content);
    lines[index]!.eol ||= eol;
    lines.splice(index + 1, 0, ...[OCX_ROUTING_MARKER_LINE, key].map(text => ({ text, eol, structural: true })));
    return { content: bom + sourceText(lines), keptUserRealtimeWsBaseUrl: false };
  }
  return { content, keptUserRealtimeWsBaseUrl: false };
}

/**
 * Root key codex-rs reads for its web-search mode. The value opencodex writes is the only one that
 * takes the native hosted tool away; the other modes keep it, so they are never written here.
 */
export const ROOT_WEB_SEARCH_KEY = "web_search";

/** The one value opencodex writes for {@link ROOT_WEB_SEARCH_KEY}. */
export const ROOT_WEB_SEARCH_DISABLED_LINE = 'web_search = "disabled"';

/** The value {@link ROOT_WEB_SEARCH_DISABLED_LINE} carries, as the journal records it. */
export const ROOT_WEB_SEARCH_DISABLED_VALUE = "disabled";

export function isRootWebSearchLine(line: string): boolean {
  // Quoted spellings (including escaped basic keys) name the same key to TOML.
  // A predicate that matched only the bare
  // spelling would leave `"web_search" = "live"` in place while inserting our own line, and two
  // root keys of the same name stop Codex from loading the file at all.
  return rootAssignmentKey(line) === ROOT_WEB_SEARCH_KEY;
}

/** What an earlier injection recorded about this key, read back from the journal. */
export interface RootWebSearchJournal {
  /** The value that injection wrote, or null when it wrote none. */
  injectedValue?: string | null;
  /** The complete user-owned assignment removed (possibly multiline), or null. */
  replacedUserLine?: string | null;
}

/** What one pass of {@link ensureRootWebSearchDisabled} did, for the journal to record. */
export interface RootWebSearchOutcome {
  content: string;
  /** The complete user-owned root assignment removed (possibly multiline), or null. */
  replacedUserLine: string | null;
  /** The value this pass wrote, or null when it wrote none. */
  wroteValue: string | null;
}

/**
 * Ensure the root `web_search` key follows the web-search sidecar's master switch.
 *
 * Codex reads this key (modes `disabled`/`cached`/`indexed`/`live`) to decide whether its native
 * Responses `web_search` tool is offered at all; `disabled` is the only mode that removes the tool
 * from the model's tool list. An operator who runs an MCP search server instead needs exactly that,
 * because a native tool the client still advertises wins the model's attention away from the MCP
 * one. So the switch is not advisory: while `webSearchSidecar.enabled` is false we own the value.
 *
 * Ownership, both directions:
 * - `disabled` removes EVERY root `web_search` line (ours or the user's) and writes the marker-owned
 *   pair. Two root keys of the same name are invalid TOML, so keeping a user line alongside ours
 *   would stop Codex from loading the file at all — and the operator has just asked for this exact
 *   value. A value the user owned is reported back as `replacedUserLine` so the journal can carry
 *   it, and `ocx restore` additionally replays the snapshot, like every other line this injection
 *   rewrites.
 * - enabled (or unset) removes only the marker-owned pair, so re-enabling the sidecar cannot leave
 *   the native tool switched off — which would silently leave the sidecar with nothing to intercept.
 *   Two further sources of ownership come from the journal: the exact value a recorded injection
 *   wrote, so a line whose marker comment a Codex app reserialize dropped is still ours (#1798), and
 *   the user line that injection removed, which goes back now that nothing owns the key.
 */
export function ensureRootWebSearchDisabled(
  content: string,
  disabled: boolean,
  journal: RootWebSearchJournal = {},
): RootWebSearchOutcome {
  const stripped = stripInjectedRootWebSearch(content, journal.injectedValue);
  const { bom, lines, rootEnd } = rootSourceLines(stripped);
  if (!disabled) {
    const restore = journal.replacedUserLine;
    const owned = lines.slice(0, rootEnd).some(line => line.structural && isRootWebSearchLine(line.text));
    return {
      content: restore?.trim() && !owned ? insertRootSourceLines(stripped, [applyEol(restore, dominantEol(stripped))]) : stripped,
      replacedUserLine: null,
      wroteValue: null,
    };
  }
  // Whatever root line is left here is not marker-owned and not the value we recorded writing, so
  // it is the operator's own mode: keep its exact text for the pass that switches the sidecar back
  // on. Only one can be valid TOML, and the first is the one Codex reads. A pass that finds no such
  // line keeps the one an earlier off pass recorded — the ordinary way to reach that state is a
  // second injection while the switch is still off (a model change), and the operator's mode must
  // not evaporate because the line it came from is already gone.
  const drop = new Set<number>();
  let replacedUserLine = journal.replacedUserLine ?? null;
  let foundUserAssignment = false;
  for (let index = 0; index < rootEnd; index++) {
    if (!lines[index]!.structural || !isRootWebSearchLine(lines[index]!.text)) continue;
    const assignment = sourceAssignmentSpan(lines, index, rootEnd);
    if (!assignment) throw new Error("Cannot safely rewrite an incomplete root web_search assignment.");
    if (!foundUserAssignment) replacedUserLine = assignment.text;
    foundUserAssignment = true;
    for (let at = index; at < assignment.end; at++) drop.add(at);
  }
  return {
    content: insertRootSourceLines(
      bom + sourceText(lines.filter((_, index) => !drop.has(index))),
      [OCX_ROUTING_MARKER_LINE, ROOT_WEB_SEARCH_DISABLED_LINE],
    ),
    replacedUserLine,
    wroteValue: ROOT_WEB_SEARCH_DISABLED_VALUE,
  };
}

/**
 * Remove the marker-owned root `web_search` pair (marker line + the key line right after it).
 * Same ownership rule as `stripInjectedOpenaiBaseUrl`: a user's own line has no marker above it and
 * survives, so a hand-set mode is never reinterpreted as ours after an injection cycle. `injectedValue`
 * adds the #1798 value evidence — the exact value a recorded injection wrote — so a line whose marker
 * comment a Codex app reserialize dropped is still recognized as ours.
 */
export function stripInjectedRootWebSearch(content: string, injectedValue?: string | null): string {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  const drop = new Set<number>();
  for (let index = 0; index < rootEnd; index++) {
    const line = lines[index]!;
    if (!line.structural || !isRootWebSearchLine(line.text)) continue;
    const assignment = sourceAssignment(lines, index, rootEnd);
    if (!assignment || typeof assignment.value !== "string") continue;
    const value = assignment.value;
    const markerOwned = index > 0 && lines[index - 1]!.structural && isOcxRoutingMarkerLine(lines[index - 1]!.text);
    if (!markerOwned && (!injectedValue || value !== injectedValue)) continue;
    for (let at = index; at < assignment.end; at++) drop.add(at);
    if (markerOwned) drop.add(index - 1);
  }
  return drop.size ? bom + sourceText(lines.filter((_, index) => !drop.has(index))) : content;
}

/**
 * Remove the marker-owned root `openai_base_url` (marker line + the key line right after it).
 * A user's own root override (no marker) survives; an orphaned marker with no key line after
 * it is dropped too so repeated strip/inject cycles cannot accumulate marker comments.
 * A marker-owned `experimental_realtime_ws_base_url` pair is removed by the same rule.
 */
export function stripInjectedOpenaiBaseUrl(content: string): string {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  const drop = new Set<number>();
  for (let index = 0; index < rootEnd; index++) {
    const line = lines[index]!;
    if (!line.structural || !isOcxRoutingMarkerLine(line.text)) continue;
    const next = lines[index + 1];
    if (index + 1 < rootEnd && next?.structural
      && (isRootOpenaiBaseUrlLine(next.text) || isRootRealtimeWsBaseUrlLine(next.text))) {
      const key = rootAssignmentKey(next.text)!;
      if (rootTomlString(next.text, key) === null) continue;
      drop.add(index);
      drop.add(index + 1);
    } else if (index + 1 >= rootEnd || (next?.structural && next.text.trim() === "")) {
      drop.add(index);
    }
  }
  return drop.size ? bom + sourceText(lines.filter((_, index) => !drop.has(index))) : content;
}

/**
 * Strip every existing `model_provider` line that we must not duplicate: any line set to
 * "opencodex" (wherever it sits — including a previously mis-nested one under a table), plus any
 * ROOT-level model_provider (before the first table) of any value, since we override the global.
 * A `model_provider` legitimately inside a user table/profile with a non-opencodex value is left
 * untouched.
 */
export function stripExistingModelProvider(content: string): string {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  const drop = new Set<number>();
  for (let index = 0; index < lines.length; index++) {
    if (!lines[index]!.structural || rootAssignmentKey(lines[index]!.text) !== "model_provider") continue;
    const assignment = sourceAssignmentSpan(lines, index, index < rootEnd ? rootEnd : lines.length);
    if (!assignment) throw new Error("Cannot safely rewrite an incomplete model_provider assignment.");
    if (index >= rootEnd) {
      const decoded = sourceAssignment(lines, index);
      if (typeof decoded?.value !== "string" || decoded.value.trim() !== "opencodex") continue;
    }
    for (let at = index; at < assignment.end; at++) drop.add(at);
  }
  return bom + sourceText(lines.filter((_, index) => !drop.has(index)));
}

export function stripRootRoutedModel(content: string): string {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  return bom + sourceText(lines.filter((line, index) => index >= rootEnd || !line.structural
    || !rootTomlString(line.text, "model")?.includes("/")));
}

/**
 * Insert `model_provider = "opencodex"` at the document ROOT — immediately before the first table
 * header (TOML root keys must precede all tables). If there are no tables, append it to the root body.
 */
export function setRootModelProvider(content: string): string {
  return insertRootSourceLines(content, ['model_provider = "opencodex"']);
}

interface CatalogBindingOwner {
  configPath?: string;
  journaledPath?: string | null;
}

function ownedCatalogPath(binding: string, owner: CatalogBindingOwner): string | null {
  const configPath = owner.configPath ?? CODEX_CONFIG_PATH;
  const defaultPath = defaultCodexCatalogPathForConfig(configPath);
  if (sameCodexCatalogPath(configPath, binding, defaultPath)) return defaultPath;
  const journaled = owner.journaledPath;
  return journaled && sameCodexCatalogPath(configPath, binding, journaled)
    ? resolveCodexCatalogPath(configPath, journaled) : null;
}

function* catalogAssignments(lines: SourceLine[], rootEnd: number) {
  for (let i = 0; i < rootEnd; i++) {
    if (!lines[i].structural || rootAssignmentKey(lines[i].text) !== "model_catalog_json") continue;
    const assignment = sourceAssignment(lines, i, rootEnd);
    const value = assignment?.value;
    yield { start: i, end: assignment?.end ?? i + 1, binding: typeof value === "string" ? value : null };
  }
}

function readRootModelCatalogPath(content: string, owner: CatalogBindingOwner): string | null {
  const { lines, rootEnd } = rootSourceLines(content);
  let owned: string | null = null;
  for (const { binding } of catalogAssignments(lines, rootEnd)) {
    if (binding === null) continue;
    if (!ownedCatalogPath(binding, owner)) return binding;
    owned ??= binding;
  }
  return owned;
}

export function updateRootModelCatalogPath(content: string, binding: string | null, owner: CatalogBindingOwner = {}):
  { content: string; injectedBinding: string | null } {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  const ownedLines = new Set<number>();
  let hasUserAssignment = false;
  for (const existing of catalogAssignments(lines, rootEnd)) {
    if (existing.binding && ownedCatalogPath(existing.binding, owner)) {
      for (let line = existing.start; line < existing.end; line++) ownedLines.add(line);
    } else {
      hasUserAssignment = true;
    }
  }
  const injectedBinding = hasUserAssignment ? null : binding;
  const kept = lines.filter((_, i) => !ownedLines.has(i));
  if (injectedBinding === null) return { content: bom + sourceText(kept), injectedBinding };

  const key = "model_catalog_json = " + tomlString(injectedBinding);
  const firstOwned = ownedLines.values().next().value;
  if (firstOwned === undefined) {
    return { content: insertRootSourceLines(content, [key]), injectedBinding };
  }
  const eol = lines[firstOwned].eol;
  kept.splice(firstOwned, 0, { text: key, eol, structural: true });
  return { content: bom + sourceText(kept), injectedBinding };
}

export function removeProfileSection(content: string): string {
  const { bom, lines } = rootSourceLines(content);
  let inProfile = false;
  const kept = lines.filter(line => {
    if (line.structural && /^\s*\[/.test(line.text)) {
      try {
        const parsed = Bun.TOML.parse(line.text) as Record<string, unknown>;
        inProfile = typeof parsed.profiles === "object" && parsed.profiles !== null
          && Object.hasOwn(parsed.profiles, "opencodex");
      } catch { inProfile = false; }
    }
    return !inProfile;
  });
  return normalizeStructuralWhitespace(bom + sourceText(kept));
}

export function normalizeServiceTier(content: string): string {
  const { bom, lines, rootEnd } = rootSourceLines(content);
  for (const line of lines.slice(0, rootEnd)) {
    if (line.structural) line.text = line.text.replace(/^(\s*service_tier\s*=\s*)["']priority["']\s*$/, '$1"fast"');
  }
  return bom + sourceText(lines);
}

export function ensureFastModeFeature(content: string, fastMode?: boolean): string {
  // Tri-state fast mode (see OcxConfig.fastMode): true forces `fast_mode = true`,
  // false forces `fast_mode = false`, and undefined leaves the user's config
  // untouched (no [features] table is added and an existing fast_mode line is
  // preserved as-is). Table and key matching accept the valid TOML spellings
  // `[features] # comment`, `["features"]` / `['features']`, and quoted keys.
  if (fastMode === undefined) return content;
  const { bom, lines } = rootSourceLines(content);
  const eol = lines.find(line => line.eol)?.eol || "\n";
  const featuresStart = lines.findIndex(line => {
    if (!line.structural || !/^\s*\[/.test(line.text)) return false;
    try {
      const parsed = Bun.TOML.parse(line.text) as Record<string, unknown>;
      return Object.keys(parsed).length === 1 && typeof parsed.features === "object"
        && parsed.features !== null && !Array.isArray(parsed.features)
        && Object.keys(parsed.features).length === 0;
    } catch { return false; }
  });
  if (featuresStart === -1) {
    return content.replace(/[\r\n]+$/, "") + eol + eol + "[features]" + eol
      + "fast_mode = " + (fastMode ? "true" : "false") + eol;
  }

  const nextTable = lines.findIndex(
    (line, index) => index > featuresStart && line.structural && /^\s*\[/.test(line.text),
  );
  const featuresEnd = nextTable === -1 ? lines.length : nextTable;
  for (let i = featuresStart + 1; i < featuresEnd; i++) {
    if (lines[i].structural && rootAssignmentKey(lines[i].text) === "fast_mode") {
      // Refuse to rewrite an incomplete physical view of a collection/string value.
      try { Bun.TOML.parse(lines[i].text); } catch { return content; }
      lines[i].text = `${/^\s*/.exec(lines[i].text)![0]}fast_mode = ${fastMode ? "true" : "false"}`;
      return bom + sourceText(lines);
    }
  }

  let insertAt = featuresEnd;
  while (insertAt > featuresStart + 1 && lines[insertAt - 1].structural && lines[insertAt - 1].text.trim() === "") insertAt--;
  if (insertAt > 0 && !lines[insertAt - 1].eol) lines[insertAt - 1].eol = eol;
  lines.splice(insertAt, 0, { text: `fast_mode = ${fastMode ? "true" : "false"}`, eol, structural: true });
  return bom + sourceText(lines);
}

export function stripOpencodexCatalogPath(content: string, owner: CatalogBindingOwner = {}): string {
  return updateRootModelCatalogPath(content, null, owner).content;
}

export function buildProfileFile(port: number, catalogPath?: string | null, supportsWebsockets?: boolean, includeApiAuthHeader?: boolean, hostname?: string, fastMode?: boolean): string;
export function buildProfileFile(target: CodexRoutingTarget, catalogPath?: string | null, supportsWebsockets?: boolean, fastMode?: boolean): string;
export function buildProfileFile(
  portOrTarget: number | CodexRoutingTarget,
  catalogPath?: string | null,
  supportsWebsockets = false,
  includeApiAuthHeaderOrFastMode?: boolean,
  hostname?: string,
  fastMode?: boolean,
): string {
  const target = typeof portOrTarget === "number"
    ? validateCodexRoutingTarget({
        baseUrl: `http://${providerBaseHost(hostname)}:${portOrTarget}/v1`,
        requiresAdmissionToken: includeApiAuthHeaderOrFastMode === true,
        tokenEnv: "OPENCODEX_API_AUTH_TOKEN",
      })
    : validateCodexRoutingTarget(portOrTarget);
  return buildProfileFileForTarget(
    target,
    catalogPath,
    supportsWebsockets,
    typeof portOrTarget === "number" ? fastMode : includeApiAuthHeaderOrFastMode,
  );
}

export function buildProfileFileForTarget(
  target: CodexRoutingTarget,
  catalogPath?: string | null,
  supportsWebsockets = false,
  fastMode?: boolean,
  displayName?: string,
): string {
  const origin = routingTargetOrigin(target);
  const host = new URL(origin).host;
  // Design B (loopback): the reference/fallback file documents the root override form.
  // Non-loopback keeps the legacy provider-table shape (built-in provider cannot carry
  // the x-opencodex-api-key env header); explicit Desktop policies share that shape.
  if (!usesProviderTable(target)) {
    const lines = [
      "# OpenCodex proxy fallback config (Design B)",
      `# Root override that points Codex's built-in openai provider at the proxy on ${host}.`,
      "# Merge these root keys into ~/.codex/config.toml manually if auto-injection was removed.",
      buildOpenaiBaseUrlLineForTarget(target),
    ];
    if (catalogPath) lines.push(`model_catalog_json = ${tomlString(catalogPath)}`);
    if (fastMode !== undefined) lines.push("", "[features]", `fast_mode = ${fastMode ? "true" : "false"}`, "");
    return lines.join("\n");
  }
  const lines = [
    "# OpenCodex proxy profile — use with: codex --profile opencodex",
    `# Routes all model requests through the opencodex proxy at ${host}`,
    'model_provider = "opencodex"',
  ];
  if (catalogPath) lines.push(`model_catalog_json = ${tomlString(catalogPath)}`);
  if (fastMode !== undefined) lines.push("", "[features]", `fast_mode = ${fastMode ? "true" : "false"}`);
  lines.push(buildProviderTableBlockForTarget(target, supportsWebsockets, displayName).trimEnd(), "");
  return lines.join("\n");
}

/**
 * Root keys this build owns in either profile shape. They are never carried
 * forward: leaving provider-table mode drops `model_provider` from the template,
 * and a caller that passes no catalog path drops `model_catalog_json`, so a
 * carried copy would point the profile at routing this build no longer writes.
 */
const MANAGED_PROFILE_ROOT_KEYS = new Set([
  "model_provider",
  "model_catalog_json",
  "openai_base_url",
]);

/**
 * Root keys the previous profile carried that this build does not write.
 *
 * Operators add Codex settings such as `stream_idle_timeout_ms` and
 * `stream_max_retries` to `opencodex.config.toml`. Rebuilding the file from the
 * template dropped them without a word (#8066), so any root key this build does
 * not own is carried over, ahead of the first table. Values that span several
 * lines are copied whole, because one line of a multi-line value would not
 * parse, and every carried assignment keeps its original bytes: nothing is
 * decoded and reserialized, so a 64-bit integer Bun cannot represent survives.
 *
 * A carried root key named like a table the generated profile writes (an inline
 * `features = { ... }` against a generated `[features]`) is dropped: TOML
 * forbids defining the same table twice, and the generated table wins because
 * it carries the settings this build manages.
 */
export function preserveUnmanagedProfileKeys(existing: string | null, generated: string): string {
  if (!existing) return generated;
  const generatedKeys = rootKeysOf(generated);
  if (generatedKeys.size === 0) return generated;
  const generatedTables = topLevelTableNamesOf(generated);

  const existingSource = rootSourceLines(existing);
  const carried: string[] = [];
  const carriedKeys = new Set<string>();
  for (let index = 0; index < existingSource.rootEnd; index += 1) {
    if (!existingSource.lines[index]?.structural) continue;
    const span = sourceAssignmentSpan(existingSource.lines, index, existingSource.rootEnd);
    if (!span) continue;
    index = span.end - 1;
    if (generatedKeys.has(span.key) || MANAGED_PROFILE_ROOT_KEYS.has(span.key)) continue;
    if (generatedTables.has(span.key)) continue;
    if (carriedKeys.has(span.key)) continue;
    carriedKeys.add(span.key);
    // Drop only trailing blank lines; the assignment's own bytes, trailing spaces included, stay.
    carried.push(span.text.replace(/(?:\r?\n[ \t]*)+$/, ""));
  }
  if (carried.length === 0) return generated;

  const lines = generated.split("\n");
  const firstTable = lines.findIndex((line) => /^\s*\[/.test(line));
  lines.splice(firstTable === -1 ? lines.length : firstTable, 0, [
    "# Root keys OpenCodex does not manage, kept from the previous profile:",
    ...carried,
    "",
  ].join("\n"));
  return lines.join("\n");
}

/** Names of the root assignments in a TOML document, before its first table. */
function rootKeysOf(content: string): Set<string> {
  const keys = new Set<string>();
  const source = rootSourceLines(content);
  for (let index = 0; index < source.rootEnd; index += 1) {
    if (!source.lines[index]?.structural) continue;
    const span = sourceAssignmentSpan(source.lines, index, source.rootEnd);
    if (!span) continue;
    keys.add(span.key);
    index = span.end - 1;
  }
  return keys;
}

/** First path segment of every table header in a generated document. */
function topLevelTableNamesOf(content: string): Set<string> {
  const names = new Set<string>();
  for (const line of rootSourceLines(content).lines) {
    if (!line.structural || !/^\s*\[/.test(line.text)) continue;
    try {
      const name = Object.keys(Bun.TOML.parse(line.text))[0];
      if (name !== undefined) names.add(name);
    } catch { /* the template only writes valid headers */ }
  }
  return names;
}

export function chooseCatalogPathForInjection(
  content: string,
  requested?: string | null,
  owner: CatalogBindingOwner = {},
): string | null {
  const configPath = owner.configPath ?? CODEX_CONFIG_PATH;
  if (requested !== undefined) return requested ? resolveCodexCatalogPath(configPath, requested) : null;

  const existing = readRootModelCatalogPath(content, owner);
  if (existing) {
    const owned = ownedCatalogPath(existing, owner);
    if (!owned) return resolveCodexCatalogPath(configPath, existing);
    if (existsSync(owned)) return owned;
  }

  const defaultPath = defaultCodexCatalogPathForConfig(configPath);
  return existsSync(defaultPath) ? defaultPath : null;
}

/** Diagnose a missing default catalog, which prevents Codex from loading the config (#5261). */
export function missingOwnedCatalogPath(content: string, configPath = CODEX_CONFIG_PATH): string | null {
  const owner = { configPath };
  const existing = readRootModelCatalogPath(content, owner);
  const owned = existing ? ownedCatalogPath(existing, owner) : null;
  return owned && !existsSync(owned) ? owned : null;
}
