@gemus/mcp-proxy 0.1.1 → 0.1.4

package/README.md

@@ -1,4 +1,4 @@
-# @gemus/mcp-proxy (Issue #1751, P1 — WIP)
+# @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**
@@ -6,11 +6,13 @@ MCP server so codex spawns it locally; the proxy owns upstream auth to the remot
 (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: minimal skeleton, behavioral checkpoint PASSED
+## Status: implemented
 
-`src/proxy.mjs` is the validated passthrough+tap skeleton. The backfill delivery layer (Stop-hook
-endpoint → read rollout via `transcript_path` → `ExecuteClaimTracker` → key-only `deliverImageToNode`)
-is the next build increment (plan Steps 2–4).
+`src/proxy.mjs` is the production passthrough, execute-tap, and deterministic image-backfill
+companion. A trusted Stop hook triggers `generated_images`/rollout discovery; `ExecuteClaimTracker`
+then delivers an unambiguous image to its planned node or conservatively creates an orphan
+`image-upload`. MCP initialization advertises the shared Codex capability contract used by the
+server blueprint policy.
 
 ## What was validated end-to-end (2026-07-06, codex-cli 0.142.2 → local dev `/api/mcp`)
 
@@ -23,7 +25,8 @@ is the next build increment (plan Steps 2–4).
   `workflowId` from `arguments`, and **turn/thread identity from `_meta.x-codex-turn-metadata`
   (`thread_id`/`turn_id`)** — so per-turn scoping needs no Stop hook. `execute` is the same path.
 - **(c) turn-end + retrieval** — `Stop` hook fires post-flush carrying `transcript_path` → exact
-  rollout; imagegen writes `generated_images/<session>/ig_<call_id>.png` + rollout `saved_path`+base64.
+  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.
 
@@ -53,4 +56,4 @@ GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp PROXY_LOG=/tmp/proxy.l
 ```
 
 Env: `GEMUS_KEY` (required), `GEMUS_URL` (default `https://gemus.ai/api/mcp`), `PROXY_LOG` (optional
-debug log), `PROXY_BACKFILL_IDLE_MS` (default 30000 — turn-idle fallback before salvage-orphan).
+debug log), `PROXY_BACKFILL_IDLE_MS` (default 180000 — turn-idle fallback before salvage-orphan).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Local stdio<->HTTP MCP proxy for Codex desktop: transparent passthrough + execute tap + imagegen backfill (Issue #1751, P1).",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@gemus/codex-backfill-core": "0.1.0"
+    "@gemus/codex-backfill-core": "0.1.2"
   },
   "engines": {
     "node": ">=18"

package/src/__tests__/backfill.test.ts

@@ -11,6 +11,7 @@ const mocks = vi.hoisted(() => ({
   addImageToCanvas: vi.fn(),
   readRollout: vi.fn(),
   findRolloutFile: vi.fn(),
+  readGeneratedImageFiles: vi.fn(),
 }))
 
 vi.mock('@gemus/codex-backfill-core', async (importOriginal) => {
@@ -21,6 +22,7 @@ vi.mock('@gemus/codex-backfill-core', async (importOriginal) => {
     addImageToCanvas: mocks.addImageToCanvas,
     readRollout: mocks.readRollout,
     findRolloutFile: mocks.findRolloutFile,
+    readGeneratedImageFiles: mocks.readGeneratedImageFiles,
   }
 })
 
@@ -71,6 +73,8 @@ beforeEach(() => {
   mocks.addImageToCanvas.mockReset().mockResolvedValue({ ok: true, entityId: 'agent_x' })
   mocks.readRollout.mockReset().mockReturnValue('')
   mocks.findRolloutFile.mockReset().mockReturnValue('/fake/rollout.jsonl')
+  // Default: generated_images unavailable → backfill falls back to the rollout source (existing tests).
+  mocks.readGeneratedImageFiles.mockReset().mockReturnValue({ available: false, images: [] })
 })
 
 describe('normalizeToolName (tap → tracker)', () => {
@@ -88,14 +92,25 @@ describe('normalizeToolName (tap → tracker)', () => {
 })
 
 describe('injectSteering (Mode-B initialize instructions)', () => {
-  it('appends companion steering to the initialize response instructions', () => {
+  it('appends a search-neutral skill bootstrap to initialize instructions', () => {
     const msg = { jsonrpc: '2.0', id: 1, result: { protocolVersion: '2024-11-05', serverInfo: { name: 'gemus' } } }
     expect(injectSteering(msg)).toBe(true)
-    expect(msg.result.instructions).toContain('auto-backfilled')
-    expect(msg.result.instructions).toContain('NEVER') // don't self-forward
+    expect(msg.result.instructions).toContain('gemus-getting-started')
+    expect(msg.result.instructions).toContain('gemus-codex-imagen')
     expect(msg.result.instructions).toBe(COMPANION_STEERING)
   })
 
+  it('does not pollute deferred search documents with registered tool names', () => {
+    const toolNames = [
+      'canvas_read', 'view_image', 'node_list', 'workflow_list', 'canvas_edit', 'ppt_edit',
+      'open_canvas', 'blueprint', 'execute', 'batch_execute', 'recall_history',
+    ]
+    for (const toolName of toolNames) {
+      const exactName = new RegExp(`(?<![A-Za-z0-9_])${toolName}(?![A-Za-z0-9_])`, 'i')
+      expect(COMPANION_STEERING, `companion steering references ${toolName}`).not.toMatch(exactName)
+    }
+  })
+
   it('preserves any existing server instructions (appends, not replaces)', () => {
     const msg = { id: 1, result: { protocolVersion: '1', instructions: 'server says hi' } }
     injectSteering(msg)
@@ -255,3 +270,87 @@ describe('backfillTurn — idempotency + guards', () => {
     expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
   })
 })
+
+describe('backfillTurn — footprint-0 call passthrough + timeout semantics (#1756 Layer 1a)', () => {
+  it('threads the injected `call` into deliver AND orphan (footprint-0)', async () => {
+    const call = vi.fn()
+    const bf = createBackfiller({
+      server: 'http://localhost:3000',
+      apiKey: 'mak_test',
+      codexHome: '/fake/.codex',
+      call,
+    })
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    mocks.deliverImageToNode.mockResolvedValue({ ok: false, code: 'ALREADY_COMPLETED' }) // force orphan fallback
+
+    await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({ call })
+    expect(mocks.addImageToCanvas.mock.calls[0][0]).toMatchObject({ call })
+  })
+
+  it('a timed-out deliver leaves the image FRESH — no orphan, not marked seen (no duplicate)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    // deliver times out → result unknown; the platform job may still land, so we must NOT orphan.
+    mocks.deliverImageToNode.mockResolvedValue({ ok: false, timedOut: true, error: 'inject timeout' })
+
+    const r1 = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    expect(r1).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
+    expect(mocks.addImageToCanvas).not.toHaveBeenCalled() // NO orphan on timeout
+
+    // Image stayed fresh (not seen): a later Stop-hook pass can still deliver it once the job lands.
+    mocks.deliverImageToNode.mockResolvedValue({ ok: true, status: 'processing' })
+    const r2 = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    expect(r2.delivered).toBe(1)
+  })
+})
+
+describe('backfillTurn — Layer 2 file byte source (#1756)', () => {
+  it('uses generated_images when available and does NOT read the rollout', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    // generated_images available with one fresh image → file source wins, rollout untouched.
+    mocks.readGeneratedImageFiles.mockReturnValue({
+      available: true,
+      images: [{ callId: 'call_current', base64: 'iVBORw0KGgoAAAA1', mimeType: 'image/png' }],
+    })
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readGeneratedImageFiles).toHaveBeenCalled()
+    expect(mocks.readRollout).not.toHaveBeenCalled() // file source is authoritative when available
+    expect(r.delivered).toBe(1)
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({
+      nodeId: 'nodeA',
+      image: { callId: 'call_current' },
+    })
+  })
+
+  it('available but empty → no delivery, and does NOT fall back to rollout (mtime guard preserved)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readGeneratedImageFiles.mockReturnValue({ available: true, images: [] })
+    // Even though the rollout has an image, availability=true must lock us to the (empty) file source.
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readRollout).not.toHaveBeenCalled()
+    expect(r).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
+  })
+
+  it('unavailable → falls back to rollout-scrape (older codex)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readGeneratedImageFiles.mockReturnValue({ available: false, images: [] })
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readRollout).toHaveBeenCalledWith('/x')
+    expect(r.delivered).toBe(1)
+  })
+})

package/src/__tests__/mcpHeaders.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest'
+import { buildProxyUpstreamHeaders } from '../mcpHeaders.mjs'
+
+describe('buildProxyUpstreamHeaders', () => {
+  it('advertises the canonical Codex MCP capabilities alongside bearer authentication', () => {
+    expect(buildProxyUpstreamHeaders('mak_test123')).toEqual({
+      Authorization: 'Bearer mak_test123',
+      'X-Gemus-Client-Capabilities': 'agent-authored-prompts,codex-imagen',
+    })
+  })
+})

package/src/backfill.mjs

@@ -16,6 +16,10 @@
 // a later trigger no-ops. salvageOnly NEVER calls claim() — mirrors bridge salvage semantics (图不丢, 不认领).
 import * as core from '@gemus/codex-backfill-core'
 
+// #1756 Layer 2 mtime cutoff：只认本进程启动后落盘的 generated_images 文件，防 proxy 重启后把该
+// session 历史图当 fresh 重复交付（session_id 跨 resume 复用、seen 是进程内存）。模块加载≈proxy 启动。
+const procStartMs = Date.now()
+
 /**
  * Normalize a raw MCP wire tool name to the tracker's expected form. The proxy sees `execute` /
  * `batch_execute` on the wire; ExecuteClaimTracker only matches `mcp__gemus__execute` /
@@ -30,27 +34,14 @@ export function normalizeToolName(name) {
   return WIRE_TO_NORMALIZED[name] ?? name
 }
 
-// Companion steering (Mode B has no bridge to inject CLIENT_DELIVERED_GUIDANCE into the system prompt).
-// This proxy IS the backfiller, so it tells codex — via the MCP initialize `instructions` field — not to
-// self-forward imagegen output. Mirrors src/lib/agent/core/prompt/workflowBehavior.ts (condensed). Without
-// it codex hunts the file / uploads it to a public host to self-deliver (#1751 real-machine observation).
+// Keep initialize instructions search-neutral. Codex appends this namespace text to every deferred
+// tool's BM25 document, so operational rules and exact tool names live in installed plugin skills.
 export const COMPANION_STEERING = [
-  '# Gemus companion — codex-imagen is auto-backfilled',
-  '',
-  'A local Gemus companion backfills your own image generations onto the planned canvas nodes at turn',
-  'end. For a `codex-imagen` (gen-image) node: (1) create the node with config.model="codex-imagen",',
-  '(2) call `execute` with dryRun:true and read the returned resolvedPrompt, (3) generate the image',
-  'LOCALLY with your built-in imagegen, then (4) STOP.',
+  '# Gemus companion',
   '',
-  'NEVER locate, read, host, upload, or submit the imagegen file yourself — you cannot access it and it',
-  'is delivered for you. NEVER pass `content` for a codex-imagen node, and NEVER spin up a local HTTP',
-  'server or upload the image to a public host to "deliver" it. A codex-imagen node showing no output /',
-  'clientDeliveredStatus:"awaiting_backfill" DURING your turn is ON TRACK, not a failure — do not re-read',
-  'it in a loop, do not switch its model to a platform provider (gemini/etc), do not self-forward. Just',
-  'end your turn; the image arrives on the node after it.',
-  '',
-  '(Text is the exception: codex-text has no backfill — self-forward with execute dryRun:false +',
-  'content:{text:"..."}.)',
+  'Before using Gemus, load and follow the installed `gemus-getting-started` skill.',
+  'For local image generation and turn-end backfill, also load `gemus-codex-imagen`.',
+  'These skills are the authoritative operational guidance for this direct MCP connection.',
 ].join('\n')
 
 /**
@@ -71,9 +62,12 @@ export function injectSteering(msg) {
  * @param {string} deps.server   平台 origin（不含 /api/mcp）
  * @param {string} deps.apiKey   用户 mak_ key
  * @param {string} deps.codexHome  ~/.codex（idle-timer fallback 用 findRolloutFile(session_id) 定位 rollout）
+ * @param {import('@gemus/codex-backfill-core').GemusToolCall} [deps.call] footprint-0 交付 transport
+ *   （#1756 Layer 1a）：省略 → connect-per-call（每图新开 key-only session）；传入 → 在 proxy 已有
+ *   upstream 连接上注入 execute/canvas_edit（不占新槽，即便 cap 被泄漏填满仍能交付）。
  * @param {(msg: string, obj?: unknown) => void} [deps.log]
  */
-export function createBackfiller({ server, apiKey, codexHome, log = () => {} }) {
+export function createBackfiller({ server, apiKey, codexHome, call, log = () => {} }) {
   /** @type {Map<string, { tracker: InstanceType<typeof core.ExecuteClaimTracker>, workflowId?: string, sessionId?: string }>} */
   const turns = new Map() // keyed by turn_id; bounded (evict oldest) so a long session can't leak
   const TURN_CAP = 64
@@ -123,7 +117,7 @@ export function createBackfiller({ server, apiKey, codexHome, log = () => {} })
 
   /** orphan 一张图（Mode B 需真实 workflowId），**只在成功后**标记 seen；返回是否成功。 */
   async function orphanOne(workflowId, image) {
-    const r = await core.addImageToCanvas({ server, apiKey, workflowId, image })
+    const r = await core.addImageToCanvas({ server, apiKey, workflowId, image, call })
     if (r.ok) {
       seen.add(image.callId)
       return true
@@ -143,14 +137,27 @@ export function createBackfiller({ server, apiKey, codexHome, log = () => {} })
   async function backfillTurnInner({ turnKey, sessionId, rolloutPath, salvageOnly }) {
     const t = turns.get(turnKey)
     const sid = sessionId || t?.sessionId
-    const path = rolloutPath || core.findRolloutFile(codexHome, sid)
-    const jsonl = core.readRollout(path)
-    const all = core.extractImageOutputs(jsonl)
+    // #1756 Layer 2: 优先读 generated_images 落盘文件（去 rollout-scrape 脆化）。三态 fallback——
+    // 仅目录整体不可用（旧 codex 不落盘）才回退 rollout；目录可用即锁定文件源（即便过滤后空），
+    // 否则会绕过 mtime 守卫把历史图从 rollout 重新捞出重复交付。
+    const fileResult = sid
+      ? core.readGeneratedImageFiles(codexHome, sid, procStartMs)
+      : { available: false, images: [] }
+    let all
+    let source
+    if (fileResult.available) {
+      all = fileResult.images
+      source = 'generated_images'
+    } else {
+      const path = rolloutPath || core.findRolloutFile(codexHome, sid)
+      all = core.extractImageOutputs(core.readRollout(path))
+      source = path || '(none)'
+    }
     const fresh = all.filter((img) => !seen.has(img.callId))
 
     if (fresh.length === 0) {
       // 图还没 flush（idle 过早触发）或都已交付 —— 都不动 seen/turn 状态，留给后续 hook。
-      log('backfill: no fresh images', { turnKey, salvageOnly, path: path || '(none)' })
+      log('backfill: no fresh images', { turnKey, salvageOnly, source })
       return { delivered: 0, orphaned: 0, dropped: 0 }
     }
 
@@ -175,12 +182,17 @@ export function createBackfiller({ server, apiKey, codexHome, log = () => {} })
     let delivered = 0
     let orphaned = 0
     for (const { nodeId, image } of claims) {
-      const r = await core.deliverImageToNode({ server, apiKey, workflowId, nodeId, image })
+      const r = await core.deliverImageToNode({ server, apiKey, workflowId, nodeId, image, call })
       if (r.ok) {
         seen.add(image.callId)
         delivered++
+      } else if (r.timedOut) {
+        // #1756: 注入交付超时 = 结果未知（平台 job 可能仍在跑并最终写 DB）。**不 orphan、不标 seen**——
+        // 否则同图既落节点又多一个 image-upload 孤儿。留 fresh，交给下轮 pass（Stop hook/idle）在 job
+        // 落地后经 execute 幂等门重判（already_completed 才安全 orphan）。
+        log('backfill: deliver timed out — leaving image fresh (no orphan)', { nodeId, callId: image.callId })
       } else if (await orphanOne(workflowId, image)) {
-        // already_completed / 其它失败 → orphan 保底（镜像 bridge：新图未落节点则至少 image-upload）。
+        // already_completed / 其它确定性失败 → orphan 保底（镜像 bridge：新图未落节点则至少 image-upload）。
         orphaned++
       } else {
         log('backfill: deliver+orphan both failed', { nodeId, callId: image.callId, error: r.error ?? r.code })

package/src/mcpHeaders.mjs

@@ -0,0 +1,12 @@
+import {
+  CLIENT_CAPABILITIES,
+  CLIENT_CAPABILITIES_HEADER,
+  serializeClientCapabilities,
+} from '@gemus/codex-backfill-core'
+
+export function buildProxyUpstreamHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    [CLIENT_CAPABILITIES_HEADER]: serializeClientCapabilities(CLIENT_CAPABILITIES),
+  }
+}

package/src/proxy.mjs

@@ -24,6 +24,8 @@ 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'
 
 const KEY = process.env.GEMUS_KEY || ''
 const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
@@ -33,16 +35,68 @@ const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
 // 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
 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 槽），而是把
+// 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),
 })
 
@@ -191,23 +245,54 @@ if (typeof hookServer.unref === 'function') hookServer.unref()
 
 // ── transparent JSON-RPC passthrough (raw send/onmessage) ──────────────────────────────────────
 const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
-  requestInit: { headers: { Authorization: `Bearer ${KEY}` } },
+  requestInit: { headers: buildProxyUpstreamHeaders(KEY) },
 })
 const stdio = new StdioServerTransport()
 
 stdio.onmessage = (m) => { tapClientToServer(m); log('C->G', m); upstream.send(m).catch((e) => log('ERR-http-send', String(e))) }
-upstream.onmessage = (m) => { tapServerToClient(m); steerOnInit(m); log('G->C', m); stdio.send(m).catch((e) => log('ERR-stdio-send', String(e))) }
+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
+  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
+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
+}
+
 let shuttingDown = false
 async function shutdown() {
   if (shuttingDown) return
   shuttingDown = true
+  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()
   try { hookServer.close() } catch { /* ignore */ }
   if (discoveryFile) { try { fs.unlinkSync(discoveryFile) } catch { /* ignore */ } }
   try { await upstream.terminateSession() } catch { /* ignore */ }
@@ -223,4 +308,5 @@ process.on('SIGINT', shutdown)
 
 await upstream.start()
 await stdio.start()
-log('STARTED', { GEMUS_URL, SERVER_ORIGIN, hasKey: Boolean(KEY), pid: process.pid, idleMs: IDLE_MS })
+startHeartbeat()
+log('STARTED', { GEMUS_URL, SERVER_ORIGIN, hasKey: Boolean(KEY), pid: process.pid, idleMs: IDLE_MS, heartbeatMs: HEARTBEAT_MS })