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
/**
* Write-session engine: lifecycle, correction loop, collision guard,
* review gate, audit (Agent Write Contract Suite, t_bc36a8a2).
*/
import { afterEach, beforeEach, expect, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
WriteSessionRequestError,
abandonSession,
approveSession,
openArtifactSession,
sessionEnvelope,
submitToSession,
} from "../../../../src/core/brain/write-session/engine.ts";
import { readWriteSession } from "../../../../src/core/brain/write-session/store.ts";
import { parseLogDay } from "../../../../src/core/brain/log.ts";
import { useUnshardedLegacyLog } from "../../../helpers/device-id.ts";
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
let tmp: string;
let vault: string;
const NOW = "2026-06-04T10:00:00.000Z";
const DATE = "2026-06-04";
const GOOD = ["---", "kind: note", "---", "", "# Decision record", "", "We adopt it."].join("\n");
function open(over: Record<string, unknown> = {}) {
return openArtifactSession(vault, {
agent: "fixture-agent",
targetPath: "Brain/notes/adr.md",
now: NOW,
...over,
});
}
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-ws-engine-"));
vault = join(tmp, "vault");
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("open returns a needs-llm-step envelope with prompt, hints, and ttl", () => {
const env = open({ schemaType: "note" });
expect(env.status).toBe("needs-llm-step");
expect(env.kind).toBe("artifact");
expect(env.step).toBe("artifact");
expect(env.session_id).toMatch(/^ws-/);
expect(env.prompt).toContain("Brain/notes/adr.md");
expect(env.schema_hints.some((h) => h.includes("type: note"))).toBe(true);
expect(env.attempts_left).toBe(3);
expect(Date.parse(env.expires_at) - Date.parse(NOW)).toBe(24 * 3600 * 1000);
expect(env.existing).toBeNull();
});
test("open rejects an invalid target with structured errors", () => {
try {
open({ targetPath: "Brain/preferences/pref-x.md" });
throw new Error("expected WriteSessionRequestError");
} catch (exc) {
expect(exc).toBeInstanceOf(WriteSessionRequestError);
const errors = (exc as WriteSessionRequestError).errors;
expect(errors.map((e) => e.code)).toContain("target-reserved");
}
});
test("open against an occupied target attaches existing metadata", () => {
mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
writeFileSync(join(vault, "Brain", "notes", "adr.md"), "---\nkind: note\n---\n\n# Old\n");
const env = open();
expect(env.existing).not.toBeNull();
expect(env.existing!.first_heading).toBe("Old");
});
test("invalid submit returns needs-correction, preserves state, decrements attempts", () => {
const opened = open();
const env = submitToSession(vault, {
sessionId: opened.session_id,
artifact: "# no frontmatter",
now: NOW,
});
expect(env.status).toBe("needs-correction");
expect(env.errors.map((e) => e.code)).toContain("frontmatter-missing");
expect(env.prompt).toContain("resubmit the full corrected artifact");
expect(env.attempts_left).toBe(2);
expect(env.target_path).toBe("Brain/notes/adr.md");
});
test("retry cap exhaustion is terminal failed with an audit event", () => {
const opened = open({ retryCap: 2 });
submitToSession(vault, { sessionId: opened.session_id, artifact: "bad", now: NOW });
const env = submitToSession(vault, { sessionId: opened.session_id, artifact: "bad", now: NOW });
expect(env.status).toBe("failed");
expect(env.attempts_left).toBe(0);
const probe = readWriteSession(vault, opened.session_id, NOW);
expect(probe.session!.failReason).toBe("retry-cap");
const { entries } = parseLogDay(vault, DATE);
const audit = entries.filter((e) => e.eventType === "write-session");
expect(audit).toHaveLength(1);
expect(audit[0]!.body["status"]).toBe("failed");
});
test("valid submit commits atomically and is terminal done", () => {
const opened = open();
const env = submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW });
expect(env.status).toBe("done");
const committed = readFileSync(join(vault, "Brain", "notes", "adr.md"), "utf8");
expect(committed).toContain("# Decision record");
expect(committed.endsWith("\n")).toBe(true);
const { entries } = parseLogDay(vault, DATE);
const audit = entries.filter((e) => e.eventType === "write-session");
expect(audit).toHaveLength(1);
expect(audit[0]!.body["status"]).toBe("done");
expect(audit[0]!.body["target"]).toBe("Brain/notes/adr.md");
// terminal: a second submit is rejected
expect(() =>
submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW }),
).toThrow(/terminal/);
});
test("create intent never overwrites an existing target", () => {
mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
writeFileSync(join(vault, "Brain", "notes", "adr.md"), "PRECIOUS\n");
const opened = open();
const env = submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW });
expect(env.status).toBe("needs-correction");
expect(env.errors.map((e) => e.code)).toContain("target-exists");
expect(readFileSync(join(vault, "Brain", "notes", "adr.md"), "utf8")).toBe("PRECIOUS\n");
});
test("overwrite intent replaces; merge intent appends a delimited section", () => {
mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
writeFileSync(join(vault, "Brain", "notes", "adr.md"), "---\nkind: note\n---\n\n# Old\n");
const over = open({ intent: "overwrite" });
expect(
submitToSession(vault, { sessionId: over.session_id, artifact: GOOD, now: NOW }).status,
).toBe("done");
expect(readFileSync(join(vault, "Brain", "notes", "adr.md"), "utf8")).not.toContain("# Old");
writeFileSync(join(vault, "Brain", "notes", "adr.md"), "---\nkind: note\n---\n\n# Old\n");
const merge = open({ intent: "merge" });
expect(
submitToSession(vault, { sessionId: merge.session_id, artifact: GOOD, now: NOW }).status,
).toBe("done");
const merged = readFileSync(join(vault, "Brain", "notes", "adr.md"), "utf8");
expect(merged).toContain("# Old");
expect(merged).toContain("# Decision record");
expect(merged.indexOf("# Old")).toBeLessThan(merged.indexOf("# Decision record"));
expect(merged).toContain(merge.session_id);
});
test("require_review stops at needs-review; approve commits", () => {
const opened = open({ requireReview: true });
const env = submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW });
expect(env.status).toBe("needs-review");
expect(existsSync(join(vault, "Brain", "notes", "adr.md"))).toBe(false);
const approved = approveSession(vault, { sessionId: opened.session_id, now: NOW });
expect(approved.status).toBe("done");
expect(readFileSync(join(vault, "Brain", "notes", "adr.md"), "utf8")).toContain(
"# Decision record",
);
const { entries } = parseLogDay(vault, DATE);
const audit = entries.filter((e) => e.eventType === "write-session");
expect(audit).toHaveLength(1);
expect(audit[0]!.body["review"]).toBe("required");
});
test("approve outside needs-review is a structured error", () => {
const opened = open();
expect(() => approveSession(vault, { sessionId: opened.session_id, now: NOW })).toThrow(
WriteSessionRequestError,
);
});
test("abandon is terminal failed/abandoned with audit", () => {
const opened = open();
const env = abandonSession(vault, { sessionId: opened.session_id, now: NOW });
expect(env.status).toBe("failed");
const probe = readWriteSession(vault, opened.session_id, NOW);
expect(probe.session!.failReason).toBe("abandoned");
const { entries } = parseLogDay(vault, DATE);
expect(entries.filter((e) => e.eventType === "write-session")).toHaveLength(1);
});
test("an expired session is audited exactly once across repeated ops", () => {
const opened = open({ ttlMs: 1000 });
const LATER = "2026-06-04T11:00:00Z";
for (let i = 0; i < 3; i++) {
expect(() =>
submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: LATER }),
).toThrow(/terminal/);
}
const { entries } = parseLogDay(vault, DATE);
const audit = entries.filter((e) => e.eventType === "write-session");
expect(audit).toHaveLength(1);
expect(audit[0]!.body["reason"]).toBe("expired");
});
test("an expired session refuses submits with a terminal error", () => {
const opened = open({ ttlMs: 1000 });
expect(() =>
submitToSession(vault, {
sessionId: opened.session_id,
artifact: GOOD,
now: "2026-06-04T11:00:00Z",
}),
).toThrow(/expired|terminal/);
});
test("sessionEnvelope reflects current state for status queries", () => {
const opened = open();
submitToSession(vault, { sessionId: opened.session_id, artifact: "bad", now: NOW });
const probe = readWriteSession(vault, opened.session_id, NOW);
const env = sessionEnvelope(probe.session!);
expect(env.status).toBe("needs-correction");
expect(env.attempts_left).toBe(2);
expect(env.session_id).toBe(opened.session_id);
});
test("unknown session id is a structured error", () => {
expect(() =>
submitToSession(vault, { sessionId: "ws-20990101-000000", artifact: GOOD, now: NOW }),
).toThrow(WriteSessionRequestError);
});
test("commit refuses a target whose Brain ancestor is a symlink out of the vault", () => {
// `validateTargetPath` runs at open time and reads the path as spelled:
// `Brain/notes/escape/adr.md` is clean, so the session opens. Only the
// write chokepoint can see that `Brain/notes/escape` is a symlink
// pointing outside the vault. The containment guard must reject the
// commit before any mkdir/write lands the file on the symlink target.
const outside = join(tmp, "outside");
mkdirSync(outside, { recursive: true });
mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
symlinkSync(outside, join(vault, "Brain", "notes", "escape"), "dir");
const opened = open({ targetPath: "Brain/notes/escape/adr.md" });
expect(() =>
submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW }),
).toThrow(/escapes vault/);
// Fail-closed: nothing was written through the symlink.
expect(existsSync(join(outside, "adr.md"))).toBe(false);
});
test("open refuses Brain machinery targets, case-folded", () => {
for (const targetPath of [
"Brain/standing-rules.md",
"Brain/active.md",
"Brain/Preferences/x.md",
"Brain/log./x.md",
]) {
expect(() => open({ targetPath })).toThrow(WriteSessionRequestError);
}
expect(existsSync(join(vault, "Brain", "standing-rules.md"))).toBe(false);
expect(existsSync(join(vault, "Brain", "active.md"))).toBe(false);
});
test("commit refuses a lane folder that is a symlink into Brain machinery", () => {
// The spelled target sits in a session lane; the bytes would land in
// Brain/preferences/. The commit re-reads where the bytes land.
mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
symlinkSync(join(vault, "Brain", "preferences"), join(vault, "Brain", "notes"), "dir");
const opened = open({ targetPath: "Brain/notes/pref-forged.md" });
try {
submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW });
throw new Error("expected WriteSessionRequestError");
} catch (exc) {
expect(exc).toBeInstanceOf(WriteSessionRequestError);
expect((exc as WriteSessionRequestError).errors.map((e) => e.code)).toEqual([
"target-reserved",
]);
expect((exc as Error).message).toContain("Brain/preferences/pref-forged.md");
}
expect(existsSync(join(vault, "Brain", "preferences", "pref-forged.md"))).toBe(false);
});
test("commit refuses a lane note that is a symlink to the standing rules", () => {
const rules = join(vault, "Brain", "standing-rules.md");
writeFileSync(rules, "Operator rules.\n");
mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
symlinkSync(rules, join(vault, "Brain", "notes", "adr.md"));
const opened = open({ intent: "overwrite" });
expect(() =>
submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW }),
).toThrow(/standing-rules/);
expect(readFileSync(rules, "utf8")).toBe("Operator rules.\n");
});
test("commit refuses a target the write binding does not admit", () => {
writeFileSync(
join(vault, "Brain", "_brain.yaml"),
"schema_version: 1\nwrite_binding:\n path_prefixes:\n - Brain/reports/\n",
);
const opened = open();
try {
submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW });
throw new Error("expected WriteSessionRequestError");
} catch (exc) {
expect(exc).toBeInstanceOf(WriteSessionRequestError);
expect((exc as Error).message).toContain("outside the write binding");
}
expect(existsSync(join(vault, "Brain", "notes", "adr.md"))).toBe(false);
});
test("commit refuses, without crashing, a target under a file used as a folder", () => {
mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
writeFileSync(join(vault, "Brain", "notes", "existing.md"), "x\n");
const opened = open({ targetPath: "Brain/notes/existing.md/x.md" });
try {
submitToSession(vault, { sessionId: opened.session_id, artifact: GOOD, now: NOW });
throw new Error("expected WriteSessionRequestError");
} catch (exc) {
expect(exc).toBeInstanceOf(WriteSessionRequestError);
expect((exc as WriteSessionRequestError).errors.map((e) => e.code)).toEqual([
"target-unresolvable",
]);
}
});