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
/**
* Freshen on read (index-freshness design): a reader that finds the search
* index older than `search_freshen_interval_s` answers from the index it has
* and starts ONE detached, low-priority incremental index run, so the next
* read sees the current vault. Nothing stays resident: the only triggers are
* reads (`search()`) and session start (`ensureVaultCurrent`), both of which
* only happen while an agent works.
*
* Everything here is per device and lives next to the index
* (`<dirname(dbPath)>/`), never in `Brain/`: the claim that keeps concurrent
* readers from starting a run each, and the state file the child writes its
* outcome and backoff to.
*
* `maybeFreshenIndex` never throws and never waits for the run: a reader
* of a fresh index pays nothing; a due one pays one state-file read, one
* lock probe and one exclusive create.
*/
import { randomUUID } from "node:crypto";
import { linkSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { appendMetric } from "../brain/metrics.ts";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import { o2bCommand } from "../maintenance/o2b-command.ts";
import { isWriterLockHeld } from "./store/writer-lock.ts";
import type { ResolvedSearchConfig } from "./types.ts";
/** The claim a reader takes before it starts a run; the child releases it. */
export const FRESHEN_CLAIM_FILE = "freshen.claim";
/** The child's outcome, failure streak and backoff. */
export const FRESHEN_STATE_FILE = "freshen-state.json";
/**
* The pending-write marker a forced refresh claim leaves when a run is
* already in flight (`freshen-pending.json`, beside the state file) -
* the claim held, or the index writer lock probed held, which is the
* same run mid-pass. The claim's exclusivity means exactly one run is in flight, and
* that run may have scanned past the write before it landed - its stamp
* cannot prove it saw the write, and until the next interval its
* freshness suppresses freshen-on-read. The marker is the queue: the
* child reads it before releasing the claim and runs one bounded extra
* incremental pass when the marker is newer than its scan start. See
* {@link settleFreshenPending}.
*/
export const FRESHEN_PENDING_FILE = "freshen-pending.json";
/** A write waiting for a pass that can provably cover it. */
export interface FreshenPending {
/** Milliseconds since the epoch: when the pending write landed. */
readonly since: number;
}
/**
* Metrics surface for background runs. A row is written only when a run
* changed the index or failed: an idle machine would otherwise append one
* row a minute to a synced file for nothing.
*/
export const INDEX_FRESHEN_SURFACE = "index_freshen";
/** A claim older than this belongs to a run that died; it is taken over. */
export const FRESHEN_CLAIM_ABANDONED_MS = 10 * 60 * 1000;
const BACKOFF_BASE_MS = 60_000;
const BACKOFF_CAP_MS = 3_600_000;
/** Why a reader did not start a run. */
export const FRESHEN_SKIP = Object.freeze({
off: "off",
noIndex: "no_index",
fresh: "fresh",
backoff: "backoff",
readOnly: "read_only",
writerLock: "writer_lock",
claimed: "claimed",
/** The index directory refused the claim (read-only mount, no permission). */
unwritable: "unwritable",
spawnFailed: "spawn_failed",
} as const);
export type FreshenSkip = (typeof FRESHEN_SKIP)[keyof typeof FRESHEN_SKIP];
/** What a reader did: started a run, or the reason it did not. */
export type FreshenDecision = "spawned" | FreshenSkip;
export interface FreshenState {
readonly failures: number;
readonly backoffUntil: string | null;
readonly lastOutcome: "completed" | "failed" | null;
readonly lastRunAt: string | null;
readonly lastDurationMs: number | null;
readonly lastError: string | null;
/** Documents the last completed run added, updated or deleted. */
readonly lastChanged: number | null;
}
export const EMPTY_FRESHEN_STATE: FreshenState = Object.freeze({
failures: 0,
backoffUntil: null,
lastOutcome: null,
lastRunAt: null,
lastDurationMs: null,
lastError: null,
lastChanged: null,
});
export interface DecideFreshenInput {
readonly nowMs: number;
readonly lastIndexedAt: string | null;
readonly intervalSeconds: number;
readonly backoffUntilMs: number | null;
}
/**
* Whether a read should start a run. Pure. An index that was never
* stamped belongs to self-heal (a missing or unbuilt index is rebuilt
* there); an unparseable stamp is treated as due, since claiming it fresh
* would leave the index stale forever. Freshness is decided before the
* backoff, so a reader can skip the state file while the index is fresh.
*/
export function decideFreshen(
input: DecideFreshenInput,
): { readonly action: "spawn" } | { readonly action: "skip"; readonly reason: FreshenSkip } {
if (input.intervalSeconds <= 0) return { action: "skip", reason: FRESHEN_SKIP.off };
if (input.lastIndexedAt === null) return { action: "skip", reason: FRESHEN_SKIP.noIndex };
const indexedMs = Date.parse(input.lastIndexedAt);
if (Number.isFinite(indexedMs) && input.nowMs - indexedMs < input.intervalSeconds * 1000) {
return { action: "skip", reason: FRESHEN_SKIP.fresh };
}
if (input.backoffUntilMs !== null && input.backoffUntilMs > input.nowMs) {
return { action: "skip", reason: FRESHEN_SKIP.backoff };
}
return { action: "spawn" };
}
/** Seconds since `lastIndexedAt`, or null when it is absent or unparseable. */
export function indexAgeSeconds(lastIndexedAt: string | null, nowMs: number): number | null {
if (lastIndexedAt === null) return null;
const ms = Date.parse(lastIndexedAt);
if (!Number.isFinite(ms)) return null;
return Math.max(0, Math.floor((nowMs - ms) / 1000));
}
/** Backoff after the `failures`-th failure in a row: 1 min doubling to 1 h. */
export function nextBackoffMs(failures: number): number {
const n = Math.max(1, failures);
return Math.min(BACKOFF_BASE_MS * 2 ** (n - 1), BACKOFF_CAP_MS);
}
/**
* A claim file that cannot be parsed is normally one being written: the
* exclusive create and the write are two steps. Only past this grace is a
* torn claim taken for a dead run's.
*/
const CLAIM_TORN_GRACE_MS = 10_000;
/** A takeover lock older than this belongs to a reader that died mid-takeover. */
const TAKEOVER_STALE_MS = 30_000;
/** A claim taken, or why it was not. */
export type FreshenClaim =
| { readonly token: string }
| { readonly skip: typeof FRESHEN_SKIP.claimed | typeof FRESHEN_SKIP.unwritable };
/**
* Take the claim, or return null when a live run holds it or the index
* directory refuses it. {@link tryClaimFreshen} tells the two apart.
*/
export function claimFreshen(dir: string, nowMs: number): string | null {
const claim = tryClaimFreshen(dir, nowMs);
return "token" in claim ? claim.token : null;
}
/**
* Take the claim. The claim is an exclusive create, so of N readers racing
* on a stale index exactly one wins; a create that fails for any reason
* other than an existing claim (EROFS, EACCES) is reported as unwritable,
* since no reader there can ever start a run. A claim older than
* {@link FRESHEN_CLAIM_ABANDONED_MS} (or torn and older than
* {@link CLAIM_TORN_GRACE_MS}) is a run that died (a reboot, an OOM kill)
* and is taken over - but only by the reader holding the exclusive
* takeover lock, which re-reads the claim under it and replaces it with an
* atomic rename, so the slot is never empty and a fresh claim is never
* touched.
*/
export function tryClaimFreshen(dir: string, nowMs: number): FreshenClaim {
const path = join(dir, FRESHEN_CLAIM_FILE);
const token = `fr-${randomUUID()}`;
const body = JSON.stringify({ token, at: nowMs });
const claimed = { skip: FRESHEN_SKIP.claimed } as const;
for (let attempt = 0; attempt < 2; attempt++) {
try {
writeFileSync(path, body, { flag: "wx" });
return { token };
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== "EEXIST") {
return { skip: FRESHEN_SKIP.unwritable };
}
}
const seen = readClaimBody(path);
if (seen === null) continue; // released since: race the create again
if (!claimAbandoned(path, seen, nowMs)) return claimed;
const taken = takeOver(path, token, body, nowMs);
return taken === null ? claimed : { token: taken };
}
return claimed;
}
function takeOver(path: string, token: string, body: string, nowMs: number): string | null {
const lock = `${path}.takeover`;
if (!createExclusive(lock)) {
let age = 0;
try {
age = nowMs - statSync(lock).mtimeMs;
} catch {
return null;
}
if (age <= TAKEOVER_STALE_MS) return null;
unlinkQuietly(lock);
if (!createExclusive(lock)) return null;
}
try {
const current = readClaimBody(path);
if (current !== null && !claimAbandoned(path, current, nowMs)) return null;
const tmp = `${path}.${token}.tmp`;
writeFileSync(tmp, body);
renameSync(tmp, path);
return token;
} catch {
return null;
} finally {
unlinkQuietly(lock);
}
}
function createExclusive(path: string): boolean {
try {
writeFileSync(path, String(process.pid), { flag: "wx" });
return true;
} catch {
return false;
}
}
function readClaimBody(path: string): string | null {
try {
return readFileSync(path, "utf8");
} catch {
return null;
}
}
function claimAbandoned(path: string, body: string, nowMs: number): boolean {
try {
const parsed = JSON.parse(body) as { at?: unknown };
if (typeof parsed.at === "number") return nowMs - parsed.at > FRESHEN_CLAIM_ABANDONED_MS;
} catch {
// Torn or empty: judged by age below.
}
try {
return nowMs - statSync(path).mtimeMs > CLAIM_TORN_GRACE_MS;
} catch {
return false;
}
}
function unlinkQuietly(path: string): void {
try {
unlinkSync(path);
} catch {
// Already gone.
}
}
/** Release the claim, but only while it is still ours. */
export function releaseFreshen(dir: string, token: string): void {
const path = join(dir, FRESHEN_CLAIM_FILE);
try {
const parsed = JSON.parse(readFileSync(path, "utf8")) as { token?: unknown };
if (parsed.token === token) unlinkSync(path);
} catch {
// Absent or unreadable: nothing of ours to release.
}
}
/**
* Record that a write landed at `nowMs` and is waiting for a pass that
* can provably cover it. Always overwrites with the newest instant: the
* marker must never name an instant older than the youngest uncovered
* write, or a pass would clear it while the newer write is still
* missing. Best-effort, like every other piece of freshen bookkeeping -
* a marker that cannot be written costs the write its second pass, not
* the write itself.
*/
export function markFreshenPending(dir: string, nowMs: number): void {
try {
atomicWriteFileSync(
join(dir, FRESHEN_PENDING_FILE),
JSON.stringify({ since: nowMs } satisfies FreshenPending) + "\n",
);
} catch {
// Best effort: the next forced claim re-marks.
}
}
/** The pending marker at an arbitrary path, or `null` when torn or absent. */
function readPendingAt(path: string): FreshenPending | null {
try {
const parsed = JSON.parse(readFileSync(path, "utf8")) as {
since?: unknown;
};
if (typeof parsed.since !== "number" || !Number.isFinite(parsed.since)) return null;
return { since: parsed.since };
} catch {
return null;
}
}
/** The pending marker, or `null` when there is none or it is torn. */
export function readFreshenPending(dir: string): FreshenPending | null {
return readPendingAt(join(dir, FRESHEN_PENDING_FILE));
}
/** Drop the pending marker. An absent marker is nothing to fail a run over. */
export function clearFreshenPending(dir: string): void {
try {
unlinkSync(join(dir, FRESHEN_PENDING_FILE));
} catch {
// Already gone.
}
}
/** A marker taken off its path by {@link takeFreshenPending}, held for the settle. */
export interface TakenFreshenPending {
/** The marker as it stood on the path, or `null` when its file was torn. */
readonly pending: FreshenPending | null;
/**
* Put the taken marker back. A writer that re-marked while the settle
* held this take keeps the path: the link answers that atomically
* (EEXIST means the path is occupied again), and the newer instant
* supersedes the taken one, the marker naming the YOUNGEST uncovered
* write.
*/
restore(): void;
/** Drop the taken marker: the pass that ran covered it. */
drop(): void;
}
/**
* Take the pending marker off its path atomically, so the settle can
* judge and clear it without racing the writers that mark between the
* settle's read and its unlink - the one window a plain
* read-then-clear leaves open, and exactly the lost write the marker
* exists to prevent. The rename moves whatever stands at the path NOW
* (a later writer's marker can only land after it), and `restore` puts
* the take back unless a newer marker claimed the path in between.
* `null` when there was no marker to take.
*/
export function takeFreshenPending(dir: string): TakenFreshenPending | null {
const path = join(dir, FRESHEN_PENDING_FILE);
const held = `${path}.${randomUUID()}.settle`;
try {
renameSync(path, held);
} catch {
return null; // No marker (or the directory refused): nothing queued.
}
const pending = readPendingAt(held);
return {
pending,
restore: () => {
try {
linkSync(held, path);
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== "EEXIST") {
// A filesystem without hard links (EPERM, ENOTSUP, EXDEV on
// network and exFAT mounts): the exclusive put-back is
// unavailable there, so the take goes back by plain rename -
// the small window where a writer's newer marker could be
// replaced is the price of not destroying the marker outright.
try {
renameSync(held, path);
return;
} catch {
// rename(2) replaces an occupied destination on every
// platform this runs on, so reaching here is a genuine I/O
// failure, not an occupied path: the take cannot be put
// back and is dropped below - the same best-effort loss a
// marker that cannot be written already names.
}
}
}
unlinkQuietly(held);
},
drop: () => {
unlinkQuietly(held);
},
};
}
/**
* The freshen child's settle, run before it releases the claim.
*
* A forced write that arrived while THIS run held the claim left a
* marker naming the instant its write landed. The run's own pass covers
* everything up to its scan start, so:
*
* - a marker at or before the scan start is covered - clear it;
* - a newer marker is not: run ONE more incremental pass - the bound
* is one extra pass, never a loop - and take the marker only once
* the pass has finished, clearing it when it still names an instant
* the extra pass's own scan start covers. A still-newer marker (a
* write landing during the extra pass) survives for the next run,
* which covers and clears it the same way;
* - a caller that cannot run a pass (a config that never resolved)
* leaves the marker exactly as it stands.
*
* The marker is READ before any pass runs and TAKEN only after - never
* the other way round. A take that outran its pass handed a killed or
* thrown-away child a marker stranded in the take's hold file, where
* nothing reads it again: the write stood unqueued and unmarked. With
* the pass running against a marker that never left its path, a child
* that dies mid-pass leaves the queue exactly as it found it, and the
* take's hold window shrinks to the judge-and-clear after the pass -
* where {@link takeFreshenPending}'s restore still answers a writer
* that re-marked with newer work, superseding the take rather than
* being unlinked by this settle. A pass that throws covered nothing and
* the marker was never taken, so it stands for the next run.
*
* Returns whether the extra pass ran. Throws only what `runPass`
* throws, and the caller decides how a failed extra pass is reported.
*/
export async function settleFreshenPending(
dir: string,
scanStartedAtMs: number,
runPass: (() => Promise<void>) | null,
): Promise<boolean> {
// Read without taking: the marker stays on its own path through every
// fallible step below, so a child that dies at any of them leaves the
// queue standing for the next run.
const pending = readFreshenPending(dir);
if (pending === null) return false;
if (pending.since <= scanStartedAtMs) {
// This run's scan began after the pending write: the pass that just
// finished covered it. The take judges what stands NOW, so a writer
// that re-marked between the read and this take keeps its newer
// marker - only a still-covered marker is dropped.
const covered = takeFreshenPending(dir);
if (covered !== null) {
if (covered.pending !== null && covered.pending.since <= scanStartedAtMs) {
covered.drop();
} else {
covered.restore();
}
}
return false;
}
if (runPass === null) {
// No pass to run: the marker stands untouched for the next run.
return false;
}
const secondStart = Date.now();
// A pass that throws propagates with the marker still on its path -
// it covered nothing, and that standing marker is the truthful queue.
await runPass();
const taken = takeFreshenPending(dir);
if (taken === null) return true;
if (taken.pending !== null && taken.pending.since <= secondStart) {
// The extra pass started after the marker's instant, so it covered
// the pending write - and the marker goes with it. A marker that
// outlived its own coverage would push every later run into an
// extra pass forever.
taken.drop();
} else {
// The write landed after the extra pass's scan start: this run
// cannot prove it saw the write, so the marker survives for the
// next run - superseded, not merged, if a writer re-marked during
// the pass.
taken.restore();
}
return true;
}
function str(v: unknown): string | null {
return typeof v === "string" ? v : null;
}
function num(v: unknown): number | null {
return typeof v === "number" && Number.isFinite(v) ? v : null;
}
/** The state file, or the empty state when it is absent or torn. */
export function readFreshenState(dir: string): FreshenState {
try {
const raw = JSON.parse(readFileSync(join(dir, FRESHEN_STATE_FILE), "utf8")) as Record<
string,
unknown
>;
const outcome = raw["lastOutcome"];
return Object.freeze({
failures: num(raw["failures"]) ?? 0,
backoffUntil: str(raw["backoffUntil"]),
lastOutcome: outcome === "completed" || outcome === "failed" ? outcome : null,
lastRunAt: str(raw["lastRunAt"]),
lastDurationMs: num(raw["lastDurationMs"]),
lastError: str(raw["lastError"]),
lastChanged: num(raw["lastChanged"]),
});
} catch {
return EMPTY_FRESHEN_STATE;
}
}
/** Write the state file atomically. */
export function writeFreshenState(dir: string, state: FreshenState): void {
atomicWriteFileSync(join(dir, FRESHEN_STATE_FILE), JSON.stringify(state, null, 2) + "\n");
}
/**
* Prefix the child's argv so it runs at idle I/O priority where the
* platform has a tool for it; the child lowers its own CPU priority.
*/
export function freshenCommand(
base: ReadonlyArray<string>,
has: (tool: string) => boolean,
platform: NodeJS.Platform,
): string[] {
if (platform === "linux" && has("ionice")) return ["ionice", "-c3", ...base];
if (platform === "darwin" && has("taskpolicy")) return ["taskpolicy", "-b", ...base];
return [...base];
}
/**
* The options the freshen child is spawned with. Detached on every
* platform: a non-detached child dies with its parent on Windows, and on
* POSIX it stays in the reader's process group, so a short-lived hook
* whose group is signalled on exit would take the run down with it.
*/
export function freshenSpawnOptions(env: NodeJS.ProcessEnv): {
readonly stdin: "ignore";
readonly stdout: "ignore";
readonly stderr: "ignore";
readonly windowsHide: true;
readonly detached: true;
readonly env: Record<string, string | undefined>;
} {
return {
stdin: "ignore",
stdout: "ignore",
stderr: "ignore",
windowsHide: true,
detached: true,
// Bun gives a child spawned without `env` the environment this process
// STARTED with; a config chosen after start must reach the child.
env: { ...env },
};
}
function spawnDetached(argv: string[]): void {
const proc = Bun.spawn(argv, freshenSpawnOptions(process.env));
proc.unref();
}
export interface MaybeFreshenOptions {
readonly lastIndexedAt: string | null;
/** A read-only open (cross-vault, recall sources): never write there. */
readonly readOnly?: boolean;
/**
* Skip the freshness gate and spawn whenever the remaining guards
* allow. This is the post-write shape: the caller just changed the
* vault, so the stamp is due by definition and comparing it against
* the interval would answer the wrong question. Config off still
* means off (`intervalSeconds <= 0` refuses whatever the flag says),
* an index that was never stamped stays self-heal's, and the claim
* exclusivity, the failure backoff and the writer-lock probe all
* stand exactly as on the interval path.
*/
readonly force?: boolean;
readonly nowMs?: number;
/** Test seam: replaces the detached spawn. */
readonly spawn?: (argv: string[]) => void;
}
/**
* Start a background incremental index run when the index is stale.
* Never throws; returns what it did.
*/
export function maybeFreshenIndex(
config: ResolvedSearchConfig,
opts: MaybeFreshenOptions,
): FreshenDecision {
try {
const freshen = config.freshen;
if (freshen === undefined || freshen.intervalSeconds <= 0) return FRESHEN_SKIP.off;
if (opts.readOnly === true) return FRESHEN_SKIP.readOnly;
const nowMs = opts.nowMs ?? Date.now();
const dir = dirname(config.dbPath);
const input = {
nowMs,
lastIndexedAt: opts.lastIndexedAt,
intervalSeconds: freshen.intervalSeconds,
};
if (opts.force === true) {
// The freshness comparison is the one gate force exists to skip;
// everything else decides for the same reasons as on the interval
// path. The stamp check doubles as the self-heal boundary: an
// index that was never stamped is rebuilt there, not here.
if (opts.lastIndexedAt === null) return FRESHEN_SKIP.noIndex;
// No freshness floor on the stamp: the stamp marks when a run
// FINISHED, and a run that finished after the write began may well
// have scanned before the write landed - its stamp cannot prove it
// saw the write. A forced run that skipped on such a stamp would
// leave the write unindexed until the next interval or the next
// write, silently. The collapse the floor promised is the claim
// machinery's: a run already in flight holds the claim, so a write
// landing during it starts nothing. Back-to-back applied writes
// spawn one run each, capped by that exclusivity and the failure
// backoff - the price of every run provably covering its write.
const backoffUntil = readFreshenState(dir).backoffUntil;
const backoffMs = backoffUntil === null ? Number.NaN : Date.parse(backoffUntil);
if (Number.isFinite(backoffMs) && backoffMs > nowMs) return FRESHEN_SKIP.backoff;
} else {
// Every search lands here: decide on the index stamp alone first and
// read the state file for the backoff only once the index is due.
const due = decideFreshen({ ...input, backoffUntilMs: null });
if (due.action === "skip") return due.reason;
const backoffUntil = readFreshenState(dir).backoffUntil;
const backoffMs = backoffUntil === null ? Number.NaN : Date.parse(backoffUntil);
const decision = decideFreshen({
...input,
backoffUntilMs: Number.isFinite(backoffMs) ? backoffMs : null,
});
if (decision.action === "skip") return decision.reason;
}
if (isWriterLockHeld(config.dbPath)) return FRESHEN_SKIP.writerLock;
const claim = tryClaimFreshen(dir, nowMs);
if (!("token" in claim)) return claim.skip;
const token = claim.token;
const argv = freshenCommand(
[
...o2bCommand(),
"search",
"index",
// No vault: the child resolves the same vault-free config.
...(config.vault === null ? [] : ["--vault", config.vault]),
...(freshen.configPath !== null ? ["--config", freshen.configPath] : []),
// Where the claim and the state live, so a child that fails before
// it can resolve its config can still record it and release.
"--freshen-state",
dir,
"--freshen",
token,
],
(tool) => Bun.which(tool) !== null,
process.platform,
);
try {
(opts.spawn ?? spawnDetached)(argv);
} catch {
releaseFreshen(dir, token);
return FRESHEN_SKIP.spawnFailed;
}
return "spawned";
} catch {
// A reader must never fail because freshening could not decide.
return FRESHEN_SKIP.spawnFailed;
}
}
export interface FreshenOutcome {
readonly outcome: "completed" | "failed";
readonly durationMs: number;
/** Documents added, updated or deleted (completed runs). */
readonly changed?: number;
readonly error?: string;
}
/**
* What the background child records when it ends: the state file (outcome,
* streak, backoff) and, when it changed something or failed, one metric
* row. Never throws: a run must not fail because its bookkeeping did.
*/
export function recordFreshenOutcome(
vault: string | null,
dir: string,
result: FreshenOutcome,
nowMs: number = Date.now(),
): void {
const previous = readFreshenState(dir);
const failed = result.outcome === "failed";
const failures = failed ? previous.failures + 1 : 0;
const runAt = new Date(nowMs).toISOString();
try {
writeFreshenState(dir, {
failures,
backoffUntil: failed ? new Date(nowMs + nextBackoffMs(failures)).toISOString() : null,
lastOutcome: result.outcome,
lastRunAt: runAt,
lastDurationMs: result.durationMs,
lastError: failed ? (result.error ?? "failed") : null,
lastChanged: failed ? null : (result.changed ?? 0),
});
} catch {
// Best effort, like the self-heal outcome rows.
}
if (vault === null || (!failed && (result.changed ?? 0) === 0)) return;
try {
appendMetric(vault, {
surface: INDEX_FRESHEN_SURFACE,
runAt,
payload: {
outcome: result.outcome,
duration_ms: result.durationMs,
...(failed ? { error: result.error ?? "failed", failures } : {}),
...(!failed ? { changed: result.changed ?? 0 } : {}),
},
});
} catch {
// Same: metrics are diagnostics, never a reason to fail.
}
}
/** What `o2b search status` and the doctor show about freshen on read. */
export interface FreshenStatus {
/** 0 when freshening is off. */
readonly intervalSeconds: number;
readonly indexAgeSeconds: number | null;
readonly state: FreshenState;
/** The backoff end, only while it is still in the future. */
readonly activeBackoffUntil: string | null;
/**
* The live measured index-behind total (t_e4438152): documents the
* next incremental run would add, update or delete, measured NOW.
* Passed in by the caller that chose to pay the walk - this stays a
* pure state-file reader, so the doctor's freshen check (which reads
* the state file on its own) picks up no walk cost. Null means not
* measured - a failed measurement is not a measurement, never zero.
*/
readonly indexBehind: number | null;
}
export function freshenStatus(
config: ResolvedSearchConfig,
lastIndexedAt: string | null,
nowMs: number = Date.now(),
indexBehind: number | null = null,
): FreshenStatus {
const state = readFreshenState(dirname(config.dbPath));
const backoffMs = state.backoffUntil === null ? Number.NaN : Date.parse(state.backoffUntil);
return Object.freeze({
intervalSeconds: config.freshen?.intervalSeconds ?? 0,
indexAgeSeconds: indexAgeSeconds(lastIndexedAt, nowMs),
state,
activeBackoffUntil: Number.isFinite(backoffMs) && backoffMs > nowMs ? state.backoffUntil : null,
indexBehind,
});
}
/** The status lines, aligned with the rest of `o2b search status`. */
export function renderFreshenStatus(s: FreshenStatus): string[] {
const lines = [
`freshen: ${s.intervalSeconds > 0 ? `every ${s.intervalSeconds}s` : "off"}`,
`index_age: ${s.indexAgeSeconds === null ? "(unknown)" : `${s.indexAgeSeconds}s`}`,
// The label stays within the 19 columns every status label fits in.
`index_behind: ${
s.indexBehind === null
? "(not measured)"
: `${s.indexBehind} doc${s.indexBehind === 1 ? "" : "s"}`
}`,
];
const st = s.state;
if (st.lastOutcome === "completed") {
lines.push(`last_freshen: completed ${st.lastRunAt} (${st.lastChanged ?? 0} changed)`);
} else if (st.lastOutcome === "failed") {
lines.push(
`last_freshen: failed ${st.lastRunAt} (${st.failures} in a row): ${st.lastError}`,
);
} else {
lines.push("last_freshen: (none)");
}
// The label stays within the 19 columns every status label fits in.
if (s.activeBackoffUntil !== null) {
lines.push(`freshen_backoff: until ${s.activeBackoffUntil}`);
}
return lines;
}
/** The `freshen` object of `o2b search status --json`. */
export function serializeFreshenStatus(s: FreshenStatus): Record<string, unknown> {
return {
interval_s: s.intervalSeconds,
index_age_s: s.indexAgeSeconds,
index_behind: s.indexBehind,
last_outcome: s.state.lastOutcome,
last_run_at: s.state.lastRunAt,
last_changed: s.state.lastChanged,
last_error: s.state.lastError,
failures: s.state.failures,
backoff_until: s.activeBackoffUntil,
};
}