@gemus/mcp-proxy 0.1.7 → 0.1.8

package/README.md

@@ -1,9 +1,10 @@
 # @gemus/mcp-proxy (Issues #1751, #1756, #1917)
 
 Local stdio↔HTTP MCP proxy that gives **Codex desktop (direct-connect / Mode B)** users canvas
-image write-back. Bundled into the Codex plugin (`.codex-plugin/`), declared as a **command-based**
-MCP server so codex spawns it locally; the proxy owns upstream auth to the remote gemus `/api/mcp`
-(Codex does no OAuth for stdio servers). Full design: `docs/plans/1751-codex-desktop-companion.md`
+image write-back. The Codex plugin declares it as a **default-disabled, command-based** MCP server
+so Codex can spawn it locally after explicit enablement; the proxy owns upstream auth to the remote
+Gemus `/api/mcp` (Codex does no OAuth for stdio servers). Full design:
+`docs/plans/1751-codex-desktop-companion.md`
 and `docs/architecture/agent architecture/codex-desktop-companion.md`.
 
 ## Status: implemented
@@ -27,24 +28,55 @@ server blueprint policy.
 - **(c) turn-end + retrieval** — `Stop` hook fires post-flush carrying `transcript_path` → exact
   rollout; imagegen writes `generated_images/<session>/<sanitized-call-id>.png` (historically `ig_*`,
   currently `call_*`) + rollout `saved_path`+base64.
-- **Session cap** — `KEY_ONLY_SESSION_CAP=3`/user is real; the proxy MUST `DELETE` its upstream
-  session on close (implemented in `shutdown()`) to avoid leaking slots.
+- **Session cap** — the key-only session cap defaults to 10 concurrent sessions per user
+  (`MCP_KEY_ONLY_SESSION_CAP`); the proxy MUST `DELETE` its upstream session on close (implemented
+  in `cleanup()`) to avoid leaking slots.
 
-## Install (Codex desktop)
+## Companion setup and migration (Codex desktop)
 
-The key is supplied as a **literal** in the user's *local* codex config — codex does NOT interpolate
-`${VAR}` in an MCP server's `env`, and a public plugin manifest must never carry a key (Step-0.4
-findings). So the keyed MCP server is registered locally, not via the plugin manifest:
+The plugin owns the non-secret process contract: exact `@gemus/mcp-proxy@0.1.8`,
+`startup_timeout_sec = 60`, `tool_timeout_sec = 300`, and a default-disabled rollout. The user
+environment owns `GEMUS_KEY` and optional `GEMUS_URL`; the public plugin and generated commands
+never contain their values.
 
-```bash
-# 1. Register the proxy as codex's gemus MCP server (writes a literal key into ~/.codex/config.toml).
-codex mcp add gemus --env GEMUS_KEY=mak_<your key> -- npx -y @gemus/mcp-proxy
-#    (get a mak_ key from gemus.ai → Settings → MCP Keys; GEMUS_URL defaults to https://gemus.ai/api/mcp)
-
-# 2. Install the plugin (Stop hook + skills) from the gemus marketplace, then TRUST the hook:
-codex plugin add gemus@<marketplace>
-#    In interactive codex run `/hooks` and trust the gemus Stop hook — REQUIRED for canvas backfill.
-#    Without a trusted hook, images still land on the canvas (orphan node), just not the planned node.
+Environment ownership and lifetime:
+
+- **Windows / PowerShell:** persist the key in the Windows user environment and refresh the current
+  process.
+- **macOS:** If changing login context, sign out and back in first; rerun the `launchctl setenv`
+  setup in the new login session; then fully quit and restart Codex and open a new task.
+- **Linux:** export the key and launch Codex from the same terminal; no universal desktop-session
+  inheritance is assumed.
+
+Companion and direct modes are mutually exclusive. The canonical new-user and legacy migration flow
+is:
+
+1. Set `GEMUS_KEY` in the user environment.
+2. Remove any legacy global server (`codex mcp remove gemus`; not-found is harmless).
+3. Install with `codex plugin marketplace add Gemus-AI/gemus-codex-plugin`, then
+   `codex plugin add gemus@gemus`. Existing users refresh the marketplace snapshot and replace the
+   installed cache:
+
+   ```bash
+   codex plugin marketplace upgrade gemus
+   codex plugin remove gemus@gemus
+   codex plugin add gemus@gemus
+   ```
+4. Explicitly enable the plugin-scoped server:
+
+   ```toml
+   [plugins."gemus@gemus".mcp_servers.gemus]
+   enabled = true
+   ```
+
+5. Restart Codex and open a new task, then use `/hooks` to trust the Stop hook separately.
+
+Intentional direct HTTP/OAuth users keep their global direct server and leave the plugin Companion
+disabled:
+
+```toml
+[plugins."gemus@gemus".mcp_servers.gemus]
+enabled = false
 ```
 
 ## Local dev
@@ -52,7 +84,6 @@ codex plugin add gemus@<marketplace>
 ```bash
 pnpm --filter @gemus/codex-backfill-core build          # proxy imports the built core at runtime
 GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp PROXY_LOG=/tmp/proxy.log node src/proxy.mjs
-# or register against dev:  codex mcp add gemus --env GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp -- node <abs>/src/proxy.mjs
 ```
 
 Env: `GEMUS_KEY` (required), `GEMUS_URL` (default `https://gemus.ai/api/mcp`), `PROXY_LOG` (optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Local stdio<->HTTP MCP proxy for Codex desktop: transparent passthrough + execute tap + imagegen backfill (Issue #1751, P1).",
   "type": "module",
   "bin": {

package/src/__tests__/fixtures/proxy-runtime-loader.mjs

@@ -0,0 +1,136 @@
+function moduleUrl(source) {
+  return `data:text/javascript,${encodeURIComponent(source)}`
+}
+
+const markerPrelude = `
+  import fs from 'node:fs'
+  function mark(name) {
+    const file = process.env.PROXY_TEST_CONSTRUCTION_LOG
+    if (file) fs.appendFileSync(file, name + '\\n')
+  }
+`
+
+const modules = new Map([
+  ['@gemus/codex-backfill-core', `
+    export const CLIENT_CAPABILITIES = []
+    export const CLIENT_CAPABILITIES_HEADER = 'X-Gemus-Client-Capabilities'
+    export function serializeClientCapabilities(value) { return JSON.stringify(value) }
+    export function unwrapMcpContent(value) { return value }
+  `],
+  ['@modelcontextprotocol/sdk/server/stdio.js', `
+    ${markerPrelude}
+    export class StdioServerTransport {
+      constructor() { mark('stdio-transport') }
+      async start() {
+        if (process.env.PROXY_TEST_STDIO_START_FAILURE === '1') {
+          this.onclose?.()
+          throw new Error(
+            'stdio failed Authorization: Bearer '
+            + process.env.GEMUS_KEY
+            + ' at '
+            + process.env.GEMUS_URL
+          )
+        }
+        if (process.env.PROXY_TEST_FORWARD_STDIN === '1') {
+          let input = ''
+          process.stdin.setEncoding('utf8')
+          process.stdin.on('data', (chunk) => {
+            input += chunk
+            for (;;) {
+              const newline = input.indexOf('\\n')
+              if (newline < 0) break
+              const line = input.slice(0, newline).trim()
+              input = input.slice(newline + 1)
+              if (line) this.onmessage?.(JSON.parse(line))
+            }
+          })
+        }
+        process.stdin.resume()
+        process.stdin.once('end', () => this.onclose?.())
+      }
+      async send() {}
+    }
+  `],
+  ['@modelcontextprotocol/sdk/client/streamableHttp.js', `
+    ${markerPrelude}
+    export class StreamableHTTPClientTransport {
+      constructor() { mark('upstream-transport') }
+      async start() {}
+      async send(message) {
+        if (
+          process.env.PROXY_TEST_UPSTREAM_INITIALIZE_FAILURE === '1'
+          && message?.method === 'initialize'
+        ) {
+          throw new Error(
+            'initialize fetch failed Authorization: Bearer '
+            + process.env.GEMUS_KEY
+            + ' at '
+            + process.env.GEMUS_URL
+          )
+        }
+      }
+      async terminateSession() {}
+      async close() {}
+    }
+  `],
+  ['node:http', `
+    ${markerPrelude}
+    function hookError() {
+      return new Error(
+        'hook listen failed Authorization: Bearer '
+        + process.env.GEMUS_KEY
+        + ' at '
+        + process.env.GEMUS_URL
+      )
+    }
+    const http = {
+      createServer() {
+        mark('hook-server')
+        const listeners = new Map()
+        return {
+          on(event, handler) { listeners.set(event, handler); return this },
+          listen(_port, _host, callback) {
+            if (process.env.PROXY_TEST_HOOK_LISTEN_FAILURE === '1') {
+              queueMicrotask(() => listeners.get('error')?.(hookError()))
+            } else {
+              queueMicrotask(callback)
+            }
+            return this
+          },
+          address() { return { port: 43114 } },
+          unref() {},
+          close() {
+            mark('hook-server-close')
+            if (process.env.PROXY_TEST_HOOK_ERROR_AFTER_CLOSE === '1') {
+              queueMicrotask(() => listeners.get('error')?.(hookError()))
+            }
+          },
+        }
+      },
+    }
+    export default http
+  `],
+  ['./backfill.mjs', `
+    ${markerPrelude}
+    export function createBackfiller() {
+      mark('backfiller')
+      return {
+        observeCall() {},
+        observeResult() {},
+        async backfillTurn() {},
+      }
+    }
+    export function injectSteering() { return false }
+  `],
+])
+
+export async function resolve(specifier, context, nextResolve) {
+  const source = modules.get(specifier)
+  if (
+    source !== undefined
+    && (specifier !== './backfill.mjs' || context.parentURL?.endsWith('/proxy.mjs'))
+  ) {
+    return { url: moduleUrl(source), shortCircuit: true }
+  }
+  return nextResolve(specifier, context)
+}

package/src/__tests__/startup.test.ts

@@ -0,0 +1,558 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  assertGemusKey,
+  createFatalReporter,
+  safeEndpointLabel,
+  sanitizeStartupError,
+  startProxy,
+} from '../startup.mjs'
+
+const PROXY_PATH = path.resolve(
+  process.cwd(),
+  'packages/gemus-mcp-proxy/src/proxy.mjs',
+)
+const PROXY_RUNTIME_LOADER_PATH = path.resolve(
+  process.cwd(),
+  'packages/gemus-mcp-proxy/src/__tests__/fixtures/proxy-runtime-loader.mjs',
+)
+const PROXY_RUNTIME_LOADER_URL = pathToFileURL(PROXY_RUNTIME_LOADER_PATH).href
+
+async function readFileOrEmpty(file: string) {
+  try {
+    return await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
+    throw error
+  }
+}
+
+async function runProxy(
+  envOverrides: NodeJS.ProcessEnv,
+  {
+    closeStdinAfterMs = 600,
+    input,
+  }: {
+    closeStdinAfterMs?: number
+    input?: Record<string, unknown>
+  } = {},
+) {
+  const env = { ...process.env, ...envOverrides }
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) delete env[key]
+  }
+
+  return await new Promise<{
+    code: number | null
+    signal: NodeJS.Signals | null
+    stdout: string
+    stderr: string
+  }>((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      ['--no-warnings', '--experimental-loader', PROXY_RUNTIME_LOADER_URL, PROXY_PATH],
+      {
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    )
+    let stdout = ''
+    let stderr = ''
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', (chunk) => { stdout += chunk })
+    child.stderr.on('data', (chunk) => { stderr += chunk })
+    child.on('error', reject)
+    if (input) child.stdin.write(`${JSON.stringify(input)}\n`)
+
+    const closeTimer = setTimeout(() => child.stdin.end(), closeStdinAfterMs)
+    const killTimer = setTimeout(() => child.kill(), 5_000)
+    child.on('close', (code, signal) => {
+      clearTimeout(closeTimer)
+      clearTimeout(killTimer)
+      resolve({ code, signal, stdout, stderr })
+    })
+  })
+}
+
+describe('assertGemusKey', () => {
+  it('rejects a missing GEMUS_KEY with actionable restart guidance', () => {
+    expect(() => assertGemusKey('')).toThrow(
+      'GEMUS_KEY is required. Set it in your user environment and restart Codex.',
+    )
+  })
+})
+
+describe('sanitizeStartupError', () => {
+  it('keeps the missing-key diagnostic readable when the configured secret is empty', () => {
+    expect(
+      sanitizeStartupError(
+        new Error('GEMUS_KEY is required. Set it in your user environment and restart Codex.'),
+        { secret: '' },
+      ),
+    ).toBe(
+      'Gemus MCP proxy failed to start: GEMUS_KEY is required. Set it in your user environment and restart Codex.',
+    )
+  })
+
+  it('redacts the exact configured secret regardless of its shape', () => {
+    const secret = 'arbitrary-secret-without-known-prefix'
+    const output = sanitizeStartupError(new Error(`upstream rejected ${secret}`), { secret })
+
+    expect(output).toBe('Gemus MCP proxy failed to start: upstream rejected [REDACTED]')
+    expect(output).not.toContain(secret)
+  })
+
+  it.each([
+    ['mak_ token', 'request rejected mak_AbC123-._~+/=', 'request rejected [REDACTED]'],
+    ['Bearer token', 'Authorization: Bearer opaque-token', 'Authorization: Bearer [REDACTED]'],
+    ['authorization header', 'Authorization: opaque-token', 'Authorization: [REDACTED]'],
+    ['API key header', 'X-API-Key=opaque-token', 'X-API-Key=[REDACTED]'],
+  ])('redacts a %s while preserving non-sensitive context', (_label, input, expected) => {
+    const output = sanitizeStartupError(new Error(input), { secret: 'different-secret' })
+
+    expect(output).toBe(`Gemus MCP proxy failed to start: ${expected}`)
+    expect(output).toContain('request rejected'.includes(expected) ? 'request rejected' : expected.split(/[:=]/)[0])
+  })
+
+  it('removes URL userinfo, query, and fragment without hiding the safe endpoint context', () => {
+    const output = sanitizeStartupError(
+      new Error(
+        'connect ECONNREFUSED https://alice:p%40ss@example.test/api/mcp?token=query-secret#fragment-secret',
+      ),
+      { secret: 'unrelated-secret' },
+    )
+
+    expect(output).toBe(
+      'Gemus MCP proxy failed to start: connect ECONNREFUSED https://example.test/api/mcp',
+    )
+    expect(output).not.toMatch(/alice|p%40ss|query-secret|fragment-secret/)
+  })
+
+  it.each(['ftp', 'ws'])(
+    'sanitizes a credential-bearing %s URL while preserving its safe endpoint',
+    (scheme) => {
+      const output = sanitizeStartupError(
+        new Error(
+          `connect failed ${scheme}://alice:password@example.test/api/mcp?token=query-secret#fragment-secret`,
+        ),
+        { secret: 'unrelated-secret' },
+      )
+
+      expect(output).toBe(
+        `Gemus MCP proxy failed to start: connect failed ${scheme}://example.test/api/mcp`,
+      )
+      expect(output).not.toMatch(
+        /alice|password|query-secret|fragment-secret/,
+      )
+    },
+  )
+
+  it.each([
+    [
+      'quoted authorization',
+      'request failed Authorization: "Basic opaque credential" status=401',
+      'request failed Authorization: "Basic [REDACTED]" status=401',
+    ],
+    [
+      'JSON authorization',
+      'request failed {"authorization":"Bearer opaque-token"} status=401',
+      'request failed {"authorization":"Bearer [REDACTED]"} status=401',
+    ],
+    [
+      'quoted API key',
+      "request failed X-API-Key='opaque credential' status=401",
+      "request failed X-API-Key='[REDACTED]' status=401",
+    ],
+  ])('redacts %s values without consuming adjacent context', (_label, input, expected) => {
+    expect(sanitizeStartupError(new Error(input), { secret: '' })).toBe(
+      `Gemus MCP proxy failed to start: ${expected}`,
+    )
+  })
+})
+
+describe('safeEndpointLabel', () => {
+  it('returns only URL origin and path', () => {
+    expect(
+      safeEndpointLabel(
+        'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+      ),
+    ).toBe('https://example.test/api/mcp')
+  })
+})
+
+describe('createFatalReporter', () => {
+  it('writes one synchronous diagnostic when optional logging throws or fatal repeats', () => {
+    const writeStderr = vi.fn()
+    const writeLog = vi.fn(() => { throw new Error('unwritable log') })
+    const reportFatal = createFatalReporter({
+      secret: 'exact-secret',
+      writeStderr,
+      writeLog,
+    })
+
+    reportFatal(new Error('first failure exact-secret'))
+    reportFatal(new Error('second failure exact-secret'))
+
+    expect(writeStderr).toHaveBeenCalledTimes(1)
+    expect(writeStderr).toHaveBeenCalledWith(
+      'Gemus MCP proxy failed to start: first failure [REDACTED]\n',
+    )
+    expect(writeLog).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('startProxy', () => {
+  it('starts upstream before stdio and invokes the success callback last', async () => {
+    const events: string[] = []
+    const upstream = { start: vi.fn(async () => { events.push('upstream') }) }
+    const stdio = { start: vi.fn(async () => { events.push('stdio') }) }
+
+    await startProxy({
+      key: 'configured',
+      upstream,
+      stdio,
+      onStarted: () => { events.push('started') },
+    })
+
+    expect(events).toEqual(['upstream', 'stdio', 'started'])
+  })
+
+  it('does not construct startup work when GEMUS_KEY is missing', async () => {
+    const upstream = { start: vi.fn() }
+    const stdio = { start: vi.fn() }
+
+    await expect(
+      startProxy({ key: '', upstream, stdio, onStarted: vi.fn() }),
+    ).rejects.toThrow('GEMUS_KEY is required')
+    expect(upstream.start).not.toHaveBeenCalled()
+    expect(stdio.start).not.toHaveBeenCalled()
+  })
+
+  it('propagates an upstream startup error without starting stdio', async () => {
+    const error = new Error('upstream failed')
+    const upstream = { start: vi.fn().mockRejectedValue(error) }
+    const stdio = { start: vi.fn() }
+
+    await expect(
+      startProxy({ key: 'configured', upstream, stdio, onStarted: vi.fn() }),
+    ).rejects.toBe(error)
+    expect(stdio.start).not.toHaveBeenCalled()
+  })
+
+  it('propagates a stdio startup error without invoking the success callback', async () => {
+    const error = new Error('stdio failed')
+    const upstream = { start: vi.fn().mockResolvedValue(undefined) }
+    const stdio = { start: vi.fn().mockRejectedValue(error) }
+    const onStarted = vi.fn()
+
+    await expect(
+      startProxy({ key: 'configured', upstream, stdio, onStarted }),
+    ).rejects.toBe(error)
+    expect(onStarted).not.toHaveBeenCalled()
+  })
+})
+
+describe('createShutdownCoordinator', () => {
+  it('runs cleanup once and preserves a fatal exit requested during graceful close', async () => {
+    let releaseCleanup!: () => void
+    const cleanup = vi.fn(() => new Promise<void>((resolve) => {
+      releaseCleanup = resolve
+    }))
+    const exit = vi.fn()
+    const startup = await import('../startup.mjs') as typeof import('../startup.mjs') & {
+      createShutdownCoordinator?: (options: {
+        cleanup: () => Promise<void>
+        exit: (code: number) => void
+      }) => (code?: number) => Promise<void>
+    }
+
+    expect(startup.createShutdownCoordinator).toBeTypeOf('function')
+    const shutdown = startup.createShutdownCoordinator!({ cleanup, exit })
+    const graceful = shutdown(0)
+    const fatal = shutdown(1)
+
+    expect(cleanup).toHaveBeenCalledTimes(1)
+    expect(exit).not.toHaveBeenCalled()
+    releaseCleanup()
+    await Promise.all([graceful, fatal])
+
+    expect(exit).toHaveBeenCalledTimes(1)
+    expect(exit).toHaveBeenCalledWith(1)
+  })
+})
+
+describe('proxy process startup', () => {
+  it('fails before runtime construction when GEMUS_KEY is missing', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-startup-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: undefined,
+        GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: logPath,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+      })
+      const log = await readFileOrEmpty(logPath)
+      const constructionLog = await readFileOrEmpty(constructionLogPath)
+      const lines = log.trim().split(/\r?\n/)
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stdout).toBe('')
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: GEMUS_KEY is required. Set it in your user environment and restart Codex.\n',
+      )
+      expect(lines).toHaveLength(1)
+      expect(lines[0]).toContain('GEMUS_KEY is required')
+      expect(log).not.toMatch(/HOOK-SERVER|STARTED|alice|password|query-secret|fragment-secret/)
+      expect(constructionLog).toBe('')
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('logs a successful endpoint using only origin and path', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-started-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'configured-key',
+        GEMUS_URL: 'http://alice:password@127.0.0.1:1/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: logPath,
+      })
+      const log = await readFile(logPath, 'utf8')
+      const started = log.split(/\r?\n/).find((line) => line.includes('STARTED'))
+
+      expect(result.code).toBe(0)
+      expect(started).toContain('http://127.0.0.1:1/api/mcp')
+      expect(started).not.toMatch(/alice|password|query-secret|fragment-secret|userinfo|search|hash/)
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps exit code 1 when stdio onclose races with a startup error', async () => {
+    const secret = 'arbitrary-secret'
+    const result = await runProxy({
+      GEMUS_KEY: secret,
+      GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+      PROXY_LOG: undefined,
+      PROXY_TEST_STDIO_START_FAILURE: '1',
+    })
+
+    expect(result.code).toBe(1)
+    expect(result.signal).toBeNull()
+    expect(result.stderr).toContain('Gemus MCP proxy failed to start: stdio failed')
+    expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+    expect(result.stderr).toContain('https://example.test/api/mcp')
+    expect(result.stderr).not.toMatch(
+      /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+    )
+  })
+
+  it('exits non-zero when the first upstream initialize send fails', async () => {
+    const secret = 'arbitrary-secret'
+    const result = await runProxy(
+      {
+        GEMUS_KEY: secret,
+        GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: undefined,
+        PROXY_TEST_FORWARD_STDIN: '1',
+        PROXY_TEST_UPSTREAM_INITIALIZE_FAILURE: '1',
+      },
+      {
+        input: {
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: {
+            protocolVersion: '2025-06-18',
+            capabilities: {},
+            clientInfo: { name: 'startup-test', version: '1.0.0' },
+          },
+        },
+      },
+    )
+
+    expect(result.code).toBe(1)
+    expect(result.signal).toBeNull()
+    expect(result.stderr).toBe(
+      'Gemus MCP proxy failed to start: initialize fetch failed Authorization: Bearer [REDACTED] at https://example.test/api/mcp\n',
+    )
+    expect(result.stderr).not.toMatch(
+      /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+    )
+  })
+
+  it.each(['ftp', 'ws'])(
+    'sanitizes a credential-bearing %s endpoint in a real initialize failure',
+    async (scheme) => {
+      const secret = 'arbitrary-secret'
+      const endpoint = `${scheme}://alice:password@example.test/api/mcp?token=query-secret#fragment-secret`
+      const result = await runProxy(
+        {
+          GEMUS_KEY: secret,
+          GEMUS_URL: endpoint,
+          PROXY_LOG: undefined,
+          PROXY_TEST_FORWARD_STDIN: '1',
+          PROXY_TEST_UPSTREAM_INITIALIZE_FAILURE: '1',
+        },
+        {
+          input: {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+              protocolVersion: '2025-06-18',
+              capabilities: {},
+              clientInfo: { name: 'startup-test', version: '1.0.0' },
+            },
+          },
+        },
+      )
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        `Gemus MCP proxy failed to start: initialize fetch failed Authorization: Bearer [REDACTED] at ${scheme}://example.test/api/mcp\n`,
+      )
+      expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+      expect(result.stderr).not.toContain(endpoint)
+      expect(result.stderr).not.toMatch(
+        /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+      )
+    },
+  )
+
+  it('routes an asynchronous hook listen error through one sanitized fatal shutdown', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-hook-listen-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    const secret = 'arbitrary-secret'
+    const endpoint =
+      'ws://alice:password@example.test/api/mcp?token=query-secret#fragment-secret'
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: secret,
+        GEMUS_URL: endpoint,
+        PROXY_LOG: logPath,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+        PROXY_TEST_HOOK_LISTEN_FAILURE: '1',
+      })
+      const log = await readFileOrEmpty(logPath)
+      const constructionLog = await readFileOrEmpty(constructionLogPath)
+      const fatalLines = log
+        .split(/\r?\n/)
+        .filter((line) => line.includes(' FATAL '))
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: hook listen failed Authorization: Bearer [REDACTED] at ws://example.test/api/mcp\n',
+      )
+      expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+      expect(fatalLines).toHaveLength(1)
+      expect(log).not.toContain('STARTED')
+      expect(constructionLog.match(/hook-server-close/g)).toHaveLength(1)
+      for (const output of [result.stderr, log]) {
+        expect(output).not.toContain(endpoint)
+        expect(output).not.toMatch(
+          /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+        )
+      }
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('ignores a hook error emitted after graceful shutdown begins', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-hook-close-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    const endpoint =
+      'ws://alice:password@example.test/api/mcp?token=query-secret#fragment-secret'
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'arbitrary-secret',
+        GEMUS_URL: endpoint,
+        PROXY_LOG: logPath,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+        PROXY_TEST_HOOK_ERROR_AFTER_CLOSE: '1',
+      })
+      const log = await readFileOrEmpty(logPath)
+      const constructionLog = await readFileOrEmpty(constructionLogPath)
+
+      expect(result.code).toBe(0)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe('')
+      expect(log).not.toContain(' FATAL ')
+      expect(log).not.toContain(endpoint)
+      expect(log).not.toMatch(
+        /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+      )
+      expect(constructionLog.match(/hook-server-close/g)).toHaveLength(1)
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('sanitizes a synchronous construction failure outside transport start', async () => {
+    const result = await runProxy({
+      GEMUS_KEY: 'arbitrary-secret',
+      GEMUS_URL: 'https://alice:password@[broken/api/mcp?token=query-secret#fragment-secret',
+      PROXY_LOG: undefined,
+    })
+
+    expect(result.code).toBe(1)
+    expect(result.signal).toBeNull()
+    expect(result.stderr).toBe('Gemus MCP proxy failed to start: Invalid URL\n')
+    expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+    expect(result.stderr).not.toMatch(
+      /arbitrary-secret|alice|password|query-secret|fragment-secret|ERR_INVALID_URL/,
+    )
+  })
+
+  it('keeps the missing-key diagnostic singular when PROXY_LOG is unwritable', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-unwritable-log-'))
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: undefined,
+        PROXY_LOG: tempRoot,
+      })
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: GEMUS_KEY is required. Set it in your user environment and restart Codex.\n',
+      )
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps a later startup diagnostic singular when PROXY_LOG is unwritable', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-unwritable-log-'))
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'arbitrary-secret',
+        GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: tempRoot,
+        PROXY_TEST_STDIO_START_FAILURE: '1',
+      })
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: stdio failed Authorization: Bearer [REDACTED] at https://example.test/api/mcp\n',
+      )
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+})

package/src/proxy.mjs

@@ -14,8 +14,9 @@
 // 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 (needs /hooks trust); codex does NOT interpolate ${VAR} in MCP env → key is a literal
-// in local `codex mcp add --env`. See docs/plans/1751-codex-desktop-companion.md.
+// 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'
@@ -27,9 +28,48 @@ 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 {
+  assertGemusKey,
+  createFatalReporter,
+  createShutdownCoordinator,
+  safeEndpointLabel,
+  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
@@ -40,11 +80,6 @@ const IDLE_MS = Number(process.env.PROXY_BACKFILL_IDLE_MS) || 180_000
 // （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
-const LOG = process.env.PROXY_LOG // optional debug log path
-const log = (dir, m) => {
-  if (!LOG) return
-  fs.appendFileSync(LOG, `[${new Date().toISOString()}] ${dir} ${typeof m === 'string' ? m : JSON.stringify(m).slice(0, 1000)}\n`)
-}
 
 // ── footprint-0 交付注入（#1756 Layer 1a）─────────────────────────────────────────────────────────
 // 交付/orphan 不再每图新开 key-only session（connect-per-call，抢 KEY_ONLY_SESSION_CAP 槽），而是把
@@ -236,7 +271,10 @@ const hookServer = http.createServer((req, res) => {
       .catch((e) => log('HOOK-BACKFILL-ERR', String(e)))
   })
 })
-hookServer.on('error', (e) => log('HOOK-SERVER-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 })
@@ -273,7 +311,17 @@ const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
   fetch: failFast.fetch,
 })
 
-stdio.onmessage = (m) => { tapClientToServer(m); log('C->G', m); upstream.send(m).catch((e) => log('ERR-http-send', String(e))) }
+stdio.onmessage = (m) => {
+  tapClientToServer(m)
+  log('C->G', m)
+  upstream.send(m).catch((error) => {
+    if (m?.method === 'initialize') {
+      void terminateFatally(error)
+      return
+    }
+    log('ERR-http-send', String(error))
+  })
+}
 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
@@ -319,10 +367,7 @@ function startHeartbeat() {
   if (typeof heartbeatTimer.unref === 'function') heartbeatTimer.unref() // don't keep the process alive on this alone
 }
 
-let shuttingDown = false
-async function shutdown() {
-  if (shuttingDown) return
-  shuttingDown = true
+async function cleanup() {
   if (heartbeatTimer) clearInterval(heartbeatTimer)
   for (const t of idleTimers.values()) clearTimeout(t)
   idleTimers.clear()
@@ -334,16 +379,39 @@ async function shutdown() {
   if (discoveryFile) { try { fs.unlinkSync(discoveryFile) } catch { /* ignore */ } }
   try { await upstream.terminateSession() } catch { /* ignore */ }
   try { await upstream.close() } catch { /* ignore */ }
-  process.exit(0)
 }
-stdio.onclose = () => { log('stdio-close', ''); void shutdown() }
+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 = (e) => log('http-err', String(e))
-process.on('SIGTERM', shutdown)
-process.on('SIGINT', shutdown)
+process.on('SIGTERM', () => { void shutdownGracefully() })
+process.on('SIGINT', () => { void shutdownGracefully() })
 
-await upstream.start()
-await stdio.start()
-startHeartbeat()
-log('STARTED', { GEMUS_URL, SERVER_ORIGIN, hasKey: Boolean(KEY), pid: process.pid, idleMs: IDLE_MS, heartbeatMs: HEARTBEAT_MS })
+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/startup.mjs

@@ -0,0 +1,94 @@
+const REDACTED = '[REDACTED]'
+
+export function assertGemusKey(key) {
+  if (!key) {
+    throw new Error('GEMUS_KEY is required. Set it in your user environment and restart Codex.')
+  }
+}
+
+export function safeEndpointLabel(value) {
+  try {
+    const url = value instanceof URL ? value : new URL(value)
+    return `${url.origin}${url.pathname}`
+  } catch {
+    return '[invalid endpoint]'
+  }
+}
+
+export function sanitizeStartupError(error, { secret }) {
+  const message = error instanceof Error ? error.message : String(error)
+  const exactRedacted = secret ? message.replaceAll(secret, REDACTED) : message
+  const withoutUrlCredentials = exactRedacted.replace(
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi,
+    (value) => safeEndpointLabel(value),
+  )
+  const withoutQuotedHeaders = withoutUrlCredentials.replace(
+    /((?:(?:Proxy-)?Authorization|X-API-Key|API-Key|X-Gemus-Key|Gemus-Key)["']?\s*[:=]\s*)(["'])(.*?)\2/gi,
+    (_match, prefix, quote, value) => {
+      const scheme = /^(Bearer|Basic|Digest)\s+/i.exec(value)?.[1]
+      return `${prefix}${quote}${scheme ? `${scheme} ` : ''}${REDACTED}${quote}`
+    },
+  )
+  const withoutAuthorizationHeaders = withoutQuotedHeaders.replace(
+    /((?:Proxy-)?Authorization\s*[:=]\s*)(?!["'])(?:(Bearer|Basic|Digest)\s+)?[^\s,;}]+/gi,
+    (_match, prefix, scheme) => `${prefix}${scheme ? `${scheme} ` : ''}${REDACTED}`,
+  )
+  const withoutBearerTokens = withoutAuthorizationHeaders.replace(
+    /Bearer\s+(?!\[REDACTED\])[^\s"',;}]+/gi,
+    `Bearer ${REDACTED}`,
+  )
+  const withoutKeyHeaders = withoutBearerTokens.replace(
+    /((?:X-API-Key|API-Key|X-Gemus-Key|Gemus-Key)\s*[:=]\s*)(?!["'])[^\s,;}]+/gi,
+    `$1${REDACTED}`,
+  )
+  const sanitized = withoutKeyHeaders.replace(
+    /mak_[A-Za-z0-9._~+/=-]+/g,
+    REDACTED,
+  )
+
+  return `Gemus MCP proxy failed to start: ${sanitized}`
+}
+
+export function createFatalReporter({ secret, writeStderr, writeLog = () => {} }) {
+  let reported = false
+
+  return function reportFatal(error) {
+    const message = sanitizeStartupError(error, { secret })
+    if (reported) return message
+    reported = true
+
+    writeStderr(`${message}\n`)
+    try {
+      writeLog(message)
+    } catch {
+      // Optional logging must never replace the guaranteed stderr diagnostic.
+    }
+    return message
+  }
+}
+
+export async function startProxy({ key, upstream, stdio, onStarted }) {
+  assertGemusKey(key)
+  await upstream.start()
+  await stdio.start()
+  onStarted()
+}
+
+export function createShutdownCoordinator({ cleanup, exit }) {
+  let requestedExitCode = 0
+  let cleanupPromise
+
+  return function shutdown(exitCode = 0) {
+    requestedExitCode = Math.max(requestedExitCode, exitCode)
+    if (!cleanupPromise) {
+      cleanupPromise = (async () => {
+        try {
+          await cleanup()
+        } finally {
+          exit(requestedExitCode)
+        }
+      })()
+    }
+    return cleanupPromise
+  }
+}