track runtime content hash for kernel venv staleness

[kevinjosethomas]

• the kernel venv could keep a stale prime-agent-runtime indefinitely because the staleness check compared a constant against itself, silently breaking mcp skills like linear and notion.
• the venv now records a content hash of the local runtime source and rebuilds automatically whenever that source changes, instead of relying on manual schema bumps.
• also asserts mcp support is importable in the readiness probe and bumps the bootstrap schema so existing stale venvs refresh on next run.

---

Note

Medium Risk
Changes Python kernel bootstrap and can force full venv rebuilds on upgrade or after local runtime edits; incorrect hashing could cause unnecessary rebuilds or miss staleness.

Overview
Fixes kernel venvs keeping an outdated prime-agent-runtime because staleness only compared the fixed package name "prime-agent-runtime" to itself, so local runtime changes never triggered a refresh (breaking MCP-related capabilities).

.bootstrap-version (schema 8) now stores a runtime identity: a sha256: hash over local pyproject.toml and all src/rlm/**/*.py when a checkout is found via resolveRuntimeIdentity / hashRuntimeSource; registry-only installs still use the package name. Readiness checks compare that identity on each ensureKernelPython run and rebuild the venv when it diverges, without relying on manual schema bumps for every runtime edit.

The runtime readiness probe also requires rlm.McpIntegration to import. Tests expect the new schema, dynamic runtime identity, and a rebuild when the recorded hash is stale.

^{Reviewed by Cursor Bugbot for commit db85a7a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Track runtime content hash to detect kernel venv staleness

• Adds resolveRuntimeIdentity in bootstrap.ts to compute a sha256 hash over rlm/*.py files and pyproject.toml when a local runtime source dir is present, falling back to 'prime-agent-runtime' for registry installs.
• Threads runtimeIdentity through kernelReady, kernelBaseReady, writeBootstrapVersion, and syncPythonSkills so the .bootstrap-version file records the content hash rather than a fixed package name.
• Any change to runtime source files (names or contents) now causes the venv to be rebuilt automatically on next kernel startup.
• Bumps BOOTSTRAP_SCHEMA from 7 to 8 and adds from rlm import McpIntegration to the runtime readiness check.
• Risk: all existing venvs at schema 7 are immediately considered stale and will be rebuilt on first use.

^{Macroscope summarized db85a7a.}

[linear]

ENG-4371 Kernel venv keeps stale prime-agent-runtime; needs generic runtime version check

Summary

The IPython kernel venv (~/.prime/agent/kernel-venv) can keep a stale prime-agent-runtime even after the local source has moved on, because the bootstrap "is this venv current?" check has no notion of runtime content/version. This silently disables features that depend on newer runtime code — most visibly the MCP integrations (Linear, Notion), which fail to import with ImportError: cannot import name 'McpIntegration' from 'rlm' and get registered as unavailable skills.

This is not an auth problem: the failure happens at the skill's very first import line (from rlm import McpIntegration), before any credential / login path runs.

Root cause

In packages/coding-agent/src/core/kernel/bootstrap.ts:

• The venv-reuse gate is kernelReady() -> bootstrapBaseVersionCurrent(), which compares version.runtime === RUNTIME_REQUIREMENT. Both sides are the literal string "prime-agent-runtime". There is no version or content hash for the runtime, so a venv built from an older (even since-deleted) local source still compares as "current".
• RUNTIME_READY_CHECK asserts rlm.run, rlm.host_request, harness CRUD, HarnessEntry.reference, etc., but does not assert anything about MCP (from rlm import McpIntegration). So a runtime missing rlm/mcp_base.py entirely still passes the readiness probe.
• The only lever that currently forces a rebuild is bumping BOOTSTRAP_SCHEMA. It was not bumped when the runtime gained MCP support, so existing venvs were never invalidated.

Observed in the wild: a kernel venv whose prime_agent_runtime direct_url.json pointed at file:///.../.worktrees/eng-4227/prime-agent-runtime (a worktree that no longer exists and predates mcp_base.py). Recorded .bootstrap-version had schema: 7, matching the running schema, so the venv was reused indefinitely.

Impact

• MCP skills (Linear, Notion) silently unavailable for users whose venv predates MCP support, with a confusing error that looks auth-related.
• Any future runtime change is invisible to existing venvs unless someone remembers to bump BOOTSTRAP_SCHEMA. Easy to forget; affects end users, not just local dev.

Proposed fix

Make venv staleness detection track the runtime version generically, instead of relying on a static string + manual schema bumps:

1. Add a runtime version/identity that updates automatically whenever the runtime changes. Options:
   • Record prime_agent_runtime.__version__ (and bump it on every runtime change), or
   • Record a content hash of the installed rlm package, and compare it against the local source on startup.
2. Store that value in .bootstrap-version and compare it in bootstrapBaseVersionCurrent(); a mismatch triggers reinstall from local source.

This way the venv refreshes for users automatically on any runtime change, without per-feature readiness assertions or remembering to bump the schema. (Adding a specific McpIntegration assertion to RUNTIME_READY_CHECK would fix this one symptom, but the generic version check is the durable fix.)

Workaround

Delete and rebuild the venv: rm -rf ~/.prime/agent/kernel-venv (next IPython run rebuilds from local prime-agent-runtime/).

Review in Linear

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f2c6b78. Configure here.}

[macroscopeapp]

🟡 Medium

prime-agent/packages/coding-agent/src/core/kernel/bootstrap.ts

Line 530 in c2ab34e

function runtimeCandidateDirs(): string[] {

resolveRuntimeSourceDir() returns the first candidate directory containing a pyproject.toml, and runtimeCandidateDirs() lists dist/prime-agent-runtime ahead of the live source checkout. After packages/coding-agent is built once, the dist/prime-agent-runtime snapshot becomes stale relative to the real source tree, but resolveRuntimeIdentity() and bootstrapVenv() still hash and install from that stale copy. The kernel venv then uses outdated runtime code and never rebuilds when the actual local runtime source changes, defeating the staleness tracking this PR adds. Consider preferring the live source checkout when it exists, or documenting why the built copy should take precedence.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/coding-agent/src/core/kernel/bootstrap.ts around line 530:

`resolveRuntimeSourceDir()` returns the first candidate directory containing a `pyproject.toml`, and `runtimeCandidateDirs()` lists `dist/prime-agent-runtime` ahead of the live source checkout. After `packages/coding-agent` is built once, the `dist/prime-agent-runtime` snapshot becomes stale relative to the real source tree, but `resolveRuntimeIdentity()` and `bootstrapVenv()` still hash and install from that stale copy. The kernel venv then uses outdated runtime code and never rebuilds when the actual local runtime source changes, defeating the staleness tracking this PR adds. Consider preferring the live source checkout when it exists, or documenting why the built copy should take precedence.