Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
40.2 KB
Raw Blame
/**
 * backup-coverage.test.ts — pins src/core/backup/coverage.ts:
 * computeBackupCoverage asset classification (source repos probed via real
 * tmp git fixtures, bootstrap workspace via the receipt file, db_only tiering
 * via gbrain.yml, the DB-only-brain worst case), the getBackupStatus cache
 * choke point (probed persists, probe-less never persists, failed compute
 * never clobbers), and the serve-side single-flight refresher.
 *
 * Engine is a minimal executeRaw stub cast to BrainEngine (no real PGLite);
 * loadAllSources + countLivePages are distinguished by SQL substring.
 */
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runExport } from '../src/commands/export.ts';
import {
  computeBackupCoverage,
  getBackupStatus,
  maybeRefreshBackupStatusInProcess,
  __resetBackupRefreshForTests,
} from '../src/core/backup/coverage.ts';
import { pushStatusPathForRoot } from '../src/core/workspace-push.ts';
import {
  saveBridgeState,
  SKILLPACK_BRIDGE_SCHEMA_VERSION,
} from '../src/core/skillpack/bridge-state.ts';
import {
  BACKUP_STATUS_SCHEMA_VERSION,
  __setBackupIntervalForTests,
  __setBackupNagStatePathForTests,
  __setBackupStatusPathForTests,
  invalidateBackupStatus,
  loadBackupStatus,
  saveBackupStatus,
  type BackupStatus,
} from '../src/core/backup/status-file.ts';

const ENV_KEYS = [
  'GBRAIN_HOME',
  'GBRAIN_BACKUP_CHECK',
  'GBRAIN_BACKUP_CHECK_DAYS',
  'GBRAIN_BRAIN_ID',
  'DATABASE_URL',
  'GBRAIN_DATABASE_URL',
  'GBRAIN_SOURCE',
  'GBRAIN_SKIP_STARTUP_HOOKS',
] as const;

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

const home = () => join(tmp, '.gbrain');

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), 'gb-bkcov-'));
  saved = {};
  for (const k of ENV_KEYS) {
    saved[k] = process.env[k];
    delete process.env[k];
  }
  process.env.GBRAIN_HOME = tmp; // configDir() === tmp/.gbrain
  statusPath = join(home(), 'backup-status.json');
  __setBackupStatusPathForTests(statusPath);
  __setBackupNagStatePathForTests(join(home(), 'backup-nag-state.json'));
  __resetBackupRefreshForTests();
});

afterEach(() => {
  __setBackupStatusPathForTests(null);
  __setBackupNagStatePathForTests(null);
  __setBackupIntervalForTests(null);
  __resetBackupRefreshForTests();
  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 });
});

// ── Fixtures ─────────────────────────────────────────────────────────────────

function g(dir: string, args: string[]): void {
  execFileSync('git', ['-C', dir, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
}

function initRepo(dir: string): void {
  mkdirSync(dir, { recursive: true });
  execFileSync('git', ['init', '-b', 'main', dir], { stdio: ['ignore', 'pipe', 'pipe'] });
  g(dir, ['config', 'user.email', '[email protected]']);
  g(dir, ['config', 'user.name', 'Test User']);
  g(dir, ['config', 'commit.gpgsign', 'false']);
}

function commitFile(dir: string, name: string, content: string, msg: string): void {
  writeFileSync(join(dir, name), content);
  g(dir, ['add', '.']);
  g(dir, ['commit', '-m', msg]);
}

/** SourceRow shape per src/core/sources-load.ts:192-226. */
function srcRow(id: string, localPath: string | null, extra: Record<string, unknown> = {}) {
  return {
    id,
    name: id,
    local_path: localPath,
    last_commit: null,
    last_sync_at: null,
    config: {},
    created_at: new Date(),
    archived: false,
    newest_content_at: null,
    ...extra,
  };
}

function stubEngine(opts: {
  kind?: 'pglite' | 'postgres';
  sources?: unknown[];
  pages?: number;
  onCall?: () => void;
  /** persistence_brain.enabled (managed persistence activated). */
  managed?: boolean;
  /** Source ids that have a persistence_source_bindings row. */
  bound?: string[];
} = {}): BrainEngine {
  return {
    kind: opts.kind ?? 'pglite',
    executeRaw: async (sql: string, params: unknown[] = []) => {
      opts.onCall?.();
      if (sql.includes('FROM persistence_brain')) return [{ enabled: opts.managed === true }];
      if (sql.includes('FROM persistence_source_bindings')) {
        return (opts.bound ?? []).includes(String(params[0])) ? [{ source_id: params[0], worktree_id: 'wt-example' }] : [];
      }
      if (sql.includes('FROM pages')) return [{ n: opts.pages ?? 0 }];
      if (sql.includes('FROM sources')) return opts.sources ?? [];
      return [];
    },
  } as unknown as BrainEngine;
}

function writeReceipt(ws: string, extra: Record<string, unknown> = {}): void {
  const dir = join(home(), 'bootstrap');
  mkdirSync(dir, { recursive: true });
  writeFileSync(
    join(dir, 'receipt.json'),
    JSON.stringify(
      {
        receipt_version: 1,
        workspace_dir: ws,
        source_id: 'workspace',
        agent_name: 'agent-example',
        created_at: new Date().toISOString(),
        created_by: 'test',
        brain_created_by_bootstrap: false,
        created_paths: [],
        registrations: [],
        ...extra,
      },
      null,
      2,
    ),
  );
}

/** Hand-built cache verdict that passes loadBackupStatus validation. */
function mkStatus(overall: 'ok' | 'warn', checkedAt: string): BackupStatus {
  const noRemote = overall === 'warn' ? 1 : 0;
  return {
    schema_version: BACKUP_STATUS_SCHEMA_VERSION,
    checked_at: checkedAt,
    gbrain_version: '0.0.0-test',
    interval_days: 30,
    computed_by: 'cli',
    overall,
    totals: {
      assets: noRemote,
      no_remote: noRemote,
      unpushed: 0,
      failing: 0,
      recoverable_repos: 0,
      pages_at_risk: 0,
    },
    assets:
      overall === 'warn'
        ? [{ kind: 'source_repo', id: 'stale-example', state: 'no_remote', fix_argv: null }]
        : [],
  };
}

function sleep(ms: number): Promise<void> {
  return new Promise((r) => setTimeout(r, ms));
}

async function pollUntil(fn: () => boolean, timeoutMs = 2000): Promise<boolean> {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    if (fn()) return true;
    await sleep(25);
  }
  return fn();
}

// ── Source-repo probing ──────────────────────────────────────────────────────

describe('computeBackupCoverage — source repos', () => {
  test('repo without origin → no_remote asset, overall warn', async () => {
    const repo = join(tmp, 'repo-a');
    initRepo(repo);
    commitFile(repo, 'a.md', 'hello', 'init');
    const engine = stubEngine({ sources: [srcRow('src-a', repo)] });

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'source_repo');
    expect(asset).toBeDefined();
    expect(asset?.id).toBe('src-a');
    expect(asset?.state).toBe('no_remote');
    expect(asset?.detail).toContain('git remote add origin');
    expect(asset?.fix_argv).toBeNull(); // no bootstrap manifest → recipe only
    expect(s.overall).toBe('warn');
    expect(s.totals.no_remote).toBe(1);
  });

  test('repo one commit ahead of a local bare origin → unpushed, overall stays ok', async () => {
    const bare = join(tmp, 'bare.git');
    execFileSync('git', ['init', '--bare', '-b', 'main', bare], { stdio: ['ignore', 'pipe', 'pipe'] });
    const work = join(tmp, 'work');
    initRepo(work);
    commitFile(work, 'a.md', 'baseline', 'baseline');
    g(work, ['remote', 'add', 'origin', bare]);
    g(work, ['push', '-u', 'origin', 'main']);
    commitFile(work, 'b.md', 'more', 'ahead commit');

    const engine = stubEngine({ sources: [srcRow('src-work', work)] });
    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'source_repo');
    expect(asset?.state).toBe('unpushed');
    expect(asset?.ahead).toBeGreaterThanOrEqual(1);
    expect(asset?.detail).toContain('ahead of origin/');
    expect(s.totals.unpushed).toBe(1);
    expect(s.totals.no_remote).toBe(0);
    expect(s.overall).toBe('warn');
    expect(s.totals.recoverable_repos).toBe(0);
  });

  test('localGitProbes:false → unknown assets and getBackupStatus never persists', async () => {
    const repo = join(tmp, 'repo-np');
    initRepo(repo);
    commitFile(repo, 'a.md', 'x', 'init');
    const engine = stubEngine({ sources: [srcRow('src-np', repo)] });

    const s = await getBackupStatus(engine, { localGitProbes: false });

    const asset = s.assets.find((a) => a.kind === 'source_repo');
    expect(asset?.state).toBe('unknown');
    expect(asset?.detail).toBe('probes_skipped');
    expect(existsSync(statusPath)).toBe(false); // probe-less computes are never persisted
  });

  test('archived + null-path sources are skipped; a MISSING local_path surfaces as an unknown asset', async () => {
    const repo = join(tmp, 'repo-archived');
    initRepo(repo);
    commitFile(repo, 'a.md', 'x', 'init');
    const engine = stubEngine({
      sources: [
        srcRow('archived-src', repo, { archived: true }),
        srcRow('ghost-src', join(tmp, 'no-such-dir')),
        srcRow('null-path-src', null),
      ],
    });

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    // The most disk-loss-adjacent state of all: a registered path that is GONE
    // is surfaced ('unknown' — it may live on another machine), never silently
    // skipped. Archived and null-path rows still produce nothing.
    const repos = s.assets.filter((a) => a.kind === 'source_repo');
    expect(repos).toHaveLength(1);
    expect(repos[0]?.id).toBe('ghost-src');
    expect(repos[0]?.state).toBe('unknown');
    expect(repos[0]?.detail).toBe('local_path not found on this machine');
    expect(repos[0]?.fix_argv).toBeNull();
    expect(s.totals.assets).toBe(1); // the missing-path asset IS counted
    expect(s.overall).toBe('warn');
  });

  test('remote added but NOTHING pushed → no_remote (nothing pushed), overall warn', async () => {
    // The half-completed `git remote add` state: origin exists but
    // origin/<branch> is unresolvable — zero recoverable history on the
    // remote, so it must WARN, not read ok.
    const bare = join(tmp, 'never-pushed-origin.git');
    execFileSync('git', ['init', '--bare', '-b', 'main', bare], { stdio: ['ignore', 'pipe', 'pipe'] });
    const work = join(tmp, 'never-pushed');
    initRepo(work);
    commitFile(work, 'a.md', 'unpushed history', 'init');
    g(work, ['remote', 'add', 'origin', bare]); // deliberately NO push

    const engine = stubEngine({ sources: [srcRow('src-never-pushed', work)] });
    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'source_repo');
    expect(asset?.id).toBe('src-never-pushed');
    expect(asset?.state).toBe('no_remote');
    expect(asset?.detail).toContain('nothing pushed');
    expect(asset?.detail).toContain('git push -u origin');
    expect(asset?.fix_argv).toBeNull();
    expect(s.overall).toBe('warn');
    expect(s.totals.no_remote).toBe(1);
    expect(s.totals.recoverable_repos).toBe(0); // nothing on the remote to recover
  });

  test('gbrain.yml storage.db_only tiering → info asset with the export fix', async () => {
    const repo = join(tmp, 'repo-tiered');
    initRepo(repo);
    writeFileSync(join(repo, 'gbrain.yml'), 'storage:\n  db_only:\n    - private/\n');
    commitFile(repo, 'a.md', 'x', 'init');
    const engine = stubEngine({ sources: [srcRow('tiered-src', repo)] });

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'db_only');
    expect(asset).toBeDefined();
    expect(asset?.id).toBe('tiered-src');
    expect(asset?.state).toBe('info');
    expect(asset?.fix_argv).toEqual(['gbrain', 'export', '--source', 'tiered-src', '--dir', 'BACKUP_DIR/tiered-src']);
    // Pasted as-is, the command must not redirect or substitute anything:
    // `<backup-dir>/x` would read stdin from `backup-dir` and truncate `/x`.
    expect(asset?.fix_argv?.join(' ')).not.toMatch(/[<>|;&$`]/);
  });

  test('following each db_only fix dumps every source, even when two share a slug', async () => {
    const engine = new PGLiteEngine();
    await engine.connect({});
    await engine.initSchema();
    const original = { exit: process.exit, log: console.log, error: console.error };
    try {
      for (const id of ['src-a', 'src-b']) {
        const repo = join(tmp, id);
        mkdirSync(repo);
        writeFileSync(join(repo, 'gbrain.yml'), 'storage:\n  db_only:\n    - private/\n');
        await engine.executeRaw('INSERT INTO sources (id, name, local_path) VALUES ($1, $1, $2)', [id, repo]);
        await engine.putPage('private/shared', { type: 'note', title: id, compiled_truth: `body-${id}`, timeline: '' }, { sourceId: id });
      }
      const s = await computeBackupCoverage(engine, { localGitProbes: false });
      const fixes = s.assets.filter((a) => a.kind === 'db_only').map((a) => a.fix_argv ?? []);
      expect(fixes).toHaveLength(2);

      // Export publication refuses symlinked ancestors (macOS /var).
      const backupDir = join(realpathSync(tmp), 'dumps');
      process.exit = ((code: number) => { throw new Error(`EXIT:${code}`); }) as never;
      console.log = console.error = () => {};
      for (const argv of fixes) {
        expect(argv.slice(0, 2)).toEqual(['gbrain', 'export']);
        await runExport(engine, argv.slice(2).map((arg) => arg.replace(/^BACKUP_DIR\//, backupDir + '/')));
      }
      for (const id of ['src-a', 'src-b']) {
        expect(readFileSync(join(backupDir, id, 'private/shared.md'), 'utf8')).toContain(`body-${id}`);
      }
    } finally {
      process.exit = original.exit;
      console.log = original.log;
      console.error = original.error;
      await engine.disconnect();
    }
  }, 60000);
});

// ── DB-only brain + empty brain ──────────────────────────────────────────────

describe('computeBackupCoverage — db_content and empty brain', () => {
  test('pglite brain with pages but no sources/receipt → db_content no_remote, pages at risk', async () => {
    const engine = stubEngine({ kind: 'pglite', pages: 42 });
    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'db_content');
    expect(asset?.state).toBe('no_remote');
    expect(asset?.detail).toContain('42 pages');
    expect(asset?.fix_argv).toEqual(['gbrain', 'bootstrap', 'repo']);
    expect(s.totals.pages_at_risk).toBe(42);
    expect(s.overall).toBe('warn');
  });

  test('postgres brain with pages but no sources/receipt → db_content info, overall ok', async () => {
    const engine = stubEngine({ kind: 'postgres', pages: 42 });
    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'db_content');
    expect(asset?.state).toBe('info');
    expect(s.totals.pages_at_risk).toBe(0);
    expect(s.overall).toBe('ok');
  });

  test('empty brain (0 pages, no sources, no receipt) → ok and never warn', async () => {
    const s = await computeBackupCoverage(stubEngine({}), { localGitProbes: true });

    expect(s.overall).toBe('ok');
    expect(s.totals.assets).toBe(0);
    expect(s.totals.pages_at_risk).toBe(0);
    // Zero assets, or only info assets — never a warn-carrying state.
    expect(s.assets.every((a) => a.state === 'info')).toBe(true);
  });
});

// ── Bootstrap workspace via the receipt ─────────────────────────────────────

describe('computeBackupCoverage — bootstrap workspace', () => {
  test('receipt without repo_url → bootstrap_workspace no_remote names both bootstrap repo and attach, fix_argv null', async () => {
    const ws = join(tmp, 'ws');
    mkdirSync(ws, { recursive: true });
    writeReceipt(ws);

    const s = await computeBackupCoverage(stubEngine({}), { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'bootstrap_workspace');
    expect(asset).toBeDefined();
    expect(asset?.id).toBe(ws);
    expect(asset?.state).toBe('no_remote');
    // This check is file-plane only (no git subprocess) so it can't tell an
    // empty/unconfigured origin (needs `bootstrap repo`) from an
    // already-pushed out-of-band one (needs `bootstrap attach`, since
    // `bootstrap repo` guaranteed-refuses with ORIGIN_NOT_EMPTY there — see
    // src/core/bootstrap/repo.ts). fix_argv stays null rather than advertise
    // a command that's wrong in the out-of-band case; the message names both.
    expect(asset?.fix_argv).toBeNull();
    expect(asset?.detail).toContain('no private repo yet');
    expect(asset?.detail).toContain('bootstrap repo');
    expect(asset?.detail).toContain('bootstrap attach');
    expect(s.overall).toBe('warn');
    expect(s.totals.no_remote).toBe(1);
  });

  test('receipt with repo_url and no failing push statuses → bootstrap_workspace ok', async () => {
    const ws = join(tmp, 'ws');
    mkdirSync(ws, { recursive: true });
    writeReceipt(ws, { repo_url: 'https://example.com/acme-example/brain.git' });

    const s = await computeBackupCoverage(stubEngine({}), { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'bootstrap_workspace');
    expect(asset?.state).toBe('unknown');
    expect(s.overall).toBe('warn');
    expect(s.totals.recoverable_repos).toBe(0);
  });
});

// ── getBackupStatus caching ──────────────────────────────────────────────────

describe('getBackupStatus — cache choke point', () => {
  test('probed compute persists; fresh cache short-circuits; forceRefresh recomputes', async () => {
    const t0 = new Date('2026-08-01T00:00:00.000Z');
    const first = await getBackupStatus(stubEngine({}), { localGitProbes: true, now: t0 });
    expect(existsSync(statusPath)).toBe(true);
    expect(first.checked_at).toBe(t0.toISOString());
    expect(loadBackupStatus()?.checked_at).toBe(t0.toISOString());

    // Fresh cache is returned as-is: a throwing engine is never even touched,
    // and the persisted verdict is not clobbered.
    let throwCalls = 0;
    const throwing = {
      kind: 'pglite',
      executeRaw: async () => {
        throwCalls++;
        throw new Error('boom');
      },
    } as unknown as BrainEngine;
    const second = await getBackupStatus(throwing, {
      localGitProbes: true,
      now: new Date(t0.getTime() + 60_000),
    });
    expect(second.checked_at).toBe(first.checked_at);
    expect(throwCalls).toBe(0);
    expect(loadBackupStatus()?.checked_at).toBe(first.checked_at);

    // forceRefresh + working engine recomputes and re-persists.
    const t1 = new Date(t0.getTime() + 60 * 60 * 1000);
    const third = await getBackupStatus(stubEngine({}), {
      localGitProbes: true,
      now: t1,
      forceRefresh: true,
    });
    expect(third.checked_at).toBe(t1.toISOString());
    expect(loadBackupStatus()?.checked_at).toBe(t1.toISOString());
  });

  test('a failed compute never clobbers — the prior cached verdict is returned', async () => {
    const t0 = new Date('2026-08-01T00:00:00.000Z');
    const first = await getBackupStatus(stubEngine({}), { localGitProbes: true, now: t0 });
    expect(loadBackupStatus()?.checked_at).toBe(first.checked_at);

    // Inject a mid-compute throw through the public API: an Invalid Date
    // makes computeBackupCoverage's checked_at serialization throw, so
    // getBackupStatus must fall back to the prior cache, not clobber it.
    const out = await getBackupStatus(stubEngine({}), {
      localGitProbes: true,
      forceRefresh: true,
      now: new Date('not-a-date'),
    });
    expect(out.checked_at).toBe(first.checked_at); // prior verdict returned
    expect(loadBackupStatus()?.checked_at).toBe(first.checked_at); // never clobbered

    // With no prior cache the same failure propagates to the caller.
    rmSync(statusPath, { force: true });
    await expect(
      getBackupStatus(stubEngine({}), {
        localGitProbes: true,
        forceRefresh: true,
        now: new Date('not-a-date'),
      }),
    ).rejects.toThrow();
  });
});

// ── countLivePages: an unestablished count is DEGRADED, never a fake zero ────

describe('computeBackupCoverage — pages count unestablished', () => {
  function pagesRowEngine(pagesRows: unknown[]): BrainEngine {
    return {
      kind: 'pglite',
      executeRaw: async (sql: string) => {
        if (sql.includes('FROM pages')) return pagesRows;
        if (sql.includes('FROM sources')) return [];
        return [];
      },
    } as unknown as BrainEngine;
  }

  test('empty rowset for the pages query → degraded verdict, never persisted', async () => {
    // Returning 0 would fabricate a "no pages at risk" all-clear; an empty
    // rowset is UNESTABLISHED and must degrade (and degraded never persists).
    const s = await getBackupStatus(pagesRowEngine([]), { localGitProbes: true, forceRefresh: true });
    expect(s.degraded).toBe(true);
    expect(s.totals.pages_at_risk).toBe(0);
    expect(s.assets.find((a) => a.kind === 'db_content')).toBeUndefined();
    expect(existsSync(statusPath)).toBe(false);
  });

  test('non-numeric n → degraded verdict, never persisted', async () => {
    const s = await getBackupStatus(pagesRowEngine([{ n: 'lots' }]), {
      localGitProbes: true,
      forceRefresh: true,
    });
    expect(s.degraded).toBe(true);
    expect(existsSync(statusPath)).toBe(false);
  });
});

// ── Host-brain scoping: the status cache has no brain dimension ──────────────

describe('getBackupStatus — host-brain cache scoping', () => {
  test('non-host GBRAIN_BRAIN_ID: computes fresh (never reads the cache) and never persists', async () => {
    // Seed a FRESH host warn cache (a minute old — well inside the interval,
    // but distinguishable from a same-millisecond fresh compute) — for the
    // host brain this would short-circuit the compute entirely.
    const hostCache = mkStatus('warn', new Date(Date.now() - 60_000).toISOString());
    saveBackupStatus(hostCache);

    process.env.GBRAIN_BRAIN_ID = 'some-team';
    const out = await getBackupStatus(stubEngine({}), { localGitProbes: true });

    // The mounted-brain call computed FRESH from the empty stub (ok), instead
    // of returning the host cache's warn…
    expect(out.overall).toBe('ok');
    expect(out.checked_at).not.toBe(hostCache.checked_at);
    // …and the pre-existing host cache is untouched (an empty mounted brain's
    // ok must never silence a real host warn).
    expect(loadBackupStatus()).toEqual(hostCache);

    // Unset restores normal behavior: the fresh host cache answers as-is.
    delete process.env.GBRAIN_BRAIN_ID;
    const back = await getBackupStatus(stubEngine({}), { localGitProbes: true });
    expect(back.checked_at).toBe(hostCache.checked_at);
    expect(back.overall).toBe('warn');
  });

  test('non-host brain + absent cache: a probed compute leaves the cache file absent', async () => {
    process.env.GBRAIN_BRAIN_ID = 'some-team';
    expect(existsSync(statusPath)).toBe(false);
    const out = await getBackupStatus(stubEngine({}), { localGitProbes: true, forceRefresh: true });
    expect(out.overall).toBe('ok');
    expect(out.degraded).toBeUndefined(); // a clean compute — just never saved
    expect(existsSync(statusPath)).toBe(false);
  });

  test("GBRAIN_BRAIN_ID='host' behaves exactly like unset (reads + persists)", async () => {
    process.env.GBRAIN_BRAIN_ID = 'host';
    const out = await getBackupStatus(stubEngine({}), { localGitProbes: true });
    expect(out.overall).toBe('ok');
    expect(existsSync(statusPath)).toBe(true);
    expect(loadBackupStatus()?.checked_at).toBe(out.checked_at);
  });
});

// ── Serve-side in-process refresher ──────────────────────────────────────────

describe('maybeRefreshBackupStatusInProcess', () => {
  test('absent cache → computes with probes and persists a serve-stamped verdict', async () => {
    const repo = join(tmp, 'repo-refresh');
    initRepo(repo);
    commitFile(repo, 'a.md', 'x', 'init');
    const engine = stubEngine({ sources: [srcRow('src-refresh', repo)] });

    expect(existsSync(statusPath)).toBe(false);
    maybeRefreshBackupStatusInProcess(engine);

    expect(await pollUntil(() => existsSync(statusPath))).toBe(true);
    const s = loadBackupStatus();
    expect(s?.computed_by).toBe('serve');
    expect(s?.overall).toBe('warn'); // fixture repo has no origin
    expect(s?.assets.some((a) => a.kind === 'source_repo' && a.state === 'no_remote')).toBe(true);
  });

  test('two synchronous calls single-flight into one compute', async () => {
    let calls = 0;
    const engine = stubEngine({ onCall: () => calls++ });

    maybeRefreshBackupStatusInProcess(engine);
    maybeRefreshBackupStatusInProcess(engine);

    expect(await pollUntil(() => existsSync(statusPath))).toBe(true);
    await sleep(100); // let any (wrongly) duplicated compute land
    // One compute = exactly two executeRaw calls (sources + pages), not four.
    expect(calls).toBe(2);
  });

  test('fresh ok cache → does nothing (engine never touched)', async () => {
    saveBackupStatus(mkStatus('ok', new Date().toISOString()));
    let calls = 0;
    const engine = stubEngine({ onCall: () => calls++ });

    maybeRefreshBackupStatusInProcess(engine);
    await sleep(150);

    expect(calls).toBe(0);
  });

  test('warn cache older than 24h → recomputes even though the cache is not interval-stale', async () => {
    const old = new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString();
    saveBackupStatus(mkStatus('warn', old));
    let calls = 0;
    const engine = stubEngine({ onCall: () => calls++ });

    maybeRefreshBackupStatusInProcess(engine);

    expect(await pollUntil(() => loadBackupStatus()?.checked_at !== old)).toBe(true);
    expect(calls).toBeGreaterThanOrEqual(2);
    const s = loadBackupStatus();
    expect(s?.overall).toBe('ok'); // the empty brain no longer warns
    expect(Date.parse(s!.checked_at)).toBeGreaterThan(Date.parse(old));
  });
});

// ── Dirty working tree, shared roots, non-repo paths ─────────────────────────

describe('computeBackupCoverage — dirty tree, shared git roots, non-repo paths', () => {
  test('origin-backed pushed repo with a modified tracked file → dirty, overall stays ok', async () => {
    const bare = join(tmp, 'dirty-bare.git');
    execFileSync('git', ['init', '--bare', '-b', 'main', bare], { stdio: ['ignore', 'pipe', 'pipe'] });
    const work = join(tmp, 'dirty-work');
    initRepo(work);
    commitFile(work, 'a.md', 'clean state', 'baseline');
    g(work, ['remote', 'add', 'origin', bare]);
    g(work, ['push', '-u', 'origin', 'main']);
    writeFileSync(join(work, 'a.md'), 'modified but not committed'); // dirty, NOT ahead

    const engine = stubEngine({ sources: [srcRow('src-dirty', work)] });
    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'source_repo');
    expect(asset?.id).toBe('src-dirty');
    expect(asset?.state).toBe('dirty');
    expect(asset?.detail).toBe('uncommitted changes');
    expect(asset?.fix_argv).toBeNull();
    expect(s.overall).toBe('warn');
    expect(s.totals.no_remote).toBe(0);
    expect(s.totals.unpushed).toBe(0);
    expect(s.totals.recoverable_repos).toBe(0);
  });

  test('two sources in the SAME git repo (root + subdir) dedupe to ONE probed asset with joined ids', async () => {
    const repo = join(tmp, 'shared-root');
    initRepo(repo);
    mkdirSync(join(repo, 'docs'), { recursive: true });
    writeFileSync(join(repo, 'docs', 'inner.md'), 'inner');
    commitFile(repo, 'a.md', 'x', 'init'); // commits a.md + docs/inner.md

    const engine = stubEngine({
      sources: [srcRow('root-src', repo), srcRow('sub-src', join(repo, 'docs'))],
    });
    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const repos = s.assets.filter((a) => a.kind === 'source_repo');
    expect(repos).toHaveLength(1); // one git root → one probed asset
    expect(repos[0]?.id).toBe('root-src, sub-src');
    expect(repos[0]?.state).toBe('no_remote'); // fixture repo has no origin
    expect(s.totals.no_remote).toBe(1); // counted once, not per source
    expect(s.overall).toBe('warn');
  });

  test('existing plain directory (not a git repo) → unknown/not_a_git_repo; memoized per path, one asset PER SOURCE', async () => {
    const plain = join(tmp, 'plain-dir');
    mkdirSync(plain, { recursive: true });
    writeFileSync(join(plain, 'notes.md'), 'not under git');

    // Two sources at the SAME non-repo path: discovery is memoized (one
    // subprocess), but EVERY source at the known non-repo path still gets its
    // own asset row — the second source is no longer silently dropped.
    const engine = stubEngine({
      sources: [srcRow('plain-src', plain), srcRow('plain-src-dup', plain)],
    });
    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    const repos = s.assets.filter((a) => a.kind === 'source_repo');
    expect(repos).toHaveLength(2);
    expect(repos.map((a) => a.id).sort()).toEqual(['plain-src', 'plain-src-dup']);
    for (const a of repos) {
      expect(a.state).toBe('unknown');
      expect(a.detail).toBe('not_a_git_repo');
      expect(a.fix_argv).toBeNull();
    }
    expect(s.overall).toBe('warn');
    expect(s.totals.no_remote).toBe(0);
  });
});

// API connector sources (Google / GitHub)

describe('computeBackupCoverage: API connector sources', () => {
  const connectorRow = (id: string) => ({
    kind: 'connector',
    id,
    state: 'info',
    fix_argv: ['gbrain', 'sync', '--source', id, '--full'],
  });

  function plainCache(name: string): string {
    const dir = join(tmp, name);
    mkdirSync(dir, { recursive: true });
    writeFileSync(join(dir, 'thread.md'), 'cached connector page');
    return dir;
  }

  test.each([
    { label: 'managed + unbound Google source (connector_database)', kind: 'google', managed: true, path: 'cache' },
    { label: 'managed + unbound GitHub source whose cache dir is gone', kind: 'github', managed: true, path: 'missing' },
    { label: 'unmanaged Google source with a plain cache dir', kind: 'google', managed: false, path: 'cache' },
    { label: 'unmanaged Google source whose cache dir is gone', kind: 'google', managed: false, path: 'missing' },
  ] as const)('$label → connector info asset, not an unrecoverable repo', async ({ kind, managed, path }) => {
    const localPath = path === 'cache' ? plainCache('conn-cache') : join(tmp, 'gone-cache');
    const engine = stubEngine({ managed, sources: [srcRow('conn-src', localPath, { config: { kind } })] });

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    expect(s.assets.filter((a) => a.kind === 'source_repo')).toEqual([]);
    const asset = s.assets.find((a) => a.id === 'conn-src');
    expect(asset).toMatchObject(connectorRow('conn-src'));
    expect(asset?.detail).toContain('provider API');
    expect(s.overall).toBe('ok');
  });

  test('managed + BOUND connector keeps the canonical-root Git contract (plain dir → not_a_git_repo)', async () => {
    const localPath = plainCache('bound-cache');
    const engine = stubEngine({
      managed: true,
      bound: ['conn-bound'],
      sources: [srcRow('conn-bound', localPath, { config: { kind: 'google' } })],
    });

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    expect(s.assets.find((a) => a.id === 'conn-bound')).toMatchObject({ kind: 'source_repo', state: 'unknown', detail: 'not_a_git_repo' });
    expect(s.overall).toBe('warn');
  });

  test.each([
    { engine: 'pglite', state: 'no_remote', overall: 'warn' },
    { engine: 'postgres', state: 'info', overall: 'ok' },
  ] as const)('connector-only $engine brain with pages → db_content $state (no git-backed asset)', async ({ engine: kind, state, overall }) => {
    const engine = stubEngine({ kind, managed: true, pages: 7, sources: [srcRow('conn-src', null, { config: { kind: 'google' } })] });

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    expect(s.assets.find((a) => a.id === 'conn-src')).toMatchObject({ kind: 'connector', state: 'info' });
    expect(s.assets.find((a) => a.kind === 'db_content')).toMatchObject({ state });
    expect(s.overall).toBe(overall);
  });

  test('a failing persistence read degrades the verdict instead of exempting the connector', async () => {
    const engine = {
      kind: 'pglite',
      executeRaw: async (sql: string) => {
        if (sql.includes('FROM persistence_brain')) throw new Error('persistence table unreadable');
        if (sql.includes('FROM pages')) return [{ n: 1 }];
        if (sql.includes('FROM sources')) return [srcRow('conn-src', join(tmp, 'x'), { config: { kind: 'google' } })];
        return [];
      },
    } as unknown as BrainEngine;

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    expect(s.degraded).toBe(true);
    expect(s.overall).toBe('warn');
    expect(s.assets.find((a) => a.id === 'conn-src')).toBeUndefined();
  });

  test('unmanaged connector whose local_path IS a git repo is probed like any repo', async () => {
    const repo = join(tmp, 'gh-repo');
    initRepo(repo);
    commitFile(repo, 'a.md', 'x', 'init');
    const engine = stubEngine({ sources: [srcRow('gh-src', repo, { config: { kind: 'github' } })] });

    const s = await computeBackupCoverage(engine, { localGitProbes: true });

    expect(s.assets.find((a) => a.id === 'gh-src')).toMatchObject({ kind: 'source_repo', state: 'no_remote' });
  });
});

// ── Bootstrap workspace: failing push status ─────────────────────────────────

describe('computeBackupCoverage — bootstrap workspace failing push', () => {
  test('receipt WITH repo_url + a failing per-root push-status → failing asset with sanitized detail', async () => {
    const ws = join(tmp, 'ws-failing');
    mkdirSync(ws, { recursive: true }); // repoRoot must exist or the ghost filter drops the entry
    writeReceipt(ws, { repo_url: 'https://example.com/acme-example/brain.git' });

    // A failing per-root status via the real path helper (workspace-push.ts).
    // The reason carries hostile chars: sanitizePushReason must strip them
    // before the detail reaches any human/model-visible surface.
    const statusFile = pushStatusPathForRoot(ws);
    mkdirSync(join(home(), 'bootstrap'), { recursive: true });
    writeFileSync(
      statusFile,
      JSON.stringify({
        ts: new Date().toISOString(),
        ok: false,
        reason: 'push failed: `rm -rf` $HOME \u0007beep',
        repoRoot: ws,
      }),
    );

    const s = await computeBackupCoverage(stubEngine({}), { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'bootstrap_workspace');
    expect(asset).toBeDefined();
    expect(asset?.id).toBe(ws);
    expect(asset?.state).toBe('failing');
    expect(asset?.detail).toBe('last_push_failed');
    expect(asset?.detail).not.toContain('`');
    expect(asset?.detail).not.toContain('$');
    expect(asset?.detail).not.toContain('\u0007');
    expect(asset?.fix_argv).toEqual(['gbrain', 'sources', 'push', '--path', ws]);
    expect(s.totals.failing).toBe(1);
    expect(s.overall).toBe('warn');
    // A failing push means the remote is BEHIND: counting it recoverable would
    // overstate the recovery statement, so recoverable_repos excludes it.
    expect(s.totals.recoverable_repos).toBe(0);
  });

  test("a failing push status for a DIFFERENT root leaves the workspace ok", async () => {
    const ws = join(tmp, 'ws-healthy');
    mkdirSync(ws, { recursive: true });
    writeReceipt(ws, { repo_url: 'https://example.com/acme-example/brain.git' });

    // A failing status for some OTHER push-tracked repo (root exists, so the
    // ghost filter keeps the entry alive) — the workspace verdict reads ONLY
    // its own per-root status and must not inherit this failure.
    const other = join(tmp, 'other-root');
    mkdirSync(other, { recursive: true });
    mkdirSync(join(home(), 'bootstrap'), { recursive: true });
    writeFileSync(
      pushStatusPathForRoot(other),
      JSON.stringify({ ts: new Date().toISOString(), ok: false, reason: 'push failed elsewhere', repoRoot: other }),
    );

    const s = await computeBackupCoverage(stubEngine({}), { localGitProbes: true });

    const asset = s.assets.find((a) => a.kind === 'bootstrap_workspace');
    expect(asset).toBeDefined();
    expect(asset?.state).toBe('unknown');
    expect(s.totals.failing).toBe(0);
    expect(s.totals.recoverable_repos).toBe(0);
    expect(s.overall).toBe('warn');
  });
});

// ── Harness skills (bridge-state ledger) ─────────────────────────────────────

describe('computeBackupCoverage — harness_skills info row', () => {
  test('bridge state with one entry → one harness_skills info asset', async () => {
    // Written through the real saver so the fixture matches the BridgeState
    // schema loadBridgeState validates (schema_version + entries shape).
    saveBridgeState({
      schema_version: SKILLPACK_BRIDGE_SCHEMA_VERSION,
      entries: [
        {
          harness: 'claude-code',
          dest: join(tmp, 'harness-skills-dest'),
          last_persona: null,
          last_mode: 'full',
          written: { 'query-skill': { mode: 'full', files: { 'SKILL.md': 'abc123' } } },
          gbrain_version: '0.0.0-test',
          installed_at: '2026-08-01T00:00:00.000Z',
          updated_at: '2026-08-01T00:00:00.000Z',
        },
      ],
    });

    const s = await computeBackupCoverage(stubEngine({}), { localGitProbes: true });

    const rows = s.assets.filter((a) => a.kind === 'harness_skills');
    expect(rows).toHaveLength(1);
    expect(rows[0]?.id).toBe('1 harness skill dir(s)');
    expect(rows[0]?.state).toBe('info');
    expect(rows[0]?.detail).toContain('installed copies');
    expect(rows[0]?.fix_argv).toBeNull();
    expect(s.overall).toBe('ok'); // info never warns
  });
});

describe('degraded verdict never clobbers a probed cache', () => {
  test('forceRefresh against a broken engine keeps the prior warn cache', async () => {
    const home = mkdtempSync(join(tmpdir(), 'gb-bkc-degraded-'));
    const prevHome = process.env.GBRAIN_HOME;
    process.env.GBRAIN_HOME = home;
    try {
      const warn: BackupStatus = {
        schema_version: BACKUP_STATUS_SCHEMA_VERSION,
        checked_at: new Date().toISOString(),
        gbrain_version: '0.0.0',
        interval_days: 30,
        computed_by: 'cli',
        overall: 'warn',
        totals: { assets: 1, no_remote: 1, unpushed: 0, failing: 0, recoverable_repos: 0, pages_at_risk: 0 },
        assets: [{ kind: 'source_repo', id: 'kept-repo', state: 'no_remote', fix_argv: null }],
      };
      saveBackupStatus(warn);
      const broken = {
        kind: 'pglite',
        executeRaw: async () => {
          throw new Error('engine down');
        },
      } as unknown as BrainEngine;
      const out = await getBackupStatus(broken, { localGitProbes: true, forceRefresh: true });
      // The degraded empty verdict is discarded in favor of the cached warn…
      expect(out.overall).toBe('warn');
      expect(out.assets[0]?.id).toBe('kept-repo');
      // …and the cache file itself is untouched (no clobber).
      expect(loadBackupStatus()?.overall).toBe('warn');
      // With NO cache, the degraded verdict is returned but never persisted.
      invalidateBackupStatus();
      const degraded = await getBackupStatus(broken, { localGitProbes: true, forceRefresh: true });
      expect(degraded.degraded).toBe(true);
      expect(loadBackupStatus()).toBeNull();
    } finally {
      if (prevHome === undefined) delete process.env.GBRAIN_HOME;
      else process.env.GBRAIN_HOME = prevHome;
      rmSync(home, { recursive: true, force: true });
    }
  });
});