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
22.4 KB
Raw Blame
/**
 * Unified operator status snapshot (Source pipeline integrity suite, O3,
 * t_9f9c5466).
 *
 * One read-only composition of the signal sources an operator otherwise
 * has to poll one command at a time - doctor, semantic health, hygiene,
 * stale scan, review candidates, active profile, and state-file health -
 * into a single readable snapshot. Every problem line carries the exact
 * next command to run, and that command is looked up from the O2
 * diagnostics-signal registry ({@link resolveSignal}), never hardcoded in
 * the renderer: a hint has exactly one home, the issue definition.
 *
 * Reads only. Each source is wrapped fail-soft so one broken surface
 * (an unreadable index, a malformed config) degrades that line rather
 * than sinking the whole snapshot.
 */

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

import { resolveSearchConfig } from "../search/index.ts";
import { isWriterLockHeld } from "../search/store/writer-lock.ts";
import { FREEZE_NEXT_COMMAND, readFreezeMarker, type FreezeMarker } from "./freeze-marker.ts";
import { runDoctor } from "./doctor.ts";
import { resolveSignal } from "./diagnostics.ts";
import {
  describeSelfHealUpgradeFailure,
  readSelfHealUpgradeFailure,
  type SelfHealUpgradeFailure,
} from "../maintenance/self-heal-upgrade-state.ts";
import { runHygieneScan } from "./hygiene/scan.ts";
import type { HygieneFinding } from "./hygiene/types.ts";
import { memoryFromStore, storePagesIn } from "./memory-pages.ts";
import { brainConfigPath, brainDirsOf, brainManualPath, vaultRelative } from "./paths.ts";
import { loadTemporalConfigSafe } from "./policy.ts";
import { listProfiles } from "./portability/profiles.ts";
import { buildReviewCandidates } from "./review-candidates.ts";
import { describeManualRevisionAhead, manualRevisionAhead } from "./templates.ts";
import { buildTimelineIndex } from "./temporal/build-index.ts";
import { findStaleEntries } from "./temporal/stale-watch.ts";

/** One problem line: an issue class, its summary, and the next command. */
export interface SnapshotProblem {
  /** Diagnostics-signal code driving the next-command lookup. */
  readonly code: string;
  /** Human label for the issue class (from the signal definition). */
  readonly label: string;
  /** One-line summary (counts / verdict) of the finding. */
  readonly detail: string;
  /** Exact next command to run (from the signal definition). */
  readonly nextCommand: string;
}

export interface SnapshotCounts {
  readonly preferences: number;
  readonly retired: number;
  readonly inbox: number;
}

/**
 * The three honest answers about the search writer lock. `unknown` is
 * "I could not find out" - a stat that failed, a config that would not
 * resolve - and is deliberately NOT a spelling of `free`: a caller that
 * treats the second as the first has been told something untrue (the same
 * rule `isWriterLockHeld` itself states).
 */
export const WRITER_LOCK_STATE = Object.freeze({
  /** A live writer holds the lock right now. */
  held: "held",
  /** No live holder at the instant of the read. */
  free: "free",
  /** The state could not be measured; `writerLockReason` says what stopped it. */
  unknown: "unknown",
} as const);

/** Closed union over {@link WRITER_LOCK_STATE}. */
export type WriterLockState = (typeof WRITER_LOCK_STATE)[keyof typeof WRITER_LOCK_STATE];

/**
 * What this surface states about the memory store (t_cfe2ce5d).
 *
 * Scoped v1 to the SEARCH writer lock - the one `isWriterLockHeld`
 * answers. The scattered brain-lane `.lock` files stay with the doctor's
 * stale-lock probe; this group must not be read as covering both lock
 * families.
 *
 * `writerLockOwner` is `null` ALWAYS in v1, and that is a measurement
 * rather than a gap: the lock is a bare `proper-lockfile` directory whose
 * only metadata is its mtime, refreshed by a heartbeat. It answers "is
 * someone alive holding this"; it cannot answer "who". Naming a holder is
 * a deferred acquire-side change (stamping identity inside the lock
 * directory), not a field this snapshot can honestly fill today.
 *
 * A held lock is a live writer, not a fault: it is reported, never folded
 * into `healthy` or `problems` - the `frozen` precedent. Crash residue is
 * the doctor's `stale-lock` uncertain finding, which owns the "is this
 * holder actually dead" question.
 */
export interface SnapshotStore {
  /** Three-state answer about the search writer lock, fail-soft. */
  readonly writerLock: WriterLockState;
  /** Set when `unknown`: what stopped the measurement, errno included. */
  readonly writerLockReason: string | null;
  /**
   * Age of the lock directory's mtime when `held`, in milliseconds, from
   * the snapshot clock; `null` when free, unknown, or unmeasurable. The
   * heartbeat refreshes the mtime, so this is a lower bound on how long
   * the holder has been alive, never an upper bound.
   */
  readonly writerLockAgeMs: number | null;
  /** `null` in v1 - the lock record carries no identity. See above. */
  readonly writerLockOwner: string | null;
  /**
   * The lock path (the resolved search index path) at LOCAL reach;
   * `null` elsewhere. The path is a resolved host path that may sit
   * outside the vault, so the MCP surface withholds it below local reach
   * exactly the way `stateFiles.searchIndex` answers presence without it.
   */
  readonly writerLockPath: string | null;
  /**
   * This snapshot never writes and never takes the lock. The consequence
   * is rendered beside the flag, SCOPED TO WHAT THE LOCK GATES: while
   * `writerLock` is `held`, an index write THIS caller attempted - `o2b
   * search index` / reindex - would refuse with `INDEX_LOCKED` after its
   * retries. This is the search writer lock, and it gates index writers
   * only: vault and memory writes serialize on the brain lane's own lock
   * files, not on this one, so the rendered line says they are not gated
   * rather than implying a refusal this lock cannot cause.
   */
  readonly thisCaller: typeof THIS_CALLER_READ_ONLY;
}

/** The one value `thisCaller` can honestly take: this surface writes nothing. */
export const THIS_CALLER_READ_ONLY = "read-only";

export interface OperatorSnapshot {
  readonly counts: SnapshotCounts;
  /** stale preferences + signals + log files. */
  readonly staleTotal: number;
  /** would_create + would_promote + would_retire from the dry-run dream. */
  readonly reviewQueue: number;
  /** Active profile name, or null when none is set. */
  readonly activeProfile: string | null;
  /** Presence of the two on-disk state files that back the vault. */
  readonly stateFiles: {
    readonly config: boolean;
    readonly searchIndex: boolean;
  };
  /** Semantic-health verdict (clean | watch | investigate). */
  readonly healthVerdict: string;
  /** Every problem line, each carrying its next command. */
  readonly problems: ReadonlyArray<SnapshotProblem>;
  /** True when there are no problem lines. */
  readonly healthy: boolean;
  /**
   * The fleet freeze, or `null` when the vault is open (who-wrote-what,
   * Task C).
   *
   * Reported here rather than only as a doctor finding because "why is
   * nothing writing" is the first question a freeze raises, and the
   * operator snapshot is the surface that answers first questions. It is
   * NOT folded into {@link healthy}: a freeze is a state an operator
   * asked for, and calling it a problem would report an instruction as a
   * fault. The doctor names it as a warning, which is where a standing
   * condition belongs.
   */
  readonly frozen: FreezeMarker | null;
  /**
   * The last failure of the automatic managed-file upgrade on this device,
   * or `null` when none is recorded. It is also a problem line: a failed
   * self-heal leaves a pending upgrade behind and nothing else says so.
   */
  readonly selfHealUpgradeFailure: SelfHealUpgradeFailure | null;
  /**
   * What this snapshot can honestly state about the memory store: the
   * search writer lock's three-state answer, its age, the absence of any
   * owner identity on the lock record, and this caller's own read-only
   * standing. See {@link SnapshotStore}.
   */
  readonly store: SnapshotStore;
}

export interface BuildOperatorSnapshotOptions {
  /** Config path for the search-index and profile lookups. */
  readonly configPath?: string;
  /** Wall clock for stale/review scans. Defaults to `new Date()`. */
  readonly now?: Date;
  /**
   * May the caller read the vault file at this vault-relative path? Handed
   * to the hygiene scan (see `HygieneDetectorContext.readable`); a local
   * caller passes nothing.
   */
  readonly readable?: (rel: string) => boolean;
  /**
   * Does the caller see this finding? The hygiene problem line counts only
   * the findings it keeps, so the count matches what `brain_hygiene`
   * would list for the same caller rather than the whole vault's: a count
   * over the unfiltered set would move with a page the caller may not
   * read. A local caller passes nothing.
   */
  readonly keepFinding?: (finding: HygieneFinding) => boolean;
  /**
   * Whether the search writer lock is held at this index path. Injected
   * only by tests - the product asks `isWriterLockHeld`, and a throw from
   * it reads `unknown` rather than `free`, exactly as that module's
   * contract requires. Named after `MigrationPlanInput.writerLockHeldAt`,
   * so the two seams read as one pattern.
   */
  readonly writerLockHeldAt?: (dbPath: string) => boolean;
  /**
   * The caller is below local reach: the stale scan's timeline and the
   * doctor pass leave out the log events of the store's `private`
   * partition. Default false.
   */
  readonly withholdsPrivate?: boolean;
}

/**
 * Compose the operator snapshot. Async because the review-candidates
 * source runs a dry-run dream (read-only). Never mutates the vault.
 */
export async function buildOperatorSnapshot(
  vault: string | null,
  opts: BuildOperatorSnapshotOptions = {},
): Promise<OperatorSnapshot> {
  const now = opts.now ?? new Date();
  const problems: SnapshotProblem[] = [];
  const problem = (code: string, detail: string): void => {
    const sig = resolveSignal(code);
    problems.push({ code, label: sig.issueClass, detail, nextCommand: sig.nextCommand });
  };

  // --- State-file health ---
  // With no vault (design D14) the brain settings are store records with
  // shipped defaults, so there is no settings file to miss.
  const configPresent = vault === null || existsSync(brainConfigPath(vault));
  let searchDbPath: string | null = null;
  try {
    searchDbPath = resolveSearchConfig({ vault, configPath: opts.configPath ?? undefined }).dbPath;
  } catch {
    searchDbPath = null;
  }
  const searchIndexPresent = searchDbPath !== null && existsSync(searchDbPath);
  if (!configPresent) {
    problem("state-file", "Brain config `_brain.yaml` is missing");
  }

  // --- Store ownership (t_cfe2ce5d) ---
  const store = readStoreGroup(searchDbPath, now, opts.writerLockHeldAt);

  // --- Automatic upgrade ---
  // Both read files a vault's upgrade writes; with no vault there are none.
  const selfHealUpgradeFailure = vault === null ? null : readSelfHealUpgradeFailure(vault);
  if (selfHealUpgradeFailure !== null) {
    problem("self-heal-upgrade-failed", describeSelfHealUpgradeFailure(selfHealUpgradeFailure));
  }
  const manualAhead = vault === null ? null : readManualRevisionAhead(vault);
  if (manualAhead !== null && vault !== null) {
    problem(
      "managed-file-from-newer-release",
      `${describeManualRevisionAhead(vaultRelative(brainManualPath(vault), vault), manualAhead)}; ` +
        "update Open Second Brain on this device",
    );
  }

  // --- Doctor + semantic health ---
  let healthVerdict = "clean";
  try {
    // Thread the resolved search DB path so DB-backed findings (e.g.
    // tier-drift) are included rather than silently skipped.
    const doctor = runDoctor(vault, {
      now,
      ...(searchDbPath !== null ? { dbPath: searchDbPath } : {}),
      ...(opts.withholdsPrivate === true ? { withholdsPrivate: true } : {}),
    });
    if (doctor.errors.length > 0) {
      problem("doctor-errors", `${doctor.errors.length} invariant error(s)`);
    }
    if (doctor.warnings.length > 0) {
      problem("doctor-warnings", `${doctor.warnings.length} warning(s)`);
    }
    const verdict = doctor.semantic_health?.verdict;
    if (verdict !== undefined) healthVerdict = verdict;
    if (verdict !== undefined && verdict !== "clean") {
      problem("semantic-health", `semantic-health verdict: ${verdict}`);
    }
  } catch {
    // A failed probe must degrade the snapshot, never read as all-clear.
    problem("doctor-errors", "doctor probe failed to run");
  }

  // --- Hygiene ---
  // The hygiene and stale scans walk vault notes. With no vault they are
  // not run (design D14): the snapshot says so below rather than reading
  // as a clean scan.
  if (vault !== null) {
    try {
      const hy = runHygieneScan(vault, {
        now,
        ...(opts.readable !== undefined ? { readable: opts.readable } : {}),
      });
      const keepFinding = opts.keepFinding;
      const findings =
        keepFinding === undefined ? hy.findings : hy.findings.filter((f) => keepFinding(f));
      if (findings.length > 0) {
        problem("hygiene-findings", `${findings.length} hygiene finding(s)`);
      }
    } catch {
      problem("hygiene-findings", "hygiene scan failed to run");
    }
  }

  // --- Stale scan ---
  let staleTotal = 0;
  if (vault !== null) {
    try {
      const cfg = loadTemporalConfigSafe(vault);
      const index = buildTimelineIndex(vault, { withholdsPrivate: opts.withholdsPrivate === true });
      const stale = findStaleEntries(index, vault, cfg, { now });
      staleTotal =
        stale.stalePreferences.length + stale.staleSignals.length + stale.staleLogFiles.length;
      if (staleTotal > 0) {
        problem("stale-notes", `${staleTotal} stale entr${staleTotal === 1 ? "y" : "ies"}`);
      }
    } catch {
      problem("stale-notes", "stale scan failed to run");
    }
  }

  // --- Review candidates (dry-run dream) ---
  let reviewQueue = 0;
  try {
    const review = await buildReviewCandidates(vault, { now });
    reviewQueue =
      review.would_create.length + review.would_promote.length + review.would_retire.length;
    if (reviewQueue > 0) {
      problem("review-queue", `${reviewQueue} review candidate(s) pending`);
    }
  } catch {
    problem("review-queue", "review-candidate scan failed to run");
  }

  // --- Active profile (informational) ---
  let activeProfile: string | null = null;
  if (opts.configPath !== undefined) {
    try {
      activeProfile = listProfiles(opts.configPath).active;
    } catch {
      activeProfile = null;
    }
  }

  return Object.freeze({
    counts: Object.freeze({
      preferences: countMarkdown(vault, brainDirsOf(vault).preferences),
      retired: countMarkdown(vault, brainDirsOf(vault).retired),
      inbox: countMarkdown(vault, brainDirsOf(vault).inbox),
    }),
    staleTotal,
    reviewQueue,
    activeProfile,
    stateFiles: Object.freeze({ config: configPresent, searchIndex: searchIndexPresent }),
    healthVerdict,
    problems: Object.freeze(problems),
    healthy: problems.length === 0,
    frozen: vault === null ? null : readFreezeMarker(vault),
    selfHealUpgradeFailure,
    store,
  });
}

/**
 * Ask the search writer lock its three-state answer, wrapped fail-soft
 * exactly like the migration preflight's `writerLockRefusal`: a probe
 * that throws reads `unknown` with the errno in the reason, because
 * "I could not find out" is not "the lock is free". An index path that
 * never resolved is the same honest state - the lock could not be probed
 * at all - so it reads `unknown` too, with the reason naming that.
 */
function readStoreGroup(
  dbPath: string | null,
  now: Date,
  probe: ((dbPath: string) => boolean) | undefined,
): SnapshotStore {
  if (dbPath === null) {
    return Object.freeze({
      writerLock: WRITER_LOCK_STATE.unknown,
      writerLockReason: "the search index path could not be resolved, so the lock was not probed",
      writerLockAgeMs: null,
      writerLockOwner: null,
      writerLockPath: null,
      thisCaller: THIS_CALLER_READ_ONLY,
    });
  }
  let held: boolean;
  try {
    held = (probe ?? isWriterLockHeld)(dbPath);
  } catch (error) {
    const err = error as NodeJS.ErrnoException;
    return Object.freeze({
      writerLock: WRITER_LOCK_STATE.unknown,
      writerLockReason: `the writer lock state could not be determined (${err.code ?? "unknown error"}): ${err.message}`,
      writerLockAgeMs: null,
      writerLockOwner: null,
      writerLockPath: dbPath,
      thisCaller: THIS_CALLER_READ_ONLY,
    });
  }
  return Object.freeze({
    writerLock: held ? WRITER_LOCK_STATE.held : WRITER_LOCK_STATE.free,
    writerLockReason: null,
    writerLockAgeMs: held ? lockAgeMs(dbPath, now) : null,
    writerLockOwner: null,
    writerLockPath: dbPath,
    thisCaller: THIS_CALLER_READ_ONLY,
  });
}

/**
 * The held lock's mtime age against the snapshot clock, or `null` when the
 * stat fails - a best-effort measurement beside a state that is already
 * known, never a second chance to claim a state that is not.
 */
function lockAgeMs(dbPath: string, now: Date): number | null {
  try {
    return Math.max(0, Math.round(now.getTime() - statSync(writerLockDir(dbPath)).mtimeMs));
  } catch {
    return null;
  }
}

/**
 * The writer lock directory for an index path: a bare `${dbPath}.lock`
 * directory whose only metadata is its mtime (the `proper-lockfile` on-disk
 * protocol, which `writer-lock.ts` keeps; it takes the lock with `mkdir`).
 * Spelled here because the age reads that directory's mtime, and the state
 * probe (`isWriterLockHeld`) asks the same path.
 */
const WRITER_LOCK_SUFFIX = ".lock";

function writerLockDir(dbPath: string): string {
  return `${dbPath}${WRITER_LOCK_SUFFIX}`;
}

/**
 * Render the snapshot as compact operator-readable text. A healthy vault
 * prints a single all-clear line plus the summary; otherwise each problem
 * prints with its next command underneath.
 */
export function renderOperatorSnapshot(snap: OperatorSnapshot): string {
  const out: string[] = [];
  const header = snap.healthy
    ? "Vault status: all clear"
    : `Vault status: ${snap.problems.length} problem(s)`;
  out.push(header);
  out.push(
    `  preferences: ${snap.counts.preferences}   retired: ${snap.counts.retired}` +
      `   inbox: ${snap.counts.inbox}`,
  );
  out.push(`  stale: ${snap.staleTotal}   review queue: ${snap.reviewQueue}`);
  out.push(`  active profile: ${snap.activeProfile ?? "none"}`);
  out.push(
    `  state files: config ${snap.stateFiles.config ? "ok" : "MISSING"}, ` +
      `search index ${snap.stateFiles.searchIndex ? "present" : "absent"}`,
  );
  out.push(`  health: ${snap.healthVerdict}`);
  // Printed on BOTH branches, and that is the point: "no line" would be
  // indistinguishable from a renderer that forgot to ask, and the state
  // an operator most needs stated is the one where nothing is writing.
  out.push(
    snap.frozen === null
      ? "  frozen: no"
      : `  frozen: yes - set at ${snap.frozen.frozen_at} by ` +
          `${snap.frozen.by === "" ? "an unnamed agent" : snap.frozen.by} ` +
          `(${snap.frozen.reason === "" ? "no reason given" : snap.frozen.reason}); ` +
          `lift with \`${FREEZE_NEXT_COMMAND}\``,
  );
  // Printed on BOTH branches, like the frozen line: the state an operator
  // most needs stated is the one where nothing is writing, and "no line"
  // would be indistinguishable from a renderer that forgot to ask. A held
  // lock names the refusal an INDEX write would hit - scoped to what the
  // lock gates, since vault and memory writes serialize elsewhere - so
  // the agent reading this before writing does not learn it from the
  // write failing.
  out.push(`  ${renderStoreLine(snap.store)}`);

  if (!snap.healthy) {
    out.push("");
    out.push("Problems:");
    for (const p of snap.problems) {
      out.push(`  [${p.code}] ${p.detail}`);
      out.push(`    -> next: ${p.nextCommand}`);
    }
  }
  out.push("");
  return out.join("\n");
}

/**
 * Count `.md` files directly under `dir` (non-recursive). Missing dir = 0.
 * On a store-only machine (task 2.10): the fold's records whose page sat
 * in `dir`.
 */
function countMarkdown(vault: string | null, dir: string): number {
  if (vault === null || memoryFromStore(vault)) {
    // A failed probe degrades to 0 like the legacy branch, never rejects
    // the whole snapshot.
    try {
      return storePagesIn(vault, dir).length;
    } catch {
      return 0;
    }
  }
  if (!existsSync(dir)) return 0;
  try {
    let n = 0;
    for (const name of readdirSync(dir)) {
      if (!name.endsWith(".md")) continue;
      try {
        if (statSync(join(dir, name)).isFile()) n += 1;
      } catch {
        /* race: skip */
      }
    }
    return n;
  } catch {
    return 0;
  }
}

/** Age suffix for the held-lock line; absent when the mtime was unreadable. */
function heldForSuffix(ageMs: number | null): string {
  return ageMs === null ? "" : ` for ${ageMs}ms`;
}

/**
 * The one store line, rendered for every state the group can hold. The
 * owner's absence is stated when the lock is held - the lock record
 * carries no identity, and silence would read as a renderer that forgot
 * to ask who - and the held line names the concrete refusal an index
 * writer hits (`INDEX_LOCKED`, the search lane's typed contention
 * error), scoped to what the search writer lock gates: vault and memory
 * writes serialize on the brain lane's own lock files and are not gated
 * by this lock, so the line says so rather than implying a refusal the
 * lock cannot cause.
 */
function renderStoreLine(store: SnapshotStore): string {
  const caller = `this caller ${store.thisCaller}`;
  switch (store.writerLock) {
    case WRITER_LOCK_STATE.free:
      return `store: writer lock free; ${caller}`;
    case WRITER_LOCK_STATE.held:
      return (
        `store: writer lock held${heldForSuffix(store.writerLockAgeMs)} ` +
        "(owner: unknown, the lock record carries no identity; " +
        "an index write (o2b search index / reindex) would refuse with INDEX_LOCKED; " +
        "vault and memory writes are not gated by this lock); " +
        caller
      );
    case WRITER_LOCK_STATE.unknown:
      return `store: writer lock state unknown (${store.writerLockReason ?? "reason unavailable"}); ${caller}`;
  }
}

/**
 * The manual's template revision when a newer release wrote it, else null.
 * Fail-soft like every source here: an unreadable manual reads as current.
 */
function readManualRevisionAhead(vault: string): number | null {
  try {
    return manualRevisionAhead(readFileSync(brainManualPath(vault), "utf8"));
  } catch {
    return null;
  }
}