Shared memory and context tools for agentic work.
Code Rooms
"use strict";
const assert = require("node:assert/strict");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");
const test = require("node:test");
const {
acquireAgentRuntimeLease,
agentRuntimeCacheTarget,
planAgentRuntimeCacheTarget,
assertAgentSourceIdentity,
agentStatePaths,
prepareAgentState,
ensureAgentRuntimeIdentity,
releaseAgentRuntimeLease,
} = require("../lib/agent-runtime-cache");
const symlinkTestOptions = {
skip: process.platform === "win32" && "Windows symlink creation requires host privilege",
};
test("readonly cache selection does not create missing state and agrees with normal identity", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-readonly-cache-plan-"));
try {
const repo = path.join(fixture, "repo-alpha"), cache = path.join(fixture, "missing-cache");
fs.mkdirSync(repo);
const env = { M1ND_AGENT_CACHE_DIR: cache };
const planned = planAgentRuntimeCacheTarget(repo, env);
assert.equal(fs.existsSync(cache), false);
const selected = agentRuntimeCacheTarget(repo, env);
assert.deepEqual(planned.identity, selected.identity);
assert.equal(planned.runtimeDir, selected.runtimeDir);
assert.equal(fs.readdirSync(cache).length, 0);
} finally { fs.rmSync(fixture, { recursive: true, force: true }); }
});
test("automatic cache refuses ambient Git repository redirection before creating a cache", () => {
const { execFileSync } = require("node:child_process");
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-git-redirection-"));
const keys = ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_NAMESPACE"];
const saved = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
for (const key of keys) delete process.env[key];
const repo = path.join(fixture, "repo-alpha"), other = path.join(fixture, "repo-beta");
fs.mkdirSync(other);
execFileSync("git", ["-C", other, "init", "-q", "-b", "foreign-view"], { stdio: "pipe" });
for (const key of keys) {
const cache = path.join(fixture, `cache-${key}`);
process.env[key] = key === "GIT_WORK_TREE" ? other : path.join(other, ".git");
assert.throws(() => agentRuntimeCacheTarget(repo, { M1ND_AGENT_CACHE_DIR: cache }),
{ code: "M1ND_AGENT_GIT_REDIRECTION" }, key);
delete process.env[key];
}
const selected = agentRuntimeCacheTarget(repo, { M1ND_AGENT_CACHE_DIR: path.join(fixture, "selected-cache") });
process.env.GIT_DIR = path.join(other, ".git");
assert.throws(() => assertAgentSourceIdentity(selected.sourceGuard, "before query"),
{ code: "M1ND_AGENT_SOURCE_IDENTITY_CHANGED" });
} finally {
if (saved[key] === undefined) delete process.env[key];
else process.env[key] = saved[key];
fs.rmSync(fixture, { recursive: true, force: true });
test("automatic cache refuses a bare repository instead of attesting a source worktree", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-bare-view-"));
const repo = path.join(fixture, "repo-alpha"), cache = path.join(fixture, "cache");
execFileSync("git", ["init", "--bare", "-q", repo], { stdio: "pipe" });
{ code: "M1ND_AGENT_NOT_WORKTREE" });
test("cache source guard rejects branch and HEAD drift instead of reusing its selected identity", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-source-guard-git-"));
const repo = path.join(fixture, "repo-alpha");
const git = (...args) => execFileSync("git", ["-C", repo, ...args], { stdio: "pipe" });
git("init", "-q");
fs.writeFileSync(path.join(repo, "signal.js"), "export const signal = 1;\n");
git("add", ".");
git("-c", "user.name=Fixture User", "-c", "user.email=fixture@example.invalid", "commit", "-qm", "initial");
const target = agentRuntimeCacheTarget(repo, { M1ND_AGENT_CACHE_DIR: path.join(fixture, "cache") });
assert.doesNotThrow(() => assertAgentSourceIdentity(target.sourceGuard, "selected"));
git("checkout", "-qb", "other-branch");
assert.throws(() => assertAgentSourceIdentity(target.sourceGuard, "before startup"), /source identity changed.*before startup/);
const branchTarget = agentRuntimeCacheTarget(repo, { M1ND_AGENT_CACHE_DIR: path.join(fixture, "cache") });
fs.appendFileSync(path.join(repo, "signal.js"), "export const later = 2;\n");
git("-c", "user.name=Fixture User", "-c", "user.email=fixture@example.invalid", "commit", "-qm", "advance");
assert.throws(() => assertAgentSourceIdentity(branchTarget.sourceGuard, "after query"), /source identity changed.*after query/);
test("cache source guard rejects root replacement even with the same path and Git revision", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-source-guard-root-"));
const repo = path.join(fixture, "repo-alpha"), parked = path.join(fixture, "parked");
execFileSync("git", ["-C", repo, "init", "-q"]);
fs.renameSync(repo, parked);
fs.cpSync(parked, repo, { recursive: true });
assert.throws(() => assertAgentSourceIdentity(target.sourceGuard, "before return"), /source identity changed.*before return/);
test("cache source guard fails closed if Git metadata becomes unreadable", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-source-guard-unreadable-"));
fs.renameSync(path.join(repo, ".git"), path.join(repo, "saved-git"));
fs.writeFileSync(path.join(repo, ".git"), "gitdir: missing-git-directory\n");
assert.throws(() => assertAgentSourceIdentity(target.sourceGuard, "after refresh"), /source identity changed.*after refresh/);
fs.unlinkSync(path.join(repo, ".git"));
fs.renameSync(path.join(repo, "saved-git"), path.join(repo, ".git"));
const previousPath = process.env.PATH;
process.env.PATH = "";
assert.throws(() => assertAgentSourceIdentity(target.sourceGuard, "missing Git"), /source identity changed.*Git.*unavailable/);
if (previousPath === undefined) delete process.env.PATH;
else process.env.PATH = previousPath;
test("state-dir plans storage without writes and prepares private registry/cache siblings", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-state-plan-"));
const state = path.join(fixture, "private-state");
const plan = agentStatePaths(repo, state);
assert.equal(fs.existsSync(state), false);
prepareAgentState(plan);
const target = agentRuntimeCacheTarget(repo, { M1ND_AGENT_CACHE_DIR: plan.cache_base });
assert.equal(path.dirname(target.runtimeDir), plan.cache_base);
assert.equal(fs.statSync(plan.registry_root).isDirectory(), true);
if (process.platform !== "win32") assert.equal(fs.statSync(plan.state_root).mode & 0o077, 0);
test("state-dir rejects source-tree state before creating it", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-state-source-"));
const state = path.join(fixture, "derived");
assert.throws(() => agentStatePaths(fixture, state), /outside the indexed repository/);
test("state-dir refuses symlink roots and a symlinked registry without adoption", symlinkTestOptions, () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-state-symlink-"));
const repo = path.join(fixture, "repo-alpha"), outside = path.join(fixture, "outside");
const state = path.join(fixture, "state"), alias = path.join(fixture, "alias");
for (const p of [repo, outside, state]) fs.mkdirSync(p, { mode: 0o700 });
fs.symlinkSync(outside, alias, "dir");
assert.throws(() => prepareAgentState(agentStatePaths(repo, alias)), /non-symlink/);
fs.symlinkSync(outside, path.join(state, "registry"), "dir");
assert.throws(() => prepareAgentState(agentStatePaths(repo, state)), /non-symlink/);
const sourceAlias = path.join(fixture, "source-alias");
fs.symlinkSync(repo, sourceAlias, "dir");
assert.throws(() => agentStatePaths(repo, path.join(sourceAlias, "new-state")), /outside the indexed repository/);
assert.deepEqual(fs.readdirSync(outside), []);
assert.deepEqual(fs.readdirSync(repo), []);
test("state-dir CLI scope is read-only and conflicting launch overrides fail before writes", () => {
const { spawnSync } = require("node:child_process");
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-state-cli-"));
const repo = path.join(fixture, "repo-alpha"), state = path.join(fixture, "state");
const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith("M1ND_")));
const base = [path.resolve(__dirname, "../bin/m1nd.js"), "agent", "scope", "--repo", repo, "--binary", process.execPath, "--state-dir", state, "--json"];
function run(extra, additions = {}) { return spawnSync(process.execPath, [...base, ...extra], { env: { ...env, ...additions }, encoding: "utf8", timeout: 10000 }); }
const plan = run(["--no-attach"]);
assert.equal(plan.status, 0, plan.stderr);
assert.equal(JSON.parse(plan.stdout).runtime.state_selection.state_root, fs.realpathSync(fixture) + path.sep + "state");
for (const extra of [[], ["--no-attach", "--shared-runtime"], ["--no-attach", "--runtime-dir", state]]) {
const result = run(extra);
assert.equal(result.status, 1);
assert.match(result.stderr, /requires --no-attach/);
for (const key of ["M1ND_MCP_ARGS", "M1ND_RUNTIME_DIR", "M1ND_RUNTIME_BASE", "M1ND_GRAPH_SOURCE", "M1ND_PLASTICITY_STATE", "M1ND_ATTACH_URL"]) {
const result = run(["--no-attach"], { [key]: "conflicting-override" });
assert.ok(result.stderr.includes(key), result.stderr);
test("state-dir continuation commands retain the selected isolated storage", () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-state-continuation-"));
const repo = path.join(fixture, "repo-alpha"), state = path.join(fixture, "state with space");
fs.mkdirSync(path.join(repo, "src"));
fs.writeFileSync(path.join(repo, "src/config.js"), "export const configuration = 1;\n");
for (const command of [["scope"], ["handoff"], ["auto", "--query", "locate configuration"],
["auto", "--query", "understand this repo"], ["next", "--query", "src/config.js"],
["recover", "--from", "transport_closed"], ["recover", "--from", "wrong_workspace_binding"]]) {
const run = spawnSync(process.execPath, [path.resolve(__dirname, "../bin/m1nd.js"), "agent", ...command,
"--repo", repo, "--binary", process.execPath, "--no-attach", "--state-dir", state, "--json"],
{ env, encoding: "utf8", timeout: 10000 });
assert.equal(run.status, 0, run.stderr);
const payload = JSON.parse(run.stdout);
const instructions = [payload.action?.action?.command, payload.handoff?.resume_hint,
...(payload.next_actions || []),
...(payload.recovery_plan || []).map((step) => step.command)].filter((text) => /(?:^| )m1nd agent /.test(text || ""));
assert.ok(instructions.length > 0, JSON.stringify(payload));
for (const instruction of instructions) {
assert.match(instruction, /--state-dir /, instruction);
assert.match(instruction, /--no-attach(?: |$)/, instruction);
assert.ok(instruction.includes("state with space"), instruction);
test("runtime cache target refuses a symlinked cache base", symlinkTestOptions, () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-base-symlink-"));
const repo = path.join(fixture, "repo");
const outside = path.join(fixture, "outside");
const cacheBase = path.join(fixture, "cache");
fs.mkdirSync(outside);
fs.symlinkSync(outside, cacheBase, "dir");
assert.throws(
() => agentRuntimeCacheTarget(repo, { ...process.env, M1ND_AGENT_CACHE_DIR: cacheBase }),
/agent runtime cache base must be a non-symlink directory/
);
test("runtime cache target refuses a cache base writable by group or other users", { skip: process.platform === "win32" }, () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-insecure-base-"));
fs.mkdirSync(cacheBase);
fs.chmodSync(cacheBase, 0o777);
/agent runtime cache base must not be writable by group or other users/
test("runtime cache target refuses a cache base beneath a non-sticky writable parent", { skip: process.platform === "win32" }, () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-insecure-parent-"));
const parent = path.join(fixture, "writable-parent");
const cacheBase = path.join(parent, "cache");
fs.mkdirSync(parent);
fs.chmodSync(parent, 0o777);
/agent runtime cache ancestor must not be writable by group or other users unless sticky/
test("runtime cache target refuses a foreign-owned private ancestor", {
skip: process.platform === "win32" || typeof process.getuid !== "function",
}, (t) => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-foreign-parent-"));
const parent = path.join(fixture, "private-parent");
fs.mkdirSync(parent, { mode: 0o700 });
const realStatSync = fs.statSync;
const canonicalParent = fs.realpathSync(parent);
const foreignUid = process.getuid() === 1 ? 2 : 1;
t.mock.method(fs, "statSync", (target, ...args) => {
const stat = realStatSync(target, ...args);
return target === canonicalParent ? Object.assign(Object.create(stat), { uid: foreignUid }) : stat;
/agent runtime cache ancestor must be owned by the current user or root/
t.mock.restoreAll();
test("runtime cache rejects a symlinked runtime directory without writing through it", symlinkTestOptions, async () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-symlink-"));
const cacheRoot = path.join(fixture, "cache");
const runtimeDir = path.join(cacheRoot, "runtime");
fs.mkdirSync(cacheRoot, { recursive: true });
fs.mkdirSync(outside, { recursive: true });
fs.symlinkSync(outside, runtimeDir, "dir");
await assert.rejects(
acquireAgentRuntimeLease(runtimeDir),
/agent runtime cache runtime directory must be a non-symlink directory/
assert.deepEqual(fs.readdirSync(outside), [], "cache lease wrote through the symlink");
test("cancelled cache waiter removes its waiter proof without acquiring another owner", async () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-cancelled-waiter-"));
const runtimeDir = path.join(fixture, "runtime");
const holder = await acquireAgentRuntimeLease(runtimeDir);
const ownerProof = path.join(holder.ownerDir, "owner.json");
const ownerBefore = fs.readFileSync(ownerProof, "utf8");
const interrupted = Object.assign(new Error("m1nd agent interrupted by SIGTERM"), {
code: "M1ND_AGENT_INTERRUPTED",
signal: "SIGTERM",
exitCode: 143,
const cancellation = { error: null };
const originalSetTimeout = global.setTimeout;
let waiterObserved = false;
global.setTimeout = (callback, delay, ...args) => {
if (delay === 25 && !waiterObserved) {
waiterObserved = true;
cancellation.error = interrupted;
return originalSetTimeout(callback, delay, ...args);
acquireAgentRuntimeLease(runtimeDir, { cancellation }),
(error) => error === interrupted
assert.equal(waiterObserved, true, "fixture did not reach the real lease waiter");
assert.equal(fs.readFileSync(ownerProof, "utf8"), ownerBefore, "cancelled waiter modified the proven owner");
assert.deepEqual(
fs.readdirSync(runtimeDir).filter((name) => name.startsWith(".agent-cache-waiter-v1-")),
[],
"cancelled waiter left ownership state behind"
global.setTimeout = originalSetTimeout;
releaseAgentRuntimeLease(holder);
test("runtime cache refuses a preexisting symlinked owner directory", symlinkTestOptions, async () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-owner-symlink-"));
const outside = path.join(fixture, "outside-owner");
fs.mkdirSync(runtimeDir, { recursive: true });
fs.symlinkSync(outside, path.join(runtimeDir, ".agent-cache-owner-v1"), "dir");
/agent runtime cache owner directory must be a non-symlink directory/
assert.deepEqual(fs.readdirSync(outside), [], "cache lease wrote through the owner symlink");
test("runtime cache refuses a symlinked identity manifest", symlinkTestOptions, async () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-identity-symlink-"));
const outsideIdentity = path.join(fixture, "outside-identity.json");
const identity = {
schema: "m1nd-agent-runtime-cache-v1",
canonical_root: path.join(fixture, "repo"),
source_revision: { kind: "non_git", head: null, branch: null },
const lease = await acquireAgentRuntimeLease(runtimeDir);
fs.writeFileSync(outsideIdentity, `${JSON.stringify(identity)}\n`);
fs.symlinkSync(outsideIdentity, path.join(runtimeDir, "agent-cache-identity.json"));
() => ensureAgentRuntimeIdentity(lease, identity),
/agent runtime cache identity must be a regular non-symlink file/
assert.equal(fs.readFileSync(outsideIdentity, "utf8"), `${JSON.stringify(identity)}\n`);
releaseAgentRuntimeLease(lease);
test("runtime cache refuses a symlinked owner proof without creating identity state", symlinkTestOptions, async () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-owner-proof-symlink-"));
const outsideProof = path.join(fixture, "outside-owner.json");
const owner = { schema: "m1nd-agent-runtime-owner-v1", token: lease.token, pid: process.pid };
const ownerProof = path.join(lease.ownerDir, "owner.json");
fs.unlinkSync(ownerProof);
fs.writeFileSync(outsideProof, `${JSON.stringify(owner)}\n`);
fs.symlinkSync(outsideProof, ownerProof);
/agent runtime cache owner proof must be a regular non-symlink file/
assert.equal(fs.existsSync(path.join(runtimeDir, "agent-cache-identity.json")), false);
assert.equal(fs.readFileSync(outsideProof, "utf8"), `${JSON.stringify(owner)}\n`);
test("runtime cache release refuses an owner directory swapped for a symlink", symlinkTestOptions, async () => {
const fixture = fs.mkdtempSync(path.join(os.tmpdir(), "m1nd-agent-cache-owner-swap-"));
const outsideOwner = path.join(fixture, "outside-owner");
fs.mkdirSync(outsideOwner, { recursive: true });
fs.writeFileSync(path.join(outsideOwner, "owner.json"), `${JSON.stringify(owner)}\n`);
fs.rmSync(lease.ownerDir, { recursive: true, force: true });
fs.symlinkSync(outsideOwner, lease.ownerDir, "dir");
() => releaseAgentRuntimeLease(lease),
/agent runtime cache owner proof is unreadable; refusing mutation/
assert.equal(fs.existsSync(path.join(outsideOwner, "owner.json")), true, "release unlinked the outside proof");