codex-overleaf-link 2.4.1 → 2.5.1

package/native-host/src/taskRunnerRuntime.js

@@ -2,7 +2,12 @@
 
 const { buildCodexRuntimeEvent } = require('./codexRuntimeIdentity');
 
+const { runOwnedNativeHelper } = require('./nativeHelperLifecycle');
+const { stopCodexAppServer, throwIfAborted } = require('./codexSessionTiming');
 const { spawn } = require('node:child_process');
+const { normalizeSafeProjectPath } = require('../../extension/src/shared/projectFiles');
+const { createHash } = require('node:crypto');
+const NativeRequestIdentity = require('../../extension/src/shared/nativeRequestIdentity');
 const { buildOperationSummary, splitDeletePlan } = require('../../extension/src/shared/summary');
 const {
   MIN_COMPATIBLE_EXTENSION_VERSION,
@@ -10,6 +15,7 @@ const {
   SUPPORTED_NATIVE_PROTOCOL
 } = require('../../extension/src/shared/compatibility');
 const { runCodexSession } = require('./codexSessionRunner');
+const WritingStyleRuntime = require('./writingStyleRuntime');
 const { resolveCodexModels } = require('./codexModels');
 const {
   handleProviderRequest,
@@ -23,7 +29,8 @@ const { forkCodexThread } = require('./codexThreadFork');
 const { readAssetChunk, releaseAsset } = require('./nativeAssetTransfer');
 const { logDebug, truncateText } = require('./debugLog');
 const { HOST_NAME } = require('./manifest');
-const { getNativeRuntimePlatform, summarizeNativeEnvironment } = require('./nativeEnvironment');
+const { getNativeRuntimePlatform, summarizeNativeEnvironment, refreshCodexRuntimeEnv } = require('./nativeEnvironment');
+const { formatModelUpgradeError } = require('./codexModelRecovery');
 const {
   NATIVE_REQUEST_QUOTAS,
   firstQuotaViolation,
@@ -33,6 +40,8 @@ const {
 } = require('./nativeTransportEnvelope');
 const { version: PACKAGE_VERSION } = require('../../package.json');
 
+const processStopBarrier = require('./processStopBarrier');
+const runLifecycle = require('./nativeRunLifecycle');
 const activeProjectLocks = new Map();
 const activeRunControllers = new Map();
 const activeRunEntries = new Map();
@@ -41,7 +50,7 @@ const activeRunEntries = new Map();
 // Overleaf tab was reloaded — the requestId lived in content-side JS state
 // and is gone, but the native-host-side controller is still running).
 const activeRunByProject = new Map();
-const CODEX_RUN_PASSTHROUGH_ERROR_CODES = new Set(['thread_resume_failed', 'codex_no_usable_result']);
+const CODEX_RUN_PASSTHROUGH_ERROR_CODES = new Set(['thread_resume_failed', 'codex_no_usable_result', 'codex_process_stop_unconfirmed', 'selected_context_unresolved', 'codex_local_skill_unavailable']);
 
 async function handleRequest(request, env = process.env, emit = () => {}) {
   if (!request || typeof request !== 'object') {
@@ -53,19 +62,29 @@ async function handleRequest(request, env = process.env, emit = () => {}) {
     return quotaErrorResponse(request.id, quotaError);
   }
 
+  if (['bridge.ping', 'codex.run', 'codex.models', 'codex.thread.fork'].includes(request.method)) {
+    env = refreshCodexRuntimeEnv(env);
+  }
+
   if (request.method === 'bridge.ping') {
     return okResponse(request.id, {
       host: HOST_NAME,
       platform: getNativeRuntimePlatform({ env }),
       protocolVersion: 2,
       supportedProtocol: { ...SUPPORTED_NATIVE_PROTOCOL },
-      capabilities: Object.fromEntries(REQUIRED_CAPABILITIES.map(capability => [capability, true])),
+      capabilities: { ...Object.fromEntries(REQUIRED_CAPABILITIES.map(capability => [capability, true])), literalProjectPaths: true },
       minExtensionVersion: MIN_COMPATIBLE_EXTENSION_VERSION,
       version: PACKAGE_VERSION,
       environment: summarizeNativeEnvironment(env)
     });
   }
 
+  if (['codex.run', 'mirror.sync', 'mirror.patchFiles', 'mirror.confirmWriteback'].includes(request.method)
+    && processStopBarrier.isBlocked(resolveProjectKey(request.params || {}), env.CODEX_OVERLEAF_MIRROR_ROOT)) {
+    return errorResponse(request.id, 'codex_process_stop_unconfirmed',
+      'The previous Codex process has not exited. This project remains isolated until exit is confirmed.');
+  }
+
   if (request.method === 'mirror.sync') {
     return handleMirrorSync(request, env);
   }
@@ -115,7 +134,7 @@ async function handleRequest(request, env = process.env, emit = () => {}) {
   }
 
   if (request.method === 'codex.cancel') {
-    return handleCodexCancel(request);
+    return handleCodexCancel(request, env);
   }
 
   if (request.method === 'codex.history.clearPlugin') {
@@ -142,6 +161,18 @@ async function handleRequest(request, env = process.env, emit = () => {}) {
     return okResponse(request.id, releaseAsset(request.params || {}));
   }
 
+  if (request.method === 'writing-style.get' || request.method === 'writing-style.set') {
+    try {
+      const params = request.params || {};
+      const result = request.method === 'writing-style.get'
+        ? await WritingStyleRuntime.get(params, env, id => activeRunEntries.has(id))
+        : await WritingStyleRuntime.set(params, env);
+      return okResponse(request.id, result);
+    } catch (error) {
+      return errorResponse(request.id, error.code || 'writing_style_failed', error.message);
+    }
+  }
+
   if (request.method === 'skills.list') {
     return handleSkillsList(request, env);
   }
@@ -179,7 +210,22 @@ function quotaErrorResponse(id, violation) {
 }
 
 async function handleCodexRun(request, env, emit) {
+  const identity = NativeRequestIdentity.validate(request.id);
+  if (!identity.ok) return errorResponse(request.id, identity.error.code, identity.error.message, identity.error.details);
   let params = request.params || {};
+  if (params.writingStyleBuild != null) {
+    if (typeof params.writingStyleBuild !== 'object' || Array.isArray(params.writingStyleBuild)) {
+      return errorResponse(request.id, 'writing_style_invalid_build', 'Writing style build settings must be an object.');
+    }
+    params = {
+      ...params,
+      mode: 'ask',
+      useExistingMirror: false,
+      fileOverlays: [],
+      writingStyle: null,
+      writingStyleBuild: { ...params.writingStyleBuild, requestId: String(request.id) }
+    };
+  }
   if (isCodexMissing(env)) {
     return errorResponse(
       request.id,
@@ -198,17 +244,16 @@ async function handleCodexRun(request, env, emit) {
     return errorResponse(request.id, 'project_locked', `Project ${projectKey} is currently in use by codex.run`);
   }
   const abortController = new AbortController();
+  const lifetime = runLifecycle.register({ controller: abortController, projectKey, rootDir: env.CODEX_OVERLEAF_MIRROR_ROOT });
   const activeEntry = {
-    id: request.id || '',
+    id: request.id,
     projectKey,
     controller: abortController,
     control: null
   };
-  if (request.id) {
-    activeRunControllers.set(request.id, abortController);
-    activeRunEntries.set(request.id, activeEntry);
-    activeRunByProject.set(projectKey, activeEntry);
-  }
+  activeRunControllers.set(request.id, abortController);
+  activeRunEntries.set(request.id, activeEntry);
+  activeRunByProject.set(projectKey, activeEntry);
   let providerResolution;
   try {
     try {
@@ -226,6 +271,7 @@ async function handleCodexRun(request, env, emit) {
       return providerErrorResponse(request.id, error);
     }
 
+    abortController.signal.throwIfAborted();
     if (params.useExistingMirror) {
       const { getMirrorStatus, applyFileOverlays } = require('./mirrorWorkspace');
       const rootDir = env.CODEX_OVERLEAF_MIRROR_ROOT;
@@ -250,10 +296,12 @@ async function handleCodexRun(request, env, emit) {
         );
       }
 
-      if (Array.isArray(params.fileOverlays) && params.fileOverlays.length) {
+      // OT overlays prove that the current page agrees with the trusted OT
+      // baseline; they must not rewrite it or supply a replacement hash.
+      if (!isOtWarmMirrorReuseRequest(params) && Array.isArray(params.fileOverlays) && params.fileOverlays.length) {
         await applyFileOverlays({ projectId: projectKey, overlays: params.fileOverlays, rootDir });
       }
-    } else if (!isSnapshotlessSkillInstallerRun(params) && !hasRunnableProjectSnapshotEvidence(params)) {
+    } else if (!params.writingStyleBuild && !isSnapshotlessSkillInstallerRun(params) && !hasRunnableProjectSnapshotEvidence(params)) {
       return errorResponse(
         request.id,
         'codex_run_requires_snapshot_evidence',
@@ -267,6 +315,8 @@ async function handleCodexRun(request, env, emit) {
       emit,
       rootDir: env.CODEX_OVERLEAF_MIRROR_ROOT,
       providerLaunch: providerResolution.providerLaunch,
+      onStopUnconfirmed: error => processStopBarrier.record(projectKey, env.CODEX_OVERLEAF_MIRROR_ROOT, error),
+      onProcessStarted: lifetime.trackProcess,
       onControlReady: control => {
         activeEntry.control = control;
       },
@@ -285,6 +335,13 @@ async function handleCodexRun(request, env, emit) {
       });
       return errorResponse(request.id, 'codex_cancelled', 'Codex run was cancelled by the user');
     }
+    const modelUpgradeError = formatModelUpgradeError(error, env, {
+      model: params.model, locale: params.locale
+    });
+    if (modelUpgradeError) {
+      logDebug('codex.run.model_version_rejected', modelUpgradeError.details);
+      return errorResponse(request.id, modelUpgradeError.code, modelUpgradeError.message, modelUpgradeError.details);
+    }
     if (shouldPassthroughCodexRunError(error)) {
       logDebug('codex.run.passthrough_failed', {
         code: error.code,
@@ -300,16 +357,17 @@ async function handleCodexRun(request, env, emit) {
     });
     return errorResponse(request.id, 'codex_run_failed', truncateText(error.message, 12000));
   } finally {
-    if (request.id && activeRunControllers.get(request.id) === abortController) {
+    if (activeRunControllers.get(request.id) === abortController) {
       activeRunControllers.delete(request.id);
     }
-    if (request.id && activeRunEntries.get(request.id) === activeEntry) {
+    if (activeRunEntries.get(request.id) === activeEntry) {
       activeRunEntries.delete(request.id);
     }
     if (activeRunByProject.get(projectKey)?.controller === abortController) {
       activeRunByProject.delete(projectKey);
     }
     releaseProjectLock(projectKey, lockToken);
+    lifetime.complete();
   }
 }
 
@@ -354,8 +412,8 @@ async function handleCodexSteer(request) {
 }
 
 function findActiveRunEntry(params = {}) {
-  const targetId = String(params.requestId || params.id || '');
-  if (targetId && activeRunEntries.has(targetId)) {
+  const targetId = params.requestId ?? params.id;
+  if (activeRunEntries.has(targetId)) {
     return activeRunEntries.get(targetId);
   }
   const projectKey = String(params.projectKey || '');
@@ -372,13 +430,13 @@ function findActiveRunEntry(params = {}) {
 //      the user otherwise has no way to recover short of restarting Chrome.
 //      Only fires when `force: true` is explicitly set so accidental calls
 //      can't punch through a real live run.
-function handleCodexCancel(request) {
+function handleCodexCancel(request, env = process.env) {
   const params = request.params || {};
-  const targetId = params.requestId || params.id;
+  const targetId = params.requestId ?? params.id;
   const projectKey = typeof params.projectKey === 'string' ? params.projectKey : '';
   const force = params.force === true;
 
-  if (targetId && activeRunControllers.has(targetId)) {
+  if (activeRunControllers.has(targetId)) {
     activeRunControllers.get(targetId).abort(createCancellationError());
     return okResponse(request.id, {
       cancelled: true,
@@ -393,9 +451,13 @@ function handleCodexCancel(request) {
       return okResponse(request.id, {
         cancelled: true,
         projectKey,
-        requestId: entry.id || ''
+        requestId: entry.id
       });
     }
+    if (processStopBarrier.isBlocked(projectKey, env.CODEX_OVERLEAF_MIRROR_ROOT)) {
+      return errorResponse(request.id, 'codex_process_stop_unconfirmed',
+        'Cancellation was requested, but process exit is not yet confirmed.');
+    }
     if (force && activeProjectLocks.has(projectKey)) {
       activeProjectLocks.delete(projectKey);
       activeRunByProject.delete(projectKey);
@@ -423,8 +485,10 @@ function handleCodexHistoryClear(request, env) {
   }
 }
 
-function handleSkillsList(request, env) {
+async function handleSkillsList(request, env) {
   try {
+    if (request.params?.scope === 'codex-local') return okResponse(request.id,
+      await require('./codexLocalSkills').listCodexLocalSkills({ env }));
     const { CODEX_OVERLEAF_SKILL_SCOPE, listCodexOverleafSkills, listProjectSkills } = require('./localSkills');
     if (request.params?.scope === CODEX_OVERLEAF_SKILL_SCOPE) {
       // Install/restore official skills before listing so newly shipped ones
@@ -443,9 +507,9 @@ function handleSkillsList(request, env) {
     return errorResponse(request.id, 'skills_list_failed', error.message);
   }
 }
-
 function handleSkillsInstall(request, env) {
   try {
+    if (request.params?.scope === 'codex-local') throw new Error('Local Codex skills are managed by Codex.');
     const { CODEX_OVERLEAF_SKILL_SCOPE, installCodexOverleafSkill, installProjectSkill } = require('./localSkills');
     if (request.params?.scope === CODEX_OVERLEAF_SKILL_SCOPE) {
       return okResponse(request.id, installCodexOverleafSkill({
@@ -464,9 +528,9 @@ function handleSkillsInstall(request, env) {
     return errorResponse(request.id, 'skills_install_failed', error.message);
   }
 }
-
 function handleSkillsRemove(request, env) {
   try {
+    if (request.params?.scope === 'codex-local') throw new Error('Local Codex skills are managed by Codex.');
     const { CODEX_OVERLEAF_SKILL_SCOPE, removeCodexOverleafSkill, removeProjectSkill } = require('./localSkills');
     if (request.params?.scope === CODEX_OVERLEAF_SKILL_SCOPE) {
       return okResponse(request.id, removeCodexOverleafSkill({
@@ -494,13 +558,13 @@ function hasRunnableProjectSnapshotEvidence(params = {}) {
   if (params.restrictToFocusFiles !== true) {
     return false;
   }
-  const normalizedFocusFiles = normalizeSnapshotEvidencePaths(params.focusFiles);
+  const normalizedFocusFiles = normalizeSnapshotEvidencePaths(params.focusFiles, params.focusFilesAreLiteral === true);
   if (!normalizedFocusFiles.length || !Array.isArray(params.project?.files)) {
     return false;
   }
   const evidenceFiles = new Map();
   for (const file of params.project.files) {
-    const filePath = normalizeSnapshotEvidencePath(file?.path);
+    const filePath = normalizeSafeProjectPath(file?.path);
     if (!filePath || !isUsableSnapshotEvidenceContent(file?.content)) {
       continue;
     }
@@ -511,19 +575,14 @@ function hasRunnableProjectSnapshotEvidence(params = {}) {
 
 function isSnapshotlessSkillInstallerRun(params = {}) {
   return params.skipMirrorSync === true
-    && String(params.skillInvocation?.id || '').trim() === 'skill-installer';
+    && String(params.skillInvocation?.id || '').trim() === 'skill-installer'
+    && (!params.skillInvocation?.scope || params.skillInvocation.scope === 'builtin');
 }
 
 function validateOtFocusedWarmMirrorReuse(params = {}, status = {}) {
   if (!isOtWarmMirrorReuseRequest(params)) {
     return { ok: false };
   }
-  if (Array.isArray(params.fileOverlays) && params.fileOverlays.length) {
-    return {
-      ok: false,
-      message: 'OT warm mirror reuse does not accept file overlays'
-    };
-  }
   if (status?.exists !== true) {
     return {
       ok: false,
@@ -536,7 +595,7 @@ function validateOtFocusedWarmMirrorReuse(params = {}, status = {}) {
       message: 'OT warm mirror reuse requires restrictToFocusFiles=true'
     };
   }
-  const normalizedFocusFiles = normalizeSnapshotEvidencePaths(params.focusFiles);
+  const normalizedFocusFiles = normalizeSnapshotEvidencePaths(params.focusFiles, params.focusFilesAreLiteral === true);
   if (!normalizedFocusFiles.length) {
     return {
       ok: false,
@@ -544,14 +603,14 @@ function validateOtFocusedWarmMirrorReuse(params = {}, status = {}) {
     };
   }
 
-  const freshFiles = new Set();
+  const freshFiles = new Map();
   for (const file of Array.isArray(status.otFreshFiles) ? status.otFreshFiles : []) {
     if (file?.state !== 'fresh') {
       continue;
     }
-    const filePath = normalizeSnapshotEvidencePath(file.path);
+    const filePath = normalizeSafeProjectPath(file.path);
     if (filePath) {
-      freshFiles.add(filePath);
+      freshFiles.set(filePath, file);
     }
   }
   const missingFiles = normalizedFocusFiles.filter(filePath => !freshFiles.has(filePath));
@@ -562,6 +621,22 @@ function validateOtFocusedWarmMirrorReuse(params = {}, status = {}) {
     };
   }
 
+  if (Array.isArray(params.fileOverlays) && params.fileOverlays.length) {
+    const overlays = new Set();
+    for (const overlay of params.fileOverlays) {
+      const filePath = normalizeSafeProjectPath(overlay?.path);
+      if (!normalizedFocusFiles.includes(filePath) || overlays.has(filePath)
+        || typeof overlay?.content !== 'string' || !/^[a-f0-9]{64}$/i.test(freshFiles.get(filePath)?.sha256 || '')
+        || createHash('sha256').update(overlay.content).digest('hex') !== freshFiles.get(filePath).sha256.toLowerCase()) {
+        return { ok: false, message: 'OT warm mirror overlay does not match the current focused OT baseline' };
+      }
+      overlays.add(filePath);
+    }
+    if (normalizedFocusFiles.some(filePath => !overlays.has(filePath))) {
+      return { ok: false, message: 'OT warm mirror overlays do not cover all focused files' };
+    }
+  }
+
   return { ok: true };
 }
 
@@ -577,11 +652,11 @@ function isUsableSnapshotEvidenceContent(content) {
   return Boolean(text) && !/^(loading|loading\.{3}|loading…)$/i.test(text);
 }
 
-function normalizeSnapshotEvidencePaths(value) {
+function normalizeSnapshotEvidencePaths(value, literal = false) {
   const seen = new Set();
   const paths = [];
   for (const item of Array.isArray(value) ? value : []) {
-    const filePath = normalizeSnapshotEvidencePath(item);
+    const filePath = literal ? normalizeSafeProjectPath(item) : normalizeSnapshotEvidencePath(item);
     if (!filePath || seen.has(filePath)) {
       continue;
     }
@@ -606,6 +681,7 @@ function createCancellationError() {
 }
 
 function isCancellationError(error = {}) {
+  if (['codex_turn_failed', 'codex_turn_status_invalid'].includes(error.code)) return false;
   return error.code === 'codex_cancelled'
     || error.name === 'AbortError'
     || /cancelled by the user|was cancelled/i.test(error.message || '');
@@ -703,6 +779,7 @@ async function handleMirrorConfirmWriteback(request, env) {
     const result = await confirmWritebackFiles({
       projectId,
       paths: params.paths,
+      expectedFiles: params.expectedFiles,
       rootDir
     });
     return okResponse(request.id, result);
@@ -1077,10 +1154,12 @@ function parseAgentArgsJson(value) {
 }
 
 function runExternalAgent(agentSpec, params, emit = () => {}, options = {}) {
-  return new Promise((resolve, reject) => {
+  return runOwnedNativeHelper(signal => new Promise((resolve, reject) => {
+    throwIfAborted(signal);
     const child = spawn(agentSpec.file, agentSpec.args || [], {
       env: options.env || process.env,
       shell: false,
+      detached: process.platform !== 'win32',
       stdio: ['pipe', 'pipe', 'pipe']
     });
     const timeoutMs = parseOptionalPositiveInteger(options.timeoutMs);
@@ -1090,6 +1169,8 @@ function runExternalAgent(agentSpec, params, emit = () => {}, options = {}) {
     let stderrRemainder = '';
     let outputBytes = 0;
     let settled = false;
+    const onAbort = () => fail(signal.reason);
+    signal.addEventListener('abort', onAbort, { once: true });
 
     const timeout = timeoutMs
       ? setTimeout(() => {
@@ -1114,10 +1195,8 @@ function runExternalAgent(agentSpec, params, emit = () => {}, options = {}) {
       if (timeout) {
         clearTimeout(timeout);
       }
-      if (child.exitCode === null && !child.killed) {
-        child.kill('SIGTERM');
-      }
-      reject(error);
+      signal.removeEventListener('abort', onAbort);
+      stopCodexAppServer(child, { processGroup: process.platform !== 'win32', reason: error }).then(() => reject(error), reject);
     }
 
     function succeed(result) {
@@ -1128,7 +1207,8 @@ function runExternalAgent(agentSpec, params, emit = () => {}, options = {}) {
       if (timeout) {
         clearTimeout(timeout);
       }
-      resolve(result);
+      signal.removeEventListener('abort', onAbort);
+      stopCodexAppServer(child, { processGroup: process.platform !== 'win32' }).then(() => resolve(result), reject);
     }
 
     child.stdout.setEncoding('utf8');
@@ -1150,6 +1230,7 @@ function runExternalAgent(agentSpec, params, emit = () => {}, options = {}) {
         emitTaskEvent(emit, event.type || 'agent.progress', event.title || event.type || 'Agent progress', event.detail || {}, event.status || 'running');
       }
     });
+    child.stdin.on('error', fail);
     child.on('error', fail);
     child.on('close', code => {
       if (settled) {
@@ -1176,7 +1257,7 @@ function runExternalAgent(agentSpec, params, emit = () => {}, options = {}) {
     });
 
     child.stdin.end(JSON.stringify(params));
-  });
+  }));
 }
 
 function parsePositiveInteger(value, fallback) {
@@ -1249,27 +1330,19 @@ function errorResponse(id, code, message, details = {}) {
   };
 }
 
-function getActiveNativeWorkState() {
+function getActiveNativeWorkState(env = process.env) {
   return {
     projectLocks: activeProjectLocks.size,
+    processStopBarriers: processStopBarrier.getBlockedProjectCount(env.CODEX_OVERLEAF_MIRROR_ROOT, { env }),
     runControllers: activeRunControllers.size,
     activeTurnControls: Array.from(activeRunEntries.values()).filter(entry => entry.control).length
   };
 }
 
-function abortAllActiveOperations(reason = 'Native messaging transport disconnected.') {
-  const error = new Error(String(reason || 'Native messaging transport disconnected.'));
-  error.code = 'native_transport_closed';
-  for (const controller of activeRunControllers.values()) {
-    if (controller && !controller.signal?.aborted) {
-      controller.abort(error);
-    }
-  }
-}
-
 module.exports = {
   NATIVE_REQUEST_QUOTAS,
-  abortAllActiveOperations,
+  abortAllActiveOperations: runLifecycle.abortAllActiveOperations,
+  quarantineActiveOperations: runLifecycle.quarantineActiveOperations,
   buildDefaultTaskResult,
   getActiveNativeWorkState,
   handleRequest,

package/native-host/src/tomlStatements.js

@@ -0,0 +1,140 @@
+'use strict';
+
+// Preserve TOML source text while finding complete logical statements. This is
+// a lexical boundary scanner, not a TOML value/schema parser. Filters must never
+// treat an apparent key or table header inside a multiline value as syntax.
+function splitTomlStatements(content) {
+  const text = String(content || '').replace(/\r\n/g, '\n');
+  const statements = [];
+  const containers = [];
+  let start = 0;
+  let quote = '';
+  let multiline = false;
+  let comment = false;
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index];
+    if (comment) {
+      if (char !== '\n') continue;
+      comment = false;
+    }
+    if (quote) {
+      if (quote === '"' && char === '\\') {
+        // Basic strings escape the next character, including the first quote
+        // of a potential delimiter. Literal strings have no escape syntax.
+        index++;
+      } else if (char === quote) {
+        if (!multiline) {
+          quote = '';
+        } else if (text.slice(index, index + 3) === quote.repeat(3)) {
+          // A legal closing delimiter can have one or two literal quotes just
+          // before it: consume all four/five instead of opening another string.
+          let count = 3;
+          while (count < 5 && text[index + count] === quote) count++;
+          index += count - 1;
+          quote = '';
+        }
+      }
+      continue;
+    }
+    if (char === '#') {
+      comment = true;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      multiline = text.slice(index, index + 3) === char.repeat(3);
+      if (multiline) index += 2;
+    } else if (char === '[' || char === '{') {
+      containers.push(char);
+    } else if (char === ']' || char === '}') {
+      const opener = char === ']' ? '[' : '{';
+      if (containers.pop() !== opener) throw incompleteValue();
+    } else if (char === '\n' && containers.length === 0) {
+      statements.push(text.slice(start, index + 1));
+      start = index + 1;
+    }
+  }
+
+  // Do not silently remove the remaining config if a selected value is broken.
+  // The caller prepares the full string before writing the destination file.
+  if (quote || containers.length) throw incompleteValue();
+  if (start < text.length) statements.push(text.slice(start));
+  return statements;
+}
+
+function incompleteValue() {
+  return new Error('Codex configuration contains an unterminated or mismatched TOML value.');
+}
+
+// Parse only a statement's key path, leaving its value and original formatting
+// untouched. A quoted dot belongs to a key; an unquoted dot separates keys.
+function readTomlStatementPath(statement) {
+  const text = String(statement || '');
+  let index = 0;
+  const whitespace = () => { while (text[index] === ' ' || text[index] === '\t') index++; };
+  whitespace();
+  if (!text[index] || text[index] === '#' || text[index] === '\n') return null;
+  const table = text[index] === '[';
+  let brackets = 0;
+  if (table) {
+    brackets = text[index + 1] === '[' ? 2 : 1;
+    index += brackets;
+  }
+  const keys = [];
+  while (true) {
+    whitespace();
+    let key = '';
+    const quote = text[index];
+    if (quote === '"' || quote === "'") {
+      index++;
+      while (index < text.length && text[index] !== quote) {
+        const char = text[index++];
+        if (char === '\n' || char === '\r') throw invalidKey();
+        if (quote !== '"' || char !== '\\') { key += char; continue; }
+        const escape = text[index++];
+        const simple = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+        if (Object.prototype.hasOwnProperty.call(simple, escape)) { key += simple[escape]; continue; }
+        const count = escape === 'u' ? 4 : escape === 'U' ? 8 : 0;
+        const hex = text.slice(index, index + count);
+        if (!count || hex.length !== count || !/^[0-9a-f]+$/i.test(hex)) throw invalidKey();
+        const point = Number.parseInt(hex, 16);
+        if (point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff)) throw invalidKey();
+        key += String.fromCodePoint(point);
+        index += count;
+      }
+      if (text[index++] !== quote) throw invalidKey();
+    } else {
+      const match = text.slice(index).match(/^[A-Za-z0-9_-]+/);
+      if (!match) return null;
+      key = match[0]; index += key.length;
+    }
+    keys.push(key);
+    whitespace();
+    if (text[index] !== '.') break;
+    index++;
+  }
+  if (table) {
+    if (text.slice(index, index + brackets) !== ']'.repeat(brackets)) return null;
+    index += brackets; whitespace();
+    if (text[index] && text[index] !== '#' && text[index] !== '\n') return null;
+  } else if (text[index] !== '=') return null;
+  return { table, keys, ...(table ? {} : { valueStart: index + 1 }) };
+}
+
+function filterTomlRootKeys(content, excludedKeys) {
+  const excluded = new Set(excludedKeys);
+  const output = [];
+  let section = [];
+  for (const statement of splitTomlStatements(content)) {
+    const parsed = readTomlStatementPath(statement);
+    if (parsed?.table) section = parsed.keys;
+    const root = section.length ? section[0] : parsed?.keys[0];
+    if (!excluded.has(root)) output.push(statement);
+  }
+  return output.join('');
+}
+
+function invalidKey() {
+  return new Error('Codex configuration contains an invalid TOML key.');
+}
+
+module.exports = { splitTomlStatements, filterTomlRootKeys, readTomlStatementPath };