{"record":{"id":"100f614dc0e714a7","repo":"JuliusBrussee/caveman","slug":"cave-stale-lock-dev-snapshot","errorCode":null,"errorMessage":"cave_stale_lock:dev_snapshot","messagePattern":"cave_stale_lock:dev_snapshot","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/cli.ts","lineNumber":1057,"sourceCode":"  const sourceSha256 = await sourceGraphSHA256(root, sourceFiles);\n  return { config, agent, evals, sourceSha256 };\n}\n\nasync function validLockIdentity(\n  root: string,\n  entry: string,\n  expectedAgent?: AgentDefinition,\n  beforeSourceHash?: Parameters<typeof loadBuildInputs>[2],\n): Promise<CaveBuildLock | undefined> {\n  try {\n    const lock = await readLock(root);\n    const loaded = await loadBuildInputs(root, \"caveman.config.ts\", beforeSourceHash);\n    if (resolve(root, loaded.config.entry) !== resolve(root, entry)) {\n      throw new Error(\"cave_stale_lock:entry\");\n    }\n    if (expectedAgent !== undefined &&\n        agentDefinitionSHA256(loaded.agent) !== agentDefinitionSHA256(expectedAgent)) {\n      throw new Error(\"cave_stale_lock:dev_snapshot\");\n    }\n    const checked = checkLock(lock, {\n      sourceSha256: loaded.sourceSha256,\n      agentDefinitionSha256: agentDefinitionSHA256(loaded.agent),\n      contextIRSha256: contextIRSHA256(await lowerBuildContext(\n        root,\n        loaded.agent,\n      ).then((value) => value.ir)),\n      evalSuiteSha256: sha256(stableStringify(loaded.evals.filter((item) => item.approved && item.required))),\n      runtimeVersion: FRAMEWORK_VERSION,\n      adapterVersion: PI_ADAPTER_VERSION,\n      upstreamVersion: PI_UPSTREAM_VERSION,\n      transformRegistrySha256: await transformRegistrySHA256(),\n      catalogSha256: CATALOG_SHA256,\n    });\n    if (!checked.valid) throw new Error(`cave_stale_lock:${checked.stale.join(\",\")}: run npm run build to relock`);\n    return lock;\n  } catch (error) {","sourceCodeStart":1039,"sourceCodeEnd":1075,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/766dce6b1394ebb56a3090748d5a0240a5aefb36/packages/agent/src/cli.ts#L1039-L1075","documentation":"Inside `validLockIdentity`, when the caller supplies `expectedAgent`, the freshly loaded agent definition must hash identically (`agentDefinitionSHA256(loaded.agent) !== agentDefinitionSHA256(expectedAgent)` → throw). The in-memory dev snapshot of the agent no longer matches the definition that the current config/entry produce — typically the agent was edited after the snapshot was taken.","triggerScenarios":"Starting a dev/locked flow with an `expectedAgent` snapshot captured before the entry module was edited (hot reload changed the definition); the config entry now loading a different definition than the dev snapshot holds.","commonSituations":"Editing the entry file mid-`caveman dev` session; editing the agent definition between `npm run build` and a locked dev run.","solutions":["Run `npm run build` to relock, then restart the dev process","Restart dev so the expected snapshot is reloaded from the current entry","Avoid editing the entry module between snapshot capture and the locked run"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before a locked dev run, compare the snapshot against a fresh load:\nconst fresh = await loadAgent(resolve(root, config.entry));\nif (agentDefinitionSHA256(fresh) !== agentDefinitionSHA256(expectedAgent)) {\n  await exec(\"npm run build\"); // definition drifted — relock first\n}","typeGuard":null,"tryCatchPattern":"catch (e) { if (e instanceof Error && e.message === \"cave_stale_lock:dev_snapshot\") { /* restart dev / rebuild to refresh the snapshot */ } else throw e; }","preventionTips":["Restart the dev process after every entry-module edit","Rebuild before any locked run","Avoid editing the agent definition while a locked run is in flight"],"tags":["build-lock","dev","hot-reload","drift","snapshot"],"backgroundTag":"stale-build-artifact","analyzedSha":"766dce6b1394ebb56a3090748d5a0240a5aefb36","analyzedAt":"2026-08-18T03:14:35.516Z","contentChangedAt":"2026-08-18T03:14:35.516Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}