@yugabytedb/meko-mcp 1.2.0 → 2.1.0

package/lib/clients/codex.mjs

@@ -28,6 +28,7 @@ import { askYesNo } from "../prompt.mjs";
 import {
   getCodexAgentsMdPath,
   getCodexConfigPath,
+  getCodexHooksInstallRoot,
   getCodexHooksPath,
   getCodexMekoEnvFilePath,
   getCodexSkillsRoot,
@@ -36,6 +37,8 @@ import {
 } from "../config.mjs";
 import {
   getInstallerVersion,
+  installStableTree,
+  isPackagedInstall,
   isDanglingSymlink,
   markerIsStale,
   readInstallerMarker,
@@ -50,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 -->";
@@ -64,14 +77,19 @@ 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.
+// Code / Cursor. Codex hard-caps SessionEnd at three seconds, so its dedicated
+// handler only spools input and launches the actual capture in the background.
 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 },
+  { event: "SessionEnd", script: "codex-session-end.sh", timeout: 3 },
+];
+// Include the former synchronous Codex SessionEnd handler so reinstall prunes
+// it instead of leaving both old and new handlers active.
+const MEKO_HOOK_SCRIPTS = [
+  ...MEKO_HOOKS.map((hook) => hook.script),
+  "session-end.sh",
 ];
-const MEKO_HOOK_SCRIPTS = MEKO_HOOKS.map((hook) => hook.script);
 
 /**
  * @param {{
@@ -80,6 +98,7 @@ const MEKO_HOOK_SCRIPTS = MEKO_HOOKS.map((hook) => hook.script);
  *   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,
@@ -95,7 +114,10 @@ export function createCodexAdapter(options = {}) {
   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;
@@ -107,6 +129,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) {
@@ -169,10 +201,11 @@ export function createCodexAdapter(options = {}) {
         surfaces.app = app?.found ? app : null;
       }
 
+      let cliFound = false;
       if (surfaces.cli) {
         try {
           runCommand(`codex mcp get ${shellQuote(name)}`);
-          return { found: true, status: "Configured" };
+          cliFound = true;
         } catch {
           // fall through to TOML grep — `codex mcp get` exits non-zero when
           // the entry isn't present, but might also fail for unrelated
@@ -182,13 +215,27 @@ export function createCodexAdapter(options = {}) {
       }
       const path = settingsPathFor(scope, null);
       const raw = safeReadFile(path);
-      if (raw === null) return { found: false, status: "" };
-      return parseCodexConfigForServer(raw, name).found
+      if (raw !== null) {
+        const parsed = parseCodexConfigForServer(raw, name);
+        if (parsed.found) {
+          return {
+            found: true,
+            status: "Configured",
+            ...(parsed.url ? { url: parsed.url } : {}),
+          };
+        }
+      }
+      return cliFound
         ? { found: true, status: "Configured" }
         : { found: false, status: "" };
     },
     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)}`);
@@ -209,6 +256,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}`);
@@ -220,6 +269,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;
       }
 
@@ -257,6 +311,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.
@@ -300,9 +390,11 @@ export function createCodexAdapter(options = {}) {
     },
     setHookEnvironment({ url, apiKey, log, dryRun, verbose }) {
       const hooksPath = resolveHooksPath();
-      const hooksRoot = resolveHooksRootPath();
+      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) {
@@ -313,8 +405,16 @@ export function createCodexAdapter(options = {}) {
         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, hooksRoot, { envFilePath });
+      const changed = upsertCodexMekoHooks(hooksPath, installedHooksRoot, {
+        envFilePath,
+      });
       if (verbose || changed) {
         log?.dim?.(`  Updated Codex hooks at ${hooksPath}`);
       }
@@ -374,7 +474,9 @@ export function createCodexAdapter(options = {}) {
           removePath(destination);
         }
 
-        const strategy = symlinkOrCopy(source, destination);
+        const strategy = symlinkOrCopy(source, destination, {
+          preferCopy: packagedInstallDetector(),
+        });
         if (strategy === "copy") writeInstallerMarker(destination);
       }
 
@@ -434,7 +536,10 @@ export function createCodexAdapter(options = {}) {
       try {
         const hooksPath = resolveHooksPath();
         const envFilePath = resolveMekoEnvFilePath();
-        const changed = removeCodexMekoHooks(hooksPath, { envFilePath });
+        const changed = removeCodexMekoHooks(hooksPath, {
+          envFilePath,
+          hooksInstallRoot: resolveHooksInstallRoot(),
+        });
         if (changed) {
           results.push({
             key: "hooks",
@@ -550,7 +655,7 @@ function upsertCodexMekoHooks(hooksPath, hooksRoot, { envFilePath } = {}) {
 function buildCodexHookCommand(scriptPath, { envFilePath } = {}) {
   const parts = [];
   if (envFilePath) parts.push(`. ${shellQuote(envFilePath)}`);
-  parts.push(`bash ${shellQuote(scriptPath)}`);
+  parts.push(`MEKO_HOOK_CLIENT=codex bash ${shellQuote(scriptPath)}`);
   return parts.join(" && ");
 }
 
@@ -576,7 +681,7 @@ function writeCodexMekoEnvFile(path, { url, apiKey }) {
   chmodSync(path, 0o600);
 }
 
-function removeCodexMekoHooks(hooksPath, { envFilePath } = {}) {
+function removeCodexMekoHooks(hooksPath, { envFilePath, hooksInstallRoot } = {}) {
   const cfg = readJsonFile(hooksPath);
   let changed = false;
   if (cfg.hooks && typeof cfg.hooks === "object") {
@@ -610,6 +715,17 @@ function removeCodexMekoHooks(hooksPath, { envFilePath } = {}) {
       // 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;
 }
 
@@ -764,6 +880,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)
 // ---------------------------------------------------------------------------
@@ -1206,4 +1516,10 @@ export const __TEST__ = {
   AGENTS_MD_END,
   defaultDetectShellRc,
   buildCliRegisterCommand,
+  ensureCodexHttpHeaderUserAgent,
+  readCodexHttpHeaders,
+  findHttpHeadersSubtable,
+  parseTomlKvPairs,
+  isLocalUrl,
+  CODEX_MCP_USER_AGENT,
 };

package/lib/clients/common.mjs

@@ -9,11 +9,16 @@ import {
   unlinkSync,
   rmSync,
   readFileSync,
+  renameSync,
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+export const MEKO_MCP_USER_AGENT = "meko-mcp-installer/1.0";
+export const MEKO_PRODUCTION_MCP_URL = "https://mcp.mekodata.ai/mcp";
+export const MEKO_PRODUCTION_CONSOLE_URL = "https://cloud.mekodata.ai";
+
 /**
  * @returns {string} Absolute repository root path.
  */
@@ -83,6 +88,16 @@ export function resolveHooksRoot() {
   return join(getAssetRoot(), "hooks-handlers");
 }
 
+/**
+ * @returns {string} absolute path to the statusline script source.
+ *   Lives under skills/scripts/ in source, mirrored under assets/scripts/ in
+ *   the npm-packed install — both roots are siblings of skills/hooks-handlers/
+ *   and skills/skills/.
+ */
+export function resolveStatuslineSource() {
+  return join(getAssetRoot(), "scripts", "meko-statusline.sh");
+}
+
 /**
  * Run a shell command and return stdout.
  * @param {string} cmd
@@ -192,11 +207,15 @@ function unlinkAllowingMissing(targetPath) {
  * @param {string} destination
  * @returns {"symlink"|"copy"}
  */
-export function symlinkOrCopy(source, destination) {
+export function symlinkOrCopy(source, destination, { preferCopy = false } = {}) {
   mkdirSync(dirname(destination), { recursive: true });
   if (isDanglingSymlink(destination)) {
     unlinkAllowingMissing(destination);
   }
+  if (preferCopy) {
+    cpSync(source, destination, { recursive: true });
+    return "copy";
+  }
   try {
     symlinkSync(source, destination, "junction");
     return "symlink";
@@ -206,6 +225,29 @@ export function symlinkOrCopy(source, destination) {
   }
 }
 
+/** Atomically refresh a runtime-owned directory at a stable path. */
+export function installStableTree(source, destination) {
+  if (resolve(source) === resolve(destination)) return;
+  const suffix = `${process.pid}-${Date.now()}`;
+  const staging = `${destination}.tmp-${suffix}`;
+  const backup = `${destination}.bak-${suffix}`;
+
+  mkdirSync(dirname(destination), { recursive: true });
+  try {
+    cpSync(source, staging, { recursive: true });
+    if (existsSync(destination)) renameSync(destination, backup);
+    try {
+      renameSync(staging, destination);
+    } catch (err) {
+      if (existsSync(backup)) renameSync(backup, destination);
+      throw err;
+    }
+    rmSync(backup, { recursive: true, force: true });
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
 /**
  * Remove path if it is a symlink or directory/file.
  * @param {string} targetPath