${agent} caveman-cloud MCP registration failed exact postfli

Error message

${agent} caveman-cloud MCP registration failed exact postflight

What it means

Final and strictest MCP postflight in verifyAgentNativeBundle: even if the marker matches textually, agentNativeCloudMcpMatches(agent, cloudMcp) must confirm the agent's live registration of the caveman-cloud server is exactly the applied one. It catches semantic mismatches the marker comparison misses (e.g. normalized paths, env expansion, duplicate entries).

Source

Thrown at packages/cli/src/index.ts:2592

    mkdirSync(dirname(file), { recursive: true });
    atomicWriteFile(file, Buffer.from(body));
    return {
      file,
      before_base64: originals.get(file) ?? null,
      after_sha256: bytesHash(Buffer.from(body)),
    };
  });
}

function verifyAgentNativeBundle(agent: "claude" | "codex", journal: AgentNativeBundleJournal, cloudMcp: { command: string; args: string[] }): void {
  const status = nativeIntegrationStatus(agent);
  if (status.state !== "installed") throw new Error(`${agent} native integration postflight is ${status.state}`);
  const marker = readMcpServerMarker(agent, "caveman-cloud");
  if (!marker || marker.command !== cloudMcp.command || JSON.stringify(marker.args) !== JSON.stringify(cloudMcp.args)) {
    throw new Error(`${agent} caveman-cloud MCP postflight mismatch`);
  }
  if (!agentNativeCloudMcpMatches(agent, cloudMcp)) {
    throw new Error(`${agent} caveman-cloud MCP registration failed exact postflight`);
  }
  for (const skill of journal.skills) {
    const current = fileBytes(skill.file);
    if (!current || bytesHash(current) !== skill.after_sha256) throw new Error(`${skill.file} failed skill postflight`);
  }
}

function removeAgentNativeBundle(agent: "claude" | "codex"): void {
  recoverPendingAgentNativeRemoval(agent);
  recoverPendingAgentNativeBundle(agent);
  const journal = readAgentNativeBundleJournal(agent);
  if (!journal) {
    process.stderr.write(`${mark("warn")} ${agent}: no agent-native bundle journal found\n`);
    return;
  }
  for (const skill of journal.skills) {
    const current = fileBytes(skill.file);
    if (!current || bytesHash(current) !== skill.after_sha256) throw new Error(`${skill.file} changed after setup; refusing destructive bundle removal`);

View on GitHub (pinned to 27d5a3981a)

Solutions

Ensure exactly one caveman binary is on PATH and reinstall the agent-native bundle so registration points at it
Delete duplicate "caveman-cloud" entries in the agent's mcpServers config, then re-run setup
Run `which caveman` and compare against the command recorded in the agent config; align them (e.g. via CAVEMAN_AGENT_BIN or reinstall)
Re-run `caveman setup --agent-native <agent>` after `--remove` to force a clean registration

Defensive patterns

Strategy: validation

Validate before calling

// pre-flight: single caveman binary on PATH prevents registration pointing at stale builds
import { execSync } from "node:child_process";
const hits = execSync("which -a caveman", { encoding: "utf8" }).trim().split("\n");
if (hits.length > 1) console.warn(`multiple caveman binaries: ${hits.join(", ")}; unify before agent-native setup`);

Try / catch

try {
  await setup(["--agent-native", agent]);
} catch (error) {
  if (/failed exact postflight/.test((error as Error).message)) {
    // exact-match failure means live registration differs; remove + clean reinstall
    await setup(["--agent-native", agent, "--remove"]);
    await setup(["--agent-native", agent]);
  } else throw error;
}

Prevention

Keep exactly one caveman install on PATH (prefer `caveman setup --install` over ad-hoc npm globals)
Remove duplicate caveman-cloud entries in agent config before setup
Pin CAVEMAN_AGENT_BIN/overrides to one absolute binary path in automation

When it happens

Trigger: The config file contains the marker but the agent-side registration resolves differently: binary path resolved via symlink/PATH to another caveman build, duplicate caveman-cloud entries where the agent picks the stale one, or env-var interpolation inside args that changes after write.

Common situations: Multiple caveman installs on PATH (npm global vs setup --install binary) so the registered command points at an older binary; leftover duplicate MCP entries from earlier setups; agent config normalizing absolute paths on save.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/5372b45c344af842. Report an issue: GitHub.