@yugabytedb/meko-mcp 1.1.0 → 2.0.0

package/lib/clients/codex.mjs

@@ -11,12 +11,14 @@
 import { execSync } from "node:child_process";
 import {
   appendFileSync,
+  chmodSync,
   copyFileSync,
   existsSync,
   lstatSync,
   mkdirSync,
   readFileSync,
   readlinkSync,
+  rmSync,
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
@@ -26,13 +28,22 @@ import { askYesNo } from "../prompt.mjs";
 import {
   getCodexAgentsMdPath,
   getCodexConfigPath,
+  getCodexHooksInstallRoot,
+  getCodexHooksPath,
+  getCodexMekoEnvFilePath,
   getCodexSkillsRoot,
+  readJsonFile,
+  writeJsonFile,
 } from "../config.mjs";
 import {
   getInstallerVersion,
+  installStableTree,
+  isPackagedInstall,
+  isDanglingSymlink,
   markerIsStale,
   readInstallerMarker,
   removePath,
+  resolveHooksRoot,
   resolveSkillSource,
   shellQuote,
   symlinkOrCopy,
@@ -42,6 +53,16 @@ import {
 const CODEX_INSTALL_URL = "https://github.com/openai/codex";
 const CODEX_APP_INSTALL_URL = "https://openai.com/index/codex";
 
+// Cloud Meko (mcp.mekodata.ai) sits behind a WAF that returns an HTML 403 for
+// any request with no User-Agent. Codex's native MCP client (codex_rmcp_client)
+// sends none by default, so its `initialize` handshake 403s and the server
+// fails to start. `codex mcp add` exposes no header flag, so we set a per-server
+// `http_headers` entry in config.toml. Scoped to [mcp_servers.<name>] only — it
+// affects requests to the Meko MCP server and nothing else. Local installs skip
+// this (no WAF in front of localhost). See GH #174 and the capture.js UA fix.
+const CODEX_MCP_USER_AGENT =
+  "codex-mcp/1.0 (+https://github.com/yugabyte/meko-mcp-server)";
+
 // AGENTS.md sentinel markers. Idempotent upsert/strip relies on these being
 // stable across versions — never rename without a migration story.
 const AGENTS_MD_START = "<!-- meko:start -->";
@@ -54,12 +75,25 @@ const RC_FENCE_START = "# >>> meko mcp >>>";
 const RC_FENCE_END = "# <<< meko mcp <<<";
 
 const SKILLS = [{ name: "meko-mcp-tools" }];
+// Codex hook timeouts are in SECONDS (Duration::from_secs in
+// codex-rs/hooks/src/engine/command_runner.rs), not milliseconds like Claude
+// Code / Cursor. Default is 600s if omitted; we cap SessionStart/SessionEnd
+// at 15s/30s to match the Claude Code values logically.
+const MEKO_HOOKS = [
+  { event: "SessionStart", script: "session-start.sh", timeout: 15 },
+  { event: "PreCompact", script: "pre-compact.sh" },
+  { event: "SessionEnd", script: "session-end.sh", timeout: 30 },
+];
+const MEKO_HOOK_SCRIPTS = MEKO_HOOKS.map((hook) => hook.script);
 
 /**
  * @param {{
  *   getConfigPath?: () => string,
  *   getAgentsMdPath?: () => string,
+ *   getHooksPath?: () => string,
  *   getSkillsRoot?: () => string,
+ *   resolveHooksRoot?: () => string,
+ *   getHooksInstallRoot?: () => string,
  *   runCommand?: (cmd: string) => string,
  *   probeCodex?: () => {found: boolean, version: string, path: string},
  *   probeCodexApp?: () => {found: boolean, path: string, platform: string, version: string} | null,
@@ -71,7 +105,14 @@ const SKILLS = [{ name: "meko-mcp-tools" }];
 export function createCodexAdapter(options = {}) {
   const resolveConfigPath = options.getConfigPath ?? getCodexConfigPath;
   const resolveAgentsMdPath = options.getAgentsMdPath ?? getCodexAgentsMdPath;
+  const resolveHooksPath = options.getHooksPath ?? getCodexHooksPath;
+  const resolveMekoEnvFilePath =
+    options.getMekoEnvFilePath ?? getCodexMekoEnvFilePath;
+  const resolveHooksRootPath = options.resolveHooksRoot ?? resolveHooksRoot;
+  const resolveHooksInstallRoot =
+    options.getHooksInstallRoot ?? getCodexHooksInstallRoot;
   const resolveSkillsRoot = options.getSkillsRoot ?? getCodexSkillsRoot;
+  const packagedInstallDetector = options.isPackagedInstall ?? isPackagedInstall;
   const runCommand = options.runCommand ?? defaultRunCommand;
   const probeCodex = options.probeCodex ?? defaultProbeCodex;
   const probeCodexApp = options.probeCodexApp ?? defaultProbeCodexApp;
@@ -83,6 +124,16 @@ export function createCodexAdapter(options = {}) {
 
   let scopeWarned = false;
 
+  // A reinstall's remove→register sequence deletes the whole
+  // [mcp_servers.<name>] block (via `codex mcp remove` or removeCodexConfigBlock),
+  // including any http_headers in either inline or table form, before
+  // registerServer rewrites it — which would silently drop a user's custom
+  // headers. removeRegistration stashes the pre-existing headers (as a key→value
+  // map, form-agnostic) here so the later ensureCodexHttpHeaderUserAgent step
+  // can merge them back while guaranteeing a User-Agent. null = nothing to
+  // preserve.
+  let preservedHttpHeaders = null;
+
   /** Returns the resolved config.toml path; warns once on project scope. */
   function settingsPathFor(scope, log) {
     if (scope === "project" && !scopeWarned) {
@@ -165,6 +216,11 @@ export function createCodexAdapter(options = {}) {
     },
     removeRegistration(name, { scope, log } = {}) {
       const path = settingsPathFor(scope, log);
+      // Capture any existing http_headers (inline OR table form) BEFORE we
+      // delete the block, so a reinstall can restore the user's custom values
+      // (see preservedHttpHeaders). Done on both the CLI and TOML paths since
+      // `codex mcp remove` also drops the whole block and any subtable.
+      preservedHttpHeaders = readCodexHttpHeaders(safeReadFile(path), name);
       if (surfaces.cli) {
         try {
           runCommand(`codex mcp remove ${shellQuote(name)}`);
@@ -185,6 +241,8 @@ export function createCodexAdapter(options = {}) {
       const useApiKey = apiKey ? "MEKO_API_KEY" : null;
       const cliCmd = buildCliRegisterCommand(name, url, useApiKey);
 
+      const cloud = !isLocalUrl(url);
+
       if (dryRun) {
         if (surfaces.cli) {
           log.dim?.(`  Would run: ${cliCmd}`);
@@ -196,6 +254,11 @@ export function createCodexAdapter(options = {}) {
             "  Codex resolves the bearer token from $MEKO_API_KEY at runtime; the key is not written to config.toml.",
           );
         }
+        if (cloud) {
+          log.dim?.(
+            `  Would ensure [mcp_servers.${name}] has an http_headers User-Agent (Cloud WAF needs one; backs up ${path} first, preserves any existing header).`,
+          );
+        }
         return;
       }
 
@@ -233,6 +296,42 @@ export function createCodexAdapter(options = {}) {
         if (verbose) log.dim?.(`  Wrote [mcp_servers.${name}] to ${path}`);
       }
 
+      // Cloud Meko's WAF 403s Codex's native MCP client when it sends no
+      // User-Agent on the initialize handshake. `codex mcp add` has no header
+      // flag, so patch the written block with an http_headers User-Agent.
+      // Reads the file first, preserves any existing http_headers, and backs
+      // up config.toml before writing. Local installs have no WAF, so skip.
+      if (cloud) {
+        // Merge back any custom http_headers captured by removeRegistration
+        // before the reinstall wiped the block, while guaranteeing a User-Agent.
+        const preserved = preservedHttpHeaders;
+        preservedHttpHeaders = null; // consume — don't leak into a later call
+        const outcome = ensureCodexHttpHeaderUserAgent(path, name, {
+          preserved,
+        });
+        if (outcome === "restored") {
+          log.dim?.(
+            `  Restored your existing http_headers on [mcp_servers.${name}] (with a User-Agent) after re-registration.`,
+          );
+        } else if (outcome === "merged") {
+          log.dim?.(
+            `  Added a User-Agent to your existing http_headers on [mcp_servers.${name}] so Codex's MCP client clears the Cloud WAF (backup written to ${path}.bak).`,
+          );
+        } else if (outcome === "added") {
+          log.dim?.(
+            `  Set http_headers User-Agent on [mcp_servers.${name}] so Codex's MCP client clears the Cloud WAF (backup written to ${path}.bak).`,
+          );
+        } else if (outcome === "present" && verbose) {
+          log.dim?.(
+            `  [mcp_servers.${name}] already has an http_headers User-Agent — left as-is.`,
+          );
+        } else if (outcome === "absent") {
+          log.warn?.(
+            `  Could not find [mcp_servers.${name}] in ${path} to set the Cloud WAF User-Agent header; if Codex reports an HTTP 403 on startup, add http_headers = { "User-Agent" = "${CODEX_MCP_USER_AGENT}" } manually.`,
+          );
+        }
+      }
+
       // Cloud auth UX: env-var-only model. The key is never written to
       // config.toml; the user's runtime env supplies it. Print actionable
       // instructions and (when interactive) offer to wire things up.
@@ -256,6 +355,12 @@ export function createCodexAdapter(options = {}) {
               log,
             });
           }
+        } else if (hasApp && platform === "darwin") {
+          setLaunchctlMekoApiKey({
+            apiKey,
+            runCommand,
+            log,
+          });
         }
       }
 
@@ -268,10 +373,39 @@ export function createCodexAdapter(options = {}) {
       if (yes) return true;
       return promptUser(`${name} MCP is already configured. Overwrite?`, false);
     },
-    setHookEnvironment({ log, dryRun }) {
-      if (!dryRun) {
+    setHookEnvironment({ url, apiKey, log, dryRun, verbose }) {
+      const hooksPath = resolveHooksPath();
+      const assetHooksRoot = resolveHooksRootPath();
+      const installedHooksRoot = resolveHooksInstallRoot();
+      const envFilePath = resolveMekoEnvFilePath();
+      if (dryRun) {
+        log?.dim?.(`  Would copy Codex hook scripts to ${installedHooksRoot}`);
+        log?.dim?.(`  Would write env file at ${envFilePath} (mode 0600)`);
+        log?.dim?.(`  Would configure Codex hooks at ${hooksPath}`);
+        if (apiKey) {
+          log?.dim?.(
+            `  MEKO_API_KEY will be stored in ${envFilePath} (mode 0600); hook commands source it (no API key in process args).`,
+          );
+        }
+        return;
+      }
+
+      // Copy the hook scripts to a home-dir-stable location before wiring
+      // hooks.json at that path. Referencing the shipped asset root directly
+      // would pin an ephemeral npx cache dir that npx later GCs, leaving the
+      // hook a dangling `bash '<missing>'` that exits 127. See
+      // getCodexHooksInstallRoot for the full rationale.
+      installStableTree(assetHooksRoot, installedHooksRoot);
+      writeCodexMekoEnvFile(envFilePath, { url, apiKey });
+      const changed = upsertCodexMekoHooks(hooksPath, installedHooksRoot, {
+        envFilePath,
+      });
+      if (verbose || changed) {
+        log?.dim?.(`  Updated Codex hooks at ${hooksPath}`);
+      }
+      if (apiKey) {
         log?.dim?.(
-          "  Codex does not expose user-installable session hooks; auto-capture is unavailable.",
+          `  MEKO_API_KEY stored in ${envFilePath} (mode 0600). Hook commands source the file at run time, so the key never appears in process arguments.`,
         );
       }
     },
@@ -314,9 +448,20 @@ export function createCodexAdapter(options = {}) {
           } else {
             continue;
           }
+        } else if (isDanglingSymlink(destination)) {
+          // Stale symlink left behind by an earlier install whose target
+          // (e.g. a deleted worktree) no longer exists. existsSync is false
+          // for these, so the branch above misses them. Clear it so the
+          // fresh-install path below can replace it cleanly.
+          log.dim?.(
+            `  Replacing dangling symlink at ${destination} (target missing).`,
+          );
+          removePath(destination);
         }
 
-        const strategy = symlinkOrCopy(source, destination);
+        const strategy = symlinkOrCopy(source, destination, {
+          preferCopy: packagedInstallDetector(),
+        });
         if (strategy === "copy") writeInstallerMarker(destination);
       }
 
@@ -373,6 +518,28 @@ export function createCodexAdapter(options = {}) {
         });
       }
 
+      try {
+        const hooksPath = resolveHooksPath();
+        const envFilePath = resolveMekoEnvFilePath();
+        const changed = removeCodexMekoHooks(hooksPath, {
+          envFilePath,
+          hooksInstallRoot: resolveHooksInstallRoot(),
+        });
+        if (changed) {
+          results.push({
+            key: "hooks",
+            ok: true,
+            message: "Codex Meko hooks cleaned up.",
+          });
+        }
+      } catch (err) {
+        results.push({
+          key: "hooks",
+          ok: false,
+          message: `Could not clean Codex hooks: ${err.message}`,
+        });
+      }
+
       try {
         const agentsMdPath = resolveAgentsMdPath();
         const raw = safeReadFile(agentsMdPath);
@@ -434,6 +601,160 @@ export function createCodexAdapter(options = {}) {
   };
 }
 
+// Codex's hooks.json schema only deserializes `hooks` and `state` — sibling
+// keys like `env` are silently dropped, and `HookHandlerConfig::Command` has
+// no per-command `env` field. The runner spawns each command via
+// `$SHELL -lc <command>` with the parent env inherited.
+//
+// We sidestep that by writing a 0600 env file (default ~/.codex/meko-env.sh)
+// that the hook command sources before invoking the script:
+//   `. /path/to/meko-env.sh && bash /path/to/hook.sh`
+// The API key never appears in process arguments, so a `ps -ef` from another
+// user (or a logging shim) can't lift it from the command line. Same trust
+// boundary as `git credential-store`.
+function upsertCodexMekoHooks(hooksPath, hooksRoot, { envFilePath } = {}) {
+  const cfg = readJsonFile(hooksPath);
+  const before = JSON.stringify(cfg);
+  if (!cfg.hooks || typeof cfg.hooks !== "object") {
+    cfg.hooks = {};
+  }
+
+  pruneCodexMekoHooksObject(cfg.hooks);
+  for (const hook of MEKO_HOOKS) {
+    const entry = {
+      type: "command",
+      command: buildCodexHookCommand(join(hooksRoot, hook.script), { envFilePath }),
+    };
+    if (hook.timeout) entry.timeout = hook.timeout;
+    upsertCodexHookEntry(cfg.hooks, hook.event, entry);
+  }
+
+  const after = JSON.stringify(cfg);
+  if (after !== before) {
+    writeJsonFile(hooksPath, cfg);
+    return true;
+  }
+  return false;
+}
+
+function buildCodexHookCommand(scriptPath, { envFilePath } = {}) {
+  const parts = [];
+  if (envFilePath) parts.push(`. ${shellQuote(envFilePath)}`);
+  parts.push(`bash ${shellQuote(scriptPath)}`);
+  return parts.join(" && ");
+}
+
+/**
+ * Write the Meko env file the Codex hooks source. Mode 0600 (user
+ * read/write only) so the API key isn't readable by other users.
+ * Idempotent: re-running with the same values is a no-op write that
+ * still asserts the mode.
+ */
+function writeCodexMekoEnvFile(path, { url, apiKey }) {
+  mkdirSync(dirname(path), { recursive: true });
+  const lines = [
+    "# Auto-generated by @yugabytedb/meko-mcp installer.",
+    "# Sourced by Codex hooks (see ~/.codex/hooks.json) before each hook runs.",
+    "# Mode 0600 — do not commit, do not share, do not relax permissions.",
+    `export MEKO_MCP_URL=${shellQuote(url || "")}`,
+    `export MEKO_API_KEY=${shellQuote(apiKey || "")}`,
+    "",
+  ];
+  writeFileSync(path, lines.join("\n"), { encoding: "utf8", mode: 0o600 });
+  // writeFileSync's `mode` only applies on initial create; re-assert
+  // explicitly so a permission relaxation between installs is corrected.
+  chmodSync(path, 0o600);
+}
+
+function removeCodexMekoHooks(hooksPath, { envFilePath, hooksInstallRoot } = {}) {
+  const cfg = readJsonFile(hooksPath);
+  let changed = false;
+  if (cfg.hooks && typeof cfg.hooks === "object") {
+    const before = JSON.stringify(cfg);
+    pruneCodexMekoHooksObject(cfg.hooks);
+    if (Object.keys(cfg.hooks).length === 0) {
+      delete cfg.hooks;
+    }
+    // Older installs (PR 127 first cut) wrote a top-level cfg.env block that
+    // Codex silently ignored. Strip it during uninstall so we don't leave a
+    // misleading env hanging around in user configs.
+    if (cfg.env && typeof cfg.env === "object") {
+      delete cfg.env.MEKO_MCP_URL;
+      delete cfg.env.MEKO_API_KEY;
+      if (Object.keys(cfg.env).length === 0) {
+        delete cfg.env;
+      }
+    }
+    if (JSON.stringify(cfg) !== before) {
+      writeJsonFile(hooksPath, cfg);
+      changed = true;
+    }
+  }
+
+  // Remove the meko-env.sh file too — leaving a 0600 file with credentials
+  // around after uninstall is a security gap.
+  if (envFilePath) {
+    try {
+      rmSync(envFilePath, { force: true });
+    } catch {
+      // best-effort
+    }
+  }
+
+  // Remove the copied hook scripts (getCodexHooksInstallRoot). We remove the
+  // whole meko-hooks/ wrapper, not just the hooks-handlers leaf, so no empty
+  // parent is left behind. best-effort — never let cleanup fail uninstall.
+  if (hooksInstallRoot) {
+    try {
+      rmSync(dirname(hooksInstallRoot), { recursive: true, force: true });
+    } catch {
+      // best-effort
+    }
+  }
+  return changed;
+}
+
+function upsertCodexHookEntry(hooksObj, event, entry) {
+  if (!Array.isArray(hooksObj[event])) hooksObj[event] = [];
+  let group = hooksObj[event].find((item) => Array.isArray(item?.hooks));
+  if (!group) {
+    group = { hooks: [] };
+    hooksObj[event].push(group);
+  }
+  const exists = group.hooks.some((hook) => hook.command === entry.command);
+  if (!exists) group.hooks.push(entry);
+}
+
+function pruneCodexMekoHooksObject(hooksObj) {
+  for (const event of Object.keys(hooksObj)) {
+    const groups = hooksObj[event];
+    if (!Array.isArray(groups)) continue;
+    hooksObj[event] = groups
+      .map((group) => {
+        if (!Array.isArray(group?.hooks)) return group;
+        return {
+          ...group,
+          hooks: group.hooks.filter((hook) => !isMekoHookCommand(hook?.command)),
+        };
+      })
+      .filter((group) => !Array.isArray(group?.hooks) || group.hooks.length > 0);
+    if (hooksObj[event].length === 0) {
+      delete hooksObj[event];
+    }
+  }
+}
+
+function isMekoHookCommand(command) {
+  if (typeof command !== "string") return false;
+  return MEKO_HOOK_SCRIPTS.some((script) => {
+    const escaped = script.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(
+      String.raw`(^|[/\\])hooks-handlers[/\\]${escaped}(?=$|['"\s])`,
+    );
+    return pattern.test(command);
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Probes (default impls; tests inject stubs)
 // ---------------------------------------------------------------------------
@@ -544,6 +865,200 @@ function buildCliRegisterCommand(name, url, bearerEnv) {
   return cmd;
 }
 
+/**
+ * True for localhost / loopback MCP URLs (no cloud WAF in front). Parses the
+ * URL and compares the HOSTNAME exactly — a substring test would wrongly
+ * classify `https://localhost.example.com` (a real remote host) as local and
+ * skip the WAF User-Agent header. Unparseable input is treated as non-local
+ * (cloud), i.e. we err toward setting the header.
+ */
+function isLocalUrl(url) {
+  let host;
+  try {
+    host = new URL(String(url ?? "")).hostname;
+  } catch {
+    return false;
+  }
+  // `new URL` strips the brackets from IPv6 literals, so `[::1]` → `::1`.
+  host = host.replace(/^\[|\]$/g, "").toLowerCase();
+  return (
+    host === "localhost" ||
+    host === "::1" ||
+    // Entire 127.0.0.0/8 block is loopback, not just 127.0.0.1.
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
+  );
+}
+
+const HTTP_HEADER_USER_AGENT_KEY = "User-Agent";
+
+// Matches one `KEY = "VALUE"` (or single-quoted) pair. KEY may be
+// double-quoted, single-quoted, or a bare TOML key (letters/digits/_/-).
+// Used for both the inline `{ ... }` body and the table-form body.
+const TOML_KV_PAIR =
+  /(?:"([^"]*)"|'([^']*)'|([A-Za-z0-9_-]+))\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+/** True if `map` has a `User-Agent` key, case-insensitively (HTTP names are). */
+function hasUserAgentKey(map) {
+  return Object.keys(map).some((k) => k.toLowerCase() === "user-agent");
+}
+
+/** Parse `KEY = "VALUE"` pairs from a chunk of TOML into an ordered object. */
+function parseTomlKvPairs(text) {
+  const out = {};
+  TOML_KV_PAIR.lastIndex = 0;
+  let m;
+  while ((m = TOML_KV_PAIR.exec(text)) !== null) {
+    const key = m[1] ?? m[2] ?? m[3];
+    const value = m[4] ?? m[5] ?? "";
+    if (key !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Locate a table-form `[mcp_servers.<name>.http_headers]` section, if present.
+ * `parseCodexConfigForServer`'s block ends at the first subtable, so this form
+ * lives OUTSIDE that block and needs its own lookup.
+ *
+ * @returns {{start: number, end: number, body: string}|null}
+ */
+function findHttpHeadersSubtable(raw, name) {
+  const header = `[mcp_servers.${name}.http_headers]`;
+  const idx = findHeader(raw, header);
+  if (idx === -1) return null;
+  const end = findNextHeader(raw, idx + header.length);
+  return { start: idx, end, body: raw.slice(idx + header.length, end) };
+}
+
+/**
+ * Read the effective `http_headers` for a server from EITHER form (inline
+ * `http_headers = { ... }` inside the block, or a `[…​.http_headers]` subtable),
+ * returning an ordered key→value map, or null when neither is present. Used to
+ * snapshot a user's headers before a reinstall wipes them.
+ *
+ * @param {string|null} raw
+ * @param {string} name
+ * @returns {Record<string,string>|null}
+ */
+function readCodexHttpHeaders(raw, name) {
+  if (raw === null || raw === undefined) return null;
+  const existing = parseCodexConfigForServer(raw, name);
+  if (!existing.found) return null;
+
+  const block = raw.slice(existing.start, existing.end);
+  const inline = block.match(/^[ \t]*http_headers[ \t]*=[ \t]*\{([^}]*)\}/m);
+  if (inline) return parseTomlKvPairs(inline[1]);
+
+  const subtable = findHttpHeadersSubtable(raw, name);
+  if (subtable) return parseTomlKvPairs(subtable.body);
+
+  return null;
+}
+
+/** Render a headers map as a single canonical inline `http_headers` line. */
+function renderInlineHttpHeaders(map) {
+  const parts = Object.entries(map).map(
+    ([k, v]) => `"${escapeTomlString(k)}" = "${escapeTomlString(v)}"`,
+  );
+  return `http_headers = { ${parts.join(", ")} }`;
+}
+
+/**
+ * Ensure the `[mcp_servers.<name>]` block carries an `http_headers` User-Agent
+ * so Codex's native MCP client clears the Cloud WAF (see CODEX_MCP_USER_AGENT).
+ *
+ * This MERGES rather than all-or-nothing: it reads the effective headers from
+ * whichever form is present — inline `http_headers = { ... }` or a table-form
+ * `[mcp_servers.<name>.http_headers]` — plus any `preserved` map captured
+ * before a reinstall wiped the block, then guarantees a `User-Agent` entry
+ * exists while keeping every other header the user set. The result is written
+ * as a single canonical inline line, and any table-form section is removed so
+ * we never leave two conflicting `http_headers` definitions (invalid TOML).
+ *
+ * Contract — check, back up, then change:
+ *   1. Read config.toml (returns "absent" if the file or server block is gone).
+ *   2. Merge preserved + existing headers; if a User-Agent is already present
+ *      AND no reshaping is needed (no table form to collapse), report "present"
+ *      and write nothing.
+ *   3. Otherwise write the merged inline header via writeWithBackup (`.bak`).
+ *
+ * @param {string} configPath
+ * @param {string} name
+ * @param {{userAgent?: string, preserved?: Record<string,string>|null}} [opts]
+ * @returns {"added"|"restored"|"merged"|"present"|"absent"} what happened
+ */
+function ensureCodexHttpHeaderUserAgent(
+  configPath,
+  name,
+  { userAgent, preserved = null } = {},
+) {
+  const ua = userAgent ?? CODEX_MCP_USER_AGENT;
+  const raw = safeReadFile(configPath);
+  if (raw === null) return "absent";
+  const existing = parseCodexConfigForServer(raw, name);
+  if (!existing.found) return "absent";
+
+  const block = raw.slice(existing.start, existing.end);
+  const inlineMatch = block.match(
+    /^[ \t]*http_headers[ \t]*=[ \t]*\{([^}]*)\}[ \t]*$/m,
+  );
+  const subtable = findHttpHeadersSubtable(raw, name);
+
+  // Merge order: existing on-disk headers first (inline or table), then any
+  // reinstall-preserved map layered on top. Preserved wins on key collisions
+  // because it reflects the user's most recent intent before the wipe.
+  const onDisk = inlineMatch
+    ? parseTomlKvPairs(inlineMatch[1])
+    : subtable
+      ? parseTomlKvPairs(subtable.body)
+      : {};
+  const merged = { ...onDisk, ...(preserved ?? {}) };
+
+  const hadUserAgent = hasUserAgentKey(merged);
+  const restoring = Boolean(preserved);
+
+  // Nothing to do only when a User-Agent is already present AND the on-disk
+  // form is a single inline line (nothing to collapse or restore).
+  if (hadUserAgent && inlineMatch && !subtable && !restoring) return "present";
+
+  if (!hadUserAgent) merged[HTTP_HEADER_USER_AGENT_KEY] = ua;
+
+  const line = renderInlineHttpHeaders(merged);
+
+  // Build the new server block: drop any existing inline line, then insert the
+  // canonical inline line right under the table header.
+  let newBlock = block;
+  if (inlineMatch) {
+    newBlock = newBlock.replace(
+      /^[ \t]*http_headers[ \t]*=[ \t]*\{[^}]*\}[ \t]*\n?/m,
+      "",
+    );
+  }
+  const headerLine = `[mcp_servers.${name}]`;
+  const headerIdx = newBlock.indexOf(headerLine);
+  const insertAt = headerIdx + headerLine.length;
+  newBlock =
+    newBlock.slice(0, insertAt) + `\n${line}` + newBlock.slice(insertAt);
+
+  // Reassemble the file, splicing the block back and excising any table-form
+  // subtable (now folded into the inline line) to avoid a duplicate key.
+  let next = raw.slice(0, existing.start) + newBlock + raw.slice(existing.end);
+  if (subtable) {
+    // Recompute the subtable bounds against the rewritten string — the block
+    // edit shifted offsets. The subtable always sits after our block.
+    const fresh = findHttpHeadersSubtable(next, name);
+    if (fresh) {
+      next = next.slice(0, fresh.start) + next.slice(fresh.end);
+      next = next.replace(/\n{3,}/g, "\n\n");
+    }
+  }
+
+  writeWithBackup(configPath, next);
+  if (restoring) return "restored";
+  if (subtable || (inlineMatch && !hadUserAgent)) return "merged";
+  return "added";
+}
+
 // ---------------------------------------------------------------------------
 // TOML helpers (App-only fallback path)
 // ---------------------------------------------------------------------------
@@ -915,12 +1430,24 @@ export async function maybeOfferLaunchctlSetenv({
     false,
   );
   if (!accept) return { set: false };
+  return setLaunchctlMekoApiKey({ apiKey, runCommand, log });
+}
+
+/**
+ * Run `launchctl setenv MEKO_API_KEY <key>` so the macOS Codex.app launched
+ * from Finder/Dock can authenticate during the current login session.
+ *
+ * The key is passed to launchctl but never logged.
+ *
+ * @returns {{set: boolean}}
+ */
+export function setLaunchctlMekoApiKey({ apiKey, runCommand, log }) {
   try {
     runCommand(`launchctl setenv MEKO_API_KEY ${shellQuote(apiKey)}`);
     log?.dim?.("  Set MEKO_API_KEY via launchctl (current login session).");
     return { set: true };
   } catch (err) {
-    log?.warn?.(`  launchctl setenv failed: ${err.message}`);
+    log?.warn?.("  launchctl setenv failed; run it manually if Codex.app needs cloud auth.");
     return { set: false };
   }
 }
@@ -974,4 +1501,10 @@ export const __TEST__ = {
   AGENTS_MD_END,
   defaultDetectShellRc,
   buildCliRegisterCommand,
+  ensureCodexHttpHeaderUserAgent,
+  readCodexHttpHeaders,
+  findHttpHeadersSubtable,
+  parseTomlKvPairs,
+  isLocalUrl,
+  CODEX_MCP_USER_AGENT,
 };