{"record":{"id":"059eacf7ca8b4334","repo":"JuliusBrussee/caveman","slug":"cannot-read-pending-agent-agent-native-bundle-j","errorCode":null,"errorMessage":"cannot read pending ${agent} agent-native bundle journal: ${(error as Error).message}","messagePattern":"cannot read pending (.+?) agent-native bundle journal: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2309,"sourceCode":"      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 {\n    const value = JSON.parse(readFileSync(agentNativeBundleRemovalJournalPath(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 pending bundle removal 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 removal journal: ${(error as Error).message}`);\n  }\n}\n\nfunction readMcpServerMarker(agent: string, serverName: string): { command: string; args: string[] } | null {\n  try {","sourceCodeStart":2291,"sourceCodeEnd":2327,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/cli/src/index.ts#L2291-L2327","documentation":"readPendingAgentNativeBundleJournal() reads the '.pending' variant of the agent-native bundle journal — the transaction record of an in-flight skill/MCP installation. A non-ENOENT error (bad JSON, or shape validation failing: schema_version !== 1, wrong agent, missing cloud_mcp, non-array skills) is rethrown with this message before any recovery is attempted.","triggerScenarios":"A previous `caveman setup` / agent-native install was killed mid-transaction leaving a partially written .pending journal, then any later agent command runs recovery and hits the malformed file; or a CLI version skew changed the journal schema between write and read.","commonSituations":"Ctrl-C or SIGKILL during `caveman claude` setup; power loss; two caveman processes racing (no integration lock held); manual editing of the pending journal.","solutions":["Inspect the pending journal file and compare it to the committed journal for the agent","If the interrupted setup's target state is irrelevant, delete the pending journal and re-run setup to redo the bundle cleanly","Ensure only one caveman process runs setup per agent (the integration lock) to avoid partial writes"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"function pendingJournalIntact(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 isPendingJournalReadError(e: unknown): boolean {\n  return e instanceof Error && e.message.includes(\"cannot read pending \") && e.message.includes(\"bundle journal\");\n}","tryCatchPattern":"try {\n  runCavemanAgentCommand(\"codex\");\n} catch (e) {\n  if (isPendingJournalReadError(e)) {\n    // an interrupted setup left a partial .pending journal — resolve it before any agent command\n  } else throw e;\n}","preventionTips":["Let `caveman setup` run to completion; avoid killing it mid-bundle-install","After a crash, re-run the same setup command first so recovery completes before other work","Keep one caveman process per agent (integration lock exists for a reason)"],"tags":["journal","recovery","install","agent-native"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}