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 <run|status>` (t_166d1226): the quiet-window
* lane for heavy passes. `run` gates on the local-time window
* (--window H-H, unset = always open), recent interactive query-rate,
* host pressure, the vault's storage-capacity forecast, and the
* expiring SQLite lease, then executes dream, reindex,
* bridges, and clusters stale-first; --force bypasses the soft gates
* and every streak refusal but never the lease, while --retry <task>
* (repeatable) bypasses the streak refusal for that task alone and
* leaves every gate in force. The relink task previews the anchor
* additions it would make and rewrites the stored signal pages only
* under --relink-apply; either way its per-source report rides the run
* result. The reindex pass stays keyword-only
* unless `maintenance_embeddings` opts the lane into the embedding phase
* and the resolved config can reach a provider: then the pass announces
* its predicted spend before it runs, receipts what the phase actually
* priced after it, and --force-cost bypasses a positive embedding cost
* gate for this run alone - recorded on the receipt when it did.
* `status` renders the lease holder and recent journal. Designed as
* the cron entry point: a dead dashboard hour surfaces as
* skipped:window in the journal instead of a contended vault.
* `run --cron-template [--interval N] [--format cron|systemd]` prints
* the recipe that schedules this very verb and returns before the
* lease, the gates, the journal and the metrics: it installs nothing.
*
* Exit codes: see {@link MAINTENANCE_EXIT}.
*/
import {
createSafeguard,
OPERATION,
resolveSafeguardTimeoutMs,
} from "../../../core/brain/safeguard.ts";
import { currentLease, MAINTENANCE_LEASE_NAME } from "../../../core/brain/maintenance/lease.ts";
import {
MAINTENANCE_BUSY_MINUTES,
MAINTENANCE_BUSY_MINUTES_MAX,
MAINTENANCE_BUSY_THRESHOLD,
MAINTENANCE_BUSY_THRESHOLD_MAX,
runMaintenance,
type DailyWindow,
type LaneTask,
type LaneTaskId,
type MaintenanceTaskResult,
} from "../../../core/brain/maintenance/lane.ts";
import {
listJournal,
MAINTENANCE_JOURNAL_CAP,
recordedPriceSource,
type MaintenanceSpendReceipt,
} from "../../../core/brain/maintenance/journal.ts";
import {
customTasksOffNotice,
resolveCustomTasks,
} from "../../../core/brain/maintenance/custom-tasks.ts";
import { isCustomLaneTask } from "../../../core/brain/maintenance/custom-task-id.ts";
import { buildLaneTasks } from "../../../core/brain/maintenance/lane-tasks.ts";
import type { RelinkAnchorsReport } from "../../../core/brain/maintenance/relink-anchors-task.ts";
import { resolveAgentName } from "../../../core/config.ts";
import { CronTemplateError, parseRecipeFormat } from "../../cron-recipe.ts";
import {
DEFAULT_MAINTENANCE_INTERVAL,
MAX_WINDOW_HOUR,
parseWindowBounds,
renderMaintenanceCronTemplate,
} from "../../maintenance-cron.ts";
import {
formatEstimatedUsd,
PRICE_UNKNOWN_LABEL,
USD_DECIMALS,
} from "../../../core/search/embedding-spend.ts";
import type { EmbeddingSpendPreview } from "../../../core/search/indexer.ts";
import { resolveSearchConfig } from "../../../core/search/index.ts";
import { onInterrupt } from "../../interrupt.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import { MAINTENANCE_USAGE, brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";
/**
* What this verb's exit code says, and why a refusal has its own number.
*
* 0 covers a gate skip as well as a clean pass: a quiet hour, a busy
* vault and a loaded host are self-resolving conditions and cron must
* not alarm on them. 1 means a task was ATTEMPTED and failed for a
* reason the error names.
*
* A streak refusal is neither. Nothing ran, so 1 would report a failure
* this run did not have - the same collapse the lane's own row avoids by
* carrying no `ok` - and every failure behind the refusal was already
* reported as a 1 on the run that produced it. But 0 would tell a
* nightly cron that a lane which has stopped doing a heavy pass is
* healthy, and it is not: a refusal stands until an operator clears it,
* which is exactly the condition an exit code exists to surface.
*
* So it gets its own number, on the precedent this repository already
* set for "the run did not attempt" - `DOCTOR_EXIT.probeIncomplete` and
* `SEARCH_CHECK_EXIT.probeIncomplete`. It is not 6, because 6 means "the
* probe could not find out" on both of those surfaces and this run found
* out precisely: it names the task and the streak.
*
* A safeguard timeout is the 6 case, by the docblock's own reasoning: the
* task was killed mid-run at a checkpoint, so its outcome is unmeasured -
* precisely "could not find out", the same condition those two surfaces
* spend 6 on. Collapsing it into 1 told a nightly cron that a pass is
* broken when the only proved fact is that the pass did not finish; the
* timeout already names itself (and its budget) in the row's error.
* A `custom:<name>` task is the exception: its timeout is the command
* hanging, which the failure streak already counts as a failure, so it
* exits 1 and the exit code reads the row the way the journal does.
*
* Precedence follows `exitCodeForCheck` and `doctorExitCode`: a proved
* failure keeps the generic code even when another task timed out or was
* refused, and an attempted-but-unmeasured pass outranks a refusal
* (something ran, where a refusal records that nothing did) - so the
* specific number never masks the more basic finding.
*/
export const MAINTENANCE_EXIT = Object.freeze({
ok: 0,
failed: 1,
usage: 2,
probeIncomplete: 6,
refused: 7,
} as const);
export type MaintenanceExit = (typeof MAINTENANCE_EXIT)[keyof typeof MAINTENANCE_EXIT];
/** Flags that shape a lane run and have no place in the printed recipe. */
const RUN_ONLY_FLAGS = [
"force",
"retry",
"force-cost",
"relink-apply",
"busy-minutes",
"busy-threshold",
"agent",
"progress",
"json",
] as const;
/** A built-in task's safeguard timeout: the one row whose outcome is unmeasured. */
function builtInTimeout(t: MaintenanceTaskResult): boolean {
return t.timed_out === true && !isCustomLaneTask(t.name);
}
/**
* The run's exit code from the lane's task rows, keyed ONLY on rows the
* lane itself distinguished: `timed_out` (safeguard deadline, outcome
* unmeasured), `refused` (streak refusal, nothing ran) and the plain
* failed attempt. A timed-out row carries `ok: false` like any failure,
* so the timeout check must come off `timed_out` - reading `ok` here
* would make the exit 6 impossible to reach.
*/
export function maintenanceExitCode(tasks: ReadonlyArray<MaintenanceTaskResult>): MaintenanceExit {
if (tasks.some((t) => !t.ok && t.refused !== true && !builtInTimeout(t))) {
return MAINTENANCE_EXIT.failed;
}
if (tasks.some(builtInTimeout)) return MAINTENANCE_EXIT.probeIncomplete;
return tasks.some((t) => t.refused === true) ? MAINTENANCE_EXIT.refused : MAINTENANCE_EXIT.ok;
}
export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
force: { type: "boolean" },
retry: { type: "string-array" },
window: { type: "string" },
tz: { type: "string" },
"busy-minutes": { type: "string" },
"busy-threshold": { type: "string" },
limit: { type: "string" },
agent: { type: "string" },
progress: { type: "boolean" },
json: { type: "boolean" },
"force-cost": { type: "boolean" },
"relink-apply": { type: "boolean" },
"cron-template": { type: "boolean" },
interval: { type: "string" },
format: { type: "string" },
});
const op = positional[0];
const asJson = flags["json"] === true;
if (op !== "run" && op !== "status") {
process.stderr.write(`${MAINTENANCE_USAGE}\n`);
return MAINTENANCE_EXIT.usage;
}
const cronTemplate = flags["cron-template"] === true;
const intervalRaw = flags["interval"] as string | undefined;
const formatRaw = flags["format"] as string | undefined;
// Named, not ignored: a recipe flag on a verb that is not printing a
// recipe would otherwise be accepted and do nothing, and `status
// --cron-template` would render the journal to someone who asked for a
// schedule.
if (cronTemplate && op === "status") {
process.stderr.write(
"brain maintenance status: --cron-template applies to run only " +
"(o2b brain maintenance run --cron-template)\n",
);
return MAINTENANCE_EXIT.usage;
}
if (!cronTemplate && (intervalRaw !== undefined || formatRaw !== undefined)) {
process.stderr.write(
`brain maintenance ${op}: --interval and --format apply only with --cron-template\n`,
);
return MAINTENANCE_EXIT.usage;
}
// The reverse rule: the recipe has no place for a lane-run flag, so
// printing it with one would schedule something other than was asked.
const runOnly = cronTemplate
? RUN_ONLY_FLAGS.filter((name) => {
const value = flags[name];
return (
value !== undefined && value !== false && !(Array.isArray(value) && value.length === 0)
);
})
: [];
if (runOnly.length > 0) {
process.stderr.write(
"brain maintenance run: --cron-template prints the recipe only and does not take " +
runOnly.map((name) => `--${name}`).join(", ") +
" (a lane-run flag)\n",
);
return MAINTENANCE_EXIT.usage;
}
const { config, vault } = brainVerbContext(flags);
const now = new Date();
try {
if (op === "status") {
// Bounded on the journal's own ring size, which is also the bound
// `brain_maintenance` enforces. Unbounded here, `--limit 100000`
// was accepted on this surface and refused on the other for the
// same lane; and the ring cannot hold more than its cap anyway, so
// a larger number was never a request the journal could answer.
const limitRaw = flags["limit"] as string | undefined;
const limit = limitRaw !== undefined ? Number(limitRaw) : 10;
if (!Number.isInteger(limit) || limit < 1 || limit > MAINTENANCE_JOURNAL_CAP) {
process.stderr.write(
`brain maintenance status: --limit must be an integer between 1 and ${MAINTENANCE_JOURNAL_CAP}\n`,
);
return MAINTENANCE_EXIT.usage;
}
const lease = currentLease(vault, { name: MAINTENANCE_LEASE_NAME, now });
const journal = listJournal(vault, limit);
// Declared and switched off is said once, here, rather than left to
// look like a lane that forgot the operator's tasks.
const customOff = customTasksOffNotice(resolveCustomTasks(config ?? undefined));
if (asJson) okJson({ lease, journal, ...(customOff !== null ? { notice: customOff } : {}) });
else {
if (customOff !== null) ok(customOff);
ok(lease === null ? "lease: free" : `lease: ${lease.holder} until ${lease.expiresAt}`);
ok(`journal (${journal.length} recent):`);
for (const e of journal) {
// A refusal row names its task but records no outcome, because
// the task never ran; rendering it as FAILED would report an
// attempt that did not happen.
const outcome = e.ok === undefined ? "" : ` ${e.ok ? "ok" : "FAILED"}`;
ok(
` ${e.ts} ${e.verdict}${e.task ? ` ${e.task}${outcome}` : ""}${journalReceiptSuffix(e.receipt)}`,
);
}
}
return MAINTENANCE_EXIT.ok;
}
let window: DailyWindow | undefined;
const windowRaw = flags["window"] as string | undefined;
if (windowRaw !== undefined) {
// The recipe renderer's own parser, so the lane and the recipe it
// prints cannot disagree on what a window is.
const bounds = parseWindowBounds(windowRaw.trim());
if (bounds === null) {
process.stderr.write(
`brain maintenance run: --window must be H-H with hours 0..${MAX_WINDOW_HOUR}, got: ${windowRaw}\n`,
);
return MAINTENANCE_EXIT.usage;
}
window = { ...bounds, tz: (flags["tz"] as string | undefined) ?? "UTC" };
}
if (cronTemplate) {
// Before the busy flags, the lease and every gate: printing the
// recipe is not a lane pass, so it must leave no lease, no journal
// row and no metric behind. The window was validated above so a
// recipe never embeds a window the lane would refuse at 3 a.m.
return printMaintenanceRecipe(vault, intervalRaw, formatRaw, windowRaw, flags["tz"]);
}
// Same ceilings the MCP tool's schema declares and its handler
// enforces, read from the same constants beside the defaults: one
// lane must not accept through one door what it refuses at the other.
const busyMinutes = numberFlag(
flags["busy-minutes"],
MAINTENANCE_BUSY_MINUTES,
MAINTENANCE_BUSY_MINUTES_MAX,
);
const busyThreshold = numberFlag(
flags["busy-threshold"],
MAINTENANCE_BUSY_THRESHOLD,
MAINTENANCE_BUSY_THRESHOLD_MAX,
);
if (busyMinutes === null || busyThreshold === null) {
process.stderr.write(
`brain maintenance run: --busy-minutes must be an integer between 1 and ` +
`${MAINTENANCE_BUSY_MINUTES_MAX} and --busy-threshold between 1 and ` +
`${MAINTENANCE_BUSY_THRESHOLD_MAX}\n`,
);
return MAINTENANCE_EXIT.usage;
}
const holder =
((flags["agent"] as string | undefined)?.trim() || resolveAgentName(config)) +
`@${process.pid}`;
// Progress is opt-in, on the same terms as every other long verb: a
// sink attached by default would change the stderr of every cron
// invocation that has ever run this lane.
//
// The lane is a DISPATCHER over four long operations, not a fifth
// one, so it forwards the caller's sink to each task instead of
// counting tasks itself. A lane-owned counter would emit "1 of 4"
// and then say nothing for the length of a full reindex, which is
// the silence this release exists to remove - and it would ALSO
// double-count, because each of the four already reports its own
// stages. Forwarding needs no change to `MaintenanceTask`: the shared
// builder hands the sink to each built-in task by closure, and every
// record names the operation that emitted it, which is exactly what
// tells a reader which task the lane is currently inside. The MCP
// lane passes its sink to the same builder; a second shape would
// make the two surfaces disagree about one mechanism.
const observation =
flags["progress"] === true
? attachProgress({ command: "brain", argv: ["maintenance"], jsonRequested: asJson })
: null;
reportProgressRefusal(observation);
const laneProgress = observation?.sink !== undefined ? { onProgress: observation.sink } : {};
// Everything that can throw before the lane starts happens BEFORE the
// handle exists. `release` MUST run for every handle - it removes
// process-global listeners and settles a signal nobody acted on - and
// a throw between `onInterrupt()` and the `try` would skip it. This
// was the one verb of the six that had the ordering wrong.
const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
// Ctrl-C reaches the lane between tasks: `runMaintenance` awaits each
// one, so a signal delivered during a task is dispatched before the
// next task's first checkpoint. The lane records the abort as that
// task's failure and releases the lease in its own `finally`, so the
// vault is never left leased by a stopped run.
const interrupt = onInterrupt(OPERATION.maintenance);
// One fresh deadline per lane task: each long pass gets its own
// budget (per-op key -> global -> default), created lazily so the
// clock starts when the task starts, not when the lane is gated.
// A lane task IS one of the guarded operations - `LANE_TASK` reads its
// values out of `OPERATION` - so the task name is the budget key, and
// the union this used to retype locally is gone from both surfaces.
const laneSafeguard = (operation: LaneTask) =>
createSafeguard({
operation,
timeoutMs: resolveSafeguardTimeoutMs(operation, config ?? undefined),
signal: interrupt.signal,
});
let result: Awaited<ReturnType<typeof runMaintenance>>;
try {
// Built once and read twice - the lane runs these, and `--retry` is
// checked against their names. The task bodies live in one shared
// builder that the MCP tool calls too: the two surfaces carried
// inline copies of the four built-ins and the copies drifted, so
// neither surface spells a task any more. `taskNames` is the
// vocabulary THIS install registered - the built-ins plus any
// declared custom tasks - which is what `--retry` validates against.
//
// Inside the `try`, because the check below can return: a return
// between `onInterrupt()` and the `try` would skip `release`.
//
// Spend is opt-in (`maintenance_embeddings`): the builder decides
// whether the reindex pass may embed, announces the predicted spend
// inside the task and receipts what the phase priced. `--force-cost`
// bypasses a positive gate for this run and is recorded on the
// receipt when it did override one.
const lane = buildLaneTasks({
vault,
...(config ? { configPath: config } : {}),
searchConfig,
now,
forceCost: flags["force-cost"] === true,
relinkApply: flags["relink-apply"] === true,
safeguardFor: laneSafeguard,
signal: interrupt.signal,
...laneProgress,
...(asJson
? {}
: {
onBanner: (preview: EmbeddingSpendPreview) =>
ok(formatSpendBanner(preview, searchConfig.semantic.costGateUsd)),
}),
});
// Named, never dropped: a refused declaration journals nothing, and
// the valid tasks still run.
for (const reason of lane.custom.errors) {
process.stderr.write(`custom task refused: ${reason}\n`);
}
const registered = new Set<string>(lane.taskNames);
// Deduplicated, as the MCP tool does: naming a task twice retries it once.
const requested = [...new Set(stringArrayFlag(flags["retry"]))];
const unknownRetries = requested.filter((name) => !registered.has(name));
if (unknownRetries.length > 0) {
// Named, not ignored: a typo that silently retried nothing would
// leave the operator reading a refusal they thought they had just
// asked past.
process.stderr.write(
`brain maintenance run: --retry names no lane task: ${unknownRetries.join(", ")} ` +
`(tasks: ${lane.taskNames.join(", ")})\n`,
);
return MAINTENANCE_EXIT.usage;
}
const retryTasks = requested as LaneTaskId[];
result = await runMaintenance(vault, {
now,
holder,
force: flags["force"] === true,
...(window !== undefined ? { window } : {}),
busy: { minutes: busyMinutes, threshold: busyThreshold },
...(retryTasks.length > 0 ? { retryTasks } : {}),
...(config ? { configPath: config } : {}),
tasks: lane.tasks,
});
// The run-level spend block: the banner this run announced and the
// receipt its reindex pass returned, both absent when nothing spent.
const spend = lane.reindex.spendBlock(result.tasks);
// The relink pass's report: the preview on the default arm, the
// changes under --relink-apply. Absent while the task has not run
// (a gate skip, a refusal), so a skipped lane reports no numbers.
const relink = lane.relinkReport();
if (asJson) {
okJson({
verdict: result.verdict,
tasks: result.tasks,
// The capacity gate's report on a skipped:capacity run: the
// same block the MCP tool attaches, from the same lane result,
// so the two surfaces cannot disagree about what a skip says.
...(result.capacity !== undefined ? { capacity: result.capacity } : {}),
...(spend !== undefined ? { spend } : {}),
...(relink !== undefined ? { relink } : {}),
});
} else {
ok(`maintenance: ${result.verdict}`);
if (result.capacity !== undefined) {
ok(` capacity: ${result.capacity.tier} - ${result.capacity.remedy}`);
}
for (const t of result.tasks) ok(` ${renderTaskLine(t)}`);
if (relink !== undefined) {
ok(` relink: ${renderRelinkLine(relink)}`);
}
}
// A stopped lane is reported as stopped, not as four failures. The
// lane catches each task's abort and journals it, so without this the
// run would exit 1 - a code that says "these passes are broken" about
// passes the operator simply cancelled. The report above is written
// first either way: the journal is what makes the stop auditable.
//
// Decided INSIDE the try, before `release`: the acknowledgement and
// the exit code are the same decision, and a `release` that ran
// first would re-raise the signal this arm is in the middle of
// reporting.
if (interrupt.received() !== null) {
interrupt.acknowledge();
return interrupt.exitCode();
}
// An attempted failure outranks a refusal, and a pass the safeguard
// killed mid-run is reported as unmeasured, not broken: the table and
// its reasoning live on {@link MAINTENANCE_EXIT}.
return maintenanceExitCode(result.tasks);
} finally {
interrupt.release();
}
} catch (exc) {
const message = `maintenance ${op} failed: ${(exc as Error).message ?? exc}`;
if (asJson) {
okJson({ ok: false, message });
return MAINTENANCE_EXIT.failed;
}
return fail(message);
}
}
/**
* Print the lane's cron or systemd recipe for `vault`. A bad interval or
* format is the lane's usage code 2, not the 1 the two older recipe
* surfaces return: in this verb's vocabulary 1 means "attempted and
* failed" (see {@link MAINTENANCE_EXIT}).
*/
function printMaintenanceRecipe(
vault: string,
intervalRaw: string | undefined,
formatRaw: string | undefined,
windowRaw: string | undefined,
tzRaw: unknown,
): MaintenanceExit {
try {
const body = renderMaintenanceCronTemplate(intervalRaw ?? DEFAULT_MAINTENANCE_INTERVAL, {
vault,
format: parseRecipeFormat(formatRaw),
...(windowRaw !== undefined ? { window: windowRaw.trim() } : {}),
...(typeof tzRaw === "string" ? { tz: tzRaw } : {}),
});
process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);
return MAINTENANCE_EXIT.ok;
} catch (err) {
if (err instanceof CronTemplateError) {
process.stderr.write(`brain maintenance run: ${err.message}\n`);
return MAINTENANCE_EXIT.usage;
}
throw err;
}
}
/**
* One task row of the human run report. A refusal is rendered as neither
* `ok` nor FAILED and carries no duration - the task never ran, and
* printing `in 0ms` would describe an attempt that did not happen (the
* lane's row omits `ok` for the same reason; this line agrees with it).
* A safeguard timeout is rendered TIMED OUT rather than FAILED for the
* same reason the exit code says 6 and not 1: the pass was killed at a
* checkpoint, and the row's error - not this renderer - is what names
* the safeguard and the budget it spent. A receipt rides the line as a
* parenthetical, because the row that did the spending is the row an
* operator reads first.
*/
export function renderTaskLine(t: MaintenanceTaskResult): string {
if (t.refused === true) return `${t.name}: REFUSED (${t.error})`;
const outcome =
t.timed_out === true ? `TIMED OUT (${t.error})` : t.ok ? "ok" : `FAILED (${t.error})`;
const line = `${t.name}: ${outcome} in ${t.duration_ms}ms`;
if (t.receipt === undefined) return line;
return `${line} (${receiptFields(t.receipt)})`;
}
/** A spend receipt's tokens, estimate and model, as the task line prints them. */
function receiptFields(receipt: MaintenanceSpendReceipt): string {
// The journal read casts its rows unvalidated, so a row from another
// build or a hand edit may carry no estimate or a non-number one; that
// reads as an unknown price instead of breaking the whole listing.
const estimate =
typeof receipt.estimatedUsd === "number" && Number.isFinite(receipt.estimatedUsd)
? `estimatedUsd=${receipt.estimatedUsd.toFixed(USD_DECIMALS)}`
: PRICE_UNKNOWN_LABEL;
return `tokens=${receipt.tokens}, ${estimate}, model=${receipt.model ?? "unknown"}`;
}
/**
* A journaled receipt for the status listing: the task line's fields plus
* the recorded price source, so a row written before sources existed
* reads as unrecorded instead of as a known price.
*/
function journalReceiptSuffix(receipt: MaintenanceSpendReceipt | undefined): string {
if (receipt === undefined) return "";
return ` (${receiptFields(receipt)}, price_source=${recordedPriceSource(receipt)})`;
}
/**
* The pre-spend banner for an embedding pass about to run. The estimate
* is INFORMATION, not only a refusal message: a zero gate (the default)
* never blocks, and the operator still sees what the pass is predicted
* to spend at the resolved model. Money formatting follows the cost
* gate's own refusal message - four fixed decimals - so the banner and
* the refusal that can follow it print one spelling.
*/
export function formatSpendBanner(preview: EmbeddingSpendPreview, gateUsd: number): string {
const gate = gateUsd > 0 ? formatEstimatedUsd(gateUsd) : "off";
const estimate =
preview.estimatedUsd === null
? PRICE_UNKNOWN_LABEL
: `estimated ${formatEstimatedUsd(preview.estimatedUsd)}`;
return (
`embedding spend: model ${preview.model ?? "unknown"}, ${preview.pendingChunks} chunks pending, ` +
`${estimate} (gate: ${gate})`
);
}
/**
* One line for the relink pass's report, under the task rows. The verb
* says which arm ran: without `--relink-apply` the numbers are the
* preview's, and the sentence must not read as though signal pages
* changed.
*/
export function renderRelinkLine(report: RelinkAnchorsReport): string {
const arm = report.apply
? `added ${report.anchorsAdded} anchor(s) to ${report.signalsChanged} signal(s)`
: `would add ${report.anchorsAdded} anchor(s) to ${report.signalsChanged} signal(s)`;
return `${arm} across ${report.perSource.length} source page(s)`;
}
/** A repeatable flag's values; a flag never passed is an empty list. */
function stringArrayFlag(raw: unknown): string[] {
return Array.isArray(raw)
? raw.filter((value): value is string => typeof value === "string")
: [];
}
/** An integer flag inside `1..max`, its default, or null when refused. */
function numberFlag(raw: unknown, fallback: number, max: number): number | null {
if (raw === undefined) return fallback;
const value = Number(raw);
return Number.isInteger(value) && value > 0 && value <= max ? value : null;
}