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
12.7 KB
Raw Blame
/**
 * The fleet freeze, read side: one marker file, honoured by every writer
 * on every device (who-wrote-what, Task C).
 *
 * An operator running several agents on several machines has no single
 * stop. Killing one process stops one process; a Syncthing peer that was
 * mid-pass keeps writing, and the vault the operator is trying to hold
 * still moves under them. The stop this module supplies is a FILE -
 * `Brain/.state/frozen.json` - because a file is the only thing every
 * device already agrees about: it rides the same sync channel the vault
 * does, so freezing on the laptop freezes the desktop as soon as the two
 * have talked, with nothing to install and no daemon to reach.
 *
 * ## Why this module imports almost nothing
 *
 * The freeze check runs inside `assertVaultIdentityForWrite`, which is
 * imported by `paths.ts`, which is imported by `log.ts`. So this module
 * must not reach any of the three: an edge back would close a cycle whose
 * cost is paid at module-initialisation time by every consumer in the
 * tree (`tests/core/architecture/import-cycles.test.ts` is the ratchet).
 * It therefore builds its own path from the leaf constants through the
 * machine-state resolver (`state/machine-state.ts`, which reaches none of
 * the three), and the `paths.ts` re-export is a convenience for callers
 * rather than the definition.
 *
 * Once this machine is switched to the store (design D14 item 13) the
 * marker is device-local: it lives in the device-local state, freezes
 * this machine only, and no longer rides the vault's sync channel.
 *
 * ## An unreadable marker is a freeze
 *
 * The asymmetry with {@link readVaultIdentity} is deliberate and is the
 * one judgement in this module. An absent identity marker collapses to
 * "unknown" because a fresh vault and a wrong root look identical. A
 * marker that is PRESENT and does not parse carries no such ambiguity of
 * intent: somebody put a file called `frozen.json` in the state directory,
 * and the only reading under which a parse error should reopen the vault
 * is one where a truncated sync is allowed to cancel an operator's stop.
 * So a marker that cannot be read freezes, and the refusal names
 * {@link FREEZE_MARKER_UNREADABLE_REASON} rather than inventing a reason
 * it did not read.
 *
 * ## The two lanes
 *
 * The freeze cannot cover literally every write, because the events that
 * record the freeze - `freeze`, `unfreeze`, `write-refused` - are
 * themselves writes into `Brain/log/`. A freeze that silenced its own
 * audit trail would make the one state an operator most needs to
 * reconstruct the least recorded. {@link WRITE_LANE} names that split
 * once: `content` is everything the freeze holds, `audit` is the log
 * appender and this feature's own marker writer. A source-scan test pins
 * that `audit` is requested from those modules and nowhere else, so the
 * exemption cannot spread by being convenient.
 */

import { existsSync, readFileSync, statSync } from "node:fs";
import { resolve } from "node:path";

import {
  machineStateLocation,
  machineStatePathIn,
  machineStateRoot,
} from "../state/machine-state.ts";
import {
  DEGRADATION_CODE,
  degradationNotice,
  formatDegradationNotice,
  type DegradationNotice,
} from "../integrity/degradation.ts";
import { BRAIN_INTERNAL_STATE_REL } from "./path-constants.ts";

/** Marker schema version. Bumped only on an incompatible field change. */
export const FREEZE_MARKER_SCHEMA_VERSION = 1;

/** Marker filename inside `Brain/.state/`. */
export const FROZEN_MARKER_FILE = "frozen.json";

/** Site name carried by every notice this module emits. */
const SITE = "brain.freeze";

/**
 * The one command that ends a freeze, spelled once.
 *
 * Every refusal carries it - the thrown error, the MCP refusal payload,
 * the doctor finding - because a stop with no named way out is a dead end
 * for whoever hits it, including the operator who set it.
 */
export const FREEZE_NEXT_COMMAND = "o2b brain unfreeze";

/**
 * The reason reported when the marker is present and could not be read.
 * See the module docblock for why that is a freeze and not an absence.
 */
export const FREEZE_MARKER_UNREADABLE_REASON = "marker-unreadable";

/**
 * Which half of the write surface a caller belongs to.
 *
 * `content` is everything the freeze exists to hold: notes, preferences,
 * signals, state, snapshots - every byte an agent or a pass produces.
 * `audit` is the record of what happened, which has to keep working while
 * the vault is frozen or the freeze erases its own evidence.
 */
export const WRITE_LANE = Object.freeze({
  content: "content",
  audit: "audit",
} as const);

export type WriteLane = (typeof WRITE_LANE)[keyof typeof WRITE_LANE];

/**
 * The durable freeze record. Like the identity marker it carries nothing
 * machine-local except `device_id`, which names the device that SET the
 * freeze rather than a path - so the file is byte-identical on every peer
 * and means the same thing on each of them.
 */
export interface FreezeMarker {
  readonly schema: number;
  /** When the freeze was set, ISO-8601 UTC. */
  readonly frozen_at: string;
  /** Agent identity that set it, as `resolveAgentName` reports it. */
  readonly by: string;
  /** Device that set it, or the empty string when unresolvable. */
  readonly device_id: string;
  /** Operator-supplied reason, or the empty string when none was given. */
  readonly reason: string;
}

/**
 * Path of the freeze marker: `<vault>/Brain/.state/frozen.json`, or the
 * same path under the device-local state once this machine is switched
 * (design D14 item 13: the freeze marker is device-local and no longer
 * rides the vault's sync channel).
 */
export function frozenMarkerPath(vault: string): string {
  return markerPathIn(machineStateRoot(vault));
}

/** The freeze marker below a machine-state root already resolved. */
function markerPathIn(root: string): string {
  return machineStatePathIn(root, BRAIN_INTERNAL_STATE_REL, FROZEN_MARKER_FILE);
}

/**
 * A write was attempted against a frozen vault.
 *
 * Carries the marker's fields beside the structured notice so a caller -
 * the MCP boundary, a CLI verb, an internal writer - reports the evidence
 * rather than re-parsing the message. The shape mirrors
 * `VaultIdentityMismatchError`, which is the other refusal this guard can
 * raise, so both are handled the same way at a call site.
 */
export class VaultFrozenError extends Error {
  readonly notice: DegradationNotice;
  readonly frozen_at: string;
  readonly by: string;
  readonly reason: string;
  readonly next_command: string;

  constructor(notice: DegradationNotice, marker: FreezeMarker) {
    super(formatDegradationNotice(notice));
    this.name = "VaultFrozenError";
    this.notice = notice;
    this.frozen_at = marker.frozen_at;
    this.by = marker.by;
    this.reason = marker.reason;
    this.next_command = FREEZE_NEXT_COMMAND;
  }
}

/** The marker every present-but-unparseable file collapses to. */
const UNREADABLE_MARKER: FreezeMarker = Object.freeze({
  schema: FREEZE_MARKER_SCHEMA_VERSION,
  frozen_at: "",
  by: "",
  device_id: "",
  reason: FREEZE_MARKER_UNREADABLE_REASON,
});

/**
 * Inode identity of the marker the last read parsed, per resolved root.
 *
 * The check sits in front of every content write - the same
 * append-heavy loops `vault-identity.ts` measures - so the steady-state
 * cost has to be one syscall rather than an open-read-parse. The marker
 * is written through `atomicWriteFileSync` (temp file plus rename), so a
 * replaced marker always arrives with a new inode; matching on
 * (inode, size, mtime) therefore proves the bytes are the ones already
 * parsed.
 */
interface MarkerStamp {
  readonly ino: number;
  readonly size: number;
  readonly mtimeMs: number;
  readonly marker: FreezeMarker;
}
const MARKER_STAMPS = new Map<string, MarkerStamp>();

/**
 * Resolved marker path per root, kept only once it is the device-local
 * one: a switch is sticky, so that answer holds for the process, while an
 * unswitched machine resolves again on every read (another process may
 * switch it, and the marker then lives in the device-local state).
 */
const MARKER_PATHS = new Map<string, string>();

/**
 * How many times the marker's BYTES have been read and parsed, process
 * wide.
 *
 * Exported for the cache test, which is the only place the hot-path claim
 * in the docblock above is actually measured. A counter rather than a
 * spy: the alternative is monkey-patching `node:fs` in a test, which
 * pins the implementation instead of the property.
 */
let reloadCount = 0;

export function freezeMarkerReloadCount(): number {
  return reloadCount;
}

/**
 * Drop every cached marker. Exported for tests, which run many vaults in
 * one process; production code has no reason to call it.
 */
export function resetFreezeMarkerCache(): void {
  MARKER_STAMPS.clear();
  MARKER_PATHS.clear();
}

/** Parse the marker's bytes, or report the unreadable collapse. */
function parseMarker(path: string): FreezeMarker {
  reloadCount += 1;
  let parsed: Partial<FreezeMarker>;
  try {
    parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<FreezeMarker>;
  } catch {
    return UNREADABLE_MARKER;
  }
  if (parsed === null || typeof parsed !== "object") return UNREADABLE_MARKER;
  // `frozen_at` is the one field a freeze cannot be reconstructed without:
  // a refusal that cannot say WHEN the vault was stopped is not a record,
  // it is a wall. Its absence therefore reads as unreadable rather than as
  // a freeze with an empty timestamp.
  if (typeof parsed.frozen_at !== "string" || parsed.frozen_at === "") return UNREADABLE_MARKER;
  return Object.freeze({
    schema: typeof parsed.schema === "number" ? parsed.schema : FREEZE_MARKER_SCHEMA_VERSION,
    frozen_at: parsed.frozen_at,
    by: typeof parsed.by === "string" ? parsed.by : "",
    device_id: typeof parsed.device_id === "string" ? parsed.device_id : "",
    reason: typeof parsed.reason === "string" ? parsed.reason : "",
  });
}

/**
 * The freeze marker for `vault`, or `null` when the vault is not frozen.
 *
 * A present-but-unparseable marker returns {@link UNREADABLE_MARKER} -
 * that is, a freeze - never `null`.
 */
export function readFreezeMarker(vault: string): FreezeMarker | null {
  const root = resolve(vault);
  let path = MARKER_PATHS.get(root);
  if (path === undefined) {
    // Only a relocated path is cached: a switch never goes back without a
    // rollback, while an unswitched answer can change under this process
    // (another process switches the machine), and the guarded write
    // resolves the mode for itself anyway.
    const location = machineStateLocation(root);
    path = markerPathIn(location.root);
    if (location.relocated) MARKER_PATHS.set(root, path);
  }
  // `throwIfNoEntry: false` for the same reason `currentVaultId` uses it:
  // an absent marker is the steady state, and the throwing form built and
  // discarded one Error, with its stack, per guarded write. The `catch`
  // stays because the option suppresses ENOENT only and every other stat
  // failure (EACCES, ELOOP) must not propagate out of a write guard.
  let stat;
  try {
    stat = statSync(path, { throwIfNoEntry: false });
  } catch {
    stat = undefined;
  }
  if (stat === undefined) {
    MARKER_STAMPS.delete(root);
    return null;
  }
  const cached = MARKER_STAMPS.get(root);
  if (
    cached !== undefined &&
    cached.ino === stat.ino &&
    cached.size === stat.size &&
    cached.mtimeMs === stat.mtimeMs
  ) {
    return cached.marker;
  }
  const marker = parseMarker(path);
  MARKER_STAMPS.set(root, {
    ino: stat.ino,
    size: stat.size,
    mtimeMs: stat.mtimeMs,
    marker,
  });
  return marker;
}

/** Whether the marker file exists at all, uncached. For the writer only. */
export function freezeMarkerExists(vault: string): boolean {
  return existsSync(frozenMarkerPath(vault));
}

/** The `vault-frozen` notice for `marker`, worded once. */
export function vaultFrozenNotice(vault: string, marker: FreezeMarker): DegradationNotice {
  const why = marker.reason === "" ? "no reason given" : marker.reason;
  return degradationNotice({
    code: DEGRADATION_CODE.vaultFrozen,
    site: SITE,
    path: resolve(vault),
    detail:
      `refusing to write: this vault was frozen at ${marker.frozen_at} by ` +
      `${marker.by === "" ? "an unnamed agent" : marker.by} (${why}). ` +
      `Run \`${FREEZE_NEXT_COMMAND}\` to lift it`,
  });
}

/**
 * Assert that the content lane may write to `vault`.
 *
 * Throws {@link VaultFrozenError} while the marker is present, including
 * when it is present and unreadable. Returns silently otherwise; it never
 * writes, creates, or repairs anything.
 */
export function assertVaultNotFrozen(vault: string): void {
  const marker = readFreezeMarker(vault);
  if (marker === null) return;
  throw new VaultFrozenError(vaultFrozenNotice(vault, marker), marker);
}