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
5.9 KB
Raw Blame
/**
 * Device-local advisory lock for the brain store (design D2).
 *
 * Every lock the store takes lives in the device-local state directory,
 * never inside the synced store: a lock file that a sync tool copies to
 * another machine would either block that machine or be deleted under the
 * holder. The lock is held only for the short critical section it guards
 * (one shard append, one clock tick).
 *
 * Built on `proper-lockfile`'s directory lock, the same primitive the log
 * appender and the device-id generator use, because it recovers from a
 * crashed holder: a lock directory older than {@link STORE_LOCK_STALE_MS}
 * is taken over. The synchronous lock never refreshes its age while held,
 * so the window has to outlast any critical section a live holder can be
 * stuck in: one append and its fsync are milliseconds long, but a paused
 * VM, an antivirus scan or a stalled disk can hold one for many seconds,
 * and taking such a lock over would let two writers interleave in one
 * shard. Sixty seconds, the window the vault writer lock uses
 * (`brain/sync-lockfile.ts`). The directory form works the same on
 * Windows, where it needs no handle kept open.
 *
 * The wait is bounded by the shared lock budget
 * (`OPEN_SECOND_BRAIN_LOCK_WAIT_MS`, five seconds by default) and is a
 * blocking sleep, like every other synchronous lock in this tree.
 *
 * On Windows a released lock directory lingers in a "delete pending" state
 * until the last handle closes, and a `mkdir` of that name meanwhile fails
 * with `EPERM` instead of `EEXIST`. {@link isLockContention} counts that as
 * a held lock, so a writer that loses a race to a releasing holder waits
 * its turn instead of failing; the Brain log lock (`brain/log.ts`) shares
 * the rule.
 */

import { mkdirSync } from "node:fs";
import { dirname } from "node:path";

import lockfile from "proper-lockfile";

import { isWindowsDeletePending, resolveLockWaitBudgetMs } from "../brain/sync-lockfile.ts";
import { sleepSync } from "../fs-atomic.ts";

/** Age after which a lock directory counts as abandoned by a crashed holder. */
export const STORE_LOCK_STALE_MS = 60_000;

/** Upper bound of one sleep between attempts. */
const RETRY_SLEEP_MAX_MS = 20;

/**
 * Whether a failed `proper-lockfile` acquire of `lockTarget` means another
 * holder has the lock: `ELOCKED`, or on Windows an `EPERM`/`EACCES` while
 * the lock directory `<lockTarget>.lock` is still there (a release that
 * has not finished). An `EPERM` with nothing at the name is a directory
 * that refuses writes and stays an error. `platform` is a test seam.
 */
export function isLockContention(
  err: unknown,
  lockTarget: string,
  platform: NodeJS.Platform = process.platform,
): boolean {
  const e = err as NodeJS.ErrnoException;
  return e.code === "ELOCKED" || isWindowsDeletePending(e, `${lockTarget}.lock`, platform);
}

/** A Windows `EPERM`/`EACCES`, the code a lock create gets while a name is being deleted. */
export function isWindowsRefusal(
  err: unknown,
  platform: NodeJS.Platform = process.platform,
): boolean {
  const code = (err as NodeJS.ErrnoException).code;
  return platform === "win32" && (code === "EPERM" || code === "EACCES");
}

/** How {@link acquireDirLock} waits and what its refusal says. */
export interface DirLockOptions {
  /** Age after which the lock directory counts as abandoned. */
  readonly staleMs: number;
  /** Longest total wait before giving up with `ELOCKED`. */
  readonly budgetMs: number;
  /** What the refusal calls the lock ("store lock", "log lock"). */
  readonly label: string;
  /** What the refusal tells the operator to do next. */
  readonly remedy: string;
}

/**
 * Take the `proper-lockfile` directory lock of `lockTarget`
 * (`<lockTarget>.lock`), waiting with jittered, growing sleeps while it is
 * held, and return its release. Throws an `ELOCKED` error naming the
 * target when the lock stays held past the budget; any other failure is
 * rethrown as it is.
 */
export function acquireDirLock(lockTarget: string, options: DirLockOptions): () => void {
  const started = Date.now();
  let refusalRetried = false;
  for (let attempt = 0; ; attempt++) {
    try {
      return lockfile.lockSync(lockTarget, { stale: options.staleMs, realpath: false });
    } catch (err) {
      if (!isLockContention(err, lockTarget)) {
        // A Windows EPERM with nothing at the name is a refusing directory
        // or a release that finished between the mkdir and the check; one
        // more try tells them apart.
        if (refusalRetried || !isWindowsRefusal(err)) throw err;
        refusalRetried = true;
        continue;
      }
      if (Date.now() - started >= options.budgetMs) {
        const refused: NodeJS.ErrnoException = new Error(
          `${options.label} busy: ${lockTarget}: still held after waiting ` +
            `${Date.now() - started} ms; ${options.remedy}`,
          { cause: err },
        );
        refused.code = "ELOCKED";
        refused.path = lockTarget;
        throw refused;
      }
      // Jittered, growing sleep so waiters do not wake in lockstep.
      sleepSync(1 + Math.floor(Math.random() * Math.min(RETRY_SLEEP_MAX_MS, 2 + attempt * 2)));
    }
  }
}

/**
 * Run `fn` while holding the device-local lock named by `lockTarget` (a
 * path inside the device-local state directory; the lock directory is
 * `<lockTarget>.lock`). Throws an `ELOCKED` error naming the target when
 * the lock stays held past the wait budget.
 */
export function withLocalLock<T>(lockTarget: string, fn: () => T, budgetMs?: number): T {
  mkdirSync(dirname(lockTarget), { recursive: true });
  const release = acquireDirLock(lockTarget, {
    staleMs: STORE_LOCK_STALE_MS,
    budgetMs: budgetMs ?? resolveLockWaitBudgetMs(),
    label: "store lock",
    remedy:
      "retry once the other writer finishes, or allow a longer wait with " +
      "OPEN_SECOND_BRAIN_LOCK_WAIT_MS=<milliseconds>",
  });
  try {
    return fn();
  } finally {
    release();
  }
}