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
/**
* Tests for the `@osb set` marker write-back engine (today-operator-
* surface, Task 6). Covers the report/apply mode contract, the
* guardrail gate, schema-validated mutation, the `attribute-write`
* audit event, per-marker isolation on ambiguous/invalid targets,
* marker consumption, and idempotence.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { parseFrontmatter } from "../../../src/core/vault.ts";
import { readAttributes } from "../../../src/core/brain/attributes.ts";
import { parseLogDay } from "../../../src/core/brain/log.ts";
import {
applyMarkerWritebacks,
MarkerWritebackGuardrailError,
} from "../../../src/core/brain/marker-writeback.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
const NOW = new Date("2026-07-17T12:34:56Z");
const LOG_DATE = "2026-07-17";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-marker-writeback-"));
const dirs = brainDirs(vault);
for (const d of [dirs.brain, dirs.log]) {
mkdirSync(d, { recursive: true });
}
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
function writeConfig(opts: { markerWriteback: boolean; readPaths?: ReadonlyArray<string> }): void {
const readPaths = opts.readPaths ?? ["Notes"];
const lines = [
"schema_version: 1",
"primary_agent: null",
"",
"dream:",
" candidate_threshold: 3",
" unconfirmed_window_days: 14",
" contradiction_window_days: 14",
"",
"retire:",
" stale_evidence_days: 90",
"",
"confidence:",
" low_max_applied: 2",
" medium_min: 0.40",
" high_min: 0.75",
"",
"snapshots:",
" retention_count: 10",
"",
"schema:",
" page_types: [paper]",
" attributes:",
" - paper.status=reading status",
" - paper.year=publication year",
"",
"notes:",
" read_paths:",
...readPaths.map((p) => ` - ${p}`),
"",
"guardrails:",
` marker_writeback: ${opts.markerWriteback ? "true" : "false"}`,
"",
];
writeFileSync(join(brainDirs(vault).brain, "_brain.yaml"), lines.join("\n"), "utf8");
}
function writePaper(rel: string, front: Record<string, string> = {}): void {
const path = join(vault, rel);
mkdirSync(join(path, ".."), { recursive: true });
const fm = ["---", "type: paper", "title: A Paper"];
for (const [k, v] of Object.entries(front)) fm.push(`${k}: ${v}`);
fm.push("---", "", "# A Paper", "", "body", "");
writeFileSync(path, fm.join("\n"), "utf8");
}
function writeSource(rel: string, ...markerLines: string[]): void {
const path = join(vault, rel);
mkdirSync(join(path, ".."), { recursive: true });
writeFileSync(path, `# Journal\n\n${markerLines.join("\n")}\n`, "utf8");
}
function readSource(rel: string): string {
return readFileSync(join(vault, rel), "utf8");
}
function attrsOf(rel: string): Record<string, string> {
const [fm] = parseFrontmatter(join(vault, rel));
return readAttributes(fm);
}
function attributeWriteEvents() {
return parseLogDay(vault, LOG_DATE).entries.filter((e) => e.eventType === "attribute-write");
}
describe("report mode", () => {
test("lists pending mutations, resolves the target, and writes nothing", async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/paper.md");
writeSource("Notes/journal.md", "@osb set note=paper field=status value=queued");
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: false,
agent: "claude-dev-agent",
now: NOW,
});
expect(report.apply).toBe(false);
expect(report.entries).toHaveLength(1);
const entry = report.entries[0]!;
expect(entry.status).toBe("would-apply");
expect(entry.resolvedPath).toBe("Notes/paper.md");
expect(entry.field).toBe("status");
expect(entry.value).toBe("queued");
expect(entry.priorValue).toBeNull();
expect(report.pendingCount).toBe(1);
// Nothing written: target frontmatter untouched, source unconsumed,
// no log file.
expect(attrsOf("Notes/paper.md")).toEqual({});
expect(readSource("Notes/journal.md")).not.toContain("@osb✓");
expect(parseLogDay(vault, LOG_DATE).entries).toHaveLength(0);
});
test("report mode works even with the guardrail off", async () => {
writeConfig({ markerWriteback: false });
writePaper("Notes/paper.md");
writeSource("Notes/journal.md", "@osb set note=paper field=status value=queued");
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: false,
agent: "a",
now: NOW,
});
expect(report.guardrailEnabled).toBe(false);
expect(report.entries[0]!.status).toBe("would-apply");
});
});
describe("guardrail gate", () => {
test("apply mode with the guardrail off throws a typed error naming the flag", async () => {
writeConfig({ markerWriteback: false });
writePaper("Notes/paper.md");
writeSource("Notes/journal.md", "@osb set note=paper field=status value=queued");
let caught: unknown;
try {
await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(MarkerWritebackGuardrailError);
expect((caught as MarkerWritebackGuardrailError).flag).toBe("marker_writeback");
expect((caught as Error).message).toContain("guardrails.marker_writeback");
// Fail-closed: nothing written.
expect(attrsOf("Notes/paper.md")).toEqual({});
expect(readSource("Notes/journal.md")).not.toContain("@osb✓");
});
});
describe("apply mode - happy path", () => {
test("writes the attribute, appends one audit event, consumes the marker", async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/paper.md");
writeSource("Notes/journal.md", "@osb set note=paper field=status value=queued");
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: true,
agent: "claude-dev-agent",
now: NOW,
});
expect(report.apply).toBe(true);
expect(report.appliedCount).toBe(1);
expect(report.entries[0]!.status).toBe("applied");
expect(report.entries[0]!.priorValue).toBeNull();
// Frontmatter mutated.
expect(attrsOf("Notes/paper.md")).toEqual({ status: "queued" });
// Exactly one attribute-write event with the full body shape.
const events = attributeWriteEvents();
expect(events).toHaveLength(1);
const body = events[0]!.body;
expect(body["note"]).toBe("Notes/paper.md");
expect(body["field"]).toBe("status");
expect(body["prior_value"]).toBe("null");
expect(body["new_value"]).toBe("queued");
expect(body["source_path"]).toBe("Notes/journal.md");
expect(body["source_line"]).toBe("3");
expect(body["agent"]).toBe("claude-dev-agent");
// Marker consumed (sentinel present).
expect(readSource("Notes/journal.md")).toContain("@osb✓");
});
test("re-running over the same files applies nothing (idempotent)", async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/paper.md");
writeSource("Notes/journal.md", "@osb set note=paper field=status value=queued");
await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
const second = await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
expect(second.entries).toHaveLength(0);
expect(second.appliedCount).toBe(0);
// Still exactly one audit event and one attribute value.
expect(attributeWriteEvents()).toHaveLength(1);
expect(attrsOf("Notes/paper.md")).toEqual({ status: "queued" });
});
test("prior value is captured on overwrite", async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/paper.md");
writeSource("Notes/first.md", "@osb set note=paper field=status value=queued");
writeSource("Notes/second.md", "@osb set note=paper field=status value=finished");
await applyMarkerWritebacks(vault, {
files: ["Notes/first.md"],
apply: true,
agent: "a",
now: NOW,
});
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/second.md"],
apply: true,
agent: "a",
now: NOW,
});
expect(report.entries[0]!.priorValue).toBe("queued");
expect(attrsOf("Notes/paper.md")).toEqual({ status: "finished" });
const events = attributeWriteEvents();
expect(events).toHaveLength(2);
expect(events[1]!.body["prior_value"]).toBe("queued");
expect(events[1]!.body["new_value"]).toBe("finished");
});
});
describe("apply mode - log redaction", () => {
test("writes the verbatim value to frontmatter but redacts secret-shaped values in the log event", async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/paper.md");
writeSource("Notes/first.md", "@osb set note=paper field=status value=api_key=oldsecret1");
writeSource("Notes/second.md", "@osb set note=paper field=status value=api_key=abcd1234");
await applyMarkerWritebacks(vault, {
files: ["Notes/first.md"],
apply: true,
agent: "a",
now: NOW,
});
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/second.md"],
apply: true,
agent: "a",
now: NOW,
});
expect(report.entries[0]!.status).toBe("applied");
// The note's frontmatter carries the operator's value verbatim -
// redaction is for the log surface, not the data write.
expect(attrsOf("Notes/paper.md")).toEqual({ status: "api_key=abcd1234" });
// The attribute-write log events redact both the prior and new
// secret-shaped values, mirroring apply-evidence's use of
// `sanitiseTextField`.
const events = attributeWriteEvents();
expect(events).toHaveLength(2);
expect(events[0]!.body["new_value"]).toBe("api_key=***REDACTED***");
const body = events[1]!.body;
expect(body["prior_value"]).toBe("api_key=***REDACTED***");
expect(body["new_value"]).toBe("api_key=***REDACTED***");
});
});
describe("apply mode - cross-file line shift", () => {
// Regression: a later source file whose `set` marker targets an
// earlier source note grows that note's frontmatter by a line, which
// shifts every body-marker line in the earlier note. Consuming markers
// per file at the end of that file's own iteration (before any later
// mutation runs) keeps `rewriteMarkers` pointed at the live line, so
// both markers are consumed and a second run applies nothing.
test("earlier note's body marker is consumed before a later source grows its frontmatter", async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/c.md");
// Note A is both a source file (its body carries a marker targeting
// C) and the target of B's marker. Written by hand so the marker
// lives in the body, below the frontmatter.
const aPath = join(vault, "Notes/a.md");
mkdirSync(join(aPath, ".."), { recursive: true });
writeFileSync(
aPath,
[
"---",
"type: paper",
"title: A Paper",
"---",
"",
"# A Paper",
"",
"@osb set note=Notes/c.md field=status value=queued",
"",
].join("\n"),
"utf8",
);
writeSource("Notes/b.md", "@osb set note=Notes/a.md field=year value=2026");
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/a.md", "Notes/b.md"],
apply: true,
agent: "a",
now: NOW,
});
// Both markers applied.
expect(report.appliedCount).toBe(2);
expect(attrsOf("Notes/c.md")).toEqual({ status: "queued" });
expect(attrsOf("Notes/a.md")).toEqual({ year: "2026" });
// Both markers consumed at the correct lines: A's body marker (which
// B's frontmatter write shifted down) still carries the sentinel and
// still references C, and B's marker carries the sentinel referencing
// A. No unconsumed `@osb set` survives in either file.
const aSrc = readSource("Notes/a.md");
expect(aSrc).toContain("@osb✓ [[Notes/c.md]] set note=Notes/c.md field=status value=queued");
expect(aSrc).not.toContain("\n@osb set");
const bSrc = readSource("Notes/b.md");
expect(bSrc).toContain("@osb✓ [[Notes/a.md]] set note=Notes/a.md field=year value=2026");
expect(bSrc).not.toContain("\n@osb set");
// Exactly one attribute-write event per mutation.
const events = attributeWriteEvents();
expect(events).toHaveLength(2);
expect(events.filter((e) => e.body["note"] === "Notes/c.md")).toHaveLength(1);
expect(events.filter((e) => e.body["note"] === "Notes/a.md")).toHaveLength(1);
// A second run applies nothing: no entries, no new events.
const second = await applyMarkerWritebacks(vault, {
files: ["Notes/a.md", "Notes/b.md"],
apply: true,
agent: "a",
now: NOW,
});
expect(second.entries).toHaveLength(0);
expect(second.appliedCount).toBe(0);
expect(second.pendingCount).toBe(0);
expect(attributeWriteEvents()).toHaveLength(2);
});
});
describe("apply mode - per-marker isolation", () => {
test("an ambiguous target fails that marker with candidates; others still apply", async () => {
writeConfig({ markerWriteback: true, readPaths: ["Notes", "Archive"] });
writePaper("Notes/paper.md");
writePaper("Archive/paper.md");
writePaper("Notes/report.md");
writeSource(
"Notes/journal.md",
"@osb set note=paper field=status value=queued",
"@osb set note=Notes/report.md field=year value=2026",
);
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
const ambiguous = report.entries.find((e) => e.rawTarget === "paper")!;
expect(ambiguous.status).toBe("invalid-target");
expect(ambiguous.errorCode).toBe("ambiguous");
expect([...ambiguous.candidates].toSorted()).toEqual(["Archive/paper.md", "Notes/paper.md"]);
const good = report.entries.find((e) => e.rawTarget === "Notes/report.md")!;
expect(good.status).toBe("applied");
// The valid marker applied and was consumed; the ambiguous one is
// left unconsumed for a later retry.
expect(attrsOf("Notes/report.md")).toEqual({ year: "2026" });
const src = readSource("Notes/journal.md");
expect(src).toContain("@osb✓ [[Notes/report.md]] set note=Notes/report.md");
expect(src).toContain("@osb set note=paper field=status value=queued");
expect(attrsOf("Notes/paper.md")).toEqual({});
});
test("an undeclared field fails closed via the vocabulary error, unconsumed", async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/paper.md");
writeSource("Notes/journal.md", "@osb set note=paper field=rating value=5");
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
expect(report.entries).toHaveLength(1);
expect(report.entries[0]!.status).toBe("invalid-field");
expect(report.entries[0]!.error).toContain("rating");
expect(report.failedCount).toBe(1);
// Nothing written or consumed.
expect(attrsOf("Notes/paper.md")).toEqual({});
expect(readSource("Notes/journal.md")).not.toContain("@osb✓");
expect(attributeWriteEvents()).toHaveLength(0);
});
test("an untyped target note fails closed as invalid-field", async () => {
writeConfig({ markerWriteback: true });
// A note with no `type` in frontmatter under a read path.
const path = join(vault, "Notes", "untyped.md");
mkdirSync(join(path, ".."), { recursive: true });
writeFileSync(path, "# Untyped\n\nbody\n", "utf8");
writeSource("Notes/journal.md", "@osb set note=untyped field=status value=queued");
const report = await applyMarkerWritebacks(vault, {
files: ["Notes/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
expect(report.entries[0]!.status).toBe("invalid-field");
expect(report.entries[0]!.error).toContain("declares no type");
expect(readSource("Notes/journal.md")).not.toContain("@osb✓");
});
});
describe("governance refusals are per-marker verdicts", () => {
function writeBoundConfig(): void {
writeConfig({ markerWriteback: true, readPaths: ["Projects", "Notes"] });
const configPath = join(brainDirs(vault).brain, "_brain.yaml");
const body = readFileSync(configPath, "utf8");
writeFileSync(
configPath,
`${body}\nwrite_binding:\n path_prefixes:\n - Projects\n`,
"utf8",
);
}
function seed(): void {
writeBoundConfig();
writePaper("Notes/outside.md");
writePaper("Projects/inside.md");
writePaper("Brain/preferences/pref-x.md");
writeSource(
"Projects/journal.md",
"@osb set note=Notes/outside.md field=status value=queued",
"@osb set note=Brain/preferences/pref-x.md field=status value=queued",
"@osb set note=Projects/inside.md field=status value=queued",
);
}
test("report mode reports a refused target instead of promising the write", async () => {
seed();
const report = await applyMarkerWritebacks(vault, {
files: ["Projects/journal.md"],
apply: false,
agent: "a",
now: NOW,
});
expect(report.entries.map((e) => [e.rawTarget, e.status])).toEqual([
["Notes/outside.md", "refused"],
["Brain/preferences/pref-x.md", "refused"],
["Projects/inside.md", "would-apply"],
]);
expect(report.entries[0]!.error).toMatch(/write binding/i);
expect(report.entries[1]!.error).toContain("Brain machinery");
expect(report.failedCount).toBe(2);
expect(report.pendingCount).toBe(1);
});
test("apply mode refuses those markers and still applies the rest of the run", async () => {
seed();
const report = await applyMarkerWritebacks(vault, {
files: ["Projects/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
expect(report.entries.map((e) => [e.rawTarget, e.status])).toEqual([
["Notes/outside.md", "refused"],
["Brain/preferences/pref-x.md", "refused"],
["Projects/inside.md", "applied"],
]);
expect(attrsOf("Notes/outside.md")).toEqual({});
expect(attrsOf("Brain/preferences/pref-x.md")).toEqual({});
expect(attrsOf("Projects/inside.md")).toEqual({ status: "queued" });
// Refused markers stay live for the operator; the applied one is consumed.
const src = readSource("Projects/journal.md");
expect(src).toContain("@osb set note=Notes/outside.md");
expect(src).toContain("@osb set note=Brain/preferences/pref-x.md");
expect(src).toContain("@osb✓ [[Projects/inside.md]]");
expect(attributeWriteEvents()).toHaveLength(1);
});
});
describe("apply mode - consumption failure surfaces applied-unconsumed", () => {
// Forces the post-write hazard: the attribute write and audit append
// succeed, but the marker-consumption rewrite fails (the source lives in a
// read-only directory, so `atomicWriteFileSync` cannot create its temp
// file). The mutation stands while the marker stays live - the run must
// report that honestly (applied-unconsumed), not as a clean `applied`.
// Skipped when running as root, which bypasses directory write bits, and
// on Windows, where chmod cannot make a directory refuse new files.
test.skipIf(CHMOD_CANNOT_DENY)(
"a failed rewrite yields applied-unconsumed with the mutation intact and the marker live",
async () => {
writeConfig({ markerWriteback: true });
writePaper("Notes/paper.md");
// Source lives in its own directory so it can be made read-only without
// touching the target note (Notes) or the log (Brain).
writeSource("Locked/journal.md", "@osb set note=paper field=status value=queued");
const lockedDir = join(vault, "Locked");
chmodSync(lockedDir, 0o555);
try {
const report = await applyMarkerWritebacks(vault, {
files: ["Locked/journal.md"],
apply: true,
agent: "a",
now: NOW,
});
// Honest partial status: not counted as a clean apply.
expect(report.appliedCount).toBe(0);
expect(report.unconsumedCount).toBe(1);
const entry = report.entries[0]!;
expect(entry.status).toBe("applied-unconsumed");
expect(entry.error).toContain("consumption failed");
// The mutation landed and the audit event was written before the
// consumption step failed.
expect(attrsOf("Notes/paper.md")).toEqual({ status: "queued" });
expect(attributeWriteEvents()).toHaveLength(1);
// The marker is still live (unconsumed) for the operator to reconcile.
expect(readSource("Locked/journal.md")).not.toContain("@osb✓");
expect(readSource("Locked/journal.md")).toContain("@osb set note=paper");
} finally {
// Restore write access so afterEach can clean the tmp vault.
chmodSync(lockedDir, 0o755);
}
},
);
});