@gemus/mcp-proxy 0.1.8 → 0.1.10

package/src/relay.mjs

@@ -0,0 +1,440 @@
+#!/usr/bin/env node
+// @gemus/mcp-proxy — local stdio<->HTTP MCP proxy for Codex desktop (Issue #1751, P1).
+//
+// Codex (stdio) <-> this proxy <-> remote gemus /api/mcp (streamable HTTP, Bearer mak_ key).
+// The proxy is a TRANSPARENT JSON-RPC passthrough (tools + resources + notifications all relay
+// untouched) that additionally TAPS execute/batch_execute to observe client-delivered image
+// backfill anchors, then at turn end backfills codex imagegen output into the planned gen-* nodes.
+// Codex does no auth for stdio MCP servers, so THIS process owns upstream auth (the user's mak_ key).
+//
+// Turn-end backfill has two triggers:
+//   • Stop hook (trusted) → loopback HTTP POST /backfill { transcript_path, thread_id } → claim path.
+//   • idle-timer fallback (untrusted hook) → salvageOnly (orphan-only). Both idempotent via seen-set.
+//
+// Validated end-to-end on 2026-07-06 (codex-cli 0.142.2, real dev /api/mcp): transparent passthrough
+// of all 12 gemus tools; codex spawns one proxy per session; real tool-calls tapped with workflowId
+// (from arguments) + turn/thread identity (from _meta.x-codex-turn-metadata). Step-0.4: plugin-bundled
+// Stop hook fires after /hooks trust. The plugin-scoped Companion forwards GEMUS_KEY from the user
+// environment, so neither the plugin config nor generated commands contain a literal key.
+// See docs/plans/1751-codex-desktop-companion.md.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import http from 'node:http'
+import os from 'node:os'
+import path from 'node:path'
+import fs from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { createBackfiller, injectSteering } from './backfill.mjs'
+import { unwrapMcpContent } from '@gemus/codex-backfill-core'
+import { buildProxyUpstreamHeaders } from './mcpHeaders.mjs'
+import { createFailFast, isJsonRpcResponse } from './failFast.mjs'
+import { createProxyFailure } from './proxyMessages.mjs'
+import { createUpstreamHttp } from './upstreamHttp.mjs'
+import {
+  assertGemusKey,
+  createFatalReporter,
+  createShutdownCoordinator,
+  safeEndpointLabel,
+  settleWithin,
+  startProxy,
+} from './startup.mjs'
+
+const KEY = process.env.GEMUS_KEY || ''
+const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
+const LOG = process.env.PROXY_LOG // optional debug log path
+const log = (dir, m) => {
+  if (!LOG) return
+  try {
+    fs.appendFileSync(LOG, `[${new Date().toISOString()}] ${dir} ${typeof m === 'string' ? m : JSON.stringify(m).slice(0, 1000)}\n`)
+  } catch {
+    // Debug logging is optional and must never affect proxy lifecycle.
+  }
+}
+
+const reportFatal = createFatalReporter({
+  secret: KEY,
+  writeStderr: (message) => fs.writeSync(2, message),
+  writeLog: (message) => log('FATAL', message),
+})
+let shutdown
+let shutdownRequested = false
+function terminateFatally(error) {
+  reportFatal(error)
+  shutdownRequested = true
+  if (shutdown) return shutdown(1)
+  process.exit(1)
+}
+process.on('uncaughtException', (error) => { void terminateFatally(error) })
+process.on('unhandledRejection', (reason) => { void terminateFatally(reason) })
+
+try {
+  assertGemusKey(KEY)
+} catch (error) {
+  terminateFatally(error)
+}
+
+const SERVER_ORIGIN = GEMUS_URL.replace(/\/api\/mcp\/?$/, '') // core delivery appends /api/mcp itself
+const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
+// turn-idle fallback (untrusted-hook path). Default 3min: imagegen alone runs 30-60s with NO MCP tool
+// calls, so a short idle looks like "turn ended" mid-generation and fires prematurely. A trusted Stop
+// hook fires at turn end and clears this timer, so trusted users never hit it (#1751 real-machine fix).
+const IDLE_MS = Number(process.env.PROXY_BACKFILL_IDLE_MS) || 180_000
+// footprint-0 注入交付超时（#1756 Layer 1a）。必须 ≥ 平台对 codex-imagen 回填节点的同步等待上限
+// （deriveWaitTimeoutMs('gen-image-generation')=180s，见 src/server/generation/waitTimeout.ts），否则
+// proxy 先超时 → 假失败 → orphan 回退 → 同图重复交付。240s = 180s + 余量。别调到 180s 以下。
+const INJECT_TIMEOUT_MS = Number(process.env.PROXY_INJECT_TIMEOUT_MS) || 240_000
+
+// ── footprint-0 交付注入（#1756 Layer 1a）─────────────────────────────────────────────────────────
+// 交付/orphan 不再每图新开 key-only session（connect-per-call，抢 KEY_ONLY_SESSION_CAP 槽），而是把
+// execute/canvas_edit 的 tools/call **注入到 proxy 已建好、已计入 cap 的那条 upstream 连接**上（footprint
+// 0）——即便 cap 被泄漏填满也能交付。注入用字符串 id 命名空间 `gemus-bf-*`（绝不撞 Codex 的数字 id），
+// 响应在 upstream.onmessage 里按 id 自消费、不转发给 Codex。`upstream` 在下方声明，注入在 turn 末才调，
+// 故闭包内按调用时解析、无 TDZ 问题。
+/** in-flight 注入：id(string) → { settle }。settle 幂等收敛（响应/超时/取消/关停任一先到即结算）。 */
+const pendingInjections = new Map()
+let injectSeq = 0
+
+/** 把 JSON-RPC 响应转成与 core `callGemusTool` 逐字一致的 CallGemusToolResult 形状。 */
+function interpretInjection(m) {
+  if (m?.error) return { ok: false, error: m.error.message || `MCP error ${m.error.code}` }
+  const result = m?.result
+  if (result && result.isError === true) {
+    const first = Array.isArray(result.content) ? result.content[0] : undefined
+    return { ok: false, error: (first && first.text) || 'MCP tool error' }
+  }
+  return { ok: true, result: unwrapMcpContent(result && result.content) }
+}
+
+/** @type {import('@gemus/codex-backfill-core').GemusToolCall} */
+function injectedCall(toolName, args, opts = {}) {
+  const { progressToken, signal } = opts
+  const id = `gemus-bf-${++injectSeq}`
+  const req = {
+    jsonrpc: '2.0',
+    id,
+    method: 'tools/call',
+    params: { name: toolName, arguments: args, ...(progressToken ? { _meta: { progressToken } } : {}) },
+  }
+  return new Promise((resolve) => {
+    const settle = (v) => {
+      clearTimeout(timer)
+      if (signal) signal.removeEventListener('abort', onAbort)
+      pendingInjections.delete(id)
+      resolve(v)
+    }
+    const onAbort = () => settle({ ok: false, error: 'aborted' })
+    const timer = setTimeout(() => settle({ ok: false, timedOut: true, error: 'inject timeout' }), INJECT_TIMEOUT_MS)
+    pendingInjections.set(id, { settle })
+    if (signal) signal.addEventListener('abort', onAbort)
+    upstream.send(req).catch((e) => settle({ ok: false, error: String(e) }))
+    log('INJECT', { id, toolName, progressToken })
+  })
+}
+
+const backfiller = createBackfiller({
+  server: SERVER_ORIGIN,
+  apiKey: KEY,
+  codexHome: CODEX_HOME,
+  call: injectedCall,
+  log: (msg, obj) => log('BACKFILL', obj ? `${msg} ${JSON.stringify(obj)}` : msg),
+})
+
+// ── turn identity + request↔response correlation ───────────────────────────────────────────────
+// Step-0.4 capture: tool-call `_meta` + Stop-hook payload both carry `turn_id` + `session_id` (no
+// thread_id). Turn state keys on turn_id; session_id locates the rollout in the idle fallback.
+/** in-flight tools/call: jsonrpc id (string) → { turnKey, name } — so the server→client response
+ * (which carries no _meta) can be attributed to its turn + tool. */
+const inflight = new Map()
+/** per-turn idle timer — turn-END fallback when no Stop hook fires (untrusted). Reset on activity. */
+const idleTimers = new Map()
+let sessionId // learned from first tool-call _meta.session_id; used for the hook discovery file
+let discoveryFile // <tmpdir>/gemus-proxy-<sessionId>.json — written once sessionId is known
+
+function metaOf(msg) {
+  const meta = msg?.params?._meta?.['x-codex-turn-metadata']
+  return {
+    turnId: meta?.turn_id || meta?.turnId,
+    sessionId: meta?.session_id || meta?.sessionId,
+  }
+}
+
+function armIdleTimer(turnKey) {
+  if (!turnKey) return
+  const existing = idleTimers.get(turnKey)
+  if (existing) clearTimeout(existing)
+  const timer = setTimeout(() => {
+    idleTimers.delete(turnKey)
+    // salvageOnly fallback: turn went quiet with no Stop hook. Orphan any fresh images (never claim).
+    // seen-set makes this a no-op if a hook already backfilled this turn.
+    backfiller
+      .backfillTurn({ turnKey, rolloutPath: null, salvageOnly: true })
+      .catch((e) => log('IDLE-BACKFILL-ERR', String(e)))
+  }, IDLE_MS)
+  if (typeof timer.unref === 'function') timer.unref() // don't keep the process alive on this timer alone
+  idleTimers.set(turnKey, timer)
+}
+
+function writeDiscoveryOnce() {
+  if (discoveryFile || !sessionId || !hookPort || !hookToken) return
+  discoveryFile = path.join(os.tmpdir(), `gemus-proxy-${sessionId}.json`)
+  try {
+    fs.writeFileSync(discoveryFile, JSON.stringify({ port: hookPort, token: hookToken }))
+    log('DISCOVERY-WRITE', { discoveryFile, port: hookPort })
+  } catch (e) {
+    log('DISCOVERY-ERR', String(e))
+  }
+}
+
+// injectSteering (imported) mutates the initialize response's `instructions` to tell codex not to
+// self-forward imagegen output — the one always-on steering channel in Mode B. See backfill.mjs.
+function steerOnInit(msg) {
+  try {
+    if (injectSteering(msg)) log('STEERING-INJECTED', { instructionsLen: msg.result.instructions.length })
+  } catch (e) {
+    log('STEERING-ERR', String(e))
+  }
+}
+
+// ── taps (do not mutate the relayed messages) ──────────────────────────────────────────────────
+function tapClientToServer(msg) {
+  try {
+    if (msg?.method !== 'tools/call') return
+    const { turnId, sessionId: sid } = metaOf(msg)
+    if (sid && !sessionId) {
+      sessionId = sid
+      writeDiscoveryOnce()
+    }
+    if (turnId) armIdleTimer(turnId)
+    const id = msg.id
+    if (id === undefined || id === null) return // notifications: no response to correlate
+    const name = msg.params?.name || ''
+    inflight.set(String(id), { turnKey: turnId, name })
+    backfiller.observeCall({ jsonrpcId: id, turnKey: turnId, sessionId: sid, name, args: msg.params?.arguments || {} })
+  } catch (e) {
+    log('TAP-C2S-ERR', String(e))
+  }
+}
+
+function tapServerToClient(msg) {
+  try {
+    const id = msg?.id
+    if (id === undefined || id === null) return
+    const pending = inflight.get(String(id))
+    if (!pending) return
+    inflight.delete(String(id))
+    if (!msg.result) return // errors: nothing to observe for claim tracking
+    backfiller.observeResult({
+      jsonrpcId: id,
+      turnKey: pending.turnKey,
+      name: pending.name,
+      resultContent: msg.result?.content,
+    })
+  } catch (e) {
+    log('TAP-S2C-ERR', String(e))
+  }
+}
+
+// ── loopback Stop-hook endpoint (127.0.0.1:<random port> + per-run token) ──────────────────────
+let hookPort
+const hookToken = randomBytes(16).toString('hex')
+const hookServer = http.createServer((req, res) => {
+  if (req.method !== 'POST' || !req.url?.startsWith('/backfill')) {
+    res.writeHead(404).end()
+    return
+  }
+  let body = ''
+  req.on('data', (c) => {
+    body += c
+    if (body.length > 64 * 1024) req.destroy() // trivial DoS guard; payload is tiny JSON
+  })
+  req.on('end', () => {
+    let payload
+    try {
+      payload = JSON.parse(body)
+    } catch {
+      res.writeHead(400).end()
+      return
+    }
+    if (payload?.token !== hookToken) {
+      res.writeHead(403).end()
+      return
+    }
+    // Stop-hook payload (Step-0.4 capture): { session_id, turn_id, transcript_path, ... } — no thread_id.
+    const turnKey = payload.turn_id || payload.turnId
+    const sid = payload.session_id || payload.sessionId
+    const rolloutPath = payload.transcript_path || payload.transcriptPath || null
+    log('HOOK-BACKFILL', { turnKey, sid, rolloutPath })
+    res.writeHead(200).end('ok')
+    // A Stop hook backfilled this turn → cancel its idle-timer fallback (avoid a redundant salvage pass).
+    const timer = idleTimers.get(turnKey)
+    if (timer) { clearTimeout(timer); idleTimers.delete(turnKey) }
+    // Stop hook fires post-flush → claim path (not salvage). Fire-and-forget; never throw.
+    backfiller
+      .backfillTurn({ turnKey, sessionId: sid, rolloutPath, salvageOnly: false })
+      .catch((e) => log('HOOK-BACKFILL-ERR', String(e)))
+  })
+})
+hookServer.on('error', (error) => {
+  if (shutdownRequested) return
+  void terminateFatally(error)
+})
+hookServer.listen(0, '127.0.0.1', () => {
+  hookPort = hookServer.address().port
+  log('HOOK-SERVER', { port: hookPort })
+  writeDiscoveryOnce() // in case sessionId was already learned before listen resolved
+})
+if (typeof hookServer.unref === 'function') hookServer.unref()
+
+// ── transparent JSON-RPC passthrough (raw send/onmessage) ──────────────────────────────────────
+const stdio = new StdioServerTransport()
+const initializingIds = new Set()
+const classifiedInitializeFailures = new Set()
+
+// #2068 fail-fast: StreamableHTTPClientTransport.send() resolves before the upstream SSE result
+// arrives and only surfaces a stream death via a global, id-less `onerror` (no reconnect for POST).
+// The custom `fetch` wrapper parses each request's JSON-RPC id and, if the response stream dies
+// before that id's result crosses the wire, injects a JSON-RPC error so Codex fails in <2s instead
+// of hanging to its 300s timeout. onLost only injects to stdio — it does NOT tap: tapping here would
+// delete the proxy's `inflight` entry, so the DROP-AFTER-FAILFAST branch below could no longer let
+// backfill observe a late real result (env delivery on the still-open, idle-timed-out case).
+const upstreamHttp = createUpstreamHttp()
+const failFast = createFailFast({
+  idleTimeoutMs: Number(process.env.PROXY_FAILFAST_TIMEOUT_MS) || 120_000,
+  realFetch: upstreamHttp.fetch,
+  log,
+  onLost: (id, failure) => {
+    const { response, diagnostic } = createProxyFailure(id, failure)
+    const key = String(id)
+    log('FAILFAST-INJECT', diagnostic)
+    if (initializingIds.has(key)) {
+      classifiedInitializeFailures.add(key)
+      void terminateFatally(new Error(response.error.message))
+      return
+    }
+    stdio.send(response).catch((e) => log('ERR-stdio-send', String(e)))
+  },
+})
+
+const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
+  requestInit: { headers: buildProxyUpstreamHeaders(KEY) },
+  fetch: failFast.fetch,
+})
+
+stdio.onmessage = (m) => {
+  tapClientToServer(m)
+  log('C->G', m)
+  const key = String(m?.id)
+  if (m?.method === 'initialize') initializingIds.add(key)
+  upstream.send(m).catch((error) => {
+    const classified = classifiedInitializeFailures.delete(key)
+    initializingIds.delete(key)
+    if (m?.method === 'initialize') {
+      if (classified) return
+      void terminateFatally(error)
+      return
+    }
+    log('ERR-http-send', { kind: 'transport' })
+  })
+}
+upstream.onmessage = (m) => {
+  // footprint-0 (#1756): our injected execute/canvas_edit responses carry a `gemus-bf-*` string id.
+  // Self-consume them here (settle the pending injection) and DO NOT forward to Codex — Codex never
+  // issued these calls, so it must never see the responses.
+  if (typeof m?.id === 'string' && m.id.startsWith('gemus-bf-')) {
+    const p = pendingInjections.get(m.id)
+    if (p) p.settle(interpretInjection(m))
+    return
+  }
+  // #1756 liveness heartbeat: our own `ping` pongs (gemus-ping-*) are self-consumed — Codex never
+  // issued them, so it must never see the responses.
+  if (typeof m?.id === 'string' && m.id.startsWith('gemus-ping-')) return
+  // #2068 fail-fast bookkeeping. Gate on RESPONSE only (isJsonRpcResponse) — a server→client request
+  // (elicitation/sampling) also carries an id that can collide with an in-flight tools/call id, and
+  // must be forwarded to Codex untouched, never settled/dropped.
+  if (isJsonRpcResponse(m)) {
+    initializingIds.delete(String(m.id))
+    if (failFast.failedIds.has(String(m.id))) {
+      // Already fail-fasted (idle timeout on a still-open stream) → Codex got the error. Still tap so
+      // backfill (#1751) observes the late real result (inflight survives — onLost didn't tap), but
+      // do NOT re-forward it to Codex (no double-send). forget() bounds failedIds.
+      tapServerToClient(m); failFast.forget(m.id); log('DROP-AFTER-FAILFAST', m.id); return
+    }
+    failFast.settle(m.id)
+  }
+  tapServerToClient(m); steerOnInit(m); log('G->C', m); stdio.send(m).catch((e) => log('ERR-stdio-send', String(e)))
+}
+
+// ── session hygiene (spike: KEY_ONLY_SESSION_CAP=3) ────────────────────────────────────────────
+// We must DELETE the upstream session or we leak a key-only slot when codex ends the conversation.
+// NOTE: transport.close() does NOT issue DELETE (it only aborts + fires onclose, streamableHttp.js:280);
+// terminateSession() sends the DELETE (:431). Call it first, then close(). Also clean up local artifacts.
+// #1756 proxy-death detection: send an MCP `ping` every 30s so the platform can tell a live proxy
+// (keeps pinging) from a dead one (hard-killed → no graceful DELETE → leaked session). This is
+// **independent of Codex tool activity**, so a proxy mid-imagegen (silent to Codex for minutes) still
+// proves liveness → the platform reclaims only genuinely-dead sessions (short floor), never a live one.
+const HEARTBEAT_MS = Number(process.env.PROXY_HEARTBEAT_MS) || 30_000
+const SHUTDOWN_STEP_TIMEOUT_MS = 2000
+let pingSeq = 0
+let heartbeatTimer
+function startHeartbeat() {
+  heartbeatTimer = setInterval(() => {
+    upstream.send({ jsonrpc: '2.0', id: `gemus-ping-${++pingSeq}`, method: 'ping' }).catch((e) => log('PING-ERR', String(e)))
+  }, HEARTBEAT_MS)
+  if (typeof heartbeatTimer.unref === 'function') heartbeatTimer.unref() // don't keep the process alive on this alone
+}
+
+async function cleanup() {
+  if (heartbeatTimer) clearInterval(heartbeatTimer)
+  for (const t of idleTimers.values()) clearTimeout(t)
+  idleTimers.clear()
+  // Settle any in-flight footprint-0 injections so a mid-delivery shutdown doesn't hang their awaits.
+  for (const p of pendingInjections.values()) p.settle({ ok: false, error: 'proxy shutting down' })
+  pendingInjections.clear()
+  failFast.dispose() // #2068: clear fail-fast final-safety timers
+  try { hookServer.close() } catch { /* ignore */ }
+  if (discoveryFile) { try { fs.unlinkSync(discoveryFile) } catch { /* ignore */ } }
+  await settleWithin(
+    Promise.resolve().then(() => upstream.terminateSession()),
+    SHUTDOWN_STEP_TIMEOUT_MS,
+  )
+  await settleWithin(
+    Promise.resolve().then(() => upstream.close()),
+    SHUTDOWN_STEP_TIMEOUT_MS,
+  )
+  try { await upstreamHttp.shutdown() } catch { /* ignore */ }
+}
+shutdown = createShutdownCoordinator({
+  cleanup,
+  exit: (code) => process.exit(code),
+})
+function shutdownGracefully() {
+  shutdownRequested = true
+  return shutdown(0)
+}
+stdio.onclose = () => { log('stdio-close', ''); void shutdownGracefully() }
+upstream.onclose = () => { log('http-close', '') }
+stdio.onerror = (e) => log('stdio-err', String(e))
+upstream.onerror = () => log('http-err', { kind: 'transport' })
+process.on('SIGTERM', () => { void shutdownGracefully() })
+process.on('SIGINT', () => { void shutdownGracefully() })
+
+try {
+  await startProxy({
+    key: KEY,
+    upstream,
+    stdio,
+    onStarted: () => {
+      if (shutdownRequested) return
+      startHeartbeat()
+      log('STARTED', {
+        endpoint: safeEndpointLabel(GEMUS_URL),
+        hasKey: Boolean(KEY),
+        pid: process.pid,
+        idleMs: IDLE_MS,
+        heartbeatMs: HEARTBEAT_MS,
+      })
+    },
+  })
+} catch (error) {
+  await terminateFatally(error)
+}

package/src/setup/cli.mjs

@@ -0,0 +1,130 @@
+import { pathToFileURL } from 'node:url'
+import { acquireGemusSecret } from './secret.mjs'
+import { installGemusEnvironment } from './environment.mjs'
+import { inspectCodexConfig, planCodexConfigMigration } from './config.mjs'
+import { CodexConfigChangedError, commitCodexConfig, preflightCodexConfig } from './configFile.mjs'
+import { createCodexRunner, reconcileCodex } from './codex.mjs'
+
+const MAX_STALE_REPLANS = 2
+
+class CredentialChangedError extends Error {
+  constructor() {
+    super('Codex credential settings changed during setup; rerun setup to use the latest credentials.')
+    this.code = 'CODEX_CREDENTIALS_CHANGED'
+  }
+}
+
+function redact(text, secrets) {
+  let result = String(text ?? '')
+  for (const secret of secrets) {
+    if (typeof secret === 'string' && secret) result = result.split(secret).join('[redacted]')
+  }
+  return result
+}
+
+function safeSetupError(error, secrets, lastCompletedPhase) {
+  const message = redact(error?.message, secrets)
+  let summary
+  if (error?.code === 'CODEX_CREDENTIALS_CHANGED') summary = message
+  else if (/supports only/i.test(message)) summary = message
+  else if (/^Codex \w+ failed \(exit \d+\)\.$/.test(message)) {
+    summary = `Gemus Companion setup failed during ${message} Verify Codex Desktop.`
+  } else if (/Codex/i.test(message)) {
+    summary = 'Gemus Companion setup failed: Codex could not be reconciled. Verify Codex Desktop.'
+  } else if (/GEMUS_KEY is required/i.test(message)) summary = message
+  else summary = 'Gemus Companion setup failed. No configuration changes were committed.'
+  return `${summary} Last completed phase: ${lastCompletedPhase}. It is safe to rerun setup.`
+}
+
+export function validateSetupArgs(args = []) {
+  if (!Array.isArray(args) || args.length !== 0) throw new Error('Usage: gemus-mcp-proxy setup (no arguments accepted).')
+}
+
+export async function runSetup(deps = {}) {
+  const env = deps.env ?? process.env
+  const platform = deps.platform ?? process.platform
+  const stdout = deps.stdout ?? process.stdout
+  let lastCompletedPhase = 'none'
+  if (platform !== 'win32' && platform !== 'darwin') {
+    throw new Error(safeSetupError(
+      new Error('Gemus Companion setup supports only Windows and macOS.'),
+      [env.GEMUS_KEY, env.GEMUS_URL],
+      lastCompletedPhase,
+    ))
+  }
+  const preflight = deps.preflightCodexConfig ?? preflightCodexConfig
+  const readConfig = deps.readConfig ?? (async () => (await preflight({ env })).source)
+  const runReconcile = deps.reconcileCodex ?? ((options) => reconcileCodex({ run: createCodexRunner(options) }))
+  const commit = deps.commitCodexConfig ?? commitCodexConfig
+  const acquire = deps.acquireGemusSecret ?? acquireGemusSecret
+  const install = deps.installGemusEnvironment ?? installGemusEnvironment
+
+  let initialSource
+  let initialSecret
+  let initialInspection
+  try {
+    initialSource = (await preflight({ env })).source
+    initialInspection = inspectCodexConfig(initialSource)
+    if (initialInspection.issues.length) throw new Error('Codex configuration contains unsupported Gemus settings.')
+    lastCompletedPhase = 'config preflight'
+    initialSecret = await acquire({ env, legacyKey: initialInspection.legacyKey, legacyUrl: initialInspection.legacyUrl, stdin: deps.stdin, stdout })
+    lastCompletedPhase = 'credential acquisition'
+    await runReconcile({ env, platform })
+    lastCompletedPhase = 'Codex reconciliation'
+  } catch (error) {
+    throw new Error(safeSetupError(error, [env.GEMUS_KEY, env.GEMUS_URL], lastCompletedPhase))
+  }
+
+  let environmentInstalled = false
+  for (let attempt = 0; attempt <= MAX_STALE_REPLANS; attempt += 1) {
+    let source
+    let migration
+    try {
+      source = await readConfig()
+      migration = planCodexConfigMigration(source)
+      const keyFromEnv = env.GEMUS_KEY !== undefined && env.GEMUS_KEY !== ''
+      const urlFromEnv = env.GEMUS_URL !== undefined && env.GEMUS_URL !== ''
+      if ((!keyFromEnv && migration.legacyKey !== initialInspection.legacyKey) || (!urlFromEnv && migration.legacyUrl !== initialInspection.legacyUrl)) {
+        throw new CredentialChangedError()
+      }
+      lastCompletedPhase = 'latest config planning'
+      if (!environmentInstalled) {
+        await install({ key: initialSecret.key, url: initialSecret.url, platform, stdout, parentEnv: env })
+        environmentInstalled = true
+      }
+      lastCompletedPhase = 'environment installation'
+      const committed = await commit({ expectedSource: source, nextText: migration.nextText, env })
+      lastCompletedPhase = 'config commit'
+      if (committed.backupPath) {
+        if (migration.legacyKeyWasPresent) {
+          stdout?.write(
+            `Warning: the faithful legacy backup may contain the old GEMUS_KEY. Backup path: ${committed.backupPath}\n`,
+          )
+        } else {
+          stdout?.write(`A backup of your previous Codex configuration was created: ${committed.backupPath}\n`)
+        }
+      }
+      stdout?.write('Gemus Companion is ready. Restart Codex Desktop to use it.\n')
+      return committed
+    } catch (error) {
+      if ((error instanceof CodexConfigChangedError || error?.code === 'CODEX_CONFIG_CHANGED') && attempt < MAX_STALE_REPLANS) continue
+      throw new Error(safeSetupError(
+        error,
+        [env.GEMUS_KEY, env.GEMUS_URL, initialSecret?.key, initialSecret?.url, migration?.legacyKey, migration?.legacyUrl],
+        lastCompletedPhase,
+      ))
+    }
+  }
+}
+
+async function main() {
+  try {
+    validateSetupArgs(process.argv.slice(2))
+    await runSetup()
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = 1
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) void main()