Shared memory and context tools for agentic work.
Code Rooms
//! Freshness at first contact — the in-process half of the battery.
//!
//! The process-restart half (a stale graph declared on `north`/`health`, the
//! named refresh clearing it) lives in `tests/graph_freshness_first_contact.rs`.
//! This file pins the parts that need a hand on `caller_root`, which no stdio
//! client can set: a caller working in a git worktree of the indexed repository,
//! at another commit, must get an honest signal — the drift, or a root mismatch —
//! and never silence. It also pins the cost side: a fresh graph adds nothing, and
//! the note is not a new verb.
use crate as m1nd_mcp;
use m1nd_core::domain::DomainConfig;
use m1nd_core::graph::Graph;
use m1nd_mcp::server::{dispatch_tool, McpConfig};
use m1nd_mcp::session::SessionState;
use serde_json::json;
use std::path::{Path, PathBuf};
use std::process::Command;
const AGENT: &str = "graph-freshness-internal-probe";
/// The registry size this change must leave untouched (criteria F4: no new verb).
const REGISTERED_TOOL_COUNT: usize = 147;
fn git_available() -> bool {
Command::new("git").arg("--version").output().is_ok()
}
/// Run git in `dir` with no user or system configuration in play.
fn git(dir: &Path, git_home: &Path, args: &[&str]) -> String {
let output = Command::new("git")
.args([
"-c",
"user.name=freshness-fixture",
"user.email=fixture@example.invalid",
"commit.gpgsign=false",
"init.defaultBranch=main",
])
.args(args)
.current_dir(dir)
.env("HOME", git_home)
.env("GIT_CONFIG_NOSYSTEM", "1")
.env_remove("GIT_DIR")
.env_remove("GIT_WORK_TREE")
.env_remove("GIT_COMMON_DIR")
.output()
.expect("spawn git");
assert!(
output.status.success(),
"git {args:?} failed: {}",
String::from_utf8_lossy(&output.stderr)
);
String::from_utf8_lossy(&output.stdout).trim().to_string()
fn write_crate(root: &Path, padding: usize) {
std::fs::create_dir_all(root.join("src")).expect("mk src");
std::fs::write(
root.join("Cargo.toml"),
"[package]\nname = \"repo-alpha\"\nversion = \"0.0.0\"\n",
)
.expect("Cargo.toml");
let mut source = String::new();
for index in 0..padding {
source.push_str(&format!("pub fn filler_{index}() -> u64 {{ {index} }}\n"));
source.push_str("pub fn worktree_probe_target() -> u64 {\n 42\n}\n");
std::fs::write(root.join("src/lib.rs"), source).expect("lib.rs");
fn canonical(path: &Path) -> String {
std::fs::canonicalize(path)
.unwrap_or_else(|_| path.to_path_buf())
.to_string_lossy()
.to_string()
fn build_state(runtime: &Path) -> SessionState {
std::fs::create_dir_all(runtime).expect("runtime dir");
let config = McpConfig {
graph_source: runtime.join("graph_snapshot.json"),
plasticity_state: runtime.join("plasticity_state.json"),
runtime_dir: Some(runtime.to_path_buf()),
registry_dir: Some(runtime.join("registry")),
..McpConfig::default()
};
SessionState::initialize(Graph::new(), &config, DomainConfig::code()).expect("init session")
/// A repository at C1, its graph built by the production code ingest.
struct Fixture {
_temp: tempfile::TempDir,
runtime: PathBuf,
git_home: PathBuf,
main: PathBuf,
c1: String,
state: SessionState,
fn indexed_fixture() -> Fixture {
let temp = tempfile::tempdir().expect("tempdir");
let git_home = temp.path().join("git-home");
std::fs::create_dir_all(&git_home).expect("git home");
let main = temp.path().join("repo-alpha");
write_crate(&main, 0);
git(&main, &git_home, &["init", "-q"]);
git(&main, &git_home, &["add", "-A"]);
git(&main, &git_home, &["commit", "-q", "-m", "c1"]);
let c1 = git(&main, &git_home, &["rev-parse", "HEAD"]);
let runtime = temp.path().join("runtime");
let mut state = build_state(&runtime);
let ingested = dispatch_tool(
&mut state,
"ingest",
&json!({
"agent_id": AGENT,
"path": canonical(&main),
"adapter": "code",
"mode": "replace",
}),
.expect("index the fixture at C1");
ingested["node_count"].as_u64().unwrap_or(0) > 0,
"the fixture must produce a graph: {ingested}"
Fixture {
_temp: temp,
runtime,
git_home,
main,
c1,
state,
/// A worktree of the fixture repository on its own branch, one commit past C1.
fn worktree_at_another_commit(fixture: &Fixture, worktree: &Path, branch: &str) -> String {
let path = worktree.to_string_lossy().to_string();
git(
&fixture.main,
&fixture.git_home,
&["worktree", "add", "-q", "-b", branch, &path],
write_crate(worktree, 12);
worktree,
&["commit", "-q", "-am", branch],
let head = git(worktree, &fixture.git_home, &["rev-parse", "HEAD"]);
assert_ne!(head, fixture.c1, "the worktree must sit at another commit");
head
fn north(state: &mut SessionState) -> serde_json::Value {
dispatch_tool(
"north",
&json!({ "agent_id": AGENT, "task": "where is worktree_probe_target defined" }),
.expect("north")
fn health(state: &mut SessionState) -> serde_json::Value {
dispatch_tool(state, "health", &json!({ "agent_id": AGENT })).expect("health")
/// Honest = the packet either refuses to vouch for the caller's repo (reception
/// mismatch) or declares the drift against the caller's own checkout.
fn assert_honest(surface: &str, packet: &serde_json::Value, indexed: &str, head: &str) {
let mismatch = packet["reception"]["match"].as_str() == Some("caller_root_mismatch");
let drift = packet.get("graph_drift").is_some_and(|note| {
note["indexed"].as_str() == Some(&indexed[..12])
&& note["head"].as_str() == Some(&head[..12])
});
mismatch || drift,
"{surface}: a caller in a worktree at another commit got neither a root mismatch nor \
a drift note — silence: {packet}"
#[test]
fn a_caller_in_a_worktree_at_another_commit_is_never_met_with_silence() {
if !git_available() {
eprintln!("skipping: git is not on PATH");
return;
let mut fixture = indexed_fixture();
// Nested: the worktree lives INSIDE the indexed root, so the bound brain
// covers it by path and reception alone stays silent.
let nested = fixture.main.join(".worktrees").join("feature");
let nested_head = worktree_at_another_commit(&fixture, &nested, "feature");
fixture.state.caller_root = Some(canonical(&nested));
let c1 = fixture.c1.clone();
let packet = north(&mut fixture.state);
assert_honest("north (nested worktree)", &packet, &c1, &nested_head);
let packet = health(&mut fixture.state);
assert_honest("health (nested worktree)", &packet, &c1, &nested_head);
// Sibling: the worktree lives outside the indexed root.
let sibling = fixture
.main
.parent()
.expect("fixture parent")
.join("repo-alpha-sibling");
let sibling_head = worktree_at_another_commit(&fixture, &sibling, "sibling");
fixture.state.caller_root = Some(canonical(&sibling));
assert_honest("north (sibling worktree)", &packet, &c1, &sibling_head);
assert_honest("health (sibling worktree)", &packet, &c1, &sibling_head);
fn a_graph_at_head_adds_no_drift_key() {
fixture.state.caller_root = Some(canonical(&fixture.main));
assert!(packet.get("graph_drift").is_none(), "{packet}");
fn the_drift_note_is_not_a_new_verb() {
let registered = m1nd_mcp::server::all_tool_schemas()["tools"]
.as_array()
.map(Vec::len)
.unwrap_or(0);
assert_eq!(registered, REGISTERED_TOOL_COUNT);
assert_eq!(
m1nd_mcp::action_routes::MCP_TOOL_ROUTE_NAMES.len(),
REGISTERED_TOOL_COUNT
/// Boot compatibility: the indexed commit is advisory and lives only in its
/// sidecar, so the checkpoint candidate — and the strict rebuild digest an
/// older binary recomputes at boot — is byte-for-byte the same whether the
/// commit is known, unknown, published, or deleted.
fn the_checkpoint_digest_is_blind_to_the_indexed_commit() {
let sidecar = fixture
.runtime
.join(crate::graph_drift::INDEXED_VCS_STATE_FILE);
fixture.state.indexed_vcs.is_some(),
"the code ingest must record the commit it walked"
sidecar.is_file(),
"the direct persist must publish the sidecar after the graph"
let known = fixture
.state
.authoritative_checkpoint_state_digest()
.expect("digest with the commit known");
fixture.state.indexed_vcs = None;
std::fs::remove_file(&sidecar).expect("delete the sidecar");
let unknown = fixture
.expect("digest with the commit unknown");
known, unknown,
"the indexed commit leaked into the checkpoint digest"
/// The warm-session cost contract: the per-call drift check never reads the
/// graph (so it cannot be O(graph)), spawns no process while the graph is at
/// HEAD, and pays for a drifted HEAD's git counts once, not per call.
fn the_drift_check_never_reads_the_graph_and_caches_its_git_work() {
use crate::graph_drift::{graph_drift_note, probe};
use std::sync::mpsc;
use std::time::Duration;
// Hold the graph's write lock on another thread for the whole run. A drift
// check that touched the graph would block on it until the holder gives up,
// and the holder reports that it had to.
let graph = fixture.state.graph.clone();
let (locked_tx, locked_rx) = mpsc::channel();
let (done_tx, done_rx) = mpsc::channel::<()>();
let holder = std::thread::spawn(move || {
let _write = graph.write();
locked_tx.send(()).expect("signal lock held");
done_rx.recv_timeout(Duration::from_secs(30)).is_err()
locked_rx.recv().expect("lock held");
probe::reset();
for _ in 0..50 {
assert!(graph_drift_note(&mut fixture.state).is_none());
probe::git_spawns(),
0,
"at HEAD the drift check must read HEAD from files, not spawn git per call"
// HEAD moves: the counts are measured once, then served from the cache.
write_crate(&fixture.main, 12);
&["commit", "-q", "-am", "c2"],
let first = graph_drift_note(&mut fixture.state).expect("drift after a new commit");
let measured = probe::git_spawns();
assert!(measured > 0, "the first drifted call measures the counts");
assert_eq!(graph_drift_note(&mut fixture.state), Some(first.clone()));
measured,
"a drifted HEAD must be measured once per (indexed commit, checkout, HEAD)"
probe::witness_computations(),
"the drift check must never fingerprint the graph"
done_tx.send(()).expect("release the graph lock");
let blocked = holder.join().expect("lock holder");
!blocked,
"the drift check waited on the graph lock: it reads the graph per call"