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 src/core/brain/pretool-host-backup.ts - the pure decision
* core and fail-closed backup executor behind the opt-in PreToolUse
* host-settings backup hook (t_f4555087).
*
* The matcher resolves tilde, cwd-relative and symlinked forms of a
* Claude settings path to one canonical target; anything else allows.
* The executor backs the file up under the trust conventions' stamped
* folder (tests/core/trust-conventions.test.ts), never overwrites a
* same-second backup, and appends exactly one receipt carrying actor,
* pid, before-hash and summary.
*/
import { afterEach, describe, expect, test } from "bun:test";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
statSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join, sep } from "node:path";
import {
decideHostBackup,
executeHostBackup,
HostBackupError,
HOST_BACKUP_ALLOC_MAX_ATTEMPTS,
PROTECTED_SETTINGS_NAMES,
WRITE_TOOL_NAMES,
} from "../../../src/core/brain/pretool-host-backup.ts";
import { hookAuditDir } from "../../../src/core/brain/paths.ts";
import { CHMOD_CANNOT_DENY, IS_WINDOWS } from "../../helpers/platform.ts";
/** Minimal audit reader: every record in the (single-shard) audit root. */
function readAuditRecords(auditDir: string): Array<Record<string, unknown>> {
const records: Array<Record<string, unknown>> = [];
for (const file of readdirSync(auditDir)) {
for (const line of readFileSync(join(auditDir, file), "utf8").split("\n")) {
if (line.trim().length > 0) records.push(JSON.parse(line) as Record<string, unknown>);
}
}
return records;
}
let tmpDirs: string[] = [];
function tmpDir(prefix: string): string {
const dir = mkdtempSync(join(tmpdir(), prefix));
tmpDirs.push(dir);
return dir;
}
afterEach(() => {
for (const d of tmpDirs.splice(0)) rmSync(d, { recursive: true, force: true });
});
function decide(home: string, cwd: string, filePath: string, toolName = "Write") {
return decideHostBackup({
runtime: "claudecode",
toolName,
toolInput: { file_path: filePath },
home,
cwd,
});
}
describe("decideHostBackup", () => {
test("tilde, cwd-relative and symlinked settings paths resolve to one canonical target", () => {
const home = tmpDir("osb-hb-home-");
mkdirSync(join(home, "f", ".claude"), { recursive: true });
writeFileSync(join(home, "f", ".claude", "settings.json"), "{}\n");
const tilde = decide(home, home, "~/f/.claude/settings.json");
const relative = decide(home, join(home, "f"), ".claude/settings.json");
// A symlinked settings dir resolving at the same file. A directory
// junction needs no symlink privilege on Windows and is a plain
// symlink on POSIX - the one portable way to build this fixture.
symlinkSync(join(home, "f", ".claude"), join(home, "linked-claude"), "junction");
const symlinked = decide(home, home, join(home, "linked-claude", "settings.json"));
for (const d of [tilde, relative, symlinked]) {
expect(d.kind).toBe("backup");
}
const target = tilde.kind === "backup" ? tilde.targets[0]! : "";
expect(relative.kind === "backup" && relative.targets[0]).toBe(target);
expect(symlinked.kind === "backup" && symlinked.targets[0]).toBe(target);
// The canonical target names the real .claude settings file; the
// comparison is separator-agnostic so the win32 spelling matches.
expect(target.split(sep).join("/").endsWith(".claude/settings.json")).toBe(true);
});
test("settings.local.json and the user-level settings file are protected", () => {
const home = tmpDir("osb-hb-home2-");
mkdirSync(join(home, ".claude"), { recursive: true });
writeFileSync(join(home, ".claude", "settings.local.json"), "{}\n");
const local = decide(home, home, "~/.claude/settings.local.json");
expect(local.kind).toBe("backup");
const user = decide(home, home, "~/.claude/settings.json");
expect(user.kind).toBe("backup");
// The names the predicate matches, named once.
expect([...PROTECTED_SETTINGS_NAMES]).toEqual(["settings.json", "settings.local.json"]);
expect([...WRITE_TOOL_NAMES]).toEqual(["Write", "Edit", "MultiEdit", "apply_patch"]);
});
test("unrelated paths return allow", () => {
const home = tmpDir("osb-hb-home3-");
mkdirSync(join(home, "proj"), { recursive: true });
writeFileSync(join(home, "proj", "note.md"), "hi\n");
for (const p of [
"~/f/Brain/note.md",
".claude/other.json",
"settings.json",
"~/f/.claude/settings.json.bak.123",
"/etc/passwd",
]) {
const d = decide(home, join(home, "proj"), p);
expect(d.kind).toBe("allow");
}
});
test("codex config.toml is excluded: protect's own fence manages it", () => {
const home = tmpDir("osb-hb-home4-");
const d = decide(home, home, "~/.codex/config.toml");
expect(d.kind).toBe("allow");
});
test("a non-write tool or a missing path argument allows", () => {
const home = tmpDir("osb-hb-home5-");
const read = decideHostBackup({
runtime: "claudecode",
toolName: "Read",
toolInput: { file_path: "~/.claude/settings.json" },
home,
cwd: home,
});
expect(read.kind).toBe("allow");
const noPath = decideHostBackup({
runtime: "claudecode",
toolName: "Write",
toolInput: {},
home,
cwd: home,
});
expect(noPath.kind).toBe("allow");
});
});
describe("decideHostBackup — Codex apply_patch payloads", () => {
test("an Update File header naming a protected path backs up", () => {
const home = tmpDir("osb-hb-ap-");
mkdirSync(join(home, ".claude"), { recursive: true });
writeFileSync(join(home, ".claude", "settings.json"), "{}\n");
const d = decideHostBackup({
runtime: "codex",
toolName: "apply_patch",
toolInput: {
input:
"*** Begin Patch\n*** Update File: " +
join(home, ".claude", "settings.json") +
"\n@@\n- old\n+ new\n*** End Patch",
},
home,
cwd: home,
});
expect(d.kind).toBe("backup");
if (d.kind !== "backup") return;
expect(d.targets).toEqual([join(home, ".claude", "settings.json")]);
});
test("every header path is collected; only the protected ones back up", () => {
const home = tmpDir("osb-hb-ap2-");
mkdirSync(join(home, ".claude"), { recursive: true });
writeFileSync(join(home, ".claude", "settings.json"), "{}\n");
writeFileSync(join(home, ".claude", "settings.local.json"), "{}\n");
writeFileSync(join(home, "notes.md"), "x\n");
const d = decideHostBackup({
runtime: "codex",
toolName: "apply_patch",
toolInput: {
input:
"*** Begin Patch\n" +
"*** Add File: " +
join(home, "notes.md") +
"\n+hello\n" +
"*** Update File: " +
join(home, ".claude", "settings.json") +
"\n@@\n" +
"*** Delete File: " +
join(home, ".claude", "settings.local.json") +
"\n*** End Patch",
},
home,
cwd: home,
});
expect(d.kind).toBe("backup");
if (d.kind !== "backup") return;
expect(d.targets).toEqual([
join(home, ".claude", "settings.json"),
join(home, ".claude", "settings.local.json"),
]);
});
test("a relative header path resolves against the hook cwd", () => {
const home = tmpDir("osb-hb-ap3-");
const proj = join(home, "proj");
mkdirSync(join(proj, ".claude"), { recursive: true });
writeFileSync(join(proj, ".claude", "settings.local.json"), "{}\n");
const d = decideHostBackup({
runtime: "codex",
toolName: "apply_patch",
toolInput: { input: "*** Begin Patch\n*** Add File: .claude/settings.local.json\n+{}\n" },
home,
cwd: proj,
});
expect(d.kind).toBe("backup");
if (d.kind !== "backup") return;
expect(d.targets).toEqual([join(proj, ".claude", "settings.local.json")]);
});
});
describe("decideHostBackup — symlinked settings files", () => {
test("a settings file that is itself a symlink is protected via its lexical path", () => {
const home = tmpDir("osb-hb-symlink-");
mkdirSync(join(home, "dotfiles"), { recursive: true });
mkdirSync(join(home, ".claude"), { recursive: true });
const real = join(home, "dotfiles", "settings.json");
writeFileSync(real, '{"theme":"dark"}\n');
symlinkSync(real, join(home, ".claude", "settings.json"));
// The realpath resolves the final component into the dotfiles dir,
// whose parent is not `.claude`; the lexical path the agent names
// IS a `.claude` settings file, and either match protects.
const d = decide(home, home, "~/.claude/settings.json");
expect(d.kind).toBe("backup");
if (d.kind !== "backup") return;
expect(d.targets).toEqual([join(home, ".claude", "settings.json")]);
});
test("the symlinked file's backup carries the real bytes through the link", () => {
const home = tmpDir("osb-hb-symlink2-");
mkdirSync(join(home, "dotfiles"), { recursive: true });
mkdirSync(join(home, ".claude"), { recursive: true });
const real = join(home, "dotfiles", "settings.json");
const contents = '{"token":"s3cret"}\n';
writeFileSync(real, contents);
const lexical = join(home, ".claude", "settings.json");
symlinkSync(real, lexical);
const out = executeHostBackup({
target: lexical,
vault: null,
now: new Date("2026-10-16T12:34:56Z"),
actor: "hook:claudecode",
});
expect(out.kind).toBe("backed-up");
if (out.kind !== "backed-up") return;
expect(readFileSync(out.backupPath, "utf8")).toBe(contents);
});
});
describe("executeHostBackup — backups root git hygiene", () => {
test("the first project backup drops a *-ignore into the backups root", () => {
const home = tmpDir("osb-hb-ignore-");
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.local.json");
writeFileSync(target, '{"allow":["Bash"]}\n');
const out = executeHostBackup({
target,
vault: null,
now: new Date("2026-10-16T12:34:56Z"),
actor: "hook:claudecode",
});
expect(out.kind).toBe("backed-up");
if (out.kind !== "backed-up") return;
// settings.local.json copies can hold tokens; without this marker
// the next `git add -A` commits them from a project repo.
const ignorePath = join(home, ".claude", ".o2b-backups", ".gitignore");
expect(existsSync(ignorePath)).toBe(true);
const text = readFileSync(ignorePath, "utf8");
expect(text).toContain("*");
expect(text).toContain("!.gitignore");
});
test("a second backup never rewrites the ignore file", () => {
const home = tmpDir("osb-hb-ignore2-");
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
writeFileSync(target, "x\n");
const opts = {
target,
vault: null,
now: new Date("2026-10-16T12:34:56Z"),
actor: "hook:claudecode",
};
executeHostBackup(opts);
const ignorePath = join(home, ".claude", ".o2b-backups", ".gitignore");
const before = readFileSync(ignorePath, "utf8");
executeHostBackup({ ...opts, now: new Date("2026-10-16T12:34:57Z") });
expect(readFileSync(ignorePath, "utf8")).toBe(before);
});
});
describe("executeHostBackup", () => {
test("two backups inside one second produce two distinct files", () => {
const home = tmpDir("osb-hb-exec-");
const vault = tmpDir("osb-hb-vault-");
mkdirSync(join(vault, "Brain"), { recursive: true }); // a legacy tree: unswitched
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
writeFileSync(target, '{"theme":"dark"}\n');
const now = new Date("2026-10-16T12:34:56Z");
const first = executeHostBackup({ target, vault, now, actor: "hook:claudecode" });
const second = executeHostBackup({ target, vault, now, actor: "hook:claudecode" });
expect(first.kind).toBe("backed-up");
expect(second.kind).toBe("backed-up");
if (first.kind !== "backed-up" || second.kind !== "backed-up") return;
expect(first.backupPath).not.toBe(second.backupPath);
// Both hold the exact source bytes.
expect(readFileSync(first.backupPath, "utf8")).toBe('{"theme":"dark"}\n');
expect(readFileSync(second.backupPath, "utf8")).toBe('{"theme":"dark"}\n');
// Folder layout: <dir>/.o2b-backups/settings.json/<stamp>[-N].
// Separator-agnostic: the win32 backup path is backslash-joined.
expect(first.backupPath.split(sep).join("/")).toContain(
".o2b-backups/settings.json/2026-10-16-123456",
);
});
test.skipIf(IS_WINDOWS)(
"the backup file is private 0600 - settings backups carry secrets",
() => {
const home = tmpDir("osb-hb-mode-");
const vault = tmpDir("osb-hb-vault-mode-");
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
writeFileSync(target, '{"token":"s3cret"}\n');
const out = executeHostBackup({
target,
vault,
now: new Date("2026-10-16T12:34:56Z"),
actor: "hook:claudecode",
});
expect(out.kind).toBe("backed-up");
if (out.kind !== "backed-up") return;
// Both twins agree with the wrapper's openSync(..., "wx", 0o600):
// the canonical core creates exclusively at the same private mode.
expect(statSync(out.backupPath).mode & 0o777).toBe(0o600);
},
);
test("exhausted collision attempts raise a typed error, never overwriting", () => {
const home = tmpDir("osb-hb-exh-");
const vault = tmpDir("osb-hb-vault2-");
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
writeFileSync(target, "x\n");
// Pre-create every candidate name the allocator may try.
const backupRoot = join(home, ".claude", ".o2b-backups", "settings.json");
mkdirSync(backupRoot, { recursive: true });
const now = new Date("2026-10-16T12:34:56Z");
for (let attempt = 1; attempt <= HOST_BACKUP_ALLOC_MAX_ATTEMPTS; attempt++) {
const name = attempt === 1 ? "2026-10-16-123456" : `2026-10-16-123456-${attempt}`;
writeFileSync(join(backupRoot, name), "occupied\n");
}
let raised: unknown = null;
try {
executeHostBackup({ target, vault, now, actor: "hook:claudecode" });
} catch (e) {
raised = e;
}
expect(raised).toBeInstanceOf(HostBackupError);
expect((raised as Error).message).toContain(target);
// Nothing was overwritten.
expect(readFileSync(join(backupRoot, "2026-10-16-123456"), "utf8")).toBe("occupied\n");
});
test("a missing source file allows with no receipt", () => {
const home = tmpDir("osb-hb-miss-");
const vault = tmpDir("osb-hb-vault3-");
const target = join(home, ".claude", "settings.json");
const out = executeHostBackup({ target, vault, now: new Date(), actor: "hook:claudecode" });
expect(out.kind).toBe("allow-no-source");
expect(existsSync(hookAuditDir(vault))).toBe(false);
});
test.skipIf(CHMOD_CANNOT_DENY)(
"an unreadable source returns a typed failure naming the path",
() => {
const home = tmpDir("osb-hb-unread-");
const vault = tmpDir("osb-hb-vault4-");
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
writeFileSync(target, "secret\n");
chmodSync(target, 0o000);
try {
let raised: unknown = null;
try {
executeHostBackup({ target, vault, now: new Date(), actor: "hook:claudecode" });
} catch (e) {
raised = e;
}
expect(raised).toBeInstanceOf(HostBackupError);
expect((raised as Error).message).toContain(target);
} finally {
chmodSync(target, 0o644);
}
},
);
test("a failed copy raises a typed failure naming the path", () => {
const home = tmpDir("osb-hb-failcopy-");
const vault = tmpDir("osb-hb-vault5-");
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
writeFileSync(target, "x\n");
// A FILE where the backup folder must be makes every create fail.
writeFileSync(join(home, ".claude", ".o2b-backups"), "not a dir\n");
let raised: unknown = null;
try {
executeHostBackup({ target, vault, now: new Date(), actor: "hook:claudecode" });
} catch (e) {
raised = e;
}
expect(raised).toBeInstanceOf(HostBackupError);
expect((raised as Error).message).toContain(target);
});
test("success appends exactly one receipt with actor, pid, before-hash, summary", () => {
const home = tmpDir("osb-hb-rcpt-");
const vault = tmpDir("osb-hb-vault6-");
mkdirSync(join(vault, "Brain"), { recursive: true }); // a legacy tree: unswitched
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
const contents = '{"theme":"dark"}\n';
writeFileSync(target, contents);
const out = executeHostBackup({
target,
vault,
now: new Date("2026-10-16T12:34:56Z"),
actor: "hook:claudecode",
});
expect(out.kind).toBe("backed-up");
if (out.kind !== "backed-up") return;
// Exactly one audit record across the whole week shard.
const auditDir = hookAuditDir(vault);
const files = readdirSync(auditDir);
expect(files.length).toBe(1);
const records = readAuditRecords(auditDir);
expect(records.length).toBe(1);
const r = records[0]!;
expect(r.actor).toBe("hook:claudecode");
expect(r.ok).toBe(true);
expect(r.target).toBe(target);
// The trust receipt head (tests/core/trust-conventions.test.ts).
expect(r.details).toBeDefined();
const details = r.details as Record<string, unknown>;
expect(details["pid"]).toBe(process.pid);
expect(details["before_hash"]).toMatch(/^sha256:[0-9a-f]{64}$/);
expect(String(details["summary"])).toContain("settings.json");
expect(details["backup"]).toBe(out.backupPath);
// The hash is the source content's sha-256.
const digest = new Bun.CryptoHasher("sha256").update(contents).digest("hex");
expect(details["before_hash"]).toBe(`sha256:${digest}`);
});
test("a missing vault skips the receipt without failing the backup", () => {
const home = tmpDir("osb-hb-novault-");
mkdirSync(join(home, ".claude"), { recursive: true });
const target = join(home, ".claude", "settings.json");
writeFileSync(target, "x\n");
const out = executeHostBackup({
target,
vault: null,
now: new Date(),
actor: "hook:claudecode",
});
expect(out.kind).toBe("backed-up");
if (out.kind !== "backed-up") return;
expect(out.receiptPath).toBeNull();
expect(existsSync(out.backupPath)).toBe(true);
});
});