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
8.0 KB
Raw Blame
/**
 * The waiting lock's fairness, its budget override and what a refusal tells
 * the operator (issue #198).
 *
 * The wait loop used to be unfair in one specific way: a writer that
 * released a lock and came straight back for it re-created the lock file
 * before any sleeping waiter woke, so under a steady stream of writes one
 * waiter could lose every draw for the whole budget and be refused on a
 * perfectly healthy race. A waiter now marks the held lock file, and a
 * holder that releases a marked lock steps back before it re-acquires.
 */

import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
  existsSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  statSync,
  symlinkSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { manifestPath, updateManifest } from "../../../src/core/brain/ingest/content-manifest.ts";
import {
  acquireLockSync,
  acquireLockSyncWithRetry,
  LOCK_WAIT_BUDGET_ENV,
  LOCK_WAIT_BUDGET_MS,
  resolveLockWaitBudgetMs,
} 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 root: string;
let savedEnv: string | undefined;

beforeEach(() => {
  root = mkdtempSync(join(tmpdir(), "o2b-lock-fair-"));
  savedEnv = process.env[LOCK_WAIT_BUDGET_ENV];
  delete process.env[LOCK_WAIT_BUDGET_ENV];
});

afterEach(() => {
  if (savedEnv === undefined) delete process.env[LOCK_WAIT_BUDGET_ENV];
  else process.env[LOCK_WAIT_BUDGET_ENV] = savedEnv;
  rmSync(root, { recursive: true, force: true });
});

/** Refusal raised by `fn`, or a failed expectation if it did not throw. */
function refusal(fn: () => unknown): NodeJS.ErrnoException {
  try {
    fn();
  } catch (err) {
    return err as NodeJS.ErrnoException;
  }
  throw new Error("expected a lock refusal, got none");
}

describe("resolveLockWaitBudgetMs — the environment override", () => {
  test("unset or blank means the built-in default", () => {
    expect(resolveLockWaitBudgetMs({})).toBe(LOCK_WAIT_BUDGET_MS);
    expect(resolveLockWaitBudgetMs({ [LOCK_WAIT_BUDGET_ENV]: "  " })).toBe(LOCK_WAIT_BUDGET_MS);
  });

  test.each([
    ["20000", 20_000],
    [" 750 ", 750],
    ["0", 0],
  ])("%p is a budget of %p ms", (raw, expected) => {
    expect(resolveLockWaitBudgetMs({ [LOCK_WAIT_BUDGET_ENV]: raw })).toBe(expected);
  });

  test.each(["5s", "-1", "1.5", "NaN", "Infinity", "1e400"])(
    "%p is refused by name rather than replaced with the default",
    (raw) => {
      expect(() => resolveLockWaitBudgetMs({ [LOCK_WAIT_BUDGET_ENV]: raw })).toThrow(
        LOCK_WAIT_BUDGET_ENV,
      );
    },
  );

  test("a caller that passes no budget waits for the override, not the default", () => {
    const target = join(root, "override.json");
    const held = acquireLockSync(target);
    try {
      process.env[LOCK_WAIT_BUDGET_ENV] = "60";
      const started = Date.now();
      const err = refusal(() => acquireLockSyncWithRetry(target));
      expect(err.code).toBe("ELOCKED");
      expect(Date.now() - started).toBeLessThan(LOCK_WAIT_BUDGET_MS / 2);
    } finally {
      held.release();
    }
  });
});

describe("acquireLockSyncWithRetry — a refusal says what to do next", () => {
  test("names the lock, the wait, the retry and the override", () => {
    const target = join(root, "remedy.json");
    const held = acquireLockSync(target);
    try {
      process.env[LOCK_WAIT_BUDGET_ENV] = "40";
      const err = refusal(() => acquireLockSyncWithRetry(target));
      expect(err.code).toBe("ELOCKED");
      expect(err.path).toBe(`${target}.lock`);
      expect(err.message).toContain(`lock busy: ${target}.lock`);
      expect(err.message).toMatch(/after waiting \d+ ms/);
      expect(err.message).toContain("retry");
      expect(err.message).toContain(`${LOCK_WAIT_BUDGET_ENV}`);
      // The original single-attempt collision stays reachable.
      expect((err.cause as NodeJS.ErrnoException).code).toBe("ELOCKED");
    } finally {
      held.release();
    }
  });

  test("an explicit short budget does not point at the override it ignores", () => {
    const target = join(root, "interactive.json");
    const held = acquireLockSync(target);
    try {
      const err = refusal(() => acquireLockSyncWithRetry(target, 30));
      expect(err.message).toContain("retry");
      expect(err.message).not.toContain(LOCK_WAIT_BUDGET_ENV);
    } finally {
      held.release();
    }
  });

  test("a refused ingest write tells the operator to retry, serialize or wait longer", () => {
    const vault = root;
    writeFileSync(join(vault, "source.md"), "body", "utf8");
    const manifestLock = acquireLockSync(manifestPath(vault));
    try {
      process.env[LOCK_WAIT_BUDGET_ENV] = "40";
      const err = refusal(() => updateManifest(vault, ["source.md"]));
      expect(err.code).toBe("ELOCKED");
      expect(err.message).toContain("lock busy");
      expect(err.message).toContain("retry the ingest");
      expect(err.message).toContain("one at a time");
      expect(err.message).toContain(LOCK_WAIT_BUDGET_ENV);
    } finally {
      manifestLock.release();
    }
  });
});

describe("acquireLockSyncWithRetry — a waiter is not starved by a returning holder", () => {
  test("a holder that releases a lock someone waits on hands it over before re-acquiring", async () => {
    const target = join(root, "handoff.json");
    const lockPath = `${target}.lock`;
    const marker = join(root, "waiter-acquired");
    const child = join(root, "waiter.ts");
    writeFileSync(
      child,
      [
        `import { acquireLockSyncWithRetry } from ${JSON.stringify(join(import.meta.dir, "../../../src/core/brain/sync-lockfile.ts"))};`,
        "const [target, marker] = process.argv.slice(2);",
        "const h = acquireLockSyncWithRetry(target, 20000);",
        `require("node:fs").writeFileSync(marker, String(Date.now()));`,
        "Bun.sleepSync(50);",
        "h.release();",
      ].join("\n"),
      "utf8",
    );

    let held = acquireLockSync(target);
    const baseSize = statSync(lockPath).size;
    const proc = Bun.spawn(["bun", child, target, marker], {
      stdout: "pipe",
      stderr: "pipe",
      env: { ...process.env },
    });
    try {
      // Wait until the child has failed at least one draw and marked the lock.
      const until = Date.now() + 20_000;
      while (statSync(lockPath).size <= baseSize) {
        if (Date.now() > until) throw new Error("the waiter never marked the held lock");
        // oxlint-disable-next-line no-await-in-loop -- polling the child's progress, one wait at a time by design
        await Bun.sleep(5);
      }
      // Release and come straight back, as a writer in a loop does. Without
      // the hand-over this re-acquire wins before the sleeping waiter wakes.
      held.release();
      held = acquireLockSyncWithRetry(target);
      expect(existsSync(marker)).toBe(true);
    } finally {
      held.release();
      const code = await proc.exited;
      const err = await new Response(proc.stderr).text();
      expect(`${code} ${err.trim()}`).toBe("0 ");
    }
  }, 60_000);

  test.skipIf(process.platform === "win32")(
    "a waiter's mark never writes through a symlink planted at the lock path",
    () => {
      const victim = join(root, "victim.txt");
      writeFileSync(victim, "unchanged", "utf8");
      const target = join(root, "planted.json");
      symlinkSync(victim, `${target}.lock`);
      const err = refusal(() => acquireLockSyncWithRetry(target, 60));
      expect(err.code).toBe("ELOCKED");
      expect(readFileSync(victim, "utf8")).toBe("unchanged");
    },
  );

  test("an uncontended writer in a loop does not pay the hand-over pause", () => {
    const target = join(root, "loop.json");
    const rounds = 40;
    const started = Date.now();
    for (let i = 0; i < rounds; i++) acquireLockSyncWithRetry(target).release();
    // A pause on every round would cost at least rounds x 50 ms.
    expect(Date.now() - started).toBeLessThan(rounds * 25);
  });
});