Skip to content

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
21.2 KB
Raw Blame
/**
 * 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);
  });
});