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
4.1 KB
Raw Blame
/**
 * Expiring maintenance lease (write-time-integrity-governance,
 * t_166d1226). A tiny dedicated SQLite database in the vault-local
 * state dir - deliberately NOT brain.sqlite, so holding the lease
 * never contends with the search index writer lock - holds one row
 * per lease name. Acquisition is a single conditional upsert, so two
 * workers racing across processes cannot both win; a crashed worker's
 * lease frees itself by expiry, never by manual cleanup.
 */

import { Database } from "bun:sqlite";
import { mkdirSync } from "node:fs";
import { dirname } from "node:path";
import { closeDatabase } from "../../sqlite-close.ts";
import { DERIVED_STORE_DIR } from "../path-constants.ts";
import { machineStatePath } from "../../state/machine-state.ts";

export const MAINTENANCE_LEASE_NAME = "maintenance";

export interface AcquireLeaseOptions {
  readonly name?: string;
  readonly holder: string;
  readonly ttlMs: number;
  readonly now: Date;
}

export interface ReleaseLeaseOptions {
  readonly name?: string;
  readonly holder: string;
}

export interface LeaseState {
  readonly name: string;
  readonly holder: string;
  readonly expiresAt: string;
}

function leaseDbPath(vault: string): string {
  return machineStatePath(vault, DERIVED_STORE_DIR, "maintenance.sqlite");
}

function openLeaseDb(vault: string): Database {
  const path = leaseDbPath(vault);
  mkdirSync(dirname(path), { recursive: true });
  const db = new Database(path);
  db.exec("PRAGMA journal_mode = WAL");
  db.exec("PRAGMA busy_timeout = 5000");
  db.exec(
    "CREATE TABLE IF NOT EXISTS leases (" +
      "  name       TEXT PRIMARY KEY," +
      "  holder     TEXT NOT NULL," +
      "  expires_at TEXT NOT NULL" +
      ")",
  );
  return db;
}

/**
 * Try to take the lease. True when this holder now owns it - either
 * it was free, expired, or already ours (re-entrant renew).
 */
export function acquireLease(vault: string, opts: AcquireLeaseOptions): boolean {
  if (!Number.isFinite(opts.ttlMs) || opts.ttlMs <= 0) {
    // A non-positive TTL would mint an already-expired lease and every
    // contender would acquire at once - silent loss of mutual exclusion.
    throw new Error(`lease ttlMs must be a positive number, got ${opts.ttlMs}`);
  }
  const name = opts.name ?? MAINTENANCE_LEASE_NAME;
  const nowIso = opts.now.toISOString();
  const expiresAt = new Date(opts.now.getTime() + opts.ttlMs).toISOString();
  const db = openLeaseDb(vault);
  try {
    db.run(
      "INSERT INTO leases(name, holder, expires_at) VALUES (?, ?, ?) " +
        "ON CONFLICT(name) DO UPDATE SET holder = excluded.holder, expires_at = excluded.expires_at " +
        "WHERE leases.expires_at < ? OR leases.holder = excluded.holder",
      [name, opts.holder, expiresAt, nowIso],
    );
    const row = db
      .query<{ holder: string }, [string]>("SELECT holder FROM leases WHERE name = ?")
      .get(name);
    return row?.holder === opts.holder;
  } finally {
    closeDatabase(db);
  }
}

/** Release the lease; only the current holder may. */
export function releaseLease(vault: string, opts: ReleaseLeaseOptions): boolean {
  const name = opts.name ?? MAINTENANCE_LEASE_NAME;
  const db = openLeaseDb(vault);
  try {
    db.run("DELETE FROM leases WHERE name = ? AND holder = ?", [name, opts.holder]);
    const gone = db
      .query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM leases WHERE name = ?")
      .get(name);
    return (gone?.n ?? 0) === 0;
  } finally {
    closeDatabase(db);
  }
}

/** The live lease, or null when free or expired. */
export function currentLease(
  vault: string,
  opts: { readonly name?: string; readonly now?: Date } = {},
): LeaseState | null {
  const name = opts.name ?? MAINTENANCE_LEASE_NAME;
  const now = opts.now ?? new Date();
  const db = openLeaseDb(vault);
  try {
    const row = db
      .query<{ name: string; holder: string; expires_at: string }, [string]>(
        "SELECT name, holder, expires_at FROM leases WHERE name = ?",
      )
      .get(name);
    if (!row || row.expires_at < now.toISOString()) return null;
    return { name: row.name, holder: row.holder, expiresAt: row.expires_at };
  } finally {
    closeDatabase(db);
  }
}