{"record":{"id":"5372b45c344af842","repo":"JuliusBrussee/caveman","slug":"agent-caveman-cloud-mcp-registration-failed-exa","errorCode":null,"errorMessage":"${agent} caveman-cloud MCP registration failed exact postflight","messagePattern":"(.+?) caveman-cloud MCP registration failed exact postflight","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2912,"sourceCode":"    mkdirSync(dirname(file), { recursive: true });\n    atomicWriteFile(file, Buffer.from(body));\n    return {\n      file,\n      before_base64: originals.get(file) ?? null,\n      after_sha256: bytesHash(Buffer.from(body)),\n    };\n  });\n}\n\nfunction verifyAgentNativeBundle(agent: \"claude\" | \"codex\", journal: AgentNativeBundleJournal, cloudMcp: { command: string; args: string[] }): void {\n  const status = nativeIntegrationStatus(agent);\n  if (status.state !== \"installed\") throw new Error(`${agent} native integration postflight is ${status.state}`);\n  const marker = readMcpServerMarker(agent, \"caveman-cloud\");\n  if (!marker || marker.command !== cloudMcp.command || JSON.stringify(marker.args) !== JSON.stringify(cloudMcp.args)) {\n    throw new Error(`${agent} caveman-cloud MCP postflight mismatch`);\n  }\n  if (!agentNativeCloudMcpMatches(agent, cloudMcp)) {\n    throw new Error(`${agent} caveman-cloud MCP registration failed exact postflight`);\n  }\n  for (const skill of journal.skills) {\n    const current = fileBytes(skill.file);\n    if (!current || bytesHash(current) !== skill.after_sha256) throw new Error(`${skill.file} failed skill postflight`);\n  }\n}\n\nfunction removeAgentNativeBundle(agent: \"claude\" | \"codex\"): void {\n  recoverPendingAgentNativeRemoval(agent);\n  recoverPendingAgentNativeBundle(agent);\n  const journal = readAgentNativeBundleJournal(agent);\n  if (!journal) {\n    process.stderr.write(`${mark(\"warn\")} ${agent}: no agent-native bundle journal found\\n`);\n    return;\n  }\n  for (const skill of journal.skills) {\n    const current = fileBytes(skill.file);\n    if (!current || bytesHash(current) !== skill.after_sha256) throw new Error(`${skill.file} changed after setup; refusing destructive bundle removal`);","sourceCodeStart":2894,"sourceCodeEnd":2930,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L2894-L2930","documentation":"Thrown by verifyAgentNativeBundle when the deeper exact-match check agentNativeCloudMcpMatches fails even though the basic marker comparison passed. It means the agent's recorded caveman-cloud MCP registration does not match the exact expected registration shape required by postflight.","triggerScenarios":"Setup wrote the MCP entry but the agent's stored representation differs in fields beyond command/args (extra keys, changed env, different scope/file) — agentNativeCloudMcpMatches returns false after the simple marker comparison succeeded.","commonSituations":"Agent CLI version changed its MCP config schema between setup and verification; the agent merged the entry with extra fields; a config migration restructured where MCP servers are recorded.","solutions":["Re-run `caveman setup --agent-native <agent>` so the exact registration is rewritten in the current agent config schema.","Update (or pin) the agent CLI version: a schema change between versions is the most common cause of an exact-match failure.","Inspect agentNativeCloudMcpMatches expectations and the agent's config to identify which field diverges, and remove the extra/stale fields.","Remove the bundle with `caveman setup --agent-native <agent> --remove` and set it up fresh."],"exampleFix":"// before: agent CLI auto-upgraded mid-setup, schema changed\n$ claude update & caveman setup --agent-native claude\n// after: pin/complete the agent version before setup\n$ claude --version  # confirm stable version\n$ caveman setup --agent-native claude","handlingStrategy":"validation","validationCode":"if (!agentNativeCloudMcpMatches(agent, expectedCloudMcp)) {\n  console.error(\"exact MCP registration mismatch; re-run caveman setup --agent-native \" + agent);\n}","typeGuard":null,"tryCatchPattern":"try {\n  verifyAgentNativeBundle(agent, journal, cloudMcp);\n} catch (err) {\n  if (/failed exact postflight/.test((err as Error).message)) {\n    console.error(\"Agent config schema drifted; pin agent version and re-run setup\");\n  }\n}","preventionTips":["Pin the agent CLI version during setup; don't auto-upgrade mid-install.","Re-run setup after any agent version change.","Inspect the agent's config for extra/merged fields after third-party tools modify it."],"tags":["postflight","mcp","exact-match","schema-drift","cli"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}