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
/**
* `o2b brain maintenance` CLI surface (t_166d1226): run executes
* dream + reindex under the lease (exit 0 even on a gate skip - cron
* must not alarm on a quiet hour), status renders lease + journal.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
appendFileSync,
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { MAINTENANCE_USAGE, VERB_HELP } from "../../src/cli/brain/help-text.ts";
import {
MAINTENANCE_EXIT,
formatSpendBanner,
maintenanceExitCode,
renderTaskLine,
} from "../../src/cli/brain/verbs/maintenance.ts";
import {
LANE_TASK,
LANE_TASKS,
type MaintenanceSpendReceipt,
type MaintenanceTaskResult,
} from "../../src/core/brain/maintenance/lane.ts";
import {
appendJournal,
listJournal,
MAINTENANCE_JOURNAL_CAP,
MAINTENANCE_SPEND_METRIC,
MAINTENANCE_VERDICT,
} from "../../src/core/brain/maintenance/journal.ts";
import { listMetrics } from "../../src/core/brain/metrics.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import { writeFrontmatterAtomic } from "../../src/core/vault.ts";
import { currentLease, MAINTENANCE_LEASE_NAME } from "../../src/core/brain/maintenance/lease.ts";
import { MAINTENANCE_EMBEDDINGS_ENV } from "../../src/core/config.ts";
import {
isEmbeddingPriceSource,
type EmbeddingPriceSource,
} from "../../src/core/search/embeddings/pricing.ts";
import { MAINTENANCE_FAILURE_STREAK_LIMIT_DEFAULT } from "../../src/core/brain/policy/blocks/maintenance.ts";
import { sqliteVecLoadable } from "../helpers/sqlite-vec.ts";
import { startFakeHttp, type FakeHttp } from "../helpers/fake-http.ts";
import { FAKE_PROVIDER_KEY } from "../helpers/fake-credentials.ts";
import { homeEnv } from "../helpers/platform.ts";
import { runCli } from "../helpers/run-cli.ts";
import { useUnshardedLegacyLog } from "../helpers/device-id.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
/**
* Whether `sqlite-vec` loaded in THIS process: the spend-surface tests
* need a vector index, so an unloadable extension skips them rather than
* failing on an environment fact (same guard the vector-backfill CLI
* tests declare).
*/
const VEC_LOADABLE = sqliteVecLoadable();
let tmp: string;
let vault: string;
let configPath: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-cli-maint-"));
vault = join(tmp, "vault");
mkdirSync(join(vault, "Brain"), { recursive: true });
configPath = join(tmp, "config.yaml");
writeFileSync(configPath, `vault: ${vault}\n`);
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("run executes dream and reindex; status shows the journal", async () => {
const init = await runCli(["brain", "init", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(init.returncode).toBe(0);
const run = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(run.returncode).toBe(0);
const ran = JSON.parse(run.stdout) as {
verdict: string;
tasks: Array<{ name: string; ok: boolean }>;
};
expect(ran.verdict).toBe("run");
// The lane's population, not a hand-copied list: a fifth task is added
// to LANE_TASKS in one place or not at all (the drift the surface-parity
// census exists for).
expect(ran.tasks.map((t) => t.name).toSorted()).toEqual([...LANE_TASKS].toSorted());
expect(ran.tasks.every((t) => t.ok)).toBe(true);
expect(existsSync(join(vault, ".open-second-brain", "maintenance-runs.jsonl"))).toBe(true);
const status = await runCli(["brain", "maintenance", "status", "--vault", vault, "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(status.returncode).toBe(0);
const state = JSON.parse(status.stdout) as {
lease: unknown;
journal: Array<{ verdict: string }>;
};
expect(state.lease).toBeNull();
expect(state.journal.length).toBeGreaterThanOrEqual(2);
});
test("a window that excludes the current hour skips with exit 0", async () => {
const init = await runCli(["brain", "init", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(init.returncode).toBe(0);
// A degenerate 1-hour window that the current hour cannot match:
// pick the hour after next in UTC, exclusive end one hour later.
const hour = (new Date().getUTCHours() + 2) % 24;
const end = (hour + 1) % 24;
const run = await runCli(
["brain", "maintenance", "run", "--window", `${hour}-${end}`, "--vault", vault, "--json"],
{ env: { OPEN_SECOND_BRAIN_CONFIG: configPath } },
);
expect(run.returncode).toBe(0);
expect(JSON.parse(run.stdout).verdict).toBe("skipped:window");
});
test("a malformed window is a usage error", async () => {
const result = await runCli(
["brain", "maintenance", "run", "--window", "25-3", "--vault", vault],
{ env: { OPEN_SECOND_BRAIN_CONFIG: configPath } },
);
expect(result.returncode).toBe(2);
});
/**
* The per-test config, which alone names the test vault. The lane mints per-device state and runs custom tasks from the home
* directory, so every lane-running child gets a home of its own under
* the test's temp dir rather than the runner's.
*/
function baseEnv(): Record<string, string> {
const home = join(tmp, "home");
mkdirSync(home, { recursive: true });
return { OPEN_SECOND_BRAIN_CONFIG: configPath, ...homeEnv(home) };
}
/** The local provider is configured, model-free and price-free, and the lane is opted in. */
function localSemanticEnv(): Record<string, string> {
return {
OPEN_SECOND_BRAIN_CONFIG: configPath,
OPEN_SECOND_BRAIN_SEARCH_SEMANTIC: "true",
OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER: "local",
[MAINTENANCE_EMBEDDINGS_ENV]: "true",
};
}
/** Seed `task`'s journal with the failures that trip the streak refusal. */
function seedFailureStreak(task: string, count: number): void {
const path = join(vault, ".open-second-brain", "maintenance-runs.jsonl");
mkdirSync(dirname(path), { recursive: true });
for (let i = 0; i < count; i++) {
appendFileSync(
path,
JSON.stringify({
ts: new Date(Date.now() - (count - i) * 86_400_000).toISOString(),
holder: `seed@${i}`,
verdict: "run",
task,
ok: false,
duration_ms: 1,
error: "seeded failure",
}) + "\n",
);
}
}
test("a refused task is reported as refused, with its own exit code", async () => {
const init = await runCli(["brain", "init", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(init.returncode).toBe(0);
seedFailureStreak("dream", MAINTENANCE_FAILURE_STREAK_LIMIT_DEFAULT);
const run = await runCli(["brain", "maintenance", "run", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
// Not 1: nothing was attempted, so nothing failed - and not 0, because
// a heavy pass is standing refused and only an operator can change that.
expect(run.returncode).toBe(MAINTENANCE_EXIT.refused);
expect(run.stdout).toContain("dream: REFUSED");
expect(run.stdout).not.toContain("dream: FAILED");
// The healthy tasks still ran under the same lease.
expect(run.stdout).toContain("reindex: ok");
});
test("--retry runs the refused task and names an unknown task as a usage error", async () => {
const init = await runCli(["brain", "init", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(init.returncode).toBe(0);
seedFailureStreak("dream", MAINTENANCE_FAILURE_STREAK_LIMIT_DEFAULT);
const typo = await runCli(
["brain", "maintenance", "run", "--retry", "dreams", "--vault", vault],
{ env: { OPEN_SECOND_BRAIN_CONFIG: configPath } },
);
expect(typo.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(typo.stderr).toContain("dreams");
const retried = await runCli(
["brain", "maintenance", "run", "--retry", "dream", "--vault", vault, "--json"],
{ env: { OPEN_SECOND_BRAIN_CONFIG: configPath } },
);
expect(retried.returncode).toBe(MAINTENANCE_EXIT.ok);
const payload = JSON.parse(retried.stdout) as {
tasks: Array<{ name: string; ok: boolean; refused?: boolean }>;
};
const dream = payload.tasks.find((t) => t.name === "dream");
expect(dream?.refused).toBeUndefined();
expect(dream?.ok).toBe(true);
});
/** `run --cron-template` with `extra` flags against the test vault. */
function recipe(extra: ReadonlyArray<string>) {
return runCli(["brain", "maintenance", "run", "--cron-template", "--vault", vault, ...extra], {
env: baseEnv(),
});
}
describe("run --cron-template prints the lane recipe and writes nothing", () => {
test("prints a recipe naming the job and the vault; no lease, no journal", async () => {
const printed = await recipe([]);
expect(printed.returncode).toBe(MAINTENANCE_EXIT.ok);
expect(printed.stdout).toContain("osb-maintenance");
expect(printed.stdout).toContain(`o2b brain maintenance run --vault '${vault}' --json`);
expect(printed.stdout).toContain("0 */1 * * *");
// Returned before the lease and the journal: printing a recipe is not
// a lane pass, so it must leave no trace a later status would read.
expect(currentLease(vault, { name: MAINTENANCE_LEASE_NAME, now: new Date() })).toBeNull();
expect(listJournal(vault, MAINTENANCE_JOURNAL_CAP)).toEqual([]);
expect(existsSync(join(vault, ".open-second-brain", "maintenance-runs.jsonl"))).toBe(false);
});
test("a bad interval or format is the lane's usage code, with the kernel's message", async () => {
const seconds = await recipe(["--interval", "30s"]);
expect(seconds.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(seconds.stderr).toContain("second-level intervals are not supported");
const months = await recipe(["--interval", "90d"]);
expect(months.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(months.stderr).toContain("an interval of 90 days cannot be expressed");
const launchd = await recipe(["--format", "launchd"]);
expect(launchd.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(launchd.stderr).toContain("systemd");
});
test("a lane-run flag beside --cron-template is the usage code, named, and writes nothing", async () => {
const forced = await recipe(["--force"]);
expect(forced.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(forced.stderr).toContain(
"--cron-template prints the recipe only and does not take --force (a lane-run flag)",
);
expect(forced.stdout).toBe("");
const several = await recipe(["--json", "--retry", "dream"]);
expect(several.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(several.stderr).toContain("--retry, --json");
expect(currentLease(vault, { name: MAINTENANCE_LEASE_NAME, now: new Date() })).toBeNull();
expect(listJournal(vault, MAINTENANCE_JOURNAL_CAP)).toEqual([]);
});
test("the window is validated and carried into the printed body", async () => {
const bad = await recipe(["--window", "25-3"]);
expect(bad.returncode).toBe(MAINTENANCE_EXIT.usage);
const windowed = await recipe(["--window", "3-5", "--tz", "Europe/Berlin"]);
expect(windowed.returncode).toBe(MAINTENANCE_EXIT.ok);
expect(windowed.stdout).toContain("--window 3-5");
expect(windowed.stdout).toContain("--tz Europe/Berlin");
const unwindowed = await recipe([]);
expect(unwindowed.stdout).not.toContain("--window");
});
test("status refuses --cron-template", async () => {
const status = await runCli(
["brain", "maintenance", "status", "--cron-template", "--vault", vault],
{ env: baseEnv() },
);
expect(status.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(status.stderr).toContain("--cron-template");
});
test("--format systemd prints a user timer at the default interval", async () => {
const timer = await recipe(["--format", "systemd"]);
expect(timer.returncode).toBe(MAINTENANCE_EXIT.ok);
expect(timer.stdout).toContain("OnUnitActiveSec=1h");
expect(timer.stdout).toContain(`o2b brain maintenance run --vault '${vault}' --json`);
});
});
/** Rewrite the per-test config with `lines` after the vault key. */
function writeConfig(lines: ReadonlyArray<string>): void {
writeFileSync(configPath, [`vault: ${vault}`, ...lines].join("\n") + "\n");
}
async function initVault(): Promise<void> {
const init = await runCli(["brain", "init", "--vault", vault], { env: baseEnv() });
expect(init.returncode).toBe(0);
}
describe("declared custom tasks ride the lane", () => {
test("with the switch on, run reports the custom row after the built-ins", async () => {
writeConfig(["maintenance_custom_tasks: true", "maintenance_custom_tidy: exit 0"]);
await initVault();
const run = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"], {
env: baseEnv(),
});
expect(run.returncode).toBe(MAINTENANCE_EXIT.ok);
const payload = JSON.parse(run.stdout) as { tasks: Array<{ name: string; ok: boolean }> };
const tidy = payload.tasks.find((t) => t.name === "custom:tidy");
expect(tidy?.ok).toBe(true);
expect(payload.tasks.map((t) => t.name).toSorted()).toEqual(
[...LANE_TASKS, "custom:tidy"].toSorted(),
);
});
test("--retry accepts a declared custom task and names an undeclared one", async () => {
writeConfig(["maintenance_custom_tasks: true", "maintenance_custom_tidy: exit 0"]);
await initVault();
seedFailureStreak("custom:tidy", MAINTENANCE_FAILURE_STREAK_LIMIT_DEFAULT);
const refused = await runCli(["brain", "maintenance", "run", "--vault", vault], {
env: baseEnv(),
});
expect(refused.returncode).toBe(MAINTENANCE_EXIT.refused);
expect(refused.stdout).toContain("custom:tidy: REFUSED");
const unknown = await runCli(
["brain", "maintenance", "run", "--retry", "custom:nope", "--vault", vault],
{ env: baseEnv() },
);
expect(unknown.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(unknown.stderr).toContain("custom:nope");
expect(unknown.stderr).toContain("custom:tidy");
const retried = await runCli(
["brain", "maintenance", "run", "--retry", "custom:tidy", "--vault", vault, "--json"],
{ env: baseEnv() },
);
expect(retried.returncode).toBe(MAINTENANCE_EXIT.ok);
const payload = JSON.parse(retried.stdout) as {
tasks: Array<{ name: string; ok: boolean; refused?: boolean }>;
};
const tidy = payload.tasks.find((t) => t.name === "custom:tidy");
expect(tidy?.refused).toBeUndefined();
expect(tidy?.ok).toBe(true);
});
test("a bad declaration is named on stderr and the valid tasks still run", async () => {
writeConfig([
"maintenance_custom_tasks: true",
"maintenance_custom_tidy: exit 0",
"maintenance_custom_Bad: exit 0",
]);
await initVault();
const run = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"], {
env: baseEnv(),
});
expect(run.stderr).toContain("custom task refused:");
expect(run.stderr).toContain("Bad");
const payload = JSON.parse(run.stdout) as {
tasks: MaintenanceTaskResult[];
};
// A refused declaration journals nothing and is not a failed attempt:
// the run that only refused it exits 0.
expect(run.returncode).toBe(0);
expect(payload.tasks.find((t) => t.name === "custom:Bad")).toBeUndefined();
expect(payload.tasks.find((t) => t.name === "custom:tidy")?.ok).toBe(true);
});
test("status shows custom rows, and says when declared tasks are switched off", async () => {
writeConfig(["maintenance_custom_tasks: true", "maintenance_custom_tidy: exit 0"]);
await initVault();
const run = await runCli(["brain", "maintenance", "run", "--vault", vault], {
env: baseEnv(),
});
expect(run.returncode).toBe(MAINTENANCE_EXIT.ok);
const on = await runCli(["brain", "maintenance", "status", "--vault", vault], {
env: baseEnv(),
});
expect(on.stdout).toContain("custom:tidy ok");
expect(on.stdout).not.toContain("custom tasks declared but maintenance_custom_tasks is off");
writeConfig(["maintenance_custom_tidy: exit 0"]);
const off = await runCli(["brain", "maintenance", "status", "--vault", vault], {
env: baseEnv(),
});
expect(off.returncode).toBe(MAINTENANCE_EXIT.ok);
expect(off.stdout).toContain("custom tasks declared but maintenance_custom_tasks is off");
});
});
/** A clean task row, as the lane produces it. */
function okRow(name: MaintenanceTaskResult["name"]): MaintenanceTaskResult {
return { name, ok: true, duration_ms: 1 };
}
/** A deterministic task fault: the pass ran and failed for a named reason. */
function errorRow(name: MaintenanceTaskResult["name"]): MaintenanceTaskResult {
return { name, ok: false, duration_ms: 5, error: "deterministic fault" };
}
/** A safeguard-deadline row: the pass was killed mid-run, its outcome unmeasured. */
function timedOutRow(name: MaintenanceTaskResult["name"]): MaintenanceTaskResult {
return {
name,
ok: false,
duration_ms: 120_001,
error: `${name} exceeded its safeguard timeout of 120000ms - aborted at a checkpoint`,
timed_out: true,
};
}
/** A streak-refusal row: the task never ran. */
function refusedRow(name: MaintenanceTaskResult["name"]): MaintenanceTaskResult {
return {
name,
ok: false,
duration_ms: 0,
error: "refused: 3 consecutive journaled failures",
refused: true,
failure_streak: 3,
};
}
describe("brain maintenance --help", () => {
test("opens with the verb's own usage line and names custom tasks and the recipe", () => {
const help = VERB_HELP["maintenance"]!;
expect(help.startsWith(`${MAINTENANCE_USAGE}\n`)).toBe(true);
for (const flag of [
"--cron-template",
"--interval",
"--format",
"--force-cost",
"--progress",
]) {
expect(MAINTENANCE_USAGE).toContain(flag);
}
expect(help).toContain("custom:<name>");
expect(help).toContain("maintenance_custom_tasks: true");
});
});
describe("maintenanceExitCode", () => {
test("a clean run exits 0 and a deterministic task fault exits 1", () => {
expect(maintenanceExitCode([okRow(LANE_TASK.dream), okRow(LANE_TASK.reindex)])).toBe(
MAINTENANCE_EXIT.ok,
);
expect(maintenanceExitCode([errorRow(LANE_TASK.reindex)])).toBe(MAINTENANCE_EXIT.failed);
});
test("a timed-out pass exits 6: the run could not find out", () => {
// The safeguard killed the task mid-run, so its outcome is unmeasured -
// the same "could not find out" `SEARCH_CHECK_EXIT` and `DOCTOR_EXIT`
// already spend 6 on, not the proved failure 1 names.
expect(maintenanceExitCode([timedOutRow(LANE_TASK.bridges)])).toBe(
MAINTENANCE_EXIT.probeIncomplete,
);
// The healthy tasks around it do not make the run clean.
expect(maintenanceExitCode([timedOutRow(LANE_TASK.bridges), okRow(LANE_TASK.clusters)])).toBe(
MAINTENANCE_EXIT.probeIncomplete,
);
});
test("a timed-out custom task exits 1: the streak counts its hang as a failure", () => {
expect(maintenanceExitCode([timedOutRow("custom:tidy")])).toBe(MAINTENANCE_EXIT.failed);
expect(maintenanceExitCode([timedOutRow("custom:tidy"), timedOutRow(LANE_TASK.bridges)])).toBe(
MAINTENANCE_EXIT.failed,
);
});
test("a refusal-only run still exits 7", () => {
expect(maintenanceExitCode([refusedRow(LANE_TASK.dream), okRow(LANE_TASK.reindex)])).toBe(
MAINTENANCE_EXIT.refused,
);
});
test("a proved failure outranks an unmeasured pass; an unmeasured pass outranks a refusal", () => {
// error + timeout -> 1: the specific proved failure must not be masked.
expect(maintenanceExitCode([errorRow(LANE_TASK.dream), timedOutRow(LANE_TASK.reindex)])).toBe(
MAINTENANCE_EXIT.failed,
);
// timeout + refusal -> 6: something ran, so the run outranks a refusal
// (which records that nothing did).
expect(maintenanceExitCode([timedOutRow(LANE_TASK.reindex), refusedRow(LANE_TASK.dream)])).toBe(
MAINTENANCE_EXIT.probeIncomplete,
);
});
test("the table is a table and agrees with the 6 the other surfaces already spend", () => {
const codes = Object.values(MAINTENANCE_EXIT);
expect(new Set(codes).size).toBe(codes.length);
expect(MAINTENANCE_EXIT.probeIncomplete).toBe(6);
});
});
describe("renderTaskLine", () => {
test("a timed-out pass is TIMED OUT, not FAILED: the safeguard killed it mid-run", () => {
const line = renderTaskLine(timedOutRow(LANE_TASK.bridges));
expect(line).toContain("bridges: TIMED OUT");
expect(line).not.toContain("FAILED");
// The error names the safeguard and its budget; the line carries it.
expect(line).toContain("120000ms");
expect(line).toContain("in 120001ms");
});
test("a refusal, a deterministic failure and a pass keep their existing renderings", () => {
expect(renderTaskLine(refusedRow(LANE_TASK.dream))).toContain("dream: REFUSED");
expect(renderTaskLine(errorRow(LANE_TASK.reindex))).toContain("reindex: FAILED");
expect(renderTaskLine(okRow(LANE_TASK.clusters))).toContain("clusters: ok in 1ms");
});
test("a receipt rides the line as a parenthetical", () => {
const receipt: MaintenanceSpendReceipt = {
model: "text-embedding-3-small",
tokens: 38110,
estimatedUsd: 0.0076,
forced: false,
};
const line = renderTaskLine({ ...okRow(LANE_TASK.reindex), receipt });
expect(line).toContain("reindex: ok in 1ms");
expect(line).toContain("(tokens=38110, estimatedUsd=0.0076, model=text-embedding-3-small)");
});
test("a receipt for an unknown price says so instead of a dollar figure", () => {
const receipt: MaintenanceSpendReceipt = {
model: "zembed-1",
tokens: 120,
estimatedUsd: null,
forced: true,
priceSource: "unknown",
};
const line = renderTaskLine({ ...okRow(LANE_TASK.reindex), receipt });
expect(line).toContain("(tokens=120, price unknown, model=zembed-1)");
expect(line).not.toContain("$0");
});
});
describe("the journal listing", () => {
test("a receipt written before price sources renders as unrecorded, its estimate as written", async () => {
const init = await runCli(["brain", "init", "--vault", vault], { env: baseEnv() });
expect(init.returncode).toBe(0);
appendJournal(vault, {
ts: "2026-09-01T00:00:00Z",
holder: "test",
verdict: MAINTENANCE_VERDICT.run,
task: LANE_TASK.reindex,
ok: true,
receipt: {
model: "text-embedding-3-small",
tokens: 500,
estimatedUsd: 0.0123,
forced: false,
},
});
appendJournal(vault, {
ts: "2026-09-02T00:00:00Z",
holder: "test",
verdict: MAINTENANCE_VERDICT.run,
task: LANE_TASK.reindex,
ok: true,
receipt: {
model: "zembed-1",
tokens: 40,
estimatedUsd: null,
forced: true,
priceSource: "unknown",
},
});
const status = await runCli(["brain", "maintenance", "status", "--vault", vault], {
env: baseEnv(),
});
expect(status.returncode).toBe(0);
expect(status.stdout).toContain(
"(tokens=500, estimatedUsd=0.0123, model=text-embedding-3-small, price_source=unrecorded)",
);
expect(status.stdout).toContain(
"(tokens=40, price unknown, model=zembed-1, price_source=unknown)",
);
});
});
describe("a journaled receipt without a numeric estimate", () => {
test("reads price unknown and never breaks the listing", async () => {
const init = await runCli(["brain", "init", "--vault", vault], { env: baseEnv() });
expect(init.returncode).toBe(0);
// Rows another build, another device's shard or a hand edit could
// write: the journal read casts them, so the listing must not trust
// the estimate's type.
const receipts = [
{ model: "m-absent", tokens: 3, forced: false },
{ model: "m-string", tokens: 4, forced: false, estimatedUsd: "x" },
] as unknown as ReadonlyArray<MaintenanceSpendReceipt>;
for (const [i, receipt] of receipts.entries()) {
appendJournal(vault, {
ts: `2026-09-0${i + 4}T00:00:00Z`,
holder: "test",
verdict: MAINTENANCE_VERDICT.run,
task: LANE_TASK.reindex,
ok: true,
receipt,
});
}
const status = await runCli(["brain", "maintenance", "status", "--vault", vault], {
env: baseEnv(),
});
expect(status.returncode).toBe(0);
expect(status.stdout).toContain(
"(tokens=3, price unknown, model=m-absent, price_source=unrecorded)",
);
expect(status.stdout).toContain(
"(tokens=4, price unknown, model=m-string, price_source=unrecorded)",
);
});
});
describe("a receipt whose price source this build does not know", () => {
test("renders as unrecorded, never as the stray value", async () => {
expect(isEmbeddingPriceSource("vendor")).toBe(false);
const init = await runCli(["brain", "init", "--vault", vault], { env: baseEnv() });
expect(init.returncode).toBe(0);
appendJournal(vault, {
ts: "2026-09-03T00:00:00Z",
holder: "test",
verdict: MAINTENANCE_VERDICT.run,
task: LANE_TASK.reindex,
ok: true,
receipt: {
model: "voyage-3",
tokens: 70,
estimatedUsd: 0.0001,
forced: false,
priceSource: "vendor" as EmbeddingPriceSource,
},
});
const status = await runCli(["brain", "maintenance", "status", "--vault", vault], {
env: baseEnv(),
});
expect(status.returncode).toBe(0);
expect(status.stdout).toContain("model=voyage-3, price_source=unrecorded)");
expect(status.stdout).not.toContain("vendor");
});
});
describe("formatSpendBanner", () => {
test("names the model, the pending census and the gate - including a zero gate", () => {
expect(
formatSpendBanner(
{
model: "text-embedding-3-small",
pendingChunks: 214,
tokens: 1,
estimatedUsd: 0.011,
priceSource: "builtin",
blocked: false,
reason: null,
},
0,
),
).toBe(
"embedding spend: model text-embedding-3-small, 214 chunks pending, " +
"estimated $0.0110 (gate: off)",
);
expect(
formatSpendBanner(
{
model: null,
pendingChunks: 1,
tokens: 0,
estimatedUsd: 0,
priceSource: "builtin",
blocked: false,
reason: null,
},
0.5,
),
).toBe("embedding spend: model unknown, 1 chunks pending, estimated $0.0000 (gate: $0.5000)");
});
test("an unknown price prints price unknown, never a dollar figure", () => {
expect(
formatSpendBanner(
{
model: "zembed-1",
pendingChunks: 3,
tokens: 9,
estimatedUsd: null,
priceSource: "unknown",
blocked: true,
reason: "unpriced",
},
0.5,
),
).toBe("embedding spend: model zembed-1, 3 chunks pending, price unknown (gate: $0.5000)");
});
});
/** Initialize the vault, drop one note in, and index it keyword-only. */
async function seedPendingChunks(): Promise<void> {
const init = await runCli(["brain", "init", "--vault", vault], { env: baseEnv() });
expect(init.returncode).toBe(0);
writeFileSync(
join(vault, "Brain", "note.md"),
"# note\n\nprose long enough to cut at least one chunk for the index.\n",
);
const indexed = await runCli(["search", "index", "--vault", vault], { env: baseEnv() });
expect(indexed.returncode).toBe(0);
}
describe("the spend surface end to end", () => {
test.skipIf(!VEC_LOADABLE)(
"a semantic lane announces spend before the pass and receipts it after",
async () => {
await seedPendingChunks();
const run = await runCli(["brain", "maintenance", "run", "--vault", vault], {
env: localSemanticEnv(),
});
expect(run.returncode).toBe(0);
expect(run.stdout).toContain("embedding spend: model hashing-ngram-v1");
expect(run.stdout).toContain("chunks pending");
expect(run.stdout).toContain("(gate: off)");
expect(run.stdout).toMatch(
/reindex: ok in \d+ms \(tokens=\d+, estimatedUsd=0\.0000, model=hashing-ngram-v1\)/,
);
},
);
test.skipIf(!VEC_LOADABLE)(
"--json carries banner and receipt; a run with nothing pending reports neither",
async () => {
await seedPendingChunks();
const first = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"], {
env: localSemanticEnv(),
});
expect(first.returncode).toBe(0);
const payload = JSON.parse(first.stdout) as {
spend?: {
banner: {
model: string;
pendingChunks: number;
estimatedUsd: number;
priceSource: string;
gateUsd: number;
};
receipt: MaintenanceSpendReceipt;
};
tasks: Array<{ name: string; ok: boolean; receipt?: MaintenanceSpendReceipt }>;
};
expect(payload.spend?.banner.model).toBe("hashing-ngram-v1");
expect(payload.spend?.banner.pendingChunks).toBeGreaterThan(0);
expect(payload.spend?.banner.gateUsd).toBe(0);
const reindex = payload.tasks.find((t) => t.name === "reindex");
expect(reindex?.ok).toBe(true);
expect(payload.spend?.receipt).toEqual(reindex?.receipt);
expect(payload.spend?.receipt.tokens).toBeGreaterThan(0);
expect(payload.spend?.receipt.forced).toBe(false);
// Who stated the price rides the banner, the receipt and the metric.
expect(payload.spend?.banner.priceSource).toBe("builtin");
expect(payload.spend?.receipt.priceSource).toBe("builtin");
const metric = listMetrics(vault, { surface: MAINTENANCE_SPEND_METRIC }).at(-1);
expect(metric?.payload["price_source"]).toBe("builtin");
// The receipt the lane journaled agrees with the row it reported.
const status = await runCli(["brain", "maintenance", "status", "--vault", vault, "--json"], {
env: baseEnv(),
});
expect(status.returncode).toBe(0);
const state = JSON.parse(status.stdout) as {
journal: Array<{ task?: string; receipt?: MaintenanceSpendReceipt }>;
};
expect(state.journal.find((e) => e.task === "reindex")?.receipt).toEqual(
payload.spend?.receipt,
);
// The next run's census is over the index BEFORE its walk, and
// every embedded chunk the first pass left cannot spend again: the
// banner is absent. (The receipt may still be present - the lane's
// dream writes pages this run's walk then indexes, and the phase
// prices what ITS census finds - which is exactly why the receipt
// is the phase's own number and not the banner's.)
const second = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"], {
env: localSemanticEnv(),
});
expect(second.returncode).toBe(0);
const secondPayload = JSON.parse(second.stdout) as {
spend?: { banner?: unknown };
tasks: Array<{ name: string; receipt?: unknown }>;
};
expect(secondPayload.spend?.banner).toBeUndefined();
},
);
test.skipIf(!VEC_LOADABLE)(
"without the opt-in a remote provider and an off gate stay keyword-only and spend nothing",
async () => {
let server: FakeHttp | null = null;
try {
server = await startFakeHttp();
await seedPendingChunks();
const remoteEnv = {
OPEN_SECOND_BRAIN_CONFIG: configPath,
OPEN_SECOND_BRAIN_SEARCH_SEMANTIC: "true",
OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER: "openai-compat",
OPEN_SECOND_BRAIN_EMBEDDING_BASE_URL: server.url,
OPEN_SECOND_BRAIN_EMBEDDING_MODEL: "text-embedding-3-small",
OPEN_SECOND_BRAIN_EMBEDDING_KEY: FAKE_PROVIDER_KEY,
OPEN_SECOND_BRAIN_EMBEDDING_COST_GATE: "0",
};
const run = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"], {
env: remoteEnv,
});
expect(run.returncode).toBe(0);
const payload = JSON.parse(run.stdout) as {
spend?: unknown;
tasks: Array<{ name: string; ok: boolean; receipt?: unknown }>;
};
const reindex = payload.tasks.find((t) => t.name === LANE_TASK.reindex);
expect(reindex?.ok).toBe(true);
expect(reindex?.receipt).toBeUndefined();
expect(payload.spend).toBeUndefined();
expect(server.callCount()).toBe(0);
} finally {
await server?.close();
}
},
);
test.skipIf(!VEC_LOADABLE)(
"a positive gate refuses the pass unforced; --force-cost flags the receipt",
async () => {
let server: FakeHttp | null = null;
try {
server = await startFakeHttp();
await seedPendingChunks();
const pricedEnv = () => ({
OPEN_SECOND_BRAIN_CONFIG: configPath,
OPEN_SECOND_BRAIN_SEARCH_SEMANTIC: "true",
OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER: "openai-compat",
OPEN_SECOND_BRAIN_EMBEDDING_BASE_URL: server!.url,
OPEN_SECOND_BRAIN_EMBEDDING_MODEL: "text-embedding-3-small",
OPEN_SECOND_BRAIN_EMBEDDING_KEY: FAKE_PROVIDER_KEY,
OPEN_SECOND_BRAIN_EMBEDDING_COST_GATE: "0.000001",
[MAINTENANCE_EMBEDDINGS_ENV]: "true",
});
const blocked = await runCli(["brain", "maintenance", "run", "--vault", vault], {
env: pricedEnv(),
});
expect(blocked.returncode).toBe(MAINTENANCE_EXIT.failed);
expect(blocked.stdout).toContain("embedding spend: model text-embedding-3-small");
expect(blocked.stdout).toContain("reindex: FAILED");
// The refusal is the cost gate's own message, naming the ceiling
// and the remedy; a failed pass receipts nothing.
expect(blocked.stdout).toContain("exceeds embedding_cost_gate_usd");
expect(blocked.stdout).toContain("Re-run with --force-cost");
// Refused BEFORE the provider was contacted: the gate spends nothing.
expect(server.callCount()).toBe(0);
const forced = await runCli(
["brain", "maintenance", "run", "--vault", vault, "--force-cost", "--json"],
{ env: pricedEnv() },
);
expect(forced.returncode).toBe(0);
const payload = JSON.parse(forced.stdout) as {
spend?: { receipt?: MaintenanceSpendReceipt };
tasks: Array<{ name: string; ok: boolean; receipt?: MaintenanceSpendReceipt }>;
};
const reindex = payload.tasks.find((t) => t.name === "reindex");
expect(reindex?.ok).toBe(true);
expect(reindex?.receipt?.forced).toBe(true);
expect(payload.spend?.receipt?.forced).toBe(true);
expect(server.callCount()).toBeGreaterThan(0);
} finally {
await server?.close();
}
},
);
});
describe("the relink arm is opt-in", () => {
/**
* A bootstrapped fixture vault holding one canonical entity, one source
* page that links it, and one page-sourced signal that names nothing:
* the exact shape the relink pass heals. Returns the signal's path.
*/
function writeRelinkFixture(): string {
const entitiesDir = join(vault, "Brain", "entities", "people");
mkdirSync(entitiesDir, { recursive: true });
const now = new Date().toISOString();
writeFrontmatterAtomic(
join(entitiesDir, "ent-people-ada-lovelace.md"),
{
kind: "brain-entity",
entity_id: "ent-people-ada-lovelace",
category: "people",
name: "Ada Lovelace",
status: "active",
created_at: now,
updated_at: now,
tags: ["brain", "brain/entity"],
},
"# Ada Lovelace",
{ overwrite: true },
);
mkdirSync(join(vault, "notes"), { recursive: true });
writeFileSync(
join(vault, "notes", "meeting.md"),
"# Meeting\n\n- [[ent-people-ada-lovelace]] joined the review.\n",
"utf8",
);
writeSignal(vault, {
topic: "relink-surface",
signal: "positive",
agent: "tester",
principle: "the review concluded with five follow-ups",
created_at: now,
date: now.slice(0, 10),
slug: "relink-surface",
scope: "writing",
source: ["[[notes/meeting.md]]"],
// The pass's in-scope stamp: relink reads only server-derived
// sources, so the fixture signal is extraction-written.
source_type: "extracted",
dedup_hash: `relink-surface-${now}`,
// The placeholder Raw section: the shape a signal stored without a
// verbatim quote carries, and the line the relink rewrite can fill.
raw: "_(not provided)_",
});
const signalPath = join(vault, "Brain", "inbox");
const name = readdirSync(signalPath).find((f) => f.startsWith("sig-") && f.endsWith(".md"));
if (name === undefined) throw new Error("fixture signal was not written");
return join(signalPath, name);
}
test("without the flag the lane's relink task previews: it reports and writes nothing", async () => {
await initVault();
const signalPath = writeRelinkFixture();
const before = readFileSync(signalPath, "utf8");
const run = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"], {
env: baseEnv(),
});
expect(run.returncode).toBe(0);
const payload = JSON.parse(run.stdout) as {
relink?: {
apply: boolean;
signalsPageSourced: number;
anchorsAdded: number;
perSource: Array<{ source: string; signals: number; anchorsAdded: number }>;
};
};
// The unattended lane runs the relink pass as a preview and carries
// its report beside the task rows.
expect(payload.relink?.apply).toBe(false);
expect(payload.relink?.signalsPageSourced).toBe(1);
expect(payload.relink?.anchorsAdded).toBe(1);
expect(payload.relink?.perSource).toEqual([
{ source: "notes/meeting.md", signals: 1, anchorsAdded: 1 },
]);
expect(readFileSync(signalPath, "utf8")).toBe(before);
});
test("--relink-apply rewrites the stored lines and the report says what changed", async () => {
await initVault();
const signalPath = writeRelinkFixture();
const run = await runCli(
["brain", "maintenance", "run", "--relink-apply", "--vault", vault, "--json"],
{ env: baseEnv() },
);
expect(run.returncode).toBe(0);
const payload = JSON.parse(run.stdout) as {
relink?: { apply: boolean; signalsChanged: number; anchorsAdded: number };
tasks: Array<{ name: string; ok: boolean }>;
};
expect(payload.relink?.apply).toBe(true);
expect(payload.relink?.signalsChanged).toBe(1);
expect(payload.relink?.anchorsAdded).toBe(1);
expect(readFileSync(signalPath, "utf8")).toContain("entities: ent-people-ada-lovelace");
});
test("the preview arm names its report in the human output too", async () => {
await initVault();
writeRelinkFixture();
const run = await runCli(["brain", "maintenance", "run", "--vault", vault], {
env: baseEnv(),
});
expect(run.returncode).toBe(0);
expect(run.stdout).toContain("relink: would add 1 anchor(s) to 1 signal(s)");
});
test("--relink-apply is a lane-run flag: the recipe refuses it", async () => {
const refused = await recipe(["--relink-apply"]);
expect(refused.returncode).toBe(MAINTENANCE_EXIT.usage);
expect(refused.stderr).toContain("--relink-apply");
expect(listJournal(vault, MAINTENANCE_JOURNAL_CAP)).toEqual([]);
});
});