codex-copilot-dx 0.7.9 → 0.8.0

package/README.md

@@ -76,7 +76,7 @@ Normal startup and reuse of an existing adapter check `~/.codex/config.toml` onc
 | `[features]` `context_management` | Add `true` when missing; preserve explicit values and alternative declarations as described above | `true` |
 | `[mcp_servers.ccdx_image]` | Added in a marked CCDX-owned block only after `ccdx enable-image`; removed by `ccdx disable-image` | Absent by default |
 
-The two token limits are fixed defaults, not detected model capabilities. Existing custom values are retained. Writes target the listed keys with line-based edits and atomic replacement; this is not a general TOML formatter. The shell environment updater recognizes the literal `[shell_environment_policy.set]` header. Use `ccdx doctor config` to inspect parsed values and preview what this writer would do with the current file. No actual change means no file rewrite.
+The two token limits are fixed defaults, not detected model capabilities. Existing custom values are retained. Writes target the listed keys with format-preserving edits and atomic replacement; this is not a general TOML formatter. Quoted keys, quoted table headers, and explicit dotted shell-environment declarations are recognized; inline shell-environment tables are left intact. Startup and image configuration commands validate UTF-8/TOML and verify that unrelated settings retain their values before writing. An unsafe edit leaves the original file unchanged. Use `ccdx doctor config` to inspect parsed values and preview what this writer would do with the current file. No actual change means no file rewrite.
 
 ## Version 0.7.0 migration
 
@@ -131,7 +131,7 @@ The selector is ordered numerically:
 8. Relay — fixed nodes receive and pass a short light trail
 9. Split — one incoming light trail divides into two outgoing trails
 
-Enter the corresponding number to select an animation. The Comet row includes a static preview, and after a selection CCDX plays one cycle of the chosen animation as confirmation when terminal animation is enabled. The setting is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set.
+All nine rows preview their animations together while you enter a number to select one. The live previews keep each theme's original timing and leave the input cursor in place; selection ends them immediately. Small terminals, disabled animation, CI and dumb terminals retain static previews. Resizing or clearing the terminal pauses the live gallery so input stays usable. When the gallery cannot run, CCDX retains the selected animation's one-cycle confirmation when supported. The setting is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set.
 
 All nine animations use the same 20-column colon track and cyan/blue palette. They indicate activity, not completion percentage. Braille was removed in 0.7.7. A saved `terminal_animation: "braille"` falls back to Comet without rewriting the settings file; choosing another animation replaces it, and explicitly choosing Comet clears it. Other settings remain intact.
 
@@ -145,9 +145,9 @@ Image generation is disabled by default. Configure it interactively only when yo
 ccdx enable-image
 ```
 
-The command asks for an HTTPS `/images/generations` endpoint and an API key without echoing the key. It reads the endpoint's `/models` catalog, detects either the standard OpenAI Images request format or the supported `input.messages` format, and asks for a numeric model selection only when multiple image models are available. Its validation request omits the prompt and does not generate an image.
+The command asks for an HTTPS `/images/generations` endpoint and an API key without echoing the key. It reads the endpoint's `/models` catalog and asks for a numeric model selection only when multiple image models are available. It then detects either the standard OpenAI Images request format or the supported `input.messages` format for the selected model only. Its single validation request omits the prompt and does not generate an image.
 
-The provider credential is stored in `~/.config/codex-copilot-dx/image-provider.json`, or under `XDG_CONFIG_HOME`, with mode `0600`. The API key is never written to `~/.codex/config.toml`; that file receives only a marked local MCP entry pointing to the running CCDX adapter with a 210-second tool timeout. Enabling also installs CCDX-owned `ccdx-image` guidance under `~/.codex/skills`, with a self-contained Node helper. Codex uses the MCP tool directly, including through deferred tool search; an already-open task without that tool can use the helper to call the same local service and display the saved image. Neither route requires Python, an OpenAI SDK, or copying credentials. The original built-in imagegen skill remains available for capabilities such as editing and reference images.
+The provider credential is stored in `~/.config/codex-copilot-dx/image-provider.json`, or under `XDG_CONFIG_HOME`, with mode `0600`. The API key is never written to `~/.codex/config.toml`; that file receives only a marked local MCP entry pointing to the running CCDX adapter with a 210-second tool timeout. Enabling also installs CCDX-owned `ccdx-image` guidance under `~/.codex/skills`, with a self-contained Node helper. Codex uses the MCP tool directly, including through deferred tool search; an already-open task without that tool can use the helper to call the same local service and display the saved image. Neither route requires Python, an OpenAI SDK, or copying credentials. The original built-in imagegen skill remains available for capabilities such as editing uploaded images and other reference-image workflows.
 
 The enable command verifies the local MCP handshake and generation-tool directory without generating an image. It reports provider configuration separately from local service readiness; it cannot assert that every running Codex task has refreshed its catalog. Codex normally detects changed skills; restart Codex App once if an open task has not refreshed them. Normal CCDX startup installs or updates this guidance for providers already enabled in 0.7.8, without repeating API setup. Unchanged guidance is not rewritten. The existing adapter can remain running because provider settings are loaded when the tool is invoked.
 
@@ -160,7 +160,11 @@ ccdx disable-image
 
 `image-status` never prints the API key and performs only a local, non-generating tool-readiness check. Disabling removes the stored provider credential, the CCDX-owned MCP block, and unmodified CCDX image guidance; user-modified skill files are preserved. Cached tool calls then fail closed. The Node helper creates a new file under the task's `output/imagegen` directory by default and reports its absolute path; it never overwrites an existing file or automatically repeats a failed generation. The image endpoint is contacted only by `enable-image` validation and by explicit `generate_image` tool calls. Ordinary Responses, models, authentication, Fast, Auto-review, compaction, and image-input paths remain on their existing routes.
 
-Generated image downloads must use public HTTPS addresses, do not follow redirects, are DNS-checked against private and reserved addresses, and are capped at 32 MiB. The local MCP route accepts calls only from the same device and permits at most two concurrent generations. The tool supports new-image generation at `1024x1024`, `1536x1024`, or `1024x1536`; it does not claim image editing or multi-turn image editing support.
+Generated image downloads must use public HTTPS addresses, do not follow redirects, are DNS-checked against private and reserved addresses, and are capped at 32 MiB. DNS resolution and downloading share one deadline and respond to cancellation; a late DNS result cannot start a cancelled download. The local MCP route accepts calls only from the same device and permits at most two concurrent image operations. It requires `application/json` and rejects browser `Origin` headers; native Codex and Node clients do not send an Origin. The tool supports new-image generation at `1024x1024`, `1536x1024`, or `1024x1536`.
+
+With `qwen-image-3.0-pro` or `qwen-image-3.0` using either supported protocol, CCDX also exposes `edit_image`. Ask Codex to modify a specific CCDX-generated image; it passes that image's returned `image_id` and the edit instruction to the same configured provider. Each edit returns a new image and ID while preserving the original; omitting `size` retains the source's requested dimensions. The Qwen request contains the source image again on every edit, as required by its [single-turn image editing API](https://help.aliyun.com/zh/model-studio/qwen-image-generation-and-editing-api-reference).
+
+Editing references are opaque IDs bound to the provider configuration, not paths or URLs. Source images up to 10 MiB are kept in a 64 MiB byte-bounded in-memory LRU. IDs expire on eviction, provider/credential changes, or adapter restart; restarting Codex App alone does not clear them. A missing or expired ID fails before upstream dispatch. This feature does not import arbitrary local images or provide masks, transparent output, or an `/images/edits` endpoint. Other providers retain their existing generation behavior. The helper accepts `--image-id` for the same edit operation; its stdout remains the saved absolute file path and stderr reports the new ID. Normal host approvals still apply, and failed edits are never replaced with an automatic new generation.
 
 ### Update
 
@@ -349,6 +353,8 @@ For `/v1/responses/compact`, CCDX sends one terminal `compaction_trigger`, valid
 
 Changing the model or transport of a continuation can require removing incompatible encrypted history from the forwarded request. A specific upstream encrypted-state verification failure can also trigger one sanitized retry, including when a nominally successful HTTP response ends with `response.failed`. CCDX withholds only the pre-output prelude of an encrypted continuation while evaluating that terminal event; it never retries after visible model output, so it cannot duplicate an already-started answer. Unrelated failures pass through unchanged. CCDX does not decrypt that state locally.
 
+After the stream handshake succeeds, stream liveness uses the idle timeout rather than the expired handshake deadline. Eligible HTTP-200 failure recovery acquires a bounded preparation budget and history admission before rebuilding its payload, then releases those reservations when the retry opens upstream or fails. Normal streams still release preparation admission after their response headers arrive.
+
 Successful streaming responses are accepted only when the upstream body is SSE and reaches its protocol terminal event. Unexpected EOF becomes a protocol-native stream error, and repeated blank tool-argument deltas are stopped per tool call. Allowlisted rate-limit, retry, model, trace, and upstream request-ID metadata are forwarded; cookies, authorization, body-length, and encoding headers are not.
 
 CCDX keeps each native Responses message on its first upstream ID when Copilot changes that ID during streaming. Message deltas, completion events, and cached history stay consistent, addressing this cause of duplicate live messages in Codex App. Tool identities, reasoning/encrypted content, message phases, and speed-tier routing are unchanged by this ID normalization. Stable events retain their original SSE bytes; changed events are rewritten with bounded, backpressured streaming.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.7.9",
+  "version": "0.8.0",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/adapter.mjs

@@ -196,7 +196,7 @@ export function createAdapterHandler(options = {}) {
     if (pathname === "/mcp/image") {
       if (imageMcpHandler) return imageMcpHandler(req, res);
       return import("./image-mcp.mjs").then(({ createImageMcpHandler }) => {
-        imageMcpHandler = createImageMcpHandler();
+        imageMcpHandler ||= createImageMcpHandler();
         return imageMcpHandler(req, res);
       });
     }

package/src/cli-animation.mjs

@@ -6,6 +6,7 @@ import {
   renderTerminalAnimationFrame,
   TERMINAL_ANIMATION_THEMES,
 } from "./terminal-animation.mjs";
+import { startTerminalAnimationGallery } from "./terminal-animation-gallery.mjs";
 import {
   readUserSettings,
   terminalAnimationPreference,
@@ -34,6 +35,7 @@ export async function runAnimationCommand({
   output = process.stdout,
   prompt,
   preview = playTerminalAnimationPreview,
+  gallery = startTerminalAnimationGallery,
 } = {}) {
   if (!prompt && (!input.isTTY || !output.isTTY)) {
     throw new Error(`${commandName} animation requires an interactive terminal`);
@@ -45,24 +47,49 @@ export async function runAnimationCommand({
 
   output.write(`${commandName} animation\n`);
   output.write(`Current: ${TERMINAL_ANIMATION_THEMES[currentIndex].label} (${current.source})\n\n`);
+  const labels = TERMINAL_ANIMATION_THEMES.map((theme, index) => `  ${index + 1}. ${theme.label}${markers(theme, current.theme)}`);
+  const prefixWidth = Math.max(...labels.map((label) => label.length)) + 2;
   TERMINAL_ANIMATION_THEMES.forEach((theme, index) => {
-    const staticPreview = theme.id === DEFAULT_TERMINAL_ANIMATION_THEME
-      ? `  ${renderTerminalAnimationFrame(theme.id, 10)}`
-      : "";
-    output.write(`  ${index + 1}. ${theme.label}${markers(theme, current.theme)}${staticPreview}\n`);
+    output.write(`${labels[index].padEnd(prefixWidth)}${renderTerminalAnimationFrame(theme.id, theme.startFrame)}\n`);
   });
 
   let readline;
+  const abort = new AbortController();
   const ask = prompt || (async (question) => {
-    readline ||= createInterface({ input, output });
-    return readline.question(question);
+    if (!readline) {
+      readline = createInterface({ input, output });
+      readline.once("SIGINT", () => abort.abort());
+      readline.once("close", () => abort.abort());
+    }
+    return readline.question(question, { signal: abort.signal });
   });
 
   let selectedTheme = current.theme;
   let keepCurrent = false;
+  let livePreviewed = false;
+  let rowsBelow = 0;
+  let activeGallery;
+  let layoutChanged = false;
+  const stopForLayoutChange = () => {
+    layoutChanged = true;
+    activeGallery?.stop();
+  };
+  const onKeypress = (_text, key) => {
+    if ((key?.ctrl && key.name === "l") || (readline?.getCursorPos().rows ?? 0) > 0) stopForLayoutChange();
+  };
+  output.on?.("resize", stopForLayoutChange);
+  input.on?.("keypress", onKeypress);
   try {
     while (true) {
-      const answer = String(await ask(`Select [${currentIndex + 1}], or q to cancel: `) || "").trim();
+      activeGallery = layoutChanged ? { enabled: false, stop() {} }
+        : gallery({ output, env, prefixWidth, rowsBelow, getInputRows: () => readline?.getCursorPos().rows ?? 0 });
+      livePreviewed ||= activeGallery.enabled;
+      let answer;
+      try {
+        answer = String(await ask(`Select [${currentIndex + 1}], or q to cancel: `) || "").trim();
+      } finally {
+        activeGallery.stop();
+      }
       if (answer.toLowerCase() === "q") {
         output.write("No changes made.\n");
         return { changed: false, cancelled: true, theme: current.theme };
@@ -79,8 +106,16 @@ export async function runAnimationCommand({
         break;
       }
       output.write(`Enter a number from 1 to ${TERMINAL_ANIMATION_THEMES.length}, or q to cancel.\n`);
+      rowsBelow += 2;
     }
+  } catch (error) {
+    if (!abort.signal.aborted) throw error;
+    output.write("\nNo changes made.\n");
+    return { changed: false, cancelled: true, theme: current.theme };
   } finally {
+    activeGallery?.stop();
+    output.off?.("resize", stopForLayoutChange);
+    input.off?.("keypress", onKeypress);
     readline?.close();
   }
 
@@ -88,7 +123,7 @@ export async function runAnimationCommand({
     ? { changed: false, theme: current.theme }
     : writeTerminalAnimationTheme(selectedTheme, { env, home });
   const disabledValue = disabledEnvironmentValue(env);
-  if (!disabledValue) {
+  if (!disabledValue && !livePreviewed) {
     try {
       await preview(selectedTheme, { output });
     } catch {

package/src/cli-image.mjs

@@ -64,9 +64,12 @@ export function hiddenQuestion(input, output, question) {
 }
 
 function fileContent(filePath) {
-  try { return fs.readFileSync(filePath, "utf8"); }
+  try { return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(filePath)); }
   catch (error) {
     if (error?.code === "ENOENT") return "";
+    if (error?.code === "ERR_ENCODING_INVALID_ENCODED_DATA") {
+      throw new Error("Codex configuration is not valid UTF-8 TOML; no configuration changes were written");
+    }
     throw error;
   }
 }
@@ -206,8 +209,14 @@ export async function runImageCommand({
   if (!apiKey) throw new Error("Image API key is required");
 
   output.write("Checking image API...\n");
-  const inspected = await inspectImageProvider({ endpoint, apiKey, fetchImpl });
-  const model = await chooseModel(inspected.modelIds, current?.model, ask, output);
+  let model;
+  const inspected = await inspectImageProvider({
+    endpoint, apiKey, fetchImpl,
+    selectModel: async (modelIds) => {
+      model = await chooseModel(modelIds, current?.model, ask, output);
+      return model;
+    },
+  });
   const result = enableImageProvider({
     providerConfig: {
       endpoint: inspected.endpoint,

package/src/cli-options.mjs

@@ -301,7 +301,7 @@ function topicHelp(name, topic) {
     status: `Usage:\n  ${name} status\n\nShows bounded runtime, routing, performance, queue, and cache metrics from a running adapter.`,
     models: `Usage:\n  ${name} models [--format table|plain]\n\nPerforms a fresh, read-only Copilot model-directory lookup for the saved account. Interactive terminals use a table by default.`,
     usage: `Usage:\n  ${name} usage [--format table|plain]\n\nSummarizes local token usage metadata without reading prompt or completion content. Interactive terminals use a table by default.`,
-    animation: `Usage:\n  ${name} animation\n\nInteractively selects the terminal activity animation used the next time the adapter starts.`,
+    animation: `Usage:\n  ${name} animation\n\nPreviews all terminal activity animations together and selects the theme used the next time the adapter starts.`,
     "enable-image": `Usage:\n  ${name} enable-image\n\nInteractively configures an HTTPS image API endpoint and API key, detects its supported image model and protocol, installs CCDX image guidance, and checks the local image tool for Codex App without generating an image.`,
     "disable-image": `Usage:\n  ${name} disable-image\n\nDisables the local CCDX image tool and removes its stored API credential and unmodified CCDX image guidance.`,
     "image-status": `Usage:\n  ${name} image-status\n\nShows provider configuration and probes local image-tool readiness without generating an image or exposing its API key.`,

package/src/codex-config-doctor.mjs

@@ -51,9 +51,14 @@ function unmanagedSettings(config) {
 }
 
 function startupPreview(content, config, host, port) {
-  const updated = content === null
-    ? { content: initialCodexConfig(port, host), changed: true }
-    : computeUpdatedCodexConfig(content, port, host);
+  let updated;
+  try {
+    updated = content === null
+      ? { content: initialCodexConfig(port, host), changed: true }
+      : computeUpdatedCodexConfig(content, port, host);
+  } catch {
+    return { kind: "err", message: "Startup configuration cannot be edited safely; review the file before starting ccdx" };
+  }
   if (!updated.changed) return { kind: "ok", message: "No startup configuration changes required" };
   let next;
   try {

package/src/config-toml.mjs

@@ -0,0 +1,147 @@
+import { isDeepStrictEqual } from "node:util";
+import { parse } from "smol-toml";
+
+export function parseCodexToml(content) {
+  try {
+    return parse(content, { integersAsBigInt: true });
+  } catch {
+    // TOML parser errors include source snippets, which may contain credentials.
+    throw new Error("Codex configuration is not valid TOML; no configuration changes were written");
+  }
+}
+
+export function configValue(config, keys) {
+  return keys.reduce((value, key) => (
+    value && Object.hasOwn(value, key) ? value[key] : undefined
+  ), config);
+}
+
+function keyParts(source) {
+  let value = parseCodexToml(`${source} = 0`);
+  const keys = [];
+  while (value && typeof value === "object") {
+    const [key] = Object.keys(value);
+    keys.push(key);
+    value = value[key];
+  }
+  return keys;
+}
+
+// Locate complete declarations without interpreting value syntax. The TOML parser
+// remains authoritative; this scanner only supplies spans for surgical edits.
+export function codexTomlStatements(content) {
+  const statements = [];
+  let section = [];
+  let offset = 0;
+  let line = 0;
+  while (offset < content.length) {
+    const char = content[offset];
+    if (/\s/.test(char)) {
+      if (char === "\n") line += 1;
+      offset += 1;
+      continue;
+    }
+    const start = offset;
+    const startLine = line;
+    if (char === "#" || char === "[") {
+      const end = content.indexOf("\n", offset);
+      offset = end < 0 ? content.length : end;
+      const source = content.slice(start, offset).trimEnd();
+      if (char === "#") statements.push({ kind: "comment", start, end: offset, line: startLine, source });
+      else {
+        const brackets = source.startsWith("[[") ? 2 : 1;
+        let quote = "";
+        let close = brackets;
+        for (; close < source.length; close += 1) {
+          const next = source[close];
+          if (quote === '"' && next === "\\") { close += 1; continue; }
+          if (quote) { if (next === quote) quote = ""; continue; }
+          if (next === '"' || next === "'") quote = next;
+          else if (next === "]") break;
+        }
+        section = keyParts(source.slice(brackets, close));
+        statements.push({ kind: "table", keys: section, start, end: offset, line: startLine });
+      }
+      continue;
+    }
+
+    let quote = "";
+    for (; offset < content.length; offset += 1) {
+      const next = content[offset];
+      if (quote === '"' && next === "\\") { offset += 1; continue; }
+      if (quote) { if (next === quote) quote = ""; continue; }
+      if (next === '"' || next === "'") quote = next;
+      else if (next === "=") break;
+    }
+    const keys = [...section, ...keyParts(content.slice(start, offset).trim())];
+    offset += 1;
+    while (content[offset] === " " || content[offset] === "\t") offset += 1;
+    const valueStart = offset;
+    let depth = 0;
+    let multiline = false;
+    for (; offset < content.length; offset += 1) {
+      const next = content[offset];
+      if (next === "\n") line += 1;
+      if (quote) {
+        if (quote === '"' && next === "\\") {
+          if (content[offset + 1] === "\n") line += 1;
+          offset += 1;
+        } else if (next === quote) {
+          if (!multiline) quote = "";
+          else if (content.startsWith(quote.repeat(3), offset)) {
+            while (content[offset + 1] === quote) offset += 1;
+            quote = "";
+          }
+        }
+        continue;
+      }
+      if (next === '"' || next === "'") {
+        quote = next;
+        multiline = content.startsWith(next.repeat(3), offset);
+        if (multiline) offset += 2;
+      } else if (next === "[" || next === "{") depth += 1;
+      else if (next === "]" || next === "}") depth -= 1;
+      else if (next === "#") {
+        if (depth === 0) break;
+        const end = content.indexOf("\n", offset);
+        offset = end < 0 ? content.length : end - 1;
+      } else if (next === "\n" && depth === 0) {
+        line -= 1;
+        break;
+      }
+    }
+    const valueEnd = valueStart + content.slice(valueStart, offset).trimEnd().length;
+    statements.push({ kind: "value", keys, section, start, end: offset, line: startLine, valueStart, valueEnd });
+  }
+  return statements;
+}
+
+function omitManaged(config, paths) {
+  const result = structuredClone(config);
+  for (const keys of paths) {
+    const parents = [];
+    let value = result;
+    for (const key of keys) {
+      if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, key)) break;
+      parents.push([value, key]);
+      value = value[key];
+    }
+    if (parents.length === keys.length) {
+      const [parent, leaf] = parents.pop();
+      delete parent[leaf];
+    }
+    while (parents.length) {
+      const [owner, key] = parents.pop();
+      if (!owner[key] || typeof owner[key] !== "object" || Array.isArray(owner[key]) || Object.keys(owner[key]).length) break;
+      delete owner[key];
+    }
+  }
+  return result;
+}
+
+export function validateManagedConfigEdit(before, content, managedPaths) {
+  const after = parseCodexToml(content);
+  if (!isDeepStrictEqual(omitManaged(before, managedPaths), omitManaged(after, managedPaths))) {
+    throw new Error("Unsafe Codex configuration edit outside CCDX's managed keys; no configuration changes were written");
+  }
+}

package/src/config.mjs

@@ -4,6 +4,7 @@ import os from "node:os";
 import { status } from "./status.mjs";
 import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
 import { adapterBaseUrl } from "./running-adapter.mjs";
+import { codexTomlStatements, configValue, parseCodexToml, validateManagedConfigEdit } from "./config-toml.mjs";
 
 const CONFIG_PATH = path.join(os.homedir(), ".codex", "config.toml");
 const MODEL_CONTEXT_WINDOW = 1_000_000;
@@ -11,99 +12,75 @@ const MODEL_AUTO_COMPACT_TOKEN_LIMIT = 900_000;
 const IMAGE_MCP_START = "# ccdx:image-mcp:start";
 const IMAGE_MCP_END = "# ccdx:image-mcp:end";
 const IMAGE_MCP_SECTION = "mcp_servers.ccdx_image";
+const STARTUP_MANAGED_PATHS = [
+  "openai_base_url",
+  "model_context_window",
+  "model_auto_compact_token_limit",
+  "shell_environment_policy.set.OPENAI_BASE_URL",
+  "shell_environment_policy.set.OPENAI_API_KEY",
+  "features.context_management",
+].map((key) => key.split("."));
+const IMAGE_MANAGED_PATH = ["mcp_servers", "ccdx_image"];
+
+function sameKeys(left, right) {
+  return left.length === right.length && left.every((key, index) => key === right[index]);
+}
 
-function isTomlTableHeader(line) {
-  const source = line.trimStart();
-  const openingBrackets = source.startsWith("[[") ? 2 : source.startsWith("[") ? 1 : 0;
-  if (!openingBrackets) return false;
-
-  let quote = "";
-  let escaped = false;
-  for (let index = openingBrackets; index < source.length; index += 1) {
-    const char = source[index];
-    if (quote) {
-      if (quote === '"' && char === "\\" && !escaped) {
-        escaped = true;
-        continue;
-      }
-      if (char === quote && !escaped) quote = "";
-      escaped = false;
-      continue;
-    }
-    if (char === '"' || char === "'") {
-      quote = char;
-      continue;
-    }
-    if (char !== "]" || (openingBrackets === 2 && source[index + 1] !== "]")) continue;
-
-    if (!source.slice(openingBrackets, index).trim()) return false;
-    const tail = source.slice(index + openingBrackets).trim();
-    return tail === "" || tail.startsWith("#");
-  }
-  return false;
+function setExistingTomlValue(lines, keys, value) {
+  const content = lines.join("\n");
+  if (configValue(parseCodexToml(content), keys) === value) return false;
+  const entry = codexTomlStatements(content).find((item) => item.kind === "value" && sameKeys(item.keys, keys));
+  if (!entry) return false;
+  const updated = content.slice(0, entry.valueStart) + JSON.stringify(value) + content.slice(entry.valueEnd);
+  lines.splice(0, lines.length, ...updated.split("\n"));
+  return true;
 }
 
 function setTopLevelTomlDefault(lines, key, value) {
-  let end = lines.findIndex(isTomlTableHeader);
-  if (end === -1) end = lines.length;
-
-  const keyRe = new RegExp(`^\\s*${key}\\s*=`);
-  if (lines.slice(0, end).some((line) => keyRe.test(line))) return false;
-
+  const content = lines.join("\n");
+  if (Object.hasOwn(parseCodexToml(content), key)) return false;
+  let end = codexTomlStatements(content).find((item) => item.kind === "table")?.line ?? lines.length;
   while (end > 0 && lines[end - 1].trim() === "") end--;
   lines.splice(end, 0, `${key} = ${value}`);
   return true;
 }
 
 function setTomlKey(lines, sectionName, key, value) {
-  const sectionLine = `[${sectionName}]`;
-  const start = lines.findIndex((line) => line.trim() === sectionLine);
-  if (start === -1) return false;
-
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i++) {
-    if (isTomlTableHeader(lines[i])) {
-      end = i;
-      break;
-    }
+  const keys = [...sectionName.split("."), key];
+  const content = lines.join("\n");
+  if (configValue(parseCodexToml(content), keys) !== undefined) {
+    return setExistingTomlValue(lines, keys, value);
   }
-
-  const nextLine = `${key} = "${value}"`;
-  const keyRe = new RegExp(`^\\s*${key}\\s*=`);
-  for (let i = start + 1; i < end; i++) {
-    if (keyRe.test(lines[i])) {
-      const changed = lines[i] !== nextLine;
-      lines[i] = nextLine;
-      return changed;
-    }
-  }
-
-  lines.splice(end, 0, nextLine);
+  const statements = codexTomlStatements(content);
+  const parent = keys.slice(0, -1);
+  const table = statements.find((item) => item.kind === "table" && sameKeys(item.keys, parent));
+  const dotted = statements.find((item) => item.kind === "value"
+    && item.keys.length > parent.length && sameKeys(item.keys.slice(0, parent.length), parent));
+  const anchor = table || dotted;
+  // Preserve absent and inline environment tables; only edit declarations whose
+  // exact value or insertion scope can be identified without rewriting them.
+  if (!anchor) return false;
+  const scope = table ? table.keys : dotted.section;
+  const nextKey = keys.slice(scope.length).join(".");
+  const end = statements.find((item) => item.kind === "table" && item.start > anchor.start)?.line ?? lines.length;
+  lines.splice(end, 0, `${nextKey} = ${JSON.stringify(value)}`);
   return true;
 }
 
 function ensureContextManagementDefault(lines) {
-  const firstSection = lines.findIndex(isTomlTableHeader);
-  const topLevel = lines.slice(0, firstSection === -1 ? lines.length : firstSection);
-  // Preserve alternative existing TOML declarations rather than creating a
-  // conflicting table or replacing a structured context-management value.
-  if (topLevel.some((line) => /^\s*(?:features|"features"|'features')\s*(?:=|\.)/.test(line))
-    || lines.some((line) => /^\s*\[\s*(?:features|"features"|'features')\s*\.\s*(?:context_management|"context_management"|'context_management')\s*(?:\.|\])/.test(line))) {
-    return false;
-  }
-  const start = lines.findIndex((line) => /^\s*\[\s*(?:features|"features"|'features')\s*\]\s*(?:#.*)?$/.test(line));
-  if (start === -1) {
+  const content = lines.join("\n");
+  const config = parseCodexToml(content);
+  if (configValue(config, ["features", "context_management"]) !== undefined) return false;
+  const statements = codexTomlStatements(content);
+  const table = statements.find((item) => item.kind === "table" && sameKeys(item.keys, ["features"]));
+  if (!table) {
+    if (Object.hasOwn(config, "features")) return false;
     if (lines.length && lines.at(-1).trim() !== "") lines.push("");
     lines.push("[features]", "context_management = true");
     return true;
   }
-
-  let end = start + 1;
-  while (end < lines.length && !isTomlTableHeader(lines[end])) end += 1;
-  if (lines.slice(start + 1, end).some((line) => /^\s*(?:context_management|"context_management"|'context_management')\s*(?:=|\.)/.test(line))) {
-    return false;
-  }
-  while (end > start + 1 && lines[end - 1].trim() === "") end -= 1;
+  let end = statements.find((item) => item.kind === "table" && item.start > table.start)?.line ?? lines.length;
+  while (end > table.line + 1 && lines[end - 1].trim() === "") end -= 1;
   lines.splice(end, 0, "context_management = true");
   return true;
 }
@@ -116,8 +93,9 @@ function imageMcpHost(adapterHost) {
 }
 
 function removeManagedImageMcp(lines) {
-  const starts = lines.flatMap((line, index) => line === IMAGE_MCP_START ? [index] : []);
-  const ends = lines.flatMap((line, index) => line === IMAGE_MCP_END ? [index] : []);
+  const comments = codexTomlStatements(lines.join("\n")).filter((item) => item.kind === "comment");
+  const starts = comments.filter((item) => lines[item.line] === IMAGE_MCP_START).map((item) => item.line);
+  const ends = comments.filter((item) => lines[item.line] === IMAGE_MCP_END).map((item) => item.line);
   let start = starts[0] ?? -1;
   const end = ends[0] ?? -1;
   if (start === -1 && end === -1) return false;
@@ -136,7 +114,7 @@ function removeManagedImageMcp(lines) {
 }
 
 function hasUnmanagedImageMcp(lines) {
-  return lines.some((line) => line.trim() === `[${IMAGE_MCP_SECTION}]`);
+  return configValue(parseCodexToml(lines.join("\n")), IMAGE_MANAGED_PATH) !== undefined;
 }
 
 function ensureImageMcp(lines, enabled, adapterPort, adapterHost) {
@@ -167,6 +145,7 @@ export function computeUpdatedCodexConfig(
   adapterHost = "127.0.0.1",
   { imageProviderEnabled } = {},
 ) {
+  const config = parseCodexToml(content);
   const baseUrl = `${adapterBaseUrl(adapterHost, adapterPort)}/v1`;
   const hadTrailingNewline = content.endsWith("\n");
   const lines = content.split("\n");
@@ -174,17 +153,11 @@ export function computeUpdatedCodexConfig(
 
   let changed = false;
   const openaiLine = `openai_base_url = "${baseUrl}"`;
-  const firstSection = lines.findIndex(isTomlTableHeader);
-  const topLevelEnd = firstSection === -1 ? lines.length : firstSection;
-  const openaiIndex = lines.findIndex((line, index) => (
-    index < topLevelEnd && /^\s*openai_base_url\s*=/.test(line)
-  ));
-  if (openaiIndex === -1) {
+  if (!Object.hasOwn(config, "openai_base_url")) {
     lines.unshift(openaiLine);
     changed = true;
-  } else if (lines[openaiIndex] !== openaiLine) {
-    lines[openaiIndex] = openaiLine;
-    changed = true;
+  } else {
+    changed = setExistingTomlValue(lines, ["openai_base_url"], baseUrl);
   }
 
   changed = setTopLevelTomlDefault(lines, "model_context_window", MODEL_CONTEXT_WINDOW) || changed;
@@ -196,7 +169,10 @@ export function computeUpdatedCodexConfig(
     changed = ensureImageMcp(lines, imageProviderEnabled, adapterPort, adapterHost) || changed;
   }
 
-  return { content: lines.join("\n") + (hadTrailingNewline ? "\n" : ""), changed };
+  const updated = lines.join("\n") + (hadTrailingNewline ? "\n" : "");
+  validateManagedConfigEdit(config, updated, typeof imageProviderEnabled === "boolean"
+    ? [...STARTUP_MANAGED_PATHS, IMAGE_MANAGED_PATH] : STARTUP_MANAGED_PATHS);
+  return { content: updated, changed };
 }
 
 export function initialCodexConfig(adapterPort, adapterHost, { imageProviderEnabled = false } = {}) {
@@ -224,11 +200,14 @@ export function computeImageMcpCodexConfig(
   content,
   { enabled, adapterPort = 2026, adapterHost = "127.0.0.1" } = {},
 ) {
+  const config = parseCodexToml(content);
   const hadTrailingNewline = content.endsWith("\n");
   const lines = content.split("\n");
   if (hadTrailingNewline) lines.pop();
   const changed = ensureImageMcp(lines, Boolean(enabled), adapterPort, adapterHost);
-  return { content: lines.join("\n") + (hadTrailingNewline || lines.length ? "\n" : ""), changed };
+  const updated = lines.join("\n") + (hadTrailingNewline || lines.length ? "\n" : "");
+  validateManagedConfigEdit(config, updated, [IMAGE_MANAGED_PATH]);
+  return { content: updated, changed };
 }
 
 export function ensureCodexConfig(adapterPort = 2026, {
@@ -245,7 +224,13 @@ export function ensureCodexConfig(adapterPort = 2026, {
     return;
   }
 
-  const content = fs.readFileSync(filePath, "utf-8");
+  let content;
+  try {
+    content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(filePath));
+  } catch (error) {
+    if (error?.code !== "ERR_ENCODING_INVALID_ENCODED_DATA") throw error;
+    throw new Error("Codex configuration is not valid UTF-8 TOML; no configuration changes were written");
+  }
   const updated = computeUpdatedCodexConfig(content, adapterPort, host, { imageProviderEnabled });
 
   if (!updated.changed) {

package/src/copilot-responses-compat.mjs

@@ -33,6 +33,10 @@ const RETRY_POLICIES = Object.freeze([
   }),
 ]);
 
+export function hasCopilotResponseRetryPolicy(statusCode, errorText, usedPolicies = new Set()) {
+  return RETRY_POLICIES.some((policy) => !usedPolicies.has(policy.id) && policy.matches(statusCode, errorText));
+}
+
 export function selectCopilotResponseRetry(
   reqContext,
   statusCode,