Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* backup/status-file.ts — ENGINE-FREE core of the monthly backup-coverage
* check: the cached verdict file, the notice renderer, and the bounded nag
* gate shared by every render channel.
*
* ENGINE-FREE BY CONSTRUCTION: this module is imported by `gbrain hook`
* (which must never touch the engine — serve holds the PGLite single-writer
* lock) and by cli.ts's startup rail. Imports are fs/path, config file-plane
* helpers, and the PURE policy functions from skillpack/nag-state.ts only.
* Compute lives in backup/coverage.ts (engine-side).
*
* Two machine-owned files under the gbrain home (atomic tmp+rename, 0600,
* fail-open on corrupt — a broken state file must never break a session):
*
* backup-status.json the cached BackupStatus verdict. Written ONLY by a
* successful probed compute (coverage.ts); deleted by
* invalidateBackupStatus() on fix paths (bootstrap
* repo / sources harden / sources push success).
* backup-nag-state.json bounded-nag state. OWN schema (gbrain-backup-nag-v1)
* — NOT skillpack's: loadNagState() reconstructs only
* {schema_version, entries} on load, so the dampener /
* global-cap fields here would be silently dropped on
* round-trip. We reuse ONLY the pure policy functions
* (decideNagAction / recordNagDisplay).
*
* Nag semantics (per channel, composed as an AND):
* - per-channel ceiling 3 per pseudo-version, where pack_version =
* YYYY-MM(checked_at) + verdict fingerprint — a new month or a CHANGED
* verdict re-surfaces; a same-month recompute with an unchanged verdict
* stays quiet.
* - cross-channel 24h dampener (top-level last_shown_at).
* - global cap: 3 RECORDED impressions per month-bucket across all
* recording channels (global_shown_count anchored by global_month).
* record() is DEFERRED — call it only after the text actually reached the
* wire (the hook.ts banner discipline); cross-process last-writer-wins on
* this file is acceptable (worst case: one extra display).
*/
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import { dirname } from 'node:path';
import { gbrainPath, loadConfigFileOnly } from '../config.ts';
import {
decideNagAction,
recordNagDisplay,
type NagEntry,
} from '../skillpack/nag-state.ts';
// ── Verdict types ───────────────────────────────────────────────────────────
/** v2: API connector sources became their own `connector` asset kind; a v1 cache reads as absent and is recomputed. */
export const BACKUP_STATUS_SCHEMA_VERSION = 'gbrain-backup-status-v2' as const;
export const BACKUP_NAG_SCHEMA_VERSION = 'gbrain-backup-nag-v1' as const;
export type BackupAssetKind = 'source_repo' | 'bootstrap_workspace' | 'harness_skills' | 'db_only' | 'db_content' | 'connector';
export type BackupAssetState = 'ok' | 'no_remote' | 'unpushed' | 'dirty' | 'failing' | 'info' | 'unknown';
export type BackupComputedBy = 'cli' | 'advisor' | 'doctor' | 'serve' | 'spawn' | 'sync';
export interface BackupAssetVerdict {
kind: BackupAssetKind;
/** Source id / workspace root / label. LOCAL surfaces only — aggregate
* remote wording never includes this field. */
id: string;
state: BackupAssetState;
/** Sanitized detail codes/counts only — never raw git stderr. */
detail?: string;
/** Commits ahead of origin (when probed). */
ahead?: number;
/** Structured fix argv (AdvisorFix discipline) or null when no single
* mechanical fix exists. */
fix_argv?: string[] | null;
configured_remote?: boolean;
verification?: {
state: 'verified' | 'not_checked' | 'unavailable' | 'missing_ref' | 'mismatch' | 'budget_exhausted' | 'stale';
/** Why an `unavailable` probe failed: its full slot (`backup.remote_timeout_ms`, default 2 s) ran out, or git exited with an error. */
cause?: 'timeout' | 'exit';
checked_at?: string;
local_commit?: string;
remote_commit?: string;
repository_fingerprint?: string;
};
}
export interface BackupTotals {
assets: number;
no_remote: number;
unpushed: number;
failing: number;
/** Git-backed assets that would survive a disk loss (recovery statement). */
recoverable_repos: number;
/** Pages at risk on disk loss (db_only + undeclared DB-only signal). */
pages_at_risk: number;
configured_repos?: number;
/** #6907: repositories whose remote probe ran out of time: their backup is unconfirmed, not known missing. */
remote_timeouts?: number;
}
export interface BackupStatus {
schema_version: typeof BACKUP_STATUS_SCHEMA_VERSION;
/** ISO 8601 UTC of the completed compute. */
checked_at: string;
gbrain_version: string;
interval_days: number;
computed_by: BackupComputedBy;
overall: 'ok' | 'warn';
totals: BackupTotals;
assets: BackupAssetVerdict[];
/**
* True when the compute could not read sources/pages (engine down mid-run).
* A degraded verdict is never persisted over a probed cache
* (coverage.ts getBackupStatus) — it would silence or fabricate a warn.
*/
degraded?: boolean;
remote_check_at?: string;
recovery_scope?: string;
/**
* E7: how much the brain holds and since when, measured with the verdict.
* Backup coaching (doctor warn, MCP notice, CLI rail) waits until the brain
* holds >= BACKUP_COACH_MIN_ITEMS pages+facts or is >= BACKUP_COACH_MIN_AGE_DAYS
* old; before that doctor reports `severity: 'info'`. Absent on old caches
* (treated as mature, the pre-E7 behaviour).
*/
maturity?: { items: number; since: string | null };
}
export const BACKUP_COACH_MIN_ITEMS = 25;
export const BACKUP_COACH_MIN_AGE_DAYS = 7;
/** E7: is the brain old or full enough that a missing backup is worth coaching about? */
export function backupCoachingDue(s: Pick<BackupStatus, 'maturity'>, now: number = Date.now()): boolean {
const m = s.maturity;
if (!m) return true;
if (m.items >= BACKUP_COACH_MIN_ITEMS) return true;
const since = m.since ? Date.parse(m.since) : NaN;
return Number.isFinite(since) && now - since >= BACKUP_COACH_MIN_AGE_DAYS * 24 * 60 * 60 * 1000;
}
export const BACKUP_VERIFICATION_MAX_AGE_MS = 60 * 60 * 1000;
export const BACKUP_RECOVERY_SCOPE = 'Git evidence covers committed repository files only; not a full database backup. DB-only pages, facts, configuration and credentials need a separate backup and restore drill.';
/** Repository-shaped assets: the ones whose recovery is verified against a remote. */
export function isRepoAsset(a: BackupAssetVerdict): boolean {
return a.kind === 'source_repo' || a.kind === 'bootstrap_workspace';
}
/** A clean asset whose HEAD matched the remote within the evidence window. */
export function isVerifiedRecoverable(a: BackupAssetVerdict): boolean {
return a.state === 'ok' && a.verification?.state === 'verified';
}
/** #6907: a remote probe that ran out of its slot; nothing says the remote lacks the commits. */
export function isRemoteTimeout(a: BackupAssetVerdict): boolean {
return a.verification?.state === 'unavailable' && a.verification.cause === 'timeout';
}
/**
* True when this asset keeps the verdict in warn: an unverified repository,
* or any asset counted in the no_remote / unpushed / failing totals.
* currentBackupEvidence and the doctor message both read this.
*/
export function assetBlocksRecovery(a: BackupAssetVerdict): boolean {
return isRepoAsset(a) ? !isVerifiedRecoverable(a) : a.state === 'no_remote' || a.state === 'unpushed' || a.state === 'failing';
}
/**
* The fixed `unknown` detail codes coverage.ts and repository.ts write. The
* aggregate surface echoes only these, so a future free-text detail cannot
* carry a path or a branch name to a remote reader.
*/
const UNKNOWN_DETAIL_CODES = new Set(['not_a_git_repo', 'probes_skipped', 'probe_cap', 'probe_failed', 'local_path not found on this machine']);
/**
* #5505: one entry per asset that keeps the verdict in warn, with the reason
* that holds it there, so warnings name the real cause instead of assuming
* "no git remote". `aggregate` callers must render the reasons only, never ids.
*/
export function blockingAssetReasons(
s: BackupStatus,
surface: 'local' | 'aggregate',
): Array<{ id: string; state: BackupAssetState; reason: string }> {
return s.assets.filter(assetBlocksRecovery).map((a) => ({
id: a.id,
state: a.state,
reason: a.state === 'no_remote' ? (a.configured_remote === true ? 'remote configured, nothing pushed' : 'no git remote')
: a.state === 'unknown' ? (surface === 'local' || UNKNOWN_DETAIL_CODES.has(a.detail ?? '') ? a.detail ?? 'unknown' : 'unknown')
: a.state === 'ok' ? (isRemoteTimeout(a) ? 'remote check timed out' : `remote not verified: ${a.verification?.state ?? 'not_checked'}`)
: a.state,
}));
}
export function currentBackupEvidence(s: BackupStatus, now = Date.now()): BackupStatus {
const statusAge = now - Date.parse(s.checked_at);
const stale = isBackupStatusStale(s, now) || !Number.isFinite(statusAge) || statusAge < 0;
const assets = s.assets.map(a => {
if (a.verification?.state !== 'verified') return a;
const age = now - Date.parse(a.verification.checked_at ?? '');
if (!s.degraded && Number.isFinite(age) && age >= 0 && age <= BACKUP_VERIFICATION_MAX_AGE_MS && !stale) return a;
return { ...a, verification: { ...a.verification, state: 'stale' as const } };
});
const repos = assets.filter(isRepoAsset);
const recoverable = repos.filter(isVerifiedRecoverable).length;
return {
...s,
assets,
recovery_scope: BACKUP_RECOVERY_SCOPE,
totals: { ...s.totals, recoverable_repos: recoverable },
overall: s.degraded || stale || repos.length > recoverable || s.totals.no_remote > 0 || s.totals.unpushed > 0 || s.totals.failing > 0 ? 'warn' : s.overall,
};
}
// ── Paths (test seams follow the nag-state.ts idiom) ────────────────────────
let statusPathOverride: string | null = null;
let nagStatePathOverride: string | null = null;
let intervalOverrideMs: number | null = null;
export function backupStatusPath(): string {
return statusPathOverride ?? gbrainPath('backup-status.json');
}
export function __setBackupStatusPathForTests(p: string | null): void {
statusPathOverride = p;
}
export function backupNagStatePath(): string {
return nagStatePathOverride ?? gbrainPath('backup-nag-state.json');
}
export function __setBackupNagStatePathForTests(p: string | null): void {
nagStatePathOverride = p;
}
export function __setBackupIntervalForTests(ms: number | null): void {
intervalOverrideMs = ms;
}
// ── Config / kill switches ──────────────────────────────────────────────────
/** Default automatic-compute window: 30 days ("once a month"). */
export const BACKUP_INTERVAL_DAYS_DEFAULT = 30;
/** Human notice budget (the push-banner discipline). */
export const BACKUP_BANNER_MAX_CHARS = 300;
/** Cross-channel dampener: at most one recorded impression per day. */
export const BACKUP_DAMPENER_MS = 24 * 60 * 60 * 1000;
/** Recorded impressions allowed per month-bucket across ALL channels. */
export const BACKUP_GLOBAL_CEILING = 3;
function configBackup(): { check_enabled?: unknown; check_interval_days?: unknown } {
try {
const cfg = loadConfigFileOnly() as { backup?: { check_enabled?: unknown; check_interval_days?: unknown } };
return cfg.backup ?? {};
} catch {
return {};
}
}
/**
* Hard off-switches. Default ON — the whole point is protecting users who
* never opted in. `GBRAIN_BACKUP_CHECK=0` is the env kill switch; the
* file-plane key `backup.check_enabled` accepts 'false'/'0'/'off'/false.
* Render sites AND compute sites both consult this, so a stale warn cache
* goes silent the moment the feature is disabled.
*/
export function backupCheckDisabled(): boolean {
const env = process.env.GBRAIN_BACKUP_CHECK?.trim().toLowerCase();
if (env === '0' || env === 'false' || env === 'off') return true;
const raw = configBackup().check_enabled;
if (raw === undefined || raw === null) return false;
if (raw === false) return true;
const s = String(raw).trim().toLowerCase();
return s === 'false' || s === '0' || s === 'off';
}
/**
* Automatic-compute window in ms. env GBRAIN_BACKUP_CHECK_DAYS > config >
* default 30. Clamped to ≥1 day (a leftover DAYS=0 must not re-probe up to
* 500 git roots on every dispatch) — forcing a recompute is `gbrain backup
* check` or the test seam, never DAYS=0.
*/
export function backupIntervalMs(): number {
if (intervalOverrideMs !== null) return intervalOverrideMs;
const day = 24 * 60 * 60 * 1000;
const env = process.env.GBRAIN_BACKUP_CHECK_DAYS;
const cfgRaw = configBackup().check_interval_days;
const raw = env !== undefined && env !== '' ? Number(env) : cfgRaw !== undefined ? Number(cfgRaw) : NaN;
const days = Number.isFinite(raw) && raw >= 1 ? raw : BACKUP_INTERVAL_DAYS_DEFAULT;
return days * day;
}
// ── Cached verdict I/O ──────────────────────────────────────────────────────
function atomicWriteJson(path: string, value: unknown): void {
mkdirSync(dirname(path), { recursive: true });
const tmp = `${path}.tmp-${process.pid}`;
try {
writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
renameSync(tmp, path);
} catch (err) {
try {
rmSync(tmp, { force: true });
} catch {}
throw err;
}
}
/** Missing / corrupt / unknown-schema → null (fail-open). */
export function loadBackupStatus(): BackupStatus | null {
const path = backupStatusPath();
if (!existsSync(path)) return null;
try {
const raw = JSON.parse(readFileSync(path, 'utf-8')) as Partial<BackupStatus>;
if (raw.schema_version !== BACKUP_STATUS_SCHEMA_VERSION) return null;
if (typeof raw.checked_at !== 'string' || !Array.isArray(raw.assets)) return null;
if (raw.overall !== 'ok' && raw.overall !== 'warn') return null;
// Renderers dereference totals un-guarded — a truncated-but-schema-valid
// cache must read as absent, not crash `gbrain backup status`.
const t = raw.totals;
if (
!t ||
typeof t.assets !== 'number' ||
typeof t.no_remote !== 'number' ||
typeof t.recoverable_repos !== 'number' ||
typeof t.pages_at_risk !== 'number'
) {
return null;
}
return raw as BackupStatus;
} catch {
return null;
}
}
export function saveBackupStatus(s: BackupStatus): void {
atomicWriteJson(backupStatusPath(), s);
}
/**
* Fix-path invalidation: called on `bootstrap repo` / `sources harden` /
* `sources push` success so a fixed repo stops nagging immediately instead of
* at the next 30-day recompute. Best-effort — never throws.
*/
export function invalidateBackupStatus(): void {
try {
rmSync(backupStatusPath(), { force: true });
} catch {}
}
/**
* Absent cache counts as stale (cold start computes on the first trigger).
* A checked_at more than 24h in the FUTURE is stale/invalid (clock skew).
*/
export function isBackupStatusStale(s: BackupStatus | null, now: number = Date.now()): boolean {
if (!s) return true;
const t = Date.parse(s.checked_at);
if (!Number.isFinite(t)) return true;
if (t > now + 24 * 60 * 60 * 1000) return true;
return now - t > backupIntervalMs();
}
// ── Notice rendering ────────────────────────────────────────────────────────
/** Cache age as a short human phrase ("2h ago", "12d ago"). */
export function backupCacheAge(s: BackupStatus, now: number = Date.now()): string {
const t = Date.parse(s.checked_at);
if (!Number.isFinite(t)) return 'unknown age';
const ms = Math.max(0, now - t);
const h = Math.floor(ms / (60 * 60 * 1000));
if (h < 1) return 'under an hour ago';
if (h < 48) return `${h}h ago`;
return `${Math.floor(h / 24)}d ago`;
}
/**
* The user-facing warning line. Returns null when overall is ok.
*
* 'human' (trusted local surfaces: hook banner, CLI rail, backup status):
* names up to two assets, second person, concrete numbers, never preachy
* (DESIGN.md voice), capped at BACKUP_BANNER_MAX_CHARS.
*
* 'aggregate' (remote/MCP surfaces): counts ONLY — never a local path or
* source id (remote-privacy-sweep is the backstop).
*/
export function backupNoticeText(s: BackupStatus, surface: 'human' | 'aggregate'): string | null {
if (s.overall !== 'warn') return null;
const n = s.totals.no_remote;
const total = s.totals.assets;
if (n === 0) {
return "Current backup recovery is not verified for all knowledge assets. Run 'gbrain backup check' on the brain host; git does not cover the full database.";
}
if (surface === 'aggregate') {
return (
`gbrain monthly backup check: ${n} of ${total} knowledge assets have no git remote ` +
`(local-only). A disk loss loses them. Run 'gbrain backup status' on the brain host for fix commands.`
);
}
const names = s.assets
.filter((a) => a.state === 'no_remote')
.slice(0, 2)
.map((a) => a.id);
const which = names.length > 0 ? ` (${names.join(', ')}${n > names.length ? ', …' : ''})` : '';
const text =
`${n} of your ${total} knowledge assets aren't on any git remote${which}. ` +
`A disk loss loses them. Run: gbrain backup status`;
return text.length > BACKUP_BANNER_MAX_CHARS ? `${text.slice(0, BACKUP_BANNER_MAX_CHARS - 1)}…` : text;
}
// ── Nag state (own schema; reuses ONLY nag-state.ts pure policy fns) ────────
export interface BackupNagState {
schema_version: typeof BACKUP_NAG_SCHEMA_VERSION;
entries: NagEntry[];
/** Cross-channel dampener: ISO of the last RECORDED impression anywhere. */
last_shown_at?: string;
/** Recorded impressions in global_month (cap BACKUP_GLOBAL_CEILING). */
global_shown_count?: number;
/** YYYY-MM anchor for global_shown_count; rollover resets the count. */
global_month?: string;
/** Session-end detached-spawn debounce (no separate sidecar file). */
last_spawn_at?: string;
}
const EMPTY_NAG: BackupNagState = { schema_version: BACKUP_NAG_SCHEMA_VERSION, entries: [] };
export function loadBackupNagState(): BackupNagState {
const path = backupNagStatePath();
if (!existsSync(path)) return { ...EMPTY_NAG, entries: [] };
try {
const raw = JSON.parse(readFileSync(path, 'utf-8')) as Partial<BackupNagState>;
if (raw.schema_version !== BACKUP_NAG_SCHEMA_VERSION || !Array.isArray(raw.entries)) {
return { ...EMPTY_NAG, entries: [] };
}
return {
schema_version: BACKUP_NAG_SCHEMA_VERSION,
entries: raw.entries as NagEntry[],
last_shown_at: typeof raw.last_shown_at === 'string' ? raw.last_shown_at : undefined,
global_shown_count: typeof raw.global_shown_count === 'number' ? raw.global_shown_count : undefined,
global_month: typeof raw.global_month === 'string' ? raw.global_month : undefined,
last_spawn_at: typeof raw.last_spawn_at === 'string' ? raw.last_spawn_at : undefined,
};
} catch {
return { ...EMPTY_NAG, entries: [] };
}
}
export function saveBackupNagState(state: BackupNagState): void {
try {
atomicWriteJson(backupNagStatePath(), state);
} catch {
// Fail-open: a nag-state write failure must never break the caller.
}
}
function monthBucket(iso: string): string {
return iso.slice(0, 7); // YYYY-MM
}
/**
* Pseudo-version: month bucket of the verdict's checked_at + a fingerprint of
* the no-remote set. A new month or a CHANGED verdict reads as a version bump
* (re-surfaces, count resets via recordNagDisplay); a same-month forced
* recompute with an unchanged verdict keeps the same pseudo-version and stays
* suppressed once the ceiling is hit.
*/
export function backupVerdictVersion(s: BackupStatus): string {
const ids = s.assets
.filter((a) => a.state === 'no_remote')
.map((a) => a.id)
.sort()
.join(',');
const t = s.totals;
return `${monthBucket(s.checked_at)}:${t.no_remote}/${t.assets}:${ids}`;
}
const NAG_KEY_BASE = { brain_id: 'host', source_id: 'backup' } as const;
/**
* True when `iso` marks an event within the trailing dampener window. One
* helper for every consumer (gate, read-only consult, spawn debounce) so the
* future-skew guard cannot diverge: a far-future timestamp (clock jump /
* corrupt write) is ignored rather than suppressing forever.
*/
function withinDampener(iso: string | undefined, now: number): boolean {
if (!iso) return false;
const t = Date.parse(iso);
return Number.isFinite(t) && now - t < BACKUP_DAMPENER_MS && t <= now + BACKUP_DAMPENER_MS;
}
export interface BackupNagDecision {
show: boolean;
/** Deferred — invoke only AFTER the text reached the wire. No-op when
* show=false or for read-only consults. */
record: () => void;
}
const NOOP_DECISION: BackupNagDecision = { show: false, record: () => {} };
/**
* The bounded-nag gate every RECORDING channel routes through
* ('hook-banner' | 'hook-note' | 'cli' | 'mcp' | 'status' | 'advisor' | …).
* The global cap and dampener are enforced HERE, uniformly, so any future
* channel inherits them.
*/
export function backupNagGate(channel: string, s: BackupStatus, now: number = Date.now()): BackupNagDecision {
try {
if (s.overall !== 'warn' || backupCheckDisabled() || !backupCoachingDue(s, now)) return NOOP_DECISION;
const state = loadBackupNagState();
const nowIso = new Date(now).toISOString();
const month = monthBucket(nowIso);
// Cross-channel 24h dampener.
if (withinDampener(state.last_shown_at, now)) return NOOP_DECISION;
// Global per-month-bucket cap (count resets on rollover).
const globalCount = state.global_month === month ? (state.global_shown_count ?? 0) : 0;
if (globalCount >= BACKUP_GLOBAL_CEILING) return NOOP_DECISION;
const key = { ...NAG_KEY_BASE, pack_name: channel };
const packVersion = backupVerdictVersion(s);
const prior = state.entries.find(
(e) => e.brain_id === key.brain_id && e.source_id === key.source_id && e.pack_name === key.pack_name,
);
const decision = decideNagAction(prior, { pack_version: packVersion });
if (!decision.show) return NOOP_DECISION;
return {
show: true,
record: () => {
try {
// Re-load for last-writer-wins freshness; races are acceptable
// (worst case one extra display, documented).
const fresh = loadBackupNagState();
const freshPrior = fresh.entries.find(
(e) => e.brain_id === key.brain_id && e.source_id === key.source_id && e.pack_name === key.pack_name,
);
const entry = recordNagDisplay(freshPrior, key, { pack_version: packVersion, nowIso });
const others = fresh.entries.filter(
(e) => !(e.brain_id === key.brain_id && e.source_id === key.source_id && e.pack_name === key.pack_name),
);
const freshGlobal = fresh.global_month === month ? (fresh.global_shown_count ?? 0) : 0;
saveBackupNagState({
...fresh,
entries: [...others, entry],
last_shown_at: nowIso,
global_month: month,
global_shown_count: freshGlobal + 1,
});
} catch {
// Fail-open.
}
},
};
} catch {
return NOOP_DECISION;
}
}
/**
* Read-only consult for the OpenClaw context-engine line: `assemble()`
* composes server-side and cannot know delivery, so it never writes nag
* state. Shows only when the shared dampener has aged out AND the recording
* channels' global budget is not exhausted — bounded by their budget without
* ever spending it. (The caller adds its own in-process 24h latch.)
*/
export function backupNagReadOnlyConsult(s: BackupStatus, now: number = Date.now()): boolean {
try {
if (s.overall !== 'warn' || backupCheckDisabled()) return false;
const state = loadBackupNagState();
if (withinDampener(state.last_shown_at, now)) return false;
const month = monthBucket(new Date(now).toISOString());
const globalCount = state.global_month === month ? (state.global_shown_count ?? 0) : 0;
return globalCount < BACKUP_GLOBAL_CEILING;
} catch {
return false;
}
}
// ── Session-end spawn debounce (folded into the nag file — no sidecar) ──────
/** True when a detached `gbrain backup check --quiet` may be spawned. */
export function backupSpawnDue(now: number = Date.now()): boolean {
try {
return !withinDampener(loadBackupNagState().last_spawn_at, now);
} catch {
return true;
}
}
export function recordBackupSpawn(now: number = Date.now()): void {
try {
const state = loadBackupNagState();
saveBackupNagState({ ...state, last_spawn_at: new Date(now).toISOString() });
} catch {}
}
// ── CLI startup rail helper (keeps the cli.ts diff tiny) ────────────────────
/** Commands that must never host the backup nag on the CLI rail. `serve`
* especially: a harness-spawned MCP server must not burn the shared budget
* into a log nobody reads. */
export const BACKUP_CLI_NAG_SKIP = new Set([
'upgrade',
'post-upgrade',
'check-update',
'self-upgrade',
'hook',
'backup',
'doctor',
'advisor',
'serve',
'call',
'jobs',
]);
/**
* The cli.ts startup-rail body (called right after maybeEmitUpdateMarker).
* Guards live here — one place, every call site covered. Fail-open.
*/
export function maybeEmitBackupNag(
command: string | undefined,
opts: { quiet?: boolean } = {},
write: (line: string) => void = (line) => process.stderr.write(line),
): void {
try {
if (process.env.NODE_ENV === 'test' && process.env.GBRAIN_FORCE_BACKUP_NAG !== '1') return;
if (process.env.GBRAIN_SKIP_STARTUP_HOOKS) return;
if (opts.quiet) return;
if (!command || BACKUP_CLI_NAG_SKIP.has(command)) return;
if (backupCheckDisabled()) return;
const s = loadBackupStatus();
if (!s || s.overall !== 'warn') return;
const gate = backupNagGate('cli', s);
if (!gate.show) return;
const text = backupNoticeText(s, 'human');
if (!text) return;
if (!process.stderr.isTTY) {
write(`BACKUP_LOCAL_ONLY ${s.totals.no_remote}\n`);
}
write(`gbrain backup check: ${text}\n`);
gate.record();
} catch {
// Never break a CLI invocation over a notice.
}
}