{"record":{"id":"308c7d07d03af8f9","repo":"JuliusBrussee/caveman","slug":"agent-native-integration-postflight-is-status","errorCode":null,"errorMessage":"${agent} native integration postflight is ${status.state}","messagePattern":"(.+?) native integration postflight is (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2906,"sourceCode":"  }\n}\n\nfunction installAgentNativeBundleSkills(agent: \"claude\" | \"codex\", journal: AgentNativeBundleJournal): void {\n  const originals = new Map(journal.skills.map((skill) => [skill.file, skill.before_base64]));\n  journal.skills = agentNativeSkillFiles(agent).map(({ file, body }) => {\n    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) {","sourceCodeStart":2888,"sourceCodeEnd":2924,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L2888-L2924","documentation":"Thrown by verifyAgentNativeBundle during `caveman setup --agent-native` postflight when the native integration status for the agent (claude or codex) is anything other than \"installed\" after setup supposedly completed. The CLI verifies that the native integration actually took hold; if it didn't, the bundle verification fails loudly rather than leaving a half-configured agent.","triggerScenarios":"Running `caveman setup --agent-native claude` (or codex) where nativeIntegrationStatus(agent) returns a state like \"not-installed\", \"partial\", or \"error\" immediately after the install step — e.g. the agent's config file was not written or the native marker is missing.","commonSituations":"Agent CLI not installed or upgraded to an incompatible version that moved its config location; read-only home directory preventing config writes; a prior failed setup left partial state; running as a different user than the one whose config was modified.","solutions":["Run `caveman setup --agent-native <agent>` again after fixing any write-permission issues so the install step can complete.","Verify the agent binary/config exists (e.g. `claude --version`, check ~/.claude or ~/.codex) and install/update the agent if missing.","Check nativeIntegrationStatus output for the agent to see the failing state and address the underlying cause (permissions, missing binary, unsupported agent version).","Use `caveman setup --agent-native <agent> --remove` to clear partial state, then re-run setup."],"exampleFix":"// before: setup proceeds even though agent binary absent\n$ caveman setup --agent-native claude\n// after: ensure agent is installed first\n$ claude --version || npm install -g @anthropic-ai/claude-code\n$ caveman setup --agent-native claude","handlingStrategy":"validation","validationCode":"import { nativeIntegrationStatus } from \"caveman/cli\";\nconst status = nativeIntegrationStatus(\"claude\");\nif (status.state !== \"installed\") {\n  console.error(`native integration not ready: ${status.state}`);\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  verifyAgentNativeBundle(agent, journal, cloudMcp);\n} catch (err) {\n  console.error(`postflight failed: ${(err as Error).message}. Re-run: caveman setup --agent-native ${agent}`);\n  process.exitCode = 1;\n}","preventionTips":["Install/verify the agent CLI before running caveman setup.","Run setup as the same user who owns the agent config directory.","Avoid agent auto-updates racing with setup commands."],"tags":["postflight","native-integration","setup","cli"],"backgroundTag":"invalid-state-transition","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"}