Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.4 KB
Raw Blame
/**
 * advisor/collect-backup-coverage.ts — surfaces the monthly backup-coverage
 * verdict ("which knowledge repos have no git remote?") as advisor findings.
 *
 * Local runs (trusted CLI owner) refresh the verdict through the shared
 * choke point getBackupStatus (stale-only recompute keeps the collector
 * cron-safe; a fresh cache makes this a file read) and emit per-asset
 * findings with fix commands, gated as ONE batch through backupNagGate so
 * the advisor participates in the same bounded-nag budget as every other
 * channel. Remote runs are cache-readers with aggregate counts ONLY
 * (amendment-29 discipline — never a local path or source id) and never
 * write nag state.
 */

import { getBackupStatus } from '../backup/coverage.ts';
import { backupCheckDisabled, backupNagGate, blockingAssetReasons, currentBackupEvidence, loadBackupStatus } from '../backup/status-file.ts';
import type { AdvisorCollector, AdvisorFinding } from './types.ts';

export const collectBackupCoverage: AdvisorCollector = {
  id: 'backup-coverage',
  collect: async (ctx) => {
    // The off switch silences compute AND every render channel (the ops-doc
    // contract) — including this collector, on both the local compute branch
    // and the remote cache-read branch.
    if (backupCheckDisabled()) return [];
    const findings: AdvisorFinding[] = [];
    const local = !ctx.remote;

    if (!local) {
      // Remote: cache-only read, aggregate wording, no nag writes (D4 — no
      // git subprocesses on a remote surface, ever).
      const raw = loadBackupStatus();
      if (!raw) return [];
      const s = currentBackupEvidence(raw, ctx.now.getTime());
      if (s.overall !== 'warn') return [];
      // #5505: count the reasons that hold the warn, not only no_remote.
      const byReason = new Map<string, number>();
      for (const { reason } of blockingAssetReasons(s, 'aggregate')) byReason.set(reason, (byReason.get(reason) ?? 0) + 1);
      const blocked = [...byReason.values()].reduce((a, b) => a + b, 0);
      const reasons = [...byReason].map(([reason, n]) => `${n} ${reason}`).join(', ');
      findings.push({
        id: 'backup_coverage_aggregate',
        severity: 'warn',
        title: (blocked > 0
          ? `${blocked} of ${s.totals.assets} knowledge assets lack verified recovery (${reasons})`
          : 'The cached backup verdict is not current') +
          '. Run `gbrain backup status` on the brain host for fix commands.',
        fix: { command_argv: null },
        collector: 'backup-coverage',
        ask_user: true,
      });
      return findings;
    }

    const s = await getBackupStatus(ctx.engine, {
      localGitProbes: true,
      computedBy: 'advisor',
      now: ctx.now,
    });
    if (s.overall !== 'warn') return [];

    // One gate for the whole batch (the verdict fingerprint covers the set);
    // recording at collect time matches the collect-mcp-client-fit precedent.
    const gate = backupNagGate('advisor', s, ctx.now.getTime());
    if (!gate.show) return [];

    for (const a of s.assets) {
      if (a.state === 'no_remote' && a.kind === 'source_repo') {
        findings.push({
          id: `backup_source_no_remote:${a.id}`,
          severity: 'warn',
          title: `Knowledge repo ${a.id} has no git remote — a disk loss loses it.`,
          detail: a.detail,
          fix: { command_argv: a.fix_argv ?? null },
          collector: 'backup-coverage',
          ask_user: true,
        });
      } else if (a.state === 'no_remote' && a.kind === 'bootstrap_workspace') {
        findings.push({
          id: 'backup_workspace_no_repo',
          severity: 'warn',
          title: 'Your agent workspace has no private repo yet — a disk loss loses skills, memory, and identity.',
          detail: a.detail,
          // No default fallback here (matches source_repo above): coverage.ts
          // deliberately leaves fix_argv null for this kind since it can't
          // tell an empty origin (bootstrap repo) from an already-pushed
          // out-of-band one (bootstrap attach) without a git subprocess — a
          // hardcoded ['gbrain','bootstrap','repo'] fallback would reintroduce
          // the same wrong-command-in-the-out-of-band-case bug this exists to fix.
          fix: { command_argv: a.fix_argv ?? null },
          collector: 'backup-coverage',
          ask_user: true,
        });
      } else if (a.state === 'no_remote' && a.kind === 'db_content') {
        findings.push({
          id: 'backup_db_content_unbacked',
          severity: 'warn',
          title: 'Your brain lives only in the local database — nothing is git-backed.',
          detail: a.detail,
          fix: { command_argv: a.fix_argv ?? ['gbrain', 'bootstrap', 'repo'] },
          collector: 'backup-coverage',
          ask_user: true,
        });
      }
    }
    // #5505: dirty trees, non-Git paths and unverified remotes hold the warn
    // too; name them instead of leaving the warn with no finding.
    const otherBlocked = blockingAssetReasons(s, 'local').filter((a) => a.state !== 'no_remote' && a.state !== 'unpushed');
    if (otherBlocked.length > 0) {
      findings.push({
        id: 'backup_recovery_unverified',
        severity: 'warn',
        title: `${otherBlocked.length} knowledge asset(s) lack verified recovery: ${otherBlocked.map((a) => `${a.id} (${a.reason})`).join(', ')}.`,
        detail: 'run gbrain backup status for the per-asset detail and fix commands',
        fix: { command_argv: null },
        collector: 'backup-coverage',
        ask_user: true,
      });
    }
    const unpushed = s.assets.filter((a) => a.state === 'unpushed');
    if (unpushed.length > 0) {
      findings.push({
        id: 'backup_unpushed_work',
        severity: 'info',
        title: `${unpushed.length} repo(s) have commits not yet on their remote.`,
        detail: unpushed.map((a) => `${a.id}: ${a.detail ?? 'ahead of origin'}`).join('; '),
        fix: { command_argv: null },
        collector: 'backup-coverage',
        ask_user: true,
      });
    }
    if (s.assets.some((a) => a.kind === 'db_only')) {
      findings.push({
        id: 'backup_db_only_caveat',
        severity: 'info',
        title: 'db_only pages are not covered by any git remote — dump them with gbrain export.',
        detail: 'run gbrain doctor (undeclared_db_only_pages) for the page-level audit',
        fix: { command_argv: null },
        collector: 'backup-coverage',
        ask_user: true,
      });
    }

    if (findings.length > 0) gate.record();
    return findings;
  },
};