{"record":{"id":"d50cdd801514f10f","repo":"JuliusBrussee/caveman","slug":"cannot-read-agent-agent-native-bundle-journal","errorCode":null,"errorMessage":"cannot read ${agent} agent-native bundle journal: ${(error as Error).message}","messagePattern":"cannot read (.+?) agent-native bundle journal: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2296,"sourceCode":"\nfunction agentNativeBundleJournalPath(agent: \"claude\" | \"codex\", pending = false): string {\n  return join(cavemanHome(), \"integrations\", `${agent}.agent-native-bundle${pending ? \".pending\" : \"\"}.json`);\n}\n\nfunction agentNativeBundleRemovalJournalPath(agent: \"claude\" | \"codex\"): string {\n  return join(cavemanHome(), \"integrations\", `${agent}.agent-native-bundle.removing.json`);\n}\n\nfunction readAgentNativeBundleJournal(agent: \"claude\" | \"codex\"): AgentNativeBundleJournal | null {\n  try {\n    const value = JSON.parse(readFileSync(agentNativeBundleJournalPath(agent), \"utf8\")) as AgentNativeBundleJournal;\n    if (value.schema_version !== 1 || value.agent !== agent || !value.cloud_mcp || !Array.isArray(value.skills)) {\n      throw new Error(\"unsupported bundle journal\");\n    }\n    return value;\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return null;\n    throw new Error(`cannot read ${agent} agent-native bundle journal: ${(error as Error).message}`);\n  }\n}\n\nfunction readPendingAgentNativeBundleJournal(agent: \"claude\" | \"codex\"): AgentNativeBundleJournal | null {\n  try {\n    const value = JSON.parse(readFileSync(agentNativeBundleJournalPath(agent, true), \"utf8\")) as AgentNativeBundleJournal;\n    if (value.schema_version !== 1 || value.agent !== agent || !value.cloud_mcp || !Array.isArray(value.skills)) {\n      throw new Error(\"unsupported pending bundle journal\");\n    }\n    return value;\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return null;\n    throw new Error(`cannot read pending ${agent} agent-native bundle journal: ${(error as Error).message}`);\n  }\n}\n\nfunction readPendingAgentNativeBundleRemoval(agent: \"claude\" | \"codex\"): AgentNativeBundleJournal | null {\n  try {","sourceCodeStart":2278,"sourceCodeEnd":2314,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/cli/src/index.ts#L2278-L2314","documentation":"readAgentNativeBundleJournal() reads ~/.caveman-cloud/integrations/<agent>.agent-native-bundle.json — the journal describing the last committed agent-native bundle state (skills + caveman-cloud MCP). Any error other than ENOENT — invalid JSON, or a shape failing validation (schema_version !== 1, wrong agent, missing cloud_mcp/skills array) — is rethrown with this message. The journal is what makes later recovery non-destructive, so an unreadable one is fatal to further setup steps.","triggerScenarios":"Running `caveman <agent>` / setup / mcp flows when the journal file exists but is hand-edited, written by a different (older/newer) CLI version with another schema, truncated by a crash mid-write, or contains a mismatched agent id.","commonSituations":"Downgrading the CLI after a newer schema_version was written; a user or other tool editing files under ~/.caveman-cloud/integrations; disk-full or crash during an earlier setup leaving a partial journal.","solutions":["Inspect the journal file (~/.caveman-cloud/integrations/<agent>.agent-native-bundle.json) for truncation or unexpected fields","Upgrade the caveman CLI to the version that wrote the journal if a schema skew is suspected","If the bundle state is stale/unwanted, remove or rename the journal file after confirming no interrupted setup is pending, then re-run setup to rebuild it"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import { readFileSync } from \"node:fs\";\nfunction journalReadable(p: string): boolean {\n  try {\n    const v = JSON.parse(readFileSync(p, \"utf8\"));\n    return v.schema_version === 1 && Array.isArray(v.skills) && !!v.cloud_mcp;\n  } catch { return false; }\n}","typeGuard":"function isJournalReadError(e: unknown): boolean {\n  return e instanceof Error && e.message.includes(\"cannot read \") && e.message.includes(\"agent-native bundle journal\");\n}","tryCatchPattern":"try {\n  runCavemanAgentCommand(\"claude\");\n} catch (e) {\n  if (isJournalReadError(e)) {\n    // inspect/back up ~/.caveman-cloud/integrations/claude.agent-native-bundle.json, fix or remove, re-run\n  } else throw e;\n}","preventionTips":["Never hand-edit files under ~/.caveman-cloud/integrations","Run setup serially per agent so journals are written atomically","Upgrade/downgrade the CLI wholesale, not mid-transaction"],"tags":["journal","install","corruption","agent-native"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}