@minhspark/codex-mcp-bridge 1.10.0

package/src/peer-protocol.mjs

@@ -0,0 +1,367 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+import { homeDir } from "./platform.mjs";
+
+const SOCKET_DIR = "/tmp/cc-socks";
+const PEER_PROTOCOL_VERSION = 1;
+const CLAUDE_VERSION_HINT = "2.1.229";
+const PS_BIN = "/bin/ps";
+
+const sessionsDir = () => path.join(homeDir(), ".claude", "sessions");
+const projectsDir = () => path.join(homeDir(), ".claude", "projects");
+
+/**
+ * A Claude Code session advertises itself in ~/.claude/sessions/<pid>.json and
+ * listens for peer messages on a unix socket. Messages are newline-delimited
+ * JSON; the wrapper element is what Claude renders in its chat surface.
+ */
+export function buildFrame({ text, fromSocket, priority = "next" }) {
+  return {
+    msgV: PEER_PROTOCOL_VERSION,
+    msg_id: crypto.randomUUID(),
+    type: "user",
+    message: {
+      role: "user",
+      content: `<cross-session-message from="uds:${fromSocket}" from-mode="bypass">\n${text}\n</cross-session-message>`,
+    },
+    priority,
+    from: `uds:${fromSocket}`,
+  };
+}
+
+export function parseFrame(line) {
+  const frame = JSON.parse(line);
+  const raw = frame?.message?.content ?? "";
+  const inner = raw.match(/<cross-session-message[^>]*>\n?([\s\S]*?)\n?<\/cross-session-message>/);
+  return {
+    msgId: frame.msg_id ?? null,
+    from: frame.from ?? null,
+    fromSocket: (frame.from ?? "").replace(/^uds:/, "") || null,
+    text: (inner ? inner[1] : raw).trim(),
+  };
+}
+
+/**
+ * MCP servers are spawned with an empty PATH, so `ps` must be addressed by its
+ * absolute path - a bare lookup throws ENOENT and takes the whole server down
+ * before it can answer the client's initialize call. The timestamp only guards
+ * against pid reuse, so an empty value is an acceptable fallback.
+ */
+function readProcessStart(pid) {
+  try {
+    return execFileSync(PS_BIN, ["-o", "lstart=", "-p", String(pid)]).toString().trim();
+  } catch {
+    return "";
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
+export const BRIDGE_ENTRYPOINT = "codex-bridge";
+
+export function listClaudeSessions({ includeDead = false, includeBridges = false } = {}) {
+  const dir = sessionsDir();
+  if (!fs.existsSync(dir)) return [];
+  const rows = [];
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    let entry;
+    try {
+      entry = JSON.parse(fs.readFileSync(path.join(dir, file), "utf8"));
+    } catch {
+      continue;
+    }
+    if (!entry?.pid || !entry?.messagingSocketPath) continue;
+    if (entry.entrypoint === BRIDGE_ENTRYPOINT && !includeBridges) continue;
+    const alive = isProcessAlive(entry.pid) && fs.existsSync(entry.messagingSocketPath);
+    if (!alive && !includeDead) continue;
+    rows.push({
+      pid: entry.pid,
+      name: entry.name ?? null,
+      sessionId: entry.sessionId ?? null,
+      cwd: entry.cwd ?? null,
+      kind: entry.kind ?? null,
+      entrypoint: entry.entrypoint ?? null,
+      startedAt: entry.startedAt ?? null,
+      socket: entry.messagingSocketPath,
+      alive,
+    });
+  }
+  return rows.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0));
+}
+
+export function findClaudeSession(target) {
+  const sessions = listClaudeSessions();
+  const needle = String(target).trim();
+  return (
+    sessions.find((s) => String(s.pid) === needle) ??
+    sessions.find((s) => s.sessionId === needle) ??
+    sessions.find((s) => s.name === needle) ??
+    sessions.find((s) => (s.name ?? "").toLowerCase().includes(needle.toLowerCase())) ??
+    null
+  );
+}
+
+/**
+ * Claude Code stores a transcript at ~/.claude/projects/<slug>/<sessionId>.jsonl
+ * where the slug rewrites more than just path separators (/mnt/dev_disk ->
+ * -mnt-dev-disk, losing the underscore), so the file is located by scanning
+ * rather than by reconstructing the slug.
+ */
+function findTranscriptFile(sessionId, cwd) {
+  const dir = projectsDir();
+  const guess = path.join(dir, String(cwd ?? "").replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`);
+  if (fs.existsSync(guess)) return guess;
+  if (!fs.existsSync(dir)) return guess;
+  for (const project of fs.readdirSync(dir)) {
+    const candidate = path.join(dir, project, `${sessionId}.jsonl`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return guess;
+}
+
+export function readTranscript(sessionId, cwd, limit = 10) {
+  const file = findTranscriptFile(sessionId, cwd);
+  if (!fs.existsSync(file)) return { file, messages: [] };
+  const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+  const messages = [];
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const role = entry?.message?.role;
+    if (role !== "user" && role !== "assistant") continue;
+    if (entry.isMeta || entry.isSidechain) continue;
+    const content = entry?.message?.content;
+    const text = Array.isArray(content)
+      ? content
+          .filter((c) => c?.type === "text")
+          .map((c) => c.text ?? "")
+          .join("\n")
+      : String(content ?? "");
+    if (!text.trim()) continue;
+    messages.push({ role, text: text.trim() });
+  }
+  return { file, messages: messages.slice(-limit) };
+}
+
+/**
+ * Registers this process as a peer that Claude sessions can see in their agent
+ * list and reply to. Without a registered socket, Claude has no address to
+ * answer on and the conversation stays one-way.
+ */
+export class PeerEndpoint {
+  constructor({ name = `codex-${process.pid}`, cwd = process.cwd(), log = () => {} } = {}) {
+    this.name = name;
+    this.cwd = cwd;
+    this.log = log;
+    this.pid = process.pid;
+    this.socketPath = path.join(SOCKET_DIR, `${this.pid}.sock`);
+    this.registryPath = path.join(sessionsDir(), `${this.pid}.json`);
+    this.keyPath = null;
+    this.server = null;
+    this.inbox = [];
+    this.listeners = new Set();
+    this.started = false;
+  }
+
+  /**
+   * A bridge killed with SIGKILL leaves its registry entry and socket behind,
+   * and Claude then lists a crowd of dead peers with the same name. Sweep the
+   * leftovers of previous bridge runs before advertising this one.
+   */
+  #sweepDeadBridges() {
+    const dir = sessionsDir();
+    if (!fs.existsSync(dir)) return;
+    for (const file of fs.readdirSync(dir)) {
+      if (!file.endsWith(".json")) continue;
+      const registry = path.join(dir, file);
+      let entry;
+      try {
+        entry = JSON.parse(fs.readFileSync(registry, "utf8"));
+      } catch {
+        continue;
+      }
+      if (entry?.entrypoint !== BRIDGE_ENTRYPOINT) continue;
+      if (!entry.pid || entry.pid === this.pid || isProcessAlive(entry.pid)) continue;
+      for (const stale of [registry, entry.messagingSocketPath, ...fs.readdirSync(dir)
+        .filter((f) => f.startsWith(`${entry.pid}.`) && f.endsWith(".key"))
+        .map((f) => path.join(dir, f))]) {
+        if (!stale) continue;
+        try {
+          fs.rmSync(stale, { force: true });
+        } catch {}
+      }
+      this.log(`swept dead bridge peer pid ${entry.pid}`);
+    }
+  }
+
+  async start() {
+    if (this.started) return;
+    this.#sweepDeadBridges();
+    const procStart = readProcessStart(this.pid);
+    const peerToken = crypto.randomBytes(16).toString("hex");
+    const keyHash = crypto.createHash("sha256").update(`${peerToken}${procStart}`).digest("hex");
+    this.keyPath = path.join(sessionsDir(), `${this.pid}.${keyHash}.key`);
+
+    fs.mkdirSync(SOCKET_DIR, { recursive: true });
+    fs.mkdirSync(sessionsDir(), { recursive: true });
+    if (fs.existsSync(this.socketPath)) fs.rmSync(this.socketPath, { force: true });
+
+    await new Promise((resolve, reject) => {
+      this.server = net.createServer((socket) => this.#handleConnection(socket));
+      this.server.on("error", reject);
+      this.server.listen(this.socketPath, resolve);
+    });
+    fs.chmodSync(this.socketPath, 0o600);
+
+    this.registry = {
+      pid: this.pid,
+      sessionId: crypto.randomUUID(),
+      cwd: this.cwd,
+      startedAt: Date.now(),
+      procStart,
+      version: CLAUDE_VERSION_HINT,
+      peerProtocol: PEER_PROTOCOL_VERSION,
+      kind: "interactive",
+      entrypoint: BRIDGE_ENTRYPOINT,
+      messagingSocketPath: this.socketPath,
+      name: this.name,
+      nameSource: "derived",
+    };
+    fs.writeFileSync(this.registryPath, JSON.stringify(this.registry), { mode: 0o600 });
+    fs.writeFileSync(this.keyPath, JSON.stringify({ peerToken, procStart }), { mode: 0o600 });
+
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+      process.on(signal, () => {
+        this.stop();
+        process.exit(0);
+      });
+    }
+    process.on("exit", () => this.stop());
+
+    this.started = true;
+    this.log(`peer "${this.name}" listening on ${this.socketPath}`);
+  }
+
+  #handleConnection(socket) {
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      let index;
+      while ((index = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) continue;
+        let message;
+        try {
+          message = parseFrame(line);
+        } catch {
+          this.log(`ignored malformed peer frame (${line.slice(0, 80)})`);
+          continue;
+        }
+        const record = { ...message, receivedAt: Date.now() };
+        this.inbox.push(record);
+        this.log(`inbox <- ${record.fromSocket ?? "?"}: ${record.text.slice(0, 120)}`);
+        for (const listener of [...this.listeners]) {
+          try {
+            listener(record);
+          } catch (err) {
+            this.log(`peer listener error: ${err.message}`);
+          }
+        }
+      }
+    });
+    socket.on("error", (err) => this.log(`peer socket error: ${err.message}`));
+  }
+
+  /**
+   * Codex starts one bridge per session, so several peers advertise at once.
+   * Renaming to the bound thread is what lets a human tell them apart in
+   * Claude's agent list.
+   */
+  rename(name) {
+    if (!name || name === this.name) return this.name;
+    this.name = name;
+    if (this.started && this.registry) {
+      this.registry.name = name;
+      fs.writeFileSync(this.registryPath, JSON.stringify(this.registry), { mode: 0o600 });
+      this.log(`peer renamed to "${name}"`);
+    }
+    return this.name;
+  }
+
+  onMessage(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  async send(targetSocket, text, { priority = "next" } = {}) {
+    const frame = buildFrame({ text, fromSocket: this.socketPath, priority });
+    await new Promise((resolve, reject) => {
+      const client = net.connect({ path: targetSocket }, () => {
+        client.write(`${JSON.stringify(frame)}\n`, () => {
+          client.end();
+          resolve();
+        });
+      });
+      client.on("error", reject);
+    });
+    return frame.msg_id;
+  }
+
+  /**
+   * Claude answers with a fresh msg_id rather than an in-reply-to field, so a
+   * reply is matched by origin socket and arrival time.
+   */
+  waitForReply(fromSocket, { timeoutMs = 120000, since = Date.now() } = {}) {
+    const existing = this.inbox.find((m) => m.fromSocket === fromSocket && m.receivedAt >= since);
+    if (existing) return Promise.resolve(existing);
+    return new Promise((resolve) => {
+      const timer = globalThis.setTimeout(() => {
+        unsubscribe();
+        resolve(null);
+      }, timeoutMs);
+      const unsubscribe = this.onMessage((record) => {
+        if (record.fromSocket !== fromSocket) return;
+        globalThis.clearTimeout(timer);
+        unsubscribe();
+        resolve(record);
+      });
+    });
+  }
+
+  drainInbox(limit = 20) {
+    const messages = this.inbox.slice(-limit);
+    this.inbox = [];
+    return messages;
+  }
+
+  stop() {
+    try {
+      this.server?.close();
+    } catch {}
+    for (const file of [this.socketPath, this.registryPath, this.keyPath]) {
+      if (!file) continue;
+      try {
+        fs.rmSync(file, { force: true });
+      } catch {}
+    }
+    this.started = false;
+  }
+}

package/src/platform.mjs

@@ -0,0 +1,320 @@
+import { execFile, execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const IS_MACOS = process.platform === "darwin";
+export const IS_WINDOWS = process.platform === "win32";
+export const IS_LINUX = process.platform === "linux";
+
+export const PLATFORM_LABEL = IS_MACOS
+  ? "macOS"
+  : IS_WINDOWS
+    ? "Windows"
+    : IS_LINUX
+      ? "Linux"
+      : process.platform;
+
+const CODEX_DESKTOP_APP_MACOS = "/Applications/ChatGPT.app";
+const CODEX_DESKTOP_BIN_MACOS = `${CODEX_DESKTOP_APP_MACOS}/Contents/Resources/codex`;
+const CODEX_THREAD_URL_PREFIX = "codex://threads/";
+
+/**
+ * Read per call rather than at import, so a client that changes the
+ * environment does not have to restart the bridge to be believed.
+ */
+const remapEnabled = () => process.env.CODEX_BRIDGE_REMAP !== "0";
+
+/**
+ * `os.homedir()` reads HOME on macOS and Linux but USERPROFILE on Windows, so
+ * a process that sets only HOME is obeyed on two platforms and ignored on the
+ * third. Every module resolves the home directory through here so all three
+ * behave the same.
+ */
+export const homeDir = () => process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
+
+/**
+ * A path that names a drive letter or an attached volume was almost certainly
+ * written on the other machine - that is the whole signal, and it needs no
+ * configuration to read. Naming one particular drive here would have been a
+ * fact about one machine, and the generic form covers every dual-boot and
+ * external-disk layout instead of a single blessed one.
+ */
+const FOREIGN_ROOT_PATTERNS = [
+  /^[A-Za-z]:\/(.+)$/,
+  /^\/Volumes\/[^/]+\/(.+)$/,
+  /^\/mnt\/[^/]+\/(.+)$/,
+  /^\/media\/[^/]+\/[^/]+\/(.+)$/,
+];
+
+/**
+ * Where the bridge itself is checked out answers the question "where does this
+ * user keep projects?" without anyone having to say so: a bridge living in
+ * ~/code/codex-mcp-bridge makes ~/code the obvious place to look for a sibling
+ * project. That is a measurement, not a guess, and it keeps one developer's
+ * directory layout out of the source.
+ */
+function bridgeParentDir() {
+  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  return path.dirname(repoRoot);
+}
+
+/**
+ * Set CODEX_BRIDGE_WORKSPACE_ROOTS to take over the search entirely - it
+ * replaces the derived roots rather than adding to them, so the order is
+ * exactly what was written.
+ */
+function workspaceRoots() {
+  const configured = process.env.CODEX_BRIDGE_WORKSPACE_ROOTS;
+  if (configured) {
+    return configured
+      .split(path.delimiter)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return [homeDir(), bridgeParentDir()];
+}
+
+function isRunnable(candidate) {
+  if (!candidate || !existsSync(candidate)) return false;
+  if (IS_WINDOWS) return true;
+  try {
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function windowsCodexCandidates() {
+  const roaming = process.env.APPDATA;
+  const local = process.env.LOCALAPPDATA;
+  return [
+    local && path.join(local, "Programs", "OpenAI", "Codex", "bin", "codex.exe"),
+    roaming && path.join(roaming, "npm", "codex.cmd"),
+    process.env.ProgramFiles && path.join(process.env.ProgramFiles, "nodejs", "codex.cmd"),
+  ];
+}
+
+function unixCodexCandidates() {
+  const home = homeDir();
+  return [
+    path.join(home, ".local", "bin", "codex"),
+    path.join(home, ".npm-global", "bin", "codex"),
+    "/opt/homebrew/bin/codex",
+    "/usr/local/bin/codex",
+    path.join(home, ".volta", "bin", "codex"),
+    path.join(home, ".bun", "bin", "codex"),
+    path.join(home, ".cargo", "bin", "codex"),
+    path.join(home, ".codex", "packages", "standalone", "current", "codex"),
+  ];
+}
+
+/**
+ * The desktop app ships its own codex build and holds ~/.codex/state_*.sqlite
+ * open while it runs. Spawning the app-server from a different CLI build makes
+ * two versions write that same state, so prefer the app's binary whenever the
+ * app is installed and fall back to the standalone CLI installs otherwise.
+ */
+function macosCodexCandidates() {
+  return [
+    hasCodexDesktopApp() ? CODEX_DESKTOP_BIN_MACOS : null,
+    ...unixCodexCandidates(),
+  ];
+}
+
+function pathCandidates() {
+  const separator = IS_WINDOWS ? ";" : ":";
+  const names = IS_WINDOWS ? ["codex.exe", "codex.cmd"] : ["codex"];
+  return (process.env.PATH ?? "")
+    .split(separator)
+    .filter(Boolean)
+    .flatMap((dir) => names.map((name) => path.join(dir, name)));
+}
+
+/**
+ * Claude Desktop and launchd start child processes with a trimmed PATH, so a
+ * bare `codex` lookup fails on macOS where the CLI usually lives under
+ * ~/.local/bin, ~/.npm-global/bin or Homebrew. Probe every known install
+ * location for the running platform before giving up on PATH resolution.
+ */
+export function resolveCodexBin(explicit) {
+  const candidates = [
+    explicit,
+    process.env.CODEX_BIN,
+    ...(IS_WINDOWS ? windowsCodexCandidates() : IS_MACOS ? macosCodexCandidates() : unixCodexCandidates()),
+    ...pathCandidates(),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (isRunnable(candidate)) return candidate;
+  }
+  return "codex";
+}
+
+/**
+ * The macOS and Linux `codex` launcher is a Node script with a
+ * `#!/usr/bin/env node` shebang, so the spawned child needs a PATH that
+ * actually contains node - the trimmed PATH handed to MCP servers does not.
+ */
+/**
+ * A path is only usable as a Codex cwd when the agent can also write to it.
+ * The NTFS mounts this project is shared through are read-only on macOS, so an
+ * existence check alone would still hand Codex a directory it cannot edit.
+ */
+export function isWritableDir(target) {
+  try {
+    accessSync(target, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeSeparators(input) {
+  return input.replace(/\\/g, "/").replace(/\/+$/, "") || input;
+}
+
+function foreignRootRelative(input) {
+  const normalized = normalizeSeparators(input);
+  for (const pattern of FOREIGN_ROOT_PATTERNS) {
+    const match = normalized.match(pattern);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+function remapCandidates(input) {
+  const relative = foreignRootRelative(input);
+  if (!relative) return [];
+  const segments = relative.split("/").filter(Boolean);
+  return workspaceRoots().map((root) => path.join(root, ...segments));
+}
+
+/**
+ * The same project lives at a different absolute path on each machine: on the
+ * shared drive's own letter under Windows, under its mount point when that
+ * drive is visible from macOS, and in a native checkout otherwise. Handing
+ * Codex the wrong one starts the thread against a directory the user is not
+ * looking at, or one the agent cannot write to - which then stalls the turn on
+ * a permission request instead of failing outright.
+ *
+ * The path as given always goes first: if this machine can already write
+ * there, no rewriting is warranted and guessing would be the bug. Rewriting
+ * only happens for a path this machine cannot use, which is exactly the case
+ * it was written for - macOS mounts NTFS read-only, so the drive a Windows
+ * brief quotes is visible and useless at the same time.
+ */
+export function resolveWorkspacePath(input) {
+  if (!input) return { path: input, remapped: false, writable: false, note: null };
+  const original = input;
+  const candidates = [input, ...(remapEnabled() ? remapCandidates(input) : [])];
+  const ordered = candidates.filter((candidate, index) => candidates.indexOf(candidate) === index);
+
+  const writable = ordered.find((candidate) => existsSync(candidate) && isWritableDir(candidate));
+  if (writable) {
+    return {
+      path: writable,
+      remapped: writable !== original,
+      writable: true,
+      note:
+        writable !== original
+          ? `cwd remapped for ${PLATFORM_LABEL}: ${original} -> ${writable}`
+          : null,
+    };
+  }
+
+  const existing = ordered.find((candidate) => existsSync(candidate));
+  if (existing) {
+    return {
+      path: existing,
+      remapped: existing !== original,
+      writable: false,
+      note: `cwd ${existing} exists but is not writable on ${PLATFORM_LABEL}; Codex will fail on any file edit.`,
+    };
+  }
+
+  throw new Error(
+    `No usable working directory for "${original}" on ${PLATFORM_LABEL}. Tried: ${ordered.join(", ")}.`,
+  );
+}
+
+export function spawnEnv(extra = {}) {
+  const separator = IS_WINDOWS ? ";" : ":";
+  const systemDirs = IS_WINDOWS
+    ? []
+    : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+  const merged = [path.dirname(process.execPath), ...systemDirs, ...(process.env.PATH ?? "").split(separator)]
+    .filter(Boolean)
+    .filter((dir, index, all) => all.indexOf(dir) === index)
+    .join(separator);
+  return { ...process.env, PATH: merged, ...extra };
+}
+
+export function claudeDesktopConfigPath() {
+  const home = homeDir();
+  if (IS_MACOS) {
+    return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (IS_WINDOWS) {
+    const roaming = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+    return path.join(roaming, "Claude", "claude_desktop_config.json");
+  }
+  const configHome = process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
+  return path.join(configHome, "Claude", "claude_desktop_config.json");
+}
+
+export function launchAgentPath() {
+  return path.join(homeDir(), "Library", "LaunchAgents", "com.codex-mcp-bridge.app-server.plist");
+}
+
+export const LAUNCH_AGENT_LABEL = "com.codex-mcp-bridge.app-server";
+
+export function codexThreadUrl(threadId) {
+  return `${CODEX_THREAD_URL_PREFIX}${threadId}`;
+}
+
+export function hasCodexDesktopApp() {
+  return IS_MACOS && existsSync(CODEX_DESKTOP_APP_MACOS);
+}
+
+export function isLaunchAgentInstalled() {
+  return IS_MACOS && existsSync(launchAgentPath());
+}
+
+/**
+ * The desktop app runs its own stdio app-server against the same ~/.codex
+ * sqlite state. A second long-lived app-server contends for that state and the
+ * app's UI stutters, so the two should not both sit idle in the background.
+ */
+export function isDesktopAppServerRunning() {
+  if (!IS_MACOS) return false;
+  try {
+    const out = execFileSync("/bin/ps", ["-Ao", "command="], { maxBuffer: 4 * 1024 * 1024 }).toString();
+    return out.split("\n").some((line) => line.includes("ChatGPT.app") && line.includes("app-server"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Bring a thread to the foreground in the Codex desktop app so a human can
+ * watch the turn run instead of only reading the transcript afterwards.
+ * macOS registers the `codex://` scheme through /Applications/ChatGPT.app.
+ */
+export async function openThreadInCodexApp(threadId, { activate = true } = {}) {
+  const url = codexThreadUrl(threadId);
+  if (!IS_MACOS) {
+    throw new Error(`Opening a Codex thread in the desktop app is macOS-only. Open ${url} manually.`);
+  }
+  if (!hasCodexDesktopApp()) {
+    throw new Error(`Codex desktop app not found at ${CODEX_DESKTOP_APP_MACOS}. Install it to use ${url}.`);
+  }
+  const args = activate ? [url] : ["-g", url];
+  await execFileAsync("open", args, { timeout: 10000 });
+  return url;
+}