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
/**
* Sync lockfile primitive for the brain write path. Single-attempt
* exclusive create via `fs.openSync(target + '.lock', 'wx')`. Collisions
* surface as a regular Error with `.code === 'ELOCKED'`; the brain
* txn layer maps that to a `BrainCollisionError({ kind: 'SourceLock' })`.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
existsSync,
lstatSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
statSync,
unlinkSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { randomUUID } from "node:crypto";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { IS_WINDOWS } from "../../helpers/platform.ts";
import {
acquireLockSync,
acquireLockSyncWithRetry,
isWindowsDeletePending,
LOCK_WAIT_BUDGET_MS,
LOCK_WAIT_INTERACTIVE_MS,
lockScanRoots,
removeStaleLockSync,
scanStaleLocks,
TAKEOVER_CLAIM_STALE_MS,
} from "../../../src/core/brain/sync-lockfile.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 tmpRoot: string;
beforeEach(() => {
tmpRoot = mkdtempSync(join(tmpdir(), "osb-sync-lock-"));
});
afterEach(() => {
if (tmpRoot) rmSync(tmpRoot, { recursive: true, force: true });
});
describe("acquireLockSync", () => {
test("creates a .lock sibling file and release removes it", () => {
const target = join(tmpRoot, "pref-foo.md");
writeFileSync(target, "---\nkind: brain-preference\n---\n");
const handle = acquireLockSync(target);
expect(handle.path).toBe(target + ".lock");
expect(existsSync(target + ".lock")).toBe(true);
handle.release();
expect(existsSync(target + ".lock")).toBe(false);
});
test("throws Error with code ELOCKED when the lock is already held", () => {
const target = join(tmpRoot, "pref-bar.md");
writeFileSync(target, "---\nkind: brain-preference\n---\n");
const first = acquireLockSync(target);
try {
let caught: unknown;
try {
acquireLockSync(target);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(Error);
expect((caught as NodeJS.ErrnoException).code).toBe("ELOCKED");
} finally {
first.release();
}
});
test("after release, target is acquirable again", () => {
const target = join(tmpRoot, "pref-baz.md");
writeFileSync(target, "---\n---\n");
const first = acquireLockSync(target);
first.release();
const second = acquireLockSync(target);
expect(existsSync(target + ".lock")).toBe(true);
second.release();
});
test("release is idempotent (second call is a no-op)", () => {
const target = join(tmpRoot, "pref-idem.md");
writeFileSync(target, "");
const handle = acquireLockSync(target);
handle.release();
handle.release(); // must not throw
expect(existsSync(target + ".lock")).toBe(false);
});
test("acquire creates the lock even when the target file does not exist", () => {
// The brain txn path needs to be able to lock the target before the
// file is created (first-time write). The lock primitive must not
// require the target to exist.
const target = join(tmpRoot, "pref-new.md");
const handle = acquireLockSync(target);
try {
expect(existsSync(target + ".lock")).toBe(true);
expect(existsSync(target)).toBe(false);
} finally {
handle.release();
}
});
test("release leaves a lock file it no longer owns in place", () => {
// A takeover removed this holder's lock and another process acquired the
// name; the first holder's release must not delete the second's lock.
const target = join(tmpRoot, "pref-owned.md");
const first = acquireLockSync(target);
unlinkSync(target + ".lock");
const second = acquireLockSync(target);
try {
first.release();
expect(existsSync(target + ".lock")).toBe(true);
expect(() => acquireLockSync(target)).toThrow(/lock busy/);
} finally {
second.release();
}
expect(existsSync(target + ".lock")).toBe(false);
});
test.skipIf(IS_WINDOWS)(
"release keeps a reused-identity lock that carries a foreign holder token",
() => {
// A filesystem can hand a freed inode straight back to the next
// create, so the lock file that answers this holder's device and
// inode can be another holder's. Ownership is decided by the body's
// holder token as well: overwriting the body in place keeps the
// identity while replacing the holder, and the first release must
// read the foreign stamp, judge the name not its own, and leave the
// file in place.
const target = join(tmpRoot, "pref-reused.md");
const lockPath = target + ".lock";
const first = acquireLockSync(target);
const identity = statSync(lockPath, { bigint: true });
writeFileSync(lockPath, `${process.pid}\n${randomUUID()}\n`);
const reused = statSync(lockPath, { bigint: true });
expect(reused.dev).toBe(identity.dev);
expect(reused.ino).toBe(identity.ino);
first.release();
expect(existsSync(lockPath)).toBe(true);
expect(() => acquireLockSync(target)).toThrow(/lock busy/);
unlinkSync(lockPath);
expect(existsSync(lockPath)).toBe(false);
},
);
test("release unlinks a lock whose token's first byte lost to a racing waiter mark", () => {
// A waiter that opened the name in the microseconds before the
// holder's stamp landed writes its mark at position zero and
// clobbers the token's first byte. The body still carries the
// holder's unique token line, so the release must treat the file
// as its own and remove it.
const target = join(tmpRoot, "pref-clobbered.md");
const lockPath = target + ".lock";
const first = acquireLockSync(target);
const before = readFileSync(lockPath, "utf8");
writeFileSync(lockPath, `w${before.slice(1)}`);
first.release();
expect(existsSync(lockPath)).toBe(false);
const again = acquireLockSync(target);
again.release();
});
});
describe("exit sweep after a stale handle's release", () => {
test("a newer handle's lock is still removed at exit after an older handle released", () => {
// The older handle lost its lock to a takeover; the newer handle in the
// same process re-registered the path. The older release must not drop
// that registration, or the exit sweep would leave the newer lock behind.
const target = join(tmpRoot, "pref-exit.md");
const module = resolve(import.meta.dir, "../../../src/core/brain/sync-lockfile.ts");
const script = `
const { unlinkSync } = await import("node:fs");
const { acquireLockSync } = await import(${JSON.stringify(module)});
const target = ${JSON.stringify(target)};
const first = acquireLockSync(target);
unlinkSync(target + ".lock");
acquireLockSync(target);
first.release();
`;
const child = Bun.spawnSync([process.execPath, "-e", script]);
expect(child.exitCode).toBe(0);
expect(existsSync(target + ".lock")).toBe(false);
});
});
describe("isWindowsDeletePending", () => {
const eperm = Object.assign(new Error("EPERM"), { code: "EPERM" }) as NodeJS.ErrnoException;
const eacces = Object.assign(new Error("EACCES"), { code: "EACCES" }) as NodeJS.ErrnoException;
const eexist = Object.assign(new Error("EEXIST"), { code: "EEXIST" }) as NodeJS.ErrnoException;
test("win32 EPERM / EACCES on a name something holds is contention", () => {
expect(isWindowsDeletePending(eperm, "x.lock", "win32", () => true)).toBe(true);
expect(isWindowsDeletePending(eacces, "x.lock", "win32", () => true)).toBe(true);
});
test("win32 EPERM with nothing at the name is a directory that refuses creates", () => {
// An ACL or Controlled Folder Access: waiting the whole budget and then
// saying "lock busy" would hide the real reason for five seconds.
expect(isWindowsDeletePending(eperm, "x.lock", "win32", () => false)).toBe(false);
});
test("never on POSIX, and never for another code", () => {
expect(isWindowsDeletePending(eperm, "x.lock", "linux", () => true)).toBe(false);
expect(isWindowsDeletePending(eexist, "x.lock", "win32", () => true)).toBe(false);
});
test("the default probe reads the real filesystem", () => {
const held = join(tmpRoot, "held.lock");
writeFileSync(held, "");
expect(isWindowsDeletePending(eperm, held, "win32")).toBe(true);
expect(isWindowsDeletePending(eperm, join(tmpRoot, "absent.lock"), "win32")).toBe(false);
});
});
describe("scanStaleLocks", () => {
test("returns paths of every .lock file under Brain/", () => {
const a = join(tmpRoot, "Brain", "preferences", "pref-a.md");
const b = join(tmpRoot, "Brain", "log", "continuity", "2026-06.jsonl");
mkdirSync(dirname(a), { recursive: true });
mkdirSync(dirname(b), { recursive: true });
writeFileSync(a, "");
const ha = acquireLockSync(a);
// Manually drop a lock deeper in the tree to exercise the walk.
writeFileSync(b + ".lock", "");
const found = scanStaleLocks(tmpRoot).toSorted();
expect(found).toContain(a + ".lock");
expect(found).toContain(b + ".lock");
ha.release();
require("node:fs").unlinkSync(b + ".lock");
});
/**
* The manifest and the ingest checkpoint - the two locks the parallel
* ingest path takes most often - live in `.open-second-brain/`, not in
* `Brain/`. A scan rooted at `Brain/` alone reported nothing for them,
* so a crashed ingest left a lock the doctor could not name.
*/
test("returns .lock files under the derived-store directory too", () => {
const manifest = join(tmpRoot, ".open-second-brain", "ingest-manifest.json");
const checkpoint = join(
tmpRoot,
".open-second-brain",
"ingest-checkpoints",
"0123456789abcdef.json",
);
mkdirSync(dirname(checkpoint), { recursive: true });
const hm = acquireLockSync(manifest);
const hc = acquireLockSync(checkpoint);
try {
const found = scanStaleLocks(tmpRoot);
expect(found).toContain(manifest + ".lock");
expect(found).toContain(checkpoint + ".lock");
} finally {
hm.release();
hc.release();
}
});
test("returns an empty array when no locks exist", () => {
const found = scanStaleLocks(tmpRoot);
expect(found).toEqual([]);
});
test("a lock outside every enumerated root is not reported", () => {
// Not a defect - it is the enumeration's boundary, stated so the
// census below has something to be a census OF.
const stray = join(tmpRoot, "notes", "user-note.md");
mkdirSync(dirname(stray), { recursive: true });
const handle = acquireLockSync(stray);
try {
expect(scanStaleLocks(tmpRoot)).toEqual([]);
} finally {
handle.release();
}
});
});
/**
* The scan walks an ENUMERATED set of roots ({@link lockScanRoots}) rather
* than one hard-coded directory, so a lock location that is not under one
* of them escapes `brain doctor` silently - which is exactly what happened
* to the manifest and the checkpoint.
*
* This census reads the sources rather than their behaviour, in the same
* discipline as `tests/hooks/audit-root.test.ts`: the defect is not that
* any one module locks the wrong place today, it is that adding a
* thirteenth lock site under a third root would leave the scan quietly
* incomplete. A new site fails this list until its author states which
* root the scan will find it under.
*/
describe("every module that takes a lock is under a scanned root", () => {
const SRC = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "src");
/**
* Declared lock sites, each with the vault-relative root
* {@link lockScanRoots} reaches it through. Verified against the path
* builders: every entry resolves under `Brain/` except the five that
* live in the derived-store directory - the shared checkpoint substrate
* (both the ingest and the session-import lanes lock through it), the
* ingest content manifest, the session import ledger, the session
* mining ledger, and the lessons-approval ledger (t_1e952e43).
*/
const DECLARED: ReadonlyMap<string, string> = new Map([
["core/brain/architect/generate.ts", "Brain"],
["core/brain/attestation/record.ts", ".open-second-brain"],
["core/brain/checkpoint-store.ts", ".open-second-brain"],
["core/brain/continuity/store.ts", "Brain"],
["core/brain/diagnostics.ts", "Brain"],
["core/brain/git/store.ts", "Brain"],
["core/brain/health/remediation.ts", "Brain"],
["core/brain/idempotency-ledger.ts", "Brain"],
["core/brain/ingest/content-manifest.ts", ".open-second-brain"],
// the lessons-approvals ledger read-modify-write (t_1e952e43), the
// fifth derived-store lock site
["core/brain/lessons-promotion.ts", ".open-second-brain"],
["core/brain/lineage/ledger.ts", "Brain"],
["core/brain/metrics.ts", "Brain"],
["core/brain/link-graph/hallways.ts", "Brain"],
["core/brain/link-graph/orphan-repair.ts", "Brain"],
["core/brain/payload-registry.ts", "Brain"],
["core/brain/pinned.ts", "Brain"],
["core/brain/pledge-intake.ts", "Brain"],
["core/brain/pledges.ts", "Brain"],
["core/brain/preference-txn.ts", "Brain"],
["core/brain/query-demand.ts", "Brain"],
["core/brain/receipts/compact.ts", "Brain"],
["core/brain/session-mining-ledger.ts", ".open-second-brain"],
["core/brain/session-mining-surveys.ts", ".open-second-brain"],
["core/brain/sessions/discover.ts", ".open-second-brain"],
["core/brain/skill-proposals.ts", "Brain"],
// the lane page store locks a record-lane page on an unswitched
// machine (task 2.10 WP6); its pages live under Brain/
["core/store/lane-pages.ts", "Brain"],
]);
/** Every `src/` file that calls the lock primitive, vault-relative to `src/`. */
function lockCallers(): string[] {
const out: string[] = [];
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const full = join(dir, entry.name);
if (entry.isDirectory()) {
walk(full);
continue;
}
if (!entry.name.endsWith(".ts")) continue;
const rel = full.slice(SRC.length + 1).replaceAll("\\", "/");
if (rel === "core/brain/sync-lockfile.ts") continue;
const text = readFileSync(full, "utf8");
if (/acquireLockSync(WithRetry)?\(/.test(text)) out.push(rel);
}
};
walk(SRC);
return out.toSorted();
}
test("the sweep actually found the lock callers", () => {
// A census over an empty set passes for the wrong reason.
expect(lockCallers().length).toBeGreaterThan(5);
});
test("no lock site is missing from the declared set", () => {
const undeclared = lockCallers().filter((rel) => !DECLARED.has(rel));
expect(undeclared).toEqual([]);
});
test("every declared root is one the scan actually walks", () => {
const roots = lockScanRoots("/vault").map((abs) => abs.slice("/vault/".length));
for (const root of new Set(DECLARED.values())) {
expect(roots).toContain(root);
}
});
});
describe("acquireLockSyncWithRetry — the budget is a bound this module can honour", () => {
test.each([Number.NaN, Number.POSITIVE_INFINITY, -1, 1.5])(
"refuses budgetMs %p by name instead of waiting on it",
(budget) => {
const target = join(tmpRoot, "budget.json");
const held = acquireLockSync(target);
try {
expect(() => acquireLockSyncWithRetry(target, budget)).toThrow(
/budgetMs must be an integer >= 0/,
);
} finally {
held.release();
}
},
);
test("a zero budget is legal and means exactly one attempt", () => {
const target = join(tmpRoot, "zero-budget.json");
const held = acquireLockSync(target);
try {
const started = Date.now();
let caught: NodeJS.ErrnoException | null = null;
try {
acquireLockSyncWithRetry(target, 0);
} catch (err) {
caught = err as NodeJS.ErrnoException;
}
expect(caught?.code).toBe("ELOCKED");
expect(Date.now() - started).toBeLessThan(100);
} finally {
held.release();
}
});
});
/**
* The wait is a synchronous FREEZE of the whole thread. That is the cost
* the module's docblock states rather than argues away, and this is what
* pins it, in both halves: the freeze is total (no timer runs during it,
* so no progress event is emitted, no SIGINT handler runs, and inside the
* MCP server no other tool call proceeds), and it ends when the budget
* does rather than running on.
*/
describe("acquireLockSyncWithRetry — what the caller gives up while it waits", () => {
test("the wait freezes the event loop, and ends when the budget does", () => {
const target = join(tmpRoot, "frozen.json");
const held = acquireLockSync(target);
let ticks = 0;
const timer = setInterval(() => {
ticks++;
}, 10);
try {
const budget = 300;
const started = Date.now();
let caught: NodeJS.ErrnoException | null = null;
try {
acquireLockSyncWithRetry(target, budget);
} catch (err) {
caught = err as NodeJS.ErrnoException;
}
const elapsed = Date.now() - started;
expect(caught?.code).toBe("ELOCKED");
// Bounded: the wait ends at the budget, not at some multiple of it.
expect(elapsed).toBeGreaterThanOrEqual(budget);
expect(elapsed).toBeLessThan(budget + 500);
// Total: a 10 ms interval got no tick across 300 ms of waiting.
// If this ever reads non-zero the wait has become interruptible,
// and the docblock - not this expectation - is what should change
// first.
expect(ticks).toBe(0);
} finally {
clearInterval(timer);
held.release();
}
});
/**
* The budget is not one number for everyone: it is how long a caller is
* willing to freeze its process, which differs by what losing the race
* costs that caller. Pinned so neither number can drift into the other's
* job unnoticed - the default is the fan-out's, and the interactive one
* is strictly shorter.
*/
test("an interactive caller waits strictly less than the fan-out default", () => {
expect(LOCK_WAIT_INTERACTIVE_MS).toBeLessThan(LOCK_WAIT_BUDGET_MS);
// 1 s reproducibly fails the four-process manifest race, so the
// shorter budget is a refusal to freeze, not a second default.
expect(LOCK_WAIT_BUDGET_MS).toBeGreaterThanOrEqual(5_000);
});
test("the architect takes the interactive budget, not the default", () => {
const generate = readFileSync(
join(
resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."),
"src/core/brain/architect/generate.ts",
),
"utf8",
);
// An interactive pass with a progress stream and a Ctrl-C behind it
// must not park the terminal for the fan-out's budget.
expect(generate).toContain("acquireLockSyncWithRetry(dir, LOCK_WAIT_INTERACTIVE_MS)");
});
});
describe("removeStaleLockSync takeover claims", () => {
const abandoned = () => true;
function plantLock(name: string): { lock: string; claim: string } {
const lock = join(tmpRoot, `${name}.lock`);
writeFileSync(lock, "left behind by a killed holder\n");
const st = lstatSync(lock, { bigint: true });
return { lock, claim: `${lock}.takeover-${st.ino}-${st.mtimeNs}` };
}
function age(path: string, ms: number): void {
const at = (Date.now() - ms) / 1000;
utimesSync(path, at, at);
}
test("a fresh claim on the same lock file turns a late contender away", () => {
const { lock, claim } = plantLock("fresh-claim");
writeFileSync(claim, "");
expect(removeStaleLockSync(lock, abandoned)).toBe(false);
expect(existsSync(lock)).toBe(true);
});
test("a stale claim left by a dead winner does not make the lock unbreakable", () => {
const { lock, claim } = plantLock("dead-winner");
writeFileSync(claim, "");
age(claim, TAKEOVER_CLAIM_STALE_MS + 5_000);
expect(removeStaleLockSync(lock, abandoned)).toBe(true);
expect(existsSync(lock)).toBe(false);
});
test("a lock whose every claim generation is stale is cleared for the next attempt", () => {
const { lock, claim } = plantLock("exhausted");
const generations = [claim, `${claim}-1`, `${claim}-2`, `${claim}-3`];
for (const path of generations) {
writeFileSync(path, "");
age(path, TAKEOVER_CLAIM_STALE_MS + 5_000);
}
expect(removeStaleLockSync(lock, abandoned)).toBe(false);
expect(generations.some((path) => existsSync(path))).toBe(false);
expect(removeStaleLockSync(lock, abandoned)).toBe(true);
});
test("a successful takeover sweeps this lock's stale claims and keeps fresh ones", () => {
const { lock } = plantLock("sweep");
const oldClaim = `${lock}.takeover-1-2`;
const freshClaim = `${lock}.takeover-3-4`;
const otherLockClaim = join(tmpRoot, "other.lock.takeover-5-6");
for (const path of [oldClaim, freshClaim, otherLockClaim]) writeFileSync(path, "");
age(oldClaim, TAKEOVER_CLAIM_STALE_MS + 5_000);
age(otherLockClaim, TAKEOVER_CLAIM_STALE_MS + 5_000);
expect(removeStaleLockSync(lock, abandoned)).toBe(true);
expect(existsSync(oldClaim)).toBe(false);
expect(existsSync(freshClaim)).toBe(true);
expect(existsSync(otherLockClaim)).toBe(true);
});
});