@bitkyc08/opencodex 2.82.0 → 2.84.0

package/src/codex/catalog/provider-models.ts

@@ -1,3 +1,6 @@
+import { fetchCopilotAutoModels, copilotPickerModels, copilotRequiresAuto } from "../../providers/github-copilot-auto";
+import { resolveGithubCopilotTransport } from "../../providers/github-copilot-transport";
+import { resolveCopilotApiBaseUrl } from "../../oauth/github-copilot";
 import { isAnthropicOAuthInstance } from "../../providers/anthropic-instance";
 import { effectiveProviderAlias, effectiveProviderAliasDecision } from "../../providers/default-aliases";
 import { initialModelSelectionPending } from "../../providers/initial-model-selection";
@@ -164,6 +167,7 @@ export function observedModelsAuthResolver(
     },
   };
 }
+/** Project captured discovery through config hints and retention; Auto-only Copilot exposes only Auto. */
 export async function fetchProviderModelsWithAuth(
   captured: CapturedProviderGather,
   ttlMs: number,
@@ -282,6 +286,27 @@ export async function fetchProviderModelsWithAuth(
       : { apiKey: await resolveModelsAuthToken(name, prov), observed: false }
     : resolveAuth.resolve(name, prov));
   const apiKey = auth.apiKey;
+  if (name === "github-copilot" && apiKey) {
+    const transport = resolveGithubCopilotTransport({ ...prov, apiKey }, prov.authMode === "oauth"
+      ? resolveCopilotApiBaseUrl(auth.oauthApiBaseUrl) : undefined);
+    try {
+      const models = await fetchCopilotAutoModels(transport, AbortSignal.timeout(8_000), undefined, ttlMs);
+      const picker = copilotPickerModels(prov, models).map(/** Apply configured hints to the permission-filtered account catalog without changing upstream metadata. */
+        model => applyProviderConfigHints(name, prov, {
+        id: model.id, provider: name,
+        ...catalogHintsFromModelsApiItem(name, model as ProviderModelsApiItem),
+      }, contextCap, metadataModelIdCaseFold, captured.effectiveAlias));
+      if (!isCurrentCacheGeneration()) return observed(configured, "degraded");
+      markProviderDiscoveryOk(name, picker.length);
+      // Retain callable manual/combo selectors, but do not advertise named selection
+      // for an Auto-only account even when its saved configuration still contains it.
+      return observed(copilotRequiresAuto(prov, models)
+        ? picker : withConfiguredRetention(picker, { warnDrops: true }), "authoritative");
+    } catch {
+      if (isCurrentCacheGeneration()) markProviderDiscoveryFailed(name, { reason: "provider" });
+      return observed(configured, "degraded");
+    }
+  }
   const maySendAnthropicDiscovery = () => {
     if (!isAnthropicOAuthInstance(name) || prov.authMode !== "oauth") return true;
     if (!mayResolveModelsOAuth(name, prov)) return false;

package/src/codex/desktop-app/darwin.ts

@@ -1,7 +1,7 @@
 /**
  * macOS adapter for the Codex desktop-app restart.
  *
- * Measured shape (devlog/_plan/260913_cross_platform_desktop_app_restart/001_platform_topology.md):
+ * Measured shape (devlog/_fin/260913_cross_platform_desktop_app_restart/001_platform_topology.md):
  *
  *   15901     1  /Applications/ChatGPT.app/Contents/MacOS/ChatGPT
  *   16733 15901  /Applications/ChatGPT.app/Contents/Resources/codex ... app-server ...

package/src/codex/desktop-app/handoff.ts

@@ -23,7 +23,7 @@
  *   it passes `allowHandoff: false` so it can only ever take the direct path or refuse.
  *   Recursion is structurally impossible rather than merely unlikely.
  *
- * Design: devlog/_plan/260913_cross_platform_desktop_app_restart/020_phase2_detached_self_handoff.md
+ * Design: devlog/_fin/260913_cross_platform_desktop_app_restart/020_phase2_detached_self_handoff.md
  */
 import { spawn } from "node:child_process";
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";

package/src/codex/desktop-app/linux.ts

@@ -1,7 +1,7 @@
 /**
  * Linux adapter for the Codex desktop-app restart.
  *
- * Measured shape (devlog/_plan/260913_cross_platform_desktop_app_restart/001_platform_topology.md):
+ * Measured shape (devlog/_fin/260913_cross_platform_desktop_app_restart/001_platform_topology.md):
  *
  *   /usr/bin/chatgpt -> /usr/lib/chatgpt/codex-launcher  (2-line sh script)
  *   that execs /usr/lib/chatgpt/ChatGPT

package/src/codex/desktop-app/lock.ts

@@ -22,7 +22,7 @@
  *   itself. An unconditional unlink would let a late release destroy somebody else's
  *   live lock, which is exactly the mutual exclusion this file exists to provide.
  *
- * Design: `devlog/_plan/260913_cross_platform_desktop_app_restart/020_phase2_detached_self_handoff.md` §4.1.
+ * Design: `devlog/_fin/260913_cross_platform_desktop_app_restart/020_phase2_detached_self_handoff.md` §4.1.
  */
 import { mkdirSync, openSync, closeSync, writeSync, readFileSync, unlinkSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";

package/src/codex/desktop-app/types.ts

@@ -7,7 +7,7 @@
  * PID-reuse and fail-closed reasoning from being re-derived three times, once per
  * operating system, with two of the three getting it subtly wrong.
  *
- * Design and audit history: `devlog/_plan/260913_cross_platform_desktop_app_restart/`.
+ * Design and audit history: `devlog/_fin/260913_cross_platform_desktop_app_restart/`.
  */
 import { sep } from "node:path";
 

package/src/codex/desktop-app/windows.ts

@@ -7,7 +7,7 @@
  * AUMID. The shape is DesktopAppAdapter so the ladder, not this file, owns
  * PID-reuse re-verification and the fail-closed sequencing.
  *
- * Measured (devlog/_plan/260913_cross_platform_desktop_app_restart/001_platform_topology.md §3):
+ * Measured (devlog/_fin/260913_cross_platform_desktop_app_restart/001_platform_topology.md §3):
  * OpenAI.Codex MSIX, ChatGPT.exe, InstallLocation under WindowsApps.
  */
 import { execFileSync } from "node:child_process";

package/src/codex/desktop-app-restart.ts

@@ -29,7 +29,7 @@
  * never reported as "nothing to do". A stale picker is a much smaller problem than a
  * wrongly killed process.
  *
- * Design and audit history: devlog/_plan/260913_cross_platform_desktop_app_restart/.
+ * Design and audit history: devlog/_fin/260913_cross_platform_desktop_app_restart/.
  */
 import {
   acquireDesktopRestartLock,

package/src/codex/main-account.ts

@@ -510,8 +510,9 @@ async function resolveMainAccountToken(
         }
         const refresh = dependencies.refreshToken ?? refreshNativeMainGrant;
         let refreshed: OAuthCredentials;
+        if (signal.aborted) throw signal.reason;
         try {
-          refreshed = await refresh(locked.refreshToken, { signal });
+          refreshed = await refresh(locked.refreshToken, { signal: refreshTimeout });
         } catch (cause) {
           // A refusal already classified at the endpoint keeps that verdict. An injected refresh
           // threw an ordinary Error and has only its message, so prose still decides there --
@@ -535,16 +536,14 @@ async function resolveMainAccountToken(
           }
           throw new MainAccountTokenRefreshError(reason, { cause });
         }
-        // The refresh may resolve after the caller went away (an implementation that does
-        // not observe the signal, or an abort landing in the window between resolution and
-        // commit). A cancelled request's late refresh must not rewrite auth.json on behalf
-        // of a request that no longer exists -- the same fence the reauth twin applies
-        // before its own commit above.
-        if (dependencies.signal?.aborted) throw dependencies.signal.reason;
+        // Once the exchange starts, only its own timeout may abort it: a successful
+        // rotating grant retires the old refresh token. Save the only live grant before
+        // honoring caller cancellation, while retaining the external-writer guards.
         const result = persistRefreshedMainAuthJson(locked, refreshed);
         // A permitted in-flight success speaks only for its own profile and grant.
         clearMainRefreshGrantRejection(mainRefreshGrantKey(locked)!);
         if (dependencies.preserveReauth !== true) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+        if (dependencies.signal?.aborted) throw dependencies.signal.reason;
         return result;
       }),
       { waitMs: 30_000, signal },

package/src/codex/native-profile-startup.ts

@@ -20,6 +20,7 @@ import { withNativeMainExclusiveClaim } from "./native-main-claim";
 import { scrubNativeMainAuthTempResidues } from "./native-main-auth-temp";
 import { NATIVE_STAGE_SWEEP_INTERVAL_MS } from "./native-profile-stage-store";
 import type { NativeCodexOwnership } from "../integrations/native/ownership-preflight";
+import { isPassiveRead } from "../lib/passive-read";
 
 export type NativeMainStartupGateSnapshot =
   | { status: "ready"; homeId: string | null }
@@ -701,7 +702,9 @@ export async function releaseNativeMainStartupLifecycle(server: object): Promise
 
 export function isNativeMainTrafficBlocked(): boolean {
   const reason = activeServiceOwnershipBlockReason();
-  if (reason !== null && reprobeServiceOwnership(reason)) {
+  // A passive read (a Remote Link Child's, #6959) reports the gate as it stands: re-inspecting
+  // service ownership can activate the native-main lifecycle and its recovery on this machine.
+  if (reason !== null && !isPassiveRead() && reprobeServiceOwnership(reason)) {
     // The host became ownable after boot (#2108): the fence lifts here rather than
     // waiting for the restart the reporter had to perform by hand.
     return activeServiceOwnershipBlockReason() !== null || snapshot.status === "blocked";

package/src/codex/prompt-journal.ts

@@ -318,7 +318,7 @@ export function recoverIfNeeded(
       };
     }
     try {
-      publishConfigWrite(expectedTargets.configPath, held, (destination, hooks) => restore(destination, record.preConfigBytes, hooks));
+      publishConfigWrite(expectedTargets.configPath, held, (destination, hooks) => restore(destination, record.preConfigBytes, expectingImage(hooks, record.postConfig)));
     } catch (error) {
       return {
         ok: false,
@@ -336,7 +336,7 @@ export function recoverIfNeeded(
       };
     }
     try {
-      publishConfigWriteTarget(expectedTargets.configPath, held, expectedTargets.storePath, (destination, hooks) => restore(destination, record.preStoreBytes, hooks));
+      publishConfigWriteTarget(expectedTargets.configPath, held, expectedTargets.storePath, (destination, hooks) => restore(destination, record.preStoreBytes, expectingImage(hooks, record.postStore)));
     } catch (error) {
       return {
         ok: false,
@@ -363,3 +363,21 @@ function restore(path: string, bytes: string | null, hooks: AtomicWriteHooks): v
   if (bytes === null) durableDelete(path, hooks);
   else durableWrite(path, bytes, hooks);
 }
+
+/**
+ * Bind a write to the image the caller classified. The rename retry hooks check
+ * path and inode identity only; an in-place edit by another process during a
+ * Windows sharing-violation retry keeps the inode, so without this re-read a
+ * later attempt would replace newer bytes. Checked before every attempt.
+ */
+export function expectingImage(hooks: AtomicWriteHooks, expectedHash: string): AtomicWriteHooks {
+  return {
+    ...hooks,
+    validateBeforeRename: (targetPath: string) => {
+      hooks.validateBeforeRename?.(targetPath);
+      if (hashBytes(readOrNull(targetPath)) !== expectedHash) {
+        throw new Error(targetPath + " changed during the write; refusing to overwrite it. Files and recovery evidence were preserved.");
+      }
+    },
+  };
+}

package/src/codex/prompt-layers/encoding.ts

@@ -119,3 +119,52 @@ export function decodeTomlBasicString(literal: string): string | null {
   }
   return out;
 }
+
+/** Shared scalar assignment matching; quoted and escaped keys retain their spelling. */
+export function matchKeyHead(line: string, key: string): { prefix: string; rest: string } | null {
+  const m = /^\s*("(?:[^"\\]|\\.)*"|'[^']*'|[A-Za-z0-9_-]+)\s*=\s*/.exec(line);
+  if (!m) return null;
+  const token = m[1]!;
+  const decoded = token.startsWith('"') ? decodeTomlBasicString(token)
+    : token.startsWith("'") ? token.slice(1, -1) : token;
+  return decoded === key ? { prefix: m[0], rest: line.slice(m[0].length) } : null;
+}
+
+/**
+ * For each line, whether it begins outside every string and composite span, or
+ * `null` when a span never closes and the scope of later lines is unknown.
+ *
+ * Line matchers for assignments and table headers must only look at lines that
+ * start at top level: `"model_instructions_file" = "x"` written inside a
+ * `"""…"""` value or a multi-line array is prose, not syntax. Readers and
+ * editors share this so a write and the snapshot read back agree.
+ */
+export function lexicalLineStarts(lines: readonly string[]): boolean[] | null {
+  const starts: boolean[] = [];
+  let open: string | null = null;
+  let depth = 0;
+  for (const line of lines) {
+    starts.push(open === null && depth === 0);
+    for (let i = 0; i < line.length; i += 1) {
+      const char = line[i]!;
+      if (open !== null) {
+        if (char === "\\" && (open === '"' || open === '"""')) { i += 1; continue; }
+        if (char !== open[0]) continue;
+        if (open.length === 1) { open = null; continue; }
+        let run = 0;
+        while (line[i + run] === char) run += 1;
+        // Up to two quotes may sit inside the value just before the closing three.
+        if (run >= 3) open = null;
+        i += run - 1;
+      } else if (char === "#") break;
+      else if (char === '"' || char === "'") {
+        open = line.startsWith(char.repeat(3), i) ? char.repeat(3) : char;
+        i += open.length - 1;
+      } else if (char === "[" || char === "{") depth += 1;
+      else if (char === "]" || char === "}") { depth -= 1; if (depth < 0) return null; }
+    }
+    // Single-line strings cannot cross a newline.
+    if (open !== null && open.length === 1) return null;
+  }
+  return open === null && depth === 0 ? starts : null;
+}

package/src/codex/prompt-layers/import-source.ts

@@ -0,0 +1,30 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+
+// CRLF normalization can halve the byte count. Every body within 64 KiB
+// therefore fits this raw ceiling; title bytes stay outside the body budget.
+const MAX_IMPORT_SOURCE_BYTES = 2 * 64 * 1024;
+
+/** The prompt-text-probe descriptor pattern: nonblocking, regular, bounded. */
+export function readBaseImportSource(path: string): string {
+  const nonBlocking = (constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0;
+  const descriptor = openSync(path, constants.O_RDONLY | nonBlocking);
+  try {
+    if (!fstatSync(descriptor).isFile()) throw new Error("prompt source is not a regular file");
+    const parts: Buffer[] = [];
+    const view = Buffer.allocUnsafe(8192);
+    let total = 0;
+    for (;;) {
+      const count = readSync(descriptor, view, 0, Math.min(view.length, MAX_IMPORT_SOURCE_BYTES + 1 - total), total);
+      if (count === 0) return Buffer.concat(parts).toString("utf8");
+      total += count;
+      if (total > MAX_IMPORT_SOURCE_BYTES) {
+        const error = new Error("prompt source exceeds the import byte ceiling") as NodeJS.ErrnoException;
+        error.code = "EFBIG";
+        throw error;
+      }
+      parts.push(Buffer.from(view.subarray(0, count)));
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+}

package/src/codex/prompt-layers/toml-edit.ts

@@ -1,5 +1,5 @@
 import { OCX_SECTION_MARKER } from "../injected-marker";
-import { encodeBasicString } from "./encoding";
+import { encodeBasicString, lexicalLineStarts, matchKeyHead } from "./encoding";
 import { TABLE_HEADER, ANY_DEV_INSTRUCTIONS, DEV_INSTRUCTIONS_KEY } from "./toml-read";
 
 /** Line editing, not re-serialization: the user's comments and layout survive. */
@@ -37,28 +37,156 @@ function joinLines(lines: string[], eol: "\r\n" | "\n"): string {
   return eol === "\n" ? text : text.replace(/\n/g, "\r\n");
 }
 
-function firstTableIndex(lines: string[]): number {
-  const idx = lines.findIndex(l => TABLE_HEADER.test(l));
+function firstTableIndex(lines: string[], starts?: readonly boolean[]): number {
+  const idx = lines.findIndex((l, i) => (starts === undefined || starts[i] === true) && TABLE_HEADER.test(l));
   return idx === -1 ? lines.length : idx;
 }
 
-/** Set a root-scope boolean, inserting above the first table when absent. */
-export function setRootBool(content: string, key: string, value: boolean): string {
+/**
+ * Raised when a recognized `key =` line carries a value a line editor cannot
+ * replace safely — a multi-line `"""…"""`/`'''…'''` span, an unterminated
+ * quote, or trailing junk that is neither value nor comment. Callers refuse
+ * BEFORE writing rather than splice over a span they cannot see the end of.
+ */
+export class UnsupportedTomlForm extends Error {
+  constructor(readonly line: string) {
+    super(`unsupported TOML value form: ${line.trim()}`);
+    this.name = "UnsupportedTomlForm";
+  }
+}
+
+/** Where `<key> =` ends and the value begins. `prefix` keeps indent and key quoting. */
+interface AssignmentHead {
+  prefix: string;
+  rest: string;
+}
+
+/**
+ * Lexical line scope for the editors below (see `lexicalLineStarts`). A span
+ * that never closes means the scope of every later line is unknown, so the
+ * whole edit refuses instead of guessing.
+ */
+function scopedLineStarts(lines: readonly string[]): boolean[] {
+  const starts = lexicalLineStarts(lines);
+  if (starts === null) throw new UnsupportedTomlForm("configuration contains an unterminated string or composite value");
+  return starts;
+}
+
+/**
+ * Split `rest` (everything after `key =`) into the value token and a trailing
+ * `#…` comment — adjacent or whitespace-separated, both preserved.
+ *
+ * The scan is string-aware so a `#` inside a quoted value is never mistaken
+ * for a comment opener: `"a#b" # note` parses as value `"a#b"` + comment
+ * ` # note`, while `false# note` parses as `false` + `# note`. Anything the
+ * token scan cannot classify — a multi-line string opener, an unterminated
+ * quote, text after the value that is not a comment — throws
+ * UnsupportedTomlForm so the caller refuses rather than guesses a span.
+ */
+function splitValueComment(head: AssignmentHead, line: string): { value: string; comment: string } {
+  const { rest } = head;
+  if (rest.startsWith('"""') || rest.startsWith("'''")) throw new UnsupportedTomlForm(line);
+  let value: string;
+  const first = rest[0];
+  if (first === '"') {
+    // Basic string: an escaped quote does not close, an unterminated one refuses.
+    let i = 1;
+    while (i < rest.length && rest[i] !== '"') i += rest[i] === "\\" ? 2 : 1;
+    if (i >= rest.length) throw new UnsupportedTomlForm(line);
+    value = rest.slice(0, i + 1);
+  } else if (first === "'") {
+    // Literal string: no escapes, the next ' closes it.
+    const end = rest.indexOf("'", 1);
+    if (end === -1) throw new UnsupportedTomlForm(line);
+    value = rest.slice(0, end + 1);
+  } else {
+    // Composite values may continue onto another line. This scalar editor
+    // refuses them instead of replacing only their opener and orphaning the tail.
+    if (first === "[" || first === "{") throw new UnsupportedTomlForm(line);
+    const m = /^[^\s#]+/.exec(rest);
+    if (!m) throw new UnsupportedTomlForm(line);
+    value = m[0];
+  }
+  const tail = rest.slice(value.length);
+  if (tail !== "" && !/^\s*(?:#|$)/.test(tail)) throw new UnsupportedTomlForm(line);
+  return { value, comment: tail };
+}
+
+/**
+ * The shape of `key`'s root-scope assignment, or "absent". "unsupported" means
+ * a `key =` line was found but its value is a form the line editor refuses —
+ * multiline strings and the like — so a caller can fail BEFORE touching disk
+ * instead of inside the transaction.
+ */
+export function rootKeyValueForm(content: string, key: string): "absent" | "simple" | "unsupported" {
+  const { body } = splitBom(content);
+  const lines = splitLines(body);
+  let starts: boolean[];
+  try { starts = scopedLineStarts(lines); } catch { return "unsupported"; }
+  const limit = firstTableIndex(lines, starts);
+  for (let i = 0; i < limit; i += 1) {
+    if (!starts[i]) continue;
+    const head = matchKeyHead(lines[i]!, key);
+    if (!head) continue;
+    try {
+      splitValueComment(head, lines[i]!);
+      return "simple";
+    } catch {
+      return "unsupported";
+    }
+  }
+  return "absent";
+}
+
+/**
+ * Replace or remove one matched line. The line's own indentation, key quoting,
+ * and trailing comment are preserved; `null` removes the assignment but keeps
+ * a comment behind so a `# note` written beside the key survives a reset.
+ */
+function applyLineEdit(lines: string[], i: number, key: string, replacement: string | null): void {
+  const head = matchKeyHead(lines[i]!, key)!;
+  const { comment } = splitValueComment(head, lines[i]!);
+  if (replacement === null) {
+    if (comment.trim()) lines[i] = comment.trim();
+    else lines.splice(i, 1);
+  } else {
+    lines[i] = `${head.prefix}${replacement}${comment}`;
+  }
+}
+
+type EditMode = "inplace" | "appended" | "noop";
+interface LineEdit { text: string; mode: EditMode }
+
+/**
+ * Set a root-scope boolean, inserting above the first table when absent.
+ *
+ * `null` REMOVES the key rather than writing a value, which is what restoring a
+ * documented default means: `include_permissions_instructions = true` and an
+ * absent key are different facts about the same file, and only the absent one
+ * lets a changed upstream default ever take effect again.
+ *
+ * The value slot is classified, not just skipped over: any value form the line
+ * editor cannot see the end of — a multi-line string span, an unterminated
+ * quote — throws UnsupportedTomlForm so the write is refused instead of
+ * appending a second assignment TOML would reject as a duplicate key. A value
+ * that is not a boolean is a bad fact about the same key, so it is REPLACED,
+ * and a trailing comment survives a write or a removal whether or not a space
+ * precedes the `#`.
+ */
+function setRootBoolLines(content: string, key: string, value: boolean | null): LineEdit {
   const eol = dominantEol(content);
   const { bom, body } = splitBom(content);
   const lines = splitLines(body);
-  const limit = firstTableIndex(lines);
-  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const pattern = new RegExp(`^(\\s*${escaped}\\s*=\\s*)(?:true|false)(\\s*(?:#.*)?)$`);
+  const starts = scopedLineStarts(lines);
+  const limit = firstTableIndex(lines, starts);
   for (let i = 0; i < limit; i += 1) {
-    const m = pattern.exec(lines[i]!);
-    if (m) {
-      lines[i] = `${m[1]}${value}${m[2]}`;
-      return bom + joinLines(lines, eol);
-    }
+    if (!starts[i] || !matchKeyHead(lines[i]!, key)) continue;
+    applyLineEdit(lines, i, key, value === null ? null : String(value));
+    return { text: bom + joinLines(lines, eol), mode: "inplace" };
   }
+  if (value === null) return { text: bom + joinLines(lines, eol), mode: "noop" };
   lines.splice(limit, 0, `${key} = ${value}`);
-  return bom + joinLines(lines, eol);
+  return { text: bom + joinLines(lines, eol), mode: "appended" };
 }
 
 /**
@@ -68,51 +196,56 @@ export function setRootBool(content: string, key: string, value: boolean): strin
  * rather than an empty string: `model_instructions_file = ""` is a path Codex would try
  * to read, not an absent setting.
  */
-export function setRootString(content: string, key: string, value: string | null): string {
+function setRootStringLines(content: string, key: string, value: string | null): LineEdit {
   const eol = dominantEol(content);
   const { bom, body } = splitBom(content);
   const lines = splitLines(body);
-  const limit = firstTableIndex(lines);
-  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const pattern = new RegExp(`^\\s*${escaped}\\s*=\\s*"[^"]*"\\s*(?:#.*)?$`);
+  const starts = scopedLineStarts(lines);
+  const limit = firstTableIndex(lines, starts);
   for (let i = 0; i < limit; i += 1) {
-    if (!pattern.test(lines[i]!)) continue;
-    if (value === null) lines.splice(i, 1);
-    else lines[i] = `${key} = ${encodeBasicString(value)}`;
-    return bom + joinLines(lines, eol);
+    if (!starts[i] || !matchKeyHead(lines[i]!, key)) continue;
+    applyLineEdit(lines, i, key, value === null ? null : encodeBasicString(value));
+    return { text: bom + joinLines(lines, eol), mode: "inplace" };
   }
-  if (value === null) return bom + joinLines(lines, eol);
+  if (value === null) return { text: bom + joinLines(lines, eol), mode: "noop" };
   lines.splice(limit, 0, `${key} = ${encodeBasicString(value)}`);
-  return bom + joinLines(lines, eol);
+  return { text: bom + joinLines(lines, eol), mode: "appended" };
 }
 
-/** Set a boolean inside `[table]`, appending the table when absent. */
-export function setTableBool(content: string, table: string, key: string, value: boolean): string {
+/**
+ * Set a boolean inside `[table]`, appending the table when absent.
+ *
+ * `null` removes the key line but leaves the table header: an empty `[skills]`
+ * is valid TOML, and deleting the header would also orphan any comments the
+ * user wrote inside the table.
+ */
+function setTableBoolLines(content: string, table: string, key: string, value: boolean | null): LineEdit {
   const eol = dominantEol(content);
   const { bom, body } = splitBom(content);
   const lines = splitLines(body);
+  const starts = scopedLineStarts(lines);
   const escaped = table.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const start = lines.findIndex(l => new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`).test(l));
+  const header = new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`);
+  const start = lines.findIndex((l, i) => starts[i] === true && header.test(l));
   if (start === -1) {
+    if (value === null) return { text: bom + joinLines(lines, eol), mode: "noop" };
     const tail = lines.length > 0 && lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
     lines.splice(tail, 0, `[${table}]`, `${key} = ${value}`);
-    return bom + joinLines(lines, eol);
+    return { text: bom + joinLines(lines, eol), mode: "appended" };
   }
-  const keyEscaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const pattern = new RegExp(`^(\\s*${keyEscaped}\\s*=\\s*)(?:true|false)(\\s*(?:#.*)?)$`);
   let end = start + 1;
-  while (end < lines.length && !TABLE_HEADER.test(lines[end]!)) end += 1;
+  while (end < lines.length && !(starts[end] && TABLE_HEADER.test(lines[end]!))) end += 1;
   for (let i = start + 1; i < end; i += 1) {
-    const m = pattern.exec(lines[i]!);
-    if (m) {
-      lines[i] = `${m[1]}${value}${m[2]}`;
-      return bom + joinLines(lines, eol);
-    }
+    if (!starts[i] || !matchKeyHead(lines[i]!, key)) continue;
+    applyLineEdit(lines, i, key, value === null ? null : String(value));
+    return { text: bom + joinLines(lines, eol), mode: "inplace" };
   }
+  if (value === null) return { text: bom + joinLines(lines, eol), mode: "noop" };
   lines.splice(end, 0, `${key} = ${value}`);
-  return bom + joinLines(lines, eol);
+  return { text: bom + joinLines(lines, eol), mode: "appended" };
 }
 
+
 /**
  * Replace, insert, or remove the generated two-line block. Canonical form is
  * marker + assignment at the top of the document; replacement is "find the
@@ -161,3 +294,102 @@ export function removeUnownedProjection(content: string): string {
   }
   return joinLines(lines, eol);
 }
+
+/**
+ * Refuse, before any write, an edit that does not do exactly what it was asked.
+ *
+ * The line editors above address bare table headers and bare or quoted keys. A
+ * quoted, spaced, inline or dotted spelling of the same table makes them append a
+ * duplicate header (a file Codex cannot load) or, for restore-default, leave the
+ * override in place while the caller reports success. Both are caught by parsing
+ * the before and after images: the parsed result must equal the parsed input with
+ * only the intended path set or removed. When Bun cannot parse the input (its
+ * parser has documented gaps a valid Codex config can hit, such as i64 extremes),
+ * only an in-place replacement of a key the editor located is trusted; an append
+ * or a no-op restore cannot be verified and is refused. A target value with
+ * control characters is checked for presence and type only, for the same reason.
+ */
+function checkedEdit(before: string, edit: LineEdit, path: readonly string[], value: string | boolean | null): string {
+  const after = edit.text;
+  let parsedBefore: Record<string, unknown>;
+  try { parsedBefore = Bun.TOML.parse(before.replace(/^\ufeff/, "")) as Record<string, unknown>; } catch {
+    if (edit.mode === "inplace") return after;
+    throw new UnsupportedTomlForm("config.toml uses syntax this editor cannot verify; edit it by hand");
+  }
+  let parsedAfter: Record<string, unknown>;
+  try { parsedAfter = Bun.TOML.parse(after.replace(/^\ufeff/, "")) as Record<string, unknown>; } catch {
+    throw new UnsupportedTomlForm("edit would leave config.toml unparseable");
+  }
+  try {
+    const expected = tomlClone(parsedBefore) as Record<string, unknown>;
+    let parent: Record<string, unknown> | null = expected;
+    let afterParent: unknown = parsedAfter;
+    for (const segment of path.slice(0, -1)) {
+      const next: unknown = parent?.[segment];
+      afterParent = isPlainTable(afterParent) ? afterParent[segment] : undefined;
+      if (next === undefined) {
+        if (value === null) { parent = null; break; }
+        parent![segment] = {};
+        parent = parent![segment] as Record<string, unknown>;
+        continue;
+      }
+      if (!isPlainTable(next)) throw new UnsupportedTomlForm("edit target is not a plain table");
+      parent = next;
+    }
+    const key = path[path.length - 1]!;
+    if (parent !== null) {
+      if (value === null) delete parent[key];
+      else if (typeof value === "string" && /[\u0000-\u001f\u007f]/.test(value)) {
+        const landed = isPlainTable(afterParent) ? afterParent[key] : undefined;
+        if (typeof landed !== "string") throw new UnsupportedTomlForm("edit did not land on the intended key");
+        parent[key] = landed;
+      } else parent[key] = value;
+    }
+    if (!tomlEqual(parsedAfter, expected)) throw new UnsupportedTomlForm("edit did not land on the intended key");
+  } catch (error) {
+    if (error instanceof UnsupportedTomlForm) throw error;
+    throw new UnsupportedTomlForm("edit could not be verified");
+  }
+  return after;
+}
+
+function isPlainTable(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Arrays and plain tables are copied; TOML date/time values are immutable and shared. */
+function tomlClone(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(tomlClone);
+  if (isPlainTable(value)) return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, tomlClone(v)]));
+  return value;
+}
+
+function tomlEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => tomlEqual(v, b[i]));
+  }
+  if (isPlainTable(a) || isPlainTable(b)) {
+    if (!isPlainTable(a) || !isPlainTable(b)) return false;
+    const ka = Object.keys(a), kb = Object.keys(b);
+    return ka.length === kb.length && ka.every(k => Object.hasOwn(b, k) && tomlEqual(a[k], b[k]));
+  }
+  if (a !== null && b !== null && typeof a === "object" && typeof b === "object") {
+    return Object.getPrototypeOf(a) === Object.getPrototypeOf(b) && String(a) === String(b);
+  }
+  return false;
+}
+
+export function setRootBool(content: string, key: string, value: boolean | null): string {
+  return checkedEdit(content, setRootBoolLines(content, key, value), [key], value);
+}
+
+export function setRootString(content: string, key: string, value: string | null): string {
+  return checkedEdit(content, setRootStringLines(content, key, value), [key], value);
+}
+
+export function setTableBool(content: string, table: string, key: string, value: boolean | null): string {
+  return checkedEdit(content, setTableBoolLines(content, table, key, value), [...table.split("."), key], value);
+}