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
25.2 KB
Raw Blame
/**
 * Brain operational status snapshot.
 *
 * One function: {@link computeBrainStatus} walks `Brain/` and returns
 * counts, last-activity timestamps, a `maintenance_debt` block, and a
 * single sanity flag. Pure read β€” nothing is mutated, nothing is parsed
 * deeply (we cap I/O at `readdirSync` for counts and one `parseLogDay`
 * per log file for timestamps and for the debt count).
 *
 * Used by:
 *
 *   - the MCP `second_brain_status` tool (extended `brain` field)
 *   - the MCP resource `osb://status` (markdown render)
 *   - the MCP `brain_context` tool, which reads only the cheap, bounded
 *     `computeMaintenanceOverdueFlag` below β€” never this whole function
 *     β€” because it is the always-loaded reader (see that function's
 *     docblock for the cost bound).
 *
 * Callers that want the timestamps but not the counts can read either
 * field independently β€” the shape is shallow.
 *
 * ## `maintenance_debt` (nothing-writes-silently, Unit D)
 *
 * DERIVED, not counted: there is no write-time counter and no
 * STATE_SURFACES row backing this block. It is recomputed on every
 * call from the same `Brain/log/` JSONL shards `scanLogTimestamps`
 * already reads to find `last_dream_at`, so it cannot desync from the
 * log and carries no write-path coupling.
 *
 * The field is named `log_events_since_dream`, not `writes_since_dream`,
 * because that is what it measures and nothing more. `write-batch.ts`
 * β€” the executor behind `brain_create_note`, `brain_update_note`,
 * `brain_append_note`, and the note ops of `brain_write_batch` β€” never
 * calls `appendLogEvent`; a caller-named note write leaves no log event
 * to count. Calling this field "writes since dream" would be a false
 * label on a true number, which is exactly the dishonesty this wave
 * removes. It counts Brain LOG events (dream/feedback/apply-evidence/
 * retire/promote/… β€” the full {@link BRAIN_LOG_EVENT_KIND} vocabulary),
 * a real and useful signal of unreviewed lifecycle activity, just not
 * the one its old provisional name would have implied.
 *
 * Two fields the card asked for are deliberately absent, not forgotten:
 *
 *   - `open_conflicts` needs a semantic-health run
 *     (`health/reconcile.ts`) to produce a `SemanticHealthReport`; that
 *     report is not already computed on this path and running it here
 *     would make every `second_brain_status` call pay for a health
 *     pass. Measured too expensive for a status snapshot; callers that
 *     want it run `brain_health` / the reconcile report directly.
 *   - `pending_triggers` was investigated against
 *     `src/core/brain/triggers/store.ts`. Its only readers,
 *     `readTriggers`/`listTriggers`, fully parse frontmatter AND every
 *     body section of EVERY `.md` file under `Brain/triggers/` before a
 *     status filter is even applied β€” there is no status-only or
 *     count-only accessor β€” and terminal triggers (acted / dismissed /
 *     expired / suppressed) are never pruned from that directory, so
 *     the read cost grows with the vault's entire trigger history, not
 *     with the currently-open count. Not the cheap count this block
 *     requires; measured too expensive, not forgotten.
 */

import { legacyVaultOf } from "./no-vault.ts";
import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";

import { memorySource, signalPageRaw, storePagesIn } from "./memory-pages.ts";
import { parseFrontmatter } from "../vault.ts";
import { brainDirs, snapshotsDir } from "./paths.ts";
import type { BrainLogEntry } from "./log.ts";
import { storeLogDays, withLogReadPass } from "./log-days.ts";
import { withoutPrivateEntries } from "./log-events-at-reach.ts";
import { readStoreLogEvents } from "../store/read/log-events.ts";
import { listLogDates, readLogDay } from "./log-jsonl.ts";
import { loadBrainConfig } from "./policy.ts";
import { parseSignal, parseStoreSignal } from "./signal.ts";
import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "./types.ts";
import { lessonApprovalCounts, type LessonApprovalCounts } from "./lessons-promotion.ts";

// ----- Public types --------------------------------------------------------

export interface BrainStatusCounts {
  readonly inbox: number;
  readonly inbox_processed: number;
  /** Signals in `inbox/archived/` (left the contradiction window unconsumed). */
  readonly inbox_archived: number;
  readonly preferences: number;
  readonly preferences_by_status: Readonly<Record<string, number>>;
  readonly retired: number;
  readonly log_days: number;
  readonly snapshots: number;
}

/**
 * Whether `log_events_since_dream` is counted against a real dream
 * boundary or reports the whole log because no boundary exists yet.
 * `never_dreamed` is a distinct state from "zero events" β€” see the
 * module docblock.
 */
export const MAINTENANCE_DEBT_STATUS = Object.freeze({
  neverDreamed: "never_dreamed",
  counted: "counted",
  /**
   * At least one log shard in the counted window could not be read, or
   * held lines the reader could not parse, so the figure is a LOWER
   * BOUND. Distinct from `counted` because the number an operator acts
   * on is the one place a partial walk must not pass for a total.
   */
  undercounted: "undercounted",
} as const);

export type MaintenanceDebtStatus =
  (typeof MAINTENANCE_DEBT_STATUS)[keyof typeof MAINTENANCE_DEBT_STATUS];

/** See the "`maintenance_debt`" section of this module's docblock. */
export interface MaintenanceDebt {
  readonly status: MaintenanceDebtStatus;
  readonly log_events_since_dream: number;
}

const NEVER_DREAMED_DEBT: MaintenanceDebt = Object.freeze({
  status: MAINTENANCE_DEBT_STATUS.neverDreamed,
  log_events_since_dream: 0,
});

export interface BrainStatusSnapshot {
  /** Whether `<vault>/Brain/` exists at all. */
  readonly present: boolean;
  readonly counts: BrainStatusCounts;
  readonly last_dream_at: string | null;
  readonly last_apply_evidence_at: string | null;
  readonly maintenance_debt: MaintenanceDebt;
  readonly sanity: {
    /**
     * Number of signals in `inbox/` whose `created_at` predates
     * `now - dream.unconfirmed_window_days`. A non-zero value means
     * dream hasn't been run for at least an entire trial window and
     * the signals risk silent expiry.
     */
    readonly signals_awaiting_dream: number;
  };
  /**
   * Lesson-promotion approval counts (t_1e952e43): the decisions
   * currently in force plus how many approved rows went stale,
   * carried by the snapshot the MCP status tool already returns -
   * report-only, no new surface minted for them. Fail-soft: a
   * damaged ledger answers zeros and names itself in `read_error`;
   * doctor is the surface for the damage itself.
   */
  readonly lessons: LessonApprovalCounts & {
    /** Present only when the approvals ledger could not be read. */
    readonly read_error?: string;
  };
}

/** The lessons counts block for a vault with no Brain layer. */
const LESSONS_COUNTS_ABSENT: LessonApprovalCounts = Object.freeze({
  approved: 0,
  denied: 0,
  stale: 0,
});

/**
 * The fail-soft read_error the snapshot carries when the approvals
 * ledger cannot be read. Deliberately a fixed, generalized sentence:
 * the ledger reader's error messages embed the ledger's absolute path,
 * and machine paths stay out of MCP output - doctor is the surface that
 * names the cause and the recovery in operator-facing output.
 */
const LESSONS_LEDGER_READ_ERROR =
  "lessons-approvals.json could not be read (the ledger is damaged or unusable); " +
  "o2b doctor names the cause and the recovery";

/**
 * Read the lessons counts fail-soft: the doctor is the surface for a
 * damaged ledger, the status snapshot answers with zeros and names
 * itself, because an MCP consumer must not lose the whole brain block
 * over one unreadable file.
 */
function lessonsCountsSafe(vault: string): LessonApprovalCounts & {
  readonly read_error?: string;
} {
  try {
    return lessonApprovalCounts(vault);
  } catch {
    return { ...LESSONS_COUNTS_ABSENT, read_error: LESSONS_LEDGER_READ_ERROR };
  }
}

export interface ComputeBrainStatusOptions {
  /** Wall clock for staleness math. Defaults to `new Date()`. */
  readonly now?: Date;
  /**
   * The caller is below local reach: the log days, the last dream and
   * apply-evidence times and the maintenance debt are computed as if the
   * events of the store's `private` partition did not exist. Default false.
   */
  readonly withholdsPrivate?: boolean;
}

// ----- Public API ----------------------------------------------------------

export function computeBrainStatus(
  vault: string,
  opts: ComputeBrainStatusOptions = {},
): BrainStatusSnapshot {
  // One read pass: the counts, the log timestamps and the maintenance debt
  // each walk the log, and a store-only machine reads its log once.
  return withLogReadPass(() => computeBrainStatusInPass(vault, opts));
}

function computeBrainStatusInPass(
  vault: string,
  opts: ComputeBrainStatusOptions,
): BrainStatusSnapshot {
  const dirs = brainDirs(vault);
  // A store-only machine keeps its memory records in the store (task
  // 2.10): the brain is present when the store is, with or without the
  // legacy tree.
  const source = memorySource(vault);
  if (source === "none" || (source === "legacy" && !existsSync(dirs.brain))) {
    return Object.freeze({
      present: false,
      lessons: LESSONS_COUNTS_ABSENT,
      counts: {
        inbox: 0,
        inbox_processed: 0,
        inbox_archived: 0,
        preferences: 0,
        preferences_by_status: Object.freeze({}),
        retired: 0,
        log_days: 0,
        snapshots: 0,
      },
      last_dream_at: null,
      last_apply_evidence_at: null,
      maintenance_debt: NEVER_DREAMED_DEBT,
      sanity: { signals_awaiting_dream: 0 },
    });
  }

  const withholds = opts.withholdsPrivate === true;
  const counts = source === "store" ? countStoreArtifacts(vault, withholds) : countArtifacts(vault);
  const { lastDreamAt, lastApplyEvidenceAt } = scanLogTimestamps(vault, withholds);
  const signalsAwaitingDream = countSignalsAwaitingDream(
    vault,
    opts.now ?? new Date(),
    source === "store",
  );
  const maintenanceDebt = computeMaintenanceDebt(vault, lastDreamAt, withholds);

  return Object.freeze({
    present: true,
    counts,
    lessons: lessonsCountsSafe(vault),
    last_dream_at: lastDreamAt,
    last_apply_evidence_at: lastApplyEvidenceAt,
    maintenance_debt: maintenanceDebt,
    sanity: Object.freeze({ signals_awaiting_dream: signalsAwaitingDream }),
  });
}

/**
 * Cheap, bounded proxy for `maintenance_debt` fit for the always-loaded
 * `brain_context` path.
 *
 * Cost bound: at most one {@link listLogDates} call (a `readdirSync` of
 * `Brain/log/` plus filename parsing β€” no file content is read) and, if
 * any date exists, one {@link readLogDay} call for the SINGLE newest
 * date. That is O(1) in the number of log days regardless of how much
 * history the vault holds β€” `computeMaintenanceDebt` below, in
 * contrast, walks every day at or after `last_dream_at` (all of them,
 * for a never-dreamed vault) and MUST NOT run on this path.
 *
 * Returns `null` when there is no log history yet, when the newest day's
 * shard(s) exist but could not be read, and when the newest day holds no
 * readable event at all β€” all three are "unknown", never a false
 * `false` and never a `true` invented out of an empty or unparsable
 * file. Returns `true` when the newest log day has at least one event
 * and none of them is a `dream` event, `false` when it has a `dream`
 * event. A `dream` event is decisive even beside a warning: it was read,
 * and nothing unread can unsay it. This is a same-day signal only: a vault that
 * dreamed yesterday and logged something unrelated today still reads
 * `true`. Callers that need the precise count read
 * `maintenance_debt.log_events_since_dream` from `computeBrainStatus`
 * instead (`second_brain_status` / `osb://status`).
 */
export function computeMaintenanceOverdueFlag(
  vault: string | null,
  opts: { readonly withholdsPrivate?: boolean } = {},
): boolean | null {
  const withholds = opts.withholdsPrivate === true;
  const log = recentStatusLog(vault, withholds) ?? statusLog(vault, withholds);
  if (log === null) return null;
  const newest = log.dates.at(-1);
  if (newest === undefined) return null;
  let day;
  try {
    day = log.day(newest);
  } catch {
    // Same tolerance as `scanLogTimestamps`: an unreadable day is
    // reported as unknown, not silently folded into a boolean answer.
    return null;
  }
  if (day.entries.some((e) => e.eventType === BRAIN_LOG_EVENT_KIND.dream)) return false;
  // No dream event among the events that were read. That is only an
  // answer when the read was whole and had something in it: an empty day
  // and a day whose bytes did not parse are both "nothing to judge", and
  // `true` there would report overdue maintenance out of a file nobody
  // could read.
  if (day.entries.length === 0 || day.warnings.length > 0) return null;
  return true;
}

// ----- Implementation ------------------------------------------------------

function countArtifacts(vault: string): BrainStatusCounts {
  const dirs = brainDirs(vault);
  const inbox = countMd(dirs.inbox);
  const inbox_processed = countMd(dirs.processed);
  const inbox_archived = countMd(dirs.archived);
  const retired = countMd(dirs.retired);
  // Shard-aware: count distinct DAYS, not files (several shards share a day).
  const log_days = listLogDates(vault).length;
  const snapshots = countZst(snapshotsDir(vault));

  // Per-status preference counts: read frontmatter line `status:` only
  // β€” no full parse β€” to keep this cheap. Unknown values bucket under
  // `unknown` so the doctor's parse errors are still visible upstream.
  const preferences_by_status: Record<string, number> = {};
  let preferences = 0;
  if (existsSync(dirs.preferences)) {
    for (const name of readdirSync(dirs.preferences)) {
      if (!name.endsWith(".md")) continue;
      if (!name.startsWith("pref-")) continue;
      preferences++;
      const status = readFrontmatterStatus(join(dirs.preferences, name));
      preferences_by_status[status] = (preferences_by_status[status] ?? 0) + 1;
    }
  }
  // Always include the canonical bucket names with 0 so consumers
  // don't need to defensively `?? 0`.
  for (const s of Object.values(BRAIN_PREFERENCE_STATUS)) {
    preferences_by_status[s] = preferences_by_status[s] ?? 0;
  }

  return {
    inbox,
    inbox_processed,
    inbox_archived,
    preferences,
    preferences_by_status: Object.freeze(preferences_by_status),
    retired,
    log_days,
    snapshots,
  };
}

/**
 * {@link countArtifacts} on a store-only machine: the fold's records
 * counted by the folder their page sat in, the preferences bucketed by
 * their status. The log days and the snapshots are not memory records
 * and are counted where they are.
 */
function countStoreArtifacts(vault: string, withholdsPrivate: boolean): BrainStatusCounts {
  const dirs = brainDirs(vault);
  const inFolder = (dir: string): number => storePagesIn(vault, dir).length;
  const preferences_by_status: Record<string, number> = {};
  let preferences = 0;
  for (const page of storePagesIn(vault, dirs.preferences)) {
    if (!page.id.startsWith("pref-")) continue;
    preferences++;
    const value = page.meta["_status"];
    const status = typeof value === "string" && value.trim() !== "" ? value.trim() : "unknown";
    preferences_by_status[status] = (preferences_by_status[status] ?? 0) + 1;
  }
  for (const s of Object.values(BRAIN_PREFERENCE_STATUS)) {
    preferences_by_status[s] = preferences_by_status[s] ?? 0;
  }
  return {
    inbox: inFolder(dirs.inbox),
    inbox_processed: inFolder(dirs.processed),
    inbox_archived: inFolder(dirs.archived),
    preferences,
    preferences_by_status: Object.freeze(preferences_by_status),
    retired: inFolder(dirs.retired),
    log_days: statusLog(vault, withholdsPrivate)?.dates.length ?? 0,
    // The snapshot module's folder: the device-local state once switched.
    snapshots: countZst(snapshotsDir(vault)),
  };
}

/** The log as the status readers walk it: dates, and one day's events with its warnings. */
interface StatusLog {
  readonly dates: ReadonlyArray<string>;
  day(date: string): {
    readonly entries: ReadonlyArray<BrainLogEntry>;
    readonly warnings: ReadonlyArray<unknown>;
  };
}

/** Days of the store log the overdue flag looks at before it reads the whole log. */
const RECENT_LOG_DAYS = 31;

/**
 * The last {@link RECENT_LOG_DAYS} days of a store-only machine's log, or
 * `null` when the machine reads day files or the window holds no event
 * (the caller then reads the whole log), so the always-loaded overdue
 * flag reads a bounded window, not the store's whole history. The window
 * runs one day past today's UTC date: an entry is filed by the date its
 * own timestamp spells, and one a device whose clock runs ahead wrote can
 * already name tomorrow; the whole-log read has no upper bound either.
 */
function recentStatusLog(vault: string | null, withholdsPrivate: boolean): StatusLog | null {
  const now = new Date();
  const from = new Date(now.getTime() - RECENT_LOG_DAYS * 86_400_000);
  const to = new Date(now.getTime() + 86_400_000);
  const stored = readStoreLogEvents(
    { from: from.toISOString().slice(0, 10), to: to.toISOString().slice(0, 10) },
    { vault },
  );
  if (stored === null) return null;
  // Below local reach a private event is not there, and a day it alone
  // filled is not a log day.
  const shown = withoutPrivateEntries(
    stored.map((s) => s.entry),
    withholdsPrivate,
  );
  if (shown.length === 0) return null;
  const byDate = new Map<string, BrainLogEntry[]>();
  for (const entry of shown) {
    const date = entry.timestamp.slice(0, 10);
    const day = byDate.get(date);
    if (day === undefined) byDate.set(date, [entry]);
    else day.push(entry);
  }
  return {
    dates: [...byDate.keys()].toSorted(),
    day: (date) => ({ entries: byDate.get(date) ?? [], warnings: [] }),
  };
}

/**
 * The log of `vault`: the day files on an unswitched machine (`null` when
 * `Brain/log/` is absent), the store's `log-event` records on a store-only
 * one (task 2.10), where a day carries no read warning.
 */
function statusLog(vault: string | null, withholdsPrivate = false): StatusLog | null {
  const stored = storeLogDays(vault);
  if (stored !== null) {
    // Below local reach a private event is not there, and a day it alone
    // filled is not a log day. Day files carry no mark.
    const days = stored
      .map((d) => ({ date: d.date, entries: withoutPrivateEntries(d.entries, withholdsPrivate) }))
      .filter((d) => d.entries.length > 0 || !withholdsPrivate);
    const byDate = new Map(days.map((d) => [d.date, d.entries] as const));
    return {
      dates: days.map((d) => d.date),
      day: (date) => ({ entries: byDate.get(date) ?? [], warnings: [] }),
    };
  }
  const root = legacyVaultOf(vault, "statusLog");
  if (!existsSync(brainDirs(root).log)) return null;
  return { dates: listLogDates(root), day: (date) => readLogDay(root, date) };
}

function countMd(dir: string): number {
  if (!existsSync(dir)) return 0;
  let n = 0;
  for (const name of readdirSync(dir)) {
    if (name.endsWith(".md")) n++;
  }
  return n;
}

function countZst(dir: string): number {
  if (!existsSync(dir)) return 0;
  let n = 0;
  for (const name of readdirSync(dir)) {
    if (name.endsWith(".tar.zst")) n++;
  }
  return n;
}

function readFrontmatterStatus(path: string): string {
  // Use the canonical frontmatter parser instead of a regex sniff so
  // quoted values (`_status: "confirmed"`) and other legal YAML
  // shapes round-trip correctly. Files we can't parse bucket under
  // `unknown` β€” doctor surfaces them as schema errors elsewhere.
  try {
    const [meta] = parseFrontmatter(path);
    const value = meta["_status"];
    if (typeof value !== "string") return "unknown";
    const trimmed = value.trim();
    return trimmed.length > 0 ? trimmed : "unknown";
  } catch {
    return "unknown";
  }
}

function scanLogTimestamps(
  vault: string,
  withholdsPrivate: boolean,
): {
  lastDreamAt: string | null;
  lastApplyEvidenceAt: string | null;
} {
  const log = statusLog(vault, withholdsPrivate);
  if (log === null) return { lastDreamAt: null, lastApplyEvidenceAt: null };
  const days = log.dates.toReversed(); // newest day first

  let lastDreamAt: string | null = null;
  let lastApplyEvidenceAt: string | null = null;
  for (const date of days) {
    // We only need the most-recent timestamp of each kind, so once
    // both are set we can stop scanning older files.
    let entries;
    try {
      entries = log.day(date).entries;
    } catch {
      continue;
    }
    for (let i = entries.length - 1; i >= 0; i--) {
      const e = entries[i]!;
      if (lastDreamAt === null && e.eventType === BRAIN_LOG_EVENT_KIND.dream) {
        lastDreamAt = e.timestamp;
      }
      if (lastApplyEvidenceAt === null && e.eventType === BRAIN_LOG_EVENT_KIND.applyEvidence) {
        lastApplyEvidenceAt = e.timestamp;
      }
      if (lastDreamAt !== null && lastApplyEvidenceAt !== null) break;
    }
    if (lastDreamAt !== null && lastApplyEvidenceAt !== null) break;
  }
  return { lastDreamAt, lastApplyEvidenceAt };
}

/**
 * Derive `maintenance_debt` from the JSONL log shards, AFTER
 * `last_dream_at` has already been resolved by {@link scanLogTimestamps}.
 * No stored counter, no STATE_SURFACES row β€” see the module docblock.
 *
 * `lastDreamAt === null` (never dreamed) counts every event ever
 * logged, because there is no dream boundary to count "since". A real
 * `last_dream_at` counts only events with a strictly later timestamp β€”
 * and a shard in that window that could not be read, or a line in it
 * that could not be parsed, makes the answer `undercounted`: the number
 * is then a floor, and the sibling flag's discipline (never a confident
 * answer over an incomplete read) applies to the precise figure too.
 *
 * the dream event itself is the boundary, not a countable event β€” and
 * walks days newest-first, stopping as soon as a day predates the
 * dream's own day, so the scan is bounded to "since the last dream",
 * not the whole log history, on every vault that HAS dreamed.
 */
function computeMaintenanceDebt(
  vault: string,
  lastDreamAt: string | null,
  withholdsPrivate: boolean,
): MaintenanceDebt {
  const log = statusLog(vault, withholdsPrivate);
  if (log === null) return NEVER_DREAMED_DEBT;

  const cutoffMs = lastDreamAt !== null ? Date.parse(lastDreamAt) : null;
  const cutoffDate = lastDreamAt !== null ? lastDreamAt.slice(0, 10) : null;
  const days = log.dates.toReversed(); // newest day first

  let count = 0;
  let complete = true;
  for (const date of days) {
    // Every earlier day is entirely pre-dream once we're past the
    // dream's own day β€” no need to open its shards at all.
    if (cutoffDate !== null && date < cutoffDate) break;
    let entries;
    try {
      const day = log.day(date);
      entries = day.entries;
      // A shard that would not open, or a line that would not parse:
      // either way events this window contains are absent from `count`,
      // and the figure below is a floor rather than the count it looks
      // like. Recorded, not aborted β€” the events that WERE read are
      // still the operator's best available number.
      if (day.warnings.length > 0) complete = false;
    } catch {
      // Same tolerance as scanLogTimestamps: skip the day rather than
      // abort the snapshot β€” but never silently, see above.
      complete = false;
      continue;
    }
    for (const e of entries) {
      if (cutoffMs !== null) {
        const ts = Date.parse(e.timestamp);
        if (!Number.isFinite(ts) || ts <= cutoffMs) continue;
      }
      count++;
    }
  }

  return Object.freeze({
    status: !complete
      ? MAINTENANCE_DEBT_STATUS.undercounted
      : lastDreamAt === null
        ? MAINTENANCE_DEBT_STATUS.neverDreamed
        : MAINTENANCE_DEBT_STATUS.counted,
    log_events_since_dream: count,
  });
}

function countSignalsAwaitingDream(vault: string, now: Date, fromStore: boolean): number {
  const dirs = brainDirs(vault);
  if (!fromStore && !existsSync(dirs.inbox)) return 0;
  let windowDays: number;
  try {
    windowDays = loadBrainConfig(vault).dream.unconfirmed_window_days;
  } catch {
    return 0; // Config absent: doctor will flag; status reports 0.
  }
  const cutoffMs = now.getTime() - windowDays * 24 * 3600 * 1000;
  let stale = 0;
  if (fromStore) {
    for (const page of storePagesIn(vault, dirs.inbox)) {
      if (!page.id.startsWith("sig-")) continue;
      let createdAtMs: number;
      try {
        createdAtMs = Date.parse(
          parseStoreSignal(page.path, page.meta, signalPageRaw(page)).created_at,
        );
      } catch {
        continue;
      }
      if (Number.isFinite(createdAtMs) && createdAtMs < cutoffMs) stale++;
    }
    return stale;
  }
  for (const name of readdirSync(dirs.inbox)) {
    if (!name.endsWith(".md")) continue;
    if (!name.startsWith("sig-")) continue;
    // Read the authoritative `created_at` from frontmatter β€” filename
    // is a hint but the timestamp is the source of truth (slug
    // collisions and manual `mv` operations can desync the two).
    let createdAtMs: number;
    try {
      createdAtMs = Date.parse(parseSignal(join(dirs.inbox, name)).created_at);
    } catch {
      continue; // Unparseable signal β€” doctor's domain, not status's.
    }
    if (!Number.isFinite(createdAtMs)) continue;
    if (createdAtMs < cutoffMs) stale++;
  }
  return stale;
}