Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
28.7 KB
Raw Blame
/**
 * test/backup-status-file.test.ts — engine-free coverage for
 * src/core/backup/status-file.ts: cached-verdict I/O, staleness, interval /
 * kill-switch config resolution, notice rendering (privacy pins), the
 * pseudo-version fingerprint, the bounded nag gate lifecycle (per-channel
 * ceiling, 24h dampener, global monthly cap), the read-only consult, the
 * spawn debounce, and the CLI startup-rail helper.
 *
 * Uses the module's __set...ForTests seams pointed at files under a mkdtemp
 * dir; never touches the real ~/.gbrain. No engine.
 */
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

import {
  BACKUP_BANNER_MAX_CHARS,
  BACKUP_DAMPENER_MS,
  BACKUP_GLOBAL_CEILING,
  BACKUP_INTERVAL_DAYS_DEFAULT,
  BACKUP_NAG_SCHEMA_VERSION,
  BACKUP_STATUS_SCHEMA_VERSION,
  BACKUP_CLI_NAG_SKIP,
  backupCheckDisabled,
  backupIntervalMs,
  backupNagGate,
  backupNagReadOnlyConsult,
  backupNagStatePath,
  backupNoticeText,
  backupSpawnDue,
  backupStatusPath,
  backupVerdictVersion,
  invalidateBackupStatus,
  isBackupStatusStale,
  loadBackupNagState,
  loadBackupStatus,
  maybeEmitBackupNag,
  recordBackupSpawn,
  saveBackupNagState,
  saveBackupStatus,
  __setBackupIntervalForTests,
  __setBackupNagStatePathForTests,
  __setBackupStatusPathForTests,
  type BackupAssetVerdict,
  type BackupStatus,
} from '../src/core/backup/status-file.ts';

const HOUR = 60 * 60 * 1000;
const DAY = 24 * HOUR;

const ENV_KEYS = [
  'GBRAIN_HOME',
  'GBRAIN_BACKUP_CHECK',
  'GBRAIN_BACKUP_CHECK_DAYS',
  'GBRAIN_SKIP_STARTUP_HOOKS',
  'GBRAIN_FORCE_BACKUP_NAG',
  'NODE_ENV',
] as const;

let tmp: string;
let statusPath: string;
let nagPath: string;
let saved: Record<string, string | undefined>;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), 'gb-backup-status-'));
  saved = {};
  for (const k of ENV_KEYS) saved[k] = process.env[k];
  // Clear the backup knobs; leave NODE_ENV as-is (bun test sets it).
  delete process.env.GBRAIN_BACKUP_CHECK;
  delete process.env.GBRAIN_BACKUP_CHECK_DAYS;
  delete process.env.GBRAIN_SKIP_STARTUP_HOOKS;
  delete process.env.GBRAIN_FORCE_BACKUP_NAG;
  process.env.GBRAIN_HOME = tmp; // config reads resolve to <tmp>/.gbrain/config.json
  statusPath = join(tmp, 'backup-status.json');
  nagPath = join(tmp, 'backup-nag-state.json');
  __setBackupStatusPathForTests(statusPath);
  __setBackupNagStatePathForTests(nagPath);
  __setBackupIntervalForTests(null);
});

afterEach(() => {
  __setBackupStatusPathForTests(null);
  __setBackupNagStatePathForTests(null);
  __setBackupIntervalForTests(null);
  for (const k of ENV_KEYS) {
    if (saved[k] === undefined) delete process.env[k];
    else process.env[k] = saved[k];
  }
  rmSync(tmp, { recursive: true, force: true });
});

function writeConfig(cfg: Record<string, unknown>): void {
  const dir = join(tmp, '.gbrain');
  mkdirSync(dir, { recursive: true });
  writeFileSync(join(dir, 'config.json'), JSON.stringify({ engine: 'pglite', ...cfg }));
}

/** Warn-by-default fixture: 2 of 3 assets have no remote. Ids deliberately
 * include a local path and a client name for the privacy pins. */
function makeStatus(overrides: Partial<BackupStatus> = {}): BackupStatus {
  const assets: BackupAssetVerdict[] =
    overrides.assets ??
    ([
      { kind: 'source_repo', id: '/tmp/secret-repo', state: 'no_remote', fix_argv: null },
      { kind: 'source_repo', id: 'client-acme', state: 'no_remote', fix_argv: null },
      { kind: 'source_repo', id: 'public-notes', state: 'ok' },
    ] as BackupAssetVerdict[]);
  const no_remote = assets.filter((a) => a.state === 'no_remote').length;
  const base: BackupStatus = {
    schema_version: BACKUP_STATUS_SCHEMA_VERSION,
    checked_at: '2026-01-05T12:00:00.000Z',
    gbrain_version: '0.0.0-test',
    interval_days: 30,
    computed_by: 'cli',
    overall: no_remote > 0 ? 'warn' : 'ok',
    totals: {
      assets: assets.length,
      no_remote,
      unpushed: 0,
      failing: 0,
      recoverable_repos: assets.length - no_remote,
      pages_at_risk: 0,
    },
    assets,
  };
  return { ...base, ...overrides };
}

function okStatus(): BackupStatus {
  return makeStatus({
    assets: [{ kind: 'source_repo', id: 'public-notes', state: 'ok' }] as BackupAssetVerdict[],
  });
}

function collect(): { write: (line: string) => void; lines: string[] } {
  const lines: string[] = [];
  return { write: (line: string) => lines.push(line), lines };
}

// ── 1. Cached verdict I/O ────────────────────────────────────────────────────

describe('loadBackupStatus / saveBackupStatus', () => {
  test('seams route the machine files under the tmp dir', () => {
    expect(backupStatusPath()).toBe(statusPath);
    expect(backupNagStatePath()).toBe(nagPath);
  });

  test('save/load round-trip', () => {
    const s = makeStatus();
    saveBackupStatus(s);
    expect(existsSync(statusPath)).toBe(true);
    expect(loadBackupStatus()).toEqual(s);
  });

  test('missing file -> null', () => {
    expect(existsSync(statusPath)).toBe(false);
    expect(loadBackupStatus()).toBeNull();
  });

  test('corrupt JSON -> null (fail-open)', () => {
    writeFileSync(statusPath, '{ definitely not json');
    expect(loadBackupStatus()).toBeNull();
  });

  test('unknown schema_version -> null', () => {
    const s = makeStatus();
    writeFileSync(statusPath, JSON.stringify({ ...s, schema_version: 'gbrain-backup-status-v999' }));
    expect(loadBackupStatus()).toBeNull();
  });

  test('structurally invalid payloads -> null (checked_at / assets / overall)', () => {
    const s = makeStatus();
    writeFileSync(statusPath, JSON.stringify({ ...s, checked_at: 42 }));
    expect(loadBackupStatus()).toBeNull();
    writeFileSync(statusPath, JSON.stringify({ ...s, assets: 'nope' }));
    expect(loadBackupStatus()).toBeNull();
    writeFileSync(statusPath, JSON.stringify({ ...s, overall: 'panic' }));
    expect(loadBackupStatus()).toBeNull();
  });

  test('missing or malformed totals block -> null (renderers dereference totals un-guarded)', () => {
    const s = makeStatus();
    // Schema-valid JSON with the totals block REMOVED must read as absent,
    // not crash `gbrain backup status`.
    const { totals: _dropped, ...withoutTotals } = s;
    writeFileSync(statusPath, JSON.stringify(withoutTotals));
    expect(loadBackupStatus()).toBeNull();
    // Truncated-but-schema-valid totals (non-numeric / null) are rejected too.
    writeFileSync(statusPath, JSON.stringify({ ...s, totals: null }));
    expect(loadBackupStatus()).toBeNull();
    writeFileSync(statusPath, JSON.stringify({ ...s, totals: { assets: 'three' } }));
    expect(loadBackupStatus()).toBeNull();
    writeFileSync(statusPath, JSON.stringify({ ...s, totals: { ...s.totals, no_remote: 'two' } }));
    expect(loadBackupStatus()).toBeNull();
    // The intact fixture still loads (the guard rejects only malformed shapes).
    writeFileSync(statusPath, JSON.stringify(s));
    expect(loadBackupStatus()).toEqual(s);
  });
});

// ── 2. invalidateBackupStatus ────────────────────────────────────────────────

describe('invalidateBackupStatus', () => {
  test('removes the cache file', () => {
    saveBackupStatus(makeStatus());
    expect(existsSync(statusPath)).toBe(true);
    invalidateBackupStatus();
    expect(existsSync(statusPath)).toBe(false);
    expect(loadBackupStatus()).toBeNull();
  });

  test('no-op when the file is absent', () => {
    expect(existsSync(statusPath)).toBe(false);
    expect(() => invalidateBackupStatus()).not.toThrow();
    expect(existsSync(statusPath)).toBe(false);
  });
});

// ── 3. isBackupStatusStale ───────────────────────────────────────────────────

describe('isBackupStatusStale', () => {
  const now = Date.parse('2026-06-15T00:00:00.000Z');

  test('null -> true (cold start computes)', () => {
    expect(isBackupStatusStale(null, now)).toBe(true);
  });

  test('fresh -> false (injected now)', () => {
    const s = makeStatus({ checked_at: new Date(now - HOUR).toISOString() });
    expect(isBackupStatusStale(s, now)).toBe(false);
  });

  test('older than the default 30d interval -> true', () => {
    const s = makeStatus({ checked_at: new Date(now - 31 * DAY).toISOString() });
    expect(isBackupStatusStale(s, now)).toBe(true);
    const edge = makeStatus({ checked_at: new Date(now - 29 * DAY).toISOString() });
    expect(isBackupStatusStale(edge, now)).toBe(false);
  });

  test('interval seam is honored', () => {
    __setBackupIntervalForTests(1000);
    expect(isBackupStatusStale(makeStatus({ checked_at: new Date(now - 2000).toISOString() }), now)).toBe(true);
    expect(isBackupStatusStale(makeStatus({ checked_at: new Date(now - 500).toISOString() }), now)).toBe(false);
  });

  test('checked_at >24h in the FUTURE -> true (clock skew); <=24h future is tolerated', () => {
    expect(isBackupStatusStale(makeStatus({ checked_at: new Date(now + 25 * HOUR).toISOString() }), now)).toBe(true);
    expect(isBackupStatusStale(makeStatus({ checked_at: new Date(now + HOUR).toISOString() }), now)).toBe(false);
  });

  test('unparseable checked_at -> true', () => {
    expect(isBackupStatusStale(makeStatus({ checked_at: 'not-a-date' }), now)).toBe(true);
  });
});

// ── 4. backupIntervalMs ──────────────────────────────────────────────────────

describe('backupIntervalMs', () => {
  test('default is 30 days', () => {
    expect(BACKUP_INTERVAL_DAYS_DEFAULT).toBe(30);
    expect(backupIntervalMs()).toBe(30 * DAY);
  });

  test('env GBRAIN_BACKUP_CHECK_DAYS=7 -> 7 days', () => {
    process.env.GBRAIN_BACKUP_CHECK_DAYS = '7';
    expect(backupIntervalMs()).toBe(7 * DAY);
  });

  test('DAYS=0 is clamped to the default (invalid, NOT always-stale)', () => {
    process.env.GBRAIN_BACKUP_CHECK_DAYS = '0';
    expect(backupIntervalMs()).toBe(30 * DAY);
    // A fresh cache stays fresh under DAYS=0 — the clamp prevents always-stale.
    const now = Date.parse('2026-06-15T00:00:00.000Z');
    const fresh = makeStatus({ checked_at: new Date(now - HOUR).toISOString() });
    expect(isBackupStatusStale(fresh, now)).toBe(false);
  });

  test('config backup.check_interval_days honored; env wins over config', () => {
    writeConfig({ backup: { check_interval_days: 2 } });
    expect(backupIntervalMs()).toBe(2 * DAY);
    process.env.GBRAIN_BACKUP_CHECK_DAYS = '7';
    expect(backupIntervalMs()).toBe(7 * DAY);
  });
});

// ── 5. backupCheckDisabled ───────────────────────────────────────────────────

describe('backupCheckDisabled', () => {
  test('default false (on — the whole point is unopted users)', () => {
    expect(backupCheckDisabled()).toBe(false);
  });

  test('env GBRAIN_BACKUP_CHECK=0 -> true', () => {
    process.env.GBRAIN_BACKUP_CHECK = '0';
    expect(backupCheckDisabled()).toBe(true);
  });

  test("env GBRAIN_BACKUP_CHECK 'false' / 'off' (case-insensitive, trimmed) -> true", () => {
    for (const v of ['false', 'off', 'FALSE', 'Off', ' false ']) {
      process.env.GBRAIN_BACKUP_CHECK = v;
      expect(backupCheckDisabled()).toBe(true);
    }
  });

  test("env GBRAIN_BACKUP_CHECK '1' / 'true' / '' do NOT disable", () => {
    for (const v of ['1', 'true', 'on', '']) {
      process.env.GBRAIN_BACKUP_CHECK = v;
      expect(backupCheckDisabled()).toBe(false);
    }
  });

  test("config backup.check_enabled false/'false'/'off'/'0' -> true", () => {
    for (const v of [false, 'false', 'off', '0'] as const) {
      writeConfig({ backup: { check_enabled: v } });
      expect(backupCheckDisabled()).toBe(true);
    }
  });

  test("config backup.check_enabled true/'true' -> false", () => {
    for (const v of [true, 'true'] as const) {
      writeConfig({ backup: { check_enabled: v } });
      expect(backupCheckDisabled()).toBe(false);
    }
  });
});

// ── 6. backupNoticeText ──────────────────────────────────────────────────────

describe('backupNoticeText', () => {
  test('ok verdict -> null on both surfaces', () => {
    expect(backupNoticeText(okStatus(), 'human')).toBeNull();
    expect(backupNoticeText(okStatus(), 'aggregate')).toBeNull();
  });

  test('human form names up to two assets and stays <= 300 chars', () => {
    const text = backupNoticeText(makeStatus(), 'human');
    expect(text).not.toBeNull();
    expect(text!).toContain('/tmp/secret-repo');
    expect(text!).toContain('client-acme');
    expect(text!).toContain('2 of your 3');
    expect(text!.length).toBeLessThanOrEqual(BACKUP_BANNER_MAX_CHARS);
  });

  test('human form is truncated to the banner budget even with long asset ids', () => {
    const long = makeStatus({
      assets: [
        { kind: 'source_repo', id: `/very/deep/${'x'.repeat(200)}`, state: 'no_remote', fix_argv: null },
        { kind: 'source_repo', id: `/another/${'y'.repeat(200)}`, state: 'no_remote', fix_argv: null },
      ] as BackupAssetVerdict[],
    });
    const text = backupNoticeText(long, 'human');
    expect(text).not.toBeNull();
    expect(text!.length).toBeLessThanOrEqual(BACKUP_BANNER_MAX_CHARS);
    expect(text!.endsWith('…')).toBe(true);
  });

  test('aggregate form carries counts only — never an asset id or path fragment (privacy pin)', () => {
    const text = backupNoticeText(makeStatus(), 'aggregate');
    expect(text).not.toBeNull();
    expect(text!).toContain('2 of 3');
    expect(text!).not.toContain('secret-repo');
    expect(text!).not.toContain('client-acme');
    expect(text!).not.toContain('/tmp');
    // No path fragments from the fixture ids at all.
    expect(text!).not.toContain('/tmp/secret-repo');
  });
});

// ── 7. backupVerdictVersion ──────────────────────────────────────────────────

describe('backupVerdictVersion', () => {
  test('same month + same no-remote set -> equal (day within month is irrelevant)', () => {
    const a = makeStatus({ checked_at: '2026-01-05T12:00:00.000Z' });
    const b = makeStatus({ checked_at: '2026-01-28T09:30:00.000Z' });
    expect(backupVerdictVersion(a)).toBe(backupVerdictVersion(b));
  });

  test('different month -> different', () => {
    const a = makeStatus({ checked_at: '2026-01-05T12:00:00.000Z' });
    const b = makeStatus({ checked_at: '2026-02-05T12:00:00.000Z' });
    expect(backupVerdictVersion(a)).not.toBe(backupVerdictVersion(b));
  });

  test('different no-remote set -> different', () => {
    const a = makeStatus();
    const b = makeStatus({
      assets: [
        { kind: 'source_repo', id: '/tmp/secret-repo', state: 'no_remote', fix_argv: null },
        { kind: 'source_repo', id: 'client-other', state: 'no_remote', fix_argv: null },
        { kind: 'source_repo', id: 'public-notes', state: 'ok' },
      ] as BackupAssetVerdict[],
    });
    expect(backupVerdictVersion(a)).not.toBe(backupVerdictVersion(b));
  });
});

// ── 8. backupNagGate lifecycle ───────────────────────────────────────────────

describe('backupNagGate', () => {
  test('ok verdict -> hidden; disabled -> hidden even on warn', () => {
    expect(backupNagGate('cli', okStatus(), Date.parse('2026-03-01T00:00:00Z')).show).toBe(false);
    process.env.GBRAIN_BACKUP_CHECK = '0';
    expect(backupNagGate('cli', makeStatus(), Date.parse('2026-03-01T00:00:00Z')).show).toBe(false);
  });

  test('first show -> record -> immediate re-gate hidden by the 24h dampener', () => {
    const s = makeStatus();
    const t0 = Date.parse('2026-03-01T00:00:00.000Z');
    const g1 = backupNagGate('hook-banner', s, t0);
    expect(g1.show).toBe(true);
    g1.record();
    expect(backupNagGate('hook-banner', s, t0 + 1000).show).toBe(false);
    expect(backupNagGate('hook-banner', s, t0 + BACKUP_DAMPENER_MS - 1000).show).toBe(false);
  });

  test('per-channel ceiling of 3 per pseudo-version; a different channel is independent of it but bound by the dampener', () => {
    const s = makeStatus({ checked_at: '2026-01-05T12:00:00.000Z' });
    // Spread the three recorded impressions across months so the GLOBAL cap
    // never saturates — this isolates the per-channel ceiling.
    const t1 = Date.parse('2026-01-05T12:00:00.000Z');
    const t2 = Date.parse('2026-02-06T12:00:00.000Z');
    const t3 = Date.parse('2026-03-07T12:00:00.000Z');
    for (const t of [t1, t2, t3]) {
      const g = backupNagGate('cli', s, t);
      expect(g.show).toBe(true);
      g.record();
    }
    const state = loadBackupNagState();
    expect(state.entries).toHaveLength(1);
    expect(state.entries[0]!.declined_count).toBe(3);
    expect(state.entries[0]!.suppressed).toBe(true);
    expect(state.global_shown_count).toBe(1); // March bucket only holds one

    // Ceiling hit: hidden even after the dampener ages out (+48h).
    const t4 = Date.parse('2026-03-09T12:00:00.000Z');
    expect(backupNagGate('cli', s, t4).show).toBe(false);

    // A DIFFERENT channel: not bound by cli's per-channel ceiling...
    expect(backupNagGate('status', s, t4).show).toBe(true);
    // ...but IS blocked by the shared 24h dampener right after a record.
    expect(backupNagGate('status', s, t3 + HOUR).show).toBe(false);
  });

  test('same-month forced recompute (new checked_at, same verdict) stays suppressed; month rollover re-surfaces with reset count', () => {
    const s = makeStatus({ checked_at: '2026-01-05T12:00:00.000Z' });
    const t1 = Date.parse('2026-01-05T12:00:00.000Z');
    const t2 = Date.parse('2026-02-06T12:00:00.000Z');
    const t3 = Date.parse('2026-03-07T12:00:00.000Z');
    for (const t of [t1, t2, t3]) {
      const g = backupNagGate('cli', s, t);
      expect(g.show).toBe(true);
      g.record();
    }
    const t4 = Date.parse('2026-03-09T12:00:00.000Z'); // dampener aged, global under cap
    expect(backupNagGate('cli', s, t4).show).toBe(false); // at ceiling

    // Same checked_at month, different day, same no-remote set -> same
    // pseudo-version -> STAYS suppressed.
    const sSameMonth = makeStatus({ checked_at: '2026-01-28T03:00:00.000Z' });
    expect(backupVerdictVersion(sSameMonth)).toBe(backupVerdictVersion(s));
    expect(backupNagGate('cli', sSameMonth, t4).show).toBe(false);

    // New checked_at month -> new pack_version -> re-surfaces, count resets.
    const sApril = makeStatus({ checked_at: '2026-04-01T00:00:00.000Z' });
    const t5 = Date.parse('2026-04-10T12:00:00.000Z');
    const g = backupNagGate('cli', sApril, t5);
    expect(g.show).toBe(true);
    g.record();
    const entry = loadBackupNagState().entries.find((e) => e.pack_name === 'cli');
    expect(entry!.declined_count).toBe(1); // reset, not 4
    expect(entry!.suppressed).toBe(false);
    // Still under ceiling: shows again once the dampener ages out.
    expect(backupNagGate('cli', sApril, t5 + 26 * HOUR).show).toBe(true);
  });

  test('global cap: 3 recorded impressions in one month across channels hides EVERY channel; next month re-arms', () => {
    const s = makeStatus({ checked_at: '2026-03-01T00:00:00.000Z' });
    const base = Date.parse('2026-03-01T00:00:00.000Z');
    const channels = ['a', 'b', 'c'];
    channels.forEach((ch, i) => {
      const g = backupNagGate(ch, s, base + i * 25 * HOUR);
      expect(g.show).toBe(true);
      g.record();
    });
    expect(loadBackupNagState().global_shown_count).toBe(BACKUP_GLOBAL_CEILING);

    const later = base + 3 * 25 * HOUR; // dampener aged; still March
    expect(backupNagGate('d', s, later).show).toBe(false); // fresh channel: global cap
    expect(backupNagGate('a', s, later).show).toBe(false); // under-ceiling channel: global cap
    expect(backupNagGate('d', s, later + 25 * HOUR).show).toBe(false); // stays hidden in-month

    // Next month: global count re-arms (dampener long aged).
    const april = Date.parse('2026-04-02T00:00:00.000Z');
    expect(backupNagGate('d', s, april).show).toBe(true);
  });

  test('record() is deferred — show without record leaves no state, so the next gate still shows', () => {
    const s = makeStatus();
    const t0 = Date.parse('2026-03-01T00:00:00.000Z');
    const g1 = backupNagGate('cli', s, t0);
    expect(g1.show).toBe(true);
    // record NOT called: nothing persisted, nothing counted.
    expect(existsSync(nagPath)).toBe(false);
    expect(backupNagGate('cli', s, t0 + 60_000).show).toBe(true); // even inside the would-be dampener window
    expect(backupNagGate('cli', s, t0 + BACKUP_DAMPENER_MS + HOUR).show).toBe(true);
  });
});

// ── 9. backupNagReadOnlyConsult ──────────────────────────────────────────────

describe('backupNagReadOnlyConsult', () => {
  const now = Date.parse('2026-03-10T00:00:00.000Z');

  test('warn + no state -> true, and never creates the state file', () => {
    expect(existsSync(nagPath)).toBe(false);
    expect(backupNagReadOnlyConsult(makeStatus(), now)).toBe(true);
    expect(existsSync(nagPath)).toBe(false);
  });

  test('ok verdict / disabled -> false', () => {
    expect(backupNagReadOnlyConsult(okStatus(), now)).toBe(false);
    process.env.GBRAIN_BACKUP_CHECK = '0';
    expect(backupNagReadOnlyConsult(makeStatus(), now)).toBe(false);
  });

  test('within 24h of last_shown_at -> false; never writes the state file', () => {
    saveBackupNagState({
      schema_version: BACKUP_NAG_SCHEMA_VERSION,
      entries: [],
      last_shown_at: new Date(now - HOUR).toISOString(),
    });
    const before = readFileSync(nagPath, 'utf-8');
    expect(backupNagReadOnlyConsult(makeStatus(), now)).toBe(false);
    expect(readFileSync(nagPath, 'utf-8')).toBe(before);
  });

  test('global count at ceiling for the current month -> false; under cap next month -> true; never writes', () => {
    saveBackupNagState({
      schema_version: BACKUP_NAG_SCHEMA_VERSION,
      entries: [],
      last_shown_at: new Date(now - 48 * HOUR).toISOString(),
      global_month: '2026-03',
      global_shown_count: BACKUP_GLOBAL_CEILING,
    });
    const before = readFileSync(nagPath, 'utf-8');
    expect(backupNagReadOnlyConsult(makeStatus(), now)).toBe(false);
    // Month rollover: the March count no longer binds.
    expect(backupNagReadOnlyConsult(makeStatus(), Date.parse('2026-04-05T00:00:00.000Z'))).toBe(true);
    expect(readFileSync(nagPath, 'utf-8')).toBe(before);
  });
});

// ── 10. backupSpawnDue / recordBackupSpawn ───────────────────────────────────

describe('backupSpawnDue / recordBackupSpawn', () => {
  test('due when never recorded; not due within 24h; due after (injected now)', () => {
    const t0 = Date.parse('2026-05-01T00:00:00.000Z');
    expect(backupSpawnDue(t0)).toBe(true);
    recordBackupSpawn(t0);
    expect(backupSpawnDue(t0 + HOUR)).toBe(false);
    expect(backupSpawnDue(t0 + 23 * HOUR)).toBe(false);
    expect(backupSpawnDue(t0 + 25 * HOUR)).toBe(true);
  });

  test('recordBackupSpawn preserves the rest of the nag state', () => {
    const t0 = Date.parse('2026-05-01T00:00:00.000Z');
    const g = backupNagGate('cli', makeStatus(), t0);
    g.record();
    recordBackupSpawn(t0 + 1000);
    const state = loadBackupNagState();
    expect(state.entries).toHaveLength(1);
    expect(state.last_spawn_at).toBe(new Date(t0 + 1000).toISOString());
    expect(state.last_shown_at).toBe(new Date(t0).toISOString());
  });
});

// ── 11. maybeEmitBackupNag (CLI startup rail) ────────────────────────────────

describe('maybeEmitBackupNag', () => {
  test('warn cache + non-skip command emits the machine marker + human line and records', () => {
    process.env.GBRAIN_FORCE_BACKUP_NAG = '1';
    saveBackupStatus(makeStatus());
    const c = collect();
    maybeEmitBackupNag('search', {}, c.write);
    // stderr is not a TTY under redirected test runs -> machine marker first.
    expect(c.lines.some((l) => l === 'BACKUP_LOCAL_ONLY 2\n')).toBe(true);
    const human = c.lines.find((l) => l.startsWith('gbrain backup check: '));
    expect(human).toBeDefined();
    expect(human!).toContain("aren't on any git remote");
    // Recorded: nag state exists and counted one impression.
    const state = loadBackupNagState();
    expect(state.global_shown_count).toBe(1);
    expect(state.entries.find((e) => e.pack_name === 'cli')).toBeDefined();
    // Immediate second invocation is dampened -> silent.
    const c2 = collect();
    maybeEmitBackupNag('search', {}, c2.write);
    expect(c2.lines).toEqual([]);
  });

  test('skip-set commands emit nothing and record nothing', () => {
    process.env.GBRAIN_FORCE_BACKUP_NAG = '1';
    saveBackupStatus(makeStatus());
    for (const cmd of ['serve', 'backup', 'doctor', 'advisor', 'call', 'jobs', 'hook', 'upgrade']) {
      expect(BACKUP_CLI_NAG_SKIP.has(cmd)).toBe(true);
      const c = collect();
      maybeEmitBackupNag(cmd, {}, c.write);
      expect(c.lines).toEqual([]);
    }
    // Undefined command is skipped too.
    const c = collect();
    maybeEmitBackupNag(undefined, {}, c.write);
    expect(c.lines).toEqual([]);
    expect(existsSync(nagPath)).toBe(false);
  });

  test('quiet opt emits nothing', () => {
    process.env.GBRAIN_FORCE_BACKUP_NAG = '1';
    saveBackupStatus(makeStatus());
    const c = collect();
    maybeEmitBackupNag('search', { quiet: true }, c.write);
    expect(c.lines).toEqual([]);
    expect(existsSync(nagPath)).toBe(false);
  });

  test('GBRAIN_SKIP_STARTUP_HOOKS set -> nothing', () => {
    process.env.GBRAIN_FORCE_BACKUP_NAG = '1';
    process.env.GBRAIN_SKIP_STARTUP_HOOKS = '1';
    saveBackupStatus(makeStatus());
    const c = collect();
    maybeEmitBackupNag('search', {}, c.write);
    expect(c.lines).toEqual([]);
  });

  test('disabled -> nothing (stale warn cache goes silent)', () => {
    process.env.GBRAIN_FORCE_BACKUP_NAG = '1';
    process.env.GBRAIN_BACKUP_CHECK = '0';
    saveBackupStatus(makeStatus());
    const c = collect();
    maybeEmitBackupNag('search', {}, c.write);
    expect(c.lines).toEqual([]);
  });

  test('ok cache -> nothing; missing cache -> nothing', () => {
    process.env.GBRAIN_FORCE_BACKUP_NAG = '1';
    saveBackupStatus(okStatus());
    const c = collect();
    maybeEmitBackupNag('search', {}, c.write);
    expect(c.lines).toEqual([]);
    invalidateBackupStatus();
    const c2 = collect();
    maybeEmitBackupNag('search', {}, c2.write);
    expect(c2.lines).toEqual([]);
  });

  test("NODE_ENV=test without GBRAIN_FORCE_BACKUP_NAG -> early return (test-suite guard)", () => {
    process.env.NODE_ENV = 'test';
    delete process.env.GBRAIN_FORCE_BACKUP_NAG;
    saveBackupStatus(makeStatus());
    const c = collect();
    maybeEmitBackupNag('search', {}, c.write);
    expect(c.lines).toEqual([]);
  });
});

// ── 12. Fail-open corruption + atomic-write hygiene ──────────────────────────

describe('fail-open + atomicity', () => {
  test('corrupt nag-state file -> gate fail-open (still decides; record repairs the file)', () => {
    writeFileSync(nagPath, '{ this is not json');
    const s = makeStatus();
    const t0 = Date.parse('2026-03-01T00:00:00.000Z');
    const g = backupNagGate('cli', s, t0);
    expect(g.show).toBe(true); // worst case: one extra display, never a crash
    g.record();
    const state = loadBackupNagState();
    expect(state.schema_version).toBe(BACKUP_NAG_SCHEMA_VERSION);
    expect(state.entries).toHaveLength(1);
    expect(state.global_shown_count).toBe(1);
  });

  test('unknown nag-state schema -> empty state (fail-open load)', () => {
    writeFileSync(nagPath, JSON.stringify({ schema_version: 'gbrain-backup-nag-v999', entries: [{}] }));
    const state = loadBackupNagState();
    expect(state.entries).toEqual([]);
  });

  test('kill-mid-write: a partial .tmp sibling next to the status path is ignored', () => {
    const s = makeStatus();
    saveBackupStatus(s);
    // Simulate a writer killed between writeFileSync(tmp) and renameSync.
    writeFileSync(`${statusPath}.tmp-99999`, '{"schema_version":"gbrain-ba'); // truncated JSON
    expect(loadBackupStatus()).toEqual(s); // real file wins; tmp never consulted
    // And with ONLY the orphaned partial present, load sees a missing file.
    rmSync(statusPath);
    expect(loadBackupStatus()).toBeNull();
  });

  test('saveBackupStatus leaves no .tmp droppings on the happy path', () => {
    saveBackupStatus(makeStatus());
    expect(existsSync(`${statusPath}.tmp-${process.pid}`)).toBe(false);
    expect(existsSync(statusPath)).toBe(true);
  });
});