Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
rmSync,
readFileSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { IS_WINDOWS } from "../helpers/platform.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { HYGIENE_AUDIT_DIR } from "../../src/core/brain/audit-dirs.ts";
import { VERB_HELP } from "../../src/cli/brain/help-text.ts";
import { runCli } from "../helpers/run-cli.ts";
import { splitPosixShellWords } from "../helpers/posix-shell-words.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
let tmp: string;
let vault: string;
let configPath: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-entity-cli-"));
vault = join(tmp, "vault");
configPath = join(tmp, "config.yaml");
writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });
async function seed(): Promise<void> {
const out = await runCli(
[
"brain",
"entity",
"set",
"people",
"Ada",
"--alias",
"the operator",
"--body",
"Vault operator.",
],
{ env: env() },
);
expect(out.returncode).toBe(0);
}
describe("o2b brain entity", () => {
test("set creates and reports the entity id", async () => {
const out = await runCli(["brain", "entity", "set", "people", "Ada", "--json"], {
env: env(),
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as Record<string, unknown>;
expect(payload["id"]).toBe("ent-people-ada");
expect(payload["created"]).toBe(true);
});
test("get resolves by alias and prints the record", async () => {
await seed();
const out = await runCli(["brain", "entity", "get", "the operator", "--json"], {
env: env(),
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as Record<string, unknown>;
expect(payload["id"]).toBe("ent-people-ada");
expect(payload["name"]).toBe("Ada");
});
test("get returns exit 2 for an unknown entity", async () => {
await seed();
const out = await runCli(["brain", "entity", "get", "nobody", "--json"], { env: env() });
expect(out.returncode).toBe(2);
});
test("list filters by category", async () => {
await seed();
await runCli(["brain", "entity", "set", "projects", "Open Second Brain"], { env: env() });
const out = await runCli(["brain", "entity", "list", "--category", "people", "--json"], {
env: env(),
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as { entities: Array<{ id: string }> };
expect(payload.entities.map((e) => e.id)).toEqual(["ent-people-ada"]);
});
test("relate writes a typed relation", async () => {
await seed();
await runCli(["brain", "entity", "set", "projects", "Open Second Brain"], { env: env() });
const out = await runCli(
["brain", "entity", "relate", "Ada", "related", "Open Second Brain", "--json"],
{ env: env() },
);
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as { relations: Array<{ target: string }> };
expect(payload.relations[0]!.target).toBe("ent-projects-open-second-brain");
});
test("archive and restore round-trip", async () => {
await seed();
const archived = await runCli(["brain", "entity", "archive", "Ada", "--json"], {
env: env(),
});
expect(archived.returncode).toBe(0);
expect((JSON.parse(archived.stdout) as Record<string, unknown>)["status"]).toBe("archived");
const gone = await runCli(["brain", "entity", "get", "Ada"], { env: env() });
expect(gone.returncode).toBe(2);
const restored = await runCli(["brain", "entity", "archive", "Ada", "--restore", "--json"], {
env: env(),
});
expect(restored.returncode).toBe(0);
expect((JSON.parse(restored.stdout) as Record<string, unknown>)["status"]).toBe("active");
});
test("duplicate alias claim fails with a clear error", async () => {
await seed();
const out = await runCli(
["brain", "entity", "set", "people", "Imposter", "--alias", "the operator"],
{ env: env() },
);
expect(out.returncode).not.toBe(0);
expect(out.stderr).toContain("alias");
});
test("set strips Markdown decoration from the stored name", async () => {
const out = await runCli(["brain", "entity", "set", "projects", "**Mercury**", "--json"], {
env: env(),
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as Record<string, unknown>;
expect(payload["name"]).toBe("Mercury");
expect(payload["id"]).toBe("ent-projects-mercury");
});
test("set rejects a structurally-junk name with a non-zero exit", async () => {
const out = await runCli(["brain", "entity", "set", "people", "***"], { env: env() });
expect(out.returncode).not.toBe(0);
expect(out.stderr).toContain("invalid entity label");
});
test("prune is dry-run by default and reports no candidates on a clean vault", async () => {
await seed();
const out = await runCli(["brain", "entity", "prune", "--json"], { env: env() });
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as { confirmed: boolean; candidates: unknown[] };
expect(payload.confirmed).toBe(false);
expect(payload.candidates).toEqual([]);
});
});
/**
* Recall-quality A4: `o2b brain entity lexicon rebuild` derives the
* store-learned lexicon artifact. Dry-run report by default; a derived
* write is not destructive, so writing takes `--apply`, never `--confirm`
* - and the verb writes ONLY the derived artifact, never entity nodes.
*/
describe("o2b brain entity lexicon rebuild (recall-quality A4)", () => {
/** A corpus page whose tokens teach the artifact; caseful, `notes` common. */
function seedCorpus(): void {
writeFileSync(
join(vault, "corpus-page.md"),
"Notes about the setup. The runner kept notes. Notes ran, notes ran again.\n",
);
}
test("dry-run by default: reports, writes nothing", async () => {
seedCorpus();
const out = await runCli(["brain", "entity", "lexicon", "rebuild", "--json"], {
env: env(),
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as Record<string, unknown>;
expect(payload["applied"]).toBe(false);
expect(Number(payload["entries"])).toBeGreaterThan(0);
expect(payload["schema"]).toBe("o2b.entity-lexicon.v1");
expect(existsSync(join(vault, "Brain", "entities", "lexicon.json"))).toBe(false);
});
test("--apply writes only the derived artifact (no --confirm needed)", async () => {
seedCorpus();
const out = await runCli(["brain", "entity", "lexicon", "rebuild", "--apply", "--json"], {
env: env(),
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as Record<string, unknown>;
expect(payload["applied"]).toBe(true);
const artifactPath = join(vault, "Brain", "entities", "lexicon.json");
expect(existsSync(artifactPath)).toBe(true);
const doc = JSON.parse(readFileSync(artifactPath, "utf8")) as Record<string, unknown>;
expect(doc["schema"]).toBe("o2b.entity-lexicon.v1");
expect(typeof doc["corpus_scope"]).toBe("string");
expect(typeof doc["dataset_hash"]).toBe("string");
// Only the derived artifact: no entity nodes were minted by the rebuild.
expect(readdirSync(join(vault, "Brain", "entities")).filter((f) => f.endsWith(".md"))).toEqual(
[],
);
});
test("a rebuilt lexicon gates creation end to end: a learned common word is refused", async () => {
seedCorpus();
const rebuild = await runCli(["brain", "entity", "lexicon", "rebuild", "--apply"], {
env: env(),
});
expect(rebuild.returncode).toBe(0);
expect(rebuild.stdout).toContain("lexicon");
const refused = await runCli(["brain", "entity", "set", "people", "Notes"], { env: env() });
expect(refused.returncode).not.toBe(0);
expect(refused.stderr).toContain("function-word-run");
// A code-shaped label still admits beside the lexicon.
const code = await runCli(["brain", "entity", "set", "systems", "FTS5"], { env: env() });
expect(code.returncode).toBe(0);
});
test("an unknown lexicon subcommand is a usage error", async () => {
const out = await runCli(["brain", "entity", "lexicon", "polish"], { env: env() });
expect(out.returncode).not.toBe(0);
});
});
/**
* Recall-quality review M3: `entity prune --confirm` must agree with the
* A2 creation policy. The advisory verdict classes - a single-token shout
* (NASA, a brand or acronym) and a function-word run (Meeting, a topic) -
* stay in place unless the operator opts in with `--include-advisory`;
* structural junk still prunes by default.
*/
describe("o2b brain entity prune - advisory classes are opt-in (recall-quality M3)", () => {
function seedCorpus(): void {
writeFileSync(
join(vault, "corpus-page.md"),
"Meeting notes about the setup. The weekly meeting ran. " +
"Notes ran, the meeting kept notes, notes ran again.\n",
);
}
/** Write an entity node directly, bypassing the creation quality gate. */
function writeNode(category: string, id: string, name: string): string {
const dir = join(vault, "Brain", "entities", category);
mkdirSync(dir, { recursive: true });
const path = join(dir, `${id}.md`);
writeFileSync(
path,
[
"---",
"kind: brain-entity",
`entity_id: ${id}`,
`category: ${category}`,
`name: ${name}`,
"status: active",
"created_at: 2026-07-18T00:00:00Z",
"updated_at: 2026-07-18T00:00:00Z",
"tags:",
" - brain",
" - brain/entity",
"---",
"",
`# ${name}`,
"",
].join("\n"),
);
return path;
}
/** A caseful lexicon plus one advisory acronym, one advisory topic, one junk node. */
async function seedAdvisoryStore(): Promise<{ nasa: string; meeting: string; junk: string }> {
seedCorpus();
const rebuild = await runCli(["brain", "entity", "lexicon", "rebuild", "--apply"], {
env: env(),
});
expect(rebuild.returncode).toBe(0);
return {
nasa: writeNode("projects", "ent-projects-nasa", "NASA"),
meeting: writeNode("people", "ent-people-meeting", "Meeting"),
junk: writeNode("people", "ent-people-junk", "***"),
};
}
test("prune --confirm keeps the acronym and the topic, removes structural junk", async () => {
const { nasa, meeting, junk } = await seedAdvisoryStore();
const out = await runCli(["brain", "entity", "prune", "--confirm", "--json"], { env: env() });
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as { removed: string[]; advisory_skipped: number };
expect(payload.removed).toEqual([junk]);
expect(payload.advisory_skipped).toBe(2);
expect(existsSync(nasa)).toBe(true);
expect(existsSync(meeting)).toBe(true);
});
test("--include-advisory removes the advisory classes too", async () => {
const { nasa, meeting, junk } = await seedAdvisoryStore();
const out = await runCli(
["brain", "entity", "prune", "--confirm", "--include-advisory", "--json"],
{ env: env() },
);
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as { removed: string[]; advisory_skipped: number };
expect(payload.advisory_skipped).toBe(0);
// All three findings go: the structural junk alongside the advisory classes.
expect([...payload.removed].sort()).toEqual([nasa, meeting, junk].sort());
expect(existsSync(nasa)).toBe(false);
expect(existsSync(meeting)).toBe(false);
expect(existsSync(junk)).toBe(false);
});
});
describe("o2b brain entity merge", () => {
async function seedMergePair(): Promise<{ keepId: string; dropId: string; dropPath: string }> {
const keep = await runCli(
["brain", "entity", "set", "people", "Ada Lovelace", "--body", "Analytical engines."],
{ env: env() },
);
expect(keep.returncode).toBe(0);
const drop = await runCli(["brain", "entity", "set", "people", "Ada", "--json"], {
env: env(),
});
expect(drop.returncode).toBe(0);
const dropPayload = JSON.parse(drop.stdout) as { id: string; path: string };
return {
keepId: "ent-people-ada-lovelace",
dropId: dropPayload.id,
dropPath: dropPayload.path,
};
}
test("dry-run --json prints the plan and its hash without touching the vault", async () => {
const { keepId, dropId, dropPath } = await seedMergePair();
const out = await runCli(["brain", "entity", "merge", keepId, dropId, "--dry-run", "--json"], {
env: env(),
});
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as {
dry_run: boolean;
plan: { keep_id: string; drop_id: string; alias_added: string | null };
plan_hash: string;
};
expect(payload.dry_run).toBe(true);
expect(payload.plan.keep_id).toBe(keepId);
expect(payload.plan.drop_id).toBe(dropId);
expect(payload.plan.alias_added).toBe("Ada");
expect(payload.plan_hash).toMatch(/^[0-9a-f]{64}$/);
// The drop page is still on disk: a preview writes nothing.
expect(existsSync(dropPath)).toBe(true);
});
test("apply without --expect-hash refuses by name and writes nothing", async () => {
const { keepId, dropId, dropPath } = await seedMergePair();
const out = await runCli(["brain", "entity", "merge", keepId, dropId, "--force"], {
env: env(),
});
expect(out.returncode).toBe(1);
expect(out.stderr).toContain("hash-required");
expect(existsSync(dropPath)).toBe(true);
});
test("apply with a stale or mismatched hash refuses before any write", async () => {
const { keepId, dropId, dropPath } = await seedMergePair();
const out = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--expect-hash", "deadbeef"],
{ env: env() },
);
expect(out.returncode).toBe(1);
expect(out.stderr).toContain("hash-mismatch");
expect(existsSync(dropPath)).toBe(true);
});
test("apply with the echoed hash and --force merges without prompting", async () => {
const { keepId, dropId, dropPath } = await seedMergePair();
// The preview runs at the same --force stance as the apply: the plan
// hash seals whether the guard ran, so a hash is only spendable at the
// stance it was previewed in.
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--dry-run", "--json"],
{ env: env() },
);
const { plan_hash: hash } = JSON.parse(preview.stdout) as { plan_hash: string };
const out = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--expect-hash", hash, "--json"],
{ env: env() },
);
expect(out.returncode).toBe(0);
const payload = JSON.parse(out.stdout) as {
applied: boolean;
keep_id: string;
drop_id: string;
snapshot_run_id: string;
};
expect(payload.applied).toBe(true);
expect(payload.keep_id).toBe(keepId);
expect(payload.drop_id).toBe(dropId);
// Recovery points read entity-merge-*, so a restore names the merge -
// not the prune verb the reason was borrowed from.
expect(payload.snapshot_run_id).toMatch(/^entity-merge-/);
expect(existsSync(dropPath)).toBe(false);
// The old name now resolves to the survivor.
const get = await runCli(["brain", "entity", "get", "Ada", "--json"], { env: env() });
expect(get.returncode).toBe(0);
expect((JSON.parse(get.stdout) as { id: string }).id).toBe(keepId);
// A doctor re-run after apply is clean of duplicate-entity findings.
const doctor = await runCli(["brain", "doctor", "--json"], { env: env() });
expect(doctor.stdout).not.toContain("duplicate-entity");
});
test("merges are attributed to the configured agent, not 'unknown'", async () => {
const auditText = (): string => {
const auditDir = join(vault, "Brain", "log", HYGIENE_AUDIT_DIR);
return readdirSync(auditDir)
.filter((f) => f.endsWith(".jsonl"))
.map((f) => readFileSync(join(auditDir, f), "utf8"))
.join("\n");
};
// No --agent at all: the config's agent_name attributes the merge.
const { keepId, dropId } = await seedMergePair();
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--dry-run", "--json"],
{ env: env() },
);
const { plan_hash: hash } = JSON.parse(preview.stdout) as { plan_hash: string };
const out = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--expect-hash", hash, "--json"],
{ env: env() },
);
expect(out.returncode).toBe(0);
expect(auditText()).toContain('"actor":"test-agent"');
expect(auditText()).not.toContain('"actor":"unknown"');
// A blank --agent normalizes away to the configured agent too - it is
// not a null actor smuggled into the audit record.
const second = await runCli(["brain", "entity", "set", "people", "Grace Hopper"], {
env: env(),
});
expect(second.returncode).toBe(0);
const third = await runCli(["brain", "entity", "set", "people", "Grace"], { env: env() });
expect(third.returncode).toBe(0);
const secondPreview = await runCli(
[
"brain",
"entity",
"merge",
"ent-people-grace-hopper",
"ent-people-grace",
"--force",
"--dry-run",
"--json",
],
{ env: env() },
);
const { plan_hash: secondHash } = JSON.parse(secondPreview.stdout) as { plan_hash: string };
const blankAgent = await runCli(
[
"brain",
"entity",
"merge",
"ent-people-grace-hopper",
"ent-people-grace",
"--force",
"--expect-hash",
secondHash,
"--agent",
" ",
"--json",
],
{ env: env() },
);
expect(blankAgent.returncode).toBe(0);
expect(auditText()).not.toContain('"actor":"unknown"');
expect(auditText()).toContain('"actor":"test-agent"');
});
test("--json without --force refuses as structured consent-required JSON", async () => {
const { keepId, dropId, dropPath } = await seedMergePair();
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--dry-run", "--json"],
{ env: env() },
);
const { plan_hash: hash } = JSON.parse(preview.stdout) as { plan_hash: string };
const out = await runCli(
["brain", "entity", "merge", keepId, dropId, "--json", "--expect-hash", hash],
{ env: env() },
);
expect(out.returncode).toBe(1);
// A JSON caller gets a structured refusal on stdout, not fail() prose
// on stderr: the code is the stable consent vocabulary.
const payload = JSON.parse(out.stdout) as { ok: boolean; code: string; message: string };
expect(payload.ok).toBe(false);
expect(payload.code).toBe("consent-required");
expect(payload.message).toContain("--json without --force");
expect(out.stderr).toBe("");
expect(existsSync(dropPath)).toBe(true);
});
test("non-TTY stdin without --force refuses instead of prompting", async () => {
const { keepId, dropId } = await seedMergePair();
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--dry-run", "--json"],
{ env: env() },
);
const { plan_hash: hash } = JSON.parse(preview.stdout) as { plan_hash: string };
const out = await runCli(["brain", "entity", "merge", keepId, dropId, "--expect-hash", hash], {
env: env(),
});
expect(out.returncode).toBe(1);
expect(out.stderr).toContain("--force required when stdin is not a TTY");
});
test("plain dry-run prints the plan-hash line and an apply command", async () => {
const { keepId, dropId } = await seedMergePair();
const out = await runCli(["brain", "entity", "merge", keepId, dropId, "--dry-run"], {
env: env(),
});
expect(out.returncode).toBe(0);
expect(out.stdout).toContain("plan-hash: ");
expect(out.stdout).toContain("--expect-hash ");
expect(out.stdout).toContain("dry-run; no changes written");
});
test("plain dry-run names the cyclic edges the merge will remove", async () => {
const { keepId, dropId } = await seedMergePair();
// The survivor points at the dropped page: a self-relation after the
// merge, so the plan removes it - and says so before the operator
// consents.
const relate = await runCli(["brain", "entity", "relate", "Ada Lovelace", "related", "Ada"], {
env: env(),
});
expect(relate.returncode).toBe(0);
const out = await runCli(["brain", "entity", "merge", keepId, dropId, "--dry-run"], {
env: env(),
});
expect(out.returncode).toBe(0);
expect(out.stdout).toContain("cyclic edges removed: 1");
});
test("an unexpected failure answers a JSON caller with structured internal-error", async () => {
const { keepId, dropId } = await seedMergePair();
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--dry-run", "--json"],
{ env: env() },
);
const { plan_hash: hash } = JSON.parse(preview.stdout) as { plan_hash: string };
// Swap the vault's identity marker underneath the live process: the
// write gate refuses below the verb's own refusal vocabulary - the
// store changed, not a merge decision. Nothing has been written when
// it fires.
const marker = join(vault, "Brain", "vault-id.json");
writeFileSync(
marker,
JSON.stringify({
schema_version: 1,
vault_id: "tampered-away-from-the-pinned-id",
created_at: "2026-01-01T00:00:00Z",
}),
);
const out = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--expect-hash", hash, "--json"],
{ env: env() },
);
expect(out.returncode).toBe(1);
const payload = JSON.parse(out.stdout) as { ok: boolean; code: string; message: string };
expect(payload.ok).toBe(false);
expect(payload.code).toBe("internal-error");
// The error's own message, one line - never a stack.
expect(payload.message.split("\n").length).toBe(1);
expect(payload.message.length).toBeGreaterThan(0);
expect(out.stderr).toBe("");
});
test("the echoed apply command shell-quotes subjects a shell would split", async () => {
// Subjects echo verbatim into a command line, so a name with a space
// must come back quoted: `merge 'Ada Lovelace'` parses back as ONE
// argument, the raw form would split into two.
await seedMergePair();
const out = await runCli(["brain", "entity", "merge", "Ada Lovelace", "Ada", "--dry-run"], {
env: env(),
});
expect(out.returncode).toBe(0);
// The spaced name is quoted; the plain word stays bare.
expect(out.stdout).toContain("merge 'Ada Lovelace' Ada");
expect(out.stdout).not.toContain("merge Ada Lovelace");
});
test("the echoed apply command carries the --vault flag it was given", async () => {
// A synced copy at a spaced path: pasting the echo back must target
// THAT vault - quoted, so the path survives the shell as one argument -
// not silently fall back to whichever vault the paste resolves.
const spacedVault = join(tmp, "synced copy");
const spacedConfig = join(tmp, "spaced.yaml");
writeFileSync(spacedConfig, `vault: ${spacedVault}\nagent_name: test-agent\n`);
bootstrapBrain(spacedVault, { configPath: spacedConfig });
const spacedEnv = () => ({ OPEN_SECOND_BRAIN_CONFIG: spacedConfig });
const keep = await runCli(["brain", "entity", "set", "people", "Ada Lovelace"], {
env: spacedEnv(),
});
expect(keep.returncode).toBe(0);
const drop = await runCli(["brain", "entity", "set", "people", "Ada"], { env: spacedEnv() });
expect(drop.returncode).toBe(0);
const out = await runCli(
[
"brain",
"entity",
"merge",
"ent-people-ada-lovelace",
"ent-people-ada",
"--dry-run",
"--vault",
spacedVault,
],
{ env: spacedEnv() },
);
expect(out.returncode).toBe(0);
expect(out.stdout).toContain(`--vault '${spacedVault}'`);
});
// The paste-back echo is a POSIX-shell contract, and this scenario needs
// a double quote inside a directory name, which no Windows file system
// allows: the hostile vault cannot exist there, so there is no Windows
// case to run.
test.skipIf(IS_WINDOWS)(
"the echoed apply command round-trips a vault path a shell would mangle",
async () => {
// Entity ids echo bare, so the hostile characters ride the --vault
// flag: a synced copy whose directory name carries a bang, spaces and
// both quote kinds. Pasting the echo back must resolve to THAT
// directory, which the parse side of the round-trip checks word by
// word against the original path.
const hostileVault = join(tmp, `synced! v'ault "x"`);
const hostileConfig = join(tmp, "hostile.yaml");
writeFileSync(hostileConfig, `vault: ${hostileVault}\nagent_name: test-agent\n`);
bootstrapBrain(hostileVault, { configPath: hostileConfig });
const hostileEnv = () => ({ OPEN_SECOND_BRAIN_CONFIG: hostileConfig });
const keep = await runCli(["brain", "entity", "set", "people", "Ada Lovelace"], {
env: hostileEnv(),
});
expect(keep.returncode).toBe(0);
const drop = await runCli(["brain", "entity", "set", "people", "Ada"], { env: hostileEnv() });
expect(drop.returncode).toBe(0);
const out = await runCli(
[
"brain",
"entity",
"merge",
"ent-people-ada-lovelace",
"ent-people-ada",
"--dry-run",
"--vault",
hostileVault,
],
{ env: hostileEnv() },
);
expect(out.returncode).toBe(0);
const apply = out.stdout.split("\n").find((l) => l.startsWith(" apply: "))!;
const words = splitPosixShellWords(apply.slice(" apply: ".length));
// o2b brain entity merge <keep> <drop> --vault <vault> --expect-hash <hash>
expect(words).toHaveLength(10);
expect(words[4]).toBe("ent-people-ada-lovelace");
expect(words[5]).toBe("ent-people-ada");
expect(words[7]).toBe(hostileVault);
expect(words[9]).toMatch(/^[0-9a-f]{64}$/);
},
);
test("a clean pair previewed without --force applies with --force", async () => {
// The standard agent flow: preview at the plain stance (the guard ran
// and passed), apply with --force for consent. guard_bypassed stamps
// only an override the guard would have refused, so a clean pair
// re-plans to the SAME hash at either stance and the apply lands -
// stamping the flag instead refused every merge with hash-mismatch
// and pushed agents into previewing under --force to get anything
// through.
const { keepId, dropId, dropPath } = await seedMergePair();
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--dry-run", "--json"],
{ env: env() },
);
const payload = JSON.parse(preview.stdout) as {
plan_hash: string;
plan: { guard_bypassed: boolean };
};
expect(payload.plan.guard_bypassed).toBe(false);
const out = await runCli(
[
"brain",
"entity",
"merge",
keepId,
dropId,
"--force",
"--expect-hash",
payload.plan_hash,
"--json",
],
{ env: env() },
);
expect(out.returncode).toBe(0);
expect((JSON.parse(out.stdout) as { applied: boolean }).applied).toBe(true);
expect(existsSync(dropPath)).toBe(false);
});
test("a pair that starts refusing cannot apply under a plain preview's hash", async () => {
// The keep body anchors Mary Somerville before her record exists: the
// preview's guard passes and stamps no bypass. Registering her flips
// the verdict without touching either previewed page, so applying
// with --force re-plans at a stance the preview never took - the hash
// refuses as stale, and the pair cannot ride a preview that claimed
// the guard ran.
const keep = await runCli(
[
"brain",
"entity",
"set",
"people",
"Ada Lovelace",
"--body",
"Mary Somerville wrote often.",
],
{ env: env() },
);
expect(keep.returncode).toBe(0);
const drop = await runCli(["brain", "entity", "set", "people", "Ada", "--json"], {
env: env(),
});
expect(drop.returncode).toBe(0);
const dropPayload = JSON.parse(drop.stdout) as { id: string; path: string };
const preview = await runCli(
[
"brain",
"entity",
"merge",
"ent-people-ada-lovelace",
dropPayload.id,
"--dry-run",
"--json",
],
{ env: env() },
);
const { plan_hash: hash } = JSON.parse(preview.stdout) as { plan_hash: string };
const mary = await runCli(["brain", "entity", "set", "people", "Mary Somerville"], {
env: env(),
});
expect(mary.returncode).toBe(0);
const out = await runCli(
[
"brain",
"entity",
"merge",
"ent-people-ada-lovelace",
dropPayload.id,
"--force",
"--expect-hash",
hash,
"--json",
],
{ env: env() },
);
expect(out.returncode).toBe(1);
const refused = JSON.parse(out.stdout) as { ok: boolean; code: string; message: string };
expect(refused).toMatchObject({ ok: false, code: "hash-mismatch" });
// The refusal tells the plain stale-plan story - the vault moved -
// whatever the --force stance the preview or the apply took: a
// guarded pair hashes differently only through the override stamp,
// and the message never names a stance story on top.
expect(refused.message).toContain("vault changed since the preview");
expect(refused.message).not.toContain("--force");
expect(existsSync(dropPayload.path)).toBe(true);
});
test("a vault-changed mismatch refuses with the plain stale-plan story", async () => {
// A body edited after the preview shifts the sealed digests - the
// common mismatch, nothing to do with the guard stance. Naming the
// --force interplay on every mismatch sent operators chasing a
// stance problem that did not exist.
const { keepId, dropId } = await seedMergePair();
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--dry-run", "--json"],
{ env: env() },
);
const { plan_hash: hash } = JSON.parse(preview.stdout) as { plan_hash: string };
const edit = await runCli(
["brain", "entity", "set", "people", "Ada", "--body", "Edited after the preview."],
{ env: env() },
);
expect(edit.returncode).toBe(0);
const out = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--expect-hash", hash, "--json"],
{ env: env() },
);
expect(out.returncode).toBe(1);
const payload = JSON.parse(out.stdout) as { ok: boolean; code: string; message: string };
expect(payload).toMatchObject({ ok: false, code: "hash-mismatch" });
expect(payload.message).toContain("vault changed since the preview");
expect(payload.message).not.toContain("guard");
expect(out.stderr).toBe("");
});
test("the echoed apply command carries --force exactly when the preview ran with it", async () => {
const { keepId, dropId } = await seedMergePair();
const plain = await runCli(["brain", "entity", "merge", keepId, dropId, "--dry-run"], {
env: env(),
});
expect(plain.returncode).toBe(0);
const plainApply = plain.stdout.split("\n").find((l) => l.startsWith(" apply: "))!;
expect(plainApply).toContain("--expect-hash ");
expect(plainApply).not.toContain("--force");
const forced = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--dry-run"],
{ env: env() },
);
expect(forced.returncode).toBe(0);
const forcedApply = forced.stdout.split("\n").find((l) => l.startsWith(" apply: "))!;
expect(forcedApply.endsWith(" --force")).toBe(true);
});
test("a --force preview states the bypass only when the guard would refuse", async () => {
// The guard line keys on the plan's guard_bypassed stamp, not on the
// flag: a pair the guard refuses is previewable only under the
// override, and the consent the operator gives names it.
const keep = await runCli(
[
"brain",
"entity",
"set",
"people",
"Ada Lovelace",
"--body",
"Mary Somerville wrote often.",
],
{ env: env() },
);
expect(keep.returncode).toBe(0);
const drop = await runCli(
["brain", "entity", "set", "people", "Ada", "--body", "Short note about Ada."],
{ env: env() },
);
expect(drop.returncode).toBe(0);
const mary = await runCli(["brain", "entity", "set", "people", "Mary Somerville"], {
env: env(),
});
expect(mary.returncode).toBe(0);
const forced = await runCli(
[
"brain",
"entity",
"merge",
"ent-people-ada-lovelace",
"ent-people-ada",
"--force",
"--dry-run",
],
{ env: env() },
);
expect(forced.returncode).toBe(0);
expect(forced.stdout).toContain("text-level merge guard");
expect(forced.stdout).toContain("bypass");
});
test("a clean pair states no bypass at either stance", async () => {
// The other half of the guard-line contract, on its own seeded pair:
// the guard passes, so the override never happened and neither
// stance's preview names one.
const { keepId, dropId } = await seedMergePair();
const plain = await runCli(["brain", "entity", "merge", keepId, dropId, "--dry-run"], {
env: env(),
});
expect(plain.returncode).toBe(0);
expect(plain.stdout).not.toContain("bypass");
const forcedClean = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--dry-run"],
{ env: env() },
);
expect(forcedClean.returncode).toBe(0);
expect(forcedClean.stdout).not.toContain("bypass");
});
test("the entity help states that --force bypasses the text-level merge guard", () => {
expect(VERB_HELP.entity).toContain("--force");
expect(VERB_HELP.entity).toContain("bypasses the text-level merge guard");
});
test("a guard-tripping pair merges end-to-end under --force; the hash gate still binds", async () => {
// The keep body anchors Mary Somerville, the drop body anchors only Ada:
// disjoint guarded anchor sets, the shape the core merge guard refuses.
const keep = await runCli(
[
"brain",
"entity",
"set",
"people",
"Ada Lovelace",
"--body",
"Mary Somerville wrote often.",
],
{ env: env() },
);
expect(keep.returncode).toBe(0);
const drop = await runCli(
["brain", "entity", "set", "people", "Ada", "--body", "Short note about Ada.", "--json"],
{ env: env() },
);
expect(drop.returncode).toBe(0);
const dropPayload = JSON.parse(drop.stdout) as { id: string; path: string };
const mary = await runCli(["brain", "entity", "set", "people", "Mary Somerville"], {
env: env(),
});
expect(mary.returncode).toBe(0);
const keepId = "ent-people-ada-lovelace";
const dropId = dropPayload.id;
const dropPath = dropPayload.path;
// Even the preview refuses while the guard stands, by its stable code.
const blocked = await runCli(
["brain", "entity", "merge", keepId, dropId, "--dry-run", "--json"],
{ env: env() },
);
expect(blocked.returncode).toBe(1);
expect(JSON.parse(blocked.stdout)).toMatchObject({ ok: false, code: "entity-guard" });
expect(existsSync(dropPath)).toBe(true);
// --force unblocks the guarded preview and still echoes the hash; the
// plan stamps the override the guard refused.
const preview = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--dry-run", "--json"],
{ env: env() },
);
expect(preview.returncode).toBe(0);
const parsed = JSON.parse(preview.stdout) as {
plan_hash: string;
plan: { guard_bypassed: boolean };
};
expect(parsed.plan.guard_bypassed).toBe(true);
const { plan_hash: hash } = parsed;
expect(hash).toMatch(/^[0-9a-f]{64}$/);
// The hash gate is a fact-check, not consent: --force does NOT bypass it.
const stale = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--expect-hash", "deadbeef"],
{ env: env() },
);
expect(stale.returncode).toBe(1);
expect(stale.stderr).toContain("hash-mismatch");
expect(existsSync(dropPath)).toBe(true);
const out = await runCli(
["brain", "entity", "merge", keepId, dropId, "--force", "--expect-hash", hash, "--json"],
{ env: env() },
);
expect(out.returncode).toBe(0);
expect((JSON.parse(out.stdout) as { applied: boolean }).applied).toBe(true);
expect(existsSync(dropPath)).toBe(false);
// The old name resolves to the survivor: the guarded merge really landed.
const get = await runCli(["brain", "entity", "get", "Ada", "--json"], { env: env() });
expect(get.returncode).toBe(0);
expect((JSON.parse(get.stdout) as { id: string }).id).toBe(keepId);
});
});